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
@@ -13,6 +13,8 @@ import type { ProjectScan } from "./types";
13
13
  import { OWNED_FILES, ownedFilesTable } from "../scaffold/owned-files";
14
14
  import { isHarnessItself } from "../harness-identity";
15
15
  import { typecheckDecision } from "../typescript-project";
16
+ import { localCalendarDay } from "../local-calendar-day";
17
+ import { resolveShipPolicy, shipWorkflowRule } from "../ship-mode";
16
18
 
17
19
  /**
18
20
  * Build the AGENTS.md frontmatter block.
@@ -22,36 +24,83 @@ import { typecheckDecision } from "../typescript-project";
22
24
  * drop a hand-set owner, and emitting nothing — the previous behavior —
23
25
  * stripped the block entirely on every re-scaffold.
24
26
  */
25
- function buildFrontmatter(root: string): string {
26
- const today = new Date().toISOString().slice(0, 10);
27
+ export function existingFrontmatter(root: string): Record<string, string> {
28
+ const path = join(root, "AGENTS.md");
29
+ const existing: Record<string, string> = {};
30
+ if (!existsSync(path)) return existing;
31
+ const content = readFileSync(path, "utf-8");
32
+ const match = content.match(/^---\n([\s\S]*?)\n---\n/);
33
+ if (!match) return existing;
34
+ for (const line of match[1].split("\n")) {
35
+ const kv = line.match(/^([\w-]+):\s*(.*)$/);
36
+ if (!kv) continue;
37
+ const value = kv[2].trim();
38
+ // Carry forward only simple scalars. The block is re-emitted verbatim,
39
+ // so a value holding a delimiter or control character could terminate
40
+ // the frontmatter early and turn the rest of the file into a second
41
+ // document — or smuggle keys past this loop on the next round-trip.
42
+ if (value.includes("---") || /[\x00-\x1f]/.test(value)) continue;
43
+ if (value.length > 200) continue;
44
+ existing[kv[1]] = value;
45
+ }
46
+ return existing;
47
+ }
48
+
49
+ /**
50
+ * The committed AGENTS.md with its frontmatter block removed (#827).
51
+ *
52
+ * `null` means there is nothing to compare against — no file, or a file with
53
+ * no frontmatter block, which is a shape this generator has never written.
54
+ * Null and `""` are different facts and the caller must not conflate them:
55
+ * an absent file has no `updated:` to carry forward, so it gets today's.
56
+ */
57
+ export function existingBody(root: string): string | null {
58
+ const path = join(root, "AGENTS.md");
59
+ if (!existsSync(path)) return null;
60
+ const content = readFileSync(path, "utf-8");
61
+ const match = content.match(/^---\n[\s\S]*?\n---\n\n/);
62
+ if (!match) return null;
63
+ return content.slice(match[0].length);
64
+ }
65
+
66
+ /**
67
+ * Build the AGENTS.md frontmatter block.
68
+ *
69
+ * Preserves whatever the existing file declared (owner, status, custom keys)
70
+ * and refreshes `updated:` ONLY when the body it is about actually changed.
71
+ * Regenerating from scratch would silently drop a hand-set owner, and
72
+ * emitting nothing — the behavior before #552 — stripped the block entirely
73
+ * on every re-scaffold.
74
+ *
75
+ * #827: `updated` used to be forced to today AFTER the spread, so it could
76
+ * never be carried forward and AGENTS.md could never be a fixed point of its
77
+ * own generator — the file stopped being one the morning after it was
78
+ * written, with no code or spec change in between. Dropping the field
79
+ * instead would make the file a fixed point and lose the freshness signal
80
+ * doc-hygiene wants, so neither of those is the fix. What the field claims
81
+ * to mean is "the date this file's content last changed", and deriving it
82
+ * from the body is what makes it mean that; the fixed point then falls out
83
+ * rather than being exempted into existence.
84
+ *
85
+ * @param bodyUnchanged the generator's body for this scan equals the one on
86
+ * disk. The caller computes the body first and answers
87
+ * this; the frontmatter is not in a position to.
88
+ */
89
+ function buildFrontmatter(root: string, today: string, bodyUnchanged: boolean): string {
27
90
  const defaults: Record<string, string> = {
28
91
  "doc-type": "reference",
29
92
  status: "active",
30
93
  updated: today,
31
94
  };
32
95
 
33
- const path = join(root, "AGENTS.md");
34
- const existing: Record<string, string> = {};
35
- if (existsSync(path)) {
36
- const content = readFileSync(path, "utf-8");
37
- const match = content.match(/^---\n([\s\S]*?)\n---\n/);
38
- if (match) {
39
- for (const line of match[1].split("\n")) {
40
- const kv = line.match(/^([\w-]+):\s*(.*)$/);
41
- if (!kv) continue;
42
- const value = kv[2].trim();
43
- // Carry forward only simple scalars. The block is re-emitted verbatim,
44
- // so a value holding a delimiter or control character could terminate
45
- // the frontmatter early and turn the rest of the file into a second
46
- // document — or smuggle keys past this loop on the next round-trip.
47
- if (value.includes("---") || /[\x00-\x1f]/.test(value)) continue;
48
- if (value.length > 200) continue;
49
- existing[kv[1]] = value;
50
- }
51
- }
52
- }
96
+ const existing = existingFrontmatter(root);
53
97
 
54
- const merged: Record<string, string> = { ...defaults, ...existing, updated: today };
98
+ // An existing stamp survives only when the body it dates is unchanged. A
99
+ // file with no stamp at all gets today's either way — there is nothing to
100
+ // carry, and a missing `updated:` is not evidence of freshness.
101
+ const stamp = bodyUnchanged ? (existing.updated ?? today) : today;
102
+
103
+ const merged: Record<string, string> = { ...defaults, ...existing, updated: stamp };
55
104
  const order = ["doc-type", "status", "owner", "updated"];
56
105
  const keys = [...order.filter(k => k in merged), ...Object.keys(merged).filter(k => !order.includes(k))];
57
106
  return `---\n${keys.map(k => `${k}: ${merged[k]}`).join("\n")}\n---\n\n`;
@@ -62,7 +111,14 @@ export interface GeneratedRule {
62
111
  content: string;
63
112
  }
64
113
 
65
- export function generateAgentsMd(scan: ProjectScan): string {
114
+ /**
115
+ * @param today the calendar day a CHANGED body is stamped with. Injectable
116
+ * so a test can advance the clock without advancing anything
117
+ * else — the whole of #827 is a field that moves when nothing
118
+ * else did, and a case that cannot change the date cannot see
119
+ * it. Defaults to the real day, so every caller is unchanged.
120
+ */
121
+ export function generateAgentsMd(scan: ProjectScan, today: string = localCalendarDay()): string {
66
122
  const {
67
123
  name,
68
124
  identity,
@@ -76,17 +132,28 @@ export function generateAgentsMd(scan: ProjectScan): string {
76
132
  } = scan;
77
133
 
78
134
  const techLine = techStack.length > 0 ? `\n**Tech:** ${techStack.join(", ")}` : "";
79
- const repoLine = repoUrl ? `- **Repo:** ${repoUrl}` : "<!-- TODO: Add repo URL -->";
135
+
136
+ // #552. `scan.repoUrl` is `git remote get-url origin`, and a project with
137
+ // no remote called `origin` gets `""` — which this line turned into
138
+ // `<!-- TODO: Add repo URL -->`, twice, on every single run, with NOWHERE
139
+ // for the consumer to put the answer. `--profile=minimal` writes no
140
+ // `.claude/rungate/`, so there was no config key either, and editing
141
+ // AGENTS.md is futile because the next run regenerates it.
142
+ //
143
+ // The frontmatter is the place, because it is the one part of this file
144
+ // that already survives regeneration: `buildFrontmatter` carries forward
145
+ // every simple scalar the existing block declared. So `repo:` written once
146
+ // by hand persists, and the git remote stays the default when there is one.
147
+ const declaredRepo = existingFrontmatter(scan.root).repo;
148
+ const effectiveRepoUrl = repoUrl || (declaredRepo ?? "");
149
+ const repoLine = effectiveRepoUrl
150
+ ? `- **Repo:** ${effectiveRepoUrl}`
151
+ : "<!-- TODO: Add repo URL — set `repo:` in this file's frontmatter, which survives regeneration -->";
80
152
 
81
153
  const consumerSection = consumers.length > 0
82
154
  ? `\n## Consumers (${consumers.length})\n\n${consumers.map(c => `- ${c}`).join("\n")}\n\nCheck cascade impact when modifying shared modules.`
83
155
  : "";
84
156
 
85
- // Re-scaffolding used to strip AGENTS.md's frontmatter, because the
86
- // generator never emitted any. Carry the existing block forward with a
87
- // refreshed `updated:` so doc-hygiene keeps working across re-scaffolds.
88
- const frontmatter = buildFrontmatter(scan.root);
89
-
90
157
  // convert-spec is only advertised where the script actually exists —
91
158
  // rungate has it, a scaffolded consumer may not. It was being dropped on
92
159
  // every re-scaffold because the table did not know about it at all.
@@ -159,7 +226,12 @@ bunx rungate --help
159
226
 
160
227
  Pin the version: re-scaffolding on a newer rungate rewrites generated files.`;
161
228
 
162
- return `${frontmatter}# ${name}
229
+ // Re-scaffolding used to strip AGENTS.md's frontmatter, because the
230
+ // generator never emitted any. Carry the existing block forward so
231
+ // doc-hygiene keeps working across re-scaffolds — and build the BODY
232
+ // first, because `updated:` is a statement about the body and cannot be
233
+ // decided before it exists (#827).
234
+ const body = `# ${name}
163
235
 
164
236
  ## Project Identity
165
237
 
@@ -191,6 +263,8 @@ ${consumerSection}
191
263
  ${repoLine}${makeTargets}
192
264
  - **Test:** \`${testCmd}\`
193
265
  `;
266
+
267
+ return buildFrontmatter(scan.root, today, body === existingBody(scan.root)) + body;
194
268
  }
195
269
 
196
270
  /**
@@ -263,28 +337,27 @@ description: Shared behavioral principles for all agents working in this project
263
337
  `,
264
338
  });
265
339
 
340
+ // The TEXT is not a constant any more (#911). A project that has decided to
341
+ // bypass the harness declares `ship.mode: "direct"` in its config, and this
342
+ // rule says so — with the date and the reason — instead of telling every
343
+ // agent the opposite of its instructions. `lib/ship-mode.ts` is the single
344
+ // decider; an unrecognised mode throws out of here rather than defaulting.
266
345
  rules.push({
267
346
  filename: "ship-workflow.md",
268
- content: `---
269
- description: All implementation work must go through the ship workflow — never spawn agents directly
270
- ---
271
-
272
- ## Ship Workflow Required
273
-
274
- When shipping an issue or implementing code changes, use the ship workflow:
275
-
276
- \`\`\`
277
- Skill("ship") → Workflow({ scriptPath: "workflows/ship.js" })
278
- \`\`\`
279
-
280
- **NEVER spawn Marcus, Quinn, or Rook directly with the Agent tool.** The ship workflow captures transcripts, runs compliance grading, and enforces gates. Spawning agents directly bypasses all measurement.
281
-
282
- If Skill("harness") or Skill("goal") fails, fall back to Skill("ship") with the issue number.
283
- `,
347
+ content: shipWorkflowRule(resolveShipPolicy(scan.harnessConfig)),
284
348
  });
285
349
 
286
350
  if (specs.length > 0) {
287
- const specsTable = specs.map(s => `| ${s.file} | ${s.governs} | ${s.testable} |`).join("\n");
351
+ // A row that sends a reader to a document stating no requirements says so
352
+ // in the row (#579). `specs/PROJECT-STATE.md` sat here for two months as
353
+ // the governing spec for project state management while being a rendered
354
+ // status snapshot, and the table was the reason anyone went there.
355
+ const specsTable = specs
356
+ .map(s => {
357
+ const governs = s.criteriaNone ? `STATES NO CRITERIA — ${s.governs}` : s.governs;
358
+ return `| ${s.file} | ${governs} | ${s.testable} |`;
359
+ })
360
+ .join("\n");
288
361
  rules.push({
289
362
  filename: "specs-routing.md",
290
363
  content: `---
@@ -357,8 +430,58 @@ ${ownedFilesTable()}
357
430
  | regenerate | Rewrites it every run; reports CHANGED only when the bytes differ |
358
431
  | provenance | Rewrites it unless you edited it, in which case it is preserved and reported (#370) |
359
432
  | job-preserving | Owns named jobs inside a file you also write to; your jobs are carried forward |
433
+ | section-preserving | Rewrites the file every run except for named sections, which are carried forward verbatim |
360
434
  | create-only | Seeds it once and never touches it again — the content is yours, not the harness's |
361
435
 
436
+ ### AGENTS.md is section-owned (#568)
437
+
438
+ Everything in \`AGENTS.md\` is generated from the scan and your
439
+ \`.claude/rungate/\` config, with one exception: a \`## Hard Constraints\`
440
+ section is yours, and a re-scaffold carries it forward verbatim —
441
+ including the \`<!-- BEGIN AUTO-EXTRACTED -->\` block, and including any
442
+ lines you wrote outside it.
443
+
444
+ It was the only user-owned content in the tree that survived
445
+ regeneration until #655, which is a promise \`specs/bootstrap-data-flow/\`
446
+ makes and nothing kept until #568: one run on a consumer removed 37
447
+ constraint lines and reported \`REGENERATED: AGENTS.md\`, exit 0. Put
448
+ non-inferable project rules there — the ones an agent cannot read off the
449
+ code — and nowhere else in the file.
450
+
451
+ If a run cannot carry every one of those lines forward it **refuses the
452
+ write**, names the lines, and leaves your file untouched.
453
+
454
+ ### An agent brief is section-owned too (#655)
455
+
456
+ A rule mined from THIS repository's compliance history — the output of the
457
+ hill-climb loop — is non-inferable by construction, and until #655 it had
458
+ nowhere in the project to live. Every brief surface was rebuilt from
459
+ harness-wide inputs on the next \`bunx rungate scaffold .\`:
460
+ \`templates/agent-briefs/_shared.md\` resolves under the harness's own
461
+ templates directory, so a project rule written there reaches every
462
+ consumer; \`roles.json\`'s \`tiers.reinforcement\` carries section NAMES, not
463
+ rule text; and the write itself was a bare \`writeFileSync\`.
464
+
465
+ So \`.claude/agents/*.md\` now works the way \`AGENTS.md\` does, through the
466
+ same merge in \`lib/agents-md-sections.ts\`:
467
+
468
+ - Add a \`## Project Constraints\` heading to a brief and everything under
469
+ it, up to the next \`##\`, is yours. A re-scaffold carries it forward
470
+ verbatim and rewrites the rest.
471
+ - The section is **opt-in**. No template emits it, because a generated
472
+ section would collide with yours and the merge would refuse every run.
473
+ A heading plus one line is a section; a heading alone is not.
474
+ - If a run cannot carry every one of those lines forward it **refuses the
475
+ write**, names the lines, and leaves the brief untouched — the same
476
+ refusal-rather-than-silent-loss property #568 gave AGENTS.md.
477
+ - A reinforcement the hill-climb applies goes there in preference to
478
+ \`## Efficiency Rules\`, \`## Testing Rules\` or \`## Never Do\`, so what the
479
+ loop writes is the content a re-scaffold preserves.
480
+
481
+ The \`## Hard Constraints\` spelling is AGENTS.md's and only AGENTS.md's. A
482
+ brief section is scoped to one role; using one heading for both would make
483
+ a rule written in the wrong file look like it was in the right one.
484
+
362
485
  ### The workflow files are job-owned, not file-owned (#216)
363
486
 
364
487
  rungate owns the \`test\` job in \`ci.yml\` and the \`gates\` job in
@@ -371,6 +494,39 @@ cannot carry a job forward — a flow mapping (\`jobs: {deploy: {...}}\`), or a
371
494
  file it cannot parse — it **refuses the write**, names the jobs at risk and
372
495
  the line delta, and leaves your file untouched. Re-run with \`--force\` only
373
496
  if you mean to discard them.
497
+
498
+ ### Every workflow file is reported, owned or not (#722)
499
+
500
+ The table above is a list of files this generator **writes**. That is why a
501
+ workflow it did not write could not be added to it: the next scaffold would
502
+ either start generating the file or the row would describe behaviour the
503
+ code does not have, which is #208 exactly.
504
+
505
+ So ownership travels with the bytes instead. Each generated workflow carries
506
+ a \`# generated-sha:\` marker on its first line — a YAML comment, invisible
507
+ to anything that parses the file — and a re-scaffold reports **every** file
508
+ in \`.github/workflows/\`:
509
+
510
+ | Status | What it means |
511
+ |--------|---------------|
512
+ | generated-and-unchanged | rungate wrote it and nobody has touched it |
513
+ | generated-and-hand-edited | rungate wrote it and the bytes have moved; preserved, not rewritten |
514
+ | NOT-OWNED | no marker — rungate did not write this and does not manage it |
515
+
516
+ **A NOT-OWNED workflow is reported by name and otherwise left alone.** What
517
+ you do with it is yours; the harness only refuses to keep quiet about it.
518
+ Each name is printed individually, because "5 unowned workflows" is not
519
+ something anybody can act on.
520
+
521
+ The line also carries its own coverage — \`read N/M file(s)\` — and a
522
+ directory that could not be read reports \`UNMEASURED\` rather than an empty
523
+ list. A scan that read 2 of 7 files and a scan that read all 7 are otherwise
524
+ the same clean report, and no reader can tell them apart from the output.
525
+
526
+ This matters on a tree the harness was added to rather than one it created.
527
+ One consumer ran five \`engine: copilot\` workflows that cost money, failed on
528
+ quota and emailed its owner, and every scaffold run reported clean — not
529
+ because anything went wrong, but because nothing had ever looked.
374
530
  `,
375
531
  });
376
532
 
@@ -5,6 +5,7 @@
5
5
  * Takes scan data in, produces file content out. No file I/O.
6
6
  */
7
7
  import type { ProjectScan } from "./types";
8
+ import { localCalendarDay } from "../local-calendar-day";
8
9
 
9
10
  /**
10
11
  * Generate CODE-MAP.md content from project scan data.
@@ -12,7 +13,7 @@ import type { ProjectScan } from "./types";
12
13
  * Returns the full markdown string. Does NOT write files.
13
14
  */
14
15
  export function generateCodeMap(scan: ProjectScan): string {
15
- const today = new Date().toISOString().split("T")[0];
16
+ const today = localCalendarDay();
16
17
  const { name, dirs, deps, devDeps, modules, routes } = scan;
17
18
 
18
19
  let md = `---
@@ -17,6 +17,14 @@ export interface SpecEntry {
17
17
  file: string;
18
18
  governs: string;
19
19
  testable: string;
20
+ /**
21
+ * The spec declares `criteria: none` in its frontmatter (#579).
22
+ *
23
+ * Carried into the routing table rather than left in the file, because the
24
+ * reader harmed by a criteria-free spec is the one the table SENDS there.
25
+ * Optional so a consumer's scanner predating this still typechecks.
26
+ */
27
+ criteriaNone?: boolean;
20
28
  }
21
29
 
22
30
  export interface TestFile {
@@ -0,0 +1,55 @@
1
+ /**
2
+ * Every path's most recent commit date, from ONE git subprocess (#323).
3
+ *
4
+ * A LEAF module (#508). The implementation and its history live below,
5
+ * unchanged, moved out of `lib/conformity.ts` so a CLI can use it:
6
+ * conformity imports `bun:test` at module scope, and
7
+ * `scripts/extract-constraints.ts` runs outside a test runner. It is
8
+ * re-exported from `lib/conformity.ts`, which is the name every existing
9
+ * caller and SC-842 knows — one binding, two names, the same arrangement
10
+ * `isHarnessItself` has with `lib/harness-identity.ts` (#380).
11
+ *
12
+ * The second caller is why this moved. `computeStaleness` in
13
+ * `scripts/extract-constraints.ts` was still spawning one `git log` per
14
+ * document — the exact code #323 replaced here, in a file #323 did not
15
+ * touch — and HYGIENE-6 was timing out at 5001ms because of it.
16
+ */
17
+ import { spawnSync } from "child_process";
18
+ import { existsSync } from "fs";
19
+ import { join } from "path";
20
+
21
+ export function lastCommitDates(root: string, pathspecs: string[]): Map<string, string> {
22
+ const lastCommit = new Map<string, string>();
23
+ // Not a git repository: nothing is tracked, so no path has a commit date.
24
+ // That is a real answer, not a failure, and scaffolded projects hit it.
25
+ if (!existsSync(join(root, ".git"))) return lastCommit;
26
+ if (pathspecs.length === 0) return lastCommit;
27
+ {
28
+ const log = spawnSync(
29
+ "git",
30
+ ["-C", root, "log", "--format=%H %ci", "--name-only", "--", ...pathspecs],
31
+ { timeout: 60_000, maxBuffer: 64 * 1024 * 1024 },
32
+ );
33
+ if (log.error) {
34
+ throw new Error(`lastCommitDates: git log could not run in ${root}: ${log.error.message}`);
35
+ }
36
+ if (log.status !== 0) {
37
+ throw new Error(
38
+ `lastCommitDates: git log exited ${log.status} in ${root}: ` +
39
+ `${log.stderr?.toString().trim() || "(no stderr)"}`,
40
+ );
41
+ }
42
+ let currentDate = "";
43
+ for (const line of log.stdout.toString().split("\n")) {
44
+ const header = /^[0-9a-f]{7,40} (\d{4}-\d{2}-\d{2})/.exec(line);
45
+ if (header) {
46
+ currentDate = header[1];
47
+ continue;
48
+ }
49
+ const path = line.trim();
50
+ if (!path || !currentDate) continue;
51
+ if (!lastCommit.has(path)) lastCommit.set(path, currentDate);
52
+ }
53
+ }
54
+ return lastCommit;
55
+ }
@@ -0,0 +1,140 @@
1
+ /**
2
+ * The git-config isolation set, declared ONCE as data (#1001).
3
+ *
4
+ * ## Why this file exists rather than a second copy of a string
5
+ *
6
+ * `git` executes code out of its own configuration. `core.fsmonitor` is a
7
+ * command git runs, `core.hooksPath` points at hooks git fires, and
8
+ * `core.excludesFile` can make a file invisible to the reading that is
9
+ * supposed to see it. So **running `git` in a directory someone else chose
10
+ * means running whatever that directory's `.git/config` says**, and
11
+ * converting a shell string to an argv does nothing about it.
12
+ *
13
+ * That was measured once, under #960/#965, in a scratch repository with one
14
+ * planted untracked file (git 2.50.1):
15
+ *
16
+ * | poisoned key | written where | unisolated | isolated |
17
+ * |---|---|---|---|
18
+ * | `core.excludesFile` → a file listing the plant | `~/.gitconfig` | **plant INVISIBLE** | `?? planted.txt` |
19
+ * | `core.excludesFile` → a file listing the plant | the checkout's `.git/config` | **plant INVISIBLE** | `?? planted.txt` |
20
+ * | `core.fsmonitor` → a script touching a marker | `~/.gitconfig` | **marker written — git ran it** | not run |
21
+ * | `core.hooksPath` → a dir with `post-index-change` | `~/.gitconfig` | **hook fired** | not fired |
22
+ *
23
+ * **The lesson was learned once and propagated nowhere.** It lived as a
24
+ * single shell-prefix string inside `lib/scaffold/ai-review-step.ts`, so
25
+ * `hooks/CommitEnforcement.hook.ts` — which runs `git -C <a path out of an
26
+ * agent's reply text>` — could not reuse it even in principle: its call sites
27
+ * are `execFileSync('git', […])` and a shell prefix is not an argv.
28
+ *
29
+ * One declaration, two projections. `gitIsolatedShellPrefix()` reproduces the
30
+ * existing string exactly, so `AI_REVIEW_GIT_ISOLATED` is now derived rather
31
+ * than spelled; `gitIsolatedArgs`/`gitIsolatedEnv` serve the `execFileSync`
32
+ * callers. A second declaration of either is refused by
33
+ * `test/git-isolation.test.ts`.
34
+ *
35
+ * ## Why env vars AND `-c`, which is not belt-and-braces
36
+ *
37
+ * `GIT_CONFIG_GLOBAL`/`GIT_CONFIG_SYSTEM`/`GIT_CONFIG_NOSYSTEM` neutralise
38
+ * whole FILES, so they cover keys nobody thought to enumerate — but they do
39
+ * not touch the checkout's own `.git/config`, which is inside the tree being
40
+ * read. The `-c` flags are the only thing covering row two of the table, and
41
+ * command scope outranks local scope. **Neither covers the other.**
42
+ *
43
+ * ## `safe.directory='*'` is load-bearing, not a loosening
44
+ *
45
+ * `actions/checkout` writes `safe.directory` for the workspace into the
46
+ * GLOBAL config on every job. Neutralise the global file and that exception
47
+ * goes with it, so wherever the working tree is owned by a different uid than
48
+ * the process — containers, rootless self-hosted pools — `git` exits 128 with
49
+ * *"detected dubious ownership"*. `safe.directory` is honoured only from
50
+ * protected scopes (system, global, command), so `-c` restores it from the
51
+ * one source the subject cannot write, and the checkout's `.git/config` still
52
+ * cannot set it. Without it, isolation would be stricter than what it
53
+ * replaces in a way that fails closed on **green** repositories.
54
+ *
55
+ * ## WHAT THIS DOES NOT COVER
56
+ *
57
+ * - **Config a caller passes deliberately.** These are defaults a caller
58
+ * prepends; anything added after them wins.
59
+ * - **`git` subcommands that reach the network.** `fetch` with these env vars
60
+ * also discards a proxy, a CA bundle, or an `insteadOf` rewrite a
61
+ * self-hosted runner legitimately keeps in `~/.gitconfig`. That is a
62
+ * different trade-off and is why `buildRestoreScript` was left out of #960.
63
+ * - **The repository's CONTENT.** Isolating config is not reviewing a tree.
64
+ *
65
+ * Issue: #1001. Refs #960, #965.
66
+ */
67
+
68
+ /**
69
+ * Env vars neutralising whole config FILES.
70
+ *
71
+ * `GIT_CONFIG_NOSYSTEM=1` is not redundant with `GIT_CONFIG_SYSTEM=/dev/null`
72
+ * on every git version, so both are set.
73
+ */
74
+ export const GIT_ISOLATION_ENV: Readonly<Record<string, string>> = Object.freeze({
75
+ GIT_CONFIG_GLOBAL: "/dev/null",
76
+ GIT_CONFIG_SYSTEM: "/dev/null",
77
+ GIT_CONFIG_NOSYSTEM: "1",
78
+ });
79
+
80
+ /**
81
+ * Keys overridden at COMMAND scope, which outranks the checkout's own
82
+ * `.git/config` — the one scope the env vars above cannot reach.
83
+ *
84
+ * `core.fsmonitor` is set to the empty string rather than removed: an empty
85
+ * value is how git spells "no fsmonitor", and there is no `-c` form that
86
+ * unsets a key.
87
+ */
88
+ export const GIT_ISOLATION_CONFIG: ReadonlyArray<readonly [string, string]> = Object.freeze([
89
+ ["core.fsmonitor", ""],
90
+ ["core.excludesFile", "/dev/null"],
91
+ ["core.hooksPath", "/dev/null"],
92
+ ["safe.directory", "*"],
93
+ ] as const);
94
+
95
+ /**
96
+ * The shell-prefix projection: `VAR=… VAR=… git -c k=v …`, ready to be
97
+ * interpolated in front of a subcommand in a generated script.
98
+ *
99
+ * `safe.directory`'s value is single-quoted because `*` would otherwise be
100
+ * glob-expanded by the shell. That quoting is a property of THIS projection
101
+ * and must not leak into the argv one, where the value is passed literally —
102
+ * a `'*'` reaching git through `execFileSync` would be three characters that
103
+ * match no directory, i.e. isolation that silently does not apply.
104
+ */
105
+ export function gitIsolatedShellPrefix(): string {
106
+ const env = Object.entries(GIT_ISOLATION_ENV).map(([k, v]) => `${k}=${v}`).join(" ");
107
+ const flags = GIT_ISOLATION_CONFIG.map(([k, v]) => `-c ${k}=${shellQuoteIfGlob(v)}`).join(" ");
108
+ return `${env} git ${flags}`;
109
+ }
110
+
111
+ /** Single-quote a value a shell would otherwise expand. */
112
+ function shellQuoteIfGlob(v: string): string {
113
+ return /[*?[\]]/.test(v) ? `'${v}'` : v;
114
+ }
115
+
116
+ /**
117
+ * The argv projection: the `-c` flags, followed by whatever the caller
118
+ * passes.
119
+ *
120
+ * Pre-command options only, so a caller's own `-C <dir>` may follow in any
121
+ * order. Pair with `gitIsolatedEnv`; the flags alone leave `~/.gitconfig`
122
+ * live, and the env alone leaves the checkout's `.git/config` live.
123
+ */
124
+ export function gitIsolatedArgs(args: readonly string[] = []): string[] {
125
+ const flags: string[] = [];
126
+ for (const [k, v] of GIT_ISOLATION_CONFIG) flags.push("-c", `${k}=${v}`);
127
+ return [...flags, ...args];
128
+ }
129
+
130
+ /**
131
+ * `base` with the isolation vars applied on top.
132
+ *
133
+ * Takes the base environment as a parameter rather than reading
134
+ * `process.env`, so a case can drive it without touching the machine's.
135
+ */
136
+ export function gitIsolatedEnv(
137
+ base: NodeJS.ProcessEnv = process.env,
138
+ ): NodeJS.ProcessEnv {
139
+ return { ...base, ...GIT_ISOLATION_ENV };
140
+ }
package/lib/github.ts CHANGED
@@ -37,6 +37,21 @@ export interface GitHubClient {
37
37
  update: (params: { owner: string; repo: string; pull_number: number; [key: string]: any }) => Promise<{ data: any }>;
38
38
  list: (params: { owner: string; repo: string; [key: string]: any }) => Promise<{ data: any[] }>;
39
39
  };
40
+ repos: {
41
+ /** Repository metadata. `owner.type` and `default_branch` are what PROTECT-1 reads (#909). */
42
+ get: (params: { owner: string; repo: string }) => Promise<{ data: any }>;
43
+ /**
44
+ * One branch. Carries `protected`, and needs only read access (#909).
45
+ *
46
+ * Asked BEFORE `getBranchProtection`, which needs admin: a 404 from the
47
+ * protection endpoint means "unprotected" or "you are not an admin"
48
+ * with no way to tell which, and conflating those would let a token
49
+ * without admin report every repo clean.
50
+ */
51
+ getBranch: (params: { owner: string; repo: string; branch: string }) => Promise<{ data: any }>;
52
+ /** Branch protection. Requires admin on the repo; 403 for everyone else. */
53
+ getBranchProtection: (params: { owner: string; repo: string; branch: string }) => Promise<{ data: any }>;
54
+ };
40
55
  checks: {
41
56
  /**
42
57
  * Check runs for one ref (#46).