peaks-loop 4.1.17 → 4.1.19

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 (205) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +269 -0
  3. package/README-en.md +6 -0
  4. package/README.md +5 -0
  5. package/contracts/test-style-contract.md +14 -5
  6. package/dist/cli/commands/audit-red-lines-runners.js +6 -1
  7. package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
  8. package/dist/cli/commands/best-practice-scan-collision.js +115 -0
  9. package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
  10. package/dist/cli/commands/best-practice-scan-command.js +9 -18
  11. package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
  12. package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
  13. package/dist/cli/commands/code-auto-compact-command.js +71 -40
  14. package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
  15. package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
  16. package/dist/cli/commands/code-gate-command.d.ts +4 -4
  17. package/dist/cli/commands/code-gate-command.js +4 -4
  18. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  19. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  20. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  21. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  22. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  23. package/dist/cli/commands/core/skill-registry-commands.js +32 -0
  24. package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
  25. package/dist/cli/commands/core/skill-store-report.js +79 -0
  26. package/dist/cli/commands/core/standards-init-command.js +44 -8
  27. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  28. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  29. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  30. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  31. package/dist/cli/commands/dispatch-prompt-composition.js +7 -2
  32. package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
  33. package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
  34. package/dist/cli/commands/hooks-commands.js +36 -7
  35. package/dist/cli/commands/hooks-uninstall-command.js +5 -5
  36. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  37. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  38. package/dist/cli/commands/mut-commands.d.ts +9 -1
  39. package/dist/cli/commands/mut-commands.js +82 -154
  40. package/dist/cli/commands/preferences-commands.js +27 -2
  41. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  42. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  43. package/dist/services/24h-mode/auto-engage.js +14 -6
  44. package/dist/services/artifacts/artifact-templates.js +10 -0
  45. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  46. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  47. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  48. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  49. package/dist/services/artifacts/request-artifact-service.js +6 -6
  50. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  51. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  52. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  53. package/dist/services/audit/static-service.js +4 -4
  54. package/dist/services/code/auto-compact-history.d.ts +6 -1
  55. package/dist/services/code/auto-compact-history.js +6 -1
  56. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  57. package/dist/services/code/auto-compact-modes.js +75 -20
  58. package/dist/services/code/auto-compact-orchestrator.js +7 -5
  59. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  60. package/dist/services/code/auto-compact-profile.js +51 -0
  61. package/dist/services/code/auto-compact-run-types.d.ts +8 -4
  62. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  63. package/dist/services/compact-history/compact-history-service.js +5 -1
  64. package/dist/services/context/auto-compact-types.d.ts +7 -5
  65. package/dist/services/dispatch/dispatch-ledger-reader.d.ts +13 -0
  66. package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
  67. package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
  68. package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
  69. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  70. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  71. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  72. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  73. package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
  74. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  75. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  76. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  77. package/dist/services/hooks/pre-tool-code-gate.d.ts +4 -4
  78. package/dist/services/hooks/pre-tool-code-gate.js +4 -4
  79. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  80. package/dist/services/hooks/presence-marker-detector.js +21 -19
  81. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  82. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  83. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  84. package/dist/services/mode/mode-status-service.d.ts +26 -27
  85. package/dist/services/mode/mode-status-service.js +36 -60
  86. package/dist/services/preferences/preferences-types.d.ts +30 -0
  87. package/dist/services/preferences/preferences-types.js +13 -0
  88. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  89. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  90. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  91. package/dist/services/scan/rid-change-claims.js +116 -0
  92. package/dist/services/session/getSessionDir.d.ts +13 -0
  93. package/dist/services/session/getSessionDir.js +7 -1
  94. package/dist/services/skills/hooks-settings-types.d.ts +17 -21
  95. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  96. package/dist/services/skills/presence-caller-id.js +43 -0
  97. package/dist/services/skills/presence-gate.d.ts +65 -0
  98. package/dist/services/skills/presence-gate.js +113 -0
  99. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  100. package/dist/services/skills/presence-lease-resolver.js +114 -0
  101. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  102. package/dist/services/skills/presence-lease-selection.js +135 -0
  103. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  104. package/dist/services/skills/presence-lease-service.js +34 -87
  105. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  106. package/dist/services/skills/presence-lease-store.js +94 -0
  107. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  108. package/dist/services/skills/presence-lease-types.js +27 -0
  109. package/dist/services/skills/presence-role.d.ts +35 -0
  110. package/dist/services/skills/presence-role.js +72 -0
  111. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  112. package/dist/services/skills/skill-presence-service.js +143 -174
  113. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  114. package/dist/services/skills/skill-presence-write.js +74 -0
  115. package/dist/services/skills/skill-statusline-service.js +7 -7
  116. package/dist/services/skills/sync-service-support.d.ts +27 -0
  117. package/dist/services/skills/sync-service.js +1 -0
  118. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  119. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  120. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  121. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  122. package/dist/services/standards/migrate-service.d.ts +1 -1
  123. package/dist/services/standards/migrate-service.js +27 -7
  124. package/dist/services/standards/project-scripts.d.ts +25 -0
  125. package/dist/services/standards/project-scripts.js +116 -0
  126. package/dist/services/standards/project-standards-service.d.ts +23 -15
  127. package/dist/services/standards/project-standards-service.js +176 -243
  128. package/dist/services/standards/standards-constitution.d.ts +89 -0
  129. package/dist/services/standards/standards-constitution.js +199 -0
  130. package/dist/services/standards/standards-files.d.ts +37 -0
  131. package/dist/services/standards/standards-files.js +138 -0
  132. package/dist/services/standards/standards-pointer.d.ts +73 -0
  133. package/dist/services/standards/standards-pointer.js +98 -0
  134. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  135. package/dist/services/standards/standards-render-agents.js +149 -0
  136. package/dist/services/standards/standards-render-common.d.ts +38 -1
  137. package/dist/services/standards/standards-render-common.js +44 -7
  138. package/dist/services/standards/standards-render.d.ts +1 -3
  139. package/dist/services/standards/standards-render.js +6 -87
  140. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  141. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  142. package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
  143. package/dist/services/workflow/workflow-inflight-probe.js +163 -75
  144. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  145. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  146. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  147. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  148. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  149. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  150. package/dist/services/workspace/runtime-layout.js +62 -0
  151. package/output-styles/peaks-skill-swarm.md +18 -2
  152. package/package.json +10 -9
  153. package/schemas/doctor-report.schema.json +1 -1
  154. package/scripts/canonical-store-fs.mjs +112 -0
  155. package/scripts/canonical-store-link.mjs +13 -22
  156. package/scripts/canonical-store-marker.mjs +241 -0
  157. package/scripts/canonical-store.mjs +119 -141
  158. package/scripts/install-skills-bundles.mjs +56 -13
  159. package/scripts/install-skills-fs.mjs +73 -0
  160. package/scripts/install-skills-output-styles.mjs +8 -2
  161. package/scripts/install-skills-report.mjs +19 -0
  162. package/scripts/install-skills.mjs +9 -0
  163. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  164. package/skills/bee/peaks-prd/SKILL.md +5 -3
  165. package/skills/bee/peaks-qa/SKILL.md +4 -2
  166. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  167. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  168. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  169. package/skills/bee/peaks-rd/SKILL.md +4 -2
  170. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  171. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  172. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  173. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +24 -5
  174. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  175. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  176. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  177. package/skills/bee/peaks-sc/SKILL.md +4 -2
  178. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  179. package/skills/bee/peaks-txt/SKILL.md +5 -3
  180. package/skills/bee/peaks-ui/SKILL.md +6 -4
  181. package/skills/peaks-audit/SKILL.md +3 -1
  182. package/skills/peaks-code/SKILL.md +4 -2
  183. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  184. package/skills/peaks-code/references/completion-handoff.md +1 -1
  185. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  186. package/skills/peaks-code/references/micro-cycle.md +2 -2
  187. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  188. package/skills/peaks-code/references/runbook.md +4 -4
  189. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  190. package/skills/peaks-code/references/standards-preflight.md +7 -6
  191. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  192. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  193. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  194. package/skills/peaks-content/SKILL.md +3 -1
  195. package/skills/peaks-doctor/SKILL.md +3 -1
  196. package/skills/peaks-final-review/SKILL.md +3 -1
  197. package/skills/peaks-ide/SKILL.md +3 -1
  198. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  199. package/skills/peaks-race-code/SKILL.md +9 -4
  200. package/skills/peaks-resume/SKILL.md +3 -1
  201. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  202. package/skills/peaks-solo/SKILL.md +3 -1
  203. package/skills/peaks-sop/SKILL.md +4 -2
  204. package/skills/peaks-status/SKILL.md +3 -1
  205. package/skills/peaks-test/SKILL.md +3 -1
@@ -1,3 +1,40 @@
1
+ /**
2
+ * `peaks mut` — command builders and helper functions.
3
+ *
4
+ * Originally extracted from `mut-commands.ts` (file-size cap campaign).
5
+ * It holds the stub-report factories, the summary emitter, the named-error
6
+ * mapping, and — after the `max-lines-per-function` rule was measured at
7
+ * 209 code lines for `createMutCommands` — the three subcommand builders
8
+ * that drive the mutation pipeline (`run`, `mutants`, `asserts`).
9
+ * The `report` subcommand — a pure reader of an already-written file —
10
+ * lives with the CLI surface in `mut-commands.ts`.
11
+ *
12
+ * The named-error part exists for R7: a missing or unloadable mutation
13
+ * toolchain must surface a MACHINE-READABLE error code (for example
14
+ * `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
15
+ * non-zero exit code — never `UNHANDLED_ERROR` with a bare
16
+ * "Cannot find package".
17
+ */
18
+ import { Command } from 'commander';
19
+ import { buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
20
+ import { printErrorEnvelope } from '../cli-helpers.js';
21
+ /**
22
+ * Fallback code for a mutation failure that carries no named code of its
23
+ * own. The production invoker raises the specific codes; anything that
24
+ * escapes it without one still gets a stable, greppable name.
25
+ */
26
+ export const MUT_CLI_ERROR_CODE = 'MUT_FAILED';
27
+ /** Named mutation codes are always `MUT_` + upper snake case. */
28
+ const NAMED_CODE_PATTERN = /^MUT_[A-Z0-9_]+$/;
29
+ /**
30
+ * The IO the mut family writes to when the caller injects none. Same
31
+ * shape as `src/cli/program.ts`'s default sinks: one trailing newline
32
+ * per write.
33
+ */
34
+ export const DEFAULT_MUT_IO = {
35
+ stdout: (text) => process.stdout.write(`${text}\n`),
36
+ stderr: (text) => process.stderr.write(`${text}\n`)
37
+ };
1
38
  /**
2
39
  * Pure helper: a stub AssertionsReport used when only Stryker ran.
3
40
  * The mutants-only path does NOT touch the AST scanner; we still need
@@ -33,11 +70,167 @@ export function emptyMutation() {
33
70
  * both `--json` and the human-readable branches so the `passed` /
34
71
  * `sha256` shape stays consistent regardless of TTY mode.
35
72
  */
36
- export function emitSummary(json, payload) {
73
+ export function emitSummary(io, json, payload) {
37
74
  if (json) {
38
- process.stdout.write(JSON.stringify(payload) + '\n');
75
+ io.stdout(JSON.stringify(payload));
76
+ return;
39
77
  }
40
- else {
41
- process.stdout.write(`mut-report.json: ${payload.path}\nsha256: ${payload.sha256}\npassed: ${payload.passed}\n`);
78
+ io.stdout(`mut-report.json: ${payload.path}\nsha256: ${payload.sha256}\npassed: ${payload.passed}`);
79
+ }
80
+ /**
81
+ * Read the machine-readable code off a failure. The production invoker
82
+ * raises named codes (`MUT_TOOLCHAIN_UNAVAILABLE`, `MUT_NO_MUTANTS`,
83
+ * `MUT_MUTATE_PATTERN_REQUIRED`, …) and `runMutation` preserves them
84
+ * while wrapping. Anything without a recognised code falls back to
85
+ * `MUT_FAILED` so the envelope is never anonymous.
86
+ */
87
+ export function mutErrorCode(err) {
88
+ if (err && typeof err === 'object' && 'code' in err) {
89
+ const code = err.code;
90
+ if (typeof code === 'string' && NAMED_CODE_PATTERN.test(code)) {
91
+ return code;
92
+ }
42
93
  }
94
+ return MUT_CLI_ERROR_CODE;
95
+ }
96
+ /** The human-readable half of the envelope. */
97
+ export function mutErrorMessage(err) {
98
+ return err instanceof Error ? err.message : String(err);
99
+ }
100
+ /**
101
+ * Emit the failure envelope on stderr and set a non-zero exit code.
102
+ * stdout stays reserved for the `--json` payload (R6), so the envelope
103
+ * goes to stderr exactly like every other peaks CLI error.
104
+ */
105
+ export function emitMutError(io, err) {
106
+ printErrorEnvelope(io, 'mut', mutErrorCode(err), mutErrorMessage(err), {}, []);
107
+ }
108
+ /**
109
+ * `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
110
+ * report). One-axis: --session-id required.
111
+ */
112
+ export function buildMutRunCommand(invokeStryker, io) {
113
+ return new Command('run')
114
+ .description('Run the full mut pipeline (Stryker + assertion scan + report). One-axis: --session-id required.')
115
+ .requiredOption('--project <path>', 'project root')
116
+ .requiredOption('--test-files <files...>', 'test files to mutate against')
117
+ .option('--mutate <patterns...>', 'source patterns to mutate, relative to --project')
118
+ .requiredOption('--input-sig <hex>', 'TACT.sig (sha256) for chain')
119
+ .requiredOption('--session-id <sid>', 'session id; CLI writes artifacts only under .peaks/_runtime/<sid>/mut/ (one-axis layout)')
120
+ .requiredOption('--out <path>', 'output path for mut-report.json')
121
+ .option('--json', 'machine-readable output', false)
122
+ .action(async (a) => {
123
+ try {
124
+ const { mutation } = await runMutation({
125
+ project: a.project,
126
+ testFiles: a.testFiles,
127
+ mutate: a.mutate ?? [],
128
+ invokeStryker
129
+ });
130
+ const assertions = await scanAssertions({
131
+ project: a.project,
132
+ testFiles: a.testFiles
133
+ });
134
+ const report = await buildMutReport({
135
+ inputSig: a.inputSig,
136
+ out: a.out,
137
+ mutation,
138
+ assertions
139
+ });
140
+ emitSummary(io, a.json, {
141
+ ok: true,
142
+ sha256: report.sha256,
143
+ passed: report.thresholds.passed,
144
+ path: a.out
145
+ });
146
+ if (!report.thresholds.passed) {
147
+ // H6: CLI裁决 — threshold breach is a non-zero exit so callers
148
+ // (peaks-rd, peaks-qa, CI) can block on it without parsing stdout.
149
+ process.exitCode = 1;
150
+ }
151
+ }
152
+ catch (err) {
153
+ // R7: a named code + actionable message + non-zero exit, never an
154
+ // UNHANDLED_ERROR envelope with a bare "Cannot find package".
155
+ emitMutError(io, err);
156
+ }
157
+ });
158
+ }
159
+ /**
160
+ * `peaks mut mutants` — Stryker only; writes a stub-assertions
161
+ * mut-report.json. One-axis: --session-id required.
162
+ */
163
+ export function buildMutMutantsCommand(invokeStryker, io) {
164
+ return new Command('mutants')
165
+ .description('Run Stryker only; write a stub-assertions mut-report.json. One-axis: --session-id required.')
166
+ .requiredOption('--project <path>', 'project root')
167
+ .requiredOption('--test-files <files...>', 'test files to mutate against')
168
+ .option('--mutate <patterns...>', 'source patterns to mutate, relative to --project')
169
+ .requiredOption('--input-sig <hex>', 'TACT.sig')
170
+ .requiredOption('--session-id <sid>', 'session id')
171
+ .requiredOption('--out <path>', 'output path for mut-report.json')
172
+ .option('--json', 'machine-readable output', false)
173
+ .action(async (a) => {
174
+ try {
175
+ const { mutation } = await runMutation({
176
+ project: a.project,
177
+ testFiles: a.testFiles,
178
+ mutate: a.mutate ?? [],
179
+ invokeStryker
180
+ });
181
+ const report = await buildMutReport({
182
+ inputSig: a.inputSig,
183
+ out: a.out,
184
+ mutation,
185
+ assertions: emptyAssertions()
186
+ });
187
+ emitSummary(io, a.json, {
188
+ ok: true,
189
+ sha256: report.sha256,
190
+ passed: report.thresholds.passed,
191
+ path: a.out
192
+ });
193
+ if (!report.thresholds.passed) {
194
+ process.exitCode = 1;
195
+ }
196
+ }
197
+ catch (err) {
198
+ emitMutError(io, err);
199
+ }
200
+ });
201
+ }
202
+ /**
203
+ * `peaks mut asserts` — the assertion scan only; writes a mut-report.json
204
+ * with an empty mutation block. One-axis: --session-id required.
205
+ */
206
+ export function buildMutAssertsCommand(io) {
207
+ return new Command('asserts')
208
+ .description('Run the assertion scan only; write a mut-report.json with empty mutation block. One-axis: --session-id required.')
209
+ .requiredOption('--project <path>', 'project root')
210
+ .requiredOption('--test-files <files...>', 'test files to scan')
211
+ .requiredOption('--input-sig <hex>', 'TACT.sig')
212
+ .requiredOption('--session-id <sid>', 'session id')
213
+ .requiredOption('--out <path>', 'output path for mut-report.json')
214
+ .option('--json', 'machine-readable output', false)
215
+ .action(async (a) => {
216
+ const assertions = await scanAssertions({
217
+ project: a.project,
218
+ testFiles: a.testFiles
219
+ });
220
+ const report = await buildMutReport({
221
+ inputSig: a.inputSig,
222
+ out: a.out,
223
+ mutation: emptyMutation(),
224
+ assertions
225
+ });
226
+ emitSummary(io, a.json, {
227
+ ok: true,
228
+ sha256: report.sha256,
229
+ passed: report.thresholds.passed,
230
+ path: a.out
231
+ });
232
+ if (!report.thresholds.passed) {
233
+ process.exitCode = 1;
234
+ }
235
+ });
43
236
  }
@@ -3,6 +3,8 @@ import { type StrykerInvoker } from 'peaks-loop-mut';
3
3
  import type { ProgramIO } from '../cli-helpers.js';
4
4
  export interface MutCommandsOptions {
5
5
  readonly invokeStryker: StrykerInvoker;
6
+ /** Where the command writes. Defaults to stdout/stderr. */
7
+ readonly io?: ProgramIO;
6
8
  }
7
9
  /**
8
10
  * Construct the `peaks mut` family as a standalone Commander command.
@@ -17,4 +19,10 @@ export declare function createMutCommands(opts: MutCommandsOptions): Command;
17
19
  * `createMutCommands({ invokeStryker })` instead so the heavy
18
20
  * @stryker-mutator/core runtime stays out of the unit-test path.
19
21
  */
20
- export declare function registerMutCommands(program: Command, _io: ProgramIO): void;
22
+ export declare function registerMutCommands(program: Command, io: ProgramIO): void;
23
+ /**
24
+ * `peaks mut report` — re-read a previously-written mut-report.json (no
25
+ * Stryker / scan invocation). One-axis: --session-id required for the
26
+ * audit trail.
27
+ */
28
+ export declare function buildMutReportCommand(io: ProgramIO): Command;
@@ -12,11 +12,17 @@
12
12
  * that chains back to TACT.sig via the `inputSig` field.
13
13
  * - KISS: keep the public surface narrow — run / mutants / asserts /
14
14
  * report. The CLI is a thin orchestrator over the service layer.
15
+ *
16
+ * The three subcommands that drive the mutation pipeline (`run`, `mutants`,
17
+ * `asserts`) live in `mut-commands-helpers.ts`; this file assembles them
18
+ * and owns `report` — a pure reader of an already-written file. The split
19
+ * keeps `createMutCommands` inside the `max-lines-per-function` budget
20
+ * (50 code lines); it measured 209 before the split.
15
21
  */
16
22
  import { readFile } from 'node:fs/promises';
17
23
  import { Command } from 'commander';
18
- import { scanAssertions, runMutation, buildMutReport, createProductionStrykerInvoker, MutReportSchema } from 'peaks-loop-mut';
19
- import { emitSummary, emptyAssertions, emptyMutation } from './mut-commands-helpers.js';
24
+ import { createProductionStrykerInvoker, MutReportSchema } from 'peaks-loop-mut';
25
+ import { buildMutAssertsCommand, buildMutMutantsCommand, buildMutRunCommand, DEFAULT_MUT_IO } from './mut-commands-helpers.js';
20
26
  /**
21
27
  * Construct the `peaks mut` family as a standalone Commander command.
22
28
  * Returns the parent `mut` Command so callers can attach it under any
@@ -24,170 +30,92 @@ import { emitSummary, emptyAssertions, emptyMutation } from './mut-commands-help
24
30
  * directly by the unit tests).
25
31
  */
26
32
  export function createMutCommands(opts) {
33
+ const io = opts.io ?? DEFAULT_MUT_IO;
27
34
  const mut = new Command('mut').description('peaks-mut: mutation testing + assertion validity scan (spec §4.2 / §7)');
28
- mut
29
- .command('run')
30
- .description('Run the full mut pipeline (Stryker + assertion scan + report). One-axis: --session-id required.')
31
- .requiredOption('--project <path>', 'project root')
32
- .requiredOption('--test-files <files...>', 'test files to mutate against')
33
- .requiredOption('--input-sig <hex>', 'TACT.sig (sha256) for chain')
34
- .requiredOption('--session-id <sid>', 'session id; CLI writes artifacts only under .peaks/_runtime/<sid>/mut/ (one-axis layout)')
35
- .requiredOption('--out <path>', 'output path for mut-report.json')
36
- .option('--json', 'machine-readable output', false)
37
- .action(async (a) => {
38
- const { mutation } = await runMutation({
39
- project: a.project,
40
- testFiles: a.testFiles,
41
- invokeStryker: opts.invokeStryker
42
- });
43
- const assertions = await scanAssertions({
44
- project: a.project,
45
- testFiles: a.testFiles
46
- });
47
- const report = await buildMutReport({
48
- inputSig: a.inputSig,
49
- out: a.out,
50
- mutation,
51
- assertions
52
- });
53
- emitSummary(a.json, {
54
- ok: true,
55
- sha256: report.sha256,
56
- passed: report.thresholds.passed,
57
- path: a.out
58
- });
59
- if (!report.thresholds.passed) {
60
- // H6: CLI裁决 — threshold breach is a non-zero exit so callers
61
- // (peaks-rd, peaks-qa, CI) can block on it without parsing
62
- // stdout.
63
- process.exitCode = 1;
64
- }
65
- });
66
- mut
67
- .command('mutants')
68
- .description('Run Stryker only; write a stub-assertions mut-report.json. One-axis: --session-id required.')
69
- .requiredOption('--project <path>', 'project root')
70
- .requiredOption('--test-files <files...>', 'test files to mutate against')
71
- .requiredOption('--input-sig <hex>', 'TACT.sig')
72
- .requiredOption('--session-id <sid>', 'session id')
73
- .requiredOption('--out <path>', 'output path for mut-report.json')
74
- .option('--json', 'machine-readable output', false)
75
- .action(async (a) => {
76
- const { mutation } = await runMutation({
77
- project: a.project,
78
- testFiles: a.testFiles,
79
- invokeStryker: opts.invokeStryker
80
- });
81
- const report = await buildMutReport({
82
- inputSig: a.inputSig,
83
- out: a.out,
84
- mutation,
85
- assertions: emptyAssertions()
86
- });
87
- emitSummary(a.json, {
88
- ok: true,
89
- sha256: report.sha256,
90
- passed: report.thresholds.passed,
91
- path: a.out
92
- });
93
- if (!report.thresholds.passed) {
94
- process.exitCode = 1;
95
- }
96
- });
97
- mut
98
- .command('asserts')
99
- .description('Run the assertion scan only; write a mut-report.json with empty mutation block. One-axis: --session-id required.')
100
- .requiredOption('--project <path>', 'project root')
101
- .requiredOption('--test-files <files...>', 'test files to scan')
102
- .requiredOption('--input-sig <hex>', 'TACT.sig')
103
- .requiredOption('--session-id <sid>', 'session id')
104
- .requiredOption('--out <path>', 'output path for mut-report.json')
105
- .option('--json', 'machine-readable output', false)
106
- .action(async (a) => {
107
- const assertions = await scanAssertions({
108
- project: a.project,
109
- testFiles: a.testFiles
110
- });
111
- const report = await buildMutReport({
112
- inputSig: a.inputSig,
113
- out: a.out,
114
- mutation: emptyMutation(),
115
- assertions
116
- });
117
- emitSummary(a.json, {
118
- ok: true,
119
- sha256: report.sha256,
120
- passed: report.thresholds.passed,
121
- path: a.out
122
- });
123
- if (!report.thresholds.passed) {
124
- process.exitCode = 1;
125
- }
126
- });
127
- mut
128
- .command('report')
35
+ mut.addCommand(buildMutRunCommand(opts.invokeStryker, io));
36
+ mut.addCommand(buildMutMutantsCommand(opts.invokeStryker, io));
37
+ mut.addCommand(buildMutAssertsCommand(io));
38
+ mut.addCommand(buildMutReportCommand(io));
39
+ return mut;
40
+ }
41
+ /**
42
+ * Program-level wiring: attach the `peaks mut` family to the root
43
+ * program with the production Stryker invoker. Tests should use
44
+ * `createMutCommands({ invokeStryker })` instead so the heavy
45
+ * @stryker-mutator/core runtime stays out of the unit-test path.
46
+ */
47
+ export function registerMutCommands(program, io) {
48
+ const invokeStryker = createProductionStrykerInvoker();
49
+ program.addCommand(createMutCommands({ invokeStryker, io }));
50
+ }
51
+ /**
52
+ * `peaks mut report` — re-read a previously-written mut-report.json (no
53
+ * Stryker / scan invocation). One-axis: --session-id required for the
54
+ * audit trail.
55
+ */
56
+ export function buildMutReportCommand(io) {
57
+ return new Command('report')
129
58
  .description('Re-read a previously-written mut-report.json (no Stryker / scan invocation). One-axis: --session-id required for the audit trail.')
130
59
  .requiredOption('--in <path>', 'input mut-report.json path')
131
60
  .requiredOption('--session-id <sid>', 'session id')
132
61
  .option('--json', 'machine-readable output', false)
133
62
  .action(async (a) => {
134
- const raw = await readFile(a.in, 'utf8');
135
- let parsedJson;
136
- try {
137
- parsedJson = JSON.parse(raw);
138
- }
139
- catch (err) {
140
- process.stderr.write(`INVALID_JSON: ${err instanceof Error ? err.message : String(err)}\n`);
141
- process.exitCode = 2;
63
+ const read = await readMutReportForDisplay(a.in);
64
+ if (!read.ok) {
65
+ io.stderr(read.message);
66
+ process.exitCode = read.exitCode;
142
67
  return;
143
68
  }
144
- const parsed = MutReportSchema.safeParse(parsedJson);
145
- if (!parsed.success) {
146
- process.stderr.write(`INVALID: ${parsed.error.message}\n`);
147
- process.exitCode = 2;
148
- return;
149
- }
150
- const r = parsed.data;
151
- const summary = {
152
- mutation: {
153
- tool: r.mutation.tool,
154
- killRate: r.mutation.killRate
155
- },
156
- assertions: {
157
- total: r.assertions.totalAssertions,
158
- weak: r.assertions.weakAssertions,
159
- weakRate: r.assertions.weakRate
160
- },
161
- thresholds: { passed: r.thresholds.passed },
162
- followups: r.followups.length,
163
- sha256: r.sha256,
164
- sessionId: a.sessionId
165
- };
166
- if (a.json) {
167
- process.stdout.write(JSON.stringify(summary) + '\n');
168
- }
169
- else {
170
- process.stdout.write([
171
- `mutation: tool=${r.mutation.tool} killRate=${(r.mutation.killRate * 100).toFixed(1)}%`,
172
- `assertions: total=${r.assertions.totalAssertions} weak=${r.assertions.weakAssertions} rate=${(r.assertions.weakRate * 100).toFixed(1)}%`,
173
- `thresholds: passed=${r.thresholds.passed}`,
174
- `followups: ${r.followups.length}`,
175
- `sha256: ${r.sha256}`
176
- ].join('\n') + '\n');
177
- }
178
- if (!r.thresholds.passed) {
69
+ renderMutReportSummary(io, read.report, a.sessionId, a.json);
70
+ if (!read.report.thresholds.passed) {
179
71
  process.exitCode = 1;
180
72
  }
181
73
  });
182
- return mut;
183
74
  }
184
75
  /**
185
- * Program-level wiring: attach the `peaks mut` family to the root
186
- * program with the production Stryker invoker. Tests should use
187
- * `createMutCommands({ invokeStryker })` instead so the heavy
188
- * @stryker-mutator/core runtime stays out of the unit-test path.
76
+ * Read + validate a mut-report.json. A malformed file is a display
77
+ * failure (exit code 2), not a crash — the original `report` subcommand
78
+ * behaved that way and the behavior is preserved.
189
79
  */
190
- export function registerMutCommands(program, _io) {
191
- const invokeStryker = createProductionStrykerInvoker();
192
- program.addCommand(createMutCommands({ invokeStryker }));
80
+ async function readMutReportForDisplay(inPath) {
81
+ const raw = await readFile(inPath, 'utf8');
82
+ let parsedJson;
83
+ try {
84
+ parsedJson = JSON.parse(raw);
85
+ }
86
+ catch (err) {
87
+ const detail = err instanceof Error ? err.message : String(err);
88
+ return { ok: false, exitCode: 2, message: `INVALID_JSON: ${detail}` };
89
+ }
90
+ const parsed = MutReportSchema.safeParse(parsedJson);
91
+ if (!parsed.success) {
92
+ return { ok: false, exitCode: 2, message: `INVALID: ${parsed.error.message}` };
93
+ }
94
+ return { ok: true, report: parsed.data };
95
+ }
96
+ /** Render the report summary as one JSON line or a human-readable block. */
97
+ function renderMutReportSummary(io, report, sessionId, json) {
98
+ const summary = {
99
+ mutation: { tool: report.mutation.tool, killRate: report.mutation.killRate },
100
+ assertions: {
101
+ total: report.assertions.totalAssertions,
102
+ weak: report.assertions.weakAssertions,
103
+ weakRate: report.assertions.weakRate
104
+ },
105
+ thresholds: { passed: report.thresholds.passed },
106
+ followups: report.followups.length,
107
+ sha256: report.sha256,
108
+ sessionId
109
+ };
110
+ if (json) {
111
+ io.stdout(JSON.stringify(summary));
112
+ return;
113
+ }
114
+ io.stdout([
115
+ `mutation: tool=${report.mutation.tool} killRate=${(report.mutation.killRate * 100).toFixed(1)}%`,
116
+ `assertions: total=${report.assertions.totalAssertions} weak=${report.assertions.weakAssertions} rate=${(report.assertions.weakRate * 100).toFixed(1)}%`,
117
+ `thresholds: passed=${report.thresholds.passed}`,
118
+ `followups: ${report.followups.length}`,
119
+ `sha256: ${report.sha256}`
120
+ ].join('\n'));
193
121
  }
@@ -1,6 +1,8 @@
1
1
  import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
2
2
  import { dirname } from 'node:path';
3
3
  import { loadPreferences, migratePreferences, preferencesPath, savePreferences } from '../../services/preferences/preferences-service.js';
4
+ import { AUTO_COMPACT_PROFILE_VALUES, isAutoCompactProfile } from '../../services/preferences/preferences-types.js';
5
+ import { normalizeAutoCompactMode } from '../../services/code/auto-compact-modes.js';
4
6
  const ALLOWED_KEYS = new Set([
5
7
  'economyMode',
6
8
  'swarmMode',
@@ -9,7 +11,8 @@ const ALLOWED_KEYS = new Set([
9
11
  'classifyConservatism',
10
12
  'classifyRules',
11
13
  'swarmSpeculative',
12
- 'loopAutonomousEnabled'
14
+ 'loopAutonomousEnabled',
15
+ 'autoCompactProfile'
13
16
  ]);
14
17
  /**
15
18
  * Stable, sorted list of allowed preference keys. Used in error messages
@@ -31,6 +34,28 @@ const ALLOWED_KEYS_LIST = Array.from(ALLOWED_KEYS).sort();
31
34
  function unknownKeyError(key) {
32
35
  return new Error(`PREFERENCES_KEY_UNKNOWN: ${key}. Allowed keys: ${ALLOWED_KEYS_LIST.join(', ')}.`);
33
36
  }
37
+ /**
38
+ * The value guard for `autoCompactProfile`.
39
+ *
40
+ * An illegal value is REJECTED with the legal ones named — it is never
41
+ * silently coerced to the default, because a silently-coerced profile is a
42
+ * cadence the operator did not ask for and cannot see.
43
+ *
44
+ * The legacy alias `partial` is accepted here too and stored in its
45
+ * canonical form (`eager`), so the file on disk only ever carries a
46
+ * canonical profile.
47
+ */
48
+ function normalizeAutoCompactProfileValue(key, value) {
49
+ if (key !== 'autoCompactProfile')
50
+ return value;
51
+ if (isAutoCompactProfile(value))
52
+ return value;
53
+ const alias = typeof value === 'string' ? normalizeAutoCompactMode(value) : null;
54
+ if (alias === null) {
55
+ throw new Error(`PREFERENCES_VALUE_INVALID: autoCompactProfile must be one of ${AUTO_COMPACT_PROFILE_VALUES.join(' | ')} (got ${JSON.stringify(value)}).`);
56
+ }
57
+ return alias;
58
+ }
34
59
  export function registerPreferencesCommands(program) {
35
60
  const prefs = program
36
61
  .command('preferences')
@@ -101,7 +126,7 @@ export function registerPreferencesCommands(program) {
101
126
  // Not valid JSON — keep the raw string.
102
127
  }
103
128
  const merged = savePreferences(opts.project, {
104
- [opts.key]: parsed
129
+ [opts.key]: normalizeAutoCompactProfileValue(opts.key, parsed)
105
130
  });
106
131
  const envelope = {
107
132
  ok: true,
@@ -23,11 +23,11 @@ export function acceptanceCoverageNextActions(result) {
23
23
  export function printAcceptanceCoverageLookupFailure(io, options, result) {
24
24
  const code = result.kind === 'prd-not-found' ? 'PRD_NOT_FOUND' : 'TEST_CASES_NOT_FOUND';
25
25
  const message = result.kind === 'prd-not-found'
26
- ? `PRD artifact for requestId=${options.rid} not found`
26
+ ? result.message
27
27
  : `QA test-cases file not found at ${result.expectedPath}`;
28
28
  printResult(io, fail('scan.acceptance-coverage', code, message, { requestId: options.rid }, [
29
29
  result.kind === 'prd-not-found'
30
- ? 'Run `peaks request init --role prd --id <rid> --apply --type <type>` first.'
30
+ ? 'Produce the PRD for this slice: `peaks request init --role prd --id <rid> --apply --type <type>` writes prd/requests/<rid>.md, and a handoff capsule at prd/handoff-<rid>.md is read as the fallback.'
31
31
  : 'Generate qa/test-cases/<rid>.md before running this check.'
32
32
  ]), options.json);
33
33
  process.exitCode = 1;
@@ -44,9 +44,17 @@ export declare function applyAutoEngagePresenceMode(input: {
44
44
  * Slice H3 (rid=h3-24h-threshold-not-wired): `no-in-flight-lease` is
45
45
  * the common case in practice — entering `24H_ACTIVE` before any skill
46
46
  * workflow has a lease — and it used to be reported only inside
47
- * `data.presenceMode`, where nothing read it. The user then believed
48
- * the 24h thresholds were in force while the profile still resolved to
49
- * `standard`.
47
+ * `data.presenceMode`, where nothing read it.
48
+ *
49
+ * WHAT THIS ADVISORY SAYS ABOUT THE COMPACTION PROFILE: nothing that
50
+ * contradicts the product. The auto-compact profile is a PUBLIC choice
51
+ * (`autoCompactProfile` in `.peaks/preferences.json`, or an explicit
52
+ * `--mode`), and the 24h state machine does not derive it — so the
53
+ * advisory reports the PRESENCE MODE, and says that the profile is the
54
+ * project's own setting. The claim it must not make is that the
55
+ * thresholds "are still derived from the 24h state machine": that turned
56
+ * false the moment the profile became a public, explicitly settable
57
+ * choice, and the wording below states the truth instead.
50
58
  *
51
59
  * `nextActions` address the LLM driver (it runs the CLI on the user's
52
60
  * behalf); they never ask the user to type a verb.
@@ -51,9 +51,17 @@ export function applyAutoEngagePresenceMode(input) {
51
51
  * Slice H3 (rid=h3-24h-threshold-not-wired): `no-in-flight-lease` is
52
52
  * the common case in practice — entering `24H_ACTIVE` before any skill
53
53
  * workflow has a lease — and it used to be reported only inside
54
- * `data.presenceMode`, where nothing read it. The user then believed
55
- * the 24h thresholds were in force while the profile still resolved to
56
- * `standard`.
54
+ * `data.presenceMode`, where nothing read it.
55
+ *
56
+ * WHAT THIS ADVISORY SAYS ABOUT THE COMPACTION PROFILE: nothing that
57
+ * contradicts the product. The auto-compact profile is a PUBLIC choice
58
+ * (`autoCompactProfile` in `.peaks/preferences.json`, or an explicit
59
+ * `--mode`), and the 24h state machine does not derive it — so the
60
+ * advisory reports the PRESENCE MODE, and says that the profile is the
61
+ * project's own setting. The claim it must not make is that the
62
+ * thresholds "are still derived from the 24h state machine": that turned
63
+ * false the moment the profile became a public, explicitly settable
64
+ * choice, and the wording below states the truth instead.
57
65
  *
58
66
  * `nextActions` address the LLM driver (it runs the CLI on the user's
59
67
  * behalf); they never ask the user to type a verb.
@@ -64,16 +72,16 @@ export function presenceModeAdvisory(result) {
64
72
  if (result.reason === 'no-in-flight-lease') {
65
73
  return {
66
74
  warnings: [
67
- 'The `24h` presence mode was NOT recorded: no in-flight presence lease to stamp (`no-in-flight-lease`). Auto-compact thresholds are still derived from the 24h state machine, so the 24h (partial) lines apply; the mode gate and statusline will NOT see `24h`.'
75
+ 'The `24h` presence mode was NOT recorded: no in-flight presence lease to stamp (`no-in-flight-lease`). The auto-compact profile is NOT derived from the 24h state machine — it is the project setting `autoCompactProfile`; the mode gate and statusline will NOT see `24h`.'
68
76
  ],
69
77
  nextActions: [
70
- 'Do NOT report that the 24h thresholds are inactive — they are active via the 24h state machine. If the mode gate / statusline also need to see `24h`, start the skill workflow first and then re-run `peaks session 24h-mode transition --state 24H_ACTIVE` yourself. Do not ask the user to run it.'
78
+ 'Do NOT report that the compaction profile changed — the 24h mode does not decide it, and the project setting `autoCompactProfile` still governs it. If the mode gate / statusline also need to see `24h`, start the skill workflow first and then re-run `peaks session 24h-mode transition --state 24H_ACTIVE` yourself. Do not ask the user to run it.'
71
79
  ]
72
80
  };
73
81
  }
74
82
  return {
75
83
  warnings: [
76
- `The \`24h\` presence mode was NOT recorded (\`${result.reason}\`). Auto-compact thresholds are still derived from the 24h state machine, so the 24h (partial) lines apply; the mode gate and statusline will NOT see \`24h\`.`
84
+ `The \`24h\` presence mode was NOT recorded (\`${result.reason}\`). The auto-compact profile is NOT derived from the 24h state machine — it is the project setting \`autoCompactProfile\`; the mode gate and statusline will NOT see \`24h\`.`
77
85
  ],
78
86
  nextActions: []
79
87
  };
@@ -92,6 +92,16 @@ function renderRdTemplate(requestId, _sessionId, sessionId, timestamp, requestTy
92
92
  ${renderTypeLine(requestType)}
93
93
  ` +
94
94
  RD_TEMPLATE_BODY +
95
+ // The rid's OWN changed paths, one per line, machine-readable. The
96
+ // declared-type rule judges THIS set instead of the whole working tree
97
+ // (which blamed a docs rid for another slice's src change), and the
98
+ // `<path>` placeholder is what the body lint refuses while it is unfilled —
99
+ // so an RD that never declared its paths cannot leave `draft`.
100
+ `## Changed paths
101
+
102
+ changedPath: <path>
103
+
104
+ ` +
95
105
  `## Handoff
96
106
 
97
107
  - to peaks-qa: ${formatHandoffPath(sessionId, 'qa', requestId)}