peaks-loop 4.1.18 → 4.1.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +126 -0
  3. package/README-en.md +6 -0
  4. package/README.md +5 -0
  5. package/contracts/test-style-contract.md +14 -5
  6. package/dist/cli/commands/audit-red-lines-runners.js +6 -1
  7. package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
  8. package/dist/cli/commands/best-practice-scan-collision.js +115 -0
  9. package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
  10. package/dist/cli/commands/best-practice-scan-command.js +9 -18
  11. package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
  12. package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
  13. package/dist/cli/commands/code-auto-compact-command.js +26 -18
  14. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  15. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  16. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  17. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  18. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  19. package/dist/cli/commands/core/standards-init-command.js +44 -8
  20. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  21. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  22. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  23. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  24. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  25. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  26. package/dist/cli/commands/mut-commands.d.ts +9 -1
  27. package/dist/cli/commands/mut-commands.js +82 -154
  28. package/dist/cli/commands/preferences-commands.js +27 -2
  29. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  30. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  31. package/dist/services/24h-mode/auto-engage.js +14 -6
  32. package/dist/services/artifacts/artifact-templates.js +10 -0
  33. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  34. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  35. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  36. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  37. package/dist/services/artifacts/request-artifact-service.js +6 -6
  38. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  39. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  40. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  41. package/dist/services/audit/static-service.js +4 -4
  42. package/dist/services/code/auto-compact-history.d.ts +6 -1
  43. package/dist/services/code/auto-compact-history.js +6 -1
  44. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  45. package/dist/services/code/auto-compact-modes.js +75 -20
  46. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  47. package/dist/services/code/auto-compact-profile.js +51 -0
  48. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  49. package/dist/services/compact-history/compact-history-service.js +5 -1
  50. package/dist/services/context/auto-compact-types.d.ts +7 -5
  51. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  52. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  53. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  54. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  55. package/dist/services/doctor/doctor-service/plugin-registry.js +2 -0
  56. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  57. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  58. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  59. package/dist/services/hooks/presence-marker-detector.js +21 -19
  60. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  61. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  62. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  63. package/dist/services/mode/mode-status-service.d.ts +26 -27
  64. package/dist/services/mode/mode-status-service.js +36 -60
  65. package/dist/services/preferences/preferences-types.d.ts +30 -0
  66. package/dist/services/preferences/preferences-types.js +13 -0
  67. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  68. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  69. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  70. package/dist/services/scan/rid-change-claims.js +116 -0
  71. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  72. package/dist/services/skills/presence-caller-id.js +43 -0
  73. package/dist/services/skills/presence-gate.d.ts +65 -0
  74. package/dist/services/skills/presence-gate.js +113 -0
  75. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  76. package/dist/services/skills/presence-lease-resolver.js +114 -0
  77. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  78. package/dist/services/skills/presence-lease-selection.js +135 -0
  79. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  80. package/dist/services/skills/presence-lease-service.js +34 -87
  81. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  82. package/dist/services/skills/presence-lease-store.js +94 -0
  83. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  84. package/dist/services/skills/presence-lease-types.js +27 -0
  85. package/dist/services/skills/presence-role.d.ts +35 -0
  86. package/dist/services/skills/presence-role.js +72 -0
  87. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  88. package/dist/services/skills/skill-presence-service.js +143 -174
  89. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  90. package/dist/services/skills/skill-presence-write.js +74 -0
  91. package/dist/services/skills/skill-statusline-service.js +7 -7
  92. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  93. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  94. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  95. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  96. package/dist/services/standards/migrate-service.d.ts +1 -1
  97. package/dist/services/standards/migrate-service.js +27 -7
  98. package/dist/services/standards/project-scripts.d.ts +25 -0
  99. package/dist/services/standards/project-scripts.js +116 -0
  100. package/dist/services/standards/project-standards-service.d.ts +23 -15
  101. package/dist/services/standards/project-standards-service.js +176 -243
  102. package/dist/services/standards/standards-constitution.d.ts +89 -0
  103. package/dist/services/standards/standards-constitution.js +199 -0
  104. package/dist/services/standards/standards-files.d.ts +37 -0
  105. package/dist/services/standards/standards-files.js +138 -0
  106. package/dist/services/standards/standards-pointer.d.ts +73 -0
  107. package/dist/services/standards/standards-pointer.js +98 -0
  108. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  109. package/dist/services/standards/standards-render-agents.js +149 -0
  110. package/dist/services/standards/standards-render-common.d.ts +38 -1
  111. package/dist/services/standards/standards-render-common.js +44 -7
  112. package/dist/services/standards/standards-render.d.ts +1 -3
  113. package/dist/services/standards/standards-render.js +6 -87
  114. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  115. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  116. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  117. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  118. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  119. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  120. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  121. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  122. package/dist/services/workspace/runtime-layout.js +62 -0
  123. package/output-styles/peaks-skill-swarm.md +18 -2
  124. package/package.json +8 -9
  125. package/schemas/doctor-report.schema.json +1 -1
  126. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  127. package/skills/bee/peaks-prd/SKILL.md +5 -3
  128. package/skills/bee/peaks-qa/SKILL.md +4 -2
  129. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  130. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  131. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  132. package/skills/bee/peaks-rd/SKILL.md +4 -2
  133. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  134. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  135. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  136. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +4 -4
  137. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  138. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  139. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  140. package/skills/bee/peaks-sc/SKILL.md +4 -2
  141. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  142. package/skills/bee/peaks-txt/SKILL.md +5 -3
  143. package/skills/bee/peaks-ui/SKILL.md +6 -4
  144. package/skills/peaks-audit/SKILL.md +3 -1
  145. package/skills/peaks-code/SKILL.md +3 -1
  146. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  147. package/skills/peaks-code/references/completion-handoff.md +1 -1
  148. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  149. package/skills/peaks-code/references/micro-cycle.md +2 -2
  150. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  151. package/skills/peaks-code/references/runbook.md +4 -4
  152. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  153. package/skills/peaks-code/references/standards-preflight.md +7 -6
  154. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  155. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  156. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  157. package/skills/peaks-content/SKILL.md +3 -1
  158. package/skills/peaks-doctor/SKILL.md +3 -1
  159. package/skills/peaks-final-review/SKILL.md +3 -1
  160. package/skills/peaks-ide/SKILL.md +3 -1
  161. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  162. package/skills/peaks-race-code/SKILL.md +3 -1
  163. package/skills/peaks-resume/SKILL.md +3 -1
  164. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  165. package/skills/peaks-solo/SKILL.md +3 -1
  166. package/skills/peaks-sop/SKILL.md +4 -2
  167. package/skills/peaks-status/SKILL.md +3 -1
  168. package/skills/peaks-test/SKILL.md +3 -1
@@ -0,0 +1,149 @@
1
+ /**
2
+ * The cross-tool constitution: `AGENTS.md` carries the body, `CLAUDE.md`
3
+ * imports it.
4
+ *
5
+ * WHY TWO FILES. `AGENTS.md` is the cross-tool standard (OpenAI's AGENTS.md,
6
+ * now under the Linux Foundation's Agentic AI Foundation) — 20+ tools read it
7
+ * natively, which is a wider reach than `CLAUDE.md` has. Claude Code reads it
8
+ * too, but only when the project has no `CLAUDE.md` of its own, and Claude
9
+ * Code's own project instructions are `CLAUDE.md`. So the body lives in
10
+ * `AGENTS.md` and `CLAUDE.md` is a pointer that imports it. One body, two
11
+ * readers, no drift.
12
+ *
13
+ * THE IMPORT SYNTAX IS `@AGENTS.md` ON ITS OWN LINE — Claude Code's
14
+ * documented "Import additional files" form (`@path/to/import`), verified
15
+ * against https://code.claude.com/docs/en/memory#import-additional-files.
16
+ * Two facts from that page shape the file: a backticked `@AGENTS.md` is
17
+ * LITERAL text and is NOT imported, and a quoted path is not imported at all.
18
+ * So exactly ONE unbackticked `@AGENTS.md` appears here, and every other
19
+ * mention of the file name is backticked.
20
+ *
21
+ * THE DEGRADED FORM. A tool that does not understand the import sees one
22
+ * pointer line instead of the body — not "nothing". The pointer therefore
23
+ * also names `AGENTS.md` in prose, so a tool that reads the file literally
24
+ * still learns where the instructions are.
25
+ */
26
+ import { PRESENCE_CONTRACT_TEXT } from './standards-render-common.js';
27
+ /** The shared, cross-tool instruction body. */
28
+ export const AGENTS_MD_FILENAME = 'AGENTS.md';
29
+ /** The IDE-native file that imports the body. */
30
+ export const CLAUDE_MD_FILENAME = 'CLAUDE.md';
31
+ /**
32
+ * The Claude Code import line — `@AGENTS.md`, on a line of its own.
33
+ *
34
+ * It is declared here, next to the renderer that prints it, because the line
35
+ * is a SYNTAX CONTRACT and not prose: the writer that adds it and the planner
36
+ * that looks for it must agree on its exact spelling, and one declaration is
37
+ * the only way they can. `standards-pointer.ts` owns the rules around it.
38
+ */
39
+ export const CLAUDE_MD_POINTER_LINE = '@AGENTS.md';
40
+ /** The category label the AGENTS.md body prints in front of each command. */
41
+ const CATEGORY_LABELS = {
42
+ build: 'Build',
43
+ test: 'Test',
44
+ lint: 'Lint'
45
+ };
46
+ /**
47
+ * The exact commands, one line per command, each with its purpose.
48
+ *
49
+ * No command line appears that the project does not actually have — a missing
50
+ * category produces no line at all, because a command an agent cannot run is
51
+ * a failed tool call, not an instruction.
52
+ */
53
+ function renderCommandSection(scripts) {
54
+ if (scripts.commands.length === 0)
55
+ return [];
56
+ const lines = ['## Build, test and lint commands', ''];
57
+ for (const entry of scripts.commands) {
58
+ lines.push(`- ${CATEGORY_LABELS[entry.category]}: \`${entry.command}\` — ${entry.purpose}.`);
59
+ }
60
+ lines.push('');
61
+ return lines;
62
+ }
63
+ /**
64
+ * The standards the agent must read before acting.
65
+ *
66
+ * `rulesRoot` is the directory the project's standards actually live in:
67
+ * `.peaks/standards` for the 2.0 canonical layout, `.claude/rules` for a
68
+ * project still carrying the 1.x tree.
69
+ */
70
+ function renderStandardsSection(language, rulesRoot) {
71
+ return [
72
+ '## Peaks standards to read',
73
+ '',
74
+ `- Read \`${rulesRoot}/common/coding-style.md\` before editing code.`,
75
+ `- Read \`${rulesRoot}/common/code-review.md\` before reviewing changes.`,
76
+ `- Read \`${rulesRoot}/common/security.md\` before touching filesystem, user input, external calls, auth, or secrets.`,
77
+ `- Read \`${rulesRoot}/${language}/coding-style.md\` for language-specific standards when applicable.`,
78
+ ''
79
+ ];
80
+ }
81
+ /** The per-role preflight contract the Peaks workflow roles rely on. */
82
+ function renderWorkflowSection() {
83
+ return [
84
+ '## Peaks workflow automation',
85
+ '',
86
+ '- peaks-rd checks these standards before RD planning or implementation work.',
87
+ '- peaks-qa checks code review and security guidance before verification work.',
88
+ '- peaks-code summarizes RD and QA standards preflight before end-to-end code workflows.',
89
+ ''
90
+ ];
91
+ }
92
+ /** The skill-presence / status-header contract. The text is shared with `peaks standards migrate`. */
93
+ function renderPresenceSection() {
94
+ return ['## Active Peaks-Loop skill presence', '', PRESENCE_CONTRACT_TEXT, ''];
95
+ }
96
+ /**
97
+ * The provenance marker.
98
+ *
99
+ * It is KEPT — an AI-generated instruction file that reads as if a human had
100
+ * written it is exactly the failure the research behind this layout warns
101
+ * about. It is placed LAST, under its own heading, so it cannot be read as
102
+ * one more instruction at the top of the file.
103
+ */
104
+ function renderProvenanceSection() {
105
+ return ['## Provenance', '', '> 🤖 AI 生成,请审阅', ''];
106
+ }
107
+ /**
108
+ * The AGENTS.md body.
109
+ *
110
+ * Kept short on purpose: the whole file is loaded on every turn, and a
111
+ * research finding behind this layout says an LLM-generated instruction file
112
+ * that is padded with derivable facts lowers task success and raises
113
+ * reasoning cost. Facts the agent can read off `package.json` (the build
114
+ * tool, the dependency list) are therefore NOT repeated here — they live in
115
+ * the standards files this body points at.
116
+ */
117
+ export function renderAgentsMd(language, scripts, rulesRoot) {
118
+ const lines = [
119
+ '# Project Instructions',
120
+ '',
121
+ 'This repository uses project-local Peaks standards. Existing repository conventions override generic generated guidance.',
122
+ ''
123
+ ];
124
+ lines.push(...renderCommandSection(scripts));
125
+ lines.push(...renderStandardsSection(language, rulesRoot));
126
+ lines.push(...renderWorkflowSection());
127
+ lines.push(...renderPresenceSection());
128
+ lines.push(...renderProvenanceSection());
129
+ return `${lines.join('\n').trimEnd()}\n`;
130
+ }
131
+ /**
132
+ * The CLAUDE.md pointer.
133
+ *
134
+ * `@AGENTS.md` is the import. It must stay unbackticked and unquoted — Claude
135
+ * Code skips code spans and does not import a quoted path — and it must be the
136
+ * only such occurrence in the file, or the body is loaded twice.
137
+ */
138
+ export function renderClaudeMdPointer() {
139
+ return [
140
+ '# Project Instructions',
141
+ '',
142
+ CLAUDE_MD_POINTER_LINE,
143
+ '',
144
+ 'The project instructions live in `AGENTS.md` — the file every coding agent in this',
145
+ 'project shares. This file exists only so Claude Code loads that body: edit',
146
+ '`AGENTS.md`, not this file.',
147
+ ''
148
+ ].join('\n');
149
+ }
@@ -11,5 +11,42 @@
11
11
  import type { ProjectContext } from './project-context.js';
12
12
  import type { StandardsLanguage } from './project-standards-service.js';
13
13
  export declare function renderHeader(title: string): string;
14
+ /**
15
+ * The skill-presence / status-header contract every Peaks instruction file
16
+ * carries.
17
+ *
18
+ * ONE source for the text: the AGENTS.md body renders it verbatim and
19
+ * `peaks standards migrate` replaces the legacy heartbeat block with exactly
20
+ * this paragraph — so a migrated file and a freshly generated one cannot
21
+ * drift apart.
22
+ *
23
+ * THE HEADER IS FIVE SEGMENTS. `Peaks-Loop Skill | Peaks-Loop Role |
24
+ * Peaks-Loop Gate | Peaks-Loop Context | Next` — the shape the response
25
+ * contract in `.claude/output-styles/peaks-skill-swarm.md` publishes. Every
26
+ * cell but `Next` is a MACHINE FACT read from one `peaks skill presence --json`
27
+ * call: `data.skill`, `data.role`, `data.gate`, `data.context.ratioPct` and
28
+ * `data.context.action`. The contract therefore names where each cell comes
29
+ * from, because a cell the model fills in from its own judgement is not a
30
+ * status header — it is prose with a header's punctuation.
31
+ *
32
+ * THE PATH IS THE CORRECTED ONE. `.peaks/_runtime/active-skill.json` and its
33
+ * legacy sibling `.peaks/.active-skill.json` were removed from the presence
34
+ * service in 4.0.11; the canonical projection is the session-scoped lease at
35
+ * `.peaks/_runtime/<sessionId>/leases/presence-*.json`. The instruction is
36
+ * "ask the CLI", because the CLI is what resolves the lease.
37
+ */
38
+ export declare const PRESENCE_CONTRACT_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.";
14
39
  export declare function renderCodeReview(ctx: ProjectContext): string;
15
- export declare function renderManagedClaudeMdIndex(language: StandardsLanguage): string;
40
+ /**
41
+ * The managed standards block `peaks standards update` maintains.
42
+ *
43
+ * It names `AGENTS.md` as the constitution because that is where the body
44
+ * lives now; `CLAUDE.md` imports it. The block is appended to whichever
45
+ * constitution file the writer owns, so it must read correctly in both.
46
+ *
47
+ * `rulesRoot` is the directory the project's standards actually live in:
48
+ * `.peaks/standards` for the 2.0 canonical layout, `.claude/rules` for a
49
+ * project still carrying the 1.x tree. The block names FILES, so it must
50
+ * name the ones that are really there.
51
+ */
52
+ export declare function renderManagedStandardsIndex(language: StandardsLanguage, rulesRoot: string): string;
@@ -7,6 +7,31 @@ export function renderHeader(title) {
7
7
  ''
8
8
  ].join('\n');
9
9
  }
10
+ /**
11
+ * The skill-presence / status-header contract every Peaks instruction file
12
+ * carries.
13
+ *
14
+ * ONE source for the text: the AGENTS.md body renders it verbatim and
15
+ * `peaks standards migrate` replaces the legacy heartbeat block with exactly
16
+ * this paragraph — so a migrated file and a freshly generated one cannot
17
+ * drift apart.
18
+ *
19
+ * THE HEADER IS FIVE SEGMENTS. `Peaks-Loop Skill | Peaks-Loop Role |
20
+ * Peaks-Loop Gate | Peaks-Loop Context | Next` — the shape the response
21
+ * contract in `.claude/output-styles/peaks-skill-swarm.md` publishes. Every
22
+ * cell but `Next` is a MACHINE FACT read from one `peaks skill presence --json`
23
+ * call: `data.skill`, `data.role`, `data.gate`, `data.context.ratioPct` and
24
+ * `data.context.action`. The contract therefore names where each cell comes
25
+ * from, because a cell the model fills in from its own judgement is not a
26
+ * status header — it is prose with a header's punctuation.
27
+ *
28
+ * THE PATH IS THE CORRECTED ONE. `.peaks/_runtime/active-skill.json` and its
29
+ * legacy sibling `.peaks/.active-skill.json` were removed from the presence
30
+ * service in 4.0.11; the canonical projection is the session-scoped lease at
31
+ * `.peaks/_runtime/<sessionId>/leases/presence-*.json`. The instruction is
32
+ * "ask the CLI", because the CLI is what resolves the lease.
33
+ */
34
+ export const PRESENCE_CONTRACT_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 — 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.';
10
35
  export function renderCodeReview(ctx) {
11
36
  const baseRules = [
12
37
  '- Review diffs for correctness, maintainability, test coverage, and regression risk.',
@@ -30,18 +55,30 @@ export function renderCodeReview(ctx) {
30
55
  const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific review focus', ...extra] : baseRules;
31
56
  return `${renderHeader('Code Review Standards')}${rules.join('\n')}\n`;
32
57
  }
33
- export function renderManagedClaudeMdIndex(language) {
58
+ /**
59
+ * The managed standards block `peaks standards update` maintains.
60
+ *
61
+ * It names `AGENTS.md` as the constitution because that is where the body
62
+ * lives now; `CLAUDE.md` imports it. The block is appended to whichever
63
+ * constitution file the writer owns, so it must read correctly in both.
64
+ *
65
+ * `rulesRoot` is the directory the project's standards actually live in:
66
+ * `.peaks/standards` for the 2.0 canonical layout, `.claude/rules` for a
67
+ * project still carrying the 1.x tree. The block names FILES, so it must
68
+ * name the ones that are really there.
69
+ */
70
+ export function renderManagedStandardsIndex(language, rulesRoot) {
34
71
  return [
35
72
  '<!-- peaks-standards:index:start -->',
36
73
  '## Peaks Standards Index',
37
- '- Constitution: `CLAUDE.md` is the repository-wide constitution.',
38
- '- Local laws: `.peaks/standards/**` are project-local laws and are created only when missing.',
74
+ '- Constitution: `AGENTS.md` is the repository-wide constitution.',
75
+ `- Local laws: \`${rulesRoot}/**\` are project-local laws and are created only when missing.`,
39
76
  '- Managed by: `peaks standards update`.',
40
77
  '- Managed files:',
41
- ' - `.peaks/standards/common/code-review.md`',
42
- ' - `.peaks/standards/common/coding-style.md`',
43
- ' - `.peaks/standards/common/security.md`',
44
- ` - .peaks/standards/${language}/coding-style.md`,
78
+ ` - \`${rulesRoot}/common/code-review.md\``,
79
+ ` - \`${rulesRoot}/common/coding-style.md\``,
80
+ ` - \`${rulesRoot}/common/security.md\``,
81
+ ` - ${rulesRoot}/${language}/coding-style.md`,
45
82
  '- Conflict note: keep the existing body unchanged and resolve any disagreement manually before the next standards update.',
46
83
  '<!-- peaks-standards:index:end -->',
47
84
  ''
@@ -5,7 +5,6 @@
5
5
  */
6
6
  import { type ProjectContext } from './project-context.js';
7
7
  import type { StandardsLanguage } from './project-standards-service.js';
8
- export declare function renderClaudeMd(language: StandardsLanguage, ctx: ProjectContext): string;
9
8
  export declare function renderCommonCodingStyle(ctx: ProjectContext): string;
10
9
  export declare function renderSecurity(ctx: ProjectContext): string;
11
10
  /**
@@ -17,5 +16,4 @@ export declare function renderSecurity(ctx: ProjectContext): string;
17
16
  */
18
17
  export declare function renderUiLibraryPriorityRule(ctx: ProjectContext): string | null;
19
18
  export declare function renderLanguageCodingStyle(language: StandardsLanguage, ctx: ProjectContext): string;
20
- export declare function renderClaudeMdOneX(language: StandardsLanguage, ctx: ProjectContext): string;
21
- export { renderCodeReview, renderManagedClaudeMdIndex } from './standards-render-common.js';
19
+ export { renderCodeReview, renderManagedStandardsIndex } from './standards-render-common.js';
@@ -3,64 +3,7 @@
3
3
  * service stays under the 800-line cap. Behaviour-preserving verbatim move;
4
4
  * `export` keywords were added to the symbols the service still imports.
5
5
  */
6
- import { buildToolLabel, componentLibraryLabel, cssFrameworkLabel } from './project-context.js';
7
6
  import { renderHeader } from './standards-render-common.js';
8
- function renderProjectStackSection(ctx) {
9
- if (!ctx.hasPackageJson)
10
- return '';
11
- const lines = ['## Detected project stack', ''];
12
- lines.push(`- Build tool: ${buildToolLabel(ctx.buildTool)}${ctx.buildConfigPath !== undefined ? ` (\`${ctx.buildConfigPath}\`)` : ''}`);
13
- lines.push(`- Component library: ${componentLibraryLabel(ctx.componentLibrary)}`);
14
- if (ctx.cssFrameworks.length > 0) {
15
- lines.push(`- CSS: ${ctx.cssFrameworks.map(cssFrameworkLabel).join(', ')}`);
16
- }
17
- if (ctx.stateManagement.length > 0)
18
- lines.push(`- State management: ${ctx.stateManagement.join(', ')}`);
19
- if (ctx.routing.length > 0)
20
- lines.push(`- Routing: ${ctx.routing.join(', ')}`);
21
- if (ctx.dataFetching.length > 0)
22
- lines.push(`- Data fetching: ${ctx.dataFetching.join(', ')}`);
23
- if (ctx.notableDeps.length > 0)
24
- lines.push(`- Notable deps: ${ctx.notableDeps.join(', ')}`);
25
- lines.push('');
26
- if (ctx.cssConflicts.length > 0) {
27
- lines.push('## CSS framework conflicts', '');
28
- for (const conflict of ctx.cssConflicts)
29
- lines.push(`- ${conflict}`);
30
- lines.push('');
31
- }
32
- if (ctx.legacySignals.length > 0) {
33
- lines.push('## Legacy constraints (preserve for new code in the same modules)', '');
34
- for (const signal of ctx.legacySignals)
35
- lines.push(`- ${signal}`);
36
- lines.push('');
37
- }
38
- return lines.join('\n');
39
- }
40
- export function renderClaudeMd(language, ctx) {
41
- const head = [
42
- '# Project Instructions',
43
- '',
44
- '> 🤖 AI 生成,请审阅',
45
- '',
46
- 'This repository uses project-local Peaks standards. Existing repository conventions override generic generated guidance.',
47
- '',
48
- 'Peaks workflow automation:',
49
- '- peaks-rd checks these standards before RD planning or implementation work.',
50
- '- peaks-qa checks code review and security guidance before verification work.',
51
- '- peaks-code summarizes RD and QA standards preflight before end-to-end code workflows.',
52
- '',
53
- 'Rules:',
54
- '- Read `.peaks/standards/common/coding-style.md` before editing code.',
55
- '- Read `.peaks/standards/common/code-review.md` before reviewing changes.',
56
- '- Read `.peaks/standards/common/security.md` before touching filesystem, user input, external calls, auth, or secrets.',
57
- `- Read .peaks/standards/${language}/coding-style.md for language-specific standards when applicable.`,
58
- '',
59
- '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.'
60
- ].join('\n');
61
- const stack = renderProjectStackSection(ctx);
62
- return stack === '' ? head : `${head}\n${stack}`;
63
- }
64
7
  export function renderCommonCodingStyle(ctx) {
65
8
  const baseRules = [
66
9
  '- Prefer simple, readable code over clever abstractions.',
@@ -171,8 +114,8 @@ export function renderLanguageCodingStyle(language, ctx) {
171
114
  extra.push("- Use the project's existing service-layer pattern (`src/services/**`) for API calls; do not hand-roll `fetch` in components.");
172
115
  }
173
116
  // UI library priority (effective 2026-08-01). Applies to any project whose
174
- // scan identified one of the supported component libraries; the rule
175
- // is generated by the standards update so it ships to every downstream
117
+ // scan identified one of the supported component libraries; the rule is
118
+ // generated by the standards update so it ships to every downstream
176
119
  // project through `peaks standards init/update`.
177
120
  const uiRule = renderUiLibraryPriorityRule(ctx);
178
121
  if (uiRule !== null)
@@ -180,31 +123,7 @@ export function renderLanguageCodingStyle(language, ctx) {
180
123
  const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific rules', ...extra] : baseRules;
181
124
  return `${renderHeader(`${languageName} Coding Standards`)}${rules.join('\n')}\n`;
182
125
  }
183
- export function renderClaudeMdOneX(language, ctx) {
184
- const head = [
185
- '# Project Instructions',
186
- '',
187
- '> 🤖 AI 生成,请审阅',
188
- '',
189
- 'This repository uses project-local Peaks standards. Existing repository conventions override generic generated guidance.',
190
- '',
191
- 'Peaks workflow automation:',
192
- '- peaks-rd checks these standards before RD planning or implementation work.',
193
- '- peaks-qa checks code review and security guidance before verification work.',
194
- '- peaks-code summarizes RD and QA standards preflight before end-to-end code workflows.',
195
- '',
196
- 'Rules:',
197
- '- Read `.claude/rules/common/coding-style.md` before editing code.',
198
- '- Read `.claude/rules/common/code-review.md` before reviewing changes.',
199
- '- Read `.claude/rules/common/security.md` before touching filesystem, user input, external calls, auth, or secrets.',
200
- `- Read .claude/rules/${language}/coding-style.md for language-specific standards when applicable.`,
201
- '',
202
- '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.'
203
- ].join('\n');
204
- const stack = renderProjectStackSection(ctx);
205
- return stack === '' ? head : `${head}\n${stack}`;
206
- }
207
- // `renderHeader` lives in standards-render-common.ts (imported above);
208
- // `renderCodeReview` and `renderManagedClaudeMdIndex` are re-exported
209
- // from there so importers keep using this same path.
210
- export { renderCodeReview, renderManagedClaudeMdIndex } from './standards-render-common.js';
126
+ // `renderHeader` and `PRESENCE_CONTRACT_TEXT` live in standards-render-common.ts
127
+ // (imported above); `renderCodeReview` and `renderManagedStandardsIndex` are
128
+ // re-exported from there so importers keep using the same path.
129
+ export { renderCodeReview, renderManagedStandardsIndex } from './standards-render-common.js';
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Workflow graph creation and existence.
3
+ *
4
+ * WHY THIS MODULE EXISTS. A presence lease names the graph it belongs to
5
+ * (`graphRef: graphs/<workflowId>.json`) and the terminalize path requires
6
+ * that graph to be on disk. The lease write path created the lease and
7
+ * nothing else, so a lease written by `skill presence:set` pointed at a
8
+ * graph that was never written and could not be terminalized. Both write
9
+ * paths build their graph through this module, so the file on disk is the
10
+ * same graph either way.
11
+ *
12
+ * WHAT IT DOES NOT DO. `ensureGraphExists` never rewrites a graph that is
13
+ * already on disk. A graph that is present but corrupt is left exactly as it
14
+ * is, so the read and terminalize paths keep failing closed on it; only the
15
+ * never-written case is repaired here.
16
+ *
17
+ * The write itself belongs to the graph store (`writeGraph`): locked,
18
+ * atomic (tmp + rename), validated. Nothing here writes a graph file on
19
+ * its own.
20
+ */
21
+ import { type WorkflowGraph, type WorkflowId } from './workflow-graph-types.js';
22
+ /** What a graph is built from. */
23
+ export interface NewWorkflowGraphInput {
24
+ readonly workflowId: WorkflowId;
25
+ readonly rootSkill: string;
26
+ readonly parentWorkflowId?: WorkflowId;
27
+ }
28
+ /**
29
+ * The graph a workflow starts from: one terminal node, no edges.
30
+ *
31
+ * This is the builder the init path uses, so a graph created here is the
32
+ * same graph that path writes — the terminal node is `prepared` and the
33
+ * terminalize path is what moves it to `terminalized` / `lost`.
34
+ */
35
+ export declare function newWorkflowGraph(input: NewWorkflowGraphInput): WorkflowGraph;
36
+ /** What `ensureGraphExists` needs to place a graph on disk. */
37
+ export interface EnsureGraphInput {
38
+ readonly projectRoot: string;
39
+ readonly sessionId: string;
40
+ readonly workflowId: WorkflowId;
41
+ readonly skill: string;
42
+ readonly parentWorkflowId?: WorkflowId;
43
+ }
44
+ /** What `ensureGraphExists` did. */
45
+ export interface EnsureGraphResult {
46
+ readonly path: string;
47
+ readonly created: boolean;
48
+ }
49
+ /**
50
+ * Make sure the graph a lease names is on disk, creating it when it is not.
51
+ *
52
+ * The graph reference is derived from the workflow id, which is the only
53
+ * shape the graph store accepts (`graphs/<workflowId>.json`); the lease
54
+ * service validates the same shape before it calls this.
55
+ *
56
+ * Returns `created: false` when the graph is already there. An existing
57
+ * graph is never rewritten, so a corrupt one stays corrupt and keeps
58
+ * failing closed on the read and terminalize paths.
59
+ */
60
+ export declare function ensureGraphExists(input: EnsureGraphInput): EnsureGraphResult;
61
+ /** What `readGraphOrRepair` needs. */
62
+ export interface ReadGraphInput {
63
+ readonly projectRoot: string;
64
+ readonly sessionId: string;
65
+ readonly workflowId: WorkflowId;
66
+ readonly graphRef: string;
67
+ readonly skill: string;
68
+ }
69
+ /**
70
+ * Read the graph a workflow owns, repairing the never-written case.
71
+ *
72
+ * A graph that is on disk but corrupt is NOT repaired: `readGraph` raises
73
+ * PEAKS_GRAPH_CORRUPTED and that error travels on untouched, so the
74
+ * terminalize path keeps failing closed on a corrupt graph. Only the graph
75
+ * that was never written is replaced by the graph the write path creates.
76
+ */
77
+ export declare function readGraphOrRepair(input: ReadGraphInput): WorkflowGraph;
@@ -0,0 +1,97 @@
1
+ /**
2
+ * Workflow graph creation and existence.
3
+ *
4
+ * WHY THIS MODULE EXISTS. A presence lease names the graph it belongs to
5
+ * (`graphRef: graphs/<workflowId>.json`) and the terminalize path requires
6
+ * that graph to be on disk. The lease write path created the lease and
7
+ * nothing else, so a lease written by `skill presence:set` pointed at a
8
+ * graph that was never written and could not be terminalized. Both write
9
+ * paths build their graph through this module, so the file on disk is the
10
+ * same graph either way.
11
+ *
12
+ * WHAT IT DOES NOT DO. `ensureGraphExists` never rewrites a graph that is
13
+ * already on disk. A graph that is present but corrupt is left exactly as it
14
+ * is, so the read and terminalize paths keep failing closed on it; only the
15
+ * never-written case is repaired here.
16
+ *
17
+ * The write itself belongs to the graph store (`writeGraph`): locked,
18
+ * atomic (tmp + rename), validated. Nothing here writes a graph file on
19
+ * its own.
20
+ */
21
+ import { existsSync } from 'node:fs';
22
+ import { emptyGraph, graphPathFor, readGraph, validateGraph, writeGraph, PEAKS_GRAPH_NOT_FOUND } from './workflow-graph-store.js';
23
+ /**
24
+ * The graph a workflow starts from: one terminal node, no edges.
25
+ *
26
+ * This is the builder the init path uses, so a graph created here is the
27
+ * same graph that path writes — the terminal node is `prepared` and the
28
+ * terminalize path is what moves it to `terminalized` / `lost`.
29
+ */
30
+ export function newWorkflowGraph(input) {
31
+ const graph = emptyGraph({
32
+ workflowId: input.workflowId,
33
+ rootSkill: input.rootSkill,
34
+ ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {})
35
+ });
36
+ validateGraph(graph);
37
+ return graph;
38
+ }
39
+ /**
40
+ * Make sure the graph a lease names is on disk, creating it when it is not.
41
+ *
42
+ * The graph reference is derived from the workflow id, which is the only
43
+ * shape the graph store accepts (`graphs/<workflowId>.json`); the lease
44
+ * service validates the same shape before it calls this.
45
+ *
46
+ * Returns `created: false` when the graph is already there. An existing
47
+ * graph is never rewritten, so a corrupt one stays corrupt and keeps
48
+ * failing closed on the read and terminalize paths.
49
+ */
50
+ export function ensureGraphExists(input) {
51
+ const graphRef = `graphs/${input.workflowId}.json`;
52
+ const path = graphPathFor({
53
+ projectRoot: input.projectRoot,
54
+ sessionId: input.sessionId,
55
+ graphRef,
56
+ workflowId: input.workflowId
57
+ });
58
+ if (existsSync(path))
59
+ return { path, created: false };
60
+ const graph = newWorkflowGraph({
61
+ workflowId: input.workflowId,
62
+ rootSkill: input.skill,
63
+ ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {})
64
+ });
65
+ writeGraph({
66
+ projectRoot: input.projectRoot,
67
+ sessionId: input.sessionId,
68
+ graphRef,
69
+ workflowId: input.workflowId,
70
+ graph,
71
+ holder: `ensureGraph:${input.workflowId}`
72
+ });
73
+ return { path, created: true };
74
+ }
75
+ /**
76
+ * Read the graph a workflow owns, repairing the never-written case.
77
+ *
78
+ * A graph that is on disk but corrupt is NOT repaired: `readGraph` raises
79
+ * PEAKS_GRAPH_CORRUPTED and that error travels on untouched, so the
80
+ * terminalize path keeps failing closed on a corrupt graph. Only the graph
81
+ * that was never written is replaced by the graph the write path creates.
82
+ */
83
+ export function readGraphOrRepair(input) {
84
+ try {
85
+ return readGraph({
86
+ projectRoot: input.projectRoot,
87
+ sessionId: input.sessionId,
88
+ graphRef: input.graphRef,
89
+ workflowId: input.workflowId
90
+ });
91
+ }
92
+ catch (err) {
93
+ if (err.code !== PEAKS_GRAPH_NOT_FOUND)
94
+ throw err;
95
+ return newWorkflowGraph({ workflowId: input.workflowId, rootSkill: input.skill });
96
+ }
97
+ }
@@ -12,7 +12,8 @@
12
12
  import { existsSync, readFileSync } from 'node:fs';
13
13
  import { join } from 'node:path';
14
14
  import { TERMINAL_REASONS } from './workflow-graph-types.js';
15
- import { emptyGraph, readGraph, writeGraph, validateGraph, graphPathFor, PEAKS_GRAPH_NOT_FOUND, PEAKS_GRAPH_CORRUPTED, PEAKS_TERMINALIZE_ATOMICITY_FAILED, PEAKS_TERMINAL_REASON_INVALID } from './workflow-graph-store.js';
15
+ import { writeGraph, validateGraph, graphPathFor, PEAKS_GRAPH_NOT_FOUND, PEAKS_GRAPH_CORRUPTED, PEAKS_TERMINALIZE_ATOMICITY_FAILED, PEAKS_TERMINAL_REASON_INVALID } from './workflow-graph-store.js';
16
+ import { newWorkflowGraph, readGraphOrRepair } from './workflow-graph-ensure.js';
16
17
  import { setPresenceLease, readPresenceLease, markPresenceLost } from '../skills/presence-lease-service.js';
17
18
  function lifeError(code, message, extra = {}) {
18
19
  const err = new Error(message);
@@ -28,12 +29,11 @@ export async function initWorkflow(input) {
28
29
  if (graphRef !== `graphs/${workflowId}.json`) {
29
30
  throw lifeError(PEAKS_GRAPH_NOT_FOUND, `graphRef must normalize to graphs/${workflowId}.json; got ${graphRef}`);
30
31
  }
31
- const graph = emptyGraph({
32
+ const graph = newWorkflowGraph({
32
33
  workflowId,
33
34
  rootSkill: input.skill,
34
35
  ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {})
35
36
  });
36
- validateGraph(graph);
37
37
  // Phase 1: write graph first.
38
38
  writeGraph({
39
39
  projectRoot: input.projectRoot,
@@ -83,12 +83,27 @@ export async function terminalizeWorkflow(input) {
83
83
  const events = [];
84
84
  let successEventCount = 0;
85
85
  try {
86
- // Phase 1: read graph (fail closed if missing/corrupt).
87
- const graph = readGraph({
86
+ // Phase 0: the lease IS the workflow's identity. It is read before the
87
+ // graph so a terminalize aimed at a workflow this lease does not carry
88
+ // is refused before anything is written, and so the repair below can
89
+ // take the lease's own skill as the graph's rootSkill.
90
+ const currentLease = readPresenceLease({
88
91
  projectRoot: input.projectRoot,
89
92
  sessionId: input.sessionId,
93
+ callerId: input.callerId,
94
+ workflowId: input.workflowId,
95
+ graphRef: input.graphRef
96
+ });
97
+ // Phase 1: read the graph. A graph that was never written is repaired —
98
+ // the same graph the write path creates — while a graph that is on disk
99
+ // but CORRUPT keeps failing closed (PEAKS_GRAPH_CORRUPTED is rethrown
100
+ // untouched).
101
+ const graph = readGraphOrRepair({
102
+ projectRoot: input.projectRoot,
103
+ sessionId: input.sessionId,
104
+ workflowId: input.workflowId,
90
105
  graphRef: input.graphRef,
91
- workflowId: input.workflowId
106
+ skill: currentLease.skill
92
107
  });
93
108
  // Phase 2: check unconsumed envelopes (RD §4 terminalize contract).
94
109
  if (input.requireConsumed === true) {