peaks-loop 4.1.18 → 4.1.20

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 (169) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +256 -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 +26 -18
  14. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  15. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  16. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  17. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  18. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  19. package/dist/cli/commands/core/standards-init-command.js +44 -8
  20. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  21. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  22. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  23. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  24. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  25. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  26. package/dist/cli/commands/mut-commands.d.ts +9 -1
  27. package/dist/cli/commands/mut-commands.js +82 -154
  28. package/dist/cli/commands/preferences-commands.js +27 -2
  29. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  30. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  31. package/dist/services/24h-mode/auto-engage.js +14 -6
  32. package/dist/services/artifacts/artifact-templates.js +10 -0
  33. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  34. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  35. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  36. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  37. package/dist/services/artifacts/request-artifact-service.js +6 -6
  38. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  39. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  40. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  41. package/dist/services/audit/static-service.js +4 -4
  42. package/dist/services/code/auto-compact-history.d.ts +6 -1
  43. package/dist/services/code/auto-compact-history.js +6 -1
  44. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  45. package/dist/services/code/auto-compact-modes.js +75 -20
  46. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  47. package/dist/services/code/auto-compact-profile.js +51 -0
  48. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  49. package/dist/services/compact-history/compact-history-service.js +5 -1
  50. package/dist/services/context/auto-compact-types.d.ts +7 -5
  51. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  52. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  53. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  54. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  55. package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
  56. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  57. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  58. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  59. package/dist/services/hooks/presence-marker-detector.js +21 -19
  60. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  61. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  62. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  63. package/dist/services/mode/mode-status-service.d.ts +26 -27
  64. package/dist/services/mode/mode-status-service.js +36 -60
  65. package/dist/services/preferences/preferences-types.d.ts +30 -0
  66. package/dist/services/preferences/preferences-types.js +13 -0
  67. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  68. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  69. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  70. package/dist/services/scan/rid-change-claims.js +116 -0
  71. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  72. package/dist/services/skills/presence-caller-id.js +43 -0
  73. package/dist/services/skills/presence-gate.d.ts +65 -0
  74. package/dist/services/skills/presence-gate.js +113 -0
  75. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  76. package/dist/services/skills/presence-lease-resolver.js +114 -0
  77. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  78. package/dist/services/skills/presence-lease-selection.js +135 -0
  79. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  80. package/dist/services/skills/presence-lease-service.js +34 -87
  81. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  82. package/dist/services/skills/presence-lease-store.js +94 -0
  83. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  84. package/dist/services/skills/presence-lease-types.js +27 -0
  85. package/dist/services/skills/presence-role.d.ts +35 -0
  86. package/dist/services/skills/presence-role.js +72 -0
  87. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  88. package/dist/services/skills/skill-presence-service.js +143 -174
  89. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  90. package/dist/services/skills/skill-presence-write.js +74 -0
  91. package/dist/services/skills/skill-statusline-service.js +7 -7
  92. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  93. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  94. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  95. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  96. package/dist/services/standards/migrate-service.d.ts +1 -1
  97. package/dist/services/standards/migrate-service.js +27 -7
  98. package/dist/services/standards/project-scripts.d.ts +25 -0
  99. package/dist/services/standards/project-scripts.js +116 -0
  100. package/dist/services/standards/project-standards-service.d.ts +23 -15
  101. package/dist/services/standards/project-standards-service.js +176 -243
  102. package/dist/services/standards/standards-constitution.d.ts +89 -0
  103. package/dist/services/standards/standards-constitution.js +199 -0
  104. package/dist/services/standards/standards-files.d.ts +37 -0
  105. package/dist/services/standards/standards-files.js +138 -0
  106. package/dist/services/standards/standards-pointer.d.ts +73 -0
  107. package/dist/services/standards/standards-pointer.js +98 -0
  108. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  109. package/dist/services/standards/standards-render-agents.js +149 -0
  110. package/dist/services/standards/standards-render-common.d.ts +38 -1
  111. package/dist/services/standards/standards-render-common.js +44 -7
  112. package/dist/services/standards/standards-render.d.ts +1 -3
  113. package/dist/services/standards/standards-render.js +6 -87
  114. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  115. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  116. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  117. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  118. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  119. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  120. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  121. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  122. package/dist/services/workspace/runtime-layout.js +62 -0
  123. package/output-styles/peaks-skill-swarm.md +18 -2
  124. package/package.json +9 -9
  125. package/schemas/doctor-report.schema.json +1 -1
  126. package/scripts/canonical-store-report.mjs +84 -0
  127. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  128. package/skills/bee/peaks-prd/SKILL.md +5 -3
  129. package/skills/bee/peaks-qa/SKILL.md +4 -2
  130. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  131. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  132. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  133. package/skills/bee/peaks-rd/SKILL.md +4 -2
  134. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  135. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  136. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  137. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +4 -4
  138. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  139. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  140. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  141. package/skills/bee/peaks-sc/SKILL.md +4 -2
  142. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  143. package/skills/bee/peaks-txt/SKILL.md +5 -3
  144. package/skills/bee/peaks-ui/SKILL.md +6 -4
  145. package/skills/peaks-audit/SKILL.md +3 -1
  146. package/skills/peaks-code/SKILL.md +3 -1
  147. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  148. package/skills/peaks-code/references/completion-handoff.md +1 -1
  149. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  150. package/skills/peaks-code/references/micro-cycle.md +2 -2
  151. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  152. package/skills/peaks-code/references/runbook.md +4 -4
  153. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  154. package/skills/peaks-code/references/standards-preflight.md +7 -6
  155. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  156. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  157. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  158. package/skills/peaks-content/SKILL.md +3 -1
  159. package/skills/peaks-doctor/SKILL.md +3 -1
  160. package/skills/peaks-final-review/SKILL.md +3 -1
  161. package/skills/peaks-ide/SKILL.md +3 -1
  162. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  163. package/skills/peaks-race-code/SKILL.md +3 -1
  164. package/skills/peaks-resume/SKILL.md +3 -1
  165. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  166. package/skills/peaks-solo/SKILL.md +3 -1
  167. package/skills/peaks-sop/SKILL.md +4 -2
  168. package/skills/peaks-status/SKILL.md +3 -1
  169. package/skills/peaks-test/SKILL.md +3 -1
@@ -1,8 +1,12 @@
1
- import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, realpathSync, readFileSync, writeFileSync } from 'node:fs';
1
+ import { existsSync, lstatSync, mkdirSync, realpathSync } from 'node:fs';
2
2
  import { homedir as osHomedir } from 'node:os';
3
- import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
3
+ import { dirname, join, resolve } from 'node:path';
4
4
  import { detectProjectContext } from './project-context.js';
5
- import { renderClaudeMd, renderClaudeMdOneX, renderCodeReview, renderCommonCodingStyle, renderLanguageCodingStyle, renderManagedClaudeMdIndex, renderSecurity } from './standards-render.js';
5
+ import { renderCodeReview, renderCommonCodingStyle, renderLanguageCodingStyle, renderSecurity } from './standards-render.js';
6
+ import { renderAgentsMd, renderClaudeMdPointer } from './standards-render-agents.js';
7
+ import { assertSafeConstitutionPath, buildConstitutionUpdate, DEFAULT_CONSTITUTION, isConstitutionPath, isInsidePath, summarizeConstitutionUpdate } from './standards-constitution.js';
8
+ import { applyConstitutionFile, hasThickOneXClaudeRules, writeNewFile } from './standards-files.js';
9
+ import { detectProjectScripts } from './project-scripts.js';
6
10
  export { renderUiLibraryPriorityRule } from './standards-render.js';
7
11
  export class ProjectStandardsWriteTargetError extends Error {
8
12
  code = 'PROJECT_STANDARDS_WRITE_TARGET_OUTSIDE_ROOT';
@@ -39,10 +43,6 @@ const SUPPORTED_LANGUAGES = new Set([
39
43
  function normalizeRoot(path) {
40
44
  return realpathSync(resolve(path));
41
45
  }
42
- function isInsidePath(childPath, parentPath) {
43
- const rel = relative(parentPath, childPath);
44
- return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
45
- }
46
46
  function assertDirectoryNotSymlink(path) {
47
47
  if (existsSync(path) && lstatSync(path).isSymbolicLink()) {
48
48
  throw new Error('Project standards directory must stay inside the project root');
@@ -60,13 +60,6 @@ function assertWritablePathInsideProject(path, projectRoot) {
60
60
  }
61
61
  assertRealPathInsideProject(currentPath, projectRoot);
62
62
  }
63
- function assertSafeClaudeMdPath(filePath, projectRoot) {
64
- if (!existsSync(filePath))
65
- return;
66
- if (lstatSync(filePath).isSymbolicLink() || !isInsidePath(realpathSync(filePath), projectRoot)) {
67
- throw new Error('Project standards CLAUDE.md must stay inside the project root');
68
- }
69
- }
70
63
  function assertSafeStandardsRoot(projectRoot) {
71
64
  const resolvedRoot = normalizeRoot(projectRoot);
72
65
  const claudeDir = join(resolvedRoot, '.claude');
@@ -115,19 +108,8 @@ function detectLanguageInternal(projectRoot) {
115
108
  export function detectLanguage(projectRoot) {
116
109
  return detectLanguageInternal(projectRoot);
117
110
  }
118
- function readFileIfExists(path) {
119
- if (!existsSync(path))
120
- return null;
121
- const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
122
- try {
123
- return readFileSync(fd, 'utf8');
124
- }
125
- finally {
126
- closeSync(fd);
127
- }
128
- }
129
111
  function getPendingStandardsRuleWrites(plan) {
130
- return plan.plannedWrites.filter((write) => write.relativePath !== 'CLAUDE.md' && write.status !== 'existing');
112
+ return plan.plannedWrites.filter((write) => !isConstitutionPath(write.relativePath) && write.status !== 'existing');
131
113
  }
132
114
  function prevalidateWrites(projectRoot, writes, resolveHomedir = osHomedir) {
133
115
  const homeRoot = resolveHomedir();
@@ -135,8 +117,8 @@ function prevalidateWrites(projectRoot, writes, resolveHomedir = osHomedir) {
135
117
  const targetPath = resolve(write.filePath);
136
118
  const targetDir = dirname(targetPath);
137
119
  assertWritablePathInsideProject(targetDir, projectRoot);
138
- if (write.relativePath === 'CLAUDE.md') {
139
- assertSafeClaudeMdPath(targetPath, projectRoot);
120
+ if (isConstitutionPath(write.relativePath)) {
121
+ assertSafeConstitutionPath(targetPath, projectRoot);
140
122
  }
141
123
  assertNotHomedirBaseline(targetPath, projectRoot, homeRoot);
142
124
  }
@@ -201,20 +183,38 @@ function writeMissingStandardsRules(plan, writes = getPendingStandardsRuleWrites
201
183
  }
202
184
  return writtenFiles;
203
185
  }
204
- function createTemplates(language, ctx) {
205
- return [
206
- { relativePath: 'CLAUDE.md', content: renderClaudeMd(language, ctx) },
207
- { relativePath: '.peaks/standards/common/code-review.md', content: renderCodeReview(ctx) },
208
- {
209
- relativePath: '.peaks/standards/common/coding-style.md',
210
- content: renderCommonCodingStyle(ctx)
211
- },
212
- { relativePath: '.peaks/standards/common/security.md', content: renderSecurity(ctx) },
186
+ /** The standards directory of the 2.0 canonical layout. */
187
+ const CANONICAL_RULES_ROOT = '.peaks/standards';
188
+ /** The standards directory of the 1.x layout a thick `.claude/rules/` tree implies. */
189
+ const LEGACY_RULES_ROOT = '.claude/rules';
190
+ /**
191
+ * The 2.0 canonical layout: the shared cross-tool body, the pointer that
192
+ * imports it, and the project-local standards tree.
193
+ */
194
+ function createTemplates(input) {
195
+ const templates = [
213
196
  {
214
- relativePath: `.peaks/standards/${language}/coding-style.md`,
215
- content: renderLanguageCodingStyle(language, ctx)
197
+ relativePath: input.constitution.bodyFile,
198
+ content: renderAgentsMd(input.language, input.scripts, CANONICAL_RULES_ROOT)
216
199
  }
217
200
  ];
201
+ if (input.constitution.pointerFile !== null) {
202
+ templates.push({
203
+ relativePath: input.constitution.pointerFile,
204
+ content: renderClaudeMdPointer()
205
+ });
206
+ }
207
+ templates.push({
208
+ relativePath: '.peaks/standards/common/code-review.md',
209
+ content: renderCodeReview(input.ctx)
210
+ }, {
211
+ relativePath: '.peaks/standards/common/coding-style.md',
212
+ content: renderCommonCodingStyle(input.ctx)
213
+ }, { relativePath: '.peaks/standards/common/security.md', content: renderSecurity(input.ctx) }, {
214
+ relativePath: `.peaks/standards/${input.language}/coding-style.md`,
215
+ content: renderLanguageCodingStyle(input.language, input.ctx)
216
+ });
217
+ return templates;
218
218
  }
219
219
  /**
220
220
  * Legacy 1.x templates — used only when the consumer project
@@ -223,161 +223,53 @@ function createTemplates(language, ctx) {
223
223
  * silently overwritten; the caller should follow up with
224
224
  * `peaks standards migrate --from-claude-rules` to converge to
225
225
  * the 2.0 canonical layout.
226
+ *
227
+ * The constitution is the SAME two files as in the 2.0 layout — the body
228
+ * plus the pointer that imports it — so a project on either layout ends up
229
+ * with one body and one pointer; only the directory the body points its
230
+ * standards reads at differs.
226
231
  */
227
- function createLegacyOneXTemplates(language, ctx) {
228
- return [
229
- { relativePath: 'CLAUDE.md', content: renderClaudeMdOneX(language, ctx) },
230
- { relativePath: '.claude/rules/common/code-review.md', content: renderCodeReview(ctx) },
231
- { relativePath: '.claude/rules/common/coding-style.md', content: renderCommonCodingStyle(ctx) },
232
- { relativePath: '.claude/rules/common/security.md', content: renderSecurity(ctx) },
232
+ function createLegacyOneXTemplates(input) {
233
+ const templates = [
233
234
  {
234
- relativePath: `.claude/rules/${language}/coding-style.md`,
235
- content: renderLanguageCodingStyle(language, ctx)
235
+ relativePath: input.constitution.bodyFile,
236
+ content: renderAgentsMd(input.language, input.scripts, LEGACY_RULES_ROOT)
236
237
  }
237
238
  ];
239
+ if (input.constitution.pointerFile !== null) {
240
+ templates.push({
241
+ relativePath: input.constitution.pointerFile,
242
+ content: renderClaudeMdPointer()
243
+ });
244
+ }
245
+ templates.push({ relativePath: '.claude/rules/common/code-review.md', content: renderCodeReview(input.ctx) }, {
246
+ relativePath: '.claude/rules/common/coding-style.md',
247
+ content: renderCommonCodingStyle(input.ctx)
248
+ }, { relativePath: '.claude/rules/common/security.md', content: renderSecurity(input.ctx) }, {
249
+ relativePath: `.claude/rules/${input.language}/coding-style.md`,
250
+ content: renderLanguageCodingStyle(input.language, input.ctx)
251
+ });
252
+ return templates;
238
253
  }
239
254
  /**
240
- * Detect whether the consumer project still carries a 1.x "thick"
241
- * `.claude/rules/` tree (the legacy layout that 2.0 migrates away
242
- * from). A project with thick 1.x rules should NOT be silently
243
- * re-initialised into the 2.0 `.peaks/standards/` layout; the
244
- * caller should explicitly run `peaks standards migrate --from-claude-rules`
245
- * instead. A new project (no `.claude/rules/` tree, or only a
246
- * previously-thinned 2-line-pointer tree) is safe to bootstrap
247
- * directly into the 2.0 canonical layout.
255
+ * The write plan for ONE template.
256
+ * A constitution file's plan comes from the four-state planner, so `init` and
257
+ * `update` decide the same thing about the same file; a rules file's plan
258
+ * stays the simpler one: an existing file is left alone.
248
259
  */
249
- function hasThickOneXClaudeRules(projectRoot) {
250
- const claudeRulesDir = join(projectRoot, '.claude', 'rules');
251
- if (!existsSync(claudeRulesDir))
252
- return false;
253
- const stat = lstatSync(claudeRulesDir);
254
- if (!stat.isDirectory())
255
- return false;
256
- // Walk one level deep; if any .md file under common/ or
257
- // typescript/ (or the language pack) exists and is NOT a
258
- // 2-line pointer, treat the tree as thick 1.x.
259
- const POINTER_MARKER = 'Canonical peaks-loop 2.0 rules live at:';
260
- const stack = [claudeRulesDir];
261
- while (stack.length > 0) {
262
- const dir = stack.pop();
263
- if (dir === undefined)
264
- break;
265
- let entries;
266
- try {
267
- entries = readdirSync(dir);
268
- }
269
- catch {
270
- return false;
271
- }
272
- for (const entry of entries) {
273
- if (entry.startsWith('.'))
274
- continue;
275
- const entryPath = join(dir, entry);
276
- let entryStat;
277
- try {
278
- entryStat = lstatSync(entryPath);
279
- }
280
- catch {
281
- continue;
282
- }
283
- if (entryStat.isDirectory()) {
284
- stack.push(entryPath);
285
- }
286
- else if (entryStat.isFile() && entry.endsWith('.md')) {
287
- let body = '';
288
- try {
289
- body = readFileSync(entryPath, 'utf8');
290
- }
291
- catch {
292
- continue;
293
- }
294
- if (!body.includes(POINTER_MARKER))
295
- return true;
296
- }
297
- }
298
- }
299
- return false;
300
- }
301
- function createManagedClaudeBlock(language) {
302
- return renderManagedClaudeMdIndex(language);
303
- }
304
- function buildClaudeUpdate(projectRoot, language, ctx) {
305
- const filePath = resolve(projectRoot, 'CLAUDE.md');
306
- assertSafeClaudeMdPath(filePath, projectRoot);
307
- const existingContent = readFileIfExists(filePath);
308
- const managedBlock = createManagedClaudeBlock(language);
309
- if (existingContent === null) {
310
- return {
311
- relativePath: 'CLAUDE.md',
312
- filePath,
313
- status: 'planned',
314
- content: `${renderClaudeMd(language, ctx).trimEnd()}\n\n${managedBlock}`,
315
- appendBlock: '',
316
- reviewSuggestions: []
317
- };
318
- }
319
- const existingBlockStart = existingContent.indexOf('<!-- peaks-standards:index:start -->');
320
- if (existingBlockStart < 0) {
321
- return {
322
- relativePath: 'CLAUDE.md',
323
- filePath,
324
- status: 'appended',
325
- content: `${existingContent.trimEnd()}
326
-
327
- ${managedBlock}`,
328
- appendBlock: `
329
-
330
- ${managedBlock}`,
331
- reviewSuggestions: []
332
- };
333
- }
334
- const existingManagedBlock = existingContent.slice(existingBlockStart).trimEnd();
335
- if (existingManagedBlock === managedBlock.trimEnd()) {
260
+ function buildWrite(projectRoot, template, constitutionUpdate) {
261
+ const plans = [constitutionUpdate.body, constitutionUpdate.pointer].filter((plan) => plan !== null);
262
+ const constitutionPlan = plans.find((plan) => plan.relativePath === template.relativePath);
263
+ if (constitutionPlan !== undefined) {
336
264
  return {
337
- relativePath: 'CLAUDE.md',
338
- filePath,
339
- status: 'existing',
340
- content: existingContent,
341
- appendBlock: '',
342
- reviewSuggestions: []
265
+ relativePath: constitutionPlan.relativePath,
266
+ filePath: constitutionPlan.filePath,
267
+ content: constitutionPlan.content,
268
+ status: constitutionPlan.status
343
269
  };
344
270
  }
345
- return {
346
- relativePath: 'CLAUDE.md',
347
- filePath,
348
- status: 'review',
349
- content: existingContent,
350
- appendBlock: '',
351
- reviewSuggestions: [
352
- 'Existing CLAUDE.md already has a managed standards block. Review the managed block manually before changing it.'
353
- ]
354
- };
355
- }
356
- function buildWrite(projectRoot, template) {
357
271
  const filePath = resolve(projectRoot, template.relativePath);
358
- return {
359
- ...template,
360
- filePath,
361
- status: existsSync(filePath) ? 'existing' : 'planned'
362
- };
363
- }
364
- function writeNewFile(path, content) {
365
- const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
366
- try {
367
- writeFileSync(fd, content, 'utf8');
368
- }
369
- finally {
370
- closeSync(fd);
371
- }
372
- }
373
- function appendExistingFile(path, content) {
374
- const fd = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW);
375
- try {
376
- writeFileSync(fd, content, 'utf8');
377
- }
378
- finally {
379
- closeSync(fd);
380
- }
272
+ return { ...template, filePath, status: existsSync(filePath) ? 'existing' : 'planned' };
381
273
  }
382
274
  export function createProjectStandardsInitPlan(options) {
383
275
  const projectRoot = normalizeRoot(options.projectRoot);
@@ -386,6 +278,8 @@ export function createProjectStandardsInitPlan(options) {
386
278
  ? detectLanguageInternal(projectRoot)
387
279
  : parseLanguage(options.language);
388
280
  const ctx = detectProjectContext(projectRoot);
281
+ const scripts = detectProjectScripts(projectRoot);
282
+ const constitution = options.constitution ?? DEFAULT_CONSTITUTION;
389
283
  // Default to the 2.0 canonical layout (`.peaks/standards/`).
390
284
  // If the consumer project still carries a 1.x "thick" `.claude/rules/`
391
285
  // tree, fall back to the legacy 1.x path so the operator's existing
@@ -393,84 +287,126 @@ export function createProjectStandardsInitPlan(options) {
393
287
  // with `peaks standards migrate --from-claude-rules` to migrate them
394
288
  // to 2.0.
395
289
  const useLegacyOneXLayout = hasThickOneXClaudeRules(projectRoot);
396
- const plannedWrites = useLegacyOneXLayout
397
- ? createLegacyOneXTemplates(language, ctx).map((template) => buildWrite(projectRoot, template))
398
- : createTemplates(language, ctx).map((template) => buildWrite(projectRoot, template));
290
+ const rulesRoot = useLegacyOneXLayout ? LEGACY_RULES_ROOT : CANONICAL_RULES_ROOT;
291
+ const templates = useLegacyOneXLayout
292
+ ? createLegacyOneXTemplates({ constitution, language, ctx, scripts })
293
+ : createTemplates({ constitution, language, ctx, scripts });
294
+ const constitutionUpdate = buildConstitutionUpdate({
295
+ projectRoot,
296
+ constitution,
297
+ language,
298
+ scripts,
299
+ rulesRoot
300
+ });
301
+ const plannedWrites = templates.map((template) => buildWrite(projectRoot, template, constitutionUpdate));
399
302
  return {
400
303
  apply: options.apply ?? false,
401
304
  projectRoot,
402
305
  language,
403
306
  source: SOURCE,
404
307
  skillPreflight: SKILL_PREFLIGHT,
308
+ constitution,
309
+ rulesRoot,
310
+ constitutionUpdate,
405
311
  plannedWrites
406
312
  };
407
313
  }
408
314
  export function createProjectStandardsUpdatePlan(options) {
409
- const basePlan = createProjectStandardsInitPlan(options);
410
- const ctx = detectProjectContext(basePlan.projectRoot);
411
- const claudeMd = buildClaudeUpdate(basePlan.projectRoot, basePlan.language, ctx);
412
- return {
413
- ...basePlan,
414
- claudeMd
415
- };
315
+ // The init plan already carries the constitution write plan `update` applies.
316
+ return createProjectStandardsInitPlan(options);
416
317
  }
417
318
  export function executeProjectStandardsInit(options) {
418
- const plan = createProjectStandardsInitPlan(options);
419
- const writtenFiles = [];
420
- const resolveHomedir = options.resolveHomedir ?? osHomedir;
421
- if (plan.apply) {
422
- assertSafeStandardsRoot(plan.projectRoot);
423
- const pendingWrites = plan.plannedWrites.filter((write) => write.status !== 'existing');
424
- prevalidateWrites(plan.projectRoot, pendingWrites, resolveHomedir);
425
- for (const write of pendingWrites) {
426
- const targetPath = resolve(write.filePath);
427
- mkdirSync(dirname(targetPath), { recursive: true });
428
- writeNewFile(targetPath, write.content);
429
- writtenFiles.push(write.relativePath);
319
+ // ONE writer for both verbs. `init` and `update` differ in what they
320
+ // REPORT, not in what they write: both plan the constitution with the same
321
+ // four-state planner, so a downstream project that already has an AGENTS.md
322
+ // and a CLAUDE.md receives the missing managed block and the missing
323
+ // `@AGENTS.md` pointer from EITHER command — and the same result.
324
+ const { writtenFiles, plannedWrites, ...plan } = executeProjectStandardsUpdate(options);
325
+ return { ...plan, plannedWrites, writtenFiles };
326
+ }
327
+ /**
328
+ * The planned-write statuses after the constitution files were applied.
329
+ *
330
+ * A constitution file takes the status the update gave it; a rules file
331
+ * takes `written` when this run wrote it; everything else keeps its plan
332
+ * status.
333
+ */
334
+ function mergePlannedWriteStatuses(input) {
335
+ return input.plannedWrites.map((write) => {
336
+ if (write.relativePath === input.bodyPath)
337
+ return { ...write, status: input.bodyStatus };
338
+ if (input.pointerPath !== null && write.relativePath === input.pointerPath) {
339
+ return { ...write, status: input.pointerStatus ?? write.status };
430
340
  }
431
- }
432
- return {
433
- ...plan,
434
- plannedWrites: plan.plannedWrites.map((write) => writtenFiles.includes(write.relativePath) ? { ...write, status: 'written' } : write),
435
- writtenFiles
436
- };
341
+ if (input.writtenFiles.includes(write.relativePath)) {
342
+ return { ...write, status: 'written' };
343
+ }
344
+ return write;
345
+ });
346
+ }
347
+ /**
348
+ * Write the rules files and the constitution files of one update run.
349
+ *
350
+ * Returns the status each constitution file ended at.
351
+ */
352
+ function applyUpdateWrites(input) {
353
+ const pointerPlan = input.plan.constitutionUpdate.pointer;
354
+ assertSafeStandardsRoot(input.plan.projectRoot);
355
+ const pendingRuleWrites = getPendingStandardsRuleWrites(input.plan);
356
+ prevalidateWrites(input.plan.projectRoot, pendingRuleWrites, input.resolveHomedir);
357
+ input.writtenFiles.push(...writeMissingStandardsRules(input.plan, pendingRuleWrites));
358
+ const prevalidate = (file) => prevalidateWrites(input.plan.projectRoot, [file], input.resolveHomedir);
359
+ const bodyStatus = applyConstitutionFile({
360
+ file: input.plan.constitutionUpdate.body,
361
+ writtenFiles: input.writtenFiles,
362
+ appendedFiles: input.appendedFiles,
363
+ prevalidate
364
+ });
365
+ if (pointerPlan === null)
366
+ return { bodyStatus, pointerStatus: null };
367
+ const pointerStatus = applyConstitutionFile({
368
+ file: pointerPlan,
369
+ writtenFiles: input.writtenFiles,
370
+ appendedFiles: input.appendedFiles,
371
+ prevalidate
372
+ });
373
+ return { bodyStatus, pointerStatus };
437
374
  }
438
375
  export function executeProjectStandardsUpdate(options) {
439
376
  const plan = createProjectStandardsUpdatePlan(options);
440
377
  const writtenFiles = [];
441
378
  const appendedFiles = [];
442
- const reviewSuggestions = [...plan.claudeMd.reviewSuggestions];
443
- let claudeMd = { ...plan.claudeMd };
379
+ const pointerPlan = plan.constitutionUpdate.pointer;
380
+ const reviewSuggestions = [
381
+ ...plan.constitutionUpdate.body.reviewSuggestions,
382
+ ...(pointerPlan === null ? [] : pointerPlan.reviewSuggestions)
383
+ ];
444
384
  const resolveHomedir = options.resolveHomedir ?? osHomedir;
385
+ let bodyStatus = plan.constitutionUpdate.body.status;
386
+ let pointerStatus = pointerPlan === null ? null : pointerPlan.status;
445
387
  if (plan.apply) {
446
- assertSafeStandardsRoot(plan.projectRoot);
447
- const pendingRuleWrites = getPendingStandardsRuleWrites(plan);
448
- prevalidateWrites(plan.projectRoot, pendingRuleWrites, resolveHomedir);
449
- const targetPath = resolve(claudeMd.filePath);
450
- prevalidateWrites(plan.projectRoot, [claudeMd], resolveHomedir);
451
- writtenFiles.push(...writeMissingStandardsRules(plan, pendingRuleWrites));
452
- if (claudeMd.status === 'planned') {
453
- writeNewFile(targetPath, claudeMd.content);
454
- writtenFiles.push(claudeMd.relativePath);
455
- claudeMd = { ...claudeMd, status: 'written' };
456
- }
457
- else if (claudeMd.status === 'appended') {
458
- appendExistingFile(targetPath, claudeMd.appendBlock);
459
- appendedFiles.push(claudeMd.relativePath);
460
- }
388
+ const applied = applyUpdateWrites({ plan, writtenFiles, appendedFiles, resolveHomedir });
389
+ bodyStatus = applied.bodyStatus;
390
+ pointerStatus = applied.pointerStatus;
461
391
  }
462
- const plannedWrites = plan.plannedWrites.map((write) => {
463
- if (write.relativePath === 'CLAUDE.md') {
464
- return { ...write, status: claudeMd.status };
465
- }
466
- if (writtenFiles.includes(write.relativePath)) {
467
- return { ...write, status: 'written' };
468
- }
469
- return write;
392
+ const bodyPath = plan.constitutionUpdate.body.relativePath;
393
+ const pointerPath = pointerPlan === null ? null : pointerPlan.relativePath;
394
+ const plannedWrites = mergePlannedWriteStatuses({
395
+ plannedWrites: plan.plannedWrites,
396
+ bodyPath,
397
+ bodyStatus,
398
+ pointerPath,
399
+ pointerStatus,
400
+ writtenFiles
470
401
  });
471
402
  return {
472
403
  ...plan,
473
- claudeMd,
404
+ constitutionUpdate: {
405
+ body: { ...plan.constitutionUpdate.body, status: bodyStatus },
406
+ pointer: pointerPlan === null
407
+ ? null
408
+ : { ...pointerPlan, status: pointerStatus ?? pointerPlan.status }
409
+ },
474
410
  plannedWrites,
475
411
  writtenFiles,
476
412
  appendedFiles,
@@ -491,7 +427,8 @@ export function summarizeProjectStandardsInitResult(result) {
491
427
  writtenFiles: result.writtenFiles,
492
428
  skippedFiles: result.plannedWrites
493
429
  .filter((write) => write.status === 'existing')
494
- .map((write) => write.relativePath)
430
+ .map((write) => write.relativePath),
431
+ reviewSuggestions: result.reviewSuggestions
495
432
  };
496
433
  }
497
434
  export function summarizeProjectStandardsUpdateResult(result) {
@@ -511,10 +448,6 @@ export function summarizeProjectStandardsUpdateResult(result) {
511
448
  .filter((write) => write.status === 'existing')
512
449
  .map((write) => write.relativePath),
513
450
  reviewSuggestions: result.reviewSuggestions,
514
- claudeMd: {
515
- relativePath: result.claudeMd.relativePath,
516
- status: result.claudeMd.status,
517
- reviewSuggestions: result.claudeMd.reviewSuggestions
518
- }
451
+ constitutionUpdate: summarizeConstitutionUpdate(result.constitutionUpdate)
519
452
  };
520
453
  }
@@ -0,0 +1,89 @@
1
+ import type { ProjectScripts } from './project-scripts.js';
2
+ import type { StandardsLanguage, StandardsWriteStatus } from './project-standards-service.js';
3
+ /** Which instruction files the standards writer owns for one project. */
4
+ export type StandardsConstitution = {
5
+ /** The shared cross-tool body file. */
6
+ readonly bodyFile: string;
7
+ /**
8
+ * The IDE-native file that imports the body, or `null` when the IDE reads
9
+ * the body file directly and needs no pointer.
10
+ */
11
+ readonly pointerFile: string | null;
12
+ };
13
+ /**
14
+ * The default shape: both files.
15
+ *
16
+ * `AGENTS.md` is read natively by 20+ coding agents; `CLAUDE.md` is what
17
+ * Claude Code reads, and it imports the body. Emitting both covers every
18
+ * reader without a per-tool configuration step.
19
+ */
20
+ export declare const DEFAULT_CONSTITUTION: StandardsConstitution;
21
+ /** One constitution file's write plan. */
22
+ export type ConstitutionFileUpdate = {
23
+ readonly relativePath: string;
24
+ readonly filePath: string;
25
+ readonly status: StandardsWriteStatus;
26
+ readonly content: string;
27
+ readonly appendBlock: string;
28
+ readonly reviewSuggestions: readonly string[];
29
+ };
30
+ /** The whole constitution's write plan. */
31
+ export type ConstitutionUpdate = {
32
+ readonly body: ConstitutionFileUpdate;
33
+ readonly pointer: ConstitutionFileUpdate | null;
34
+ };
35
+ /** The JSON shape of a constitution update — one file summary, plus its pointer. */
36
+ export type ConstitutionUpdateSummary = {
37
+ readonly body: {
38
+ readonly relativePath: string;
39
+ readonly status: StandardsWriteStatus;
40
+ readonly reviewSuggestions: readonly string[];
41
+ };
42
+ readonly pointer: {
43
+ readonly relativePath: string;
44
+ readonly status: StandardsWriteStatus;
45
+ readonly reviewSuggestions: readonly string[];
46
+ } | null;
47
+ };
48
+ /** The JSON shape of a constitution update. */
49
+ export declare function summarizeConstitutionUpdate(update: ConstitutionUpdate): ConstitutionUpdateSummary;
50
+ /** True when the relative path names a constitution file the writer owns. */
51
+ export declare function isConstitutionPath(relativePath: string): boolean;
52
+ /** True when `childPath` is `parentPath` or lives under it. */
53
+ export declare function isInsidePath(childPath: string, parentPath: string): boolean;
54
+ /**
55
+ * The write-target containment guard for a constitution file.
56
+ *
57
+ * A symlinked `CLAUDE.md` / `AGENTS.md`, or one that resolves outside the
58
+ * project root, is a write-target escape attempt and must be rejected before
59
+ * anything is written.
60
+ */
61
+ export declare function assertSafeConstitutionPath(filePath: string, projectRoot: string): void;
62
+ /**
63
+ * The constitution write plan for one project.
64
+ *
65
+ * `rulesRoot` is the directory the project's standards actually live in —
66
+ * `.peaks/standards` for the 2.0 canonical layout, `.claude/rules` for a
67
+ * project still carrying the 1.x tree — so the body points at the files that
68
+ * are really there.
69
+ */
70
+ export declare function buildConstitutionUpdate(input: {
71
+ readonly projectRoot: string;
72
+ readonly constitution: StandardsConstitution;
73
+ readonly language: StandardsLanguage;
74
+ readonly scripts: ProjectScripts;
75
+ readonly rulesRoot: string;
76
+ }): ConstitutionUpdate;
77
+ /**
78
+ * Create the constitution files that are absent. Never overwrites.
79
+ *
80
+ * Used by the layout migration (`standards migrate --from-claude-rules`),
81
+ * which brings a 1.x project onto the 2.0 canonical layout.
82
+ */
83
+ export declare function scaffoldConstitutionFiles(input: {
84
+ readonly projectRoot: string;
85
+ readonly constitution: StandardsConstitution;
86
+ readonly language: StandardsLanguage;
87
+ readonly scripts: ProjectScripts;
88
+ readonly rulesRoot: string;
89
+ }): readonly string[];