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
@@ -4,11 +4,16 @@
4
4
  * helper, and the synthetic-lookup refusal renderer. Later additions (the
5
5
  * refusal write-path rule, the fragments-free refusal) live here for the same
6
6
  * file-size reason.
7
+ *
8
+ * The artifact PATH and the record of which intent owns it moved to
9
+ * `best-practice-scan-collision.ts` in the same campaign: the §12.3 collision
10
+ * check needed more room than this file had under the 300-line cap.
7
11
  */
8
12
  import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
9
13
  import { dirname, join, parse } from 'node:path';
10
14
  import { fail } from 'peaks-loop-shared/result';
11
15
  import { printResult } from '../cli-helpers.js';
16
+ import { intentIdLine, scanArtifactPath } from './best-practice-scan-collision.js';
12
17
  export const CATCH_GATE_PROMPT = [
13
18
  '⚠️ 任何跟你真实业务不一样,改 — LLM 推荐可能错。',
14
19
  '回应 (默认 = 接受): 接受 / 接受方案 A|接受方案 B|接受方案 C / 拒绝 + 原因'
@@ -19,20 +24,32 @@ export const INTENT_REQUIRED_MESSAGE = 'best-practice-scan requires --intent <te
19
24
  export const SYNTHETIC_SOURCE_MESSAGE = 'best-practice-scan: SKIPPED — the Context7 / WebSearch lookups in this build are stubs ' +
20
25
  '(synthetic fragments), so no real documentation was consulted and there is nothing to ' +
21
26
  'recommend. No recommendation, no comparison table and no ⚠️ catch gate were produced.';
22
- export function bestPracticeDir(projectRoot) {
23
- return join(projectRoot, 'best-practice');
24
- }
25
- /** `YYYY-MM-DD` is 10 characters, and the slug is capped at 32 so the filename
26
- * stays a filename. Both are part of the pinned artifact path. */
27
- const ISO_DATE_LENGTH = 10;
28
- const SLUG_MAX_LENGTH = 32;
29
- /** `<project>/best-practice/<date>-<slug>.md`. The slug is lossy by design:
30
- * every character outside `[A-Za-z0-9_-]` collapses to `-` and the result is
31
- * truncated to 32, so no intent can introduce a path separator. */
32
- export function scanArtifactPath(projectRoot, slugSource) {
33
- const dateStr = new Date().toISOString().slice(0, ISO_DATE_LENGTH);
34
- const slug = slugSource.replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, SLUG_MAX_LENGTH) || 'intent';
35
- return join(bestPracticeDir(projectRoot), `${dateStr}-${slug}.md`);
27
+ /**
28
+ * The catch-gate reply: the `PEAKS_BEST_PRACTICE_STDIN` seam in tests, the
29
+ * real stdin in production.
30
+ *
31
+ * Moved here from the command file: that file had three lines of headroom
32
+ * under the 300-line cap, and the collision check needed more than that.
33
+ */
34
+ export async function readUserInput() {
35
+ const override = process.env.PEAKS_BEST_PRACTICE_STDIN;
36
+ if (override !== undefined)
37
+ return override;
38
+ if (process.stdin.isTTY)
39
+ return '';
40
+ return new Promise((resolveStdin) => {
41
+ let data = '';
42
+ process.stdin.setEncoding('utf8');
43
+ process.stdin.on('data', (chunk) => {
44
+ // `setEncoding('utf8')` above makes every chunk a string at runtime, but
45
+ // the declared type of the 'data' event is still a Buffer, so the `+`
46
+ // needs a string operand. `String(chunk)` is the same ToString the `+`
47
+ // operator applies, so the bytes accumulated are unchanged.
48
+ data += String(chunk);
49
+ });
50
+ process.stdin.on('end', () => resolveStdin(data.trim()));
51
+ process.stdin.on('error', () => resolveStdin(data.trim()));
52
+ });
36
53
  }
37
54
  /** Refusal body for a synthetic scan. It is written to the artifact path so
38
55
  * the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
@@ -74,7 +91,7 @@ export function writeRefusal(projectRoot, intent, refusal) {
74
91
  ? join(dirname(primary), 'skipped', parse(primary).base)
75
92
  : primary;
76
93
  mkdirSync(dirname(target), { recursive: true });
77
- writeFileSync(target, refusal + '\n', 'utf8');
94
+ writeFileSync(target, intentIdLine(intent) + '\n' + refusal + '\n', 'utf8');
78
95
  return target;
79
96
  }
80
97
  /**
@@ -84,11 +101,14 @@ export function writeRefusal(projectRoot, intent, refusal) {
84
101
  * payload is proved to serialise *before* anything is written: a payload the
85
102
  * printer cannot render must not leave behind an artifact claiming a scan that
86
103
  * never reported.
104
+ *
105
+ * The first line is the intent-id marker, so a later scan can tell which
106
+ * intent owns this artifact.
87
107
  */
88
- export function writeRenderedArtifact(artifactPath, table, payload) {
108
+ export function writeRenderedArtifact(artifactPath, table, payload, intent) {
89
109
  JSON.stringify(payload);
90
110
  mkdirSync(dirname(artifactPath), { recursive: true });
91
- writeFileSync(artifactPath, table + '\n', 'utf8');
111
+ writeFileSync(artifactPath, intentIdLine(intent) + '\n' + table + '\n', 'utf8');
92
112
  }
93
113
  export const NO_FRAGMENTS_MESSAGE = 'best-practice-scan: NO FRAGMENTS — the lookups this scan resolved against returned no ' +
94
114
  'documentation at all, so there is nothing to compare and no recommendation to make. ' +
@@ -1,9 +1,13 @@
1
1
  import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
2
2
  import { fail } from 'peaks-loop-shared/result';
3
3
  import { runAutoCompact } from '../../services/code/auto-compact-orchestrator.js';
4
+ import { normalizeAutoCompactMode } from '../../services/code/auto-compact-modes.js';
5
+ import { resolveAutoCompactProfile } from '../../services/code/auto-compact-profile.js';
4
6
  import { probeInFlightBatch } from '../../services/workflow/workflow-inflight-probe.js';
7
+ import { readDispatchLedgerFacts } from '../../services/dispatch/dispatch-ledger-reader.js';
5
8
  import { readActiveSid } from './code-runtime-session.js';
6
9
  import { buildAutoCompactEnvelope } from './code-auto-compact-envelope.js';
10
+ import { describeDeferral, withDeferralDetail } from './code-auto-compact-deferral.js';
7
11
  const AUTO_COMPACT_DESCRIPTION = 'v2.13.0 AC-4: zero-human-intervention auto-compact. Probes current ' +
8
12
  'context-fill % via the active IDE adapter; ≥ 0.85 writes a pre-compact ' +
9
13
  'checkpoint + convergence plan + auto-decisions log; ≥ 0.95 ASKS the ' +
@@ -15,57 +19,64 @@ const AUTO_COMPACT_DESCRIPTION = 'v2.13.0 AC-4: zero-human-intervention auto-com
15
19
  'command acts on. This command is also fired by the installed ' +
16
20
  'PreToolUse hook, which passes `--project .` — without that argument ' +
17
21
  'the hook could never run at all. rid-027 ' +
18
- 'adds `--mode <mode>`: `standard` (0.85/0.95) or `partial` (0.70/0.85 ' +
19
- 'for 24h long-run mode).';
22
+ 'adds `--mode <mode>`: `standard` (pre-compact 0.85 / red-line 0.95) ' +
23
+ 'or `eager` (pre-compact 0.70 / red-line 0.85 — fires earlier than ' +
24
+ '`standard`). With no `--mode`, the project setting `autoCompactProfile` ' +
25
+ 'decides (default `standard`).';
20
26
  /** The invalid-`--mode` branch, lifted verbatim out of the action body. */
21
27
  function reportInvalidAutoCompactMode(io, modeName, json) {
22
- printResult(io, fail('code.auto-compact', 'AUTO_COMPACT_INVALID_MODE', `Invalid --mode '${modeName}'. Valid values: standard | partial.`, null, ['Re-run with --mode standard or --mode partial.']), json);
28
+ printResult(io, fail('code.auto-compact', 'AUTO_COMPACT_INVALID_MODE', `Invalid --mode '${modeName}'. Valid values: standard | eager. The legacy alias 'partial' is also accepted and means 'eager'.`, null, ['Re-run with --mode standard or --mode eager.']), json);
23
29
  process.exitCode = 1;
24
30
  }
25
31
  /**
26
32
  * The `runAutoCompact` input object, lifted verbatim: it reads only its two
27
33
  * parameters, so it has no ordering dependency on the call site.
28
34
  */
29
- function buildAutoCompactInput(opts, modeName) {
30
- // Slice 4.0.8 (D4d): production `inFlightBatch` MUST come from
31
- // the workflow graph probe. The legacy `--in-flight-batch`
32
- // boolean CLI flag is a TEST-ONLY seam (gated by
33
- // `PEAKS_TEST_SEAM === '1'`). When the env flag is unset
34
- // (the production case), we wire `probeInflightBatch` to the
35
- // canonical `workflow-inflight-probe.ts` service so the
36
- // production decision is graph-backed, not lease-age.
35
+ function buildAutoCompactInput(opts, modeName, capture) {
36
+ // The in-flight signal comes from the session's DISPATCH LEDGER — the
37
+ // `active-dispatches.json` index and the dispatch records it names. The
38
+ // workflow graphs never carried the fact (a dispatch node sits at
39
+ // `prepared` and no writer stamps a heartbeat onto it), so a graph-backed
40
+ // probe could only ever answer "no" and the deferral was unreachable.
41
+ //
42
+ // The legacy `--in-flight-batch` boolean CLI flag is a TEST-ONLY seam
43
+ // (gated by `PEAKS_TEST_SEAM === '1'`). When the env flag is unset (the
44
+ // production case), we wire `probeInflightBatch` to the canonical
45
+ // `workflow-inflight-probe.ts` service fed by the ledger reader, so the
46
+ // production decision is ledger-backed.
37
47
  const isTestSeam = process.env.PEAKS_TEST_SEAM === '1';
48
+ const projectRoot = opts.project;
38
49
  return {
39
- projectRoot: opts.project,
50
+ projectRoot,
40
51
  sessionId: opts.sessionId ?? readActiveSid(opts.project) ?? undefined,
41
52
  ...(isTestSeam && opts.inFlightBatch === true
42
53
  ? { inFlightBatch: { hasInFlightBatch: true } }
43
54
  : {}),
44
55
  ...(!isTestSeam
45
56
  ? {
46
- probeInflightBatch: () => {
47
- // Synchronous probe: the workflow-inflight-probe
48
- // service is pure / synchronous (no I/O). The
49
- // empty `graphs` array is the production CLI
50
- // default — callers that want a richer fixture
51
- // (e.g. `peaks session 24h-mode`) should hand-roll
52
- // a probe and pass it via the orchestrator's
53
- // input. When no graph is materialized, the
54
- // probe returns `inFlightBatch: false`, matching
55
- // the 4.0.7 zero-pause contract for stock
56
- // projects.
57
- const out = probeInFlightBatch({ now: new Date().toISOString(), graphs: [] });
57
+ probeInflightBatch: (sessionId) => {
58
+ // Synchronous probe: the reader reads files and the
59
+ // workflow-inflight-probe service is pure / synchronous
60
+ // (no I/O). The reader gathers the ledger's facts and the
61
+ // probe decides from them; the reader/probe boundary is
62
+ // what keeps the decision testable on its own.
63
+ const ledger = readDispatchLedgerFacts({ projectRoot, sessionId });
64
+ const out = probeInFlightBatch({ now: new Date().toISOString(), ledger });
65
+ // The whole answer is kept, not just its boolean: the deferral
66
+ // reports WHICH deferral it was, and the reason is in here.
67
+ capture.last = out;
58
68
  return out.inFlightBatch === true;
59
69
  }
60
70
  }
61
71
  : {}),
62
72
  force: opts.force === true,
63
73
  bypassRedLine: opts.bypassRedLine === true,
64
- // Forward the FLAG verbatim — `undefined` when the user named no
65
- // mode — so the orchestrator's fallback to the presence-derived
66
- // mode can actually run. Forwarding the validated `modeName` is
67
- // what disabled 24h → partial.
68
- mode: opts.mode === undefined ? undefined : modeName
74
+ // The profile is resolved ONCE, by the resolver, and handed down
75
+ // explicitly: the CLI flag beats the project setting, and the project
76
+ // setting beats the default. The orchestrator's own fallback reads the
77
+ // same resolver, so the two cannot disagree about which profile is in
78
+ // force.
79
+ mode: modeName
69
80
  };
70
81
  }
71
82
  /** The catch branch, lifted verbatim out of the action body. */
@@ -75,23 +86,43 @@ function reportAutoCompactFailure(io, err, json) {
75
86
  ]), json);
76
87
  process.exitCode = 1;
77
88
  }
89
+ /**
90
+ * The deferral's detail — or null when this run did not defer.
91
+ *
92
+ * The code is the gate: `AUTO_COMPACT_WAIT` is the one the orchestrator returns
93
+ * when the in-flight deferral applied. A run that skipped for another reason, or
94
+ * that reached the red line (where the deferral does not apply), carries no
95
+ * detail, because there was no deferral to describe.
96
+ */
97
+ function deferralDetail(result, probe) {
98
+ if (result.code !== 'AUTO_COMPACT_WAIT')
99
+ return null;
100
+ if (probe === null)
101
+ return null;
102
+ return describeDeferral(probe);
103
+ }
78
104
  /** The action body, lifted to a module-level function so both it and the registrar fit in 50 lines. */
79
105
  async function runAutoCompactAction(opts, io) {
80
106
  try {
81
- const { isValidMode } = await import('../../services/code/auto-compact-modes.js');
82
- const modeName = opts.mode ?? 'standard';
83
- if (!isValidMode(modeName)) {
84
- reportInvalidAutoCompactMode(io, modeName, opts.json);
107
+ // `--mode` is normalized ONCE, here: the legacy alias `partial` becomes
108
+ // `eager` before anything is stored, reported or logged, so the alias
109
+ // never reaches the runtime state.
110
+ const cliMode = opts.mode === undefined ? null : normalizeAutoCompactMode(opts.mode);
111
+ if (opts.mode !== undefined && cliMode === null) {
112
+ reportInvalidAutoCompactMode(io, opts.mode, opts.json);
85
113
  return;
86
114
  }
87
- const result = await runAutoCompact(buildAutoCompactInput(opts, modeName));
115
+ const selection = resolveAutoCompactProfile({ projectRoot: opts.project, cliMode });
116
+ const capture = { last: null };
117
+ const result = await runAutoCompact(buildAutoCompactInput(opts, selection.profile, capture));
88
118
  const code = result.code;
89
119
  const exitOk = result.ok || code === 'AUTO_COMPACT_SKIP' || code === 'AUTO_COMPACT_WAIT';
90
120
  // Adapt AutoCompactResult → ResultEnvelope so printResult's
91
121
  // generic accepts it. The orchestrator envelope carries
92
122
  // `data` on success-path and `nextActions` on the error
93
123
  // path; surface both directly to the user.
94
- printResult(io, buildAutoCompactEnvelope(result), opts.json);
124
+ const envelope = buildAutoCompactEnvelope(result);
125
+ printResult(io, withDeferralDetail(envelope, deferralDetail(result, capture.last)), opts.json);
95
126
  if (!exitOk)
96
127
  process.exitCode = 1;
97
128
  }
@@ -116,9 +147,9 @@ export function registerCodeAutoCompactCommand(code, io) {
116
147
  // advertising it, not to change its meaning.
117
148
  .option('--bypass-red-line', 'no-op: the 95% red line no longer gates dispatch, so there is nothing to bypass (accepted for backward compatibility)')
118
149
  // No commander default here, deliberately. A declared default makes
119
- // `opts.mode` permanently defined, which defeats the orchestrator's
120
- // `input.mode ?? resolveAutoCompactMode(projectRoot)` fallback and
121
- // silently disables "24h mode auto-selects partial" — the help text
122
- // below promises it. Absence must stay absent.
123
- .option('--mode <mode>', 'auto-compact mode (standard | partial). Default: standard. 24h mode auto-selects partial.')).action((opts) => runAutoCompactAction(opts, io));
150
+ // `opts.mode` permanently defined, which would defeat the resolver's
151
+ // "project setting → default" fallback — the help text below promises
152
+ // that the project setting decides when no `--mode` is named.
153
+ // Absence must stay absent.
154
+ .option('--mode <mode>', 'auto-compact mode for THIS call: standard | eager (the legacy alias `partial` is accepted and means `eager`). Default: the project setting `autoCompactProfile`, else standard.')).action((opts) => runAutoCompactAction(opts, io));
124
155
  }
@@ -0,0 +1,34 @@
1
+ import type { ResultEnvelope } from 'peaks-loop-shared/result';
2
+ import type { ProbeResult } from '../../services/workflow/workflow-inflight-probe.js';
3
+ /** One probe diagnostic, reduced to the two fields a consumer needs. */
4
+ export interface DeferralCode {
5
+ readonly code: string;
6
+ readonly message: string;
7
+ }
8
+ /** What the deferral was, in the shape the envelope carries it. */
9
+ export interface DeferralDetail {
10
+ /** The probe's own reason: `fresh-dispatch` or `unknown-ledger-state`. */
11
+ readonly reason: string;
12
+ /** True when the deferral rests on something the probe could not establish. */
13
+ readonly unknown: boolean;
14
+ readonly warnings: readonly DeferralCode[];
15
+ readonly errors: readonly DeferralCode[];
16
+ }
17
+ /** The probe's answer, in the shape the envelope carries it. */
18
+ export declare function describeDeferral(probe: ProbeResult): DeferralDetail;
19
+ /**
20
+ * The one sentence that tells the two deferrals apart.
21
+ *
22
+ * The codes are named because they are the machine-readable half of the same
23
+ * fact, and an operator who wants the detail can grep the code.
24
+ */
25
+ export declare function deferralSentence(detail: DeferralDetail): string;
26
+ /**
27
+ * The envelope, with the deferral's reason attached.
28
+ *
29
+ * The detail lands in three places, because three readers exist: `data.deferral`
30
+ * for a machine, `warnings` for the codes the probe collected, and the message
31
+ * itself for whoever reads the printed output. An envelope that did not defer
32
+ * comes back unchanged.
33
+ */
34
+ export declare function withDeferralDetail(envelope: ResultEnvelope<unknown>, detail: DeferralDetail | null): ResultEnvelope<unknown>;
@@ -0,0 +1,59 @@
1
+ /** The probe's reason when it defers because a fact about the batch is unknown. */
2
+ const UNKNOWN_REASON = 'unknown-ledger-state';
3
+ function toCode(warning) {
4
+ return { code: warning.code, message: warning.message };
5
+ }
6
+ /** The probe's answer, in the shape the envelope carries it. */
7
+ export function describeDeferral(probe) {
8
+ return {
9
+ reason: probe.reason,
10
+ unknown: probe.reason === UNKNOWN_REASON,
11
+ warnings: probe.warnings.map(toCode),
12
+ errors: probe.errors.map(toCode)
13
+ };
14
+ }
15
+ /**
16
+ * The one sentence that tells the two deferrals apart.
17
+ *
18
+ * The codes are named because they are the machine-readable half of the same
19
+ * fact, and an operator who wants the detail can grep the code.
20
+ */
21
+ export function deferralSentence(detail) {
22
+ const codes = [...detail.errors, ...detail.warnings].map((code) => code.code);
23
+ const head = detail.unknown
24
+ ? 'Deferral reason: the dispatch ledger state is UNKNOWN'
25
+ : 'Deferral reason: a dispatch IS in flight';
26
+ const why = detail.unknown
27
+ ? 'the ledger, or one of the records it names, could not be read, or a record said ' +
28
+ 'something this probe does not recognise, so this deferral is NOT a known running batch'
29
+ : 'the ledger holds a live dispatch, so the compaction waits for it; this is the ' +
30
+ 'expected deferral, not a ledger problem';
31
+ const named = codes.length === 0 ? '' : ` Codes: ${codes.join(', ')}.`;
32
+ return `${head} (reason=${detail.reason}) — ${why}.${named}`;
33
+ }
34
+ /**
35
+ * The envelope, with the deferral's reason attached.
36
+ *
37
+ * The detail lands in three places, because three readers exist: `data.deferral`
38
+ * for a machine, `warnings` for the codes the probe collected, and the message
39
+ * itself for whoever reads the printed output. An envelope that did not defer
40
+ * comes back unchanged.
41
+ */
42
+ export function withDeferralDetail(envelope, detail) {
43
+ if (detail === null)
44
+ return envelope;
45
+ const sentence = deferralSentence(detail);
46
+ const codes = [...detail.errors, ...detail.warnings].map((code) => `${code.code}: ${code.message}`);
47
+ const data = typeof envelope.data === 'object' && envelope.data !== null ? { ...envelope.data } : {};
48
+ const nextActions = [...envelope.nextActions];
49
+ if (nextActions.length === 0)
50
+ nextActions.push(sentence);
51
+ else
52
+ nextActions[0] = `${nextActions[0]} ${sentence}`;
53
+ return {
54
+ ...envelope,
55
+ data: { ...data, deferral: detail },
56
+ warnings: [...envelope.warnings, ...codes],
57
+ nextActions
58
+ };
59
+ }
@@ -4,10 +4,10 @@
4
4
  * payload from stdin and either exits 0 (allow) or exits 2 with stderr
5
5
  * containing PEAKS_CODE_PROHIBITED_DIRECT_EDIT (deny).
6
6
  *
7
- * This command is the runtime adapter for the shell-script sibling
8
- * (`src/services/hooks/pre-tool-code-gate.sh`). Both share the same
9
- * path-family decision; the CLI invokes the same pure decision
10
- * function (`decideGateAction`) the shell script encodes.
7
+ * This command is the runtime adapter the shell-script sibling
8
+ * (`src/services/hooks/pre-tool-code-gate.sh`) EXECS. The path-family
9
+ * decision lives in ONE implementation — `decideGateAction` — and the
10
+ * sibling's own no-CLI fallback is a narrower copy of it.
11
11
  *
12
12
  * Settings.json entry shape (vendor-neutral, registered by
13
13
  * `peaks hooks install`): an `Edit|Write|MultiEdit` matcher whose command is
@@ -4,10 +4,10 @@
4
4
  * payload from stdin and either exits 0 (allow) or exits 2 with stderr
5
5
  * containing PEAKS_CODE_PROHIBITED_DIRECT_EDIT (deny).
6
6
  *
7
- * This command is the runtime adapter for the shell-script sibling
8
- * (`src/services/hooks/pre-tool-code-gate.sh`). Both share the same
9
- * path-family decision; the CLI invokes the same pure decision
10
- * function (`decideGateAction`) the shell script encodes.
7
+ * This command is the runtime adapter the shell-script sibling
8
+ * (`src/services/hooks/pre-tool-code-gate.sh`) EXECS. The path-family
9
+ * decision lives in ONE implementation — `decideGateAction` — and the
10
+ * sibling's own no-CLI fallback is a narrower copy of it.
11
11
  *
12
12
  * Settings.json entry shape (vendor-neutral, registered by
13
13
  * `peaks hooks install`): an `Edit|Write|MultiEdit` matcher whose command is
@@ -34,6 +34,11 @@ export declare function canonicalizeProjectOption(project: string | undefined):
34
34
  * The field is additive and present only when stale, so no existing consumer
35
35
  * of the envelope changes shape. `null` projectRoot means the caller had no
36
36
  * project to inspect — skipped, not assumed stale.
37
+ *
38
+ * WHAT THE WARNING SAYS. It names the FILE that no longer matches and WHAT
39
+ * about it, because "the version numbers differ" does not tell a reader which
40
+ * file to open. The remedy (`peaks workspace init`) is in the message: the
41
+ * reader is an LLM that must be able to act without guessing a command.
37
42
  */
38
43
  export declare function generatedConfigNotice(projectRoot: string | undefined): {
39
44
  field: Record<string, unknown>;
@@ -48,6 +48,11 @@ export function canonicalizeProjectOption(project) {
48
48
  * The field is additive and present only when stale, so no existing consumer
49
49
  * of the envelope changes shape. `null` projectRoot means the caller had no
50
50
  * project to inspect — skipped, not assumed stale.
51
+ *
52
+ * WHAT THE WARNING SAYS. It names the FILE that no longer matches and WHAT
53
+ * about it, because "the version numbers differ" does not tell a reader which
54
+ * file to open. The remedy (`peaks workspace init`) is in the message: the
55
+ * reader is an LLM that must be able to act without guessing a command.
51
56
  */
52
57
  export function generatedConfigNotice(projectRoot) {
53
58
  if (projectRoot === undefined)
@@ -55,21 +60,50 @@ export function generatedConfigNotice(projectRoot) {
55
60
  const staleness = detectStaleGeneratedArtifacts(projectRoot);
56
61
  if (!staleness.stale)
57
62
  return { field: {}, warnings: [] };
58
- const onDiskVersion = staleness.onDisk?.packageVersion ?? '(unstamped)';
59
63
  return {
60
64
  field: {
61
65
  generatedArtifacts: {
62
66
  stale: true,
63
67
  reasons: staleness.reasons,
64
68
  onDiskPackageVersion: staleness.onDisk?.packageVersion ?? null,
65
- installedPackageVersion: staleness.expected.packageVersion
69
+ installedPackageVersion: staleness.expected.packageVersion,
70
+ drift: staleness.drift
66
71
  }
67
72
  },
68
- warnings: [
69
- `Generated config at '${projectRoot}' was produced by peaks-loop ${onDiskVersion} ` +
70
- `but ${staleness.expected.packageVersion} is installed (${staleness.reasons.join(', ')}). ` +
71
- `Re-run \`peaks workspace init\` ` +
72
- `to regenerate .claude/settings.local.json and the offline template copy.`
73
- ]
73
+ warnings: [stalenessWarning(projectRoot, staleness)]
74
74
  };
75
75
  }
76
+ /**
77
+ * The one sentence the reader gets.
78
+ *
79
+ * The drift detail is appended only when there IS one: a verdict driven by the
80
+ * stamp alone (`unstamped`, `stamp-unreadable`, `template-changed`) has no
81
+ * file to point at, and inventing one would be a claim about a file nobody
82
+ * compared.
83
+ *
84
+ * The details are GROUPED per artifact, so a file that differs in two ways is
85
+ * named once with both of its differences — a warning that repeats the same
86
+ * path twice reads as two files.
87
+ */
88
+ function stalenessWarning(projectRoot, staleness) {
89
+ const onDiskVersion = staleness.onDisk?.packageVersion ?? '(unstamped)';
90
+ const head = `Generated config at '${projectRoot}' was produced by peaks-loop ${onDiskVersion} ` +
91
+ `but ${staleness.expected.packageVersion} is installed (${staleness.reasons.join(', ')}). ` +
92
+ `Re-run \`peaks workspace init\` ` +
93
+ `to regenerate .claude/settings.local.json and the offline template copy.`;
94
+ if (staleness.drift.length === 0)
95
+ return head;
96
+ return `${head} Inconsistent: ${groupDriftDetails(staleness.drift)}.`;
97
+ }
98
+ /** The drift details, one clause per artifact. */
99
+ function groupDriftDetails(drift) {
100
+ const grouped = new Map();
101
+ for (const entry of drift) {
102
+ const details = grouped.get(entry.artifact) ?? [];
103
+ details.push(entry.detail);
104
+ grouped.set(entry.artifact, details);
105
+ }
106
+ return [...grouped.entries()]
107
+ .map(([artifact, details]) => `${artifact}: ${details.join('; ')}`)
108
+ .join(' | ');
109
+ }