peaks-loop 4.1.4 → 4.1.6

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 (294) hide show
  1. package/.claude-plugin/marketplace.json +7 -2
  2. package/CHANGELOG.md +148 -0
  3. package/README-en.md +47 -183
  4. package/README.md +24 -188
  5. package/dist/cli/cli-helpers.d.ts +20 -0
  6. package/dist/cli/cli-helpers.js +34 -0
  7. package/dist/cli/commands/_register.js +2 -0
  8. package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
  9. package/dist/cli/commands/best-practice-scan-command.js +35 -20
  10. package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
  11. package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
  12. package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
  13. package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
  14. package/dist/cli/commands/code-commands.d.ts +6 -4
  15. package/dist/cli/commands/code-commands.js +6 -4
  16. package/dist/cli/commands/code-gate-command.d.ts +5 -5
  17. package/dist/cli/commands/code-gate-command.js +49 -9
  18. package/dist/cli/commands/code-mode-gate-plan-command.d.ts +1 -1
  19. package/dist/cli/commands/code-mode-gate-plan-command.js +2 -2
  20. package/dist/cli/commands/core/memory-extract-command.js +10 -5
  21. package/dist/cli/commands/dispatch-cli-invocation-check.d.ts +108 -0
  22. package/dist/cli/commands/dispatch-cli-invocation-check.js +87 -0
  23. package/dist/cli/commands/dispatch-cli-invocation-scan.d.ts +66 -0
  24. package/dist/cli/commands/dispatch-cli-invocation-scan.js +162 -0
  25. package/dist/cli/commands/dispatch-command-spec.js +1 -1
  26. package/dist/cli/commands/dispatch-commands.js +12 -5
  27. package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
  28. package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
  29. package/dist/cli/commands/dispatch-preflight.js +46 -0
  30. package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
  31. package/dist/cli/commands/dispatch-prompt-composition.d.ts +7 -1
  32. package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
  33. package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
  34. package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
  35. package/dist/cli/commands/doc-commands.js +1 -1
  36. package/dist/cli/commands/feedback-commands-helpers.js +1 -1
  37. package/dist/cli/commands/final-review-prepare-command.js +22 -1
  38. package/dist/cli/commands/gate-commands-enforce.js +3 -3
  39. package/dist/cli/commands/hook-handle.js +41 -20
  40. package/dist/cli/commands/lint-commands.js +3 -1
  41. package/dist/cli/commands/loop-eval-capture-index.js +2 -4
  42. package/dist/cli/commands/openspec-command-shared.js +2 -2
  43. package/dist/cli/commands/perf-audit-commands.js +15 -5
  44. package/dist/cli/commands/project-commands.js +9 -6
  45. package/dist/cli/commands/race-commands.d.ts +15 -0
  46. package/dist/cli/commands/race-commands.js +65 -0
  47. package/dist/cli/commands/race-pilot-gate-record-command.d.ts +3 -0
  48. package/dist/cli/commands/race-pilot-gate-record-command.js +81 -0
  49. package/dist/cli/commands/request-command-options.d.ts +8 -0
  50. package/dist/cli/commands/request-commands.js +2 -0
  51. package/dist/cli/commands/request-init-command.js +67 -12
  52. package/dist/cli/commands/{vm-status-command.d.ts → request-retag-command.d.ts} +1 -1
  53. package/dist/cli/commands/request-retag-command.js +50 -0
  54. package/dist/cli/commands/request-show-command.d.ts +8 -0
  55. package/dist/cli/commands/request-show-command.js +14 -1
  56. package/dist/cli/commands/request-transition-command.js +12 -4
  57. package/dist/cli/commands/request-transition-failures.d.ts +14 -0
  58. package/dist/cli/commands/request-transition-failures.js +76 -7
  59. package/dist/cli/commands/request-transition-preflight.js +1 -1
  60. package/dist/cli/commands/scan-scope-commands.js +2 -2
  61. package/dist/cli/commands/security-audit-commands.js +26 -6
  62. package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
  63. package/dist/cli/commands/verdict-aggregate-command.js +2 -1
  64. package/dist/cli/commands/workflow-gate-commands.js +4 -4
  65. package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
  66. package/dist/cli/program.js +0 -2
  67. package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
  68. package/dist/services/artifacts/artifact-contract-block.js +231 -0
  69. package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
  70. package/dist/services/artifacts/artifact-prerequisites.js +65 -135
  71. package/dist/services/artifacts/artifact-templates.d.ts +1 -1
  72. package/dist/services/artifacts/artifact-templates.js +17 -10
  73. package/dist/services/artifacts/prerequisite-checks.d.ts +87 -0
  74. package/dist/services/artifacts/prerequisite-checks.js +198 -0
  75. package/dist/services/artifacts/prerequisite-transition-event.d.ts +20 -0
  76. package/dist/services/artifacts/prerequisite-transition-event.js +27 -0
  77. package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
  78. package/dist/services/artifacts/rd-transition-gates.js +71 -0
  79. package/dist/services/artifacts/request-artifact-metadata.d.ts +31 -0
  80. package/dist/services/artifacts/request-artifact-metadata.js +44 -0
  81. package/dist/services/artifacts/request-artifact-service.d.ts +5 -0
  82. package/dist/services/artifacts/request-artifact-service.js +43 -69
  83. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +21 -1
  84. package/dist/services/artifacts/request-artifact-state-helpers.js +34 -8
  85. package/dist/services/artifacts/request-retag-service.d.ts +68 -0
  86. package/dist/services/artifacts/request-retag-service.js +125 -0
  87. package/dist/services/artifacts/request-state-order.d.ts +38 -0
  88. package/dist/services/artifacts/request-state-order.js +99 -0
  89. package/dist/services/artifacts/request-type-demand.d.ts +44 -0
  90. package/dist/services/artifacts/request-type-demand.js +71 -0
  91. package/dist/services/audit/audit-goal-service.d.ts +7 -0
  92. package/dist/services/audit/enforcers/active-skill-resolver.d.ts +18 -0
  93. package/dist/services/audit/enforcers/active-skill-resolver.js +48 -1
  94. package/dist/services/audit/enforcers/code-ban.d.ts +11 -2
  95. package/dist/services/audit/enforcers/code-ban.js +21 -1
  96. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.d.ts +17 -0
  97. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.js +24 -7
  98. package/dist/services/audit-independent/handoff-missing-refusal.d.ts +26 -0
  99. package/dist/services/audit-independent/handoff-missing-refusal.js +109 -0
  100. package/dist/services/audit-independent/handoff-readers.d.ts +37 -0
  101. package/dist/services/audit-independent/handoff-readers.js +81 -0
  102. package/dist/services/audit-independent/index.d.ts +6 -1
  103. package/dist/services/audit-independent/index.js +6 -1
  104. package/dist/services/audit-independent/judged-declaration-build.d.ts +48 -0
  105. package/dist/services/audit-independent/judged-declaration-build.js +73 -0
  106. package/dist/services/audit-independent/judged-declaration-check.d.ts +80 -0
  107. package/dist/services/audit-independent/judged-declaration-check.js +216 -0
  108. package/dist/services/audit-independent/judged-declaration.d.ts +94 -0
  109. package/dist/services/audit-independent/judged-declaration.js +218 -0
  110. package/dist/services/audit-independent/perf-audit-service.js +12 -14
  111. package/dist/services/audit-independent/security-audit-artifact.d.ts +28 -0
  112. package/dist/services/audit-independent/security-audit-artifact.js +90 -0
  113. package/dist/services/audit-independent/security-audit-service.d.ts +6 -53
  114. package/dist/services/audit-independent/security-audit-service.js +34 -178
  115. package/dist/services/capability-guard-runner/contracts/J05.js +60 -14
  116. package/dist/services/codegraph/codegraph-index-integrity.js +2 -0
  117. package/dist/services/context/build-dispatch-system-prompt.d.ts +8 -12
  118. package/dist/services/context/build-dispatch-system-prompt.js +18 -18
  119. package/dist/services/context/collector.js +5 -1
  120. package/dist/services/context/post-compact-reinjection.js +1 -1
  121. package/dist/services/dispatch/active-dispatch-index.d.ts +36 -0
  122. package/dist/services/dispatch/active-dispatch-index.js +118 -0
  123. package/dist/services/dispatch/batch-counter.js +1 -2
  124. package/dist/services/dispatch/dispatch-record-writer.d.ts +29 -16
  125. package/dist/services/dispatch/dispatch-record-writer.js +58 -100
  126. package/dist/services/dispatch/dispatch-sub-agent.js +1 -1
  127. package/dist/services/dispatch/karpathy-block.d.ts +55 -0
  128. package/dist/services/dispatch/karpathy-block.js +101 -0
  129. package/dist/services/dispatch/ledger-reaper.d.ts +80 -0
  130. package/dist/services/dispatch/ledger-reaper.js +131 -0
  131. package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
  132. package/dist/services/dispatch/test-tool-detection.js +12 -1
  133. package/dist/services/evidence/evidence-generator.js +23 -12
  134. package/dist/services/feedback/feedback-promotion-service.d.ts +8 -11
  135. package/dist/services/feedback/feedback-promotion-service.js +30 -35
  136. package/dist/services/feedback/promotion-artifact-json-evidence.d.ts +18 -0
  137. package/dist/services/feedback/promotion-artifact-missing.d.ts +22 -0
  138. package/dist/services/feedback/promotion-artifact-missing.js +63 -0
  139. package/dist/services/final-review/final-review-contract.d.ts +95 -4
  140. package/dist/services/final-review/final-review-contract.js +64 -0
  141. package/dist/services/final-review/final-review-delivery.d.ts +13 -0
  142. package/dist/services/final-review/final-review-delivery.js +26 -12
  143. package/dist/services/final-review/final-review-evidence-collect.js +8 -53
  144. package/dist/services/final-review/final-review-evidence-records.d.ts +21 -0
  145. package/dist/services/final-review/final-review-evidence-records.js +67 -0
  146. package/dist/services/final-review/final-review-evidence-sources.d.ts +22 -0
  147. package/dist/services/final-review/final-review-evidence-sources.js +28 -4
  148. package/dist/services/final-review/final-review-prompt.js +19 -6
  149. package/dist/services/final-review/final-review-runner.js +5 -0
  150. package/dist/services/final-review/final-review-service.d.ts +2 -2
  151. package/dist/services/final-review/index.d.ts +1 -1
  152. package/dist/services/final-review/pre-post-diff.d.ts +2 -75
  153. package/dist/services/final-review/pre-post-diff.js +60 -59
  154. package/dist/services/hooks/pre-tool-code-gate.d.ts +7 -1
  155. package/dist/services/hooks/pre-tool-code-gate.js +21 -2
  156. package/dist/services/hooks/worktree-authorization-gate.js +6 -31
  157. package/dist/services/hooks/worktree-refusal-messages.d.ts +74 -0
  158. package/dist/services/hooks/worktree-refusal-messages.js +102 -0
  159. package/dist/services/lint/eslint-runner-support.d.ts +1 -1
  160. package/dist/services/lint/eslint-runner-support.js +2 -1
  161. package/dist/services/lint/eslint-runner-types.d.ts +8 -0
  162. package/dist/services/lint/eslint-runner.js +17 -4
  163. package/dist/services/llm/anthropic-runner.js +24 -7
  164. package/dist/services/loop/loop-observability.d.ts +39 -0
  165. package/dist/services/loop/loop-observability.js +55 -0
  166. package/dist/services/loop/monotonic-guard.js +6 -9
  167. package/dist/services/loop/monotonic-runner.js +8 -7
  168. package/dist/services/loop/run-driver.js +18 -22
  169. package/dist/services/memory/project-memory-service/index/kind-dispatch.js +14 -1
  170. package/dist/services/memory/project-memory-service/index/project-memory-plan-exec.js +13 -2
  171. package/dist/services/memory/project-memory-service/index.d.ts +2 -2
  172. package/dist/services/memory/project-memory-service/index.js +1 -1
  173. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.d.ts +36 -0
  174. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.js +48 -2
  175. package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts +23 -1
  176. package/dist/services/memory/project-memory-service/parsers/markdown-pure.js +37 -0
  177. package/dist/services/memory/project-memory-service/types.d.ts +32 -0
  178. package/dist/services/observability/observability-service.d.ts +7 -0
  179. package/dist/services/observability/observability-service.js +2 -1
  180. package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
  181. package/dist/services/openspec/coverage-evidence-reader.js +8 -8
  182. package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
  183. package/dist/services/openspec/openspec-archive-service.js +6 -6
  184. package/dist/services/prd/gate-evidence-derivation.d.ts +4 -3
  185. package/dist/services/prd/gate-evidence-derivation.js +4 -3
  186. package/dist/services/qa/bdd-test-style-verifier.js +22 -8
  187. package/dist/services/race/gate2-evaluator.d.ts +58 -0
  188. package/dist/services/race/gate2-evaluator.js +111 -0
  189. package/dist/services/race/gate2-policy.d.ts +17 -0
  190. package/dist/services/race/gate2-policy.js +31 -0
  191. package/dist/services/race/lane-phase.d.ts +19 -0
  192. package/dist/services/race/lane-phase.js +113 -0
  193. package/dist/services/race/pilot-gate-store.d.ts +67 -0
  194. package/dist/services/race/pilot-gate-store.js +227 -0
  195. package/dist/services/scan/file-size-baseline.d.ts +33 -0
  196. package/dist/services/scan/file-size-baseline.js +173 -0
  197. package/dist/services/scan/file-size-scan.d.ts +35 -3
  198. package/dist/services/scan/file-size-scan.js +63 -42
  199. package/dist/services/scan/type-corroboration.d.ts +32 -0
  200. package/dist/services/scan/type-corroboration.js +51 -0
  201. package/dist/services/scan/type-sanity-service.d.ts +14 -0
  202. package/dist/services/scan/type-sanity-service.js +23 -22
  203. package/dist/services/security/safe-settings-path.d.ts +5 -0
  204. package/dist/services/security/safe-settings-path.js +64 -8
  205. package/dist/services/skill/resume-detector.js +11 -11
  206. package/dist/services/skills/hooks-codegate-superpowers.d.ts +5 -6
  207. package/dist/services/skills/hooks-codegate-superpowers.js +7 -8
  208. package/dist/services/skills/hooks-settings-service.d.ts +1 -1
  209. package/dist/services/skills/hooks-settings-service.js +1 -1
  210. package/dist/services/skills/presence-lease-order.d.ts +13 -0
  211. package/dist/services/skills/presence-lease-order.js +24 -0
  212. package/dist/services/skills/skill-conformance-service.js +1 -0
  213. package/dist/services/skills/skill-statusline-service.js +4 -7
  214. package/dist/services/slice/slice-check-service.js +8 -8
  215. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +24 -8
  216. package/dist/services/workflow/pipeline-verify-gate-support.js +34 -39
  217. package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
  218. package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
  219. package/dist/services/workflow/pipeline-verify-service.js +27 -28
  220. package/dist/services/workflow/request-type-resolution.d.ts +99 -0
  221. package/dist/services/workflow/request-type-resolution.js +130 -0
  222. package/dist/services/workflow/workflow-skip-service.d.ts +1 -20
  223. package/dist/services/workflow/workflow-skip-service.js +22 -25
  224. package/dist/services/workflow/workflow-state-store.d.ts +9 -0
  225. package/dist/services/workflow/workflow-state-store.js +26 -1
  226. package/dist/services/workspace/claude-settings-retirements.d.ts +54 -0
  227. package/dist/services/workspace/claude-settings-retirements.js +112 -0
  228. package/dist/services/workspace/claude-settings-template-merge.d.ts +35 -15
  229. package/dist/services/workspace/claude-settings-template-merge.js +33 -53
  230. package/dist/services/workspace/claude-settings-template.d.ts +62 -12
  231. package/dist/services/workspace/claude-settings-template.js +58 -58
  232. package/dist/services/workspace/migrate-1-4-1-service.js +3 -0
  233. package/dist/services/workspace/reconcile-service.js +0 -1
  234. package/dist/shared/incrementing-number.d.ts +33 -2
  235. package/dist/shared/incrementing-number.js +72 -3
  236. package/package.json +5 -7
  237. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  238. package/skills/bee/peaks-prd/SKILL.md +4 -3
  239. package/skills/bee/peaks-qa/SKILL.md +1 -1
  240. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  241. package/skills/bee/peaks-qa/references/qa-transition-gates.md +1 -1
  242. package/skills/bee/peaks-rd/SKILL.md +2 -2
  243. package/skills/bee/peaks-rd/references/rd-fanout-contracts.md +1 -1
  244. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +8 -4
  245. package/skills/bee/peaks-rd/references/rd-transition-gates.md +3 -3
  246. package/skills/bee/peaks-rd/references/v2-12-fanout-collapse.md +2 -2
  247. package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md +1 -1
  248. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  249. package/skills/bee/peaks-sc/SKILL.md +1 -1
  250. package/skills/bee/peaks-security-audit/SKILL.md +10 -2
  251. package/skills/bee/peaks-txt/SKILL.md +4 -3
  252. package/skills/bee/peaks-ui/SKILL.md +3 -3
  253. package/skills/peaks-audit/SKILL.md +29 -1
  254. package/skills/peaks-code/SKILL.md +37 -17
  255. package/skills/peaks-code/references/fast-lane-norm.md +42 -0
  256. package/skills/peaks-code/references/fast-mode.md +3 -2
  257. package/skills/peaks-code/references/local-artifact-workspace.md +3 -3
  258. package/skills/peaks-code/references/micro-cycle.md +3 -3
  259. package/skills/peaks-code/references/resume-detection.md +1 -1
  260. package/skills/peaks-code/references/runbook.md +12 -6
  261. package/skills/peaks-code/references/step-11-memory-sediment.md +4 -0
  262. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  263. package/skills/peaks-code/references/swarm-dispatch-contract.md +40 -16
  264. package/skills/peaks-code/references/workflow-gates-and-types.md +6 -6
  265. package/skills/peaks-code/references/worktree-governance.md +4 -4
  266. package/skills/peaks-content/SKILL.md +1 -1
  267. package/skills/peaks-doctor/SKILL.md +1 -1
  268. package/skills/peaks-final-review/SKILL.md +31 -11
  269. package/skills/peaks-ide/SKILL.md +1 -1
  270. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  271. package/skills/peaks-race-code/SKILL.md +185 -0
  272. package/skills/peaks-resume/SKILL.md +1 -1
  273. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  274. package/skills/peaks-solo/SKILL.md +1 -1
  275. package/skills/peaks-sop/SKILL.md +1 -1
  276. package/skills/peaks-status/SKILL.md +1 -1
  277. package/skills/peaks-test/SKILL.md +7 -4
  278. package/dist/cli/commands/vm-command-shared.d.ts +0 -23
  279. package/dist/cli/commands/vm-command-shared.js +0 -23
  280. package/dist/cli/commands/vm-commands.d.ts +0 -3
  281. package/dist/cli/commands/vm-commands.js +0 -45
  282. package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
  283. package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
  284. package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
  285. package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
  286. package/dist/cli/commands/vm-release-command.d.ts +0 -5
  287. package/dist/cli/commands/vm-release-command.js +0 -101
  288. package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
  289. package/dist/cli/commands/vm-spawn-command.js +0 -177
  290. package/dist/cli/commands/vm-status-command.js +0 -50
  291. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.d.ts +0 -23
  292. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.js +0 -64
  293. package/dist/services/vm/vm-lease.d.ts +0 -40
  294. package/dist/services/vm/vm-lease.js +0 -160
@@ -0,0 +1,55 @@
1
+ /**
2
+ * The loop runtime's two observability emissions: the monotonic guard's verdict
3
+ * for a cycle, and that cycle's own outcome.
4
+ *
5
+ * WHY BOTH MAPPINGS LIVE HERE. The two producers cannot emit for themselves:
6
+ * `checkMonotonicImprovement` is pure (no project root, no session id —
7
+ * `monotonic-guard.ts:83`), and the cycle bookkeeping in `runLoopLocked` has no
8
+ * emitter. So the emit happens in the callers, and the callers are two files.
9
+ * The mapping from loop state to event vocabulary is decided ONCE, here, rather
10
+ * than re-derived at each call site.
11
+ *
12
+ * Fire-and-forget by contract: whatever `emitObservabilityEvent` returns
13
+ * (`written: false` on every error path) is dropped, and neither helper throws.
14
+ */
15
+ import { emitCycleEvent, emitMonotonicTriggerEvent } from '../observability/observability-service.js';
16
+ /**
17
+ * `monotonic-trigger` — once per computed report, from each caller of
18
+ * `checkMonotonicImprovement`, which is pure and cannot emit for itself.
19
+ *
20
+ * `pass` → `report: 'pass'`; `block` → `report: 'block'`; `action` is the
21
+ * report's own `code`, a vocabulary the guard already produces
22
+ * (`MONOTONIC_OK` / `MONOTONIC_VIOLATION` / `MONOTONIC_NO_PREVIOUS` /
23
+ * `MONOTONIC_INCOMPARABLE_EVALUATORS`). **`skip` emits NOTHING**: nothing was
24
+ * guarded, so counting it would make the counter track "how often the guard ran"
25
+ * instead of "how often a monotonic condition fired". `'warn'` stays unused —
26
+ * the guard cannot return it, and it is not repurposed here.
27
+ */
28
+ export function emitMonotonicReport(projectRoot, sid, report) {
29
+ if (report.status === 'skip')
30
+ return;
31
+ emitMonotonicTriggerEvent({
32
+ projectRoot,
33
+ sessionId: sid,
34
+ report: report.status,
35
+ action: report.code
36
+ });
37
+ }
38
+ /**
39
+ * `cycle` — exactly ONE event per cycle, at the end of the iteration.
40
+ *
41
+ * One, not two: `aggregateDashboardMetrics` counts events, not distinct cycle
42
+ * ids (`aggregation.ts:212`), so emitting `'started'` alongside this one would
43
+ * double `cycleCount`. `'started'` therefore stays unused. `status` is
44
+ * `'failed'` for the cycle whose report carries the violation — the same
45
+ * condition `runLoopLocked` aborts on — and `'completed'` otherwise, so
46
+ * `cycleCount` equals the number of cycles the driver actually ran.
47
+ */
48
+ export function emitCycleOutcome(projectRoot, sid, cycle, report) {
49
+ emitCycleEvent({
50
+ projectRoot,
51
+ sessionId: sid,
52
+ cycle,
53
+ status: report.monotonicityViolation ? 'failed' : 'completed'
54
+ });
55
+ }
@@ -13,6 +13,8 @@
13
13
  *
14
14
  * File budget: ≤ 800 lines (Karpathy §2).
15
15
  */
16
+ import { readFileSync, readdirSync } from 'node:fs';
17
+ import { join } from 'node:path';
16
18
  /** Score normalisation — gateAction maps to a 0..1 score:
17
19
  * pass → 1.0
18
20
  * warn → 0.5
@@ -148,15 +150,10 @@ function classifyFsError(err) {
148
150
  * .peaks/_sub_agents/<sid>/shared/ 跨批 signal → 不 crash").
149
151
  * Pure helper; only present for the cross-session case. */
150
152
  export function loadCrossSessionSignal(projectRoot, sid) {
151
- // Lazily import so unit tests in non-windows environments don't pull
152
- // node:fs through a static `import` (test envs stay small).
153
- // eslint-disable-next-line @typescript-eslint/no-var-requires
154
- const fs = require('node:fs');
155
- const path = require('node:path');
156
- const sharedDir = path.join(projectRoot, '.peaks', '_sub_agents', sid, 'shared');
153
+ const sharedDir = join(projectRoot, '.peaks', '_sub_agents', sid, 'shared');
157
154
  const readdir = (() => {
158
155
  try {
159
- return { ok: true, value: fs.readdirSync(sharedDir) };
156
+ return { ok: true, value: readdirSync(sharedDir) };
160
157
  }
161
158
  catch (err) {
162
159
  return { ok: false, reason: classifyFsError(err) };
@@ -177,10 +174,10 @@ export function loadCrossSessionSignal(projectRoot, sid) {
177
174
  }
178
175
  if (best === null)
179
176
  return null;
180
- const target = path.join(sharedDir, `cycle-${best}.json`);
177
+ const target = join(sharedDir, `cycle-${best}.json`);
181
178
  const readFile = (() => {
182
179
  try {
183
- return { ok: true, value: fs.readFileSync(target, 'utf8') };
180
+ return { ok: true, value: readFileSync(target, 'utf8') };
184
181
  }
185
182
  catch (err) {
186
183
  return { ok: false, reason: classifyFsError(err) };
@@ -21,10 +21,12 @@
21
21
  *
22
22
  * File budget: ≤ 800 lines (Karpathy §2).
23
23
  */
24
+ import { existsSync, readFileSync, readdirSync } from 'node:fs';
24
25
  import { join } from 'node:path';
25
26
  import { dispatchEvaluator } from './evaluator-dispatcher.js';
26
27
  import { checkMonotonicImprovement, toScoreRow, DEFAULT_MONOTONIC_THRESHOLD } from './monotonic-guard.js';
27
28
  import { appendMetricLine, readMetricLines } from '../observability/jsonl-store.js';
29
+ import { emitMonotonicReport } from './loop-observability.js';
28
30
  import { findProjectRoot } from '../config/config-safety.js';
29
31
  import { classifyFsError, MONOTONIC_CYCLE_KIND, WALKED_EVALUATORS } from './monotonic-runner-types.js';
30
32
  /** Resolve the slice dir — kept for API/BC (run-driver.ts uses it to
@@ -112,15 +114,11 @@ function loadMostRecentCycleFromSubAgents(projectRoot, sid, rid) {
112
114
  return loadMostRecentCycleFromDir(dir, rid);
113
115
  }
114
116
  function loadMostRecentCycleFromDir(dir, rid) {
115
- // Lazily import so unit tests in non-windows environments don't pull
116
- // node:fs through a static `import`.
117
- // eslint-disable-next-line @typescript-eslint/no-var-requires
118
- const fs = require('node:fs');
119
- if (!fs.existsSync(dir))
117
+ if (!existsSync(dir))
120
118
  return null;
121
119
  const readdir = (() => {
122
120
  try {
123
- return { ok: true, value: fs.readdirSync(dir) };
121
+ return { ok: true, value: readdirSync(dir) };
124
122
  }
125
123
  catch (err) {
126
124
  return { ok: false, reason: classifyFsError(err) };
@@ -143,7 +141,7 @@ function loadMostRecentCycleFromDir(dir, rid) {
143
141
  const target = join(dir, `cycle-${bestCycle}.json`);
144
142
  const readFile = (() => {
145
143
  try {
146
- return { ok: true, value: fs.readFileSync(target, 'utf8') };
144
+ return { ok: true, value: readFileSync(target, 'utf8') };
147
145
  }
148
146
  catch (err) {
149
147
  return { ok: false, reason: classifyFsError(err) };
@@ -222,6 +220,9 @@ export function runMonotonicCheck(options) {
222
220
  const currentCycle = { cycle, scores: rows };
223
221
  const previousCycle = loadPreviousCycle(options.projectRoot, options.sid, options.rid);
224
222
  const report = checkMonotonicImprovement(previousCycle, currentCycle, { threshold });
223
+ // The guard is pure and holds no session binding, so its caller emits, one
224
+ // line after the verdict exists.
225
+ emitMonotonicReport(options.projectRoot, options.sid, report);
225
226
  let persistedAt = null;
226
227
  const envelopeWarns = [];
227
228
  if (persist) {
@@ -7,31 +7,27 @@
7
7
  * load-bearing: it reads `.peaks/_runtime/<sid>/loop/<rid>/spec.yaml`,
8
8
  * walks each `evaluators[].kind` in order via `dispatchEvaluator`,
9
9
  * captures a score row, persists the current cycle to disk, runs the
10
- * monotonic guard against the prior cycle, and decides whether to
11
- * continue / abort based on `termination.strategy`.
10
+ * monotonic guard against the prior cycle, emits that cycle's `cycle` and
11
+ * `monotonic-trigger` events (`loop-observability.ts`), and decides
12
+ * whether to continue / abort based on `termination.strategy`.
12
13
  *
13
- * Strategy semantics:
14
- * - `monotonic-violation` (default): abort on MONOTONICITY_VIOLATION.
15
- * - `max-cycles`: run exactly `termination.maxCycles` (default 5)
16
- * cycles, aborting on any violation along the way.
17
- * - `manual`: run exactly one cycle and exit 0; further cycles are
18
- * the operator's responsibility.
19
- * - anything else: `UNKNOWN_TERMINATION_STRATEGY`.
14
+ * Strategy semantics: `monotonic-violation` (default) aborts on
15
+ * MONOTONICITY_VIOLATION; `max-cycles` runs exactly `termination.maxCycles`
16
+ * (default 5), aborting on any violation along the way; `manual` runs exactly
17
+ * one cycle and exits 0, further cycles being the operator's responsibility;
18
+ * anything else is `UNKNOWN_TERMINATION_STRATEGY`.
20
19
  *
21
- * Karpathy §2 Simplicity First: no new deps. Pure-data + JSON to
22
- * disk. The single in-process lock flag prevents two concurrent
23
- * `peaks loop run` calls (same sid+rid) from corrupting the cycle
24
- * index; cross-process locking is out of scope per the dispatch
25
- * prompt.
26
- *
27
- * File budget: ≤ 800 lines.
20
+ * Karpathy §2 Simplicity First: no new deps. Pure data + JSON to disk. The
21
+ * in-process lock flag stops two concurrent `peaks loop run` calls (same
22
+ * sid+rid) corrupting the cycle index; cross-process locking is out of scope.
28
23
  */
29
- import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
24
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
30
25
  import { join } from 'node:path';
31
26
  import { resolveLoopSpec, lintLoopSpec, specPath, MONOTONIC_TERMINATION, DEFAULT_MAX_CYCLES } from './spec-service.js';
32
27
  import { dispatchEvaluator } from './evaluator-dispatcher.js';
33
28
  import { checkMonotonicImprovement, toScoreRow, DEFAULT_MONOTONIC_THRESHOLD } from './monotonic-guard.js';
34
29
  import { nextCycleIndex, sliceDir } from './monotonic-runner.js';
30
+ import { emitCycleOutcome, emitMonotonicReport } from './loop-observability.js';
35
31
  import { findProjectRoot } from '../config/config-safety.js';
36
32
  function classifyFsError(err) {
37
33
  const code = err?.code;
@@ -278,7 +274,11 @@ function runLoopLocked(spec, strategy, maxCycles, options) {
278
274
  ? persistCycleRecord(options.projectRoot, options.sid, options.rid, cycleNo, rows)
279
275
  : null;
280
276
  const record = buildCycleRecord(cycleNo, rows, previousCycle, threshold, persistedAt);
277
+ // The guard is pure and holds no binding, so the caller emits for it; one
278
+ // `cycle` event per cycle, after the push, or the per-event count doubles.
279
+ emitMonotonicReport(options.projectRoot, options.sid, record.monotonicReport);
281
280
  cycles.push(record);
281
+ emitCycleOutcome(options.projectRoot, options.sid, cycleNo, record.monotonicReport);
282
282
  finalReport = record.monotonicReport;
283
283
  if (record.monotonicReport.monotonicityViolation) {
284
284
  regressionCount += record.monotonicReport.regressions.length;
@@ -344,13 +344,9 @@ function loadCycleAt(projectRoot, sid, rid, n) {
344
344
  return parseCycleFromPath(path, n);
345
345
  }
346
346
  function parseCycleFromPath(path, fallbackCycle) {
347
- // Defer to monotonic-runner via a lazy require (the function is
348
- // small and avoids leaking its internals).
349
- // eslint-disable-next-line @typescript-eslint/no-var-requires
350
- const fs = require('node:fs');
351
347
  const readFile = (() => {
352
348
  try {
353
- return { ok: true, value: fs.readFileSync(path, 'utf8') };
349
+ return { ok: true, value: readFileSync(path, 'utf8') };
354
350
  }
355
351
  catch (err) {
356
352
  return { ok: false, reason: classifyFsError(err) };
@@ -62,6 +62,7 @@ export function extractSessionMemories(options) {
62
62
  extractedCount: 0,
63
63
  writtenFiles: [],
64
64
  updatedIndex: false,
65
+ skippedWrites: [],
65
66
  droppedBlocks: [],
66
67
  scanFailures: []
67
68
  };
@@ -116,6 +117,7 @@ export function extractSessionMemories(options) {
116
117
  extractedCount: 0,
117
118
  writtenFiles: [],
118
119
  updatedIndex: false,
120
+ skippedWrites: [],
119
121
  droppedBlocks,
120
122
  scanFailures
121
123
  };
@@ -136,12 +138,22 @@ export function extractSessionMemories(options) {
136
138
  // writes so callers can still tell what the run actually produced.
137
139
  const existingNames = apply ? readStoredMemoryNames(primaryMemoryDir) : new Set();
138
140
  const writtenFiles = [];
141
+ const skippedWrites = [];
139
142
  if (apply) {
140
143
  mkdirSync(primaryMemoryDir, { recursive: true });
141
144
  for (const memory of allExtracted) {
142
145
  const slug = slugify(memory.title);
143
- if (existingNames.has(slug))
146
+ if (existingNames.has(slug)) {
147
+ // Same defect as the artifact path, one function over: the skip left no
148
+ // trace, so `extractedCount: 5` with 4 files on disk read as success.
149
+ skippedWrites.push({
150
+ slug,
151
+ title: memory.title,
152
+ sourceArtifact: memory.sourceArtifact,
153
+ filePath: join(primaryMemoryDir, `${slug}.md`)
154
+ });
144
155
  continue;
156
+ }
145
157
  const targetPath = join(primaryMemoryDir, `${slug}.md`);
146
158
  const safePath = resolveInputPath(targetPath);
147
159
  const stableSafePath = stablePath(safePath);
@@ -163,6 +175,7 @@ export function extractSessionMemories(options) {
163
175
  extractedCount: allExtracted.length,
164
176
  writtenFiles,
165
177
  updatedIndex: apply && writtenFiles.length > 0,
178
+ skippedWrites,
166
179
  droppedBlocks,
167
180
  scanFailures
168
181
  };
@@ -61,6 +61,7 @@ export function createProjectMemoryExtractPlan(options) {
61
61
  export function executeProjectMemoryExtract(options) {
62
62
  const plan = createProjectMemoryExtractPlan(options);
63
63
  const writtenFiles = [];
64
+ const skippedWrites = [];
64
65
  if (plan.apply) {
65
66
  mkdirSync(plan.primaryMemoryDir, { recursive: true });
66
67
  const safeMemoryDir = assertSafeProjectMemoryDir(plan.projectRoot);
@@ -74,8 +75,18 @@ export function executeProjectMemoryExtract(options) {
74
75
  const existingNames = readStoredMemoryNames(plan.primaryMemoryDir);
75
76
  for (const write of plan.plannedWrites) {
76
77
  const slug = slugify(write.memory.title);
77
- if (existingNames.has(slug))
78
+ if (existingNames.has(slug)) {
79
+ // Recorded, not merely skipped: a skip and a successful write left
80
+ // identical evidence in the envelope, so the block vanished from the
81
+ // report of a run that had extracted it.
82
+ skippedWrites.push({
83
+ slug,
84
+ title: write.memory.title,
85
+ sourceArtifact: write.memory.sourceArtifact,
86
+ filePath: write.filePath
87
+ });
78
88
  continue;
89
+ }
79
90
  const targetPath = resolveInputPath(write.filePath);
80
91
  const stableTargetPath = stablePath(targetPath);
81
92
  if (!isInsidePath(stableTargetPath, stableRealPath(safeMemoryDir))) {
@@ -97,7 +108,7 @@ export function executeProjectMemoryExtract(options) {
97
108
  const indexPath = join(plan.primaryMemoryDir, 'index.json');
98
109
  generateMemoryIndexFile(plan.projectRoot, plan.primaryMemoryDir, indexPath);
99
110
  }
100
- return { ...plan, writtenFiles };
111
+ return { ...plan, writtenFiles, skippedWrites };
101
112
  }
102
113
  export function createProjectMemoryBackupPlan(options) {
103
114
  const projectRoot = normalizeRoot(options.projectRoot);
@@ -1,7 +1,7 @@
1
- export type { BackupPlanOptions, ExtractedProjectMemory, MemoryBlockDrop, MemoryBlockDropReason, MemoryBlockParse, MemoryKindTier, ExtractPlanOptions, ExtractSessionMemoriesOptions, ExtractSessionMemoriesResult, MemoryIndex, MemoryIndexEntry, ProjectMemoryBackupPlan, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryCopy, ProjectMemoryExtractPlan, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, ProjectMemoryKind, ProjectMemoryReadResult, ProjectMemoryShowResult, ProjectMemoryWrite, StoredProjectMemory } from './types.js';
1
+ export type { BackupPlanOptions, ExtractedProjectMemory, MemoryBlockDrop, MemoryBlockDropReason, MemoryBlockParse, MemoryKindTier, MemoryWriteSkip, ExtractPlanOptions, ExtractSessionMemoriesOptions, ExtractSessionMemoriesResult, MemoryIndex, MemoryIndexEntry, ProjectMemoryBackupPlan, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryCopy, ProjectMemoryExtractPlan, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, ProjectMemoryKind, ProjectMemoryReadResult, ProjectMemoryShowResult, ProjectMemoryWrite, StoredProjectMemory } from './types.js';
2
2
  export { VALID_PROJECT_MEMORY_KINDS } from './parsers/frontmatter.js';
3
3
  export { HOT_MEMORY_KINDS, MEMORY_KIND_TIER, PROJECT_MEMORY_KINDS, WARM_MEMORY_KINDS } from './types.js';
4
- export { describeMemoryBlockDrops, describeSessionScanFailures, summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, extractStableProjectMemoriesWithDiagnostics, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
4
+ export { describeMemoryBlockDrops, describeMemoryWriteSkips, describeSessionScanFailures, MAX_NAMED_MEMORY_WRITE_SKIPS, summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, extractStableProjectMemoriesWithDiagnostics, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
5
5
  export type { SessionScanFailure } from './types.js';
6
6
  export type { ExtractedMemoryBlocks } from './parsers/markdown-pure.js';
7
7
  export { parseBlock, parseBlockResult, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
@@ -14,7 +14,7 @@ export { VALID_PROJECT_MEMORY_KINDS } from './parsers/frontmatter.js';
14
14
  // Canonical kind vocabulary + hot/warm tier map (slice E)
15
15
  export { HOT_MEMORY_KINDS, MEMORY_KIND_TIER, PROJECT_MEMORY_KINDS, WARM_MEMORY_KINDS } from './types.js';
16
16
  // Pure markdown helpers
17
- export { describeMemoryBlockDrops, describeSessionScanFailures, summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, extractStableProjectMemoriesWithDiagnostics, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
17
+ export { describeMemoryBlockDrops, describeMemoryWriteSkips, describeSessionScanFailures, MAX_NAMED_MEMORY_WRITE_SKIPS, summarizeBackupResult, summarizeExtractResult, summarizeMemoryBody, extractStableProjectMemories, extractStableProjectMemoriesWithDiagnostics, END_MARKER, START_MARKER } from './parsers/markdown-pure.js';
18
18
  // Frontmatter parser + renderer
19
19
  export { parseBlock, parseBlockResult, parseMemoryFrontmatter, parseStoredMemoryFile, renderMemoryFile, resolveMemoryKind, resolveMemoryName, slugify } from './parsers/frontmatter.js';
20
20
  // Store: path safety + sensitive content
@@ -5,6 +5,42 @@ export declare const VALID_MEMORY_KINDS: ReadonlySet<ProjectMemoryKind>;
5
5
  /** Exported for guard tests + tooling that needs to enumerate the accepted
6
6
  * set (CLI help text, `--kind` validation) without duplicating the literal. */
7
7
  export declare const VALID_PROJECT_MEMORY_KINDS: readonly ProjectMemoryKind[];
8
+ /**
9
+ * Filename stem for a memory title, and the `name:` its stored frontmatter
10
+ * carries.
11
+ *
12
+ * The character class is Unicode-aware deliberately. An ASCII-only class
13
+ * reduced EVERY title written in a non-Latin script to the same empty string,
14
+ * so all of them landed on one constant name: whichever title arrived first
15
+ * took that file, and each later one was skipped because the store refuses to
16
+ * overwrite a file it already holds. Two titles that still reduce to one stem
17
+ * are refused outright by the plan builders' duplicate-name check.
18
+ *
19
+ * A title with no letter or digit in any script ("!!!") leaves nothing to build
20
+ * a name from. That branch takes the first 32 hex characters of the title's
21
+ * sha256 instead of a fixed constant, so distinct titles still reach distinct
22
+ * names. It is a DIGEST rather than the title's bytes because of LENGTH: an
23
+ * encoding that grew with the title (the two-hex-chars-per-byte
24
+ * `toString('hex')` this replaced) produced names past the filesystem limit for
25
+ * a long enough title, so the write failed and took the whole batch with it —
26
+ * measured, exit 1 and 0 files for a 140-character title. A digest is 39
27
+ * characters whatever the title is.
28
+ *
29
+ * THE FIXED LENGTH IS BOUGHT WITH A PROBABILISTIC GUARANTEE, and that is the
30
+ * strongest thing this branch can claim. For the derived branch distinct titles
31
+ * reach distinct names with overwhelming probability rather than by
32
+ * construction: a collision needs two titles whose first 128 digest bits agree
33
+ * — the birthday bound puts that at about n^2 / 2^129 for n derived names in one
34
+ * store, i.e. under 1 in 10^26 at a million names. The branch above keeps the
35
+ * stronger, exact property (two titles share a stem only if they are equal
36
+ * modulo case and runs of non-letter/non-digit characters). Neither branch loses
37
+ * a block silently on a collision: within a run the duplicate-name check refuses
38
+ * the whole extract, and across runs the later write is skipped and NAMED in the
39
+ * envelope's `warnings`.
40
+ *
41
+ * The '_' is outside the alphabet the branch above can emit, so a derived name
42
+ * cannot equal a title-derived stem.
43
+ */
8
44
  export declare function slugify(title: string): string;
9
45
  /**
10
46
  * Single implementation of the extract-path block parse. Returns a
@@ -7,6 +7,7 @@
7
7
  // every name here so the `index.ts` barrel, `markdown-pure.ts` and the CLI
8
8
  // keep importing them from `./parsers/frontmatter.js` unchanged.
9
9
  // ---------------------------------------------------------------------------
10
+ import { createHash } from 'node:crypto';
10
11
  import { PROJECT_MEMORY_KINDS } from '../types.js';
11
12
  /** Accepted-kind set, derived from the canonical `PROJECT_MEMORY_KINDS`
12
13
  * tuple so the parser cannot drift from the union type / tier map. */
@@ -14,12 +15,57 @@ export const VALID_MEMORY_KINDS = new Set(PROJECT_MEMORY_KINDS);
14
15
  /** Exported for guard tests + tooling that needs to enumerate the accepted
15
16
  * set (CLI help text, `--kind` validation) without duplicating the literal. */
16
17
  export const VALID_PROJECT_MEMORY_KINDS = PROJECT_MEMORY_KINDS;
18
+ /**
19
+ * Hex characters of the title digest the derived branch keeps. 32 hex = 128
20
+ * bits, and the name is therefore `memory_` + 32 = **39 characters for every
21
+ * title**, however long the title is.
22
+ */
23
+ const DERIVED_NAME_HEX_LENGTH = 32;
24
+ /**
25
+ * Filename stem for a memory title, and the `name:` its stored frontmatter
26
+ * carries.
27
+ *
28
+ * The character class is Unicode-aware deliberately. An ASCII-only class
29
+ * reduced EVERY title written in a non-Latin script to the same empty string,
30
+ * so all of them landed on one constant name: whichever title arrived first
31
+ * took that file, and each later one was skipped because the store refuses to
32
+ * overwrite a file it already holds. Two titles that still reduce to one stem
33
+ * are refused outright by the plan builders' duplicate-name check.
34
+ *
35
+ * A title with no letter or digit in any script ("!!!") leaves nothing to build
36
+ * a name from. That branch takes the first 32 hex characters of the title's
37
+ * sha256 instead of a fixed constant, so distinct titles still reach distinct
38
+ * names. It is a DIGEST rather than the title's bytes because of LENGTH: an
39
+ * encoding that grew with the title (the two-hex-chars-per-byte
40
+ * `toString('hex')` this replaced) produced names past the filesystem limit for
41
+ * a long enough title, so the write failed and took the whole batch with it —
42
+ * measured, exit 1 and 0 files for a 140-character title. A digest is 39
43
+ * characters whatever the title is.
44
+ *
45
+ * THE FIXED LENGTH IS BOUGHT WITH A PROBABILISTIC GUARANTEE, and that is the
46
+ * strongest thing this branch can claim. For the derived branch distinct titles
47
+ * reach distinct names with overwhelming probability rather than by
48
+ * construction: a collision needs two titles whose first 128 digest bits agree
49
+ * — the birthday bound puts that at about n^2 / 2^129 for n derived names in one
50
+ * store, i.e. under 1 in 10^26 at a million names. The branch above keeps the
51
+ * stronger, exact property (two titles share a stem only if they are equal
52
+ * modulo case and runs of non-letter/non-digit characters). Neither branch loses
53
+ * a block silently on a collision: within a run the duplicate-name check refuses
54
+ * the whole extract, and across runs the later write is skipped and NAMED in the
55
+ * envelope's `warnings`.
56
+ *
57
+ * The '_' is outside the alphabet the branch above can emit, so a derived name
58
+ * cannot equal a title-derived stem.
59
+ */
17
60
  export function slugify(title) {
18
61
  const slug = title
19
62
  .toLowerCase()
20
- .replace(/[^a-z0-9]+/g, '-')
63
+ .replace(/[^\p{L}\p{N}]+/gu, '-')
21
64
  .replace(/^-+|-+$/g, '');
22
- return slug.length > 0 ? slug : 'project-memory';
65
+ if (slug.length > 0)
66
+ return slug;
67
+ const digest = createHash('sha256').update(title, 'utf8').digest('hex');
68
+ return `memory_${digest.slice(0, DERIVED_NAME_HEX_LENGTH)}`;
23
69
  }
24
70
  /**
25
71
  * Single implementation of the extract-path block parse. Returns a
@@ -1,4 +1,4 @@
1
- import type { ExtractedProjectMemory, MemoryBlockDrop, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, SessionScanFailure } from '../types.js';
1
+ import type { ExtractedProjectMemory, MemoryBlockDrop, MemoryWriteSkip, ProjectMemoryBackupResult, ProjectMemoryBackupSummary, ProjectMemoryExtractResult, ProjectMemoryExtractSummary, SessionScanFailure } from '../types.js';
2
2
  export declare const START_MARKER = "<!-- peaks-memory:start -->";
3
3
  export declare const END_MARKER = "<!-- peaks-memory:end -->";
4
4
  export declare function summarizeMemoryBody(body: string): string;
@@ -29,5 +29,27 @@ export declare function describeMemoryBlockDrops(dropped: ReadonlyArray<MemoryBl
29
29
  * whole file that never yielded blocks at all.
30
30
  */
31
31
  export declare function describeSessionScanFailures(failures: ReadonlyArray<SessionScanFailure>): string[];
32
+ /**
33
+ * How many skipped writes are NAMED before the list closes with a count.
34
+ *
35
+ * The COUNT must never be lost — the failure reported here is a reader who could
36
+ * not tell how many writes were skipped — so it is always `skips.length`, never
37
+ * the number of lines above it. The LIST is what is capped: it grows with the
38
+ * capsule while the envelope does not, and 200 skipped blocks measured 201 lines
39
+ * and a 95 KB envelope with no ceiling on `warnings` anywhere in the code.
40
+ */
41
+ export declare const MAX_NAMED_MEMORY_WRITE_SKIPS = 20;
42
+ /**
43
+ * Render one warning line per planned write the store already held, plus a
44
+ * closing line with both counts.
45
+ *
46
+ * The counts are passed in rather than derived from `skips.length`: the caller
47
+ * observed the run, and `planned - skipped` is a claim about writes this
48
+ * function did not see. The closing line exists because the failure being
49
+ * reported is exactly a reader having no way to notice that the two counts
50
+ * differed — the named lines say which blocks were lost, the count says how
51
+ * many, and only the second one stays exact past the cap.
52
+ */
53
+ export declare function describeMemoryWriteSkips(skips: ReadonlyArray<MemoryWriteSkip>, plannedCount: number, writtenCount: number): string[];
32
54
  export declare function summarizeExtractResult(result: ProjectMemoryExtractResult): ProjectMemoryExtractSummary;
33
55
  export declare function summarizeBackupResult(result: ProjectMemoryBackupResult): ProjectMemoryBackupSummary;
@@ -164,6 +164,43 @@ export function describeMemoryBlockDrops(dropped) {
164
164
  export function describeSessionScanFailures(failures) {
165
165
  return failures.map((failure) => `Could not read the session artifact ${failure.file}: ${failure.detail}.`);
166
166
  }
167
+ /**
168
+ * How many skipped writes are NAMED before the list closes with a count.
169
+ *
170
+ * The COUNT must never be lost — the failure reported here is a reader who could
171
+ * not tell how many writes were skipped — so it is always `skips.length`, never
172
+ * the number of lines above it. The LIST is what is capped: it grows with the
173
+ * capsule while the envelope does not, and 200 skipped blocks measured 201 lines
174
+ * and a 95 KB envelope with no ceiling on `warnings` anywhere in the code.
175
+ */
176
+ export const MAX_NAMED_MEMORY_WRITE_SKIPS = 20;
177
+ /**
178
+ * Render one warning line per planned write the store already held, plus a
179
+ * closing line with both counts.
180
+ *
181
+ * The counts are passed in rather than derived from `skips.length`: the caller
182
+ * observed the run, and `planned - skipped` is a claim about writes this
183
+ * function did not see. The closing line exists because the failure being
184
+ * reported is exactly a reader having no way to notice that the two counts
185
+ * differed — the named lines say which blocks were lost, the count says how
186
+ * many, and only the second one stays exact past the cap.
187
+ */
188
+ export function describeMemoryWriteSkips(skips, plannedCount, writtenCount) {
189
+ if (skips.length === 0)
190
+ return [];
191
+ const lines = skips
192
+ .slice(0, MAX_NAMED_MEMORY_WRITE_SKIPS)
193
+ .map((skip) => `Skipped writing the memory "${skip.title}" from ${skip.sourceArtifact}: ${skip.filePath} already exists, so the block was not written.`);
194
+ const unlisted = skips.length - MAX_NAMED_MEMORY_WRITE_SKIPS;
195
+ if (unlisted > 0) {
196
+ // The dropped names are dropped for good: `skippedWrites` stays out of the
197
+ // envelope's `data`, so `warnings` is the only carrier. Saying so beats
198
+ // pointing the reader at a list that is not there.
199
+ lines.push(`… and ${unlisted} more skipped writes; the count below is the full number.`);
200
+ }
201
+ lines.push(`Wrote ${writtenCount} of ${plannedCount} planned memories; ${skips.length} skipped because the target file already exists.`);
202
+ return lines;
203
+ }
167
204
  export function summarizeExtractResult(result) {
168
205
  return {
169
206
  apply: result.apply,
@@ -36,6 +36,26 @@ export type MemoryBlockDrop = {
36
36
  /** Human-readable explanation of the failed precondition. */
37
37
  detail: string;
38
38
  };
39
+ /**
40
+ * A planned write that was NOT performed because the store already holds its
41
+ * target name.
42
+ *
43
+ * Distinct from `MemoryBlockDrop`: that one is a PARSE rejection, decided from
44
+ * the block's own text. This one is a WRITE skip — the block parsed, and it is
45
+ * still not in `.peaks/memory/`. Without it the two outcomes read alike from the
46
+ * envelope, because either one leaves `writtenFiles` short of `plannedWrites`.
47
+ * Empty on a preview, which writes nothing and so skips nothing.
48
+ */
49
+ export type MemoryWriteSkip = {
50
+ /** Filename stem the write would have used — already present in the store. */
51
+ slug: string;
52
+ /** Title of the memory that was not written. */
53
+ title: string;
54
+ /** Artifact the block was read from. */
55
+ sourceArtifact: string;
56
+ /** Absolute path that already exists and was therefore left untouched. */
57
+ filePath: string;
58
+ };
39
59
  /**
40
60
  * Result of parsing one memory block, as a discriminated union.
41
61
  *
@@ -72,6 +92,12 @@ export type ProjectMemoryExtractPlan = {
72
92
  };
73
93
  export type ProjectMemoryExtractResult = ProjectMemoryExtractPlan & {
74
94
  writtenFiles: string[];
95
+ /**
96
+ * Planned writes the store already held, so `writtenFiles` is shorter than
97
+ * `plannedWrites` by exactly this many. Reported through the CLI envelope's
98
+ * `warnings` channel, which is why it adds no field to the summary.
99
+ */
100
+ skippedWrites: MemoryWriteSkip[];
75
101
  };
76
102
  export type ProjectMemoryExtractSummary = {
77
103
  apply: boolean;
@@ -171,6 +197,12 @@ export type ExtractSessionMemoriesResult = {
171
197
  extractedCount: number;
172
198
  writtenFiles: string[];
173
199
  updatedIndex: boolean;
200
+ /**
201
+ * Planned writes the store already held, so `writtenFiles` is shorter than
202
+ * `extractedCount` by exactly this many. Same diagnostic contract as
203
+ * `ProjectMemoryExtractResult.skippedWrites`.
204
+ */
205
+ skippedWrites: MemoryWriteSkip[];
174
206
  /**
175
207
  * Blocks that were FOUND between the markers in this session's artifacts but
176
208
  * rejected by the parser. Same diagnostic contract as
@@ -90,6 +90,13 @@ export declare function emitTokenUsageEvent(opts: {
90
90
  projectRoot: string;
91
91
  inputTokens: number;
92
92
  outputTokens: number;
93
+ /**
94
+ * Where the two counts came from. Required, not defaulted: a `0` the provider
95
+ * reported and a `0` nobody measured are the same number, and the whole point
96
+ * of the tag is to stop them being read as one — a caller that cannot say
97
+ * which it holds has not measured.
98
+ */
99
+ source: 'provider' | 'estimated';
93
100
  }): EmitResult;
94
101
  /**
95
102
  */
@@ -142,7 +142,8 @@ export function emitTokenUsageEvent(opts) {
142
142
  detail: {
143
143
  inputTokens: opts.inputTokens,
144
144
  outputTokens: opts.outputTokens,
145
- totalTokens
145
+ totalTokens,
146
+ source: opts.source
146
147
  }
147
148
  }, { projectRoot: opts.projectRoot });
148
149
  }