peaks-loop 4.1.17 → 4.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +269 -0
  3. package/README-en.md +6 -0
  4. package/README.md +5 -0
  5. package/contracts/test-style-contract.md +14 -5
  6. package/dist/cli/commands/audit-red-lines-runners.js +6 -1
  7. package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
  8. package/dist/cli/commands/best-practice-scan-collision.js +115 -0
  9. package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
  10. package/dist/cli/commands/best-practice-scan-command.js +9 -18
  11. package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
  12. package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
  13. package/dist/cli/commands/code-auto-compact-command.js +71 -40
  14. package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
  15. package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
  16. package/dist/cli/commands/code-gate-command.d.ts +4 -4
  17. package/dist/cli/commands/code-gate-command.js +4 -4
  18. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  19. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  20. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  21. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  22. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  23. package/dist/cli/commands/core/skill-registry-commands.js +32 -0
  24. package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
  25. package/dist/cli/commands/core/skill-store-report.js +79 -0
  26. package/dist/cli/commands/core/standards-init-command.js +44 -8
  27. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  28. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  29. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  30. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  31. package/dist/cli/commands/dispatch-prompt-composition.js +7 -2
  32. package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
  33. package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
  34. package/dist/cli/commands/hooks-commands.js +36 -7
  35. package/dist/cli/commands/hooks-uninstall-command.js +5 -5
  36. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  37. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  38. package/dist/cli/commands/mut-commands.d.ts +9 -1
  39. package/dist/cli/commands/mut-commands.js +82 -154
  40. package/dist/cli/commands/preferences-commands.js +27 -2
  41. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  42. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  43. package/dist/services/24h-mode/auto-engage.js +14 -6
  44. package/dist/services/artifacts/artifact-templates.js +10 -0
  45. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  46. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  47. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  48. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  49. package/dist/services/artifacts/request-artifact-service.js +6 -6
  50. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  51. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  52. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  53. package/dist/services/audit/static-service.js +4 -4
  54. package/dist/services/code/auto-compact-history.d.ts +6 -1
  55. package/dist/services/code/auto-compact-history.js +6 -1
  56. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  57. package/dist/services/code/auto-compact-modes.js +75 -20
  58. package/dist/services/code/auto-compact-orchestrator.js +7 -5
  59. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  60. package/dist/services/code/auto-compact-profile.js +51 -0
  61. package/dist/services/code/auto-compact-run-types.d.ts +8 -4
  62. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  63. package/dist/services/compact-history/compact-history-service.js +5 -1
  64. package/dist/services/context/auto-compact-types.d.ts +7 -5
  65. package/dist/services/dispatch/dispatch-ledger-reader.d.ts +13 -0
  66. package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
  67. package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
  68. package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
  69. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  70. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  71. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  72. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  73. package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
  74. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  75. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  76. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  77. package/dist/services/hooks/pre-tool-code-gate.d.ts +4 -4
  78. package/dist/services/hooks/pre-tool-code-gate.js +4 -4
  79. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  80. package/dist/services/hooks/presence-marker-detector.js +21 -19
  81. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  82. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  83. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  84. package/dist/services/mode/mode-status-service.d.ts +26 -27
  85. package/dist/services/mode/mode-status-service.js +36 -60
  86. package/dist/services/preferences/preferences-types.d.ts +30 -0
  87. package/dist/services/preferences/preferences-types.js +13 -0
  88. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  89. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  90. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  91. package/dist/services/scan/rid-change-claims.js +116 -0
  92. package/dist/services/session/getSessionDir.d.ts +13 -0
  93. package/dist/services/session/getSessionDir.js +7 -1
  94. package/dist/services/skills/hooks-settings-types.d.ts +17 -21
  95. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  96. package/dist/services/skills/presence-caller-id.js +43 -0
  97. package/dist/services/skills/presence-gate.d.ts +65 -0
  98. package/dist/services/skills/presence-gate.js +113 -0
  99. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  100. package/dist/services/skills/presence-lease-resolver.js +114 -0
  101. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  102. package/dist/services/skills/presence-lease-selection.js +135 -0
  103. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  104. package/dist/services/skills/presence-lease-service.js +34 -87
  105. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  106. package/dist/services/skills/presence-lease-store.js +94 -0
  107. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  108. package/dist/services/skills/presence-lease-types.js +27 -0
  109. package/dist/services/skills/presence-role.d.ts +35 -0
  110. package/dist/services/skills/presence-role.js +72 -0
  111. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  112. package/dist/services/skills/skill-presence-service.js +143 -174
  113. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  114. package/dist/services/skills/skill-presence-write.js +74 -0
  115. package/dist/services/skills/skill-statusline-service.js +7 -7
  116. package/dist/services/skills/sync-service-support.d.ts +27 -0
  117. package/dist/services/skills/sync-service.js +1 -0
  118. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  119. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  120. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  121. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  122. package/dist/services/standards/migrate-service.d.ts +1 -1
  123. package/dist/services/standards/migrate-service.js +27 -7
  124. package/dist/services/standards/project-scripts.d.ts +25 -0
  125. package/dist/services/standards/project-scripts.js +116 -0
  126. package/dist/services/standards/project-standards-service.d.ts +23 -15
  127. package/dist/services/standards/project-standards-service.js +176 -243
  128. package/dist/services/standards/standards-constitution.d.ts +89 -0
  129. package/dist/services/standards/standards-constitution.js +199 -0
  130. package/dist/services/standards/standards-files.d.ts +37 -0
  131. package/dist/services/standards/standards-files.js +138 -0
  132. package/dist/services/standards/standards-pointer.d.ts +73 -0
  133. package/dist/services/standards/standards-pointer.js +98 -0
  134. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  135. package/dist/services/standards/standards-render-agents.js +149 -0
  136. package/dist/services/standards/standards-render-common.d.ts +38 -1
  137. package/dist/services/standards/standards-render-common.js +44 -7
  138. package/dist/services/standards/standards-render.d.ts +1 -3
  139. package/dist/services/standards/standards-render.js +6 -87
  140. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  141. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  142. package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
  143. package/dist/services/workflow/workflow-inflight-probe.js +163 -75
  144. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  145. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  146. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  147. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  148. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  149. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  150. package/dist/services/workspace/runtime-layout.js +62 -0
  151. package/output-styles/peaks-skill-swarm.md +18 -2
  152. package/package.json +10 -9
  153. package/schemas/doctor-report.schema.json +1 -1
  154. package/scripts/canonical-store-fs.mjs +112 -0
  155. package/scripts/canonical-store-link.mjs +13 -22
  156. package/scripts/canonical-store-marker.mjs +241 -0
  157. package/scripts/canonical-store.mjs +119 -141
  158. package/scripts/install-skills-bundles.mjs +56 -13
  159. package/scripts/install-skills-fs.mjs +73 -0
  160. package/scripts/install-skills-output-styles.mjs +8 -2
  161. package/scripts/install-skills-report.mjs +19 -0
  162. package/scripts/install-skills.mjs +9 -0
  163. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  164. package/skills/bee/peaks-prd/SKILL.md +5 -3
  165. package/skills/bee/peaks-qa/SKILL.md +4 -2
  166. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  167. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  168. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  169. package/skills/bee/peaks-rd/SKILL.md +4 -2
  170. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  171. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  172. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  173. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +24 -5
  174. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  175. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  176. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  177. package/skills/bee/peaks-sc/SKILL.md +4 -2
  178. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  179. package/skills/bee/peaks-txt/SKILL.md +5 -3
  180. package/skills/bee/peaks-ui/SKILL.md +6 -4
  181. package/skills/peaks-audit/SKILL.md +3 -1
  182. package/skills/peaks-code/SKILL.md +4 -2
  183. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  184. package/skills/peaks-code/references/completion-handoff.md +1 -1
  185. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  186. package/skills/peaks-code/references/micro-cycle.md +2 -2
  187. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  188. package/skills/peaks-code/references/runbook.md +4 -4
  189. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  190. package/skills/peaks-code/references/standards-preflight.md +7 -6
  191. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  192. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  193. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  194. package/skills/peaks-content/SKILL.md +3 -1
  195. package/skills/peaks-doctor/SKILL.md +3 -1
  196. package/skills/peaks-final-review/SKILL.md +3 -1
  197. package/skills/peaks-ide/SKILL.md +3 -1
  198. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  199. package/skills/peaks-race-code/SKILL.md +9 -4
  200. package/skills/peaks-resume/SKILL.md +3 -1
  201. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  202. package/skills/peaks-solo/SKILL.md +3 -1
  203. package/skills/peaks-sop/SKILL.md +4 -2
  204. package/skills/peaks-status/SKILL.md +3 -1
  205. package/skills/peaks-test/SKILL.md +3 -1
@@ -1,12 +1,11 @@
1
1
  /**
2
2
  * IDE-aware wrapper for `peaks standards init` / `peaks standards update`.
3
3
  *
4
- * `executeProjectStandardsInit` / `executeProjectStandardsUpdate` always
5
- * wrote to `CLAUDE.md` + `.claude/rules/**` regardless of which IDE
6
- * the user was running. This wrapper dispatches on the IDE detected
7
- * (or explicitly requested via `--ide`) and falls back to the legacy
8
- * Claude Code path with a stderr warning when the detected IDE has
9
- * no `standardsProfile` declared (Trae in slice 1.3.2).
4
+ * `--ide` USED TO BE DETECTION-ONLY: it picked the adapter, the adapter's
5
+ * `standardsProfile` was looked up, and then every branch called the SAME
6
+ * writer — the profile was read and never used. This module is where that
7
+ * gap is closed: the profile's `rootFile` now decides which instruction
8
+ * files are emitted.
10
9
  *
11
10
  * Two entry points:
12
11
  *
@@ -19,19 +18,17 @@
19
18
  * Detection precedence:
20
19
  * 1. Explicit `options.ideId` (CLI `--ide` flag)
21
20
  * 2. `IdeRegistry.detect()` from cwd (or the `projectRoot` if given)
22
- * 3. `null` (no IDE detected) → fall back to the legacy Claude Code path
21
+ * 3. `null` (no IDE detected) → the default cross-tool constitution
23
22
  *
24
23
  * Fallback behavior: when the resolved IDE has no `standardsProfile`
25
- * declared, the wrapper STILL calls the legacy Claude Code writer
26
- * (so the user gets the files they would have gotten before slice #011)
27
- * and emits a stderr warning with the IDE id and the fact that the
28
- * adapter is UNVERIFIED for the standards profile. This keeps the
29
- * "Trae is UNVERIFIED, ship a working file tree, surface the gap"
30
- * contract intact.
24
+ * declared, the wrapper writes the DEFAULT shape — the shared body plus the
25
+ * pointer that imports it — and emits a stderr warning naming the IDE and
26
+ * the fact that its standards profile is undeclared.
31
27
  */
32
- import type { IdeId } from '../ide/ide-types.js';
28
+ import type { IdeId, IdeStandardsProfile } from '../ide/ide-types.js';
33
29
  import { detectAllResourceTargets, getStandardsProfile } from '../ide/resource-profile.js';
34
30
  import { type ProjectStandardsInitOptions, type ProjectStandardsInitResult, type ProjectStandardsUpdateResult } from './project-standards-service.js';
31
+ import { type StandardsConstitution } from './standards-constitution.js';
35
32
  export type { ProjectStandardsInitResult, ProjectStandardsUpdateResult };
36
33
  export type ProjectStandardsIdeAwareOptions = ProjectStandardsInitOptions & {
37
34
  /**
@@ -45,11 +42,28 @@ export type ProjectStandardsUpdateIdeAwareOptions = ProjectStandardsInitOptions
45
42
  /** Explicit IDE override. See {@link ProjectStandardsIdeAwareOptions}. */
46
43
  readonly ideId?: IdeId;
47
44
  };
45
+ /**
46
+ * The constitution shape an IDE's standards profile implies.
47
+ *
48
+ * THE RULE. `IdeStandardsProfile.rootFile` names the file the IDE reads as
49
+ * its project instructions:
50
+ * - `AGENTS.md` → the IDE reads the shared body directly, so NO pointer
51
+ * file is emitted.
52
+ * - `CLAUDE.md` → the IDE reads its own file, so a pointer that imports
53
+ * the body is emitted beside it.
54
+ * - `null` (or any other name) → the IDE has no equivalent of the body,
55
+ * so only the body is emitted.
56
+ *
57
+ * A profile the registry does not declare falls back to the default shape —
58
+ * body plus pointer — because that is the shape that covers EVERY reader:
59
+ * the body for the AGENTS-native tools, the pointer for Claude Code.
60
+ */
61
+ export declare function resolveStandardsConstitution(profile: IdeStandardsProfile | null): StandardsConstitution;
48
62
  /**
49
63
  * Resolve the active IDE id for a standards call. Order of precedence:
50
64
  * 1. explicit `options.ideId`
51
65
  * 2. `IdeRegistry.detect()` from `options.projectRoot`
52
- * 3. `null` (no detected IDE — caller falls back to legacy)
66
+ * 3. `null` (no detected IDE — caller falls back to the default shape)
53
67
  */
54
68
  export declare function resolveStandardsIdeId(options: {
55
69
  readonly projectRoot: string;
@@ -58,12 +72,8 @@ export declare function resolveStandardsIdeId(options: {
58
72
  /**
59
73
  * Run `peaks standards init` with IDE-aware dispatch.
60
74
  *
61
- * When the resolved IDE has a `standardsProfile`, the call still
62
- * delegates to the existing `executeProjectStandardsInit` (the
63
- * profile maps to the Claude Code path; future per-IDE writers
64
- * plug in here). When the IDE is unregistered for the standards
65
- * profile, the call delegates to the legacy path + emits a stderr
66
- * warning.
75
+ * The resolved IDE's `standardsProfile.rootFile` decides whether the writer
76
+ * emits the pointer file beside the shared body.
67
77
  */
68
78
  export declare function executeProjectStandardsInitIdeAware(options: ProjectStandardsIdeAwareOptions): ProjectStandardsInitResult;
69
79
  /**
@@ -74,8 +84,9 @@ export declare function executeProjectStandardsInitIdeAware(options: ProjectStan
74
84
  export declare function executeProjectStandardsUpdateIdeAware(options: ProjectStandardsUpdateIdeAwareOptions): ProjectStandardsUpdateResult;
75
85
  /**
76
86
  * Test seam + integration-test helper: returns the resolved IDE id
77
- * for the call, plus the active standards profile. Exported for
78
- * to assert the dispatch decision without running the full write.
87
+ * for the call, plus the active standards profile and the constitution
88
+ * shape that profile implies. Exported for callers that need to assert the
89
+ * dispatch decision without running the full write.
79
90
  */
80
91
  export declare function inspectStandardsDispatch(options: {
81
92
  readonly projectRoot: string;
@@ -83,6 +94,7 @@ export declare function inspectStandardsDispatch(options: {
83
94
  }): {
84
95
  readonly ideId: IdeId | null;
85
96
  readonly profile: ReturnType<typeof getStandardsProfile>;
97
+ readonly constitution: StandardsConstitution;
86
98
  };
87
99
  /**
88
100
  * Test seam: the resource-profile accessor exposes
@@ -1,15 +1,39 @@
1
1
  import { detectAllResourceTargets, getStandardsProfile } from '../ide/resource-profile.js';
2
2
  import { executeProjectStandardsInit, executeProjectStandardsUpdate } from './project-standards-service.js';
3
+ import { DEFAULT_CONSTITUTION } from './standards-constitution.js';
3
4
  import { detectInstalledIde } from '../ide/ide-detector.js';
5
+ /**
6
+ * The constitution shape an IDE's standards profile implies.
7
+ *
8
+ * THE RULE. `IdeStandardsProfile.rootFile` names the file the IDE reads as
9
+ * its project instructions:
10
+ * - `AGENTS.md` → the IDE reads the shared body directly, so NO pointer
11
+ * file is emitted.
12
+ * - `CLAUDE.md` → the IDE reads its own file, so a pointer that imports
13
+ * the body is emitted beside it.
14
+ * - `null` (or any other name) → the IDE has no equivalent of the body,
15
+ * so only the body is emitted.
16
+ *
17
+ * A profile the registry does not declare falls back to the default shape —
18
+ * body plus pointer — because that is the shape that covers EVERY reader:
19
+ * the body for the AGENTS-native tools, the pointer for Claude Code.
20
+ */
21
+ export function resolveStandardsConstitution(profile) {
22
+ if (profile === null)
23
+ return DEFAULT_CONSTITUTION;
24
+ if (profile.rootFile === 'CLAUDE.md')
25
+ return DEFAULT_CONSTITUTION;
26
+ return { bodyFile: DEFAULT_CONSTITUTION.bodyFile, pointerFile: null };
27
+ }
4
28
  function warnUnregisteredIde(ideId, projectRoot) {
5
29
  process.stderr.write(`peaks standards: IDE '${ideId}' has no standardsProfile declared; ` +
6
- `falling back to the legacy Claude Code path (CLAUDE.md + .claude/rules/**) ` +
7
- `for project '${projectRoot}'. This is a slice #011 follow-up gap; ` +
8
- `see .peaks/memory/ide-adapter-resource-profile-framework.md.\n`);
30
+ `writing the default cross-tool constitution (AGENTS.md + the CLAUDE.md pointer that imports it) ` +
31
+ `for project '${projectRoot}'. ` +
32
+ `See .peaks/memory/ide-adapter-resource-profile-framework.md.\n`);
9
33
  }
10
34
  function warnNoIdeDetected(projectRoot) {
11
35
  process.stderr.write(`peaks standards: no IDE detected in '${projectRoot}'; ` +
12
- `writing to the 2.0 canonical path (CLAUDE.md + .peaks/standards/**). ` +
36
+ `writing the 2.0 canonical layout (AGENTS.md + the CLAUDE.md pointer that imports it + .peaks/standards/**). ` +
13
37
  `Projects with a legacy 1.x thick .claude/rules/ tree keep that layout ` +
14
38
  `(use \`peaks standards migrate --from-claude-rules\` to converge to 2.0). ` +
15
39
  `Pass --ide <id> to bypass detection.\n`);
@@ -18,7 +42,7 @@ function warnNoIdeDetected(projectRoot) {
18
42
  * Resolve the active IDE id for a standards call. Order of precedence:
19
43
  * 1. explicit `options.ideId`
20
44
  * 2. `IdeRegistry.detect()` from `options.projectRoot`
21
- * 3. `null` (no detected IDE — caller falls back to legacy)
45
+ * 3. `null` (no detected IDE — caller falls back to the default shape)
22
46
  */
23
47
  export function resolveStandardsIdeId(options) {
24
48
  if (options.ideId !== undefined) {
@@ -29,12 +53,8 @@ export function resolveStandardsIdeId(options) {
29
53
  /**
30
54
  * Run `peaks standards init` with IDE-aware dispatch.
31
55
  *
32
- * When the resolved IDE has a `standardsProfile`, the call still
33
- * delegates to the existing `executeProjectStandardsInit` (the
34
- * profile maps to the Claude Code path; future per-IDE writers
35
- * plug in here). When the IDE is unregistered for the standards
36
- * profile, the call delegates to the legacy path + emits a stderr
37
- * warning.
56
+ * The resolved IDE's `standardsProfile.rootFile` decides whether the writer
57
+ * emits the pointer file beside the shared body.
38
58
  */
39
59
  export function executeProjectStandardsInitIdeAware(options) {
40
60
  const ideId = resolveStandardsIdeId(options);
@@ -47,10 +67,10 @@ export function executeProjectStandardsInitIdeAware(options) {
47
67
  warnUnregisteredIde(ideId, options.projectRoot);
48
68
  return executeProjectStandardsInit(options);
49
69
  }
50
- // Claude Code path: profile matches the legacy writer. Future per-IDE
51
- // writers (markdown+frontmatter, multiple rule roots, etc.) plug in
52
- // here by branching on `profile.format` / `profile.rulesDir`.
53
- return executeProjectStandardsInit(options);
70
+ return executeProjectStandardsInit({
71
+ ...options,
72
+ constitution: resolveStandardsConstitution(profile)
73
+ });
54
74
  }
55
75
  /**
56
76
  * Run `peaks standards update` with IDE-aware dispatch.
@@ -68,19 +88,24 @@ export function executeProjectStandardsUpdateIdeAware(options) {
68
88
  warnUnregisteredIde(ideId, options.projectRoot);
69
89
  return executeProjectStandardsUpdate(options);
70
90
  }
71
- return executeProjectStandardsUpdate(options);
91
+ return executeProjectStandardsUpdate({
92
+ ...options,
93
+ constitution: resolveStandardsConstitution(profile)
94
+ });
72
95
  }
73
96
  /**
74
97
  * Test seam + integration-test helper: returns the resolved IDE id
75
- * for the call, plus the active standards profile. Exported for
76
- * to assert the dispatch decision without running the full write.
98
+ * for the call, plus the active standards profile and the constitution
99
+ * shape that profile implies. Exported for callers that need to assert the
100
+ * dispatch decision without running the full write.
77
101
  */
78
102
  export function inspectStandardsDispatch(options) {
79
103
  const ideId = resolveStandardsIdeId(options);
80
104
  if (ideId === null) {
81
- return { ideId: null, profile: null };
105
+ return { ideId: null, profile: null, constitution: DEFAULT_CONSTITUTION };
82
106
  }
83
- return { ideId, profile: getStandardsProfile(ideId) };
107
+ const profile = getStandardsProfile(ideId);
108
+ return { ideId, profile, constitution: resolveStandardsConstitution(profile) };
84
109
  }
85
110
  /**
86
111
  * Test seam: the resource-profile accessor exposes
@@ -6,6 +6,12 @@ export interface MigrateClaudeRulesData {
6
6
  readonly backupPath: string | null;
7
7
  readonly thinnedFiles: readonly string[];
8
8
  readonly scaffoldedFiles: readonly string[];
9
+ /**
10
+ * The constitution files this migration created — `AGENTS.md` (the shared
11
+ * cross-tool body) and the `CLAUDE.md` pointer that imports it. A file
12
+ * that already existed is never overwritten.
13
+ */
14
+ readonly scaffoldedConstitutionFiles: readonly string[];
9
15
  readonly preservedFiles: readonly string[];
10
16
  readonly wouldChange: boolean;
11
17
  readonly applied: boolean;
@@ -22,6 +22,9 @@
22
22
  */
23
23
  import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
24
24
  import { dirname, join } from 'node:path';
25
+ import { detectLanguage } from './project-standards-service.js';
26
+ import { detectProjectScripts } from './project-scripts.js';
27
+ import { DEFAULT_CONSTITUTION, scaffoldConstitutionFiles } from './standards-constitution.js';
25
28
  const POINTER_TEXT = (canonicalPath) => `# Canonical peaks-loop 2.0 rules live at: ${canonicalPath}\n# This file is a 2-line pointer. Edit the canonical file instead.\n`;
26
29
  function timestampSlug() {
27
30
  return new Date().toISOString().replace(/[:.]/g, '-');
@@ -129,6 +132,7 @@ export function migrateClaudeRules(input) {
129
132
  const thinnedFiles = [];
130
133
  const scaffoldedFiles = [];
131
134
  const preservedFiles = [];
135
+ const scaffoldedConstitutionFiles = [];
132
136
  // wouldChange is true iff there is at least one thick file to
133
137
  // thin. An empty .claude/rules/ is NOT a wouldChange (no-op).
134
138
  const wouldChange = hasThickFiles;
@@ -181,6 +185,16 @@ export function migrateClaudeRules(input) {
181
185
  warnings.push(`Scaffold step failed for ${file.relPath}: ${err instanceof Error ? err.message : String(err)}`);
182
186
  }
183
187
  }
188
+ // Step 4: scaffold the constitution — `AGENTS.md` (the shared
189
+ // cross-tool body) and the `CLAUDE.md` pointer that imports it.
190
+ // Existing files are never overwritten.
191
+ scaffoldedConstitutionFiles.push(...scaffoldConstitutionFiles({
192
+ projectRoot,
193
+ constitution: DEFAULT_CONSTITUTION,
194
+ language: detectLanguage(projectRoot),
195
+ scripts: detectProjectScripts(projectRoot),
196
+ rulesRoot: canonicalRelPath.replace(/\/$/, '')
197
+ }));
184
198
  }
185
199
  if (thinnedFiles.length > 0) {
186
200
  nextActions.push(`Thinned ${thinnedFiles.length} .md file(s) under .claude/rules (recursive) → 2-line pointer.`);
@@ -188,6 +202,9 @@ export function migrateClaudeRules(input) {
188
202
  if (scaffoldedFiles.length > 0) {
189
203
  nextActions.push(`Scaffolded ${scaffoldedFiles.length} 2.0 canonical rule(s) at .peaks/standards/.`);
190
204
  }
205
+ if (scaffoldedConstitutionFiles.length > 0) {
206
+ nextActions.push(`Scaffolded constitution file(s): ${scaffoldedConstitutionFiles.join(', ')} (AGENTS.md carries the body; CLAUDE.md imports it).`);
207
+ }
191
208
  if (preservedFiles.length > 0) {
192
209
  nextActions.push(`Preserved ${preservedFiles.length} existing .peaks/standards/ file(s) (no overwrite).`);
193
210
  }
@@ -203,6 +220,7 @@ export function migrateClaudeRules(input) {
203
220
  backupPath,
204
221
  thinnedFiles,
205
222
  scaffoldedFiles,
223
+ scaffoldedConstitutionFiles,
206
224
  preservedFiles,
207
225
  wouldChange,
208
226
  applied: apply && hasThickFiles,
@@ -26,7 +26,7 @@
26
26
  * - File missing → `file: null`, no throw.
27
27
  * - Legacy block not present → `foundOldBlock: false`, no write.
28
28
  */
29
- export declare const NEW_TEMPLATE_TEXT = "Active Peaks-Loop skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI handles canonical-path resolution (`.peaks/_runtime/active-skill.json` with back-compat fallback to `.peaks/.active-skill.json`); do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`. Display the header on every turn while the CLI returns an active skill; omit when the CLI returns no active skill.";
29
+ export declare const NEW_TEMPLATE_TEXT = "Active Peaks-Loop skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI resolves the session-scoped presence lease at `.peaks/_runtime/<sessionId>/leases/presence-*.json`; do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Loop Skill: <skill> | Peaks-Loop Role: <role> | Peaks-Loop Gate: <gate> | Peaks-Loop Context: <ratio%> (<zone>) | Next: <one short action>`. Copy `<role>` from the `data.role` field of that same read (`orchestrator` or `bee`; `null` for a skill outside both lists), and copy `<ratio%>` and `<zone>` from the `data.context.ratioPct` and `data.context.action` fields of that read \u2014 never judge the tier or estimate the context fill yourself. Display the header on every turn while the CLI returns an active skill; omit it when the CLI returns no active skill.";
30
30
  export type MigrateStandardsInput = {
31
31
  project: string;
32
32
  apply?: boolean;
@@ -1,5 +1,25 @@
1
1
  import { existsSync, readFileSync, writeFileSync } from 'node:fs';
2
2
  import { isAbsolute, resolve } from 'node:path';
3
+ import { PRESENCE_CONTRACT_TEXT } from './standards-render-common.js';
4
+ /**
5
+ * The constitution files a legacy block can live in, newest layout first.
6
+ *
7
+ * `AGENTS.md` carries the body today. `CLAUDE.md` is still checked because a
8
+ * 1.x-era consumer tree has only that one — migrating it is the whole point
9
+ * of this command.
10
+ */
11
+ const CONSTITUTION_CANDIDATES = ['AGENTS.md', 'CLAUDE.md'];
12
+ /**
13
+ * The file to migrate: the first constitution file that exists, or `null`.
14
+ */
15
+ function resolveMigrationTarget(projectRoot) {
16
+ for (const name of CONSTITUTION_CANDIDATES) {
17
+ const path = resolve(projectRoot, name);
18
+ if (existsSync(path))
19
+ return path;
20
+ }
21
+ return null;
22
+ }
3
23
  /**
4
24
  * project's `CLAUDE.md` to drop the legacy heartbeat block.
5
25
  *
@@ -28,7 +48,7 @@ import { isAbsolute, resolve } from 'node:path';
28
48
  * - File missing → `file: null`, no throw.
29
49
  * - Legacy block not present → `foundOldBlock: false`, no write.
30
50
  */
31
- export const NEW_TEMPLATE_TEXT = 'Active Peaks-Loop skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI handles canonical-path resolution (`.peaks/_runtime/active-skill.json` with back-compat fallback to `.peaks/.active-skill.json`); do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`. Display the header on every turn while the CLI returns an active skill; omit when the CLI returns no active skill.';
51
+ export const NEW_TEMPLATE_TEXT = PRESENCE_CONTRACT_TEXT;
32
52
  const LEGACY_BLOCK_OPENER_LINE = 'Peaks-Loop 心跳检测 (heartbeat check)';
33
53
  const LEGACY_BLOCK_CLOSER = 'External reference: https://github.com/affaan-m/everything-claude-code';
34
54
  const LEGACY_MARKER_FALLBACK = 'Do NOT skip step 3-5. The CLI heartbeat:touch command';
@@ -106,10 +126,10 @@ export function rewriteLegacyBlock(content, newText = NEW_TEMPLATE_TEXT) {
106
126
  export function migrateStandards(input) {
107
127
  const project = input.project;
108
128
  const projectRoot = isAbsolute(project) ? project : resolve(project);
109
- const filePath = resolve(projectRoot, 'CLAUDE.md');
129
+ const filePath = resolveMigrationTarget(projectRoot);
110
130
  const apply = input.apply === true;
111
131
  const dryRun = input.dryRun === true || apply === false;
112
- if (!existsSync(filePath)) {
132
+ if (filePath === null) {
113
133
  return {
114
134
  ok: true,
115
135
  data: {
@@ -119,7 +139,7 @@ export function migrateStandards(input) {
119
139
  applied: false,
120
140
  before: null,
121
141
  after: null,
122
- nextActions: ['CLAUDE.md does not exist; nothing to migrate']
142
+ nextActions: ['AGENTS.md does not exist; nothing to migrate']
123
143
  },
124
144
  warnings: []
125
145
  };
@@ -137,7 +157,7 @@ export function migrateStandards(input) {
137
157
  applied: false,
138
158
  before: { lines: original.split('\n').length },
139
159
  after: null,
140
- nextActions: ['CLAUDE.md is already up to date']
160
+ nextActions: ['AGENTS.md is already up to date']
141
161
  },
142
162
  warnings: []
143
163
  };
@@ -151,7 +171,7 @@ export function migrateStandards(input) {
151
171
  applied: false,
152
172
  before: { lines: original.split('\n').length },
153
173
  after: null,
154
- nextActions: ['CLAUDE.md has no peaks-loop block; nothing to migrate']
174
+ nextActions: ['AGENTS.md has no peaks-loop block; nothing to migrate']
155
175
  },
156
176
  warnings: []
157
177
  };
@@ -175,7 +195,7 @@ export function migrateStandards(input) {
175
195
  };
176
196
  }
177
197
  writeFileSync(filePath, rewritten, 'utf8');
178
- nextActions.push('CLAUDE.md rewritten; no further action required');
198
+ nextActions.push('AGENTS.md rewritten; no further action required');
179
199
  return {
180
200
  ok: true,
181
201
  data: {
@@ -0,0 +1,25 @@
1
+ /** The command categories the AGENTS.md body can carry. */
2
+ export type ProjectScriptCategory = 'build' | 'test' | 'lint';
3
+ export type ProjectScriptCommand = {
4
+ readonly category: ProjectScriptCategory;
5
+ /** The script name exactly as it appears in `package.json#scripts`. */
6
+ readonly script: string;
7
+ /** The exact command line to run. */
8
+ readonly command: string;
9
+ /** What the command does — one clause, so an agent can pick the right one. */
10
+ readonly purpose: string;
11
+ };
12
+ export type ProjectScripts = {
13
+ /** The package manager the command lines are spelled for. */
14
+ readonly packageManager: string;
15
+ /** At most one command per category, in category order. */
16
+ readonly commands: readonly ProjectScriptCommand[];
17
+ };
18
+ /**
19
+ * The exact commands this project really has, read from `package.json#scripts`.
20
+ *
21
+ * Returns an empty command list for a project without a readable
22
+ * `package.json` — the AGENTS.md body then carries no command section at all,
23
+ * which is the honest outcome for a project with no scripts to name.
24
+ */
25
+ export declare function detectProjectScripts(projectRoot: string): ProjectScripts;
@@ -0,0 +1,116 @@
1
+ /**
2
+ * The exact build / test / lint commands of a consumer project.
3
+ *
4
+ * WHY THIS EXISTS. The AGENTS.md body tells an agent which commands to run.
5
+ * A command that does not exist in the target project is worse than no command
6
+ * at all: the agent runs it, the tool call fails, and the turn is wasted. So
7
+ * every command in here is DERIVED from `package.json#scripts` — the script
8
+ * NAME is read from that file and the RUNNER is derived from the lockfile or
9
+ * the `packageManager` field. A category with no matching script is omitted
10
+ * rather than guessed, and no command is ever invented.
11
+ */
12
+ import { existsSync, readFileSync } from 'node:fs';
13
+ import { join } from 'node:path';
14
+ import { isExpectedFsMiss } from '../../shared/fs-utils.js';
15
+ /**
16
+ * The candidate scripts per category, most specific first. Each candidate
17
+ * carries its OWN purpose because `test:unit` does not run "the test suite" —
18
+ * it runs the unit tests, and an agent told otherwise runs the wrong thing.
19
+ */
20
+ const SCRIPT_CANDIDATES = [
21
+ { category: 'build', name: 'build', purpose: 'builds the project' },
22
+ { category: 'test', name: 'test', purpose: 'runs the test suite' },
23
+ { category: 'test', name: 'test:unit', purpose: 'runs the unit tests' },
24
+ { category: 'test', name: 'tests', purpose: 'runs the test suite' },
25
+ { category: 'lint', name: 'lint', purpose: 'runs the linter' },
26
+ { category: 'lint', name: 'lint:check', purpose: 'runs the linter in check mode' }
27
+ ];
28
+ /**
29
+ * Lockfile → runner. First hit wins; `package.json#packageManager` outranks
30
+ * every entry here, because that field is the project's own declaration.
31
+ */
32
+ const LOCKFILE_RUNNERS = [
33
+ { file: 'pnpm-lock.yaml', runner: 'pnpm' },
34
+ { file: 'yarn.lock', runner: 'yarn' },
35
+ { file: 'bun.lock', runner: 'bun' },
36
+ { file: 'bun.lockb', runner: 'bun' },
37
+ { file: 'package-lock.json', runner: 'npm' }
38
+ ];
39
+ const DEFAULT_RUNNER = 'npm';
40
+ function readPackageJson(projectRoot) {
41
+ const pkgPath = join(projectRoot, 'package.json');
42
+ if (!existsSync(pkgPath))
43
+ return null;
44
+ try {
45
+ return JSON.parse(readFileSync(pkgPath, 'utf8'));
46
+ }
47
+ catch (err) {
48
+ // Only an EXPECTED FS miss means "no readable package.json here" — the
49
+ // same answer the guard above gives. Anything else (a malformed
50
+ // package.json, a TypeError) is a real defect and must surface instead
51
+ // of being flattened into "this project has no scripts".
52
+ if (isExpectedFsMiss(err))
53
+ return null;
54
+ throw err;
55
+ }
56
+ }
57
+ /** `pnpm@10.11.0` → `pnpm`. */
58
+ function runnerFromPackageManagerField(value) {
59
+ if (value === undefined)
60
+ return null;
61
+ const trimmed = value.trim();
62
+ if (trimmed.length === 0)
63
+ return null;
64
+ const at = trimmed.lastIndexOf('@');
65
+ const name = at > 0 ? trimmed.slice(0, at) : trimmed;
66
+ return name.length > 0 ? name : null;
67
+ }
68
+ function runnerFromLockfile(projectRoot) {
69
+ for (const entry of LOCKFILE_RUNNERS) {
70
+ if (existsSync(join(projectRoot, entry.file)))
71
+ return entry.runner;
72
+ }
73
+ return DEFAULT_RUNNER;
74
+ }
75
+ /** The exact command line for one script under one runner. */
76
+ function commandLine(runner, script) {
77
+ if (runner === 'npm')
78
+ return `npm run ${script}`;
79
+ if (runner === 'yarn')
80
+ return `yarn ${script}`;
81
+ if (runner === 'bun')
82
+ return `bun run ${script}`;
83
+ if (runner === 'pnpm')
84
+ return `pnpm ${script}`;
85
+ return `${runner} run ${script}`;
86
+ }
87
+ /**
88
+ * The exact commands this project really has, read from `package.json#scripts`.
89
+ *
90
+ * Returns an empty command list for a project without a readable
91
+ * `package.json` — the AGENTS.md body then carries no command section at all,
92
+ * which is the honest outcome for a project with no scripts to name.
93
+ */
94
+ export function detectProjectScripts(projectRoot) {
95
+ const pkg = readPackageJson(projectRoot);
96
+ if (pkg === null)
97
+ return { packageManager: DEFAULT_RUNNER, commands: [] };
98
+ const scripts = pkg.scripts ?? {};
99
+ const packageManager = runnerFromPackageManagerField(pkg.packageManager) ?? runnerFromLockfile(projectRoot);
100
+ const commands = [];
101
+ const seen = new Set();
102
+ for (const candidate of SCRIPT_CANDIDATES) {
103
+ if (seen.has(candidate.category))
104
+ continue;
105
+ if (!(candidate.name in scripts))
106
+ continue;
107
+ seen.add(candidate.category);
108
+ commands.push({
109
+ category: candidate.category,
110
+ script: candidate.name,
111
+ command: commandLine(packageManager, candidate.name),
112
+ purpose: candidate.purpose
113
+ });
114
+ }
115
+ return { packageManager, commands };
116
+ }
@@ -1,3 +1,4 @@
1
+ import { type ConstitutionUpdate, type ConstitutionUpdateSummary, type StandardsConstitution } from './standards-constitution.js';
1
2
  export { renderUiLibraryPriorityRule } from './standards-render.js';
2
3
  /**
3
4
  * Typed error raised when a planned `peaks standards` write target would
@@ -40,10 +41,18 @@ export type ProjectStandardsInitPlan = {
40
41
  readonly language: StandardsLanguage;
41
42
  readonly source: ProjectStandardsSource;
42
43
  readonly skillPreflight: StandardsSkillPreflight;
44
+ /** Which instruction files this project owns, and where its standards live. */
45
+ readonly constitution: StandardsConstitution;
46
+ /** The directory the project's standards files live in. */
47
+ readonly rulesRoot: string;
48
+ /** The four-state constitution write plan, shared by `init` and `update`. */
49
+ readonly constitutionUpdate: ConstitutionUpdate;
43
50
  readonly plannedWrites: StandardsWrite[];
44
51
  };
45
52
  export type ProjectStandardsInitResult = ProjectStandardsInitPlan & {
46
53
  readonly writtenFiles: string[];
54
+ /** Why a constitution file was left for a human, when one was. */
55
+ readonly reviewSuggestions: string[];
47
56
  };
48
57
  export type ProjectStandardsInitSummary = {
49
58
  readonly apply: boolean;
@@ -54,17 +63,13 @@ export type ProjectStandardsInitSummary = {
54
63
  readonly plannedWrites: Array<Pick<StandardsWrite, 'relativePath' | 'status'>>;
55
64
  readonly writtenFiles: string[];
56
65
  readonly skippedFiles: string[];
66
+ readonly reviewSuggestions: string[];
57
67
  };
58
- export type ProjectStandardsUpdatePlan = ProjectStandardsInitPlan & {
59
- readonly claudeMd: {
60
- readonly relativePath: 'CLAUDE.md';
61
- readonly filePath: string;
62
- readonly status: StandardsWriteStatus;
63
- readonly content: string;
64
- readonly appendBlock: string;
65
- readonly reviewSuggestions: string[];
66
- };
67
- };
68
+ /**
69
+ * The update plan — the init plan, which already carries the constitution
70
+ * write plan the update applies.
71
+ */
72
+ export type ProjectStandardsUpdatePlan = ProjectStandardsInitPlan;
68
73
  export type ProjectStandardsUpdateResult = ProjectStandardsUpdatePlan & {
69
74
  readonly writtenFiles: string[];
70
75
  readonly appendedFiles: string[];
@@ -81,11 +86,7 @@ export type ProjectStandardsUpdateSummary = {
81
86
  readonly appendedFiles: string[];
82
87
  readonly skippedFiles: string[];
83
88
  readonly reviewSuggestions: string[];
84
- readonly claudeMd: {
85
- readonly relativePath: 'CLAUDE.md';
86
- readonly status: StandardsWriteStatus;
87
- readonly reviewSuggestions: string[];
88
- };
89
+ readonly constitutionUpdate: ConstitutionUpdateSummary;
89
90
  };
90
91
  export type ProjectStandardsInitOptions = {
91
92
  readonly projectRoot: string;
@@ -99,6 +100,13 @@ export type ProjectStandardsInitOptions = {
99
100
  * mutating global Node state (which is read-only).
100
101
  */
101
102
  readonly resolveHomedir?: () => string;
103
+ /**
104
+ * Which instruction files this project owns. Defaults to
105
+ * {@link DEFAULT_CONSTITUTION} — the body file plus the pointer that
106
+ * imports it. The IDE-aware layer narrows it for IDEs that read the body
107
+ * file directly and need no pointer.
108
+ */
109
+ readonly constitution?: StandardsConstitution;
102
110
  };
103
111
  /**
104
112
  * Public alias for `detectLanguageInternal` so callers outside this