@khoavu882/doflow 2.0.0-beta.5 → 2.0.1

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

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

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

@@ -15,14 +15,15 @@
 
 ## 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.)
+> One row per principle of both constitution tiers; a tier-2 ID replaces the base one. `Tier` is the
+> constitution's (MUST unless it says SHOULD), `Result` is PASS or FAIL. A MUST marked FAIL, or a MUST
+> principle with no row, refuses the planning stage's exit; a SHOULD FAIL is advisory. Revise the
+> plan, or a person amends the constitution with `/do-constitution`; there is no waiver.
 
-- [ ] Complies with [PRINCIPLE]: [how]
-- [ ] No violation of [PRINCIPLE]: [how]
-
-**Result:** PASS / FAIL — [note]
+| Principle | Tier | Result | How |
+|---|---|---|---|
+| P1 | MUST | PASS | [how the plan complies] |
+| [ID] | [MUST/SHOULD] | [PASS/FAIL] | [how] |
 
 ## 3. Research & Decisions
 
@@ -126,12 +127,12 @@ flowchart LR
 
 ### 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]
+- [ ] A.1 [P] [US1] [task] — acceptance: [FR-/NFR-/IC- ids, comma-separated]; owner: [agent]; files: [paths]; depends-on: [service, optional]; external-contract: [doc path, optional]
+- [ ] A.2 [US1] [task, depends A.1] — acceptance: [FR-/NFR-/IC- ids, comma-separated]; 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]
+- [ ] B.1 [P] [US2] [task] — acceptance: [FR-/NFR-/IC- ids, comma-separated]; owner: [agent]; files: [paths]; depends-on: [service, optional]; external-contract: [doc path, optional]
 
 ### Checkpoints
 

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

@@ -4,12 +4,12 @@
 
 > 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
+> stage's question-tool 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
+> RULE_04 of `rules/RULES.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.
@@ -40,6 +40,18 @@
 
 **Answer:** [verbatim]
 
+## Coverage
+
+<!-- One line per requirement area as it stands after this round, each Clear, Partial, Missing or
+     Deferred (spec-kit clarify's coverage map). Missing or Partial areas are the next round's
+     questions, or the stated gaps when the loop stops; Deferred names who deferred it. -->
+- Problem and outcome: [Clear|Partial|Missing|Deferred]
+- Users and stories: [Clear|Partial|Missing|Deferred]
+- Functional scope: [Clear|Partial|Missing|Deferred]
+- Non-functional: [Clear|Partial|Missing|Deferred]
+- Out of scope: [Clear|Partial|Missing|Deferred]
+- Acceptance: [Clear|Partial|Missing|Deferred]
+
 <!-- Repeat one "## Question N" block per question actually asked this round — omit blocks for
      questions that were not asked rather than leaving placeholders behind.
 

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

@@ -5,7 +5,7 @@
 **Intent:** [agent-docs/intent/<name>.md, or "none"]
 
 > WHAT and WHY only — no tech or implementation detail. Zero unresolved clarification markers at
-> hand-off — every ambiguity is resolved via `AskUserQuestion` before this file is written;
+> hand-off — every ambiguity is resolved via the question tool before this file is written;
 > deferred answers become assumptions in §8.
 >
 > Structure follows `references/ARTIFACT_FORMAT.md`: indexed sections carry a table above full

package/core/shared/workflows/do-flow-chain.md

@@ -13,5 +13,7 @@ delivery sequence, pausing where human judgment matters:
 5. Execute `/do-execute-plan --scope next` repeatedly until the plan's checklist is complete.
 6. Run `/do-test`, then `/do-code-review`, and report both results before proposing any commit.
 
+Unattended (no person watching), stop at each pause above and report; silence is never approval.
+
 If the user comments directly inside any specification file, re-read it, apply the requested
 changes, and ask for approval again before moving on.

package/core/worker-evidence/antigravity/checks.json

@@ -0,0 +1,14 @@
+{
+  "schema": "doflow-worker-checks-v1",
+  "harness": "antigravity",
+  "binary": "agy",
+  "version": { "argv": ["--version"], "expect": "^\\d+\\.\\d+\\.\\d+" },
+  "checks": [
+    {
+      "id": "help-model",
+      "argv": ["--help"],
+      "expect": ["^\\s+--model\\s"],
+      "establishes": ["model"]
+    }
+  ]
+}

package/core/worker-evidence/codex/2026-10-18-cli-check.json

@@ -0,0 +1,107 @@
+{
+  "binary": "codex",
+  "checks": [
+    {
+      "argv": [
+        "exec",
+        "--help"
+      ],
+      "establishes": [
+        "runnableProbe",
+        "oneShot"
+      ],
+      "exit": 0,
+      "expect": [
+        "^Usage: codex exec \\[OPTIONS\\] \\[PROMPT\\]",
+        "instructions are read from stdin"
+      ],
+      "id": "exec-one-shot",
+      "matched": [
+        "Usage: codex exec [OPTIONS] [PROMPT]",
+        "          instructions are read from stdin. If stdin is piped and a prompt is also provided, stdin"
+      ],
+      "result": "pass"
+    },
+    {
+      "argv": [
+        "exec",
+        "--help"
+      ],
+      "establishes": [
+        "structuredOutput"
+      ],
+      "exit": 0,
+      "expect": [
+        "^\\s+--json$",
+        "Print events to stdout as JSONL",
+        "-o, --output-last-message"
+      ],
+      "id": "exec-json",
+      "matched": [
+        "      --json",
+        "          Print events to stdout as JSONL",
+        "  -o, --output-last-message <FILE>"
+      ],
+      "result": "pass"
+    },
+    {
+      "argv": [
+        "exec",
+        "--help"
+      ],
+      "establishes": [
+        "readOnly",
+        "isolatedEdit"
+      ],
+      "exit": 0,
+      "expect": [
+        "-s, --sandbox <SANDBOX_MODE>",
+        "read-only, workspace-write"
+      ],
+      "id": "exec-sandbox",
+      "matched": [
+        "  -s, --sandbox <SANDBOX_MODE>",
+        "          [possible values: read-only, workspace-write, danger-full-access]"
+      ],
+      "result": "pass"
+    },
+    {
+      "argv": [
+        "features",
+        "list",
+        "--disable",
+        "multi_agent",
+        "--disable",
+        "multi_agent_v2"
+      ],
+      "establishes": [
+        "spawnDenial"
+      ],
+      "exit": 0,
+      "expect": [
+        "^multi_agent\\s+\\S+\\s+false$",
+        "^multi_agent_v2\\s+\\S+\\s+false$"
+      ],
+      "id": "spawn-denial",
+      "matched": [
+        "multi_agent                              stable             false",
+        "multi_agent_v2                           stable             false"
+      ],
+      "result": "pass"
+    }
+  ],
+  "cliVersion": "codex-cli 0.163.0",
+  "establishes": [
+    "isolatedEdit",
+    "oneShot",
+    "readOnly",
+    "runnableProbe",
+    "spawnDenial",
+    "structuredOutput"
+  ],
+  "harness": "codex",
+  "kind": "cli-check",
+  "recordedAt": "2026-10-18T01:08:16.330Z",
+  "run": null,
+  "schema": "doflow-worker-evidence-v1"
+}

package/core/worker-evidence/codex/2026-10-18-live-run-edit.json

@@ -0,0 +1,73 @@
+{
+  "binary": "codex",
+  "checks": [],
+  "cliVersion": "codex-cli 0.163.0",
+  "establishes": [
+    "oneShot",
+    "structuredOutput",
+    "spawnDenial",
+    "isolatedEdit"
+  ],
+  "harness": "codex",
+  "kind": "live-run",
+  "recordedAt": "2026-10-18T03:36:27.965Z",
+  "run": {
+    "argvShape": [
+      "exec",
+      "-s",
+      "workspace-write",
+      "--disable",
+      "multi_agent",
+      "--disable",
+      "multi_agent_v2",
+      "--json",
+      "-o",
+      "<last-message-file>",
+      "--ephemeral",
+      "-"
+    ],
+    "edit": true,
+    "exit": 0,
+    "isolation": {
+      "attemptHead": {
+        "after": {
+          "object": "28bffdd57fb3d737fea5e478dfdc6a40b5d7ad6a",
+          "ref": "refs/heads/doflow-attempt/109-d1-edit/d-009378735f3b"
+        },
+        "before": {
+          "object": "28bffdd57fb3d737fea5e478dfdc6a40b5d7ad6a",
+          "ref": "refs/heads/doflow-attempt/109-d1-edit/d-009378735f3b"
+        }
+      },
+      "callerHead": {
+        "after": {
+          "object": "28bffdd57fb3d737fea5e478dfdc6a40b5d7ad6a",
+          "ref": "refs/heads/main"
+        },
+        "before": {
+          "object": "28bffdd57fb3d737fea5e478dfdc6a40b5d7ad6a",
+          "ref": "refs/heads/main"
+        }
+      },
+      "changes": [],
+      "reason": null,
+      "refsChanged": false,
+      "status": "clean"
+    },
+    "parser": "codex-exec-json-v1",
+    "readOnly": null,
+    "report": {
+      "deniedCount": 0,
+      "reason": null,
+      "status": "success",
+      "usage": {
+        "tokens": 181978
+      }
+    },
+    "resultOffered": true,
+    "runId": "w-821933d703be",
+    "stdoutBytes": 5891,
+    "withheld": []
+  },
+  "schema": "doflow-worker-evidence-v1"
+}

package/core/worker-evidence/codex/2026-10-18-live-run-read-only.json

@@ -0,0 +1,62 @@
+{
+  "binary": "codex",
+  "checks": [],
+  "cliVersion": "codex-cli 0.163.0",
+  "establishes": [
+    "oneShot",
+    "structuredOutput",
+    "spawnDenial",
+    "readOnly"
+  ],
+  "harness": "codex",
+  "kind": "live-run",
+  "recordedAt": "2026-10-18T03:35:53.729Z",
+  "run": {
+    "argvShape": [
+      "exec",
+      "-s",
+      "read-only",
+      "--disable",
+      "multi_agent",
+      "--disable",
+      "multi_agent_v2",
+      "--json",
+      "-o",
+      "<last-message-file>",
+      "--ephemeral",
+      "-"
+    ],
+    "edit": false,
+    "exit": 0,
+    "isolation": null,
+    "parser": "codex-exec-json-v1",
+    "readOnly": {
+      "changes": [],
+      "head": {
+        "after": {
+          "object": "28bffdd57fb3d737fea5e478dfdc6a40b5d7ad6a",
+          "ref": "refs/heads/d1-read-only"
+        },
+        "before": {
+          "object": "28bffdd57fb3d737fea5e478dfdc6a40b5d7ad6a",
+          "ref": "refs/heads/d1-read-only"
+        }
+      },
+      "refsChanged": false,
+      "status": "clean"
+    },
+    "report": {
+      "deniedCount": 0,
+      "reason": null,
+      "status": "success",
+      "usage": {
+        "tokens": 63066
+      }
+    },
+    "resultOffered": true,
+    "runId": "w-067a85a5cc2d",
+    "stdoutBytes": 2203,
+    "withheld": []
+  },
+  "schema": "doflow-worker-evidence-v1"
+}