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
@@ -0,0 +1,190 @@
1
+ /**
2
+ * Check: the canonical skill store against the installed package
3
+ * (`skills:store-version:store`).
4
+ *
5
+ * THE HOLE THIS CLOSES. `skill-reference-parity` compares the canonical store
6
+ * against the IDE trees — and on a normal install the IDE entry is a LINK INTO
7
+ * the store, so the two sides are the SAME tree and the comparison is always in
8
+ * parity. A store frozen at an old release is perfectly self-consistent, and
9
+ * therefore invisible to that check. The comparison this one makes is the other
10
+ * axis: STORE against PACKAGE. The store's sidecar records the version that
11
+ * produced each copy; the package's `package.json#version` is the version that
12
+ * SHOULD have produced it. A gap between them is staleness nothing else can see.
13
+ *
14
+ * THE PATTERN. It is the `dist-source-version` shape applied to the store: a
15
+ * missing input is INFORMATIONAL, never a red — a machine with no store at all
16
+ * has nothing stale, and saying so is not a finding. A store that cannot be
17
+ * read is a different case: it looks exactly like "no drift", so it is
18
+ * reported.
19
+ *
20
+ * IT ALWAYS EMITS A ROW. A check that stays silent when it finds nothing
21
+ * cannot be told apart from a check that never ran; this one says "clean" out
22
+ * loud, with the version it compared against.
23
+ *
24
+ * READ-ONLY. It lists the store and reads sidecars. It never writes, repairs
25
+ * or deletes; the remedy it names (`peaks skill sync`) is the repair.
26
+ */
27
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
28
+ import { join } from 'node:path';
29
+ import { CLI_VERSION } from 'peaks-loop-shared/version';
30
+ import { z } from 'zod';
31
+ import { isExpectedFsMiss } from '../../../../shared/fs-utils.js';
32
+ import { tryParseJson } from '../../../../shared/json-parse.js';
33
+ import { compareReleaseVersions } from '../../../artifacts/prerequisite-checks.js';
34
+ import { peaksHome } from '../../../sop/sop-paths.js';
35
+ /** The sidecar shape the store writes. A marker in any other shape is legacy. */
36
+ const markerSchema = z.object({
37
+ format: z.literal('peaks-managed-v2'),
38
+ path: z.string().optional(),
39
+ version: z.string().optional()
40
+ });
41
+ /** The version a sidecar records, or null when it records none. */
42
+ export function readMarkerVersion(markerPath) {
43
+ let content;
44
+ try {
45
+ content = readFileSync(markerPath, 'utf8');
46
+ }
47
+ catch (err) {
48
+ // A sidecar that raced away is "no version"; anything else is a real fault
49
+ // and is not swallowed here.
50
+ if (!isExpectedFsMiss(err))
51
+ throw err;
52
+ return null;
53
+ }
54
+ const parsed = tryParseJson(content, markerSchema);
55
+ if (!parsed.ok)
56
+ return null;
57
+ const version = parsed.value.version;
58
+ return typeof version === 'string' && version.length > 0 ? version : null;
59
+ }
60
+ /**
61
+ * Is the recorded version behind the installed one? An UNKNOWN version is
62
+ * behind: a copy that cannot say how old it is cannot be shown to be current,
63
+ * and the installed package is the authority on what should be there.
64
+ */
65
+ function isBehind(recorded, installed) {
66
+ return compareReleaseVersions(recorded ?? '0.0.0', installed) < 0;
67
+ }
68
+ /**
69
+ * The managed entries of one canonical skills store, and the ones behind.
70
+ *
71
+ * `storeRoot` is the canonical SKILLS directory (`<PEAKS_HOME or ~/.peaks>/skills`).
72
+ * An entry the user authored carries no sidecar and is not ours, so it is not
73
+ * counted and never reported.
74
+ */
75
+ export function inspectCanonicalStoreVersions(storeRoot, installedVersion) {
76
+ if (!existsSync(storeRoot)) {
77
+ return {
78
+ storeRoot,
79
+ storePresent: false,
80
+ readable: true,
81
+ managed: 0,
82
+ entries: [],
83
+ stale: [],
84
+ installedVersion
85
+ };
86
+ }
87
+ let names;
88
+ try {
89
+ names = readdirSync(storeRoot).sort();
90
+ }
91
+ catch (err) {
92
+ // A store root that exists but cannot be listed is not "no drift" — it is
93
+ // a store nobody can check, and it is reported rather than passed over.
94
+ if (!isExpectedFsMiss(err))
95
+ throw err;
96
+ return {
97
+ storeRoot,
98
+ storePresent: true,
99
+ readable: false,
100
+ managed: 0,
101
+ entries: [],
102
+ stale: [],
103
+ installedVersion
104
+ };
105
+ }
106
+ const entries = [];
107
+ for (const name of names) {
108
+ if (name.endsWith('.peaks-managed') || name.startsWith('.peaks-tmp-'))
109
+ continue;
110
+ const markerPath = join(storeRoot, `${name}.peaks-managed`);
111
+ if (!existsSync(markerPath))
112
+ continue;
113
+ entries.push({ name, version: readMarkerVersion(markerPath) });
114
+ }
115
+ const stale = entries.filter((entry) => isBehind(entry.version, installedVersion));
116
+ return {
117
+ storeRoot,
118
+ storePresent: true,
119
+ readable: true,
120
+ managed: entries.length,
121
+ entries,
122
+ stale,
123
+ installedVersion
124
+ };
125
+ }
126
+ /** The canonical skills store, exactly where the store writes it. */
127
+ function canonicalSkillsStore() {
128
+ return join(peaksHome(), 'skills');
129
+ }
130
+ /** How an entry's recorded version reads in a message. */
131
+ function describeEntry(entry) {
132
+ return entry.version === null
133
+ ? `${entry.name} (no version recorded)`
134
+ : `${entry.name} (${entry.version})`;
135
+ }
136
+ function toCheck(inspection) {
137
+ const id = 'skills:store-version:store';
138
+ if (!inspection.storePresent) {
139
+ return {
140
+ id,
141
+ ok: true,
142
+ message: `No canonical skill store at ${inspection.storeRoot}; nothing to compare ` +
143
+ '(run `peaks skill sync` to create one)'
144
+ };
145
+ }
146
+ if (!inspection.readable) {
147
+ return {
148
+ id,
149
+ ok: false,
150
+ severity: 'warning',
151
+ message: `The canonical skill store at ${inspection.storeRoot} cannot be read; ` +
152
+ 'it was not compared with the installed package'
153
+ };
154
+ }
155
+ if (inspection.managed === 0) {
156
+ return {
157
+ id,
158
+ ok: true,
159
+ message: `The canonical skill store at ${inspection.storeRoot} holds no peaks-managed entries; ` +
160
+ 'nothing to compare'
161
+ };
162
+ }
163
+ if (inspection.stale.length === 0) {
164
+ return {
165
+ id,
166
+ ok: true,
167
+ message: `The canonical skill store at ${inspection.storeRoot} is current for all ` +
168
+ `${inspection.managed} managed entries against peaks-loop ${inspection.installedVersion}`
169
+ };
170
+ }
171
+ return {
172
+ id,
173
+ ok: false,
174
+ message: `The canonical skill store at ${inspection.storeRoot} is behind the installed ` +
175
+ `peaks-loop ${inspection.installedVersion}: ${inspection.stale.length} of ` +
176
+ `${inspection.managed} managed entries record an older version ` +
177
+ `(${inspection.stale.map(describeEntry).join(', ')}). ` +
178
+ 'Run `peaks skill sync` to refresh the store.'
179
+ };
180
+ }
181
+ function run({ options }) {
182
+ const injected = options.canonicalStoreVersion;
183
+ const storeRoot = injected?.storeRoot ?? canonicalSkillsStore();
184
+ const installedVersion = injected?.installedVersion ?? CLI_VERSION;
185
+ return [toCheck(inspectCanonicalStoreVersions(storeRoot, installedVersion))];
186
+ }
187
+ export const check = {
188
+ name: 'canonical-store-version',
189
+ run
190
+ };
@@ -0,0 +1,37 @@
1
+ /**
2
+ * Check: the runtime root holds only what the registry knows
3
+ * (`L3:l3-runtime-root-census`).
4
+ *
5
+ * WHY A NEW CHECK, AND NOT AN EXTENSION OF `L3:l3-orphan-sessions`.
6
+ *
7
+ * The orphan check answers ONE question: "is this DIRECTORY a valid session
8
+ * id?". It reads directories only, so a stray FILE at the root was invisible
9
+ * to it — 204 of them had accumulated on 2026-10-24 with no product check
10
+ * able to name them. Widening that check to cover files would have made its
11
+ * id lie: an id that says "orphan sessions" must not start reporting stray
12
+ * files.
13
+ *
14
+ * This check answers a different question: "does the runtime root contain
15
+ * anything the registry does not know?". Its id names the ROOT rather than
16
+ * one failure mode, so it covers both an orphan session dir and a stray file
17
+ * — which is exactly what the registry has to be right about.
18
+ *
19
+ * IT READS THE REAL TREE. The drift guard (`tests/unit/workspace/
20
+ * runtime-layout-drift-guard.test.ts`) walks `src/**` and proved the CODE
21
+ * does not write an unregistered child; it never looked at the working tree.
22
+ * This check is the counterpart: it looks at the working tree.
23
+ *
24
+ * FAIL-CLOSED. A runtime root that cannot be read is NOT a clean root. The
25
+ * census reports "could not determine" and this check reports `ok: false`; it
26
+ * is rendered with `severity: 'warning'`, so an unreadable root is visible in
27
+ * the JSON envelope without turning `peaks doctor` red on a project that
28
+ * simply has no peaks workspace yet.
29
+ */
30
+ import type { DoctorCheckPlugin } from '../types.js';
31
+ /**
32
+ * The check id. The `L3:` prefix keeps it in the family that runs last, and
33
+ * the name covers the whole root — an orphan session dir and a stray file are
34
+ * the same finding here: something the registry does not know.
35
+ */
36
+ export declare const RUNTIME_ROOT_CENSUS_CHECK_ID = "L3:l3-runtime-root-census";
37
+ export declare const check: DoctorCheckPlugin;
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Check: the runtime root holds only what the registry knows
3
+ * (`L3:l3-runtime-root-census`).
4
+ *
5
+ * WHY A NEW CHECK, AND NOT AN EXTENSION OF `L3:l3-orphan-sessions`.
6
+ *
7
+ * The orphan check answers ONE question: "is this DIRECTORY a valid session
8
+ * id?". It reads directories only, so a stray FILE at the root was invisible
9
+ * to it — 204 of them had accumulated on 2026-10-24 with no product check
10
+ * able to name them. Widening that check to cover files would have made its
11
+ * id lie: an id that says "orphan sessions" must not start reporting stray
12
+ * files.
13
+ *
14
+ * This check answers a different question: "does the runtime root contain
15
+ * anything the registry does not know?". Its id names the ROOT rather than
16
+ * one failure mode, so it covers both an orphan session dir and a stray file
17
+ * — which is exactly what the registry has to be right about.
18
+ *
19
+ * IT READS THE REAL TREE. The drift guard (`tests/unit/workspace/
20
+ * runtime-layout-drift-guard.test.ts`) walks `src/**` and proved the CODE
21
+ * does not write an unregistered child; it never looked at the working tree.
22
+ * This check is the counterpart: it looks at the working tree.
23
+ *
24
+ * FAIL-CLOSED. A runtime root that cannot be read is NOT a clean root. The
25
+ * census reports "could not determine" and this check reports `ok: false`; it
26
+ * is rendered with `severity: 'warning'`, so an unreadable root is visible in
27
+ * the JSON envelope without turning `peaks doctor` red on a project that
28
+ * simply has no peaks workspace yet.
29
+ */
30
+ import { readdirSync } from 'node:fs';
31
+ import { join } from 'node:path';
32
+ import { getErrorMessage } from 'peaks-loop-shared/result';
33
+ import { censusRuntimeRoot } from '../../../workspace/runtime-layout.js';
34
+ /**
35
+ * The check id. The `L3:` prefix keeps it in the family that runs last, and
36
+ * the name covers the whole root — an orphan session dir and a stray file are
37
+ * the same finding here: something the registry does not know.
38
+ */
39
+ export const RUNTIME_ROOT_CENSUS_CHECK_ID = 'L3:l3-runtime-root-census';
40
+ /** How many offenders the message inlines before eliding the rest. */
41
+ const MAX_NAMES_IN_MESSAGE = 5;
42
+ /**
43
+ * Read the runtime root.
44
+ *
45
+ * A read that fails (missing directory, permission denied) is reported as
46
+ * `unreadable`, NEVER as an empty list: an empty list would read as "clean",
47
+ * which is the one answer an unreadable tree is not entitled to give.
48
+ */
49
+ function readRuntimeRoot(runtimeDir) {
50
+ try {
51
+ const entries = readdirSync(runtimeDir, { withFileTypes: true });
52
+ const mapped = entries.map((entry) => ({
53
+ name: entry.name,
54
+ kind: entry.isDirectory() ? 'dir' : 'file'
55
+ }));
56
+ return { status: 'read', entries: mapped };
57
+ }
58
+ catch (error) {
59
+ return { status: 'unreadable', reason: getErrorMessage(error) };
60
+ }
61
+ }
62
+ /** The offenders, each with its kind, elided past the cut. */
63
+ function describeViolations(violations) {
64
+ const shown = violations.slice(0, MAX_NAMES_IN_MESSAGE);
65
+ const elided = violations.length - shown.length;
66
+ const names = shown.map((violation) => `${violation.name} (${violation.kind})`).join(', ');
67
+ return elided > 0 ? `${names} (+${elided} more)` : names;
68
+ }
69
+ function render(census) {
70
+ if (census.status === 'clean') {
71
+ return {
72
+ id: RUNTIME_ROOT_CENSUS_CHECK_ID,
73
+ ok: true,
74
+ message: `Runtime root census: all ${census.entryCount} top-level entr(y/ies) under .peaks/_runtime/ are registered or session-shaped`
75
+ };
76
+ }
77
+ if (census.status === 'violations') {
78
+ return {
79
+ id: RUNTIME_ROOT_CENSUS_CHECK_ID,
80
+ ok: false,
81
+ severity: 'error',
82
+ message: `Runtime root census: ${census.violations.length} stray entr(y/ies) under .peaks/_runtime/ are not registered: ${describeViolations(census.violations)}. Register the legitimate ones in src/services/workspace/runtime-layout.ts; move the rest under the session dir.`
83
+ };
84
+ }
85
+ return {
86
+ id: RUNTIME_ROOT_CENSUS_CHECK_ID,
87
+ ok: false,
88
+ severity: 'warning',
89
+ message: `Runtime root census could not be determined — the runtime root could not be read (${census.reason}); the tree was NOT verified clean.`
90
+ };
91
+ }
92
+ function run({ resolvedL3Root, isValidSessionId }) {
93
+ const runtimeDir = join(resolvedL3Root, '.peaks/_runtime');
94
+ const read = readRuntimeRoot(runtimeDir);
95
+ return [render(censusRuntimeRoot({ read, isValidSessionId }))];
96
+ }
97
+ export const check = {
98
+ name: 'l3-runtime-root-census',
99
+ run
100
+ };
@@ -11,6 +11,12 @@
11
11
  * repairs, rewrites, or deletes. A mismatch is a warning — a skill missing one
12
12
  * reference still runs — and the message names the LLM-run repair.
13
13
  *
14
+ * IT ALWAYS EMITS A ROW. A check that stays silent when it finds nothing
15
+ * cannot be told apart from one that never ran, so this one says "clean" out
16
+ * loud: `skills:reference-parity:store` with `ok: true` when every tree is in
17
+ * parity, or when there was nothing to compare. The SAME id goes red when
18
+ * the store could not be compared at all (absent or unreadable).
19
+ *
14
20
  * The canonical store is the anchor: only skills present under
15
21
  * `<PEAKS_HOME or ~/.peaks>/skills` are compared, so a user-authored skill that
16
22
  * exists only in an IDE root is not reported as drift.
@@ -27,9 +33,11 @@ import type { DoctorCheck, DoctorCheckPlugin } from '../types.js';
27
33
  * directories to compare against it. Roots that do not exist are skipped, so
28
34
  * the wrapper may pass every adapter that declares `skillInstall`.
29
35
  *
30
- * Identical trees emit no check at all: the absence of a parity finding is the
31
- * pass, which keeps the doctor report exactly as long as its findings. A store
32
- * that exists but cannot be read is a warning, never silence.
36
+ * IT ALWAYS EMITS A ROW. The store-level row `skills:reference-parity:store`
37
+ * has FOUR outcomes: GREEN in parity (the comparison ran and every tree
38
+ * matched), GREEN with nothing to compare (no IDE skill root exists), RED
39
+ * when the store is absent, and RED when the store is not a readable
40
+ * directory. A diverging tree reports its own `<ide>:<skill>` row instead.
33
41
  */
34
42
  export declare function compareSkillReferenceParity(canonicalRoot: string, ideRoots: ReadonlyArray<{
35
43
  ide: string;
@@ -11,6 +11,12 @@
11
11
  * repairs, rewrites, or deletes. A mismatch is a warning — a skill missing one
12
12
  * reference still runs — and the message names the LLM-run repair.
13
13
  *
14
+ * IT ALWAYS EMITS A ROW. A check that stays silent when it finds nothing
15
+ * cannot be told apart from one that never ran, so this one says "clean" out
16
+ * loud: `skills:reference-parity:store` with `ok: true` when every tree is in
17
+ * parity, or when there was nothing to compare. The SAME id goes red when
18
+ * the store could not be compared at all (absent or unreadable).
19
+ *
14
20
  * The canonical store is the anchor: only skills present under
15
21
  * `<PEAKS_HOME or ~/.peaks>/skills` are compared, so a user-authored skill that
16
22
  * exists only in an IDE root is not reported as drift.
@@ -167,52 +173,65 @@ function toCheck(issue, canonicalRoot) {
167
173
  message: `${parts.join('; ')}. ${REPAIR_HINT}.`
168
174
  };
169
175
  }
176
+ /** The store-level RED row: one id and one severity for both failure arms. */
177
+ function storeWarningRow(message) {
178
+ return { id: 'skills:reference-parity:store', ok: false, severity: 'warning', message };
179
+ }
170
180
  /**
171
- * Pure comparator. `canonicalRoot` is the canonical skills store
172
- * (`<PEAKS_HOME or ~/.peaks>/skills`); `ideRoots` are the IDE-side skills
173
- * directories to compare against it. Roots that do not exist are skipped, so
174
- * the wrapper may pass every adapter that declares `skillInstall`.
175
- *
176
- * Identical trees emit no check at all: the absence of a parity finding is the
177
- * pass, which keeps the doctor report exactly as long as its findings. A store
178
- * that exists but cannot be read is a warning, never silence.
181
+ * The store-level RED row when the canonical store cannot be compared, or null
182
+ * when it can: both failure arms share one id and one `severity: 'warning'`.
179
183
  */
180
- export function compareSkillReferenceParity(canonicalRoot, ideRoots) {
184
+ function storeFailureRow(canonicalRoot) {
181
185
  if (!existsSync(canonicalRoot)) {
182
- return [
183
- {
184
- id: 'skills:reference-parity:store',
185
- ok: true,
186
- message: `Canonical skill store not found at ${canonicalRoot}; nothing to compare`
187
- }
188
- ];
186
+ return storeWarningRow(`Canonical skill store not found at ${canonicalRoot}; IDE skill roots were not compared`);
189
187
  }
190
188
  const problem = storeProblem(canonicalRoot);
191
- if (problem !== null) {
192
- return [
193
- {
194
- id: 'skills:reference-parity:store',
195
- ok: false,
196
- severity: 'warning',
197
- message: `Canonical skill store at ${canonicalRoot} ${problem}; IDE skill roots were not compared`
198
- }
199
- ];
200
- }
189
+ if (problem === null)
190
+ return null;
191
+ return storeWarningRow(`Canonical skill store at ${canonicalRoot} ${problem}; IDE skill roots were not compared`);
192
+ }
193
+ /** The divergence rows for every IDE skill root, or the GREEN store row. */
194
+ function compareIdeSkillTrees(canonicalRoot, ideRoots) {
201
195
  const canonicalSkills = new Map();
202
196
  for (const skill of listSkillNames(canonicalRoot)) {
203
197
  canonicalSkills.set(skill, listRelativeFiles(join(canonicalRoot, skill)));
204
198
  }
205
199
  const checks = [];
200
+ let compared = 0;
206
201
  for (const { ide, skillsDir } of ideRoots) {
207
202
  if (!existsSync(skillsDir))
208
203
  continue;
209
- for (const skill of [...canonicalSkills.keys()].sort()) {
210
- const issue = diffSkillTrees(ide, skill, canonicalSkills.get(skill) ?? new Set(), listRelativeFiles(join(skillsDir, skill)));
204
+ for (const [skill, files] of canonicalSkills) {
205
+ compared += 1;
206
+ const issue = diffSkillTrees(ide, skill, files, listRelativeFiles(join(skillsDir, skill)));
211
207
  if (issue !== null)
212
208
  checks.push(toCheck(issue, canonicalRoot));
213
209
  }
214
210
  }
215
- return checks;
211
+ if (checks.length > 0)
212
+ return checks;
213
+ const clean = compared === 0
214
+ ? `No skill tree to compare with the canonical store at ${canonicalRoot}; nothing to compare`
215
+ : `Every IDE skill tree is in parity with the canonical store at ${canonicalRoot} (${compared} skill trees compared)`;
216
+ return [{ id: 'skills:reference-parity:store', ok: true, message: clean }];
217
+ }
218
+ /**
219
+ * Pure comparator. `canonicalRoot` is the canonical skills store
220
+ * (`<PEAKS_HOME or ~/.peaks>/skills`); `ideRoots` are the IDE-side skills
221
+ * directories to compare against it. Roots that do not exist are skipped, so
222
+ * the wrapper may pass every adapter that declares `skillInstall`.
223
+ *
224
+ * IT ALWAYS EMITS A ROW. The store-level row `skills:reference-parity:store`
225
+ * has FOUR outcomes: GREEN in parity (the comparison ran and every tree
226
+ * matched), GREEN with nothing to compare (no IDE skill root exists), RED
227
+ * when the store is absent, and RED when the store is not a readable
228
+ * directory. A diverging tree reports its own `<ide>:<skill>` row instead.
229
+ */
230
+ export function compareSkillReferenceParity(canonicalRoot, ideRoots) {
231
+ const failure = storeFailureRow(canonicalRoot);
232
+ if (failure !== null)
233
+ return [failure];
234
+ return compareIdeSkillTrees(canonicalRoot, ideRoots);
216
235
  }
217
236
  function canonicalSkillsStore() {
218
237
  const home = process.env.PEAKS_HOME?.trim();
@@ -35,6 +35,7 @@ import { check as skillParse } from './checks/skill-parse.js';
35
35
  import { check as skillRunbook } from './checks/skill-runbook.js';
36
36
  import { check as skillApplyNote } from './checks/skill-apply-note.js';
37
37
  import { check as skillReferenceParity } from './checks/skill-reference-parity.js';
38
+ import { check as canonicalStoreVersion } from './checks/canonical-store-version.js';
38
39
  import { check as schemaValidity } from './checks/schema-validity.js';
39
40
  import { check as userConfig } from './checks/user-config.js';
40
41
  import { check as skillPresence } from './checks/skill-presence.js';
@@ -52,6 +53,7 @@ import { check as eccHooksSchemaDrift } from './checks/ecc-hooks-schema-drift.js
52
53
  import { check as checkIdSchema } from './checks/check-id-schema.js';
53
54
  import { check as backcompatAcceptance } from './checks/backcompat-acceptance.js';
54
55
  import { check as l3OrphanSessions } from './checks/l3-orphan-sessions.js';
56
+ import { check as l3RuntimeRootCensus } from './checks/l3-runtime-root-census.js';
55
57
  import { check as l3MemoryHealth } from './checks/l3-memory-health.js';
56
58
  /**
57
59
  * Ordered list of doctor check plugins. The order mirrors the legacy
@@ -66,6 +68,7 @@ export const PLUGINS = [
66
68
  skillRunbook, // id prefix "skill-runbook:"
67
69
  skillApplyNote, // id prefix "skill-apply-note:"
68
70
  skillReferenceParity, // ids "skills:reference-parity:<ide>:<skill>" + "skills:reference-parity:store"
71
+ canonicalStoreVersion, // id "skills:store-version:store" — the store against the installed package
69
72
  schemaValidity, // id prefix "schema:"
70
73
  userConfig, // id "config:user"
71
74
  skillPresence, // ids "skill-presence:current" + "skill-presence:freshness"
@@ -83,5 +86,6 @@ export const PLUGINS = [
83
86
  backcompatAcceptance, // id "config:backcompat-acceptance"
84
87
  checkIdSchema, // id "doctor-self:check-id-pattern"
85
88
  l3OrphanSessions, // id "L3:l3-orphan-sessions"
89
+ l3RuntimeRootCensus, // id "L3:l3-runtime-root-census"
86
90
  l3MemoryHealth // id "L3:l3-memory-health"
87
91
  ];
@@ -120,6 +120,18 @@ export type DoctorOptions = {
120
120
  skillsDir: string;
121
121
  }>;
122
122
  };
123
+ /**
124
+ * Injected roots/versions for the `skills:store-version` check. When omitted
125
+ * the check binds `$PEAKS_HOME`/`~/.peaks` and the installed release. Tests
126
+ * pass a temp store and a temp version here, so no test reads the real home
127
+ * directory or the real release.
128
+ */
129
+ canonicalStoreVersion?: {
130
+ /** The canonical SKILLS directory (`<root>/skills`). */
131
+ readonly storeRoot: string;
132
+ /** The version to compare the store against. */
133
+ readonly installedVersion: string;
134
+ };
123
135
  /**
124
136
  * root for the L3:l3-memory-health check (defaults to
125
137
  * `findProjectRoot(process.cwd())`). Tests use this to point the
@@ -30,10 +30,17 @@ export declare function readToolCallCwd(payload: Readonly<Record<string, unknown
30
30
  * The rule ASSUMES the tool call runs inside the named project, which is
31
31
  * where the gate is installed. When it does not, the payload `cwd` is
32
32
  * rejected and the path is read against the gate's own working directory
33
- * instead — a different tree — and the error is one-directional: a file that
34
- * lies outside every family can be denied. It is never the other way round,
35
- * and that is the trade the gate makes everywhere else: a wrongly allowed
36
- * edit is a hole, a wrongly refused one is an inconvenience.
33
+ * instead — a different tree.
34
+ *
35
+ * While the base the path is read against IS the call's own directory, the
36
+ * error stays one-directional: a file that lies outside every family can be
37
+ * denied, and never the other way round — a wrongly allowed edit is a hole,
38
+ * a wrongly refused one is an inconvenience. That direction is NOT a general
39
+ * property of the fallback: when the base is the gate's own working
40
+ * directory and the call runs somewhere else, the call's relative path is
41
+ * read against a tree that is not the call's, and a file that really is
42
+ * inside a hard-blocked family can be ALLOWED.
43
+ * Measured 2026-10-23; backlog §19.3.
37
44
  *
38
45
  * The fallback is the gate process's own working directory: that is where the
39
46
  * hook runs, and in the normal invocation it IS the tool call's directory.
@@ -88,10 +88,17 @@ function isInsideProject(root, dir) {
88
88
  * The rule ASSUMES the tool call runs inside the named project, which is
89
89
  * where the gate is installed. When it does not, the payload `cwd` is
90
90
  * rejected and the path is read against the gate's own working directory
91
- * instead — a different tree — and the error is one-directional: a file that
92
- * lies outside every family can be denied. It is never the other way round,
93
- * and that is the trade the gate makes everywhere else: a wrongly allowed
94
- * edit is a hole, a wrongly refused one is an inconvenience.
91
+ * instead — a different tree.
92
+ *
93
+ * While the base the path is read against IS the call's own directory, the
94
+ * error stays one-directional: a file that lies outside every family can be
95
+ * denied, and never the other way round — a wrongly allowed edit is a hole,
96
+ * a wrongly refused one is an inconvenience. That direction is NOT a general
97
+ * property of the fallback: when the base is the gate's own working
98
+ * directory and the call runs somewhere else, the call's relative path is
99
+ * read against a tree that is not the call's, and a file that really is
100
+ * inside a hard-blocked family can be ALLOWED.
101
+ * Measured 2026-10-23; backlog §19.3.
95
102
  *
96
103
  * The fallback is the gate process's own working directory: that is where the
97
104
  * hook runs, and in the normal invocation it IS the tool call's directory.
@@ -13,10 +13,10 @@
13
13
  * (.peaks/**, .peaks/_runtime/**, skills/**, docs/**, *.md)
14
14
  * → allow (silent exit 0).
15
15
  *
16
- * Pure function. The shell-script sibling
17
- * (`pre-tool-code-gate.sh`) is the canonical source for the same
18
- * logic, usable from any non-Node harness. Both share the same
19
- * hard-blocked + allow-listed path families.
16
+ * Pure function. This module is the ONE implementation of the rule: the
17
+ * shell-script sibling (`pre-tool-code-gate.sh`) is a thin wrapper that
18
+ * execs the CLI built on it, and its own no-CLI fallback carries a
19
+ * narrower copy of the same families.
20
20
  */
21
21
  import { normalizeGatePath, type GateRoots } from './gate-path-normalize.js';
22
22
  export { normalizeGatePath };
@@ -13,10 +13,10 @@
13
13
  * (.peaks/**, .peaks/_runtime/**, skills/**, docs/**, *.md)
14
14
  * → allow (silent exit 0).
15
15
  *
16
- * Pure function. The shell-script sibling
17
- * (`pre-tool-code-gate.sh`) is the canonical source for the same
18
- * logic, usable from any non-Node harness. Both share the same
19
- * hard-blocked + allow-listed path families.
16
+ * Pure function. This module is the ONE implementation of the rule: the
17
+ * shell-script sibling (`pre-tool-code-gate.sh`) is a thin wrapper that
18
+ * execs the CLI built on it, and its own no-CLI fallback carries a
19
+ * narrower copy of the same families.
20
20
  */
21
21
  import { canonicalGatePath, normalizeGatePath, rootPair } from './gate-path-normalize.js';
22
22
  export { normalizeGatePath };
@@ -5,6 +5,9 @@ export type DetectPresenceMarkerInput = {
5
5
  export type DetectPresenceMarkerResult = {
6
6
  active: boolean;
7
7
  skill?: string;
8
+ /** The gate the active presence is parked on — the machine fact behind
9
+ * the status header's middle cell. Absent when the lease carries none. */
10
+ gate?: string;
8
11
  markerFound: boolean;
9
12
  warning?: string;
10
13
  };