peaks-loop 4.1.17 → 4.1.19
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +269 -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 +71 -40
- package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
- package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
- package/dist/cli/commands/code-gate-command.d.ts +4 -4
- package/dist/cli/commands/code-gate-command.js +4 -4
- 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/skill-registry-commands.js +32 -0
- package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
- package/dist/cli/commands/core/skill-store-report.js +79 -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/dispatch-prompt-composition.js +7 -2
- package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
- package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
- package/dist/cli/commands/hooks-commands.js +36 -7
- package/dist/cli/commands/hooks-uninstall-command.js +5 -5
- 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-orchestrator.js +7 -5
- package/dist/services/code/auto-compact-profile.d.ts +23 -0
- package/dist/services/code/auto-compact-profile.js +51 -0
- package/dist/services/code/auto-compact-run-types.d.ts +8 -4
- 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/dispatch/dispatch-ledger-reader.d.ts +13 -0
- package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
- package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
- package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
- 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 +4 -0
- package/dist/services/doctor/doctor-service/types.d.ts +12 -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/pre-tool-code-gate.d.ts +4 -4
- package/dist/services/hooks/pre-tool-code-gate.js +4 -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/session/getSessionDir.d.ts +13 -0
- package/dist/services/session/getSessionDir.js +7 -1
- package/dist/services/skills/hooks-settings-types.d.ts +17 -21
- 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/skills/sync-service-support.d.ts +27 -0
- package/dist/services/skills/sync-service.js +1 -0
- 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-inflight-probe.d.ts +68 -31
- package/dist/services/workflow/workflow-inflight-probe.js +163 -75
- 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 +10 -9
- package/schemas/doctor-report.schema.json +1 -1
- package/scripts/canonical-store-fs.mjs +112 -0
- package/scripts/canonical-store-link.mjs +13 -22
- package/scripts/canonical-store-marker.mjs +241 -0
- package/scripts/canonical-store.mjs +119 -141
- package/scripts/install-skills-bundles.mjs +56 -13
- package/scripts/install-skills-fs.mjs +73 -0
- package/scripts/install-skills-output-styles.mjs +8 -2
- package/scripts/install-skills-report.mjs +19 -0
- package/scripts/install-skills.mjs +9 -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 +24 -5
- 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 +4 -2
- 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 +9 -4
- 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
|
@@ -14,8 +14,14 @@ import { join } from 'node:path';
|
|
|
14
14
|
import { reconcileCanonicalEntry } from './canonical-store.mjs';
|
|
15
15
|
import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
|
|
16
16
|
import { pruneBundledEntries } from './canonical-store-prune.mjs';
|
|
17
|
-
import {
|
|
18
|
-
import {
|
|
17
|
+
import { collectStoreOnlyEntries } from './canonical-store-report.mjs';
|
|
18
|
+
import { createInstallResult, finalizeInstallResult } from './install-skills-report.mjs';
|
|
19
|
+
import {
|
|
20
|
+
createInstallRootValidator,
|
|
21
|
+
prepareInstallRoot,
|
|
22
|
+
readPackageVersion,
|
|
23
|
+
resolvePackageRoot
|
|
24
|
+
} from './install-skills-fs.mjs';
|
|
19
25
|
import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
|
|
20
26
|
|
|
21
27
|
/**
|
|
@@ -71,6 +77,11 @@ function isSkillSource(sourcePath) {
|
|
|
71
77
|
export function installBundledSkills(options = {}) {
|
|
72
78
|
const packageRoot = resolvePackageRoot(options);
|
|
73
79
|
const skillsRoot = join(packageRoot, 'skills');
|
|
80
|
+
// The version of the package that owns `skills/<name>`. It is stamped into
|
|
81
|
+
// every canonical copy's sidecar, and it is what makes a store frozen at an
|
|
82
|
+
// old release KNOWABLY stale instead of merely different.
|
|
83
|
+
const packageVersion = readPackageVersion(packageRoot);
|
|
84
|
+
const dryRun = options.dryRun === true;
|
|
74
85
|
|
|
75
86
|
if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
|
|
76
87
|
return createInstallResult();
|
|
@@ -88,8 +99,14 @@ export function installBundledSkills(options = {}) {
|
|
|
88
99
|
|
|
89
100
|
const installed = [];
|
|
90
101
|
const skipped = [];
|
|
91
|
-
|
|
92
|
-
|
|
102
|
+
// What the STORE holds per entry, as found — `current`, `stale`, `unmanaged`,
|
|
103
|
+
// `retired` or `absent`. It is the report the install used to leave in a return
|
|
104
|
+
// value nobody read, and it is what tells a caller (and a human) which entries are
|
|
105
|
+
// behind the installed release before anything is repaired.
|
|
106
|
+
const entries = [];
|
|
107
|
+
// The install root: a real run creates it and guards it, a dry run does neither —
|
|
108
|
+
// a dry run that leaves a directory behind is not a dry run.
|
|
109
|
+
const validateSkillsRoot = prepareInstallRoot(targetRoot, 'Peaks skills', dryRun);
|
|
93
110
|
|
|
94
111
|
const candidates = collectSkillCandidates(skillsRoot);
|
|
95
112
|
|
|
@@ -111,10 +128,19 @@ export function installBundledSkills(options = {}) {
|
|
|
111
128
|
kind: 'skills',
|
|
112
129
|
name: skillName,
|
|
113
130
|
sourcePath,
|
|
114
|
-
linkPath: targetPath
|
|
131
|
+
linkPath: targetPath,
|
|
132
|
+
version: packageVersion,
|
|
133
|
+
dryRun
|
|
115
134
|
});
|
|
116
135
|
validateSkillsRoot();
|
|
117
136
|
|
|
137
|
+
entries.push({
|
|
138
|
+
name: skillName,
|
|
139
|
+
state: reconciled.state,
|
|
140
|
+
action: reconciled.action,
|
|
141
|
+
version: reconciled.version ?? null,
|
|
142
|
+
reason: reconciled.reason ?? null
|
|
143
|
+
});
|
|
118
144
|
if (reconciled.linkAction === 'skipped') {
|
|
119
145
|
skipped.push(skillName);
|
|
120
146
|
continue;
|
|
@@ -122,17 +148,32 @@ export function installBundledSkills(options = {}) {
|
|
|
122
148
|
installed.push(skillName);
|
|
123
149
|
}
|
|
124
150
|
|
|
151
|
+
// The store holds entries this package does NOT ship: the user's own skills, and
|
|
152
|
+
// the ones a retired release left behind. The report covers the STORE, not only
|
|
153
|
+
// the package's slice of it — a user's skill that the report never mentions is a
|
|
154
|
+
// skill the user cannot see is safe.
|
|
155
|
+
entries.push(
|
|
156
|
+
...collectStoreOnlyEntries({
|
|
157
|
+
kind: 'skills',
|
|
158
|
+
knownNames: candidates.map((candidate) => candidate.skillName),
|
|
159
|
+
dryRun
|
|
160
|
+
})
|
|
161
|
+
);
|
|
162
|
+
|
|
125
163
|
// Slice 3 — PRUNE. The loop above only ever ADDS. A skill removed from the
|
|
126
164
|
// package left its canonical copy, every IDE link and every sidecar on the
|
|
127
165
|
// user's machine forever, because nothing walked the DESTINATIONS. This does,
|
|
128
|
-
// and deletes only what `isManagedEntry` proves is ours.
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
166
|
+
// and deletes only what `isManagedEntry` proves is ours. A dry run deletes
|
|
167
|
+
// nothing — a plan that removes files is not a plan.
|
|
168
|
+
const pruned = dryRun
|
|
169
|
+
? []
|
|
170
|
+
: pruneBundledEntries({
|
|
171
|
+
kind: 'skills',
|
|
172
|
+
keepNames: candidates.map((candidate) => candidate.skillName),
|
|
173
|
+
linkDirs: [targetRoot]
|
|
174
|
+
}).pruned;
|
|
134
175
|
|
|
135
|
-
return { installed, skipped, pruned };
|
|
176
|
+
return finalizeInstallResult({ installed, skipped, pruned, entries }, dryRun);
|
|
136
177
|
}
|
|
137
178
|
|
|
138
179
|
/**
|
|
@@ -161,6 +202,7 @@ export function installBundledSkills(options = {}) {
|
|
|
161
202
|
export function installBundledAgents(options = {}) {
|
|
162
203
|
const packageRoot = resolvePackageRoot(options);
|
|
163
204
|
const agentsRoot = join(packageRoot, 'agents');
|
|
205
|
+
const packageVersion = readPackageVersion(packageRoot);
|
|
164
206
|
|
|
165
207
|
// Per-IDE env-var override (claude-code only today): PEAKS_CLAUDE_AGENTS_DIR.
|
|
166
208
|
// Universal escape hatch: PEAKS_SKIP_AGENT_INSTALL=1 (parallel to
|
|
@@ -207,7 +249,8 @@ export function installBundledAgents(options = {}) {
|
|
|
207
249
|
name: agentFileName,
|
|
208
250
|
sourcePath,
|
|
209
251
|
linkPath: join(targetRoot, agentFileName),
|
|
210
|
-
createFileLink: options.createFileLink
|
|
252
|
+
createFileLink: options.createFileLink,
|
|
253
|
+
version: packageVersion
|
|
211
254
|
});
|
|
212
255
|
validateAgentsRoot();
|
|
213
256
|
|
|
@@ -15,6 +15,7 @@ import {
|
|
|
15
15
|
fchmodSync,
|
|
16
16
|
fstatSync,
|
|
17
17
|
lstatSync,
|
|
18
|
+
mkdirSync,
|
|
18
19
|
openSync,
|
|
19
20
|
readFileSync,
|
|
20
21
|
renameSync,
|
|
@@ -86,10 +87,82 @@ export function createInstallRootValidator(targetRoot, label) {
|
|
|
86
87
|
};
|
|
87
88
|
}
|
|
88
89
|
|
|
90
|
+
/**
|
|
91
|
+
* The validator a DRY RUN uses.
|
|
92
|
+
*
|
|
93
|
+
* WHY IT IS NOT THE OTHER ONE. `createInstallRootValidator` exists to catch the
|
|
94
|
+
* install root being swapped under a write — it stats the root before the write
|
|
95
|
+
* and compares after. A dry run writes nothing, so there is no write to catch, and
|
|
96
|
+
* the root may not even EXIST: a dry run must not create it either, because a
|
|
97
|
+
* dry run that leaves a directory behind is not a dry run.
|
|
98
|
+
*/
|
|
99
|
+
export function createDryRunRootValidator() {
|
|
100
|
+
return () => undefined;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Prepare the install root for a run, and hand back the validator that guards it.
|
|
105
|
+
*
|
|
106
|
+
* A real run creates the directory and then guards it. A dry run does neither: it
|
|
107
|
+
* creates no directory and guards nothing, because there is no write to guard.
|
|
108
|
+
*
|
|
109
|
+
* WHY IT IS ONE FUNCTION. The choice belongs to the CALLER'S ONE CALL SITE: the
|
|
110
|
+
* install loop is already at the complexity the lint allows, and a second
|
|
111
|
+
* decision here would push it over for a difference that is exactly one branch
|
|
112
|
+
* wide.
|
|
113
|
+
*
|
|
114
|
+
* @param {string} targetRoot
|
|
115
|
+
* @param {string} label
|
|
116
|
+
* @param {boolean} dryRun
|
|
117
|
+
*/
|
|
118
|
+
export function prepareInstallRoot(targetRoot, label, dryRun) {
|
|
119
|
+
if (dryRun === true) {
|
|
120
|
+
return createDryRunRootValidator();
|
|
121
|
+
}
|
|
122
|
+
mkdirSync(targetRoot, { recursive: true });
|
|
123
|
+
return createInstallRootValidator(targetRoot, label);
|
|
124
|
+
}
|
|
125
|
+
|
|
89
126
|
export function resolvePackageRoot(options = {}) {
|
|
90
127
|
return resolve(options.packageRoot ?? join(dirname(fileURLToPath(import.meta.url)), '..'));
|
|
91
128
|
}
|
|
92
129
|
|
|
130
|
+
/**
|
|
131
|
+
* The version of the package that owns the bundled assets — the one number the
|
|
132
|
+
* canonical store's staleness decision compares against.
|
|
133
|
+
*
|
|
134
|
+
* WHERE IT IS READ. `package.json#version` of the package root, and the package
|
|
135
|
+
* root is wherever THIS script lives: `<install>/scripts/install-skills.mjs`
|
|
136
|
+
* gives `<install>`, which is the globally installed `peaks-loop` package on a
|
|
137
|
+
* user's machine and the repository checkout in a development tree. Both are
|
|
138
|
+
* the package that owns `skills/<name>`, so the same comparison is meaningful
|
|
139
|
+
* in both cases — the difference is only who moves the version.
|
|
140
|
+
*
|
|
141
|
+
* A package.json that is missing, unreadable or versionless answers null, and
|
|
142
|
+
* null means "no version to compare against" — the caller then decides by the
|
|
143
|
+
* bytes alone, which is the behaviour that predates the version stamp.
|
|
144
|
+
*
|
|
145
|
+
* @param {string} packageRoot
|
|
146
|
+
* @returns {string | null}
|
|
147
|
+
*/
|
|
148
|
+
export function readPackageVersion(packageRoot) {
|
|
149
|
+
const packageJsonPath = join(packageRoot, 'package.json');
|
|
150
|
+
if (!existsSync(packageJsonPath)) return null;
|
|
151
|
+
let parsed;
|
|
152
|
+
try {
|
|
153
|
+
parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
|
|
154
|
+
} catch (error) {
|
|
155
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
156
|
+
process.stderr.write(
|
|
157
|
+
`Peaks install: ${packageJsonPath} could not be read as JSON (${message}); ` +
|
|
158
|
+
'the canonical store cannot compare versions and will decide by content alone.\n'
|
|
159
|
+
);
|
|
160
|
+
return null;
|
|
161
|
+
}
|
|
162
|
+
const version = parsed?.version;
|
|
163
|
+
return typeof version === 'string' && version.length > 0 ? version : null;
|
|
164
|
+
}
|
|
165
|
+
|
|
93
166
|
export function isInsidePath(childPath, parentPath) {
|
|
94
167
|
const relativePath = relative(parentPath, childPath);
|
|
95
168
|
return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
|
|
@@ -13,7 +13,11 @@ import { join } from 'node:path';
|
|
|
13
13
|
|
|
14
14
|
import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
|
|
15
15
|
import { pruneBundledEntries } from './canonical-store-prune.mjs';
|
|
16
|
-
import {
|
|
16
|
+
import {
|
|
17
|
+
createInstallRootValidator,
|
|
18
|
+
readPackageVersion,
|
|
19
|
+
resolvePackageRoot
|
|
20
|
+
} from './install-skills-fs.mjs';
|
|
17
21
|
import { createInstallResult } from './install-skills-report.mjs';
|
|
18
22
|
import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
|
|
19
23
|
|
|
@@ -54,6 +58,7 @@ import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
|
|
|
54
58
|
export function installBundledOutputStyles(options = {}) {
|
|
55
59
|
const packageRoot = resolvePackageRoot(options);
|
|
56
60
|
const outputStylesRoot = join(packageRoot, 'output-styles');
|
|
61
|
+
const packageVersion = readPackageVersion(packageRoot);
|
|
57
62
|
|
|
58
63
|
if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(outputStylesRoot)) {
|
|
59
64
|
return createInstallResult();
|
|
@@ -94,7 +99,8 @@ export function installBundledOutputStyles(options = {}) {
|
|
|
94
99
|
name: outputStyleName,
|
|
95
100
|
sourcePath,
|
|
96
101
|
linkPath: join(targetRoot, outputStyleName),
|
|
97
|
-
createFileLink: options.createFileLink
|
|
102
|
+
createFileLink: options.createFileLink,
|
|
103
|
+
version: packageVersion
|
|
98
104
|
});
|
|
99
105
|
validateOutputStylesRoot();
|
|
100
106
|
|
|
@@ -12,6 +12,25 @@ export function createInstallResult() {
|
|
|
12
12
|
return { installed: [], skipped: [], pruned: [], fallbacks: [] };
|
|
13
13
|
}
|
|
14
14
|
|
|
15
|
+
/**
|
|
16
|
+
* The result a run reports, with the dry run's own rule applied.
|
|
17
|
+
*
|
|
18
|
+
* WHY. A dry run installs nothing, so it reports nothing installed: a plan that
|
|
19
|
+
* says "184 skill symlinks" describes a run that did not happen. The plan itself
|
|
20
|
+
* is not lost — every entry carries the action it would take (`planned`) — and
|
|
21
|
+
* this is where the installed list is emptied, so the ONE place that decides what
|
|
22
|
+
* a dry run claims does it.
|
|
23
|
+
*
|
|
24
|
+
* @param {{ installed: string[], skipped: string[], pruned?: string[], entries?: unknown[] }} result
|
|
25
|
+
* @param {boolean} dryRun
|
|
26
|
+
*/
|
|
27
|
+
export function finalizeInstallResult(result, dryRun) {
|
|
28
|
+
if (dryRun === true) {
|
|
29
|
+
return { ...result, installed: [] };
|
|
30
|
+
}
|
|
31
|
+
return result;
|
|
32
|
+
}
|
|
33
|
+
|
|
15
34
|
/**
|
|
16
35
|
* A fallback is not a failure — but it must never LOOK like a plain success. The
|
|
17
36
|
* entry is a real copy instead of a link, and the postinstall says so, naming each
|
|
@@ -192,6 +192,15 @@ if (
|
|
|
192
192
|
`(${totalInstalled} total symlinks)\n`
|
|
193
193
|
);
|
|
194
194
|
}
|
|
195
|
+
// The skills' own `skipped` list was the one bucket the postinstall never
|
|
196
|
+
// printed: an entry that was left alone — a store copy peaks-loop does not
|
|
197
|
+
// own, a second live install — looked exactly like a successful install
|
|
198
|
+
// from the outside. The agents and output styles already say so; the
|
|
199
|
+
// skills now do too.
|
|
200
|
+
reportLeftAlone(
|
|
201
|
+
'skills',
|
|
202
|
+
perPlatform.flatMap((platform) => platform.skipped ?? [])
|
|
203
|
+
);
|
|
195
204
|
const outputStylesResult = installBundledOutputStyles();
|
|
196
205
|
// Slice 7/7 — bundled agents (Claude Code sub-agent prompts) ship
|
|
197
206
|
// under `agents/*.md` in the peaks-loop tarball and are auto-installed
|
|
@@ -17,8 +17,10 @@ metadata:
|
|
|
17
17
|
## Loop hygiene (every turn — MANDATORY)
|
|
18
18
|
|
|
19
19
|
**Skill header.** While this skill is active, open every turn with
|
|
20
|
-
`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
|
|
20
|
+
`Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
|
|
21
21
|
Every turn, not only the first — it is how the user knows which skill is driving.
|
|
22
|
+
`Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
|
|
23
|
+
(`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
|
|
22
24
|
|
|
23
25
|
**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
|
|
24
26
|
read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
|
|
@@ -13,8 +13,10 @@ visibility: internal
|
|
|
13
13
|
## Loop hygiene (every turn — MANDATORY)
|
|
14
14
|
|
|
15
15
|
**Skill header.** While this skill is active, open every turn with
|
|
16
|
-
`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
|
|
16
|
+
`Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
|
|
17
17
|
Every turn, not only the first — it is how the user knows which skill is driving.
|
|
18
|
+
`Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
|
|
19
|
+
(`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
|
|
18
20
|
|
|
19
21
|
**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
|
|
20
22
|
read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
|
|
@@ -108,7 +110,7 @@ peaks project memories --project <repo> --json
|
|
|
108
110
|
```
|
|
109
111
|
|
|
110
112
|
This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <project|decision|convention|rule|reference|feedback|module|lesson|bug|investigation|technical-pattern|project-rule|design|handoff|session-handoff|project-todo|publish-closure|project-closure|slice-closure|slice-pilot-findings|sediment>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
|
|
111
|
-
Then display: `Peaks-Loop Skill: peaks-prd | Peaks-Loop Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-prd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
|
|
113
|
+
Then display: `Peaks-Loop Skill: peaks-prd | Peaks-Loop Role: <role> | Peaks-Loop Gate: startup | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`. `Role` and `Context` are machine facts: copy them from `peaks skill presence --json` (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them. Update with `peaks skill presence:set peaks-prd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
|
|
112
114
|
|
|
113
115
|
## Responsibilities
|
|
114
116
|
|
|
@@ -308,7 +310,7 @@ PRD must not mark the product artifact ready for RD if the frontend change point
|
|
|
308
310
|
|
|
309
311
|
## Standards dry-run coordination
|
|
310
312
|
|
|
311
|
-
For code repository workflows, PRD may run or consume `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run` so downstream scope can reference the expected `CLAUDE.md` and `.claude/rules/**`
|
|
313
|
+
For code repository workflows, PRD may run or consume `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run` so downstream scope can reference the expected standards state — the `AGENTS.md` body, the optional `CLAUDE.md` pointer (written only when the IDE profile needs it), and the rules tree under `.peaks/standards/**` (2.0 canonical layout) or `.claude/rules/**` (legacy 1.x project). PRD records this as preflight status only. RD remains responsible for applying standards mutations when authorized.
|
|
312
314
|
|
|
313
315
|
## Matt Pocock skills integration
|
|
314
316
|
|
|
@@ -13,8 +13,10 @@ visibility: internal
|
|
|
13
13
|
## Loop hygiene (every turn — MANDATORY)
|
|
14
14
|
|
|
15
15
|
**Skill header.** While this skill is active, open every turn with
|
|
16
|
-
`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
|
|
16
|
+
`Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
|
|
17
17
|
Every turn, not only the first — it is how the user knows which skill is driving.
|
|
18
|
+
`Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
|
|
19
|
+
(`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
|
|
18
20
|
|
|
19
21
|
**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
|
|
20
22
|
read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
|
|
@@ -154,7 +156,7 @@ Gate index: A (test-cases), A2 (tests executed), A3 (security reference — v2.1
|
|
|
154
156
|
|
|
155
157
|
## Project standards preflight
|
|
156
158
|
|
|
157
|
-
Before QA verification in a code repository, call `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run`. Apply only when write authorization exists.
|
|
159
|
+
Before QA verification in a code repository, call `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run` — the bundle is the `AGENTS.md` body, the optional `CLAUDE.md` pointer (written only when the IDE profile needs it), and the rules tree under `.peaks/standards/**` or `.claude/rules/**`. Apply only when write authorization exists.
|
|
158
160
|
|
|
159
161
|
→ see `references/qa-standards-preflight.md` for the full preflight contract.
|
|
160
162
|
|
|
@@ -19,4 +19,4 @@ peaks project memories --project <repo> --json
|
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <project|decision|convention|rule|reference|feedback|module|lesson|bug|investigation|technical-pattern|project-rule|design|handoff|session-handoff|project-todo|publish-closure|project-closure|slice-closure|slice-pilot-findings|sediment>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
|
|
22
|
-
Then display: `Peaks-Loop Skill: peaks-qa | Peaks-Loop Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
|
|
22
|
+
Then display: `Peaks-Loop Skill: peaks-qa | Peaks-Loop Role: <role> | Peaks-Loop Gate: startup | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`. `Role` and `Context` are machine facts: copy them from `peaks skill presence --json` (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them. Update with `peaks skill presence:set peaks-qa --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
|
|
@@ -5,4 +5,6 @@
|
|
|
5
5
|
- `peaks standards init --project <path> --dry-run`
|
|
6
6
|
- `peaks standards update --project <path> --dry-run`
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
The bundle the CLI writes has three parts: the **body** `AGENTS.md` (always written), the **pointer** `CLAUDE.md` (written only when the IDE profile needs it — a profile that reads `AGENTS.md` directly, e.g. `--ide codex`, writes no pointer), and the **rules tree** under `.peaks/standards/**` (2.0 canonical layout) or `.claude/rules/**` (legacy 1.x project). Judge the preflight from the CLI's own output instead of a hard-coded path: `peaks standards init --project <path> --dry-run --json` reports `data.plannedWrites[]` = `[{ relativePath, status }]`, where `init` reports two states — `planned` (absent → will be created) / `existing` (present on disk; `init` does not compare content, so a stale file still reads `existing`). The four-state view of the body file comes from `peaks standards update --project <path> --dry-run --json`: `planned` (absent) / `appended` (present, managed block missing) / `existing` (present and current) / `review` (present, managed block differs → a human decides; that command exits 1 with code `STANDARDS_UPDATE_REVIEW_REQUIRED`). Those four states cover `AGENTS.md` and, when the IDE profile writes one, `CLAUDE.md`; rules-tree files are `planned` / `existing` in both commands. The `relativePath` values also tell you which rules root this project uses.
|
|
9
|
+
|
|
10
|
+
If the repo needs a first-time standards bundle, treat `standards init` as the creation path. If the body file (`AGENTS.md`) already exists, use `standards update` to decide whether Peaks-Loop can append a managed block or should only return review suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.
|
|
@@ -25,7 +25,7 @@ If the upstream superpowers chain suggests raw `git worktree add`:
|
|
|
25
25
|
3. Continue with `peaks worktree spawn` (or the auth-grant fallback)
|
|
26
26
|
|
|
27
27
|
- **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
|
|
28
|
-
- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-qa`. The sub-agent must not overwrite
|
|
28
|
+
- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-qa`. The sub-agent must not overwrite the main presence lease; the main Code loop owns it. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-qa.json` and only that.
|
|
29
29
|
- **Workspace initialization** — Code has already run `peaks workspace init` before fan-out. Do not re-run it.
|
|
30
30
|
- **Mode selection** — Code has already chosen the mode.
|
|
31
31
|
- **Statusline install** — already done by Code at session startup.
|
|
@@ -52,7 +52,7 @@ What the sub-agent **MUST** still do:
|
|
|
52
52
|
**Hard prohibitions** (sub-agent context):
|
|
53
53
|
|
|
54
54
|
- Do NOT call `Skill(skill="...")`.
|
|
55
|
-
- Do NOT call `peaks skill presence:set` — Code owns the
|
|
55
|
+
- Do NOT call `peaks skill presence:set` — Code owns the presence lease.
|
|
56
56
|
- Do NOT run the actual test suite, do NOT execute security/perf tools, do NOT open a browser — those are the **QA validation** phase, not the Swarm planning phase.
|
|
57
57
|
- Do NOT commit, push, install hooks, or apply settings.json mutations.
|
|
58
58
|
- Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}`.
|
|
@@ -14,8 +14,10 @@ visibility: internal
|
|
|
14
14
|
## Loop hygiene (every turn — MANDATORY)
|
|
15
15
|
|
|
16
16
|
**Skill header.** While this skill is active, open every turn with
|
|
17
|
-
`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
|
|
17
|
+
`Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
|
|
18
18
|
Every turn, not only the first — it is how the user knows which skill is driving.
|
|
19
|
+
`Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
|
|
20
|
+
(`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
|
|
19
21
|
|
|
20
22
|
**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
|
|
21
23
|
read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
|
|
@@ -118,7 +120,7 @@ See `references/rd-runbook.md` for the full 9-step runbook (steps #0–#8) with
|
|
|
118
120
|
|
|
119
121
|
You cannot declare a phase complete from memory. Each gate below is a `ls` or `grep` command you **MUST run** and whose output you **MUST see** before proceeding. CLI enforcement: the gates are ALSO enforced by `peaks request transition`, which fails with `code: PREREQUISITES_MISSING` if any are absent.
|
|
120
122
|
|
|
121
|
-
Gate index: A (project-scan), A2 (tech-doc path verification), A3 (
|
|
123
|
+
Gate index: A (project-scan), A2 (tech-doc path verification), A3 (standards files — AGENTS.md body + rules tree; the CLAUDE.md pointer is written only when the IDE profile needs it), B (tech-doc + request artifact), B2 (unit tests on changed surface), B3 (code-review.md), B4 (security-review.md), B5 (lint — no unfilled placeholders + JS/TS ESLint 卡控 via `peaks lint check`. First-time project setup: run `peaks lint baseline` to generate the project-level `.peaks/lint/baseline.json`. Per-slice flow uses `peaks lint check` (= diffOnly: true + baseline waiver + redLineMode: 'baseline-aware'). LLM red-line reference lives at `.peaks/memory/lint-redline-summary.md` (auto-written by `peaks lint check --red-line`); read it BEFORE writing JS/TS so the next slice sees prior sibling-violation context. Project-aware baseline: each project regenerates its own baseline; cross-project reuse is low-value — see `references/jsts-eslint-gate.md` §7), B6 (request-type-sanity), B7 (repair-status — 3-cycle cap), B8 (diff-vs-scope), B9 (perf-baseline).
|
|
122
124
|
|
|
123
125
|
→ see `references/rd-transition-gates.md` for the per-gate contract + `ls` / `grep` shell snippets.
|
|
124
126
|
|
|
@@ -4,6 +4,6 @@
|
|
|
4
4
|
|
|
5
5
|
Do not default to a git-backed artifact repository, external artifact sync, or automatic commits for intermediate artifacts. Git inclusion or sync requires explicit user confirmation or an active profile that clearly authorizes it. Browser evidence must be sanitized before retention: do not store login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs containing PII or SSO/MFA material.
|
|
6
6
|
|
|
7
|
-
When project-local `CLAUDE.md`
|
|
7
|
+
When the project-local standards bundle is created or updated — the `AGENTS.md` body, the optional `CLAUDE.md` pointer (written only when the IDE profile needs it), and the rules tree under `.peaks/standards/**` or `.claude/rules/**` — route the mutation through `peaks standards init` or `peaks standards update`; do not hand-write standards mutations. Derive the content from the current scan results and existing project standards. Keep only the rules that match the project's languages, frameworks, tooling, and repository layout. Do not emit generic templates, copy-pasted boilerplate, or rules unrelated to the current scan evidence. Do not update user-global `~/.claude/rules/**` from this workflow.
|
|
8
8
|
|
|
9
9
|
If the scan results are insufficient to justify a rule, leave it out or surface a review-only suggestion instead of writing it into project standards.
|
|
@@ -161,8 +161,17 @@ peaks codegraph affected --project <repo> <changed-files...> --json
|
|
|
161
161
|
# → `peaks request transition --state qa-handoff` returns `code: PREREQUISITES_MISSING`.
|
|
162
162
|
# Escape hatch (assisted mode): `--allow-incomplete --confirm`.
|
|
163
163
|
|
|
164
|
-
# 6.6 BEFORE implementation: verify
|
|
165
|
-
#
|
|
164
|
+
# 6.6 BEFORE implementation: verify the standards files are in place (Peaks-Loop Gate A3)
|
|
165
|
+
# The file set is decided by the CLI — never hard-code it:
|
|
166
|
+
# peaks standards init --project . --dry-run --json
|
|
167
|
+
# → data.plannedWrites[] = [{relativePath, status}]; status 'planned' = that file is absent.
|
|
168
|
+
# BODY = AGENTS.md (always written).
|
|
169
|
+
# POINTER = CLAUDE.md (written only when the IDE profile needs it; its absence from
|
|
170
|
+
# plannedWrites is NOT a failure).
|
|
171
|
+
# RULES = .peaks/standards/** (2.0 canonical) or .claude/rules/** (legacy 1.x project).
|
|
172
|
+
# BLOCKED when plannedWrites is empty or any status is 'planned'.
|
|
173
|
+
# Missing standards files → run `peaks standards init --project . --apply` (first time)
|
|
174
|
+
# or `peaks standards update --project . --apply` (existing) first, then re-check.
|
|
166
175
|
# Without project rules, security review and code review triggers won't fire.
|
|
167
176
|
|
|
168
177
|
# 7. AFTER implementation, BEFORE QA handoff — RUN THESE GATES:
|
|
@@ -5,4 +5,6 @@
|
|
|
5
5
|
- `peaks standards init --project <path> --dry-run`
|
|
6
6
|
- `peaks standards update --project <path> --dry-run`
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
The bundle the CLI writes has three parts: the **body** `AGENTS.md` (always written), the **pointer** `CLAUDE.md` (written only when the IDE profile needs it — a profile that reads `AGENTS.md` directly, e.g. `--ide codex`, writes no pointer), and the **rules tree** under `.peaks/standards/**` (2.0 canonical layout) or `.claude/rules/**` (legacy 1.x project). Judge the preflight from the CLI's own output instead of a hard-coded path: `peaks standards init --project <path> --dry-run --json` reports `data.plannedWrites[]` = `[{ relativePath, status }]`, where `init` reports two states — `planned` (absent → will be created) / `existing` (present on disk; `init` does not compare content, so a stale file still reads `existing`). The four-state view of the body file comes from `peaks standards update --project <path> --dry-run --json`: `planned` (absent) / `appended` (present, managed block missing) / `existing` (present and current) / `review` (present, managed block differs → a human decides; that command exits 1 with code `STANDARDS_UPDATE_REVIEW_REQUIRED`). Those four states cover `AGENTS.md` and, when the IDE profile writes one, `CLAUDE.md`; rules-tree files are `planned` / `existing` in both commands. The `relativePath` values also tell you which rules root this project uses.
|
|
9
|
+
|
|
10
|
+
If the body file (`AGENTS.md`) is missing, treat creation as the preferred path. If the body already exists, use `standards update` to decide whether to append a managed index block or surface review-only suggestions. Apply only when write authorization exists; otherwise keep the CLI output as a preflight next action. Do not hand-write standards file mutations inside the skill.
|
|
@@ -59,9 +59,9 @@ If the upstream superpowers chain suggests raw `git worktree add`:
|
|
|
59
59
|
> design — if either changes, update the other.
|
|
60
60
|
|
|
61
61
|
- **Session id** — use the parent's sid (read `.peaks/_runtime/session.json` or pass `--session-id <parent-sid>` to any session-creating CLI). Do NOT spawn your own session. The new `peaks session info --active` reads the canonical binding for you.
|
|
62
|
-
- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-rd`. The sub-agent must not overwrite
|
|
62
|
+
- **Skill presence (MANDATORY first action)** — do NOT call `peaks skill presence:set peaks-rd`. The sub-agent must not overwrite the main presence lease; the main Code loop owns it. If you need to mark your own state, write a marker file at `.peaks/_runtime/<sessionId>/system/sub-agent-rd.json` and only that.
|
|
63
63
|
- **Workspace initialization** — Code has already run `peaks workspace init` before fan-out. Do not re-run it.
|
|
64
|
-
- **Mode selection** — Code has already chosen the mode. Read it from the prompt arguments (or from
|
|
64
|
+
- **Mode selection** — Code has already chosen the mode. Read it from the prompt arguments (or from `peaks skill presence --json` if you can, but do not write it).
|
|
65
65
|
- **Statusline install** — already done by Code at session startup; do not re-run.
|
|
66
66
|
|
|
67
67
|
What the sub-agent **MUST** still do, from this skill's contract:
|
|
@@ -89,7 +89,7 @@ What the sub-agent **MUST** still do, from this skill's contract:
|
|
|
89
89
|
**Hard prohibitions** (sub-agent context, in addition to general red lines):
|
|
90
90
|
|
|
91
91
|
- Do NOT call `Skill(skill="...")` from inside the sub-agent — that defeats the fan-out.
|
|
92
|
-
- Do NOT call `peaks skill presence:set` — Code owns the
|
|
92
|
+
- Do NOT call `peaks skill presence:set` — Code owns the presence lease.
|
|
93
93
|
- Do NOT commit, push, install hooks, or apply settings.json mutations.
|
|
94
94
|
- Do NOT ask the user interactive questions. If you need clarification, return `{"status":"blocked","blockedReason":"<text>"}` and let Code handle the user message.
|
|
95
95
|
- Do NOT modify code (the Swarm phase is planning only; code edits happen in the RD implementation phase, which is a separate sub-agent or inline run after Gate B).
|
|
@@ -171,7 +171,7 @@ Corrected 2026-10-13, kept visible rather than edited away: this paragraph used
|
|
|
171
171
|
|
|
172
172
|
When you (the LLM sub-agent) write new or modified unit tests in `tests/unit/**`, every `it()` / `test()` block MUST follow the given-when-then contract:
|
|
173
173
|
|
|
174
|
-
1. The first string-literal argument of `it()` / `test()` MUST describe business behavior
|
|
174
|
+
1. The first string-literal argument of `it()` / `test()` MUST describe business behavior and MUST include either the word "when" (state / pre-condition) or "should" (observable outcome). The idiomatic form `when X, should Y` names both, so prefer it — but it is a preference, not a requirement: a description carrying only "when" or only "should" is compliant.
|
|
175
175
|
2. The body callback (the second argument) MUST start with exactly 3 leading comments:
|
|
176
176
|
```typescript
|
|
177
177
|
// given: <precondition — system / user state>
|
|
@@ -185,4 +185,23 @@ Run `node scripts/migrate-to-bdd.mjs --dry-run <file>` before writing new tests
|
|
|
185
185
|
- description: must contain `/(\bwhen\b|\bshould\b)/`
|
|
186
186
|
- first 3 body comments: must match `/^\s*\/\/\s*given\s*:/`, `/^\s*\/\/\s*when\s*:/`, `/^\s*\/\/\s*then\s*:/`
|
|
187
187
|
|
|
188
|
-
If your tests fail peaks-qa's `bdd-test-style-verifier` (see Slice B), the slice will be returned-to-rd. Fix the violations, do NOT bypass the check.
|
|
188
|
+
If your tests fail peaks-qa's `bdd-test-style-verifier` (see Slice B), the slice will be returned-to-rd. Fix the violations, do NOT bypass the check.
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## Scratch path (absolute — never a cwd-relative redirect)
|
|
193
|
+
|
|
194
|
+
The dispatch CLI machine-injects a scratch-path block into every sub-agent prompt, naming the ABSOLUTE scratch directory for that dispatch: `<projectRoot>/.peaks/_runtime/<sessionId>/<role>/scratch/`. The rule it carries is one line: **never redirect to a cwd-relative path**. The two paths that do NOT pass through that composer — `--from-dag` and `--mode detached` — carry no scratch block, so a caller using either must state the rule itself.
|
|
195
|
+
|
|
196
|
+
**Why it is a block and not a line in a brief.** The rule used to live only in the orchestrator's brief, which is exactly as strong as the orchestrator's memory at 3am. Measured 2026-10-02, five zero-byte `*.err` captures — the `2> name.err` of five per-file test runs — landed at the repository root and were committed; `git status` stayed clean because the files were tracked, and neither the file-size census nor eslint reads a `.err`.
|
|
197
|
+
|
|
198
|
+
**Two copies, one pin.** The block below is the canonical text; `src/cli/commands/dispatch-scratch-path-block.ts` holds its machine copy (`SCRATCH_PATH_BLOCK_TEMPLATE`) and `tests/unit/cli/commands/dispatch-scratch-path-block.test.ts` asserts the two are byte-equal, so neither can drift. The path differs for every dispatch, so the placeholder is what this file carries.
|
|
199
|
+
|
|
200
|
+
```
|
|
201
|
+
Scratch path (REQUIRED — absolute path; never a cwd-relative redirect)
|
|
202
|
+
|
|
203
|
+
Write every temporary file for this task under this ABSOLUTE path:
|
|
204
|
+
{{scratchDir}}
|
|
205
|
+
|
|
206
|
+
Never redirect to a path that depends on the working directory — `2> out.err`, `> run.log`, `./scratch/`. A cwd-relative redirect writes wherever the task happens to `cd`: measured 2026-10-02, five zero-byte `*.err` captures landed at the repository root and were committed, and `git status` stayed clean because the files were tracked. Use the absolute path above; it lives under the session's runtime dir, which is gitignored, so nothing written there can be committed by accident.
|
|
207
|
+
```
|
|
@@ -38,13 +38,57 @@ ls <every-single-directory-path-in-tech-doc> 2>&1 | grep -c "No such file"
|
|
|
38
38
|
# breaks the implementation, and forces the user to correct the engineer.
|
|
39
39
|
```
|
|
40
40
|
|
|
41
|
-
**Peaks-Loop Gate A3 — Before implementation: project standards files
|
|
41
|
+
**Peaks-Loop Gate A3 — Before implementation: the project's standards files are in place:**
|
|
42
|
+
|
|
43
|
+
The standards bundle has three parts, and only the first has a fixed name:
|
|
44
|
+
|
|
45
|
+
- `AGENTS.md` — the **body** (the cross-tool constitution). Always written, in every layout.
|
|
46
|
+
- `CLAUDE.md` — the **pointer** (`@AGENTS.md`). Written ONLY when the IDE profile needs it.
|
|
47
|
+
A profile that reads `AGENTS.md` directly (e.g. `--ide codex`) writes no pointer at all,
|
|
48
|
+
so its absence is NOT a failure.
|
|
49
|
+
- the **rules tree** — `.peaks/standards/**` for the 2.0 canonical layout, `.claude/rules/**`
|
|
50
|
+
for a legacy 1.x project that still carries a thick `.claude/rules/` tree.
|
|
51
|
+
|
|
52
|
+
Never hard-code a path in this gate: ask the CLI which files this project actually uses.
|
|
53
|
+
|
|
42
54
|
```bash
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
#
|
|
55
|
+
# 1) The CLI decides the file set. Never hard-code a rules path here.
|
|
56
|
+
peaks standards init --project . --dry-run --json
|
|
57
|
+
# → data.plannedWrites[] = [{ relativePath, status }, ...]
|
|
58
|
+
# init reports TWO states: planned (absent → will be created) | existing (present on
|
|
59
|
+
# disk — init does not compare content, so a stale file still reads 'existing').
|
|
60
|
+
# The four-state view of the body file comes from
|
|
61
|
+
# `peaks standards update --project . --dry-run --json`:
|
|
62
|
+
# planned | appended (managed block missing) | existing (managed
|
|
63
|
+
# block matches) | review (managed block differs → a human decides; that command exits
|
|
64
|
+
# 1 with code STANDARDS_UPDATE_REVIEW_REQUIRED). The four states cover AGENTS.md and,
|
|
65
|
+
# when the IDE profile writes one, CLAUDE.md; rules-tree files are planned | existing
|
|
66
|
+
# in both commands.
|
|
67
|
+
# → data.skippedFiles[] = the entries already present on disk
|
|
68
|
+
#
|
|
69
|
+
# 2) The body file is invariant — it is in plannedWrites in every layout. Verify it landed:
|
|
70
|
+
ls AGENTS.md
|
|
71
|
+
# "No such file" → BLOCKED
|
|
72
|
+
#
|
|
73
|
+
# 3) Judge the rest from the JSON, not from a hard-coded path list:
|
|
74
|
+
# BLOCKED when plannedWrites is empty, or when any entry has status 'planned'
|
|
75
|
+
# (that required standards file is absent).
|
|
76
|
+
# PASS otherwise. `init` never reports 'appended' / 'review' — when the update
|
|
77
|
+
# dry-run does, report each one as a follow-up:
|
|
78
|
+
# 'appended' → `peaks standards update --project . --apply` adds the managed block;
|
|
79
|
+
# 'review' → the managed block differs; a human decides (see `peaks standards update`).
|
|
80
|
+
#
|
|
81
|
+
# The layout is read off the paths themselves:
|
|
82
|
+
# .peaks/standards/** → 2.0 canonical layout
|
|
83
|
+
# .claude/rules/** → legacy 1.x layout
|
|
84
|
+
# CLAUDE.md is listed only when the IDE profile needs a pointer — its ABSENCE from
|
|
85
|
+
# plannedWrites is NOT a failure and must not be reported as BLOCKED.
|
|
86
|
+
#
|
|
87
|
+
# Any 'planned' entry → BLOCKED. Run `peaks standards init --project . --apply` (first
|
|
88
|
+
# time) or `peaks standards update --project . --apply` (existing) FIRST, then re-run the
|
|
89
|
+
# dry-run until no entry is 'planned'.
|
|
46
90
|
# Do not write a single line of implementation code without standards files in place.
|
|
47
|
-
# Without
|
|
91
|
+
# Without the standards body + rules tree, code review and security review triggers won't fire.
|
|
48
92
|
```
|
|
49
93
|
|
|
50
94
|
**Peaks-Loop Gate B — Before QA handoff:**
|
|
@@ -19,4 +19,4 @@ peaks project memories --project <repo> --json
|
|
|
19
19
|
```
|
|
20
20
|
|
|
21
21
|
This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <project|decision|convention|rule|reference|feedback|module|lesson|bug|investigation|technical-pattern|project-rule|design|handoff|session-handoff|project-todo|publish-closure|project-closure|slice-closure|slice-pilot-findings|sediment>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
|
|
22
|
-
Then display: `Peaks-Loop Skill: peaks-rd | Peaks-Loop Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
|
|
22
|
+
Then display: `Peaks-Loop Skill: peaks-rd | Peaks-Loop Role: <role> | Peaks-Loop Gate: startup | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`. `Role` and `Context` are machine facts: copy them from `peaks skill presence --json` (`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them. Update with `peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
|
|
@@ -9,8 +9,10 @@ description: Third-party independent code-review skill for Peaks. Use as a paral
|
|
|
9
9
|
## Loop hygiene (every turn — MANDATORY)
|
|
10
10
|
|
|
11
11
|
**Skill header.** While this skill is active, open every turn with
|
|
12
|
-
`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
|
|
12
|
+
`Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`.
|
|
13
13
|
Every turn, not only the first — it is how the user knows which skill is driving.
|
|
14
|
+
`Role` and `Context` are machine facts: copy them from `peaks skill presence --json`
|
|
15
|
+
(`data.role`, `data.context.ratioPct`, `data.context.action`) — never invent them.
|
|
14
16
|
|
|
15
17
|
**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
|
|
16
18
|
read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
|