peaks-loop 4.1.4 → 4.1.5

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.
Files changed (240) hide show
  1. package/.claude-plugin/marketplace.json +7 -2
  2. package/CHANGELOG.md +112 -0
  3. package/README-en.md +1 -1
  4. package/README.md +1 -1
  5. package/dist/cli/cli-helpers.d.ts +20 -0
  6. package/dist/cli/cli-helpers.js +34 -0
  7. package/dist/cli/commands/_register.js +2 -0
  8. package/dist/cli/commands/code-commands.d.ts +6 -4
  9. package/dist/cli/commands/code-commands.js +6 -4
  10. package/dist/cli/commands/code-gate-command.d.ts +5 -5
  11. package/dist/cli/commands/code-gate-command.js +49 -9
  12. package/dist/cli/commands/code-mode-gate-plan-command.d.ts +1 -1
  13. package/dist/cli/commands/code-mode-gate-plan-command.js +2 -2
  14. package/dist/cli/commands/core/memory-extract-command.js +10 -5
  15. package/dist/cli/commands/dispatch-cli-invocation-check.d.ts +108 -0
  16. package/dist/cli/commands/dispatch-cli-invocation-check.js +87 -0
  17. package/dist/cli/commands/dispatch-cli-invocation-scan.d.ts +66 -0
  18. package/dist/cli/commands/dispatch-cli-invocation-scan.js +162 -0
  19. package/dist/cli/commands/dispatch-commands.js +12 -5
  20. package/dist/cli/commands/dispatch-preflight.js +46 -0
  21. package/dist/cli/commands/dispatch-prompt-composition.d.ts +6 -0
  22. package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
  23. package/dist/cli/commands/doc-commands.js +1 -1
  24. package/dist/cli/commands/feedback-commands-helpers.js +1 -1
  25. package/dist/cli/commands/final-review-prepare-command.js +22 -1
  26. package/dist/cli/commands/gate-commands-enforce.js +3 -3
  27. package/dist/cli/commands/hook-handle.js +41 -20
  28. package/dist/cli/commands/lint-commands.js +3 -1
  29. package/dist/cli/commands/loop-eval-capture-index.js +2 -4
  30. package/dist/cli/commands/perf-audit-commands.js +15 -5
  31. package/dist/cli/commands/project-commands.js +9 -6
  32. package/dist/cli/commands/race-commands.d.ts +15 -0
  33. package/dist/cli/commands/race-commands.js +65 -0
  34. package/dist/cli/commands/race-pilot-gate-record-command.d.ts +3 -0
  35. package/dist/cli/commands/race-pilot-gate-record-command.js +81 -0
  36. package/dist/cli/commands/request-command-options.d.ts +8 -0
  37. package/dist/cli/commands/request-commands.js +2 -0
  38. package/dist/cli/commands/request-init-command.js +67 -12
  39. package/dist/cli/commands/request-retag-command.d.ts +3 -0
  40. package/dist/cli/commands/request-retag-command.js +50 -0
  41. package/dist/cli/commands/request-show-command.d.ts +8 -0
  42. package/dist/cli/commands/request-show-command.js +14 -1
  43. package/dist/cli/commands/request-transition-command.js +12 -4
  44. package/dist/cli/commands/request-transition-failures.d.ts +14 -0
  45. package/dist/cli/commands/request-transition-failures.js +45 -3
  46. package/dist/cli/commands/scan-scope-commands.js +2 -2
  47. package/dist/cli/commands/security-audit-commands.js +26 -6
  48. package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
  49. package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
  50. package/dist/services/artifacts/artifact-contract-block.js +212 -0
  51. package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
  52. package/dist/services/artifacts/artifact-prerequisites.js +63 -133
  53. package/dist/services/artifacts/artifact-templates.d.ts +1 -1
  54. package/dist/services/artifacts/artifact-templates.js +17 -10
  55. package/dist/services/artifacts/prerequisite-checks.d.ts +87 -0
  56. package/dist/services/artifacts/prerequisite-checks.js +198 -0
  57. package/dist/services/artifacts/prerequisite-transition-event.d.ts +20 -0
  58. package/dist/services/artifacts/prerequisite-transition-event.js +27 -0
  59. package/dist/services/artifacts/request-artifact-metadata.d.ts +31 -0
  60. package/dist/services/artifacts/request-artifact-metadata.js +44 -0
  61. package/dist/services/artifacts/request-artifact-service.d.ts +5 -0
  62. package/dist/services/artifacts/request-artifact-service.js +23 -51
  63. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +12 -0
  64. package/dist/services/artifacts/request-artifact-state-helpers.js +28 -4
  65. package/dist/services/artifacts/request-retag-service.d.ts +68 -0
  66. package/dist/services/artifacts/request-retag-service.js +125 -0
  67. package/dist/services/artifacts/request-state-order.d.ts +38 -0
  68. package/dist/services/artifacts/request-state-order.js +99 -0
  69. package/dist/services/artifacts/request-type-demand.d.ts +44 -0
  70. package/dist/services/artifacts/request-type-demand.js +71 -0
  71. package/dist/services/audit/audit-goal-service.d.ts +7 -0
  72. package/dist/services/audit/enforcers/active-skill-resolver.d.ts +18 -0
  73. package/dist/services/audit/enforcers/active-skill-resolver.js +48 -1
  74. package/dist/services/audit/enforcers/code-ban.d.ts +11 -2
  75. package/dist/services/audit/enforcers/code-ban.js +21 -1
  76. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.d.ts +17 -0
  77. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.js +24 -7
  78. package/dist/services/audit-independent/handoff-missing-refusal.d.ts +26 -0
  79. package/dist/services/audit-independent/handoff-missing-refusal.js +109 -0
  80. package/dist/services/audit-independent/handoff-readers.d.ts +37 -0
  81. package/dist/services/audit-independent/handoff-readers.js +81 -0
  82. package/dist/services/audit-independent/index.d.ts +6 -1
  83. package/dist/services/audit-independent/index.js +6 -1
  84. package/dist/services/audit-independent/judged-declaration-build.d.ts +48 -0
  85. package/dist/services/audit-independent/judged-declaration-build.js +73 -0
  86. package/dist/services/audit-independent/judged-declaration-check.d.ts +79 -0
  87. package/dist/services/audit-independent/judged-declaration-check.js +155 -0
  88. package/dist/services/audit-independent/judged-declaration.d.ts +94 -0
  89. package/dist/services/audit-independent/judged-declaration.js +218 -0
  90. package/dist/services/audit-independent/perf-audit-service.js +12 -14
  91. package/dist/services/audit-independent/security-audit-artifact.d.ts +28 -0
  92. package/dist/services/audit-independent/security-audit-artifact.js +90 -0
  93. package/dist/services/audit-independent/security-audit-service.d.ts +6 -53
  94. package/dist/services/audit-independent/security-audit-service.js +34 -178
  95. package/dist/services/capability-guard-runner/contracts/J05.js +60 -14
  96. package/dist/services/codegraph/codegraph-index-integrity.js +2 -0
  97. package/dist/services/context/build-dispatch-system-prompt.d.ts +3 -3
  98. package/dist/services/context/build-dispatch-system-prompt.js +7 -7
  99. package/dist/services/context/collector.js +5 -1
  100. package/dist/services/dispatch/active-dispatch-index.d.ts +36 -0
  101. package/dist/services/dispatch/active-dispatch-index.js +118 -0
  102. package/dist/services/dispatch/batch-counter.js +1 -2
  103. package/dist/services/dispatch/dispatch-record-writer.d.ts +29 -16
  104. package/dist/services/dispatch/dispatch-record-writer.js +58 -100
  105. package/dist/services/dispatch/dispatch-sub-agent.js +1 -1
  106. package/dist/services/dispatch/karpathy-block.d.ts +55 -0
  107. package/dist/services/dispatch/karpathy-block.js +101 -0
  108. package/dist/services/dispatch/ledger-reaper.d.ts +80 -0
  109. package/dist/services/dispatch/ledger-reaper.js +131 -0
  110. package/dist/services/evidence/evidence-generator.js +15 -8
  111. package/dist/services/feedback/feedback-promotion-service.d.ts +8 -11
  112. package/dist/services/feedback/feedback-promotion-service.js +30 -35
  113. package/dist/services/feedback/promotion-artifact-json-evidence.d.ts +18 -0
  114. package/dist/services/feedback/promotion-artifact-missing.d.ts +22 -0
  115. package/dist/services/feedback/promotion-artifact-missing.js +63 -0
  116. package/dist/services/final-review/final-review-contract.d.ts +95 -4
  117. package/dist/services/final-review/final-review-contract.js +64 -0
  118. package/dist/services/final-review/final-review-delivery.d.ts +13 -0
  119. package/dist/services/final-review/final-review-delivery.js +26 -12
  120. package/dist/services/final-review/final-review-evidence-collect.js +8 -53
  121. package/dist/services/final-review/final-review-evidence-records.d.ts +21 -0
  122. package/dist/services/final-review/final-review-evidence-records.js +67 -0
  123. package/dist/services/final-review/final-review-evidence-sources.d.ts +22 -0
  124. package/dist/services/final-review/final-review-evidence-sources.js +28 -4
  125. package/dist/services/final-review/final-review-prompt.js +19 -6
  126. package/dist/services/final-review/final-review-runner.js +5 -0
  127. package/dist/services/final-review/final-review-service.d.ts +2 -2
  128. package/dist/services/final-review/index.d.ts +1 -1
  129. package/dist/services/final-review/pre-post-diff.d.ts +2 -75
  130. package/dist/services/final-review/pre-post-diff.js +60 -59
  131. package/dist/services/hooks/pre-tool-code-gate.d.ts +7 -1
  132. package/dist/services/hooks/pre-tool-code-gate.js +21 -2
  133. package/dist/services/hooks/worktree-authorization-gate.js +6 -31
  134. package/dist/services/hooks/worktree-refusal-messages.d.ts +74 -0
  135. package/dist/services/hooks/worktree-refusal-messages.js +102 -0
  136. package/dist/services/lint/eslint-runner-support.d.ts +1 -1
  137. package/dist/services/lint/eslint-runner-support.js +2 -1
  138. package/dist/services/lint/eslint-runner-types.d.ts +8 -0
  139. package/dist/services/lint/eslint-runner.js +17 -4
  140. package/dist/services/llm/anthropic-runner.js +24 -7
  141. package/dist/services/loop/loop-observability.d.ts +39 -0
  142. package/dist/services/loop/loop-observability.js +55 -0
  143. package/dist/services/loop/monotonic-guard.js +6 -9
  144. package/dist/services/loop/monotonic-runner.js +8 -7
  145. package/dist/services/loop/run-driver.js +18 -22
  146. package/dist/services/memory/project-memory-service/index/kind-dispatch.js +14 -1
  147. package/dist/services/memory/project-memory-service/index/project-memory-plan-exec.js +13 -2
  148. package/dist/services/memory/project-memory-service/index.d.ts +2 -2
  149. package/dist/services/memory/project-memory-service/index.js +1 -1
  150. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.d.ts +36 -0
  151. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.js +48 -2
  152. package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts +23 -1
  153. package/dist/services/memory/project-memory-service/parsers/markdown-pure.js +37 -0
  154. package/dist/services/memory/project-memory-service/types.d.ts +32 -0
  155. package/dist/services/observability/observability-service.d.ts +7 -0
  156. package/dist/services/observability/observability-service.js +2 -1
  157. package/dist/services/prd/gate-evidence-derivation.d.ts +4 -3
  158. package/dist/services/prd/gate-evidence-derivation.js +4 -3
  159. package/dist/services/qa/bdd-test-style-verifier.js +22 -8
  160. package/dist/services/race/gate2-evaluator.d.ts +58 -0
  161. package/dist/services/race/gate2-evaluator.js +111 -0
  162. package/dist/services/race/gate2-policy.d.ts +17 -0
  163. package/dist/services/race/gate2-policy.js +31 -0
  164. package/dist/services/race/lane-phase.d.ts +19 -0
  165. package/dist/services/race/lane-phase.js +113 -0
  166. package/dist/services/race/pilot-gate-store.d.ts +67 -0
  167. package/dist/services/race/pilot-gate-store.js +227 -0
  168. package/dist/services/scan/file-size-baseline.d.ts +26 -0
  169. package/dist/services/scan/file-size-baseline.js +150 -0
  170. package/dist/services/scan/file-size-scan.d.ts +42 -3
  171. package/dist/services/scan/file-size-scan.js +58 -42
  172. package/dist/services/scan/type-sanity-service.js +13 -3
  173. package/dist/services/skill/resume-detector.js +3 -3
  174. package/dist/services/skills/hooks-codegate-superpowers.d.ts +5 -6
  175. package/dist/services/skills/hooks-codegate-superpowers.js +7 -8
  176. package/dist/services/skills/hooks-settings-service.d.ts +1 -1
  177. package/dist/services/skills/hooks-settings-service.js +1 -1
  178. package/dist/services/skills/presence-lease-order.d.ts +13 -0
  179. package/dist/services/skills/presence-lease-order.js +24 -0
  180. package/dist/services/skills/skill-conformance-service.js +1 -0
  181. package/dist/services/skills/skill-statusline-service.js +4 -7
  182. package/dist/services/slice/slice-check-service.js +8 -8
  183. package/dist/services/workflow/pipeline-verify-gate-support.js +2 -1
  184. package/dist/services/workflow/pipeline-verify-service.js +1 -1
  185. package/dist/services/workflow/workflow-skip-service.d.ts +0 -20
  186. package/dist/services/workflow/workflow-skip-service.js +3 -4
  187. package/dist/services/workspace/claude-settings-retirements.d.ts +54 -0
  188. package/dist/services/workspace/claude-settings-retirements.js +112 -0
  189. package/dist/services/workspace/claude-settings-template-merge.d.ts +35 -15
  190. package/dist/services/workspace/claude-settings-template-merge.js +33 -53
  191. package/dist/services/workspace/claude-settings-template.d.ts +62 -12
  192. package/dist/services/workspace/claude-settings-template.js +58 -58
  193. package/dist/services/workspace/migrate-1-4-1-service.js +3 -0
  194. package/dist/services/workspace/reconcile-service.js +0 -1
  195. package/dist/shared/incrementing-number.d.ts +10 -0
  196. package/dist/shared/incrementing-number.js +27 -0
  197. package/package.json +5 -5
  198. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  199. package/skills/bee/peaks-prd/SKILL.md +1 -1
  200. package/skills/bee/peaks-qa/SKILL.md +1 -1
  201. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  202. package/skills/bee/peaks-qa/references/qa-transition-gates.md +1 -1
  203. package/skills/bee/peaks-rd/SKILL.md +2 -2
  204. package/skills/bee/peaks-rd/references/rd-fanout-contracts.md +1 -1
  205. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +8 -4
  206. package/skills/bee/peaks-rd/references/rd-transition-gates.md +3 -3
  207. package/skills/bee/peaks-rd/references/v2-12-fanout-collapse.md +2 -2
  208. package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md +1 -1
  209. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  210. package/skills/bee/peaks-sc/SKILL.md +1 -1
  211. package/skills/bee/peaks-security-audit/SKILL.md +10 -2
  212. package/skills/bee/peaks-txt/SKILL.md +4 -3
  213. package/skills/bee/peaks-ui/SKILL.md +3 -3
  214. package/skills/peaks-audit/SKILL.md +29 -1
  215. package/skills/peaks-code/SKILL.md +5 -2
  216. package/skills/peaks-code/references/fast-lane-norm.md +42 -0
  217. package/skills/peaks-code/references/fast-mode.md +3 -2
  218. package/skills/peaks-code/references/local-artifact-workspace.md +3 -3
  219. package/skills/peaks-code/references/micro-cycle.md +3 -3
  220. package/skills/peaks-code/references/resume-detection.md +1 -1
  221. package/skills/peaks-code/references/runbook.md +12 -6
  222. package/skills/peaks-code/references/step-11-memory-sediment.md +4 -0
  223. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  224. package/skills/peaks-code/references/swarm-dispatch-contract.md +40 -16
  225. package/skills/peaks-code/references/workflow-gates-and-types.md +6 -6
  226. package/skills/peaks-code/references/worktree-governance.md +4 -4
  227. package/skills/peaks-content/SKILL.md +1 -1
  228. package/skills/peaks-doctor/SKILL.md +1 -1
  229. package/skills/peaks-final-review/SKILL.md +31 -11
  230. package/skills/peaks-ide/SKILL.md +1 -1
  231. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  232. package/skills/peaks-race-code/SKILL.md +185 -0
  233. package/skills/peaks-resume/SKILL.md +1 -1
  234. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  235. package/skills/peaks-solo/SKILL.md +1 -1
  236. package/skills/peaks-sop/SKILL.md +1 -1
  237. package/skills/peaks-status/SKILL.md +1 -1
  238. package/skills/peaks-test/SKILL.md +7 -4
  239. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.d.ts +0 -23
  240. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.js +0 -64
@@ -0,0 +1,108 @@
1
+ /**
2
+ * Whether the invocations a dispatch prompt names are commands this CLI will
3
+ * accept, with the flags the prompt gives them.
4
+ *
5
+ * A dispatch brief tells a sub-agent which commands to run, and those quotations
6
+ * are prose to every other reader — no gate parses them. A brief naming a flag
7
+ * the command does not declare therefore reaches the sub-agent intact and costs
8
+ * it a failed run, and nothing measures it. This module makes the quotation
9
+ * checkable: each run `./dispatch-cli-invocation-scan.ts` cut out of the prompt
10
+ * is resolved against the registered command tree, and the flags it carries are
11
+ * compared with the ones the resolved command declares.
12
+ *
13
+ * The source of truth is the REGISTERED CLI, never a hand-kept flag table. The
14
+ * caller passes the real root `Command`; declared flags are read off
15
+ * `option.long` / `option.short` and gathered up the parent chain, so a flag an
16
+ * ancestor declares counts as declared. Measured on this CLI: `peaks code
17
+ * context-now --verbose` is accepted and `--verbose` is declared only on the
18
+ * root program, while `peaks worktree auth grant --rid x` is refused — with
19
+ * `error: required option '--operation <op>' not specified` in that form, and
20
+ * with `error: unknown option '--rid'` only once `--operation` and `--reason`
21
+ * are supplied, because commander reports a missing required option first. Both
22
+ * halves were run.
23
+ *
24
+ * The `option.mandatory` distinction recorded in
25
+ * `tests/unit/services/artifacts/artifact-contract-block.test.ts` does NOT apply
26
+ * here. That test asks which flags a command REQUIRES; this one asks which flags
27
+ * a command DECLARES. `option.required` — true for every option that takes a
28
+ * value — is never read, so the trap of reading it in place of `mandatory`
29
+ * cannot arise.
30
+ *
31
+ * WHAT THIS CHECK DOES NOT SEE, each one measured and each one deliberate:
32
+ *
33
+ * - A sentence that NAMES a flag without invoking a command.
34
+ * - A flag COMMANDER itself supplies. `--help` (and its short form) is accepted by
35
+ * every registered command but is not one of `command.options`, so
36
+ * `peaks worktree auth grant --help` is reported as an undeclared flag. Measured
37
+ * while correcting the dispatch block, where a pointer at `--help` was a
38
+ * candidate rewording and had to be rejected for this reason alone. Recorded
39
+ * rather than fixed: the same walk up the parent chain is what makes an
40
+ * inherited flag count as declared, so a targeted excuse for `--help` belongs to
41
+ * its own slice with its own corpus measurement.
42
+ * - An invocation of a program that is not `peaks` (`git`, `pnpm`, `npx` — this
43
+ * CLI holds no registry for them), and an invocation that reaches this CLI by
44
+ * PATH rather than by name. The corpus spells the perf-audit run it ought to
45
+ * have flagged as `node node_modules/tsx/dist/cli.mjs src/cli/index.ts
46
+ * perf-audit run --rid …`, with no `peaks` token at all, so no run is
47
+ * extracted and that line is unchecked today.
48
+ * - Whether a quoted invocation is meant as an INSTRUCTION or as a quotation of
49
+ * a defect. This is the check's known false-positive class, measured rather
50
+ * than hidden: a brief that documents a rejected invocation quotes it, and
51
+ * reads exactly like a brief that instructs it.
52
+ * - A run longer than the scan's bound, a flag spelled past a line break that is
53
+ * not a continuation, and a capitalised `Peaks`. Each is measured and argued
54
+ * in `./dispatch-cli-invocation-scan.ts`, where the boundary lives.
55
+ * - `--mode detached` and `--from-dag`, which return before the pipeline that
56
+ * composes a prompt (`dispatch-commands.ts`), so a brief handed over on either
57
+ * path is never checked. The in-process path is the one that writes the
58
+ * dispatch record the corpus is drawn from.
59
+ *
60
+ * TWO DECISIONS ARE RECORDED HERE BECAUSE BOTH ARE MEASUREMENTS, NOT TASTE.
61
+ *
62
+ * 1. The subject is the CALLER's prompt, not the assembled one. Measured over
63
+ * the 147 dispatch records under `.peaks/_sub_agents/`: 176 undeclared-flag
64
+ * findings, of which 147 sit inside the machine-injected worktree block this
65
+ * CLI writes into every prompt and 29 inside caller-authored text. Only the
66
+ * 29 belong to the caller who is warned, and only they make the check
67
+ * discriminating — a check reading the assembled string warns on every
68
+ * dispatch, whatever the brief says.
69
+ * 2. A finding WARNS; it does not refuse. Of those 29, ONE is a false positive:
70
+ * a CORRECT brief (the record for this very slice) that quotes
71
+ * `peaks request init --rid <rid>` inside a table documenting the defect. A
72
+ * corpus that cannot be made clean is the branch that must not refuse, and
73
+ * narrowing the check until it is green would stop it firing on the input it
74
+ * exists for. The false positive is named rather than engineered away.
75
+ */
76
+ import type { Command } from 'commander';
77
+ import { type PromptCliInvocation } from './dispatch-cli-invocation-scan.js';
78
+ /**
79
+ * What the registered CLI said about one invocation. `unknown-command` is a
80
+ * distinct state on purpose: a check that folded "could not resolve" into
81
+ * "clean" would pass every prompt it failed to read.
82
+ */
83
+ export type PromptCliVerdict = {
84
+ readonly kind: 'clean';
85
+ readonly command: string;
86
+ } | {
87
+ readonly kind: 'undeclared-flag';
88
+ readonly command: string;
89
+ readonly flags: readonly string[];
90
+ } | {
91
+ readonly kind: 'unknown-command';
92
+ readonly attempted: string;
93
+ };
94
+ /** One invocation and the verdict on it. */
95
+ export interface PromptCliFinding {
96
+ readonly text: string;
97
+ readonly verdict: PromptCliVerdict;
98
+ }
99
+ /**
100
+ * Resolve one invocation against `root` and compare its flags with the ones the
101
+ * resolved command declares. Operands stop the descent; options are skipped
102
+ * during it, since a flag may sit between two subcommand words.
103
+ */
104
+ export declare function checkPromptCliInvocation(invocation: PromptCliInvocation, root: Command): PromptCliVerdict;
105
+ /** Every invocation `text` carries, each with the verdict on it. */
106
+ export declare function checkPromptCliInvocations(text: string, root: Command): PromptCliFinding[];
107
+ /** The warning list a dispatch envelope carries for the prompt it is handing over. */
108
+ export declare function cliInvocationWarnings(text: string, root: Command): string[];
@@ -0,0 +1,87 @@
1
+ import { extractPromptCliInvocations } from './dispatch-cli-invocation-scan.js';
2
+ /** How many undeclared flags a warning names before it counts the rest instead. */
3
+ const FLAG_LIMIT = 8;
4
+ /** The flag a token carries, or null when the token is an operand rather than an option. */
5
+ function optionName(token) {
6
+ if (!/^--?[A-Za-z]/.test(token))
7
+ return null;
8
+ const equals = token.indexOf('=');
9
+ return equals === -1 ? token : token.slice(0, equals);
10
+ }
11
+ /** The subcommand of `command` that answers to `name`, matching aliases too. */
12
+ function childNamed(command, name) {
13
+ return command.commands.find((candidate) => candidate.name() === name || candidate.aliases().includes(name));
14
+ }
15
+ /** The flags `command` declares, plus every flag its ancestors declare. */
16
+ function declaredFlags(command) {
17
+ const flags = new Set();
18
+ let current = command;
19
+ while (current !== null) {
20
+ for (const option of current.options) {
21
+ if (option.long !== undefined)
22
+ flags.add(option.long);
23
+ if (option.short !== undefined)
24
+ flags.add(option.short);
25
+ }
26
+ current = current.parent;
27
+ }
28
+ return flags;
29
+ }
30
+ /**
31
+ * Resolve one invocation against `root` and compare its flags with the ones the
32
+ * resolved command declares. Operands stop the descent; options are skipped
33
+ * during it, since a flag may sit between two subcommand words.
34
+ */
35
+ export function checkPromptCliInvocation(invocation, root) {
36
+ const path = [];
37
+ let current = root;
38
+ for (const token of invocation.tokens) {
39
+ if (optionName(token) !== null)
40
+ continue;
41
+ const next = childNamed(current, token);
42
+ if (next === undefined)
43
+ break;
44
+ path.push(token);
45
+ current = next;
46
+ }
47
+ if (path.length === 0) {
48
+ return { kind: 'unknown-command', attempted: invocation.tokens[0] ?? '' };
49
+ }
50
+ const declared = declaredFlags(current);
51
+ const flags = [];
52
+ for (const token of invocation.tokens) {
53
+ const flag = optionName(token);
54
+ if (flag !== null && !declared.has(flag))
55
+ flags.push(flag);
56
+ }
57
+ if (flags.length > 0)
58
+ return { kind: 'undeclared-flag', command: path.join(' '), flags };
59
+ return { kind: 'clean', command: path.join(' ') };
60
+ }
61
+ /** Every invocation `text` carries, each with the verdict on it. */
62
+ export function checkPromptCliInvocations(text, root) {
63
+ return extractPromptCliInvocations(text).map((invocation) => ({
64
+ text: invocation.text,
65
+ verdict: checkPromptCliInvocation(invocation, root)
66
+ }));
67
+ }
68
+ /** The warning list a dispatch envelope carries for the prompt it is handing over. */
69
+ export function cliInvocationWarnings(text, root) {
70
+ const warnings = [];
71
+ for (const { text: quoted, verdict } of checkPromptCliInvocations(text, root)) {
72
+ if (verdict.kind === 'undeclared-flag') {
73
+ const rest = verdict.flags.length - FLAG_LIMIT;
74
+ const named = verdict.flags
75
+ .slice(0, FLAG_LIMIT)
76
+ .map((flag) => `\`${flag}\``)
77
+ .join(', ');
78
+ const flags = rest > 0 ? `${named} (and ${rest} more)` : named;
79
+ warnings.push(`PROMPT_CLI_FLAG_NOT_DECLARED: \`${quoted}\` — \`peaks ${verdict.command}\` declares no ${flags}.`);
80
+ }
81
+ else if (verdict.kind === 'unknown-command') {
82
+ warnings.push(`PROMPT_CLI_COMMAND_NOT_FOUND: \`${quoted}\` — no registered command resolves from ` +
83
+ `\`${verdict.attempted}\`.`);
84
+ }
85
+ }
86
+ return warnings;
87
+ }
@@ -0,0 +1,66 @@
1
+ /**
2
+ * The `peaks …` runs a dispatch prompt carries, cut out of prose.
3
+ *
4
+ * Extraction only: it finds the runs, keeps the quotation boundaries that make a
5
+ * quoted command quoted, and hands back tokens. It knows nothing about which
6
+ * commands exist — that half lives in `./dispatch-cli-invocation-check.ts`. The
7
+ * split is the repository's file-cap rule rather than a design statement.
8
+ *
9
+ * THE RUN BOUNDARY. A run ends at the backtick that closed its quotation, or at
10
+ * a line break no continuation follows. Both ends matter: without the backtick
11
+ * the sentence after a quoted command would be read as its arguments, and
12
+ * without the continuation rule a wrapped invocation is read only to its first
13
+ * line — a FALSE NEGATIVE that still reports clean, measured on the real corpus
14
+ * text `peaks workflow verify-pipeline --rid <rid>` wrapping onto
15
+ * `--project <root> --type <type>`.
16
+ *
17
+ * THE CASE IS DELIBERATE. Matching is case-sensitive, and the decision is
18
+ * measured: the corpus carries 51 lines using `Peaks` as this project's own name
19
+ * in prose (`… bypassed Peaks worktree governance`, `the active Peaks skill`) and
20
+ * NOT ONE of them is an invocation. Matching them case-insensitively would add 51
21
+ * findings — 47 that happen to resolve onto a command word and read clean, and 4
22
+ * that resolve onto nothing and would warn — every one of them on prose.
23
+ *
24
+ * COST IS BOUNDED IN TWO PLACES, both put there by a measurement on
25
+ * caller-supplied text, and both recorded on the functions that carry them.
26
+ *
27
+ * CITATIONS. This file names the SHAPE of a corpus record rather than the record;
28
+ * the tests name the record in full. That is not tidiness, it is a collision
29
+ * between two of this campaign's own rules, and it has now bitten twice in one
30
+ * night on two different slices. The rule that a red-direction case be built from
31
+ * the REAL input makes a source comment want to cite the record it came from, and
32
+ * real records are named with a request-id prefix — the very substring the
33
+ * comment-hygiene marker for a request id matches. So the citation that gives a
34
+ * reader the evidence is the line that raises a ceiling. Putting it in the test
35
+ * file resolves it in the right direction: `tests/**` is outside the
36
+ * comment-hygiene scope, the case is built from that record anyway, and the
37
+ * source keeps the shape. A wording bent around the detector would have lowered
38
+ * the ceiling by making the guard unable to see the case that raised it.
39
+ */
40
+ /**
41
+ * How much of a run is read, in characters.
42
+ *
43
+ * Without it a prompt carrying many invocations on one long line makes the scan
44
+ * quadratic, because a run ends only at a delimiter: the 1772 runs in the corpus
45
+ * never exceed 167 characters (mean 36.4), but a synthetic 123 KB prompt with
46
+ * 5024 invocations on a single line took 7.2 seconds and an 800 KB one exhausted
47
+ * a 4 GB heap. Its cost is stated rather than hidden: a run longer than this is
48
+ * read only to the bound, so a flag spelled past it is not seen.
49
+ */
50
+ export declare const PROMPT_CLI_RUN_LIMIT = 512;
51
+ /** One `peaks …` run found in a prompt. */
52
+ export interface PromptCliInvocation {
53
+ /** The run with the command word restored, as the prompt spells it. */
54
+ readonly text: string;
55
+ /** The run's whitespace-separated tokens, each with trailing sentence punctuation trimmed. */
56
+ readonly tokens: readonly string[];
57
+ }
58
+ /**
59
+ * Every invocation of this CLI that `text` carries, in the order it carries them.
60
+ *
61
+ * A run end already found is reused by every later match inside it, because the
62
+ * first delimiter after a later start is the same one. That reuse is the second
63
+ * half of the cost bound: measured, 50024 invocations on one 958 KB line took
64
+ * 4216 ms without it and 53 ms with it.
65
+ */
66
+ export declare function extractPromptCliInvocations(text: string): PromptCliInvocation[];
@@ -0,0 +1,162 @@
1
+ /**
2
+ * The `peaks …` runs a dispatch prompt carries, cut out of prose.
3
+ *
4
+ * Extraction only: it finds the runs, keeps the quotation boundaries that make a
5
+ * quoted command quoted, and hands back tokens. It knows nothing about which
6
+ * commands exist — that half lives in `./dispatch-cli-invocation-check.ts`. The
7
+ * split is the repository's file-cap rule rather than a design statement.
8
+ *
9
+ * THE RUN BOUNDARY. A run ends at the backtick that closed its quotation, or at
10
+ * a line break no continuation follows. Both ends matter: without the backtick
11
+ * the sentence after a quoted command would be read as its arguments, and
12
+ * without the continuation rule a wrapped invocation is read only to its first
13
+ * line — a FALSE NEGATIVE that still reports clean, measured on the real corpus
14
+ * text `peaks workflow verify-pipeline --rid <rid>` wrapping onto
15
+ * `--project <root> --type <type>`.
16
+ *
17
+ * THE CASE IS DELIBERATE. Matching is case-sensitive, and the decision is
18
+ * measured: the corpus carries 51 lines using `Peaks` as this project's own name
19
+ * in prose (`… bypassed Peaks worktree governance`, `the active Peaks skill`) and
20
+ * NOT ONE of them is an invocation. Matching them case-insensitively would add 51
21
+ * findings — 47 that happen to resolve onto a command word and read clean, and 4
22
+ * that resolve onto nothing and would warn — every one of them on prose.
23
+ *
24
+ * COST IS BOUNDED IN TWO PLACES, both put there by a measurement on
25
+ * caller-supplied text, and both recorded on the functions that carry them.
26
+ *
27
+ * CITATIONS. This file names the SHAPE of a corpus record rather than the record;
28
+ * the tests name the record in full. That is not tidiness, it is a collision
29
+ * between two of this campaign's own rules, and it has now bitten twice in one
30
+ * night on two different slices. The rule that a red-direction case be built from
31
+ * the REAL input makes a source comment want to cite the record it came from, and
32
+ * real records are named with a request-id prefix — the very substring the
33
+ * comment-hygiene marker for a request id matches. So the citation that gives a
34
+ * reader the evidence is the line that raises a ceiling. Putting it in the test
35
+ * file resolves it in the right direction: `tests/**` is outside the
36
+ * comment-hygiene scope, the case is built from that record anyway, and the
37
+ * source keeps the shape. A wording bent around the detector would have lowered
38
+ * the ceiling by making the guard unable to see the case that raised it.
39
+ */
40
+ /** The word an invocation starts with. `peaks-loop` cannot match: the run must follow a space. */
41
+ const CLI_START = /\bpeaks\b[ \t]+/g;
42
+ /** Ends a run: the backtick that closed the quotation, or a line break nothing continues. */
43
+ const RUN_END = new Set(['`', '\n', '\r']);
44
+ /**
45
+ * How much of a run is read, in characters.
46
+ *
47
+ * Without it a prompt carrying many invocations on one long line makes the scan
48
+ * quadratic, because a run ends only at a delimiter: the 1772 runs in the corpus
49
+ * never exceed 167 characters (mean 36.4), but a synthetic 123 KB prompt with
50
+ * 5024 invocations on a single line took 7.2 seconds and an 800 KB one exhausted
51
+ * a 4 GB heap. Its cost is stated rather than hidden: a run longer than this is
52
+ * read only to the bound, so a flag spelled past it is not seen.
53
+ */
54
+ export const PROMPT_CLI_RUN_LIMIT = 512;
55
+ /** Bound on the text a finding quotes back, so one long run cannot flood an envelope. */
56
+ const QUOTED_LIMIT = 200;
57
+ /** Punctuation that ends a sentence rather than a token, and so is not part of an option name. */
58
+ const TRAILING_PUNCTUATION = new Set(['.', ',', ';', ':', ')', ']', '}', "'", '"']);
59
+ /**
60
+ * Drop the sentence punctuation a run's final token carries.
61
+ *
62
+ * A `…+$` regex reads better but is quadratic on a long punctuation run that
63
+ * does not reach the end of its token: measured here, `'.'.repeat(n) + 'x'`
64
+ * costs 0.4 ms at n=1000 and 94.8 ms at n=16000. The prompt is caller-supplied
65
+ * text, so a crafted run would turn a dispatch into a stall. A backwards scan
66
+ * is linear and charges nothing for the ordinary case.
67
+ */
68
+ function trimTrailingPunctuation(token) {
69
+ let end = token.length;
70
+ while (end > 0) {
71
+ const last = token[end - 1];
72
+ if (last === undefined || !TRAILING_PUNCTUATION.has(last))
73
+ break;
74
+ end -= 1;
75
+ }
76
+ return token.slice(0, end);
77
+ }
78
+ /** Split a run into tokens, dropping the punctuation that ends a sentence. */
79
+ function tokenize(run) {
80
+ const tokens = [];
81
+ for (const raw of run.split(/[ \t\r\n]+/)) {
82
+ const token = trimTrailingPunctuation(raw);
83
+ if (token.length > 0)
84
+ tokens.push(token);
85
+ }
86
+ return tokens;
87
+ }
88
+ function shorten(text) {
89
+ return text.length <= QUOTED_LIMIT ? text : `${text.slice(0, QUOTED_LIMIT)}…`;
90
+ }
91
+ /**
92
+ * True when the line beginning at `at` continues the invocation above it.
93
+ *
94
+ * A wrapped invocation puts the rest of its flags on the next line opening with
95
+ * a long option. The corpus carries that shape — a `workflow verify-pipeline`
96
+ * run whose `--project` and `--type` sit on the following line — and without this
97
+ * rule every flag after the break goes unchecked while the invocation still
98
+ * reports CLEAN. The case that pins it,
99
+ * `tests/unit/cli/commands/dispatch-cli-invocation-scan.test.ts`, quotes the
100
+ * record it was taken from; this comment does not, on purpose: see the note on
101
+ * citations below the exports.
102
+ *
103
+ * Requiring two dashes is what separates a continuation from a markdown bullet,
104
+ * which opens with one, so a prose list under a command is still not read as its
105
+ * arguments.
106
+ */
107
+ function continuesAfterBreak(text, at) {
108
+ let index = at;
109
+ while (index < text.length) {
110
+ const character = text[index];
111
+ if (character !== '\n' && character !== '\r' && character !== ' ' && character !== '\t')
112
+ break;
113
+ index += 1;
114
+ }
115
+ return text.startsWith('--', index) && /[A-Za-z]/.test(text[index + 2] ?? '');
116
+ }
117
+ /**
118
+ * Where the run starting at `from` ends.
119
+ *
120
+ * The scan stops at {@link PROMPT_CLI_RUN_LIMIT} characters, and that bound is
121
+ * what makes it linear. Scanning to the next line break instead costs a walk to
122
+ * the END OF THE TEXT per match, so a prompt of many short lines is quadratic in
123
+ * the number of lines: measured on that shape, `'peaks test --json\n'.repeat(n)`
124
+ * took 2.7 ms at 2000 lines / 35 KB, 26.4 ms at 8000, 101.0 ms at 16000 / 281 KB,
125
+ * 493 ms at 32000, and 109.9 s at 200000 / 3.5 MB — synchronously, inside
126
+ * `composeDispatchPrompt`, on caller-supplied text.
127
+ */
128
+ function runEnd(text, from) {
129
+ const limit = Math.min(text.length, from + PROMPT_CLI_RUN_LIMIT);
130
+ let index = from;
131
+ while (index < limit) {
132
+ const character = text[index];
133
+ if (character === undefined)
134
+ break;
135
+ if (RUN_END.has(character) && !continuesAfterBreak(text, index))
136
+ return index;
137
+ index += 1;
138
+ }
139
+ return limit;
140
+ }
141
+ /**
142
+ * Every invocation of this CLI that `text` carries, in the order it carries them.
143
+ *
144
+ * A run end already found is reused by every later match inside it, because the
145
+ * first delimiter after a later start is the same one. That reuse is the second
146
+ * half of the cost bound: measured, 50024 invocations on one 958 KB line took
147
+ * 4216 ms without it and 53 ms with it.
148
+ */
149
+ export function extractPromptCliInvocations(text) {
150
+ const invocations = [];
151
+ let runEndsAt = -1;
152
+ for (const match of text.matchAll(CLI_START)) {
153
+ const start = (match.index ?? 0) + match[0].length;
154
+ if (start >= runEndsAt)
155
+ runEndsAt = runEnd(text, start);
156
+ const run = text.slice(start, runEndsAt);
157
+ const tokens = tokenize(run);
158
+ if (tokens.length > 0)
159
+ invocations.push({ text: shorten(`peaks ${run.trim()}`), tokens });
160
+ }
161
+ return invocations;
162
+ }
@@ -67,7 +67,8 @@ async function composePromptPhase(io, options, ctx, input) {
67
67
  worktreePath: input.lease.worktreePath,
68
68
  worktreeBranch: input.lease.worktreeBranch,
69
69
  decision: input.decision,
70
- asJson: ctx.asJson
70
+ asJson: ctx.asJson,
71
+ rootCommand: input.rootCommand
71
72
  });
72
73
  }
73
74
  function buildToolCallPhase(io, ctx, input) {
@@ -106,7 +107,8 @@ async function runDispatchPipeline(io, options, role, input) {
106
107
  const composed = await composePromptPhase(io, options, ctx, {
107
108
  prompt: input.prompt,
108
109
  decision: input.decision,
109
- lease
110
+ lease,
111
+ rootCommand: input.rootCommand
110
112
  });
111
113
  if (composed === null)
112
114
  return;
@@ -137,7 +139,7 @@ async function runDispatchPipeline(io, options, role, input) {
137
139
  emitDispatchEnvelope(io, envelopeInput, warnings, input.asJson);
138
140
  writeDispatchLogEntry(ctx, counter.count, input.decision.forcedAt);
139
141
  }
140
- async function runDispatchAction(role, options, io) {
142
+ async function runDispatchAction(role, options, io, rootCommand) {
141
143
  const asJson = options.json === true;
142
144
  // explicitly requested, lazy-import the detached handler and short-
143
145
  // circuit before the warm-path in-process pipeline runs. Branch
@@ -162,7 +164,7 @@ async function runDispatchAction(role, options, io) {
162
164
  return;
163
165
  const { decision, prompt } = preflight;
164
166
  try {
165
- await runDispatchPipeline(io, options, role, { decision, prompt, asJson });
167
+ await runDispatchPipeline(io, options, role, { decision, prompt, asJson, rootCommand });
166
168
  }
167
169
  catch (error) {
168
170
  printResult(io, fail('sub-agent.dispatch', 'DISPATCH_ERROR', getErrorMessage(error), { role, toolCall: null, dispatchRecordPath: null }, [
@@ -172,7 +174,12 @@ async function runDispatchAction(role, options, io) {
172
174
  }
173
175
  }
174
176
  export function registerDispatchCommand(parent, io) {
175
- buildDispatchCommandSpec(parent).action((role, options) => runDispatchAction(role, options, io));
177
+ // `parent` is the `sub-agent` group, so its parent is the registered root —
178
+ // the real command tree the prompt's quotations are resolved against. A caller
179
+ // that mounted the group on a bare `Command` (as the unit tests do) gets that
180
+ // Command, which is the whole tree it has.
181
+ const rootCommand = parent.parent ?? parent;
182
+ buildDispatchCommandSpec(parent).action((role, options) => runDispatchAction(role, options, io, rootCommand));
176
183
  }
177
184
  /**
178
185
  * 2.7.0 slice-dag-dispatcher MVP — see `dispatch-from-dag.ts`.
@@ -1,6 +1,7 @@
1
1
  // The `peaks sub-agent dispatch` preflight: every refusal that can be decided from
2
2
  // the argv alone, before the session id, the lease or the prompt blocks are touched.
3
3
  // Returns the prompt-size decision, or `null` when a refusal was already printed.
4
+ import { readFileSync } from 'node:fs';
4
5
  import { printResult } from '../cli-helpers.js';
5
6
  import { fail } from 'peaks-loop-shared/result';
6
7
  import { evaluatePromptSize } from '../../services/context/context-guard.js';
@@ -45,6 +46,47 @@ function applyPromptLengthOverride(options) {
45
46
  }
46
47
  }
47
48
  }
49
+ function rejectPromptFileUnreadable(io, role, prompt, asJson) {
50
+ printResult(io, fail('sub-agent.dispatch', 'PROMPT_FILE_NOT_FOUND', `--prompt "${prompt}" is a file reference ("@<path>") but that path could not be read`, { role, toolCall: null, dispatchRecordPath: null }, [
51
+ 'Fix the path after "@", or pass the prompt text itself.',
52
+ 'A --prompt that does not begin with "@" is sent verbatim.'
53
+ ]), asJson);
54
+ process.exitCode = 1;
55
+ return null;
56
+ }
57
+ function rejectEmptyPromptFile(io, role, prompt, asJson) {
58
+ printResult(io, fail('sub-agent.dispatch', 'MISSING_PROMPT', `--prompt "${prompt}" resolved to an empty file: a dispatch needs instructions`, { role, toolCall: null, dispatchRecordPath: null }, [
59
+ 'Write the brief into the referenced file, or pass the prompt text itself.',
60
+ 'An empty or whitespace-only file carries no brief, so the dispatch would look successful and instruct nothing.'
61
+ ]), asJson);
62
+ process.exitCode = 1;
63
+ return null;
64
+ }
65
+ // `--prompt "@<path>"` is a file reference, mirroring `peaks prd handoff init
66
+ // --body` (prd-commands.ts `resolveBody`). Before this the "@" token was sent
67
+ // as literal text, so a dispatch naming a brief file went out carrying the path
68
+ // and none of the brief — no warning, exit 0. A prompt that does not begin with
69
+ // "@" is returned untouched, byte-identical.
70
+ //
71
+ // The emptiness check is repeated AFTER the read, and only on this branch: the
72
+ // pre-read check sees the token "@<path>", never the file's contents, so an
73
+ // empty file passes it and re-opens the same silent-dispatch defect from the
74
+ // other side. A whitespace-only file is the same input. Both are refused; a
75
+ // LITERAL prompt is not re-checked, so a whitespace-only literal is unchanged.
76
+ function resolvePromptFileRef(io, role, prompt, asJson) {
77
+ if (!prompt.startsWith('@'))
78
+ return { prompt };
79
+ try {
80
+ const content = readFileSync(prompt.slice(1), 'utf8');
81
+ if (content.trim().length === 0) {
82
+ return rejectEmptyPromptFile(io, role, prompt, asJson);
83
+ }
84
+ return { prompt: content };
85
+ }
86
+ catch {
87
+ return rejectPromptFileUnreadable(io, role, prompt, asJson);
88
+ }
89
+ }
48
90
  function rejectPromptTooLarge(io, role, promptLength, asJson) {
49
91
  printResult(io, fail('sub-agent.dispatch', 'PROMPT_TOO_LARGE', `prompt exceeds ${PROMPT_LIMIT_BYTES} bytes (got ${promptLength})`, { role, toolCall: null, dispatchRecordPath: null }, [
50
92
  'Truncate the prompt or split into multiple dispatches.',
@@ -86,6 +128,10 @@ export function preflightDispatch(io, role, options, asJson) {
86
128
  if (!options.prompt || options.prompt.length === 0) {
87
129
  return rejectMissingPrompt(io, role, asJson);
88
130
  }
131
+ const fileRef = resolvePromptFileRef(io, role, options.prompt, asJson);
132
+ if (fileRef === null)
133
+ return null;
134
+ options.prompt = fileRef.prompt;
89
135
  // Slice 4.0.8 RD §4 D4c required `--graph-node` here, before the session
90
136
  // id existed, so the only recovery it could offer was prose. The node is
91
137
  // now provisioned inside the try block below, once `sid` is known.
@@ -1,3 +1,4 @@
1
+ import type { Command } from 'commander';
1
2
  import { type ProgramIO } from '../cli-helpers.js';
2
3
  import { getAdapter } from '../../services/ide/ide-registry.js';
3
4
  import type { ContextGuardDecision } from '../../services/context/context-guard.js';
@@ -16,6 +17,11 @@ export interface ComposeDispatchPromptInput {
16
17
  worktreeBranch: string | null;
17
18
  decision: ContextGuardDecision;
18
19
  asJson: boolean;
20
+ /**
21
+ * The registered CLI, so the prompt's own quotations of it can be resolved
22
+ * against the commands that exist rather than against a second, hand-kept list.
23
+ */
24
+ rootCommand: Command;
19
25
  }
20
26
  export interface ComposedDispatchPrompt {
21
27
  adapter: ReturnType<typeof getAdapter>;
@@ -1,7 +1,3 @@
1
- // The prompt `peaks sub-agent dispatch` hands a sub-agent: the adapter check, the
2
- // optional preflight blocks (memory / codegraph / UI library / fresh context /
3
- // context probe / session capsule), the isolation and must-ls-files blocks, and the
4
- // warning list the envelope carries.
5
1
  import { fail, getErrorMessage } from 'peaks-loop-shared/result';
6
2
  import { printResult } from '../cli-helpers.js';
7
3
  import { detectInstalledIde } from '../../services/ide/ide-detector.js';
@@ -16,6 +12,9 @@ import { computeUiLibraryDispatchBlock } from '../../services/standards/ui-libra
16
12
  import { readFreshContextBlock } from '../../services/fresh-context/fresh-context-block.js';
17
13
  import { deprecatedReviewerWarnings } from './sub-agent-shared.js';
18
14
  import { buildIsolationBlock, buildMustLsFilesBlock } from './dispatch-prompt-blocks.js';
15
+ import { ensureArtifactContractBlock, readArtifactContractBlock } from '../../services/artifacts/artifact-contract-block.js';
16
+ import { ensureKarpathyBlock } from '../../services/dispatch/karpathy-block.js';
17
+ import { cliInvocationWarnings } from './dispatch-cli-invocation-check.js';
19
18
  // loadPreferences can throw on schema mismatch; we fall back to defaults
20
19
  // to avoid breaking the dispatch on a stale preferences.json file.
21
20
  function loadProjectPreferences(projectRoot) {
@@ -154,7 +153,7 @@ async function composeMemoryAugmentedBody(input, projectPrefs) {
154
153
  });
155
154
  }
156
155
  export async function composeDispatchPrompt(io, input) {
157
- const { projectRoot, role, options, isolationMode, leaseId, worktreePath, worktreeBranch, decision, asJson } = input;
156
+ const { projectRoot, sid, rid, role, options, isolationMode, leaseId, worktreePath, worktreeBranch, decision, asJson, rootCommand, prompt } = input;
158
157
  const projectPrefs = loadProjectPreferences(projectRoot);
159
158
  const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
160
159
  const adapter = getAdapter(ide);
@@ -164,8 +163,31 @@ export async function composeDispatchPrompt(io, input) {
164
163
  const memoryAugmentedBody = await composeMemoryAugmentedBody(input, projectPrefs);
165
164
  const isolationBlock = buildIsolationBlock(isolationMode, leaseId, worktreePath, worktreeBranch);
166
165
  const { mustLsFilesVerification, mustLsFilesBlock } = buildMustLsFilesBlock(options, projectRoot);
167
- const effectivePrompt = `${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
166
+ // What the downstream gate will demand of this role, named in advance. `''`
167
+ // when this role has no gated artifacts under this type, so an unaffected
168
+ // role's prompt stays byte-identical. Injection is idempotent — a caller
169
+ // prompt that already carries a block keeps exactly one (see the helper).
170
+ const contractBlock = await readArtifactContractBlock({
171
+ projectRoot,
172
+ sessionId: sid,
173
+ requestId: rid,
174
+ role
175
+ });
176
+ // The presence test runs on the ASSEMBLED prompt, not on the caller's draft:
177
+ // this string is what the sub-agent receives as `toolCall.args.prompt` and
178
+ // what the dispatch record stores as `prompt`. A draft that merely names
179
+ // Karpathy (or carries a copy with a word wrong) does not count as carrying
180
+ // the canonical block, so the block is added rather than trusted.
181
+ const effectivePrompt = ensureKarpathyBlock(ensureArtifactContractBlock(`${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`, contractBlock));
182
+ // Findings travel as WARNINGS, never as a refusal, and they are read off the
183
+ // CALLER's prompt rather than the assembled one — both decisions are measured
184
+ // and recorded on `dispatch-cli-invocation-check.ts`.
185
+ const invocationWarnings = cliInvocationWarnings(prompt, rootCommand);
168
186
  // + rerouted here, never refused — rationale on the helper itself.
169
- const warnings = [...decision.warnings, ...deprecatedReviewerWarnings(role)];
187
+ const warnings = [
188
+ ...decision.warnings,
189
+ ...deprecatedReviewerWarnings(role),
190
+ ...invocationWarnings
191
+ ];
170
192
  return { adapter, effectivePrompt, warnings, mustLsFilesVerification };
171
193
  }
@@ -6,6 +6,7 @@
6
6
  *
7
7
  * See `src/services/doc/doc-generator.ts` for the underlying logic.
8
8
  */
9
+ import { mkdirSync, writeFileSync } from 'node:fs';
9
10
  import { resolve as resolvePath } from 'node:path';
10
11
  import { findProjectRoot } from '../../services/config/config-safety.js';
11
12
  import { generateSkillFromCommands, gitLogSince, renderSkillMarkdown, suggestChangelog } from '../../services/doc/doc-generator.js';
@@ -31,7 +32,6 @@ export function registerDocCommands(program, io) {
31
32
  if (opts.output !== undefined) {
32
33
  // Write to file
33
34
  try {
34
- const { writeFileSync, mkdirSync } = require('node:fs');
35
35
  mkdirSync(resolvePath(opts.output, '..'), { recursive: true });
36
36
  writeFileSync(resolvePath(opts.output), md, 'utf8');
37
37
  printResult(io, ok('doc.generate-skill', {
@@ -18,7 +18,7 @@ export const CHECK_UNPROMOTED_DESCRIPTION = 'Scan `.peaks/memory/*.md` and list
18
18
  export const NO_LAYER_NEXT_ACTIONS = [
19
19
  'No --layer passed. Choose one of A / B / C and re-run.',
20
20
  'A: append to sops/*.md (procedural rules)',
21
- 'B: append a matcher to .peaks/.claude-settings-template.json (tool-call interception)',
21
+ 'B: append a matcher to .peaks/.claude-settings-template.json, or to .claude/settings.json for a hook that ships with this repo (tool-call interception)',
22
22
  'C: extend HardFloorCategory in mode-gate.ts (always pauses regardless of mode)',
23
23
  'Or pass --dry-run to preview all three stubs first.'
24
24
  ];