rungate 0.5.0 → 0.7.0

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 (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env bun
2
2
  import { readFileSync, readdirSync } from "fs";
3
3
  import { join, basename, resolve } from "path";
4
+ import { localCalendarDay } from "../lib/local-calendar-day";
4
5
  import {
5
6
  type ToolCall,
6
7
  type TranscriptData,
@@ -184,7 +185,7 @@ export function formatReport(audits: AgentAudit[]): string {
184
185
  const lines: string[] = [];
185
186
  lines.push("# Workflow Transcript Audit Report");
186
187
  lines.push(`\nAudited: ${audits.length} agents`);
187
- lines.push(`Date: ${new Date().toISOString().split("T")[0]}`);
188
+ lines.push(`Date: ${localCalendarDay()}`);
188
189
 
189
190
  const avgScore = Math.round(audits.reduce((s, a) => s + a.score, 0) / audits.length);
190
191
  lines.push(`\n## Summary: ${avgScore}% average (${audits.map((a) => a.grade).join(", ")})`);
@@ -16,6 +16,7 @@
16
16
  import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
17
17
  import { join, basename, dirname } from "path";
18
18
  import { SIGNAL_PHRASE_PATTERNS } from "../lib/signal-phrases";
19
+ import { localCalendarDay } from "../lib/local-calendar-day";
19
20
 
20
21
  // ── Argument parsing ──────────────────────────────────────────
21
22
 
@@ -225,7 +226,7 @@ function deriveSlug(title: string): string {
225
226
  // ── Spec generation ───────────────────────────────────────────
226
227
 
227
228
  function generateSpec(rules: ExtractedRule[], title: string, governs: string): string {
228
- const today = new Date().toISOString().split("T")[0];
229
+ const today = localCalendarDay();
229
230
 
230
231
  // Build SC lines
231
232
  const scLines = rules.map((rule, i) => {
@@ -5,19 +5,25 @@
5
5
  * Usage:
6
6
  * bun scripts/create-sc.ts --pattern file-exists --params '{"file":"AGENTS.md"}'
7
7
  * bun scripts/create-sc.ts --pattern file-exists --params '{"file":"AGENTS.md"}' --spec specs/MY-SPEC.md
8
+ * bun scripts/create-sc.ts --pattern file-exists --params '{...}' --spec specs/X.md --owner '#725'
8
9
  * bun scripts/create-sc.ts --list
9
10
  *
11
+ * `--owner` names the entry in `specs/sc-reservations.json` to allocate from.
12
+ * It defaults to this checkout's branch. An owner holding no block allocates
13
+ * above every block in the store, which is the safe direction.
14
+ *
10
15
  * Thin CLI consumer — all logic lives in lib/create-sc.ts.
11
16
  */
12
17
  import { readFileSync, writeFileSync, existsSync } from "fs";
13
18
  import {
19
+ allocateScNumber,
14
20
  generateSCText,
15
21
  listPatterns,
16
- nextSCNumber,
17
22
  formatSCLine,
18
23
  } from "../lib/create-sc";
19
24
  import { readScRegistry } from "./sync-sc-status";
20
- import { scIdsSpelledInSource } from "../lib/sc-ids";
25
+ import { describeReading } from "../lib/sc-id-cross-tree";
26
+ import { currentScOwner } from "../lib/sc-reservations";
21
27
  import { join } from "path";
22
28
 
23
29
  /** Same resolution sync-sc-status uses, so both halves read one tree. */
@@ -83,17 +89,41 @@ try {
83
89
  // spell SC ids in the same namespace without appearing in any registry,
84
90
  // so an allocation that consults only the registry can mint a criterion
85
91
  // out of a number a fixture already depends on.
86
- const scNumber = nextSCNumber(
87
- content,
88
- readScRegistry(),
89
- scIdsSpelledInSource(ROOT).keys(),
90
- );
92
+ //
93
+ // And a THIRD half, which is the one the first two could not see (#503):
94
+ // the registry is `specs/` in whichever working tree this command runs
95
+ // in. Two sessions in two worktrees both read "highest + 1" correctly and
96
+ // both got the same number.
97
+ //
98
+ // All three widths compose inside `allocateScNumber`, so this CLI cannot
99
+ // assemble two of them and believe it asked.
100
+ //
101
+ // And a FOURTH, which none of the first three can be (#725): every one of
102
+ // them reads ids that are already written down somewhere, and the four
103
+ // collisions of 2026-10-19 were ids that had been decided on and not yet
104
+ // typed. `specs/sc-reservations.json` is where a session declares a block
105
+ // before consuming it; the owner is this checkout's branch, so a session
106
+ // that reserved one is handed an id out of it and a session that did not
107
+ // is handed one above every block in the store.
108
+ //
109
+ // `--owner` overrides the branch for the case the store is keyed by issue
110
+ // rather than by branch. An owner matching no block is not an error: it
111
+ // is the no-block path, which is the safe one.
112
+ const owner = getFlag("owner") ?? currentScOwner(ROOT);
113
+ const { number: scNumber, namespace } = allocateScNumber(ROOT, content, readScRegistry(), { owner });
91
114
  const scLine = formatSCLine(scNumber, statement);
92
115
 
93
116
  // Append SC line to the end of the file
94
117
  const newContent = content.trimEnd() + "\n" + scLine + "\n";
95
118
  writeFileSync(specPath, newContent);
96
119
  console.log(`Appended to ${specPath}: ${scLine}`);
120
+ // What the number is a floor over, stated rather than implied. A clone on
121
+ // another machine is outside anything this process can reach, and an
122
+ // allocator that printed only the number would be claiming a guarantee it
123
+ // cannot give (`.claude/rules/config-access.md`).
124
+ console.log(` namespace: ${describeReading(namespace)}`);
125
+ console.log(` owner: ${owner ?? "(none — allocated above every reserved block)"}`);
126
+ for (const gap of namespace.unmeasured) console.log(` UNMEASURED: ${gap}`);
97
127
  } else {
98
128
  // Output to stdout for piping
99
129
  const scLine = formatSCLine(0, statement);
@@ -17,6 +17,7 @@ import { existsSync, writeFileSync, mkdirSync } from "fs";
17
17
  import { join } from "path";
18
18
  import { isMatchablePattern, isBehavioralSC, type ParsedSC } from "../lib/conformity";
19
19
  import { loadRegistry, type RegistryEntry } from "../lib/create-sc";
20
+ import { localCalendarDay } from "../lib/local-calendar-day";
20
21
 
21
22
  // ── Argument parsing ──────────────────────────────────────────
22
23
 
@@ -123,7 +124,7 @@ if (scStatements.length > 0) {
123
124
 
124
125
  // ── Generate spec content ─────────────────────────────────────
125
126
 
126
- const today = new Date().toISOString().split("T")[0];
127
+ const today = localCalendarDay();
127
128
 
128
129
  // Build SC lines from validated --sc statements, or use placeholder
129
130
  let scSection: string;
@@ -19,6 +19,7 @@ import { existsSync, lstatSync, readFileSync, unlinkSync, writeFileSync } from "
19
19
  import { dirname, join, resolve } from "path";
20
20
  import { fileURLToPath } from "url";
21
21
  import { seedFromTemplate } from "../lib/success-doc";
22
+ import { localCalendarDay } from "../lib/local-calendar-day";
22
23
 
23
24
  const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
24
25
 
@@ -121,7 +122,7 @@ if (/[\r\n:]/.test(owner)) {
121
122
  );
122
123
  process.exit(1);
123
124
  }
124
- const today = new Date().toISOString().slice(0, 10);
125
+ const today = localCalendarDay();
125
126
 
126
127
  // The SHARED substitution, so this and the scaffold's seed step cannot
127
128
  // produce different bytes for the same logical seed.
@@ -1,9 +1,25 @@
1
1
  #!/usr/bin/env bun
2
2
  import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
3
3
  import { join, relative } from "path";
4
- import { createHash } from "crypto";
5
4
  import { SIGNAL_PHRASE_PATTERNS } from "../lib/signal-phrases";
6
5
  import { planDocScan, type DocScanPlan } from "../lib/doc-scan-targets";
6
+ import { lastCommitDates } from "../lib/git-dates";
7
+ import { contentHash } from "../lib/content-hash";
8
+ import {
9
+ mineFixCommits,
10
+ type EvidenceCandidate,
11
+ type FailureIntakeReading,
12
+ } from "../lib/failure-intake";
13
+ import {
14
+ promoteCandidates,
15
+ PROMOTION_BUDGET_RULES,
16
+ type PromotionReading,
17
+ } from "../lib/rule-promotion";
18
+ import {
19
+ retireUnresolvable,
20
+ survivingSubset,
21
+ type RetirementReading,
22
+ } from "../lib/rule-retirement";
7
23
 
8
24
  // ── Types ────────────────────────────────────────────────────────
9
25
 
@@ -21,6 +37,37 @@ export interface StalenessEntry {
21
37
  type: string;
22
38
  }
23
39
 
40
+ /**
41
+ * What the scan planned against what it actually read (#508).
42
+ *
43
+ * `scan` below says what the walk could SEE. Nothing said what the extractor
44
+ * then managed to READ, and the two are different questions: a candidate
45
+ * count of zero from a scan that read 91 documents and a candidate count of
46
+ * zero from a scan that read 4 are the same line of output.
47
+ *
48
+ * `.claude/rules/checks-must-be-able-to-fail.md` states the general form
49
+ * after #492 measured it — *a scan that reports a verdict should report its
50
+ * own coverage* — and HYGIENE-6 is the verdict in question: it ended in
51
+ * `expect(true).toBe(true)`, so a timeout was the only red it could produce.
52
+ */
53
+ export interface ScanCoverage {
54
+ /** Documents the plan listed. */
55
+ planned: number;
56
+ /** Documents whose bytes reached `extractSignalPhrases`. */
57
+ read: number;
58
+ /**
59
+ * Planned documents the read could not take, with the error that stopped
60
+ * it — `ENOENT` for a file that moved between the walk and the read,
61
+ * `EISDIR`, `EACCES`.
62
+ *
63
+ * Recorded rather than thrown, and recorded rather than dropped. A throw
64
+ * takes an advisory backlog report down over one transient file; a drop
65
+ * makes a partial scan indistinguishable from a complete one, which is
66
+ * the failure this whole interface exists to stop.
67
+ */
68
+ unread: Array<{ file: string; reason: string }>;
69
+ }
70
+
24
71
  export interface ExtractResult {
25
72
  candidates: Candidate[];
26
73
  deduped: {
@@ -29,6 +76,34 @@ export interface ExtractResult {
29
76
  candidatesRemoved: number;
30
77
  };
31
78
  staleness: StalenessEntry[];
79
+ /** What was planned against what was read. Never inferred from `candidates`. */
80
+ coverage: ScanCoverage;
81
+ /**
82
+ * Observed failures mined from `fix:` and `Revert` commits (#545).
83
+ *
84
+ * Carried BESIDE `candidates` rather than merged into it, deliberately. The
85
+ * two populations answer different questions — "is this sentence
86
+ * rule-shaped" against "did something go wrong and cost us something" — and
87
+ * folding them together would move HYGIENE-6's advisory backlog count for a
88
+ * reason that has nothing to do with the backlog.
89
+ */
90
+ evidence: FailureIntakeReading;
91
+ /**
92
+ * Who survives, and why everything else did not (#544). Computed over BOTH
93
+ * populations, which is the point: the doc candidates are what the
94
+ * evidence-required criterion is being applied to.
95
+ */
96
+ promotion: PromotionReading;
97
+ /**
98
+ * What the generator stopped emitting, and why (#544, SC-1941).
99
+ *
100
+ * Separate from `promotion` for the same reason `evidence` is: a candidate
101
+ * dropped because the commit it cites was rebased away and one dropped
102
+ * because it ranked below the cut are different events with different
103
+ * repairs, and one `withheld` list carrying both would need a reader to
104
+ * tell them apart by reason string.
105
+ */
106
+ retirement: RetirementReading<EvidenceCandidate | Candidate>;
32
107
  /**
33
108
  * What was scanned and what could not be (#440).
34
109
  *
@@ -42,9 +117,14 @@ export interface ExtractResult {
42
117
 
43
118
  // ── Helpers ──────────────────────────────────────────────────────
44
119
 
45
- export function contentHash(text: string): string {
46
- return createHash("sha256").update(text.trim().toLowerCase()).digest("hex").slice(0, 12);
47
- }
120
+ // `contentHash` lives in `lib/content-hash.ts` now and is re-exported here
121
+ // under the name its callers already know — one binding, two names, the
122
+ // arrangement `lastCommitDates` has with `lib/conformity.ts` (#508). It moved
123
+ // because `lib/failure-intake.ts` is a second producer of candidates and the
124
+ // SC-137 veto table matches on this hash: two implementations of it would be
125
+ // behaviourally one until the day they disagreed, and the veto would silently
126
+ // stop applying to whichever producer used the other copy.
127
+ export { contentHash };
48
128
 
49
129
  function surroundingContext(lines: string[], lineIdx: number): string {
50
130
  const start = Math.max(0, lineIdx - 1);
@@ -111,24 +191,44 @@ function loadRejectedHashes(projectPath: string): Set<string> {
111
191
  return hashes;
112
192
  }
113
193
 
194
+ /**
195
+ * One git subprocess for every document, not one per document (#508).
196
+ *
197
+ * This was `Bun.spawnSync(["git", …, "log", "-1", …, "--", rel])` inside
198
+ * the loop — the exact code #323 removed from `runDocHygiene`, in a file
199
+ * #323 did not touch. 92 documents meant 92 serial subprocesses against
200
+ * the same repository, and nothing was wrong with any single one: the
201
+ * check was load-sensitive by construction, so a busy machine, a cold
202
+ * cache or another suite holding the index pushed it past the 5000ms
203
+ * default test timeout. Measured before the change at 4169ms, 4521ms and
204
+ * 3969ms on an IDLE machine with a warm cache; HYGIENE-6 had been seen red
205
+ * four times in full runs and green standalone every time.
206
+ *
207
+ * `lastCommitDates` walks the whole history newest-first with `--name-only`
208
+ * and returns every path's latest commit date from one call. Imported from
209
+ * `lib/git-dates.ts` rather than copied, because two implementations of
210
+ * one question are behaviourally one and no test can tell them apart.
211
+ */
114
212
  function computeStaleness(projectPath: string, files: string[]): StalenessEntry[] {
213
+ const considered = files
214
+ .map(f => relative(projectPath, f))
215
+ .filter(rel => !(rel.includes("docs/adr/") || /ADR/i.test(rel)));
216
+ // The exact lookup set is the pathspec, so the keys and the query cannot
217
+ // drift — #323 got this wrong first time by passing the directories.
218
+ const lastCommit = lastCommitDates(projectPath, considered);
219
+
115
220
  const stale: StalenessEntry[] = [];
116
- for (const filePath of files) {
117
- const rel = relative(projectPath, filePath);
118
- const isAdr = rel.includes("docs/adr/") || /ADR/i.test(rel);
119
- if (isAdr) continue;
120
- try {
121
- const result = Bun.spawnSync(["git", "-C", projectPath, "log", "-1", "--format=%ci", "--", rel], { timeout: 5_000 });
122
- const dateStr = result.stdout.toString().trim().split(" ")[0];
123
- if (!dateStr) continue;
124
- const daysSince = (Date.now() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24);
125
- const isSpec = rel.startsWith("specs/");
126
- const threshold = isSpec ? 90 : 180;
127
- const type = isSpec ? "spec" : "guide";
128
- if (daysSince > threshold) {
129
- stale.push({ file: rel, daysSince: Math.floor(daysSince), threshold, type });
130
- }
131
- } catch {}
221
+ for (const rel of considered) {
222
+ const dateStr = lastCommit.get(rel);
223
+ // No commit means untracked or newly added, which is the opposite of stale.
224
+ if (!dateStr) continue;
225
+ const daysSince = (Date.now() - new Date(dateStr).getTime()) / (1000 * 60 * 60 * 24);
226
+ const isSpec = rel.startsWith("specs/");
227
+ const threshold = isSpec ? 90 : 180;
228
+ const type = isSpec ? "spec" : "guide";
229
+ if (daysSince > threshold) {
230
+ stale.push({ file: rel, daysSince: Math.floor(daysSince), threshold, type });
231
+ }
132
232
  }
133
233
  return stale;
134
234
  }
@@ -171,16 +271,32 @@ function applyToAgentsMd(projectPath: string, candidates: Candidate[]): void {
171
271
 
172
272
  export async function extractConstraints(
173
273
  projectPath: string,
174
- options?: { apply?: boolean }
274
+ options?: { apply?: boolean; plan?: DocScanPlan }
175
275
  ): Promise<ExtractResult> {
176
- const scan = planDocScan(projectPath);
276
+ // `plan` is a seam, and it is here for one reason worth stating: the
277
+ // unread branch below is unreachable from outside this function, because
278
+ // the walk that produces the plan only lists files it has just stat'd. A
279
+ // branch no test can reach is the subject of this repo's central rule, so
280
+ // the plan is an input a caller may supply — which is also the race the
281
+ // branch is about, a plan taken a moment before the tree moved.
282
+ const scan = options?.plan ?? planDocScan(projectPath);
177
283
  const scanFiles = scan.files;
178
284
  const existingConstraints = loadExistingConstraints(projectPath);
179
285
  const rejectedHashes = loadRejectedHashes(projectPath);
180
286
 
181
287
  let allCandidates: Candidate[] = [];
288
+ const unread: ScanCoverage["unread"] = [];
289
+ let read = 0;
182
290
  for (const filePath of scanFiles) {
183
- const content = readFileSync(filePath, "utf-8");
291
+ let content: string;
292
+ try {
293
+ content = readFileSync(filePath, "utf-8");
294
+ } catch (err) {
295
+ const e = err as NodeJS.ErrnoException;
296
+ unread.push({ file: relative(projectPath, filePath), reason: e.code ?? e.name });
297
+ continue;
298
+ }
299
+ read++;
184
300
  allCandidates.push(...extractSignalPhrases(content, filePath, projectPath));
185
301
  }
186
302
 
@@ -203,18 +319,73 @@ export async function extractConstraints(
203
319
 
204
320
  const staleness = computeStaleness(projectPath, scanFiles);
205
321
 
206
- if (options?.apply && allCandidates.length > 0) {
207
- applyToAgentsMd(projectPath, allCandidates);
322
+ // #545. One bounded `git log`, after the document walk, so a repository
323
+ // without one costs nothing and a repository with one is read once.
324
+ const evidence = mineFixCommits(projectPath);
325
+
326
+ // #544. The doc candidates arrive with no `evidence` field at all, so the
327
+ // gate withholds every one of them. That is not a bug in the wiring — it is
328
+ // the measurement: signal-phrase extraction produces nothing a promotion
329
+ // criterion based on observed failure can promote.
330
+ // #544 SC-1941. Retirement runs BEFORE promotion and over both
331
+ // populations: a candidate citing a commit that was rebased away, or a
332
+ // `path:line` in a file that has since moved, is dropped rather than
333
+ // ranked. Recency is the only ordering signal the promoter has, so a
334
+ // candidate citing a vanished sha would otherwise rank at the very top.
335
+ //
336
+ // Its reading is folded into the promotion as an upstream, not merged into
337
+ // one here: `0 retired` on a shallow clone means the question could not be
338
+ // asked, and a promotion that reported MEASURED over that population would
339
+ // be claiming a completeness nothing established.
340
+ const retirement = retireUnresolvable(
341
+ [...evidence.candidates, ...allCandidates],
342
+ projectPath,
343
+ );
344
+
345
+ const promotion = promoteCandidates(
346
+ retirement.kept,
347
+ {
348
+ budget: PROMOTION_BUDGET_RULES,
349
+ rejectedHashes: rejectedHashes,
350
+ upstream: [evidence, retirement],
351
+ },
352
+ );
353
+
354
+ // #544. The gate has to reach the WRITE, or it is a control with no sink.
355
+ //
356
+ // Until this line, `--apply` wrote `allCandidates` — the unfiltered list —
357
+ // so a candidate the retirement pass had just dropped was written into
358
+ // `AGENTS.md` anyway and `retirement` was a field on the result that
359
+ // nothing downstream consulted. A gate whose verdict changes no output is
360
+ // not a fail-open; it is decoration.
361
+ //
362
+ // Filtered by object identity, not by hash: the same candidate objects
363
+ // flow through `retireUnresolvable`, and a hash is a judgement about a
364
+ // SENTENCE — two candidates mined from different positions can share one
365
+ // (`lib/failure-intake.ts` relies on exactly that for a revert and the fix
366
+ // it reverts), so matching on it would drop a survivor alongside a retired
367
+ // twin.
368
+ const keptDocCandidates = survivingSubset(allCandidates, retirement);
369
+
370
+ if (options?.apply && keptDocCandidates.length > 0) {
371
+ applyToAgentsMd(projectPath, keptDocCandidates);
208
372
  }
209
373
 
210
374
  return {
211
- candidates: allCandidates,
375
+ // The backlog HYGIENE-6 counts is the surviving population, for the same
376
+ // reason: re-reporting a candidate the generator has already retired
377
+ // asks somebody to triage a position that is not there any more.
378
+ candidates: keptDocCandidates,
212
379
  deduped: {
213
380
  existingConstraints: existingRemoved,
214
381
  rejectedPrior: rejectedRemoved,
215
382
  candidatesRemoved: existingRemoved + rejectedRemoved,
216
383
  },
217
384
  staleness,
385
+ coverage: { planned: scanFiles.length, read, unread },
386
+ evidence,
387
+ retirement,
388
+ promotion,
218
389
  scan,
219
390
  };
220
391
  }
@@ -10,6 +10,13 @@
10
10
  */
11
11
  import { existsSync, readFileSync, readdirSync, writeFileSync, statSync } from "fs";
12
12
  import { join, basename } from "path";
13
+ import { localCalendarDay } from "../lib/local-calendar-day";
14
+ import {
15
+ fallowAvailable,
16
+ fallowUnmeasuredNotice,
17
+ runFallowJson,
18
+ type FallowUnavailable,
19
+ } from "../lib/fallow-availability";
13
20
 
14
21
  const projectPath = process.argv[2];
15
22
  if (!projectPath || !existsSync(projectPath)) {
@@ -18,7 +25,7 @@ if (!projectPath || !existsSync(projectPath)) {
18
25
  }
19
26
 
20
27
  const projectName = basename(projectPath);
21
- const today = new Date().toISOString().split("T")[0];
28
+ const today = localCalendarDay();
22
29
 
23
30
  // ── Fallow analysis ──────────────────────────────────────────
24
31
 
@@ -30,27 +37,45 @@ interface FallowData {
30
37
  elapsed: number;
31
38
  }
32
39
 
33
- function runFallow(): FallowData | null {
34
- const result = Bun.spawnSync(
35
- ["npx", "fallow", "dead-code", "--format", "json", "--quiet"],
36
- { cwd: projectPath, timeout: 30_000 }
37
- );
38
- const stdout = result.stdout.toString().trim();
39
- if (!stdout || stdout.startsWith("{\"error\"")) return null;
40
- try {
41
- const d = JSON.parse(stdout);
42
- return {
43
- entryPoints: d.entry_points?.total || 0,
44
- unusedFiles: (d.unused_files || []).map((f: any) => f.path),
45
- unusedExports: (d.unused_exports || []).map((e: any) => ({
46
- path: e.path, export_name: e.export_name, line: e.line
47
- })),
48
- circularDeps: (d.circular_dependencies || []).map((c: any) => ({
49
- files: c.files || [c.path]
50
- })),
51
- elapsed: d.elapsed_ms || 0,
52
- };
53
- } catch { return null; }
40
+ /**
41
+ * Three outcomes, not two (#581).
42
+ *
43
+ * This returned `null` for "not installed", "the spawn failed", "the output
44
+ * did not parse" and — through `||` in the summary table below — "it ran and
45
+ * found zero". A CODE-MAP written from any of them was byte-identical, so a
46
+ * reader could not tell a project with no dead code from a project nobody
47
+ * looked at.
48
+ */
49
+ type FallowOutcome = { data: FallowData } | { unavailable: FallowUnavailable };
50
+
51
+ function runFallow(): FallowOutcome {
52
+ // Resolved locally, with no network path. A bare `npx fallow` for a tool
53
+ // that is not a declared dependency is a registry fetch on the SCAFFOLD
54
+ // path — once per consumer, forever, including behind a proxy and in an
55
+ // air-gapped CI. `lib/conformity.ts` fixed this for itself in #510 and
56
+ // this caller never got it.
57
+ //
58
+ // The spawn, the budget and the classification are no longer here: they
59
+ // were a second copy of `lib/conformity.ts`'s, with a second `30_000`
60
+ // literal, and the two disagreed about what to do with a killed run. One
61
+ // binding now, in `lib/fallow-availability.ts` (#935). What stays here is
62
+ // the SHAPING of fallow's JSON into the fields CODE-MAP.md needs, which is
63
+ // this script's own business and nobody else's.
64
+ const root = fallowAvailable(projectPath) ? projectPath : process.cwd();
65
+ const reading = runFallowJson<any>(root, ["dead-code"]);
66
+ if ("unavailable" in reading) return { unavailable: reading.unavailable };
67
+ const d = reading.data;
68
+ return { data: {
69
+ entryPoints: d.entry_points?.total || 0,
70
+ unusedFiles: (d.unused_files || []).map((f: any) => f.path),
71
+ unusedExports: (d.unused_exports || []).map((e: any) => ({
72
+ path: e.path, export_name: e.export_name, line: e.line
73
+ })),
74
+ circularDeps: (d.circular_dependencies || []).map((c: any) => ({
75
+ files: c.files || [c.path]
76
+ })),
77
+ elapsed: d.elapsed_ms || 0,
78
+ } };
54
79
  }
55
80
 
56
81
  // ── Route scanning ───────────────────────────────────────────
@@ -192,7 +217,9 @@ function readPackageInfo(): { name: string; deps: number; devDeps: number; scrip
192
217
 
193
218
  console.log(`Scanning ${projectName}...`);
194
219
 
195
- const fallow = runFallow();
220
+ const fallowOutcome = runFallow();
221
+ const fallow = "data" in fallowOutcome ? fallowOutcome.data : null;
222
+ const fallowMissing = "unavailable" in fallowOutcome ? fallowOutcome.unavailable : null;
196
223
  const routes = scanRoutes();
197
224
  const dirs = scanDirectories();
198
225
  const components = scanComponents();
@@ -200,7 +227,9 @@ const pkg = readPackageInfo();
200
227
  const consumerMappings = scanConsumerModules();
201
228
  const pageMappings = scanPageComponents();
202
229
 
203
- console.log(` Fallow: ${fallow ? `${fallow.entryPoints} entry points, ${fallow.elapsed}ms` : "not available"}`);
230
+ console.log(
231
+ ` Fallow: ${fallow ? `${fallow.entryPoints} entry points, ${fallow.elapsed}ms` : `UNMEASURED — ${fallowMissing?.reason}`}`,
232
+ );
204
233
  console.log(` Routes: ${routes.length}`);
205
234
  console.log(` Directories: ${dirs.length}`);
206
235
  console.log(` Components: ${components.length}`);
@@ -240,10 +269,10 @@ sections.push(`## Summary
240
269
  | Dev dependencies | ${pkg.devDeps} |
241
270
  | API routes | ${routes.length} |
242
271
  | React components | ${components.length} |
243
- | Entry points (fallow) | ${fallow?.entryPoints || "N/A"} |
244
- | Unused files | ${fallow?.unusedFiles.length || "N/A"} |
245
- | Unused exports | ${fallow?.unusedExports.length || "N/A"} |
246
- | Circular dependencies | ${fallow?.circularDeps.length || "N/A"} |
272
+ | Entry points (fallow) | ${fallow ? fallow.entryPoints : "UNMEASURED"} |
273
+ | Unused files | ${fallow ? fallow.unusedFiles.length : "UNMEASURED"} |
274
+ | Unused exports | ${fallow ? fallow.unusedExports.length : "UNMEASURED"} |
275
+ | Circular dependencies | ${fallow ? fallow.circularDeps.length : "UNMEASURED"} |
247
276
  | Module import mappings | ${consumerMappings.length} |
248
277
  | Page-component mappings | ${pageMappings.length} |`);
249
278
 
@@ -324,6 +353,11 @@ if (fallow) {
324
353
  }
325
354
 
326
355
  sections.push(health.trim());
356
+ } else if (fallowMissing) {
357
+ // Named, not omitted. A missing section and a section reporting nothing
358
+ // wrong are the same absence to a reader, and the reader of a CODE-MAP is
359
+ // an agent deciding whether this project has dead code.
360
+ sections.push(fallowUnmeasuredNotice(fallowMissing));
327
361
  }
328
362
 
329
363
  // Scripts
@@ -104,11 +104,21 @@ if (fix) {
104
104
  // actually do rather than what it would do with different settings (#398).
105
105
  runScaffoldWriteSteps(rehearsal.dir, projectType, actions, { force, commit: false, rehearsing: true, profile, autoFix, pruneConsumers });
106
106
  } finally {
107
- discardRehearsal(rehearsal);
107
+ // #549: a cleanup failure is a sentence, not an exception. The report
108
+ // has already printed by now, and throwing here threw it away.
109
+ const leaked = discardRehearsal(rehearsal);
110
+ if (leaked) console.error(`WARNING: ${leaked}`);
108
111
  }
109
112
  }
110
113
 
111
114
  // ── Report ─────────────────────────────────────────────────────
112
115
 
113
116
  // A refusal that only prints is one nobody's CI notices (#216).
114
- if (reportScaffoldActions(actions) > 0) process.exit(1);
117
+ //
118
+ // `!fix` is the mode, read from the same flag the branch above dispatches on
119
+ // rather than from a second variable that could disagree with it (#642). The
120
+ // notice at the top of the run is not enough on its own: a report line is
121
+ // what a grep, a `| tail`, a scrolled terminal and an agent reading the last
122
+ // N lines of a tool result each receive, and without this every one of them
123
+ // was byte-identical to the line a run that really wrote the file prints.
124
+ if (reportScaffoldActions(actions, { rehearsed: !fix }) > 0) process.exit(1);
@@ -2,6 +2,7 @@
2
2
 
3
3
  import { readFileSync, writeFileSync, mkdirSync } from "fs";
4
4
  import { join, dirname } from "path";
5
+ import { localCalendarDay } from "../lib/local-calendar-day";
5
6
 
6
7
  export interface SplitBoundary {
7
8
  heading: string;
@@ -166,7 +167,7 @@ export function generateSplitFiles(
166
167
  metadata: { owner: string; testable: boolean }
167
168
  ): SplitFile[] {
168
169
  const lines = content.split("\n");
169
- const now = new Date().toISOString().split("T")[0];
170
+ const now = localCalendarDay();
170
171
  const groups = groupBoundaries(boundaries, lines.length);
171
172
 
172
173
  return groups.map((group) => {