@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/shared/skills/do-document/references/implementation-flow.md

@@ -0,0 +1,105 @@
+# {Feature Name} — Implementation Flow
+
+> **Template version**: 1.0
+>
+> Reference for `/do-document --type impl`. It explains what each section of a generated
+> `implementation-flow.md` must contain and where to pull the content from — it is not itself a
+> filled-in implementation doc. Replace `{placeholders}` with real content when writing the actual
+> file to `agent-docs/doflow/<slug>/implementation-flow.md` for the active feature (same
+> slug-resolution mechanism the rest of the doflow chain already uses for
+> `requirement.md`/`design.md`/`plan.md` — do not introduce a second one).
+>
+> Every section below is narrative except **Changed Surfaces**, which is a table — comparative,
+> evidentiary data (a set of paths each paired with what changed) falls under the guidance tree's
+> `references/ARTIFACT_FORMAT.md` §6's rule to lay that out column-wise rather than as prose or
+> nested bullets.
+>
+> No section here is ID-bearing. This file — and any `implementation-flow.md` generated from it —
+> does not participate in `validate-artifacts.sh`'s index/detail check.
+
+---
+
+## Header [Required]
+
+Mirrors the metadata-header convention `design-template.md` already uses — a single line of
+bold-label/value pairs separated by `·`, with chain artifacts cross-referenced as plain relative
+paths (not markdown link syntax, matching `design-template.md`'s `./requirement.md`) — extended
+with `Branch` and links to `./design.md` and `./plan.md` in addition to `./requirement.md`, since an
+implementation summary sits downstream of all three:
+
+**Feature:** `[NNN-slug]` · **Branch:** `[branch-name]` · **Status:** Draft · **Created:** `[DATE]`
+· **Requirement:** ./requirement.md · **Design:** ./design.md · **Plan:** ./plan.md
+
+- **Feature / Branch** — resolved via the same active-feature mechanism the rest of the doflow
+  chain uses; do not hand-derive the slug from the directory name or guess it from `git branch`
+  independently.
+- **Status** — `Draft` while the summary is being written, `In-Review` once posted for review,
+  `Done` once accepted. This is the impl doc's own status, not `plan.md`'s task-checklist status.
+- **Created** — the date this implementation summary was generated, not when the feature started.
+- **Requirement / Design / Plan** — relative links into the same feature directory, exactly like
+  `design-template.md`'s header links to `./requirement.md`. Every doflow feature has all three by
+  the time `--type impl` is run (implementation follows planning), so none of these three links is
+  optional.
+
+## Summary [Required]
+
+1–3 sentences: what was built, in plain language a reader who has not touched the chain artifacts
+can follow. State the outcome, not the process — "added X so that Y" rather than a chronology of
+commits.
+
+`{one-to-three-sentence summary of what shipped}`
+
+## Key Decisions [Required]
+
+Narrative, not a table — decisions read as reasoning, not comparable rows. Cover the choices made
+*during* implementation that a reader would otherwise have to reconstruct from the diff: which
+approach was taken when more than one was viable, why a particular library/pattern/boundary was
+used, and anywhere the build surfaced a question `design.md` left open.
+
+Where a decision traces back to something `design.md` already recorded, reference it by section and
+ID rather than restating it — e.g. "Followed design.md §3 C2's boundary: the adapter owns
+serialization, per the Components & Boundaries split" or "Accepted the risk noted in design.md §7
+R2; see below for what that cost in practice." Decisions with no design.md antecedent (something
+that only became a decision once code was being written) still belong here, just without a
+back-reference.
+
+`{narrative: what was decided and why, cross-referencing design.md §3/§7 where applicable}`
+
+## Deviations from Plan/Design [Required]
+
+Narrative. Anywhere the actual implementation diverged from what `plan.md`'s tasks or `design.md`'s
+shape called for — a task done differently than scoped, a component boundary that moved, a step
+skipped or added — explain what changed and why. This is what lets a future reader trust
+`plan.md`/`design.md` as history without re-diffing them against the code.
+
+If nothing diverged, write exactly:
+
+`None — implemented as designed.`
+
+## Changed Surfaces [Required]
+
+A table, populated from `git diff` (or the equivalent comparison against the branch's base) for the
+feature's commits — not hand-recalled from memory. One row per changed path; "what changed" is a
+short phrase, not a full diff.
+
+| Path | What Changed |
+|------|---------------|
+| `{path/to/file}` | `{one-line description of the change}` |
+
+## Testing & Verification [Required]
+
+Narrative: what was run and how the change was verified — unit/integration tests executed, manual
+checks performed, and their outcome. Reference the plan's verification bar or design's acceptance
+criteria where the testing directly maps to one of them, but describe what actually happened, not
+what was merely planned.
+
+`{narrative: tests run, manual verification performed, and results}`
+
+## Follow-ups / Known Gaps [Required]
+
+Narrative. Anything intentionally left undone — known limitations, deferred work, follow-up tasks
+worth tracking separately — belongs here so it isn't lost once the feature is marked complete.
+
+If there are none, write exactly:
+
+`None.`

package/core/shared/skills/do-document/references/index_generator.md

@@ -0,0 +1,9 @@
+# Project Index & Architecture Reference
+
+Methodology for creating whole-repository knowledge indexes:
+
+## Index Sections
+1. **System Overview**: High-level purpose, tech stack, and primary runtime architecture.
+2. **Directory Map**: Key directories, responsibilities, and boundary layers.
+3. **Core Workflows**: End-to-end trace of primary data flows and API request paths.
+4. **Key Invariants**: Non-obvious architectural constraints and governance rules.

package/core/shared/skills/do-document/references/user-guide.md

@@ -0,0 +1,22 @@
+# User Guide Template
+# Use this template for creating user-facing guides and tutorials.
+
+## 🎯 Goal: [Feature Name]
+What the user will be able to achieve after following this guide.
+
+### 📋 Prerequisites
+- Required tools/accounts.
+- Necessary permissions.
+- Prior knowledge needed.
+
+### 🚶 Step-by-Step Instructions
+1. **Step One**: Action $\rightarrow$ Expected Result.
+2. **Step Two**: Action $\rightarrow$ Expected Result.
+   - *Tip*: Add a pro-tip or common pitfall here.
+3. **Step Three**: Final validation.
+
+### ✅ How to Verify
+How the user knows they succeeded.
+
+### ❓ Troubleshooting
+Common issues and their resolutions.

package/core/shared/skills/do-execute-plan/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: do-execute-plan
+description: "Execute plan.md's task checklist: subagent-driven orchestration over named specialist archetypes (system-architect, core-implementer, quality-guardian) with prerequisite gates, readiness contracts, and parallel execution. Use whenever requirement.md, design.md, and plan.md exist and the next step is building the plan's tasks through subagents, or when the user says 'execute the plan', 'run the plan', 'start building', or 'implement phase N'. Always activate this skill to orchestrate multi-task implementation plans with write-set isolation."
+argument-hint: "[--scope next|phase:N|all|resume] [--review] [--scaffold]"
+effort: high
+---
+
+# do-execute-plan
+
+Phase 4 of the DoFlow chain. Executes the task checklist in `plan.md` using specialist subagent archetypes with readiness validation and progressive disclosure.
+
+## Invocation
+```text
+/do-execute-plan [--scope next|phase:N|all|resume] [--review] [--scaffold]
+```
+
+## Behavioral Flow
+
+1. **Resolve State & Prerequisite Gate**:
+   - Every DoFlow runtime call in this skill — `paths`, `prereqs`, `parallel-check`, `task-brief` —
+     goes through the runtime seam. Resolve it **once** here and reuse `$DOFLOW` for all four:
+
+```bash
+# Resolve the DoFlow runtime: nearest project install wins, then the global one.
+D=$PWD; while [ "$D" != / ] && [ ! -x "$D/.doflow/scripts/doflow/bin/doflow-run" ]; do D=$(dirname "$D"); done
+DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || DOFLOW="$HOME/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || { echo "doflow: no runtime found in any .doflow/ above $PWD, nor at $HOME/.doflow. Run: npx @khoavu882/doflow install -t <harness>" >&2; exit 2; }
+```
+
+Run every command below from the project root — the walk-up starts at `$PWD`. On exit 2, print the message verbatim and stop; it names every path searched.
+
+```bash
+"$DOFLOW" paths --json
+```
+
+   - Enforce hard prerequisite gate: `"$DOFLOW" prereqs --require-plan` (requires
+     `requirement.md`, `design.md`, `plan.md`).
+   - Read `<feature_dir>/state.md` if it exists — the cross-session execution record, per
+     `MODE_Task_Management.md`'s "Session Start" sequence. A `complete` row in its Task Ledger means
+     that task is done: never re-dispatch it, resume at the first task without one. No `state.md`
+     yet is the normal first-run case, not a gap.
+
+2. **Propose the Task Class; the Runtime Validates It**:
+   - Name exactly one class id for the work this run executes. `/do-flow` passes one when it
+     invoked this skill; a user who named one settles it; otherwise derive it from `plan.md`.
+     ```bash
+     "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-execute-plan --json
+     ```
+Branch on the returned `outcome` field, not the exit code.
+- **`ACCEPTED`** — the returned `workflow` is this run's plan of record; read `stages`, `gates` and `handoff` off it rather than from memory.
+- **`REJECTED`** — **stop.** Print `message` verbatim (it already names `validClasses` and any `suggestions`), ask the user to choose from `validClasses`, then re-validate. Never substitute `feature`.
+  A rejection may be about **you** rather than the class (`reason: caller-not-a-stage`). Then the fix is to propose one of the classes in `fit.hostingClasses`, or to hand the work to the skill this class names for the stage you meant — not to re-propose the same class.
+- **Exit 2** — surface the message verbatim and stop.
+
+   - Take the readiness template from the returned workflow's implementation stage: the entry in
+     `stages[]` with `mutatesSource: true`, whose `readinessTemplate` names the contract step 4
+     grades against. Do not pick a template by hand.
+   - If the accepted workflow has no stage with `mutatesSource: true` — read
+     `hasImplementationStage` off the returned object rather than recalling which classes those are
+     — this skill is the wrong tool for that class. Say so and stop rather than executing tasks the
+     workflow never declared.
+   - Also derive `<expected gate id>`: among `gates[]`, the one entry whose `afterStage` equals the
+     stage immediately preceding this skill's own stage in `stageIds[]` (`gate-a` in `feature`, since
+     `gate-a`'s `afterStage` is `planning`, the stage right before `implementation`) — `null` if no
+     gate is anchored there. No shipped workflow anchors two gates to the same stage, so this is
+     always at most one entry; do not hardcode `gate-a`, derive it this way so a differently-shaped
+     workflow's own gate is found the same way. Step 3 needs this to tell "the gate that belongs to
+     this stage" apart from any other gate `catch-up` might stop on.
+
+3. **Position the Run, and Resolve the Approval Gate Standing Before This Stage**:
+   - This stage is the one the accepted workflow anchors an `approval`-kind gate directly *before*
+     (`gate-a`, "Before implementation", in the `feature` workflow — the gate whose `afterStage` is
+     the stage preceding this skill's own). `/do-plan` deliberately leaves it open: an approval gate
+     is answered by the human who is asked, and this skill is where that question lands when nothing
+     else has already asked it. Until it is decided, the state machine refuses this stage's own
+     completion, so resolve it here rather than at step 10.
+   - One `orchestrate --action catch-up` call positions the run, stopping either on this stage or
+     on any gate in the way; **branch on its `caughtUpTo` / `reason`, not on the exit code.** That
+     call and every branch off it — the expected gate, an earlier stage's gate, a blocking mutating
+     stage, an already-recorded stage, a finished run — are in this skill's own
+     `references/run_position.md`. Read it before running this step; carry the `caughtUpTo` it
+     lands on to step 10.
+
+4. **Readiness Evaluation (Contract State)**:
+   - Evaluate a task's contract before dispatching it, run from the project the task belongs to.
+     This skill is an orchestrated run, and says so:
+     ```bash
+     "$DOFLOW" readiness --task-class "<template from step 2>" --task-id "<task id>" --mode workflow --json
+     "$DOFLOW" evidence --task-id "<task id>" --json
+     ```
+   - **Both `--task-class` and `--task-id` are required.** Omitting either exits 2 and names the
+     valid set. Pass them explicitly rather than letting anything default: a verdict computed for
+     another task, or against another class's contract, is worse than no verdict.
+   - **Act on `stageEntry.decision`, not the exit code and not your own reading of `state`.** The
+     entry policy is the runtime's: `ENTER` → dispatch the task; `GATHER_FIRST` → gather the named
+     requirements before dispatching; `ASK_USER` → ask the owed decision and wait; `STOP` → stop
+     and surface the conflicted claim. The four underlying states remain the entire state
+     vocabulary — `READY`, `NEEDS_EVIDENCE`, `NEEDS_USER_DECISION`, `BLOCKED` — and none of them is
+     ever reported as a number, a percentage, or a confidence.
+   - Only `bug`, `feature`, `refactor`, `trivial-edit` and `dependency-change` have templates. On
+     any other class the verb exits 1 and lists the valid keys; that is the correct answer, not a
+     gap to route around.
+   - All four states are reachable, so a verdict is about this task rather than about the runtime.
+     Dispatch no task until the run's record, below, is `READY`. `BLOCKED` is a claim whose evidence contradicts itself, and `NEEDS_USER_DECISION`
+     is what `--user-decision-pending` returns. A first call on a task with nothing recorded grades
+     an empty ledger — that is a checklist, not a defect.
+   - **The run's record comes first.** The handoff, `verify` and the edit hook read the record
+     keyed on the feature slug (the run's task id), so before the first dispatch record the
+     `affected_components` evidence, then evaluate with the plan's stated inputs:
+     ```bash
+     "$DOFLOW" evidence --task-id "<slug>" --action add --batch <batch>.json --json
+     "$DOFLOW" readiness --task-class "<template from step 2>" --task-id "<slug>" --mode workflow \
+       --verification-plan "<plan.md §7 Validation Strategy>" --scope "<comma-separated paths from plan.md §4>" --json
+     ```
+     The batch holds one item: `kind` `structural` or `semantic-retrieval`, `provenance`
+     `extracted`, `locator` a file in this repository (`plan.md`), `establishes`
+     `["affected_components"]`, and `content` summarizing the components and files `plan.md` §4
+     lists (schema: the guidance tree's `references/EVIDENCE_LEDGER.md`). `scope_clear` and
+     `verification_plan` come from the two stated inputs; `--scope` as a path list is also what
+     `verify` bounds the change by. A refusal names the command to run again.
+   - `readiness` also accepts `--verification-plan`, `--scope` and `--invariants` — the verb's own
+     arguments, unrelated to this skill's `--scope`. Those are inputs
+     you **state**, not evidence the gate measured: the report lists them back as `callerAsserted`
+     in JSON and `Caller-stated:` in the human report, and a requirement satisfied that way links
+     no evidence. Pass them when they are true, and when you report the verdict say which part of
+     it rests on a statement rather than on a record. Never pass one to move a state.
+   - Do not recall the contract from memory — the templates are versioned and the command reads
+     them. This skill's own `references/readiness_gate.md` carries the per-class requirements, what each state
+     means, and exactly which input produces it. Read it before acting on a verdict, and never
+     write `READY` yourself: the gate did not say it.
+
+5. **Scaffold Generation (`--scaffold`)**:
+   - When invoked with `--scaffold`, emit a reviewable code scaffold under `<feature_dir>/scaffold/`
+     instead of executing tasks: the source layout, signatures and test stubs that `requirement.md`,
+     `design.md` and `plan.md` imply, plus a contract frame per external `depends-on:` service.
+     Signatures only, never implementation logic, and never a write into the project's source tree.
+   - The in-scope half is deterministic and is **run**, not reasoned through — one verb through the
+     same seam as every other runtime call, `"$DOFLOW" scaffold --json`, which resolves the active
+     feature itself. The external-dependency half is an algorithm you execute. Both, with the exact
+     commands, live in this skill's own `references/scaffold.md`. Report its `status` and,
+     specifically, whatever it lists as skipped or not evaluated — a partial scaffold read as
+     complete is worse than none.
+
+6. **Task Selection & Parallel Dispatch**:
+   - Read the guidance tree's `references/ORCHESTRATION.md` before dispatching agents;
+     it governs briefs, tools, running work, verification, and questions.
+   - `--scope` selects what this run executes, and takes exactly one value: `next` (the next
+     pending task, the default), `phase:N` (one phase), `all` (every pending task), or `resume`
+     (pick up where an interrupted run stopped). Where an interrupted run stopped is read from the
+     recorded state, never reconstructed from the transcript.
+   - Compute dispatch groups with `"$DOFLOW" parallel-check --phase=<N> --json` — it
+     groups by phase and `owner:`, and returns the cross-group write-set collisions
+     (`group_overlaps[]`, `group_serialize[]`) that decide what may run concurrently. Do not derive
+     write-set isolation by inspection; it is computed.
+     **Branch on the `parallel_safe` field, never on the exit code.** With `jq` unavailable this
+     verb exits 0 and reports `"parallel_safe": null` — a zero exit is not a grant of concurrency.
+     `null`, or a missing field, means unknown: run the tasks serially and say why.
+     Build each group's brief with
+     `"$DOFLOW" task-brief --group=<phase>:<owner> --tasks=<csv>`. Full protocol, field
+     meanings, and the serial and per-task fallbacks: this skill's own `references/parallel_dispatch.md`.
+   - Before dispatching each task, compile its prior context — the same plan task id step 4 graded:
+     ```bash
+     "$DOFLOW" context-pack --task-id "<task id>" --json
+     ```
+     **Exit 1 means the pack came back empty.** Unlike design and plan, this call sits right at the
+     point a subagent is about to be handed the task and told to act — so proceeding as though
+     nothing happened is exactly the failure this feature exists to remove. An empty pack here can
+     still be legitimate: step 4 lets a task reach `READY` on `callerAsserted` inputs alone, which
+     link no evidence. Do not withhold dispatch on this alone — readiness already governs whether the
+     task may be worked. Instead, carry the empty result into the group's brief itself: state in the
+     dispatch, next to the task-brief output, that no prior evidence or claims were compiled for this
+     task, so the subagent works from the plan/design text `task-brief` already supplies without
+     assuming a grounding evidence base that isn't there. A non-empty pack is included in the brief
+     as the subagent's prior context, same handoff.
+   - Claim each task before dispatch and finish it with evidence: `references/task_attempts.md`.
+   - Dispatch tasks to appropriate specialist archetypes:
+     - Architecture & Schema $\rightarrow$ `system-architect`
+     - Code Implementation & Refactoring $\rightarrow$ `core-implementer`
+     - Test Automation & Quality $\rightarrow$ `quality-guardian`
+   - Name a model tier on every dispatch — an omitted tier inherits the session's model. Pass the
+     tier from task-brief's `record.tier` as the dispatch model; for review passes and the limit
+     where a harness honors only `model: inherit`, see `references/MODEL_SELECTION.md`.
+
+7. **Batch the Phase's Evidence**:
+   - One pass at each phase boundary, never one call per fact. Use the plan task id — the same id
+     step 4 graded — for every `evidence`, `claim` and `readiness` call about that task; a
+     different id reads a different task's record.
+     ```bash
+     "$DOFLOW" evidence --task-id "<task id>" --action add --batch <batch>.json --json
+     "$DOFLOW" claim --task-id "<task id>" --action add --statement "<one conclusion>"
+     ```
+Item schema, provenance rules, and the refused-field list: the guidance tree's `references/EVIDENCE_LEDGER.md`. Read it before writing the batch.
+   - This phase's items are its completion report, and a subagent's assertion never becomes fact by
+     a subagent having made it.
+   - Add each conclusion as a claim in this same pass. Each is stored as a `hypothesis` and becomes
+     supported only through linked evidence:
+     `"$DOFLOW" claim --task-id "<task id>" --action link --claim-id <claim id> --evidence-id <evidence id> --relation supports|contradicts`.
+     An evidence id the ledger does not hold is **refused** — exit 2, naming the id — not graded,
+     so record the batch first and link afterwards. A claim carrying both fresh support and fresh
+     contradiction becomes `conflicted`, which is what makes step 4 report `BLOCKED`.
+
+8. **Update `state.md`**:
+   - One checkpoint per phase (or per task, on a `--scope next` run), immediately after step 7's
+     evidence/claim batch for that phase — same boundary, not a separate pass to remember later.
+   - No `<feature_dir>/state.md` yet: create it from the template. The template is
+     `templates/doflow/state-template.md` in the install step 1 resolved: take `constitution_base`
+     from that JSON and swap its trailing `guidance/references/CONSTITUTION_BASE.md` for that path.
+     Fill `[PLAN_PATH]` from that same resolution's `plan` field, verbatim (repo-root-relative,
+     exactly as the resolver returns it) — `state.md` and `plan.md` both sit at the feature dir's
+     own root under both layouts, the same single shared location, and the resolver's own field is
+     what confirms it rather than a hand-computed guess.
+   - Every checkpoint: append the finished task(s) to the Task Ledger (`Commits` as the actual
+     `[base7]..[head7]` range once committed, or `uncommitted (working tree)` when this run doesn't
+     commit on its own), move them from **In Progress** to **Completed**, and rewrite **Status**,
+     **Blocked**, **Findings** and **Next Action** (the next pending task) in place, deleting a
+     blocker or finding that no longer applies, so a resumed session (or a different one) can pick up
+     from this file and `git log` alone, never from conversation memory. A `Findings` entry records
+     a review finding deliberately left unfixed (rare); write "None." otherwise, never omit it.
+   - This is bookkeeping, not a gate: a write failure here degrades resumability, not correctness —
+     report it and continue rather than treating it as a task failure.
+
+9. **Phase Quality Review** (`--review`, opt-in):
+   - Off by default. With `--review`, review each phase on completion for spec compliance before
+     advancing. Without it no per-phase review runs: the completion summary says "per-phase review:
+     not requested"; review at `/do-code-review` after the test stage (or the caller's final review).
+
+10. **Record the Handoff**:
+    - Before recording it, follow the decision step in the guidance tree's
+      `references/WORKFLOW_HANDOFF.md`.
+    - Once per `/do-execute-plan` invocation, at the last `state.md` checkpoint this run writes —
+      not once per phase, since the stage hands off once however many phases it executed. The stage
+      id is step 3's `caughtUpTo`, which the run is already positioned on; there is no second
+      `catch-up` call and no `status` call to make here.
+    - **First: is this run a completion or a checkpoint?** Count `plan.md`'s still-unchecked task
+      lines with `grep -cE '^- \[ \] [A-Z]+\.[0-9]+'`. The task-id prefix is load-bearing: a bare
+      `^- \[ \]` also matches the plan's own `- [ ] All tasks checked` completion-criteria line, so
+      it reports a remaining task on a finished plan and records a checkpoint where a completion
+      was owed. Any genuinely remaining task makes this handoff a checkpoint (`annotate`, never
+      `complete-stage`); zero remaining is the completion flow. Both branches, their exact
+      commands, the readiness record the handoff reads, and how to report the
+      resulting `disposition`: this skill's own `references/handoff_record.md`. Read it before
+      running this step.
+
+**Stop when** every review finding the contract names has an answer or a stated gap, **and** the last round produced no new review finding. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing.
+
+## Embedded feature research
+
+For an external fact gap or explicit request, follow the conditional protocol in `../do-document/references/embedded-research.md` before stage completion.
+
+## Boundaries
+**Will:** Propose a task class and have the runtime validate it, put the approval gate standing
+before this stage to the user — but only when the run still reports it open — and record their
+answer, execute planned tasks with subagents, consult the readiness contract per task, batch each
+phase's evidence and claims, ensure write-set isolation, and record the stage handoff through
+`orchestrate`/`render-audit` — as a completion when every plan task is checked, as a checkpoint
+annotation when this run finished only part of the plan.
+**Will Not:** Bypass missing spec artifacts, modify source code while readiness reports `BLOCKED`,
+hand this stage off while any plan task is still unchecked, re-ask a gate the run no longer reports
+as open, execute under a class the runtime rejected or replaced with `feature`,
+call `readiness` for a stage that declares no template; or express evidence, an estimate or readiness as a number, a percentage or a confidence.

package/core/shared/skills/do-execute-plan/references/handoff_record.md

@@ -0,0 +1,57 @@
+# Step 10 — recording the stage handoff
+
+The procedural detail behind `/do-execute-plan`'s step 10. `SKILL.md` carries when the step runs
+and the completion-vs-checkpoint decision it turns on; what follows is how each branch is carried
+out. `readiness_gate.md`, referenced below, sits beside this file.
+
+- **First: is this run a completion or a checkpoint?** Re-read `plan.md`'s task checklist and
+  count the task lines still unchecked. A real task line matches `^- \[ \] [A-Z]+\.[0-9]+` (a
+  phase letter, a dot, a number — `- [ ] B.2`); the pattern deliberately excludes the generic
+  `- [ ] All tasks checked` line in the plan's own "Completion criteria" section, which carries
+  no phase-letter id and is not a task.
+  ```bash
+  grep -cE '^- \[ \] [A-Z]+\.[0-9]+' "<plan path>"
+  ```
+  **Any such line remaining means this run's handoff is a checkpoint, not a completion** — the
+  normal outcome of a `--scope next` or `--scope phase:N` run, which finishes some of the plan by
+  design. Record the checkpoint and stop; do **not** attempt `complete-stage`, which would hand
+  the stage off while tasks nobody executed are still open:
+  ```bash
+  "$DOFLOW" orchestrate --action annotate --task-id "<slug>" --node "<stage id>" --note "<checkpoint: N of M tasks done, scope was --scope next|phase:X>" --json
+  ```
+  Only when zero such lines remain does the completion flow below run.
+- **Then: confirm the readiness record before completing.** This stage is the workflow's
+  `mutatesSource` stage, so the handoff reads the record `readiness` wrote and refuses without a
+  `READY` one made before the call; it evaluates nothing itself (`readiness_gate.md`).
+  1. The `affected_components` evidence batch and the `READY` readiness call, both under the
+     feature slug, happen before Phase 1 is dispatched (`SKILL.md` step 4), not here. A refusal names the `readiness` command to run:
+     run it, gather what it lists until it reports `READY`, then repeat the handoff.
+  2. Then record the handoff. This is the genuine completion case (every task checked), the one
+     case where reaching this stage's candidate and recording it as done are the same fact, so
+     `handoff`'s always-complete-on-reach behavior is exactly right here and cannot mismark
+     unfinished work: the checkpoint branch above never reaches this call:
+     ```bash
+     "$DOFLOW" orchestrate --action handoff --task-id "<slug>" --task-class "<class>" --calling-skill do-execute-plan \
+       --note "<one line, e.g. tasks A.1–E.5 complete>" --result passed --json
+     ```
+     `--task-class` still matters here even though the run already carries one: a conflicting
+     value is refused, so passing it is a check, not a formality. `--result` reflects step 9's phase
+     review (when it ran) and step 6's own check runs, never asserted as `passed` when a review
+     finding was left unfixed. Without `--review` the result rests on the verification the run did,
+     and the note says the per-phase review was not requested.
+- **Report the resulting `disposition` plainly.** `completed` means a `READY` record was
+  found and the cursor advanced to the verification stage — check
+  its `awaitingGate`; `null` means no gate follows this stage in this workflow. `deferred` means
+  a gate, an unfinished mutating stage elsewhere, or a rejected run prevented it — report
+  `reason` plainly, this stage resolves no gate. If the handoff refuses for readiness,
+  report exactly what is unmet and fix that with the `readiness` command it names — do not
+  re-run under a class that grades looser, never assert `READY` yourself, and do not swallow the
+  failure into an `annotate`. The `annotate` path above belongs to the unfinished-tasks case
+  alone; it is not a catch-all for an unexpected readiness failure here. Finish by rendering the
+  trail — the `--slug` value attaches with an `=`; a space-separated one is rejected with an
+  error rather than silently rendering the wrong feature's trail:
+  ```bash
+  "$DOFLOW" render-audit --slug="<slug>" --json
+  ```
+- Same standing as step 8's `state.md` write: bookkeeping, not a gate. A failure here degrades
+  the trail, not the correctness of the work already done — report it and continue.

package/core/shared/skills/do-execute-plan/references/parallel_dispatch.md

@@ -0,0 +1,92 @@
+# Parallel Subagent Orchestration Reference
+
+Protocol for safe concurrent task execution by specialist subagents.
+
+**Write-set isolation is decided by the `parallel-check` verb, not by judgement.** The commands
+below compute the grouping and the overlap set deterministically from `plan.md`. Read their output;
+do not re-derive it by eye. If a verb is unavailable, say so and run the tasks serially (one at a
+time) rather than guessing at which tasks are safe to run together.
+
+## Resolving the runtime
+
+`SKILL.md` step 1 already resolved `$DOFLOW`; reuse it. Resolving is a search of the filesystem, not
+of this file's location — a relative path would resolve against the working directory, which is the
+project root, not the skill. If `$DOFLOW` is unset (this file read on its own), resolve it first:
+
+```bash
+# Resolve the DoFlow runtime: nearest project install wins, then the global one.
+D=$PWD; while [ "$D" != / ] && [ ! -x "$D/.doflow/scripts/doflow/bin/doflow-run" ]; do D=$(dirname "$D"); done
+DOFLOW="$D/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || DOFLOW="$HOME/.doflow/scripts/doflow/bin/doflow-run"
+[ -x "$DOFLOW" ] || { echo "doflow: no runtime found in any .doflow/ above $PWD, nor at $HOME/.doflow. Run: npx @khoavu882/doflow install -t <harness>" >&2; exit 2; }
+```
+
+Run every command below from the project root — the walk-up starts at `$PWD`. On exit 2, print the message verbatim and stop; it names every path searched.
+
+## 1. Compute the dispatch groups
+
+```bash
+"$DOFLOW" parallel-check --phase=<PHASE> --json
+```
+
+Returns, alongside the legacy per-task fields (`parallel_tasks`, `sequential_tasks`, `overlaps`,
+`parallel_safe`, `serialize`):
+
+| Field | Meaning |
+|---|---|
+| `groups[]` | `{id, owner, tasks[], files[]}` — one dispatch per entry. `id` is `<phase>:<owner>`. |
+| `group_overlaps[]` | `{path, groups[]}` — groups whose write sets collide on `path`. |
+| `group_serialize[]` | Group ids that **must not** run concurrently with each other. |
+| `unowned_tasks[]` | Tasks with no `owner:`; each forms a singleton group with `owner: null`. |
+
+Tasks sharing an `owner:` in the same phase merge into one group — one subagent runs them in
+sequence, which is why two tasks in the *same* group may safely touch the same file. That is the
+distinction between `overlaps` (per-task, still reported) and `group_overlaps` (cross-group, the
+one that governs dispatch).
+
+## 2. Dispatch
+
+- Launch **one subagent per group**, concurrently, except that any two groups both listed in
+  `group_serialize[]` must be run one after the other.
+- Never split a group across subagents: its tasks are ordered and may share files.
+- When the grouping cannot be computed, suppress fan-out entirely — every task runs serially in
+  dependency order. Say that fan-out was suppressed and why.
+- When groups are unavailable but per-task data is not, fall back to per-task dispatch using the
+  legacy `overlaps`/`serialize` fields.
+
+## 3. Build each group's brief
+
+```bash
+"$DOFLOW" task-brief --group=<PHASE>:<OWNER> --tasks=<id,id,...> --harness=<your harness id> --json
+```
+
+Writes the group brief and returns its path in `path`. The brief carries the shared preamble
+once (where this fits, global constraints, component boundary), then a per-task block for each id in
+the order given. Pass this file to the subagent — it is the whole contract for that dispatch.
+
+For a single-task group the brief is byte-identical to `--task=<id>` output, so a one-task group and
+an ungrouped task are the same dispatch.
+
+Report paths come from the brief path the same call returned — the workspace is the directory
+holding it, and each task's report is `<workspace>/task-<ID>-report.md`. Each task writes its own
+report before the next one starts.
+
+Both verbs reject path traversal in group and task ids with exit 2. On any non-zero exit, stop and
+surface the error — do not proceed with a partial grouping.
+
+## 4. Phase-level quality review
+
+Only when `--review` was given: once every group in a phase reports complete, run an integrated
+phase quality review before advancing. Without it, a group's completion goes straight to the
+evidence and `state.md` steps. A finding that does not clear on the first fix goes to
+`"$DOFLOW" recover --error "<what failed>" --failed-check "<check id>" --iteration <n> --json`.
+Exit 0 means a bounded retry is available (`canRetry: true`); exit 1 means the loop must stop —
+report where it stopped and why, quoting the returned `reason`. The bound is the runtime's
+(`maxRecoveryIterations` in `verify --action contract`); you do not choose the count.
+
+## Behavioral posture
+
+For complex multi-step orchestration and execution checkpoints, consult the Task Management mode in
+the installed guidance tree: `<config-dir>/guidance/modes/MODE_Task_Management.md` (for example
+`~/.doflow/guidance/modes/MODE_Task_Management.md`). It sits under the DoFlow config directory, not
+beside this file.