rungate 0.4.1 → 0.6.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 (87) hide show
  1. package/config/behavioral-sc-map.json +170 -0
  2. package/config/brief-policies.json +28 -0
  3. package/config/ceremony-profiles.json +207 -0
  4. package/config/check-registry.json +114 -0
  5. package/config/matcher-registry.json +142 -0
  6. package/config/prove-evidence.schema.json +65 -0
  7. package/config/spec-policies.json +36 -0
  8. package/config/universal-rules.yaml +15 -0
  9. package/config/workflow-schema.json +279 -0
  10. package/lib/agents-md-sections.ts +144 -0
  11. package/lib/branch-diff.ts +139 -0
  12. package/lib/bun-version.ts +268 -0
  13. package/lib/ci-checkout.ts +1 -1
  14. package/lib/cli-commands.ts +7 -1
  15. package/lib/compliance.ts +13 -11
  16. package/lib/config-loader.ts +12 -0
  17. package/lib/conformity.ts +1147 -116
  18. package/lib/context-docs.ts +143 -28
  19. package/lib/create-brief.ts +2 -1
  20. package/lib/create-sc.ts +90 -4
  21. package/lib/doc-scan-targets.ts +9 -0
  22. package/lib/evidence-command-transport.ts +160 -0
  23. package/lib/evidence-prevalidator.ts +22 -0
  24. package/lib/fallow-availability.ts +129 -0
  25. package/lib/gate-refusal-currency.ts +112 -0
  26. package/lib/gate-timeouts.ts +82 -0
  27. package/lib/generators/agent-briefs.ts +4 -1
  28. package/lib/generators/agents-md.ts +71 -23
  29. package/lib/generators/code-map.ts +2 -1
  30. package/lib/generators/types.ts +8 -0
  31. package/lib/git-dates.ts +55 -0
  32. package/lib/github.ts +195 -0
  33. package/lib/js-top-level-code.ts +27 -2
  34. package/lib/junit-checks.ts +484 -0
  35. package/lib/local-calendar-day.ts +78 -0
  36. package/lib/package-closure.ts +278 -2
  37. package/lib/project-state-shape.ts +59 -0
  38. package/lib/promote-outputs.ts +6 -2
  39. package/lib/release-preflight.ts +196 -0
  40. package/lib/report-provenance.ts +156 -0
  41. package/lib/sc-claim-forms.ts +75 -0
  42. package/lib/sc-id-cross-tree.ts +311 -0
  43. package/lib/scaffold/ai-review-step.ts +180 -0
  44. package/lib/scaffold/defaults.ts +40 -0
  45. package/lib/scaffold/managed-workflow.ts +125 -27
  46. package/lib/scaffold/owned-files.ts +48 -2
  47. package/lib/scaffold/profiles.ts +94 -0
  48. package/lib/scaffold/rehearsal.ts +232 -73
  49. package/lib/scaffold/steps.ts +777 -152
  50. package/lib/scaffold/write-steps.ts +56 -13
  51. package/lib/scanner.ts +38 -12
  52. package/lib/source-anchor.ts +144 -0
  53. package/lib/spec-listing.ts +148 -0
  54. package/lib/spec-requirements.ts +209 -0
  55. package/lib/success-doc.ts +779 -0
  56. package/lib/suite-run-reading.ts +364 -0
  57. package/lib/test-census.ts +199 -0
  58. package/lib/test-command.ts +133 -0
  59. package/lib/test-suite-lock.ts +166 -10
  60. package/lib/tool-probe.ts +120 -0
  61. package/lib/tracked-vs-ignored.ts +234 -0
  62. package/lib/trajectory.ts +377 -0
  63. package/lib/validators/spec-validators.ts +35 -6
  64. package/lib/workflow-security.ts +101 -0
  65. package/lib/workflow-test-harness.ts +349 -0
  66. package/package.json +6 -1
  67. package/scripts/audit-specs.ts +247 -12
  68. package/scripts/audit-transcript.ts +2 -1
  69. package/scripts/convert-spec.ts +2 -1
  70. package/scripts/create-sc.ts +17 -7
  71. package/scripts/create-spec.ts +2 -1
  72. package/scripts/create-success.ts +163 -0
  73. package/scripts/extract-constraints.ts +90 -19
  74. package/scripts/generate-code-map.ts +53 -12
  75. package/scripts/scaffold-project.ts +31 -4
  76. package/scripts/split-spec.ts +2 -1
  77. package/scripts/sync-sc-status.ts +57 -5
  78. package/scripts/sync-spec-tests.ts +2 -1
  79. package/specs/SPEC-TEMPLATE.md +200 -0
  80. package/templates/SUCCESS-TEMPLATE.md +72 -0
  81. package/templates/agent-briefs/_shared.md +9 -0
  82. package/templates/agent-briefs/aditi.md +46 -0
  83. package/templates/agent-briefs/discovery.md +37 -0
  84. package/templates/agent-briefs/marcus.md +39 -0
  85. package/templates/agent-briefs/quinn.md +67 -0
  86. package/templates/agent-briefs/rook.md +40 -0
  87. package/templates/agent-briefs/serena.md +39 -0
@@ -0,0 +1,129 @@
1
+ /**
2
+ * Whether `fallow` can be run without reaching the network (#581).
3
+ *
4
+ * `fallow` is an optional external tool and is NOT a declared dependency —
5
+ * not in `package.json`, not in `node_modules/.bin`, not on `PATH`, on this
6
+ * machine or on CI. So every bare `npx fallow` is a registry fetch.
7
+ *
8
+ * `lib/conformity.ts` learned that in its own words:
9
+ *
10
+ * > When it is absent, `npx fallow` does a registry fetch on every
11
+ * > invocation — four tests x one fetch each, each outliving bun's
12
+ * > per-test timeout. … Resolve it locally instead, with no network path.
13
+ *
14
+ * and then kept the fix to itself. `scripts/generate-code-map.ts` — the
15
+ * caller on the **scaffold** path, which runs once per consumer forever
16
+ * rather than four times in a suite — still spawned `npx fallow`
17
+ * unconditionally. So the fix landed in the cheap caller and not in the
18
+ * expensive one, and the cost of that is not a slow test: a consumer
19
+ * scaffolding behind a proxy, in an air-gapped CI, or on a bad connection
20
+ * gets a 30-second stall and then a silently degraded CODE-MAP, with nothing
21
+ * in the output saying a network call was attempted.
22
+ *
23
+ * It also made the suite non-deterministic. PR #580 — three state files, no
24
+ * code — went red on `SC-1665`, which asserts that `.fallow/cache.bin` was
25
+ * produced by both of two scaffold runs; when the fetch fails it is produced
26
+ * by neither. Reproduced with no repo change at all:
27
+ *
28
+ * npm_config_registry=http://127.0.0.1:1/ bun test test/scaffold-relative-root.test.ts
29
+ * error: .fallow/cache.bin is excluded but was not produced by both runs
30
+ *
31
+ * ## One binding
32
+ *
33
+ * This module exists rather than an export from `lib/conformity.ts` because
34
+ * conformity imports `bun:test` at module scope and so cannot be imported by
35
+ * a CLI. Same arrangement as `lib/git-dates.ts` (#508) and
36
+ * `lib/harness-identity.ts` (#380): one implementation, re-exported, because
37
+ * two answers to one question are behaviourally one and no test can tell
38
+ * them apart.
39
+ */
40
+
41
+ import { existsSync } from "fs";
42
+ import { join } from "path";
43
+
44
+ /**
45
+ * Memoised PER ROOT.
46
+ *
47
+ * `runFallowCheck` is exported and consumer projects call it with their own
48
+ * root, so a single process can ask about several. A root-independent cache
49
+ * would answer for the wrong directory.
50
+ */
51
+ const FALLOW_AVAILABLE = new Map<string, boolean>();
52
+
53
+ export function fallowAvailable(root: string): boolean {
54
+ const cached = FALLOW_AVAILABLE.get(root);
55
+ if (cached !== undefined) return cached;
56
+ const available = existsSync(join(root, "node_modules", ".bin", "fallow")) || Bun.which("fallow") !== null;
57
+ FALLOW_AVAILABLE.set(root, available);
58
+ return available;
59
+ }
60
+
61
+ /** Test seam: drop the memo so a case can change the answer. */
62
+ export function resetFallowAvailability(): void {
63
+ FALLOW_AVAILABLE.clear();
64
+ }
65
+
66
+ /**
67
+ * Why a fallow-derived reading is missing, or null when it is not missing.
68
+ *
69
+ * Three outcomes, not two. `null` from the old `runFallow()` meant "not
70
+ * installed", "the spawn failed", "the output did not parse" and "it ran and
71
+ * found nothing" all at once, and a CODE-MAP written from it was
72
+ * byte-identical in every case — which is
73
+ * `.claude/rules/config-access.md`'s *Silent Default Substitution* with a
74
+ * document as the victim.
75
+ */
76
+ export type FallowUnavailable =
77
+ | { kind: "not-installed"; reason: string }
78
+ | { kind: "run-failed"; reason: string };
79
+
80
+ export function fallowNotInstalled(): FallowUnavailable {
81
+ return {
82
+ kind: "not-installed",
83
+ reason:
84
+ "fallow is not installed (it is an optional tool, not a declared dependency) — " +
85
+ "no static analysis was run, and no registry fetch was attempted",
86
+ };
87
+ }
88
+
89
+ /**
90
+ * A tool's output, made safe to put in a document an agent reads.
91
+ *
92
+ * The `run-failed` reason quotes what fallow printed, and that string ends
93
+ * up inside CODE-MAP.md — which `.claude/rules/key-files.md` tells every
94
+ * agent to read to understand the codebase. So it is untrusted text on its
95
+ * way into a trusted document, and fallow's error text can quote the repo's
96
+ * own file names and contents.
97
+ *
98
+ * One line, an allowlist, and a cap. Not an escape routine: a denylist of
99
+ * markdown syntax is a detector narrower than what it detects, and the
100
+ * useful content of a tool error survives an allowlist intact.
101
+ */
102
+ export function safeToolDetail(raw: string): string {
103
+ const firstLine = raw.split("\n")[0] ?? "";
104
+ // A RUN of disallowed characters collapses to one `?`, rather than one
105
+ // `?` each. Both are safe; the difference is whether a detail that was
106
+ // entirely unprintable comes back as `????????` — which carries no
107
+ // information and is indistinguishable from a tool that said something.
108
+ const cleaned = firstLine.replace(/[^A-Za-z0-9 .,:;()/'"=+-]+/g, "?").slice(0, 120).trim();
109
+ return /^[?\s]*$/.test(cleaned) ? "(no printable detail)" : cleaned;
110
+ }
111
+
112
+ export function fallowRunFailed(detail: string): FallowUnavailable {
113
+ return {
114
+ kind: "run-failed",
115
+ reason: `fallow is installed but the run did not produce a reading: ${safeToolDetail(detail)}`,
116
+ };
117
+ }
118
+
119
+ /**
120
+ * The line a generated document carries in place of a section it could not
121
+ * produce.
122
+ *
123
+ * UNMEASURED by name. An omitted section and a section reporting nothing
124
+ * wrong are the same absence to a reader, and the reader of a CODE-MAP is an
125
+ * agent deciding whether this project has dead code.
126
+ */
127
+ export function fallowUnmeasuredNotice(u: FallowUnavailable): string {
128
+ return `## Code Health (fallow)\n\n**UNMEASURED** — ${u.reason}.`;
129
+ }
@@ -0,0 +1,112 @@
1
+ /**
2
+ * Which recorded refusals are still true at the end of the run (#532).
3
+ *
4
+ * The ship gate RE-RUNS the verify checks. `runGateTests` spawns
5
+ * `bun test gates/ --test-name-pattern "schema|scope|verify|ship|B1|B2"` for
6
+ * the ship gate, so every `verify checks > …` name is measured a second
7
+ * time, later, against a tree the heal rounds have since changed.
8
+ *
9
+ * Measured on run `wf_e230fddc-a71`:
10
+ *
11
+ * | Check | `gates.verify.failures` | `gates.ship.failures` |
12
+ * |---|---|---|
13
+ * | `verify checks > tests-pass` | FAIL | FAIL |
14
+ * | `verify checks > evidence-prevalidation` | **FAIL** | **absent** |
15
+ * | `verify checks > tsc-pass` | FAIL | FAIL |
16
+ *
17
+ * `state.evidencePrevalidation` in that same file reads
18
+ * `{"verdict":"PASS", acs: [… all "ok" …]}`. The refusal was round one, a
19
+ * heal fixed it, the ship gate re-ran it and it passed — and the terminal
20
+ * report listed it anyway, because the report is the UNION of every gate's
21
+ * list rather than the latest reading of each check.
22
+ *
23
+ * The run returned 19 refusals. Several were already resolved, so the real
24
+ * count was smaller, and the one that actually blocked the run — a
25
+ * `SECURITY_REVIEW_STALE` — was buried among them. A report with false
26
+ * entries in it is a report nobody reads twice.
27
+ *
28
+ * ## Absence is not a pass
29
+ *
30
+ * The whole thing turns on one distinction, and getting it wrong is worse
31
+ * than the bug it fixes: a check missing from a later gate's FAILURES means
32
+ * either *it passed there* or *that gate never ran it*. Those are opposite
33
+ * facts and a failure list cannot tell them apart. Retiring on absence
34
+ * would silently drop every refusal a later gate's narrower pattern skipped.
35
+ *
36
+ * So retirement requires a positive witness — `checksRun`, the names the
37
+ * later gate reported a verdict for, recorded by `gates/orchestrator.ts`
38
+ * from the same `results` array the failures come from. A gate with no
39
+ * `checksRun` retires NOTHING. `null` and `[]` are different answers here
40
+ * and only one of them is a measurement
41
+ * (.claude/rules/config-access.md, Silent Default Substitution).
42
+ *
43
+ * ## Why this is duplicated into ship.js
44
+ *
45
+ * `workflows/ship.js` runs in a sandbox with no module loading (#69), so it
46
+ * cannot import this. It carries an inlined copy inside
47
+ * `REFUSAL-CURRENCY` markers, and `test/gate-refusal-currency.test.ts`
48
+ * extracts that copy, executes it, and runs both over one input matrix —
49
+ * the same technique `test/suite-measurement-parity.test.ts` uses for
50
+ * `suiteCurrency`, and for the same reason: two copies of a rule is a
51
+ * defect waiting for one of them to drift, and the drift is silent.
52
+ */
53
+
54
+ /** What a gate run reported back: the names it measured and the ones it failed. */
55
+ export interface GateReport {
56
+ checksRun?: unknown;
57
+ failedChecks?: unknown;
58
+ }
59
+
60
+ /** One recorded refusal. `check` is absent for refusals no gate produced. */
61
+ export interface RefusalEntry {
62
+ check?: unknown;
63
+ [k: string]: unknown;
64
+ }
65
+
66
+ /**
67
+ * The checks a gate ran and did NOT fail — the only thing that can retire an
68
+ * earlier refusal.
69
+ *
70
+ * `null` when the gate reported no `checksRun`, and that is the
71
+ * load-bearing return rather than an empty array: a caller has to be able
72
+ * to tell "this gate said nothing about what it ran" from "this gate ran
73
+ * nothing".
74
+ */
75
+ export function resolvedCheckNames(report: GateReport | null | undefined): string[] | null {
76
+ if (!report || !Array.isArray(report.checksRun)) return null;
77
+ const failed = new Set(
78
+ (Array.isArray(report.failedChecks) ? report.failedChecks : []).filter(
79
+ (c: unknown): c is string => typeof c === "string" && c !== "",
80
+ ),
81
+ );
82
+ return report.checksRun.filter(
83
+ (c: unknown): c is string => typeof c === "string" && c !== "" && !failed.has(c),
84
+ );
85
+ }
86
+
87
+ /**
88
+ * Remove, IN PLACE, every earlier refusal about a check this gate re-ran and
89
+ * did not reproduce. Returns the entries it removed.
90
+ *
91
+ * In place because the ledger is one array the whole run appends to, and
92
+ * returning a copy would leave the original to be reported by whichever
93
+ * reader got there first. The removed entries are returned rather than
94
+ * discarded: a refusal that was retired is a thing an operator may want to
95
+ * see, and silently shortening a list is how a report stops being checkable.
96
+ */
97
+ export function retireSupersededRefusals(
98
+ entries: RefusalEntry[],
99
+ report: GateReport | null | undefined,
100
+ ): RefusalEntry[] {
101
+ const resolved = resolvedCheckNames(report);
102
+ if (resolved === null || resolved.length === 0) return [];
103
+ const names = new Set(resolved);
104
+ const dropped: RefusalEntry[] = [];
105
+ for (let i = entries.length - 1; i >= 0; i--) {
106
+ const check = entries[i]?.check;
107
+ if (typeof check === "string" && check !== "" && names.has(check)) {
108
+ dropped.unshift(entries.splice(i, 1)[0]);
109
+ }
110
+ }
111
+ return dropped;
112
+ }
@@ -0,0 +1,82 @@
1
+ /**
2
+ * The gate run's three nested time budgets, and the order they must be in (#550).
3
+ *
4
+ * A gate check is three processes deep, and each layer can kill the one
5
+ * inside it. Before this file the three numbers were written in three places
6
+ * by three issues and **two of the three orderings were backwards**:
7
+ *
8
+ * | Layer | Was | Where |
9
+ * |---|---|---|
10
+ * | the compiler `tsc-pass` spawns | 240000 | `gates/workflow.test.ts` |
11
+ * | the `test()` around that spawn | 5000 (bun's default) | nowhere — undeclared |
12
+ * | the whole `bun test gates/` run | 120000 | `gates/gate-executor.ts` |
13
+ *
14
+ * So the compiler was allowed four minutes by a call killed after five
15
+ * seconds, inside a run killed after two. `tsc-pass` **could not pass on any
16
+ * project whose typecheck takes longer than five seconds**, which is every
17
+ * project large enough to have a gate run. Observed live: the check printed
18
+ * `Type check PASS: bunx tsc --noEmit` to its own stdout and recorded FAIL,
19
+ * and the timeout line that said why was attributed to the NEXT check by the
20
+ * parser (the other half of #550).
21
+ *
22
+ * Nothing could say so, because a timeout and a genuine failure are the same
23
+ * red, and the 240000 beside the spawn reads as deliberate.
24
+ *
25
+ * **The rule is one line: each layer must strictly outlive the one inside
26
+ * it.** Equal is not enough — a spawn killed at the same instant as its test
27
+ * is a race, and which of the two messages you get is not decided by this
28
+ * repo.
29
+ *
30
+ * Declared here, once, so the ordering is a property of four exported
31
+ * constants rather than of four numbers nobody reads together. The numbers
32
+ * themselves are judgement, and the judgement is written down:
33
+ *
34
+ * - `EXEC_TIMEOUT_MS` — the `git`/shell helpers. Unchanged at 30s; these are
35
+ * local repository reads and one that takes longer is hung, not slow.
36
+ * - `TYPECHECK_TIMEOUT_MS` — 90s, LOWERED from 240s. 240 was never reachable,
37
+ * and a single check is not entitled to twice the whole gate's budget.
38
+ * - `GATE_TEST_TIMEOUT_MS` — 120s, the per-test default. Declared at file
39
+ * level with `setDefaultTimeout` and not as a per-test argument, because
40
+ * `}, 120000);` on `tsc-pass` alone covers exactly one check and the next
41
+ * spawning check added inherits nothing. A rule naming one test is a rule
42
+ * the next one evades.
43
+ * - `GATE_SUITE_TIMEOUT_MS` — 180s, RAISED from 120s, so the outer kill is
44
+ * above the per-test budget rather than below it.
45
+ */
46
+
47
+ /** `exec`, `execArgv`, `execArgvOf` — local git and shell reads. */
48
+ export const EXEC_TIMEOUT_MS = 30_000;
49
+
50
+ /** `bunx tsc --noEmit`, the slowest single subprocess a check starts. */
51
+ export const TYPECHECK_TIMEOUT_MS = 90_000;
52
+
53
+ /** The per-test default for `gates/workflow.test.ts`. */
54
+ export const GATE_TEST_TIMEOUT_MS = 120_000;
55
+
56
+ /** The whole `bun test gates/` run, spawned by `runGateTests`. */
57
+ export const GATE_SUITE_TIMEOUT_MS = 180_000;
58
+
59
+ /**
60
+ * The ordering, as a function so it can be driven over values that are not
61
+ * these ones — otherwise the check compares the constants against themselves
62
+ * and no mutation of them can be observed.
63
+ */
64
+ export function gateTimeoutOrderingViolations(t: {
65
+ exec: number;
66
+ typecheck: number;
67
+ test: number;
68
+ suite: number;
69
+ }): string[] {
70
+ const layers: Array<[string, number, string, number]> = [
71
+ ["the exec helpers", t.exec, "the typecheck spawn", t.typecheck],
72
+ ["the typecheck spawn", t.typecheck, "the test around it", t.test],
73
+ ["the test", t.test, "the gate suite run", t.suite],
74
+ ];
75
+ return layers
76
+ .filter(([, inner, , outer]) => !(inner < outer))
77
+ .map(
78
+ ([innerName, inner, outerName, outer]) =>
79
+ `${innerName} is allowed ${inner}ms inside ${outerName}'s ${outer}ms — the inner process ` +
80
+ `outlives the thing that started it, so it is killed before it can report (#550)`,
81
+ );
82
+ }
@@ -65,7 +65,10 @@ export function generateAgentBriefs(scan: ProjectScan): Record<string, string> {
65
65
  const harness = scan.harnessConfig;
66
66
  const devUi = harness?.dev?.uiBase || null;
67
67
  const devApi = harness?.dev?.apiBase || null;
68
- const testCmd = harness?.dev?.testCmd || scan.testCmd || "bun test";
68
+ // #488 — `scan.testCmd` already IS the decision: `testCommandDecision`
69
+ // puts `dev.testCmd` on its first rung, so re-asking here was a second
70
+ // ladder that could disagree with the first and never be noticed.
71
+ const testCmd = scan.testCmd || "bun test";
69
72
  const typeCheck = harness?.dev?.typeCheck || "bunx tsc --noEmit";
70
73
  const pages = harness?.pages || {};
71
74
  const pagesTable = Object.keys(pages).length > 0
@@ -13,6 +13,7 @@ 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";
16
17
 
17
18
  /**
18
19
  * Build the AGENTS.md frontmatter block.
@@ -22,34 +23,37 @@ import { typecheckDecision } from "../typescript-project";
22
23
  * drop a hand-set owner, and emitting nothing — the previous behavior —
23
24
  * stripped the block entirely on every re-scaffold.
24
25
  */
26
+ export function existingFrontmatter(root: string): Record<string, string> {
27
+ const path = join(root, "AGENTS.md");
28
+ const existing: Record<string, string> = {};
29
+ if (!existsSync(path)) return existing;
30
+ const content = readFileSync(path, "utf-8");
31
+ const match = content.match(/^---\n([\s\S]*?)\n---\n/);
32
+ if (!match) return existing;
33
+ for (const line of match[1].split("\n")) {
34
+ const kv = line.match(/^([\w-]+):\s*(.*)$/);
35
+ if (!kv) continue;
36
+ const value = kv[2].trim();
37
+ // Carry forward only simple scalars. The block is re-emitted verbatim,
38
+ // so a value holding a delimiter or control character could terminate
39
+ // the frontmatter early and turn the rest of the file into a second
40
+ // document — or smuggle keys past this loop on the next round-trip.
41
+ if (value.includes("---") || /[\x00-\x1f]/.test(value)) continue;
42
+ if (value.length > 200) continue;
43
+ existing[kv[1]] = value;
44
+ }
45
+ return existing;
46
+ }
47
+
25
48
  function buildFrontmatter(root: string): string {
26
- const today = new Date().toISOString().slice(0, 10);
49
+ const today = localCalendarDay();
27
50
  const defaults: Record<string, string> = {
28
51
  "doc-type": "reference",
29
52
  status: "active",
30
53
  updated: today,
31
54
  };
32
55
 
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
- }
56
+ const existing = existingFrontmatter(root);
53
57
 
54
58
  const merged: Record<string, string> = { ...defaults, ...existing, updated: today };
55
59
  const order = ["doc-type", "status", "owner", "updated"];
@@ -76,7 +80,23 @@ export function generateAgentsMd(scan: ProjectScan): string {
76
80
  } = scan;
77
81
 
78
82
  const techLine = techStack.length > 0 ? `\n**Tech:** ${techStack.join(", ")}` : "";
79
- const repoLine = repoUrl ? `- **Repo:** ${repoUrl}` : "<!-- TODO: Add repo URL -->";
83
+
84
+ // #552. `scan.repoUrl` is `git remote get-url origin`, and a project with
85
+ // no remote called `origin` gets `""` — which this line turned into
86
+ // `<!-- TODO: Add repo URL -->`, twice, on every single run, with NOWHERE
87
+ // for the consumer to put the answer. `--profile=minimal` writes no
88
+ // `.claude/rungate/`, so there was no config key either, and editing
89
+ // AGENTS.md is futile because the next run regenerates it.
90
+ //
91
+ // The frontmatter is the place, because it is the one part of this file
92
+ // that already survives regeneration: `buildFrontmatter` carries forward
93
+ // every simple scalar the existing block declared. So `repo:` written once
94
+ // by hand persists, and the git remote stays the default when there is one.
95
+ const declaredRepo = existingFrontmatter(scan.root).repo;
96
+ const effectiveRepoUrl = repoUrl || (declaredRepo ?? "");
97
+ const repoLine = effectiveRepoUrl
98
+ ? `- **Repo:** ${effectiveRepoUrl}`
99
+ : "<!-- TODO: Add repo URL — set `repo:` in this file's frontmatter, which survives regeneration -->";
80
100
 
81
101
  const consumerSection = consumers.length > 0
82
102
  ? `\n## Consumers (${consumers.length})\n\n${consumers.map(c => `- ${c}`).join("\n")}\n\nCheck cascade impact when modifying shared modules.`
@@ -284,7 +304,16 @@ If Skill("harness") or Skill("goal") fails, fall back to Skill("ship") with the
284
304
  });
285
305
 
286
306
  if (specs.length > 0) {
287
- const specsTable = specs.map(s => `| ${s.file} | ${s.governs} | ${s.testable} |`).join("\n");
307
+ // A row that sends a reader to a document stating no requirements says so
308
+ // in the row (#579). `specs/PROJECT-STATE.md` sat here for two months as
309
+ // the governing spec for project state management while being a rendered
310
+ // status snapshot, and the table was the reason anyone went there.
311
+ const specsTable = specs
312
+ .map(s => {
313
+ const governs = s.criteriaNone ? `STATES NO CRITERIA — ${s.governs}` : s.governs;
314
+ return `| ${s.file} | ${governs} | ${s.testable} |`;
315
+ })
316
+ .join("\n");
288
317
  rules.push({
289
318
  filename: "specs-routing.md",
290
319
  content: `---
@@ -357,8 +386,27 @@ ${ownedFilesTable()}
357
386
  | regenerate | Rewrites it every run; reports CHANGED only when the bytes differ |
358
387
  | provenance | Rewrites it unless you edited it, in which case it is preserved and reported (#370) |
359
388
  | job-preserving | Owns named jobs inside a file you also write to; your jobs are carried forward |
389
+ | section-preserving | Rewrites the file every run except for named sections, which are carried forward verbatim |
360
390
  | create-only | Seeds it once and never touches it again — the content is yours, not the harness's |
361
391
 
392
+ ### AGENTS.md is section-owned (#568)
393
+
394
+ Everything in \`AGENTS.md\` is generated from the scan and your
395
+ \`.claude/rungate/\` config, with one exception: a \`## Hard Constraints\`
396
+ section is yours, and a re-scaffold carries it forward verbatim —
397
+ including the \`<!-- BEGIN AUTO-EXTRACTED -->\` block, and including any
398
+ lines you wrote outside it.
399
+
400
+ That is the only user-owned content in the tree that survives
401
+ regeneration, which is a promise \`specs/bootstrap-data-flow/\` makes and
402
+ nothing kept until #568: one run on a consumer removed 37 constraint
403
+ lines and reported \`REGENERATED: AGENTS.md\`, exit 0. Put non-inferable
404
+ project rules there — the ones an agent cannot read off the code — and
405
+ nowhere else in the file.
406
+
407
+ If a run cannot carry every one of those lines forward it **refuses the
408
+ write**, names the lines, and leaves your file untouched.
409
+
362
410
  ### The workflow files are job-owned, not file-owned (#216)
363
411
 
364
412
  rungate owns the \`test\` job in \`ci.yml\` and the \`gates\` job in
@@ -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
+ }