rungate 0.8.26 → 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
- 242fddb8d473fcc077837b3b9768f218aa828117b92d2bd7130973f9a753f373
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)",
@@ -154,7 +154,7 @@ export const OWNED_FILES: OwnedFile[] = [
154
154
  strategy: "job-preserving",
155
155
  servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
156
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` — they are the harness's and are rewritten on every scaffold (#2292)",
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
@@ -188,7 +188,7 @@ export const OWNED_FILES: OwnedFile[] = [
188
188
  strategy: "job-preserving",
189
189
  servedBy: "writeManagedFile (lib/scaffold/steps.ts) via mergeManagedWorkflow — the harness owns named jobs, not the file",
190
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` — they are the harness's and are rewritten on every scaffold (#2292)",
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
  {
@@ -0,0 +1,252 @@
1
+ /**
2
+ * `.github/workflows/specs-placed.yml`, generated — SC-2780, ADR-018 Decision 1.
3
+ *
4
+ * A push to main that changes `specs/` runs every opted-in family through the
5
+ * engine with no command typed by hand: milestones from each family's
6
+ * placement table, each open issue moved into the phase its criteria hold,
7
+ * the phase-order links, the queue label, and the board's Criteria column.
8
+ *
9
+ * ## The families are read at RUN time, from the specs
10
+ *
11
+ * `rungate plan-issues --families` prints the opted-in families, one
12
+ * `<prefix><TAB><spec>` line each. It is the same reading `plan-issues
13
+ * --place` takes, so the loop and the placement never disagree about which
14
+ * specs are on the board, and a newly opted-in spec needs no re-scaffold.
15
+ * A spec whose `board:` block or placement table cannot be read makes that
16
+ * command refuse, so the run goes red by name instead of skipping the spec.
17
+ *
18
+ * ## The order is the one each step needs
19
+ *
20
+ * plan-spec per family, so every phase has its milestone
21
+ * plan-issues --place, so issues sit in the phase their criteria hold
22
+ * plan-deps per family, so the links follow the issues' NEW milestones
23
+ * board-mirror --queue-label, because a milestone set by GITHUB_TOKEN
24
+ * fires no `milestoned` event, so phase-order.yml never sees it
25
+ * board-mirror the Criteria column on the board
26
+ *
27
+ * Placing before `plan-deps` is ADR-019 Decision 2: #1722's links follow its
28
+ * move into Phase 10 in the same run.
29
+ *
30
+ * ## It never writes while an earlier ADR placement is running
31
+ *
32
+ * One merge often changes both `specs/` and an ADR, which fires this and
33
+ * `adr-accepted.yml` together, and both write milestones and links (ADR-018,
34
+ * "Not decided here"). A shared `concurrency:` group would serialise them
35
+ * but cancels whatever is pending behind the running run. A cancelled
36
+ * `adr-accepted` run is an accepted ADR whose plan is never placed, with
37
+ * nothing saying so. So this workflow keeps a group of its own, which only
38
+ * cancels its own pending runs, and each of those re-reads the whole tree.
39
+ * Its first step then waits until no `adr-accepted` run created before it is
40
+ * still unfinished.
41
+ *
42
+ * ## It calls the published CLI
43
+ *
44
+ * Like every generated workflow it runs `bunx rungate@<version>`, so the
45
+ * commands it calls must be in a published release before this file is
46
+ * (`docs/guides/RELEASING.md`, "A command a generated workflow calls ships
47
+ * BEFORE the workflow that calls it"). `--families` and `--place` shipped in
48
+ * 0.8.26.
49
+ */
50
+
51
+ import { ADR_ACCEPTED_WORKFLOW_FILE } from "./adr-accepted-workflow";
52
+
53
+ /** The file this module generates, under `.github/workflows/`. */
54
+ export const SPECS_PLACED_WORKFLOW_FILE = "specs-placed.yml";
55
+
56
+ /** The one job in it. */
57
+ export const SPECS_PLACED_JOB = "run-the-engine";
58
+
59
+ /**
60
+ * Every command the job calls, in run order. Each must be registered in
61
+ * `lib/cli-commands.ts`, or the workflow calls a command `bin/rungate.ts`
62
+ * refuses (#675's defect).
63
+ */
64
+ export const SPECS_PLACED_COMMANDS = ["plan-issues", "plan-spec", "plan-deps", "board-mirror"] as const;
65
+
66
+ /** Its own group: it cancels only its own pending runs, each of which re-reads the tree. */
67
+ export const SPECS_PLACED_GROUP = "specs-placed";
68
+
69
+ /** How long the first step waits for an earlier ADR placement, in 20-second polls. */
70
+ export const WAIT_POLLS = 90;
71
+
72
+ export interface SpecsPlacedWorkflowOptions {
73
+ /** The `runs-on:` value, already JSON-quoted by the caller. */
74
+ runsOn: string;
75
+ /** The pinned `actions/checkout` reference. */
76
+ checkout: string;
77
+ /** The pinned `oven-sh/setup-bun` reference. */
78
+ setupBun: string;
79
+ /** The `with:` body of that step, at ten spaces — the project's single bun declaration (#622). */
80
+ setupBunWith: string;
81
+ /** The step's `env:` block, from `setupBunEnv` (#2039). */
82
+ setupBunEnv: string;
83
+ /** The published harness version every step runs through `bunx`. */
84
+ version: string;
85
+ }
86
+
87
+ /**
88
+ * The wait step's script. The GitHub API lists the ADR workflow's runs; any
89
+ * not yet `completed` and created before this run is waited for. Runs created
90
+ * AFTER this one are not, so the two workflows can never wait on each other.
91
+ * Every page is read: the list is newest-first, so an earlier run still going
92
+ * falls off page one once 100 newer runs exist. A list it cannot read fails
93
+ * the step, through `pipefail`, rather than reading as "none unfinished".
94
+ */
95
+ export function buildWaitScript(): string {
96
+ return `set -euo pipefail
97
+ mine=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .created_at)
98
+ for poll in $(seq 1 ${WAIT_POLLS}); do
99
+ earlier=$(gh api --paginate "repos/$GITHUB_REPOSITORY/actions/workflows/${ADR_ACCEPTED_WORKFLOW_FILE}/runs?per_page=100" --jq ".workflow_runs[] | select(.status != \\"completed\\" and .created_at < \\"$mine\\") | .id" | paste -sd ' ' -)
100
+ if [ -z "$earlier" ]; then
101
+ echo "No earlier ${ADR_ACCEPTED_WORKFLOW_FILE} run is unfinished; going ahead."
102
+ exit 0
103
+ fi
104
+ echo "Waiting for ${ADR_ACCEPTED_WORKFLOW_FILE} run(s) $earlier to finish (poll $poll of ${WAIT_POLLS})."
105
+ sleep 20
106
+ done
107
+ echo "::error::${ADR_ACCEPTED_WORKFLOW_FILE} run(s) $earlier are still unfinished after $((${WAIT_POLLS} * 20 / 60)) minutes, so this run wrote nothing rather than write the board beside them. Re-run it once they finish."
108
+ exit 1`;
109
+ }
110
+
111
+ /**
112
+ * A loop over the families file, one command per family. It reads the file on
113
+ * descriptor 3, so a command inside the loop that reads standard input cannot
114
+ * swallow the families after it. One family's refusal does not stop the next;
115
+ * the step exits red at the end, naming every family that refused.
116
+ */
117
+ export function buildFamilyLoop(version: string, command: (cli: string) => string, what: string): string {
118
+ const cli = `bunx rungate@${version}`;
119
+ return `set -uo pipefail
120
+ refused=""
121
+ while IFS=$'\\t' read -r prefix spec <&3; do
122
+ [ -n "$prefix" ] || continue
123
+ echo "== $prefix ($spec)"
124
+ if ! ${command(cli)}; then
125
+ refused="$refused [$prefix]"
126
+ fi
127
+ done 3< families.tsv
128
+ if [ -n "$refused" ]; then
129
+ echo "::error::${what} refused for$refused. Every other family was still run."
130
+ exit 1
131
+ fi`;
132
+ }
133
+
134
+ /** The whole `specs-placed.yml` body. */
135
+ export function buildSpecsPlacedWorkflow(opts: SpecsPlacedWorkflowOptions): string {
136
+ const cli = `bunx rungate@${opts.version}`;
137
+ const indent = (script: string) => script.split("\n").map(l => (l === "" ? "" : ` ${l}`)).join("\n");
138
+ const milestones = buildFamilyLoop(
139
+ opts.version,
140
+ c => `${c} plan-spec "$spec" --repo "$GITHUB_REPOSITORY" --prefix "$prefix" --write`,
141
+ "plan-spec",
142
+ );
143
+ const links = buildFamilyLoop(
144
+ opts.version,
145
+ c => `${c} plan-deps --repo "$GITHUB_REPOSITORY" --milestone-prefix "$prefix" --write`,
146
+ "plan-deps",
147
+ );
148
+
149
+ return `# Managed by rungate — do not edit. Opt a spec in with
150
+ # board: { scope: active, prefix: <Name> } in its frontmatter and give it a
151
+ # placement table; nothing here names a spec.
152
+ #
153
+ # SC-2780 (ADR-018 Decision 1): a push to main that changes specs/ runs every
154
+ # opted-in family through the engine, with no command typed by hand.
155
+ #
156
+ # plan-issues --families which specs are on the board, read at run time
157
+ # plan-spec each family's milestones
158
+ # plan-issues --place each open issue into the phase its criteria hold
159
+ # plan-deps each family's phase-order links, after the moves
160
+ # board-mirror the queue label, then the Criteria column
161
+ #
162
+ # Every command is idempotent, so a re-run writes only what is missing.
163
+ #
164
+ # CREDENTIALS, SPLIT BY STEP. Issue, milestone, label and link writes use the
165
+ # job's own GITHUB_TOKEN. RUNGATE_PROJECT_TOKEN reaches only the board step.
166
+ name: Specs changed — run every opted-in family through the engine
167
+
168
+ on:
169
+ push:
170
+ branches: [main]
171
+ paths: ["specs/**"]
172
+
173
+ permissions:
174
+ contents: read
175
+ # Milestones, issues, labels and blocked-by links.
176
+ issues: write
177
+ # The wait step lists adr-accepted.yml's runs.
178
+ actions: read
179
+
180
+ # Its own group, never adr-accepted's: a shared group cancels the run pending
181
+ # behind the running one, and a cancelled adr-accepted run is a plan that is
182
+ # never placed. The wait step below keeps the two from writing at once.
183
+ concurrency:
184
+ group: ${SPECS_PLACED_GROUP}
185
+ cancel-in-progress: false
186
+
187
+ jobs:
188
+ ${SPECS_PLACED_JOB}:
189
+ runs-on: ${opts.runsOn}
190
+ steps:
191
+ - name: Wait for an earlier ADR placement to finish
192
+ env:
193
+ GH_TOKEN: \${{ github.token }}
194
+ run: |
195
+ ${indent(buildWaitScript())}
196
+
197
+ - uses: ${opts.checkout}
198
+ - uses: ${opts.setupBun}
199
+ with:
200
+ ${opts.setupBunWith}
201
+ ${opts.setupBunEnv}
202
+ # No token: the package is fetched before any step that holds one.
203
+ - id: families
204
+ name: Which specs are on the board?
205
+ run: |
206
+ ${cli} plan-issues --families > families.tsv
207
+ echo "Opted-in families:"
208
+ cat families.tsv
209
+ if [ -s families.tsv ]; then echo "any=true" >> "$GITHUB_OUTPUT"; else echo "any=false" >> "$GITHUB_OUTPUT"; fi
210
+
211
+ - name: Milestones from each family's placement table
212
+ if: steps.families.outputs.any == 'true'
213
+ env:
214
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
215
+ run: |
216
+ ${indent(milestones)}
217
+
218
+ - name: Each open issue into the phase its criteria hold
219
+ if: steps.families.outputs.any == 'true'
220
+ env:
221
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
222
+ run: ${cli} plan-issues --place --repo "$GITHUB_REPOSITORY" --write
223
+
224
+ # \`!cancelled()\`: each of these reads the whole tracker and writes only
225
+ # what is missing, so it never depends on an earlier step succeeding
226
+ # (#2239). The run is still red when one of those failed.
227
+ - name: Phase-order links for each family
228
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
229
+ env:
230
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
231
+ run: |
232
+ ${indent(links)}
233
+
234
+ - name: Queue label on every opted-in family's phase issue
235
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
236
+ env:
237
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
238
+ run: ${cli} board-mirror --queue-label --repo "$GITHUB_REPOSITORY" --write
239
+
240
+ - name: Criteria column on the board
241
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
242
+ env:
243
+ GITHUB_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
244
+ PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
245
+ run: |
246
+ if [ -z "$PROJECT_ID" ]; then
247
+ echo "::error::UNMEASURED — RUNGATE_PROJECT_ID is not set, so there is no board to write."
248
+ exit 1
249
+ fi
250
+ ${cli} board-mirror --project "$PROJECT_ID" --write
251
+ `;
252
+ }
@@ -49,6 +49,7 @@ import {
49
49
  buildAiReviewUnmeasuredWorkflow,
50
50
  } from "./ai-review-unmeasured-workflow";
51
51
  import { buildAdrAcceptedWorkflow } from "./adr-accepted-workflow";
52
+ import { buildSpecsPlacedWorkflow } from "./specs-placed-workflow";
52
53
  import { buildClosingReferencesWorkflow } from "./closing-references-workflow";
53
54
  import { buildIntakeWorkflow } from "./intake-workflow";
54
55
  import { buildBoardReadyWorkflow } from "./board-ready-workflow";
@@ -4504,6 +4505,18 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
4504
4505
  milestonePrefix: boardInputs.milestonePrefix,
4505
4506
  });
4506
4507
 
4508
+ // SC-2780, ADR-018 Decision 1: a push to main that changes specs/ runs
4509
+ // every opted-in family through the engine. The families are read at run
4510
+ // time by the published CLI, so nothing here names a spec.
4511
+ const specsPlacedYml = buildSpecsPlacedWorkflow({
4512
+ runsOn,
4513
+ checkout: actionRef("actions/checkout"),
4514
+ setupBun: actionRef("oven-sh/setup-bun"),
4515
+ setupBunWith: bunStep,
4516
+ setupBunEnv: setupBunEnv(" "),
4517
+ version: harnessVersion(),
4518
+ });
4519
+
4507
4520
  // #2045, ADR-014 row 2: the closing-references check, generated so a
4508
4521
  // consumer gets ADR-013 rule 9 step 4 and this repository's copy is the
4509
4522
  // generated one. It calls the published CLI, at the generating version.
@@ -4567,7 +4580,7 @@ ${buildAuthDetectStep(vertex)}${buildReviewRunStep(
4567
4580
  // lib/conformity.ts reads back, and the two are held together by
4568
4581
  // test/ai-review-workflow.test.ts AC-1, which looks for the constant's
4569
4582
  // filename in what this loop actually wrote.
4570
- for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml], ["ai-review-unmeasured.yml", aiReviewUnmeasuredYml], ["adr-accepted.yml", adrAcceptedYml], ["closing-references.yml", closingReferencesYml], ["board-ready.yml", boardReadyYml], ["board-intake.yml", boardIntakeYml], ["intake.yml", intakeYml]] as const) {
4583
+ for (const [name, content] of [["ci.yml", ciYml], ["gates.yml", gatesYml], ["ai-review.yml", aiReviewYml], ["ai-review-unmeasured.yml", aiReviewUnmeasuredYml], ["adr-accepted.yml", adrAcceptedYml], ["closing-references.yml", closingReferencesYml], ["board-ready.yml", boardReadyYml], ["board-intake.yml", boardIntakeYml], ["intake.yml", intakeYml], ["specs-placed.yml", specsPlacedYml]] as const) {
4571
4584
  const label = `.github/workflows/${name}`;
4572
4585
  try {
4573
4586
  // Keyed by FILE, and the lookup is here because this loop is the only
@@ -927,3 +927,40 @@ export function uncoveredByMilestone(
927
927
  uncovered: a.criteria.filter(id => !names(id)),
928
928
  }));
929
929
  }
930
+
931
+ /**
932
+ * Whether a spec's criteria reach the board — #2275. Only an active `board:`
933
+ * scope opts a spec in (SC-2776); deferred and undeclared are both outside,
934
+ * and `rungate board-scope` names them as NOT TRACKED so "not on the board"
935
+ * never reads as "done".
936
+ */
937
+ export function tracksOnBoard(board: BoardDeclaration): boolean {
938
+ return board.scope === "active";
939
+ }
940
+
941
+ /** The looks-done hint for one unticked criterion — see {@link onboardingHint}. */
942
+ export type OnboardingHint =
943
+ | { kind: "looks-done" }
944
+ | { kind: "ambiguous"; others: string[] }
945
+ | { kind: "cannot-tell"; why: string };
946
+
947
+ /**
948
+ * A HINT, never a tick, for one unticked criterion of `specPath` — #2275.
949
+ *
950
+ * `claimed` is the credit rule's own answer (`claimedScKeys` in
951
+ * scripts/sync-sc-status.ts, read through the caller), so what counts as a
952
+ * test claiming an id is decided in one place. An id that another spec also
953
+ * states is ambiguous and is never matched, even when a test claims it: the
954
+ * claim may be about the other spec's criterion.
955
+ */
956
+ export function onboardingHint(
957
+ id: string,
958
+ specPath: string,
959
+ claimed: (id: string) => boolean,
960
+ declaredBy: ReadonlyMap<string, readonly string[]>,
961
+ ): OnboardingHint {
962
+ const others = (declaredBy.get(id) ?? []).filter(p => p !== specPath);
963
+ if (others.length > 0) return { kind: "ambiguous", others };
964
+ if (claimed(id)) return { kind: "looks-done" };
965
+ return { kind: "cannot-tell", why: "no test claims it in a declaring position" };
966
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.26",
3
+ "version": "0.8.27",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -32,6 +32,7 @@
32
32
  "scripts/board-mirror.ts",
33
33
  "scripts/board-conformance.ts",
34
34
  "scripts/board-snapshot.ts",
35
+ "scripts/board-scope.ts",
35
36
  "scripts/plan-deps.ts",
36
37
  "scripts/plan-issues.ts",
37
38
  "scripts/board-ready.ts",
@@ -267,6 +267,12 @@ export interface DeclaredWork {
267
267
  outside?: string;
268
268
  /** A criterion placed under a value the engine does not know — `declared-work` goes UNMEASURED (SC-2778). */
269
269
  unknownPlacement?: string;
270
+ /**
271
+ * The ADR whose acceptance this change introduces and whose Decomposition
272
+ * row names this criterion (#2323). Its issue is filed when that ADR merges,
273
+ * so until then it is planned, named apart, and never unaccounted.
274
+ */
275
+ planned?: string;
270
276
  }
271
277
 
272
278
  /**
@@ -283,7 +289,9 @@ export function declaredWorkUnaccounted(b: BoardSnapshot): DeclaredWork[] {
283
289
  const named = new Set((b.repoIssues ?? []).flatMap(i => i.names));
284
290
  // SC-2778: a criterion the spec parks outside every phase is declared, not
285
291
  // owed — asking for its issue asks for work the spec says cannot start.
286
- return (b.declaredWork ?? []).filter(w => w.outside === undefined).filter(w =>
292
+ // #2323: a criterion an unmerged ADR plans has no issue YET, because the
293
+ // merge is what files it — owed, but not by anybody who could have filed it.
294
+ return (b.declaredWork ?? []).filter(w => w.outside === undefined && w.planned === undefined).filter(w =>
287
295
  w.kind === "criterion" ? !named.has(w.id) : !(typeof w.issue === "number" && open.has(w.issue)),
288
296
  );
289
297
  }
@@ -468,6 +476,12 @@ export interface Reading {
468
476
  * built elsewhere (a test, a formatter caller) need not invent an empty list.
469
477
  */
470
478
  declared?: string[];
479
+ /**
480
+ * Rows left out of BOTH sides because an ADR this change accepts plans them,
481
+ * and its merge files their issues (#2323). Named apart like {@link declared},
482
+ * under their own heading so a planned criterion never reads as parked.
483
+ */
484
+ planned?: string[];
471
485
  }
472
486
 
473
487
  interface ReadingSpec {
@@ -515,6 +529,8 @@ interface ReadingSpec {
515
529
  offenders?: (board: BoardSnapshot) => string[];
516
530
  /** The rows declared outside every phase, named — see {@link Reading.declared}. */
517
531
  declared?: (board: BoardSnapshot) => string[];
532
+ /** The rows an unmerged ADR plans, named — see {@link Reading.planned}. */
533
+ planned?: (board: BoardSnapshot) => string[];
518
534
  }
519
535
 
520
536
  /** The issue numbers actually on the board, for resolving a reference. */
@@ -891,11 +907,14 @@ export const READINGS: readonly ReadingSpec[] = [
891
907
  unknown.map(w => `${w.id} (${w.source}) is placed ${JSON.stringify(w.unknownPlacement)}`).join("; ");
892
908
  },
893
909
  measure: b => {
894
- const total = b.declaredWork!.filter(w => w.outside === undefined).length;
910
+ const total = b.declaredWork!.filter(w => w.outside === undefined && w.planned === undefined).length;
895
911
  return { measured: total - declaredWorkUnaccounted(b).length, target: total };
896
912
  },
897
913
  offenders: b => declaredWorkUnaccounted(b).map(w => `${w.id} (${w.source}) names no open issue`),
898
914
  declared: b => b.declaredWork!.filter(w => w.outside !== undefined).map(w => `${w.id} (${w.source}) — ${w.outside}`),
915
+ // Every planned row, parked or not: an ADR about to file an issue for a
916
+ // criterion the spec parks is worth seeing on both lines.
917
+ planned: b => b.declaredWork!.filter(w => w.planned !== undefined).map(w => `${w.id} (${w.source}) — ${w.planned}`),
899
918
  },
900
919
  ];
901
920
 
@@ -921,16 +940,17 @@ export function takeReading(spec: ReadingSpec, board: BoardSnapshot | null): Rea
921
940
  // board to hand it. `main` can no longer reach this arm at all (#1718:
922
941
  // every source either produces a board or returns a reason), so the one
923
942
  // way here is an API caller passing null, and that is what it now says.
924
- return { ...base, status: "unmeasured", measured: 0, target: 0, why: "no board snapshot was passed to this reading, so nothing was measured — that is a caller with no board, not a board with nothing on it", offenders: [], declared: [] };
943
+ return { ...base, status: "unmeasured", measured: 0, target: 0, why: "no board snapshot was passed to this reading, so nothing was measured — that is a caller with no board, not a board with nothing on it", offenders: [], declared: [], planned: [] };
925
944
  }
926
945
  const why = spec.unreadable?.(board) ?? null;
927
- if (why !== null) return { ...base, status: "unmeasured", measured: 0, target: 0, why, offenders: [], declared: [] };
946
+ if (why !== null) return { ...base, status: "unmeasured", measured: 0, target: 0, why, offenders: [], declared: [], planned: [] };
928
947
  const { measured, target } = spec.measure(board);
929
948
  const declared = spec.declared?.(board) ?? [];
949
+ const planned = spec.planned?.(board) ?? [];
930
950
  if (target === 0) {
931
- return { ...base, status: "unmeasured", measured, target, why: "the board carries nothing for this reading to count, so 0 of 0 is not a pass", offenders: [], declared };
951
+ return { ...base, status: "unmeasured", measured, target, why: "the board carries nothing for this reading to count, so 0 of 0 is not a pass", offenders: [], declared, planned };
932
952
  }
933
- if (measured >= target) return { ...base, status: "met", measured, target, why: `${measured} of ${target}`, offenders: [], declared };
953
+ if (measured >= target) return { ...base, status: "met", measured, target, why: `${measured} of ${target}`, offenders: [], declared, planned };
934
954
  // Named only here. A met reading never pays for the list, and an
935
955
  // UNMEASURED one must not print rows — it did not read the population it
936
956
  // would be naming them out of.
@@ -942,6 +962,7 @@ export function takeReading(spec: ReadingSpec, board: BoardSnapshot | null): Rea
942
962
  why: `${measured} of ${target} — ${target - measured} short`,
943
963
  offenders: spec.offenders?.(board) ?? [],
944
964
  declared,
965
+ planned,
945
966
  };
946
967
  }
947
968
 
@@ -968,7 +989,10 @@ export function formatReading(r: Reading): string {
968
989
  // denominator silently reads the same as one nobody wrote down.
969
990
  const named = r.declared ?? [];
970
991
  const declared = named.length === 0 ? "" : `\n declared outside phases (${named.length}): ${named.join(", ")}`;
971
- const head = `${mark} ${r.name.padEnd(20)} ${r.why}\n ${r.what} [${r.item}]${declared}`;
992
+ // #2323: work an unmerged ADR plans, whose issues its merge files.
993
+ const plans = r.planned ?? [];
994
+ const planned = plans.length === 0 ? "" : `\n planned by an ADR this change accepts (${plans.length}): ${plans.join(", ")}`;
995
+ const head = `${mark} ${r.name.padEnd(20)} ${r.why}\n ${r.what} [${r.item}]${declared}${planned}`;
972
996
  if (r.offenders.length === 0) return head;
973
997
  const shown = r.offenders.slice(0, OFFENDERS_SHOWN).map(o => `\n ${o}`).join("");
974
998
  const rest = r.offenders.length > OFFENDERS_SHOWN
@@ -1368,7 +1392,18 @@ function normaliseDeclaredWork(raw: unknown): DeclaredWork | null {
1368
1392
  if (raw === null || typeof raw !== "object") return null;
1369
1393
  const r = raw as Record<string, unknown>;
1370
1394
  if (typeof r.id !== "string" || r.id === "" || typeof r.source !== "string") return null;
1371
- if (r.kind === "criterion") return { kind: "criterion", id: r.id, source: r.source, ...placementAnnotation(r) };
1395
+ if (r.kind === "criterion") {
1396
+ // #2323: absent is "not planned"; present and not a path is a row this
1397
+ // command cannot identify, and dropping the mark would count it missing.
1398
+ if ("planned" in r && (typeof r.planned !== "string" || r.planned === "")) return null;
1399
+ return {
1400
+ kind: "criterion",
1401
+ id: r.id,
1402
+ source: r.source,
1403
+ ...placementAnnotation(r),
1404
+ ...(typeof r.planned === "string" ? { planned: r.planned } : {}),
1405
+ };
1406
+ }
1372
1407
  if (r.kind !== "stage-item") return null;
1373
1408
  if (r.issue === null || r.issue === undefined) return { kind: "stage-item", id: r.id, source: r.source, issue: null };
1374
1409
  return typeof r.issue === "number" && Number.isInteger(r.issue)
@@ -0,0 +1,149 @@
1
+ #!/usr/bin/env bun
2
+ /**
3
+ * `rungate board-scope [--spec <path>] [--json]` — #2275.
4
+ *
5
+ * Read-only. Before a maintainer opts an existing spec into the board, this
6
+ * prints what each spec holds: its criteria, how many are ticked, whether it
7
+ * has a placement table, and its `board:` setting. Each unticked criterion
8
+ * gets a looks-done HINT when a test claims its id (`onboardingHint`), or says
9
+ * why it cannot tell. Measured on two consumer repos (2026-11-16): 18 of 59
10
+ * unticked criteria were already done and nothing ticks them, so the
11
+ * checkboxes alone cannot say what is left.
12
+ *
13
+ * It never ticks anything. Ticking stays a person's act, with evidence, and
14
+ * `audit-spec-evidence` already refuses a tick that names no proof.
15
+ *
16
+ * A spec with criteria that is not opted in is listed as NOT TRACKED, a
17
+ * population of its own, so "not on the board" never reads as "done".
18
+ */
19
+ import { readFileSync } from "fs";
20
+ import { join, relative } from "path";
21
+ import { parseArgs } from "util";
22
+ import { specFilesIn } from "../lib/board-mirror";
23
+ import { readDerivedDeclaration } from "../lib/derived-spec";
24
+ import { isTemplateSpec } from "../lib/sc-ids";
25
+ import { parseCriteria } from "../lib/spec-evidence";
26
+ import { boardDeclaration, onboardingHint, parsePlacementRows, tracksOnBoard, type OnboardingHint } from "../lib/spec-placement";
27
+ import { claimedScKeys, scopedKey } from "./sync-sc-status";
28
+
29
+ /** The one exit code every refusal routes through. */
30
+ export const REFUSE_EXIT = 1;
31
+
32
+ export interface SpecScope {
33
+ path: string;
34
+ scope: string;
35
+ tracked: boolean;
36
+ criteria: number;
37
+ ticked: number;
38
+ placementTable: boolean;
39
+ /** Why the `board:` declaration could not be taken as written, by name — empty when it could. */
40
+ boardProblems: string[];
41
+ /** The generator a `generated-by:` copy names: listed, never counted as not tracked. */
42
+ generated?: string;
43
+ hints: { id: string; hint: OnboardingHint }[];
44
+ }
45
+
46
+ /** Why `--spec` may not be opted in, or null. A template's ids are placeholders; a generated copy is not the source. */
47
+ export function optInRefusal(path: string, content: string): string | null {
48
+ if (isTemplateSpec(path)) return `${path} is the spec template; its ids are placeholders, so it is never opted in`;
49
+ const derived = readDerivedDeclaration(content);
50
+ if (derived.status === "derived") {
51
+ return `${path} is generated by ${derived.generator}; opt in the source it is generated from, not this copy`;
52
+ }
53
+ return null;
54
+ }
55
+
56
+ /** Every spec in the sweep, or the one named, read for onboarding. */
57
+ export function boardScope(root: string, only?: string): { specs: SpecScope[] } | { refusal: string } {
58
+ if (only !== undefined) {
59
+ let content: string;
60
+ try {
61
+ content = readFileSync(join(root, only), "utf-8");
62
+ } catch (e) {
63
+ return { refusal: `${only} could not be read (${(e as Error).message})` };
64
+ }
65
+ const refused = optInRefusal(only, content);
66
+ if (refused !== null) return { refusal: refused };
67
+ }
68
+ // The file list, not the id sweep: a tree where no spec states a criterion
69
+ // yet is exactly what a report made before onboarding must still list.
70
+ const sweep = specFilesIn(root);
71
+ if (sweep.reading === "UNMEASURED") return { refusal: `UNMEASURED: the specs/ listing failed: ${sweep.reasons.join("; ")}` };
72
+ if (only !== undefined && !sweep.paths.includes(only)) return { refusal: `${only} is not a spec the sweep reads under specs/` };
73
+
74
+ const texts = new Map(sweep.paths.map(p => [p, readFileSync(join(root, p), "utf-8")]));
75
+ const declaredBy = new Map<string, string[]>();
76
+ for (const [p, text] of texts) {
77
+ for (const c of parseCriteria(text)) declaredBy.set(c.id, [...(declaredBy.get(c.id) ?? []), p]);
78
+ }
79
+ const claimed = claimedScKeys(join(root, "specs"), join(root, "test"));
80
+
81
+ const specs: SpecScope[] = [];
82
+ for (const path of only === undefined ? sweep.paths : [only]) {
83
+ const text = texts.get(path)!;
84
+ const board = boardDeclaration(text);
85
+ const criteria = parseCriteria(text);
86
+ const derived = readDerivedDeclaration(text);
87
+ const specFile = relative(join(root, "specs"), join(root, path));
88
+ const isClaimed = (id: string) => claimed.has(scopedKey(specFile, id));
89
+ specs.push({
90
+ path,
91
+ scope: board.scope,
92
+ tracked: tracksOnBoard(board),
93
+ boardProblems: [...board.problems, ...board.unknownKeys.map(k => `\`board.${k}\` is not a key the engine knows`)],
94
+ criteria: criteria.length,
95
+ ticked: criteria.filter(c => c.ticked).length,
96
+ placementTable: parsePlacementRows(text).length > 0,
97
+ ...(derived.status === "derived" ? { generated: derived.generator } : {}),
98
+ hints: criteria.filter(c => !c.ticked).map(c => ({ id: c.id, hint: onboardingHint(c.id, path, isClaimed, declaredBy) })),
99
+ });
100
+ }
101
+ return { specs };
102
+ }
103
+
104
+ function hintText(h: OnboardingHint): string {
105
+ if (h.kind === "looks-done") return "looks done: a test claims it. Tick it yourself, with proved-by:, if it is";
106
+ if (h.kind === "ambiguous") return `ambiguous: also stated by ${h.others.join(", ")}`;
107
+ return `cannot tell: ${h.why}`;
108
+ }
109
+
110
+ export function formatScope(specs: readonly SpecScope[], named = false): string {
111
+ const lines: string[] = [];
112
+ // A spec asked for by name is always shown, criteria or not (review of #2329).
113
+ const shown = (x: SpecScope) => named || x.criteria > 0;
114
+ for (const s of specs.filter(x => shown(x) && x.generated !== undefined)) {
115
+ lines.push(`${s.path} — generated by ${s.generated}; opt in its source, so it is not counted`);
116
+ }
117
+ for (const s of specs.filter(x => shown(x) && x.generated === undefined)) {
118
+ const state = s.tracked ? `tracked (${s.scope})` : `NOT TRACKED (${s.scope})`;
119
+ lines.push(`${s.path} — ${state}: ${s.criteria} criteria, ${s.ticked} ticked, placement table: ${s.placementTable ? "yes" : "no"}`);
120
+ // A board: block that cannot be read is named, never shown as merely untracked.
121
+ for (const p of s.boardProblems) lines.push(` board: ${p}`);
122
+ for (const { id, hint } of s.hints) lines.push(` ${id} ${hintText(hint)}`);
123
+ }
124
+ const untracked = specs.filter(s => s.criteria > 0 && !s.tracked && s.generated === undefined);
125
+ lines.push(
126
+ "",
127
+ `not tracked: ${untracked.length} spec(s), ${untracked.reduce((n, s) => n + s.criteria, 0)} criteria the board does not show`,
128
+ );
129
+ return lines.join("\n");
130
+ }
131
+
132
+ function main(argv: string[], root = process.cwd()): number {
133
+ let values: { spec?: string; json?: boolean };
134
+ try {
135
+ ({ values } = parseArgs({ args: argv, options: { spec: { type: "string" }, json: { type: "boolean" } }, strict: true }));
136
+ } catch (e) {
137
+ console.error(`board-scope: ${(e as Error).message}`);
138
+ return REFUSE_EXIT;
139
+ }
140
+ const read = boardScope(root, values.spec);
141
+ if ("refusal" in read) {
142
+ console.error(`board-scope: ${read.refusal}`);
143
+ return REFUSE_EXIT;
144
+ }
145
+ console.log(values.json ? JSON.stringify(read.specs, null, 2) : formatScope(read.specs, values.spec !== undefined));
146
+ return 0;
147
+ }
148
+
149
+ if (import.meta.main) process.exit(main(process.argv.slice(2)));
@@ -33,7 +33,7 @@
33
33
  * true by taking it.
34
34
  */
35
35
  import { spawnSync } from "child_process";
36
- import { existsSync, readFileSync } from "fs";
36
+ import { existsSync, readFileSync, readdirSync } from "fs";
37
37
  import { isAbsolute, join, relative } from "path";
38
38
  import { parseArgs } from "util";
39
39
  import { describeSpecSource, resolveSpecSource, type GitRunner } from "../lib/spec-source";
@@ -69,6 +69,7 @@ import { answerableIds, criterionAnswer, specCriteriaIn, specPathSweep } from ".
69
69
  import { dependencyPlan } from "../lib/spec-deps";
70
70
  import type { DeclaredWork, FamilyIssue, PlannedEdge, RepoIssueCriteria, SpecDeferral, SpecPlacementRow } from "./board-conformance";
71
71
  import { parseCriteria } from "../lib/spec-evidence";
72
+ import { hasDecompositionTable, newlyAccepted, parseDecompositionPlan } from "../lib/issue-decomposition";
72
73
 
73
74
  /**
74
75
  * THE one non-zero exit, declared once so `test/board-snapshot.test.ts` can
@@ -274,6 +275,8 @@ export interface ProducedSnapshot {
274
275
  export function readDeclaredWork(
275
276
  root: string,
276
277
  specs: readonly { path: string; state: SpecPlacementRow["state"]; deferred?: boolean; board?: { scope: string } }[],
278
+ /** Criteria an ADR this change accepts plans, from {@link plannedByUnmergedAdr} — #2323. */
279
+ planned: ReadonlyMap<string, string> = new Map(),
277
280
  ): { declaredWork?: DeclaredWork[] } {
278
281
  const work: DeclaredWork[] = [];
279
282
  for (const s of specs) {
@@ -292,7 +295,10 @@ export function readDeclaredWork(
292
295
  // the two readings agree on every criterion the spec parks.
293
296
  const placed = placementsById(content);
294
297
  for (const c of parseCriteria(content)) {
295
- if (!c.ticked) work.push({ kind: "criterion", id: c.id, source: s.path, ...outsidePhases(placed.get(c.id)) });
298
+ if (!c.ticked) {
299
+ const adr = planned.get(c.id);
300
+ work.push({ kind: "criterion", id: c.id, source: s.path, ...outsidePhases(placed.get(c.id)), ...(adr === undefined ? {} : { planned: adr }) });
301
+ }
296
302
  }
297
303
  }
298
304
  const statePath = join(root, "project-state.json");
@@ -329,6 +335,58 @@ export function readDeclaredWork(
329
335
  return { declaredWork: work };
330
336
  }
331
337
 
338
+ /** The ref an ADR's acceptance is read against: the main every reading here is about. */
339
+ export const PLANNED_ADR_REF = "origin/main";
340
+
341
+ /**
342
+ * Criteria planned by an ADR whose acceptance this tree introduces — #2323.
343
+ *
344
+ * An ADR that adds criteria to an opted-in spec states them before their
345
+ * issues exist, because merging the ADR is what files them (AGENTS.md rule 9
346
+ * step 3, `adr-accepted.yml`). On its own pull request `declared-work` would
347
+ * read each as "names no open issue", and the live stage ladder would refuse
348
+ * the merge that is the only way to file them.
349
+ *
350
+ * So a criterion a Decomposition row names is planned when that ADR is
351
+ * accepted in this tree and was not accepted at {@link PLANNED_ADR_REF}:
352
+ * `newlyAccepted`, the same decider `plan-issues --accepted-since` uses.
353
+ * An ADR already accepted on main is not this change's plan, and its missing
354
+ * issue is a real gap: `adr-accepted.yml` did not place it.
355
+ *
356
+ * Fails closed: a ref that does not resolve, a git that does not run, or an
357
+ * answer this cannot read exempts NOTHING, so every criterion reads as missing.
358
+ * Returns criterion id → the ADR's repo-relative path.
359
+ */
360
+ export function plannedByUnmergedAdr(root: string, git: GitRunner): Map<string, string> {
361
+ const dir = join(root, "docs", "adr");
362
+ if (!existsSync(dir)) return new Map();
363
+ const planned = new Map<string, string>();
364
+ for (const name of readdirSync(dir).filter(n => /^ADR-\d+.*\.md$/.test(n)).sort()) {
365
+ const rel = `docs/adr/${name}`;
366
+ const text = readFileSync(join(dir, name), "utf-8");
367
+ if (!hasDecompositionTable(text)) continue;
368
+ const at = git(["cat-file", "-e", `${PLANNED_ADR_REF}:${rel}`]);
369
+ if (at.code === null) return new Map();
370
+ let before: string | null = null;
371
+ if (at.ok) {
372
+ const shown = git(["show", `${PLANNED_ADR_REF}:${rel}`]);
373
+ if (!shown.ok) return new Map();
374
+ before = shown.stdout;
375
+ } else if (!/does not exist|exists on disk, but not in/.test(at.stderr)) {
376
+ // THE ONE fail-closed decider for the ref. A ref that does not resolve
377
+ // says "invalid object name", which is not "the path is absent at the
378
+ // ref", so an unreadable origin/main exempts nothing. A separate
379
+ // rev-parse probe would be a second decider for the same question.
380
+ return new Map();
381
+ }
382
+ if (!newlyAccepted(before, text)) continue;
383
+ const plan = parseDecompositionPlan(text);
384
+ if (plan.reading !== "MEASURED") continue;
385
+ for (const row of plan.rows) if (!planned.has(row.criterion)) planned.set(row.criterion, rel);
386
+ }
387
+ return planned;
388
+ }
389
+
332
390
  /** The path the deferral bank lives at, relative to the project root — SC-2734. */
333
391
  export const DEFERRAL_BANK = ".claude/spec-deferral-ratchet.json";
334
392
 
@@ -969,7 +1027,10 @@ export async function main(
969
1027
  // readings cannot disagree about which specs are in scope. A sweep that
970
1028
  // could not enumerate `specs/` emits no rows, and `declared-work` is then
971
1029
  // UNMEASURED rather than a stage-only count.
972
- const declared = placements.specPlacements === undefined ? {} : readDeclaredWork(root, placements.specPlacements);
1030
+ const declared =
1031
+ placements.specPlacements === undefined
1032
+ ? {}
1033
+ : readDeclaredWork(root, placements.specPlacements, plannedByUnmergedAdr(root, git(root)));
973
1034
 
974
1035
  // #2223 / E4. Emitted only when the column was actually queried: no board,
975
1036
  // a mismatched field, or a failed read all omit the key, and