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

package/core/shared/templates/doflow/data-model-template.md

@@ -0,0 +1,169 @@
+# Data Model: [FEATURE NAME]
+
+**Feature:** [NNN-slug] · **Design:** ./design.md · **Maturity:** Draft · **Created:** [DATE]
+
+> Entity/data model and data-flow diagrams a design decided, split out of design.md's own narrative
+> (§5/§6) and specs.md's interface-contract detail (§1). Reads ./design.md; distinct from ./specs.md
+> the way a persisted shape and the flows that move through it are distinct from the contracts that
+> expose them.
+>
+> Structure follows `references/ARTIFACT_FORMAT.md`: the document-level `Maturity` is `Draft`,
+> `In review` or `Approved`. Neither §1 nor §2 below carries an `ID`-bearing index — a diagram is not
+> a normative, citable statement — so both stay free-form; §3 History is index-then-detail like
+> every other chain artifact's final section, and its item-level `Status` is only `Live` or
+> `Superseded → <ref>`.
+
+## 1. Data Model
+
+<!-- Free-form, NOT part of the indexed convention above — diagrams and schema tables are not
+     ID-bearing normative statements, so this section stays exactly as specs-template.md's former
+     §2 already was.
+
+     The model is presented in two tiers. The conceptual domain map comes first and carries no
+     attributes, so the shape of the domain is legible before any field name. One ER view per
+     bounded subdomain follows, each carrying the attributes, keys and cardinalities of that
+     subdomain alone. Splitting one diagram into views must not drop an entity, a key or a
+     constraint the single diagram carried. -->
+
+### Conceptual domain map
+
+<!-- The entities and the relationships between them, with no attributes. Skip with "N/A: [why]" if
+     the feature persists no entity. -->
+
+```mermaid
+flowchart LR
+    USER["User"]
+    POST["Post"]
+    COMMENT["Comment"]
+
+    USER -->|"creates"| POST
+    POST -->|"contains"| COMMENT
+```
+
+#### ER view: [subdomain]
+
+<!-- One heading of this form per bounded subdomain, each an erDiagram carrying the attributes,
+     keys and cardinalities of that subdomain alone. Skip with "N/A: [why]" if the feature persists
+     no entity. -->
+
+```mermaid
+erDiagram
+    USER ||--o{ POST : "creates"
+    USER {
+        uuid id PK
+        string email UK
+        string name
+        timestamp created_at
+    }
+    POST ||--o{ COMMENT : "contains"
+    POST {
+        uuid id PK
+        uuid user_id FK
+        string title
+        text content
+        timestamp created_at
+    }
+    COMMENT {
+        uuid id PK
+        uuid post_id FK
+        uuid author_id FK
+        text body
+        timestamp created_at
+    }
+```
+
+### Database Schemas (ORM / DDL)
+
+<!-- The catalog of every table the views above draw, with its keys, indexes and ORM file. -->
+
+| Table | Purpose | Primary Key | Foreign Keys & Relations | Key Indexes | Schema / ORM File |
+|---|---|---|---|---|---|
+| `[table_name]` | [one-line table responsibility] | `id` (UUID) | `[user_id]` → `users(id)` | `idx_[table]_[col]` | `src/db/schema/[table].ts` |
+
+### UX / UI Specifications
+- **Design Tokens & Cues:** [color tokens (e.g. Indigo for Work, Emerald for Personal), badge variants, typography]
+- **Component States:** [loading, empty, populated, error states]
+
+## 2. Sequence / Data Flow
+
+<!-- Free-form, NOT part of the indexed convention — a diagram is not an ID-bearing normative
+     statement, so this section stays free-form exactly as §1 does.
+
+     One `sequenceDiagram` per non-trivial interaction the feature introduces. Scaffolding matches
+     §1's depth deliberately: this is the chain's most-used diagram type, not an afterthought.
+
+     `references/DIAGRAM_GUIDE.md` governs the lifeline ceiling. There is no message ceiling,
+     because a sequence diagram lays out columnwise and cannot tangle however many messages it
+     carries — so show the whole interaction rather than trimming it to look tidy.
+
+     Conventions:
+       - Declare every participant up front, in the order they first act, so the columns read
+         left-to-right in causal order.
+       - Use `actor` for a human or an external caller and `participant` for a component.
+       - `->>` is a call, `-->>` is a return. Keep returns only where the returned value matters.
+       - Put the failure path in an `alt` block. An interaction drawn only on its happy path hides
+         the branch a reader most needs.
+       - `Note over X,Y:` carries a constraint or an invariant, never narration of the line above.
+       - Prefer `rect` over `par` to mark a region: `par` claims the steps happen simultaneously,
+         which most groupings cannot support. Reserve `par` for genuine parallelism, `alt` for a
+         branch.
+
+     Skip with "N/A: [why]" if the feature introduces no non-trivial interaction. -->
+
+### [Interaction name]
+
+[One sentence: what triggers this flow and what it ends with.]
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant API as [entry point]
+    participant SVC as [service]
+    participant DB as [data store]
+
+    User->>API: [request]
+    API->>SVC: [call]
+
+    alt [failure condition]
+        SVC-->>API: [error shape]
+        API-->>User: [status code and message]
+    else [success]
+        SVC->>DB: [read or write]
+        DB-->>SVC: [result]
+        SVC-->>API: [payload]
+        API-->>User: [status code]
+    end
+
+    Note over SVC,DB: [invariant that must hold across this step]
+```
+
+[If the failure branch has consequences the diagram cannot carry — a retry policy, a compensating
+action, an idempotency requirement — state them in a sentence beneath the diagram rather than
+crowding the fence.]
+
+### Flow: [name]
+
+<!-- One "#### Flow: <name>" heading per end-to-end flow, each embedding its committed render from
+     design/c4/flow-<name>.png. The heading name matches its source file's stem, which is the only
+     index -- nothing maintains a manifest, because a manifest could disagree with the directory.
+
+     This slot carries NO inline text diagram, and that asymmetry is forced by grammar rather than
+     chosen: Mermaid has no lane primitive, and approximating lanes with subgraph grouping would
+     carry no lane semantics and so would misrepresent the diagram it stood in for. The authored
+     .puml remains readable text under review, so the flow's logic is still diffable.
+
+     `references/DIAGRAM_GUIDE.md` §6 governs the lane conventions. Skip with "N/A: [why]" when the
+     feature's flow involves a single actor. -->
+
+![End-to-end flow: [name]](design/c4/flow-[name].png)
+
+[One sentence: what triggers this flow and what it ends with. Any consequence the lanes cannot
+carry — a retry policy, a compensating action, an idempotency requirement — belongs here rather
+than crowded into the diagram.]
+
+## 3. History
+
+<!-- Superseded data-model entries move here; the index row above stays as a tombstone with
+     `Superseded → <ref>`. -->
+
+None — initial version.

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

@@ -0,0 +1,193 @@
+# Design: [FEATURE NAME]
+
+**Feature:** [NNN-slug] · **Requirement:** [REQUIREMENT_PATH] · **Maturity:** Draft · **Created:** [DATE]
+
+> System shape — architecture, APIs, data/interface contracts. Reads [REQUIREMENT_PATH].
+> Distinct from plan.md's HOW-to-implement; this is HOW-it's-shaped.
+>
+> Structure follows `references/ARTIFACT_FORMAT.md`: indexed sections carry a table above full
+> `**Detail**`, the document-level `Maturity` is `Draft`, `In review` or `Approved`, the item-level
+> `Status` is only `Live` or `Superseded → <ref>`, and superseded prose moves to §9.
+
+## 1. Architecture Approach
+
+**Decisions and blockers:**
+
+<!-- One row per decision this design makes, placed above the architectural prose. "Decision" names
+     what is being settled. "Shape chosen" is the answer this design gives it. "Owner" is the person
+     or role accountable for that answer. "Blocks approval?" says whether a reviewer can approve the
+     design while this decision stands as written, and names what has to happen first when it cannot.
+     A reviewer who reads only this table knows what is being decided, who decided it, and what
+     stands between the design and approval. Replace the table with "N/A: [why]" when the feature is
+     too small to carry decisions worth tabling. With a decision register, end Shape chosen with its
+     DEC-###: see ARTIFACT_FORMAT.md §12. -->
+
+| Decision | Shape chosen | Owner | Blocks approval? |
+|---|---|---|---|
+| [what is being settled] | [the shape this design gives it] | [person or role accountable] | no |
+| [what is being settled] | [the shape this design gives it] | [person or role accountable] | yes: [what must happen first] |
+
+[Component boundaries, where this fits in the existing system, 2–4 sentences.]
+
+## 2. System Overview (C4)
+
+<!-- The visual complement to §1 — lets a reader unfamiliar with this feature see the shape before
+     reading prose. C4 is kept as the conceptual zoom model (Context → Container → Component) and
+     rendered with Mermaid `flowchart` + `subgraph`. Each level heading is written
+     "C4 Level N: ...", so no level label collides with a §3 component ID such as C3.
+
+     Do NOT use the C4Context / C4Container diagram types. They are experimental in Mermaid: no
+     direction control, relationship labels collide with arrowheads, and rendering varies across
+     viewers. `flowchart` is the most widely supported type and puts labels legibly on the arrow.
+
+     Skip a level with "N/A: [why]". For a trivial single-file change with no new external
+     interaction, write "N/A: [why]" for the whole section. -->
+
+<!-- C4 Level 2 below sits inside the generated-block markers `doflow-run render-puml` replaces.
+     When this feature authors its C4 in PlantUML under design/c4/, edit container.puml and re-run
+     the verb; editing between the markers by hand is a change the next render discards.
+
+     A feature that authors no PlantUML writes the Mermaid here by hand, as it always did. The
+     markers are inert in that case — with no design/c4/ directory the verb reports and exits
+     before it opens this file — so leave them or delete them, whichever reads better.
+
+     The markers delimit LEVEL 2 ONLY. The projector emits one block per run, from container.puml
+     when it exists and context.puml otherwise, so a second marker pair would have nothing to fill.
+     Levels 1 and 3 are hand-written at every level of PlantUML adoption. -->
+
+### C4 Level 1: System Context
+
+[Who/what uses this system, and which external systems it talks to. One box per actor or external
+system — internal components belong at C4 Level 2 or C4 Level 3, not here.]
+
+```mermaid
+flowchart TB
+    subgraph actors["Actors"]
+        USER["[actor/user]<br/>(who initiates this)"]
+    end
+    subgraph system["[this system]"]
+        SVC["[one-line responsibility]"]
+    end
+    EXT["[external system]<br/>(what it provides or consumes)"]
+
+    USER -->|"[interaction, e.g. Uses]"| SVC
+    SVC -->|"[interaction, e.g. Calls]"| EXT
+    SVC -.->|"[secondary/async relation]"| EXT
+```
+
+### C4 Level 2: Container
+
+[Which deployable services/apps/data stores this feature spans, and how they talk. One box per
+independently deployable unit — internals of a single container belong at C4 Level 3.]
+
+<!-- generated from design/c4/container.puml by `doflow-run render-puml` -- do not edit by hand
+     source-hash: not-yet-rendered -->
+```mermaid
+flowchart LR
+    USER["[actor/user]"]
+    subgraph boundary["[system name]"]
+        APP["[container name]<br/>[tech stack]"]
+        DB[("[data store]<br/>[what it holds]")]
+    end
+    EXT["[external system]"]
+
+    USER -->|"[protocol, e.g. HTTPS/JSON]"| APP
+    APP -->|"[reads/writes]"| DB
+    APP -->|"[interaction]"| EXT
+```
+<!-- end generated -->
+
+### C4 Level 3: Component
+
+<!-- Required when this feature touches 3+ components within a single container; otherwise write
+     "N/A: covered by §3 Components & Boundaries". On a small change this diagram restates the §3
+     table verbatim, and a diagram that adds nothing trains authors to tick boxes. -->
+
+[Internals of the container this feature changes — handlers, services, ports, adapters.]
+
+```mermaid
+flowchart TB
+    subgraph container["[container name]"]
+        C_A["[component]<br/>[responsibility]"]
+        C_B["[component]<br/>[responsibility]"]
+    end
+    STORE[("[data store]")]
+
+    C_A -->|"[call]"| C_B
+    C_B -->|"[persists]"| STORE
+```
+
+## 3. Components & Boundaries
+
+| ID | Component | Kind | Serves | Status |
+|---|---|---|---|---|
+| C1 | [component name] | service / script / template / reference | FR-001 | Live |
+
+**Detail**
+
+<!-- A component entry names the component after its ID, then answers the four labels below in
+     order. The labels are structural, not emphasis, and none may be dropped or reordered. -->
+
+- **C1:** [component name]
+  - **Responsibility:** [what this component is answerable for, in full].
+  - **Owns:** [the state, files or decisions it holds].
+  - **Does not own:** [what a reader could expect it to hold but another component does].
+  - **Contracts:** [the FR-### and IC-### identifiers it serves].
+
+## 4. API / Interface Contracts
+
+<!-- Endpoints, CLI verb signatures, and repository/service interfaces that anchor implementation
+     live in ./specs.md §1 Interface Contracts, not here — each as one ID-bearing IC-### entry so
+     plan.md and implementation can cite a contract by id instead of a paragraph. Write `N/A: [why]` if
+     this feature genuinely introduces no interface contracts; otherwise leave a one-line pointer,
+     e.g. "See ./specs.md §1." -->
+
+## 5. Data Model
+
+The data-model shape is governed by `./data-model.md` §1.
+
+<!-- Data model diagrams (ER diagrams, table schema catalogs) and UX design tokens live in
+     ./data-model.md §1 Data Model, not here. Write `N/A: [why]` if this feature introduces no data
+     model or UX changes; otherwise leave a one-line pointer, e.g. "See ./data-model.md §1." -->
+
+## 6. Sequence / Data Flow
+
+The data-flow shape is governed by `./data-model.md` §2.
+
+<!-- Sequence diagrams showing key interaction flows (a `sequenceDiagram` works well here) live in
+     ./data-model.md §2 Sequence / Data Flow, not here. Write `N/A: [why]` if this feature introduces
+     no non-trivial interaction sequence; otherwise leave a one-line pointer, e.g.
+     "See ./data-model.md §2." -->
+
+## 7. Design Risks & Alternatives Considered
+
+| ID | Risk / Alternative | Disposition | Status |
+|---|---|---|---|
+| R1 | [risk, or an alternative shape considered] | mitigated / accepted / rejected | Live |
+
+**Detail**
+
+- **R1** → [why this shape was chosen, or why the risk is accepted and what it costs if it lands].
+
+## 8. Assumptions
+
+<!-- With a decision register, a row from a "Decide for me" pick cites its DEC-### in Basis: see ARTIFACT_FORMAT.md §12. -->
+
+| ID | Assumption | Affects | Basis |
+|---|---|---|---|
+| A1 | [assumption stated] | C1 | [why this default, or "user deferred"] |
+
+**Detail**
+
+- **A1** — [the reasoning, and what would change if it turns out wrong].
+
+<!-- Write "None — no design-level clarification questions were deferred." in place of the table
+     and detail if every design-level ambiguity was resolved by a direct answer rather than the
+     defer escape hatch during /do-design's clarification loop. -->
+
+## 9. History
+
+<!-- Superseded design decisions move here; the index row above stays as a tombstone with
+     `Superseded → <ref>`. -->
+
+None — initial version.

package/core/shared/templates/doflow/external-contract-template.md

@@ -0,0 +1,35 @@
+# [Vendor/Service Name] Contract
+
+> An `external-contract:` target for `/do-execute-plan --scaffold`. Points a `plan.md` task's
+> `depends-on:` value (a genuine external dependency with no local repo — a vendor API, a SaaS
+> integration) at this doc instead of leaving it silently skipped. `## Methods` and `## Types` are required — a doc missing either fails
+> the compliance check with an explicit warning, not a silent skip. `## Webhook` is optional; omit
+> the whole section if this dependency never pushes data back. Grammar inside every section is
+> identical to the generic-pseudocode fallback notation in
+> `skills/do-execute-plan/scaffold.md` — one notation for both, nothing new to learn.
+>
+> The generated frame lands in `agent-docs/doflow/<slug>/scaffold/contracts/<service>/`, alongside
+> the rest of that run's scaffold rather than in a `contracts/` directory of its own.
+
+## Methods
+
+```text
+interface [Vendor]Client {
+  [method1]([param1]: [Param1Type], [param2]: [Param2Type]): [Return1Type]
+  [method2]([param1]: [Param1Type]): [Return2Type]
+}
+```
+
+## Types
+
+```text
+type [Name] = { [field1]: [type1], [field2]: [type2] }
+```
+
+## Webhook
+
+[Optional — delete this section entirely if this dependency never calls back into your system.]
+
+```text
+type [Name] = { [field1]: [type1], [field2]: [type2] }
+```

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

@@ -0,0 +1,45 @@
+# Intent: [SHORT TITLE]
+
+**Raised by:** [NAME OR ROLE] · **Date:** [DATE]
+
+> An intent is written **before** any branch, feature directory or slug exists, and needs no command
+> to create: copy this file to `agent-docs/intent/<kebab-description>.md` and fill it in. It is not a
+> chain artifact — it carries no `Maturity` and no `Status`, because nothing has been decided yet.
+>
+> Write it in your own terms. Architecture, interfaces, file paths and task breakdowns are all
+> deliberately absent: an intent records a problem worth someone's attention, not a plan for solving
+> it. If it is picked up, `/do-brainstorm --intent <path>` reads it and turns it into a
+> `requirement.md`, which is where decisions start being made.
+>
+> An intent that is never built is a success of this format, not a failure of it. That is why intents
+> are not numbered: a number would claim a place in a queue that nobody has promised.
+
+## 1. Problem
+
+[What is wrong, missing or painful today, in your own words. Describe the situation, not a solution —
+if a sentence here contains the word "add" or names a mechanism, it probably belongs in §2 or nowhere
+yet.]
+
+## 2. Proposed outcome
+
+[What would be observably different if this were addressed? State it as something a person could
+notice or check, rather than as the thing to build. "Reviewers stop missing X" rather than "add a
+check for X".]
+
+## 3. Affected
+
+[Who and what this touches: the people who feel the problem, the systems involved, the existing
+behaviour that would change. Name them even where you are unsure — a guess marked as one is more
+useful than an omission.]
+
+## 4. Constraints
+
+[What already bounds this: deadlines, policies, contracts, systems that cannot change, decisions
+already taken elsewhere. Write "none known" rather than leaving it blank, so a reader can tell the
+difference between no constraints and no thought about them.]
+
+## 5. Open questions
+
+[What you do not know. List them rather than guessing — discovery treats these as the ambiguities it
+must resolve, so an honest question here is more valuable than a confident answer that turns out to be
+wrong.]

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

@@ -0,0 +1,151 @@
+# Implementation Plan: [FEATURE NAME]
+
+**Feature:** [NNN-slug] · **Requirement:** [REQUIREMENT_PATH] · **Design:** [DESIGN_PATH] · **Maturity:** Draft · **Created:** [DATE]
+
+> HOW. Reads [REQUIREMENT_PATH] and [DESIGN_PATH]. Resolve every `[NEEDS CLARIFICATION]` from the
+> requirement here.
+>
+> Structure follows `references/ARTIFACT_FORMAT.md`: indexed sections carry a table above full
+> `**Detail**`, the document-level `Maturity` is `Draft`, `In review` or `Approved`, the item-level
+> `Status` is only `Live` or `Superseded → <ref>`, and superseded prose moves to §9.
+
+## 1. Approach
+
+[Chosen approach in 2–4 sentences; the key technical decisions.]
+
+## 2. Constitution Check (GATE)
+
+> Verify against both constitution tiers, tier-2 taking precedence — you reconcile them yourself;
+> nothing merges them for you. Any violation = STOP and revise the approach before continuing.
+> (Advisory by default; not the hard hook gate.)
+
+- [ ] Complies with [PRINCIPLE]: [how]
+- [ ] No violation of [PRINCIPLE]: [how]
+
+**Result:** PASS / FAIL — [note]
+
+## 3. Research & Decisions
+
+<!-- D# only without a decision register; with one, list DEC-### instead (ARTIFACT_FORMAT.md §12). -->
+- **D1:** [decision] — resolves [NEEDS CLARIFICATION: …]; rationale: [evidence].
+
+## 4. Components & Changes
+
+| ID | Change | Files | Phase | Status |
+|---|---|---|---|---|
+| CH1 | [one-line summary] | [path] | A | Live |
+
+**Detail**
+
+- **CH1** → [what changes and why, in full].
+
+## 5. Data / Contracts
+
+[schema, API, or interface pointers — or `N/A: [why]`.]
+
+## 6. Risks & Mitigations
+
+| ID | Risk | Mitigation | Status |
+|---|---|---|---|
+| RK1 | [risk] | [mitigation] | Live |
+
+**Detail**
+
+- **RK1** → [how it would actually manifest, and what the mitigation does or does not cover].
+
+## 7. Validation Strategy
+
+| Requirement | Verified by |
+|---|---|
+| FR-001 | [test, manual check, or gate] |
+
+## 8. Tasks
+
+> Dependency-ordered. `[P]` = parallel-safe with its phase siblings — siblings marked `[P]` must
+> write disjoint `files:`, or they are not parallel-safe. `[US#]` = traces to a
+> user story in requirement.md. The `- [ ]` checkboxes are the execution contract parsed by
+> `/do-execute-plan` — keep the markers intact. `depends-on:` is optional — set it when a task
+> depends on an external service that has no owning task in this same plan (not a service also
+> touched by another task here); `/do-execute-plan --scaffold` reads it to know which services
+> need a code frame generated. `external-contract:` is also optional — set it alongside `depends-on:`
+> only when that dependency has no local repo (a vendor API, a SaaS integration) but *does* have a
+> documented contract; points to a doc built from `templates/doflow/external-contract-template.md`, and
+> tells `--scaffold` to generate a real frame from it instead of silently skipping a non-local
+> dependency (the default when no `external-contract:` is set — not every dependency needs one).
+
+### Repo Branch Plan
+
+> Populate when this plan spans 2+ repos (a container workspace, not a monorepo) — derive `Repo`
+> from each task's `files:` path *and* each task's `depends-on:` value the same way, by walking up
+> to the nearest enclosing `.git` (a `depends-on:` value that resolves to no `.git` is skipped, not
+> guessed); derive `Planned Branch` from `requirement.md`'s `**Ticket:**`
+> field + this feature's slug (`feat/<TICKET>-<slug-description>`, or `feat/<slug>` if no ticket is
+> recorded); `Role` is `primary` (owns a task here) or `dependency-only` (referenced only via
+> `depends-on:`). For a single-repo plan, write "N/A: single-repo feature" instead of the table.
+
+| Repo | Planned Branch | Role |
+|---|---|---|
+| [repo path] | `feat/[branch]` | primary |
+
+### Task Summary
+
+<!-- Phase-level orientation only. The per-task checklist below stays the single source of truth
+     for tasks and is never mirrored into a per-task index table — duplicating every task line is
+     the drift this structure exists to prevent, in the file where drift costs most.
+
+     The heading is "Task Summary", not "Phase Summary": the latter collides with the
+     "### Phase <X>" pattern used to find phase sections. Each row's task count must match the
+     `- [ ]` lines under its phase heading. -->
+
+| Phase | Tasks | Delivers | [P] |
+|---|---|---|---|
+| A | 2 | [what this phase produces] | yes |
+| B | 1 | [what this phase produces] | no |
+
+### Dependency Graph
+
+<!-- Phases, the dependency order between tasks, and which tasks carry `[P]`. Orientation only:
+     the per-task `- [ ]` checklist below stays the single source of truth and this diagram is
+     never a second inventory of it. `references/DIAGRAM_GUIDE.md` governs the node and edge
+     ceilings and the direction convention; write "N/A: [why]" for a plan too small to have
+     meaningful ordering. -->
+
+```mermaid
+flowchart LR
+    subgraph PA["Phase A — [name]"]
+        A1["A.1 [P]<br/>[task]"]
+        A2["A.2<br/>[task]"]
+    end
+    subgraph PB["Phase B — [name]"]
+        B1["B.1 [P]<br/>[task]"]
+    end
+
+    A1 -->|"blocks"| A2
+    A2 --> PB
+```
+
+### Phase A — [name]
+
+- [ ] A.1 [P] [US1] [task] — owner: [agent]; files: [paths]; depends-on: [service, optional]; external-contract: [doc path, optional]
+- [ ] A.2 [US1] [task, depends A.1] — owner: [agent]; files: [paths]; depends-on: [service, optional]; external-contract: [doc path, optional]
+
+### Phase B — [name]
+
+- [ ] B.1 [P] [US2] [task] — owner: [agent]; files: [paths]; depends-on: [service, optional]; external-contract: [doc path, optional]
+
+### Checkpoints
+
+- After Phase A: [validation step]; commit `[message]`
+
+### Completion criteria
+
+- [ ] All tasks checked
+- [ ] Validation gates pass
+- [ ] state.md updated
+
+## 9. History
+
+<!-- Superseded decisions or tasks move here; the index row above stays as a tombstone with
+     `Superseded → <ref>`. -->
+
+None — initial version.

package/core/shared/templates/doflow/question-log-template.md

@@ -0,0 +1,51 @@
+# [Stage] Dialogue — Round [N]
+
+**Feature:** [NNN-slug] · **Stage:** [intention|design|plan] · **Round:** [N]
+
+> The one recurring shape every `intention/*-question.md`, `design/*-question.md` and
+> `plan/*-question.md` file uses: the Socratic dialogue transcript for a single round of a chain
+> stage's `AskUserQuestion` loop. This is a dialogue transcript, not an ID-bearing normative
+> artifact — out of `references/ARTIFACT_FORMAT.md`'s index/detail scope, the same way that
+> reference's own intro already carves out `state.md`.
+>
+> Not to be confused with the differently-named `{stage}-questions.md` convention in
+> `rules/RULE_04_QUESTIONS.md`: that file is a *request for input*, written for a
+> non-interactive harness and awaiting a `[Answer]:` tag before the run can continue. This one is
+> the opposite direction — a completed *record* of a round that already happened, filed after the
+> user answered, never awaiting anything.
+
+## Question 1 — [question text as asked]
+
+**Options offered:**
+- [option A]
+- [option B]
+- [option C]
+- Other (free text)
+
+**Answer:** [the option the user picked, or their free-text answer, verbatim]
+
+<!-- If the user picked "Decide for me" (or the harness's equivalent defer choice) instead of a
+     normal option, do NOT record it under "Answer" as if it were one. Record it as:
+
+     **Resolved via:** recorded assumption — [one-line rationale for the default taken]
+
+     matching how requirement-template.md §8 Assumptions already documents a deferred answer: the
+     rationale that was written down, not the fact that the user declined to choose. -->
+
+## Question 2 — [question text as asked]
+
+**Options offered:**
+- [option A]
+- [option B]
+
+**Answer:** [verbatim]
+
+<!-- Repeat one "## Question N" block per question actually asked this round — omit blocks for
+     questions that were not asked rather than leaving placeholders behind.
+
+     Naming: one file per Socratic round, numbered `<stage-prefix>-NN-question.md`, zero-padded to
+     two digits:
+       - intention/brainstorm-01-question.md, intention/brainstorm-02-question.md, ...
+       - design/design-01-question.md, design/design-02-question.md, ...
+       - plan/plan-01-question.md, plan/plan-02-question.md, ...
+     A new round is always a new file — never appended to a prior round's file. -->