peaks-loop 4.1.16 → 4.1.18

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 (48) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +193 -0
  3. package/dist/cli/commands/code-auto-compact-command.js +46 -23
  4. package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
  5. package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
  6. package/dist/cli/commands/code-gate-command.d.ts +4 -4
  7. package/dist/cli/commands/code-gate-command.js +4 -4
  8. package/dist/cli/commands/core/skill-registry-commands.js +32 -0
  9. package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
  10. package/dist/cli/commands/core/skill-store-report.js +79 -0
  11. package/dist/cli/commands/dispatch-prompt-composition.js +7 -2
  12. package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
  13. package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
  14. package/dist/cli/commands/hooks-commands.js +36 -7
  15. package/dist/cli/commands/hooks-uninstall-command.js +5 -5
  16. package/dist/services/code/auto-compact-orchestrator.js +7 -5
  17. package/dist/services/code/auto-compact-run-types.d.ts +8 -4
  18. package/dist/services/dispatch/dispatch-ledger-reader.d.ts +13 -0
  19. package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
  20. package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
  21. package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
  22. package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
  23. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  24. package/dist/services/hooks/gate-path-normalize.d.ts +37 -0
  25. package/dist/services/hooks/gate-path-normalize.js +74 -4
  26. package/dist/services/hooks/hook-payload-cwd.js +25 -9
  27. package/dist/services/hooks/pre-tool-code-gate.d.ts +24 -4
  28. package/dist/services/hooks/pre-tool-code-gate.js +72 -22
  29. package/dist/services/session/getSessionDir.d.ts +13 -0
  30. package/dist/services/session/getSessionDir.js +7 -1
  31. package/dist/services/skills/hooks-settings-types.d.ts +17 -21
  32. package/dist/services/skills/sync-service-support.d.ts +27 -0
  33. package/dist/services/skills/sync-service.js +1 -0
  34. package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
  35. package/dist/services/workflow/workflow-inflight-probe.js +163 -75
  36. package/package.json +7 -5
  37. package/scripts/canonical-store-fs.mjs +112 -0
  38. package/scripts/canonical-store-link.mjs +13 -22
  39. package/scripts/canonical-store-marker.mjs +241 -0
  40. package/scripts/canonical-store.mjs +119 -141
  41. package/scripts/install-skills-bundles.mjs +56 -13
  42. package/scripts/install-skills-fs.mjs +73 -0
  43. package/scripts/install-skills-output-styles.mjs +8 -2
  44. package/scripts/install-skills-report.mjs +19 -0
  45. package/scripts/install-skills.mjs +9 -0
  46. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +20 -1
  47. package/skills/peaks-code/SKILL.md +1 -1
  48. package/skills/peaks-race-code/SKILL.md +6 -3
@@ -14,8 +14,14 @@ import { join } from 'node:path';
14
14
  import { reconcileCanonicalEntry } from './canonical-store.mjs';
15
15
  import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
16
16
  import { pruneBundledEntries } from './canonical-store-prune.mjs';
17
- import { createInstallResult } from './install-skills-report.mjs';
18
- import { createInstallRootValidator, resolvePackageRoot } from './install-skills-fs.mjs';
17
+ import { collectStoreOnlyEntries } from './canonical-store-report.mjs';
18
+ import { createInstallResult, finalizeInstallResult } from './install-skills-report.mjs';
19
+ import {
20
+ createInstallRootValidator,
21
+ prepareInstallRoot,
22
+ readPackageVersion,
23
+ resolvePackageRoot
24
+ } from './install-skills-fs.mjs';
19
25
  import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
20
26
 
21
27
  /**
@@ -71,6 +77,11 @@ function isSkillSource(sourcePath) {
71
77
  export function installBundledSkills(options = {}) {
72
78
  const packageRoot = resolvePackageRoot(options);
73
79
  const skillsRoot = join(packageRoot, 'skills');
80
+ // The version of the package that owns `skills/<name>`. It is stamped into
81
+ // every canonical copy's sidecar, and it is what makes a store frozen at an
82
+ // old release KNOWABLY stale instead of merely different.
83
+ const packageVersion = readPackageVersion(packageRoot);
84
+ const dryRun = options.dryRun === true;
74
85
 
75
86
  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
76
87
  return createInstallResult();
@@ -88,8 +99,14 @@ export function installBundledSkills(options = {}) {
88
99
 
89
100
  const installed = [];
90
101
  const skipped = [];
91
- mkdirSync(targetRoot, { recursive: true });
92
- const validateSkillsRoot = createInstallRootValidator(targetRoot, 'Peaks skills');
102
+ // What the STORE holds per entry, as found — `current`, `stale`, `unmanaged`,
103
+ // `retired` or `absent`. It is the report the install used to leave in a return
104
+ // value nobody read, and it is what tells a caller (and a human) which entries are
105
+ // behind the installed release before anything is repaired.
106
+ const entries = [];
107
+ // The install root: a real run creates it and guards it, a dry run does neither —
108
+ // a dry run that leaves a directory behind is not a dry run.
109
+ const validateSkillsRoot = prepareInstallRoot(targetRoot, 'Peaks skills', dryRun);
93
110
 
94
111
  const candidates = collectSkillCandidates(skillsRoot);
95
112
 
@@ -111,10 +128,19 @@ export function installBundledSkills(options = {}) {
111
128
  kind: 'skills',
112
129
  name: skillName,
113
130
  sourcePath,
114
- linkPath: targetPath
131
+ linkPath: targetPath,
132
+ version: packageVersion,
133
+ dryRun
115
134
  });
116
135
  validateSkillsRoot();
117
136
 
137
+ entries.push({
138
+ name: skillName,
139
+ state: reconciled.state,
140
+ action: reconciled.action,
141
+ version: reconciled.version ?? null,
142
+ reason: reconciled.reason ?? null
143
+ });
118
144
  if (reconciled.linkAction === 'skipped') {
119
145
  skipped.push(skillName);
120
146
  continue;
@@ -122,17 +148,32 @@ export function installBundledSkills(options = {}) {
122
148
  installed.push(skillName);
123
149
  }
124
150
 
151
+ // The store holds entries this package does NOT ship: the user's own skills, and
152
+ // the ones a retired release left behind. The report covers the STORE, not only
153
+ // the package's slice of it — a user's skill that the report never mentions is a
154
+ // skill the user cannot see is safe.
155
+ entries.push(
156
+ ...collectStoreOnlyEntries({
157
+ kind: 'skills',
158
+ knownNames: candidates.map((candidate) => candidate.skillName),
159
+ dryRun
160
+ })
161
+ );
162
+
125
163
  // Slice 3 — PRUNE. The loop above only ever ADDS. A skill removed from the
126
164
  // package left its canonical copy, every IDE link and every sidecar on the
127
165
  // user's machine forever, because nothing walked the DESTINATIONS. This does,
128
- // and deletes only what `isManagedEntry` proves is ours.
129
- const { pruned } = pruneBundledEntries({
130
- kind: 'skills',
131
- keepNames: candidates.map((candidate) => candidate.skillName),
132
- linkDirs: [targetRoot]
133
- });
166
+ // and deletes only what `isManagedEntry` proves is ours. A dry run deletes
167
+ // nothing — a plan that removes files is not a plan.
168
+ const pruned = dryRun
169
+ ? []
170
+ : pruneBundledEntries({
171
+ kind: 'skills',
172
+ keepNames: candidates.map((candidate) => candidate.skillName),
173
+ linkDirs: [targetRoot]
174
+ }).pruned;
134
175
 
135
- return { installed, skipped, pruned };
176
+ return finalizeInstallResult({ installed, skipped, pruned, entries }, dryRun);
136
177
  }
137
178
 
138
179
  /**
@@ -161,6 +202,7 @@ export function installBundledSkills(options = {}) {
161
202
  export function installBundledAgents(options = {}) {
162
203
  const packageRoot = resolvePackageRoot(options);
163
204
  const agentsRoot = join(packageRoot, 'agents');
205
+ const packageVersion = readPackageVersion(packageRoot);
164
206
 
165
207
  // Per-IDE env-var override (claude-code only today): PEAKS_CLAUDE_AGENTS_DIR.
166
208
  // Universal escape hatch: PEAKS_SKIP_AGENT_INSTALL=1 (parallel to
@@ -207,7 +249,8 @@ export function installBundledAgents(options = {}) {
207
249
  name: agentFileName,
208
250
  sourcePath,
209
251
  linkPath: join(targetRoot, agentFileName),
210
- createFileLink: options.createFileLink
252
+ createFileLink: options.createFileLink,
253
+ version: packageVersion
211
254
  });
212
255
  validateAgentsRoot();
213
256
 
@@ -15,6 +15,7 @@ import {
15
15
  fchmodSync,
16
16
  fstatSync,
17
17
  lstatSync,
18
+ mkdirSync,
18
19
  openSync,
19
20
  readFileSync,
20
21
  renameSync,
@@ -86,10 +87,82 @@ export function createInstallRootValidator(targetRoot, label) {
86
87
  };
87
88
  }
88
89
 
90
+ /**
91
+ * The validator a DRY RUN uses.
92
+ *
93
+ * WHY IT IS NOT THE OTHER ONE. `createInstallRootValidator` exists to catch the
94
+ * install root being swapped under a write — it stats the root before the write
95
+ * and compares after. A dry run writes nothing, so there is no write to catch, and
96
+ * the root may not even EXIST: a dry run must not create it either, because a
97
+ * dry run that leaves a directory behind is not a dry run.
98
+ */
99
+ export function createDryRunRootValidator() {
100
+ return () => undefined;
101
+ }
102
+
103
+ /**
104
+ * Prepare the install root for a run, and hand back the validator that guards it.
105
+ *
106
+ * A real run creates the directory and then guards it. A dry run does neither: it
107
+ * creates no directory and guards nothing, because there is no write to guard.
108
+ *
109
+ * WHY IT IS ONE FUNCTION. The choice belongs to the CALLER'S ONE CALL SITE: the
110
+ * install loop is already at the complexity the lint allows, and a second
111
+ * decision here would push it over for a difference that is exactly one branch
112
+ * wide.
113
+ *
114
+ * @param {string} targetRoot
115
+ * @param {string} label
116
+ * @param {boolean} dryRun
117
+ */
118
+ export function prepareInstallRoot(targetRoot, label, dryRun) {
119
+ if (dryRun === true) {
120
+ return createDryRunRootValidator();
121
+ }
122
+ mkdirSync(targetRoot, { recursive: true });
123
+ return createInstallRootValidator(targetRoot, label);
124
+ }
125
+
89
126
  export function resolvePackageRoot(options = {}) {
90
127
  return resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
91
128
  }
92
129
 
130
+ /**
131
+ * The version of the package that owns the bundled assets — the one number the
132
+ * canonical store's staleness decision compares against.
133
+ *
134
+ * WHERE IT IS READ. `package.json#version` of the package root, and the package
135
+ * root is wherever THIS script lives: `<install>/scripts/install-skills.mjs`
136
+ * gives `<install>`, which is the globally installed `peaks-loop` package on a
137
+ * user's machine and the repository checkout in a development tree. Both are
138
+ * the package that owns `skills/<name>`, so the same comparison is meaningful
139
+ * in both cases — the difference is only who moves the version.
140
+ *
141
+ * A package.json that is missing, unreadable or versionless answers null, and
142
+ * null means "no version to compare against" — the caller then decides by the
143
+ * bytes alone, which is the behaviour that predates the version stamp.
144
+ *
145
+ * @param {string} packageRoot
146
+ * @returns {string | null}
147
+ */
148
+ export function readPackageVersion(packageRoot) {
149
+ const packageJsonPath = join(packageRoot, 'package.json');
150
+ if (!existsSync(packageJsonPath)) return null;
151
+ let parsed;
152
+ try {
153
+ parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
154
+ } catch (error) {
155
+ const message = error instanceof Error ? error.message : String(error);
156
+ process.stderr.write(
157
+ `Peaks install: ${packageJsonPath} could not be read as JSON (${message}); ` +
158
+ 'the canonical store cannot compare versions and will decide by content alone.\n'
159
+ );
160
+ return null;
161
+ }
162
+ const version = parsed?.version;
163
+ return typeof version === 'string' && version.length > 0 ? version : null;
164
+ }
165
+
93
166
  export function isInsidePath(childPath, parentPath) {
94
167
  const relativePath = relative(parentPath, childPath);
95
168
  return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
@@ -13,7 +13,11 @@ import { join } from 'node:path';
13
13
 
14
14
  import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
15
15
  import { pruneBundledEntries } from './canonical-store-prune.mjs';
16
- import { createInstallRootValidator, resolvePackageRoot } from './install-skills-fs.mjs';
16
+ import {
17
+ createInstallRootValidator,
18
+ readPackageVersion,
19
+ resolvePackageRoot
20
+ } from './install-skills-fs.mjs';
17
21
  import { createInstallResult } from './install-skills-report.mjs';
18
22
  import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
19
23
 
@@ -54,6 +58,7 @@ import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
54
58
  export function installBundledOutputStyles(options = {}) {
55
59
  const packageRoot = resolvePackageRoot(options);
56
60
  const outputStylesRoot = join(packageRoot, 'output-styles');
61
+ const packageVersion = readPackageVersion(packageRoot);
57
62
 
58
63
  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(outputStylesRoot)) {
59
64
  return createInstallResult();
@@ -94,7 +99,8 @@ export function installBundledOutputStyles(options = {}) {
94
99
  name: outputStyleName,
95
100
  sourcePath,
96
101
  linkPath: join(targetRoot, outputStyleName),
97
- createFileLink: options.createFileLink
102
+ createFileLink: options.createFileLink,
103
+ version: packageVersion
98
104
  });
99
105
  validateOutputStylesRoot();
100
106
 
@@ -12,6 +12,25 @@ export function createInstallResult() {
12
12
  return { installed: [], skipped: [], pruned: [], fallbacks: [] };
13
13
  }
14
14
 
15
+ /**
16
+ * The result a run reports, with the dry run's own rule applied.
17
+ *
18
+ * WHY. A dry run installs nothing, so it reports nothing installed: a plan that
19
+ * says "184 skill symlinks" describes a run that did not happen. The plan itself
20
+ * is not lost — every entry carries the action it would take (`planned`) — and
21
+ * this is where the installed list is emptied, so the ONE place that decides what
22
+ * a dry run claims does it.
23
+ *
24
+ * @param {{ installed: string[], skipped: string[], pruned?: string[], entries?: unknown[] }} result
25
+ * @param {boolean} dryRun
26
+ */
27
+ export function finalizeInstallResult(result, dryRun) {
28
+ if (dryRun === true) {
29
+ return { ...result, installed: [] };
30
+ }
31
+ return result;
32
+ }
33
+
15
34
  /**
16
35
  * A fallback is not a failure — but it must never LOOK like a plain success. The
17
36
  * entry is a real copy instead of a link, and the postinstall says so, naming each
@@ -192,6 +192,15 @@ if (
192
192
  `(${totalInstalled} total symlinks)\n`
193
193
  );
194
194
  }
195
+ // The skills' own `skipped` list was the one bucket the postinstall never
196
+ // printed: an entry that was left alone — a store copy peaks-loop does not
197
+ // own, a second live install — looked exactly like a successful install
198
+ // from the outside. The agents and output styles already say so; the
199
+ // skills now do too.
200
+ reportLeftAlone(
201
+ 'skills',
202
+ perPlatform.flatMap((platform) => platform.skipped ?? [])
203
+ );
195
204
  const outputStylesResult = installBundledOutputStyles();
196
205
  // Slice 7/7 — bundled agents (Claude Code sub-agent prompts) ship
197
206
  // under `agents/*.md` in the peaks-loop tarball and are auto-installed
@@ -185,4 +185,23 @@ Run `node scripts/migrate-to-bdd.mjs --dry-run <file>` before writing new tests
185
185
  - description: must contain `/(\bwhen\b|\bshould\b)/`
186
186
  - first 3 body comments: must match `/^\s*\/\/\s*given\s*:/`, `/^\s*\/\/\s*when\s*:/`, `/^\s*\/\/\s*then\s*:/`
187
187
 
188
- If your tests fail peaks-qa's `bdd-test-style-verifier` (see Slice B), the slice will be returned-to-rd. Fix the violations, do NOT bypass the check.
188
+ If your tests fail peaks-qa's `bdd-test-style-verifier` (see Slice B), the slice will be returned-to-rd. Fix the violations, do NOT bypass the check.
189
+
190
+ ---
191
+
192
+ ## Scratch path (absolute — never a cwd-relative redirect)
193
+
194
+ The dispatch CLI machine-injects a scratch-path block into every sub-agent prompt, naming the ABSOLUTE scratch directory for that dispatch: `<projectRoot>/.peaks/_runtime/<sessionId>/<role>/scratch/`. The rule it carries is one line: **never redirect to a cwd-relative path**. The two paths that do NOT pass through that composer — `--from-dag` and `--mode detached` — carry no scratch block, so a caller using either must state the rule itself.
195
+
196
+ **Why it is a block and not a line in a brief.** The rule used to live only in the orchestrator's brief, which is exactly as strong as the orchestrator's memory at 3am. Measured 2026-10-02, five zero-byte `*.err` captures — the `2> name.err` of five per-file test runs — landed at the repository root and were committed; `git status` stayed clean because the files were tracked, and neither the file-size census nor eslint reads a `.err`.
197
+
198
+ **Two copies, one pin.** The block below is the canonical text; `src/cli/commands/dispatch-scratch-path-block.ts` holds its machine copy (`SCRATCH_PATH_BLOCK_TEMPLATE`) and `tests/unit/cli/commands/dispatch-scratch-path-block.test.ts` asserts the two are byte-equal, so neither can drift. The path differs for every dispatch, so the placeholder is what this file carries.
199
+
200
+ ```
201
+ Scratch path (REQUIRED — absolute path; never a cwd-relative redirect)
202
+
203
+ Write every temporary file for this task under this ABSOLUTE path:
204
+ {{scratchDir}}
205
+
206
+ Never redirect to a path that depends on the working directory — `2> out.err`, `> run.log`, `./scratch/`. A cwd-relative redirect writes wherever the task happens to `cd`: measured 2026-10-02, five zero-byte `*.err` captures landed at the repository root and were committed, and `git status` stayed clean because the files were tracked. Use the absolute path above; it lives under the session's runtime dir, which is gitignored, so nothing written there can be committed by accident.
207
+ ```
@@ -114,7 +114,7 @@ Two-layer enforcement — do NOT try to bypass either:
114
114
  ```
115
115
  For source-code changes (mentioning `src/`, `tests/unit/`, `tests/integration/`, `config/`, `bin/`, `scripts/`) the probe MUST return `canDoInSession: false` with `blockers: ["requires-sub-agent-dispatch"]`. The probe does NOT block non-source slices (memory sediment, docs, SKILL.md updates).
116
116
 
117
- 2. **Tool-level guard — `pre-tool-code-gate.sh`** (PreToolUse hook). When the orchestrator reaches for `Edit`/`Write`/`MultiEdit` against a hard-blocked path family, the hook exits 2 with stderr `PEAKS_CODE_PROHIBITED_DIRECT_EDIT: <file>... use 'peaks sub-agent dispatch rd'`. The hook is vendor-neutral — it inspects only the standard `{tool, input}` JSON contract, never env vars.
117
+ 2. **Tool-level guard — `peaks code-gate`** (PreToolUse hook). When the orchestrator reaches for `Edit`/`Write`/`MultiEdit` against a hard-blocked path family, the hook exits 2 with stderr `PEAKS_CODE_PROHIBITED_DIRECT_EDIT: <file>... use 'peaks sub-agent dispatch rd'`. The hook is vendor-neutral — it inspects only the standard `{tool, input}` JSON contract, never env vars. **The rule lives in ONE implementation**: `src/services/hooks/pre-tool-code-gate.ts`, with the path arithmetic in `gate-path-normalize.ts` and the payload's own directory in `hook-payload-cwd.ts`. The shell sibling `src/services/hooks/pre-tool-code-gate.sh` is a **thin wrapper** that execs `peaks code-gate`; it carries a second copy of the rule **only** for a machine where no Node CLI is reachable, and that fallback **refuses rather than guessing** when it cannot place the file.
118
118
 
119
119
  ### If you catch yourself reaching for Edit/Write on `src/**`
120
120
 
@@ -102,9 +102,12 @@ as the terms of the deal, not as caveats:
102
102
  --scope global` also copies `src/services/hooks/pre-tool-code-gate.sh` into the IDE's
103
103
  skills directory; a project-scope install copies nothing. Nothing wires that copy up —
104
104
  every hook entry the installer writes is a `peaks …` command, and no settings template
105
- invokes a `.sh`, so it lies inert until a harness is pointed at it by hand. If one is: it
106
- takes no driver input at all and denies the hard-blocked families unconditionally, refused
107
- even in this lane, and its refusal will not mention this file. That asymmetry is known and
105
+ invokes a `.sh`, so it lies inert until a harness is pointed at it by hand. If one is: it is a
106
+ **thin wrapper** that execs `peaks code-gate` — so where a Node CLI is reachable it takes the
107
+ driver input and honours the fast lane exactly as the command does, and it refuses rather than
108
+ guessing when it cannot place the file. Only a machine with **no** Node CLI reachable reaches
109
+ its **no-CLI fallback**, which denies the hard-blocked families unconditionally, refused even in
110
+ this lane, and its refusal will not mention this file. That asymmetry is known and
108
111
  left conservative on purpose — assigning it is not this skill's job, and teaching the shell
109
112
  gate about lanes is not yours.
110
113