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
@@ -28,18 +28,32 @@
28
28
  * machine-local bookkeeping (`session.json`, `.outer-session-cache.json`), so
29
29
  * the stamp lives beside them and needs no new `.gitignore` line.
30
30
  *
31
- * WHAT IS COMPARED. Two versions, because they move independently and a
32
- * mismatch of either means the same thing to the user (regenerate):
33
- * - `packageVersion` — the installed peaks-loop release. Moves on `npm i -g`.
34
- * - `templateVersion` — `TEMPLATE_VERSION`, the shape of the hooks tree this
35
- * release emits. Can move without a release the user would notice.
31
+ * WHAT IS COMPARED. The CONTENT of the generated artifacts, against the
32
+ * current release's rendered template — not the release number that wrote them.
33
+ * A release bump is not a change to the bytes: `packageVersion` moves on every
34
+ * publish, so a version comparison reports "behind" on every project that
35
+ * upgraded without re-running init, forever. Such a warning carries no action,
36
+ * and a warning that carries no action is noise the reader learns to ignore —
37
+ * which is the state this detector was built to end.
38
+ *
39
+ * So the verdict is a content verdict:
40
+ * - the rendered template (`buildClaudeSettingsLocalJson()`) is compared
41
+ * against `.claude/settings.local.json` and the offline template copy by
42
+ * `templateContentMatches` — the same predicate the materializer uses to
43
+ * decide `already-current`, so the detector and the writer cannot disagree
44
+ * about what "current" means;
45
+ * - `templateVersion` still decides on its own: a different template shape
46
+ * means the artifacts were written by a release whose hooks tree this one
47
+ * does not carry, which is staleness whatever the bytes look like;
48
+ * - `packageVersion` is reported as INFORMATION (which release wrote the
49
+ * artifacts on disk) and does not make a project stale on its own.
36
50
  *
37
51
  * The stamp records what the generator LAST WROTE. It is not a promise that
38
52
  * the on-disk artifacts still match it — a user may have hand-edited
39
- * `.claude/settings.local.json` since. That question is the existing
40
- * `templateContentMatches` comparator's, and it is asked on the next init,
41
- * which is what this detector tells the user to trigger.
53
+ * `.claude/settings.local.json` since, and that is drift the content
54
+ * comparison now detects.
42
55
  */
56
+ import { type GeneratedArtifactDrift } from './generated-artifacts-content.js';
43
57
  /**
44
58
  * Where the stamp lives, relative to the project root.
45
59
  *
@@ -62,12 +76,15 @@ export type GeneratedArtifactsStamp = {
62
76
  readonly writtenAt: string;
63
77
  };
64
78
  export type GeneratedArtifactsStaleness = {
65
- /** `true` only when a generated artifact exists AND its stamp is behind. */
79
+ /** `true` only when a generated artifact's CONTENT no longer matches the current template. */
66
80
  readonly stale: boolean;
67
81
  /**
68
- * Machine-readable reason codes, empty when `stale` is false:
69
- * - `package-upgraded` — on-disk stamp names an older peaks-loop release
70
- * - `template-changed` — on-disk stamp names an older template shape
82
+ * Machine-readable reason codes. `package-upgraded` is INFORMATION — which
83
+ * release wrote the artifacts — and does not by itself make `stale` true;
84
+ * every other code does.
85
+ * - `package-upgraded` — on-disk stamp names a different peaks-loop release
86
+ * - `template-changed` — on-disk stamp names a different template shape
87
+ * - `content-drift` — a generated artifact no longer matches the rendered template
71
88
  * - `unstamped` — artifacts exist but predate this stamp
72
89
  * - `stamp-unreadable` — a stamp file exists but is not parseable
73
90
  */
@@ -77,6 +94,8 @@ export type GeneratedArtifactsStaleness = {
77
94
  readonly packageVersion: string;
78
95
  readonly templateVersion: string;
79
96
  };
97
+ /** What differs, per artifact, for a `content-drift` verdict. Empty otherwise. */
98
+ readonly drift: ReadonlyArray<GeneratedArtifactDrift>;
80
99
  };
81
100
  export declare function generatedArtifactsStampPath(projectRoot: string): string;
82
101
  /**
@@ -110,7 +129,11 @@ export declare function writeGeneratedArtifactsStamp(projectRoot: string, option
110
129
  * Returns `stale: false` — with no reasons — for the two cases that are NOT
111
130
  * staleness:
112
131
  * - the project has no generated artifact at all (never initialized), and
113
- * - the stamp matches both expected versions.
132
+ * - the artifacts' CONTENT still matches the current template.
133
+ *
134
+ * A `packageVersion` that differs from the installed release is reported in
135
+ * `reasons` as information and does NOT make the project stale: a release bump
136
+ * moves that number on every publish, while the generated bytes stand still.
114
137
  *
115
138
  * `unstamped` is reported only when an artifact EXISTS and no stamp does:
116
139
  * those are projects initialized by a release that predates this module, and
@@ -28,23 +28,37 @@
28
28
  * machine-local bookkeeping (`session.json`, `.outer-session-cache.json`), so
29
29
  * the stamp lives beside them and needs no new `.gitignore` line.
30
30
  *
31
- * WHAT IS COMPARED. Two versions, because they move independently and a
32
- * mismatch of either means the same thing to the user (regenerate):
33
- * - `packageVersion` — the installed peaks-loop release. Moves on `npm i -g`.
34
- * - `templateVersion` — `TEMPLATE_VERSION`, the shape of the hooks tree this
35
- * release emits. Can move without a release the user would notice.
31
+ * WHAT IS COMPARED. The CONTENT of the generated artifacts, against the
32
+ * current release's rendered template — not the release number that wrote them.
33
+ * A release bump is not a change to the bytes: `packageVersion` moves on every
34
+ * publish, so a version comparison reports "behind" on every project that
35
+ * upgraded without re-running init, forever. Such a warning carries no action,
36
+ * and a warning that carries no action is noise the reader learns to ignore —
37
+ * which is the state this detector was built to end.
38
+ *
39
+ * So the verdict is a content verdict:
40
+ * - the rendered template (`buildClaudeSettingsLocalJson()`) is compared
41
+ * against `.claude/settings.local.json` and the offline template copy by
42
+ * `templateContentMatches` — the same predicate the materializer uses to
43
+ * decide `already-current`, so the detector and the writer cannot disagree
44
+ * about what "current" means;
45
+ * - `templateVersion` still decides on its own: a different template shape
46
+ * means the artifacts were written by a release whose hooks tree this one
47
+ * does not carry, which is staleness whatever the bytes look like;
48
+ * - `packageVersion` is reported as INFORMATION (which release wrote the
49
+ * artifacts on disk) and does not make a project stale on its own.
36
50
  *
37
51
  * The stamp records what the generator LAST WROTE. It is not a promise that
38
52
  * the on-disk artifacts still match it — a user may have hand-edited
39
- * `.claude/settings.local.json` since. That question is the existing
40
- * `templateContentMatches` comparator's, and it is asked on the next init,
41
- * which is what this detector tells the user to trigger.
53
+ * `.claude/settings.local.json` since, and that is drift the content
54
+ * comparison now detects.
42
55
  */
43
56
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
44
57
  import { dirname, join } from 'node:path';
45
58
  import { CLI_VERSION } from 'peaks-loop-shared/version';
46
59
  import { isExpectedFsMiss } from '../../shared/fs-utils.js';
47
60
  import { TEMPLATE_VERSION } from './claude-settings-template.js';
61
+ import { compareGeneratedArtifactContent } from './generated-artifacts-content.js';
48
62
  /**
49
63
  * Where the stamp lives, relative to the project root.
50
64
  *
@@ -139,7 +153,11 @@ export function writeGeneratedArtifactsStamp(projectRoot, options = {}) {
139
153
  * Returns `stale: false` — with no reasons — for the two cases that are NOT
140
154
  * staleness:
141
155
  * - the project has no generated artifact at all (never initialized), and
142
- * - the stamp matches both expected versions.
156
+ * - the artifacts' CONTENT still matches the current template.
157
+ *
158
+ * A `packageVersion` that differs from the installed release is reported in
159
+ * `reasons` as information and does NOT make the project stale: a release bump
160
+ * moves that number on every publish, while the generated bytes stand still.
143
161
  *
144
162
  * `unstamped` is reported only when an artifact EXISTS and no stamp does:
145
163
  * those are projects initialized by a release that predates this module, and
@@ -150,18 +168,22 @@ export function detectStaleGeneratedArtifacts(projectRoot) {
150
168
  const onDisk = readGeneratedArtifactsStamp(projectRoot);
151
169
  const artifactsPresent = hasGeneratedArtifact(projectRoot);
152
170
  if (!artifactsPresent) {
153
- return { stale: false, reasons: [], onDisk, expected };
171
+ return { stale: false, reasons: [], onDisk, expected, drift: [] };
154
172
  }
155
173
  if (existsSync(generatedArtifactsStampPath(projectRoot)) && onDisk === null) {
156
- return { stale: true, reasons: ['stamp-unreadable'], onDisk, expected };
174
+ return { stale: true, reasons: ['stamp-unreadable'], onDisk, expected, drift: [] };
157
175
  }
158
176
  if (onDisk === null) {
159
- return { stale: true, reasons: ['unstamped'], onDisk, expected };
177
+ return { stale: true, reasons: ['unstamped'], onDisk, expected, drift: [] };
160
178
  }
179
+ const content = compareGeneratedArtifactContent(projectRoot, GENERATED_ARTIFACT_RELATIVE_PATHS);
161
180
  const reasons = [];
162
- if (onDisk.packageVersion !== expected.packageVersion)
163
- reasons.push('package-upgraded');
164
181
  if (onDisk.templateVersion !== expected.templateVersion)
165
182
  reasons.push('template-changed');
166
- return { stale: reasons.length > 0, reasons, onDisk, expected };
183
+ if (onDisk.packageVersion !== expected.packageVersion)
184
+ reasons.push('package-upgraded');
185
+ if (content.drifted)
186
+ reasons.push('content-drift');
187
+ const stale = reasons.includes('template-changed') || reasons.includes('content-drift');
188
+ return { stale, reasons, onDisk, expected, drift: content.drifts };
167
189
  }
@@ -89,3 +89,67 @@ export declare const RUNTIME_SYSTEM_ENTRIES: readonly RuntimeSystemEntry[];
89
89
  * above so the check and the census cannot disagree about the same name.
90
90
  */
91
91
  export declare const RUNTIME_SYSTEM_SUBDIRS: ReadonlySet<string>;
92
+ /**
93
+ * Every registered top-level name — dirs AND files.
94
+ *
95
+ * Derived from the registry above so the census and the registry cannot
96
+ * disagree about what "registered" means.
97
+ */
98
+ export declare const RUNTIME_SYSTEM_ENTRY_NAMES: ReadonlySet<string>;
99
+ /** One top-level entry under the runtime root, as the census sees it. */
100
+ export interface RuntimeRootEntry {
101
+ /** The exact top-level name. */
102
+ readonly name: string;
103
+ /** `dir` for a directory, `file` for everything else. */
104
+ readonly kind: RuntimeEntryKind;
105
+ }
106
+ /** One top-level entry that is neither a session dir nor a registered system entry. */
107
+ export interface RuntimeRootViolation {
108
+ readonly name: string;
109
+ readonly kind: RuntimeEntryKind;
110
+ }
111
+ /**
112
+ * What a read of the runtime root produced.
113
+ *
114
+ * `unreadable` is a first-class outcome, not an exception: a sweep that cannot
115
+ * look must not report "clean" — the one answer it is not entitled to give
116
+ * (see `services/audit/enforcers/root-scratch-artifacts.ts`).
117
+ */
118
+ export type RuntimeRootRead = {
119
+ readonly status: 'read';
120
+ readonly entries: readonly RuntimeRootEntry[];
121
+ } | {
122
+ readonly status: 'unreadable';
123
+ readonly reason: string;
124
+ };
125
+ /**
126
+ * The census verdict. `clean` is reachable ONLY for a tree that was read.
127
+ */
128
+ export type RuntimeRootCensus = {
129
+ readonly status: 'clean';
130
+ readonly entryCount: number;
131
+ } | {
132
+ readonly status: 'violations';
133
+ readonly violations: readonly RuntimeRootViolation[];
134
+ } | {
135
+ readonly status: 'undetermined';
136
+ readonly reason: string;
137
+ };
138
+ /**
139
+ * The census: every top-level entry of the runtime root that is neither a
140
+ * session dir nor a registered system entry.
141
+ *
142
+ * Three classes, in this order:
143
+ *
144
+ * 1. a DIRECTORY whose name is a valid session id — legal. A FILE wearing a
145
+ * session-shaped name is NOT legal: only a directory can be a session
146
+ * home, so such a file is a stray.
147
+ * 2. a name in `RUNTIME_SYSTEM_ENTRIES` — legal, whatever its kind. The
148
+ * registry is the authority on which names may sit at the root.
149
+ * 3. everything else — a violation, reported with its name AND its kind.
150
+ */
151
+ export declare function censusRuntimeRoot(input: {
152
+ readonly read: RuntimeRootRead;
153
+ /** Defaults to the canonical validator; the doctor injects its own. */
154
+ readonly isValidSessionId?: (sid: string) => boolean;
155
+ }): RuntimeRootCensus;
@@ -47,6 +47,7 @@
47
47
  * walk. See `tests/unit/runtime/no-runtime-input-guard.test.ts` for the same
48
48
  * decision made the same way.
49
49
  */
50
+ import { isValidSessionId as canonicalIsValidSessionId } from './sid-naming-guard.js';
50
51
  /**
51
52
  * Reserved top-level dir for session-less command output.
52
53
  *
@@ -139,6 +140,11 @@ export const RUNTIME_SYSTEM_ENTRIES = [
139
140
  name: '.rebuild-binding.lock',
140
141
  kind: 'file',
141
142
  purpose: 'binding-store rebuild lock (session/binding-store.ts)'
143
+ },
144
+ {
145
+ name: 'classify-audit.jsonl',
146
+ kind: 'file',
147
+ purpose: "append-only classify audit log at the runtime root (cli/commands/classify-signals.ts); the path is built dynamically, so the drift guard's AST scan never saw it as a child — the census is what catches it"
142
148
  }
143
149
  ];
144
150
  /**
@@ -146,3 +152,59 @@ export const RUNTIME_SYSTEM_ENTRIES = [
146
152
  * above so the check and the census cannot disagree about the same name.
147
153
  */
148
154
  export const RUNTIME_SYSTEM_SUBDIRS = new Set(RUNTIME_SYSTEM_ENTRIES.filter((entry) => entry.kind === 'dir').map((entry) => entry.name));
155
+ // ---------------------------------------------------------------------------
156
+ // THE CENSUS
157
+ // ---------------------------------------------------------------------------
158
+ //
159
+ // WHY THE REGISTRY WAS NOT ENOUGH. The registry is a list of NAMES the code
160
+ // writes at the runtime root. Until now, only ONE of the two guards could see
161
+ // the tree it governs:
162
+ //
163
+ // - `L3:l3-orphan-sessions` reads DIRECTORIES only. It could never see a
164
+ // stray FILE at the root, so unregistered files accumulated unbounded
165
+ // (204 of them on 2026-10-24) with no product check able to name them.
166
+ // - `tests/unit/workspace/runtime-layout-drift-guard.test.ts` walks `src/**`,
167
+ // not the working tree. It proved the CODE does not write an unregistered
168
+ // child — it said nothing about what is actually sitting on disk.
169
+ //
170
+ // The census below closes the gap: it reads the REAL tree, compares it with
171
+ // the registry above, and reports every top-level entry that is neither a
172
+ // session dir nor a registered system entry — files included.
173
+ //
174
+ // IT IS PURE ON PURPOSE. The caller reads the entries off disk and hands them
175
+ // in; this module does no IO. That is what makes the decision unit-testable
176
+ // without a filesystem, and it keeps the registry module a registry.
177
+ /**
178
+ * Every registered top-level name — dirs AND files.
179
+ *
180
+ * Derived from the registry above so the census and the registry cannot
181
+ * disagree about what "registered" means.
182
+ */
183
+ export const RUNTIME_SYSTEM_ENTRY_NAMES = new Set(RUNTIME_SYSTEM_ENTRIES.map((entry) => entry.name));
184
+ /**
185
+ * The census: every top-level entry of the runtime root that is neither a
186
+ * session dir nor a registered system entry.
187
+ *
188
+ * Three classes, in this order:
189
+ *
190
+ * 1. a DIRECTORY whose name is a valid session id — legal. A FILE wearing a
191
+ * session-shaped name is NOT legal: only a directory can be a session
192
+ * home, so such a file is a stray.
193
+ * 2. a name in `RUNTIME_SYSTEM_ENTRIES` — legal, whatever its kind. The
194
+ * registry is the authority on which names may sit at the root.
195
+ * 3. everything else — a violation, reported with its name AND its kind.
196
+ */
197
+ export function censusRuntimeRoot(input) {
198
+ if (input.read.status === 'unreadable') {
199
+ return { status: 'undetermined', reason: input.read.reason };
200
+ }
201
+ const isValidSessionId = input.isValidSessionId ?? canonicalIsValidSessionId;
202
+ const violations = input.read.entries
203
+ .filter((entry) => !RUNTIME_SYSTEM_ENTRY_NAMES.has(entry.name))
204
+ .filter((entry) => !(entry.kind === 'dir' && isValidSessionId(entry.name)))
205
+ .map((entry) => ({ name: entry.name, kind: entry.kind }));
206
+ if (violations.length > 0) {
207
+ return { status: 'violations', violations };
208
+ }
209
+ return { status: 'clean', entryCount: input.read.entries.length };
210
+ }
@@ -45,12 +45,28 @@ For final evidence, prefer this visual block:
45
45
  └──────────────────────────────────────────
46
46
  ```
47
47
 
48
- For continuing turns in the same Peaks-Loop workflow, use a compact status header instead of the full banner:
48
+ For continuing turns in the same Peaks-Loop workflow, use a compact status header that **always surfaces both skill layers** — the active skill AND its role tier — plus the live context pressure, even when only the active skill is set:
49
49
 
50
50
  ```markdown
51
- Peaks-Loop Skill: <skill-name> | Peaks-Loop Gate: <current gate> | Next: <one short action>
51
+ Peaks-Loop Skill: <skill-name> | Peaks-Loop Role: <tier> | Peaks-Loop Gate: <current gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>
52
52
  ```
53
53
 
54
+ `<skill-name>` is the value returned by `peaks skill presence --json`'s `data.skill`. The `Role` line surfaces the two-layer Peaks-Loop family so the user always knows which layer is active:
55
+
56
+ - **orchestrator** (1-level) — `peaks-code`, `peaks-content`, `peaks-doctor`, `peaks-issue-fix-orchestrator`, `peaks-solo`, `peaks-ide`, `peaks-sop`, `peaks-audit`, `peaks-race-code`. These are user-facing workflows that own gate transitions.
57
+ - **bee** (1-level sub-role) — `peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, `peaks-txt`, `peaks-final-review`, `peaks-resume`, `peaks-status`, `peaks-test`, `peaks-reviewer`, `peaks-slice-decompose`, `peaks-perf-audit`, `peaks-security-audit`. These are dispatched by an orchestrator and own one stage.
58
+
59
+ **Both layers must always appear in the header regardless of which skill is currently active**, so the user sees the full Peaks-Loop family on every turn. When the active skill is a bee (e.g. `peaks-rd`), the orchestrator is implicit and you MAY add a parenthetical: `peaks-rd (under peaks-code)`. When the active skill is an orchestrator, no parent is implied.
60
+
61
+ `<tier>`, `<current gate>`, `<ratio%>` and `<zone>` are all **machine facts** — copy them verbatim from the same `peaks skill presence --json` read, never estimate them:
62
+
63
+ - `data.role` → the tier above (`orchestrator` / `bee`; `null` for an unknown skill).
64
+ - `data.gate` → the current gate.
65
+ - `data.context.ratioPct` → the context fill, e.g. `42.3%`.
66
+ - `data.context.action` → the zone, one of `none` / `soft-warn` / `auto-fire` / `pre-compact` / `red-line`.
67
+
68
+ **Persistence rule:** The active Peaks-Loop skill name and gate are persisted to the session-scoped presence lease at `.peaks/_runtime/<session-id>/leases/presence-*.json` (the canonical path; the project-level single-slot `active-skill.json` files were removed in 4.0.11). Read the active marker via `peaks skill presence --json` at the start of EVERY response when a Peaks-Loop skill workflow is active — the CLI resolves the lease across the project's session trees, do not read those files directly. If the CLI returns a valid skill, always show the compact header — even if this is the first turn of a new conversation, even after context compaction, and without exception. Only omit the header when the CLI reports no active skill. This ensures users unfamiliar with Claude Code's skill system always see which Peaks-Loop skill is orchestrating their session.
69
+
54
70
  Structure active Peaks-Loop responses around:
55
71
 
56
72
  1. **Peaks-Loop Role** — name the active Peaks-Loop role or role chain, for example PRD → RD → QA → SC.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.17",
3
+ "version": "4.1.19",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -83,6 +83,8 @@
83
83
  "scripts/install-skills-output-styles.mjs",
84
84
  "scripts/install-skills-output-style-default.mjs",
85
85
  "scripts/canonical-store.mjs",
86
+ "scripts/canonical-store-fs.mjs",
87
+ "scripts/canonical-store-marker.mjs",
86
88
  "scripts/canonical-store-link.mjs",
87
89
  "scripts/canonical-store-prune.mjs",
88
90
  "scripts/watch.mjs",
@@ -129,16 +131,15 @@
129
131
  "picomatch": "4.0.7",
130
132
  "yaml": "^2.9.1",
131
133
  "zod": "^4.6.7",
132
- "peaks-loop-internal-runtime": "0.0.57",
133
- "peaks-loop-shared": "0.0.106",
134
- "peaks-loop-shared-channel": "0.0.74",
135
- "peaks-loop-mut": "0.1.71"
134
+ "peaks-loop-internal-runtime": "0.0.59",
135
+ "peaks-loop-shared": "0.0.108",
136
+ "peaks-loop-shared-channel": "0.0.76",
137
+ "peaks-loop-mut": "0.1.73"
136
138
  },
137
139
  "devDependencies": {
138
140
  "@changesets/cli": "2.31.1",
139
141
  "@jridgewell/trace-mapping": "^0.3.31",
140
- "@stryker-mutator/core": "^8.7.1",
141
- "@stryker-mutator/typescript-checker": "^8.7.1",
142
+ "@stryker-mutator/core": "^9.6.1",
142
143
  "@stryker-mutator/vitest-runner": "^9.6.1",
143
144
  "@types/node": "^24.19.1",
144
145
  "@types/picomatch": "4.0.3",
@@ -189,8 +190,8 @@
189
190
  "test:coverage:workflow": "vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
190
191
  "schema:generate": "node scripts/generate-context-schema.mjs",
191
192
  "typecheck": "tsc -p tsconfig.json --noEmit && vitest run --coverage --coverage.include='src/services/workflow/plan-*.ts' tests/unit/services/workflow/",
192
- "mut:run": "peaks mut run --project . --out mut-report.json",
193
- "mut:scan": "peaks mut asserts --in mut-report.json",
193
+ "mut:run": "peaks mut run --project . --test-files tests/unit/cli/commands/verdict-aggregate-missing-evidence.test.ts --mutate src/cli/commands/verdict-aggregate-command.ts src/shared/path-safety.ts src/services/workflow/pipeline-verify-qa-phase.ts src/cli/cli-helpers.ts --input-sig 0000000000000000000000000000000000000000000000000000000000000000 --session-id 00000000000000000000000000000000 --out .peaks/_runtime/00000000000000000000000000000000/mut/mut-report.json --json",
194
+ "mut:scan": "peaks mut asserts --project . --test-files tests/unit/cli/commands/verdict-aggregate-missing-evidence.test.ts --input-sig 0000000000000000000000000000000000000000000000000000000000000000 --session-id 00000000000000000000000000000000 --out .peaks/_runtime/00000000000000000000000000000000/mut/mut-asserts-report.json --json",
194
195
  "audit:prose-ratio": "peaks audit prose-ratio --project .",
195
196
  "dogfood:sediment": "bash scripts/dogfood-sediment-cycle.sh",
196
197
  "lint": "node ./scripts/lint/run-lint.mjs",
@@ -14,7 +14,7 @@
14
14
  "id": {
15
15
  "type": "string",
16
16
  "pattern": "^(?:(?:skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability|build|integration|L3):[A-Za-z0-9][A-Za-z0-9._-]*|skills:[A-Za-z0-9][A-Za-z0-9._-]*(?::[A-Za-z0-9][A-Za-z0-9._-]*)+)$",
17
- "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), skills:<topic>:<ide>:<skill> (canonical-store vs IDE skill-tree parity — a file present on one side and absent on the other; topic store means the canonical store is absent), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency), integration:<name> (third-party integration probe — e.g. gateguard-fact-force PreToolUse hook conflict on .peaks/**)."
17
+ "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), skills:<topic>:<ide>:<skill> (canonical-store vs IDE skill-tree parity — a file present on one side and absent on the other; the store target carries the store-level outcome — in parity, nothing to compare, absent, or unreadable), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version), build:<topic> (build-hygiene checks — dist/source version consistency), integration:<name> (third-party integration probe — e.g. gateguard-fact-force PreToolUse hook conflict on .peaks/**)."
18
18
  },
19
19
  "ok": { "type": "boolean" },
20
20
  "message": { "type": "string", "minLength": 1 }
@@ -0,0 +1,112 @@
1
+ #!/usr/bin/env node
2
+ //
3
+ // The canonical store's FILESYSTEM vocabulary: how a path is identified, and how
4
+ // two trees are compared.
5
+ //
6
+ // Split out of `scripts/canonical-store.mjs` (the b1 file-size campaign): the
7
+ // store's own file was one line under the 300-line cap, and the version-aware
8
+ // staleness decision did not fit beside it. Every line below was moved
9
+ // VERBATIM; only this header and the import block are new.
10
+ //
11
+ // TWO CONCERNS, ONE FILE. They are here together because they are the two
12
+ // questions the store asks about the disk, and both of them are about IDENTITY
13
+ // rather than about policy:
14
+ //
15
+ // 1. IDENTITY — `linkResolvesTo` decides whether two paths are the same
16
+ // directory. It goes through `realpath`, strips the `\\?\` long-path
17
+ // prefix and folds case on Windows, so a trailing separator, a case
18
+ // difference or a long-path spelling cannot make one directory look like
19
+ // two. A path that does not resolve claims nothing.
20
+ //
21
+ // 2. EQUALITY — `contentMatches` is the byte-for-byte comparison of a source
22
+ // and the store's copy. It is what makes the copy idempotent, and it is
23
+ // the SECOND half of the staleness decision: the first half is the
24
+ // version the copy was made from, which lives with the marker.
25
+
26
+ import { lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
27
+ import { join } from 'node:path';
28
+
29
+ export function getPathStats(path) {
30
+ try {
31
+ return lstatSync(path);
32
+ } catch {
33
+ return null;
34
+ }
35
+ }
36
+
37
+ /** `\\?\C:\x` and `\\?\UNC\srv\share` are spellings of a path, not other paths. */
38
+ export function stripLongPathPrefix(value) {
39
+ const uncPrefix = '\\\\?\\UNC\\';
40
+ if (value.startsWith(uncPrefix)) return `\\\\${value.slice(uncPrefix.length)}`;
41
+ const prefix = '\\\\?\\';
42
+ return value.startsWith(prefix) ? value.slice(prefix.length) : value;
43
+ }
44
+
45
+ /**
46
+ * The real, resolved, case-folded identity of a path, or null when it does not
47
+ * resolve (a dangling junction included).
48
+ */
49
+ export function resolveIdentity(path) {
50
+ let resolved;
51
+ try {
52
+ resolved = realpathSync(path);
53
+ } catch {
54
+ return null;
55
+ }
56
+ const normalized = stripLongPathPrefix(resolved);
57
+ return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
58
+ }
59
+
60
+ /**
61
+ * Whether `linkPath` resolves to the same directory as `expectedPath`. Both sides
62
+ * go through `realpath`, so a `\\?\` prefix, a `.` segment or a case difference
63
+ * cannot make one directory look like two.
64
+ */
65
+ export function linkResolvesTo(linkPath, expectedPath) {
66
+ const actual = resolveIdentity(linkPath);
67
+ const expected = resolveIdentity(expectedPath);
68
+ return actual !== null && expected !== null && actual === expected;
69
+ }
70
+
71
+ /** Every file and directory under `rootPath`, as sorted `/`-joined relative paths. */
72
+ function listTreeEntries(rootPath) {
73
+ const entries = [];
74
+ const walk = (dir, prefix) => {
75
+ for (const name of readdirSync(dir).sort()) {
76
+ const relativePath = prefix === '' ? name : `${prefix}/${name}`;
77
+ const stats = lstatSync(join(dir, name));
78
+ if (stats.isDirectory()) {
79
+ entries.push(`${relativePath}/`);
80
+ walk(join(dir, name), relativePath);
81
+ } else if (stats.isFile()) {
82
+ entries.push(relativePath);
83
+ } else {
84
+ throw new Error(
85
+ `Peaks canonical store cannot read ${join(dir, name)}: not a file or directory`
86
+ );
87
+ }
88
+ }
89
+ };
90
+ walk(rootPath, '');
91
+ return entries;
92
+ }
93
+
94
+ /** True when `targetPath` already holds exactly the bytes `sourcePath` holds. */
95
+ export function contentMatches(sourcePath, targetPath) {
96
+ const targetStats = getPathStats(targetPath);
97
+ if (!targetStats || targetStats.isSymbolicLink()) return false;
98
+ if (!targetStats.isDirectory()) {
99
+ return targetStats.isFile() && readFileSync(sourcePath).equals(readFileSync(targetPath));
100
+ }
101
+ const sourceEntries = listTreeEntries(sourcePath);
102
+ const targetEntries = listTreeEntries(targetPath);
103
+ if (sourceEntries.length !== targetEntries.length) return false;
104
+ for (let index = 0; index < sourceEntries.length; index += 1) {
105
+ if (sourceEntries[index] !== targetEntries[index]) return false;
106
+ if (sourceEntries[index].endsWith('/')) continue;
107
+ const from = join(sourcePath, sourceEntries[index]);
108
+ const to = join(targetPath, targetEntries[index]);
109
+ if (!readFileSync(from).equals(readFileSync(to))) return false;
110
+ }
111
+ return true;
112
+ }
@@ -40,9 +40,11 @@ import {
40
40
  import { dirname } from 'node:path';
41
41
 
42
42
  import {
43
+ LEGACY_MARKER_KIND,
43
44
  MANAGED_MARKER_SUFFIX,
44
45
  ensureCanonicalCopy,
45
46
  linkResolvesTo,
47
+ parseLegacyMarker,
46
48
  readManagedTarget,
47
49
  writeManagedMarker
48
50
  } from './canonical-store.mjs';
@@ -50,9 +52,6 @@ import {
50
52
  /** Codes that mean "this host refused to create the link", not "the link is wrong". */
51
53
  const LINK_REFUSED_CODES = new Set(['EPERM', 'EACCES', 'UNKNOWN', 'ENOTSUP', 'EINVAL']);
52
54
 
53
- /** The `kind` each family wrote into its pre-canonical-store JSON sidecar. */
54
- const LEGACY_MARKER_KIND = Object.freeze({ agents: 'agent', 'output-styles': 'output-style' });
55
-
56
55
  /** Scratch prefix for the atomic copy; never a valid asset name (assets start with a letter). */
57
56
  const TEMP_PREFIX = '.peaks-tmp-';
58
57
 
@@ -92,23 +91,6 @@ function provenanceNamesCanonicalPath(recorded, canonicalPath) {
92
91
  return recordedIdentity !== null && recordedIdentity === canonicalIdentity;
93
92
  }
94
93
 
95
- /**
96
- * The sidecar shape written before the canonical store existed: JSON naming the
97
- * package path the file was copied from, plus a content hash. Parsed, never trusted.
98
- */
99
- function parseLegacyMarker(recorded) {
100
- if (typeof recorded !== 'string' || !recorded.startsWith('{')) return null;
101
- try {
102
- const marker = JSON.parse(recorded);
103
- const assetName = marker?.agentName ?? marker?.outputStyleName;
104
- if (marker?.version !== 1 || typeof marker.kind !== 'string') return null;
105
- if (typeof assetName !== 'string' || typeof marker.sourcePath !== 'string') return null;
106
- return { kind: marker.kind, assetName, sourcePath: marker.sourcePath };
107
- } catch {
108
- return null;
109
- }
110
- }
111
-
112
94
  /** A link is ours when it points at the canonical copy, or when it points at nothing. */
113
95
  function isOwnedLink(entryPath, canonicalPath, recorded) {
114
96
  if (linkResolvesTo(entryPath, canonicalPath)) return true;
@@ -262,16 +244,22 @@ function linkOrCopyEntry({ copied, linkPath, current, createFileLink }) {
262
244
  * name: string,
263
245
  * sourcePath: string,
264
246
  * linkPath?: string,
265
- * createFileLink?: (target: string, path: string, type: string) => void
247
+ * createFileLink?: (target: string, path: string, type: string) => void,
248
+ * version?: string,
249
+ * dryRun?: boolean
266
250
  * }} options
267
251
  * `createFileLink` exists so the refused-symlink arm can be MEASURED on a host where
268
252
  * symlinks are permitted (this one). Without it the fallback branch would be
269
253
  * unreachable in the test suite, and an unverified branch is an unverified claim.
270
254
  * Defaults to `fs.symlinkSync`.
255
+ * `version` is the version of the package that owns the asset; it is stamped
256
+ * into the canonical copy's sidecar so a stale copy is knowable. `dryRun`
257
+ * plans the entry and writes nothing.
271
258
  */
272
259
  export function reconcileCanonicalFileEntry(options) {
273
260
  const { kind, name, sourcePath, linkPath } = options;
274
- const copied = ensureCanonicalCopy({ kind, name, sourcePath });
261
+ const { version, dryRun } = options;
262
+ const copied = ensureCanonicalCopy({ kind, name, sourcePath, version, dryRun });
275
263
  const skipped = { ...copied, linkAction: 'skipped', fallback: null };
276
264
  if (copied.action === 'unmanaged') return skipped;
277
265
  if (typeof linkPath !== 'string' || linkPath.length === 0) return skipped;
@@ -286,6 +274,9 @@ export function reconcileCanonicalFileEntry(options) {
286
274
  sourcePath
287
275
  });
288
276
  if (entry.verdict === 'foreign') return skipped;
277
+ if (options.dryRun === true) {
278
+ return { ...copied, linkAction: 'planned', fallback: null };
279
+ }
289
280
  if (entry.verdict === 'copy') return settledCopyResult({ copied, entryPath: linkPath });
290
281
  return linkOrCopyEntry({
291
282
  copied,