rungate 0.8.2 → 0.8.4

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 (74) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/BunTestPathGuard.hook.ts +106 -0
  9. package/hooks/DocHygiene.hook.ts +2 -1
  10. package/hooks/GateResultProtection.hook.ts +28 -7
  11. package/hooks/HookCurrency.hook.ts +48 -1
  12. package/hooks/TopLevelCdGuard.hook.ts +38 -6
  13. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  14. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  15. package/lib/ai-review-jury.ts +725 -0
  16. package/lib/ai-review-rounds.ts +791 -4
  17. package/lib/ai-review-unmeasured.ts +361 -0
  18. package/lib/bash-write-guard.ts +1235 -102
  19. package/lib/bun-test-paths.ts +253 -0
  20. package/lib/cli-commands.ts +252 -11
  21. package/lib/closing-reference-audit.ts +163 -0
  22. package/lib/conformity.ts +17 -1
  23. package/lib/create-sc.ts +45 -12
  24. package/lib/derived-spec.ts +206 -0
  25. package/lib/file-claims.ts +335 -0
  26. package/lib/finding-arbiter.ts +502 -28
  27. package/lib/finding-jury.ts +61 -5
  28. package/lib/finding-pr-routing.ts +333 -0
  29. package/lib/frontmatter.ts +16 -0
  30. package/lib/gate-check-audit.ts +646 -0
  31. package/lib/generators/agents-md.ts +29 -0
  32. package/lib/github.ts +112 -7
  33. package/lib/hook-tree-currency.ts +494 -0
  34. package/lib/issue-closure-audit.ts +161 -14
  35. package/lib/issue-create-override.ts +53 -3
  36. package/lib/issue-filing-gate.ts +1073 -76
  37. package/lib/local-review-rounds.ts +523 -0
  38. package/lib/organize.ts +21 -1
  39. package/lib/project-state-shape.ts +56 -5
  40. package/lib/release-preflight.ts +90 -1
  41. package/lib/repo-path.ts +94 -0
  42. package/lib/report-provenance.ts +218 -3
  43. package/lib/risk-tier.ts +302 -0
  44. package/lib/rounds-to-pass.ts +274 -0
  45. package/lib/rule-row-drift.ts +199 -0
  46. package/lib/sc-claim-forms.ts +33 -5
  47. package/lib/sc-guard.ts +11 -1
  48. package/lib/sc-id-cross-tree.ts +17 -2
  49. package/lib/sc-ids.ts +71 -6
  50. package/lib/sc-reservations.ts +158 -14
  51. package/lib/scaffold/ai-review-findings.ts +1369 -27
  52. package/lib/scaffold/ai-review-step.ts +4095 -119
  53. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  54. package/lib/scaffold/owned-files.ts +14 -0
  55. package/lib/scaffold/steps.ts +100 -9
  56. package/lib/scratch-roots.ts +93 -3
  57. package/lib/spec-updater.ts +22 -2
  58. package/lib/spec-write-ast.ts +728 -0
  59. package/lib/spec-write-sweep.ts +470 -0
  60. package/lib/test-suite-lock.ts +127 -13
  61. package/lib/ts-ast.ts +26 -0
  62. package/lib/validators/spec-validators.ts +36 -7
  63. package/lib/write-spec.ts +138 -0
  64. package/package.json +2 -1
  65. package/scripts/ai-review-findings.ts +41 -1
  66. package/scripts/arbitrate-finding.ts +330 -12
  67. package/scripts/audit-specs.ts +225 -24
  68. package/scripts/convert-spec.ts +7 -2
  69. package/scripts/create-sc.ts +14 -2
  70. package/scripts/create-spec.ts +5 -2
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/record-ai-review-unmeasured.ts +370 -0
  73. package/scripts/split-spec.ts +17 -4
  74. package/scripts/sync-sc-status.ts +14 -2
@@ -28,12 +28,44 @@
28
28
  * `.claude/rungate/hooks.json`, the current-state table in
29
29
  * `specs/HOOK-ARCHITECTURE-SPEC.md`, and `.claude/settings.json`.
30
30
  *
31
- * It is registered at PROJECT scope. `${CLAUDE_PROJECT_DIR}` resolves to the
32
- * worktree a session is in, every worktree carries the committed
33
- * `.claude/settings.json`, and worktree isolation — the thing a stray `cd`
34
- * breaks — is a harness concern. Machine-wide registration lives in
35
- * `~/.claude/settings.json`, which no PR can carry and no test here can
36
- * honestly assert (`test/hook-registration-reconciler.test.ts`).
31
+ * ## NOT LIVE. User scope since #1578, and why the first classification was wrong
32
+ *
33
+ * #992 registered this at PROJECT scope, reasoning that `${CLAUDE_PROJECT_DIR}`
34
+ * resolves to the worktree a session is in, that every worktree carries the
35
+ * committed `.claude/settings.json`, and that worktree isolation is a harness
36
+ * concern. **The second clause is true and the conclusion does not follow.**
37
+ *
38
+ * Measured on 2026-10-24 in a worktree whose committed `.claude/settings.json`
39
+ * registered this hook: three bare `cd` calls were NOT refused, while a
40
+ * user-scoped COMP-7 refusal fired on the same `Bash` matcher in the same
41
+ * session. The decider returns `block` when invoked by hand from that cwd;
42
+ * `isHarnessProject()` resolves; `RUNGATE_CD_GUARD` is unset. The worktree
43
+ * carries the file. The session does not load it. So this hook has been
44
+ * green, registered, tested and INERT since #1050 — which is #1578, and is
45
+ * the purest form of *absence of evidence recorded as clean*.
46
+ *
47
+ * The scope follows from what a hook PROTECTS. This one protects the
48
+ * SESSION's primary working directory — the directory `isolation: 'worktree'`
49
+ * resolves against — and a session may be rooted anywhere while working on
50
+ * this repo, including via an added working directory. That is machine-wide
51
+ * state, so SC-518 governs it: machine-wide hooks live in user settings,
52
+ * because project settings only load for sessions started in that directory.
53
+ * It was misclassified from the start.
54
+ *
55
+ * Two consequences, both deliberate:
56
+ *
57
+ * - The repo no longer registers it in `.claude/settings.json`. SC-518 says
58
+ * the two scopes are not de-duplicated, so leaving it there would fire the
59
+ * hook twice once the real registration exists.
60
+ * - `test/hook-registration-reconciler.test.ts` now reports it UNMEASURED on
61
+ * every run, and that reading is the deliverable rather than a loss. A test
62
+ * saying *this cannot be verified here* beats one reporting a registration
63
+ * nobody loads as satisfied.
64
+ *
65
+ * **Live registration in `~/.claude/settings.json` is a human action, is
66
+ * outside every agent's permitted scope, and is STILL PENDING.** Merging this
67
+ * does not switch the guard on. Until a human does that, this hook refuses
68
+ * nothing.
37
69
  *
38
70
  * ## The rung, and what #1040 left behind
39
71
  *
@@ -102,21 +102,38 @@ async function main() {
102
102
  // inside one phase would leave the intake rate untouched.
103
103
  const gate = await filingGate(cmd, { projectRoot: process.cwd() });
104
104
  const unrecorded = gate.rows.filter(row => !recordAdjudication(row)).length;
105
+ // A refusal says the override "is recorded beside the refusal it waived".
106
+ // When the write failed that sentence is false, and a security control
107
+ // asserting a guarantee it is not providing is worse than one that says
108
+ // nothing — so the unrecorded notice rides ON the refusal rather than
109
+ // being skipped by the early exit, which is where it used to go.
110
+ const unrecordedNote =
111
+ unrecorded > 0
112
+ ? `[FindingArbiter] ${unrecorded} adjudication(s) could NOT be written to ${ledgerPath()}, ` +
113
+ "so they are not in the population that prices this gate and any claim below that " +
114
+ "a decision was recorded does not hold for them."
115
+ : null;
105
116
 
117
+ // `gate.note` rides on the refusal for the same reason `unrecordedNote`
118
+ // does, and it was missed when that one was fixed: a `decision: "block"`
119
+ // payload has ONE text field, so anything not folded into `reason` here is
120
+ // discarded by the early exit and never reaches the agent.
121
+ //
122
+ // The note that mattered is the corpus-drop one. A refusal computed against
123
+ // a tracker three issues short is exactly where the shortfall needs saying
124
+ // — the agent is being told its finding is already filed, by a comparison
125
+ // that did not read the whole tracker — and that was the one path on which
126
+ // it was silently dropped. `FG-60` is the case; it went red here first.
106
127
  if (gate.refusal !== null) {
107
- console.log(JSON.stringify({ decision: "block", reason: gate.refusal }));
128
+ const riders = [gate.note, unrecordedNote].filter((n): n is string => n !== null);
129
+ const reason = [gate.refusal, ...riders].join("\n\n");
130
+ console.log(JSON.stringify({ decision: "block", reason }));
108
131
  process.exit(0);
109
132
  }
110
133
  // systemMessage and not stderr: stderr from a hook that exits 0 is not
111
134
  // shown. An UNMEASURED nobody sees is a silent pass, which is the one thing
112
135
  // lib/issue-filing-gate.ts's header says this must not become.
113
- const notes = [
114
- gate.note,
115
- unrecorded > 0
116
- ? `[FindingArbiter] ${unrecorded} adjudication(s) could not be written to ${ledgerPath()}, ` +
117
- `so this filing is not in the population that prices the gate.`
118
- : null,
119
- ].filter((n): n is string => n !== null);
136
+ const notes = [gate.note, unrecordedNote].filter((n): n is string => n !== null);
120
137
  if (notes.length > 0) console.log(JSON.stringify({ systemMessage: notes.join("\n\n") }));
121
138
  process.exit(0);
122
139
  }
@@ -19,12 +19,22 @@
19
19
  * - `GateResultProtection` is authoritative for **what a permitted write may
20
20
  * contain** — forged, erased or changed gate results, and `phase` DONE.
21
21
  *
22
- * Neither subsumes the other. THIS hook is the one that ships
23
- * (`deployToConsumers: true`); the specific guard is OPT-IN and a scaffolded
24
- * consumer does not get it. So on a consumer tree this is the ONLY guard on
25
- * the artifact — which is why its matcher being case-SENSITIVE while the
26
- * specific guard's is case-folded (#1184) is a consumer-reachable gap and not
27
- * a tidiness question.
22
+ * THIS hook is the one that ships (`deployToConsumers: true`); the specific
23
+ * guard is OPT-IN and a scaffolded consumer does not get it. So on a consumer
24
+ * tree this is the ONLY guard on the artifact, and that is why its matcher
25
+ * being case-SENSITIVE while the specific guard's was case-folded (#1184) was
26
+ * a consumer-reachable gap and not a tidiness question. #1211 closed it: the
27
+ * matcher below case-folds, so the two predicates now agree on WHICH paths are
28
+ * the artifact and differ only in reach — `.includes()` here against
29
+ * `.endsWith()` there.
30
+ *
31
+ * The specific guard's refusals are therefore a SUBSET of this hook's. That is
32
+ * the safe direction and it is asserted, not assumed: this hook refusing every
33
+ * Write/Edit of the artifact means a consumer tree is covered for the question
34
+ * "may a tool call write this at all", which is the only question a consumer
35
+ * tree has a guard for. Subsumed is not dead — the two do not ship to the same
36
+ * trees, and the specific guard's refusal messages name the forgery while this
37
+ * one names the sanctioned writer.
28
38
  *
29
39
  * The contract is executed, not described:
30
40
  * `test/workflow-state-write-contract.test.ts` runs both hooks over one corpus
@@ -47,7 +57,14 @@ async function main() {
47
57
  // Write tool uses file_path; Edit tool uses file_path
48
58
  const path = (toolInput.file_path as string) || (toolInput.path as string) || '';
49
59
 
50
- if (!path.includes('workflow-state.json')) process.exit(0);
60
+ // Case-FOLDED (#1211). `WORKFLOW-STATE.JSON` and `workflow-state.json` are one
61
+ // file on a case-insensitive filesystem — measured in #1184, which closed this
62
+ // in GateResultProtection and never carried the fix here. This is the guard
63
+ // that ships, so the uppercase spelling was reaching a consumer's disk with no
64
+ // guard at all. The population the fold newly claims is enumerated and bounded
65
+ // in test/workflow-state-guard-case.test.ts; it is case-variants of this name
66
+ // and nothing else.
67
+ if (!path.toLowerCase().includes('workflow-state.json')) process.exit(0);
51
68
 
52
69
  // Block the write
53
70
  const reason = [