rungate 0.6.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 (113) 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 +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. package/scripts/sync-sc-status.ts +77 -16
@@ -0,0 +1,232 @@
1
+ /**
2
+ * Can this module write to the filesystem? (#968, hardening #323 SC-6.)
3
+ *
4
+ * ## Why this exists
5
+ *
6
+ * `test/scratch-paths-unique.test.ts` excludes itself from its own scan,
7
+ * because its negative fixtures are source text and the detector reads its
8
+ * own test data as violations. An unchecked exclusion is how an exemption
9
+ * becomes a hole, so the exclusion is paired with a case asserting the file
10
+ * creates nothing. That case was:
11
+ *
12
+ * ```ts
13
+ * const fsImport = /import\s*\{([^}]*)\}\s*from\s*"fs";/.exec(self);
14
+ * ```
15
+ *
16
+ * `exec` returns the FIRST match. MEASURED by mutating the real file and
17
+ * running it: adding `import { mkdirSync } from "fs";` as a SECOND import
18
+ * leaves the suite at 8 pass / 0 fail, and so does
19
+ * `import { mkdirSync } from "node:fs";`. The file gains a write primitive
20
+ * and the case that exists to notice stays green.
21
+ *
22
+ * One claim in #968 did NOT reproduce and is recorded here so it is not
23
+ * re-fixed: the old check does not fail open. Replacing the braced import
24
+ * with `import * as fs from "fs"` makes `exec` return null, and the
25
+ * `.not.toBeNull()` line goes red — 1 fail, measured. The defect is the first
26
+ * match, not the missing match.
27
+ *
28
+ * ## Capability, not use
29
+ *
30
+ * This reports what the module CAN do, not what it does. An imported but
31
+ * uncalled `mkdirSync` is reported, deliberately: the exclusion it guards is
32
+ * about what the file could hide, and "imported but currently unused" is one
33
+ * edit away from used. That is also what the regex it replaces did, so the
34
+ * false-positive surface is unchanged on that axis.
35
+ *
36
+ * ## Why an AST
37
+ *
38
+ * The file being checked is full of `mkdtempSync(` and `rmSync(` as STRING
39
+ * DATA — its own negative fixtures. A source-text count reads them as calls;
40
+ * the old check sidestepped that by reading only the import list, which is
41
+ * what made it blind to the second import. In an AST a string is a `Literal`
42
+ * and a call is a `CallExpression`, so the detector can read both the imports
43
+ * and the calls without its fixtures lying to it.
44
+ *
45
+ * `null` means the source did not parse — a REFUSAL, distinct from `[]`.
46
+ *
47
+ * ## WHAT THIS DOES NOT COVER (stated, because an unstated boundary reads as
48
+ * coverage, and a clean report from an incomplete detector is worse than no
49
+ * detector — #968's own thesis)
50
+ *
51
+ * MEASURED against the current implementation, each of these returns `[]`:
52
+ *
53
+ * - **An indirection through a variable.** `const w = mkdirSync` after a
54
+ * read-only import, `const m = await import("fs"); m.mkdirSync(…)`, or a
55
+ * write primitive received as a function argument. Only bindings created
56
+ * by an import statement, `require` or `Bun.*` are read.
57
+ * - **A write primitive re-exported by a local module.** `import { write }
58
+ * from "./helpers"` is not an fs module and is not reported, by design —
59
+ * the alternative is following the import graph, which this is not.
60
+ * - **`process.binding`, `Deno.*`, raw syscalls, and native addons.**
61
+ * - **A write performed by code this module merely CALLS.** The reading is
62
+ * per-module, not transitive.
63
+ *
64
+ * What IS covered, and measured: named/namespace/default imports from `fs`,
65
+ * `node:fs`, `fs/promises`, `node:fs/promises`; `require()` and dynamic
66
+ * `import()` of those; `child_process` and `node:child_process`; and
67
+ * `Bun.write`, `Bun.$`, `Bun.spawn`, `Bun.spawnSync`.
68
+ *
69
+ * The consumer that matters — `test/scratch-paths-unique.test.ts` — holds
70
+ * none of the uncovered forms, and the covered set includes every form that
71
+ * file could plausibly acquire. The gap is bounded by the thing it guards
72
+ * rather than argued away.
73
+ */
74
+
75
+ import { type AstNode, calleeRoot, parseTsModule, walkNodes } from "./ts-ast";
76
+
77
+ /** Module specifiers that resolve to node's filesystem API. */
78
+ const FS_MODULES = new Set(["fs", "node:fs", "fs/promises", "node:fs/promises"]);
79
+
80
+ /**
81
+ * Named exports of `fs` that CANNOT modify the filesystem. Everything else
82
+ * an fs module exports is treated as a write capability.
83
+ *
84
+ * ## The ratchet direction, which is the whole point of this list
85
+ *
86
+ * This was an allowlist of write names, and an allowlist has its default
87
+ * pointing the wrong way: every export node adds in future arrives
88
+ * classified as safe, silently, and the detector reports clean on it. The
89
+ * list was already five short — MEASURED on the allowlist version, all of
90
+ * `link`, `chmod`, `utimes`, `writev` and `ftruncate` returned `[]`.
91
+ *
92
+ * Inverted, an unknown name is a write. A name on THIS list is a name
93
+ * somebody considered and classified, which is the property an exemption
94
+ * list has and an allowlist does not: naming what is exempt is evidence the
95
+ * entry was looked at, naming what is safe is not.
96
+ *
97
+ * The cost of the inversion is false positives on read-only exports not
98
+ * listed here, and it is measured rather than asserted — see the census in
99
+ * the PR and the over-report cases in
100
+ * `test/fs-write-capabilities.test.ts`. `readFileSync` and `readdirSync` are
101
+ * how the detector's own consumer does its job and must not be refused.
102
+ */
103
+ const FS_READ_ONLY_NAMES = new Set([
104
+ "access", "accessSync",
105
+ "createReadStream",
106
+ "exists", "existsSync",
107
+ "lstat", "lstatSync",
108
+ "opendir", "opendirSync",
109
+ "readFile", "readFileSync",
110
+ "readdir", "readdirSync",
111
+ "readlink", "readlinkSync",
112
+ "realpath", "realpathSync",
113
+ "stat", "statSync",
114
+ "statfs", "statfsSync",
115
+ "watch", "watchFile",
116
+ // Added after the inversion's census over 667 files flagged them. Both are
117
+ // genuinely read-only and were the ONLY false positives the inversion
118
+ // introduced: `glob` enumerates, `close` releases a descriptor. They are
119
+ // listed rather than quietly tolerated, which is exactly the property the
120
+ // inverted list is for — a name here is a name somebody classified.
121
+ "glob", "globSync",
122
+ "close", "closeSync",
123
+ "fstat", "fstatSync",
124
+ // Type-only and constant exports, which carry no capability at all.
125
+ "constants", "Dirent", "Dir", "Stats", "promises",
126
+ ]);
127
+
128
+ /**
129
+ * Modules whose exports can write without touching `fs` — a shell or a
130
+ * spawn is a write capability however it is spelled.
131
+ */
132
+ const PROCESS_MODULES = new Set([
133
+ "child_process",
134
+ "node:child_process",
135
+ "bun",
136
+ ]);
137
+
138
+ function literalString(node: unknown): string | null {
139
+ const n = node as AstNode | undefined;
140
+ if (n?.type === "Literal" && typeof n.value === "string") return n.value;
141
+ return null;
142
+ }
143
+
144
+ function isFsModule(spec: string | null): boolean {
145
+ return spec !== null && FS_MODULES.has(spec);
146
+ }
147
+
148
+ function isProcessModule(spec: string | null): boolean {
149
+ return spec !== null && PROCESS_MODULES.has(spec);
150
+ }
151
+
152
+ /**
153
+ * Every filesystem-write capability `source` holds, as human sentences, in
154
+ * document order. Empty means the module cannot write. `null` means the
155
+ * source did not parse.
156
+ */
157
+ export function fsWriteCapabilities(source: string): string[] | null {
158
+ const parsed = parseTsModule(source);
159
+ if (parsed === null) return null;
160
+
161
+ const out: string[] = [];
162
+ for (const node of walkNodes(parsed.tree)) {
163
+ if (node.type === "ImportDeclaration") {
164
+ const spec = literalString(node.source);
165
+ if (isProcessModule(spec)) {
166
+ out.push(`"${spec}" is imported, and a spawned process can write anything`);
167
+ continue;
168
+ }
169
+ if (!isFsModule(spec)) continue;
170
+ for (const s of (node.specifiers ?? []) as AstNode[]) {
171
+ // A namespace or default binding carries the WHOLE module, so every
172
+ // write primitive comes with it whether or not it is named here.
173
+ // Reported on the BINDING rather than on `fs.writeFileSync(…)` member
174
+ // access: the binding is the capability, and tracking member access
175
+ // would be a narrower reading that an indirection defeats.
176
+ if (s.type === "ImportNamespaceSpecifier" || s.type === "ImportDefaultSpecifier") {
177
+ out.push(`the whole of "${spec}" is bound as \`${(s.local as AstNode).name}\``);
178
+ continue;
179
+ }
180
+ const imported = (s.imported as AstNode | undefined)?.name;
181
+ // INVERTED (#968 review): anything not known to be read-only is a
182
+ // write. An unknown export defaults to reported, not to safe.
183
+ if (typeof imported === "string" && !FS_READ_ONLY_NAMES.has(imported)) {
184
+ out.push(`\`${imported}\` is imported from "${spec}" and is not a known read-only export`);
185
+ }
186
+ }
187
+ continue;
188
+ }
189
+
190
+ if (node.type === "ImportExpression") {
191
+ const spec = literalString(node.source);
192
+ if (isFsModule(spec)) out.push(`"${spec}" is imported dynamically`);
193
+ else if (isProcessModule(spec)) out.push(`"${spec}" is imported dynamically`);
194
+ continue;
195
+ }
196
+
197
+ // `Bun.$\`…\`` is a tagged template, not a call. Checked separately or it
198
+ // is the one shell spelling this detector cannot see — the exact shape of
199
+ // defect #968 is about.
200
+ if (node.type === "TaggedTemplateExpression") {
201
+ const tag = node.tag as AstNode | undefined;
202
+ if (tag && calleeRoot(tag) === "Bun") {
203
+ const text = parsed.js.slice(tag.start, tag.end);
204
+ if (/^Bun\s*\.\s*\$$/.test(text)) out.push(`\`${text}\` can write without importing fs`);
205
+ }
206
+ continue;
207
+ }
208
+
209
+ if (node.type !== "CallExpression") continue;
210
+ const args = (node.arguments ?? []) as AstNode[];
211
+
212
+ // `require("fs")` — the whole module, same as a namespace import.
213
+ if ((node.callee as AstNode)?.type === "Identifier" && (node.callee as AstNode).name === "require") {
214
+ const spec = literalString(args[0]);
215
+ if (isFsModule(spec) || isProcessModule(spec)) out.push(`"${spec}" is loaded with require()`);
216
+ continue;
217
+ }
218
+
219
+ // Bun's own writers and spawners, which import nothing and so are
220
+ // invisible to any import-list check. `Bun.$` is reported even though a
221
+ // read-only shell call writes nothing: a shell is a write capability,
222
+ // and the cost of over-reporting it is named in the caller.
223
+ const callee = node.callee as AstNode | undefined;
224
+ if (callee && calleeRoot(callee) === "Bun") {
225
+ const text = parsed.js.slice(callee.start, callee.end);
226
+ if (/^Bun\s*\.\s*(write|\$|spawn|spawnSync)$/.test(text)) {
227
+ out.push(`\`${text}\` can write without importing fs`);
228
+ }
229
+ }
230
+ }
231
+ return out;
232
+ }
@@ -0,0 +1,147 @@
1
+ /**
2
+ * One runner buffer, split into the runs it actually holds (#737).
3
+ *
4
+ * A LEAF module, in the shape `lib/git-dates.ts` established (#508): one
5
+ * exported reading, no relative imports, so there is exactly one thing to
6
+ * mutate and every consumer names the same rule.
7
+ *
8
+ * ## Why this exists
9
+ *
10
+ * `parseGateResults` read one buffer two ways. The summary reading collected
11
+ * every `N pass` / `N fail` line and took the LAST — something nobody writes
12
+ * unless they know the buffer can hold more than one run. Three lines later
13
+ * `parseTestResults(testOutput)` was handed the whole buffer with no scoping
14
+ * at all, and pushed a result for every `(fail)` marker anywhere in it.
15
+ *
16
+ * On `main` at `71e3f413`, run `39325676895`:
17
+ *
18
+ * Test results: 158 pass, 1 fail, 1 warn
19
+ * BATCH DIAGNOSIS: 2 failures — fix all before re-running
20
+ * AC/Evidence (2): brief-ac-alignment: ..., brief-ac-alignment: ...
21
+ * Gate verify: FAIL (attempt 2)
22
+ *
23
+ * One check, named twice, counted as one. `1 fail` is attempt 2's summary;
24
+ * `2 failures` is one check failing in both attempts. Two deciders for "how
25
+ * many checks failed" that agree on every single-run output — which is every
26
+ * output anyone had looked at — and diverge only on a retry
27
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, the fourth shape).
28
+ *
29
+ * **And the disagreement was printed.** Those two numbers appeared eleven
30
+ * lines apart in every retried gate run this project has ever produced, and
31
+ * nobody read them as contradicting each other, because each is individually
32
+ * believable. #700 was being diagnosed off the corrupted one.
33
+ *
34
+ * ## The semantics, decided rather than fallen into (#737 SC-5)
35
+ *
36
+ * **Last attempt wins.** A retry exists precisely so the later attempt is the
37
+ * verdict: the branch moved, and attempt 1's failures describe a tree that
38
+ * has been superseded. Reporting them under attempt 2's heading sends an
39
+ * operator to reasons that may already be fixed.
40
+ *
41
+ * The alternative — accumulate every attempt — was rejected because it makes
42
+ * a gate that eventually passed still report failures, and there is no way to
43
+ * tell those from failures that are still live.
44
+ *
45
+ * This is also written down in `specs/GATE-CONTRACTS-SPEC.md`, because a
46
+ * parser is a bad place to learn what a retry means.
47
+ *
48
+ * ## Why an absent final summary is UNMEASURED and not an earlier run's number
49
+ *
50
+ * #469's shape, which `lib/suite-run-reading.ts` already refuses: a run that
51
+ * produced no summary did not report zero failures, it reported nothing.
52
+ * Falling back to the previous run's numbers is *Silent Default
53
+ * Substitution* — `0`, `{}`, `null` and silence are indistinguishable from
54
+ * success, and the pre-#737 code did exactly that by taking the last match
55
+ * in the whole buffer regardless of which run it came from.
56
+ */
57
+
58
+ /** Bun prints this once per invocation; it is the only run boundary available. */
59
+ const RUN_BANNER = /^bun test v.*$/gm;
60
+
61
+ const PASS_LINE = /^\s*(\d+)\s+pass\s*$/gm;
62
+ const FAIL_LINE = /^\s*(\d+)\s+fail\s*$/gm;
63
+
64
+ export interface RunSummary {
65
+ pass: number;
66
+ fail: number;
67
+ }
68
+
69
+ export interface GateRun {
70
+ /** 0-based position in the buffer. */
71
+ index: number;
72
+ /** This run's slice of the buffer, verbatim. Concatenated, the runs ARE the buffer. */
73
+ text: string;
74
+ /** The run's own summary, or null when it printed none. */
75
+ summary: RunSummary | null;
76
+ }
77
+
78
+ export interface GateBufferReading {
79
+ /** The one discriminator. Everything else is a projection of `runs`. */
80
+ reading: "MEASURED" | "UNMEASURED";
81
+ unmeasuredReasons: string[];
82
+ runs: GateRun[];
83
+ /**
84
+ * The run whose verdict counts — the last one. `null` under an UNMEASURED
85
+ * reading, so a caller cannot read numbers off a buffer that has none.
86
+ */
87
+ verdict: GateRun | null;
88
+ }
89
+
90
+ function summaryOf(text: string): RunSummary | null {
91
+ // Last within THIS run: bun prints one summary per invocation, but a
92
+ // nested runner or a wrapper can emit more, and the final one is the
93
+ // run's own. Scoped to the slice, never to the document.
94
+ const passes = [...text.matchAll(PASS_LINE)];
95
+ const fails = [...text.matchAll(FAIL_LINE)];
96
+ if (passes.length === 0 && fails.length === 0) return null;
97
+ return {
98
+ pass: passes.length > 0 ? parseInt(passes[passes.length - 1][1], 10) : 0,
99
+ fail: fails.length > 0 ? parseInt(fails[fails.length - 1][1], 10) : 0,
100
+ };
101
+ }
102
+
103
+ /**
104
+ * Split a runner buffer into runs, and say which one is the verdict.
105
+ *
106
+ * The ONE binding. `fails`, `passes` and the per-check results are all
107
+ * derived from this split by `parseGateResults`, so the two readings cannot
108
+ * be scoped differently again — which was the whole defect.
109
+ *
110
+ * Text before the first banner belongs to the first run, so for a buffer
111
+ * with one run the slice is the buffer byte for byte. That is asserted
112
+ * rather than promised (#737 SC-6): this change has to be provably confined
113
+ * to the multi-run case.
114
+ */
115
+ export function splitGateRuns(buffer: string): GateBufferReading {
116
+ const starts = [...buffer.matchAll(RUN_BANNER)].map(m => m.index!);
117
+ // Run 0 starts at byte 0 whether or not a banner does, so a preamble
118
+ // belongs to the first run rather than becoming a run of its own. Only
119
+ // the SECOND banner onwards opens a new run.
120
+ const bounds = [0, ...starts.slice(1)];
121
+
122
+ const runs: GateRun[] = bounds.map((start, i) => {
123
+ const end = i + 1 < bounds.length ? bounds[i + 1] : buffer.length;
124
+ const text = buffer.slice(start, end);
125
+ return { index: i, text, summary: summaryOf(text) };
126
+ });
127
+
128
+ const reasons: string[] = [];
129
+ // An empty buffer agrees with every claim. Said first, because the
130
+ // summary check below cannot distinguish "no runs" from "one clean run".
131
+ if (buffer.trim() === "") {
132
+ reasons.push("the runner produced no output at all, so no run can be read from it");
133
+ } else if (runs[runs.length - 1].summary === null) {
134
+ reasons.push(
135
+ `the last of ${runs.length} run(s) in the buffer printed no summary line, so its ` +
136
+ `pass/fail counts are unknown. Taking an earlier run's numbers would report a ` +
137
+ `superseded attempt as this one's result (#469).`,
138
+ );
139
+ }
140
+
141
+ return {
142
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
143
+ unmeasuredReasons: reasons,
144
+ runs,
145
+ verdict: reasons.length === 0 ? runs[runs.length - 1] : null,
146
+ };
147
+ }
@@ -14,6 +14,7 @@ import { OWNED_FILES, ownedFilesTable } from "../scaffold/owned-files";
14
14
  import { isHarnessItself } from "../harness-identity";
15
15
  import { typecheckDecision } from "../typescript-project";
16
16
  import { localCalendarDay } from "../local-calendar-day";
17
+ import { resolveShipPolicy, shipWorkflowRule } from "../ship-mode";
17
18
 
18
19
  /**
19
20
  * Build the AGENTS.md frontmatter block.
@@ -45,8 +46,47 @@ export function existingFrontmatter(root: string): Record<string, string> {
45
46
  return existing;
46
47
  }
47
48
 
48
- function buildFrontmatter(root: string): string {
49
- const today = localCalendarDay();
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 {
50
90
  const defaults: Record<string, string> = {
51
91
  "doc-type": "reference",
52
92
  status: "active",
@@ -55,7 +95,12 @@ function buildFrontmatter(root: string): string {
55
95
 
56
96
  const existing = existingFrontmatter(root);
57
97
 
58
- 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 };
59
104
  const order = ["doc-type", "status", "owner", "updated"];
60
105
  const keys = [...order.filter(k => k in merged), ...Object.keys(merged).filter(k => !order.includes(k))];
61
106
  return `---\n${keys.map(k => `${k}: ${merged[k]}`).join("\n")}\n---\n\n`;
@@ -66,7 +111,14 @@ export interface GeneratedRule {
66
111
  content: string;
67
112
  }
68
113
 
69
- 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 {
70
122
  const {
71
123
  name,
72
124
  identity,
@@ -102,11 +154,6 @@ export function generateAgentsMd(scan: ProjectScan): string {
102
154
  ? `\n## Consumers (${consumers.length})\n\n${consumers.map(c => `- ${c}`).join("\n")}\n\nCheck cascade impact when modifying shared modules.`
103
155
  : "";
104
156
 
105
- // Re-scaffolding used to strip AGENTS.md's frontmatter, because the
106
- // generator never emitted any. Carry the existing block forward with a
107
- // refreshed `updated:` so doc-hygiene keeps working across re-scaffolds.
108
- const frontmatter = buildFrontmatter(scan.root);
109
-
110
157
  // convert-spec is only advertised where the script actually exists —
111
158
  // rungate has it, a scaffolded consumer may not. It was being dropped on
112
159
  // every re-scaffold because the table did not know about it at all.
@@ -179,7 +226,12 @@ bunx rungate --help
179
226
 
180
227
  Pin the version: re-scaffolding on a newer rungate rewrites generated files.`;
181
228
 
182
- 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}
183
235
 
184
236
  ## Project Identity
185
237
 
@@ -211,6 +263,8 @@ ${consumerSection}
211
263
  ${repoLine}${makeTargets}
212
264
  - **Test:** \`${testCmd}\`
213
265
  `;
266
+
267
+ return buildFrontmatter(scan.root, today, body === existingBody(scan.root)) + body;
214
268
  }
215
269
 
216
270
  /**
@@ -283,24 +337,14 @@ description: Shared behavioral principles for all agents working in this project
283
337
  `,
284
338
  });
285
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.
286
345
  rules.push({
287
346
  filename: "ship-workflow.md",
288
- content: `---
289
- description: All implementation work must go through the ship workflow — never spawn agents directly
290
- ---
291
-
292
- ## Ship Workflow Required
293
-
294
- When shipping an issue or implementing code changes, use the ship workflow:
295
-
296
- \`\`\`
297
- Skill("ship") → Workflow({ scriptPath: "workflows/ship.js" })
298
- \`\`\`
299
-
300
- **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.
301
-
302
- If Skill("harness") or Skill("goal") fails, fall back to Skill("ship") with the issue number.
303
- `,
347
+ content: shipWorkflowRule(resolveShipPolicy(scan.harnessConfig)),
304
348
  });
305
349
 
306
350
  if (specs.length > 0) {
@@ -397,16 +441,47 @@ section is yours, and a re-scaffold carries it forward verbatim —
397
441
  including the \`<!-- BEGIN AUTO-EXTRACTED -->\` block, and including any
398
442
  lines you wrote outside it.
399
443
 
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.
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.
406
450
 
407
451
  If a run cannot carry every one of those lines forward it **refuses the
408
452
  write**, names the lines, and leaves your file untouched.
409
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
+
410
485
  ### The workflow files are job-owned, not file-owned (#216)
411
486
 
412
487
  rungate owns the \`test\` job in \`ci.yml\` and the \`gates\` job in
@@ -419,6 +494,39 @@ cannot carry a job forward — a flow mapping (\`jobs: {deploy: {...}}\`), or a
419
494
  file it cannot parse — it **refuses the write**, names the jobs at risk and
420
495
  the line delta, and leaves your file untouched. Re-run with \`--force\` only
421
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.
422
530
  `,
423
531
  });
424
532