rungate 0.8.2 → 0.8.3

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 (63) 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/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -8,21 +8,47 @@
8
8
  *
9
9
  * Thin CLI consumer — core logic exported for testing.
10
10
  */
11
- import { readFileSync, writeFileSync, readdirSync, existsSync } from "fs";
11
+ import { readFileSync, writeFileSync, existsSync } from "fs";
12
12
  import { join, dirname } from "path";
13
13
  import { fileURLToPath } from "url";
14
14
  import {
15
15
  parseFrontmatter,
16
16
  matchPattern,
17
17
  isBehavioralSC,
18
- type ParsedSC,
18
+ type ExtractedSC,
19
19
  } from "../lib/conformity";
20
+ import { parseScDeclarations } from "../lib/sc-ids";
21
+ import { collectSpecFiles } from "../lib/spec-files";
22
+ import {
23
+ mayWrite,
24
+ readDerivedDeclaration,
25
+ skipLine,
26
+ type DerivedReading,
27
+ } from "../lib/derived-spec";
20
28
 
21
29
  // ── Types ─────────────────────────────────────────────────────
22
30
 
31
+ /**
32
+ * `total` is EVERY criterion the spec declares. `ticked` is how many of those
33
+ * are already done, and `matched`/`unmatched`/`behavioral` partition the
34
+ * UNTICKED ones only, so:
35
+ *
36
+ * total === ticked + matched + unmatched + behavioral
37
+ *
38
+ * The split is deliberate rather than incidental. Those three answer "what
39
+ * open work can the conformity engine bind?", which is a question about
40
+ * criteria nobody has satisfied yet. `unmatched` feeds `strictUnmatched`, the
41
+ * exit code and the `--fix` candidate set, so folding 1,443 ticked criteria
42
+ * into it would turn a number that means "open work the engine cannot bind"
43
+ * into one that means nothing. Whether a TICKED criterion is covered is a
44
+ * different question with a different owner — `uncoveredTickedScs` in
45
+ * `lib/sc-cover.ts`.
46
+ */
23
47
  export interface SpecAuditResult {
24
48
  specFile: string;
25
49
  total: number;
50
+ /** Declared `- [x]`. Reported, and never a rewrite candidate. */
51
+ ticked: number;
26
52
  matched: number;
27
53
  unmatched: number;
28
54
  behavioral: number;
@@ -54,14 +80,37 @@ export interface RewriteEntry {
54
80
  kept?: string;
55
81
  }
56
82
 
83
+ /**
84
+ * A spec `--fix` declined to write because a generator owns it (#1286).
85
+ *
86
+ * Separate from `RewriteEntry.kept`, which records a CRITERION left alone
87
+ * inside a file that was still written. This records a FILE that was not
88
+ * opened for writing at all, so a caller cannot report it as `UPDATED:`.
89
+ */
90
+ export interface SkippedSpec {
91
+ specFile: string;
92
+ reading: DerivedReading;
93
+ /** The one-line refusal, naming the file and why. */
94
+ message: string;
95
+ /** How many criteria would have been edited had the file been writable. */
96
+ wouldHaveEdited: number;
97
+ }
98
+
57
99
  export interface AuditResult {
58
100
  specs: SpecAuditResult[];
59
101
  totalSCs: number;
102
+ totalTicked: number;
60
103
  totalMatched: number;
61
104
  totalUnmatched: number;
62
105
  totalBehavioral: number;
63
106
  strictUnmatched: number;
64
107
  rewrites?: RewriteEntry[];
108
+ /**
109
+ * Always present in fix mode, and empty is a reading rather than an
110
+ * absence — a `--fix` that skipped a file silently is the same defect as
111
+ * one that wrote it silently.
112
+ */
113
+ skipped: SkippedSpec[];
65
114
  }
66
115
 
67
116
  // ── Registry loading ──────────────────────────────────────────
@@ -90,14 +139,67 @@ function loadRegistry(): RegistryEntry[] {
90
139
 
91
140
  // ── SC extraction ─────────────────────────────────────────────
92
141
 
93
- function extractSCs(content: string, specFile: string): ParsedSC[] {
94
- const scs: ParsedSC[] = [];
95
- const pattern = /^- \[ \] (SC-\w+):\s*(.+)$/gm;
96
- let match;
97
- while ((match = pattern.exec(content)) !== null) {
98
- scs.push({ id: match[1], statement: match[2].trim(), specFile });
99
- }
100
- return scs;
142
+ /**
143
+ * Every criterion a spec declares, from the SHARED binding.
144
+ *
145
+ * This was `/^- \[ \] (SC-\w+):\s*(.+)$/gm` — a reporter carrying its own,
146
+ * narrower spelling of a thing `lib/sc-ids.ts` already decides. That is the
147
+ * fourth shape in `.claude/rules/checks-must-be-able-to-fail.md` pointing the
148
+ * wrong way: two deciders, disagreeing, with the reporter the one people read.
149
+ * It was narrow in two directions at once.
150
+ *
151
+ * - **`SC-\w+` cannot see a `CRC-` id.** `TRACKED_ID_PREFIXES` has held two
152
+ * namespaces since #1313. `specs/CODE-REVIEW-CONVERGENCE-SPEC.md` declares
153
+ * 56 criteria and is marked `compliance: strict`, and this reported
154
+ * `total 0` for it. That is worse than crashing: silence is visibly broken,
155
+ * `0` reads as "nothing to do" and stops anyone looking.
156
+ * - **The `- [ ] ` literal cannot see a TICKED criterion**, in any namespace.
157
+ * So the `SC-` side had been under-reporting for its whole life and nobody
158
+ * noticed, because the number it printed was plausible. Measured on this
159
+ * tree: **66 reported against 1,669 declared.** It was showing 4% of the
160
+ * corpus.
161
+ *
162
+ * `parseScDeclarations` is the one owner, so this reporter, the status
163
+ * flipper, the drift gate and the collision detectors now agree about what a
164
+ * criterion is by construction rather than by four regexes happening to match.
165
+ */
166
+ function extractSCs(content: string, specFile: string): ExtractedSC[] {
167
+ return parseScDeclarations(content, specFile).map((d) => ({
168
+ id: d.id,
169
+ statement: d.statement,
170
+ specFile,
171
+ checked: d.checked,
172
+ }));
173
+ }
174
+
175
+ /**
176
+ * The population `--fix` may rewrite — and it is NOT the population this
177
+ * reporter reads.
178
+ *
179
+ * Reporting a criterion costs a row in a table. Rewriting one edits a spec,
180
+ * and #1286 is open about `--fix` damaging a file it should not have touched.
181
+ * Different decisions, different risk, so the reporter widened and the writer
182
+ * did not. Each clause subtracts a population this change would otherwise
183
+ * have handed the rewriter as a side effect:
184
+ *
185
+ * | clause | what it holds back, measured on this tree |
186
+ * |---|---|
187
+ * | `!checked` | 1,443 ticked criteria — finished work |
188
+ * | `SC-` prefix | 55 unmatched `CRC-` criteria, in a spec being bound concurrently |
189
+ * | top-level | 91 unmatched criteria in a split spec under `specs/` |
190
+ *
191
+ * All three live here rather than being enforced upstream, because a clause
192
+ * split across two sites is two deciders for one question: mutate either and
193
+ * the other holds the case up.
194
+ *
195
+ * This is a SCOPE, not a second opinion about what a criterion is —
196
+ * `extractSCs` remains the only thing that decides that. Deleting a clause is
197
+ * a deliberate one-line widening whenever somebody wants it, and
198
+ * `test/audit-specs-blindness.test.ts` AB-4 measures that the set it selects
199
+ * is the pre-change population exactly.
200
+ */
201
+ export function isRewriteCandidate(sc: ExtractedSC): boolean {
202
+ return !sc.checked && sc.id.startsWith("SC-") && !sc.specFile.includes("/");
101
203
  }
102
204
 
103
205
  // ── Closest pattern matching for rewrites ─────────────────────
@@ -596,12 +698,34 @@ export function auditSpecs(
596
698
  const specsDir = join(root, "specs");
597
699
  const specs: SpecAuditResult[] = [];
598
700
  const rewrites: RewriteEntry[] = [];
701
+ const skipped: SkippedSpec[] = [];
599
702
 
600
703
  if (!existsSync(specsDir)) {
601
- return { specs, totalSCs: 0, totalMatched: 0, totalUnmatched: 0, totalBehavioral: 0, strictUnmatched: 0, rewrites };
704
+ return {
705
+ specs,
706
+ totalSCs: 0,
707
+ totalTicked: 0,
708
+ totalMatched: 0,
709
+ totalUnmatched: 0,
710
+ totalBehavioral: 0,
711
+ strictUnmatched: 0,
712
+ rewrites,
713
+ skipped,
714
+ };
602
715
  }
603
716
 
604
- const specFiles = readdirSync(specsDir).filter((f) => f.endsWith(".md"));
717
+ // The SHARED enumeration (#225), not a second walk. This was
718
+ // `readdirSync(specsDir).filter(f => f.endsWith(".md"))`, which reports
719
+ // `bootstrap-data-flow` as a directory entry and then drops it for not
720
+ // ending in `.md` — so its six specs and 260 criteria were not merely
721
+ // unread, they were unreachable. `scripts/detect-sc-drift.ts` already
722
+ // carries a docblock about having fixed exactly this for itself, so the
723
+ // reporter and the drift gate disagreed about what a spec is, and the gate
724
+ // was the one that was right.
725
+ //
726
+ // Entries come back relative to `specsDir`, so a nested spec names itself
727
+ // `bootstrap-data-flow/success-criteria.md` in the table and in a finding.
728
+ const specFiles = collectSpecFiles(specsDir);
605
729
 
606
730
  for (const specFile of specFiles) {
607
731
  const filePath = join(specsDir, specFile);
@@ -618,20 +742,27 @@ export function auditSpecs(
618
742
  const matchedSCs: SCClassification[] = [];
619
743
  const unmatchedSCs: SCClassification[] = [];
620
744
  const behavioralSCs: SCClassification[] = [];
745
+ /** The unmatched criteria as declared, so the writer can scope itself. */
746
+ const unmatchedDecls: ExtractedSC[] = [];
621
747
 
622
- for (const sc of scs) {
748
+ // Over the UNTICKED criteria only — see `SpecAuditResult`. Widening
749
+ // `total` to the whole corpus must not widen `unmatched`.
750
+ const open = scs.filter((sc) => !sc.checked);
751
+ for (const sc of open) {
623
752
  if (isBehavioralSC(sc)) {
624
753
  behavioralSCs.push({ id: sc.id, statement: sc.statement, category: "behavioral" });
625
754
  } else if (matchPattern(sc) !== null) {
626
755
  matchedSCs.push({ id: sc.id, statement: sc.statement, category: "matched" });
627
756
  } else {
628
757
  unmatchedSCs.push({ id: sc.id, statement: sc.statement, category: "unmatched" });
758
+ unmatchedDecls.push(sc);
629
759
  }
630
760
  }
631
761
 
632
762
  specs.push({
633
763
  specFile,
634
764
  total: scs.length,
765
+ ticked: scs.length - open.length,
635
766
  matched: matchedSCs.length,
636
767
  unmatched: unmatchedSCs.length,
637
768
  behavioral: behavioralSCs.length,
@@ -642,11 +773,29 @@ export function auditSpecs(
642
773
  });
643
774
 
644
775
  // ── Fix mode: rewrite unmatched SCs in-place ──────────────
645
- if (opts?.fix && unmatchedSCs.length > 0) {
776
+ const rewritable = unmatchedDecls.filter(isRewriteCandidate);
777
+
778
+ // #1286: asked BEFORE the rewrite loop, not beside the `writeFileSync`.
779
+ // A derived file must not contribute `RewriteEntry`s either — the
780
+ // scaffold turns those into `UPDATED: specs/<file>` and stages the path,
781
+ // so recording rewrites for a file nobody wrote reports an edit that did
782
+ // not happen and dirties a tree that is clean.
783
+ const reading = readDerivedDeclaration(content);
784
+ if (opts?.fix && rewritable.length > 0 && !mayWrite(reading)) {
785
+ skipped.push({
786
+ specFile,
787
+ reading,
788
+ message: skipLine(specFile, reading),
789
+ wouldHaveEdited: rewritable.length,
790
+ });
791
+ continue;
792
+ }
793
+
794
+ if (opts?.fix && rewritable.length > 0) {
646
795
  let modified = content;
647
796
  let hasChanges = false;
648
797
 
649
- for (const usc of unmatchedSCs) {
798
+ for (const usc of rewritable) {
650
799
  const closest = findClosestPattern(usc.statement);
651
800
  const decision = decideRewrite(usc.statement, closest);
652
801
 
@@ -706,6 +855,7 @@ export function auditSpecs(
706
855
  }
707
856
 
708
857
  const totalSCs = specs.reduce((sum, s) => sum + s.total, 0);
858
+ const totalTicked = specs.reduce((sum, s) => sum + s.ticked, 0);
709
859
  const totalMatched = specs.reduce((sum, s) => sum + s.matched, 0);
710
860
  const totalUnmatched = specs.reduce((sum, s) => sum + s.unmatched, 0);
711
861
  const totalBehavioral = specs.reduce((sum, s) => sum + s.behavioral, 0);
@@ -713,7 +863,17 @@ export function auditSpecs(
713
863
  .filter((s) => s.compliance === "strict")
714
864
  .reduce((sum, s) => sum + s.unmatched, 0);
715
865
 
716
- return { specs, totalSCs, totalMatched, totalUnmatched, totalBehavioral, strictUnmatched, rewrites };
866
+ return {
867
+ specs,
868
+ totalSCs,
869
+ totalTicked,
870
+ totalMatched,
871
+ totalUnmatched,
872
+ totalBehavioral,
873
+ strictUnmatched,
874
+ rewrites,
875
+ skipped,
876
+ };
717
877
  }
718
878
 
719
879
  // ── Report formatting ─────────────────────────────────────────
@@ -724,24 +884,66 @@ export function formatReport(result: AuditResult): string {
724
884
  lines.push("=".repeat(60));
725
885
  lines.push("");
726
886
 
727
- // Per-spec table
728
- lines.push(
729
- `${"Spec".padEnd(45)} ${"total".padEnd(6)} ${"matched".padEnd(8)} ${"unmatched".padEnd(10)} ${"behavioral".padEnd(10)}`
887
+ // The name column is sized to the longest name present. A nested spec is
888
+ // named by its path, so a fixed 45 would silently push every other column
889
+ // out of alignment on exactly the rows this change made visible.
890
+ const nameWidth = Math.max(
891
+ "Spec".length,
892
+ ...result.specs.map((s) => s.specFile.length),
730
893
  );
731
- lines.push("-".repeat(80));
894
+ const row = (
895
+ name: string,
896
+ total: string | number,
897
+ ticked: string | number,
898
+ matched: string | number,
899
+ unmatched: string | number,
900
+ behavioral: string | number,
901
+ ) =>
902
+ `${name.padEnd(nameWidth)} ${String(total).padEnd(6)} ${String(ticked).padEnd(7)} ` +
903
+ `${String(matched).padEnd(8)} ${String(unmatched).padEnd(10)} ${String(behavioral).padEnd(10)}`;
904
+
905
+ lines.push(row("Spec", "total", "ticked", "matched", "unmatched", "behavioral"));
906
+ lines.push("-".repeat(nameWidth + 46));
732
907
 
733
908
  for (const spec of result.specs) {
734
909
  lines.push(
735
- `${spec.specFile.padEnd(45)} ${String(spec.total).padEnd(6)} ${String(spec.matched).padEnd(8)} ${String(spec.unmatched).padEnd(10)} ${String(spec.behavioral).padEnd(10)}`
910
+ row(spec.specFile, spec.total, spec.ticked, spec.matched, spec.unmatched, spec.behavioral),
736
911
  );
737
912
  }
738
913
 
739
- lines.push("-".repeat(80));
914
+ lines.push("-".repeat(nameWidth + 46));
915
+ lines.push(
916
+ row(
917
+ "TOTAL",
918
+ result.totalSCs,
919
+ result.totalTicked,
920
+ result.totalMatched,
921
+ result.totalUnmatched,
922
+ result.totalBehavioral,
923
+ ),
924
+ );
925
+ lines.push("");
926
+ // `matched`/`unmatched`/`behavioral` are the UNTICKED split, and a reader
927
+ // who adds the columns and gets `total` only by accident will read them as
928
+ // a partition of the whole. Say which population they describe.
740
929
  lines.push(
741
- `${"TOTAL".padEnd(45)} ${String(result.totalSCs).padEnd(6)} ${String(result.totalMatched).padEnd(8)} ${String(result.totalUnmatched).padEnd(10)} ${String(result.totalBehavioral).padEnd(10)}`
930
+ `total = ticked + matched + unmatched + behavioral. ` +
931
+ `matched/unmatched/behavioral classify the ${result.totalSCs - result.totalTicked} UNTICKED criteria only.`,
742
932
  );
743
933
  lines.push("");
744
934
 
935
+ // #1286: named individually, never summarised. "1 spec skipped" is not
936
+ // something a reader can act on, and a skip nobody can see is the same
937
+ // defect as the write it replaced.
938
+ if (result.skipped.length > 0) {
939
+ lines.push(`Not written — a generator owns these (${result.skipped.length}):`);
940
+ for (const s of result.skipped) {
941
+ lines.push(` ${s.message}`);
942
+ lines.push(` ${s.wouldHaveEdited} criteria would have been edited.`);
943
+ }
944
+ lines.push("");
945
+ }
946
+
745
947
  return lines.join("\n");
746
948
  }
747
949
 
@@ -24,6 +24,7 @@ import {
24
24
  import { readScRegistry } from "./sync-sc-status";
25
25
  import { describeReading } from "../lib/sc-id-cross-tree";
26
26
  import { currentScOwner } from "../lib/sc-reservations";
27
+ import { mayWrite, readDerivedDeclaration, skipLine } from "../lib/derived-spec";
27
28
  import { join } from "path";
28
29
 
29
30
  /** Same resolution sync-sc-status uses, so both halves read one tree. */
@@ -113,6 +114,16 @@ try {
113
114
  const { number: scNumber, namespace } = allocateScNumber(ROOT, content, readScRegistry(), { owner });
114
115
  const scLine = formatSCLine(scNumber, statement);
115
116
 
117
+ // #1286: appending to a spec a generator owns writes a criterion that
118
+ // disappears at the next regeneration, having consumed an SC id that
119
+ // nothing then declares. Refuse loudly rather than allocate into a file
120
+ // that cannot keep it.
121
+ const reading = readDerivedDeclaration(content);
122
+ if (!mayWrite(reading)) {
123
+ console.error(skipLine(specPath, reading));
124
+ process.exit(1);
125
+ }
126
+
116
127
  // Append SC line to the end of the file
117
128
  const newContent = content.trimEnd() + "\n" + scLine + "\n";
118
129
  writeFileSync(specPath, newContent);
@@ -13,6 +13,7 @@
13
13
 
14
14
  import { existsSync, readFileSync } from "fs";
15
15
  import { collectSpecFiles } from "../lib/spec-files";
16
+ import { SC_ID_SOURCE } from "../lib/sc-ids";
16
17
  import { join } from "path";
17
18
 
18
19
  export interface DriftResult {
@@ -112,8 +113,15 @@ export function detectDrift(specsDir: string, projectRoot: string): DriftResult
112
113
  const specPath = join(specsDir, specFile);
113
114
  const content = readFileSync(specPath, "utf-8");
114
115
 
115
- // Find all SC lines (both checked and unchecked)
116
- const scPattern = /^- \[[ x]\] (SC-\d+):\s*(.+)$/gm;
116
+ // Find all SC lines (both checked and unchecked).
117
+ //
118
+ // Built from `SC_ID_SOURCE` (#1298). This is the gate
119
+ // `scripts/sync-sc-status.ts` runs before it flips a box, so a criterion
120
+ // this pattern cannot see is not merely unreported — it is auto-ticked
121
+ // with no drift gate at all. That is the same failure the docblock above
122
+ // records for subdirectory specs, arriving a second time by prefix, and
123
+ // `SC-\d+` could see neither an anti-criterion nor a `CRC-` id.
124
+ const scPattern = new RegExp(`^- \\[[ x]\\] (${SC_ID_SOURCE}):\\s*(.+)$`, "gm");
117
125
  let match;
118
126
 
119
127
  while ((match = scPattern.exec(content)) !== null) {