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

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

@@ -0,0 +1,373 @@
+# Artifact Format — authoring convention for chain artifacts
+
+How `requirement.md`, `design.md` and `plan.md` are structured so an engineer who did not write a
+feature can learn what it contains without reading it end to end. Loaded on demand by
+`do-brainstorm`, `do-design` and `do-plan`; not part of any always-loaded context.
+
+Checked mechanically by `scripts/doflow/bash/validate-artifacts.sh` — advisory, never blocking.
+`state.md`, contract docs, and `implementation-flow.md` are out of scope; the former are list-shaped, the latter narrative-only.
+`audit.md` is out of scope too, for a different reason: it is machine-generated by `render-audit.sh`
+and never hand-authored, so there is nothing for a consistency checker to check (see §9, "What the
+checker does and does not do" — not the `## 9. History` inside §3's own fenced example below, which
+illustrates an *artifact's* §9, not this document's).
+
+## 1. Index then detail
+
+Every enumerated, ID-bearing section opens with a table summarising its items, followed by
+`**Detail**` and the full normative text of each one.
+
+```markdown
+| ID | Requirement | Priority | Status |
+|---|---|---|---|
+| FR-001 | One-line summary | P1 | Live |
+
+**Detail**
+
+- **FR-001:** The system MUST [full normative text, every qualifier and exception intact].
+```
+
+Rules:
+
+- The **index is navigation, not a substitute.** Detail carries the full text; a reviewer must be
+  able to rely on it alone for correctness. Adding an index never shortens what was already there.
+- **Every index row has exactly one detail entry, and vice versa.** Orphans on either side are
+  what the validator reports first.
+- The first column header must be literally `ID`, and the status column header literally `Status` —
+  the checker locates them by name, so a column added to the right cannot shift the check.
+- A detail entry takes either of two forms, and both may appear in the same artifact. Neither is
+  deprecated.
+  - **Bullet form:** a line starting `- **<ID>`, where `<ID>` is the leading token inside the bold.
+    A trailing colon or a parenthetical qualifier inside the bold is fine: `- **FR-001:**` and
+    `- **NFR-002 (Backward compatible):**` both parse.
+  - **Heading form:** a line matching `#### <ID>: <text>`, which counts as a detail entry only when
+    `<ID>` also appears in the first column of that section's index table. An ID-shaped heading with
+    no matching index row is not a detail entry and is ignored, so an unrelated heading cannot
+    invent a parity finding of its own.
+
+    Two conditions bound this form, and the bullet form is the answer wherever they do not hold.
+    The index table must appear **before** the detail it pairs with, because a heading is read
+    against the rows already seen. And the index must be **ID-first**: §3's History table leads with
+    `Date`, so **History detail uses the bullet form**. Neither condition binds the bullet form,
+    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.
+Prose sections do not.
+
+## 2. Status and Maturity — two closed vocabularies
+
+### Status — the state of one indexed item
+
+| Value | Meaning |
+|---|---|
+| `Live` | In force as written |
+| `Superseded → <ref>` | Replaced; `<ref>` names what replaced it |
+
+Nothing else is permitted — no `TBD`, `Draft`, `Done` or `WIP`. Emphasis is ignored, so
+`**Superseded → FR-009**` reads the same as the bare form.
+
+An item is **never silently deleted** once another artifact references its ID. Supersession is
+recorded so a reference encountered elsewhere always resolves. An item dropped before anything
+references it may simply be removed.
+
+### Maturity — the state of the document
+
+Every chain artifact's header carries `**Maturity:** <value>`, one of exactly three:
+
+| Value | Meaning |
+|---|---|
+| `Draft` | Being written or revised; not yet offered for review |
+| `In review` | Offered for review; no reviewer has ruled on it yet |
+| `Approved` | A reviewer accepted it as it stands |
+
+The two vocabularies are **disjoint**: no value is a member of both, so no reader and no parser has
+to work out which one a value came from. `Maturity` describes the document as a whole; `Status`
+describes one indexed item inside it. A document can be `Approved` while an item inside it is
+`Superseded → <ref>`, and the two say different things.
+
+The former header form `**Status:** Draft` is gone. A header carrying `Status` is reading the item
+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
+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:
+
+- **An id is never renumbered once anything references it.** A deletion at least breaks loudly. A
+  renumber does not, because the reused id still resolves to a real item and every reference to it
+  now silently points at something else — often from another artifact, sometimes from another
+  repository's `plan.md`. When an item's content is replaced, the replacement takes a new id and the
+  old row becomes a tombstone. Ids are append-only.
+- **Moving or reshaping an item is not, on its own, a supersession.** Regrouping detail under new
+  headings, converting a bullet-form entry to §1's heading form, or relocating a section leaves what
+  the item says unchanged, so it records nothing here. Recording such a move as a supersession is as
+  damaging as omitting a real one: it fills the record with reversals that never happened. This does
+  not touch the move described at the top of this section: prose leaving a `**Detail**` block for
+  History *because* its item was superseded is that supersession's recorded consequence, not a case
+  of this rule. The test is always whether what the item says changed, never whether its text
+  moved.
+
+History is itself index-then-detail — a table so changes can be listed and compared, with detail
+below so the reasoning behind a reversal is not compressed into a cell:
+
+```markdown
+## 9. History
+
+| Date | ID | Change | Replaced by |
+|---|---|---|---|
+| 2026-07-29 | FR-001 | Field renamed during design | design §4.1 |
+
+**Detail**
+
+- **FR-001** — [what it said before, why it changed, what is true now].
+```
+
+A new artifact writes `None — initial version.` Every ID marked `Superseded` must appear here.
+
+**Revising an artifact updates its History.** An artifact revised after its initial write MUST
+record the revision here. `None — initial version.` MUST NOT remain once any indexed item has been
+added, changed or superseded — that line is a claim that the body has never moved, and leaving it
+in place after a revision makes the artifact's own account of itself false.
+
+A feature with a decision register compacts History mechanically; see §12.
+
+## 4. Diagrams
+
+> **Slot registry.** This section says which artifact carries which diagram slot. What belongs
+> *inside* a slot — the permitted Mermaid types, the per-type complexity budget, the label,
+> direction and `subgraph` conventions, the over-budget split rule, and the anti-patterns — is
+> governed by `DIAGRAM_GUIDE.md`, which the authoring skills load on demand.
+
+| Artifact | Section | Slot |
+|---|---|---|
+| `requirement.md` | §1 | Scope boundary `flowchart` |
+| `design.md` | §2 | Three C4 levels, each a `flowchart` with `subgraph` boundaries |
+| `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` |
+
+### Scope boundary — `requirement.md` §1
+
+A `flowchart` showing what is in scope, what is explicitly excluded, and what outcome each
+in-scope item produces, so the shape of the change is visible before the prose. Use
+`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 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
+heading, written `### C4 Level 1: System Context`, `### C4 Level 2: Container` and
+`### C4 Level 3: Component`.
+
+| Level | Shows | Required? |
+|---|---|---|
+| C4 Level 1 | Actors and external systems. One box per actor or external system — no internals | yes |
+| 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
+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
+excludes the `C4Context` / `C4Container` diagram types in favour of `flowchart`.
+
+### Task dependency graph — `plan.md` §8
+
+A `flowchart` showing the phases, the dependency order between tasks, and which tasks carry the
+`[P]` parallel marker, so execution order is visible before the checklist is read. The per-task
+`- [ ]` checklist stays the single source of truth for tasks and the diagram is never parsed as a
+second inventory of them — the same rule §5 states for the phase rollup. Write `N/A: [why]` for a
+plan too small to have meaningful ordering.
+
+## 5. plan.md — phase rollup
+
+§8 gains a phase-level summary above the checklists:
+
+```markdown
+### Task Summary
+
+| Phase | Tasks | Delivers | [P] |
+|---|---|---|---|
+| A | 2 | Verification layer | yes |
+```
+
+The heading is `### Task Summary`, not `### Phase Summary` — the latter collides with the
+`### Phase <X>` pattern the checker uses to find phase sections.
+
+**The per-task `- [ ]` checklist is the single source of truth for tasks and is never mirrored
+into a per-task index table.** Duplicating every task line would recreate exactly the
+hand-maintained-inventory drift this convention exists to prevent, in the one file where drift is
+most costly — and `/do-execute-plan` parses those markers as an execution contract, so their
+syntax must not change.
+
+Each rollup row's task count must match the `- [ ]` lines under its `### Phase <X>` heading.
+
+## 6. User Stories & Acceptance Criteria Conventions
+
+### User Story Hierarchy — `requirement.md` §2
+
+User Stories support hierarchical heading structures matching standard product backlog conventions:
+- Use `### Story X: [Story Title] (P#)` for top-level stories or `### Story X.Y: [Story Title] (P#)` for sub-stories.
+- Underneath each story heading, state the user requirement using standard role/want/benefit syntax:
+  `- **US1 (P1):** As a [role], I want [capability], so that [benefit].`
+
+### Behavioral Acceptance Criteria (BDD) — `requirement.md` §6
+
+Acceptance criteria are formatted as testable Gherkin BDD scenario blocks mapped to user story and functional requirement IDs:
+
+```markdown
+- [ ] **Scenario: [Scenario Title]** (US1, FR-001)
+  - **Given** [precondition or initial context]
+  - **When** [action or trigger event occurs]
+  - **Then** [expected observable outcome]
+```
+
+- **WHAT/WHY vs HOW Boundary:** `requirement.md` strictly describes user-facing behaviors and functional outcomes. Technical implementation anchors (such as database schemas, REST endpoints, repository patterns, and UX tokens) belong in `specs.md` §1 and `data-model.md`.
+
+## 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:
+- **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).
+
+This section routes *what* belongs in each of those two sections; the shape each one takes is
+governed by §10.
+
+## 8. Tables for comparison
+
+Where an artifact presents comparative or evidentiary data — several items measured on the same
+axes, a before/after contrast, a list of changes — lay it out as a table rather than prose or
+nested bullets, so items compare column-wise at a glance.
+
+## 9. What the checker does and does not do
+
+Run `"$DOFLOW" validate [--json] [--slug=<slug>] [<path>...]` after writing — the seam passes those
+flags through unchanged, and the helper behind the verb is not on `PATH` to be called by name. Exit `0` clean,
+`1` on findings, `0` plus a printed note when it cannot work out what to check (no active feature,
+resolver or `jq` unavailable).
+
+A file that was named explicitly but cannot be read or parsed is a **finding**, not a fail-open —
+it exits `1` and says the file was not checked. Silence there would report a clean result for a
+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).
+
+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
+matches no index row, so it neither satisfies a row nor reports an orphan of its own.
+
+Not checked: whether an index summary faithfully describes its detail, whether a diagram is
+accurate, whether a required section exists at all. It is a **consistency** checker, not a
+conformance checker — which is also why artifacts written before this convention, having no index
+tables, pass without needing a version marker.
+
+`audit.md` is never a target, explicit or resolved: like `state.md`, it sits outside this
+convention entirely (see this doc's intro), but for its own reason — it is generated fresh by
+`render-audit.sh` from the orchestrator's own journal on every run, never hand-authored, so there
+is no author-vs-index drift for this checker to ever catch.
+
+Findings are reported to the author and never repaired automatically: when an index and its detail
+disagree, deciding which one is wrong is authoring judgement, not a mechanical fix.
+
+## 10. Reviewer-facing sections
+
+> **Authoritative:** this section governs which reviewer-facing sections an artifact carries and
+> what shape each one takes, including the shape of `specs.md` §1 and `data-model.md` §1 that §7 routes content to.
+
+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`,
+  `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.
+- **`specs.md` §1 — families.** The index carries a `Family` column, and the detail beneath is
+  grouped under `#### Family: <name>` headings, with contracts ordered within a family and families
+  ordered as the index lists them. Each contract carries a `#### IC-###: <summary>` heading, which
+  is the heading detail-entry form of §1 and counts as that contract's detail entry because its ID
+  appears in the index.
+- **`data-model.md` §1 — a domain map, then bounded views.** The section opens with a conceptual domain
+  map: a Mermaid `flowchart` naming the entities and the relationships between them, with **no
+  attributes**, so the shape of the domain is legible before any field name. Beneath it comes one
+  `#### ER view: <subdomain>` per bounded subdomain, each a Mermaid `erDiagram` carrying the
+  attributes, keys and cardinalities of that subdomain alone. The table catalog of entities, keys,
+  indexes and ORM file references is unchanged and stays below the views. Splitting one diagram into
+  views must not drop an entity, a key or a constraint the single diagram carried.
+
+### The `N/A: [why]` escape
+
+Any of the three may be replaced by a line matching `^N/A: .+` stating why it does not apply — a
+feature too small to have decisions worth tabling, a specs document with one contract family, a
+domain with no persisted entity. A section left empty with no such line is a violation of this
+convention, because silence cannot be told apart from an oversight.
+
+This is the same escape §4 already uses for a skipped C4 level and for the scope-boundary
+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
+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.
+
+The labels are structural, not emphasis — `ARTIFACT_VOICE.md` carves them out of its rule against
+bold-labelled lists on exactly that ground. The entry still begins `- **<ID>:**` so §1's bullet form
+locates it; the labels sit in nested bullets beneath. No other artifact's detail entries take this
+shape.
+
+### Nothing checks this per artifact
+
+These are conventions the writing skill follows, not rules the checker runs. `validate-artifacts.sh`
+has no conformance rule family and gains none: §9's account of it is accurate as written, and an
+artifact missing a section named here produces no finding anywhere. The only mechanical enforcement
+lives in DoFlow's own repository, not in yours: a guard there covers the shipped templates and fails
+DoFlow's suite when a template
+loses a section. An artifact hand-edited away from its template is not covered, and knowing that is
+part of using the convention.
+
+## 11. Authoritative marking
+
+Where two sections could each be read as defining the same state, rule or outcome, the governing one
+carries, immediately beneath its heading, a blockquote naming what it governs:
+
+```markdown
+> **Authoritative:** this section governs [the state, rule or outcome].
+```
+
+The other section carries a one-line pointer naming the governing section and restates nothing —
+not a summary, not a "briefly". Restating is how the two drift apart, which is the failure the
+callout exists to prevent.
+
+Exactly one section may carry the callout for a given subject. Two callouts over the same subject
+is the same ambiguity in a new costume, and neither section then governs.
+
+## 12. Decision register citations
+
+> **Authoritative:** this section governs decision citations and compacted History.
+
+Applies only where the feature folder holds `decisions/register.json`; without one, nothing here
+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 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,
+  `Earlier entries: [decisions/history/<artifact>.md](<relative link>).`, the link relative to the
+  artifact's own directory, matching `^Earlier entries: \[decisions/history/[a-z-]+\.md\]`. Index
+  rows and tombstones stay.

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

@@ -0,0 +1,104 @@
+# Artifact Voice — prose rules for chain artifacts
+
+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.
+
+## 1. The rules
+
+Three minimums apply to every artifact before any category below. One bullet carries one claim, so a
+reader can accept or reject it on its own. A `**Detail**` entry is written in complete sentences,
+because a reviewer has to read it as an explanation. Bracket placeholders are filled in or deleted,
+never stacked where a sentence belongs.
+
+### Content patterns
+
+- **Inflated claims.** "Stands as", "a pivotal moment". State what the thing does.
+- **Name-dropping as proof.** Naming a company, paper or person to borrow weight. Say what they did
+  and why it bears on this, or drop the name.
+- **Shallow `-ing` phrases.** "Highlighting", "underscoring", "ensuring" tacked onto a clause to
+  make a plain fact sound deeper. Cut the phrase; the fact survives.
+- **Sales language.** "Boasts", "vibrant", "rich", "seamless", "robust". An artifact serves a maintainer, not a
+  buyer.
+- **Vague sourcing.** "Industry reports", "experts argue", "several sources". Name the source, or own
+  the claim.
+- **Formulaic "challenges and outlook" sections.** A closing block of abstract difficulties and
+  predictions. A real risk belongs in the risks index with a disposition.
+
+### Language and grammar
+
+- **Overused words.** actually, additionally, crucial, delve, enhance, fostering, highlight,
+  interplay, intricate, key, landscape, pivotal, showcase, tapestry, testament, underscore,
+  valuable, vibrant. Use a plainer word or none.
+- **Avoiding "is" and "are".** "Serves as", "stands as", "represents", "features" are almost always
+  a longer way to write "is". Write "is".
+- **"Not X but Y".** The construction spends a clause on something you are not claiming. Write Y.
+- **Forced groups of three.** Three items because three sounds complete. List what there is.
+- **Synonym cycling and repeated openings.** Calling one thing by three names costs the reader a
+  lookup each time; name it the same way every time. Three consecutive sentences opening on the same
+  word read as a template.
+- **False "from X to Y" ranges.** "From configuration to deployment" only works when X and Y are the
+  ends of a real span. Otherwise it is two examples wearing a range.
+- **Passive voice with a clear actor.** "The template is filled" hides who fills it. Name the actor
+  when there is one.
+
+### Filler and hedging
+
+- **Long forms of short words.** "In order to" is "to". "Due to the fact that" is "because".
+- **Stacked qualifiers.** "Could potentially possibly" hedges once and then twice more. Pick the one
+  qualifier that is true.
+- **Generic positive endings.** A closing sentence that praises what was just described adds nothing.
+- **Announcing the next point.** "Let's dive in", "first, some background". Make the point instead of introducing it.
+- **Fake candour.** "Honestly", "look", "here's the thing". These signal a confidence the sentence
+  has not earned.
+- **Objections nobody raised.** Answering a question nobody asked, or rejecting an alternative
+  nobody proposed, to look even-handed.
+- **Restating the heading.** A section whose first sentence repeats its own heading has spent a
+  sentence on nothing.
+- **Forced punchlines and dramatic fragments.** A one-line paragraph for effect.
+
+### Dead context
+
+- **A status section states what is true now.** Status lines, ledger summaries, blockers and next
+  actions are rewritten in place: when a fact stops being true, replace or delete it in the same
+  edit. No appended history and no "was", "previously" or "no longer" narrative; history lives in
+  `git log`, the decision register's superseded records and `plan.md`'s History.
+- **Resolved and finished things leave the page.** A cleared blocker, a finished phase's narration,
+  a rejected option nobody still needs and a note about a tool that has since changed are deleted,
+  not struck through or kept "for context".
+- **One home per fact.** A fact lives in one artifact; others cite it by id or path instead of
+  restating it. Copying a decision's text, a task's description or another file's list creates a
+  second version that goes stale.
+- **Hand-backs report results.** An agent's report holds outcomes, evidence locators, deviations and
+  open questions; it does not restate the brief, narrate steps or repeat what a command printed.
+
+### Style
+
+- **Sentence case headings**, not Title Case.
+- **No decorative emoji.**
+- **Straight quotes**, not typographic ones.
+- **Bold for a functional reason only**: a structural label the format defines, or a term being
+  defined.
+- **No em or en dashes.** A comma, a colon or a full stop does the work, except where §2 carves the
+  rule out.
+
+## 2. Carve-outs
+
+**Precedence:** a construct the checker parses governs over a prose rule that would rewrite it; a
+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. |
+| 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. |
+
+Everything a carve-out protects is the marked construct itself. The prose that follows it on the
+same line is free prose, and every rule in §1 applies there.
+
+Two constructs need no carve-out because no §1 rule reaches them; a prose pass still leaves them
+alone. The `- [ ]` task markers `do-execute-plan` parses carry no bold and
+no heading case; rewriting one breaks execution. The arrow in `Superseded → <ref>` is not a dash,
+but the checker matches it literally, so a prose pass that "tidies" it breaks it.

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

@@ -0,0 +1,47 @@
+# Base Constitution (tier-1)
+
+**Version:** 1.0.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.
+
+## Principles
+
+Each states the norm; the arrow points at the always-loaded rule that carries the detail.
+
+### 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`.
+
+### 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`.
+
+### 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`.
+
+### P4 — Scope discipline (YAGNI)
+Build only what the spec asks — no bonus features, no speculative abstraction.
+→ `rules/RULE_02_WORKFLOW.md`.
+
+### P5 — Parallel by default
+Independent work runs concurrently; sequential only for hard dependencies.
+→ `rules/RULE_02_WORKFLOW.md`.
+
+### 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`.
+
+## 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.