@draht/coding-agent 2026.6.11 → 2026.7.7-1
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 +21 -0
- package/README.md +1 -4
- package/dist/bun/register-bedrock.d.ts.map +1 -1
- package/dist/bun/register-bedrock.js +1 -1
- package/dist/bun/register-bedrock.js.map +1 -1
- package/dist/bun/restore-sandbox-env.d.ts +4 -0
- package/dist/bun/restore-sandbox-env.d.ts.map +1 -1
- package/dist/bun/restore-sandbox-env.js +4 -0
- package/dist/bun/restore-sandbox-env.js.map +1 -1
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +4 -4
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/config-selector.d.ts +4 -2
- package/dist/cli/config-selector.d.ts.map +1 -1
- package/dist/cli/config-selector.js +1 -1
- package/dist/cli/config-selector.js.map +1 -1
- package/dist/cli/file-processor.d.ts.map +1 -1
- package/dist/cli/file-processor.js +13 -25
- package/dist/cli/file-processor.js.map +1 -1
- package/dist/cli/session-picker.d.ts +2 -1
- package/dist/cli/session-picker.d.ts.map +1 -1
- package/dist/cli/session-picker.js +5 -4
- package/dist/cli/session-picker.js.map +1 -1
- package/dist/cli/startup-ui.d.ts +5 -1
- package/dist/cli/startup-ui.d.ts.map +1 -1
- package/dist/cli/startup-ui.js +94 -22
- package/dist/cli/startup-ui.js.map +1 -1
- package/dist/config.d.ts +6 -2
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +35 -16
- package/dist/config.js.map +1 -1
- package/dist/core/agent-session.d.ts +10 -4
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +124 -83
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/auth-storage.d.ts +11 -12
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +25 -26
- package/dist/core/auth-storage.js.map +1 -1
- package/dist/core/compaction/branch-summarization.d.ts +3 -1
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +3 -3
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +5 -4
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +23 -20
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/export-html/vendor/marked.min.js +75 -3
- 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 +2 -3
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +77 -14
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +2 -1
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +33 -1
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +29 -2
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/http-dispatcher.d.ts +1 -0
- package/dist/core/http-dispatcher.d.ts.map +1 -1
- package/dist/core/http-dispatcher.js +45 -2
- package/dist/core/http-dispatcher.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/keybindings.d.ts +1 -1
- package/dist/core/keybindings.d.ts.map +1 -1
- package/dist/core/keybindings.js +3 -6
- package/dist/core/keybindings.js.map +1 -1
- package/dist/core/model-registry.d.ts +2 -1
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +32 -67
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts +11 -1
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +37 -19
- package/dist/core/model-resolver.js.map +1 -1
- package/dist/core/package-manager.d.ts +5 -2
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +99 -43
- package/dist/core/package-manager.js.map +1 -1
- package/dist/core/project-trust.d.ts.map +1 -1
- package/dist/core/project-trust.js +4 -3
- package/dist/core/project-trust.js.map +1 -1
- package/dist/core/provider-attribution.d.ts +2 -2
- package/dist/core/provider-attribution.d.ts.map +1 -1
- package/dist/core/provider-attribution.js.map +1 -1
- package/dist/core/provider-display-names.d.ts.map +1 -1
- package/dist/core/provider-display-names.js +1 -1
- package/dist/core/provider-display-names.js.map +1 -1
- package/dist/core/resolve-config-value.d.ts +7 -8
- package/dist/core/resolve-config-value.d.ts.map +1 -1
- package/dist/core/resolve-config-value.js +24 -26
- package/dist/core/resolve-config-value.js.map +1 -1
- package/dist/core/resource-loader.d.ts +3 -2
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +16 -6
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/sdk.d.ts +9 -9
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +3 -1
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-manager.d.ts +21 -2
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +121 -77
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-manager.d.ts +10 -1
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +29 -3
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/system-prompt.d.ts.map +1 -1
- package/dist/core/system-prompt.js +7 -7
- package/dist/core/system-prompt.js.map +1 -1
- package/dist/core/timings.d.ts +4 -2
- package/dist/core/timings.d.ts.map +1 -1
- package/dist/core/timings.js +24 -14
- package/dist/core/timings.js.map +1 -1
- package/dist/core/tools/bash.d.ts.map +1 -1
- package/dist/core/tools/bash.js +32 -8
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/edit-diff.d.ts +23 -4
- package/dist/core/tools/edit-diff.d.ts.map +1 -1
- package/dist/core/tools/edit-diff.js +99 -20
- package/dist/core/tools/edit-diff.js.map +1 -1
- package/dist/core/tools/edit.d.ts.map +1 -1
- package/dist/core/tools/edit.js +2 -2
- package/dist/core/tools/edit.js.map +1 -1
- package/dist/core/tools/find.d.ts.map +1 -1
- package/dist/core/tools/find.js +19 -11
- package/dist/core/tools/find.js.map +1 -1
- package/dist/core/tools/read.d.ts.map +1 -1
- package/dist/core/tools/read.js +12 -25
- package/dist/core/tools/read.js.map +1 -1
- package/dist/core/trust-manager.d.ts +8 -3
- package/dist/core/trust-manager.d.ts.map +1 -1
- package/dist/core/trust-manager.js +26 -11
- package/dist/core/trust-manager.js.map +1 -1
- package/dist/index.d.ts +6 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -3
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts +2 -2
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +47 -15
- package/dist/main.js.map +1 -1
- package/dist/migrations.d.ts.map +1 -1
- package/dist/migrations.js +1 -123
- package/dist/migrations.js.map +1 -1
- package/dist/modes/interactive/assets/clankolas.png +0 -0
- package/dist/modes/interactive/components/assistant-message.d.ts +3 -1
- package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/assistant-message.js +23 -15
- package/dist/modes/interactive/components/assistant-message.js.map +1 -1
- package/dist/modes/interactive/components/config-selector.d.ts +34 -3
- package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/config-selector.js +284 -29
- package/dist/modes/interactive/components/config-selector.js.map +1 -1
- package/dist/modes/interactive/components/custom-entry.d.ts +19 -0
- package/dist/modes/interactive/components/custom-entry.d.ts.map +1 -0
- package/dist/modes/interactive/components/custom-entry.js +52 -0
- package/dist/modes/interactive/components/custom-entry.js.map +1 -0
- package/dist/modes/interactive/components/extension-editor.d.ts +3 -1
- package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-editor.js +12 -3
- package/dist/modes/interactive/components/extension-editor.js.map +1 -1
- package/dist/modes/interactive/components/footer.d.ts +2 -2
- package/dist/modes/interactive/components/footer.d.ts.map +1 -1
- package/dist/modes/interactive/components/footer.js +4 -0
- package/dist/modes/interactive/components/footer.js.map +1 -1
- package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
- package/dist/modes/interactive/components/login-dialog.js +0 -1
- package/dist/modes/interactive/components/login-dialog.js.map +1 -1
- package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/model-selector.js +2 -1
- package/dist/modes/interactive/components/model-selector.js.map +1 -1
- package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/scoped-models-selector.js +4 -1
- package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
- package/dist/modes/interactive/components/session-selector.d.ts +0 -1
- package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/session-selector.js +14 -8
- package/dist/modes/interactive/components/session-selector.js.map +1 -1
- package/dist/modes/interactive/components/settings-selector.d.ts +4 -0
- package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/settings-selector.js +188 -16
- package/dist/modes/interactive/components/settings-selector.js.map +1 -1
- package/dist/modes/interactive/components/status-indicator.d.ts +28 -0
- package/dist/modes/interactive/components/status-indicator.d.ts.map +1 -0
- package/dist/modes/interactive/components/status-indicator.js +60 -0
- package/dist/modes/interactive/components/status-indicator.js.map +1 -0
- package/dist/modes/interactive/components/tree-selector.d.ts +1 -1
- package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/tree-selector.js +130 -15
- package/dist/modes/interactive/components/tree-selector.js.map +1 -1
- package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/trust-selector.js +4 -4
- package/dist/modes/interactive/components/trust-selector.js.map +1 -1
- package/dist/modes/interactive/components/user-message.d.ts +6 -2
- package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/user-message.js +19 -6
- package/dist/modes/interactive/components/user-message.js.map +1 -1
- package/dist/modes/interactive/interactive-mode.d.ts +13 -11
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +252 -233
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/interactive/model-search.d.ts +12 -0
- package/dist/modes/interactive/model-search.d.ts.map +1 -0
- package/dist/modes/interactive/model-search.js +15 -0
- package/dist/modes/interactive/model-search.js.map +1 -0
- package/dist/modes/interactive/theme/theme-controller.d.ts +29 -0
- package/dist/modes/interactive/theme/theme-controller.d.ts.map +1 -0
- package/dist/modes/interactive/theme/theme-controller.js +102 -0
- package/dist/modes/interactive/theme/theme-controller.js.map +1 -0
- package/dist/modes/interactive/theme/theme-schema.json +2 -1
- package/dist/modes/interactive/theme/theme.d.ts +27 -8
- package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
- package/dist/modes/interactive/theme/theme.js +64 -42
- package/dist/modes/interactive/theme/theme.js.map +1 -1
- package/dist/modes/rpc/rpc-client.d.ts +19 -4
- package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-client.js +14 -0
- 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 +17 -1
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-types.d.ts +26 -0
- package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-types.js.map +1 -1
- package/dist/package-manager-cli.d.ts +2 -2
- package/dist/package-manager-cli.d.ts.map +1 -1
- package/dist/package-manager-cli.js +152 -48
- package/dist/package-manager-cli.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 +162 -0
- package/dist/prompts/commands/discuss-phase.md +1 -1
- package/dist/prompts/commands/execute-phase.md +4 -1
- package/dist/prompts/commands/fix.md +12 -0
- package/dist/prompts/commands/init-project.md +1 -0
- package/dist/prompts/commands/map-codebase.md +1 -1
- package/dist/prompts/commands/new-project.md +1 -0
- package/dist/prompts/commands/next-milestone.md +2 -0
- package/dist/prompts/commands/orchestrate.md +4 -4
- package/dist/prompts/commands/plan-phase.md +5 -0
- package/dist/prompts/commands/quick.md +4 -0
- package/dist/prompts/commands/review.md +4 -1
- package/dist/prompts/commands/verify-work.md +10 -8
- package/dist/rpc-entry.d.ts +3 -0
- package/dist/rpc-entry.d.ts.map +1 -0
- package/dist/rpc-entry.js +10 -0
- package/dist/rpc-entry.js.map +1 -0
- package/dist/utils/child-process.d.ts +7 -4
- package/dist/utils/child-process.d.ts.map +1 -1
- package/dist/utils/child-process.js +23 -5
- package/dist/utils/child-process.js.map +1 -1
- package/dist/utils/image-convert.d.ts +1 -0
- package/dist/utils/image-convert.d.ts.map +1 -1
- package/dist/utils/image-convert.js +21 -15
- package/dist/utils/image-convert.js.map +1 -1
- package/dist/utils/image-process.d.ts +18 -0
- package/dist/utils/image-process.d.ts.map +1 -0
- package/dist/utils/image-process.js +83 -0
- package/dist/utils/image-process.js.map +1 -0
- package/dist/utils/mime.d.ts.map +1 -1
- package/dist/utils/mime.js +41 -0
- package/dist/utils/mime.js.map +1 -1
- package/dist/utils/shell.d.ts +1 -0
- package/dist/utils/shell.d.ts.map +1 -1
- package/dist/utils/shell.js +12 -5
- package/dist/utils/shell.js.map +1 -1
- package/dist/utils/version-check.d.ts.map +1 -1
- package/dist/utils/version-check.js +4 -27
- package/dist/utils/version-check.js.map +1 -1
- package/docs/extensions.md +55 -8
- package/docs/keybindings.md +1 -1
- package/docs/packages.md +2 -2
- package/docs/providers.md +2 -1
- package/docs/rpc.md +58 -0
- package/docs/sdk.md +50 -0
- package/docs/session-format.md +18 -8
- package/docs/settings.md +10 -0
- package/docs/usage.md +2 -2
- package/examples/extensions/README.md +1 -0
- package/examples/extensions/custom-compaction.ts +2 -1
- package/examples/extensions/custom-provider-anthropic/index.ts +1 -1
- 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/index.ts +9 -5
- package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
- package/examples/extensions/custom-provider-gitlab-duo/test.ts +1 -1
- package/examples/extensions/entry-renderer.ts +41 -0
- package/examples/extensions/gondolin/package-lock.json +2 -2
- package/examples/extensions/gondolin/package.json +1 -1
- package/examples/extensions/handoff.ts +2 -2
- package/examples/extensions/plan-mode/index.ts +87 -37
- package/examples/extensions/preset.ts +10 -4
- package/examples/extensions/provider-payload.ts +5 -5
- package/examples/extensions/qna.ts +2 -2
- package/examples/extensions/question.ts +32 -18
- package/examples/extensions/questionnaire.ts +41 -28
- package/examples/extensions/sandbox/index.ts +2 -2
- package/examples/extensions/sandbox/package-lock.json +2 -2
- package/examples/extensions/sandbox/package.json +1 -1
- package/examples/extensions/subagent/agents.ts +2 -2
- package/examples/extensions/subagent/index.ts +9 -3
- package/examples/extensions/summarize.ts +2 -1
- package/examples/extensions/with-deps/package-lock.json +2 -2
- package/examples/extensions/with-deps/package.json +1 -1
- package/examples/sdk/02-custom-model.ts +1 -1
- package/examples/sdk/12-full-control.ts +2 -2
- package/package.json +14 -15
- 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 +162 -0
- package/prompts/commands/discuss-phase.md +1 -1
- package/prompts/commands/execute-phase.md +4 -1
- package/prompts/commands/fix.md +12 -0
- package/prompts/commands/init-project.md +1 -0
- package/prompts/commands/map-codebase.md +1 -1
- package/prompts/commands/new-project.md +1 -0
- package/prompts/commands/next-milestone.md +2 -0
- package/prompts/commands/orchestrate.md +4 -4
- package/prompts/commands/plan-phase.md +5 -0
- package/prompts/commands/quick.md +4 -0
- package/prompts/commands/review.md +4 -1
- package/prompts/commands/verify-work.md +10 -8
|
@@ -13,6 +13,33 @@ You are an execution agent. Your job is to implement plans precisely.
|
|
|
13
13
|
4. Commit after each task: `draht commit-task N P T "description"`
|
|
14
14
|
5. If verification fails, fix it before continuing
|
|
15
15
|
6. Never skip a verify step — that's how quality dies
|
|
16
|
+
7. If a plan instruction contradicts what you find in the code, STOP and report `NEEDS_CONTEXT` — do not silently obey either side
|
|
17
|
+
|
|
18
|
+
## Evidence, Not Plausibility
|
|
19
|
+
|
|
20
|
+
A step is done when you have watched it be done.
|
|
21
|
+
|
|
22
|
+
**Procedure:**
|
|
23
|
+
1. "Verified" means you ran the command and read the output in this session — not that the code looks right.
|
|
24
|
+
2. Quote the decisive line of output in your summary: test counts, exit codes, the actual error text.
|
|
25
|
+
3. If you did not run it, write "not verified" — never let a plausible claim wear a verified claim's clothes.
|
|
26
|
+
|
|
27
|
+
**Example:** after implementing a parser, "bun test parser: 14 pass, 0 fail" is evidence; "the parser now handles all cases" is a guess in a suit.
|
|
28
|
+
|
|
29
|
+
**Prevents:** reporting a green build nobody ever ran.
|
|
30
|
+
|
|
31
|
+
## Competence Mimics
|
|
32
|
+
|
|
33
|
+
These feel like progress and are not:
|
|
34
|
+
|
|
35
|
+
| Looks like competence | Is actually |
|
|
36
|
+
|---|---|
|
|
37
|
+
| A test that passes on first run | Probably asserts nothing — break the code, watch it fail (red first) |
|
|
38
|
+
| A large diff | Unreviewable risk; the plan asked for the minimal green change |
|
|
39
|
+
| "Refactored while I was in there" | Scope drift that hides which change broke what |
|
|
40
|
+
| A confident summary of a file you skimmed | A guess — read it or say you didn't |
|
|
41
|
+
| Silencing a failing check to keep moving | Deleting the only warning you'll get |
|
|
42
|
+
| Obeying the plan where it contradicts the code | The code is reality — report the conflict |
|
|
16
43
|
|
|
17
44
|
## Tools Available
|
|
18
45
|
- `draht read-plan N P` — read the plan to execute
|
|
@@ -35,6 +62,9 @@ You are an execution agent. Your job is to implement plans precisely.
|
|
|
35
62
|
4. Fill in the summary with actual commits, files changed, notes
|
|
36
63
|
5. After all plans in phase: `draht verify-phase N`
|
|
37
64
|
|
|
65
|
+
## Summary Format
|
|
66
|
+
Verdict first (what state is the plan in), then evidence (quoted verify output per task), then remaining risk (what you did not verify, labeled as such). Never bury a failed task under completed ones.
|
|
67
|
+
|
|
38
68
|
## Checkpoint Handling
|
|
39
69
|
- `type="auto"` → execute silently
|
|
40
70
|
- `type="checkpoint:human-verify"` → STOP, show what was built, ask for confirmation
|
|
@@ -46,3 +76,11 @@ If a task fails 3 times:
|
|
|
46
76
|
2. Mark task as failed
|
|
47
77
|
3. Continue to next task (unless it depends on the failed one)
|
|
48
78
|
4. Note the failure for fix planning
|
|
79
|
+
|
|
80
|
+
## Send Gate — run before finishing
|
|
81
|
+
|
|
82
|
+
1. **Asked** — did you build what the plan's <done> describes, not just what its literal steps said?
|
|
83
|
+
2. **Evidence** — does every "done" claim quote the output that proves it, with unrun checks labeled "not verified"?
|
|
84
|
+
3. **Attacked** — did each test fail before the implementation made it pass?
|
|
85
|
+
4. **Ordered** — verdict first, evidence second, remaining risk last?
|
|
86
|
+
5. **Wrongness** — if this work is broken, where is it most likely — and did you run that path?
|
|
@@ -12,6 +12,34 @@ You are a planning agent. Your job is to create atomic, executable plans.
|
|
|
12
12
|
3. Maximum 5 tasks per plan
|
|
13
13
|
4. Goal-backward: start from "what must be TRUE" not "what should we build"
|
|
14
14
|
5. Every task needs <verify> and <done> — no ambiguity
|
|
15
|
+
6. 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
|
|
16
|
+
7. Every assumption a plan rests on gets an explicit `Assumes:` line (with how to confirm it) in the plan header — unwritten assumptions become the executor's bugs
|
|
17
|
+
|
|
18
|
+
## Read the Goal Beneath the Goal
|
|
19
|
+
|
|
20
|
+
The phase description says what to build; the plan must capture what must become true.
|
|
21
|
+
|
|
22
|
+
**Procedure:**
|
|
23
|
+
1. Restate the phase goal as the change in the user's world: "after this phase, a user can X."
|
|
24
|
+
2. If the goal names a mechanism ("add Redis caching"), find the outcome behind it ("p95 under 200ms") and plan toward the outcome — the mechanism is a candidate, not a requirement.
|
|
25
|
+
3. If you cannot state the outcome, the phase is not plannable yet — report `NEEDS_CONTEXT` instead of planning the mechanism.
|
|
26
|
+
|
|
27
|
+
**Example:** "add retry logic to the sync job" → the outcome is "syncs recover from transient failures without human help." That truth may need idempotency more than retries; a plan built on the literal words ships retries that double-write.
|
|
28
|
+
|
|
29
|
+
**Prevents:** precisely executing the wrong plan.
|
|
30
|
+
|
|
31
|
+
## Risk-First Ordering
|
|
32
|
+
|
|
33
|
+
Not all tasks deserve equal effort or the same position in the sequence.
|
|
34
|
+
|
|
35
|
+
**Procedure:**
|
|
36
|
+
1. For each observable truth, score uncertainty (has this codebase done it before?) and blast radius (how much of the plan is invalid if it's wrong?).
|
|
37
|
+
2. Order plans and tasks so the highest uncertainty × blast-radius truth is proven first.
|
|
38
|
+
3. Boilerplate goes last — it never invalidates a plan; the risky part regularly does.
|
|
39
|
+
|
|
40
|
+
**Example:** a phase needs a third-party webhook plus a settings UI. The webhook contract is the risk: plan 1 proves an end-to-end webhook round-trip; the UI waits.
|
|
41
|
+
|
|
42
|
+
**Prevents:** discovering in task 9 that the foundation under tasks 1–8 cannot work.
|
|
15
43
|
|
|
16
44
|
## Tools Available
|
|
17
45
|
- `draht load-phase-context N` — gather all context for a phase
|
|
@@ -41,3 +69,11 @@ You are a planning agent. Your job is to create atomic, executable plans.
|
|
|
41
69
|
```
|
|
42
70
|
|
|
43
71
|
Task types: auto, checkpoint:human-verify, checkpoint:decision
|
|
72
|
+
|
|
73
|
+
## Send Gate — run before finishing
|
|
74
|
+
|
|
75
|
+
1. **Asked** — do the plans produce the outcome behind the request, not just its literal words?
|
|
76
|
+
2. **Evidence** — is every claim about the codebase something you read, with assumptions written as `Assumes:` lines?
|
|
77
|
+
3. **Attacked** — did you try to break your own decomposition (a truth with no task, a task with no independent check)?
|
|
78
|
+
4. **Ordered** — does the riskiest truth get proven first?
|
|
79
|
+
5. **Wrongness** — if these plans fail, where is it most likely — and does a task check exactly there?
|
|
@@ -12,6 +12,28 @@ You are a verification agent. Your job is to test completed work against accepta
|
|
|
12
12
|
3. Be honest — if something doesn't work, say so
|
|
13
13
|
4. Create fix plans for failures, don't just report them
|
|
14
14
|
|
|
15
|
+
## Re-Derive, Don't Trust
|
|
16
|
+
|
|
17
|
+
A claim is verified when you have reproduced it, not when it sounds right.
|
|
18
|
+
|
|
19
|
+
**Procedure:**
|
|
20
|
+
1. Never accept a summary's claim ("tests pass", "endpoint works") — re-run the command yourself and read the output.
|
|
21
|
+
2. Every pass verdict cites its observed evidence: the command you ran and the decisive output line.
|
|
22
|
+
3. For each pass, attempt one break: an input, sequence, or state the implementer probably didn't try. A pass you haven't tried to break is only "not yet failed".
|
|
23
|
+
|
|
24
|
+
**Example:** the summary says "auth middleware verified." You re-run the suite — it passes. Then you request a route with an expired token: 500 instead of 401. The claim was true and the work was still broken.
|
|
25
|
+
|
|
26
|
+
**Prevents:** rubber-stamp verification — trust laundered into evidence.
|
|
27
|
+
|
|
28
|
+
## Known vs Guessed
|
|
29
|
+
|
|
30
|
+
Label every statement in your report:
|
|
31
|
+
- **observed** — you ran it and saw it
|
|
32
|
+
- **derived** — follows necessarily from something observed
|
|
33
|
+
- **assumed** — believed but unchecked, with what would check it
|
|
34
|
+
|
|
35
|
+
A verdict inherits the weakest label it rests on: an "assumed pass" is not a pass — test it or mark the deliverable partial.
|
|
36
|
+
|
|
15
37
|
## Tools Available
|
|
16
38
|
- `draht extract-deliverables N` — list testable items
|
|
17
39
|
- `draht create-fix-plan N P "issue"` — create fix plan for failures
|
|
@@ -31,7 +53,17 @@ You are a verification agent. Your job is to test completed work against accepta
|
|
|
31
53
|
5. Update state: `draht update-state`
|
|
32
54
|
|
|
33
55
|
## Output
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
56
|
+
Answer first, reasoning second, risk last:
|
|
57
|
+
1. **Verdict** — X/Y passed, phase pass/fail, in the first line
|
|
58
|
+
2. **Evidence** — per deliverable: what you ran, what you observed, its label (observed/derived/assumed)
|
|
59
|
+
3. **Risk** — what was NOT tested and how it could bite; fix plans created; recommended next action
|
|
60
|
+
|
|
61
|
+
Never bury a failure under a list of passes.
|
|
62
|
+
|
|
63
|
+
## Send Gate — run before finishing
|
|
64
|
+
|
|
65
|
+
1. **Asked** — did you test what the user needs to be true, not just what the developer built?
|
|
66
|
+
2. **Evidence** — is every pass backed by output you personally observed this session?
|
|
67
|
+
3. **Attacked** — did you try to break each pass at least once?
|
|
68
|
+
4. **Ordered** — verdict first, evidence second, risk last?
|
|
69
|
+
5. **Wrongness** — if this UAT is wrong, which verdict is most likely the false one — and did you re-check it?
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Refine a fuzzy idea into a written design spec before planning or coding"
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# /brainstorm
|
|
6
|
+
|
|
7
|
+
The pre-planning gate. Before draht's GSD cycle runs, before code is scaffolded, before `/new-project` or `/init-project`, converge on the idea through dialogue and write it to `.planning/specs/`. This command enforces design-first discipline.
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
```
|
|
11
|
+
/brainstorm [idea or topic]
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Topic: $ARGUMENTS
|
|
15
|
+
|
|
16
|
+
## Atomic Reasoning
|
|
17
|
+
|
|
18
|
+
Before asking anything, decompose the idea into atomic reasoning units:
|
|
19
|
+
|
|
20
|
+
1. **State the logical component** — What problem does this solve? Who is it for? What changes for them when it ships?
|
|
21
|
+
2. **Validate independence** — What bounded contexts will exist? What is core vs peripheral? What can be built independently?
|
|
22
|
+
3. **Verify correctness** — What defines v1 success? What constraints exist (time, tech, team)? What is explicitly out of scope?
|
|
23
|
+
|
|
24
|
+
**Synthesize design strategy:**
|
|
25
|
+
- Ground questions in what is already on disk instead of asking what the user already told you
|
|
26
|
+
- Sequence questions foundational → detailed, one at a time
|
|
27
|
+
- Surface 2–3 approaches with trade-offs before committing
|
|
28
|
+
- Record decisions (not proposals) in a spec file
|
|
29
|
+
|
|
30
|
+
## Hear the Problem Beneath the Ask
|
|
31
|
+
|
|
32
|
+
The user's words describe an artifact; the design must serve a need. They are rarely the same thing.
|
|
33
|
+
|
|
34
|
+
**Procedure:**
|
|
35
|
+
1. Separate the stated artifact ("a dashboard") from the underlying need — what decision, pain, or moment does it serve?
|
|
36
|
+
2. When the user names a solution, ask what it solves before refining it. Solutions stay candidates until the need is confirmed.
|
|
37
|
+
3. State the need back in one sentence ("so the real problem is X — right?") and get an explicit yes before proposing any approach.
|
|
38
|
+
|
|
39
|
+
**Example:** "I want an admin dashboard" → questioning reveals they check one number, once a week → a scheduled email beats the dashboard by a month of build time.
|
|
40
|
+
|
|
41
|
+
**Prevents:** a polished spec for the wrong artifact.
|
|
42
|
+
|
|
43
|
+
## The Hard Gate
|
|
44
|
+
|
|
45
|
+
> Do NOT invoke any planning command, write any code, scaffold any project, or take any implementation action until you have:
|
|
46
|
+
> 1. Asked clarifying questions one at a time
|
|
47
|
+
> 2. Proposed 2–3 approaches with trade-offs
|
|
48
|
+
> 3. Presented a structured design and the user has approved it
|
|
49
|
+
> 4. Written the design to `.planning/specs/YYYY-MM-DD-<slug>-design.md`
|
|
50
|
+
|
|
51
|
+
If the user pushes to skip ("just build it"), surface the trade-off: "I can scaffold something now, but skipping brainstorming usually means we throw out the first version. Are you sure?" If yes, proceed but make the assumption explicit in the spec.
|
|
52
|
+
|
|
53
|
+
## The Process
|
|
54
|
+
|
|
55
|
+
### 1. Explore Context
|
|
56
|
+
|
|
57
|
+
Before asking anything, read what's already on disk:
|
|
58
|
+
- `git log --oneline -30` — what has the user been working on recently?
|
|
59
|
+
- `ls -la` — what's in the project root?
|
|
60
|
+
- `.planning/` if it exists — is there an active project?
|
|
61
|
+
- `README.md`, `package.json`, any `*.md` in root — what does this codebase claim to do?
|
|
62
|
+
|
|
63
|
+
If an existing codebase is in play (extending a real project), run `draht-tools map-codebase` + `draht-tools graph-hotspots` first to ground ideation in the real structure — so brainstormed ideas don't contradict existing architecture.
|
|
64
|
+
|
|
65
|
+
Use this to ground questions in reality instead of asking things the user has already told you.
|
|
66
|
+
|
|
67
|
+
### 2. Ask Clarifying Questions — ONE at a time
|
|
68
|
+
|
|
69
|
+
Most failed projects come from rushing past ambiguity. Ask **one focused question per message**, not a long list. Wait for the answer, then ask the next.
|
|
70
|
+
|
|
71
|
+
Question categories (sequence from foundational → detailed):
|
|
72
|
+
- **Goal** — who is this for? what changes for them when it ships?
|
|
73
|
+
- **Constraints** — deadline? budget? team size? language/stack preferences?
|
|
74
|
+
- **Scope** — what's in v1? what's explicitly NOT in v1?
|
|
75
|
+
- **Success criteria** — how do we know it works? what's the demoable outcome?
|
|
76
|
+
- **Domain** — what are the key nouns and verbs in this space? any existing glossary?
|
|
77
|
+
- **Risks** — what's the scariest part of this? what would make it fail?
|
|
78
|
+
|
|
79
|
+
If the project is obviously oversized for one cycle (e.g., "I want to build a social network"), flag it explicitly and propose decomposition into a v1 / v2 / out-of-scope split.
|
|
80
|
+
|
|
81
|
+
### 3. Propose 2–3 Approaches With Trade-offs
|
|
82
|
+
|
|
83
|
+
Once you have enough context, propose multiple approaches:
|
|
84
|
+
- Approach A: the simplest path. What it sacrifices.
|
|
85
|
+
- Approach B: the most flexible. What it costs.
|
|
86
|
+
- (Optional) Approach C: the most ambitious. Why it's tempting and why it might be too much.
|
|
87
|
+
|
|
88
|
+
For each: list trade-offs in plain language (time, complexity, future flexibility, lock-in). Let the user pick — don't pre-pick for them.
|
|
89
|
+
|
|
90
|
+
### 4. Present the Design in Sections, Each With an Approval Gate
|
|
91
|
+
|
|
92
|
+
Once an approach is chosen, present the design **section by section**, not all at once:
|
|
93
|
+
1. Goal & non-goals
|
|
94
|
+
2. User stories / observable truths
|
|
95
|
+
3. Domain model (bounded contexts, key nouns)
|
|
96
|
+
4. Architecture sketch (components, data flow)
|
|
97
|
+
5. v1 scope (what ships) vs v2/out-of-scope (what doesn't)
|
|
98
|
+
6. Open questions / risks
|
|
99
|
+
|
|
100
|
+
After each section, ask: "Does this match what you want, or should we adjust?" Only move to the next section once the current one is approved.
|
|
101
|
+
|
|
102
|
+
### 5. Write the Spec to `.planning/specs/`
|
|
103
|
+
|
|
104
|
+
Once all sections are approved:
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
.planning/specs/YYYY-MM-DD-<topic-slug>-design.md
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The file should include:
|
|
111
|
+
- Header with date and approver
|
|
112
|
+
- All approved sections
|
|
113
|
+
- Open questions section (the things you flagged but didn't resolve)
|
|
114
|
+
- Next step: which command picks this up (`/new-project` or `/init-project`)
|
|
115
|
+
|
|
116
|
+
### 6. Self-Review the Written Spec
|
|
117
|
+
|
|
118
|
+
Before handing off, attack the spec as if you were paid to kill it:
|
|
119
|
+
- Contradictions between sections (the goal says X, the architecture implies not-X)
|
|
120
|
+
- Gaps (a user story with no architectural support)
|
|
121
|
+
- Premature commitments (specific tech choices made before they were needed)
|
|
122
|
+
- Domain language drift (different names for the same thing)
|
|
123
|
+
- The strongest case the whole design is wrong — wrong scope, wrong user, or already exists as a simpler tool. Write that case and why the design survives it into the spec's Open Questions.
|
|
124
|
+
|
|
125
|
+
Report any findings to the user and update before proceeding. A spec that was never attacked has never been tested.
|
|
126
|
+
|
|
127
|
+
### 7. Hand Off
|
|
128
|
+
|
|
129
|
+
Direct the user to the next command:
|
|
130
|
+
- Greenfield with no codebase → `/new-project`
|
|
131
|
+
- Existing codebase → `/init-project`
|
|
132
|
+
|
|
133
|
+
The spec file becomes input to those commands.
|
|
134
|
+
|
|
135
|
+
## Workflow
|
|
136
|
+
|
|
137
|
+
`/brainstorm` runs before any project initialization. Each later step runs in its own session (`/new` between steps):
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
/brainstorm → /new → /new-project (or /init-project) → /new → /discuss-phase 1 → /new → /plan-phase 1 → ...
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Anti-Patterns — STOP
|
|
144
|
+
|
|
145
|
+
- **Asking multiple questions in one message** — splits the user's attention, lowers answer quality
|
|
146
|
+
- **Pre-deciding before they've answered** — "I'll just assume you mean X" is a failure mode
|
|
147
|
+
- **Skipping the alternatives** — proposing only one approach hides the trade-space
|
|
148
|
+
- **Writing the spec before approval** — the spec records *decisions*, not *proposals*. Get the decision first.
|
|
149
|
+
- **Brainstorming code** — this command is for the design, not the implementation. Resist the urge to start writing.
|
|
150
|
+
|
|
151
|
+
## Rationalization Table
|
|
152
|
+
|
|
153
|
+
| Excuse | Reality |
|
|
154
|
+
|--------|---------|
|
|
155
|
+
| "It's a simple project, no need to brainstorm" | Simple projects also have ambiguous scope. The gate is fast for simple ones. |
|
|
156
|
+
| "User said 'just build it'" | They'll be unhappier when the wrong thing gets built. Surface the trade-off. |
|
|
157
|
+
| "I already know what they want" | Verify by stating it back and getting confirmation. |
|
|
158
|
+
| "Let's iterate after a first draft" | A first draft in code is more expensive to throw away than a first draft on paper. |
|
|
159
|
+
|
|
160
|
+
## Output
|
|
161
|
+
|
|
162
|
+
Brainstorming ends with a written spec file in `.planning/specs/`. That file is the artifact. If no file is written, the command did not complete.
|
|
@@ -33,7 +33,7 @@ Before questioning, decompose this phase scope into atomic reasoning units:
|
|
|
33
33
|
2. Identify gray areas based on what's being built
|
|
34
34
|
3. Present 1-2 questions at a time about preferences
|
|
35
35
|
4. If `.planning/DOMAIN.md` exists, load it and validate discovered terms against the glossary. Add any new domain terms found during discussion.
|
|
36
|
-
5. Record decisions with `draht-tools save-context $1`
|
|
36
|
+
5. Record decisions with `draht-tools save-context $1` — label each entry **decided** (the user explicitly chose) or **assumed** (you inferred from context). Assumed entries are flagged for confirmation; a plan built on an unlabeled assumption fails silently later.
|
|
37
37
|
6. Commit: `draht-tools commit-docs "capture phase $1 context"`
|
|
38
38
|
|
|
39
39
|
## Workflow
|
|
@@ -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.
|
|
@@ -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).
|
|
@@ -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:
|
|
@@ -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
|
|
@@ -45,7 +45,7 @@ Before analyzing, decompose codebase understanding into atomic reasoning units:
|
|
|
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)
|
|
@@ -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
|
|
@@ -62,5 +62,7 @@ Before planning the next milestone, decompose progress into atomic reasoning uni
|
|
|
62
62
|
|
|
63
63
|
## Rules
|
|
64
64
|
- Always review what was actually built, not just what was planned
|
|
65
|
+
- 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
66
|
- Be honest about requirements that slipped or changed scope
|
|
66
67
|
- Each phase goal must be testable — "user can X" not "implement Y"
|
|
68
|
+
- 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
|
|
@@ -15,9 +15,9 @@ Task: $ARGUMENTS
|
|
|
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
|
|
@@ -61,7 +61,7 @@ Never run quality review on a spec-non-compliant diff. This is the per-task loop
|
|
|
61
61
|
|
|
62
62
|
Every draht agent ends its response with one of four status lines. Branch on it:
|
|
63
63
|
|
|
64
|
-
- `STATUS: DONE` —
|
|
64
|
+
- `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
65
|
- `STATUS: DONE_WITH_CONCERNS` — note the concerns. If correctness-related, address before moving on; otherwise log and continue.
|
|
66
66
|
- `STATUS: NEEDS_CONTEXT` — provide the missing info and re-dispatch the same agent. Do NOT skip ahead with a guess.
|
|
67
67
|
- `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,7 +72,7 @@ Every draht agent ends its response with one of four status lines. Branch on it:
|
|
|
72
72
|
3. Decide parallel vs chain vs fan-out vs two-stage based on dependencies
|
|
73
73
|
4. Dispatch via the `subagent` tool accordingly
|
|
74
74
|
5. Read each subagent's final `STATUS:` line and branch per the protocol above
|
|
75
|
-
6. Collect results, handle failures, report the
|
|
75
|
+
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
76
|
|
|
77
77
|
## Rules
|
|
78
78
|
- Prefer parallel dispatch when possible — it's faster and each subagent has its own context
|
|
@@ -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,11 +36,15 @@ 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
|
|
@@ -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:
|
|
@@ -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
|
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"rpc-entry.d.ts","sourceRoot":"","sources":["../src/rpc-entry.ts"],"names":[],"mappings":"","sourcesContent":["#!/usr/bin/env node\nimport { APP_NAME } from \"./config.ts\";\nimport { configureHttpDispatcher } from \"./core/http-dispatcher.ts\";\nimport { main } from \"./main.ts\";\n\nprocess.title = `${APP_NAME}-rpc`;\nprocess.env.DRAHT_CODING_AGENT = \"true\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\nconfigureHttpDispatcher();\n\nmain([\"--mode\", \"rpc\", ...process.argv.slice(2)]);\n"]}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { APP_NAME } from "./config.js";
|
|
3
|
+
import { configureHttpDispatcher } from "./core/http-dispatcher.js";
|
|
4
|
+
import { main } from "./main.js";
|
|
5
|
+
process.title = `${APP_NAME}-rpc`;
|
|
6
|
+
process.env.DRAHT_CODING_AGENT = "true";
|
|
7
|
+
process.emitWarning = (() => { });
|
|
8
|
+
configureHttpDispatcher();
|
|
9
|
+
main(["--mode", "rpc", ...process.argv.slice(2)]);
|
|
10
|
+
//# sourceMappingURL=rpc-entry.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"rpc-entry.js","sourceRoot":"","sources":["../src/rpc-entry.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,CAAC,KAAK,GAAG,GAAG,QAAQ,MAAM,CAAC;AAClC,OAAO,CAAC,GAAG,CAAC,kBAAkB,GAAG,MAAM,CAAC;AACxC,OAAO,CAAC,WAAW,GAAG,CAAC,GAAG,EAAE,CAAC,EAAC,CAAC,CAA+B,CAAC;AAE/D,uBAAuB,EAAE,CAAC;AAE1B,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { APP_NAME } from \"./config.ts\";\nimport { configureHttpDispatcher } from \"./core/http-dispatcher.ts\";\nimport { main } from \"./main.ts\";\n\nprocess.title = `${APP_NAME}-rpc`;\nprocess.env.DRAHT_CODING_AGENT = \"true\";\nprocess.emitWarning = (() => {}) as typeof process.emitWarning;\n\nconfigureHttpDispatcher();\n\nmain([\"--mode\", \"rpc\", ...process.argv.slice(2)]);\n"]}
|
|
@@ -6,10 +6,13 @@ export declare function spawnProcessSync(command: string, args: string[], option
|
|
|
6
6
|
/**
|
|
7
7
|
* Wait for a child process to terminate without hanging on inherited stdio handles.
|
|
8
8
|
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
9
|
+
* A short-lived child can `exit` while a detached descendant keeps its stdout/stderr
|
|
10
|
+
* pipe open. We must not resolve and destroy the streams on a fixed deadline measured
|
|
11
|
+
* from `exit`, or output still being written past that deadline is silently lost
|
|
12
|
+
* (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:
|
|
13
|
+
* the grace timer is re-armed on every chunk, so an actively writing descendant keeps
|
|
14
|
+
* us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant
|
|
15
|
+
* that never lets `close` fire) still releases us after the grace elapses.
|
|
13
16
|
*/
|
|
14
17
|
export declare function waitForChildProcess(child: ChildProcess): Promise<number | null>;
|
|
15
18
|
//# sourceMappingURL=child-process.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"child-process.d.ts","sourceRoot":"","sources":["../../src/utils/child-process.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAGxB,KAAK,YAAY,EACjB,KAAK,0BAA0B,EAC/B,KAAK,kCAAkC,EACvC,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,GAClE,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;AAKnG,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,kCAAkC,GACzC,gBAAgB,CAAC,MAAM,CAAC,CAI1B;AAED
|
|
1
|
+
{"version":3,"file":"child-process.d.ts","sourceRoot":"","sources":["../../src/utils/child-process.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAGxB,KAAK,YAAY,EACjB,KAAK,0BAA0B,EAC/B,KAAK,kCAAkC,EACvC,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,GAClE,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;AAKnG,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,kCAAkC,GACzC,gBAAgB,CAAC,MAAM,CAAC,CAI1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAwF/E","sourcesContent":["import {\n\ttype ChildProcess,\n\ttype ChildProcessByStdio,\n\tspawn as nodeSpawn,\n\tspawnSync as nodeSpawnSync,\n\ttype SpawnOptions,\n\ttype SpawnOptionsWithStdioTuple,\n\ttype SpawnSyncOptionsWithStringEncoding,\n\ttype SpawnSyncReturns,\n\ttype StdioNull,\n\ttype StdioPipe,\n} from \"node:child_process\";\nimport type { Readable } from \"node:stream\";\nimport crossSpawn from \"cross-spawn\";\n\nconst EXIT_STDIO_GRACE_MS = 100;\n\nexport function spawnProcess(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>,\n): ChildProcessByStdio<null, Readable, Readable>;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess {\n\treturn process.platform === \"win32\" ? crossSpawn(command, args, options) : nodeSpawn(command, args, options);\n}\n\nexport function spawnProcessSync(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnSyncOptionsWithStringEncoding,\n): SpawnSyncReturns<string> {\n\treturn process.platform === \"win32\"\n\t\t? crossSpawn.sync(command, args, options)\n\t\t: nodeSpawnSync(command, args, options);\n}\n\n/**\n * Wait for a child process to terminate without hanging on inherited stdio handles.\n *\n * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr\n * pipe open. We must not resolve and destroy the streams on a fixed deadline measured\n * from `exit`, or output still being written past that deadline is silently lost\n * (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:\n * the grace timer is re-armed on every chunk, so an actively writing descendant keeps\n * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant\n * that never lets `close` fire) still releases us after the grace elapses.\n */\nexport function waitForChildProcess(child: ChildProcess): Promise<number | null> {\n\treturn new Promise((resolve, reject) => {\n\t\tlet settled = false;\n\t\tlet exited = false;\n\t\tlet exitCode: number | null = null;\n\t\tlet postExitTimer: NodeJS.Timeout | undefined;\n\t\tlet stdoutEnded = child.stdout === null;\n\t\tlet stderrEnded = child.stderr === null;\n\n\t\tconst cleanup = () => {\n\t\t\tif (postExitTimer) {\n\t\t\t\tclearTimeout(postExitTimer);\n\t\t\t\tpostExitTimer = undefined;\n\t\t\t}\n\t\t\tchild.removeListener(\"error\", onError);\n\t\t\tchild.removeListener(\"exit\", onExit);\n\t\t\tchild.removeListener(\"close\", onClose);\n\t\t\tchild.stdout?.removeListener(\"end\", onStdoutEnd);\n\t\t\tchild.stderr?.removeListener(\"end\", onStderrEnd);\n\t\t\tchild.stdout?.removeListener(\"data\", onData);\n\t\t\tchild.stderr?.removeListener(\"data\", onData);\n\t\t};\n\n\t\tconst finalize = (code: number | null) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\tchild.stdout?.destroy();\n\t\t\tchild.stderr?.destroy();\n\t\t\tresolve(code);\n\t\t};\n\n\t\tconst maybeFinalizeAfterExit = () => {\n\t\t\tif (!exited || settled) return;\n\t\t\tif (stdoutEnded && stderrEnded) {\n\t\t\t\tfinalize(exitCode);\n\t\t\t}\n\t\t};\n\n\t\tconst armIdleTimer = () => {\n\t\t\tif (postExitTimer) clearTimeout(postExitTimer);\n\t\t\tpostExitTimer = setTimeout(() => finalize(exitCode), EXIT_STDIO_GRACE_MS);\n\t\t};\n\n\t\tconst onData = () => {\n\t\t\t// Output is still arriving after exit; defer finalizing so we don't\n\t\t\t// destroy the stream mid-write and truncate the tail.\n\t\t\tif (exited && !settled) armIdleTimer();\n\t\t};\n\n\t\tconst onStdoutEnd = () => {\n\t\t\tstdoutEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onStderrEnd = () => {\n\t\t\tstderrEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onError = (err: Error) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(err);\n\t\t};\n\n\t\tconst onExit = (code: number | null) => {\n\t\t\texited = true;\n\t\t\texitCode = code;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t\tif (!settled) {\n\t\t\t\tarmIdleTimer();\n\t\t\t}\n\t\t};\n\n\t\tconst onClose = (code: number | null) => {\n\t\t\tfinalize(code);\n\t\t};\n\n\t\tchild.stdout?.once(\"end\", onStdoutEnd);\n\t\tchild.stderr?.once(\"end\", onStderrEnd);\n\t\tchild.stdout?.on(\"data\", onData);\n\t\tchild.stderr?.on(\"data\", onData);\n\t\tchild.once(\"error\", onError);\n\t\tchild.once(\"exit\", onExit);\n\t\tchild.once(\"close\", onClose);\n\t});\n}\n"]}
|