Command reference — every pdca subcommand

← 07 Cross-cutting · Index · next: 09 Configuration reference →

The walkthrough introduces each command where the cycle first needs it. This page lists all of them in one place — first the commands that get an instance rendered, installed and checked, then every pdca subcommand: what each does, its options, what its exit code means, and where the walkthrough explains it. The usage lines are the tool's own --help output at template v0.59.0; pdca <command> --help is always the authority for the version you have installed.

Conventions

• The command is named per project. cli_name at render time sets the console script (pdca by default; pdca-<slug> if you run several instances on one machine). Before make install, or in CI, every command also runs as PYTHONPATH=src python3 -m pdca_harness.cli <command> ….
• Every command runs inside a rendered project. Each one loads pdca.toml from the current directory first. No pdca.toml, or an invalid one, is a one-line error and exit 2, never a traceback.
• Bare pdca is pdca status. The dashboard is the default command.
• Exit codes are a contract: 0 did what it says; 1 a bundle or a check did not pass, or the command refused to act; 2 bad input (config, an unknown id, an unschedulable graph). pdca flow adds 3 — see below.
• <id> is a tracker issue id as it appears in results/issue_<id>/. Several commands take none and then act on every bundle that fits.

Getting set up

These run once per instance, or once per machine, before any pdca command. Step 01 walks through them in order with Wyrd's real answers.

The order matters: render, then make install, then pdca doctor, then the offline rehearsal — and only then point a leaf at a real model. If ship_ci_workflow was left on at render, the shipped check-gates.yml runs pdca gates --working-tree on every PR of the instance, the same gate set the driver runs.

Drive the cycle

pdca flow — the front door

usage: pdca flow [-h] [--from-csv FROM_CSV] [--from-briefs FROM_BRIEFS]
                 [--rehearse] [--no-publish] [--no-act] [--by BY]
                 [--lanes LANES] [--max-passes MAX_PASSES] [--auto-iterate]
                 [--no-inhibit]
                 [issue_ids ...]

Runs the whole cycle — Plan → Do → Check (gates → review → sign-off → publish) → Act — for one issue, a batch, or a batch planned from a tracker export. One id is a single cycle; several ids run as dependency waves, briefing any unbriefed id in one shared Plan session first; no ids plus --from-csv lets the planner pick the batch from the export. A split parent in the set hands its children to the run (07). Re-issuing the same command resumes a run that stopped.

Exit status, from the tool's own help: 0 every bundle finished (with one id, a stop for sign-off counts too); 1 a bundle did not finish, or the run could not start; 2 bad input (a bad pdca.toml, no ids, an unschedulable dependency graph); 3 every bundle finished, but a fold held an accepted bundle out of the run's integration line (it pushed no branch, or it conflicts with a same-wave bundle), so that work is on no line of the run.

Covered in: index, 03, 07.

pdca run — one issue, one halted state

usage: pdca run [-h] issue_id

Advances a single bundle until the driver reaches a halted state (AWAITING_SIGNOFF, COMPLETE, …): Do, gates, reviewer, assembly, STOP. It never advances an UNPLANNED bundle — there is nothing to do without a brief — and it runs no Plan, sign-off, publish or Act. This is the L2 rung of the maturity ladder; flow wraps it. Covered in: 02.

pdca init-issue — seed a bundle from a brief you already wrote

usage: pdca init-issue [-h] [--from-brief FROM_BRIEF] issue_id

Creates results/issue_<id>/ and copies the file given by --from-brief in as its brief.md, so the bundle starts PLANNED. The flag is required: to start from a ticket, use flow <id>, which plans. This bypasses the planner leaf and its advisory review, so it is for the offline toy brief, for hand-authored briefs, and for tests. Covered in: 02, 03.

pdca signoff — record the human verdict (§9)

usage: pdca signoff [-h] (--accept | --iterate-do | --iterate-plan |
                    --discontinue) [--by BY] [--delta DELTA] [--no-publish]
                    issue_id

Exactly one disposition is required.

Refusals, all exit 1: no SUMMARY.md yet; --accept while any §6 NEEDS-HUMAN item is unchecked (the C6 guard, which lists the open items); a SUMMARY with no §9 section. The other three dispositions are not guarded. On an accept that publishes, the exit code is publish's. Covered in: 05, 05.

pdca publish — contribute an accepted bundle as a draft PR

usage: pdca publish [-h] [--dry-run] [--no-pr] [--no-issue] [--by BY] issue_id

Check's closing step: branch from the bundle's target (or the run's integration line for a dependent), apply the patch, run the host_ci rows and the contribution check against the drafted commit message and PR body, push, open a draft PR, write publish.json. A failing host-CI row or contribution check refuses the push.

Covered in: 05.

pdca record — commit finished bundles to the instance repo

usage: pdca record [-h] [--dry-run] [issue_ids ...]

Commits every bundle whose cycle is over — COMPLETE, DISCONTINUED, RESOLVED — as one batch commit; with [records] mode = "pr" it pushes a records/<date> branch and opens one draft PR instead. A named id that is not terminal is excluded, loudly. Needs the [records] table in pdca.toml; once enabled, publish triggers it too. --dry-run prints the plan. Covered in: 05.

pdca revert — undo a published contribution

usage: pdca revert [-h] [--dry-run] [--by BY] issue_id

Reads the bundle's publish.json: a merged PR gets a draft revert PR that reverse-applies the bundle's own patch.diff onto the base; an open PR is withdrawn (gh pr close --delete-branch). The revert PR stays a draft for you. --by is recorded in revert.json. Covered in: 05.

Look at state

pdca status — the dashboard (also bare pdca)

usage: pdca status [-h] [issue_id]

One line per bundle, cheap-first: state, id, and markers — [N NEEDS-HUMAN] or [cheap: confirm] on a bundle awaiting sign-off, [blocked-by: …] for an unsatisfied Depends on, [oversized] from the size signal, and for a COMPLETE bundle [PR <url>] (with ↑<base> when the PR is stacked), [unpublished], or [close: no PR]. With an id, that bundle only. Exit 0. Covered in: index, 05.

pdca queue — the sign-off burn-down

usage: pdca queue [-h]

The AWAITING_SIGNOFF bundles, cheapest first — the order to work a batch's verdicts in. Exit 0.

pdca waves — preview the schedule

usage: pdca waves [-h] [issue_ids ...]

Prints the dependency-wave plan flow would run for the given ids (none: every in-flight briefed bundle) without building anything. An unschedulable graph — a cycle, an unresolved Depends on, a Merges with group under merge mode — is reported as unschedulable: with exit 1. Covered in: 03, 07.

pdca size — the a-priori size estimate

usage: pdca size [-h] [issue_ids ...]

Read-only. For each briefed bundle (or the ids given) prints the band — ok, watch, oversized — and the signals that fired, split into churn and patch size. Decides nothing and writes nothing. Covered in: 07.

Decompose

pdca split — propose, then materialize, a decomposition

usage: pdca split [-h] [--accept] [--ids IDS] [--force] issue_id

Without --accept, the splitter leaf drafts split-proposal.md — one full draft brief per child. With --accept, the deterministic half files one tracker sub-issue per child (unless --ids names existing ones, in proposal order), materializes the child bundles, rewrites the proposal's sibling labels to real ids, writes split-lineage.json everywhere, and closes the parent with close-disposition = split. Acceptance is transactional: everything is validated before any issue is filed or file written. A bundle already two splits deep is refused unless --force. Normally the planner runs both from inside the Plan session. Covered in: 07.

Gates and checks

pdca gates — run the deterministic Check gates

usage: pdca gates [-h] [--working-tree] [--promotions] [issue_id]

The same code the driver and CI call. With an id, that bundle's full gate set is run and printed, nothing recorded. --working-tree runs the repo-scoped rows only — the CI merge re-gate. --promotions lists the advisory rows that have passed in their promote_after most recent frozen cycles and so have earned promotion to gating (you flip gating = true yourself). Exit 1 when the gating overall is fail, else 0. Covered in: 01, 05.

pdca registry-check — a manifest line must point at a touched path

usage: pdca registry-check [-h] [issue_id]

A pure diff analysis for a bundle-scoped gate row: every line a patch adds to a declared registry or manifest file ([gates.registry_consistency] files, with an optional extraction pattern) must reference a path the same patch touches; anything else is cross-bundle contamination. The id may also arrive as $PDCA_BUNDLE, which is how a gate row calls it. Exit 0 with no registry files declared or no patch; 1 on a violation; 2 when no bundle can be resolved.

pdca contribcheck — the T4 contribution check

usage: pdca contribcheck [-h] [--no-issue] [issue_id]

Fails a contribution whose PR body lacks a user-impact opener or whose commit message and PR body lack the tracker id. At Check it reports deferred (the texts are drafted at publish); publish runs it for real before the push. --no-issue (or $PDCA_PENDING_ID) drops only the tracker-id rule. Exit 0 when nothing is wrong or there is no patch to contribute, 1 on a problem, 2 when no bundle resolves. Covered in: 05.

pdca revalidate — re-gate a frozen bundle against today's engine

usage: pdca revalidate [-h] [--date DATE] issue_id

Re-runs the same gate set over a COMPLETE bundle and writes an additive, dated stamp revalidation-<date>.json recording each row's old → new result. It never touches check-gates.json, check-gates.md or §9: the original decision stands, and a changed result in either direction is a signal, not a verdict.

pdca drift — which published patches no longer apply

usage: pdca drift [-h] [--no-fetch]

For every COMPLETE bundle with an open PR, git apply --checks its patch against the freshly fetched base in a throwaway worktree and reports the ones that need a rebase. Report-only: it mutates nothing and re-decides nothing. --no-fetch checks against already-fetched refs.

pdca try — run the patched build yourself

usage: pdca try [-h] issue_id

Materializes the bundle's patched tree from patch.diff and runs the project's [manual_test].cmd from it, inheriting your terminal, with no timeout — you quit the app to return. Advisory: it changes nothing in the bundle. Needs [driver].worktree on and a configured command; otherwise it prints a hint. Covered in: 05.

Act

pdca act — cross-cycle review tooling

usage: pdca act [-h] {index,log,resolve} ...

Manual, out-of-turn Act review over frozen (COMPLETE) cycles. These carry no cadence gate — [driver].act_cadence throttles only the flow's automatic Act. index and log default to the cycles frozen since the last review (the frontier in process/.act-reviewed); --all or --since widens the scope.

usage: pdca act index [-h] [--since SINCE] [--all]
usage: pdca act log [-h] [--since SINCE] [--all] --date DATE [--append]
usage: pdca act resolve [-h] [--location LOCATION] [--date DATE] signal

Covered in: 06.

pdca triage — ingest a published PR's review findings

usage: pdca triage [-h] [--repo REPO] [--date DATE] pr

Pulls the PR's reviews and review comments through gh api, classifies each finding as BUG, CONVENTION, NOISE or TEST-GAP, routes by class (a BUG on a merged PR files a tracker issue with a carry-forward note; the rest append candidate gate, rubric and exclusion entries to process/act-log.md), and registers every finding in the Act ledger under codex-pr:<slug>. Proposes only: it never edits pdca.toml or the rubric. pr is a URL, OWNER/REPO#N, or a bare number with --repo. Re-running ingests only new findings. Covered in: 06.

Maintenance

pdca doctor — report every prerequisite, change nothing

usage: pdca doctor [-h] [--strict]

One row per prerequisite — OK, MISSING, UNAUTH or WARN — each with a fix hint. Read-only and idempotent: it installs nothing and edits nothing. Run it after make install, and again whenever you add a gate, change a leaf's family, or a red gate might be a missing tool rather than a bad patch.

Rows derived from pdca.toml, so they follow your edits with no extra config:

• every distinct command-leaf argv[0] on PATH, with a per-family auth probe (UNAUTH for a Codex CLI without a login; WARN when no Claude credentials are found) — the builder's family is REQUIRED, the others optional;
• git with an identity, and gh present and authenticated (publish, merge and revert need it);
• the bundle root writable, and free space where the harness cuts worktrees;
• the tracker notes_cmd's tool resolvable;
• the leaf sandbox's dependencies (bubblewrap, socat) when a bounded [leaves.sandbox] exemption will be seeded — REQUIRED, because a sandbox that cannot start does not fail, it silently does not confine.

Rows you declare, one [[doctor.checks]] table each:

Exit codes: 0 when every REQUIRED row passes; 1 when a REQUIRED row failed ("REQUIRED checks failed — fix the lines above first"); with --strict, 1 on any non-OK row, WARN included — the CI setting.

The same rows are the registry a brief's External dependencies field is checked against, at Plan exit, at Do's exit and at Check, so a doctor row is not only a one-time readiness check. Covered in: 01, 03, 05.

pdca cleanup — reconcile bundles with the tracker

usage: pdca cleanup [-h] [--apply] [--repo REPO] [--by BY] [issue_ids ...]

Matches each bundle's state against its tracker issue and plans the matching action: a closed issue resolves a notes-only bundle (RESOLVED) or discontinues one awaiting sign-off; a COMPLETE or DISCONTINUED bundle whose issue is still open gets it commented and closed; a merged PR on an unaccepted bundle is reported, never auto-accepted. Dry run by default; --apply executes. --repo OWNER/REPO names the tracker when it is not the configured GitHub source; --by is the §9 attribution for discontinue records. A missing or unauthenticated gh aborts before any write. Covered in: 07.

pdca sweep — reclaim the harness's worktree footprint

usage: pdca sweep [-h] [--remove] [--dry-run]

Cleans the harness's own lane, integration and overflow worktrees — never bundle artifacts, never the primary checkout. Default: strip build state and keep the checkouts warm; --remove deletes the lane worktrees too (Do and try recreate them on demand); --dry-run reports only. Runs automatically at the publish/freeze boundary per [driver].sweep_worktrees; the manual command works even when that is "off". Exit 0. Covered in: 07.

Environment variables

Two groups. The first you may set to override pdca.toml for one run; the second the driver exports to the gate commands and leaves it spawns, so your scripts can read them.

The three base variables form a ladder the per-fix red→green row resolves in that order; Wyrd's run-verify.sh in step 01 reads them exactly so. Every pdca.toml key those commands read is in the configuration reference.

← 07 Cross-cutting · Index · next: 09 Configuration reference →