@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/core/shared/guidance/references/ARTIFACT_FORMAT.md

@@ -51,8 +51,8 @@ Rules:
     which is reconciled only after the whole file is read.
 
 Which sections take an index: `requirement.md` §3 Functional Requirements, §4 Non-Functional
-Requirements and §8 Assumptions; `design.md` §3 Components & Boundaries, §7 Risks and §8
-Assumptions; `plan.md` §4 Components & Changes and §6 Risks; `specs.md` §1 Interface Contracts.
+Requirements and §8 Assumptions; `design.md` Components & Boundaries, Design Risks & Alternatives
+Considered and Assumptions; `plan.md` §4 Components & Changes and §6 Risks; `specs.md` §1 Interface Contracts.
 Prose sections do not.
 
 ## 2. Status and Maturity — two closed vocabularies
@@ -92,8 +92,8 @@ vocabulary in the wrong place, and `Draft` was never a legal member of it.
 ## 3. History — the live body stays current
 
 When an item is superseded, its obsolete prose leaves the `**Detail**` block and moves to the
-artifact's own final History section — §9 for `requirement.md`, `design.md` and `plan.md`; §2 for
-`specs.md`. The index row stays as a tombstone. Reading the body top to bottom therefore yields
+artifact's own final History section — the section titled History, last in `requirement.md`,
+`design.md` and `plan.md`; §2 for `specs.md`. The index row stays as a tombstone. Reading the body top to bottom therefore yields
 current truth with no historical detours, while the supersession is still visible at a glance.
 
 Two rules bind that mechanism, and nothing else in this document states them:
@@ -120,7 +120,7 @@ below so the reasoning behind a reversal is not compressed into a cell:
 
 | Date | ID | Change | Replaced by |
 |---|---|---|---|
-| 2026-07-29 | FR-001 | Field renamed during design | design §4.1 |
+| 2026-07-29 | FR-001 | Field renamed during design | design Interface Contracts |
 
 **Detail**
 
@@ -146,7 +146,9 @@ A feature with a decision register compacts History mechanically; see §12.
 | Artifact | Section | Slot |
 |---|---|---|
 | `requirement.md` | §1 | Scope boundary `flowchart` |
-| `design.md` | §2 | Three C4 levels, each a `flowchart` with `subgraph` boundaries |
+| `design.md` | System Overview (C4) | Three C4 levels, each a `flowchart` with `subgraph` boundaries |
+| `design.md` | Concepts | Relationship `flowchart` of the domain nouns, edges labelled |
+| `design.md` | Journeys | Per journey: one `flowchart` or `sequenceDiagram`, plus a `stateDiagram-v2` for each stateful thing it creates |
 | `plan.md` | §8 | Phase and task dependency `flowchart` |
 | `data-model.md` | §1 | Conceptual domain map `flowchart`, then one `erDiagram` per bounded subdomain |
 | `data-model.md` | §2 | Interaction `sequenceDiagram` |
@@ -158,7 +160,7 @@ in-scope item produces, so the shape of the change is visible before the prose.
 `subgraph IN["In scope"]` / `subgraph OUT["Out of scope"]`. Write `N/A: [why]` for a change too
 small to have a meaningful boundary.
 
-### C4 levels — `design.md` §2
+### C4 levels — `design.md` System Overview (C4)
 
 C4 is kept as the **conceptual zoom model** — system context, container, component — and rendered
 with Mermaid `flowchart` plus `subgraph` blocks marking C4 boundaries. Each level takes its own
@@ -171,13 +173,13 @@ heading, written `### C4 Level 1: System Context`, `### C4 Level 2: Container` a
 | C4 Level 2 | Independently deployable units and how they talk | yes |
 | C4 Level 3 | Internals of one container | only when the feature touches 3+ components in a single container |
 
-**No level label may match `^C[0-9]+$`.** That pattern is what a `design.md` §3 component ID looks
+**No level label may match `^C[0-9]+$`.** That pattern is what a `design.md` component ID looks
 like, so a bare `C3` in the same document is ambiguous between the third zoom level and the third
 component. Spelling the level `C4 Level 3` keeps the C4 vocabulary explicit for a reviewer who
 cites levels by number while leaving the component IDs unambiguous.
 
 Skip a level with `N/A: [why]`; for C4 Level 3 that is normally
-`N/A: covered by §3 Components & Boundaries`. `DIAGRAM_GUIDE.md` §1 carries the reasoning that
+`N/A: covered by Components & Boundaries`. `DIAGRAM_GUIDE.md` §1 carries the reasoning that
 excludes the `C4Context` / `C4Container` diagram types in favour of `flowchart`.
 
 ### Task dependency graph — `plan.md` §8
@@ -235,8 +237,8 @@ Acceptance criteria are formatted as testable Gherkin BDD scenario blocks mapped
 
 ## 7. Technical Scaffolding in specs.md and data-model.md
 
-`specs.md` and `data-model.md` provide dedicated homes for technical implementation anchors — `design.md` §4/§5 hold
-only a one-line pointer to them:
+`specs.md` and `data-model.md` provide dedicated homes for technical implementation anchors — `design.md`'s API / Interface Contracts and Data Model
+sections hold only a one-line pointer to them:
 - **Interface Contracts (`specs.md` §1):** HTTP endpoints (methods, routes, request/response shapes, status codes), CLI verb signatures, and repository/service interfaces (`interface` → `concrete` → `mock`).
 - **Data Model (`data-model.md` §1):** Relational data model diagrams, database table schema catalogs (table purpose, keys, relations, indexes, ORM/DDL file references), and UX design tokens (color palettes, component states, layout cues).
 
@@ -262,7 +264,8 @@ file nobody looked at.
 
 Checked: index/detail parity both directions · `Status` vocabulary · ID-shaped supersede targets
 resolve · superseded items have a History entry · plan rollup counts match the checklist ·
-decision references are not stale · no unknown decision references (every cited `DEC-###` is in the register).
+decision references are not stale · no unknown decision references (every cited `DEC-###` is in the register) ·
+plan task lines parse as the task-attempt ledger reads them (task-graph).
 
 Parity reads both detail-entry forms of §1: the `- **<ID>` bullet, and the `#### <ID>: <text>`
 heading whose ID also appears in that section's index table. A heading that merely looks ID-shaped
@@ -289,7 +292,7 @@ disagree, deciding which one is wrong is authoring judgement, not a mechanical f
 Three sections exist so a reviewer can reach a judgement from the top of a document rather than by
 reading it whole:
 
-- **`design.md` §1 — the decision-and-blocker summary.** A table with the columns `Decision`,
+- **`design.md` Architecture Approach — the decision-and-blocker summary.** A table with the columns `Decision`,
   `Shape chosen`, `Owner`, `Blocks approval?`, positioned above the architectural prose. One row per
   decision the design makes. A reviewer who reads only this table knows what is being settled, who
   settled it, and what stands between the design and approval.
@@ -318,7 +321,7 @@ flowchart. There is one spelling of it in this document and no second one.
 
 ### The component detail shape
 
-A `design.md` §3 component detail entry names the component after its ID, then answers four labels
+A `design.md` Components & Boundaries detail entry names the component after its ID, then answers four labels
 in this order: `**Responsibility:**`, `**Owns:**`, `**Does not own:**`, `**Contracts:**`. None may
 be dropped or reordered. What a component deliberately does *not* own is the half a reviewer cannot
 reconstruct from the code, which is why it has a label of its own rather than a sentence.
@@ -328,6 +331,17 @@ bold-labelled lists on exactly that ground. The entry still begins `- **<ID>:**`
 locates it; the labels sit in nested bullets beneath. No other artifact's detail entries take this
 shape.
 
+### The `design.md` section order
+
+In order: `Architecture Approach`, `System Overview (C4)`, `Concepts`, `Journeys`,
+`Components & Boundaries`, `API / Interface Contracts`, `Data Model`, `Sequence / Data Flow`,
+`Design Risks & Alternatives Considered`, `Open Points for Review`, `Assumptions`, `History`. Readers
+locate a section by title, never number, so an older nine-section design still parses. The front half
+(through `Journeys`) uses plain nouns, no component IDs or code names. Each `### Journey N — <name>`
+has one picture, a `stateDiagram-v2` per stateful thing it creates, and a rules table; `Journeys` also
+holds a `### Worked example` and an `### Eligibility / decision inputs` table. A guard compares this
+list with the template and the §4 slot registry.
+
 ### Nothing checks this per artifact
 
 These are conventions the writing skill follows, not rules the checker runs. `validate-artifacts.sh`
@@ -363,8 +377,8 @@ applies.
 
 - A line that applies a registered decision cites it as a bare `DEC-###`.
 - `plan.md` §3 lists the `DEC-###` decisions the plan rests on and authors no `D#`.
-- A design §1 row ends its `Shape chosen` cell with its `DEC-###`. A §8 row that came from a
-  "Decide for me" pick cites its `DEC-###` in `Basis`.
+- A design Architecture Approach row ends its `Shape chosen` cell with its `DEC-###`. An
+  Assumptions row that came from a "Decide for me" pick cites its `DEC-###` in `Basis`.
 - A line citing a superseded decision is a `stale` finding unless it also names a later decision in
   that chain, and a cited `DEC-###` absent from the register is an `unknown` finding (§9).
 - Compaction moves History content to `decisions/history/<artifact>.md` and leaves one pointer line,

package/core/shared/guidance/references/ARTIFACT_VOICE.md

@@ -2,7 +2,8 @@
 
 How a chain artifact reads, sentence by sentence. Structure lives in `ARTIFACT_FORMAT.md`; this file
 covers only the writing. Read on demand by `do-brainstorm`, `do-design` and `do-plan` when
-filling a template, and never loaded into a session by default.
+filling a template, and by `do-document` and `research-writer` when drafting prose. Never loaded
+into a session by default.
 
 ## 1. The rules
 
@@ -90,7 +91,7 @@ prose rule applies in full to free prose.
 | Prose rule | Conflicting construct | Which governs |
 |---|---|---|
 | Bold for a functional reason only | The `- **<ID>:**` detail-entry shape the checker locates entries by | The detail shape governs. The bold is a structural label, not emphasis. |
-| Bold for a functional reason only | The `Responsibility` / `Owns` / `Does not own` / `Contracts` labels of a `design.md` §3 component entry | The labelled shape governs. `ARTIFACT_FORMAT.md` §10 declares these four labels and their order. |
+| Bold for a functional reason only | The `Responsibility` / `Owns` / `Does not own` / `Contracts` labels of a `design.md` Components & Boundaries entry | The labelled shape governs. `ARTIFACT_FORMAT.md` §10 declares these four labels and their order. |
 | No em or en dashes | The literal `None — initial version.` that `ARTIFACT_FORMAT.md` §3 requires a new artifact to write | The literal governs. Write the em dash. |
 | Sentence case headings | Every `##` section heading in the four chain-artifact templates, which `ARTIFACT_FORMAT.md` names by their exact words and `validate-artifacts.sh` locates History by | The template headings govern. Do not re-case a heading in a chain artifact. |
 | Sentence case headings | The `#### <ID>: <text>` heading form of a detail entry, §1's second grammar | The heading governs. Its ID is matched literally against an index row, so its case is not free. |

package/core/shared/guidance/references/CONSTITUTION_BASE.md

@@ -1,47 +1,49 @@
 # Base Constitution (tier-1)
 
-**Version:** 1.0.0 · **Scope:** all repos using the doflow chain
+**Version:** 1.1.0 · **Scope:** all repos using the doflow chain
 
 > The universal, non-negotiable rules every feature inherits. This is the **tier-1 base**;
 > each repo's `agent-docs/constitution.md` (tier-2) overlays it and **takes precedence on
 > conflict**. `do-paths.sh` locates both tiers and reports whether tier-2 exists; the overlay
 > itself is performed by the chain skill reading both files, and `/do-plan`'s Constitution Check
-> records an **advisory** verdict. See `DOFLOW_CHAIN.md` → "Two-tier constitution" for what is
-> computed and what is convention.
+> records one PASS/FAIL row per principle, which the runtime checks at the planning stage's exit.
+> See `DOFLOW_CHAIN.md` → "Two-tier constitution" for what is computed and what is convention.
 
 ## Principles
 
-Each states the norm; the arrow points at the always-loaded rule that carries the detail.
+Each states the norm; the arrow points at the always-loaded rule that carries the detail. A
+principle is MUST unless its body has a `**Tier:** SHOULD` line; every base principle is MUST.
 
 ### P1 — Safety over speed
 Security, data integrity, and production safety are never traded for velocity; a destructive or
-irreversible action needs explicit confirmation. → `rules/RULE_01_SAFETY.md`.
+irreversible action needs explicit confirmation. → `rules/RULES.md` RULE_01.
 
 ### P2 — Evidence over assumptions
 A claim is backed by a test, a run, or a document, never guessed; a failure is root-caused before
-it is fixed. → `rules/RULE_01_SAFETY.md`, `PRINCIPLES.md`.
+it is fixed. → `rules/RULES.md` RULE_01, `PRINCIPLES.md`.
 
 ### P3 — Finish what you start
 No TODO stubs, mocks, or "not implemented" throws in delivered code: done means validated, not
-compiling. → `rules/RULE_02_WORKFLOW.md`.
+compiling. → `rules/RULES.md` RULE_02.
 
 ### P4 — Scope discipline (YAGNI)
 Build only what the spec asks — no bonus features, no speculative abstraction.
-→ `rules/RULE_02_WORKFLOW.md`.
+→ `rules/RULES.md` RULE_02.
 
-### P5 — Parallel by default
-Independent work runs concurrently; sequential only for hard dependencies.
-→ `rules/RULE_02_WORKFLOW.md`.
+### P5 — Parallel when write sets are disjoint
+Shared write sets/dependencies run sequentially.
+→ `rules/RULES.md` RULE_02.
 
 ### P6 — Professional honesty
 No invented metrics, no marketing language; state "untested / needs validation" plainly and push
-back on a bad approach with evidence. → `rules/RULE_03_QUALITY.md`.
+back on a bad approach with evidence. → `rules/RULES.md` RULE_03.
 
 ## Governance
 - This base is versioned (semver). Tier-2 repo constitutions may **add** or **override** principles,
   but may not weaken P1 (Safety). *This constraint is stated to the reading agent; nothing
   validates it, so a tier-2 file that weakened P1 would not be rejected by any check.*
 - `/do-plan` MUST evaluate its Constitution Check against both tiers together (tier-2 taking
-  precedence) and record PASS/FAIL. The verdict is **advisory** — it is recorded in `plan.md`
-  §2 "Constitution Check" and does not block work; the chain's one hard gate covers artifact
-  existence only.
+  precedence) and record one PASS/FAIL row per principle in `plan.md` §2 "Constitution Check". A
+  MUST row marked FAIL, or a MUST principle with no row, refuses the planning stage's exit; a
+  SHOULD FAIL is advisory. No model waiver exists: revise the plan, or a person amends the
+  constitution through `/do-constitution`. Gate scope: `DOFLOW_CHAIN.md`.

package/core/shared/guidance/references/DIAGRAM_GUIDE.md

@@ -136,7 +136,7 @@ it carries.
 
 Some features author diagrams in PlantUML under `design/c4/` and commit the render. These apply on top of everything above.
 
-**C4 divides by level**: `context.puml`, `container.puml`, `component.puml`, one file each; a level not drawn has no file. The Mermaid in `design.md` §2 is generated from these, so editing it by hand
+**C4 divides by level**: `context.puml`, `container.puml`, `component.puml`, one file each; a level not drawn has no file. The Mermaid in `design.md` System Overview (C4) is generated from these, so editing it by hand
 is a change the next render discards.
 
 **The generated view drops seven things** — element type, technology, description, sprite, tag, link

package/core/shared/guidance/references/DOFLOW_CHAIN.md

@@ -1,10 +1,11 @@
 # DoFlow Chain — Spec-Driven Delivery
 
 A spec-kit-style, phase-gated delivery loop (`do-brainstorm → do-design → do-plan →
-do-execute-plan → do-test → do-code-review`) on top of the rest of the `/do-*` skills and the five
-specialist agents (`core-implementer`, `quality-guardian`, `research-writer`, `spec-analyst`,
-`system-architect`). Discipline borrowed from spec-kit; enforcement done with the harness's real
-hooks rather than a prompt-read registry. The implement-gate hook is registered in
+do-execute-plan → do-test → do-code-review`) on top of the rest of the `/do-*` skills and the seven
+specialist agents (`core-implementer`, `delivery-lead`, `quality-guardian`,
+`research-writer`, `reviewer`, `spec-analyst`, `system-architect`). Discipline borrowed from
+spec-kit; enforcement done with the harness's real hooks rather than a prompt-read registry.
+The implement-gate hook is registered in
 `settings.json`. `do-constitution` sits outside the numbered chain — a standalone,
 still-invocable skill that maintains the persistent rules every phase inherits, not a phase
 itself. `do-implement` sits outside the numbered chain too, for the opposite reason: it is the
@@ -18,13 +19,11 @@ remains the chain's own implementation phase.
 |------|-------|
 | `skills/` | Chain skills: `do-brainstorm` (also creates the feature branch/dir, writes `requirement.md`, optionally captures a PBI/ticket ID), `do-design` (writes `design.md`), `do-plan` (also writes the dependency-ordered task checklist inside `plan.md`, plus a Repo Branch Plan for multi-repo features), `do-execute-plan` (also supports `--scaffold` to emit a reviewable code scaffold under the feature dir — the source layout, signatures and test stubs the three artifacts imply, plus a per-dependency-service contract frame — and lazily creates/tracks each repo's branch as it's first touched; a non-local dependency with a `external-contract:` field gets a frame generated from that doc instead of the default silent skip), `do-test`, `do-code-review`. `do-constitution` is standalone, not part of the numbered chain. |
 | `scripts/doflow/` | The runtime seam. Skills call `bin/doflow-run <verb>` and never name a helper: the dispatcher decides which `bash/*.sh` helper or Node command serves each verb. The dispatcher owns the verb namespace and is the only place it is written down — an inventory here is the drift this row used to produce. |
-| `hooks/`               | `pre-implement-gate.sh` — PreToolUse(Edit\|Write) backstop for the one hard gate |
-| `templates/doflow/`    | `requirement-template.md` (optional `**Ticket:**` header field) / `design-template.md` / `plan-template.md` (its own "Tasks" subsection folds in what used to be a separate tasks template, supports optional `depends-on:` and `external-contract:` fields per task, and a Repo Branch Plan table for multi-repo features) / `state-template.md` (Repo Branch Status table) / `constitution-template.md` / `external-contract-template.md` (pinned structure for a `external-contract:` target — a documented external dependency `--scaffold` can generate a mechanical frame from) — seeded into each feature dir. A shared pool across skills, not per-skill `assets/` — see note below. |
-| `references/`          | `CONSTITUTION_BASE.md` — tier-1 global constitution base |
+| `shared/hooks/policies/` | `mcp-tool-guard.sh`: MCP policy; `pre-bash-guard.sh`: command denials; `pre-implementation-gate.sh`: artifact/readiness edit gate; `stop-check.sh`: blocks stopping on unfinished-work markers. Harnesses with hook support call these; support differs per harness. |
+| `templates/doflow/` | `constitution-template.md` (tier-2); `data-model-template.md`; `design-template.md`; `external-contract-template.md`; `intent-template.md`; `plan-template.md`; `question-log-template.md`; `requirement-template.md`; `specs-template.md`; `state-template.md`. Chain skills seed feature dirs from a shared pool, not per-skill `assets/`. |
+| `guidance/references/` | `ARTIFACT_FORMAT.md`, `ARTIFACT_VOICE.md`, `CONSTITUTION_BASE.md` (global tier-1), `DIAGRAM_GUIDE.md`, `DOFLOW_CHAIN.md`, `EVIDENCE_LEDGER.md`, `MODEL_SELECTION.md`, `ORCHESTRATION.md`, `RESEARCH_CONFIG.md`, `WORKFLOW_HANDOFF.md`. |
 
-> Paths above are relative to the installed root (`${CLAUDE_CONFIG_DIR:-$HOME/.claude}` globally,
-> or a project's own `.claude/` in project scope). Chain skills' resolver lookups check the global
-> config dir first, then walk upward from `$PWD` for a project-scoped `.claude/` install.
+> Except `skills/`, use resolver roots: `.doflow/` at/above `$PWD`, then `$HOME/.doflow/`; skills install per harness in its skills dir.
 
 ## Core design rules
 
@@ -37,7 +36,7 @@ remains the chain's own implementation phase.
   Outside a git repo (e.g. doflow installed at a multi-service container root, above the actual
   git sub-repos), `do-paths.sh` falls back to scanning `agent-docs/doflow/` directly — one
   candidate auto-selects, 2+ candidates surface via `candidate_slugs` for the calling skill to
-  disambiguate using the platform-specific `RULE_04_QUESTIONS.md` mechanism. Artifacts live in
+  disambiguate using the platform-specific RULE_04 mechanism in `rules/RULES.md`. Artifacts live in
   `<repo>/agent-docs/doflow/NNN-slug/`
   either way.
 - **Pre-chain intent — an input, not a phase.** An idea that has not been committed to yet goes in
@@ -53,13 +52,11 @@ remains the chain's own implementation phase.
   `requirement.md`'s `**Intent:**` field — the argument that does so is declared in `/do-brainstorm`'s
   own `argument-hint`, which is where a single-skill argument is owned. Discovery without an intent is
   unchanged and is the ordinary case.
-- **One hard gate:** source edits are blocked when a feature is started but `requirement.md`,
-  `design.md`, or `plan.md` is missing. Every other gate is advisory/skippable (solo,
-  low-ceremony).
+- **Implement gate (hard):** Denies source edits for started features missing `requirement.md`/`design.md`/`plan.md` (`missing-artifacts`), or held tasks without READY at their workflow's first source-mutating stage (`readiness-missing`, `readiness-not-ready`, `readiness-wrong-template`, or `readiness-store-conflict` when a linked worktree's copy differs from the main checkout's). Other blockers: `shared/hooks/policies/`, and the planning stage's exit, which refuses a constitution MUST conflict ("Two-tier constitution" below); all other chain gates are advisory/skippable.
 - **Two-tier constitution — what is computed vs. what is convention.**
   `references/CONSTITUTION_BASE.md` (tier-1, global) is overlaid by
   `<repo>/agent-docs/constitution.md` (tier-2, per-repo), and tier-2 takes precedence. **That
-  overlay is performed by the chain skill reading both files — no component merges them.** This is
+  overlay is performed by the chain skill reading both files — no component writes a merged file.** This is
   the canonical statement; other places point here rather than restating it.
 
   | Step | What happens | Guarantee |
@@ -67,14 +64,15 @@ remains the chain's own implementation phase.
   | Locate tier-1 | `do-paths.sh` searches two candidates, first hit wins; `null` if none | **computed** |
   | Locate tier-2 | `do-paths.sh` emits the path plus `has_constitution_local` | **computed** |
   | Read both files | the chain skill opens them | agent-performed |
-  | Overlay; tier-2 takes precedence on conflict | the chain skill reconciles them in its own reasoning | **convention** |
+  | Overlay; tier-2 takes precedence on conflict | the chain skill reconciles them; the exit check overlays them by principle id | **convention**; **computed** for the check |
   | "Tier-2 may not weaken P1 (Safety)" | a rule stated to the agent | **convention, unvalidated** |
-  | Constitution Check verdict | recorded in `plan.md` §2 "Constitution Check" | **advisory — blocks nothing** |
+  | Constitution Check verdict | one PASS/FAIL row per principle in `plan.md` §2; the `do-plan` stage's handoff refuses a MUST marked FAIL or without a row | **computed — blocks the planning exit** |
   | Propagate pointer to the agent context file | `sync-context.sh` writes a marker block | **computed** |
 
   Both path lookups run unconditionally, whether or not `do-constitution` has ever been invoked.
-  Nothing detects a conflict between the tiers, and nothing validates the P1 rule — so avoid
-  describing this model as *resolved* (there is no merged artifact) or *enforced* (nothing blocks).
+  The model judges each principle; the runtime enforces only the record, MUST unless a principle
+  says `**Tier:** SHOULD`, with no waiver. Nothing validates the P1 rule, and no merged artifact
+  exists, so avoid describing the overlay as *resolved*.
   The convention is still load-bearing: it is how the rules actually reach a feature's planning.
 - **`templates/doflow/` is a shared template pool, not the Agent Skills standard's
   `references/`/`assets/` pattern.** The standard nests bundled resources one level inside their

package/core/shared/guidance/references/EVIDENCE_LEDGER.md

@@ -51,14 +51,13 @@ linking (below), not by a field on the item.
 
 ## Superseding a stale item
 
-An item's `freshness.status` can only move toward `STALE` — the file it named changed, and nothing
-un-changes it. Once a stale item stops mattering (a fresher item already covers the same ground),
-retire it rather than leaving it to block a task's readiness verdict forever: `evidence --action
-supersede --evidence-id <stale-id> --replaced-by <fresh-id>`, naming an id already recorded. Nothing
-is deleted or rewritten — the stale item's own content and locator stay exactly as observed, only
-its `status` becomes `superseded` and unresolvable readiness checks stop counting it. Record the
-replacing item first: the replacement must already exist, the same rule `claim --action supersede`
-already applies.
+An item's `freshness.status` only moves toward `STALE` (the file it named changed). Once a stale
+item stops mattering, retire it rather than let it block readiness forever: `evidence --action
+supersede --evidence-id <stale-id> --replaced-by <fresh-id>`, the replacement recorded first (the
+rule `claim --action supersede` applies). Nothing is deleted: the item keeps its content and
+locator, its `status` becomes `superseded`, and readiness stops counting it. With no replacement,
+`evidence --action retire` with its stale selector (see the CLI help) retires every stale item the
+same way, keeping the reason on each.
 
 ## Claims
 

package/core/shared/guidance/references/MODEL_SELECTION.md

@@ -33,8 +33,8 @@ mechanical work. Fewer turns can cost less than a cheaper model that needs repea
 ## Reviews
 
 Reviews are read-only `frontier` work by an agent and model different from the author. Report if that
-tier is unavailable. Review once per phase or fix batch; re-review only an open blocker tests cannot
-settle, after asking. Deep reviews use two independent reviewers with different lenses.
+tier is unavailable. Review once per phase or fix batch; re-review after fixes is automatic, per
+`doflow review --action start`.
 
 ## Archetype dispatch tiers
 
@@ -46,9 +46,11 @@ settle, after asking. Deep reviews use two independent reviewers with different
 |---|---|---|
 | `system-architect` | `frontier` | Architecture sets system shape: a consequential decision. |
 | `core-implementer` | `standard` | Routine coding against a settled spec. |
-| `quality-guardian` | `standard` | Its testing and evidence work; a review runs at `frontier` per-dispatch (`## Reviews`), not via `byOwner`. |
+| `quality-guardian` | `standard` | Testing and evidence work; review tasks belong to `reviewer`. |
 | `spec-analyst` | `standard` | Requirements analysis and routine research. |
 | `research-writer` | `standard` | Documentation and routine research. |
+| `delivery-lead` | `frontier` | Plans and orchestrates delivery; its records gate merges. |
+| `reviewer` | `frontier` | Review verdicts gate merges (`## Reviews`). |
 
 ## Briefs and inheritance
 

package/core/shared/guidance/references/ORCHESTRATION.md

@@ -1,7 +1,6 @@
 # Orchestration
 
-Use `references/MODEL_SELECTION.md`; follow `PRINCIPLES.md`, `rules/RULE_02_WORKFLOW.md`, and
-`rules/RULE_04_QUESTIONS.md`.
+Use `references/MODEL_SELECTION.md`; follow `PRINCIPLES.md` and `rules/RULES.md` (RULE_02, RULE_04).
 
 ## Role and handoff
 

package/core/shared/guidance/rules/RULES.md

@@ -0,0 +1,45 @@
+# Rules
+
+## RULE_01 Safety
+Conflict order: Safety > Scope > Quality > Speed. Prototype != Production requirements.
+- Read the date from the environment before any temporal claim; never infer it from your knowledge cutoff, and state its source.
+
+## RULE_02 Workflow
+- **Parallel when write sets are disjoint; otherwise sequential.** Use task lists past 3 tasks when available.
+- Run lint/typecheck before marking complete.
+- Check deps (package.json) and existing patterns before any changes.
+- Feature delivery follows the doflow chain — see `references/DOFLOW_CHAIN.md` for the phase-gated flow, artifact contracts, and the enforced gate.
+- Start it = Finish it. No partial features, TODO stubs, mocks, or "not implemented" throws. <!-- must-carry -->
+- All generated code must work as specified; no scaffolding placeholders.
+
+**Scope Discipline**
+- Build ONLY what's asked — no bonus features, no enterprise bloat (auth/monitoring/deployment unless requested). <!-- must-carry -->
+- MVP first; YAGNI; single responsibility per component.
+
+## RULE_03 Quality
+**Naming**: Follow language standards (camelCase JS, snake_case Python); no mixed conventions
+**Files**: Follow the repository's existing layout; only if none exists, use `tests/` for tests, `scripts/` for scripts and `agent-docs/` for reports.
+**Workspace**: Remove temp files, debug scripts, build artifacts after use; never leave clutter in VCS
+
+**Professional Honesty**
+- No marketing language ("blazingly fast", "100% secure", "magnificent")
+- No invented sources, figures, citations or quotes; leave out what you cannot trace; state "untested/MVP/needs validation" honestly <!-- must-carry -->
+- If you are not sure, say so plainly and name what is unknown; do not present a guess as established <!-- must-carry -->
+- Warn when a claim may be outdated: information from memory or an old source can have changed since it was written
+- Never attribute a statement or view to a real person unless you have verified it; otherwise omit the name
+- Push back on bad approaches
+
+## RULE_04 Questions
+- Ask ONLY for genuine user-owned decisions unresolved by the request, the code, or sensible defaults.
+- Enough to act → act; don't ask to confirm the obvious (see RULE_02 Scope Discipline).
+- One question that unblocks beats three that re-litigate settled choices.
+
+**Non-Interactive Fallback**
+When no native interactive question tool (one that presents options and returns the user's choice) is available in the current session:
+- Do NOT generate `{stage}-questions.md` files or halt execution waiting for manual file edits.
+- Adopt the recommended default choice, record the adopted decision and rationale in the stage notes or artifact, and proceed with execution.
+- If no sensible default exists and execution cannot safely proceed without user input, report the specific ambiguity and halt.
+
+## Flags and runtime
+What the user typed beats auto-detection. A flag is declared in the `argument-hint` of every skill that consumes it; shared flags are `--depth` and `--type`.
+The runtime grades a source-editing stage against its class contract first (four states, no score), classifies a failed verification and retries it under a bound it sets, records and reads back every call (never reconstructs a run), and routes a need to a provider healthy here, not a habitual tool.

package/core/shared/scripts/doflow/bash/do-args.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# do-args.sh — the one argument rule the do-*.sh helpers share. Sourced, never run.
+#
+# Their argument loops read `--flag=value`. A caller that writes `--flag value` used to fall through
+# the loops' `*) ;;` arm with the flag dropped and the value ignored, so `do-paths.sh --slug x`
+# silently resolved the ACTIVE feature instead of x. doflow_normalize_args folds the space form into
+# the `=` form for the flags a script declares, so the loop itself stays as it was.
+#
+#   doflow_normalize_args "<flag> <flag> ..." "$@"
+#   set -- ${DOFLOW_ARGS[@]+"${DOFLOW_ARGS[@]}"}
+#
+# The next word is a flag's value unless it starts with a dash: a value-less `--slug` (last, or
+# followed by another flag) stays bare and is dropped by the loop exactly as before, and a word that
+# starts with a dash is never swallowed. An empty word is a value. Flags a script did not declare,
+# `--flag=value` words and positional words pass through untouched. bash 3.2 compatible: the array
+# is filled by index and expanded with the `${a[@]+...}` guard, which `set -u` needs for an empty one.
+
+doflow_normalize_args() {
+  local _flags=" $1 " _word _pending=""
+  shift
+  DOFLOW_ARGS=()
+  for _word in "$@"; do
+    if [ -n "$_pending" ]; then
+      case "$_word" in
+        -*) DOFLOW_ARGS[${#DOFLOW_ARGS[@]}]="$_pending" ;;
+        *)  DOFLOW_ARGS[${#DOFLOW_ARGS[@]}]="$_pending=$_word"; _pending=""; continue ;;
+      esac
+      _pending=""
+    fi
+    case "$_word" in
+      --*=*) ;;
+      --*)   case "$_flags" in *" $_word "*) _pending="$_word"; continue ;; esac ;;
+    esac
+    DOFLOW_ARGS[${#DOFLOW_ARGS[@]}]="$_word"
+  done
+  if [ -n "$_pending" ]; then DOFLOW_ARGS[${#DOFLOW_ARGS[@]}]="$_pending"; fi
+}

package/core/shared/scripts/doflow/bash/do-exec-paths.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # do-exec-paths.sh — resolve the execution workspace and one task's artifact paths.
 #
 # The single source of truth for where a task's brief, report, and review packages
@@ -29,6 +30,9 @@ group_id=""
 tasks_csv=""
 slug_override=""
 mode=""
+# Shared argument rule: `--flag value` is read like `--flag=value` for the flags named here (do-args.sh).
+_da="$(dirname "$0")/do-args.sh"
+if [ -r "$_da" ]; then . "$_da"; doflow_normalize_args "--task --group --tasks --slug" "$@"; set -- ${DOFLOW_ARGS[@]+"${DOFLOW_ARGS[@]}"}; fi
 for arg in "$@"; do
   case "$arg" in
     --task=*)

package/core/shared/scripts/doflow/bash/do-git-state.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # do-git-state.sh — deterministic lifecycle state helper for /do-git.
 #
 # Emits JSON describing the repository's position in the development cycle.
@@ -30,6 +31,9 @@ mode=""
 class_name=""
 slug=""
 
+# Shared argument rule: `--flag value` is read like `--flag=value` for the flags named here (do-args.sh).
+_da="$(dirname "$0")/do-args.sh"
+if [ -r "$_da" ]; then . "$_da"; doflow_normalize_args "--class --slug" "$@"; set -- ${DOFLOW_ARGS[@]+"${DOFLOW_ARGS[@]}"}; fi
 for arg in "$@"; do
   case "$arg" in
     --state)                    mode="state" ;;
@@ -264,7 +268,14 @@ next_free_prerelease() {
   printf '%s-%s.%s %s\n' "$core" "$label" "$candidate" "$skipped"
 }
 
-# The newest release tag reachable from HEAD or from the production branch, by version order;
+# What a release tag looks like: vX.Y.Z with an optional pre-release. A tag such as vx or vnext also
+# matches `v*`, and under the version sort `vx` outranks every vN.N.N, so the base tag, the lifecycle
+# release_tags and the next-version proposal all filter with this one pattern. A number has no
+# leading zero (v01.0.0 is not a release), as semver has it.
+RELEASE_TAG_PATTERN='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?$'
+
+# The newest release tag reachable from HEAD or from the production branch, by version order
+# (versionsort.suffix=- ranks a pre-release below its stable release, which plain version sort does not);
 # empty when there is none. do_next_version bases its proposal on it and the lifecycle output
 # reports it, so the two never disagree. The reasoning behind "newest by version" and "reachable
 # from production too" is in do_next_version's comments below.
@@ -277,7 +288,7 @@ find_base_tag() {
   done <<< "$(production_refs)"
   eligible="$(printf '%s\n' "$eligible" | sort -u | sed '/^$/d')"
   if [ -n "$eligible" ]; then
-    base_tag="$(git tag --list 'v*' --sort=-v:refname 2>/dev/null | grep -Fx -f <(printf '%s\n' "$eligible") | head -1 || true)"
+    base_tag="$(git -c versionsort.suffix=- tag --list 'v*' --sort=-v:refname 2>/dev/null | grep -E "$RELEASE_TAG_PATTERN" | grep -Fx -f <(printf '%s\n' "$eligible") | head -1 || true)"
   fi
   printf '%s\n' "$base_tag"
 }
@@ -350,7 +361,7 @@ do_next_version() {
   fi
 
   jq -n \
-    --arg base_tag "${base_tag:-null}" \
+    --arg base_tag "$base_tag" \
     --arg current_version "$current_version" \
     --arg next_version "$next_version" \
     --arg next_prerelease "$next_prerelease" \
@@ -501,7 +512,7 @@ lifecycle_integration_ref() {
 do_lifecycle() {
   local integration="" tags="" base_tag=""
   integration="$(lifecycle_integration_ref)"
-  tags="$(git tag --list 'v*' 2>/dev/null | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$' || true)"
+  tags="$(git tag --list 'v*' 2>/dev/null | grep -E "$RELEASE_TAG_PATTERN" || true)"
   base_tag="$(find_base_tag)"
 
   local behind=0

package/core/shared/scripts/doflow/bash/do-parallel-check.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
 # do-parallel-check.sh — verify one phase's [P] siblings really write disjoint files.
 #                        Form dispatch groups by (phase, owner) and detect union overlaps.
 #
@@ -25,6 +26,9 @@ set -uo pipefail
 
 phase=""
 slug_override=""
+# Shared argument rule: `--flag value` is read like `--flag=value` for the flags named here (do-args.sh).
+_da="$(dirname "$0")/do-args.sh"
+if [ -r "$_da" ]; then . "$_da"; doflow_normalize_args "--phase --slug" "$@"; set -- ${DOFLOW_ARGS[@]+"${DOFLOW_ARGS[@]}"}; fi
 for arg in "$@"; do
   case "$arg" in
     --phase=*) phase="${arg#--phase=}" ;;