rungate 0.8.25 → 0.8.27

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.
package/gates/.gate-salt CHANGED
@@ -1 +1 @@
1
- f7edfff5c8424ba64c95ad1a592d7b40c40c3a78197e968739a5d468cd671467
1
+ c383a2a597db75009eb5771282d36d447270d59c07518a035e13962da1d45801
@@ -170,9 +170,17 @@ function unmeasuredSweep(reasons: string[]): SpecSweep {
170
170
  return { reading: "UNMEASURED", specs: [], ids: [], collisions: [], unmeasuredReasons: reasons };
171
171
  }
172
172
 
173
- export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDir): SpecSweep {
173
+ /**
174
+ * Which files under `<root>/specs` are specs — the ONE answer, shared by
175
+ * {@link specCriteriaIn} and `rungate board-scope` (#2275). It refuses only on
176
+ * what stops it locating a file; whether any spec states a criterion is the
177
+ * id sweep's question, not this one's.
178
+ */
179
+ export function specFilesIn(
180
+ root: string,
181
+ readDir: SpecDirReader = readSpecDir,
182
+ ): { reading: "MEASURED"; paths: string[] } | { reading: "UNMEASURED"; reasons: string[] } {
174
183
  const dir = join(root, "specs");
175
- let files: string[];
176
184
  try {
177
185
  const entries = readDir(dir).filter(e => e.isFile() && e.name.endsWith(".md"));
178
186
  // `parentPath` is the ONLY field that can be trusted to name a nested
@@ -189,23 +197,34 @@ export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDi
189
197
  // not a sweep with fewer specs in it.
190
198
  const unlocatable = unlocatableEntries(entries);
191
199
  if (unlocatable.length > 0) {
192
- return unmeasuredSweep([
193
- `this runtime does not report Dirent.parentPath, so ${unlocatable.length} spec file(s) ` +
194
- `under ${dir} cannot be located — a nested spec would be read as a top-level one. ` +
195
- `Nothing was read: ${unlocatable.map(e => e.name).sort().join(", ")}`,
196
- ]);
200
+ return {
201
+ reading: "UNMEASURED",
202
+ reasons: [
203
+ `this runtime does not report Dirent.parentPath, so ${unlocatable.length} spec file(s) ` +
204
+ `under ${dir} cannot be located — a nested spec would be read as a top-level one. ` +
205
+ `Nothing was read: ${unlocatable.map(e => e.name).sort().join(", ")}`,
206
+ ],
207
+ };
197
208
  }
198
209
  // `as string` rather than a second `typeof e.parentPath === "string"`:
199
210
  // the refusal above already decided that question for every entry here,
200
211
  // and a second decider answering it again is one no behavioural test can
201
212
  // tell apart from the first.
202
- files = entries
213
+ const paths = entries
203
214
  .map(e => relative(root, join(e.parentPath as string, e.name)).split(sep).join("/"))
204
215
  .filter(p => !(NOT_A_SPEC as readonly string[]).includes(p))
205
216
  .sort();
217
+ return { reading: "MEASURED", paths };
206
218
  } catch (e) {
207
- return unmeasuredSweep([`could not read ${dir}: ${(e as Error).message}`]);
219
+ return { reading: "UNMEASURED", reasons: [`could not read ${dir}: ${(e as Error).message}`] };
208
220
  }
221
+ }
222
+
223
+ export function specCriteriaIn(root: string, readDir: SpecDirReader = readSpecDir): SpecSweep {
224
+ const dir = join(root, "specs");
225
+ const listed = specFilesIn(root, readDir);
226
+ if ("reasons" in listed) return unmeasuredSweep(listed.reasons);
227
+ const files = listed.paths;
209
228
 
210
229
  const specs: SpecCriteria[] = [];
211
230
  const reasons: string[] = [];
@@ -227,7 +227,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
227
227
  // argument it would read as a positional.
228
228
  "board-conformance": {
229
229
  script: "scripts/board-conformance.ts",
230
- summary: "Does the board say what the spec says — every reading, and whether any is short of target",
230
+ summary: "Whether the board says what the spec says, reading by reading",
231
231
  usage: "rungate board-conformance [--reading <name>] [--snapshot <path>] [--list-readings]",
232
232
  },
233
233
  // Step 4 of ADR-003, in reverse. The issue template's own footer says a
@@ -239,11 +239,19 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
239
239
  "plan-issues": {
240
240
  script: "scripts/plan-issues.ts",
241
241
  summary:
242
- "Apply an approved issue plan — --decompose creates issues from criteria (step 4), --repair links and demotes existing ones",
242
+ "Apply an approved issue plan: --decompose files issues, --repair links and demotes them",
243
243
  usage:
244
244
  "rungate plan-issues (--repair | --decompose) <plan.md> --repo <owner/name> [--write] [--json]",
245
245
  projectRootFlag: true,
246
246
  },
247
+ // #2275, onboarding existing specs. Read-only: what each spec holds, its
248
+ // `board:` setting, and a looks-done hint per unticked criterion. It never
249
+ // ticks. Reads the working directory, so it takes no root flag.
250
+ "board-scope": {
251
+ script: "scripts/board-scope.ts",
252
+ summary: "Spec criteria and opt-in, with looks-done hints",
253
+ usage: "rungate board-scope [--spec <path>] [--json]",
254
+ },
247
255
  // Step 5 of ADR-003. `plan-spec` turns the placement table into milestones;
248
256
  // this turns the ORDER of those milestones into `blocked by` edges, which is
249
257
  // AGENTS.md rule 4 — ordering is data, not prose.
@@ -312,7 +320,7 @@ export const CLI_COMMANDS: Record<string, CliCommand> = {
312
320
  // each intake source runs on its own trigger.
313
321
  intake: {
314
322
  script: "scripts/intake.ts",
315
- summary: "Run each intake source and print its reading — MEASURED with a count, or UNMEASURED naming why",
323
+ summary: "Run each intake source and print its reading, MEASURED or UNMEASURED",
316
324
  usage:
317
325
  "rungate intake [--project-root <dir>] [--source <id>] [--json] " +
318
326
  "(advisory: an unreadable source prints UNMEASURED and exits 0; exit 2 on a bad argument)",
@@ -805,6 +805,63 @@ export function placementCount(specText: string): { deferred: boolean; criteria:
805
805
  return { deferred: declaresDeferred(specText), criteria: placementReading(specText).criteria.length };
806
806
  }
807
807
 
808
+ /**
809
+ * The deferral bank after a writer that is not a promotion appends to a spec.
810
+ *
811
+ * `create-sc` is the other writer of criteria. It appended to a deferred spec
812
+ * and left `.claude/spec-deferral-ratchet.json` at the old count, so the next
813
+ * pull request's SC-2734 and stage item E1 went red until someone edited the
814
+ * bank by hand. The rule is `bankWithPromotion`'s: the bank moves only from
815
+ * the count the spec stated before the append. `text: null` means there is
816
+ * nothing to write, because the spec is not deferred or its count did not
817
+ * change. A deferred spec with no readable bank refuses, never passes.
818
+ */
819
+ export function bankAfterAppend(
820
+ bankText: string | null,
821
+ specPath: string,
822
+ before: string,
823
+ after: string,
824
+ ): { ok: true; text: string | null } | { ok: false; refusal: PromotionRefusal; why: string } {
825
+ const was = placementCount(before);
826
+ const now = placementCount(after);
827
+ if (!was.deferred || now.criteria === was.criteria) return { ok: true, text: null };
828
+ if (bankText === null) {
829
+ return { ok: false, refusal: "BANK_DRIFT", why: `${specPath} is deferred and the deferral bank could not be read` };
830
+ }
831
+ return bankWithPromotion(bankText, specPath, was.criteria, now.criteria);
832
+ }
833
+
834
+ /** The writer `writeSpecWithBank` writes through: `writeSpec`, or a stand-in in a test. */
835
+ export type SpecWriter = (path: string, content: string) => { written: boolean; refusal?: string | null };
836
+
837
+ /**
838
+ * Write the spec and then the bank, both or neither (review of #2298).
839
+ *
840
+ * A bank write that fails after the spec write landed would leave the bank one
841
+ * behind, and `create-sc` cannot repair that on a retry the way
842
+ * `bankForRetry` does for a promotion: it mints a fresh id every run, so a
843
+ * bank one behind looks exactly like somebody else's unbanked criterion. So
844
+ * the spec is put back. `restored: false` is the one state left that needs a
845
+ * person, and it says so.
846
+ */
847
+ export function writeSpecWithBank(
848
+ write: SpecWriter,
849
+ spec: { path: string; before: string; after: string },
850
+ bank: { path: string; text: string | null },
851
+ ): { ok: true } | { ok: false; why: string; restored: boolean } {
852
+ const specWrite = write(spec.path, spec.after);
853
+ if (!specWrite.written) return { ok: false, why: `the spec was not written (${specWrite.refusal ?? "no reason given"})`, restored: true };
854
+ if (bank.text === null) return { ok: true };
855
+ const bankWrite = write(bank.path, bank.text);
856
+ if (bankWrite.written) return { ok: true };
857
+ const undo = write(spec.path, spec.before);
858
+ return {
859
+ ok: false,
860
+ why: `the deferral bank could not be written (${bankWrite.refusal ?? "no reason given"})`,
861
+ restored: undo.written,
862
+ };
863
+ }
864
+
808
865
  /**
809
866
  * ## Declining — the router's other outcome
810
867
  *
@@ -31,7 +31,9 @@
31
31
  * `AGENTS.md` rule 7 asks us to watch.
32
32
  */
33
33
 
34
+ import { criterionAnswer } from "./board-mirror";
34
35
  import { headingOccurrencesOf } from "./issue-shape";
36
+ import { PHASE_VALUE, phaseInFamily } from "./spec-placement";
35
37
  import type { MilestoneAction } from "./spec-placement";
36
38
 
37
39
  /** The section a repaired body carries. One spelling, by fiat. */
@@ -304,3 +306,125 @@ export function rowPlacement(
304
306
  }
305
307
  return { kind: "place", milestone: target.existing.title, phase: target.phase };
306
308
  }
309
+
310
+ /** One opted-in family, as the placing run reads it — SC-2779. */
311
+ export interface PlacingFamily {
312
+ /** The `board: { prefix }` its spec declares. */
313
+ prefix: string;
314
+ /** Every criterion the family's spec states, placed in a phase or not. */
315
+ stated: readonly string[];
316
+ /** Each placed criterion's value in the spec's table (`placementsById`). */
317
+ placements: ReadonlyMap<string, string>;
318
+ /** The live milestone for each phase the table places. A phase with none is absent. */
319
+ milestones: ReadonlyMap<number, string>;
320
+ }
321
+
322
+ /**
323
+ * What the placing run does with one open issue — SC-2779.
324
+ *
325
+ * - `move`: into `milestone`, the family's milestone for the phase.
326
+ * - `stay`: it already sits there.
327
+ * - `left`: the rule leaves it where it is, and the run says why by name.
328
+ * - `none`: it names no criterion an opted-in spec states; nothing to say.
329
+ * - `refuse`: the phase it belongs in has no milestone. The run writes nothing,
330
+ * because `plan-spec` makes milestones and this never does.
331
+ */
332
+ export type IssueMove =
333
+ | { kind: "move"; milestone: string; why: string }
334
+ | { kind: "stay"; why: string }
335
+ | { kind: "left"; why: string }
336
+ | { kind: "none" }
337
+ | { kind: "refuse"; why: string };
338
+
339
+ /**
340
+ * Which milestone an open issue belongs in, read from the opted-in specs —
341
+ * SC-2779, ADR-018 Decision 4 as ADR-019 Decision 3 narrowed it.
342
+ *
343
+ * THE one decider. `plan-issues --place` asks it about every open issue, and
344
+ * nothing else moves an issue between phases.
345
+ *
346
+ * - Criteria in ONE phase of ONE family: the issue moves to that phase's
347
+ * milestone, whether it has no milestone or a different one of that family.
348
+ * - No milestone, criteria in several phases of one family: the lowest, since
349
+ * the issue cannot finish before its earliest phase does.
350
+ * - A milestone, criteria in several phases: never moved.
351
+ * - Criteria from two families: left where it is and named, because phase
352
+ * numbers do not compare across specs.
353
+ * - A milestone that is not one of the family's phases: never moved.
354
+ *
355
+ * Two readings this adds, both in the direction of not moving anything:
356
+ *
357
+ * - **"Serves no criterion" is believed.** The same {@link criterionAnswer}
358
+ * the `needs-criterion` label reads. An issue saying it serves none names
359
+ * criteria only in passing: on 2026-11-17 #2307 cited SC-2734 and SC-2776
360
+ * that way, and reading them as served would have moved it into the
361
+ * finished Engine Phase 6, where the phase order then holds every later
362
+ * phase behind it.
363
+ * - **A criterion placed outside every phase stops the move.** `Done`,
364
+ * `Blocked` and the other non-phase values, or no placement at all, mean
365
+ * the issue does not sit wholly in a phase, so no phase is named for it.
366
+ *
367
+ * Only criteria an opted-in spec states are read. An id from a spec that is
368
+ * not on the board has no phase, so it cannot place the issue or contradict
369
+ * a placement (the reading ADR-019 measured its 39 issues with).
370
+ */
371
+ export function issuePlacement(
372
+ issue: { readonly title: string; readonly body?: string | null; readonly milestone: string | null },
373
+ families: readonly PlacingFamily[],
374
+ ): IssueMove {
375
+ const answers = families
376
+ .map(f => ({ f, answer: criterionAnswer(issue, f.stated) }))
377
+ .filter(a => a.answer.names.length > 0);
378
+ if (answers.length === 0) return { kind: "none" };
379
+ if (answers.some(a => a.answer.servesNone)) {
380
+ return {
381
+ kind: "left",
382
+ why: `says it serves no criterion, so the ids it mentions (${answers.flatMap(a => a.answer.names).join(", ")}) do not place it`,
383
+ };
384
+ }
385
+ if (answers.length > 1) {
386
+ return {
387
+ kind: "left",
388
+ why:
389
+ `names ${answers.map(a => `${a.f.prefix}'s ${a.answer.names.join(", ")}`).join(" and ")} — ` +
390
+ "phase numbers do not compare across specs",
391
+ };
392
+ }
393
+ const { f, answer } = answers[0]!;
394
+ const unphased = answer.names.filter(id => !PHASE_VALUE.test(f.placements.get(id) ?? ""));
395
+ if (unphased.length > 0) {
396
+ return {
397
+ kind: "left",
398
+ why:
399
+ `${unphased.map(id => `${id} is ${f.placements.has(id) ? `placed ${f.placements.get(id)}` : "placed nowhere"}`).join(", ")} ` +
400
+ `in ${f.prefix}'s table, so the issue does not sit wholly in a phase`,
401
+ };
402
+ }
403
+ const current = issue.milestone === null ? null : phaseInFamily(issue.milestone, f.prefix);
404
+ if (issue.milestone !== null && current === null) {
405
+ return { kind: "left", why: `is in "${issue.milestone}", which is not a ${f.prefix} phase — that is never moved` };
406
+ }
407
+ const phases = [...new Set(answer.names.map(id => Number(f.placements.get(id)!.match(PHASE_VALUE)![1])))].sort((a, b) => a - b);
408
+ if (phases.length > 1 && issue.milestone !== null) {
409
+ return {
410
+ kind: "left",
411
+ why: `names criteria in ${phases.map(p => `Phase ${p}`).join(" and ")} and already has a milestone — that is never moved`,
412
+ };
413
+ }
414
+ const target = phases[0]!;
415
+ if (current === target) return { kind: "stay", why: `already in "${issue.milestone}"` };
416
+ const milestone = f.milestones.get(target);
417
+ if (milestone === undefined) {
418
+ return {
419
+ kind: "refuse",
420
+ why: `belongs in ${f.prefix} Phase ${target}, which has no milestone — run plan-spec first; this never creates one`,
421
+ };
422
+ }
423
+ return {
424
+ kind: "move",
425
+ milestone,
426
+ why:
427
+ `${issue.milestone === null ? "no milestone" : `"${issue.milestone}"`} → "${milestone}" ` +
428
+ `(${answer.names.join(", ")}${phases.length > 1 ? `; the lowest of ${phases.map(p => `Phase ${p}`).join(", ")}` : ""})`,
429
+ };
430
+ }
@@ -303,7 +303,7 @@ function revokedSubKeys(
303
303
  * `permissions.id-token` withdrawable in a workflow whose generator never
304
304
  * emits it under any config — a consumer's own grant removed by a feature
305
305
  * that was not reasoning about their file. That risk is handled structurally
306
- * here instead: `withdrawAuthoredPaths` withdraws a leaf only where the
306
+ * here instead: `applyAuthoredPaths` touches a leaf only where the
307
307
  * generated file still emits the PARENT sub-key, so a generator silent about
308
308
  * `pull_request` makes no claim on the consumer's copy of it. The emission
309
309
  * gate is the scope, and it is tighter than a filename would be because it
@@ -312,8 +312,39 @@ function revokedSubKeys(
312
312
  * Narrow on purpose. `on.push.branches` is deliberately absent: a `push`
313
313
  * filter asks which branches earn a run on their own, which is a different
314
314
  * question, and #1136 left it alone for that reason.
315
+ *
316
+ * ## Both directions (#2292)
317
+ *
318
+ * #1148 built the channel for a REMOVAL and nothing for a CHANGE. #1207 added
319
+ * `types:` to `on.pull_request` in the generated ai-review.yml so the
320
+ * `ai-review-override` label re-runs the check; a consumer scaffolded before
321
+ * it kept a bare `pull_request:` through every re-scaffold, reported
322
+ * `unchanged`, and the waiver could never fire there. So each path now names
323
+ * its claim (`AuthoredClaim`): an asserted leaf the generator emits is
324
+ * written at the generator's value, replacing the consumer's, and the
325
+ * replacement is recorded so the write can name it.
326
+ */
327
+ export const HARNESS_AUTHORED_PATHS: ReadonlyMap<string, AuthoredClaim> = new Map([
328
+ ["on.pull_request.branches", "withdrawn-when-absent"],
329
+ ["on.pull_request.types", "asserted-when-emitted"],
330
+ ]);
331
+
332
+ /**
333
+ * What the harness claims about one authored path. One claim per path, and
334
+ * the two do not combine (#2292).
335
+ *
336
+ * - `withdrawn-when-absent` (#1148): the claim is that the leaf must NOT be
337
+ * there. Where the generator emits the parent without it, the consumer's
338
+ * copy goes. Where the generator emits it, the consumer's value stands —
339
+ * a branch list is the local knob #839 keeps, and asserting it would be
340
+ * that issue's data loss one level down.
341
+ * - `asserted-when-emitted` (#2292): the claim is the VALUE. Where the
342
+ * generator emits the leaf, the consumer's copy is written at the
343
+ * generator's value. Where it does not, the consumer's stands: ci.yml and
344
+ * gates.yml emit a bare `pull_request:`, and a consumer who added activity
345
+ * types to their own CI there has made no mistake the harness may undo.
315
346
  */
316
- export const HARNESS_AUTHORED_PATHS: ReadonlySet<string> = new Set(["on.pull_request.branches"]);
347
+ export type AuthoredClaim = "withdrawn-when-absent" | "asserted-when-emitted";
317
348
 
318
349
  /**
319
350
  * A sub-block split into the comments introducing it and the key line onward.
@@ -337,23 +368,29 @@ function splitBlockIntro(lines: string[]): [string[], string[]] {
337
368
  }
338
369
 
339
370
  /**
340
- * The consumer's section with every authored leaf the generator has stopped
341
- * emitting taken out, and the record of what went (#1148).
371
+ * The consumer's section with every authored path brought to what the
372
+ * generator says: an asserted leaf it emits written at its value (#2292),
373
+ * and a withdrawn leaf it has stopped emitting taken out (#1148). Returns the
374
+ * record of both.
342
375
  *
343
376
  * Reads both sides through the same `parseSubKeys` the rest of the merge uses
344
377
  * — applied twice, because the binding takes a key line followed by its body
345
378
  * and a sub-block is that shape once `splitBlockIntro` has taken the
346
379
  * introducing comments off it. One parser, so the thing removed and the thing
347
380
  * reported removed cannot be two different readings (#834).
381
+ *
382
+ * A leaf whose VALUE already matches is left as the consumer has it, comments
383
+ * included: the claim is on the value, and rewriting a comment block nobody
384
+ * needs changed is a diff with nothing in it.
348
385
  */
349
- function withdrawAuthoredPaths(
386
+ function applyAuthoredPaths(
350
387
  section: string,
351
388
  before: Section,
352
389
  generated: Section,
353
390
  ): { section: Section; withdrawn: RevokedSubKey[] } {
354
391
  // The same scalar guard `mergeTopLevelSection` opens with: `on: [push]` has
355
- // no sub-keys to withdraw and no way to express the removal if it did.
356
- if (!/^[A-Za-z_][A-Za-z0-9_.\-]*:\s*(#.*)?$/.test(before.lines[0])) {
392
+ // no sub-keys to reach and no way to express the change if it did.
393
+ if (!SECTION_KEY_LINE.test(before.lines[0])) {
357
394
  return { section: before, withdrawn: [] };
358
395
  }
359
396
  const parsed = parseSubKeys(before.lines);
@@ -366,29 +403,52 @@ function withdrawAuthoredPaths(
366
403
  // no statement about the consumer's copy of it.
367
404
  if (gen === undefined) return block;
368
405
  const [intro, fromKey] = splitBlockIntro(block.lines);
406
+ const genFromKey = splitBlockIntro(gen.lines)[1];
407
+ // The same guard one level down: `pull_request: {}` carries its value on
408
+ // the key line, and a leaf put under it would not parse.
409
+ if (!SUB_KEY_LINE.test(fromKey[0] ?? "") || !SUB_KEY_LINE.test(genFromKey[0] ?? "")) return block;
369
410
  const consumerLeaves = parseSubKeys(fromKey);
370
- const emitted = new Set(parseSubKeys(splitBlockIntro(gen.lines)[1]).blocks.map(s => s.key));
411
+ const genLeaves = parseSubKeys(genFromKey).blocks;
412
+ const emitted = new Set(genLeaves.map(s => s.key));
413
+ const path = (leaf: string) => `${section}.${block.key}.${leaf}`;
414
+
371
415
  const gone = consumerLeaves.blocks.filter(
372
- leaf => HARNESS_AUTHORED_PATHS.has(`${section}.${block.key}.${leaf.key}`) && !emitted.has(leaf.key),
416
+ leaf => HARNESS_AUTHORED_PATHS.get(path(leaf.key)) === "withdrawn-when-absent" && !emitted.has(leaf.key),
373
417
  );
374
- if (gone.length === 0) return block;
418
+ // The generator's leaf, at the consumer's indent for this trigger.
419
+ const shift = indentOf(fromKey[0]) - indentOf(genFromKey[0]);
420
+ const asserted = new Map<string, string[]>();
421
+ for (const g of genLeaves) {
422
+ if (HARNESS_AUTHORED_PATHS.get(path(g.key)) !== "asserted-when-emitted") continue;
423
+ const value = reindent(splitTrailingBlanks(g.lines)[0], shift);
424
+ const mine = consumerLeaves.blocks.find(l => l.key === g.key);
425
+ if (mine !== undefined && sameValue(mine.lines, value)) continue;
426
+ asserted.set(g.key, value);
427
+ }
428
+ if (gone.length === 0 && asserted.size === 0) return block;
429
+
375
430
  for (const leaf of gone) {
376
- withdrawn.push({
377
- section: `${section}.${block.key}`,
378
- key: leaf.key,
379
- lines: leaf.lines,
380
- reason: "authored",
381
- });
431
+ withdrawn.push({ section: `${section}.${block.key}`, key: leaf.key, lines: leaf.lines, reason: "authored" });
382
432
  }
433
+ for (const key of asserted.keys()) {
434
+ const mine = consumerLeaves.blocks.find(l => l.key === key);
435
+ withdrawn.push({ section: `${section}.${block.key}`, key, lines: mine?.lines ?? [], reason: "asserted" });
436
+ }
437
+
383
438
  const dropped = new Set(gone.map(l => l.key));
384
- return {
385
- ...block,
386
- lines: [
387
- ...intro,
388
- ...consumerLeaves.head,
389
- ...consumerLeaves.blocks.filter(l => !dropped.has(l.key)).flatMap(l => l.lines),
390
- ],
391
- };
439
+ const body = [
440
+ ...consumerLeaves.head,
441
+ ...consumerLeaves.blocks
442
+ .filter(l => !dropped.has(l.key))
443
+ .flatMap(l => {
444
+ const value = asserted.get(l.key);
445
+ return value === undefined ? l.lines : [...value, ...splitTrailingBlanks(l.lines)[1]];
446
+ }),
447
+ ];
448
+ const have = new Set(consumerLeaves.blocks.map(l => l.key));
449
+ const added = [...asserted].filter(([key]) => !have.has(key)).flatMap(([, value]) => value);
450
+ const [kept, trailing] = splitTrailingBlanks(body);
451
+ return { ...block, lines: [...intro, ...kept, ...added, ...trailing] };
392
452
  });
393
453
 
394
454
  if (withdrawn.length === 0) return { section: before, withdrawn: [] };
@@ -398,6 +458,28 @@ function withdrawAuthoredPaths(
398
458
  };
399
459
  }
400
460
 
461
+ /** A top-level key line with nothing after the colon but a comment. */
462
+ const SECTION_KEY_LINE = /^[A-Za-z_][A-Za-z0-9_.\-]*:\s*(#.*)?$/;
463
+ /** The same, at any indent: a sub-key that opens a mapping rather than holding a value. */
464
+ const SUB_KEY_LINE = /^\s*[A-Za-z0-9_.\-]+:\s*(#.*)?$/;
465
+
466
+ const indentOf = (line: string): number => line.length - line.trimStart().length;
467
+
468
+ /** Lines moved right (or left) by `shift` columns; blank lines stay blank. */
469
+ function reindent(lines: string[], shift: number): string[] {
470
+ if (shift === 0) return lines;
471
+ return lines.map(l =>
472
+ l.trim() === "" ? l : shift > 0 ? " ".repeat(shift) + l : l.slice(Math.min(-shift, indentOf(l))),
473
+ );
474
+ }
475
+
476
+ /** Two leaves hold the same value when their non-comment lines agree. */
477
+ function sameValue(a: string[], b: string[]): boolean {
478
+ const value = (lines: string[]) =>
479
+ lines.filter(l => l.trim() !== "" && !l.trimStart().startsWith("#")).map(l => l.trimEnd()).join("\n");
480
+ return value(a) === value(b);
481
+ }
482
+
401
483
  /**
402
484
  * The consumer's section with the revoked sub-keys taken out (#923).
403
485
  *
@@ -487,8 +569,12 @@ export interface RevokedSubKey {
487
569
  * names as its own. Reporting the second with the first's sentence sends a
488
570
  * consumer to a config key that has nothing to do with what was removed —
489
571
  * correct-but-misdescribed, which is the expensive kind of accurate.
572
+ *
573
+ * `asserted` is the third (#2292): nothing was withdrawn — the generator's
574
+ * value for an authored path REPLACED the consumer's, or was added where
575
+ * the consumer had none. `lines` holds what it replaced, possibly nothing.
490
576
  */
491
- reason: "computed" | "authored";
577
+ reason: "computed" | "authored" | "asserted";
492
578
  }
493
579
 
494
580
  /**
@@ -930,7 +1016,7 @@ export function mergeManagedWorkflowRecording(
930
1016
  // named this top-level key in `ci.workflowOverrides` has taken the whole
931
1017
  // block back, and reaching into it is the deletion-without-a-route that
932
1018
  // #839's hatch exists to make impossible.
933
- const authored = withdrawAuthoredPaths(section.key, consumer, gen);
1019
+ const authored = applyAuthoredPaths(section.key, consumer, gen);
934
1020
  revoked.push(...authored.withdrawn);
935
1021
  const withdrawn = revokedSubKeys(section.key, authored.section, gen, computed);
936
1022
  revoked.push(...withdrawn);
@@ -153,8 +153,8 @@ export const OWNED_FILES: OwnedFile[] = [
153
153
  path: ".github/workflows/ai-review.yml",
154
154
  strategy: "job-preserving",
155
155
  servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
156
- customize: "Set `ci.vertex` in `.claude/rungate/config.json` to authenticate on Vertex with Workload Identity Federation; add your own jobs alongside the generated `ai-review` job",
157
- avoid: "Don't edit the generated `ai-review` job",
156
+ customize: "Set `ci.vertex` in `.claude/rungate/config.json` to authenticate on Vertex with Workload Identity Federation; add your own triggers or jobs alongside the generated `ai-review` job",
157
+ avoid: "Don't edit the generated `ai-review` job, or the trigger types under `on.pull_request` — scaffold rewrites them (#2292)",
158
158
  },
159
159
  {
160
160
  // #1488. The `workflow_run: completed` half of the AI review: it runs
@@ -168,7 +168,7 @@ export const OWNED_FILES: OwnedFile[] = [
168
168
  strategy: "job-preserving",
169
169
  servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
170
170
  customize: "Set `ci.runner` in `.claude/rungate/config.json`; add your own jobs alongside the generated `record-unmeasured` job",
171
- avoid: "Don't edit the generated `record-unmeasured` job, and don't give it a `merge_group` trigger — it reports no status to the pull request and cannot be a required check",
171
+ avoid: "Don't edit the generated `record-unmeasured` job or give it a `merge_group` trigger — it reports no status, so it cannot be required",
172
172
  },
173
173
  {
174
174
  // #2046, ADR-014 row 3. Hand-written and caller-owned until ADR-013
@@ -187,8 +187,8 @@ export const OWNED_FILES: OwnedFile[] = [
187
187
  path: ".github/workflows/closing-references.yml",
188
188
  strategy: "job-preserving",
189
189
  servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
190
- customize: "Variable `RUNGATE_REQUIRE_CLOSING_REF=true` refuses rather than warns; add your own jobs alongside the generated `closing-references` job",
191
- avoid: "Don't edit the generated `closing-references` job",
190
+ customize: "Variable `RUNGATE_REQUIRE_CLOSING_REF=true` refuses rather than warns; add your own triggers or jobs alongside the generated `closing-references` job",
191
+ avoid: "Don't edit the generated `closing-references` job, or the trigger types under `on.pull_request` — scaffold rewrites them (#2292)",
192
192
  },
193
193
  {
194
194
  // #2047, ADR-014 row 4. Hand-written and caller-owned while it ran this
@@ -220,6 +220,16 @@ export const OWNED_FILES: OwnedFile[] = [
220
220
  customize: "Advisory — a reading never fails the run; add your own jobs alongside the generated `fix-commit-intake` job",
221
221
  avoid: "Don't edit the generated `fix-commit-intake` job, and don't drop `fetch-depth: 0` — a shallow clone reads UNMEASURED",
222
222
  },
223
+ {
224
+ // SC-2780, ADR-018 Decision 1: a push that changes specs/ runs every
225
+ // opted-in family through the engine. A consumer has no scripts/, so the
226
+ // generator writes it and calls the published CLI.
227
+ path: ".github/workflows/specs-placed.yml",
228
+ strategy: "job-preserving",
229
+ servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
230
+ customize: "Opt specs in with a `board:` block; add jobs beside `run-the-engine`",
231
+ avoid: "Don't edit `run-the-engine` or share adr-accepted's group",
232
+ },
223
233
  {
224
234
  // `regenerate` until #655, and the declaration was never consulted:
225
235
  // `generateAgentBriefsStep` called `writeFileSync` directly, so the row
@@ -281,7 +291,7 @@ export const OWNED_FILES: OwnedFile[] = [
281
291
  // #781: whether this project GENERATES the file is a reading, not a
282
292
  // constant — see lib/project-state-derivation.ts. This table has no
283
293
  // root to scan, so it states only the part that is true everywhere.
284
- customize: `${PROJECT_STATE_OWNERSHIP} — maintained by the DA; whether this project derives it from the state JSON is reported per project in .claude/rules/key-files.md`,
294
+ customize: `${PROJECT_STATE_OWNERSHIP} ; whether it is derived from the state JSON is reported in .claude/rules/key-files.md`,
285
295
  avoid: "Don't edit directly; don't expect re-scaffold to update it",
286
296
  },
287
297
  {