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

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

@@ -0,0 +1,161 @@
+# Diagram Guide — what a good chain diagram looks like
+
+`ARTIFACT_FORMAT.md` §4 says which artifact carries which diagram slot. This file says what belongs
+inside one. Read on demand by `do-brainstorm`, `do-design` and `do-plan` at the point each fills a
+slot, and never loaded into a session by default.
+
+**Scope.** These rules govern every Mermaid diagram in a feature directory, including ones in
+`as-is/`, `target/` or any other subdirectory a feature grows. The slot registry in §4 of
+`ARTIFACT_FORMAT.md` lists only the slots a template scaffolds, because those are the ones a stage
+is accountable for; the conventions here are wider than that list.
+
+## 1. Permitted types
+
+| Type | Carries |
+|---|---|
+| `flowchart` | Structure, scope boundaries, C4 levels, dependency order |
+| `sequenceDiagram` | Time-ordered interaction between participants |
+| `erDiagram` | Entities with attributes, keys and cardinality |
+| `stateDiagram-v2` | States, transitions and the guards between them |
+
+**The admission rule.** A type joins this list when it renders in GitHub, the VS Code Markdown
+preview and Obsidian with no plugin installed by the reader, and its grammar is not marked
+experimental by Mermaid. Both halves matter: a type that renders today but whose grammar is still
+moving will silently change shape under artifacts already written against it.
+
+**C4 is a zoom model here, not a diagram type.** `C4Context`, `C4Container`, `C4Component` and
+`C4Dynamic` are excluded by the admission rule's second half — Mermaid's own C4 syntax documentation
+states the C4 diagram is experimental and that its syntax and properties can change in future
+releases. The practical cost is visible in Mermaid's own examples: relationship labels are placed by
+hand with one `UpdateRelStyle($offsetX, $offsetY)` call per relationship, and layout is nudged
+through `UpdateLayoutConfig` rather than a direction keyword. Render every C4 level with `flowchart`
+plus `subgraph` instead, which gives explicit direction and puts each label on its arrow without
+per-edge tuning.
+
+**Everything else is excluded too**, including types that do render widely — `journey`, `timeline`,
+`quadrantChart`, `gitGraph`, `mindmap` — and every `-beta` grammar. Not because any one of them is
+bad, but because each added type is another set of conventions to carry and another surface that can
+drift between renderers. Four types cover what the chain actually needs.
+
+## 2. Choosing between them
+
+| When the content is… | Reach for |
+|---|---|
+| What is in and out of scope | `flowchart`, `subgraph IN` / `subgraph OUT` |
+| Actors and external systems, or deployable units, or a container's internals | `flowchart` with `subgraph` boundaries, one per C4 level |
+| Phases, tasks and what must finish before what | `flowchart`, direction `LR` |
+| Who calls whom, in what order, with the failure branch | `sequenceDiagram` |
+| Entities and the relationships between them, no attributes yet | `flowchart` |
+| Entities with their fields, keys and cardinality | `erDiagram` |
+| A run, a lifecycle, or anything with named states and guarded transitions | `stateDiagram-v2` |
+
+Two rules of thumb. If a three-column table says the same thing, write the table. If the content
+wants two of these at once, it is two diagrams.
+
+## 3. Complexity budget
+
+Each type is bounded on what actually makes that type illegible, not on one number applied to all.
+
+| Type | Element ceiling | Link ceiling |
+|---|---|---|
+| `flowchart` | 12 nodes | 16 edges |
+| `sequenceDiagram` | 8 lifelines | none |
+| `erDiagram` | 8 entities | none |
+| `stateDiagram-v2` | 10 states | none |
+
+`subgraph` containers do not count toward the node ceiling; they are grouping, not content.
+
+**Why only `flowchart` carries a link ceiling.** A `sequenceDiagram` lays out columnwise — lifelines
+vertical, messages horizontal — so no routing decision is ever made and nothing can tangle however
+many messages it carries. A `flowchart` is routed by the layout engine, and above a certain density
+that engine produces edges that overlap each other or cross boxes that are not their endpoints. The
+edge ceiling exists for that failure and belongs only to the type that has it. The same reasoning
+applies to `erDiagram` relations and `stateDiagram-v2` transitions: a reader tracks entities and
+states, and the links follow from them.
+
+**Where the numbers come from.** Measured against 56 Mermaid diagrams in a completed feature, not
+chosen for roundness. Flowchart node counts were bimodal — eleven diagrams at six or fewer, four at
+seventeen or more, nothing between twelve and sixteen — so the ceiling sits in that empty band and
+flags only the four that should have been split. Sequence lifelines ran three to thirteen, with
+twenty-three of twenty-six at eight or fewer. Entity and state counts never exceeded six and seven,
+so those ceilings are stated intent rather than a tested constraint. Re-measure against your own
+corpus before moving a ceiling, and move it with the count rather than by preference.
+
+## 4. When a diagram is over budget
+
+Split it into an overview and a detail diagram. The overview keeps the boxes a reader needs to
+orient, and one of them expands into the detail diagram beneath it.
+
+Do not shrink labels, do not drop the arrow labels, and do not accept the crowding because the
+content "really is that big". Content that big is the signal, not the exception: a diagram past the
+ceiling is two ideas sharing a frame, and the split is what separates them.
+
+The one legitimate alternative is deletion. Two nodes that always travel together are one node, and
+a relationship obvious from the layout does not need its own line.
+
+## 5. Conventions
+
+**Direction is declared, never left to default.** Write `flowchart TB` or `flowchart LR`. Pick `LR`
+for anything that reads as a progression (scope, phases, dependency order) and `TB` for anything
+that reads as containment or hierarchy.
+
+**Labels go on the arrow, not in the node.** `A -->|"reads"| B`, not a node named "reads from B".
+Keep an arrow label to a short verb phrase: if it needs a clause, the relationship is doing too much
+and wants two arrows or a different type. Quote every label, so a comma or a parenthesis inside it
+cannot end the label early.
+
+**Node ids are short and stable; the text lives in the brackets.** `SVC["Payment service"]`, not
+`PaymentService["Payment service"]`. An id is an anchor a later edit reuses; the label is prose that
+changes freely.
+
+**`subgraph` marks a boundary, and its label is quoted**: `subgraph boundary["Payment platform"]`.
+Use it for a trust boundary, a deployable unit, a C4 level or a scope partition. Do not use it to
+group things that merely look similar.
+
+**In a `sequenceDiagram`, prefer `rect` over `par` to mark a region.** `par` renders as a split
+block that reads as "these happen simultaneously", which is a claim most groupings do not want to
+make and cannot support. `rect` groups without asserting concurrency. Reserve `par` for genuine
+parallelism, and use `alt` for a branch.
+
+**Keep edges inside their boundary.** An edge that crosses a `subgraph` boundary is the one the
+layout engine routes across other edges, and it is what produces overlapping arrows and labels
+stranded mid-canvas. This is not a density problem and the node ceiling does not catch it: a
+six-node diagram with two boundary-crossing edges tangles where a nine-node diagram whose edges all
+fan into one sink stays clean. Prefer edges within a boundary, or between two boundaries at the same
+level. When a node inside a `subgraph` must reach one outside it, the boundary is usually drawn in
+the wrong place — move it, or lift the shared node out.
+
+**Secondary and asynchronous relations use `-.->`.** Reserve the dashed arrow for what it says:
+optional, deferred, or out of band. A dashed arrow used for variety costs the reader the one signal
+it carries.
+
+**Skipping a slot is `N/A: [why]`.** That escape is a format rule and is defined once, in
+`ARTIFACT_FORMAT.md` §4. A slot left silently empty cannot be told apart from an oversight.
+
+## 6. Authored sources
+
+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
+is a change the next render discards.
+
+**The generated view drops seven things** — element type, technology, description, sprite, tag, link
+and the legend — keeping nodes, edges, labels and boundaries. Need any of the seven, open the image;
+that is why the generated block names its source.
+
+**A flow gets one lane per actor**, ordered by who acts first, with the failure branch reaching its
+own terminal. One file per flow, `flow-<name>.puml`, matching its `#### Flow: <name>` heading. Skip
+with `N/A: [why]` for a single-actor flow.
+
+## 7. Anti-patterns
+
+| Pattern | Why it fails |
+|---|---|
+| A node per step of a process that has no branches | A numbered list says it in fewer words and reads faster |
+| Every node the same shape and weight | Shape is the only hierarchy a diagram has; spending none of it flattens everything |
+| An arrow with no label | The reader can see two things are connected and has to guess how |
+| A label long enough to wrap | A wrapped label pushes its own arrow around and reads as a sentence, not an annotation |
+| Restating a table that sits directly above it | Two representations of one fact drift apart, and the reader has to work out which is current |
+| One diagram carrying both the overview and the detail | Past the ceiling this is the shape the split rule exists to break up |
+| Colour or `classDef` styling as the only way to read it | Styling varies by renderer and theme; anything load-bearing belongs in the structure or the labels |
+| A diagram nobody would miss | If removing it costs the reader nothing, it was decoration |

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

@@ -0,0 +1,87 @@
+# 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
+`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
+no-artifacts-required escape hatch for implementing directly from a description or
+`do-code-review` findings when there is no `plan.md` task checklist to orchestrate — `do-execute-plan`
+remains the chain's own implementation phase.
+
+## Layout
+
+| Path | Holds |
+|------|-------|
+| `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 |
+
+> 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.
+
+## Core design rules
+
+- **Deterministic / generative split, through one seam:** all path math, feature numbering,
+  existence checks, grading and verification happen behind `bin/doflow-run <verb>` (`--json`
+  output); skill prompts resolve the seam once, then call verbs and reason about what comes back.
+  No filesystem math in prompts, and no skill reaching past the dispatcher to a helper by name.
+- **Branch-coupled state (git repos) / directory-scan fallback (non-git roots):** in a git repo,
+  the active feature is derived from the branch (`feat/NNN-slug`), not a separate state file.
+  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
+  `<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
+  `<repo>/agent-docs/intent/<kebab-description>.md`, from `templates/doflow/intent-template.md`. It is
+  deliberately outside everything the rule above describes: no branch, no slug, no feature directory,
+  nothing resolves its path, and it carries neither closed vocabulary because nothing has been decided.
+  Intents are **not numbered** — `NNN-` marks a feature that has started, and an intent that is never
+  built would consume a number and leave a gap.
+
+  It is **not a phase**, and adding it to the phase list would break it: a phase resolves against a
+  feature directory, which resolves against a branch, so the intent would come to require the branch it
+  exists to precede. Instead the discovery stage reads one when given its path, and records it in
+  `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).
+- **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
+  the canonical statement; other places point here rather than restating it.
+
+  | Step | What happens | Guarantee |
+  |------|--------------|-----------|
+  | 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** |
+  | "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** |
+  | 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 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
+  owning skill (`skill-name/assets/*`); these templates sit outside any single skill's directory
+  and are pulled in by four different skills (`do-brainstorm`, `do-design`, `do-plan`,
+  `do-constitution`) via a hardcoded relative path in each one's own Behavioral Flow. Intentional
+  — a shared pool avoids duplicating the same templates into four separate `skill/assets/`
+  folders — but noted explicitly so it isn't mistaken for the standard's per-skill `references/`
+  shape, which has a different purpose (on-demand knowledge a skill loads into its own reasoning,
+  not scaffold files it copies out as new artifacts).

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

@@ -0,0 +1,93 @@
+# Evidence Ledger — item schema, provenance, and what the runtime refuses
+
+The shape of an evidence batch is the same for every stage that writes one, so it is stated once
+here. A stage's own SKILL.md names the two commands it runs and what *its* items are; everything
+below is common to all of them. Read this before writing a batch.
+
+## The batch
+
+One pass at the stage boundary, never one call per fact. The batch file is a JSON array, one object
+per item — scratch input, deleted after the write. It is validated whole: **one rejected item writes
+nothing**, so a half-written stage never reads as complete.
+
+## Per item
+
+- **`kind`** — one of `exact-search`, `semantic-retrieval`, `structural`, `historical`,
+  `documentation`, `test-result`, `runtime-observation`, `user-statement`, `diff`,
+  `generated-analysis`.
+- **`provenance`** — `extracted` | `inferred` | `asserted`, with **no default**. An unstated
+  provenance is refused rather than filed as repository fact.
+- **`source`** — `provider` + `capability`. There is no `unknown` stand-in; if you cannot name what
+  produced the item, you do not yet have the item.
+
+Pairing rules: `extracted` needs a `locator` (unless the item carries an `observation` — the
+command is then what the next worker re-runs to check it); `inferred` and `asserted` need
+`content`; `generated-analysis` and `user-statement` can never be `extracted` — that pairing is how
+a reading of the evidence stops being distinguishable from the evidence.
+
+## Bindings and observations
+
+- **`establishes`** — the readiness-template requirement id(s) this item was gathered to prove,
+  e.g. `["baseline_tests"]`. The gate counts an item toward a requirement **only** when named here:
+  kind alone is a category, and category coverage is not proof. One extracted read may establish
+  two requirements by declaring both. An item that establishes nothing is still evidence — it just
+  satisfies no gate requirement.
+- **`observation`** — `{command, exitCode}`, the execution behind a `test-result` or
+  `runtime-observation`. Required for an `extracted` `test-result`; refused on any inferred or
+  asserted item (an inference did not run anything). Where a template expects a passing run
+  (`baseline_tests`), a bound observation that exited non-zero is reported as the failure it was —
+  never as the passing baseline it is not. A bug reproduction succeeds by observing the expected
+  failure, so its observation may exit non-zero.
+
+## The accepted set is closed
+
+An item carries exactly `kind`, `provenance`, `source`, `locator`, `content`, `taskId`,
+`establishes`, `observation` — nothing else. Any other key is refused and the whole batch writes
+nothing, so a field you invent costs the batch, not just the field. The list below is what people
+reach for most, and why each is absent:
+`id`, `freshness`, `supports`/`contradicts`, `stage`, any score field. Freshness is measured at the
+write, not declared by the writer; the ledger assigns the id; and evidence attaches to a claim by
+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.
+
+## Claims
+
+Each conclusion is added as a claim in the same pass and is stored as a `hypothesis`. It becomes
+supported only through linked evidence — the `claim` verb's link action, naming the claim id, the
+evidence id, and the relation, spelled exactly `supports` or `contradicts`. An earlier stage, a subagent, or
+an artifact from a previous session having asserted something is not support.
+
+A claim may declare a `--role` (lowercase-kebab, e.g. `root-cause`) stating its relationship to
+the task. Where a template requires a role, only a supported claim carrying it counts: a supported
+claim about something unrelated does not answer a requirement it never addressed.
+
+The link refuses an evidence id the ledger does not hold: exit 2, naming the id, not a low grade.
+Record the batch first, link afterwards. A claim carrying both fresh support and fresh
+contradiction becomes `conflicted`.
+
+## Relevance is not confidence
+
+A match count, a ranking, a "best hit", a profiler's top hot path — each is a property of the query,
+not of the fact. Record the locator. Never a score, a percentage, or a confidence.
+
+## Readiness belongs to the stage that edits source
+
+A stage whose `readinessTemplate` is `null` does not call `readiness`, and does not report one as
+skipped: there is no source edit for it to gate. The per-class readiness contract itself is owned by
+the `do-execute-plan` skill's own `readiness_gate.md` reference, not restated here.
+
+## Source is not inference in the report either
+
+The same items are the stage's completion report: per item, what was found, its source, its locator,
+and whether it is **extracted** (read verbatim from the repository or a command) or **inferred**
+(your analysis). Never merge those two provenances into one reported line.

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

@@ -0,0 +1,74 @@
+# Model Selection — choosing a tier per dispatch
+
+Choose the lowest capable tier. Name it on every dispatch, and pass `model:` whenever the API
+supports it. Never assume the parent's choice reaches subagents; where per-call selection is
+unavailable, set the model in the agent definition. An unset tier is a defect.
+
+## Capability tiers
+
+Tiers describe capability; model names vary by harness. Map each to the harness's supported
+identifier at dispatch; never hardcode a vendor model name here.
+
+| Tier | Work |
+|---|---|
+| `light` | Verbatim extraction, classification, mechanical or high-volume work. |
+| `standard` | Normal coding, debugging, writing, analysis, routine research, and evidence gathering. |
+| `frontier` | Architecture, hard debugging, broad refactors, consequential decisions, and every review. |
+
+Use the harness's supported model identifier; never invent or probe one. Consequential decisions
+gate money paths, releases or tests, rewrite history, set design, or authorize unchecked action.
+Gather evidence at `standard`; judge it at `frontier`. Split mixed-tier work or use the higher tier.
+
+## Choosing a tier for implementation
+
+| Signal | Tier |
+|---|---|
+| 1–2 files, complete spec, exact values | `light` |
+| Several files or integration with existing patterns | `standard` |
+| Design decision or subsystem investigation | `frontier` |
+
+`standard` is the floor for prose-led implementation; use `light` only for verbatim or single-file
+mechanical work. Fewer turns can cost less than a cheaper model that needs repeated correction.
+
+## 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.
+
+## Archetype dispatch tiers
+
+> **Authoritative:** this section governs each archetype's default dispatch tier.
+> `core/registry/models.json` `dispatchTiers.byOwner` mirrors it and G29 asserts they match;
+> change both together.
+
+| Archetype | Tier | Why |
+|---|---|---|
+| `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`. |
+| `spec-analyst` | `standard` | Requirements analysis and routine research. |
+| `research-writer` | `standard` | Documentation and routine research. |
+
+## Briefs and inheritance
+
+Give `light` and `standard` agents exact files, values or `path:line`, steps, and a check command.
+Give `frontier` agents intent, constraints, evidence, settled decisions, and their open choices.
+Agents that may spawn agents inherit this policy: `light` = verbatim/mechanical;
+`standard` = routine work/research/evidence; `frontier` = architecture, hard debugging,
+broad refactors, consequential decisions, and reviews. Name the tier/model per dispatch.
+
+## Escalation inside a fix loop
+
+After a stuck implementer, raise the tier at least once and use a fresh context.
+
+Consult the harness's capability notes before assuming its per-dispatch model selection behavior.
+
+## Enforceability: a rendered request, not an observed model
+
+`dispatchTiers.byOwner` in `core/registry/models.json` sets each archetype's tier, G29 pins it to the
+table above, and `resolveTier` renders it into every brief. Where a harness supports per-call model
+selection, pass `record.tier` and the policy applies; where it honors only `model: inherit`, the tier
+is a request the host cannot set and the worker runs on the session model — say which case applied in
+the hand-off. No cross-harness mechanism reads a worker's effective model, so the policy is verified
+by the rendered request plus G29, never by observation.

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

@@ -0,0 +1,36 @@
+# Orchestration
+
+Use `references/MODEL_SELECTION.md`; follow `PRINCIPLES.md`, `rules/RULE_02_WORKFLOW.md`, and
+`rules/RULE_04_QUESTIONS.md`.
+
+## Role and handoff
+
+Decide, brief, verify, and keep records. Delegate discovery, research, and source/build edits; own
+briefs, workflow calls, state, and between-task checks. Edit only own bookkeeping; return verification
+defects to an agent. Verify material claims and check author and trailers after agent commits.
+
+## Brief and tools
+
+Brief with **Goal**, **Context** (`path:line`), **Write set**, **Rules**, **Acceptance and
+verification**, **Report format**, and a model/tier. Put long briefs in scratch files. Keep settled
+scope in the dispatch; mid-run messages may be ignored, so verify the hand-back. Resume finished
+agents, and use a fresh agent when scope grows.
+
+The orchestrator chooses tools from each task's evidence needs and names local, web, and MCP tools
+and their read/write scope in the brief. For current facts, specifications, or external patterns, use
+web search/fetch or relevant documentation/retrieval MCPs; prefer primary sources, fetch support,
+and return citations or locators. Routine read-only research needs no user choice. Shared archetypes
+omit tool allowlists, so agents may use the session tool pool within host permissions and sandboxes.
+Check a host exposes needed tools; otherwise gather the source in the orchestrator or report the gap.
+Keep repository search distinct from external research.
+
+## Running work
+
+Dispatch due phases before questions. Parallelize only disjoint write sets; keep reviewers read-only.
+Use throwaway worktrees for build/container tests and serialize shared stacks. Commit green logical
+items with the required author. After a failed/stopped agent, check status, log, stashes, and reflog.
+
+## Asking
+
+Use sensible defaults. Ask one structured question only when a contract or behavior changes beyond
+the request; resolve agent questions rather than forwarding a list.

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

@@ -0,0 +1,21 @@
+# Research Configuration
+
+No loader reads this file: it holds no knobs, only the discipline a research run follows.
+
+**The class.** `research` is a declared task class whose workflow terminates at synthesis and
+declares no readiness template: do not run a readiness check, and do not report one as skipped.
+
+**Retrieval.** The capability router covers repository-local needs only — every registered
+capability resolves inside this repo, and `route` rejects a web intent by name. Web retrieval is
+the harness's own tools; name what answered in the report rather than a vendor you assumed. Ask
+`"$DOFLOW" capabilities` what is registered instead of trusting a written table, but do not expect
+a search provider there yet.
+Two passes, in order: one broad discovery pass over the whole scope — terminology, surfaces,
+competing readings — concluding nothing; then one targeted pass per named sub-question.
+
+**Stopping.** Stop when every sub-question has an answer or a stated gap, **and** the last round
+produced no new source. A round that only restates what you have is the last.
+Report the remaining gaps rather than searching to raise a count.
+
+**Reporting.** Source, provenance and locator per item — never a score, a credibility rating or a
+confidence. Schema and refused fields: `EVIDENCE_LEDGER.md`, beside this file.

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

@@ -0,0 +1,81 @@
+# Recording a workflow handoff
+
+## Decisions first
+
+Before the handoff call, run `"$DOFLOW" paths --json` again (not the stage's earlier result, which
+can predate the register) and, when it reports `has_decisions: true`:
+
+1. List the live decisions with `"$DOFLOW" decision --action list --json`. A decision that changes a
+   live one reuses its topic and names it in `supersedes`; a new topic key is for a genuinely new
+   subject only.
+2. Register this stage's decisions (question answers, gate answers carrying a choice, decisions the
+   user typed as prompts, "Decide for me" defaults, agent resolutions) in one
+   `"$DOFLOW" decision --action add --batch <file>.json --json` call. Drop an item that only
+   rewords a live decision, such as a gate answer do-flow registered; it is neither registered nor
+   used to supersede. Each item needs `topic` (kebab-case), `statement` (one line), `channel`
+   (`question|gate|prompt|default|resolution`), `stage` (the ownership-table stage name) and
+   `rationale`; `supersedes`, `refs` and `source` are optional. Skip the call when there are none.
+   On exit 1 `topic-conflict`, drop the item if it only rewords the named live decision; otherwise
+   add `supersedes` for it, then retry. On exit 1 `register-locked`, retry once; on exit 2, fix the
+   named item and retry. Hand off with the stage's decisions registered, or say which are not.
+3. Write each returned `DEC-###` into the lines of this stage's own artifacts that apply it
+   (ARTIFACT_FORMAT.md §12). A stage that owns no artifact puts the identifiers of what each
+   decision applies to (FR/IC ids) in the item's `refs` and names the returned `DEC-###` ids in the
+   handoff `--note`; it edits no artifact another stage owns.
+4. Run `"$DOFLOW" validate`. Correct each `stale` or `unknown` finding in an artifact this stage
+   owns, changing only the flagged line (an `unknown` one takes the right identifier from the live
+   list); report findings in other artifacts without editing them.
+5. Record the handoff below. It compacts History itself and reports `compaction`; its `--task-id`
+   must be the feature slug, not a plan task id, or compaction is skipped. A do-execute-plan
+   checkpoint (`annotate`) does not compact; the next completed handoff does.
+
+| Stage | Owns |
+|---|---|
+| discovery | `intention/requirement.md` |
+| design | `design/design.md`, `design/specs.md`, `design/data-model.md` |
+| planning | `plan.md` |
+| implementation, verification, review | none; findings are reported |
+
+With or without a register, record in this step each finding left unfixed, item named out of scope
+and gate answer that defers work:
+`"$DOFLOW" followup --action add --stage <stage> --statement "<one line>"`.
+
+## The handoff call
+
+After a skill finishes its work, call the resolved runtime seam:
+
+```bash
+"$DOFLOW" orchestrate --action handoff --task-id "<task>" --calling-skill "<skill>" --note "<what completed>" --json
+```
+
+Pass `--mcp-outcome <server>=used|nothing-usable|skipped:<reason>|unavailable` once per MCP server
+your step names; a server left without one prints a warning, never a block.
+
+Pass `--task-class` only when a classifying skill has accepted that class and may start a run.
+Without an existing run or an explicit class, the result is `standalone` and no state is created.
+An existing run supplies its own class; a conflicting supplied class is refused. Stage ownership
+comes from that run's program, including every occurrence of a skill used more than once.
+
+| `disposition` | Meaning | Caller action |
+|---|---|---|
+| `standalone` | No workflow applies | Finish the standalone report |
+| `completed` | This skill's current occurrence was recorded | Report the result and inspect `awaitingGate` |
+| `annotated` | All occurrences were already recorded; the latest received a rerun note | Report the amendment; do not replay stages |
+| `deferred` | A prior gate, unfinished mutating stage or rejected run prevented the handoff | Report `reason`; leave the transition to its owner |
+
+The runtime imports earlier non-mutating stages as `imported` + `unverified`, skips optional
+stages, and stops at every gate and unfinished mutating stage. It never approves a gate. A mutating
+candidate still requires the same live readiness evaluation as `complete-stage`.
+
+Use `--result passed|failed|unverified` to record the stage's outcome. Omission records `unverified`.
+For bug reproduction, observing the expected failure can satisfy the stage contract; the command's
+nonzero exit alone is not the stage verdict. Reruns append a note and preserve the original outcome.
+
+Only handle an `awaitingGate` if the skill owns that gate and the handoff just completed its anchor.
+Follow the owning skill's decision rules; this API supplies no authorization. A deferral is not a
+rejection. The lower-level `decide-gate` action remains explicit.
+
+After recording work, regenerate the feature trail with `render-audit --slug="<task>" --json`.
+An external recording failure must be reported; it does not change the substantive findings or
+artifact correctness. A deferred workflow transition is still deferred, even when the artifact is
+valid. Read the JSON fields rather than interpreting exit zero as completed work.

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

@@ -0,0 +1,25 @@
+# Safety Rules (CRITICAL)
+
+## Priority System
+**CRITICAL** — Security, data safety, production — never compromise
+**IMPORTANT** — Quality, maintainability, professionalism — strong preference
+**RECOMMENDED** — Optimization, style, best practices — apply when practical
+
+Conflict order: Safety > Scope > Quality > Speed. Prototype != Production requirements.
+
+<important if="debugging, fixing a bug, or investigating a failure">
+## Failure Investigation
+- Root cause always — understand WHY, not just THAT; fix the cause, not the symptom
+- Never skip/disable/comment-out tests or validation to pass builds
+</important>
+
+<important if="performing git operations or starting work on a codebase">
+## Git Workflow
+- `git status && git branch` first; feature branches for ALL work; never force-push main
+- Commit incrementally with descriptive messages; `git diff` before staging; restore-point commit
+  before anything risky
+</important>
+
+## Temporal Awareness
+- Read the date from `<env>` before any temporal claim; never infer it from your knowledge cutoff,
+  and state its source

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

@@ -0,0 +1,23 @@
+# Workflow Rules
+
+## Planning
+- **Parallel by default** — sequential only for hard dependencies; a task list once past 3 tasks, when the session offers one
+- Validate before execution, verify after; 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
+
+<important if="planning or starting a multi-step task">
+## Planning Efficiency
+- Identify concurrent vs sequential operations
+- Map dependencies; batch tool calls; estimate parallelization gains
+</important>
+
+## Implementation Completeness
+- Start it = Finish it. No partial features, TODO stubs, mocks, or "not implemented" throws
+- 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)
+- MVP first; YAGNI; single responsibility per component

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

@@ -0,0 +1,14 @@
+# Quality Rules
+
+## Organization & Hygiene
+**Naming**: Follow language standards (camelCase JS, snake_case Python); no mixed conventions
+**Files**: Organize by feature/domain; tests → `tests/`; scripts → `scripts/`; reports → `agent-docs/`
+**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
+- If you are not sure, say so plainly and name what is unknown; do not present a guess as established
+- 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; evidence-based claims only