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,67 @@
1
+ import { type PilotGateEvaluation, type PilotTaskRow } from './gate2-evaluator.js';
2
+ /** `fast-lane-norm.md` §2 numbers the risk surfaces 1..7; a value outside that is a typo, not a row. */
3
+ export declare const RISK_SURFACE_MAX = 7;
4
+ /**
5
+ * The file's own note, written by the writer so the artifact cannot be produced
6
+ * without it. Two claims it must carry, per PRD §4 and §5.3: what the evidence
7
+ * does NOT prove, and which of the two policy blocks is authoritative.
8
+ */
9
+ export declare const PILOT_GATE_NOTE: string;
10
+ export declare const LANE_CHOSEN_BY_VALUES: readonly ["user-named", "user-picked"];
11
+ export declare const OUTCOME_VALUES: readonly ["landed", "escalated", "stopped"];
12
+ export declare const HANDLING_VALUES: readonly ["refused", "escalated", "user-override-recorded", "none"];
13
+ export type PilotGateFile = {
14
+ readonly policyVersion?: string | undefined;
15
+ readonly tasks: readonly PilotTaskRow[];
16
+ };
17
+ export type ReadPilotGateResult = {
18
+ readonly kind: 'ok';
19
+ readonly path: string;
20
+ readonly gate: PilotGateFile;
21
+ } | {
22
+ readonly kind: 'missing';
23
+ readonly path: string;
24
+ } | {
25
+ readonly kind: 'invalid';
26
+ readonly path: string;
27
+ readonly message: string;
28
+ };
29
+ export type PilotTaskInput = {
30
+ readonly rid: string;
31
+ readonly sessionId: string;
32
+ readonly date: string;
33
+ readonly laneChosenBy: string;
34
+ readonly outcome: string;
35
+ readonly filesChanged: readonly string[];
36
+ readonly riskSurfacesHit: readonly number[];
37
+ readonly riskSurfaceHandling: string;
38
+ readonly rolledBack: boolean;
39
+ readonly ciRed: boolean;
40
+ readonly missedRiskSurface: boolean;
41
+ };
42
+ export declare function pilotGatePath(projectRoot: string): string;
43
+ export declare function readPilotGate(projectRoot: string): ReadPilotGateResult;
44
+ /**
45
+ * Validate one row, fail-closed, each refusal naming the rule it broke. Nothing
46
+ * is written when this returns `invalid`.
47
+ */
48
+ export declare function buildPilotTaskRow(input: PilotTaskInput): {
49
+ readonly kind: 'ok';
50
+ readonly row: PilotTaskRow;
51
+ } | {
52
+ readonly kind: 'invalid';
53
+ readonly message: string;
54
+ };
55
+ /**
56
+ * Idempotent upsert of one row, keyed by `--rid`: a repeated rid replaces that
57
+ * row in place (first-seen order preserved), a new rid is appended. The writer is
58
+ * also the only thing that can refresh `lastEvaluation` — the reader owns no file
59
+ * — which is what keeps the committed evaluation from going stale.
60
+ *
61
+ * Throws when the existing file cannot be read: clobbering unreadable evidence
62
+ * with a fresh one-row file would silently destroy rows.
63
+ */
64
+ export declare function upsertPilotTask(projectRoot: string, row: PilotTaskRow, now?: Date): {
65
+ readonly path: string;
66
+ readonly evaluation: PilotGateEvaluation;
67
+ };
@@ -0,0 +1,227 @@
1
+ // src/services/race/pilot-gate-store.ts
2
+ //
3
+ // THE ONLY I/O MODULE of the race-lane gate-2 evidence. `gate2-evaluator.ts`
4
+ // judges; this file reads and writes, and nothing else may.
5
+ //
6
+ // WHY THE EVIDENCE IS TRACKED. Gate 2 gates a switch of `skills/peaks-audit/SKILL.md`
7
+ // to "offered by default" — a tracked change, which must be judged on tracked
8
+ // evidence. If `pilot-gate.json` lived under `.peaks/_runtime/` it would be
9
+ // gitignored, the guard would read nothing on a clean CI clone, and "did the gate
10
+ // pass?" would remain a local fact rather than a repository fact.
11
+ //
12
+ // WHAT THIS FILE DOES NOT PROVE. The per-task prose traces stay gitignored
13
+ // (`.peaks/_runtime/<sessionId>/race/<rid>.md`), so the rows here were extracted
14
+ // from them and committed. Nothing in this repository can prove those rows came
15
+ // from tasks that were really run; the guard can only prove the rows, the counts,
16
+ // the verdict and the SKILL.md marker are mutually consistent.
17
+ //
18
+ // THE POLICY BLOCK IN THE FILE IS A RECORD, NOT THE AUTHORITY. The thresholds a
19
+ // verdict is computed from are `RACE_GATE2_POLICY_V1` in `gate2-policy.ts`. Were
20
+ // the file's own block the computational source, weakening it in a commit would
21
+ // launder the gate it exists to hold. The writer copies the constant into the
22
+ // block verbatim, and a reader can compare `recordedPolicyVersion` against the
23
+ // policy it was judged under.
24
+ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
25
+ import { dirname, join } from 'node:path';
26
+ import { CLI_VERSION } from 'peaks-loop-shared/version';
27
+ import { z } from 'zod';
28
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
29
+ import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
30
+ import { evaluatePilotGate } from './gate2-evaluator.js';
31
+ import { RACE_GATE2_POLICY_V1, RACE_GATE2_POLICY_VERSION } from './gate2-policy.js';
32
+ /** `fast-lane-norm.md` §2 numbers the risk surfaces 1..7; a value outside that is a typo, not a row. */
33
+ export const RISK_SURFACE_MAX = 7;
34
+ /**
35
+ * The file's own note, written by the writer so the artifact cannot be produced
36
+ * without it. Two claims it must carry, per PRD §4 and §5.3: what the evidence
37
+ * does NOT prove, and which of the two policy blocks is authoritative.
38
+ */
39
+ export const PILOT_GATE_NOTE = [
40
+ 'Gate-2 evidence for the peaks-race-code fast lane.',
41
+ 'WHY IT IS TRACKED: gate 2 gates a TRACKED change (skills/peaks-audit/SKILL.md), so it is judged on tracked evidence; under .peaks/_runtime/ it would be gitignored, and whether the gate passed would stay a local fact.',
42
+ 'WHAT IT DOES NOT PROVE: the per-task prose traces (.peaks/_runtime/<sessionId>/race/<rid>.md) are gitignored, so these rows were extracted from them and committed. Nothing in this repository can prove they came from tasks that were really run; a guard can only prove the rows, the counts, the verdict and the SKILL.md marker are mutually consistent.',
43
+ 'WHICH POLICY IS AUTHORITATIVE: src/services/race/gate2-policy.ts. The policy block below is the RECORD of what was applied, copied verbatim from that constant; a verdict is always computed from the constant, never from this file — otherwise weakening this block would launder the gate.',
44
+ 'ciRed false means no CI failure is attributed to this task, NOT that CI was green on its commit.',
45
+ 'missedRiskSurface false means no missed risk surface is known; no procedure exists yet for setting it (U-C), so it is a required value with nothing behind it.'
46
+ ].join(' ');
47
+ export const LANE_CHOSEN_BY_VALUES = ['user-named', 'user-picked'];
48
+ export const OUTCOME_VALUES = ['landed', 'escalated', 'stopped'];
49
+ export const HANDLING_VALUES = ['refused', 'escalated', 'user-override-recorded', 'none'];
50
+ /**
51
+ * One evidence row. `z.object` strips unknown keys, so an author-written
52
+ * `coreCapability: true` is ignored rather than honoured — the coverage value is
53
+ * derived (§3.2) and there is deliberately no field that can assert it.
54
+ */
55
+ const pilotTaskRowSchema = z.object({
56
+ rid: z.string().min(1),
57
+ sessionId: z.string().min(1),
58
+ date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
59
+ laneChosenBy: z.enum(LANE_CHOSEN_BY_VALUES),
60
+ outcome: z.enum(OUTCOME_VALUES),
61
+ filesChanged: z.array(z.string()),
62
+ riskSurfacesHit: z.array(z.number().int()),
63
+ riskSurfaceHandling: z.enum(HANDLING_VALUES),
64
+ rolledBack: z.boolean(),
65
+ ciRed: z.boolean(),
66
+ missedRiskSurface: z.boolean()
67
+ });
68
+ /**
69
+ * The reader needs what it judges with and nothing else. `tasks` is required —
70
+ * a file whose rows cannot be read is not a verdict, it is unreadable evidence.
71
+ * `policyVersion` is read for the report. The rest of the artifact
72
+ * (`evaluatorVersion`, `updatedAt`, `policy`, `lastEvaluation`) is the writer's
73
+ * record and is deliberately NOT a precondition for judging: PRD §3 versions the
74
+ * policy precisely so that a file written under a different version stays
75
+ * readable instead of turning into a parse error.
76
+ */
77
+ const pilotGateFileSchema = z.object({
78
+ policyVersion: z.string().optional(),
79
+ tasks: z.array(pilotTaskRowSchema)
80
+ });
81
+ export function pilotGatePath(projectRoot) {
82
+ return join(projectRoot, '.peaks', 'race', 'pilot-gate.json');
83
+ }
84
+ export function readPilotGate(projectRoot) {
85
+ const path = pilotGatePath(projectRoot);
86
+ if (!existsSync(path))
87
+ return { kind: 'missing', path };
88
+ let raw;
89
+ try {
90
+ raw = JSON.parse(readFileSync(path, 'utf8'));
91
+ }
92
+ catch (error) {
93
+ return {
94
+ kind: 'invalid',
95
+ path,
96
+ message: error instanceof Error ? error.message : String(error)
97
+ };
98
+ }
99
+ const parsed = pilotGateFileSchema.safeParse(raw);
100
+ if (!parsed.success) {
101
+ return { kind: 'invalid', path, message: describeIssues(parsed.error) };
102
+ }
103
+ return { kind: 'ok', path, gate: parsed.data };
104
+ }
105
+ function describeIssues(error) {
106
+ return error.issues
107
+ .map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`)
108
+ .join('; ');
109
+ }
110
+ /** Backslashes are normalized rather than refused: a path is a path on either shell. */
111
+ function normalizeFiles(files) {
112
+ const normalized = [];
113
+ for (const file of files) {
114
+ const path = file.replace(/\\/g, '/');
115
+ if (isUnsafePathInput(path)) {
116
+ return {
117
+ ok: false,
118
+ message: `--file must be repository-relative, got ${JSON.stringify(file)}`
119
+ };
120
+ }
121
+ normalized.push(path);
122
+ }
123
+ return { ok: true, files: normalized };
124
+ }
125
+ /**
126
+ * The one rule no schema can state: a hit with no disposition is a MISSING
127
+ * record, and accepting it silently would make the coverage derivation credit
128
+ * nothing and say nothing.
129
+ */
130
+ function checkRiskSurfaces(surfaces, handling) {
131
+ for (const surface of surfaces) {
132
+ if (!Number.isInteger(surface) || surface < 1 || surface > RISK_SURFACE_MAX) {
133
+ return `--risk-surface must be an integer 1..${RISK_SURFACE_MAX}, got ${surface}`;
134
+ }
135
+ }
136
+ if (surfaces.length > 0 && handling === 'none') {
137
+ return '--risk-surface-handling cannot be "none" when --risk-surface is present: a hit with no disposition is a missing record, not a clean row';
138
+ }
139
+ return null;
140
+ }
141
+ /**
142
+ * Validate one row, fail-closed, each refusal naming the rule it broke. Nothing
143
+ * is written when this returns `invalid`.
144
+ */
145
+ export function buildPilotTaskRow(input) {
146
+ const invalid = (message) => ({
147
+ kind: 'invalid',
148
+ message
149
+ });
150
+ // The rule is the id PATTERN, not a prefix: a name may key a row, it may not
151
+ // veto one. Snapshot of `.peaks/_runtime/*/rd/requests/` on 2026-10-13 — 97
152
+ // ids, 39 prefixed, 58 not — so the test this replaces refused 58 of 97 of
153
+ // what the repository mints. `REQUEST_ID_PATTERN` is imported rather than
154
+ // re-spelled so this site cannot drift, and it is STRICTER than that test:
155
+ // the old one accepted `rid-/abs`, this one refuses it.
156
+ if (!REQUEST_ID_PATTERN.test(input.rid)) {
157
+ return invalid(`--rid must match ${REQUEST_ID_PATTERN.source}, got ${JSON.stringify(input.rid)}`);
158
+ }
159
+ // `isUnsafePathInput` is the predicate `guardRuntimeSegment` is built on; the
160
+ // ids and the file paths are checked BEFORE anything is written. THIS RID ARM
161
+ // IS UNREACHABLE-TRUE: every string the pattern admits is one `[A-Za-z0-9._-]`
162
+ // segment starting alphanumeric, so it always passes, and it is KEPT as
163
+ // defence in depth — the invariant, not the test, makes the write safe. The
164
+ // SESSION arm below is the live one; `../../PWNED` reaches and is refused by it.
165
+ if (isUnsafePathInput(input.rid)) {
166
+ return invalid(`--rid must be a single safe path segment, got ${JSON.stringify(input.rid)}`);
167
+ }
168
+ if (isUnsafePathInput(input.sessionId)) {
169
+ return invalid(`--session-id must be a single safe path segment, got ${JSON.stringify(input.sessionId)}`);
170
+ }
171
+ const files = normalizeFiles(input.filesChanged);
172
+ if (!files.ok)
173
+ return invalid(files.message);
174
+ const surfaceProblem = checkRiskSurfaces(input.riskSurfacesHit, input.riskSurfaceHandling);
175
+ if (surfaceProblem !== null)
176
+ return invalid(surfaceProblem);
177
+ const parsed = pilotTaskRowSchema.safeParse({ ...input, filesChanged: files.files });
178
+ if (!parsed.success)
179
+ return invalid(describeIssues(parsed.error));
180
+ return { kind: 'ok', row: parsed.data };
181
+ }
182
+ /**
183
+ * Idempotent upsert of one row, keyed by `--rid`: a repeated rid replaces that
184
+ * row in place (first-seen order preserved), a new rid is appended. The writer is
185
+ * also the only thing that can refresh `lastEvaluation` — the reader owns no file
186
+ * — which is what keeps the committed evaluation from going stale.
187
+ *
188
+ * Throws when the existing file cannot be read: clobbering unreadable evidence
189
+ * with a fresh one-row file would silently destroy rows.
190
+ */
191
+ export function upsertPilotTask(projectRoot, row, now = new Date()) {
192
+ const existing = readPilotGate(projectRoot);
193
+ if (existing.kind === 'invalid') {
194
+ throw new Error(`PILOT_GATE_EVIDENCE_INVALID: ${existing.path}: ${existing.message}`);
195
+ }
196
+ const previousTasks = existing.kind === 'ok' ? existing.gate.tasks : [];
197
+ const index = previousTasks.findIndex((task) => task.rid === row.rid);
198
+ const tasks = index === -1
199
+ ? [...previousTasks, row]
200
+ : previousTasks.map((task, at) => (at === index ? row : task));
201
+ const evaluation = evaluatePilotGate(tasks, RACE_GATE2_POLICY_V1);
202
+ writePilotGate(projectRoot, tasks, evaluation, now);
203
+ return { path: pilotGatePath(projectRoot), evaluation };
204
+ }
205
+ /**
206
+ * The full artifact the writer owns. The `policy` block is copied from the code
207
+ * constant verbatim — it records what was applied, and a test asserts the two are
208
+ * byte-equal so the record cannot drift from the source.
209
+ */
210
+ function writePilotGate(projectRoot, tasks, evaluation, now) {
211
+ const path = pilotGatePath(projectRoot);
212
+ const artifact = {
213
+ note: PILOT_GATE_NOTE,
214
+ policyVersion: RACE_GATE2_POLICY_VERSION,
215
+ evaluatorVersion: CLI_VERSION,
216
+ updatedAt: now.toISOString(),
217
+ policy: RACE_GATE2_POLICY_V1,
218
+ tasks,
219
+ lastEvaluation: { ...evaluation, evaluatedAt: now.toISOString() }
220
+ };
221
+ // Temp file in the same directory, then rename: a crash mid-write leaves the
222
+ // previous valid evidence intact rather than a truncated one.
223
+ mkdirSync(dirname(path), { recursive: true });
224
+ const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
225
+ writeFileSync(tmp, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
226
+ renameSync(tmp, path);
227
+ }
@@ -0,0 +1,33 @@
1
+ /** A git read the scan needs could not be completed. Thrown, never returned:
2
+ * the alternative is an empty file list that reads as "nothing changed". */
3
+ export declare class GitReadFailedError extends Error {
4
+ readonly code = "FILE_SIZE_GIT_READ_FAILED";
5
+ constructor(what: string, projectRoot: string, detail: string);
6
+ }
7
+ export type ChangedFiles = {
8
+ /** Paths to measure in the working tree: Added/Modified entries plus rename
9
+ * targets. Deletions are omitted — they have no body to measure. */
10
+ paths: string[];
11
+ /** The path `file`'s baseline size must be read from: itself, or the name it
12
+ * had at `baseRef` before a rename. */
13
+ baselinePathFor(file: string): string;
14
+ };
15
+ /**
16
+ * One git enumeration for both readers that need the change set: the declared-
17
+ * type rule judges `changedPaths` (deletions included), and the size scan
18
+ * measures `changedFiles` (the A/M/R/untracked subset). Two spawns total,
19
+ * `git diff` + `git ls-files`, never one pair per reader.
20
+ */
21
+ export type GitChangeSet = {
22
+ changedPaths: string[];
23
+ changedFiles: ChangedFiles;
24
+ };
25
+ export declare function readGitChangeSet(projectRoot: string, baseRef: string, only?: readonly string[]): GitChangeSet;
26
+ /**
27
+ * The measurable subset alone. Kept as the size scan's entry point; the
28
+ * transition gate calls `readGitChangeSet` so the type rule shares the read.
29
+ */
30
+ export declare function readChangedFiles(projectRoot: string, baseRef: string, only?: readonly string[]): ChangedFiles;
31
+ /** The file's raw-line count AT `baseRef`, or `null` when the ref has no such
32
+ * path — i.e. the change ADDED the file and it is over the cap by creation. */
33
+ export declare function readBaseLineCount(projectRoot: string, baseRef: string, file: string): number | null;
@@ -0,0 +1,173 @@
1
+ // src/services/scan/file-size-baseline.ts
2
+ //
3
+ // The git side of the diff-scoped file-size scan: WHICH files changed against a
4
+ // base ref, and HOW BIG each was at that ref. Together they make the scan a
5
+ // RATCHET — a file that is over its cap but no larger than its own state at that
6
+ // ref is accepted, and only growth past the cap is refused. Same rule as the
7
+ // commit gate's "a file you touch may not be WORSE than it was"
8
+ // (`.husky/peaks-gate.mjs`).
9
+ //
10
+ // FAIL-CLOSED ON BOTH GIT READS. The enumeration and the size probe both name
11
+ // their failure instead of swallowing it: a ratchet whose input list can
12
+ // silently become empty is not a ratchet, and `catch { return [] }` cannot tell
13
+ // "git refused to enumerate" from "nothing changed".
14
+ //
15
+ // RENAMES ARE JUDGED, NOT DROPPED. A rename is enumerated as `R` and compared
16
+ // against the OLD path's size at `baseRef`, so a pure rename passes and a
17
+ // rename that grows is refused naming the growth. The `--diff-filter=AM`
18
+ // spelling this replaced excluded `R` by accident — a file could grow past its
19
+ // cap and stay invisible to the scan simply by being renamed in the same
20
+ // commit.
21
+ //
22
+ // KNOWN, RECORDED, NOT FIXED — a DELETION is invisible: `D` entries are dropped
23
+ // before the measurement, and that is left as it is because a deletion cannot
24
+ // grow. It is a documentation matter, not a hole in the ratchet.
25
+ //
26
+ // KNOWN, RECORDED, NOT FIXED — subprocess cost is `2 + 2K` git spawns, where K
27
+ // is the changed files that are OVER their cap (one `cat-file -e` plus one
28
+ // `show` each, inside the scan's `lines > cap` branch; the 2 are the
29
+ // enumerations above). It is linear in OVER-CAP changed files, not in changed
30
+ // files: 10 changed with 0 over spawns 2, with 2 over spawns 6, with 5 over
31
+ // spawns 12; 40 changed with 3 over spawns 8 and with 40 over spawns 82. At
32
+ // roughly 58 ms per process on the measured host that is 0.8 s at K=5 and 4.7 s
33
+ // at K=40, paid once per slice on a human-run command with two call sites.
34
+ // Batching every baseline read through one `git cat-file --batch` on stdin is
35
+ // the known fix if the many-over-cap case ever becomes real; it is not
36
+ // warranted at these numbers.
37
+ //
38
+ // Split out of `file-size-scan.ts`. That file was 237 raw lines at the split
39
+ // (not "at its cap"): the point is that this logic did not fit under 300 there,
40
+ // and the scan now depends on this module rather than on a hand-rolled list.
41
+ // This module's own name matches the `file-size` pattern the walk-based
42
+ // policy-wiring rule (`policyWiringFindings` in
43
+ // `tests/unit/standards/_file-size-cap-scan.ts`, asserted by
44
+ // `tests/unit/standards/file-size-cap.test.ts`) requires to import
45
+ // `file-size-policy.ts`; that test's literal fixtures name `file-size-scan.ts`,
46
+ // not this file.
47
+ import { execFileSync, spawnSync } from 'node:child_process';
48
+ import { countRawLines, normalizePolicyPath } from './file-size-policy.js';
49
+ /** A git read the scan needs could not be completed. Thrown, never returned:
50
+ * the alternative is an empty file list that reads as "nothing changed". */
51
+ export class GitReadFailedError extends Error {
52
+ code = 'FILE_SIZE_GIT_READ_FAILED';
53
+ constructor(what, projectRoot, detail) {
54
+ super(`File-size scan refused: ${what} could not be read from git in ${projectRoot} ` +
55
+ `(${detail}). A git failure is not "nothing changed"; fix the ref/path, or pass ` +
56
+ 'a `baseRef` that resolves.');
57
+ this.name = 'GitReadFailedError';
58
+ }
59
+ }
60
+ function gitNul(projectRoot, args) {
61
+ let raw;
62
+ try {
63
+ raw = execFileSync('git', ['-C', projectRoot, ...args], {
64
+ windowsHide: true
65
+ });
66
+ }
67
+ catch (error) {
68
+ const detail = error instanceof Error ? (error.message.split('\n')[0] ?? '') : String(error);
69
+ throw new GitReadFailedError(`\`git ${args.join(' ')}\``, projectRoot, detail);
70
+ }
71
+ // `-z` suppresses C-quoting (core.quotePath), so a non-ASCII name arrives as
72
+ // the real path rather than `"src/\303\251.ts"`; NUL is the only separator.
73
+ return raw
74
+ .toString('utf8')
75
+ .split('\0')
76
+ .filter((entry) => entry.length > 0);
77
+ }
78
+ /**
79
+ * The caller's list, intersected with what git reports — or the whole change set when
80
+ * the caller named none. Compared in the policy's POSIX spelling, because a
81
+ * Windows-native caller path and a git-reported one spell the same file differently.
82
+ *
83
+ * INTERSECTION, NOT POPULATION. The commit hook is handed the STAGED paths by
84
+ * lint-staged, so it knows its set and the set is narrower than the working tree: a
85
+ * modification nobody staged is not part of that commit, and measuring it would block
86
+ * the commit over a file it was never asked about. A named path git does not report as
87
+ * changed is therefore skipped, never measured — this narrows; it cannot widen.
88
+ */
89
+ function restrictedTo(all, only) {
90
+ if (only === undefined)
91
+ return [...all];
92
+ const wanted = new Set(only.map(normalizePolicyPath));
93
+ return all.filter((file) => wanted.has(normalizePolicyPath(file)));
94
+ }
95
+ /** One `--name-status -z` entry into the accumulator. Extracted because the
96
+ * inline form pushed `readGitChangeSet` past the complexity cap. */
97
+ function appendEntry(status, fields, acc) {
98
+ if (status.startsWith('R') || status.startsWith('C')) {
99
+ const from = fields[0];
100
+ const to = fields[1];
101
+ if (from === undefined || to === undefined)
102
+ return;
103
+ acc.changedPaths.push(...(status.startsWith('R') ? [from] : []), to);
104
+ acc.measurable.push(to);
105
+ acc.renameSources.set(to, from);
106
+ return;
107
+ }
108
+ const path = fields[0];
109
+ if (path === undefined)
110
+ return;
111
+ acc.changedPaths.push(path);
112
+ if (status.startsWith('A') || status.startsWith('M'))
113
+ acc.measurable.push(path);
114
+ }
115
+ export function readGitChangeSet(projectRoot, baseRef, only) {
116
+ const acc = { changedPaths: [], measurable: [], renameSources: new Map() };
117
+ const tokens = gitNul(projectRoot, [
118
+ 'diff',
119
+ '--name-status',
120
+ '--relative',
121
+ '-z',
122
+ '--end-of-options',
123
+ baseRef
124
+ ]);
125
+ for (let i = 0; i < tokens.length;) {
126
+ const status = tokens[i++] ?? '';
127
+ const count = status.startsWith('R') || status.startsWith('C') ? 2 : 1;
128
+ appendEntry(status, tokens.slice(i, i + count), acc);
129
+ i += count;
130
+ }
131
+ const untracked = gitNul(projectRoot, ['ls-files', '--others', '--exclude-standard', '-z']);
132
+ return {
133
+ changedPaths: Array.from(new Set([...acc.changedPaths, ...untracked])),
134
+ changedFiles: {
135
+ paths: restrictedTo(Array.from(new Set([...acc.measurable, ...untracked])), only),
136
+ baselinePathFor: (file) => acc.renameSources.get(file) ?? file
137
+ }
138
+ };
139
+ }
140
+ /**
141
+ * The measurable subset alone. Kept as the size scan's entry point; the
142
+ * transition gate calls `readGitChangeSet` so the type rule shares the read.
143
+ */
144
+ export function readChangedFiles(projectRoot, baseRef, only) {
145
+ return readGitChangeSet(projectRoot, baseRef, only).changedFiles;
146
+ }
147
+ /**
148
+ * Whether `git cat-file -e` could resolve `<baseRef>:<file>`, i.e. whether the
149
+ * probe EXITED ZERO. What a non-zero exit actually measures is wider than "the
150
+ * ref has no such path": a bad or unreadable ref (a misspelled name, or `HEAD~1`
151
+ * on a root commit) and any other git failure exit non-zero too and are read
152
+ * identically. That conflation is fail-closed — no baseline means
153
+ * `previousLines: null`, which the scan reads as "created over the cap" and
154
+ * refuses. Stated so the next reader does not take the narrow reading.
155
+ */
156
+ function pathExistsAtRef(projectRoot, baseRef, file) {
157
+ const probe = spawnSync('git', ['-C', projectRoot, 'cat-file', '-e', `${baseRef}:${file}`], {
158
+ stdio: 'ignore',
159
+ windowsHide: true
160
+ });
161
+ return probe.status === 0;
162
+ }
163
+ /** The file's raw-line count AT `baseRef`, or `null` when the ref has no such
164
+ * path — i.e. the change ADDED the file and it is over the cap by creation. */
165
+ export function readBaseLineCount(projectRoot, baseRef, file) {
166
+ if (!pathExistsAtRef(projectRoot, baseRef, file)) {
167
+ return null;
168
+ }
169
+ return countRawLines(execFileSync('git', ['-C', projectRoot, 'show', `${baseRef}:${file}`], {
170
+ encoding: 'utf8',
171
+ windowsHide: true
172
+ }));
173
+ }
@@ -1,3 +1,4 @@
1
+ import { type ChangedFiles } from './file-size-baseline.js';
1
2
  /**
2
3
  * Paths exempt from the file-size cap. The cap is Karpathy's "Simplicity
3
4
  * First": it exists to make a human *simplify* an over-long file. A path is
@@ -29,6 +30,17 @@ export type FileSizeViolation = {
29
30
  /** The cap this file was measured against, resolved per path by the policy
30
31
  * module (300 raw lines; 500 under root `tests/`), or the caller's override. */
31
32
  cap: number;
33
+ /**
34
+ * The file's raw-line count at `baseRef`, or `null` when the file did not
35
+ * exist there — i.e. THIS change CREATED it over the cap.
36
+ *
37
+ * A changed file that is over its cap but NOT larger than its own state at
38
+ * `baseRef` is not a violation: the whole-tree `fileSizeOverCap` ratchet
39
+ * already accepts it as a standing quantity, so touching it must stay legal.
40
+ * Only growth travels here — including growth that a rename carried along,
41
+ * which is measured against the pre-rename path.
42
+ */
43
+ previousLines: number | null;
32
44
  };
33
45
  export type FileSizeScanResult = {
34
46
  ok: boolean;
@@ -41,10 +53,17 @@ export type FileSizeScanResult = {
41
53
  * records). Reported so the exemption is auditable rather than a silent
42
54
  * skip. */
43
55
  exemptFiles: string[];
44
- /** Files that appeared in `git diff` but no longer exist on disk (e.g.
45
- * deleted in the working tree). Pre-#015 the scan crashed on these via
46
- * ENOENT; now they are reported here as informational data. */
56
+ /** Files that appeared in `git diff` but no longer exist on disk. Pre-#015
57
+ * the scan crashed on these via ENOENT; now they are reported, not counted. */
47
58
  deletedFiles: string[];
59
+ /**
60
+ * Changed files that ARE over their cap right now but this change did not
61
+ * enlarge (they were already that large at `baseRef`, or larger). They
62
+ * are NOT violations — the ratchet accepts them — but they are named here
63
+ * rather than dropped, so "0 violations" cannot mean "nothing was over the
64
+ * cap"; the same reason `exemptFiles` and `outOfScopeFiles` exist.
65
+ */
66
+ acceptedOverCapFiles: string[];
48
67
  /** Changed files the file-size policy does not measure at all: outside its
49
68
  * four scope directories, or with an extension it does not count. Reported
50
69
  * rather than silently skipped, for the same reason `exemptFiles` is.
@@ -74,5 +93,18 @@ export type FileSizeScanOptions = {
74
93
  * the policy is the default, this option only overrides it.
75
94
  */
76
95
  threshold?: number;
96
+ /**
97
+ * The caller's own list, when it has one — the commit hook is handed the STAGED
98
+ * paths by lint-staged. It RESTRICTS the git change set (a path git does not
99
+ * report as changed is skipped, never measured) and never widens it; omitted,
100
+ * git alone decides the population.
101
+ */
102
+ files?: readonly string[];
103
+ /**
104
+ * A change set the caller already read (the transition gate shares one read
105
+ * with the declared-type rule). When present, NO git enumeration runs here;
106
+ * `files` restriction is the caller's responsibility.
107
+ */
108
+ changedFiles?: ChangedFiles;
77
109
  };
78
110
  export declare function scanFileSize(options: FileSizeScanOptions): FileSizeScanResult;