peaks-loop 4.1.5 → 4.1.6

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 (86) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +36 -0
  3. package/README-en.md +47 -183
  4. package/README.md +24 -188
  5. package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
  6. package/dist/cli/commands/best-practice-scan-command.js +35 -20
  7. package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
  8. package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
  9. package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
  10. package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
  11. package/dist/cli/commands/dispatch-command-spec.js +1 -1
  12. package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
  13. package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
  14. package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
  15. package/dist/cli/commands/dispatch-prompt-composition.d.ts +1 -1
  16. package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
  17. package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
  18. package/dist/cli/commands/openspec-command-shared.js +2 -2
  19. package/dist/cli/commands/request-transition-failures.js +31 -4
  20. package/dist/cli/commands/request-transition-preflight.js +1 -1
  21. package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
  22. package/dist/cli/commands/verdict-aggregate-command.js +2 -1
  23. package/dist/cli/commands/workflow-gate-commands.js +4 -4
  24. package/dist/cli/program.js +0 -2
  25. package/dist/services/artifacts/artifact-contract-block.js +21 -2
  26. package/dist/services/artifacts/artifact-prerequisites.js +7 -7
  27. package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
  28. package/dist/services/artifacts/rd-transition-gates.js +71 -0
  29. package/dist/services/artifacts/request-artifact-service.js +22 -20
  30. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +9 -1
  31. package/dist/services/artifacts/request-artifact-state-helpers.js +6 -4
  32. package/dist/services/audit-independent/judged-declaration-check.d.ts +1 -0
  33. package/dist/services/audit-independent/judged-declaration-check.js +62 -1
  34. package/dist/services/context/build-dispatch-system-prompt.d.ts +5 -9
  35. package/dist/services/context/build-dispatch-system-prompt.js +11 -11
  36. package/dist/services/context/post-compact-reinjection.js +1 -1
  37. package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
  38. package/dist/services/dispatch/test-tool-detection.js +12 -1
  39. package/dist/services/evidence/evidence-generator.js +8 -4
  40. package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
  41. package/dist/services/openspec/coverage-evidence-reader.js +8 -8
  42. package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
  43. package/dist/services/openspec/openspec-archive-service.js +6 -6
  44. package/dist/services/scan/file-size-baseline.d.ts +13 -6
  45. package/dist/services/scan/file-size-baseline.js +54 -31
  46. package/dist/services/scan/file-size-scan.d.ts +7 -14
  47. package/dist/services/scan/file-size-scan.js +6 -1
  48. package/dist/services/scan/type-corroboration.d.ts +32 -0
  49. package/dist/services/scan/type-corroboration.js +51 -0
  50. package/dist/services/scan/type-sanity-service.d.ts +14 -0
  51. package/dist/services/scan/type-sanity-service.js +10 -19
  52. package/dist/services/security/safe-settings-path.d.ts +5 -0
  53. package/dist/services/security/safe-settings-path.js +64 -8
  54. package/dist/services/skill/resume-detector.js +8 -8
  55. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +24 -8
  56. package/dist/services/workflow/pipeline-verify-gate-support.js +32 -38
  57. package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
  58. package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
  59. package/dist/services/workflow/pipeline-verify-service.js +26 -27
  60. package/dist/services/workflow/request-type-resolution.d.ts +99 -0
  61. package/dist/services/workflow/request-type-resolution.js +130 -0
  62. package/dist/services/workflow/workflow-skip-service.d.ts +1 -0
  63. package/dist/services/workflow/workflow-skip-service.js +19 -21
  64. package/dist/services/workflow/workflow-state-store.d.ts +9 -0
  65. package/dist/services/workflow/workflow-state-store.js +26 -1
  66. package/dist/shared/incrementing-number.d.ts +23 -2
  67. package/dist/shared/incrementing-number.js +57 -15
  68. package/package.json +5 -7
  69. package/skills/bee/peaks-prd/SKILL.md +3 -2
  70. package/skills/peaks-code/SKILL.md +32 -15
  71. package/dist/cli/commands/vm-command-shared.d.ts +0 -23
  72. package/dist/cli/commands/vm-command-shared.js +0 -23
  73. package/dist/cli/commands/vm-commands.d.ts +0 -3
  74. package/dist/cli/commands/vm-commands.js +0 -45
  75. package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
  76. package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
  77. package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
  78. package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
  79. package/dist/cli/commands/vm-release-command.d.ts +0 -5
  80. package/dist/cli/commands/vm-release-command.js +0 -101
  81. package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
  82. package/dist/cli/commands/vm-spawn-command.js +0 -177
  83. package/dist/cli/commands/vm-status-command.d.ts +0 -3
  84. package/dist/cli/commands/vm-status-command.js +0 -50
  85. package/dist/services/vm/vm-lease.d.ts +0 -40
  86. package/dist/services/vm/vm-lease.js +0 -160
@@ -0,0 +1,237 @@
1
+ /**
2
+ *
3
+ * Reads and validates the `--lookup-results <file>` document that lets a
4
+ * caller — in practice the LLM, holding real Context7 / WebSearch results from
5
+ * its own MCP tool — inject real documentation fragments into
6
+ * `best-practice-scan`. The CLI itself never performs that lookup and never
7
+ * touches the network; this module is the only seam between the two.
8
+ *
9
+ * The document speaks the scan seam's own vocabulary: one optional key per
10
+ * priority, whose value is exactly `LookupFn`'s return type.
11
+ *
12
+ * { "intent": "<the same string that was passed to --intent>",
13
+ * "context7": { "ok": true, "results": [ { "title", "url", "snippet" } ] },
14
+ * "websearch": { "ok": true, "results": [ { "title", "url", "snippet" } ] } }
15
+ *
16
+ * One refusal code, `BEST_PRACTICE_SCAN_INVALID_RESULTS`. A file that breaks
17
+ * any rule performs no scan and writes no artifact — the caller is the LLM,
18
+ * which either produced a valid file or needs to be told which field is wrong.
19
+ *
20
+ * `ok: true` requires a non-empty `results` array: a claimed hit that carries
21
+ * nothing is the shape a fabrication would take, and it is refused rather than
22
+ * rendered. **The converse is not a miss.** `ok: false` does not end the scan —
23
+ * the orchestrator falls *through* a failed priority to the next one, and a
24
+ * chain in which no stub took part reports `synthetic: false` even when it found
25
+ * nothing. A document declaring `ok: false` on every seam it supplies is
26
+ * therefore valid *and* fragments-free; the CLI, not this module, refuses it.
27
+ *
28
+ * Unknown keys are refused at every level, not just the top: the document is
29
+ * the caller's, and a key this module would ignore is a key the caller believed
30
+ * it was sending. Refusing them also bounds the parsed structure, so nothing
31
+ * downstream can be handed an arbitrarily deep object.
32
+ */
33
+ import { readFileSync, statSync } from 'node:fs';
34
+ import { fail, redactSensitiveErrorMessage } from 'peaks-loop-shared/result';
35
+ import { getErrorMessage, printableWarningText, printResult } from '../cli-helpers.js';
36
+ /** The two seam keys a document may carry, named as the orchestrator names them. */
37
+ const SEAM_KEYS = ['context7', 'websearch'];
38
+ const ALLOWED_KEYS = ['intent', ...SEAM_KEYS];
39
+ const ALLOWED_SEAM_KEYS = ['ok', 'results'];
40
+ const ALLOWED_FRAGMENT_KEYS = ['title', 'url', 'snippet'];
41
+ const INVALID_RESULTS_CODE = 'BEST_PRACTICE_SCAN_INVALID_RESULTS';
42
+ /** A best-practice scan cites a handful of fragments; it does not ingest a corpus. */
43
+ const MAX_RESULTS_FILE_BYTES = 1_048_576;
44
+ const MAX_FRAGMENTS_PER_SEAM = 64;
45
+ const BOM_CODE_POINT = 0xfeff;
46
+ function isPlainObject(value) {
47
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
48
+ }
49
+ /**
50
+ * The first key of `value` that is not in `allowed`, or `undefined`.
51
+ *
52
+ * The NAME comes back sanitised for echoing, and that is deliberate: every
53
+ * caller of this function puts the key into a refusal message, the key is the
54
+ * document's own text, and nothing stops it carrying an ESC sequence (which
55
+ * reaches a terminal raw) or a newline (which forges a line of this command's
56
+ * own output). Matching is done against the raw key first, so the allowance
57
+ * check is unaffected.
58
+ */
59
+ function firstUnknownKey(value, allowed) {
60
+ const key = Object.keys(value).find((candidate) => !allowed.includes(candidate));
61
+ return key === undefined ? undefined : safeToEcho(key);
62
+ }
63
+ function isFragment(value) {
64
+ if (!isPlainObject(value))
65
+ return false;
66
+ if (firstUnknownKey(value, ALLOWED_FRAGMENT_KEYS) !== undefined)
67
+ return false;
68
+ return ALLOWED_FRAGMENT_KEYS.every((field) => {
69
+ const candidate = value[field];
70
+ return typeof candidate === 'string' && candidate.trim().length > 0;
71
+ });
72
+ }
73
+ /** The first malformed fragment, as its refusal message; `null` when all are well formed. */
74
+ function firstBadFragment(key, results) {
75
+ for (let index = 0; index < results.length; index += 1) {
76
+ if (!isFragment(results[index])) {
77
+ return `"${key}".results[${index}] must have non-empty string title, url and snippet, and no other keys`;
78
+ }
79
+ }
80
+ return null;
81
+ }
82
+ /** `{ ok: boolean, results: unknown[] }`, the only seam value shape accepted. */
83
+ function isSeamShape(value) {
84
+ return isPlainObject(value) && typeof value.ok === 'boolean' && Array.isArray(value.results);
85
+ }
86
+ /** Rules 6-8: one seam value must be `{ ok: boolean, results: DocFragment[] }`. */
87
+ function parseSeam(key, value) {
88
+ if (!isSeamShape(value)) {
89
+ return {
90
+ ok: false,
91
+ message: `"${key}" must be an object with a boolean "ok" and an array "results"`
92
+ };
93
+ }
94
+ const unknownKey = firstUnknownKey(value, ALLOWED_SEAM_KEYS);
95
+ if (unknownKey !== undefined) {
96
+ return {
97
+ ok: false,
98
+ message: `unknown key "${unknownKey}" in "${key}"; allowed keys are ${ALLOWED_SEAM_KEYS.join(', ')}`
99
+ };
100
+ }
101
+ const results = value.results;
102
+ if (value.ok && results.length === 0) {
103
+ return {
104
+ ok: false,
105
+ message: `"${key}" declares ok: true but "results" is empty; a hit must carry at least one fragment`
106
+ };
107
+ }
108
+ // Kept deliberately (Karpathy V2 raised it as speculative): `ok: false` with a
109
+ // non-empty `results` is a document that contradicts itself, and the
110
+ // orchestrator would read `ok` and silently discard the fragments. A caller
111
+ // that meant `ok: true` and mistyped it must be told, not half-read.
112
+ if (!value.ok && results.length > 0) {
113
+ return {
114
+ ok: false,
115
+ message: `"${key}" declares ok: false but "results" is non-empty`
116
+ };
117
+ }
118
+ if (results.length > MAX_FRAGMENTS_PER_SEAM) {
119
+ return {
120
+ ok: false,
121
+ message: `"${key}" carries ${results.length} fragments, over the cap of ${MAX_FRAGMENTS_PER_SEAM}; cite the few that matter`
122
+ };
123
+ }
124
+ const bad = firstBadFragment(key, results);
125
+ if (bad !== null)
126
+ return { ok: false, message: bad };
127
+ return {
128
+ ok: true,
129
+ value: { ok: value.ok, results: results }
130
+ };
131
+ }
132
+ /** Rules 2-8 over an already-parsed JSON value. Pure: no fs, no io. */
133
+ function parseLookupResults(value, intent) {
134
+ if (!isPlainObject(value)) {
135
+ return {
136
+ ok: false,
137
+ message: `the top level must be a JSON object, not ${Array.isArray(value) ? 'an array' : typeof value}`
138
+ };
139
+ }
140
+ const unknownKey = firstUnknownKey(value, ALLOWED_KEYS);
141
+ if (unknownKey !== undefined) {
142
+ return {
143
+ ok: false,
144
+ message: `unknown top-level key "${unknownKey}"; allowed keys are ${ALLOWED_KEYS.join(', ')}`
145
+ };
146
+ }
147
+ const present = SEAM_KEYS.filter((key) => value[key] !== undefined);
148
+ if (present.length === 0) {
149
+ return { ok: false, message: 'at least one of "context7" or "websearch" must be present' };
150
+ }
151
+ if (value.intent !== intent) {
152
+ const declared = typeof value.intent === 'string' ? safeToEcho(value.intent) : value.intent;
153
+ return {
154
+ ok: false,
155
+ message: `intent mismatch: the file declares ${JSON.stringify(declared)} but --intent is ${JSON.stringify(safeToEcho(intent))}`
156
+ };
157
+ }
158
+ const lookups = {};
159
+ for (const key of present) {
160
+ const parsed = parseSeam(key, value[key]);
161
+ if (!parsed.ok)
162
+ return { ok: false, message: parsed.message };
163
+ const seam = parsed.value;
164
+ // The return type is annotated because the `async` is a contract, not a
165
+ // convenience: `LookupFn` requires a Promise and `seam` is a plain object.
166
+ if (key === 'context7') {
167
+ lookups.context7Lookup = async () => seam;
168
+ }
169
+ else {
170
+ lookups.webSearchLookup = async () => seam;
171
+ }
172
+ }
173
+ return { ok: true, lookups };
174
+ }
175
+ /** A caller-supplied string is echoed into a refusal; make it safe to echo. */
176
+ function safeToEcho(value) {
177
+ return printableWarningText(redactSensitiveErrorMessage(value));
178
+ }
179
+ /**
180
+ * Rule 1 plus the refusal. Returns the injected seam lookups, or `null` after
181
+ * emitting `BEST_PRACTICE_SCAN_INVALID_RESULTS` — in which case the caller must
182
+ * set a non-zero exit code and scan nothing.
183
+ */
184
+ export function readLookupResultsOrFail(file, intent, io, asJson) {
185
+ const read = readJsonOrFail(file);
186
+ const parsed = read.ok
187
+ ? parseLookupResults(read.value, intent)
188
+ : { ok: false, message: read.message };
189
+ if (parsed.ok)
190
+ return parsed.lookups;
191
+ printResult(io, fail('best-practice.scan', INVALID_RESULTS_CODE, parsed.message, { lookupResults: safeToEcho(file), intent: safeToEcho(intent) }, ['Fix the lookup-results file, or rerun without --lookup-results to record the honest skip.']), asJson);
192
+ return null;
193
+ }
194
+ /** Rule 1: read the file and parse it as JSON, or say why not. */
195
+ function readJsonOrFail(file) {
196
+ const shown = safeToEcho(file);
197
+ // The size gate runs BEFORE the read so an oversized file is never read, and
198
+ // before the parse so it is never parsed.
199
+ let size;
200
+ try {
201
+ size = statSync(file).size;
202
+ }
203
+ catch (err) {
204
+ return {
205
+ ok: false,
206
+ message: `cannot read lookup-results file at ${shown}: ${safeToEcho(getErrorMessage(err))}`
207
+ };
208
+ }
209
+ if (size > MAX_RESULTS_FILE_BYTES) {
210
+ return {
211
+ ok: false,
212
+ message: `${shown} is ${size} bytes, over the ${MAX_RESULTS_FILE_BYTES}-byte cap for a ` +
213
+ 'lookup-results file; cite a handful of fragments, not a corpus'
214
+ };
215
+ }
216
+ let raw;
217
+ try {
218
+ raw = readFileSync(file, 'utf8');
219
+ }
220
+ catch (err) {
221
+ return {
222
+ ok: false,
223
+ message: `cannot read lookup-results file at ${shown}: ${safeToEcho(getErrorMessage(err))}`
224
+ };
225
+ }
226
+ // Windows editors write a BOM and JSON.parse rejects it, so strip it.
227
+ const text = raw.charCodeAt(0) === BOM_CODE_POINT ? raw.slice(1) : raw;
228
+ try {
229
+ return { ok: true, value: JSON.parse(text) };
230
+ }
231
+ catch {
232
+ // Deliberately not echoing the parser's message: V8 quotes ~10 bytes of the
233
+ // file back, which leaks file content past `fail()`'s secret redaction, and
234
+ // copies control bytes to a terminal verbatim.
235
+ return { ok: false, message: `${shown} is not valid JSON` };
236
+ }
237
+ }
@@ -27,7 +27,7 @@ function applyDispatchInputOptions(command) {
27
27
  .option('--write-artifact <path>', 'G7: register an artifact file at <path>; CLI computes sha256 + size + writes ArtifactMeta to the dispatch record')
28
28
  .option('--force', 'G9: override the 80% hard reject threshold at CLI (NOT allowed at hook layer per RL-30 strict)')
29
29
  .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')
30
- .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface), "container" (Part 8 contract + Part 12 L4 docker runtime), or "vm" (Part 25 contract; the VM runtime is a follow-up rid and fail-fasts with ISOLATION_VM_NOT_YET_IMPLEMENTED). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')
30
+ .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface) or "container" (Part 8 contract + Part 12 L4 docker runtime). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')
31
31
  // Slice 4.0.8 RD §4 made this a `.requiredOption`. It is optional now:
32
32
  // the requirement was enforced but never validated — nothing downstream
33
33
  // reads the node, and the record writer's graph transition is
@@ -9,7 +9,7 @@ export interface IsolationLeaseInput {
9
9
  asJson: boolean;
10
10
  }
11
11
  export interface IsolationLease {
12
- isolationMode: 'worktree' | 'container' | 'vm' | null;
12
+ isolationMode: 'worktree' | 'container' | null;
13
13
  leaseId: string | null;
14
14
  worktreePath: string | null;
15
15
  worktreeBranch: string | null;
@@ -1,15 +1,15 @@
1
- // The `--isolation` lease set-up of `peaks sub-agent dispatch`. Validates the mode,
2
- // spawns the container/worktree lease, and hands the handles back; `vm` fail-fasts
3
- // because the runtime is not implemented yet.
1
+ // The `--isolation` lease set-up of `peaks sub-agent dispatch`. Validates the mode and
2
+ // spawns the container/worktree lease, handing the handles back. `vm` is not a mode:
3
+ // it is refused by the same guard as any other unrecognised value.
4
4
  import { fail, getErrorMessage } from 'peaks-loop-shared/result';
5
5
  import { printResult } from '../cli-helpers.js';
6
6
  import { spawnWorktreeLease, spawnContainerLease } from '../../services/dispatch/isolation-lease.js';
7
7
  function rejectInvalidIsolation(io, isolation, role, asJson) {
8
- printResult(io, fail('sub-agent.dispatch', 'INVALID_ISOLATION', `--isolation only accepts "worktree" | "container" | "vm" (got "${isolation}")`, {
8
+ printResult(io, fail('sub-agent.dispatch', 'INVALID_ISOLATION', `--isolation only accepts "worktree" | "container" (got "${isolation}")`, {
9
9
  role,
10
10
  toolCall: null,
11
11
  dispatchRecordPath: null
12
- }, ['Drop --isolation or pass --isolation worktree / --isolation container / --isolation vm.']), asJson);
12
+ }, ['Drop --isolation or pass --isolation worktree / --isolation container.']), asJson);
13
13
  process.exitCode = 1;
14
14
  return null;
15
15
  }
@@ -80,48 +80,6 @@ async function spawnWorktreeIsolation(io, input) {
80
80
  return null;
81
81
  }
82
82
  }
83
- function rejectVmIsolation(io, input) {
84
- const { role, asJson } = input;
85
- // VM isolation mode is the L4 follow-up to L4 container.
86
- // The CLI contract is shipped (--isolation vm is accepted
87
- // by the dispatch parser and reflected in the envelope's
88
- // isolationMode type). The VM runtime (Linux KVM / macOS
89
- // HyperKit / Windows Hyper-V) is a much larger follow-up
90
- // and is intentionally not implemented yet — we
91
- // fail-fast with ISOLATION_VM_NOT_YET_IMPLEMENTED so
92
- // operators see a clear "this is a placeholder" signal
93
- // rather than a silent fallback to worktree.
94
- //
95
- // The full implementation lives in a future rid; the
96
- // design is:
97
- // 1. New service: src/services/vm/vm-lease.ts (parallels
98
- // worktree-lease.ts / container-lease.ts) — pure lease
99
- // store with vmId + hypervisor + status.
100
- // 2. CLI: 'peaks vm spawn --hypervisor kvm|hyperkit|hyperv
101
- // --image <name> --rid <rid> --role <role>' — runs
102
- // virsh create / hvftool / hvcreate, captures the
103
- // vm id, writes the lease.
104
- // 3. CLI: 'peaks vm release --lease-id <id>' — virsh
105
- // destroy + cleanup.
106
- // 4. dispatch --isolation vm: shells out to peaks vm
107
- // spawn, injects PEAKS_VM_LEASE_ID env (parallel
108
- // to PEAKS_CONTAINER_LEASE_ID).
109
- // 5. PreToolUse gate: when the env var is set AND the
110
- // tool call is bash-with-vm-bearing-command,
111
- // allow via the vm lease.
112
- //
113
- // Until then: fail-fast.
114
- printResult(io, fail('sub-agent.dispatch', 'ISOLATION_VM_NOT_YET_IMPLEMENTED', '--isolation vm is the L4 follow-up to --isolation container (Part 25 contract); the VM runtime (KVM / HyperKit / Hyper-V) is a much larger follow-up rid and is intentionally not implemented yet. Drop --isolation or pass --isolation worktree / --isolation container for now.', {
115
- role,
116
- toolCall: null,
117
- dispatchRecordPath: null
118
- }, [
119
- 'The VM contract is shipped (--isolation vm is accepted by the dispatch parser); the runtime is the next rid.',
120
- 'Use --isolation worktree (L2 production) or --isolation container (L4 docker, Part 12) for now.'
121
- ]), asJson);
122
- process.exitCode = 1;
123
- return null;
124
- }
125
83
  export async function resolveIsolationLease(io, options, input) {
126
84
  const { role, asJson } = input;
127
85
  // auto-spawns a worktree lease and injects PEAKS_WORKTREE_LEASE_ID
@@ -130,9 +88,7 @@ export async function resolveIsolationLease(io, options, input) {
130
88
  // without this injection, the gate has no leaseId to consult and
131
89
  // the sub-agent would need a separate `peaks worktree auth grant`.
132
90
  if (typeof options.isolation === 'string' && options.isolation.length > 0) {
133
- if (options.isolation !== 'worktree' &&
134
- options.isolation !== 'container' &&
135
- options.isolation !== 'vm') {
91
+ if (options.isolation !== 'worktree' && options.isolation !== 'container') {
136
92
  return rejectInvalidIsolation(io, options.isolation, role, asJson);
137
93
  }
138
94
  if (options.isolation === 'container') {
@@ -141,9 +97,6 @@ export async function resolveIsolationLease(io, options, input) {
141
97
  if (options.isolation === 'worktree') {
142
98
  return spawnWorktreeIsolation(io, input);
143
99
  }
144
- else if (options.isolation === 'vm') {
145
- return rejectVmIsolation(io, input);
146
- }
147
100
  }
148
101
  return { isolationMode: null, leaseId: null, worktreePath: null, worktreeBranch: null };
149
102
  }
@@ -1,5 +1,5 @@
1
1
  import { type DispatchOptions } from './sub-agent-shared.js';
2
- export declare function buildIsolationBlock(isolationMode: 'worktree' | 'container' | 'vm' | null, leaseId: string | null, worktreePath: string | null, worktreeBranch: string | null): string;
2
+ export declare function buildIsolationBlock(isolationMode: 'worktree' | 'container' | null, leaseId: string | null, worktreePath: string | null, worktreeBranch: string | null): string;
3
3
  export declare function buildMustLsFilesBlock(options: DispatchOptions, projectRoot: string): {
4
4
  mustLsFilesVerification: {
5
5
  path: string;
@@ -11,7 +11,7 @@ export interface ComposeDispatchPromptInput {
11
11
  options: DispatchOptions;
12
12
  /** The prompt the sub-agent receives, as `preflightDispatch` resolved it. */
13
13
  prompt: string;
14
- isolationMode: 'worktree' | 'container' | 'vm' | null;
14
+ isolationMode: 'worktree' | 'container' | null;
15
15
  leaseId: string | null;
16
16
  worktreePath: string | null;
17
17
  worktreeBranch: string | null;
@@ -11,7 +11,7 @@ export interface WriteDispatchRecordInput {
11
11
  effectivePrompt: string;
12
12
  toolCall: SubAgentToolCall;
13
13
  batchId: string;
14
- isolationMode: 'worktree' | 'container' | 'vm' | null;
14
+ isolationMode: 'worktree' | 'container' | null;
15
15
  leaseId: string | null;
16
16
  /** The dispatch's warning list — this function appends to it, as the inline block did. */
17
17
  warnings: string[];
@@ -8,7 +8,7 @@ export interface BuildDispatchToolCallInput {
8
8
  rid: string;
9
9
  sid: string;
10
10
  projectRoot: string;
11
- isolationMode: 'worktree' | 'container' | 'vm' | null;
11
+ isolationMode: 'worktree' | 'container' | null;
12
12
  leaseId: string | null;
13
13
  asJson: boolean;
14
14
  }
@@ -111,13 +111,13 @@ export function nextActionsForArchiveError(code) {
111
111
  ];
112
112
  case 'OPENSPEC_COVERAGE_EVIDENCE_MISSING':
113
113
  return [
114
- 'Run `pnpm test:coverage` (which invokes scripts/coverage-c8.mjs) to generate coverage-summary.json',
114
+ 'Generate coverage/coverage-summary.json with the project coverage run (`node .husky/coverage-ratchet.mjs` in this repo)',
115
115
  'Or pass --coverage-summary <path> to point at an existing summary',
116
116
  'Or re-run with --force to bypass the gate'
117
117
  ];
118
118
  case 'OPENSPEC_COVERAGE_EVIDENCE_STALE':
119
119
  return [
120
- 'Re-run `pnpm test:coverage` to refresh coverage-summary.json',
120
+ 'Re-generate coverage/coverage-summary.json, then re-run',
121
121
  'Or re-run with --force to bypass the gate after confirming the source delta is acceptable'
122
122
  ];
123
123
  case 'OPENSPEC_COVERAGE_EVIDENCE_MISMATCH':
@@ -5,6 +5,7 @@
5
5
  import { InvalidArgumentError } from 'commander';
6
6
  import { PrerequisitesNotSatisfiedError, LintGateError, TypeSanityViolationError, FileSizeViolationError } from '../../services/artifacts/request-artifact-service.js';
7
7
  import { StateOrderViolationError } from '../../services/artifacts/request-state-order.js';
8
+ import { TypeCorroborationViolationError } from '../../services/artifacts/rd-transition-gates.js';
8
9
  import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.js';
9
10
  import { fail } from 'peaks-loop-shared/result';
10
11
  import { getErrorMessage, printableWarningText, printResult } from '../cli-helpers.js';
@@ -36,21 +37,39 @@ function reportPrerequisitesFailure(io, options, error) {
36
37
  missing: error.missing,
37
38
  warnings: error.warnings
38
39
  }, [
39
- ...error.missing.map((entry) => `Produce ${entry.path}: ${entry.description}`),
40
+ // `Satisfy`, not `Produce`: a `missing` entry is an unmet REQUIREMENT, not
41
+ // necessarily an absent file. A present artifact refused for the judged
42
+ // declaration it does not carry was reported as one to "Produce", and a
43
+ // producer that did exactly that changed nothing.
44
+ ...error.missing.map((entry) => `Satisfy ${entry.path}: ${entry.description}`),
40
45
  // Sanitised for the same reason the success branch sanitises: a
41
46
  // `gateEvidence.<key>` warning can carry a control character decoded out
42
47
  // of the handoff frontmatter, and `printResult` puts these on stderr.
43
48
  ...error.warnings.map((w) => `Soft-blocked (v2.13.3 back-compat window): ${printableWarningText(w.path)} — ` +
44
49
  `${printableWarningText(w.message)}${softWarningExpiryClause(w)}`),
45
- 'Once every required artifact exists, rerun this transition.',
50
+ 'Once every unmet requirement above is met, rerun this transition.',
46
51
  'For exceptional cases (docs-only / config-only change), bypass with: --allow-incomplete --reason "<justification>"'
47
52
  ]), options.json);
48
53
  process.exitCode = 1;
49
54
  }
50
55
  function reportLintGateFailure(io, options, error) {
51
- printResult(io, fail('request.transition', error.code, error.message, { role: error.role, newState: error.newState, errorCount: error.errorCount }, [
56
+ printResult(io, fail('request.transition', error.code, error.message, {
57
+ role: error.role,
58
+ newState: error.newState,
59
+ errorCount: error.errorCount,
60
+ findings: error.findings
61
+ }, [
62
+ // One line per unmet placeholder, naming the line, the offending text and
63
+ // the rule's own reason. The refusal used to carry only their count, so a
64
+ // producer was told HOW MANY were wrong and not one of them WHERE or WHY.
65
+ ...error.findings.map((finding) => `Line ${finding.line}: ${printableWarningText(finding.text)} — ` +
66
+ printableWarningText(finding.reason)),
52
67
  'Fix lint errors in the artifact before transitioning.',
53
- 'Run `peaks request lint --role <role> --id <rid> --project <path>` to see details.',
68
+ // The rid is POSITIONAL; `--id` is not an option this command has, and the
69
+ // earlier hint named it — so the one remedy this refusal offered was a
70
+ // command the CLI answers with `unknown option '--id'`. Verified by running
71
+ // the substituted form: it reaches the action.
72
+ 'Run `peaks request lint <rid> --role <role> --project <path>` to see details.',
54
73
  'Or bypass with: --allow-incomplete --reason "<justification>"'
55
74
  ]), options.json);
56
75
  process.exitCode = 1;
@@ -90,6 +109,10 @@ function reportFileSizeFailure(io, options, error) {
90
109
  ]), options.json);
91
110
  process.exitCode = 1;
92
111
  }
112
+ function reportTypeCorroborationFailure(io, options, error) {
113
+ printResult(io, fail('request.transition', error.code, error.message, { declaredType: error.declaredType, kind: error.kind }, ['Or bypass with: --allow-incomplete --reason "<justification>"']), options.json);
114
+ process.exitCode = 1;
115
+ }
93
116
  function reportConfirmationFailure(io, options, requestId, error) {
94
117
  printResult(io, fail('request.transition', 'CONFIRMATION_REQUIRED', error.message, { role: options.role, requestId, transitionKey: error.transitionKey, mode: error.mode }, [...error.nextActions]), options.json);
95
118
  process.exitCode = 1;
@@ -123,6 +146,10 @@ export function reportTransitionFailure(io, options, requestId, error) {
123
146
  reportFileSizeFailure(io, options, error);
124
147
  return;
125
148
  }
149
+ if (error instanceof TypeCorroborationViolationError) {
150
+ reportTypeCorroborationFailure(io, options, error);
151
+ return;
152
+ }
126
153
  if (error instanceof ConfirmationRequiredError) {
127
154
  reportConfirmationFailure(io, options, requestId, error);
128
155
  return;
@@ -48,7 +48,7 @@ function refuseAllowIncompleteRestricted(io, ctx, mode) {
48
48
  process.exitCode = 1;
49
49
  }
50
50
  function refuseBypassLimitReached(io, ctx) {
51
- printResult(io, fail('request.transition', 'BYPASS_LIMIT_REACHED', `--allow-incomplete limit reached (${MAX_BYPASSES_PER_SESSION} per session)`, { role: ctx.role, requestId: ctx.requestId, limit: MAX_BYPASSES_PER_SESSION }, ['Produce the missing artifacts instead of bypassing.']), ctx.options.json);
51
+ printResult(io, fail('request.transition', 'BYPASS_LIMIT_REACHED', `--allow-incomplete limit reached (${MAX_BYPASSES_PER_SESSION} per session)`, { role: ctx.role, requestId: ctx.requestId, limit: MAX_BYPASSES_PER_SESSION }, ['Satisfy the unmet requirements instead of bypassing.']), ctx.options.json);
52
52
  process.exitCode = 1;
53
53
  }
54
54
  /**
@@ -4,6 +4,7 @@
4
4
  // 300-line file cap.
5
5
  import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
6
6
  import { join } from 'node:path';
7
+ import { slugifyDescription } from '../../shared/incrementing-number.js';
7
8
  export function readPrdBody(rid, projectRoot) {
8
9
  // Search all .peaks/**/prd/requests/*-<rid>.md and .peaks/**/prd/requests/<rid>.md
9
10
  const searchRoots = [
@@ -25,7 +26,7 @@ export function readPrdBody(rid, projectRoot) {
25
26
  for (const entry of entries) {
26
27
  if (!entry.endsWith('.md'))
27
28
  continue;
28
- if (entry === `${rid}.md` || entry.endsWith(`-${rid}.md`)) {
29
+ if (entry === `${rid}.md` || entry.endsWith(`-${slugifyDescription(rid)}.md`)) {
29
30
  return readFileSync(join(dir, entry), 'utf8');
30
31
  }
31
32
  }
@@ -8,6 +8,7 @@ import { isUnsafePathInput } from '../../shared/path-safety.js';
8
8
  import { DEFAULT_REQUEST_TYPE } from '../../services/artifacts/artifact-prerequisites.js';
9
9
  import { REQUEST_ID_PATTERN } from '../../services/artifacts/request-artifact-service.js';
10
10
  import { contractEvidencePaths } from '../../services/workflow/pipeline-verify-gate-support.js';
11
+ import { slugifyDescription } from '../../shared/incrementing-number.js';
11
12
  // filenames carry the rid. The ridless names are the pre-rid locations and
12
13
  // see `MUT_REPORT` in `artifact-prerequisites.ts`: no producer in the repo
13
14
  // look for a file that no writer can create.
@@ -176,7 +177,7 @@ async function readMut(projectRoot, sid) {
176
177
  }
177
178
  function readQa(projectRoot, sid, rid) {
178
179
  const dir = join(projectRoot, '.peaks', '_runtime', sid, QA_REL);
179
- const candidates = [`${rid}.md`, `001-${rid}.md`];
180
+ const candidates = [`${rid}.md`, `001-${slugifyDescription(rid)}.md`];
180
181
  for (const name of candidates) {
181
182
  const path = join(dir, name);
182
183
  if (existsSync(path)) {
@@ -2,9 +2,9 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
2
2
  import { fail, ok } from 'peaks-loop-shared/result';
3
3
  import { getSessionId } from '../../services/session/session-manager.js';
4
4
  import { verifyPipeline } from '../../services/workflow/pipeline-verify-service.js';
5
- import { applySkip, detectCallerKind } from '../../services/workflow/workflow-skip-service.js';
5
+ import { applySkip, detectCallerKind, SKIPPABLE_TYPES } from '../../services/workflow/workflow-skip-service.js';
6
6
  const VERIFY_PIPELINE_DESCRIPTION = 'Verify the complete rd→qa pipeline was followed for a request. Scans the v2.17.0 canonical session-axis layout (artifacts under _runtime per-session) and falls back to the legacy v2.16.0 change-axis forms during the 1-minor-release deprecation window.';
7
- const SKIP_DESCRIPTION = 'Skip specific gates for a request (RD/QA). Use --dry-run to preview without writing. Allowed gate names: QA / RD (phase shortcuts) or specific gate names (rd-request-exists, prd-handoff, bug-analysis, code-review, security-review, perf-baseline, qa-request-exists, test-cases, test-report). Three rules apply: (1) only docs/config/chore slices can skip; (2) skip is one-time per rid; (3) script callers must also pass --i-have-reviewed.';
7
+ const SKIP_DESCRIPTION = `Skip specific gates for a request (RD/QA). Use --dry-run to preview without writing. Allowed gate names: QA / RD (phase shortcuts) or specific gate names (rd-request-exists, prd-handoff, bug-analysis, code-review, security-review, perf-baseline, qa-request-exists, test-cases, test-report). Three rules apply: (1) only ${SKIPPABLE_TYPES.join('/')} slices can skip; (2) skip is one-time per rid; (3) script callers must also pass --i-have-reviewed.`;
8
8
  /** The action body, lifted to a module-level function so both it and the registrar fit in 50 lines. */
9
9
  async function runVerifyPipeline(options, io) {
10
10
  try {
@@ -50,7 +50,7 @@ function reportSkipOutcome(io, options, sessionId, result) {
50
50
  }
51
51
  // applied:false + reason → rejection.
52
52
  printResult(io, fail('workflow.skip', 'SKIP_REJECTED', result.reason ?? 'unknown rejection', result, [
53
- 'See RD request for the three rules: docs/config/chore only, one-time per rid, script callers need --i-have-reviewed.'
53
+ `See RD request for the three rules: ${SKIPPABLE_TYPES.join('/')} only, one-time per rid, script callers need --i-have-reviewed.`
54
54
  ]), options.json);
55
55
  process.exitCode = 1;
56
56
  }
@@ -97,7 +97,7 @@ export function registerWorkflowGateCommands(workflow, io) {
97
97
  .description(VERIFY_PIPELINE_DESCRIPTION)
98
98
  .requiredOption('--rid <rid>', 'request identifier')
99
99
  .requiredOption('--project <path>', 'project root path')
100
- .option('--type <type>', 'request type: feature, bugfix, refactor, docs, config, chore', 'feature')
100
+ .option('--type <type>', "request type: feature, bugfix, refactor, docs, config, chore. Omit it and the rid's own request artifact decides — the recorded `- type:` line on its RD (then PRD, then QA) carrier. Only a `--type` given here overrides that.")
101
101
  .option('--session-id <sid>', 'slice 2026-06-13-peaks-workflow-skip: session id under which to read the skip-state file. When omitted, no skip-state is consulted (legacy behavior).')).action((options) => runVerifyPipeline(options, io));
102
102
  // Mark gates as bypassed for a specific rid, so the next
103
103
  // `verify-pipeline` reports them as `status: 'skipped'` instead of
@@ -11,7 +11,6 @@ import { registerLeaseMetricsCommand } from './commands/lease-metrics-commands.j
11
11
  import { registerMcpCommands } from './commands/mcp-commands.js';
12
12
  import { registerLeaseStatsCommand } from './commands/lease-stats-commands.js';
13
13
  import { registerContainerCommand } from './commands/container-commands.js';
14
- import { registerVmCommand } from './commands/vm-commands.js';
15
14
  import { registerCronCommand } from './commands/cron-commands.js';
16
15
  import { registerCronSchedulerCommand } from './commands/cron-scheduler-commands.js';
17
16
  import { registerWorkspaceCommands } from './commands/workspace-commands.js';
@@ -195,7 +194,6 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
195
194
  registerLeaseMetricsCommand(program, io);
196
195
  registerLeaseStatsCommand(program, io);
197
196
  registerContainerCommand(program, io);
198
- registerVmCommand(program, io);
199
197
  registerCronCommand(program, io);
200
198
  registerCronSchedulerCommand(program, io);
201
199
  // The read-only MCP surface's command family. `serve` spawns the server
@@ -108,6 +108,15 @@ const BODY_RULE = 'The gate matches each marker below as a case-insensitive subs
108
108
  */
109
109
  const SCOPE_BASE = 'This block is generated from the prerequisite table alone, so the rows below are necessary and are ' +
110
110
  'not a complete contract.';
111
+ /**
112
+ * The body-lint gate, named in EVERY non-empty block because it runs for every role
113
+ * and every type: the transition OUT of `draft` lints the artifact and refuses on
114
+ * any placeholder the template still carries. The block said nothing about it, so a
115
+ * producer that satisfied every row below still met a refusal the carrier had never
116
+ * mentioned — the same defect as a row whose marker the producer was not shown.
117
+ */
118
+ const SCOPE_LINT = ' Separately from the rows above: leaving `draft` runs the body lint over this artifact, and it ' +
119
+ 'refuses on a placeholder the template still carries — an unfilled `<...>` token or a `- ...` stub.';
111
120
  /**
112
121
  * The addendum for a state the gate really does guard with more than the table.
113
122
  * Measured on a probe project and again on this slice's own rid: an artifact set
@@ -115,9 +124,19 @@ const SCOPE_BASE = 'This block is generated from the prerequisite table alone, s
115
124
  * outside the table. The earlier wording said a gate "may also check something
116
125
  * the table does not carry", which under-claims a systematic gap at exactly the
117
126
  * state this block guides a producer to.
127
+ *
128
+ * The declaration is named because naming it is the whole fix: the refusal used to
129
+ * report the artifact as absent when the artifact was there and only its
130
+ * declaration was unmet, so a producer that read this far-first ended one refusal
131
+ * later than it needed to.
132
+ * NO PRODUCER IS NAMED: the same declaration is required of whichever security
133
+ * artifact the rows above demand — a `config` slice's is `rd/security-review-<rid>.md`
134
+ * — and more than one in-repo producer writes a valid one.
118
135
  */
119
136
  const SCOPE_HANDOFF = ' At `rd:qa-handoff` the gate also runs checks that are not rows of this table, so satisfying every ' +
120
- 'row below does not by itself open that transition.';
137
+ 'row below does not by itself open that transition. One is the judged declaration: the security ' +
138
+ 'artifact the rows above name must also carry a `## Judged content` block, and a body written ' +
139
+ 'without one satisfies the row and is still refused.';
121
140
  const ARTIFACT_CONTRACT_HEADING = '## Artifact contract (generated from the prerequisite table)';
122
141
  /**
123
142
  * The block, or `''` when this role has nothing gated to say under this type.
@@ -139,7 +158,7 @@ export function buildArtifactContractBlock(input) {
139
158
  return (`\n${ARTIFACT_CONTRACT_HEADING}\n` +
140
159
  `Role \`${input.role}\`, ${typeLine}.\n` +
141
160
  `${BODY_RULE}\n` +
142
- `${SCOPE_BASE}${guardedHandoff ? SCOPE_HANDOFF : ''}\n` +
161
+ `${SCOPE_BASE}${guardedHandoff ? SCOPE_HANDOFF : ''}${SCOPE_LINT}\n` +
143
162
  rows.map((row) => row.text).join('') +
144
163
  '\n');
145
164
  }