Yoke
Hosted beta ↗
Contents

Yoke DB Reference

Raw item reads join item_refs r ON r.item_id = items.id and select r.public_ref. The read-only view follows prefix updates; project_sequence alone is ambiguous across projects. yoke db read warns when a query reads item ids (items.id or any *item_id column) without joining item_refs, and when a returned project_sequence lacks both public_ref and public_item_prefix.

yoke db read returns column values as stored. It refuses a query whose result includes a declared secret column (organizations.events_signing_key), including through SELECT *, with db_read_secret_column_refused; select the specific columns you need instead.

Source of truth: the configured Postgres authority. Agent-facing reads and writes route through registered yoke ... commands or the Yoke function-call surface. Everyday raw diagnostic SELECTs use yoke db read "SELECT ...". python3 -m yoke_core.cli.db_router query remains read-only source-dev/operator-debug diagnostics; never call raw database clients directly and never hardcode a DB path or DSN. A session holding a live steering seat on the repaired project, acting for an org administrator, uses yoke operator data-repair --content-file repair.json --reviewed-sha256 SHA --dry-run for bounded guarded repairs without a lane. Review the simulation before applying; the repair contract owns durable before/after evidence.

Quickstart for session operators: AGENTS.md § Code Conventions, § Structured Item Writes, and § Governed DB Mutation. Update those sections when this file changes.

The function catalog owns registered ids, CLI adapters, claim verification and permanent boundaries. For a source-checkout Atlas, use yoke dev run -- python3 -m yoke_core.tools.atlas_render_docs render; this source-dev renderer is not a product command. Mutations use registered function ids; CLI adapters construct the same dispatched request.

This reference covers diagnostic columns, agent packets, registered operations, JSON payloads and common pitfalls. The database branch links migration conventions and governed repair; the Topic Index links current data-model homes, QA commands and the remaining event reference.

Common column mistakes to avoid in raw SQL

Quick reference for the columns most often mis-named in agent SQL. The DB-command column lint at yoke_core.domain.lint_db_rules_columns denies these patterns and points here; legacy telemetry/check ids remain stable.

  • epic_tasks: use epic_id (NOT item_id), task_num (NOT task_number/seq), dependencies (NOT depends_on).
  • epic_progress_notes: content is in body (NOT note).
  • events: use event_name/event_type/source_type/created_at/envelope (NOT type/timestamp/source/detail/context/worker/payload/outcome).
  • deployment_runs: use id (NOT run_id), current_stage (NOT deploy_stage), created_by (NOT creator). No item_id column — join through deployment_run_items for item-bound runs. carried_work records resolved items and unresolved commit SHAs. A warning that changes what the run can attest is deployment_runs.get attestation_warnings (reason, cost, recovery) — do not parse carried_work JSON for that downgrade.
  • deployment_run_items: use run_id + item_id (composite PK, NO id column). Junction table only — has NO deploy_stage, current_stage, or status columns. Stage data lives on items.deploy_stage and deployment_runs.current_stage. Zero rows are valid for started environment-level deployment runs.
  • qa_runs: use qa_requirement_id (NOT requirement_id or req_id).
  • deployment_flows: use id (NOT flow_id), no item_id column.
  • shepherd_verdicts: use public_ref (public item key), transition (NOT gate).
  • ouroboros_entries: content is in body (NOT entry), use created_at (NOT timestamp).
  • project_capabilities: use type (NOT capability/name/capability_type), config for full JSON (may contain secrets), settings for non-sensitive JSON.
  • projects: use id (NOT project_id/name) and github_repo (NOT repo_url/github_url). Checkout paths are machine-local config, not projects columns. Work-item-level deployment-flow defaulting lives in the deploy_defaults Project Structure family, not as a column on projects.
  • Domain names: epic (NOT epics), events registry (NOT registry), runs (NOT deploy-events); board rebuild is yoke board rebuild.
  • Live-claim holder lookup: use yoke claims work holder-get PREFIX-N; inspect project steering holders with yoke claims steering list --project P --active-only. The typed work_claims model uses target_kind plus one canonical JSON scope; session ownership is session_id. See Live claim-holder lookup.

Agent-context packet

Packets are generated by yoke_core.domain.schema_api_context from curated seeds and schema introspection. Role audiences, topic ownership and budgets live in its seed modules; rendered adapters use yoke_core.domain.agents_render_context. Main, Architect, Engineer, Tester, QA Walker, Simulator and Boss receive the current decision and executable recipes their role needs. Explicit topic depth remains available for discovery. Authorization, Pack, claims, project and QA teaching belongs to its owning topic rather than a copied whole-registry roster.

yoke packets render --role main_agent
yoke packets render --role engineer_agent
yoke packets check
yoke packets budget get
yoke agents render
yoke agents render check

These adapters dispatch packets.render, packets.check, packets.budget.get, agents.render.run and agents.render.check. Run the owning command's --help for topic/depth selection and checks. When schema or recipes change, update their curated owner and regenerate; checks reject canonical/rendered drift and stale parallel examples. The only packet insertion point is <!-- YOKE:DB-PACKET role=R topic=T start --> ... <!-- YOKE:DB-PACKET end -->. Do not hand-copy a second cheat sheet. QA plan materialization and review ownership follow the active executor contract; a packet does not delegate them merely by showing a command. harness_contract separately owns manifest/bootstrap substrate facts. See the agent guide.

Topic Index

Entry points

yoke <subcommand> [args...]
yoke db read "SELECT ..."

Lifecycle-owned writes (item status, deploy_stage, epic_task status, the events table) are not available through query — use the sanctioned mutators below. The Python lint owners enforce the separation.

Bootstrap contract

Normal runtime commands (reads, domain dispatch, structured-field writes) never trigger schema/domain bootstrap as a side effect. The module chain under _AUTO_INIT_MODULES runs only when:

  • the operator invokes the explicit schema bootstrap subcommand; or
  • the calling process sets YOKE_DB_INIT_ALLOW=1 (test fixtures, first-run provisioning, cross-worktree DB creation).

When a normal command runs against an existing DB whose baseline schema is missing (no items table), the router refuses the command and prints remediation pointing at db_router init. No silent CREATE TABLE as a side effect of a read-looking command.

Additive schema self-propagates on deploy. Separately from the CLI bootstrap path above, the API server entrypoint (yoke_core.api.server_entrypoint.ensure_core_schema) runs the full idempotent schema_init.converge_core_schema — every CREATE TABLE/CREATE INDEX plus additive ADD COLUMN step — on every boot of an already-born universe. So any net-new additive table or column added to the schema-init chain reaches every born universe on its next deploy/restart with no governed migration and no manual catch-up. Foreign keys onto environments.id match the live primary-key type so a universe still on text keys reaches the ordered history that converts them, rather than failing the boot. Data-transforming changes — backfills, drops, rewrites — go in the ordered migration history instead, and are applied by the same boot converge.

Registered operations

Use yoke --help for the live product command roster and the function catalog for complete payloads and family homes. Items, epic tasks, sections, verdicts/dependencies, projects, flows/runs, ephemeral environments, events, QA, releases and Ouroboros each retain their registered owner. Python service-client modules are internal implementation, not an agent mutation surface. New item intake uses /yoke idea; the pinned workflow owns lifecycle targets.

# Narrow reads; choose the actual pinned stage rather than a copied sequence.
yoke items get PREFIX-N status
yoke items dependency list PREFIX-N
yoke project-structure get --project P --family test_roots
yoke qa requirement list --item PREFIX-N

# Complete intended content is file-backed; additive transforms stay native.
yoke items structured-field replace PREFIX-N --field spec --stdin < /tmp/spec.md
yoke items structured-field section-upsert PREFIX-N --section "Goals" --content-file /tmp/goals.md --ordering 100 --source operator
yoke items progress-log append PREFIX-N --headline "Verification" --content-file /tmp/update.md --source operator

# Diagnostic item reads retain current project-qualified identity.
yoke db read "SELECT r.public_ref, i.title FROM items i JOIN item_refs r ON r.item_id=i.id WHERE i.status='implementing'"

Read each command's --help before changing its payload or selecting a write. The QA CLI owns QA requirements and artifacts; body writes owns structured transforms; the deployment run home owns registered run recipes; members and QA owns custody. Deployment flow/run adapters are available; discover their current shape rather than treating them as pending. Exit codes: 0 success, 1 error/not found, 2 usage error.

JSON-payload columns

JSON payload shape is separate from physical SQL type. The candidate's yoke_core.domain.sql_json.JSONB_COLUMNS enumerates these native-type targets; inspect live schema before claiming a universe has completed that cutover. json_get handles empty/nullable TEXT by casting for extraction; json_set_expr preserves the current TEXT writer contract.

Table JSON-payload columns
events envelope, anomaly_flags
items db_mutation_profile, db_compatibility_attestation
qa_runs raw_result
qa_artifacts metadata
deployment_flows stages
deployment_runs carried_work, bound_sources
migration_audit baseline_verify_result, author_verify_result
path_context_values value
function_call_ledger result
github_workflow_dispatch_intents inputs
pack_catalog dependencies_json

Event envelopes are objects; anomaly flags are arrays at native cutover (legacy storage may be comma-separated). QA stores tool-result/metadata envelopes, flow stages are an array, and carried work contains resolved items, bare commits and named empty reasons. Topic schemas own exact shapes. Separately, typed work_claims.scope is a canonical JSON object selected by target_kind; it is not an entry in the legacy TEXT-target enumeration above.

Markdown and plain-text columns are NOT JSON payload and stay TEXT on both dialects. Authoring agents occasionally conflate "long text stored in a DB column" with "JSON payload" — they are different. The following columns are markdown or plain text and must not be annotated with → JSONB on Postgres:

  • items.spec, items.design_spec, items.technical_plan, items.worktree_plan, items.shepherd_caveats, items.test_results, items.deploy_log — structured markdown per the virtual-body-field model (docs/archive/decisions/virtual-body-field.md).
  • epic_progress_notes.body — markdown.
  • shepherd_verdicts.caveats, ouroboros_entries.body — markdown.
  • release_entries.title, release_entries.version, release_entries.category, release_entries.project — plain-text identifiers.

Postgres target for markdown/plain-text columns: TEXT (or VARCHAR(N) for bounded identifiers).

Common Pitfalls

  • Function is query_item, NOT _query_item
  • SQL operators: use <> not !=.
  • Prefer registered yoke ... readers over raw SQL in shell scripts for single-item operations.
  • Structured fields: Pipeline stages write to structured DB fields (spec, shepherd_caveats, design_spec, technical_plan, worktree_plan, …) through the Yoke function-call surface: agents call function ids such as items.structured_field.replace, items.structured_field.append_addendum, items.structured_field.section_upsert, items.structured_field.section_append, items.section.upsert, and items.progress_log.append. The CLI commands (yoke items structured-field replace, yoke items structured-field append-addendum, yoke items structured-field section-upsert, yoke items structured-field section-append, and yoke items section upsert) build the matching FunctionCallRequest and dispatch through the same registry. The body is a generated view assembled by yoke_core.domain.render_body. Never use ad-hoc sed chains or awk on body content. Full payload shapes, claim-verification rules, and event emissions live in db-reference/functions.md.
  • Structured-field transforms (agent path): Two operations, one envelope each. Full-field rewrites call items.structured_field.replace with the complete intended content. Additive transforms (preserve existing content, append a ## heading-led block) call items.structured_field.append_addendum / section_upsert / section_append. The handler reads through canonical DB routing, applies an idempotent transform, writes via the existing guarded structured-write path (preserving empty/shrinkage/freeze guards), and re-reads to verify. Reading a structured field with items get, redirecting through a temp file or shell variable for transformation, and piping back into items update --stdin is blocked by yoke_core.domain.lint_structured_field_transform_shell. Bypass: # lint:no-structured-transform-check (audited).
  • For bulk reads in shell scripts, use yoke db read --json or a registered read adapter rather than raw database clients.
  • frozen is INTEGER in DB (0/1) but query_item maps it to "true"/"false"
Database reference · Yoke