@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

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`.
+     hard hook (`pre-implement-gate.sh`; its scope is in `references/DOFLOW_CHAIN.md`), which remains
+     the real enforcement regardless of what happens here. 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:**

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

@@ -127,8 +127,8 @@ meant. Re-proposing the same class will be rejected the same way.
 
 ## The hard 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 denies: SKILL.md step 7): if the
+current branch already carries a feature directory the gate rejects, it denies 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.

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,13 +46,10 @@ 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.
 
@@ -97,7 +94,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
@@ -111,8 +108,9 @@ Run every command below from the project root — the walk-up starts at `$PWD`.
      "$DOFLOW" context-pack --task-id "<task id>" --json
      ```
      This verb exits 1 on an empty pack by design — nothing recorded is not the same as nothing
-     needed — and that non-zero exit is never read as success. Because this call only runs after the
-     evidence check above already found something recorded for this task id, an exit 1 here means
+     needed — and that non-zero exit is never read as success; exit 3 means overflow: the pack is
+     complete, act on `overflowAction.message` and report the gap. Because this call only runs after
+     the evidence check above already found something recorded for this task id, an exit 1 here means
      the compiled pack still held nothing usable (evidence with no linked claims, most likely):
      treat that as a mismatch worth naming in step 6's report, not as license to proceed as though
      there were no prior context to look for. On a normal, non-empty pack, carry its evidence and
@@ -140,7 +138,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**:

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

@@ -67,21 +67,20 @@ not have.
    ```bash
    "$DOFLOW" context-pack --task-id "<task id>" --json
    ```
-   **Exit 1 means the pack came back empty.** By this point `do-design` should already have batched
-   its own stage-boundary evidence and claims (its step 8), so an empty pack here carries more
-   weight than it does at design time: either that batch never ran, or this task id doesn't match
-   the one design used. Treat it as advisory rather than blocking — plan's hard gate is artifact
-   existence only — but say so plainly in this stage's report, and in `plan.md`'s own §3 "Research &
-   Decisions": a decision written straight from `requirement.md`/`design.md` prose, with no compiled
-   pack behind it, must not be recorded as if it traced to prior evidence it doesn't have. When the
-   pack is non-empty, read it alongside `requirement.md`, `design.md`, and the constitution.
+   **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. 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,
@@ -116,15 +115,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 hard hook that covers 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
@@ -132,7 +133,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
@@ -160,8 +161,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
@@ -196,9 +202,13 @@ Item schema, provenance rules, and the refused-field list: the guidance tree's `
 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.
 >