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,217 @@
1
+ /**
2
+ * workflow-census.ts — what is in `.github/workflows/`, and who wrote it.
3
+ *
4
+ * The harness owns the `test` job in `ci.yml` and the `gates` job in
5
+ * `gates.yml`. It has never owned a workflow FILE, and the owned-path list in
6
+ * `.claude/rules/harness-managed.md` is a list of files the generator writes —
7
+ * so a file the generator did not write could not be added to it without the
8
+ * generator then producing it, and was therefore invisible (#722). A consumer
9
+ * with rungate scaffolded into it ran five gh-aw workflows that cost money,
10
+ * failed on quota and emailed its owner, and every scaffold run reported clean.
11
+ *
12
+ * Ownership here is a property of the BYTES, not of a list in another file.
13
+ * `.claude/rules/*.md` have worked this way since #370: the generator stamps a
14
+ * digest of what it wrote, and the next run asks the file itself. The marker
15
+ * is a YAML comment, so it is invisible to anything that parses the workflow
16
+ * and visible to anything that reads the text.
17
+ *
18
+ * marker present, digest matches the body → generated-and-unchanged
19
+ * marker present, digest does not match → generated-and-hand-edited
20
+ * no marker → NOT-OWNED
21
+ *
22
+ * ## Why `reading` is a field
23
+ *
24
+ * A directory that could not be read yields zero NOT-OWNED files. So does a
25
+ * directory in which every file is owned. Those are the same output and
26
+ * opposite facts, and a caller inferring "clean" from an empty array gets the
27
+ * #646 failure: the answer and the absence of an answer are byte-identical.
28
+ * `0`, `{}`, `null` and silence are indistinguishable from success;
29
+ * `UNMEASURED` is not.
30
+ *
31
+ * ## Why the coverage figure is rendered, not just returned
32
+ *
33
+ * `36/426` and `426/426` are the same PASS today — #492. A verdict that does
34
+ * not state how much of its subject it read cannot be told from a complete
35
+ * one by anybody downstream, so `read/present` goes in the line itself.
36
+ *
37
+ * This module REPORTS. It does not delete, rewrite or refuse anything in a
38
+ * consumer tree: what a consumer does with a NOT-OWNED workflow is theirs.
39
+ */
40
+ import { readFileSync, readdirSync, statSync } from "fs";
41
+ import { join } from "path";
42
+
43
+ import { lineCommentProvenance } from "./owned-files";
44
+
45
+ // ── The marker ──────────────────────────────────────────
46
+
47
+ const YAML_COMMENT = lineCommentProvenance("#");
48
+
49
+ /** Stamp a generated workflow so the next run can recognise its own output. */
50
+ export const stampWorkflow = YAML_COMMENT.stamp;
51
+
52
+ /** The digest a workflow file declares, or null if it carries no marker. */
53
+ export const workflowMarker = YAML_COMMENT.declared;
54
+
55
+ /** The digest the file's body actually hashes to. */
56
+ export const workflowBodySha = YAML_COMMENT.sha;
57
+
58
+ /**
59
+ * The workflow without its provenance marker (#767).
60
+ *
61
+ * The marker is harness bookkeeping, and `resolveManagedWrite` treats every
62
+ * line outside a job as the consumer's. Those two facts met in #722 and the
63
+ * merge began refusing its own first line — *"1 line(s) the harness did not
64
+ * author would be dropped from content outside any job"* — so a generator
65
+ * change could not land on any workflow holding a preserved job.
66
+ */
67
+ export const workflowBody = YAML_COMMENT.body;
68
+
69
+ // ── The reading ─────────────────────────────────────────
70
+
71
+ export type WorkflowStatus =
72
+ /** The harness wrote it and nobody has touched it since. */
73
+ | "generated-and-unchanged"
74
+ /** The harness wrote it and the bytes have moved. Preserved, not rewritten. */
75
+ | "generated-and-hand-edited"
76
+ /** No marker: the harness did not write this and does not manage it. */
77
+ | "NOT-OWNED";
78
+
79
+ export interface WorkflowFinding {
80
+ /** File name within `.github/workflows`, e.g. `issue-triage.lock.yml`. */
81
+ name: string;
82
+ status: WorkflowStatus;
83
+ /** Why this status, in the census's own words. */
84
+ detail: string;
85
+ }
86
+
87
+ export interface WorkflowCensus {
88
+ reading: "MEASURED" | "UNMEASURED";
89
+ /** Named causes. Empty exactly when `reading` is MEASURED. */
90
+ unmeasuredReasons: string[];
91
+ files: WorkflowFinding[];
92
+ /** Projection of `files` — NOT-OWNED names, individually (AC-3). */
93
+ notOwned: string[];
94
+ /** How much of the subject was read. `read < present` is a partial scan. */
95
+ coverage: { read: number; present: number };
96
+ }
97
+
98
+ const WORKFLOW_EXT = /\.ya?ml$/i;
99
+
100
+ /**
101
+ * Read `.github/workflows/` and classify every file in it.
102
+ *
103
+ * One exported function, so there is one binding to mutate, and `reading` is
104
+ * derived here and nowhere else — a second boolean beside it would always
105
+ * agree with it, and two deciders that agree are behaviourally one.
106
+ */
107
+ export function workflowCensus(root: string): WorkflowCensus {
108
+ const dir = join(root, ".github", "workflows");
109
+ const reasons: string[] = [];
110
+
111
+ let entries: string[];
112
+ try {
113
+ if (!statSync(dir).isDirectory()) {
114
+ return census([`WORKFLOWS_DIR_ABSENT: ${dir} is not a directory`], [], 0);
115
+ }
116
+ entries = readdirSync(dir).filter(n => WORKFLOW_EXT.test(n)).sort();
117
+ } catch (e) {
118
+ // An absent directory is deliberately UNMEASURED rather than a measured
119
+ // zero. Every scaffolded project has one — the generator creates it — so
120
+ // its absence means this scan is looking somewhere the workflows are not,
121
+ // which is exactly the reading #646 was about.
122
+ const why = (e as NodeJS.ErrnoException).code === "ENOENT"
123
+ ? `WORKFLOWS_DIR_ABSENT: ${dir}`
124
+ : `WORKFLOWS_DIR_UNREADABLE: ${dir} — ${(e as Error).message}`;
125
+ return census([why], [], 0);
126
+ }
127
+
128
+ const files: WorkflowFinding[] = [];
129
+ for (const name of entries) {
130
+ let text: string;
131
+ try {
132
+ text = readFileSync(join(dir, name), "utf-8");
133
+ } catch (e) {
134
+ // Not owned and not unowned: both are claims about bytes nobody read.
135
+ reasons.push(`UNREADABLE_WORKFLOW: ${name} — ${(e as Error).message}`);
136
+ continue;
137
+ }
138
+ files.push(classify(name, text));
139
+ }
140
+
141
+ return census(reasons, files, entries.length);
142
+ }
143
+
144
+ /**
145
+ * The only place a `WorkflowCensus` is constructed.
146
+ *
147
+ * `reading`, `notOwned` and `coverage.read` are all PROJECTIONS of the two
148
+ * inputs, derived here and nowhere else. The first draft of this module set
149
+ * `reading` literally on the early-return path and computed it on the main
150
+ * path — two deciders answering one question, which no behavioural test can
151
+ * tell apart because they always agree
152
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape). One
153
+ * binding, so there is one thing to mutate.
154
+ */
155
+ function census(reasons: string[], files: WorkflowFinding[], present: number): WorkflowCensus {
156
+ return {
157
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
158
+ unmeasuredReasons: reasons,
159
+ files,
160
+ notOwned: files.filter(f => f.status === "NOT-OWNED").map(f => f.name),
161
+ coverage: { read: files.length, present },
162
+ };
163
+ }
164
+
165
+ function classify(name: string, text: string): WorkflowFinding {
166
+ const declared = workflowMarker(text);
167
+ if (declared === null) {
168
+ return {
169
+ name,
170
+ status: "NOT-OWNED",
171
+ detail: "no harness provenance marker — rungate did not write this file",
172
+ };
173
+ }
174
+ const actual = workflowBodySha(text);
175
+ if (declared === actual) {
176
+ return { name, status: "generated-and-unchanged", detail: "harness-written and untouched since" };
177
+ }
178
+ return {
179
+ name,
180
+ status: "generated-and-hand-edited",
181
+ detail: `hand-edited since the harness wrote it (declared ${declared}, body ${actual})`,
182
+ };
183
+ }
184
+
185
+ // ── The report ──────────────────────────────────────────
186
+
187
+ /**
188
+ * Render the census as scaffold `actions[]` lines.
189
+ *
190
+ * NOT-OWNED files are named one per line rather than counted. "5 unowned
191
+ * workflows" sends nobody anywhere; the five that cost a consumer money each
192
+ * have a name, and the name is the whole of what makes the line actionable.
193
+ */
194
+ export function censusReport(census: WorkflowCensus): string[] {
195
+ const { read, present } = census.coverage;
196
+ const out: string[] = [
197
+ `WORKFLOWS: ${census.reading} — read ${read}/${present} file(s) in .github/workflows`,
198
+ ];
199
+
200
+ for (const reason of census.unmeasuredReasons) {
201
+ out.push(` UNMEASURED: ${reason}`);
202
+ }
203
+
204
+ for (const f of census.files) {
205
+ if (f.status === "generated-and-unchanged") continue;
206
+ out.push(` ${f.status}: ${f.name} — ${f.detail}`);
207
+ }
208
+
209
+ if (census.notOwned.length > 0) {
210
+ out.push(
211
+ ` NOT-OWNED workflows run in this repo's CI and rungate does not manage them. ` +
212
+ `Reported, not touched — what happens to them is yours: ${census.notOwned.join(", ")}`,
213
+ );
214
+ }
215
+
216
+ return out;
217
+ }
@@ -0,0 +1,217 @@
1
+ /**
2
+ * workflow-drift.ts — the consumer-facing reading of #722's census.
3
+ *
4
+ * #722 built `workflowCensus`, which can tell a generated workflow nobody has
5
+ * touched from one somebody hand-edited, and the stamp it reads has been on
6
+ * disk in consumer repos ever since. Nothing a consumer runs ever asked it
7
+ * (#915). So a hand-edit to a generated `ci.yml`, `gates.yml` or
8
+ * `ai-review.yml` was stamped, mechanically detectable, and undetected: the
9
+ * symptom somebody "fixed" by editing the workflow disappears, the generator
10
+ * keeps shipping the unfixed version, and the next `bunx rungate scaffold .`
11
+ * reverts the edit. Nothing reds at any point in that sequence.
12
+ *
13
+ * This module turns the census into a verdict. `lib/conformity.ts` wraps it
14
+ * as `runWorkflowDriftValidation`; the census itself is unchanged.
15
+ *
16
+ * ## Why a hand-edit is not automatically drift (#839, #917)
17
+ *
18
+ * `ci.workflowOverrides` lets a consumer name top-level keys they have taken
19
+ * back from the generator. `mergeManagedWorkflow` leaves a declined key
20
+ * exactly as they wrote it and writes a notice into the file saying which
21
+ * config key declined it. An edit inside such a key is **not** reverted by a
22
+ * re-scaffold, so reporting it as drift would be reporting the escape hatch
23
+ * as a defect — and a check that reds on the supported way to deviate is a
24
+ * check somebody deletes.
25
+ *
26
+ * The stamp covers the WHOLE body, so it can say the bytes moved and cannot
27
+ * say where. That is the honest limit of this reading and it is why there are
28
+ * three outcomes rather than two:
29
+ *
30
+ * hand-edited, no key in this file is the consumer's → DRIFTED. Every byte
31
+ * is the generator's, so the next scaffold reverts the edit.
32
+ * hand-edited, some key in this file IS the consumer's → UNMEASURED, with
33
+ * the keys named. The edit may be inside one of them or outside it, and
34
+ * a whole-body digest cannot tell. Reported loudly rather than waved
35
+ * through: `.claude/rules/config-access.md` — a silent pass here is
36
+ * Silent Default Substitution with the file on the consumer's side.
37
+ * NOT-OWNED → passing, and NAMED (#722 AC-3). A consumer's own workflows
38
+ * are theirs; "5 unowned workflows" sends nobody anywhere.
39
+ *
40
+ * ## Why zero files is not agreement
41
+ *
42
+ * A census over an empty `.github/workflows/` is MEASURED with no findings,
43
+ * which renders exactly like a repo whose three generated workflows are all
44
+ * untouched. That is #621's shape — N things agreeing vacuously — so a
45
+ * reading with nothing stamped in it to compare is UNMEASURED and says which
46
+ * of the two it is.
47
+ */
48
+ import { readFileSync } from "fs";
49
+ import { join } from "path";
50
+
51
+ import { topLevelKeyOrder } from "./managed-workflow";
52
+ import { workflowCensus } from "./workflow-census";
53
+
54
+ export interface WorkflowDriftFinding {
55
+ /** File name within `.github/workflows`, e.g. `ai-review.yml`. */
56
+ name: string;
57
+ /** Why this verdict, in the reading's own words. */
58
+ detail: string;
59
+ }
60
+
61
+ export interface WorkflowDriftReading {
62
+ reading: "MEASURED" | "UNMEASURED";
63
+ /** Named causes. Empty exactly when `reading` is MEASURED. */
64
+ unmeasuredReasons: string[];
65
+ /** Hand-edited, and nothing in the file is the consumer's. The refusal. */
66
+ drifted: WorkflowDriftFinding[];
67
+ /** Hand-edited, and the consumer has declared part of this file theirs. */
68
+ consumerOwned: WorkflowDriftFinding[];
69
+ /** NOT-OWNED names, individually. Passing. */
70
+ notOwned: string[];
71
+ /**
72
+ * How much of the subject was read, and how much of what was read this
73
+ * check is even about. `read < present` is a partial scan; `generated === 0`
74
+ * is a scan with nothing to compare, which is not the same as a clean one.
75
+ */
76
+ coverage: { read: number; present: number; generated: number };
77
+ }
78
+
79
+ /**
80
+ * Read `.github/workflows/` and say whether a generated workflow has moved.
81
+ *
82
+ * `overrides` is `ci.workflowOverrides` as `workflowOverrides()` reads it —
83
+ * passed in rather than loaded here, so the config reader stays the one
84
+ * binding `.claude/rules/config-access.md` requires and this module stays
85
+ * free of a config path of its own.
86
+ *
87
+ * One exported reading, so there is one thing to mutate, and `reading` is
88
+ * derived here and nowhere else.
89
+ */
90
+ export function workflowDrift(root: string, overrides: readonly string[] = []): WorkflowDriftReading {
91
+ const dir = join(root, ".github", "workflows");
92
+ const census = workflowCensus(root);
93
+ const reasons = [...census.unmeasuredReasons];
94
+
95
+ const generated = census.files.filter(f => f.status !== "NOT-OWNED");
96
+ if (census.coverage.present === 0) {
97
+ reasons.push(
98
+ `NO_WORKFLOW_FILES: ${dir} holds no workflow files — zero files agreeing is not agreement`,
99
+ );
100
+ } else if (generated.length === 0) {
101
+ reasons.push(
102
+ `NO_GENERATED_WORKFLOW: read ${census.coverage.read} file(s) in ${dir} and none carries a ` +
103
+ `harness provenance marker — there is nothing for a drift check to compare. ` +
104
+ `Run \`bunx rungate scaffold .\` if this project is meant to have generated CI`,
105
+ );
106
+ }
107
+
108
+ const drifted: WorkflowDriftFinding[] = [];
109
+ const consumerOwned: WorkflowDriftFinding[] = [];
110
+
111
+ for (const file of generated) {
112
+ if (file.status !== "generated-and-hand-edited") continue;
113
+
114
+ let claimed: string[];
115
+ try {
116
+ claimed = consumerKeysIn(readFileSync(join(dir, file.name), "utf-8"), overrides);
117
+ } catch (e) {
118
+ // The census read this file a moment ago. A failure here is not "no
119
+ // keys are claimed" — that is a claim about bytes nobody read.
120
+ reasons.push(`UNREADABLE_WORKFLOW: ${file.name} — ${(e as Error).message}`);
121
+ continue;
122
+ }
123
+
124
+ if (claimed.length === 0) {
125
+ drifted.push({
126
+ name: file.name,
127
+ detail:
128
+ `${file.detail}. No top-level key in this file is declared the consumer's, so ` +
129
+ `\`bunx rungate scaffold .\` will overwrite the edit. Make the change in the ` +
130
+ `generator, or name the key in \`ci.workflowOverrides\` to keep it`,
131
+ });
132
+ continue;
133
+ }
134
+
135
+ consumerOwned.push({
136
+ name: file.name,
137
+ detail:
138
+ `${file.detail}, and ${claimed.join(", ")} ${claimed.length === 1 ? "is" : "are"} ` +
139
+ `declared the consumer's through \`ci.workflowOverrides\`. The provenance marker ` +
140
+ `digests the whole file, so it cannot say whether the edit landed inside a declared ` +
141
+ `key or outside one — UNMEASURED, not clean`,
142
+ });
143
+ }
144
+
145
+ return {
146
+ reading: reasons.length === 0 ? "MEASURED" : "UNMEASURED",
147
+ unmeasuredReasons: reasons,
148
+ drifted,
149
+ consumerOwned,
150
+ notOwned: census.notOwned,
151
+ coverage: { read: census.coverage.read, present: census.coverage.present, generated: generated.length },
152
+ };
153
+ }
154
+
155
+ /**
156
+ * The top-level keys of one workflow that are the consumer's, not the
157
+ * generator's.
158
+ *
159
+ * One source: `ci.workflowOverrides`, intersected with the keys this file
160
+ * actually declares. The config is global and the question is per-file — a
161
+ * project declining `concurrency` has said nothing about a workflow that has
162
+ * no `concurrency:` in it, and treating the decline as covering that file
163
+ * would blind the check to every edit in it.
164
+ *
165
+ * ## Why the file's own override notices are NOT a second source (#958)
166
+ *
167
+ * They were, until #958: the notices `mergeManagedWorkflow` writes were read
168
+ * back and unioned in, with no reference to the config. A notice is a comment
169
+ * anybody can type, so that made the file under inspection the authority on
170
+ * its own exemption — paste one line into a hand-edited workflow and DRIFTED
171
+ * became consumerOwned. #530's shape: the artifact everyone reaches for as
172
+ * ground truth, which always agrees.
173
+ *
174
+ * #928 reasoned the notice source from #722's "ownership travels with the
175
+ * bytes". The analogy does not hold. `generated-sha:` is a digest OF the
176
+ * body — it cannot be written to say something the bytes do not; a notice
177
+ * carries no such binding.
178
+ *
179
+ * Nor does the case it was built for survive inspection. The justification
180
+ * was "a consumer who removed the key from the config but has not
181
+ * re-scaffolded still has a file whose bytes were authored under the
182
+ * decline." That is backwards: if the key is gone from the config the next
183
+ * scaffold RE-MERGES it, so the edit will be reverted — which is precisely
184
+ * what DRIFTED means. The config decides what the next scaffold does, and it
185
+ * is the only authority this reading should have.
186
+ *
187
+ * Hardening the notice branch rather than deleting it — accept a notice key
188
+ * only when the config names it too — is behaviourally identical to this,
189
+ * because the union then collapses to `{config ∩ declared}`. Same verdicts,
190
+ * one less branch, and one less thing a consumer can write.
191
+ */
192
+ function consumerKeysIn(text: string, overrides: readonly string[]): string[] {
193
+ const declared = new Set(topLevelKeyOrder(text));
194
+ return overrides.filter(k => declared.has(k));
195
+ }
196
+
197
+ /**
198
+ * Render the reading as report lines.
199
+ *
200
+ * NOT-OWNED files are named one per line rather than counted, and the
201
+ * coverage figure is in the first line, for the reasons `censusReport` gives:
202
+ * `3/12` and `12/12` are the same verdict and no reader can tell them apart
203
+ * from the output.
204
+ */
205
+ export function workflowDriftReport(reading: WorkflowDriftReading): string[] {
206
+ const { read, present, generated } = reading.coverage;
207
+ const out: string[] = [
208
+ `WORKFLOW DRIFT: ${reading.reading} — read ${read}/${present} file(s), ${generated} generated`,
209
+ ];
210
+ for (const reason of reading.unmeasuredReasons) out.push(` UNMEASURED: ${reason}`);
211
+ for (const f of reading.drifted) out.push(` DRIFTED: ${f.name} — ${f.detail}`);
212
+ for (const f of reading.consumerOwned) out.push(` UNMEASURED: ${f.name} — ${f.detail}`);
213
+ if (reading.notOwned.length > 0) {
214
+ out.push(` NOT-OWNED, and not this check's business: ${reading.notOwned.join(", ")}`);
215
+ }
216
+ return out;
217
+ }
@@ -47,6 +47,7 @@ import {
47
47
  addFrontmatterToSpecs, addFrontmatterToAdrs, detectOversizedSpecs,
48
48
  checkGovernsAlignment, detectMisplacedSpecs, detectUnconvertedSpecs,
49
49
  } from "../validators/spec-validators";
50
+ import { ensureConfigTrackable } from "../config-trackable";
50
51
  import type { ProjectType } from "../generators/types";
51
52
  import { DEFAULT_PROFILE, isStepIncluded, type ScaffoldProfile } from "./profiles";
52
53
 
@@ -93,6 +94,9 @@ export function runScaffoldWriteSteps(
93
94
 
94
95
  // Phase 0: Security and directory setup
95
96
  createGitignore(projectPath, actions);
97
+ // AFTER `createGitignore` and not before: the negation only works as the
98
+ // LAST matching rule, and `createGitignore` appends (#505).
99
+ ensureConfigTrackable(projectPath, actions);
96
100
  safeDir(join(projectPath, "specs"), "specs", actions);
97
101
  safeDir(join(projectPath, "reference"), "reference", actions);
98
102
  safeDir(join(projectPath, ".github"), ".github", actions);