@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

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

@@ -1,6 +1,14 @@
 # `--scaffold` — turning the plan into a reviewable code scaffold
 
-Read this file only when `/do-execute-plan --scaffold` is the active invocation. It is step 3 of
+## Contents
+
+- What it produces
+- Two cases, one output tree
+- Part 1 — in-scope scaffold from the three artifacts
+- Part 2 — external dependencies (cross-service contract frames)
+- Constraints (carried from the design — do not relax these)
+
+Read this file only when `/do-execute-plan --scaffold` is the active invocation. It is step 5 of
 `do-execute-plan`'s Behavioral Flow, factored out here per Anthropic's progressive-disclosure
 guidance so the other invocation modes (`--scope next|phase:N|all|resume`, and the `--review`
 modifier) don't pay the token cost of this algorithm on every invocation.
@@ -80,7 +88,7 @@ do not restate its counts from memory or re-derive them by reading the tree.
 Run it from the project root: the verb resolves which feature is active exactly the way `paths`
 does, from the working directory. The one case worth knowing about is a non-git root holding more
 than one feature directory — there the resolver cannot choose, and exits 2 naming every candidate.
-Ask the user which one via `AskUserQuestion` and re-run as `"$DOFLOW" scaffold --slug=<chosen>
+Ask the user which one via the question tool and re-run as `"$DOFLOW" scaffold --slug=<chosen>
 --json`; do not pick for them.
 
 Exit codes follow the runtime's uniform contract: `0` complete, `1` a finding you must report to the
@@ -93,14 +101,14 @@ What the generator does, so you can read its output rather than guess at it:
 1. **Reads all three artifacts** and records each one's SHA-256 in `MANIFEST.md`. A missing one, or
    a `plan.md` with no parseable task list, is `BLOCKED`: no source files are written.
 2. **Builds the traceability chain** — a task's `[US#]` resolves through `requirement.md`'s FR index
-   to its requirements, and through `design.md` §3 to the components serving them. That chain is
+   to its requirements, and through `design.md` Components & Boundaries to the components serving them. That chain is
    what puts a real FR / component / task in every file header instead of a generic banner.
 3. **Mirrors the intended source layout** from every task's `files:` value into `scaffold/src/`,
    keeping each path exactly as the plan wrote it and appending `.stub`. In a repository whose code
    already lives in `src/`, that reads as `scaffold/src/src/runtime/thing.js.stub`; the doubling is
    deliberate, so a path can never collide with `MANIFEST.md` or `contracts/`.
 4. **Emits per-file frames** in the language of the file's own extension — the plan already stated
-   it, so nothing is inferred. Where `design.md` §4 declares an interface for the file's component,
+   it, so nothing is inferred. Where `design.md` API / Interface Contracts declares an interface for the file's component,
    that block is carried through verbatim as a quoted comment; where it does not, the file gets one
    clearly labelled placeholder signature and is listed under **Emitted without a declared shape**.
    No API nobody wrote down is ever invented.
@@ -397,7 +405,7 @@ rather than restated as prose.
 - Never write outside `agent-docs/doflow/<slug>/scaffold/` — not into the source tree, and not
   into a target service's own repo (including the dependency service scanned for language
   inference in Part 2 step 4 — read-only). This is the one property the whole artifact rests on, and
-  `test/guards/scaffold.test.js` enforces it by running the generator against a filesystem that can
+  `test/guards/scaffold.test.ts` enforces it by running the generator against a filesystem that can
   only reach the feature directory.
 - `code/`/`data/`/`mock/` content is pinned, not freeform: signatures and type/data shapes only,
   zero implementation logic — in the inferred language, or the pinned generic-pseudocode grammar
@@ -422,9 +430,9 @@ rather than restated as prose.
   generated `code/`/`data/`/`mock/`/`default/` output directory — still not a write outside
   `agent-docs/doflow/<slug>/scaffold/` (the first Constraint above still holds), but visually
   confusing; not auto-detected or renamed.
-- The one hard gate is `do-execute-plan` step 1 (`"$DOFLOW" prereqs --require-plan`) — neither Part
-  of this file adds a gate of its own. The advisory notice Part 2 raises for a dependency it cannot
-  resolve is non-blocking, and Part 1's non-zero exit is a finding to report, not a stop.
+- The gates are the chain's own: the advisory `pre-implement-gate.sh` and step 1's
+  `"$DOFLOW" prereqs --require-plan`. Neither Part adds gates. Part 2 unresolved dependencies do
+  not block; Part 1 non-zero exits are reportable, not stops.
 - A `depends-on:` value whose starting directory does not exist on disk at all is excluded from
   service-identity derivation *entirely* (Part 2 step 1) — it never reaches Part 2 step 5's local
   generation path. It gets a frame only if the same task also carries an `external-contract:` field
@@ -438,4 +446,4 @@ rather than restated as prose.
 - A documented dependency's frame renders in the *consuming* task's own inferred language (Part 2
   step 4,
   reused unchanged, applied to the consumer's repo) — never a language inferred from the
-  dependency itself, which has no local repo to infer one from.
+  dependency itself, which has no local repo to infer one from.

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

@@ -0,0 +1,11 @@
+# Writing a `state.md` checkpoint (SKILL.md step 8)
+
+- 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.

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

@@ -3,39 +3,93 @@
 A task is done when the ledger says so, never from a `[x]` box or a `state.md` row. Every call takes
 `--slug "<slug>"` (step 1's `feature_slug`) and `--json`; `<task id>` is the plan id (`A.1`).
 
-**At resume**, read `"$DOFLOW" task-attempt --action status --slug "<slug>" --json` and branch on
-each task's `derived`: `done` skip; `ready` claim; `running` inspect `active` (owner, start) and
-release it if that worker is gone; `blocked` report it; `pending` an earlier phase is open. A task in
-`unclaimedChecked` is ticked without a COMPLETED attempt: claim and verify it, or untick it.
+**Read the JSON, not the exit code.** Exit 0: `claimed`, `applied`, `released`, `started`, `paused`,
+`cancelled`, `resumed`, `reopened`, `usage-recorded`, or a `status`/`inspect` read. Exit 1:
+`disposition` `refused`, `stale` or `ack-required`, with a `reason`. Exit 2: `{ ok: false, error }`.
+No parseable JSON means the runtime is too old: treat it as `unsupported`, do not dispatch or record
+a refusal, report the runtime version.
 
-**Before dispatch**, claim. `--mode` is `subagent`, `sequential` or `manual`:
+**Which flow.** A plan headed `**Task graph:** v1` follows every section below. Any other plan keeps
+the legacy flow: skip resume and claim without `--epoch`.
+
+**Resume first, every session (graph plan).** Before any other call:
+
+```bash
+"$DOFLOW" task-attempt --action resume --slug "<slug>" --json
+```
+
+It answers `ack-required` (exit 1) with `report` and `digest`. Read `report` (`control`, `epoch`,
+`activeAttempts` with owner, age, `execWorktree`; `changedSources` and `doneChanged`, files edited
+since a claim or COMPLETED; `unverifiable`, `staleContext`, `graph.changed`), act on it, then ack:
 
 ```bash
-"$DOFLOW" task-attempt --action claim --slug "<slug>" --task "<task id>" --owner "<agent>" --mode subagent --json
+"$DOFLOW" task-attempt --action resume --slug "<slug>" --ack <digest> --by "<who>" --json
 ```
 
-`claimed` returns the `token`; keep it. A refusal (exit 1) means do not dispatch: `active-attempt`,
-`already-done`, `unmet-phase` (an earlier-phase task lacks a COMPLETED attempt; `unmet` lists them)
-or `unknown-task`.
+`resumed` returns the new `epoch`; `report-changed` means state moved, so read the new report and
+ack its digest. Keep the epoch in session memory, never in `state.md` or any file.
 
-**After the agent returns**, verify in the parent run, record the result as evidence after the
-claim (`--kind test-result --observed-command "<cmd>" --observed-exit <n>`, schema in the guidance
-tree's `references/EVIDENCE_LEDGER.md`), then finish with the evidence id it returned:
+**Autonomous runs** with no run (`control: 'none'`) start one with an explicit budget instead of
+acking; `started` returns `epoch: 1`:
 
 ```bash
-"$DOFLOW" task-attempt --action finish --slug "<slug>" --task "<task id>" --token <token> --result COMPLETED --evidence-id "<id>" --json
+"$DOFLOW" task-attempt --action start --slug "<slug>" --by "<who>" --budget-attempts <n> [--budget-tokens <n>] --json
 ```
 
-COMPLETED needs an active, non-stale `test-result` that exited 0, is bound to the slug or the task
-id, and was observed no earlier than the claim. The refusal names the reason; fix it and finish again.
-`plan-changed` means the task's plan line was edited after the claim: release, reread, claim again.
+**Read state** with `--action status` (or `inspect` for graph, budgets and run totals) and branch on
+each task's `derived`: `done` skip; `ready` claim (`reason` `reopened` or `plan-changed-after-done`:
+the done attempt no longer counts, redo it); `running` inspect `active` (owner, start), release if
+that worker is gone; `failed` claim again while `budget.used < budget.limit`, else replan;
+`cancelled` clears only on resume; `blocked` report it; `pending` a dependency or earlier phase is
+open (`unmet`, `held`). A task in `unclaimedChecked` is ticked with no COMPLETED attempt: claim and
+verify it, or untick it.
+
+**Claim before dispatch**, from the main session; a worker never claims. `--owner` is the task's
+declared role; `--mode` (`subagent`, `sequential`, `manual`) must be the executor that will run. A
+graph plan passes `--epoch`, a worker run `--exec-worktree <path>` (never the main session's), and a
+run with a token limit `--reserve-tokens <n>` on every claim:
+
+```bash
+"$DOFLOW" task-attempt --action claim --slug "<slug>" --task "<task id>" --owner "<declared role>" --mode subagent --epoch <n> [--exec-worktree <path>] [--reserve-tokens <n>] --json
+```
+
+`claimed` returns the `token`; the worker finishes with it. A refusal means do not dispatch:
+`active-attempt`, `already-done`, `unmet-phase`, `unmet-dependency`, `dependency-held` (`unmet`,
+`held` list them), `unknown-task`, `resume-required` (resume first), `run-paused`, `run-cancelled`,
+`owner-mismatch` (`declared` names the role; `--owner-override "<reason>"` only when deliberate),
+`worker-session`, `budget-exhausted`, `cancelled` (resume clears it), `reservation-required`,
+`aggregate-unaccounted` (on each ended attempt left unreported, `--action report-usage --task <id>
+--token <n> --tokens <n> --tokens-basis …`) or `aggregate-exhausted`.
+
+**After the agent returns**, verify in the parent run, record evidence after the claim (`--kind
+test-result --observed-command "<cmd>" --observed-exit <n>`; item schema: SKILL.md step 6),
+and finish with the returned evidence id:
+
+```bash
+"$DOFLOW" task-attempt --action finish --slug "<slug>" --task "<task id>" --token <token> --result COMPLETED --evidence-id "<id>" [--tokens <n> --tokens-basis measured|estimated] --json
+```
+
+COMPLETED needs an active, non-stale `test-result` that exited 0, bound to the slug or task id,
+observed no earlier than the claim; on refusal fix the named reason and finish again.
+`plan-changed`: the plan line was edited after the claim, so release, reread, claim again.
+`--tokens` and `--tokens-basis` go together, on finish or release; report them under a token limit.
+
+**Otherwise** finish `BLOCKED`, `ABANDONED` or `INCONCLUSIVE` (no evidence), or `FAILED` with
+`--reason "<why>"`; or abandon a dispatch with `--action release --token <token> --reason "<why>"`.
+`stale` (exit 1): the token is no longer active, so a late result from an abandoned or cancelled
+(`attempt-cancelled`) dispatch changed nothing; read `status`. There is no lease: only an explicit
+release or cancel clears a crashed claimer.
+
+**Run controls** (main session only, each with `--by "<who>"`):
 
-**Otherwise** finish with `BLOCKED`, `ABANDONED` or `INCONCLUSIVE` (no evidence needed), or abandon a
-dispatch with `--action release --token <token> --reason "<why>"`. `stale` (exit 1) means the token
-is no longer the active one, so a late result from an abandoned dispatch changed nothing; read
-`status`. There is no lease: a crashed claimer is cleared only by an explicit release.
+- `--action pause --reason "<why>"`: claims refuse `run-paused`; active attempts may still finish.
+- `--action cancel --reason "<why>"`: marks every active attempt of the run cancelled (`--adopt-unowned` adds attempts with no run; `--task <id> --token <n>` limits it to one). It stops no process.
+- An acknowledged resume sets a paused or cancelled run running and clears its cancels.
+- `--action reopen --task <id> --token <done token> --reason "<why>"`: the done attempt stops counting, the task is `ready` with `reason: reopened`; `dependentsActive` lists running dependents.
+- Refusals: `run-exists` resume it; `identity-solo` or `worker-session` act from the main session; `control-unchanged` already so; `foreign-run` cancel from that run; `no-active-attempt`/`token-mismatch` (attempt cancel) or `not-done`/`token-mismatch` (reopen) read `status` for the token; `run-cancelled` resume first.
 
-**Before step 10**, read `status`; `complete: true` means every plan task has a COMPLETED attempt.
-`orchestrate` refuses to complete this stage while a ledger exists and is incomplete, and records
-`unverified` when the feature has no ledger. Exit 2 (malformed input, torn or newer-version store)
-leaves the file unchanged: report it, do not repair it.
+**Before step 10**, read `status`: `complete: true` means every task has a COMPLETED attempt (in a
+graph plan, with its plan line unchanged; else `plan-changed-after-done`). `orchestrate` refuses to
+complete this stage while a ledger exists and is incomplete, and records `unverified` with no
+ledger. Exit 2 (malformed input, torn or newer-version store) leaves the file unchanged: report it,
+do not repair it.

package/core/shared/skills/do-flow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: do-flow
-description: "Auto-chain the doflow spec-driven flow (brainstorm → design → plan → implement → test → review), pausing only at defined approval gates. Use when the user wants the lifecycle run end-to-end, says 'build this feature end-to-end', 'run the doflow chain' or 'take this from idea to implementation', or /do classified the request as a feature. A plain change request that names no /do-* skill goes to /do first, which decides whether it needs this flow. Skip it for single-file fixes, questions and reviews."
+description: "Run the doflow feature chain end to end, from idea to reviewed code. Use when the user wants the whole lifecycle run, says 'build this feature end-to-end', 'run the doflow chain' or 'take this from idea to implementation', or /do classified the request as a feature. A plain change request that names no /do-* skill goes to /do first, which decides whether it needs this flow. Skip it for one phase on its own (that phase's /do-* skill), single-file fixes, questions and reviews."
 argument-hint: "[feature description] [--from brainstorm|design|plan|implement|test|review]"
 effort: high
 ---
@@ -46,7 +46,7 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
    signal it rests on in one line. If two classes fit equally, do **not** take the longer one: show
    what each would run —
    `"$DOFLOW" workflow --task-class "<candidate>" --json`, quote its `stageIds` — and ask via
-   `AskUserQuestion`, one option per candidate.
+   the question tool, one option per candidate.
 
 3. **Validate the class through the runtime** — a proposal is not a selection until this returns:
 
@@ -98,7 +98,7 @@ not declare is not run here, however familiar it is from the `feature` chain.
 7. **Stop at the gates the resolved workflow declares** — read them from `workflow.gates`, each
    attached to a stage by `afterStage`. `trigger: always` stops every time; any other trigger stops
    only when that named condition actually holds. Ask with the gate's own `prompt` via
-   `AskUserQuestion`. For the `feature` workflow's three, which behave as they always have:
+   the question tool. For the `feature` workflow's three, which behave as they always have:
    - **`gate-0`** (after discovery, trigger `unresolved-clarifications`) — a safety net, not the
      normal path: `do-brainstorm` resolves ambiguities to zero via its own loop, so this fires only
      if a `[NEEDS CLARIFICATION]` marker survived an aborted session. Ask one question per marker
@@ -107,9 +107,8 @@ not declare is not run here, however familiar it is from the `feature` chain.
      tree's `references/WORKFLOW_HANDOFF.md` (stage `discovery`, channel `question`) so the answers
      are registered and cited; do-brainstorm already recorded discovery's handoff, so record none.
    - **`gate-a`** (after planning) — the conversational checkpoint on top of the already-existing
-     hard hook (`pre-implement-gate.sh`, which blocks source edits until `requirement.md`,
-     `design.md` and `plan.md` exist and remains the real enforcement regardless of what happens
-     here). Options: `Proceed` / `Let me review the artifacts first` / `Stop here`.
+     advisory hook (`pre-implement-gate.sh`; its scope is in `references/DOFLOW_CHAIN.md`), which
+     still reports a missing artifact. Options: `Proceed` / `Let me review the artifacts first` / `Stop here`.
    - **`gate-b`** (after review) — no enforcement hook exists for this today; `/do-git` is a
      separate, always-manually-invoked skill. Frame the question by the review's own approval
      status: on `CHANGES REQUESTED`, foreground addressing the findings rather than offering a bare
@@ -147,14 +146,14 @@ not declare is not run here, however familiar it is from the `feature` chain.
    "$DOFLOW" decision --action add --topic "<key>" --statement "<text>" --channel gate --stage "<stage the gate follows>" --rationale "<text>" --json
    ```
 
-8. **Never skip a gate on an ambiguous answer** — an unanswered or unclear response to any
-   `AskUserQuestion` means stop and ask again, per this repo's `RULE_04_QUESTIONS`. When the
+8. **Never skip a gate on an ambiguous answer** — an unanswered or unclear response to the
+   question tool means stop and ask again, per RULE_04 in `rules/RULES.md`. When the
    terminal stage completes, state `workflow.handoff` as the next step rather than continuing into
    it.
 
 ## Conditional research within a feature
 
-Before a feature stage relies on an external fact that local or user evidence cannot establish, or when the developer explicitly asks a research question, let that stage follow `../do-document/references/embedded-research.md`. The stage opens a same-task `research-request`, records a source-linked finding or gap, then resumes itself without adding a seventh workflow stage. On resume, read request status and context pack. A blocking unanswered question prevents stage completion; neither research nor a retrieved page approves any existing gate. Do not trigger external search merely because a feature began.
+Before a feature stage relies on an external fact that local or user evidence cannot establish, or when the developer explicitly asks a research question, let that stage follow `../do-document/references/embedded-research.md`. The stage opens a same-task `research-request`, records a source-linked finding or gap, then resumes itself without adding a seventh workflow stage. On resume, read request status and context pack. A blocking unanswered question prevents stage completion; neither research nor a retrieved page approves any existing gate. Feature discovery and design run the ideation pass; otherwise search only for a gap or an explicit request.
 
 ## Boundaries
 **Will:**
@@ -164,8 +163,8 @@ Before a feature stage relies on an external fact that local or user evidence ca
   ambiguous answer.
 - Record each gate answer it collects through `orchestrate --action decide-gate`, so the stage skill
   that owns that gate finds it already resolved instead of asking the user the same question twice.
-- Compose with the existing `pre-implement-gate.sh` hard gate rather than bypass or duplicate it.
-  That hook keys on branch and artifact state, not on class, so it can deny a `bug` or
+- Compose with the existing `pre-implement-gate.sh` advisory hook rather than bypass or duplicate it.
+  That hook keys on branch and artifact state, not on class, so it can advise against a `bug` or
   `trivial-edit` workflow's edits on a branch that already holds an incomplete feature dir —
   surface its message as written.
 

package/core/shared/skills/do-flow/references/task_classes.md

@@ -125,10 +125,10 @@ A `caller-not-a-stage` rejection is about **you**, not about the class. Answer i
 stage — propose one of those, or hand the work to the skill this class names for the stage you
 meant. Re-proposing the same class will be rejected the same way.
 
-## The hard hook does not know about classes
+## The advisory hook does not know about classes
 
-`pre-implement-gate.sh` keys on branch and artifact state: if the current branch already carries a
-feature directory missing `requirement.md`, `design.md` or `plan.md`, it denies source edits
+`pre-implement-gate.sh` keys on branch and artifact state (what it advises on: SKILL.md step 7): if the
+current branch already carries a feature directory the gate flags, it advises on source edits
 regardless of the class in play — so a `bug` or `trivial-edit` workflow started on that branch will
-be blocked at its implementation stage. Surface the hook's message as written. Do not route around
-it, and do not create placeholder artifacts to satisfy it.
+get that advisory at its implementation stage. Surface the hook's message as written. Do not route
+around it, and do not create placeholder artifacts to satisfy it.

package/core/shared/skills/do-git/SKILL.md

@@ -72,6 +72,10 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
 
 ## Safety Gates
 
+### Git Operations & Safety Invariants
+- Run `git status && git branch` first; use feature branches for ALL work; never force-push main/master.
+- Commit incrementally with descriptive messages; review `git diff` before staging; create a restore-point commit before high-risk changes.
+
 The following behaviors from today's skill are carried over unchanged:
 
 - **State checks** → `git status` before anything that could discard uncommitted work

package/core/shared/skills/do-implement/SKILL.md

@@ -46,16 +46,15 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      `--from-review`: treat that review's findings as the work list, most-severe first, in the
      order the review itself ranked them.
    - Invoked with a description: treat that as the work list directly.
-   - If the current branch has an active DoFlow feature (`"$DOFLOW" paths --json` resolves a
-     `feature_dir`) and its `plan.md` already has a task matching the request, say so and offer
-     `/do-execute-plan` instead — that machinery exists for exactly this case, and duplicating it
-     here would just be a second, worse orchestrator. Proceed directly only if the user confirms
-     the lighter path, or if no such plan or matching task exists.
+   - If an active DoFlow feature's `plan.md` has a task matching the request (`"$DOFLOW" paths --json`), offer `/do-execute-plan` instead. Proceed directly only if the user confirms or no matching plan task exists.
    - Never block on a missing `requirement.md` / `design.md` / `plan.md`. Those artifacts are the
      chain's business, not a precondition of this skill.
+   - MCP `context7`: when implementing against external libraries or upgrading dependencies, verify APIs per `MCP_Context7.md`.
 
 **Stop when** every work-list finding the contract names has an answer or a stated gap, **and** the last round produced no new work-list finding. A round that only restates what you already have is the last round. Report the remaining gaps rather than continuing.
 
+Once per stage, after `feature_slug` resolves, run `"$DOFLOW" attendance --task-id "<feature_slug>"`; `unattended` → `references/WORKFLOW_HANDOFF.md` § Unattended stage.
+
 2. **Resolve the task id, then evaluate readiness — skip only when standalone**:
    - `<task id>` is the same unit every recording stage keys on: the plan task id when one exists,
      otherwise the feature slug that step 1's `"$DOFLOW" paths --json` resolved, or the issue id you
@@ -76,9 +75,9 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      of `bug`, `refactor`, `dependency-change` or `trivial-edit` the recorded work already fits.
      `do-implement` never serves `feature`; that class's implementation stage is `/do-execute-plan`.
      ```bash
-     "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-implement --json
+     "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-implement --view brief --json
      ```
-     Branch on the returned `outcome`, not the exit code. `ACCEPTED` — the returned `workflow` names
+     Branch on `outcome`, not the exit code. `ACCEPTED` — the returned `workflow` names
      the validated class to evaluate readiness against. `REJECTED` — stop, print `message` verbatim
      (it names `validClasses`), ask the user to choose from that set, then re-validate; never
      substitute `feature` for the class that was rejected.
@@ -97,7 +96,7 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      computes, so a zero exit is not a green light.
      - **`STOP`** — refuse to modify source. Report which claim is conflicted and what evidence
        disagrees, then stop. Do not edit anyway.
-     - **`ASK_USER`** — a decision is owed by the user. Ask it through the `RULE_04_QUESTIONS.md`
+     - **`ASK_USER`** — a decision is owed by the user. Ask it through RULE_04 (`rules/RULES.md`)
        mechanism and wait; editing first would decide it silently on their behalf.
      - **`ENTER`** — proceed to the context-pack call below. In standalone mode this includes
        `NEEDS_EVIDENCE`: the unmet contract is reported, not enforced — relay the missing
@@ -121,8 +120,8 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      established.
    - The repository's `pre-implement-gate` hook checks file existence (`requirement.md` /
      `design.md` / `plan.md`) on every `Edit`/`Write` call regardless of which skill is editing. On
-     a harness with an edit hook it also denies the edit of a task held to a readiness record that
-     is not `READY`; this step writes that record, and is not a way around the hook.
+     a harness with an edit hook it also advises when a held task's readiness record is not
+     `READY`; the hook never denies. This step writes that record, and is not a way around it.
 
 3. **Understand before writing**:
    - Read the files the change touches and their immediate neighbors — naming conventions, error
@@ -141,7 +140,7 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      duplicates the host's own edit-approval mechanisms.
    - Stop after the change set only when one of two things is true: the user asked for the plan
      rather than the change ("show me what you'd change first"), or naming the change set surfaced
-     a genuine user-owned decision — then ask it per `RULE_04_QUESTIONS.md` and wait, because
+     a genuine user-owned decision — then ask it per RULE_04 (`rules/RULES.md`) and wait, because
      editing first would decide it silently.
 
 5. **Implement**:
@@ -149,8 +148,8 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      unimplemented mock functions, or `throw new Error('Not implemented')` placeholders in the
      produced change. Every changed component must be fully wired and functional.
    - Before the first source edit, a run for this task needs step 2's recorded readiness to be
-     `READY`: the hook denies the edit otherwise where there is one, and elsewhere step 7's handoff
-     is refused after the edits are made. A standalone `NEEDS_EVIDENCE` does not pass it.
+     `READY`: the edit hook only advises, and the runtime refuses step 7's handoff after the edits are
+     made. A standalone `NEEDS_EVIDENCE` does not pass it.
    - Keep it scoped to what was asked — no bonus refactors, no speculative abstractions (the same
      scope-discipline rule the chain's own artifacts would otherwise remind you of; here, hold
      yourself to it directly).
@@ -218,6 +217,6 @@ advance past the mutating stage only this skill may complete.
 multi-task checklist through specialist subagents — that is `/do-execute-plan`'s job once a real
 plan exists; silently override the repository's own `pre-implement-gate` hook. That hook triggers
 on any `Edit`/`Write` call, not on which skill made it — a branch mid-chain with a started feature
-but no `design.md` still gets blocked here exactly as it would anywhere else, and that is by
+but no `design.md` still gets the same advisory here as it would anywhere else, and that is by
 design, not a gap this skill works around. Resolve a workflow gate, or start a workflow run for a
 standalone implementation.

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

@@ -37,13 +37,15 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
 
 `feature_slug` `null` with a non-empty `candidate_slugs` is an unresolved choice, not "no active feature": ask one option per entry, re-resolve with `"$DOFLOW" paths --json --slug="<chosen>"`, and use that slug for the rest of this flow. `/do-flow` passing `--slug` already resolves it — no prompt then.
 
+Once per stage, after `feature_slug` resolves, run `"$DOFLOW" attendance --task-id "<feature_slug>"`; `unattended` → `references/WORKFLOW_HANDOFF.md` § Unattended stage.
+
 2. **Propose one task class; the runtime validates it** — name exactly one class id for the work
    being planned. `/do-flow` passes one when it invoked this skill; a user who named one settles it;
    otherwise derive it from `requirement.md` and `design.md`, not from their mere existence.
    ```bash
-   "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-plan --json
+   "$DOFLOW" classify --task-class "<proposed>" --calling-skill do-plan --view brief --json
    ```
-Branch on the returned `outcome` field, not the exit code.
+Branch on `outcome`, 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.
@@ -59,8 +61,8 @@ stages to implementation, and writing them a `plan.md` adds a gate their workflo
 not have.
 
 3. **Precondition (advisory)** — if `has_requirement` or `has_design` is false, warn and offer to
-   run `/do-brainstorm` / `/do-design` first. This gate is **advisory** (skippable), not the hard
-   hook gate.
+   run `/do-brainstorm` / `/do-design` first. This gate is **advisory** (skippable), like the edit
+   hook.
 4. **Read inputs** — compile the recorded prior context first, using the same task id rule step 10
    uses below (the plan task id for anything already scoped to a single `- [ ]` task, otherwise the
    feature slug):
@@ -70,17 +72,17 @@ not have.
    **Exit 1 means the pack came back empty; exit 3 means overflow: the pack is complete, act on
    `overflowAction.message` and report the gap.** By this point `do-design` should have batched
    evidence and claims (step 8), so an empty pack carries weight: either the batch never ran or the
-   task id mismatched. Treat it as advisory rather than blocking — plan's hard gate is artifact
-   existence only — but note it in this stage's report and `plan.md` §3 "Research & Decisions": a
-   decision written straight from prose without a compiled pack must not claim prior evidence. When
-   non-empty, read it alongside `requirement.md`, `design.md`, and the constitution.
+   task id mismatched. Empty packs are advisory; prerequisites check artifact existence only. Report
+   them in this stage's report and `plan.md` §3 "Research & Decisions"; prose without a compiled
+   pack cannot claim prior evidence. When non-empty, read it alongside `requirement.md`,
+   `design.md`, and the constitution.
    **Also read `specs.md` when step 1's `has_specs` is true** — use that flag, never a filesystem
    check of your own, and read the `specs` path the resolver returned. `/do-design` moves the
    interface and data-model contracts out of `design.md` into `specs.md` §1 as numbered `IC-###`
-   entries, so on a feature that has one, `design.md`'s §4/§5 are a pointer and the contracts this
+   entries, so on a feature that has one, `design.md`'s API / Interface Contracts and Data Model sections are a pointer and the contracts this
    plan must decompose toward live only in `specs.md`. Planning from `design.md` alone on such a
    feature plans against a pointer. When `has_specs` is false (an old-layout feature dir, which never
-   had a `specs.md`), the contracts are still in `design.md` §4/§5 and there is nothing extra to
+   had a `specs.md`), the contracts are still in `design.md` (API / Interface Contracts, Data Model) and there is nothing extra to
    read. Read
    `constitution_base`,
    then read `constitution_local` **only when `has_constitution_local` is true** — use that flag,
@@ -115,15 +117,17 @@ Filling §8's task dependency graph, read the guidance tree's `references/DIAGRA
    Read `references/ARTIFACT_VOICE.md` at the same point: it carries the prose rules the artifact's sentences follow, and the carve-outs where one of those rules meets a construct the checker parses.
    This stage fills the plan from requirement + design + constitution rather than by eliciting, so
    it writes no dialogue log — its sibling stages' `intention/`/`design/` question files have no
-   counterpart here. Should a future revision of this skill add an `AskUserQuestion` clarification
+   counterpart here. Should a future revision of this skill add a question-tool clarification
    loop, each of its rounds logs to `plan-<NN>-question.md` at the feature root exactly as
    `/do-brainstorm` and `/do-design` log theirs to their own subdirectories, numbered from step 1's
    `plan_next_round`.
-6. **Constitution Check (advisory gate)** — evaluate the plan against both tiers as reconciled in
-   step 4. On a violation, STOP and revise the approach before continuing, then record PASS/FAIL in
-   the plan. The verdict is **advisory**: it is recorded in `plan.md` §2 "Constitution Check" and nothing downstream
-   blocks on it — the chain's one hard gate covers artifact existence only. Stopping on a violation
-   is a discipline this skill observes, not something a hook enforces.
+6. **Constitution Check (exit gate)** — evaluate the plan against both tiers as reconciled in step
+   4. Record one row per principle in `plan.md` §2: its id, its tier (MUST unless it says `**Tier:**
+   SHOULD`) and PASS/FAIL; a base MUST that tier-2 makes SHOULD names that overlay version in its
+   row. On a violation, revise the approach first. A MUST marked FAIL or left
+   without a row refuses step 11's handoff; a SHOULD FAIL is a note. That refusal is the runtime's,
+   beside the advisory hook on artifact existence (`references/DOFLOW_CHAIN.md` scopes both).
+   There is no waiver: revise the plan, or a person amends the constitution with `/do-constitution`.
 7. **Decompose into Tasks (section 8)** — dependency-ordered, `[US#]`-traced to the requirement's
    user stories, owner+files named per task, with checkpoints and completion criteria.
    Read the guidance tree's `references/ORCHESTRATION.md` and
@@ -131,7 +135,7 @@ Filling §8's task dependency graph, read the guidance tree's `references/DIAGRA
    `--depth shallow|normal|deep` is the single granularity knob: it sets how finely a phase is
    split into tasks and how much detail each task carries. Default `normal`.
    **Why explicit task scoping and `[P]` markers**: Specifying concrete file paths (`files: [...]`)
-   and named specialist owners (`system-architect`, `core-implementer`, `quality-guardian`) per task
+   and agent-spec owners (review tasks name `reviewer`) per task
    enables `/do-execute-plan` to compute write-set isolation (`parallel-check`). Tasks with disjoint
    file sets run concurrently without merge conflicts, while overlapping tasks are safely serialized.
    **Mark `[P]` by default:** parallel execution is the framework default, so apply `[P]` to every
@@ -159,8 +163,13 @@ Filling §8's task dependency graph, read the guidance tree's `references/DIAGRA
    table: `primary` if it owns a task via `files:`, `dependency-only` if it's only ever reached via
    `depends-on:`. A single-repo result → `N/A: single-repo feature`. Derivation only — no branch is
    created here (`/do-execute-plan`'s job, lazily, per repo).
-9. **Validate** — run the advisory consistency check and surface any findings verbatim:
+9. **Self-review, then validate** — reread the plan against itself and fix it inline: every
+   requirement id and `[US#]` story is traced to a task or a §7 row, no TBD/TODO/"later" placeholder
+   is left, and no task is coarser than `--depth` sets (split one that is). `plan-check` scans the
+   first two and prints each one as a `findings` entry with its `path:line`. Fix every entry, then run
+   the advisory consistency check and surface its findings verbatim:
    ```bash
+   "$DOFLOW" plan-check "<plan path>" --json
    "$DOFLOW" validate "<plan path>"
    ```
    This also verifies each `### Task Summary` rollup row against the `- [ ]` lines under its
@@ -190,14 +199,19 @@ Item schema, provenance rules, and the refused-field list: the guidance tree's `
    ```bash
    "$DOFLOW" render-audit --slug="<task id>" --json
    ```
-   Leave any returned approval gate for `/do-flow` or `/do-execute-plan` to present.
+   Leave any returned approval gate for `/do-flow` or `/do-execute-plan` to present (unattended: the loop
+   decides it by policy).
 
 12. **Stop** — report the plan path, Constitution Check result, the task count (`[P]`/sequential),
    and the derived branch name/repo count when the Repo Branch Plan is populated.
 
+### Planning Efficiency Invariants
+- Identify concurrent versus sequential operations across disjoint write sets.
+- Map explicit dependencies between tasks; batch tool calls; maximize parallel execution gains.
+
 ## 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.
+For an external fact gap or request, follow the Gap or request protocol in `../do-document/references/embedded-research.md` before stage completion.
 
 ## Boundaries
 **Will:** propose a task class and have the runtime validate it, read requirement + design + specs

package/core/shared/skills/do-test/SKILL.md

@@ -43,14 +43,17 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
 ```
 
    When `status` is `answered` and `agrees` is `false`, say so in one line and keep or change the level
-   by your own judgement. Record the level used with `"$DOFLOW" advise --action outcome --pick-id
-   "<pickId>" --actual "<level>"`. Skip both calls when `status` is not `answered`.
+   by your own judgement. Record the level used, and skip both calls when `status` is not `answered`:
+
+```bash
+"$DOFLOW" advise --action outcome --pick-id "<pickId>" --actual "<level>"
+```
 
 ```bash
 "$DOFLOW" verify --task-id "<task id>" --risk "<LOW|MEDIUM|HIGH|CRITICAL>" --action contract --json
 ```
 
-   Report, before a single tier runs:
+   Report, before any tier runs:
    - the compiled `tiers[]` in the order returned — that list, and nothing else, is what will run;
    - the `riskLevel` it compiled at and the `maxRecoveryIterations` it carries;
    - `detection.absent` — the command roles the runtime could not find in this repo's manifests
@@ -106,7 +109,7 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
 
 ## 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.
+For an external fact gap or request, follow the Gap or request protocol in `../do-document/references/embedded-research.md` before stage completion.
 
 ## Boundaries
 **Will:** Run the compiled tiers, report every status (including unreached), coverage, and failure traces; hand off the current stage in a chain.

package/core/shared/templates/doflow/constitution-template.md

@@ -13,10 +13,15 @@
 
 ## Principles
 
-### [PRINCIPLE_1_NAME]
+<!-- One `### <ID> — <name>` heading per principle. A principle is MUST unless its body has
+     `**Tier:** SHOULD`. An ID equal to a base one (P1–P6) replaces that base principle. -->
+
+### R1 — [PRINCIPLE_1_NAME]
+**Tier:** MUST
 [PRINCIPLE_1_STATEMENT — testable and non-negotiable.]
 
-### [PRINCIPLE_2_NAME]
+### R2 — [PRINCIPLE_2_NAME]
+**Tier:** SHOULD
 [PRINCIPLE_2_STATEMENT.]
 
 ## Constraints
@@ -25,4 +30,5 @@
 ## Governance
 - Amendments: bump semver, fill the Sync Impact Report, re-run dependent gates.
 - `/do-plan`'s Constitution Check MUST evaluate against both tiers together (these rules taking
-  precedence). Its verdict is advisory — recorded, not blocking.
+  precedence). A MUST principle marked FAIL or left without a row refuses the planning stage's exit;
+  a SHOULD FAIL is advisory.

package/core/shared/templates/doflow/data-model-template.md

@@ -3,7 +3,7 @@
 **Feature:** [NNN-slug] · **Design:** ./design.md · **Maturity:** Draft · **Created:** [DATE]
 
 > Entity/data model and data-flow diagrams a design decided, split out of design.md's own narrative
-> (§5/§6) and specs.md's interface-contract detail (§1). Reads ./design.md; distinct from ./specs.md
+> (Data Model and Sequence / Data Flow) and specs.md's interface-contract detail (§1). Reads ./design.md; distinct from ./specs.md
 > the way a persisted shape and the flows that move through it are distinct from the contracts that
 > expose them.
 >