peaks-loop 4.1.18 → 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 (168) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +126 -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 +8 -9
  125. package/schemas/doctor-report.schema.json +1 -1
  126. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  127. package/skills/bee/peaks-prd/SKILL.md +5 -3
  128. package/skills/bee/peaks-qa/SKILL.md +4 -2
  129. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  130. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  131. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  132. package/skills/bee/peaks-rd/SKILL.md +4 -2
  133. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  134. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  135. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  136. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +4 -4
  137. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  138. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  139. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  140. package/skills/bee/peaks-sc/SKILL.md +4 -2
  141. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  142. package/skills/bee/peaks-txt/SKILL.md +5 -3
  143. package/skills/bee/peaks-ui/SKILL.md +6 -4
  144. package/skills/peaks-audit/SKILL.md +3 -1
  145. package/skills/peaks-code/SKILL.md +3 -1
  146. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  147. package/skills/peaks-code/references/completion-handoff.md +1 -1
  148. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  149. package/skills/peaks-code/references/micro-cycle.md +2 -2
  150. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  151. package/skills/peaks-code/references/runbook.md +4 -4
  152. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  153. package/skills/peaks-code/references/standards-preflight.md +7 -6
  154. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  155. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  156. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  157. package/skills/peaks-content/SKILL.md +3 -1
  158. package/skills/peaks-doctor/SKILL.md +3 -1
  159. package/skills/peaks-final-review/SKILL.md +3 -1
  160. package/skills/peaks-ide/SKILL.md +3 -1
  161. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  162. package/skills/peaks-race-code/SKILL.md +3 -1
  163. package/skills/peaks-resume/SKILL.md +3 -1
  164. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  165. package/skills/peaks-solo/SKILL.md +3 -1
  166. package/skills/peaks-sop/SKILL.md +4 -2
  167. package/skills/peaks-status/SKILL.md +3 -1
  168. package/skills/peaks-test/SKILL.md +3 -1
@@ -0,0 +1,199 @@
1
+ /**
2
+ * `src/services/standards/standards-constitution.ts`
3
+ *
4
+ * The constitution write plan: which instruction files the standards writer
5
+ * owns, what goes in them, and how a hand-written file is protected.
6
+ *
7
+ * THE PROTECTION RULE — one rule, two files, ONE planner. A file that already
8
+ * exists is never overwritten: absent → created; missing the managed block or
9
+ * the `@AGENTS.md` pointer → appended to; already carrying both → left alone;
10
+ * managed block differing → left for a human. `standards init` and `standards
11
+ * update` share this planner, so the two verbs cannot disagree.
12
+ */
13
+ import { existsSync, lstatSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
14
+ import { isAbsolute, relative, resolve } from 'node:path';
15
+ import { isExpectedFsMiss } from '../../shared/fs-utils.js';
16
+ import { AGENTS_MD_FILENAME, CLAUDE_MD_FILENAME, CLAUDE_MD_POINTER_LINE, renderAgentsMd, renderClaudeMdPointer } from './standards-render-agents.js';
17
+ import { renderManagedStandardsIndex } from './standards-render-common.js';
18
+ import { managedBlockMatches, planPointer, reviewSuggestions } from './standards-pointer.js';
19
+ /**
20
+ * The default shape: both files.
21
+ *
22
+ * `AGENTS.md` is read natively by 20+ coding agents; `CLAUDE.md` is what
23
+ * Claude Code reads, and it imports the body. Emitting both covers every
24
+ * reader without a per-tool configuration step.
25
+ */
26
+ export const DEFAULT_CONSTITUTION = {
27
+ bodyFile: AGENTS_MD_FILENAME,
28
+ pointerFile: CLAUDE_MD_FILENAME
29
+ };
30
+ /** The JSON shape of a constitution update. */
31
+ export function summarizeConstitutionUpdate(update) {
32
+ return {
33
+ body: {
34
+ relativePath: update.body.relativePath,
35
+ status: update.body.status,
36
+ reviewSuggestions: update.body.reviewSuggestions
37
+ },
38
+ pointer: update.pointer === null
39
+ ? null
40
+ : {
41
+ relativePath: update.pointer.relativePath,
42
+ status: update.pointer.status,
43
+ reviewSuggestions: update.pointer.reviewSuggestions
44
+ }
45
+ };
46
+ }
47
+ /** True when the relative path names a constitution file the writer owns. */
48
+ export function isConstitutionPath(relativePath) {
49
+ return relativePath === AGENTS_MD_FILENAME || relativePath === CLAUDE_MD_FILENAME;
50
+ }
51
+ /** True when `childPath` is `parentPath` or lives under it. */
52
+ export function isInsidePath(childPath, parentPath) {
53
+ const rel = relative(parentPath, childPath);
54
+ return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
55
+ }
56
+ /**
57
+ * The write-target containment guard for a constitution file.
58
+ *
59
+ * A symlinked `CLAUDE.md` / `AGENTS.md`, or one that resolves outside the
60
+ * project root, is a write-target escape attempt and must be rejected before
61
+ * anything is written.
62
+ */
63
+ export function assertSafeConstitutionPath(filePath, projectRoot) {
64
+ if (!existsSync(filePath))
65
+ return;
66
+ if (lstatSync(filePath).isSymbolicLink() || !isInsidePath(realpathSync(filePath), projectRoot)) {
67
+ throw new Error('Project standards constitution files must stay inside the project root');
68
+ }
69
+ }
70
+ function readFileIfExists(path) {
71
+ if (!existsSync(path))
72
+ return null;
73
+ try {
74
+ return readFileSync(path, 'utf8');
75
+ }
76
+ catch (err) {
77
+ // Same narrowing as the repo's other IO reads: an expected FS miss
78
+ // (unreadable / vanished / is-a-directory) means "no readable file
79
+ // here"; every other IO error is a real defect and must surface.
80
+ if (isExpectedFsMiss(err))
81
+ return null;
82
+ throw err;
83
+ }
84
+ }
85
+ const MANAGED_BLOCK_START = '<!-- peaks-standards:index:start -->';
86
+ /** Assemble one constitution file's plan. */
87
+ function fileUpdate(input) {
88
+ return {
89
+ ...input,
90
+ appendBlock: input.appendBlock ?? '',
91
+ reviewSuggestions: input.reviewSuggestions ?? []
92
+ };
93
+ }
94
+ /**
95
+ * The four-state plan for ONE constitution file.
96
+ *
97
+ * planned — the file is absent; it will be created with body + block
98
+ * appended — the file exists and is missing what we own: the managed block,
99
+ * the pointer line, or both. The missing part is appended.
100
+ * existing — the file exists and already carries everything we own
101
+ * review — the file exists with a managed block that differs; a human decides
102
+ */
103
+ function buildFileUpdate(input) {
104
+ const filePath = resolve(input.projectRoot, input.relativePath);
105
+ const existingContent = readFileIfExists(filePath);
106
+ const common = { relativePath: input.relativePath, filePath };
107
+ if (existingContent === null) {
108
+ return fileUpdate({
109
+ ...common,
110
+ status: 'planned',
111
+ content: `${input.body.trimEnd()}\n\n${input.managedBlock}`
112
+ });
113
+ }
114
+ const pointer = planPointer(existingContent, input.pointerLine);
115
+ const blockStart = existingContent.indexOf(MANAGED_BLOCK_START);
116
+ if (blockStart < 0) {
117
+ const addition = input.managedBlock + (pointer.needed ? `\n${pointer.line}\n` : '');
118
+ return fileUpdate({
119
+ ...common,
120
+ status: 'appended',
121
+ content: `${existingContent.trimEnd()}\n\n${addition}`,
122
+ appendBlock: `\n\n${addition}`
123
+ });
124
+ }
125
+ if (managedBlockMatches(existingContent.slice(blockStart), input.managedBlock, input.pointerLine)) {
126
+ if (!pointer.needed) {
127
+ return fileUpdate({
128
+ ...common,
129
+ status: 'existing',
130
+ content: existingContent
131
+ });
132
+ }
133
+ const addition = `${pointer.line}\n`;
134
+ return fileUpdate({
135
+ ...common,
136
+ status: 'appended',
137
+ content: `${existingContent.trimEnd()}\n\n${addition}`,
138
+ appendBlock: `\n${addition}`
139
+ });
140
+ }
141
+ return fileUpdate({
142
+ ...common,
143
+ status: 'review',
144
+ content: existingContent,
145
+ reviewSuggestions: reviewSuggestions(input.relativePath, pointer.needed)
146
+ });
147
+ }
148
+ /**
149
+ * The constitution write plan for one project.
150
+ *
151
+ * `rulesRoot` is the directory the project's standards actually live in —
152
+ * `.peaks/standards` for the 2.0 canonical layout, `.claude/rules` for a
153
+ * project still carrying the 1.x tree — so the body points at the files that
154
+ * are really there.
155
+ */
156
+ export function buildConstitutionUpdate(input) {
157
+ const managedBlock = renderManagedStandardsIndex(input.language, input.rulesRoot);
158
+ const body = buildFileUpdate({
159
+ projectRoot: input.projectRoot,
160
+ relativePath: input.constitution.bodyFile,
161
+ body: renderAgentsMd(input.language, input.scripts, input.rulesRoot),
162
+ managedBlock,
163
+ pointerLine: null
164
+ });
165
+ const pointerFile = input.constitution.pointerFile;
166
+ const pointer = pointerFile === null
167
+ ? null
168
+ : buildFileUpdate({
169
+ projectRoot: input.projectRoot,
170
+ relativePath: pointerFile,
171
+ body: renderClaudeMdPointer(),
172
+ managedBlock,
173
+ pointerLine: CLAUDE_MD_POINTER_LINE
174
+ });
175
+ return { body, pointer };
176
+ }
177
+ /**
178
+ * Create the constitution files that are absent. Never overwrites.
179
+ *
180
+ * Used by the layout migration (`standards migrate --from-claude-rules`),
181
+ * which brings a 1.x project onto the 2.0 canonical layout.
182
+ */
183
+ export function scaffoldConstitutionFiles(input) {
184
+ const written = [];
185
+ const bodyPath = resolve(input.projectRoot, input.constitution.bodyFile);
186
+ if (!existsSync(bodyPath)) {
187
+ writeFileSync(bodyPath, renderAgentsMd(input.language, input.scripts, input.rulesRoot), 'utf8');
188
+ written.push(input.constitution.bodyFile);
189
+ }
190
+ const pointerFile = input.constitution.pointerFile;
191
+ if (pointerFile !== null) {
192
+ const pointerPath = resolve(input.projectRoot, pointerFile);
193
+ if (!existsSync(pointerPath)) {
194
+ writeFileSync(pointerPath, renderClaudeMdPointer(), 'utf8');
195
+ written.push(pointerFile);
196
+ }
197
+ }
198
+ return written;
199
+ }
@@ -0,0 +1,37 @@
1
+ import type { ConstitutionFileUpdate } from './standards-constitution.js';
2
+ import type { StandardsWriteStatus } from './project-standards-service.js';
3
+ /**
4
+ * Create a file that must not exist yet.
5
+ *
6
+ * `O_EXCL` is the guard: the write fails if the file appeared between the
7
+ * plan and the write, so a hand-written `CLAUDE.md` / `AGENTS.md` is never
8
+ * clobbered. `O_NOFOLLOW` refuses to write through a symlink.
9
+ */
10
+ export declare function writeNewFile(path: string, content: string): void;
11
+ /** Append to a file that already exists, refusing to follow a symlink. */
12
+ export declare function appendExistingFile(path: string, content: string): void;
13
+ /**
14
+ * Apply ONE constitution file's plan: create it when absent, append the
15
+ * managed block when it has none, leave it alone otherwise.
16
+ *
17
+ * The `prevalidate` callback is the caller's write-target guard — it lives
18
+ * with the other containment checks, and this module does not need to know
19
+ * what they are.
20
+ */
21
+ export declare function applyConstitutionFile(input: {
22
+ readonly file: ConstitutionFileUpdate;
23
+ readonly writtenFiles: string[];
24
+ readonly appendedFiles: string[];
25
+ readonly prevalidate: (file: ConstitutionFileUpdate) => void;
26
+ }): StandardsWriteStatus;
27
+ /**
28
+ * Detect whether the consumer project still carries a 1.x "thick"
29
+ * `.claude/rules/` tree (the legacy layout that 2.0 migrates away
30
+ * from). A project with thick 1.x rules should NOT be silently
31
+ * re-initialised into the 2.0 `.peaks/standards/` layout; the
32
+ * caller should explicitly run `peaks standards migrate --from-claude-rules`
33
+ * instead. A new project (no `.claude/rules/` tree, or only a
34
+ * previously-thinned 2-line-pointer tree) is safe to bootstrap
35
+ * directly into the 2.0 canonical layout.
36
+ */
37
+ export declare function hasThickOneXClaudeRules(projectRoot: string): boolean;
@@ -0,0 +1,138 @@
1
+ /**
2
+ * `src/services/standards/standards-files.ts`
3
+ *
4
+ * The file-level operations of the standards writer.
5
+ *
6
+ * They live here rather than in `project-standards-service.ts` because that
7
+ * file is already over the repo's file-size cap, and every line added to an
8
+ * over-cap file raises the whole-tree excess-lines ratchet. The rule the
9
+ * repo follows is "the cap is a permission, not a target" — a new concern
10
+ * goes into a new module until the big one is split.
11
+ */
12
+ import { closeSync, constants, existsSync, lstatSync, openSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
13
+ import { join, resolve } from 'node:path';
14
+ /**
15
+ * The mode a newly created standards file is written with.
16
+ *
17
+ * Owner-only: the files are project instruction bodies, not world-readable
18
+ * artefacts, and the mode is spelled once so the number is not a literal at
19
+ * the call site.
20
+ */
21
+ const NEW_FILE_MODE = 0o600;
22
+ /**
23
+ * Create a file that must not exist yet.
24
+ *
25
+ * `O_EXCL` is the guard: the write fails if the file appeared between the
26
+ * plan and the write, so a hand-written `CLAUDE.md` / `AGENTS.md` is never
27
+ * clobbered. `O_NOFOLLOW` refuses to write through a symlink.
28
+ */
29
+ export function writeNewFile(path, content) {
30
+ const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, NEW_FILE_MODE);
31
+ try {
32
+ writeFileSync(fd, content, 'utf8');
33
+ }
34
+ finally {
35
+ closeSync(fd);
36
+ }
37
+ }
38
+ /** Append to a file that already exists, refusing to follow a symlink. */
39
+ export function appendExistingFile(path, content) {
40
+ const fd = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW);
41
+ try {
42
+ writeFileSync(fd, content, 'utf8');
43
+ }
44
+ finally {
45
+ closeSync(fd);
46
+ }
47
+ }
48
+ /**
49
+ * Apply ONE constitution file's plan: create it when absent, append the
50
+ * managed block when it has none, leave it alone otherwise.
51
+ *
52
+ * The `prevalidate` callback is the caller's write-target guard — it lives
53
+ * with the other containment checks, and this module does not need to know
54
+ * what they are.
55
+ */
56
+ export function applyConstitutionFile(input) {
57
+ input.prevalidate(input.file);
58
+ const targetPath = resolve(input.file.filePath);
59
+ if (input.file.status === 'planned') {
60
+ writeNewFile(targetPath, input.file.content);
61
+ input.writtenFiles.push(input.file.relativePath);
62
+ return 'written';
63
+ }
64
+ if (input.file.status === 'appended') {
65
+ appendExistingFile(targetPath, input.file.appendBlock);
66
+ input.appendedFiles.push(input.file.relativePath);
67
+ }
68
+ return input.file.status;
69
+ }
70
+ /** The marker a 2.x pointer file carries. */
71
+ const POINTER_MARKER = 'Canonical peaks-loop 2.0 rules live at:';
72
+ /**
73
+ * Is this file a 1.x rules file — real content, not a 2-line pointer?
74
+ *
75
+ * An unreadable file counts as "not thick": the probe reports what it can
76
+ * prove, not what it failed to read.
77
+ */
78
+ function isThickRulesFile(entryPath, entry) {
79
+ if (!entry.endsWith('.md'))
80
+ return false;
81
+ try {
82
+ return !readFileSync(entryPath, 'utf8').includes(POINTER_MARKER);
83
+ }
84
+ catch {
85
+ return false;
86
+ }
87
+ }
88
+ /**
89
+ * Detect whether the consumer project still carries a 1.x "thick"
90
+ * `.claude/rules/` tree (the legacy layout that 2.0 migrates away
91
+ * from). A project with thick 1.x rules should NOT be silently
92
+ * re-initialised into the 2.0 `.peaks/standards/` layout; the
93
+ * caller should explicitly run `peaks standards migrate --from-claude-rules`
94
+ * instead. A new project (no `.claude/rules/` tree, or only a
95
+ * previously-thinned 2-line-pointer tree) is safe to bootstrap
96
+ * directly into the 2.0 canonical layout.
97
+ */
98
+ export function hasThickOneXClaudeRules(projectRoot) {
99
+ const claudeRulesDir = join(projectRoot, '.claude', 'rules');
100
+ if (!existsSync(claudeRulesDir))
101
+ return false;
102
+ if (!lstatSync(claudeRulesDir).isDirectory())
103
+ return false;
104
+ // Walk one level deep; if any .md file under common/ or
105
+ // typescript/ (or the language pack) exists and is NOT a
106
+ // 2-line pointer, treat the tree as thick 1.x.
107
+ const stack = [claudeRulesDir];
108
+ let dir = stack.pop();
109
+ while (dir !== undefined) {
110
+ let entries;
111
+ try {
112
+ entries = readdirSync(dir);
113
+ }
114
+ catch {
115
+ return false;
116
+ }
117
+ for (const entry of entries) {
118
+ if (entry.startsWith('.'))
119
+ continue;
120
+ const entryPath = join(dir, entry);
121
+ let entryStat;
122
+ try {
123
+ entryStat = lstatSync(entryPath);
124
+ }
125
+ catch {
126
+ continue;
127
+ }
128
+ if (entryStat.isDirectory()) {
129
+ stack.push(entryPath);
130
+ }
131
+ else if (isThickRulesFile(entryPath, entry)) {
132
+ return true;
133
+ }
134
+ }
135
+ dir = stack.pop();
136
+ }
137
+ return false;
138
+ }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * `src/services/standards/standards-pointer.ts`
3
+ *
4
+ * The `@AGENTS.md` pointer line, and the rules that govern it.
5
+ *
6
+ * WHY A MODULE OF ITS OWN. The pointer is not prose — it is a SYNTAX CONTRACT
7
+ * with another tool. Claude Code imports `@AGENTS.md` only when the path
8
+ * stands on a line of its own, unbackticked and unquoted, and it imports it
9
+ * only once: a second occurrence loads the body twice. Every mistake here is
10
+ * SILENT. The file still reads fine, the managed block still says
11
+ * "Constitution: AGENTS.md", and the import simply does not happen — which is
12
+ * how a managed block ends up making a claim that is true for every tool
13
+ * except the one it was written for.
14
+ *
15
+ * THE THREE RULES, IN ONE PLACE:
16
+ * 1. A pointer is a WHOLE LINE. A prose mention of `@AGENTS.md` — backticked,
17
+ * quoted, or mid-sentence — is not a pointer.
18
+ * 2. There is at most ONE. A file that already carries one is never given
19
+ * a second.
20
+ * 3. It travels with the managed block: a file that has the block has the
21
+ * pointer too, so the block's claim is never made to a reader that
22
+ * cannot act on it.
23
+ *
24
+ * The spelling lives in `standards-render-agents.ts`, next to the renderer
25
+ * that prints it, and is re-exported here — so the writer that adds the line
26
+ * and the planner that looks for it cannot disagree about what the line is.
27
+ */
28
+ import { CLAUDE_MD_POINTER_LINE } from './standards-render-agents.js';
29
+ export { CLAUDE_MD_POINTER_LINE };
30
+ /**
31
+ * True when the file already carries the pointer on a line of its own.
32
+ *
33
+ * A whole-line match, NOT `indexOf('@AGENTS.md')`: a prose mention would
34
+ * satisfy a substring search, the writer would then skip the real pointer,
35
+ * and Claude Code would end up with no import at all.
36
+ */
37
+ export declare function hasPointerLine(content: string): boolean;
38
+ /** What the pointer line contributes to one file's write plan. */
39
+ export type PointerPlan = {
40
+ /** The file must be given the pointer line. */
41
+ readonly needed: boolean;
42
+ /** The line to add; empty when none is needed. */
43
+ readonly line: string;
44
+ };
45
+ /**
46
+ * The pointer line's contribution to one file's write plan.
47
+ *
48
+ * `pointerLine` is `null` for the body file: `AGENTS.md` needs no import, and
49
+ * a body that pointed at itself would be circular.
50
+ */
51
+ export declare function planPointer(content: string, pointerLine: string | null): PointerPlan;
52
+ /**
53
+ * The review suggestion a `review` state owes the operator.
54
+ *
55
+ * The managed block says the constitution lives in `AGENTS.md`; without the
56
+ * pointer line Claude Code never reads that file, so the block's claim is
57
+ * true for every other tool and false for the one it was written for. A review
58
+ * state writes nothing, so this is where the operator is told.
59
+ */
60
+ export declare function pointerReviewSuggestion(relativePath: string): string;
61
+ /** The suggestions a `review` state owes the operator. */
62
+ export declare function reviewSuggestions(relativePath: string, needsPointer: boolean): readonly string[];
63
+ /**
64
+ * Does the text that follows the managed block's start marker still count as
65
+ * "the block this writer would write"?
66
+ *
67
+ * The managed block may be followed by the pointer line, with any number of
68
+ * blank lines between the two, and the file still counts as up to date — the
69
+ * block is the same block, and the pointer is where it belongs. Anything else
70
+ * after the block is the user's own text, and the user's own text is a
71
+ * review, never an overwrite.
72
+ */
73
+ export declare function managedBlockMatches(tail: string, managedBlock: string, pointerLine: string | null): boolean;
@@ -0,0 +1,98 @@
1
+ /**
2
+ * `src/services/standards/standards-pointer.ts`
3
+ *
4
+ * The `@AGENTS.md` pointer line, and the rules that govern it.
5
+ *
6
+ * WHY A MODULE OF ITS OWN. The pointer is not prose — it is a SYNTAX CONTRACT
7
+ * with another tool. Claude Code imports `@AGENTS.md` only when the path
8
+ * stands on a line of its own, unbackticked and unquoted, and it imports it
9
+ * only once: a second occurrence loads the body twice. Every mistake here is
10
+ * SILENT. The file still reads fine, the managed block still says
11
+ * "Constitution: AGENTS.md", and the import simply does not happen — which is
12
+ * how a managed block ends up making a claim that is true for every tool
13
+ * except the one it was written for.
14
+ *
15
+ * THE THREE RULES, IN ONE PLACE:
16
+ * 1. A pointer is a WHOLE LINE. A prose mention of `@AGENTS.md` — backticked,
17
+ * quoted, or mid-sentence — is not a pointer.
18
+ * 2. There is at most ONE. A file that already carries one is never given
19
+ * a second.
20
+ * 3. It travels with the managed block: a file that has the block has the
21
+ * pointer too, so the block's claim is never made to a reader that
22
+ * cannot act on it.
23
+ *
24
+ * The spelling lives in `standards-render-agents.ts`, next to the renderer
25
+ * that prints it, and is re-exported here — so the writer that adds the line
26
+ * and the planner that looks for it cannot disagree about what the line is.
27
+ */
28
+ import { CLAUDE_MD_POINTER_LINE } from './standards-render-agents.js';
29
+ export { CLAUDE_MD_POINTER_LINE };
30
+ /**
31
+ * True when the file already carries the pointer on a line of its own.
32
+ *
33
+ * A whole-line match, NOT `indexOf('@AGENTS.md')`: a prose mention would
34
+ * satisfy a substring search, the writer would then skip the real pointer,
35
+ * and Claude Code would end up with no import at all.
36
+ */
37
+ export function hasPointerLine(content) {
38
+ return content.split('\n').some((line) => line.trim() === CLAUDE_MD_POINTER_LINE);
39
+ }
40
+ /**
41
+ * The pointer line's contribution to one file's write plan.
42
+ *
43
+ * `pointerLine` is `null` for the body file: `AGENTS.md` needs no import, and
44
+ * a body that pointed at itself would be circular.
45
+ */
46
+ export function planPointer(content, pointerLine) {
47
+ if (pointerLine === null)
48
+ return { needed: false, line: '' };
49
+ if (hasPointerLine(content))
50
+ return { needed: false, line: '' };
51
+ return { needed: true, line: pointerLine };
52
+ }
53
+ /**
54
+ * The review suggestion a `review` state owes the operator.
55
+ *
56
+ * The managed block says the constitution lives in `AGENTS.md`; without the
57
+ * pointer line Claude Code never reads that file, so the block's claim is
58
+ * true for every other tool and false for the one it was written for. A review
59
+ * state writes nothing, so this is where the operator is told.
60
+ */
61
+ export function pointerReviewSuggestion(relativePath) {
62
+ return (`Existing ${relativePath} has no standalone \`${CLAUDE_MD_POINTER_LINE}\` line: ` +
63
+ `the managed block's constitution claim does not reach Claude Code until that line is added.`);
64
+ }
65
+ /** The suggestions a `review` state owes the operator. */
66
+ export function reviewSuggestions(relativePath, needsPointer) {
67
+ return [
68
+ `Existing ${relativePath} already has a managed standards block. Review the managed block manually before changing it.`,
69
+ ...(needsPointer ? [pointerReviewSuggestion(relativePath)] : [])
70
+ ];
71
+ }
72
+ /**
73
+ * The whitespace-insensitive form of a text: every run of whitespace around a
74
+ * line break collapses into the line break itself.
75
+ *
76
+ * It is used ONLY for comparisons, never for what is written. The writer owns
77
+ * the bytes; the comparison owns the question "are these the same lines?".
78
+ */
79
+ function normalizeLines(text) {
80
+ return text.replace(/\s*\n\s*/g, '\n');
81
+ }
82
+ /**
83
+ * Does the text that follows the managed block's start marker still count as
84
+ * "the block this writer would write"?
85
+ *
86
+ * The managed block may be followed by the pointer line, with any number of
87
+ * blank lines between the two, and the file still counts as up to date — the
88
+ * block is the same block, and the pointer is where it belongs. Anything else
89
+ * after the block is the user's own text, and the user's own text is a
90
+ * review, never an overwrite.
91
+ */
92
+ export function managedBlockMatches(tail, managedBlock, pointerLine) {
93
+ const expected = normalizeLines(managedBlock.trimEnd());
94
+ const actual = normalizeLines(tail.trimEnd());
95
+ if (actual === expected)
96
+ return true;
97
+ return pointerLine !== null && actual === `${expected}\n${pointerLine}`;
98
+ }
@@ -0,0 +1,34 @@
1
+ import type { ProjectScripts } from './project-scripts.js';
2
+ import type { StandardsLanguage } from './project-standards-service.js';
3
+ /** The shared, cross-tool instruction body. */
4
+ export declare const AGENTS_MD_FILENAME = "AGENTS.md";
5
+ /** The IDE-native file that imports the body. */
6
+ export declare const CLAUDE_MD_FILENAME = "CLAUDE.md";
7
+ /**
8
+ * The Claude Code import line — `@AGENTS.md`, on a line of its own.
9
+ *
10
+ * It is declared here, next to the renderer that prints it, because the line
11
+ * is a SYNTAX CONTRACT and not prose: the writer that adds it and the planner
12
+ * that looks for it must agree on its exact spelling, and one declaration is
13
+ * the only way they can. `standards-pointer.ts` owns the rules around it.
14
+ */
15
+ export declare const CLAUDE_MD_POINTER_LINE = "@AGENTS.md";
16
+ /**
17
+ * The AGENTS.md body.
18
+ *
19
+ * Kept short on purpose: the whole file is loaded on every turn, and a
20
+ * research finding behind this layout says an LLM-generated instruction file
21
+ * that is padded with derivable facts lowers task success and raises
22
+ * reasoning cost. Facts the agent can read off `package.json` (the build
23
+ * tool, the dependency list) are therefore NOT repeated here — they live in
24
+ * the standards files this body points at.
25
+ */
26
+ export declare function renderAgentsMd(language: StandardsLanguage, scripts: ProjectScripts, rulesRoot: string): string;
27
+ /**
28
+ * The CLAUDE.md pointer.
29
+ *
30
+ * `@AGENTS.md` is the import. It must stay unbackticked and unquoted — Claude
31
+ * Code skips code spans and does not import a quoted path — and it must be the
32
+ * only such occurrence in the file, or the body is loaded twice.
33
+ */
34
+ export declare function renderClaudeMdPointer(): string;