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,41 +1,165 @@
1
1
  import { join } from 'node:path';
2
- import { pathExists, readText } from 'peaks-loop-shared/fs';
2
+ import { isDirectory, listDirectories, pathExists, readText } from 'peaks-loop-shared/fs';
3
3
  import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
4
- const ACCEPTANCE_SECTION_PATTERN = /^##\s+(?:Acceptance criteria|验收标准|Acceptance Criteria)\s*$/m;
5
- function extractAcceptanceItems(prdBody) {
6
- const lines = prdBody.split(/\r?\n/);
7
- const startMatch = ACCEPTANCE_SECTION_PATTERN.exec(prdBody);
8
- if (startMatch === null) {
4
+ import { handoffRelativePath } from '../prd/handoff-path-resolution.js';
5
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
6
+ import { runtimeRoot } from '../../shared/runtime-root.js';
7
+ const ACCEPTANCE_SECTION_PATTERN = /^##\s+(?:Acceptance criteria|验收标准|Acceptance Criteria)\s*$/;
8
+ const TABLE_SEPARATOR_PATTERN = /^\s*\|(?:\s*:?-{2,}:?\s*\|)+\s*$/;
9
+ const CRITERION_COLUMN_PATTERN = /criter|判据|验收/i;
10
+ const BULLET_PATTERN = /^\s*-\s+(.+?)\s*$/;
11
+ const TABLE_ROW_PATTERN = /^\s*\|(.+)\|\s*$/;
12
+ /** The criteria a document DECLARES: the `acceptanceCriteria:` list in its frontmatter. */
13
+ function declaredCriteria(content) {
14
+ const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
15
+ if (block === null)
9
16
  return [];
17
+ const lines = (block[1] ?? '').split(/\r?\n/);
18
+ const found = [];
19
+ let inList = false;
20
+ for (let i = 0; i < lines.length; i += 1) {
21
+ const raw = lines[i] ?? '';
22
+ if (!inList) {
23
+ inList = raw.trim() === 'acceptanceCriteria:';
24
+ continue;
25
+ }
26
+ const entry = BULLET_PATTERN.exec(raw);
27
+ if (entry === null) {
28
+ if (raw.trim().length > 0)
29
+ inList = false;
30
+ continue;
31
+ }
32
+ const text = (entry[1] ?? '').trim().replace(/^["'](.*)["']$/, '$1');
33
+ found.push({ text, line: i + 2, source: 'declared' });
10
34
  }
11
- // Find the line where the header starts.
12
- let headerLine = 0;
35
+ return found;
36
+ }
37
+ /** A criteria TABLE row: the criterion text it carries and the criterion column for the
38
+ * rows after it — the header row is the one that NAMES the column. */
39
+ function tableRowCriterion(cells, next, column) {
40
+ if (cells.every((cell) => /^:?-{2,}:?$/.test(cell)))
41
+ return null;
42
+ if (TABLE_SEPARATOR_PATTERN.test(next)) {
43
+ const named = cells.findIndex((cell) => CRITERION_COLUMN_PATTERN.test(cell));
44
+ return { text: '', column: named >= 0 ? named : Math.min(1, cells.length - 1) };
45
+ }
46
+ return { text: cells[column] ?? '', column };
47
+ }
48
+ /** The criteria a document SHOWS: the bullets of its acceptance section and the criterion
49
+ * column of a criteria table inside it. */
50
+ function sectionCriteria(content) {
51
+ const lines = content.split(/\r?\n/);
52
+ const found = [];
53
+ let inSection = false;
54
+ let column = 1;
13
55
  for (let i = 0; i < lines.length; i += 1) {
14
- if (ACCEPTANCE_SECTION_PATTERN.test((lines[i] ?? '') + '\n')) {
15
- headerLine = i;
56
+ const raw = lines[i] ?? '';
57
+ if (!inSection) {
58
+ inSection = ACCEPTANCE_SECTION_PATTERN.test(raw);
59
+ continue;
60
+ }
61
+ if (/^##\s/.test(raw))
16
62
  break;
63
+ const bullet = BULLET_PATTERN.exec(raw);
64
+ if (bullet !== null) {
65
+ found.push({ text: (bullet[1] ?? '').trim(), line: i + 1, source: 'section' });
66
+ continue;
67
+ }
68
+ const row = TABLE_ROW_PATTERN.exec(raw);
69
+ if (row === null)
70
+ continue;
71
+ const cells = (row[1] ?? '').split('|').map((cell) => cell.trim());
72
+ const table = tableRowCriterion(cells, lines[i + 1] ?? '', column);
73
+ if (table === null)
74
+ continue;
75
+ column = table.column;
76
+ if (table.text.length > 0) {
77
+ found.push({ text: table.text, line: i + 1, source: 'section' });
17
78
  }
18
79
  }
80
+ return found;
81
+ }
82
+ /** The criteria of a PRD: the DECLARED list UNION the criteria the section SHOWS,
83
+ * de-duplicated by text. A criterion carrying both sources says so. */
84
+ function extractAcceptanceItems(content) {
19
85
  const items = [];
86
+ const byKey = new Map();
20
87
  let counter = 0;
21
- for (let i = headerLine + 1; i < lines.length; i += 1) {
22
- const raw = lines[i] ?? '';
23
- if (/^##\s/.test(raw))
24
- break; // next section
25
- const bulletMatch = /^\s*-\s+(.+?)\s*$/.exec(raw);
26
- if (bulletMatch === null)
27
- continue;
28
- const text = bulletMatch[1] ?? '';
29
- if (text.length === 0)
88
+ for (const raw of [...declaredCriteria(content), ...sectionCriteria(content)]) {
89
+ const text = raw.text.trim();
90
+ if (text.length === 0 || /^\.{2,}$/.test(text) || /^<[^>]+>$/.test(text))
30
91
  continue;
31
- // Skip placeholder-only bullets ("...", "<...>", etc.)
32
- if (/^\.{2,}$/.test(text) || /^<[^>]+>$/.test(text))
92
+ const key = text.toLowerCase().replace(/\s+/g, ' ');
93
+ const existing = byKey.get(key);
94
+ if (existing === undefined) {
95
+ counter += 1;
96
+ const item = { id: `A${counter}`, text, line: raw.line, source: raw.source };
97
+ byKey.set(key, item);
98
+ items.push(item);
33
99
  continue;
34
- counter += 1;
35
- items.push({ id: `A${counter}`, text, line: i + 1 });
100
+ }
101
+ if (existing.source !== raw.source)
102
+ existing.source = 'both';
36
103
  }
37
104
  return items;
38
105
  }
106
+ /** The `sessionId:` a capsule declares in its own frontmatter. The PRD-style `- session:`
107
+ * line in the body is a different field. A declared value that is not a single safe path
108
+ * segment is REFUSED: it decides where the test-cases file is read from. */
109
+ function handoffFrontmatterSessionId(content) {
110
+ const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
111
+ if (block === null)
112
+ return undefined;
113
+ const declared = /^sessionId:\s*(.+?)\s*$/m.exec(block[1] ?? '');
114
+ if (declared === null)
115
+ return undefined;
116
+ const value = (declared[1] ?? '').trim().replace(/^["'](.*)["']$/, '$1');
117
+ if (value.length === 0 || isUnsafePathInput(value))
118
+ return undefined;
119
+ return value;
120
+ }
121
+ async function candidateSessionIds(options) {
122
+ if (options.sessionId !== undefined)
123
+ return [options.sessionId];
124
+ const runtimeDir = runtimeRoot(options.projectRoot).dir();
125
+ if (!(await isDirectory(runtimeDir)))
126
+ return [];
127
+ return await listDirectories(runtimeDir);
128
+ }
129
+ /** The MAIN source is the role carrier at `prd/requests/<rid>.md`; the FALLBACK is the
130
+ * handoff capsule at `prd/handoff-<rid>.md` — the artifact the pipeline produces for a
131
+ * session that ran no peaks-prd role. The capsule's path is built by the SAME guarded
132
+ * constructor the capsule writer uses, so neither the rid nor the session id can escape
133
+ * the runtime root. */
134
+ async function resolvePrdSource(options) {
135
+ const showOptions = {
136
+ projectRoot: options.projectRoot,
137
+ role: 'prd',
138
+ requestId: options.requestId,
139
+ ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId })
140
+ };
141
+ const prdArtifact = await showRequestArtifact(showOptions);
142
+ if (prdArtifact !== null) {
143
+ const { path, content, sessionId } = prdArtifact;
144
+ return { path, sessionId, acceptanceItems: extractAcceptanceItems(content) };
145
+ }
146
+ for (const sessionDir of await candidateSessionIds(options)) {
147
+ const relative = handoffRelativePath(sessionDir, options.requestId);
148
+ const absolute = join(options.projectRoot, relative);
149
+ if (!(await pathExists(absolute)))
150
+ continue;
151
+ const content = await readText(absolute);
152
+ // The capsule's own `sessionId:` first, then the caller's `--session-id`,
153
+ // then the session dir the capsule was found in — which IS the caller's
154
+ // when one was given.
155
+ const sessionId = handoffFrontmatterSessionId(content) ?? options.sessionId ?? sessionDir;
156
+ return { path: absolute, sessionId, acceptanceItems: extractAcceptanceItems(content) };
157
+ }
158
+ return null;
159
+ }
160
+ function prdNotFoundMessage(requestId) {
161
+ return `PRD artifact for requestId=${requestId} not found: neither prd/requests/${requestId}.md nor prd/handoff-${requestId}.md was found`;
162
+ }
39
163
  const TEST_CASE_HEADER_PATTERN = /^##\s+Test Case:\s*(.+?)\s*$/;
40
164
  const ACCEPTANCE_FIELD_PATTERN = /^\s*-\s+\*\*Acceptance:\*\*\s+(.+?)\s*$/i;
41
165
  function extractTestCases(qaBody) {
@@ -56,10 +180,7 @@ function extractTestCases(qaBody) {
56
180
  continue;
57
181
  const acceptanceMatch = ACCEPTANCE_FIELD_PATTERN.exec(raw);
58
182
  if (acceptanceMatch !== null) {
59
- const refs = (acceptanceMatch[1] ?? '')
60
- .split(/[,\s]+/)
61
- .map((part) => part.trim())
62
- .filter((part) => part.length > 0);
183
+ const refs = (acceptanceMatch[1] ?? '').split(/[,\s]+/).filter((part) => part.length > 0);
63
184
  current.ids.push(...refs);
64
185
  }
65
186
  }
@@ -69,9 +190,6 @@ function extractTestCases(qaBody) {
69
190
  return cases;
70
191
  }
71
192
  function buildCoverage(items, cases) {
72
- const itemMap = new Map();
73
- for (const item of items)
74
- itemMap.set(item.id, item);
75
193
  const coverageMap = new Map();
76
194
  for (const item of items)
77
195
  coverageMap.set(item.id, []);
@@ -79,7 +197,7 @@ function buildCoverage(items, cases) {
79
197
  for (const testCase of cases) {
80
198
  for (const ref of testCase.acceptanceIds) {
81
199
  const normalized = ref.toUpperCase();
82
- if (!itemMap.has(normalized)) {
200
+ if (!coverageMap.has(normalized)) {
83
201
  invalidReferences.push({ testCaseTitle: testCase.title, reference: ref });
84
202
  continue;
85
203
  }
@@ -95,38 +213,25 @@ function buildCoverage(items, cases) {
95
213
  return { coverage, uncovered, invalidReferences };
96
214
  }
97
215
  export async function getAcceptanceCoverage(options) {
98
- const showOptions = {
99
- projectRoot: options.projectRoot,
100
- role: 'prd',
101
- requestId: options.requestId
102
- };
103
- if (options.sessionId !== undefined) {
104
- showOptions.sessionId = options.sessionId;
105
- }
106
- const prdArtifact = await showRequestArtifact(showOptions);
107
- if (prdArtifact === null) {
108
- return { kind: 'prd-not-found' };
216
+ const source = await resolvePrdSource(options);
217
+ if (source === null) {
218
+ return { kind: 'prd-not-found', message: prdNotFoundMessage(options.requestId) };
109
219
  }
110
- // under the same change-id dir as the PRD itself (the on-disk scope),
111
- // not under the body's `- session:` line. Slice
112
- // `.peaks/_runtime/change/<id>/` indirection — test-cases now live
113
- // under the canonical session dir `.peaks/_runtime/<sid>/qa/test-cases/`.
114
- // `prdArtifact.sessionId` is the bare session id (the dir the PRD was
115
- // found in), so we route through `_runtime/` here.
116
- const sessionId = prdArtifact.sessionId;
117
- const testCasesPath = join(options.projectRoot, '.peaks', '_runtime', sessionId, 'qa', 'test-cases', `${options.requestId}.md`);
220
+ // test-cases live under the canonical session dir `.peaks/_runtime/<sid>/qa/test-cases/`;
221
+ // `source.sessionId` is the bare session id of the dir the PRD — or the capsule — was in.
222
+ const testCasesPath = join(options.projectRoot, `.peaks/_runtime/${source.sessionId}/qa/test-cases/${options.requestId}.md`);
118
223
  if (!(await pathExists(testCasesPath))) {
119
224
  return { kind: 'test-cases-not-found', expectedPath: testCasesPath };
120
225
  }
121
226
  const qaBody = await readText(testCasesPath);
122
- const acceptanceItems = extractAcceptanceItems(prdArtifact.content);
227
+ const acceptanceItems = source.acceptanceItems;
123
228
  const testCases = extractTestCases(qaBody);
124
229
  const { coverage, uncovered, invalidReferences } = buildCoverage(acceptanceItems, testCases);
125
230
  const unlinkedTestCases = testCases.filter((testCase) => testCase.acceptanceIds.length === 0);
126
231
  const ok = uncovered.length === 0 && invalidReferences.length === 0 && acceptanceItems.length > 0;
127
232
  return {
128
233
  ok,
129
- prdPath: prdArtifact.path,
234
+ prdPath: source.path,
130
235
  testCasesPath,
131
236
  acceptanceItems,
132
237
  testCases,
@@ -0,0 +1,15 @@
1
+ /** True when the artifact carries the `## Changed paths` heading. */
2
+ export declare function hasChangedPathsSection(body: string): boolean;
3
+ /** Every `changedPath:` line of the body, in the order they were written. */
4
+ export declare function parseChangedPathLines(body: string): readonly string[];
5
+ /** Every rid that HAS an RD artifact in the session — declared or not. The
6
+ * caller compares this list against the claim table to learn whether the table
7
+ * is COMPLETE, which is what decides whether the anti-lie fallback may run.
8
+ */
9
+ export declare function listSessionRdArtifactIds(projectRoot: string, sessionId: string): readonly string[];
10
+ /**
11
+ * rid -> the paths it declared. ONLY artifacts carrying the `## Changed paths`
12
+ * heading are in the table; a rid without it is NOT, and the caller reads that
13
+ * absence as "this rid declared nothing" and falls back to the whole tree.
14
+ */
15
+ export declare function readRidChangeClaims(projectRoot: string, sessionId: string): ReadonlyMap<string, readonly string[]>;
@@ -0,0 +1,116 @@
1
+ /**
2
+ * The per-rid "changed paths" claim table.
3
+ *
4
+ * A request artifact declares the paths its own slice touched, in a
5
+ * machine-readable section:
6
+ *
7
+ * ```markdown
8
+ * ## Changed paths
9
+ * changedPath: src/services/skills/presence-role.ts
10
+ * ```
11
+ *
12
+ * The format is line-based `key: value` because `prd/handoff-*.md` already uses
13
+ * that shape for its own markers (`schemaVersion: 2`, `sha256:`); a
14
+ * comma-separated list would break on a comma inside a file name.
15
+ *
16
+ * TWO STATES, NOT ONE. An artifact that carries the `## Changed paths` heading
17
+ * HAS declared — an empty list is a declaration ("this slice touched nothing").
18
+ * An artifact WITHOUT it has not, and the caller falls back to the whole
19
+ * working tree, which is STRICTER, not looser. The heading is the switch.
20
+ * The rid is read with the repository's own naming rule
21
+ * (`requestIdFromFileName`), so the writer and this reader cannot drift apart.
22
+ */
23
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
24
+ import { join } from 'node:path';
25
+ import { requestIdFromFileName } from '../../shared/incrementing-number.js';
26
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
27
+ import { guardRuntimeSegment, runtimeRoot } from '../../shared/runtime-root.js';
28
+ /** The heading that marks an artifact as HAVING a declaration. */
29
+ const CHANGED_PATHS_HEADING_RE = /^#{1,6}\s+changed\s+paths\s*$/i;
30
+ /** One declared path per line: `changedPath: <path>`, at the start of the line. */
31
+ const CHANGED_PATH_LINE_RE = /^changedPath:\s*(\S.*?)\s*$/;
32
+ /** True when the artifact carries the `## Changed paths` heading. */
33
+ export function hasChangedPathsSection(body) {
34
+ return body.split(/\r?\n/).some((line) => CHANGED_PATHS_HEADING_RE.test(line.trim()));
35
+ }
36
+ /** Every `changedPath:` line of the body, in the order they were written. */
37
+ export function parseChangedPathLines(body) {
38
+ const paths = [];
39
+ for (const line of body.split(/\r?\n/)) {
40
+ const declared = CHANGED_PATH_LINE_RE.exec(line)?.[1];
41
+ if (declared !== undefined)
42
+ paths.push(declared);
43
+ }
44
+ return paths;
45
+ }
46
+ /** The session's RD request-artifact directory, or null when the id is unusable. */
47
+ function rdRequestsDir(projectRoot, sessionId) {
48
+ const session = guardedSegmentOrNull(sessionId, 'session id');
49
+ if (session === null)
50
+ return null;
51
+ return runtimeRoot(projectRoot).join(session, guardRuntimeSegment('rd', 'role'), guardRuntimeSegment('requests', 'leaf'));
52
+ }
53
+ /**
54
+ * The id as a guarded segment, or `null` when it is not one: the guard THROWS
55
+ * on an unusable id, so the predicate it applies (`isUnsafePathInput`) is asked
56
+ * first and "unusable" is a VALUE here instead of an exception.
57
+ */
58
+ function guardedSegmentOrNull(value, label) {
59
+ return isUnsafePathInput(value) ? null : guardRuntimeSegment(value, label);
60
+ }
61
+ /** The artifact file names in that directory; an unreadable directory throws. */
62
+ function rdArtifactFileNames(dir) {
63
+ if (!existsSync(dir))
64
+ return [];
65
+ try {
66
+ return readdirSync(dir).filter((name) => requestIdFromFileName(name) !== null);
67
+ }
68
+ catch (error) {
69
+ throw new Error(`cannot read the RD artifact directory ${dir}: ${String(error)}`);
70
+ }
71
+ }
72
+ /** Every rid that HAS an RD artifact in the session — declared or not. The
73
+ * caller compares this list against the claim table to learn whether the table
74
+ * is COMPLETE, which is what decides whether the anti-lie fallback may run.
75
+ */
76
+ export function listSessionRdArtifactIds(projectRoot, sessionId) {
77
+ const dir = rdRequestsDir(projectRoot, sessionId);
78
+ if (dir === null)
79
+ return [];
80
+ const ids = [];
81
+ for (const name of rdArtifactFileNames(dir)) {
82
+ const rid = requestIdFromFileName(name);
83
+ if (rid !== null && rid.length > 0)
84
+ ids.push(rid);
85
+ }
86
+ return ids;
87
+ }
88
+ /**
89
+ * rid -> the paths it declared. ONLY artifacts carrying the `## Changed paths`
90
+ * heading are in the table; a rid without it is NOT, and the caller reads that
91
+ * absence as "this rid declared nothing" and falls back to the whole tree.
92
+ */
93
+ export function readRidChangeClaims(projectRoot, sessionId) {
94
+ const dir = rdRequestsDir(projectRoot, sessionId);
95
+ const claims = new Map();
96
+ if (dir === null)
97
+ return claims;
98
+ for (const name of rdArtifactFileNames(dir)) {
99
+ const rid = requestIdFromFileName(name);
100
+ if (rid === null || rid.length === 0 || claims.has(rid))
101
+ continue;
102
+ let body;
103
+ try {
104
+ body = readFileSync(join(dir, name), 'utf8');
105
+ }
106
+ catch {
107
+ // An unreadable artifact cannot prove a declaration: leave the rid out of
108
+ // the table, which makes the table incomplete and the fallback stand down.
109
+ continue;
110
+ }
111
+ if (!hasChangedPathsSection(body))
112
+ continue;
113
+ claims.set(rid, parseChangedPathLines(body));
114
+ }
115
+ return claims;
116
+ }
@@ -1,3 +1,16 @@
1
+ /**
2
+ * The documented contract: one path segment. `isUnsafePathInput` is a
3
+ * traversal guard only and ADMITS `a/b`, so the separator axes are
4
+ * checked here as well. The session dir is ONE directory name under
5
+ * `_runtime/`.
6
+ *
7
+ * EXPORTED because the session id is the last caller-supplied segment of
8
+ * more than one session-scoped path: the runtime dir here, and the dispatch
9
+ * ledger's dir under `.peaks/_sub_agents/` (read by
10
+ * `src/services/dispatch/dispatch-ledger-reader.ts`). One predicate, two
11
+ * users, so the two cannot drift apart.
12
+ */
13
+ export declare function isSinglePathSegment(sessionId: string): boolean;
1
14
  export declare function getSessionDir(projectRoot: string, sessionId: string): string;
2
15
  /**
3
16
  * The TOTAL entry to the same axis. Same predicate, same path; the only
@@ -49,8 +49,14 @@ import { isUnsafePathInput } from '../../shared/path-safety.js';
49
49
  * traversal guard only and ADMITS `a/b`, so the separator axes are
50
50
  * checked here as well. The session dir is ONE directory name under
51
51
  * `_runtime/`.
52
+ *
53
+ * EXPORTED because the session id is the last caller-supplied segment of
54
+ * more than one session-scoped path: the runtime dir here, and the dispatch
55
+ * ledger's dir under `.peaks/_sub_agents/` (read by
56
+ * `src/services/dispatch/dispatch-ledger-reader.ts`). One predicate, two
57
+ * users, so the two cannot drift apart.
52
58
  */
53
- function isSinglePathSegment(sessionId) {
59
+ export function isSinglePathSegment(sessionId) {
54
60
  return !isUnsafePathInput(sessionId) && !sessionId.includes('/') && !sessionId.includes('\\');
55
61
  }
56
62
  export function getSessionDir(projectRoot, sessionId) {
@@ -17,28 +17,24 @@ export type HookInstallOptions = {
17
17
  */
18
18
  readonly ide?: IdeId;
19
19
  /**
20
- * Slice #013 (bugfix — peaks hooks install --no-progress): when `true`,
21
- * skip emitting the progress-start PreToolUse hook entry while still
22
- * installing the gate-enforce entry. The progress-start hook auto-spawns
23
- * a new terminal running `peaks progress watch`; with dispatch +
24
- * heartbeat (slice #009 + #010) that auto-spawn is dead weight. Default
25
- * `false` preserves the pre-slice install shape (both entries). The
26
- * sentinel-based install is idempotent: re-running with `skipProgress:
27
- * true` over a settings.json that previously had the progress entry
28
- * installed will remove that entry. `uninstall` honors the same flag
29
- * so it can find and remove both entries when both are present and
30
- * only the gate-enforce entry when only the gate-enforce is present.
20
+ * Slice #013 (bugfix — peaks hooks install --no-progress): the published
21
+ * flag that skipped the progress-start PreToolUse hook entry. That hook
22
+ * auto-spawns a new terminal running a progress watcher; with dispatch +
23
+ * heartbeat (slice #009 + #010) the auto-spawn is dead weight.
31
24
  *
32
- * Slice #014 (refactor — full removal of legacy progress-start surface):
33
- * the field is preserved for API stability, but the underlying
34
- * install only ever emits the gate-enforce entry. The progress-start
35
- * entry is no longer installed regardless of this flag's value. The
36
- * legacy `peaks progress start|watch|close` CLI surface is gone
37
- * (replaced by `peaks sub-agent dispatch|heartbeat|share`); the hook
38
- * entry would have been pointing at a `peaks progress start` that no
39
- * longer exists. The sentinel `peaks progress start` constant is still
40
- * exported (some tests + back-compat reads rely on it) but no new
41
- * hook entries use it.
25
+ * The field is retained for API stability and NO LONGER CHANGES WHAT IS
26
+ * INSTALLED: it defaults to unset and the entry resolver ignores it, so an
27
+ * install always writes the adapter's whole peaks-managed entry set — for
28
+ * Claude Code: `peaks gate enforce` (Bash and MCP tool calls),
29
+ * `peaks code-gate` (Edit|Write|MultiEdit), `peaks outer-cache write`,
30
+ * `peaks session primer`, `peaks session reinject`, `peaks compact settle`
31
+ * — plus the Layer-3 `permissions.deny` entries (worktree governance);
32
+ * the other adapters install their own single hook entry. No code path
33
+ * writes the legacy progress-start entry any more.
34
+ *
35
+ * `uninstall` ignores this field as well: it strips entries by a sentinel
36
+ * scan over the peaks-managed sentinel set, which covers every entry an
37
+ * install writes plus the legacy progress-start one.
42
38
  */
43
39
  readonly skipProgress?: boolean;
44
40
  };
@@ -0,0 +1,51 @@
1
+ /**
2
+ * The presence write side's caller-id gate.
3
+ *
4
+ * Outside Claude Code the IDE adapter cannot resolve a callerId, so
5
+ * `presence:set` was fail-closed with no way out and the lease could never be
6
+ * built. This module adds the vendor-neutral escape hatch the rest of the
7
+ * CLI already has (`peaks request init`): an explicit `--caller-id` flag and
8
+ * the `PEAKS_CALLER_ID` environment variable, both short-circuiting BEFORE
9
+ * the adapter.
10
+ *
11
+ * The priority chain lives in `resolve-caller-id.ts` and is NOT restated
12
+ * here: flag > `PEAKS_CALLER_ID` env > active IDE adapter. This module only
13
+ * turns the resolver's typed failures into a discriminated result the CLI
14
+ * can render without knowing the resolver's error taxonomy.
15
+ *
16
+ * Pure: no filesystem access, no state. The caller decides what to do with
17
+ * the resolved id.
18
+ */
19
+ import { type CallerProjectionSource } from '../session/resolve-caller-id.js';
20
+ export type PresenceCallerIdResult = {
21
+ readonly ok: true;
22
+ readonly callerId: string;
23
+ readonly source: CallerProjectionSource;
24
+ } | {
25
+ readonly ok: false;
26
+ /**
27
+ * `CALLER_ID_INVALID` — a value WAS supplied but it does not match
28
+ * the D1 regex (`^[a-zA-Z0-9._-]{1,200}$`).
29
+ * `PEAKS_CALLER_NOT_RESOLVED` — nothing could be resolved at all.
30
+ */
31
+ readonly code: 'CALLER_ID_INVALID' | 'PEAKS_CALLER_NOT_RESOLVED';
32
+ readonly message: string;
33
+ };
34
+ export interface ResolvePresenceCallerIdOptions {
35
+ /** The project root the caller id is resolved against. */
36
+ readonly projectRoot: string;
37
+ /**
38
+ * The `--caller-id <id>` flag value. Priority level 1 — it wins over the
39
+ * env var and short-circuits the adapter, so a host that is not Claude
40
+ * Code can still build a lease.
41
+ */
42
+ readonly flagValue?: string | undefined;
43
+ }
44
+ /**
45
+ * Resolve the caller id for a presence write.
46
+ *
47
+ * Never throws: a shape mismatch (`CALLER_ID_INVALID`) and an unresolvable
48
+ * caller (`PEAKS_CALLER_NOT_RESOLVED`) both come back as a refusal so the
49
+ * CLI can print one readable envelope for each.
50
+ */
51
+ export declare function resolvePresenceCallerId(opts: ResolvePresenceCallerIdOptions): PresenceCallerIdResult;
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The presence write side's caller-id gate.
3
+ *
4
+ * Outside Claude Code the IDE adapter cannot resolve a callerId, so
5
+ * `presence:set` was fail-closed with no way out and the lease could never be
6
+ * built. This module adds the vendor-neutral escape hatch the rest of the
7
+ * CLI already has (`peaks request init`): an explicit `--caller-id` flag and
8
+ * the `PEAKS_CALLER_ID` environment variable, both short-circuiting BEFORE
9
+ * the adapter.
10
+ *
11
+ * The priority chain lives in `resolve-caller-id.ts` and is NOT restated
12
+ * here: flag > `PEAKS_CALLER_ID` env > active IDE adapter. This module only
13
+ * turns the resolver's typed failures into a discriminated result the CLI
14
+ * can render without knowing the resolver's error taxonomy.
15
+ *
16
+ * Pure: no filesystem access, no state. The caller decides what to do with
17
+ * the resolved id.
18
+ */
19
+ import { CallerIdError, resolveCallerProjection } from '../session/resolve-caller-id.js';
20
+ /**
21
+ * Resolve the caller id for a presence write.
22
+ *
23
+ * Never throws: a shape mismatch (`CALLER_ID_INVALID`) and an unresolvable
24
+ * caller (`PEAKS_CALLER_NOT_RESOLVED`) both come back as a refusal so the
25
+ * CLI can print one readable envelope for each.
26
+ */
27
+ export function resolvePresenceCallerId(opts) {
28
+ try {
29
+ const projection = resolveCallerProjection({
30
+ projectRoot: opts.projectRoot,
31
+ ...(opts.flagValue !== undefined ? { flagValue: opts.flagValue } : {})
32
+ });
33
+ return { ok: true, callerId: projection.callerId, source: projection.source };
34
+ }
35
+ catch (err) {
36
+ const invalid = err instanceof CallerIdError && err.code === 'EX_DATAERR';
37
+ return {
38
+ ok: false,
39
+ code: invalid ? 'CALLER_ID_INVALID' : 'PEAKS_CALLER_NOT_RESOLVED',
40
+ message: err instanceof Error ? err.message : String(err)
41
+ };
42
+ }
43
+ }
@@ -0,0 +1,65 @@
1
+ /**
2
+ * The `gate` field of a presence lease — write-side contract.
3
+ *
4
+ * WHAT THE GATE IS. The status header the LLM is told to display —
5
+ * `Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <action>` —
6
+ * has three cells. The middle one was, until this slice, MODEL-INVENTED
7
+ * prose: `SetPresenceLeaseInput.gate` existed, but the lease constructor
8
+ * never expanded it, so the lease carried no gate and the read side had
9
+ * nothing to project. The gate is now persisted and projected, so the
10
+ * middle cell is a machine fact.
11
+ *
12
+ * ENUM OR FREE STRING? Free string with a shape check. The gate values
13
+ * this repository actually uses are enumerated in `KNOWN_PRESENCE_GATES`
14
+ * below, but they are NOT an allow-list:
15
+ *
16
+ * - `repair-cycle-<N>` is a TEMPLATE — the runtime value carries a
17
+ * counter (`repair-cycle-1`), so it cannot be closed over a static
18
+ * enumeration.
19
+ * - `peaks sop check --gate <gate-id>` addresses a gate id defined at
20
+ * runtime by an SOP, so SOP-scoped gates are not knowable at build
21
+ * time either.
22
+ * - third-party skills are free to pass their own gate token.
23
+ *
24
+ * A closed enumeration would reject those, and the CLI already accepts any
25
+ * `--gate <value>` string today; rejecting unknown values would break
26
+ * working callers for no gain. What IS rejected is a malformed value: a
27
+ * control character (it lands verbatim in the status header) or a value
28
+ * longer than `MAX_PRESENCE_GATE_LENGTH`. An empty / whitespace-only value
29
+ * is DROPPED, not rejected — that is the pre-existing behaviour of the
30
+ * `...(gate ? { gate } : {})` spread and it is kept.
31
+ */
32
+ /** Error code for a gate value that cannot be persisted. */
33
+ export declare const PEAKS_GATE_INVALID = "PEAKS_GATE_INVALID";
34
+ /** Longest gate value that may be persisted. */
35
+ export declare const MAX_PRESENCE_GATE_LENGTH = 200;
36
+ /** A presence error carrying a typed `code`. */
37
+ export type PresenceGateError = Error & {
38
+ readonly code: string;
39
+ };
40
+ /**
41
+ * The gate vocabulary this repository uses today (enumerated 2026-10-24
42
+ * from `skills/**` and `src/**`).
43
+ *
44
+ * NOT an allow-list — see the module header. The list exists so the
45
+ * regression test can assert that every gate value the repository uses is
46
+ * accepted by `normalizePresenceGate`, and so a reader can see the
47
+ * vocabulary without grepping.
48
+ */
49
+ export declare const KNOWN_PRESENCE_GATES: readonly string[];
50
+ /**
51
+ * Normalize a gate value for persistence.
52
+ *
53
+ * Returns `undefined` when there is no gate to persist (absent, or empty
54
+ * after trimming). Throws a `PEAKS_GATE_INVALID` error for a value that
55
+ * must not be written (control characters, over-length).
56
+ */
57
+ export declare function normalizePresenceGate(value: string | undefined | null): string | undefined;
58
+ /**
59
+ * Project a gate value that was READ back from disk.
60
+ *
61
+ * Tolerant by design: a hand-edited lease file, or a lease written by an
62
+ * older release, must never make the read throw. Anything that is not a
63
+ * non-empty string is reported as "no gate".
64
+ */
65
+ export declare function readPresenceGate(value: unknown): string | undefined;