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
@@ -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
@@ -17,8 +17,10 @@ metadata:
17
17
  ## Loop hygiene (every turn — MANDATORY)
18
18
 
19
19
  **Skill header.** While this skill is active, open every turn with
20
- `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
20
+ `Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
21
21
  Every turn, not only the first — it is how the user knows which skill is driving.
22
+ `Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
23
+ (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
22
24
 
23
25
  **Context is this skill's own business.** Run `peaks skill presence --json` every turn and
24
26
  read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
@@ -13,8 +13,10 @@ visibility: internal
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
15
15
  **Skill header.** While this skill is active, open every turn with
16
- `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
16
+ `Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
17
17
  Every turn, not only the first — it is how the user knows which skill is driving.
18
+ `Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
19
+ (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
18
20
 
19
21
  **Context is this skill's own business.** Run `peaks skill presence --json` every turn and
20
22
  read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
@@ -108,7 +110,7 @@ peaks project memories --project <repo> --json
108
110
  ```
109
111
 
110
112
  This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <project|decision|convention|rule|reference|feedback|module|lesson|bug|investigation|technical-pattern|project-rule|design|handoff|session-handoff|project-todo|publish-closure|project-closure|slice-closure|slice-pilot-findings|sediment>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
111
- Then display: `Peaks-Loop Skill: peaks-prd | Peaks-Loop Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-prd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
113
+ Then display: `Peaks-Loop Skill: peaks-prd | Peaks-Loop Role: <role> | Peaks-Loop Gate: startup | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`. `Role` and `Context` are machine facts: copy them from `peaks skill presence --json` (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them. Update with `peaks skill presence:set peaks-prd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
112
114
 
113
115
  ## Responsibilities
114
116
 
@@ -308,7 +310,7 @@ PRD must not mark the product artifact ready for RD if the frontend change point
308
310
 
309
311
  ## Standards dry-run coordination
310
312
 
311
- For code repository workflows, PRD may run or consume `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run` so downstream scope can reference the expected `CLAUDE.md` and `.claude/rules/**` standards state. PRD records this as preflight status only. RD remains responsible for applying standards mutations when authorized.
313
+ For code repository workflows, PRD may run or consume `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run` so downstream scope can reference the expected standards state — the `AGENTS.md` body, the optional `CLAUDE.md` pointer (written only when the IDE profile needs it), and the rules tree under `.peaks/standards/**` (2.0 canonical layout) or `.claude/rules/**` (legacy 1.x project). PRD records this as preflight status only. RD remains responsible for applying standards mutations when authorized.
312
314
 
313
315
  ## Matt Pocock skills integration
314
316
 
@@ -13,8 +13,10 @@ visibility: internal
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
15
15
  **Skill header.** While this skill is active, open every turn with
16
- `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
16
+ `Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
17
17
  Every turn, not only the first — it is how the user knows which skill is driving.
18
+ `Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
19
+ (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
18
20
 
19
21
  **Context is this skill's own business.** Run `peaks skill presence --json` every turn and
20
22
  read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
@@ -154,7 +156,7 @@ Gate index: A (test-cases), A2 (tests executed), A3 (security reference — v2.1
154
156
 
155
157
  ## Project standards preflight
156
158
 
157
- Before QA verification in a code repository, call `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run`. Apply only when write authorization exists.
159
+ Before QA verification in a code repository, call `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run` — the bundle is the `AGENTS.md` body, the optional `CLAUDE.md` pointer (written only when the IDE profile needs it), and the rules tree under `.peaks/standards/**` or `.claude/rules/**`. Apply only when write authorization exists.
158
160
 
159
161
  → see `references/qa-standards-preflight.md` for the full preflight contract.
160
162
 
@@ -19,4 +19,4 @@ peaks project memories --project <repo> --json
19
19
  ```
20
20
 
21
21
  This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <project|decision|convention|rule|reference|feedback|module|lesson|bug|investigation|technical-pattern|project-rule|design|handoff|session-handoff|project-todo|publish-closure|project-closure|slice-closure|slice-pilot-findings|sediment>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
22
- Then display: `Peaks-Loop Skill: peaks-qa | Peaks-Loop Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
22
+ Then display: `Peaks-Loop Skill: peaks-qa | Peaks-Loop Role: <role> | Peaks-Loop Gate: startup | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`. `Role` and `Context` are machine facts: copy them from `peaks skill presence --json` (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them. Update with `peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
@@ -5,4 +5,6 @@
5
5
  - `peaks standards init --project <path> --dry-run`
6
6
  - `peaks standards update --project <path> --dry-run`
7
7
 
8
- If the repo needs a first-time standards bundle, treat `standards init` as the creation path. If `CLAUDE.md` already exists, use `standards update` to decide whether Peaks-Loop can append a managed block or should only return review suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.
8
+ The bundle the CLI writes has three parts: the **body** `AGENTS.md` (always written), the **pointer** `CLAUDE.md` (written only when the IDE profile needs it — a profile that reads `AGENTS.md` directly, e.g. `--ide codex`, writes no pointer), and the **rules tree** under `.peaks/standards/**` (2.0 canonical layout) or `.claude/rules/**` (legacy 1.x project). Judge the preflight from the CLI's own output instead of a hard-coded path: `peaks standards init --project <path> --dry-run --json` reports `data.plannedWrites[]` = `[{ relativePath, status }]`, where `init` reports two states — `planned` (absent → will be created) / `existing` (present on disk; `init` does not compare content, so a stale file still reads `existing`). The four-state view of the body file comes from `peaks standards update --project <path> --dry-run --json`: `planned` (absent) / `appended` (present, managed block missing) / `existing` (present and current) / `review` (present, managed block differs → a human decides; that command exits 1 with code `STANDARDS_UPDATE_REVIEW_REQUIRED`). Those four states cover `AGENTS.md` and, when the IDE profile writes one, `CLAUDE.md`; rules-tree files are `planned` / `existing` in both commands. The `relativePath` values also tell you which rules root this project uses.
9
+
10
+ If the repo needs a first-time standards bundle, treat `standards init` as the creation path. If the body file (`AGENTS.md`) already exists, use `standards update` to decide whether Peaks-Loop can append a managed block or should only return review suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.
@@ -25,7 +25,7 @@ If the upstream superpowers chain suggests raw `git worktree add`:
25
25
  3. Continue with `peaks worktree spawn` (or the auth-grant fallback)
26
26
 
27
27
  - **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
28
- - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-qa`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Code loop owns that file. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-qa.json` and only that.
28
+ - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-qa`. The sub-agent must not overwrite the main presence lease; the main Code loop owns it. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-qa.json` and only that.
29
29
  - **Workspace initialization** — Code has already run `peaks workspace init` before fan-out. Do not re-run it.
30
30
  - **Mode selection** — Code has already chosen the mode.
31
31
  - **Statusline install** — already done by Code at session startup.
@@ -52,7 +52,7 @@ What the sub-agent **MUST** still do:
52
52
  **Hard prohibitions** (sub-agent context):
53
53
 
54
54
  - Do NOT call `Skill(skill="...")`.
55
- - Do NOT call `peaks skill presence:set` — Code owns the active-skill file.
55
+ - Do NOT call `peaks skill presence:set` — Code owns the presence lease.
56
56
  - Do NOT run the actual test suite, do NOT execute security/perf tools, do NOT open a browser — those are the **QA validation** phase, not the Swarm planning phase.
57
57
  - Do NOT commit, push, install hooks, or apply settings.json mutations.
58
58
  - Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}`.
@@ -14,8 +14,10 @@ visibility: internal
14
14
  ## Loop hygiene (every turn — MANDATORY)
15
15
 
16
16
  **Skill header.** While this skill is active, open every turn with
17
- `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
17
+ `Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
18
18
  Every turn, not only the first — it is how the user knows which skill is driving.
19
+ `Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
20
+ (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
19
21
 
20
22
  **Context is this skill's own business.** Run `peaks skill presence --json` every turn and
21
23
  read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
@@ -118,7 +120,7 @@ See `references/rd-runbook.md` for the full 9-step runbook (steps #0–#8) with
118
120
 
119
121
  You cannot declare a phase complete from memory. Each gate below is a `ls` or `grep` command you **MUST run** and whose output you **MUST see** before proceeding. CLI enforcement: the gates are ALSO enforced by `peaks request transition`, which fails with `code: PREREQUISITES_MISSING` if any are absent.
120
122
 
121
- Gate index: A (project-scan), A2 (tech-doc path verification), A3 (CLAUDE.md + .claude/rules), B (tech-doc + request artifact), B2 (unit tests on changed surface), B3 (code-review.md), B4 (security-review.md), B5 (lint — no unfilled placeholders + JS/TS ESLint 卡控 via `peaks lint check`. First-time project setup: run `peaks lint baseline` to generate the project-level `.peaks/lint/baseline.json`. Per-slice flow uses `peaks lint check` (= diffOnly: true + baseline waiver + redLineMode: 'baseline-aware'). LLM red-line reference lives at `.peaks/memory/lint-redline-summary.md` (auto-written by `peaks lint check --red-line`); read it BEFORE writing JS/TS so the next slice sees prior sibling-violation context. Project-aware baseline: each project regenerates its own baseline; cross-project reuse is low-value — see `references/jsts-eslint-gate.md` §7), B6 (request-type-sanity), B7 (repair-status — 3-cycle cap), B8 (diff-vs-scope), B9 (perf-baseline).
123
+ Gate index: A (project-scan), A2 (tech-doc path verification), A3 (standards files — AGENTS.md body + rules tree; the CLAUDE.md pointer is written only when the IDE profile needs it), B (tech-doc + request artifact), B2 (unit tests on changed surface), B3 (code-review.md), B4 (security-review.md), B5 (lint — no unfilled placeholders + JS/TS ESLint 卡控 via `peaks lint check`. First-time project setup: run `peaks lint baseline` to generate the project-level `.peaks/lint/baseline.json`. Per-slice flow uses `peaks lint check` (= diffOnly: true + baseline waiver + redLineMode: 'baseline-aware'). LLM red-line reference lives at `.peaks/memory/lint-redline-summary.md` (auto-written by `peaks lint check --red-line`); read it BEFORE writing JS/TS so the next slice sees prior sibling-violation context. Project-aware baseline: each project regenerates its own baseline; cross-project reuse is low-value — see `references/jsts-eslint-gate.md` §7), B6 (request-type-sanity), B7 (repair-status — 3-cycle cap), B8 (diff-vs-scope), B9 (perf-baseline).
122
124
 
123
125
  → see `references/rd-transition-gates.md` for the per-gate contract + `ls` / `grep` shell snippets.
124
126
 
@@ -4,6 +4,6 @@
4
4
 
5
5
  Do not default to a git-backed artifact repository, external artifact sync, or automatic commits for intermediate artifacts. Git inclusion or sync requires explicit user confirmation or an active profile that clearly authorizes it. Browser evidence must be sanitized before retention: do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
6
6
 
7
- When project-local `CLAUDE.md` or project-local `.claude/rules/**` is created or updated, route the mutation through `peaks standards init` or `peaks standards update`; do not hand-write standards mutations. Derive the content from the current scan results and existing project standards. Keep only the rules that match the project's languages, frameworks, tooling, and repository layout. Do not emit generic templates, copy-pasted boilerplate, or rules unrelated to the current scan evidence. Do not update user-global `~/.claude/rules/**` from this workflow.
7
+ When the project-local standards bundle is created or updated — the `AGENTS.md` body, the optional `CLAUDE.md` pointer (written only when the IDE profile needs it), and the rules tree under `.peaks/standards/**` or `.claude/rules/**` — route the mutation through `peaks standards init` or `peaks standards update`; do not hand-write standards mutations. Derive the content from the current scan results and existing project standards. Keep only the rules that match the project's languages, frameworks, tooling, and repository layout. Do not emit generic templates, copy-pasted boilerplate, or rules unrelated to the current scan evidence. Do not update user-global `~/.claude/rules/**` from this workflow.
8
8
 
9
9
  If the scan results are insufficient to justify a rule, leave it out or surface a review-only suggestion instead of writing it into project standards.
@@ -161,8 +161,17 @@ peaks codegraph affected --project <repo> <changed-files...> --json
161
161
  # → `peaks request transition --state qa-handoff` returns `code: PREREQUISITES_MISSING`.
162
162
  # Escape hatch (assisted mode): `--allow-incomplete --confirm`.
163
163
 
164
- # 6.6 BEFORE implementation: verify CLAUDE.md + .claude/rules/ exist (Peaks-Loop Gate A3)
165
- # Missing standards files → run `peaks standards init --project .` first
164
+ # 6.6 BEFORE implementation: verify the standards files are in place (Peaks-Loop Gate A3)
165
+ # The file set is decided by the CLI — never hard-code it:
166
+ # peaks standards init --project . --dry-run --json
167
+ # → data.plannedWrites[] = [{relativePath, status}]; status 'planned' = that file is absent.
168
+ # BODY = AGENTS.md (always written).
169
+ # POINTER = CLAUDE.md (written only when the IDE profile needs it; its absence from
170
+ # plannedWrites is NOT a failure).
171
+ # RULES = .peaks/standards/** (2.0 canonical) or .claude/rules/** (legacy 1.x project).
172
+ # BLOCKED when plannedWrites is empty or any status is 'planned'.
173
+ # Missing standards files → run `peaks standards init --project . --apply` (first time)
174
+ # or `peaks standards update --project . --apply` (existing) first, then re-check.
166
175
  # Without project rules, security review and code review triggers won't fire.
167
176
 
168
177
  # 7. AFTER implementation, BEFORE QA handoff — RUN THESE GATES:
@@ -5,4 +5,6 @@
5
5
  - `peaks standards init --project <path> --dry-run`
6
6
  - `peaks standards update --project <path> --dry-run`
7
7
 
8
- If `CLAUDE.md` is missing, treat creation as the preferred path. If `CLAUDE.md` already exists, use `standards update` to decide whether to append a managed index block or surface review-only suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.
8
+ The bundle the CLI writes has three parts: the **body** `AGENTS.md` (always written), the **pointer** `CLAUDE.md` (written only when the IDE profile needs it — a profile that reads `AGENTS.md` directly, e.g. `--ide codex`, writes no pointer), and the **rules tree** under `.peaks/standards/**` (2.0 canonical layout) or `.claude/rules/**` (legacy 1.x project). Judge the preflight from the CLI's own output instead of a hard-coded path: `peaks standards init --project <path> --dry-run --json` reports `data.plannedWrites[]` = `[{ relativePath, status }]`, where `init` reports two states — `planned` (absent → will be created) / `existing` (present on disk; `init` does not compare content, so a stale file still reads `existing`). The four-state view of the body file comes from `peaks standards update --project <path> --dry-run --json`: `planned` (absent) / `appended` (present, managed block missing) / `existing` (present and current) / `review` (present, managed block differs → a human decides; that command exits 1 with code `STANDARDS_UPDATE_REVIEW_REQUIRED`). Those four states cover `AGENTS.md` and, when the IDE profile writes one, `CLAUDE.md`; rules-tree files are `planned` / `existing` in both commands. The `relativePath` values also tell you which rules root this project uses.
9
+
10
+ If the body file (`AGENTS.md`) is missing, treat creation as the preferred path. If the body already exists, use `standards update` to decide whether to append a managed index block or surface review-only suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.
@@ -59,9 +59,9 @@ If the upstream superpowers chain suggests raw `git worktree add`:
59
59
  > design — if either changes, update the other.
60
60
 
61
61
  - **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
62
- - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-rd`. The sub-agent must not overwrite `.peaks/.active-skill.json`; the main Code loop owns that file. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-rd.json` and only that.
62
+ - **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-rd`. The sub-agent must not overwrite the main presence lease; the main Code loop owns it. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-rd.json` and only that.
63
63
  - **Workspace initialization** — Code has already run `peaks workspace init` before fan-out. Do not re-run it.
64
- - **Mode selection** — Code has already chosen the mode. Read it from the prompt arguments (or from `.peaks/.active-skill.json` if you can, but do not write it).
64
+ - **Mode selection** — Code has already chosen the mode. Read it from the prompt arguments (or from `peaks skill presence --json` if you can, but do not write it).
65
65
  - **Statusline install** — already done by Code at session startup; do not re-run.
66
66
 
67
67
  What the sub-agent **MUST** still do, from this skill's contract:
@@ -89,7 +89,7 @@ What the sub-agent **MUST** still do, from this skill's contract:
89
89
  **Hard prohibitions** (sub-agent context, in addition to general red lines):
90
90
 
91
91
  - Do NOT call `Skill(skill="...")` from inside the sub-agent — that defeats the fan-out.
92
- - Do NOT call `peaks skill presence:set` — Code owns the active-skill file.
92
+ - Do NOT call `peaks skill presence:set` — Code owns the presence lease.
93
93
  - Do NOT commit, push, install hooks, or apply settings.json mutations.
94
94
  - Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}` and let Code handle the user message.
95
95
  - Do NOT modify code (the Swarm phase is planning only; code edits happen in the RD implementation phase, which is a separate sub-agent or inline run after Gate B).
@@ -171,7 +171,7 @@ Corrected 2026-10-13, kept visible rather than edited away: this paragraph used
171
171
 
172
172
  When you (the LLM sub-agent) write new or modified unit tests in `tests/unit/**`, every `it()` / `test()` block MUST follow the given-when-then contract:
173
173
 
174
- 1. The first string-literal argument of `it()` / `test()` MUST describe business behavior in the form `when X, should Y` — must include either the word "when" (state / pre-condition) or "should" (observable outcome).
174
+ 1. The first string-literal argument of `it()` / `test()` MUST describe business behavior and MUST include either the word "when" (state / pre-condition) or "should" (observable outcome). The idiomatic form `when X, should Y` names both, so prefer it — but it is a preference, not a requirement: a description carrying only "when" or only "should" is compliant.
175
175
  2. The body callback (the second argument) MUST start with exactly 3 leading comments:
176
176
  ```typescript
177
177
  // given: <precondition — system / user state>
@@ -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
+ ```
@@ -38,13 +38,57 @@ ls <every-single-directory-path-in-tech-doc> 2>&1 | grep -c "No such file"
38
38
  # breaks the implementation, and forces the user to correct the engineer.
39
39
  ```
40
40
 
41
- **Peaks-Loop Gate A3 — Before implementation: project standards files exist (CLAUDE.md + .claude/rules/):**
41
+ **Peaks-Loop Gate A3 — Before implementation: the project's standards files are in place:**
42
+
43
+ The standards bundle has three parts, and only the first has a fixed name:
44
+
45
+ - `AGENTS.md` — the **body** (the cross-tool constitution). Always written, in every layout.
46
+ - `CLAUDE.md` — the **pointer** (`@AGENTS.md`). Written ONLY when the IDE profile needs it.
47
+ A profile that reads `AGENTS.md` directly (e.g. `--ide codex`) writes no pointer at all,
48
+ so its absence is NOT a failure.
49
+ - the **rules tree** — `.peaks/standards/**` for the 2.0 canonical layout, `.claude/rules/**`
50
+ for a legacy 1.x project that still carries a thick `.claude/rules/` tree.
51
+
52
+ Never hard-code a path in this gate: ask the CLI which files this project actually uses.
53
+
42
54
  ```bash
43
- ls CLAUDE.md .claude/rules/common/coding-style.md .claude/rules/common/code-review.md .claude/rules/common/security.md 2>&1 | grep -c "No such file"
44
- # Expected: 0 (all four files exist)
45
- # Any missing → BLOCKED. Run `peaks standards init --project .` to generate them FIRST.
55
+ # 1) The CLI decides the file set. Never hard-code a rules path here.
56
+ peaks standards init --project . --dry-run --json
57
+ # → data.plannedWrites[] = [{ relativePath, status }, ...]
58
+ # init reports TWO states: planned (absent → will be created) | existing (present on
59
+ # disk — init does not compare content, so a stale file still reads 'existing').
60
+ # The four-state view of the body file comes from
61
+ # `peaks standards update --project . --dry-run --json`:
62
+ # planned | appended (managed block missing) | existing (managed
63
+ # block matches) | review (managed block differs → a human decides; that command exits
64
+ # 1 with code STANDARDS_UPDATE_REVIEW_REQUIRED). The four states cover AGENTS.md and,
65
+ # when the IDE profile writes one, CLAUDE.md; rules-tree files are planned | existing
66
+ # in both commands.
67
+ # → data.skippedFiles[] = the entries already present on disk
68
+ #
69
+ # 2) The body file is invariant — it is in plannedWrites in every layout. Verify it landed:
70
+ ls AGENTS.md
71
+ # "No such file" → BLOCKED
72
+ #
73
+ # 3) Judge the rest from the JSON, not from a hard-coded path list:
74
+ # BLOCKED when plannedWrites is empty, or when any entry has status 'planned'
75
+ # (that required standards file is absent).
76
+ # PASS otherwise. `init` never reports 'appended' / 'review' — when the update
77
+ # dry-run does, report each one as a follow-up:
78
+ # 'appended' → `peaks standards update --project . --apply` adds the managed block;
79
+ # 'review' → the managed block differs; a human decides (see `peaks standards update`).
80
+ #
81
+ # The layout is read off the paths themselves:
82
+ # .peaks/standards/** → 2.0 canonical layout
83
+ # .claude/rules/** → legacy 1.x layout
84
+ # CLAUDE.md is listed only when the IDE profile needs a pointer — its ABSENCE from
85
+ # plannedWrites is NOT a failure and must not be reported as BLOCKED.
86
+ #
87
+ # Any 'planned' entry → BLOCKED. Run `peaks standards init --project . --apply` (first
88
+ # time) or `peaks standards update --project . --apply` (existing) FIRST, then re-run the
89
+ # dry-run until no entry is 'planned'.
46
90
  # Do not write a single line of implementation code without standards files in place.
47
- # Without CLAUDE.md and .claude/rules/, code review and security review triggers won't fire.
91
+ # Without the standards body + rules tree, code review and security review triggers won't fire.
48
92
  ```
49
93
 
50
94
  **Peaks-Loop Gate B — Before QA handoff:**
@@ -19,4 +19,4 @@ peaks project memories --project <repo> --json
19
19
  ```
20
20
 
21
21
  This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <project|decision|convention|rule|reference|feedback|module|lesson|bug|investigation|technical-pattern|project-rule|design|handoff|session-handoff|project-todo|publish-closure|project-closure|slice-closure|slice-pilot-findings|sediment>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
22
- Then display: `Peaks-Loop Skill: peaks-rd | Peaks-Loop Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
22
+ Then display: `Peaks-Loop Skill: peaks-rd | Peaks-Loop Role: <role> | Peaks-Loop Gate: startup | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`. `Role` and `Context` are machine facts: copy them from `peaks skill presence --json` (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them. Update with `peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
@@ -9,8 +9,10 @@ description: Third-party independent code-review skill for Peaks. Use as a paral
9
9
  ## Loop hygiene (every turn — MANDATORY)
10
10
 
11
11
  **Skill header.** While this skill is active, open every turn with
12
- `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
12
+ `Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
13
13
  Every turn, not only the first — it is how the user knows which skill is driving.
14
+ `Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
15
+ (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
14
16
 
15
17
  **Context is this skill's own business.** Run `peaks skill presence --json` every turn and
16
18
  read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,