QA CLI

Use the registered QA commands to author requirements, execute cases and record evidence. The database reference owns the domain catalog and shared payload conventions.

Source-backed CI gates

A CI gate that updates the source lane it runs from continues in a fresh interpreter before publication. The authorized case, prepared lane and original source identity travel together; it does not authorize or update the lane twice. Installed gates updating another project's checkout continue in their leased CLI release. A failed restart names qa_ci_source_restart_failed; keep the updated lane and rerun the same case to rejoin any existing CI run.

Run the gate and iterate

Find <id> with yoke qa requirement list --item PREFIX-N. Commit first; a CI-backed case publishes the lane itself. Run it after your test selections, and run it again only after you change something. A gate that prints nothing for a while is still running. If its watcher was killed, run the same command again: it rejoins or adopts the CI run for that commit.

In a lane, the command first brings the lane current with its base branch; uncommitted work or a conflict refuses with the fix and runs no tests. --local is for a check that ends in about one minute. If it runs longer, stop it, treat the capture as incomplete, commit, and run on CI. When the selection reports itself unbounded, keep testing what you judge relevant; the QA case covers the rest.

qa domain CLI

Python owner: yoke_core.domain.qa. Public command examples use the installed Yoke CLI, which dispatches the registered qa.* function ids:

yoke qa requirement add|add-batch|list|get|update|waive|transfer ...
yoke qa plan materialize --item PREFIX-N --transition T
yoke qa plan run --item PREFIX-N --stage STAGE [--plan PLAN] --project P — runs the item's cases; --plan ID_OR_SLUG adds no obligations; a new plan fills only an empty stage.
yoke qa plan run --deployment-run-id RUN --stage item-qa --plan PLAN --project P — runs the plan's open plan group once for the release; refuses plan_group_not_open listing its closed groups
yoke qa plan run --deployment-run-id RUN --plan PLAN --project P — run-wide, and refused on a run pinning any QA stage
yoke qa run add|complete|record-verdict|list|get ...
yoke qa artifact presign|add ...
yoke qa gate-summary ...

All CRUD logic for the qa_requirements, qa_runs, and qa_artifacts tables lives in yoke_core.domain.qa; that module name is implementation authority, not an agent-facing command recipe. Full platform documentation: QA platform.

# Add an item-bound review requirement
yoke qa requirement add \
 --item PREFIX-N --qa-kind implementation_review --qa-phase verification \
 --workflow-transition reviewed-implementation

# Bind a method case to a stage in the item's pinned workflow
yoke qa requirement add \
 --item PREFIX-N --method-id browser-check --qa-phase verification \
 --workflow-transition reviewing-implementation \
 --instructions "Inspect the workflow view." \
 --expected-outcome "The workflow view is correct." \
 --method-config '{"steps":[{"action":"navigate","route":"/workflows"}]}'

# Attach an executable case to a deployment run, optionally scoped to one
# stage and one member item the run carries. No workflow transition: the
# run owns that context. Refused on a finished run.
yoke qa requirement add \
 --deployment-run run-YYYYMMDD-NNN --method-id browser-inspection \
 --qa-phase post_deploy --deployment-stage stage-smoke \
 --deployment-member-item PREFIX-N \
 --instructions "Open the released home route." \
 --expected-outcome "The home page renders the new build." \
 --method-config '{"steps":[{"action":"navigate","route":"/"}]}'

# Move an unexecuted direct requirement; hold both work claims.
yoke qa requirement transfer --requirement-id {requirement_id} --to-item PREFIX-N --workflow-transition {stage} --rationale "Destination owns this check"

# List requirements
yoke qa requirement list --item PREFIX-N

# Get a single requirement
yoke qa requirement get --requirement-id 1

# Update a mutable field on an existing requirement
yoke qa requirement update --requirement-id 4309 --field blocking_mode --value non_blocking
yoke qa requirement update --requirement-id 4309 --field success_policy --value "$policy_json"
yoke qa requirement update --requirement-id 4309 --field method_config --value "$config_json"
# Mark a live case manual-wake: evidence first, then the path
yoke qa requirement update --requirement-id 4309 --field wake_evidence --value "$evidence"
yoke qa requirement update --requirement-id 4309 --field wake_path --value manual
# Re-declare a machine case's starting state before anything has run it
yoke qa requirement update --requirement-id 4309 --field starting_state --value '{"starting_state":"as_is","starting_state_reason":"keeps the session a person opened"}'

# Record a QA run for that item-bound review requirement.
# Blocking passes stamp verification_tree.head_sha from the claimed lane HEAD
# from the clean lane. --raw-result is evidence text, not the run identity.
yoke qa run add \
 --requirement-id 1 --performed-by agent --qa-kind implementation_review --verdict pass

# Record evidence for a method-less acceptance requirement at an explicit commit.
# qa_kind must match the requirement; raw-result holds the actual evidence.
yoke qa run add --requirement-id 1 --performed-by agent \
 --qa-kind ac_verification --verdict pass --head-sha FULL_COMMIT_SHA \
 --raw-result 'Evidence and result for every acceptance criterion'

# A pass proven outside the run credits a deployment stage only with its
# evidence attached to that run (else passed_without_evidence).
yoke qa artifact add --requirement-id 1 --run-id 1 \
 --artifact-type command_output --content-file /tmp/evidence.txt

# Epic-task review verdicts use the workflow-item helper path
yoke workflow-item epic-task review-insert \
 --epic PREFIX-833 --task-num 5 --verdict pass --body "Review passed"

# List runs
yoke qa run list --requirement-id 1

# Materialize and execute a named plan against a real deployment run.
# Name the stage the run is at, plus the member when that stage's scope is
# item: a stage credits only requirements bound to both.
yoke qa plan run \
 --item PREFIX-N --stage item-qa \
 --plan installer-campaign --project P

# Attach an artifact
yoke qa artifact add \
 --requirement-id 1 --run-id 1 --artifact-type screenshot \
 --artifact-handle '{"backend":"local","path":"/tmp/img.png"}'

# Attach inline screenshot bytes (mutually exclusive with --artifact-handle)
yoke qa artifact add \
 --requirement-id 1 --run-id 1 --artifact-type screenshot \
 --content-type image/png --filename capture.png --content-file PATH

# Preview blocking QA gaps before a reviewed-implementation transition
yoke qa gate-summary --item PREFIX-N --target reviewed-implementation --json

Subcommand	Args	Description
`yoke qa requirement add`	`--item PREFIX-N (--qa-kind K \| --method-id M) --qa-phase P --workflow-transition STAGE [opts]`, or `--deployment-run RUN --method-id M --qa-phase P [--deployment-stage STAGE [--deployment-member-item PREFIX-N]] [opts]`	Insert one requirement — bound to a QA-gated stage in the item's pinned workflow, or attached to a deployment run (authorized by the run's project scope, no workflow transition, refused on a finished run or a stage/member the run does not declare)
`yoke qa requirement add-batch`	`--item PREFIX-N (--rows-file PATH \| --stdin)`	Insert item-attached requirements atomically; every row requires `workflow_transition_id`
`yoke qa plan materialize`	`--item PREFIX-N --transition T`, internal run-level `--deployment-run-id RUN --plan PLAN --project P`, or scoped `--item PREFIX-N --stage STAGE [--plan PLAN] --project P`	Materialize attached item plans, one run-wide plan (refused when the run pins any QA stage, since every stage counts only rows carrying its own name), or frozen stage/member item cases; each case stays on the shared QA authority. For a stage already naming admitted cases, a correction-only `--plan` is accepted when repeatable `--replaces CASE_KEY=FAILED_REQUIREMENT_ID` names every plan case. Materialization and declaration commit together: the declaration immediately removes predecessor grading; the final effective corrected case blocks until its current attempt passes independent review and proof
`yoke qa plan run`	The same item, legacy run, or scoped stage/member selectors as materialize, or `--deployment-run-id RUN --stage item-qa --plan PLAN` for a plan group	Execute one server-issued durable roster against its exact subject and target; a run subject also accepts `--replaces` for the cases its `--plan` materializes
`yoke qa requirement supersede`	`--requirement-id N --superseded-by-requirement-id N --rationale TEXT`	Discharge a failed case with a passing same-scope corrected case, or retire a post_deploy item source in favor of a corrected item requirement once a passing run case superseded one of its admitted copies (or no run the item still belongs to holds a copy, so the corrected requirement owes its own proof); later releases admit only the corrected body
`yoke qa requirement supersede --declare-replacement`	`--requirement-id FAILED_ID --superseded-by-requirement-id CORRECTED_ID --rationale TEXT`	Declare an existing corrected case (a direct run case, or an item case of the same item, transition and phase) as the replacement of a failed one before it passes; the predecessor immediately leaves grading; the scoped runner grades the final corrected blocking case, and its current qualified pass records the passing-supersession audit.
`yoke qa requirement list`	`[--item PREFIX-N \| --epic PREFIX-N \| --deployment-run-id ID]`	List requirements
`yoke qa requirement get`	`--requirement-id N`	Get one requirement
`yoke qa requirement update`	`--requirement-id N --field FIELD (--value VALUE \| --null)`	Update one mutable field
`yoke qa requirement waive`	`--requirement-id N --rationale TEXT [--source operator\|agent] [--force]`	Waive a requirement with a recorded rationale
`yoke qa run add`	`--requirement-id N --performed-by T [--qa-kind K] [--verdict V] [opts]`	Insert an actual run; the run writer observes its lane start commit when available, and Machine and endpoint cases also retain their actual subject proof
`yoke qa run complete`	`--requirement-id N --run-id N [--verdict V] [--execution-status captured\|capture_failed] [opts]`	Complete a previously recorded run
`yoke qa run record-verdict`	`--requirement-id N --performed-by T --verdict V [--raw-result JSON] [opts]`	Record a one-shot verdict; a blocking pass carries `{"verification_tree": {"head_sha": "<full commit sha>"}}` in `--raw-result` JSON, except a `browser-inspection` review, whose capture already names its commit
`yoke qa run list`	`[--requirement-id N]`	List runs
`yoke qa run get`	`--run-id N [--project P]`	Get one run
`yoke qa artifact presign`	`--requirement-id N --run-id N --filename NAME [--content-type CT]`	Mint a durable upload target
`yoke qa artifact add`	`--requirement-id N --run-id N --artifact-type T (--artifact-handle JSON \| --content-base64 B64 --filename NAME \| --content-file PATH) [opts]`	Insert an artifact row from a typed handle or inline bytes
`yoke qa gate-summary`	`(--item PREFIX-N \| --epic PREFIX-N --task-num K) --target reviewed-implementation\|implemented`	Read blocking QA gaps for a transition

No public QA init or artifact-list adapter is registered. Schema initialization belongs to DB setup/migrations. Artifact-list remains an implementation/domain capability until a public adapter is registered; do not teach a fake public listing command for it. yoke qa requirement waive and yoke qa run get are registered public adapters.

A waiver may land at any time, even while a live walk runs the case. The walk keeps the case: it runs, records its result beside the waiver, and the walk moves on. The waiver keeps governing the gate.

When to use which mutator. requirement-update changes the policy or executable config of an existing requirement — tighten a success policy, move a requirement between blocking and non_blocking, bind it to a different target_env, correct a live method_config capture script (selectors, waits, assertions), or clear a nullable field. It preserves the requirement identity, so linked runs and artifacts stay attached. A method_config correction invalidates prior greens for gating unless a later run recorded the new config at start; re-run the case. Frozen deployment-run requirements refuse method_config updates. Use yoke qa requirement add when the verification surface itself needs to change — for example, swapping from unit_test to integration — since that is a different requirement. requirement-update refuses to mutate qa_kind for exactly that reason. It cannot change instructions or expected_outcome either: a post_deploy item source worded wrong is corrected by adding the corrected requirement and retiring the source with yoke qa requirement supersede after a passing run case answered its failed admitted copy, or once no run the item still belongs to holds a copy. Recording a requirement never checks the runtime against --target-env; only executing the case does.

Exit codes: 0 = success, 1 = error/not found, 2 = usage error

yoke qa case run --requirement-id N starts one agent_mission through a one-requirement plan execution, leaving sibling requirements untouched. Its lease, walker dispatch, review bundle and main-agent verdict use the ordinary plan path; exit 12 requires the returned review continuation. An inherit mission needs its ordered predecessor and refuses with plan-run recovery.

QA CLI

Source-backed CI gates

Run the gate and iterate

qa domain CLI

Related