@khoavu882/doflow 2.0.0-beta.5 → 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
@@ -141,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

@@ -70,17 +70,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 +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
@@ -131,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
@@ -159,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
@@ -195,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.
 >

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

@@ -2,12 +2,15 @@
 
 **Feature:** [NNN-slug] · **Requirement:** [REQUIREMENT_PATH] · **Maturity:** Draft · **Created:** [DATE]
 
-> System shape — architecture, APIs, data/interface contracts. Reads [REQUIREMENT_PATH].
+> System shape — architecture, journeys, APIs, data/interface contracts. Reads [REQUIREMENT_PATH].
 > Distinct from plan.md's HOW-to-implement; this is HOW-it's-shaped.
 >
+> Journey-first: business and engineering read the front half (Architecture Approach through
+> Journeys) on one page, in plain nouns. The component-level sections follow it.
+>
 > Structure follows `references/ARTIFACT_FORMAT.md`: indexed sections carry a table above full
 > `**Detail**`, the document-level `Maturity` is `Draft`, `In review` or `Approved`, the item-level
-> `Status` is only `Live` or `Superseded → <ref>`, and superseded prose moves to §9.
+> `Status` is only `Live` or `Superseded → <ref>`, and superseded prose moves to the History section.
 
 ## 1. Architecture Approach
 
@@ -27,19 +30,26 @@
 | [what is being settled] | [the shape this design gives it] | [person or role accountable] | no |
 | [what is being settled] | [the shape this design gives it] | [person or role accountable] | yes: [what must happen first] |
 
-[Component boundaries, where this fits in the existing system, 2–4 sentences.]
+<!-- Acts as the summary. In 2–4 sentences or bullets, in plain nouns with no component IDs or code
+     names: who gains what and why, the goal of this phase, and where it plugs into the existing
+     system. Leave out implementation detail: that belongs in Components & Boundaries. -->
+
+[Who this is for and why, the goal of this phase, and where it fits in the existing system.]
 
 ## 2. System Overview (C4)
 
-<!-- The visual complement to §1 — lets a reader unfamiliar with this feature see the shape before
-     reading prose. C4 is kept as the conceptual zoom model (Context → Container → Component) and
-     rendered with Mermaid `flowchart` + `subgraph`. Each level heading is written
-     "C4 Level N: ...", so no level label collides with a §3 component ID such as C3.
+<!-- The visual complement to Architecture Approach — lets a reader unfamiliar with this feature see
+     the shape before reading prose. C4 is kept as the conceptual zoom model (Context → Container →
+     Component) and rendered with Mermaid `flowchart` + `subgraph`. Each level heading is written
+     "C4 Level N: ...", so no level label collides with a component ID such as C3.
 
      Do NOT use the C4Context / C4Container diagram types. They are experimental in Mermaid: no
      direction control, relationship labels collide with arrowheads, and rendering varies across
      viewers. `flowchart` is the most widely supported type and puts labels legibly on the arrow.
 
+     EVERY edge carries a label saying what flows over it (a request, a record, money, a file),
+     never a bare arrow.
+
      Skip a level with "N/A: [why]". For a trivial single-file change with no new external
      interaction, write "N/A: [why]" for the whole section. -->
 
@@ -100,8 +110,8 @@ flowchart LR
 ### C4 Level 3: Component
 
 <!-- Required when this feature touches 3+ components within a single container; otherwise write
-     "N/A: covered by §3 Components & Boundaries". On a small change this diagram restates the §3
-     table verbatim, and a diagram that adds nothing trains authors to tick boxes. -->
+     "N/A: covered by Components & Boundaries". On a small change this diagram restates the
+     Components & Boundaries table verbatim, and a diagram that adds nothing trains authors to tick boxes. -->
 
 [Internals of the container this feature changes — handlers, services, ports, adapters.]
 
@@ -117,7 +127,85 @@ flowchart TB
     C_B -->|"[persists]"| STORE
 ```
 
-## 3. Components & Boundaries
+[One closing sentence: what this feature decides versus where the data or money moves.]
+
+## 3. Concepts
+
+<!-- Write the handful of nouns a reader must hold to follow the Journeys, in plain words: no
+     component IDs, no code names. One `flowchart` of how they relate (every edge labelled with the
+     relationship), then a glossary table. Leave out anything a journey does not use. Write
+     "N/A: [why]" for a design with no domain vocabulary worth defining. -->
+
+```mermaid
+flowchart LR
+    TERM_A["[Concept A]"]
+    TERM_B["[Concept B]"]
+    TERM_C["[Concept C]"]
+
+    TERM_A -->|"[relationship, e.g. has many]"| TERM_B
+    TERM_B -->|"[relationship, e.g. is checked against]"| TERM_C
+```
+
+| Term | Meaning |
+|---|---|
+| [Concept A] | [one plain sentence] |
+| [Concept B] | [one plain sentence] |
+
+## 4. Journeys
+
+<!-- One `### Journey N — <name>` per user or system journey, in the order a reader meets them. Each
+     carries one picture (a `flowchart` or a `sequenceDiagram`), a `stateDiagram-v2` for EVERY
+     stateful thing the journey creates, and a small rules table. Write in plain nouns: no component
+     IDs, no code names. Leave out internal calls that no actor sees. Write "N/A: [why]" for the
+     whole section when the design has no user or system journey (a pure library or refactor). -->
+
+### Journey 1 — [journey name]
+
+[One sentence: who starts this journey and what it ends with.]
+
+```mermaid
+flowchart LR
+    START["[trigger]"] -->|"[what flows]"| CHECK{"[decision]"}
+    CHECK -->|"[pass: what flows]"| DONE["[outcome]"]
+    CHECK -->|"[fail: what flows]"| STOP["[alternate outcome]"]
+```
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created
+    Created --> Active: [guarded transition]
+    Active --> Ended: [guarded transition]
+    Ended --> [*]
+```
+
+| Rule | Why it holds |
+|---|---|
+| [a rule this journey enforces] | [the reason, or what breaks without it] |
+
+### Worked example
+
+<!-- Real numbers that make the rules checkable: one case that passes and one that does not, then the
+     result. Close with one caveat sentence saying what is not guaranteed. Leave out hypothetical
+     values you cannot compute. -->
+
+| Candidate | Eligible? | Why | Result |
+|---|---|---|---|
+| [case that passes, with a real figure] | yes | [which rule it meets] | [computed outcome] |
+| [case that fails, with a real figure] | no | [which rule it breaks] | [computed outcome] |
+
+[Caveat: what is shown but not guaranteed, and where it is re-checked.]
+
+### Eligibility / decision inputs
+
+<!-- A TABLE, never a mindmap: DIAGRAM_GUIDE.md excludes `mindmap`. One row per group of inputs the
+     decision reads; say what the first version reads and what comes later. -->
+
+| Input group | What is read | Read in this version? |
+|---|---|---|
+| [group, e.g. the user] | [the facts checked] | yes |
+| [group, e.g. the limits] | [the facts checked] | later: [why] |
+
+## 5. Components & Boundaries
 
 | ID | Component | Kind | Serves | Status |
 |---|---|---|---|---|
@@ -134,7 +222,7 @@ flowchart TB
   - **Does not own:** [what a reader could expect it to hold but another component does].
   - **Contracts:** [the FR-### and IC-### identifiers it serves].
 
-## 4. API / Interface Contracts
+## 6. API / Interface Contracts
 
 <!-- Endpoints, CLI verb signatures, and repository/service interfaces that anchor implementation
      live in ./specs.md §1 Interface Contracts, not here — each as one ID-bearing IC-### entry so
@@ -142,7 +230,7 @@ flowchart TB
      this feature genuinely introduces no interface contracts; otherwise leave a one-line pointer,
      e.g. "See ./specs.md §1." -->
 
-## 5. Data Model
+## 7. Data Model
 
 The data-model shape is governed by `./data-model.md` §1.
 
@@ -150,7 +238,7 @@ The data-model shape is governed by `./data-model.md` §1.
      ./data-model.md §1 Data Model, not here. Write `N/A: [why]` if this feature introduces no data
      model or UX changes; otherwise leave a one-line pointer, e.g. "See ./data-model.md §1." -->
 
-## 6. Sequence / Data Flow
+## 8. Sequence / Data Flow
 
 The data-flow shape is governed by `./data-model.md` §2.
 
@@ -159,7 +247,7 @@ The data-flow shape is governed by `./data-model.md` §2.
      no non-trivial interaction sequence; otherwise leave a one-line pointer, e.g.
      "See ./data-model.md §2." -->
 
-## 7. Design Risks & Alternatives Considered
+## 9. Design Risks & Alternatives Considered
 
 | ID | Risk / Alternative | Disposition | Status |
 |---|---|---|---|
@@ -169,7 +257,16 @@ The data-flow shape is governed by `./data-model.md` §2.
 
 - **R1** → [why this shape was chosen, or why the risk is accepted and what it costs if it lands].
 
-## 8. Assumptions
+## 10. Open Points for Review
+
+<!-- The questions this design could not answer, ending the design instead of a bare risk list. One
+     bold-led question per bullet, followed by the reasoning already known (a figure, a trade-off, the
+     option you lean to). Lead each with the question in bold; do not number them with an ID. Write
+     "None — no open points." when every question was settled. -->
+
+- **[A question a reviewer must answer?]** [The reasoning already known and the option leaned to.]
+
+## 11. Assumptions
 
 <!-- With a decision register, a row from a "Decide for me" pick cites its DEC-### in Basis: see ARTIFACT_FORMAT.md §12. -->
 
@@ -185,7 +282,7 @@ The data-flow shape is governed by `./data-model.md` §2.
      and detail if every design-level ambiguity was resolved by a direct answer rather than the
      defer escape hatch during /do-design's clarification loop. -->
 
-## 9. History
+## 12. History
 
 <!-- Superseded design decisions move here; the index row above stays as a tombstone with
      `Superseded → <ref>`. -->