Merge pull request #100 from eduralph/docs/refresh-cli-references

docs: refresh stale CLI references after the flow-verb redesign

Author: eduralph

README.md

@@ -28,7 +28,7 @@ Act review.
 
 ```
 <your project>/
-  pdca.toml                 # driver config: bundle paths, the two leaf commands
+  pdca.toml                 # driver config: bundle paths, the model-leaf commands
   PCDA/
     quality-cycle.md        # the generic model (Plan/Do/Check/Act, 5/5/1) — reference
     quality-cycle/          # the full vendored spec (00–10), plain Markdown
@@ -63,16 +63,18 @@ command with `PYTHONPATH=src python -m pdca_harness.cli …`.
 
 ```bash
 pdca init-issue TOY --from-brief examples/toy/brief.md   # seed a bundle from a brief
-pdca run TOY              # Do → gates → reviewer → assembled SUMMARY → AWAITING_SIGNOFF
-pdca status              # all bundle states (cheap-first)
-pdca batch A B C         # fan the driver over many issues
+pdca flow TOY            # the whole cycle: Plan→Do→Check→sign-off→publish→Act
+pdca flow A B C          # several ids → batch fan-out + cheap-first sign-off queue
+pdca status              # all bundle states (cheap-first); bare `pdca` does the same
 pdca queue               # the cheap-first sign-off burn-down
 pdca gates TOY           # the deterministic gates (CI runs `pdca gates --working-tree`)
-pdca signoff TOY --accept --by you   # refused while §6 NEEDS-HUMAN is open (C6)
+pdca signoff TOY --accept --by you   # standalone accept (publishes on accept; --no-publish to skip), refused while §6 NEEDS-HUMAN is open (C6)
 ```
 
 The vertical slice runs **offline** out of the box (stub Do/gates/reviewer
-leaves), so `init-issue` → `run` → `signoff` works before you wire anything real.
+leaves), so `pdca flow TOY` drives a full cycle to COMPLETE before you wire
+anything real; `pdca flow --rehearse <id>` dry-runs the whole control flow in an
+isolated bundle root.
 
 ### 3. Make it yours
 
@@ -87,17 +89,24 @@ leaves), so `init-issue` → `run` → `signoff` works before you wire anything
   end-to-end with **stubbed** Do/gates/reviewer leaves so the loop runs offline.
 - **Single-sourced gates** — defined once in `pdca.toml` `[[gates.checks]]`, run by
   both the driver and CI via one `pdca gates` command (stub fallback until filled).
-- **Batch fan-out + sign-off queue** — `pdca batch` over N issues, `pdca queue`
+- **Publish on accept** — an accepted bundle opens a draft PR on the target branch as
+  the closing step of Check; `pdca flow` and a standalone `pdca signoff --accept` do
+  this by default (`--no-publish` to skip), and `pdca status` shows each COMPLETE
+  bundle's publish state (doc 07).
+- **Batch fan-out + sign-off queue** — `pdca flow A B C` over N issues, `pdca queue`
   cheap-first burn-down.
 - **In-driver lane concurrency** — `[driver].lanes = N` (`PDCA_LANES` /
-  `pdca flow|batch --lanes N`) fans the unattended Do + Check band across N workers in
+  `pdca flow --lanes N`) fans the unattended Do + Check band across N workers in
   one workspace; each gate sees its worker slot as `$PDCA_LANE` to keep checkouts /
   runners lane-private (doc 09).
+- **Per-cycle worktree isolation** — a cycle's Do/Check run in a git worktree off the
+  target base (`[driver].worktree`, on by default), so the host's primary checkout is
+  never mutated; the builder + gates see it as `$PDCA_WORKTREE` (doc 04).
 - **Mechanical STOP discipline** — `.claude/agents/builder.md` + a PreToolUse hook
   block the builder from marking a PR ready/merging; `reviewer.md` has execute-only
   scope; the decorrelated reviewer path is cross-vendor Codex via `AGENTS.md`.
-- **Act tooling (L4)** — `pdca act-index` is a read-only index of frozen cycles
-  that surfaces §6/§7/§10 and recurring signals; `pdca act-log` scaffolds a dated
+- **Act tooling (L4)** — `pdca act index` is a read-only index of frozen cycles
+  that surfaces §6/§7/§10 and recurring signals; `pdca act log` scaffolds a dated
   act-log entry with the considered bundles + patterns pre-filled (the deltas stay
   the human's). All four L-rungs of the maturity ladder are now present.
 - **Full spec** vendored under `template/PCDA/quality-cycle/` (reference docs,

docs/04-do.md

@@ -137,7 +137,7 @@ the close, and the C6 guard blocks accept until they consciously confirm it.
 It is a **hint, not a gate**. If the close was wrong, the human reopens to a fix path
 (iterate-to-Do); that archives the close marker and the *next* pass runs the real
 builder. A `manual-verification` close also seeds a `MANUAL-VERIFICATION.md` stub for
-the human to fill in. This is what makes a mixed-disposition `batch` safe: close
+the human to fill in. This is what makes a mixed-disposition batch run safe: close
 bundles drive themselves to sign-off cheaply alongside the ones that get built.
 
 ← [03 Plan](03-plan.md) · [Index](README.md) · next: [05 Check →](05-check.md)

template/CLAUDE.md.jinja

@@ -10,7 +10,7 @@ read it for tracker, branch targets, fixtures, and the conformance ruleset.
 
 `pdca` advances a result bundle through the cycle (`pdca status`, `pdca run <id>`,
 `pdca signoff <id> --accept`, `pdca publish <id>`), or runs it as one continuous
-Claude-driven flow (`pdca flow <id> [--from-csv …] [--no-publish] [--act]`). State is
+Claude-driven flow (`pdca flow <id> [--from-csv …] [--no-publish] [--no-act]`). State is
 the files in `{{ bundle_root }}/issue_<id>/`; nothing is hidden in a database.
 
 The driver is deterministic — **no model decides control flow**. The cycle has exactly

template/PCDA/quality-cycle/03-cycle-automation.md

@@ -10,7 +10,7 @@ status: active
 
 > One level below [02 - Cycle Artifacts](02-cycle-artifacts.md). How the PDCA cycle runs as a pipeline. Core principle: **automate where the work is mechanical (Do, plus Check's gates and reviewer), instrument where the work is human (Plan, Check's sign-off step, Act), never automate the human work away.** The pipeline runs unattended from the brief to the sign-off queue (where Check stops for the human) and resumes only when the human signs off Check; Act fires later, on a cadence, across batches of completed cycles. Living document.
 
-> **Continuous-flow extension.** Beyond the unattended `pdca run`, the driver can run the whole cycle as one continuous, Claude-driven flow — `pdca flow <id> [--from-csv …] [--act]` (or batch: `pdca flow --from-csv …`, one Plan session → several issues). This lifts the model from **two** leaves to **five**, *without* moving any control flow into a model: the planner (Plan — interactive, turns the human's documents into `brief.md`) and the sign-off and act leaves (interactive) instrument the human steps the principle above keeps human; Do (builder) and Check's reviewer stay **headless**. The state transitions, the gates, and the **C6 accept-guard remain deterministic code** — a leaf only fills an artifact. Leaves are configured in `pdca.toml` (`[leaves.*]`: `mode = stub|command`, `interactive`); set `PDCA_LEAVES_MODE=stub` to force the offline placeholders (CI / `make`).
+> **Continuous-flow extension.** Beyond the unattended `pdca run`, the driver can run the whole cycle as one continuous, Claude-driven flow — `pdca flow <id> [--from-csv …] [--no-publish] [--no-act]` (or batch: `pdca flow --from-csv …`, one Plan session → several issues; Act runs by default after COMPLETE, `--no-act` to skip). This lifts the model from **two** leaves to **six**, *without* moving any control flow into a model: the planner (Plan — interactive, turns the human's documents into `brief.md`), the sign-off and act leaves (interactive) instrument the human steps the principle above keeps human, and the publisher opens the draft PR on accept (Check's closing step); Do (builder) and Check's reviewer stay **headless**. The state transitions, the gates, and the **C6 accept-guard remain deterministic code** — a leaf only fills an artifact. Leaves are configured in `pdca.toml` (`[leaves.*]`: `mode = stub|command`, `interactive`); set `PDCA_LEAVES_MODE=stub` to force the offline placeholders (CI / `make`).
 
 > **Parallel-lanes extension.** Because the bundle is the unit of isolation, several cycles can run **concurrently** for throughput — see [09 - Parallel Lanes](09-parallel-lanes.md). The key discipline: mechanical isolation (a private working tree per lane) makes concurrent *execution* safe, but correctness *across* the parallel results is a separate problem — handled by **lane planning** (group same-area issues into one lane) and the **merge re-gate** (`gates.run_working_tree` over the merged tree + the draft PR), never by isolation alone. Parallelism stays in the unattended Do + Check band; the human touch points remain serial. Two realizations: N separate workspaces (zero machinery), or the **in-driver worker pool** — `[driver].lanes = N` (`PDCA_LANES` / `--lanes N`) fans the Do + Check band across N workers in one workspace, each exposing its lane slot to gates as `$PDCA_LANE`.