peaks-loop 4.1.18 → 4.1.20

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 (169) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +256 -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 +26 -18
  14. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  15. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  16. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  17. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  18. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  19. package/dist/cli/commands/core/standards-init-command.js +44 -8
  20. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  21. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  22. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  23. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  24. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  25. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  26. package/dist/cli/commands/mut-commands.d.ts +9 -1
  27. package/dist/cli/commands/mut-commands.js +82 -154
  28. package/dist/cli/commands/preferences-commands.js +27 -2
  29. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  30. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  31. package/dist/services/24h-mode/auto-engage.js +14 -6
  32. package/dist/services/artifacts/artifact-templates.js +10 -0
  33. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  34. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  35. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  36. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  37. package/dist/services/artifacts/request-artifact-service.js +6 -6
  38. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  39. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  40. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  41. package/dist/services/audit/static-service.js +4 -4
  42. package/dist/services/code/auto-compact-history.d.ts +6 -1
  43. package/dist/services/code/auto-compact-history.js +6 -1
  44. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  45. package/dist/services/code/auto-compact-modes.js +75 -20
  46. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  47. package/dist/services/code/auto-compact-profile.js +51 -0
  48. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  49. package/dist/services/compact-history/compact-history-service.js +5 -1
  50. package/dist/services/context/auto-compact-types.d.ts +7 -5
  51. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  52. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  53. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  54. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  55. package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
  56. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  57. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  58. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  59. package/dist/services/hooks/presence-marker-detector.js +21 -19
  60. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  61. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  62. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  63. package/dist/services/mode/mode-status-service.d.ts +26 -27
  64. package/dist/services/mode/mode-status-service.js +36 -60
  65. package/dist/services/preferences/preferences-types.d.ts +30 -0
  66. package/dist/services/preferences/preferences-types.js +13 -0
  67. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  68. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  69. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  70. package/dist/services/scan/rid-change-claims.js +116 -0
  71. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  72. package/dist/services/skills/presence-caller-id.js +43 -0
  73. package/dist/services/skills/presence-gate.d.ts +65 -0
  74. package/dist/services/skills/presence-gate.js +113 -0
  75. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  76. package/dist/services/skills/presence-lease-resolver.js +114 -0
  77. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  78. package/dist/services/skills/presence-lease-selection.js +135 -0
  79. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  80. package/dist/services/skills/presence-lease-service.js +34 -87
  81. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  82. package/dist/services/skills/presence-lease-store.js +94 -0
  83. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  84. package/dist/services/skills/presence-lease-types.js +27 -0
  85. package/dist/services/skills/presence-role.d.ts +35 -0
  86. package/dist/services/skills/presence-role.js +72 -0
  87. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  88. package/dist/services/skills/skill-presence-service.js +143 -174
  89. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  90. package/dist/services/skills/skill-presence-write.js +74 -0
  91. package/dist/services/skills/skill-statusline-service.js +7 -7
  92. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  93. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  94. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  95. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  96. package/dist/services/standards/migrate-service.d.ts +1 -1
  97. package/dist/services/standards/migrate-service.js +27 -7
  98. package/dist/services/standards/project-scripts.d.ts +25 -0
  99. package/dist/services/standards/project-scripts.js +116 -0
  100. package/dist/services/standards/project-standards-service.d.ts +23 -15
  101. package/dist/services/standards/project-standards-service.js +176 -243
  102. package/dist/services/standards/standards-constitution.d.ts +89 -0
  103. package/dist/services/standards/standards-constitution.js +199 -0
  104. package/dist/services/standards/standards-files.d.ts +37 -0
  105. package/dist/services/standards/standards-files.js +138 -0
  106. package/dist/services/standards/standards-pointer.d.ts +73 -0
  107. package/dist/services/standards/standards-pointer.js +98 -0
  108. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  109. package/dist/services/standards/standards-render-agents.js +149 -0
  110. package/dist/services/standards/standards-render-common.d.ts +38 -1
  111. package/dist/services/standards/standards-render-common.js +44 -7
  112. package/dist/services/standards/standards-render.d.ts +1 -3
  113. package/dist/services/standards/standards-render.js +6 -87
  114. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  115. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  116. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  117. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  118. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  119. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  120. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  121. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  122. package/dist/services/workspace/runtime-layout.js +62 -0
  123. package/output-styles/peaks-skill-swarm.md +18 -2
  124. package/package.json +9 -9
  125. package/schemas/doctor-report.schema.json +1 -1
  126. package/scripts/canonical-store-report.mjs +84 -0
  127. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  128. package/skills/bee/peaks-prd/SKILL.md +5 -3
  129. package/skills/bee/peaks-qa/SKILL.md +4 -2
  130. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  131. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  132. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  133. package/skills/bee/peaks-rd/SKILL.md +4 -2
  134. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  135. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  136. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  137. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +4 -4
  138. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  139. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  140. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  141. package/skills/bee/peaks-sc/SKILL.md +4 -2
  142. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  143. package/skills/bee/peaks-txt/SKILL.md +5 -3
  144. package/skills/bee/peaks-ui/SKILL.md +6 -4
  145. package/skills/peaks-audit/SKILL.md +3 -1
  146. package/skills/peaks-code/SKILL.md +3 -1
  147. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  148. package/skills/peaks-code/references/completion-handoff.md +1 -1
  149. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  150. package/skills/peaks-code/references/micro-cycle.md +2 -2
  151. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  152. package/skills/peaks-code/references/runbook.md +4 -4
  153. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  154. package/skills/peaks-code/references/standards-preflight.md +7 -6
  155. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  156. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  157. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  158. package/skills/peaks-content/SKILL.md +3 -1
  159. package/skills/peaks-doctor/SKILL.md +3 -1
  160. package/skills/peaks-final-review/SKILL.md +3 -1
  161. package/skills/peaks-ide/SKILL.md +3 -1
  162. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  163. package/skills/peaks-race-code/SKILL.md +3 -1
  164. package/skills/peaks-resume/SKILL.md +3 -1
  165. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  166. package/skills/peaks-solo/SKILL.md +3 -1
  167. package/skills/peaks-sop/SKILL.md +4 -2
  168. package/skills/peaks-status/SKILL.md +3 -1
  169. package/skills/peaks-test/SKILL.md +3 -1
@@ -1,22 +1,44 @@
1
1
  import { summarizeProjectStandardsInitResult, summarizeProjectStandardsUpdateResult } from '../../../services/standards/project-standards-service.js';
2
2
  import { executeProjectStandardsInitIdeAware, executeProjectStandardsUpdateIdeAware } from '../../../services/standards/ide-aware-standards-service.js';
3
+ import { listAdapterIds } from '../../../services/ide/ide-registry.js';
3
4
  import { fail, ok } from 'peaks-loop-shared/result';
4
5
  import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
6
+ /**
7
+ * The registered IDE ids `--ide` accepts.
8
+ *
9
+ * Read from the registry rather than re-typed here: a hand-written list of
10
+ * ids is a second copy of the registry, and the copy that shipped with this
11
+ * command was missing `hermes`, `openclaw` and `zcode` — so `--ide zcode`
12
+ * used to reach `getAdapter()` and throw instead of being accepted.
13
+ */
14
+ const SUPPORTED_IDE_IDS = listAdapterIds();
5
15
  /** The five flags `init` and `update` share, in registration order. */
6
16
  function withWriteFlags(cmd, applyHelp) {
7
17
  return cmd
8
18
  .requiredOption('--project <path>', 'target project root')
9
19
  .option('--language <language>', 'standards language pack')
10
- .option('--ide <id>', 'override IDE detection (e.g. claude-code, trae)')
20
+ .option('--ide <id>', `override IDE detection; the IDE's standards profile decides which instruction files are written (${SUPPORTED_IDE_IDS.join(' | ')})`)
11
21
  .option('--dry-run', 'preview writes without changing files')
12
22
  .option('--apply', applyHelp);
13
23
  }
24
+ /**
25
+ * The `--ide` value, validated against the registry.
26
+ *
27
+ * `null` means "not a registered IDE" — the caller refuses with a
28
+ * structured envelope instead of letting the value reach `getAdapter()`,
29
+ * where an unknown id throws an unhandled error.
30
+ */
31
+ function resolveIdeId(value) {
32
+ if (value === undefined)
33
+ return null;
34
+ return SUPPORTED_IDE_IDS.find((id) => id === value) ?? null;
35
+ }
14
36
  /** The ide-aware request both verbs build from the same flag set. */
15
- function buildIdeAwareRequest(options) {
37
+ function buildIdeAwareRequest(options, ideId) {
16
38
  return {
17
39
  projectRoot: options.project,
18
40
  ...(options.language !== undefined ? { language: options.language } : {}),
19
- ...(options.ide !== undefined ? { ideId: options.ide } : {}),
41
+ ...(ideId !== null ? { ideId } : {}),
20
42
  apply: options.apply === true
21
43
  };
22
44
  }
@@ -28,6 +50,14 @@ function refuseConflictingFlags(io, options, refusal) {
28
50
  process.exitCode = 1;
29
51
  return true;
30
52
  }
53
+ /** Refuse an `--ide` value no adapter is registered under. */
54
+ function refuseUnknownIde(io, options, command, ideId) {
55
+ if (options.ide === undefined || ideId !== null)
56
+ return false;
57
+ printResult(io, fail(command, 'UNKNOWN_IDE', `Unknown IDE '${options.ide}'.`, { ide: options.ide, supportedIdeIds: SUPPORTED_IDE_IDS }, [`Pass one of: ${SUPPORTED_IDE_IDS.join(', ')}.`]), options.json);
58
+ process.exitCode = 1;
59
+ return true;
60
+ }
31
61
  function runStandardsInit(io, options) {
32
62
  const refused = refuseConflictingFlags(io, options, {
33
63
  command: 'standards.init',
@@ -38,8 +68,11 @@ function runStandardsInit(io, options) {
38
68
  });
39
69
  if (refused)
40
70
  return;
71
+ const ideId = resolveIdeId(options.ide);
72
+ if (refuseUnknownIde(io, options, 'standards.init', ideId))
73
+ return;
41
74
  try {
42
- const result = executeProjectStandardsInitIdeAware(buildIdeAwareRequest(options));
75
+ const result = executeProjectStandardsInitIdeAware(buildIdeAwareRequest(options, ideId));
43
76
  printResult(io, ok('standards.init', summarizeProjectStandardsInitResult(result)), options.json);
44
77
  }
45
78
  catch (error) {
@@ -59,8 +92,11 @@ function runStandardsUpdate(io, options) {
59
92
  });
60
93
  if (refused)
61
94
  return;
95
+ const ideId = resolveIdeId(options.ide);
96
+ if (refuseUnknownIde(io, options, 'standards.update', ideId))
97
+ return;
62
98
  try {
63
- const result = executeProjectStandardsUpdateIdeAware(buildIdeAwareRequest(options));
99
+ const result = executeProjectStandardsUpdateIdeAware(buildIdeAwareRequest(options, ideId));
64
100
  const summary = summarizeProjectStandardsUpdateResult(result);
65
101
  const response = summary.reviewSuggestions.length > 0
66
102
  ? fail('standards.update', 'STANDARDS_UPDATE_REVIEW_REQUIRED', 'Standards update requires manual review', summary, summary.reviewSuggestions)
@@ -72,7 +108,7 @@ function runStandardsUpdate(io, options) {
72
108
  }
73
109
  catch (error) {
74
110
  printResult(io, fail('standards.update', 'STANDARDS_UPDATE_FAILED', getErrorMessage(error), {}, [
75
- 'Check the project path, CLAUDE.md contents, and existing .claude/rules directory before retrying'
111
+ 'Check the project path, AGENTS.md contents, and existing .claude/rules directory before retrying'
76
112
  ]), options.json);
77
113
  process.exitCode = 1;
78
114
  }
@@ -80,8 +116,8 @@ function runStandardsUpdate(io, options) {
80
116
  export function registerStandardsInitCommands(standards, io) {
81
117
  addJsonOption(withWriteFlags(standards
82
118
  .command('init')
83
- .description('Initialize project-local coding standards for Peaks skill preflight'), 'write missing standards into the target project')).action((options) => runStandardsInit(io, options));
119
+ .description('Initialize project-local coding standards for Peaks skill preflight (AGENTS.md body + the CLAUDE.md pointer that imports it)'), 'write missing standards into the target project')).action((options) => runStandardsInit(io, options));
84
120
  addJsonOption(withWriteFlags(standards
85
121
  .command('update')
86
- .description('Append managed standards metadata to an existing CLAUDE.md without rewriting the body'), 'append managed metadata to the target project')).action((options) => runStandardsUpdate(io, options));
122
+ .description('Append managed standards metadata to the existing AGENTS.md / CLAUDE.md without rewriting their bodies'), 'append managed metadata to the target project')).action((options) => runStandardsUpdate(io, options));
87
123
  }
@@ -2,7 +2,7 @@ import { migrateStandards } from '../../../services/standards/migrate-service.js
2
2
  import { migrateClaudeRules } from '../../../services/standards/migrate-claude-rules-service.js';
3
3
  import { fail, ok } from 'peaks-loop-shared/result';
4
4
  import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
5
- /** `--from-claude-rules`: thin `.claude/rules/` to pointers, scaffold `.peaks/standards/`. */
5
+ /** `--from-claude-rules`: thin `.claude/rules/` to pointers, scaffold `.peaks/standards/` + the constitution. */
6
6
  function runMigrateClaudeRules(io, options, projectRoot) {
7
7
  try {
8
8
  const result = migrateClaudeRules({ projectRoot, apply: options.apply === true });
@@ -13,6 +13,7 @@ function runMigrateClaudeRules(io, options, projectRoot) {
13
13
  backupPath: null,
14
14
  thinnedFiles: [],
15
15
  scaffoldedFiles: [],
16
+ scaffoldedConstitutionFiles: [],
16
17
  preservedFiles: [],
17
18
  wouldChange: false,
18
19
  applied: false,
@@ -21,7 +22,7 @@ function runMigrateClaudeRules(io, options, projectRoot) {
21
22
  process.exitCode = 1;
22
23
  }
23
24
  }
24
- /** Default branch: rewrite the legacy heartbeat block in CLAUDE.md. */
25
+ /** Default branch: rewrite the legacy heartbeat block in the project's constitution file. */
25
26
  function runMigrateLegacy(io, options, projectRoot) {
26
27
  try {
27
28
  const result = migrateStandards({ project: projectRoot, apply: options.apply === true });
@@ -43,10 +44,10 @@ function runMigrateLegacy(io, options, projectRoot) {
43
44
  export function registerStandardsMigrateCommand(standards, io) {
44
45
  addJsonOption(standards
45
46
  .command('migrate')
46
- .description('Rewrite a consumer project CLAUDE.md to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write. With --from-claude-rules, thins the 1.x .claude/rules/ tree to 2-line pointers and scaffolds .peaks/standards/ (slice 2026-06-12-standards-migrate-claude-rules).')
47
+ .description('Rewrite a consumer project constitution file (AGENTS.md, or CLAUDE.md in a 1.x tree) to drop the legacy heartbeat block (slice 028). Dry-run by default; pass --apply to write. With --from-claude-rules, thins the 1.x .claude/rules/ tree to 2-line pointers and scaffolds .peaks/standards/ plus the AGENTS.md + CLAUDE.md constitution (slice 2026-06-12-standards-migrate-claude-rules).')
47
48
  .option('--project <path>', 'target project root')
48
49
  .option('--apply', 'rewrite the legacy block in place; default is dry-run')
49
- .option('--from-claude-rules', 'thin .claude/rules/ to pointers and scaffold .peaks/standards/')).action((options) => {
50
+ .option('--from-claude-rules', 'thin .claude/rules/ to pointers and scaffold .peaks/standards/ + the constitution files')).action((options) => {
50
51
  const projectRoot = options.project ?? process.cwd();
51
52
  if (options.fromClaudeRules === true) {
52
53
  runMigrateClaudeRules(io, options, projectRoot);
@@ -36,6 +36,7 @@ export declare function makeCliRunner(args: {
36
36
  ids: {
37
37
  readonly rid: string;
38
38
  readonly sid: string;
39
+ readonly projectRoot: string;
39
40
  };
40
41
  emissions: DagEmissions;
41
42
  }): (spec: DispatchSpec) => Promise<SliceOutcome>;
@@ -1,6 +1,7 @@
1
1
  import { detectInstalledIde } from '../../services/ide/ide-detector.js';
2
2
  import { getAdapter } from '../../services/ide/ide-registry.js';
3
3
  import { planFileOverlapWaves } from '../../services/dispatch/file-overlap-wave-planner.js';
4
+ import { buildScratchPathInjection } from './dispatch-scratch-path-block.js';
4
5
  /** Detect the IDE and resolve its sub-agent dispatcher. */
5
6
  export function resolveDagDispatcher(projectRoot) {
6
7
  const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
@@ -32,9 +33,18 @@ export function planFirstLevelWaves(dag, levelArr) {
32
33
  export function makeCliRunner(args) {
33
34
  const { firstLevelIds, dispatcher, ids, emissions } = args;
34
35
  return async (spec) => {
36
+ // The scratch path is pinned HERE, in the brief the leaf receives: the DAG
37
+ // path does not pass through the prompt composer, so without this the leaf
38
+ // would pick its own redirect target, and a cwd-relative one lands at the
39
+ // repository root.
40
+ const scratch = buildScratchPathInjection({
41
+ projectRoot: ids.projectRoot,
42
+ sid: ids.sid,
43
+ role: spec.role
44
+ });
35
45
  const toolCall = dispatcher.buildToolCall({
36
46
  role: spec.role,
37
- prompt: spec.prompt,
47
+ prompt: `${spec.prompt}\n\n${scratch.block}`,
38
48
  requestId: ids.rid,
39
49
  sessionId: ids.sid
40
50
  });
@@ -3,6 +3,7 @@
3
3
  // in-process pipeline runs, so it lives in its own module.
4
4
  import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
5
5
  import { printResult } from '../cli-helpers.js';
6
+ import { buildScratchPathInjection } from './dispatch-scratch-path-block.js';
6
7
  function resolveMaxConcurrent(options) {
7
8
  return typeof options.maxConcurrent === 'string' && options.maxConcurrent.length > 0
8
9
  ? Number.parseInt(options.maxConcurrent, 10)
@@ -32,6 +33,23 @@ function reportDetachedError(io, role, error, asJson) {
32
33
  ]), asJson);
33
34
  process.exitCode = 1;
34
35
  }
36
+ /**
37
+ * The brief the vendor CLI receives: the caller's prompt plus the scratch
38
+ * block.
39
+ *
40
+ * The scratch path is pinned HERE, in the brief itself: the detached path does
41
+ * not pass through the prompt composer, so without this the leaf would pick its
42
+ * own redirect target, and a cwd-relative one lands at the repository root. The
43
+ * session id is resolved the way the detached handler resolves it, so both name
44
+ * one directory.
45
+ */
46
+ function detachedBrief(options, role) {
47
+ const projectRoot = options.project ?? process.cwd();
48
+ const sid = process.env.PEAKS_SESSION_ID ?? 'local';
49
+ const scratch = buildScratchPathInjection({ projectRoot, sid, role });
50
+ const prompt = typeof options.prompt === 'string' ? options.prompt : '';
51
+ return `${prompt}\n\n${scratch.block}`;
52
+ }
35
53
  export async function runDetachedDispatch(io, role, options, asJson) {
36
54
  try {
37
55
  const { dispatch: detachedDispatch } = await import('./sub-agent/detached.js');
@@ -39,7 +57,7 @@ export async function runDetachedDispatch(io, role, options, asJson) {
39
57
  const maxConcurrent = resolveMaxConcurrent(options);
40
58
  const result = await detachedDispatch({
41
59
  role,
42
- prompt: typeof options.prompt === 'string' ? options.prompt : '',
60
+ prompt: detachedBrief(options, role),
43
61
  requestId: options.requestId ?? 'unknown-rid',
44
62
  mode: 'detached',
45
63
  ...(typeof options.vendor === 'string' ? { vendor: options.vendor } : {}),
@@ -1,9 +1,45 @@
1
1
  /**
2
- * `peaks mut` — pure helper module extracted from `mut-commands.ts`
3
- * (file-size cap campaign). Mechanical move only: the stub-report
4
- * factories and the summary emitter keep their original behavior.
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".
5
17
  */
6
- import { type AssertionsReport, type MutationReport } from 'peaks-loop-mut';
18
+ import { Command } from 'commander';
19
+ import { type AssertionsReport, type MutationReport, type StrykerInvoker } from 'peaks-loop-mut';
20
+ import { type ProgramIO } 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 declare const MUT_CLI_ERROR_CODE = "MUT_FAILED";
27
+ /**
28
+ * The IO the mut family writes to when the caller injects none. Same
29
+ * shape as `src/cli/program.ts`'s default sinks: one trailing newline
30
+ * per write.
31
+ */
32
+ export declare const DEFAULT_MUT_IO: ProgramIO;
33
+ /** The options every Stryker-backed subcommand receives. */
34
+ export interface MutCommandArgs {
35
+ readonly project: string;
36
+ readonly testFiles: string[];
37
+ readonly mutate?: string[];
38
+ readonly inputSig: string;
39
+ readonly sessionId: string;
40
+ readonly out: string;
41
+ readonly json: boolean;
42
+ }
7
43
  /**
8
44
  * Pure helper: a stub AssertionsReport used when only Stryker ran.
9
45
  * The mutants-only path does NOT touch the AST scanner; we still need
@@ -22,9 +58,40 @@ export declare function emptyMutation(): MutationReport;
22
58
  * both `--json` and the human-readable branches so the `passed` /
23
59
  * `sha256` shape stays consistent regardless of TTY mode.
24
60
  */
25
- export declare function emitSummary(json: boolean, payload: {
61
+ export declare function emitSummary(io: ProgramIO, json: boolean, payload: {
26
62
  ok: true;
27
63
  sha256: string;
28
64
  passed: boolean;
29
65
  path: string;
30
66
  }): void;
67
+ /**
68
+ * Read the machine-readable code off a failure. The production invoker
69
+ * raises named codes (`MUT_TOOLCHAIN_UNAVAILABLE`, `MUT_NO_MUTANTS`,
70
+ * `MUT_MUTATE_PATTERN_REQUIRED`, …) and `runMutation` preserves them
71
+ * while wrapping. Anything without a recognised code falls back to
72
+ * `MUT_FAILED` so the envelope is never anonymous.
73
+ */
74
+ export declare function mutErrorCode(err: unknown): string;
75
+ /** The human-readable half of the envelope. */
76
+ export declare function mutErrorMessage(err: unknown): string;
77
+ /**
78
+ * Emit the failure envelope on stderr and set a non-zero exit code.
79
+ * stdout stays reserved for the `--json` payload (R6), so the envelope
80
+ * goes to stderr exactly like every other peaks CLI error.
81
+ */
82
+ export declare function emitMutError(io: ProgramIO, err: unknown): void;
83
+ /**
84
+ * `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
85
+ * report). One-axis: --session-id required.
86
+ */
87
+ export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
88
+ /**
89
+ * `peaks mut mutants` — Stryker only; writes a stub-assertions
90
+ * mut-report.json. One-axis: --session-id required.
91
+ */
92
+ export declare function buildMutMutantsCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
93
+ /**
94
+ * `peaks mut asserts` — the assertion scan only; writes a mut-report.json
95
+ * with an empty mutation block. One-axis: --session-id required.
96
+ */
97
+ export declare function buildMutAssertsCommand(io: ProgramIO): Command;
@@ -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;