@draht/coding-agent 2026.7.7 → 2026.7.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +27 -0
- package/README.md +2 -2
- package/agents/advisor.md +44 -0
- package/bin/draht-tools.cjs +1808 -988
- package/dist/agents/advisor.md +44 -0
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +1 -1
- package/dist/cli/args.js.map +1 -1
- package/dist/core/agent-session.d.ts +16 -3
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +76 -18
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/cache-stats.d.ts +49 -0
- package/dist/core/cache-stats.d.ts.map +1 -0
- package/dist/core/cache-stats.js +101 -0
- package/dist/core/cache-stats.js.map +1 -0
- package/dist/core/compaction/compaction.d.ts +1 -2
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +51 -73
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/extensions/index.d.ts +1 -1
- package/dist/core/extensions/index.d.ts.map +1 -1
- package/dist/core/extensions/index.js.map +1 -1
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +23 -4
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +1 -24
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +9 -9
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js.map +1 -1
- package/dist/core/model-registry.d.ts +4 -6
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +34 -8
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +2 -5
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/settings-manager.d.ts +7 -3
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +10 -1
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/slash-commands.d.ts +1 -0
- package/dist/core/slash-commands.d.ts.map +1 -1
- package/dist/core/slash-commands.js +3 -3
- package/dist/core/slash-commands.js.map +1 -1
- package/dist/gsd/hook-utils.d.ts.map +1 -1
- package/dist/gsd/hook-utils.js +3 -1
- package/dist/gsd/hook-utils.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +1 -0
- package/dist/main.js.map +1 -1
- package/dist/modes/interactive/components/footer.d.ts +4 -0
- package/dist/modes/interactive/components/footer.d.ts.map +1 -1
- package/dist/modes/interactive/components/footer.js +1 -1
- package/dist/modes/interactive/components/footer.js.map +1 -1
- package/dist/modes/interactive/components/oauth-selector.d.ts +3 -1
- package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/oauth-selector.js +17 -6
- package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
- package/dist/modes/interactive/components/settings-selector.d.ts +2 -0
- package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/settings-selector.js +10 -0
- package/dist/modes/interactive/components/settings-selector.js.map +1 -1
- package/dist/modes/interactive/interactive-mode.d.ts +10 -0
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +247 -47
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/interactive/theme/theme-schema.json +3 -4
- package/dist/modes/interactive/theme/theme.d.ts +2 -1
- package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
- package/dist/modes/interactive/theme/theme.js +8 -4
- package/dist/modes/interactive/theme/theme.js.map +1 -1
- package/dist/modes/print-mode.d.ts.map +1 -1
- package/dist/modes/print-mode.js +1 -1
- package/dist/modes/print-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-client.d.ts +6 -6
- package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-client.js +3 -3
- package/dist/modes/rpc/rpc-client.js.map +1 -1
- package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-mode.js +4 -1
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/prompts/agents/build.md +38 -0
- package/dist/prompts/agents/plan.md +36 -0
- package/dist/prompts/agents/verify.md +36 -4
- package/dist/prompts/commands/brainstorm.md +16 -2
- package/dist/prompts/commands/discuss-phase.md +1 -1
- package/dist/prompts/commands/execute-phase.md +6 -3
- package/dist/prompts/commands/fix.md +13 -1
- package/dist/prompts/commands/init-project.md +1 -0
- package/dist/prompts/commands/map-codebase.md +9 -9
- package/dist/prompts/commands/new-project.md +1 -0
- package/dist/prompts/commands/next-milestone.md +3 -0
- package/dist/prompts/commands/orchestrate-loop.md +99 -0
- package/dist/prompts/commands/orchestrate.md +29 -6
- package/dist/prompts/commands/pause-work.md +2 -1
- package/dist/prompts/commands/plan-phase.md +6 -0
- package/dist/prompts/commands/quick.md +6 -2
- package/dist/prompts/commands/review.md +4 -1
- package/dist/prompts/commands/verify-work.md +10 -8
- package/dist/utils/clipboard-image.d.ts.map +1 -1
- package/dist/utils/clipboard-image.js +1 -1
- package/dist/utils/clipboard-image.js.map +1 -1
- package/docs/custom-provider.md +4 -3
- package/docs/extensions.md +15 -10
- package/docs/models.md +49 -8
- package/docs/rpc.md +15 -5
- package/docs/sdk.md +1 -1
- package/docs/settings.md +3 -2
- package/docs/themes.md +5 -3
- package/docs/tui.md +1 -1
- package/docs/usage.md +2 -2
- package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
- package/examples/extensions/custom-provider-anthropic/package.json +1 -1
- package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
- package/examples/extensions/preset.ts +2 -2
- package/examples/extensions/reload-runtime.ts +2 -2
- package/examples/extensions/sandbox/package-lock.json +2 -2
- package/examples/extensions/sandbox/package.json +1 -1
- package/examples/extensions/with-deps/package-lock.json +2 -2
- package/examples/extensions/with-deps/package.json +1 -1
- package/examples/sdk/README.md +1 -1
- package/package.json +5 -5
- package/prompts/agents/build.md +38 -0
- package/prompts/agents/plan.md +36 -0
- package/prompts/agents/verify.md +36 -4
- package/prompts/commands/brainstorm.md +16 -2
- package/prompts/commands/discuss-phase.md +1 -1
- package/prompts/commands/execute-phase.md +6 -3
- package/prompts/commands/fix.md +13 -1
- package/prompts/commands/init-project.md +1 -0
- package/prompts/commands/map-codebase.md +9 -9
- package/prompts/commands/new-project.md +1 -0
- package/prompts/commands/next-milestone.md +3 -0
- package/prompts/commands/orchestrate-loop.md +99 -0
- package/prompts/commands/orchestrate.md +29 -6
- package/prompts/commands/pause-work.md +2 -1
- package/prompts/commands/plan-phase.md +6 -0
- package/prompts/commands/quick.md +6 -2
- package/prompts/commands/review.md +4 -1
- package/prompts/commands/verify-work.md +10 -8
|
@@ -36,6 +36,7 @@ Before executing, decompose this phase execution into atomic reasoning units:
|
|
|
36
36
|
**Synthesize execution strategy:**
|
|
37
37
|
- Identify parallel execution groups (plans with no shared files/dependencies)
|
|
38
38
|
- Order dependent plans (plan B depends on plan A's outputs)
|
|
39
|
+
- Within each group, dispatch the riskiest plan first (highest uncertainty × blast radius) — its failure invalidates the rest of the phase most cheaply, before effort has been sunk into work it would obsolete
|
|
39
40
|
- Map each plan to a subagent task with clear success criteria
|
|
40
41
|
|
|
41
42
|
## Steps
|
|
@@ -46,7 +47,7 @@ Before executing, decompose this phase execution into atomic reasoning units:
|
|
|
46
47
|
|
|
47
48
|
### Stage 1 — Implementer
|
|
48
49
|
Use the `subagent` tool in **single mode** with the `implementer` agent. Prompt includes the full plan content + the TDD cycle instructions (template below). Read the final `STATUS:` line:
|
|
49
|
-
- `DONE` →
|
|
50
|
+
- `DONE` → **re-derive before trusting**: a `DONE` that does not quote its verification output (test counts, command output) is treated as `DONE_WITH_CONCERNS` — run the task's `<verify>` step yourself and read the result before Stage 2. Subagent claims are inputs, not verdicts.
|
|
50
51
|
- `DONE_WITH_CONCERNS` → if concerns are correctness-related, re-dispatch with a fix instruction; otherwise note and proceed.
|
|
51
52
|
- `NEEDS_CONTEXT` → provide the missing info and re-dispatch.
|
|
52
53
|
- `BLOCKED` → STOP, report to the user.
|
|
@@ -55,13 +56,13 @@ Before executing, decompose this phase execution into atomic reasoning units:
|
|
|
55
56
|
Use the `subagent` tool with the `spec-reviewer` agent. ONLY checks "does the diff cover exactly what the spec asked for". Prompt includes the task XML and the diff range.
|
|
56
57
|
- `DONE` → go to Stage 3.
|
|
57
58
|
- `DONE_WITH_CONCERNS` → note and proceed.
|
|
58
|
-
- `BLOCKED` → re-dispatch implementer with the "Required Fixes" list; repeat Stage 1+2 until `DONE`. Never proceed to Stage 3 with a non-compliant diff.
|
|
59
|
+
- `BLOCKED` → re-dispatch implementer with the "Required Fixes" list; repeat Stage 1+2 until `DONE`. Never proceed to Stage 3 with a non-compliant diff. **Hard cap: 3 implementer re-dispatches per task (across Stage 2 and Stage 3 combined)** — at the cap, record the task as failed and STOP; report the disagreement to the user.
|
|
59
60
|
|
|
60
61
|
### Stage 3 — Reviewer (code quality)
|
|
61
62
|
Use the `subagent` tool with the `reviewer` agent for code-quality review. Spec compliance is already ✅.
|
|
62
63
|
- `DONE` → task complete; move to next task.
|
|
63
64
|
- `DONE_WITH_CONCERNS` → log `Should fix` items; if any are correctness-critical, re-dispatch implementer.
|
|
64
|
-
- `BLOCKED` → `Must fix` issues exist; re-dispatch implementer with the issue list. Repeat until `DONE
|
|
65
|
+
- `BLOCKED` → `Must fix` issues exist; re-dispatch implementer with the issue list. Repeat until `DONE` — subject to the same **hard cap of 3 re-dispatches per task**; at the cap, record the task as failed and STOP.
|
|
65
66
|
|
|
66
67
|
5. After all plans complete, run `draht-tools verify-phase $1` yourself (not the subagent)
|
|
67
68
|
6. Run `draht-tools update-state` yourself
|
|
@@ -86,6 +87,8 @@ For each <task> in the plan, follow this TDD cycle:
|
|
|
86
87
|
Domain rules: Use ubiquitous language from .planning/DOMAIN.md (read it). Do not import across bounded context boundaries.
|
|
87
88
|
Checkpoint handling: type="auto" → execute silently. type="checkpoint:human-verify" → stop and report back what was built. type="checkpoint:decision" → stop and report the options.
|
|
88
89
|
|
|
90
|
+
Evidence rule: quote the decisive output of every test run and <verify> step in your report (pass/fail counts, exit codes, error text). Unquoted claims will be re-run by the orchestrator. If a plan instruction contradicts what you find in the code, stop and report NEEDS_CONTEXT — do not silently obey either side.
|
|
91
|
+
|
|
89
92
|
End your response with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED` per the agent contract.
|
|
90
93
|
|
|
91
94
|
Important: Do NOT run draht, draht-tools, draht help, or pi commands. Use only standard tools (read, bash, edit, write, grep, find, ls).
|
package/prompts/commands/fix.md
CHANGED
|
@@ -19,6 +19,14 @@ Issue: $ARGUMENTS
|
|
|
19
19
|
|
|
20
20
|
Symptom fixes are failure. If you find yourself proposing a "quick fix for now, investigate later", STOP and return to Phase 1.
|
|
21
21
|
|
|
22
|
+
## The Report Is a Symptom, Not a Diagnosis
|
|
23
|
+
|
|
24
|
+
**Procedure:** Restate the failure as observable behavior — "X happens when Y; expected Z" — before touching anything. If the user names a cause ("the cache is stale"), treat it as Hypothesis #0: it enters Phase 3 like any other hypothesis and does not skip Phase 1.
|
|
25
|
+
|
|
26
|
+
**Example:** "fix the stale cache bug" — Phase 1 traces the data flow and finds the cache is fine; the query behind it silently drops a filter. The fix lands in the query.
|
|
27
|
+
|
|
28
|
+
**Prevents:** shipping a correct fix to the wrong component.
|
|
29
|
+
|
|
22
30
|
## Red Flags — STOP
|
|
23
31
|
|
|
24
32
|
Stop immediately if you catch yourself:
|
|
@@ -29,7 +37,7 @@ Stop immediately if you catch yourself:
|
|
|
29
37
|
- Making "one more fix attempt" after already trying 2+
|
|
30
38
|
- Watching each fix reveal new problems elsewhere
|
|
31
39
|
|
|
32
|
-
After **3 failed fix attempts**, STOP. This is an architectural problem, not a hypothesis problem. Report back to the user — do not try a 4th fix.
|
|
40
|
+
After **3 failed fix attempts**, STOP. This is a **hard cap**, not advice — an architectural problem, not a hypothesis problem. Report back to the user — do not try a 4th fix. Before reporting, append one dated line to `.planning/STATE.md` under `## Lessons`: what was tried and why it failed, so the next session doesn't repeat the same three attempts.
|
|
33
41
|
|
|
34
42
|
## Atomic Reasoning
|
|
35
43
|
|
|
@@ -54,6 +62,7 @@ Walk through these steps and report on each:
|
|
|
54
62
|
3. Check recent changes — `git log --oneline -20` and `git diff HEAD~5` against affected files.
|
|
55
63
|
4. Trace data flow upward until you find the source. Fix at source, not at symptom.
|
|
56
64
|
5. State the root cause as one sentence: "X happens because Y at <file:line>."
|
|
65
|
+
6. Label every statement in your report: observed (you ran it and saw it), derived (follows necessarily from evidence), or assumed (unchecked — say what would check it). A root cause resting on an assumption is a hypothesis, not a diagnosis.
|
|
57
66
|
|
|
58
67
|
End your response with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
|
|
59
68
|
Do NOT run draht, draht-tools, or pi commands.
|
|
@@ -105,6 +114,8 @@ If Phase 2 reveals a different root cause, go back to Phase 1.
|
|
|
105
114
|
| "I'll write the test after I confirm the fix" | Untested fixes don't stick. |
|
|
106
115
|
| "I'll just try things and see what works" | Can't isolate what worked. Creates new bugs. |
|
|
107
116
|
| "I already manually tested it" | A reproducing test is the only durable proof. |
|
|
117
|
+
| "The user already told me the cause" | The reporter saw the symptom. Their diagnosis is Hypothesis #0, not a finding. |
|
|
118
|
+
| "The fix passed, so my diagnosis was right" | Fixes can mask. Verify the causal chain, not just the symptom's absence. |
|
|
108
119
|
|
|
109
120
|
## Rules
|
|
110
121
|
- Always reproduce before fixing
|
|
@@ -112,3 +123,4 @@ If Phase 2 reveals a different root cause, go back to Phase 1.
|
|
|
112
123
|
- Fix at source, not symptom
|
|
113
124
|
- 3 failed attempts ⇒ architecture problem, stop and discuss
|
|
114
125
|
- If the root cause spans multiple files, explain the chain in the commit message
|
|
126
|
+
- Final report order: verdict first (fixed / not fixed, root cause in one sentence), then evidence (reproducing test red→green, suite results), then risk (what the fix could regress, what stays assumed)
|
|
@@ -78,6 +78,7 @@ Each step runs in its own session (`/new` between steps). Do NOT suggest `/next-
|
|
|
78
78
|
- Follow threads based on answers
|
|
79
79
|
- Use examples ("Like Stripe Checkout, or custom?")
|
|
80
80
|
- Confirm, don't assume
|
|
81
|
+
- When the focus names a solution ("migrate to X"), ask what problem it solves — the existing code may admit a smaller answer
|
|
81
82
|
- 3-7 follow-up rounds typical
|
|
82
83
|
- Respect what already exists — do not propose rewriting working code
|
|
83
84
|
- Stop when you have: current state, goals, MVP scope, constraints, success criteria
|
|
@@ -30,22 +30,22 @@ Before analyzing, decompose codebase understanding into atomic reasoning units:
|
|
|
30
30
|
- Note architectural concerns and patterns
|
|
31
31
|
|
|
32
32
|
## Steps
|
|
33
|
-
1. Run `draht-tools map-codebase $1`
|
|
33
|
+
1. Run `draht-tools map-codebase $1` (graph artifacts are always whole-repo — see below)
|
|
34
34
|
2. Tool generates: STACK.md, ARCHITECTURE.md, CONVENTIONS.md, CONCERNS.md
|
|
35
|
-
2a. Run `draht-tools map-graph
|
|
35
|
+
2a. Run `draht-tools map-graph` to produce the **living architecture map**. The graph always maps the whole repository from the git root, regardless of any directory argument — the tool enforces this deterministically; a directory argument only scopes the narrative analysis in step 3, not the graph itself.
|
|
36
36
|
- `.planning/codebase/MAP.json` — machine-readable map with **entry points** (CLI bins, HTTP routes, library main exports), **sinks** (FS / net / DB / stdout / exec calls), **bounded contexts** (packages), **cross-package dataflow edges**, **symbol-resolved call edges**, **flows** (which sinks each entry point reaches and through which intermediate module), per-module **layer** (presentation / application / domain / infrastructure / support), and exports/imports per file. Agents starting a new task should read MAP.json first instead of re-scanning the tree.
|
|
37
|
-
- `.planning/codebase/MAP.html` — interactive
|
|
38
|
-
- **
|
|
39
|
-
- **
|
|
37
|
+
- `.planning/codebase/MAP.html` — interactive visualization with three tabs:
|
|
38
|
+
- **Graph** — the primary interactive force-directed knowledge graph: nodes colored by cluster and sized by degree; click a node for an inspector (file, symbols, importers, callers); search plus filters for layer / cluster / edge-confidence (EXTRACTED/INFERRED/AMBIGUOUS); legend; PNG/SVG export; double-click a cluster to expand/collapse it.
|
|
39
|
+
- **Architecture** — package containers in layer bands with cross-package dataflow arrows.
|
|
40
40
|
- **Flows** — entry points on top, sinks on bottom, intermediate modules ranked by depth from entry. Click an entry point to trace which sinks it reaches.
|
|
41
|
-
Open directly
|
|
41
|
+
Open `MAP.html` directly via `file://` — the data is embedded inline so it works fully offline — or run `draht-tools map-serve` for a live-reloading dev view (regenerates on every code-file save (docs/asset saves are ignored by design), via SSE).
|
|
42
42
|
3. **Run parallel deep analysis via subagents:**
|
|
43
43
|
Use the `subagent` tool in **parallel mode** with these tasks:
|
|
44
44
|
- `architect` agent: "Analyze the codebase at $1. Identify bounded contexts from directory structure — look for top-level src/ subdirectories, packages, or modules that encapsulate coherent domain concepts. Note any cross-directory coupling suggesting blurred context boundaries. Extract domain language: collect PascalCase class/interface/type names, key function names, database table/collection names. Look for repeated nouns representing core domain concepts. Output a structured list of: bounded contexts (name + description), domain terms (glossary), aggregates per context, and context relationships (upstream/downstream, shared kernel, ACL). End with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`. Do NOT run draht, draht-tools, or pi commands."
|
|
45
45
|
- `verifier` agent: "Analyze the test infrastructure at $1. Discover: test framework(s) in use, test directory conventions, existing coverage configuration and goals, which layers have tests (unit, integration, e2e), gaps and recommendations. Output a structured test strategy report. End with `STATUS: ...`. Do NOT run draht, draht-tools, or pi commands."
|
|
46
46
|
|
|
47
47
|
4. Read each subagent's `STATUS:` line. `BLOCKED` or `NEEDS_CONTEXT` from either means STOP — partial output here corrupts downstream phases. Collect subagent results and merge with the draht-tools output.
|
|
48
|
-
5. Create `.planning/DOMAIN.md` (if it doesn't exist)
|
|
48
|
+
5. Create `.planning/DOMAIN.md` (if it doesn't exist). Everything in it is **inferred from code, not confirmed by the user** — mark uncertain context boundaries and ambiguous terms as `(inferred)` so later commands know to confirm rather than build on them. With:
|
|
49
49
|
- `## Bounded Contexts` — one entry per discovered context with a brief description
|
|
50
50
|
- `## Ubiquitous Language` — glossary of extracted domain terms
|
|
51
51
|
- `## Context Map` — how bounded contexts relate (upstream/downstream, shared kernel, ACL)
|
|
@@ -61,7 +61,7 @@ Before analyzing, decompose codebase understanding into atomic reasoning units:
|
|
|
61
61
|
|
|
62
62
|
## Living map for agents
|
|
63
63
|
|
|
64
|
-
The `MAP.json` produced in step 2a is the single source of truth for "what's in this codebase":
|
|
65
|
-
- Subagents that need orientation should read `.planning/codebase/MAP.json` before walking the file tree.
|
|
64
|
+
The `MAP.json` produced in step 2a is the single source of truth for "what's in this codebase". It is always the **whole-repo** map — `map-graph` maps from the git root regardless of where it's invoked or what directory argument is passed:
|
|
65
|
+
- Subagents that need orientation should read `.planning/codebase/MAP.json` before walking the file tree, even when working from a subdirectory — they get the full map via the `graph-*` commands, not a scoped one.
|
|
66
66
|
- It is regenerated every time `map-codebase`, `map-graph`, or `map-serve` runs, so it stays current with the code.
|
|
67
67
|
- Developers can keep `draht-tools map-serve` running in a terminal — the HTML visualization updates live as files change, so architecture documentation is never stale.
|
|
@@ -70,5 +70,6 @@ Each step runs in its own session (`/new` between steps). Do NOT suggest `/next-
|
|
|
70
70
|
- Follow threads based on answers
|
|
71
71
|
- Use examples ("Like Stripe Checkout, or custom?")
|
|
72
72
|
- Confirm, don't assume
|
|
73
|
+
- When the description names a solution ("an app with X"), ask what problem it solves — requirements record problems and outcomes; mechanisms stay candidates
|
|
73
74
|
- 3-7 follow-up rounds typical
|
|
74
75
|
- Stop when you have: problem, audience, MVP scope, constraints, success criteria
|
|
@@ -42,6 +42,7 @@ Before planning the next milestone, decompose progress into atomic reasoning uni
|
|
|
42
42
|
2. Review completed work:
|
|
43
43
|
- Scan `.planning/phases/` for all UAT reports (`*-UAT.md`) and summaries (`*-SUMMARY.md`)
|
|
44
44
|
- Note what was built, what worked well, what had issues
|
|
45
|
+
- **Write the distilled lessons back**: append each durable lesson as a dated bullet to `.planning/STATE.md` under `## Lessons` (create the section before `## Blockers` if missing) — extraction that only informs this session evaporates; the `## Lessons` section is what future sessions reread
|
|
45
46
|
3. Assess requirements:
|
|
46
47
|
- Which v1 requirements are now satisfied?
|
|
47
48
|
- Which v1 requirements remain?
|
|
@@ -62,5 +63,7 @@ Before planning the next milestone, decompose progress into atomic reasoning uni
|
|
|
62
63
|
|
|
63
64
|
## Rules
|
|
64
65
|
- Always review what was actually built, not just what was planned
|
|
66
|
+
- Distinguish **verified-complete** (a UAT report shows observed passes) from **believed-complete** (someone said so) — only the former counts toward requirement satisfaction; the latter goes back on the list
|
|
65
67
|
- Be honest about requirements that slipped or changed scope
|
|
66
68
|
- Each phase goal must be testable — "user can X" not "implement Y"
|
|
69
|
+
- Order the new phases risk-first: the phase carrying the highest uncertainty × blast radius comes earliest, so a wrong bet invalidates the least downstream work
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Run a verification-gated loop of fresh subagent iterations until a deterministic check passes"
|
|
3
|
+
argument-hint: "<goal with a measurable success criterion> [--max-iterations N]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /orchestrate-loop
|
|
7
|
+
|
|
8
|
+
Run fresh-context worker iterations against a fixed goal until an independent check passes — or a hard stop fires. The loop closes on a deterministic check, never on an agent's claim of completion.
|
|
9
|
+
|
|
10
|
+
Goal: $ARGUMENTS
|
|
11
|
+
|
|
12
|
+
> **Tool note**: Use the `subagent` tool. Workers are `implementer` (or `debugger` for pure-diagnosis goals); the final gate is `spec-reviewer`. One worker per iteration — never parallel workers inside the loop.
|
|
13
|
+
|
|
14
|
+
## When to Loop vs Orchestrate
|
|
15
|
+
|
|
16
|
+
| Situation | Command |
|
|
17
|
+
|---|---|
|
|
18
|
+
| Decomposition is known, sub-tasks dispatch once | `/orchestrate` |
|
|
19
|
+
| Phase plans exist in `.planning/phases/` | `/execute-phase` |
|
|
20
|
+
| Goal needs iteration until a measurable criterion holds | `/orchestrate-loop` |
|
|
21
|
+
|
|
22
|
+
Loops trade tokens for persistence: use one when the work is too large or too uncertain for a single pass AND success is checkable without human judgment.
|
|
23
|
+
|
|
24
|
+
## The Loop Contract — no check, no loop
|
|
25
|
+
|
|
26
|
+
A loop is only as good as its check. Before iterating, establish all four:
|
|
27
|
+
|
|
28
|
+
1. **GOAL** — one measurable end state, stated in one sentence.
|
|
29
|
+
2. **CHECK** — a command that proves the goal, pass/fail by exit code (test suite, typecheck + lint, a script comparing against a known-good oracle). Prefer terse output: failures only.
|
|
30
|
+
3. **STOP CONDITIONS** — check passes (verified independently), max iterations reached (default 10; `--max-iterations N` overrides), stall detected, or `STATUS: BLOCKED`.
|
|
31
|
+
4. **CONSTRAINTS** — what no iteration may touch: existing tests and the check itself are immutable (weakening either to "make it pass" is a hard-stop violation), plus anything out of scope.
|
|
32
|
+
|
|
33
|
+
If no deterministic check can be derived from the goal, STOP and ask the user to define one (or fall back to `/orchestrate`). Never start a loop whose only stop signal is "looks done" — without a check, you become the verification loop and it never closes.
|
|
34
|
+
|
|
35
|
+
Write the contract to `.planning/loop/LOOP.md`:
|
|
36
|
+
|
|
37
|
+
```markdown
|
|
38
|
+
# Loop: <slug>
|
|
39
|
+
Started: <date> | Max iterations: <N>
|
|
40
|
+
|
|
41
|
+
## Goal
|
|
42
|
+
<one sentence>
|
|
43
|
+
|
|
44
|
+
## Check
|
|
45
|
+
`<command>` — passes when <what the output proves>
|
|
46
|
+
|
|
47
|
+
## Constraints
|
|
48
|
+
- <immutables and out-of-scope items>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Create `.planning/loop/PROGRESS.md` alongside it (append-only iteration log).
|
|
52
|
+
|
|
53
|
+
## Iteration Protocol
|
|
54
|
+
|
|
55
|
+
Each iteration dispatches ONE fresh worker whose prompt contains, in full (workers cannot see this conversation):
|
|
56
|
+
|
|
57
|
+
1. The loop contract verbatim
|
|
58
|
+
2. The last 3 entries of `PROGRESS.md` and the last 5 `git log --oneline` lines — the recoverable state
|
|
59
|
+
3. The previous iteration's failure evidence, terse: the failing assertions or error lines, not full output
|
|
60
|
+
4. Standing orders:
|
|
61
|
+
- **Startup ritual** — read the progress log, run the CHECK first, observe the current failure before changing anything
|
|
62
|
+
- **One increment** — the smallest change that moves the check toward passing; do not batch
|
|
63
|
+
- **Commit the increment** even if the check still fails — state must survive context death
|
|
64
|
+
- **Append one `PROGRESS.md` entry** — what changed / check result observed / suggested next step
|
|
65
|
+
- Never edit or delete tests or the check to make it pass; never claim completion without quoting check output
|
|
66
|
+
|
|
67
|
+
## Independent Verification — the gate
|
|
68
|
+
|
|
69
|
+
After EVERY iteration, re-run the CHECK yourself and read exit code and output. Completion is decided by this re-run, never by the worker's report — worker claims are inputs, not verdicts.
|
|
70
|
+
|
|
71
|
+
- **Check passes** → dispatch `spec-reviewer` once over the full loop diff (contract vs everything changed since the loop started). Only a clean spec review ends the loop as DONE; concerns trigger one more targeted iteration.
|
|
72
|
+
- **Check fails** → extract the terse failure evidence and feed it into the next iteration's prompt as guidance.
|
|
73
|
+
|
|
74
|
+
## Stall Detection
|
|
75
|
+
|
|
76
|
+
Stop early when the loop is running but not progressing:
|
|
77
|
+
|
|
78
|
+
- Two consecutive iterations with the identical failure signature, or
|
|
79
|
+
- An iteration that produced no commit
|
|
80
|
+
|
|
81
|
+
On stall, do not dispatch the same input again — change something: decompose the goal, add context the workers were missing, switch worker (`implementer` → `debugger`), consult `advisor` for a course correction, or surface to the user with the evidence so far.
|
|
82
|
+
|
|
83
|
+
## Steps
|
|
84
|
+
|
|
85
|
+
1. Parse `$ARGUMENTS` into GOAL and flags; derive the CHECK; refuse to loop without one
|
|
86
|
+
2. Write `.planning/loop/LOOP.md` and `.planning/loop/PROGRESS.md`
|
|
87
|
+
3. Iterate: dispatch worker → re-run CHECK yourself → branch (pass → gate, fail → next iteration, stall / max / BLOCKED → hard stop)
|
|
88
|
+
4. On success: spec-review the full diff, then report — outcome first, check output quoted, iterations used
|
|
89
|
+
5. On any hard stop: append a handoff entry to `PROGRESS.md` (state observed, failure evidence, recommended next step) and report with observed / derived / assumed labels
|
|
90
|
+
6. Leave `.planning/loop/` in place as the loop's record
|
|
91
|
+
|
|
92
|
+
## Rules
|
|
93
|
+
|
|
94
|
+
- One worker, one increment, at least one commit per iteration
|
|
95
|
+
- Loops are volume work — run workers on the executor tier and keep steering (this context, `advisor`, `spec-reviewer`) on the strongest tier
|
|
96
|
+
- The worker never grades its own work — your re-run of the check plus a fresh-context spec review decide completion
|
|
97
|
+
- Never raise max iterations mid-loop without asking the user
|
|
98
|
+
- Tests and the check are immutable inside the loop; tampering means revert and hard stop
|
|
99
|
+
- Evidence discipline applies to the loop verdict: label results observed / derived / assumed
|
|
@@ -9,15 +9,15 @@ Decompose a task and dispatch the right mix of specialist subagents.
|
|
|
9
9
|
|
|
10
10
|
Task: $ARGUMENTS
|
|
11
11
|
|
|
12
|
-
> **Tool note**: Use the `subagent` tool. Set `agent` to one of: `architect`, `implementer`, `spec-reviewer`, `reviewer`, `debugger`, `verifier`, `git-committer`, `security-auditor`. Use `tasks: [...]` for parallel dispatch and `chain: [...]` for sequential pipelines.
|
|
12
|
+
> **Tool note**: Use the `subagent` tool. Set `agent` to one of: `architect`, `implementer`, `spec-reviewer`, `reviewer`, `debugger`, `verifier`, `git-committer`, `security-auditor`, `advisor`. Use `tasks: [...]` for parallel dispatch and `chain: [...]` for sequential pipelines.
|
|
13
13
|
|
|
14
14
|
## Atomic Reasoning
|
|
15
15
|
|
|
16
16
|
Before delegating, decompose the task into atomic work units:
|
|
17
17
|
|
|
18
|
-
1. **State the logical components** — What sub-tasks make up this work? Which are independent?
|
|
18
|
+
1. **State the logical components** — What sub-tasks make up this work? Which are independent? A sub-task is well-cut only if its success can be checked without reference to the others.
|
|
19
19
|
2. **Match agents to work** — Which specialist is right for each sub-task?
|
|
20
|
-
3. **Determine order** — What can run in parallel vs what must be sequential?
|
|
20
|
+
3. **Determine order** — What can run in parallel vs what must be sequential? Among independent sub-tasks, dispatch the riskiest first (highest uncertainty × blast radius): its failure invalidates the rest of the graph most cheaply, before effort is sunk into work it would obsolete.
|
|
21
21
|
4. **Define success** — What does "done" look like for each sub-task, and for the whole?
|
|
22
22
|
|
|
23
23
|
## Agent Selection Guide
|
|
@@ -32,9 +32,28 @@ Before delegating, decompose the task into atomic work units:
|
|
|
32
32
|
| Audit for security issues | `security-auditor` |
|
|
33
33
|
| Run lint / typecheck / tests | `verifier` |
|
|
34
34
|
| Create atomic commits | `git-committer` |
|
|
35
|
+
| Strategic steer at a decision point — rare, high-leverage | `advisor` |
|
|
35
36
|
|
|
36
37
|
`spec-reviewer` and `reviewer` are distinct on purpose. Spec-reviewer ONLY checks "did the diff implement what the spec asked, no more no less". Reviewer evaluates quality. For any task with a written spec, run spec-reviewer **before** reviewer.
|
|
37
38
|
|
|
39
|
+
## Effort Scaling
|
|
40
|
+
|
|
41
|
+
Match orchestration weight to the task — over-orchestration burns tokens without adding verification value:
|
|
42
|
+
|
|
43
|
+
| Task shape | Dispatch |
|
|
44
|
+
|---|---|
|
|
45
|
+
| Single question or trivial fix | One agent, or handle it directly — no orchestration |
|
|
46
|
+
| One change set to evaluate | 2–4 parallel evaluators (reviewer, security-auditor, verifier) |
|
|
47
|
+
| Multi-part feature with known decomposition | Fan-out / fan-in |
|
|
48
|
+
| Goal needing iteration until a measurable criterion holds | `/orchestrate-loop` |
|
|
49
|
+
|
|
50
|
+
## Model Tiering
|
|
51
|
+
|
|
52
|
+
Bill volume tokens at the cheaper rate:
|
|
53
|
+
|
|
54
|
+
- **Orchestrator pattern** — run this command on the strongest tier (e.g. Claude Fable 5) and let workers execute on the executor tier (e.g. Claude Sonnet 5): planning quality where it matters, volume tokens at worker rates.
|
|
55
|
+
- **Advisor pattern** — when the session runs on the executor tier, dispatch `advisor` sparingly: once after orientation before committing to an approach, again when stuck or before declaring a hard task done. ~1–3 consults per task; treat its guidance with serious weight.
|
|
56
|
+
|
|
38
57
|
## Orchestration Modes
|
|
39
58
|
|
|
40
59
|
### Parallel
|
|
@@ -57,11 +76,14 @@ implementer → spec-reviewer → reviewer
|
|
|
57
76
|
|
|
58
77
|
Never run quality review on a spec-non-compliant diff. This is the per-task loop inside `/execute-phase`.
|
|
59
78
|
|
|
79
|
+
### Loop (iterate until a check passes)
|
|
80
|
+
When the work cannot land in one dispatch but success is provable by a deterministic check, do not improvise retries here — hand off to `/orchestrate-loop`. It runs fresh worker iterations gated by an independent re-run of the check, with max-iteration and stall bounds.
|
|
81
|
+
|
|
60
82
|
## Reading Subagent Status
|
|
61
83
|
|
|
62
84
|
Every draht agent ends its response with one of four status lines. Branch on it:
|
|
63
85
|
|
|
64
|
-
- `STATUS: DONE` —
|
|
86
|
+
- `STATUS: DONE` — check the evidence before proceeding: a `DONE` that quotes no verification output (test counts, command results) is treated as `DONE_WITH_CONCERNS` — re-run the decisive check yourself. Subagent claims are inputs, not verdicts.
|
|
65
87
|
- `STATUS: DONE_WITH_CONCERNS` — note the concerns. If correctness-related, address before moving on; otherwise log and continue.
|
|
66
88
|
- `STATUS: NEEDS_CONTEXT` — provide the missing info and re-dispatch the same agent. Do NOT skip ahead with a guess.
|
|
67
89
|
- `STATUS: BLOCKED` — STOP. Report the blocker. Do not retry the same agent on the same input — adjust inputs (more context, decompose further, different agent) or surface to the user.
|
|
@@ -72,11 +94,12 @@ Every draht agent ends its response with one of four status lines. Branch on it:
|
|
|
72
94
|
3. Decide parallel vs chain vs fan-out vs two-stage based on dependencies
|
|
73
95
|
4. Dispatch via the `subagent` tool accordingly
|
|
74
96
|
5. Read each subagent's final `STATUS:` line and branch per the protocol above
|
|
75
|
-
6. Collect results, handle failures, report the
|
|
97
|
+
6. Collect results, handle failures, report to the user — outcome first (what happened, in one line), evidence second (what each agent verified, quoted), risk last (what remains unverified or assumed)
|
|
76
98
|
|
|
77
99
|
## Rules
|
|
78
100
|
- Prefer parallel dispatch when possible — it's faster and each subagent has its own context
|
|
79
|
-
-
|
|
101
|
+
- Every dispatch is a complete brief: objective, expected output format, tool guidance, and task boundaries — subagents cannot see the main conversation
|
|
80
102
|
- Do not nest delegations deeply — one level is usually enough
|
|
81
103
|
- Never retry the same agent on the same input after `BLOCKED` — change something
|
|
82
104
|
- For any spec-driven work, spec-reviewer runs before quality reviewer
|
|
105
|
+
- The agent that produced work never evaluates it — completion verdicts come from a fresh-context evaluator plus your own re-run of the decisive check
|
|
@@ -26,4 +26,5 @@ Before pausing, decompose session state into atomic reasoning units:
|
|
|
26
26
|
|
|
27
27
|
## Steps
|
|
28
28
|
1. Run `draht-tools pause` — creates CONTINUE-HERE.md
|
|
29
|
-
2.
|
|
29
|
+
2. **Distill lessons before the context is lost**: for anything this session tried that failed, or an approach that worked against expectations, append one dated bullet to `.planning/STATE.md` under `## Lessons` (create the section before `## Blockers` if missing). Lessons name what to do differently — "runner hits TLS issue in PowerShell, use bash", not "had problems with tests".
|
|
30
|
+
3. Commit: `draht-tools commit-docs "pause work"`
|
|
@@ -23,6 +23,7 @@ A plan is only as good as the tasks inside it. STOP and revise instead of saving
|
|
|
23
23
|
- A task takes more than ~5 minutes — break it down further
|
|
24
24
|
- The plan introduces new domain terms that are NOT in `.planning/DOMAIN.md` — update DOMAIN.md first
|
|
25
25
|
- A plan touches more than one bounded context without explicit ACL — split per context
|
|
26
|
+
- The first plan is scaffolding/boilerplate while an unproven risk (new integration, unfamiliar API, untested pattern) sits in a later plan — reorder so the risk is proven first
|
|
26
27
|
|
|
27
28
|
Run `draht-tools validate-plans $1` after saving. Fix any issues it reports before commit.
|
|
28
29
|
|
|
@@ -35,14 +36,19 @@ Before creating plans, decompose this phase goal into atomic reasoning units:
|
|
|
35
36
|
2. **Validate independence** — Which artifacts (files, endpoints, schemas) prove this truth exists? Can it be built independently?
|
|
36
37
|
3. **Verify correctness** — What test scenarios would prove this observable truth? What are the specific inputs → expected outputs?
|
|
37
38
|
|
|
39
|
+
**Atomicity test:** a task is atomic only if its `<verify>` can fail while every other task passes. If two tasks can only be checked together, they are one task.
|
|
40
|
+
|
|
38
41
|
**Synthesize planning strategy:**
|
|
39
42
|
- Group related observable truths into cohesive plans (2-5 tasks each)
|
|
40
43
|
- Identify which plans can be created in parallel vs sequentially
|
|
41
44
|
- Map each plan to specific bounded contexts and domain concepts
|
|
42
45
|
- Ensure each plan produces testable, verifiable outcomes
|
|
46
|
+
- **Order risk-first**: score each truth by uncertainty (has this codebase done it before?) × blast radius (how much becomes invalid if it's wrong?). The plan proving the highest-scoring truth executes first; boilerplate goes last. Boilerplate never invalidates a phase — the risky part regularly does.
|
|
47
|
+
- Write every assumption a plan rests on as an explicit `Assumes:` line (with how to confirm it) in the plan header. Unwritten assumptions become the executor's bugs.
|
|
43
48
|
|
|
44
49
|
## Steps
|
|
45
50
|
1. Run `draht-tools load-phase-context $1` to gather all context
|
|
51
|
+
1b. Read `.planning/STATE.md` `## Lessons` — every plan must respect the recorded lessons; a plan that repeats a documented failure is invalid. Feed relevant lessons into each architect prompt.
|
|
46
52
|
2. Optional: `draht-tools research-phase $1` for domain research
|
|
47
53
|
3. Goal-backward planning:
|
|
48
54
|
a. State the goal (outcome, not activity)
|
|
@@ -13,6 +13,10 @@ Execute a small ad-hoc task with tracking.
|
|
|
13
13
|
|
|
14
14
|
Task: $ARGUMENTS
|
|
15
15
|
|
|
16
|
+
## "Small" Is a Claim, Not a Fact
|
|
17
|
+
|
|
18
|
+
Before planning, verify the task is actually quick: grep the blast radius (callers, imports, tests touching the target). If the change reaches further than the description implies, say so and recommend `/plan-phase`-level treatment instead of forcing it through. And if the description names a solution ("add a flag"), confirm the problem it solves — a smaller fix may exist. A "quick task" that silently grows is how untracked complexity enters a codebase.
|
|
19
|
+
|
|
16
20
|
## Atomic Reasoning
|
|
17
21
|
|
|
18
22
|
Before executing, decompose this task into atomic reasoning units:
|
|
@@ -65,11 +69,11 @@ Before executing, decompose this task into atomic reasoning units:
|
|
|
65
69
|
End with `STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED`.
|
|
66
70
|
```
|
|
67
71
|
- `DONE` → go to Stage 3.
|
|
68
|
-
- `BLOCKED` → re-dispatch implementer with Required Fixes. Repeat until `DONE`.
|
|
72
|
+
- `BLOCKED` → re-dispatch implementer with Required Fixes. Repeat until `DONE`. **Hard cap: 3 re-dispatches total** — at the cap, STOP and report the disagreement to the user.
|
|
69
73
|
|
|
70
74
|
5. **Stage 3 — Reviewer (optional code-quality pass).** For non-trivial quick tasks (more than one file, or domain code), use the `subagent` tool with the `reviewer` agent. Otherwise skip.
|
|
71
75
|
- `DONE` → task complete.
|
|
72
|
-
- `BLOCKED` → re-dispatch implementer with Must-fix list.
|
|
76
|
+
- `BLOCKED` → re-dispatch implementer with Must-fix list — same **hard cap of 3 re-dispatches**; at the cap, STOP and report.
|
|
73
77
|
|
|
74
78
|
6. Write summary: `draht-tools write-quick-summary NNN`
|
|
75
79
|
7. Update state: `draht-tools update-state`
|
|
@@ -47,11 +47,14 @@ Before reviewing, decompose code changes into atomic reasoning units:
|
|
|
47
47
|
|
|
48
48
|
5. Read each subagent's final `STATUS:` line.
|
|
49
49
|
6. Collect and merge results.
|
|
50
|
-
7.
|
|
50
|
+
7. **Refute before reporting.** For each Critical or Important finding, attempt to kill it yourself before it reaches the report: read the code path that would make it a false positive — an upstream guard clause, a type constraint, an existing test that covers the case. A finding that survives an honest refutation attempt is **confirmed** (you traced the failing path); one you couldn't confirm is downgraded and labeled **suspected**. Reporting unattacked findings trains readers to ignore the report.
|
|
51
|
+
8. Produce a unified, prioritized findings report. Verdict first: one line — mergeable or not, and why. Then findings:
|
|
51
52
|
- **Critical** — must fix before merge (security `BLOCKED`, spec gaps for required deliverables, correctness issues that cause data loss / crashes)
|
|
52
53
|
- **Important** — should fix (bugs, type issues, spec over-builds, missing error handling)
|
|
53
54
|
- **Minor** — style, naming, optional improvements
|
|
54
55
|
|
|
56
|
+
Each finding carries its label (confirmed/suspected). End with residual risk: what the review did NOT cover (files skipped, paths not traced) — a review that claims total coverage it doesn't have is worse than a scoped one.
|
|
57
|
+
|
|
55
58
|
## Reading STATUS
|
|
56
59
|
- Any `STATUS: BLOCKED` → its findings escalate to Critical in the merged report
|
|
57
60
|
- `STATUS: NEEDS_CONTEXT` → provide missing info and re-dispatch that one agent
|
|
@@ -38,23 +38,25 @@ Before verifying, decompose phase acceptance into atomic reasoning units:
|
|
|
38
38
|
- `reviewer` agent: "Review the recent code changes for this phase. Check domain language compliance against `.planning/DOMAIN.md` if it exists — scan for identifiers not in the glossary and cross-context boundary violations. Report Must fix / Should fix / Consider. End with `STATUS: ...`. Do NOT run draht, draht-tools, or pi commands."
|
|
39
39
|
- `spec-reviewer` agent: "Phase-level spec compliance check for phase $1. The phase has these plan files (each is a spec): <list of .planning/phases/<N>-*/<N>-NN-PLAN.md paths>. For each plan, evaluate whether the phase's commits implement exactly what the plan's <task> elements asked — no missing tasks, no over-builds. Use git log and git diff against the phase commit range. Output a per-plan compliance verdict with omissions and over-builds. End with `STATUS: ...`."
|
|
40
40
|
|
|
41
|
-
4. **
|
|
41
|
+
4. **Spot-check before aggregating.** Subagent claims are inputs, not verdicts. Before accepting the verifier's `DONE`, re-run the test suite headline yourself and read the counts. Before accepting the spec-reviewer's compliance verdict, read one plan's diff yourself. A pass you only heard about is an "assumed pass" — and an assumed pass is not a pass. This costs two commands and catches the most expensive failure mode this command has: trust laundered into evidence.
|
|
42
|
+
|
|
43
|
+
5. **Read each subagent's `STATUS:` line.** Treat the phase as failed if any of these is `BLOCKED`:
|
|
42
44
|
- `verifier` (tests / lint / typecheck failed)
|
|
43
45
|
- `security-auditor` (Critical or High findings)
|
|
44
46
|
- `spec-reviewer` (any plan non-compliant)
|
|
45
47
|
- `reviewer` (Must-fix correctness issues)
|
|
46
48
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
49
|
+
6. Collect results and walk user through each deliverable, incorporating findings.
|
|
50
|
+
7. Record results (pass/fail/partially/skip). Label each: **observed** (you or a subagent ran it and quoted output), **derived** (follows necessarily from something observed), or **assumed** (unchecked). Verdicts inherit the weakest label they rest on.
|
|
51
|
+
8. For failures: diagnose and create fix plans via `draht-tools create-fix-plan $1 P`
|
|
50
52
|
- Fix plans MUST include a reproducing test that demonstrates the failure before any implementation
|
|
51
53
|
- Spec-reviewer omissions become explicit fix-plan tasks (one task per omission)
|
|
52
|
-
|
|
53
|
-
-
|
|
54
|
-
|
|
54
|
+
9. Write UAT report: `draht-tools write-uat $1`
|
|
55
|
+
- Order: **verdict first** (phase pass/fail, X/Y deliverables, in the first line), **evidence second** (test health summary with pass/fail/coverage, security audit results, spec compliance summary per plan, domain model status, deliverable results with labels), **risk last** (what was NOT tested and how it could bite). Never bury a failure under passes.
|
|
56
|
+
10. If all passed: mark phase complete.
|
|
55
57
|
- If more phases remain in the milestone: tell the user to start a new session and run `/discuss-phase N+1`.
|
|
56
58
|
- If ALL phases in the milestone are complete: tell the user to start a new session and run `/next-milestone`.
|
|
57
|
-
|
|
59
|
+
11. If failures: route to `execute-phase $1 --gaps-only`
|
|
58
60
|
|
|
59
61
|
## Why a phase-level spec-reviewer
|
|
60
62
|
|