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.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +256 -0
- package/README-en.md +6 -0
- package/README.md +5 -0
- package/contracts/test-style-contract.md +14 -5
- package/dist/cli/commands/audit-red-lines-runners.js +6 -1
- package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
- package/dist/cli/commands/best-practice-scan-collision.js +115 -0
- package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
- package/dist/cli/commands/best-practice-scan-command.js +9 -18
- package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
- package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
- package/dist/cli/commands/code-auto-compact-command.js +26 -18
- package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
- package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
- package/dist/cli/commands/core/skill-presence-commands.js +42 -74
- package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
- package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
- package/dist/cli/commands/core/standards-init-command.js +44 -8
- package/dist/cli/commands/core/standards-migrate-command.js +5 -4
- package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
- package/dist/cli/commands/dispatch-dag-runners.js +11 -1
- package/dist/cli/commands/dispatch-detached-branch.js +19 -1
- package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
- package/dist/cli/commands/mut-commands-helpers.js +197 -4
- package/dist/cli/commands/mut-commands.d.ts +9 -1
- package/dist/cli/commands/mut-commands.js +82 -154
- package/dist/cli/commands/preferences-commands.js +27 -2
- package/dist/cli/commands/scan-scope-helpers.js +2 -2
- package/dist/services/24h-mode/auto-engage.d.ts +11 -3
- package/dist/services/24h-mode/auto-engage.js +14 -6
- package/dist/services/artifacts/artifact-templates.js +10 -0
- package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
- package/dist/services/artifacts/backcompat-acceptance.js +8 -7
- package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
- package/dist/services/artifacts/rd-transition-gates.js +96 -19
- package/dist/services/artifacts/request-artifact-service.js +6 -6
- package/dist/services/audit/enforcers/lint-output-style.js +14 -2
- package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
- package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
- package/dist/services/audit/static-service.js +4 -4
- package/dist/services/code/auto-compact-history.d.ts +6 -1
- package/dist/services/code/auto-compact-history.js +6 -1
- package/dist/services/code/auto-compact-modes.d.ts +60 -14
- package/dist/services/code/auto-compact-modes.js +75 -20
- package/dist/services/code/auto-compact-profile.d.ts +23 -0
- package/dist/services/code/auto-compact-profile.js +51 -0
- package/dist/services/compact-history/compact-history-service.d.ts +6 -1
- package/dist/services/compact-history/compact-history-service.js +5 -1
- package/dist/services/context/auto-compact-types.d.ts +7 -5
- package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
- package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
- package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
- package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
- package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
- package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
- package/dist/services/hooks/hook-payload-cwd.js +11 -4
- package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
- package/dist/services/hooks/presence-marker-detector.js +21 -19
- package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
- package/dist/services/ide/adapters/codex-adapter.js +23 -7
- package/dist/services/ide/adapters/cursor-adapter.js +23 -7
- package/dist/services/mode/mode-status-service.d.ts +26 -27
- package/dist/services/mode/mode-status-service.js +36 -60
- package/dist/services/preferences/preferences-types.d.ts +30 -0
- package/dist/services/preferences/preferences-types.js +13 -0
- package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
- package/dist/services/scan/acceptance-coverage-service.js +157 -52
- package/dist/services/scan/rid-change-claims.d.ts +15 -0
- package/dist/services/scan/rid-change-claims.js +116 -0
- package/dist/services/skills/presence-caller-id.d.ts +51 -0
- package/dist/services/skills/presence-caller-id.js +43 -0
- package/dist/services/skills/presence-gate.d.ts +65 -0
- package/dist/services/skills/presence-gate.js +113 -0
- package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
- package/dist/services/skills/presence-lease-resolver.js +114 -0
- package/dist/services/skills/presence-lease-selection.d.ts +91 -0
- package/dist/services/skills/presence-lease-selection.js +135 -0
- package/dist/services/skills/presence-lease-service.d.ts +3 -11
- package/dist/services/skills/presence-lease-service.js +34 -87
- package/dist/services/skills/presence-lease-store.d.ts +33 -0
- package/dist/services/skills/presence-lease-store.js +94 -0
- package/dist/services/skills/presence-lease-types.d.ts +31 -0
- package/dist/services/skills/presence-lease-types.js +27 -0
- package/dist/services/skills/presence-role.d.ts +35 -0
- package/dist/services/skills/presence-role.js +72 -0
- package/dist/services/skills/skill-presence-service.d.ts +39 -9
- package/dist/services/skills/skill-presence-service.js +143 -174
- package/dist/services/skills/skill-presence-write.d.ts +60 -0
- package/dist/services/skills/skill-presence-write.js +74 -0
- package/dist/services/skills/skill-statusline-service.js +7 -7
- package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
- package/dist/services/standards/ide-aware-standards-service.js +45 -20
- package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
- package/dist/services/standards/migrate-claude-rules-service.js +18 -0
- package/dist/services/standards/migrate-service.d.ts +1 -1
- package/dist/services/standards/migrate-service.js +27 -7
- package/dist/services/standards/project-scripts.d.ts +25 -0
- package/dist/services/standards/project-scripts.js +116 -0
- package/dist/services/standards/project-standards-service.d.ts +23 -15
- package/dist/services/standards/project-standards-service.js +176 -243
- package/dist/services/standards/standards-constitution.d.ts +89 -0
- package/dist/services/standards/standards-constitution.js +199 -0
- package/dist/services/standards/standards-files.d.ts +37 -0
- package/dist/services/standards/standards-files.js +138 -0
- package/dist/services/standards/standards-pointer.d.ts +73 -0
- package/dist/services/standards/standards-pointer.js +98 -0
- package/dist/services/standards/standards-render-agents.d.ts +34 -0
- package/dist/services/standards/standards-render-agents.js +149 -0
- package/dist/services/standards/standards-render-common.d.ts +38 -1
- package/dist/services/standards/standards-render-common.js +44 -7
- package/dist/services/standards/standards-render.d.ts +1 -3
- package/dist/services/standards/standards-render.js +6 -87
- package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
- package/dist/services/workflow/workflow-graph-ensure.js +97 -0
- package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
- package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
- package/dist/services/workspace/generated-artifacts-content.js +167 -0
- package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
- package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
- package/dist/services/workspace/runtime-layout.d.ts +64 -0
- package/dist/services/workspace/runtime-layout.js +62 -0
- package/output-styles/peaks-skill-swarm.md +18 -2
- package/package.json +9 -9
- package/schemas/doctor-report.schema.json +1 -1
- package/scripts/canonical-store-report.mjs +84 -0
- package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
- package/skills/bee/peaks-prd/SKILL.md +5 -3
- package/skills/bee/peaks-qa/SKILL.md +4 -2
- package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
- package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
- package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
- package/skills/bee/peaks-rd/SKILL.md +4 -2
- package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
- package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
- package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
- package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +4 -4
- package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
- package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
- package/skills/bee/peaks-reviewer/SKILL.md +3 -1
- package/skills/bee/peaks-sc/SKILL.md +4 -2
- package/skills/bee/peaks-security-audit/SKILL.md +3 -1
- package/skills/bee/peaks-txt/SKILL.md +5 -3
- package/skills/bee/peaks-ui/SKILL.md +6 -4
- package/skills/peaks-audit/SKILL.md +3 -1
- package/skills/peaks-code/SKILL.md +3 -1
- package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
- package/skills/peaks-code/references/completion-handoff.md +1 -1
- package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
- package/skills/peaks-code/references/micro-cycle.md +2 -2
- package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
- package/skills/peaks-code/references/runbook.md +4 -4
- package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
- package/skills/peaks-code/references/standards-preflight.md +7 -6
- package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
- package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
- package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
- package/skills/peaks-content/SKILL.md +3 -1
- package/skills/peaks-doctor/SKILL.md +3 -1
- package/skills/peaks-final-review/SKILL.md +3 -1
- package/skills/peaks-ide/SKILL.md +3 -1
- package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
- package/skills/peaks-race-code/SKILL.md +3 -1
- package/skills/peaks-resume/SKILL.md +3 -1
- package/skills/peaks-slice-decompose/SKILL.md +3 -1
- package/skills/peaks-solo/SKILL.md +3 -1
- package/skills/peaks-sop/SKILL.md +4 -2
- package/skills/peaks-status/SKILL.md +3 -1
- 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;
|