rungate 0.8.26 → 0.8.28

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.
@@ -0,0 +1,215 @@
1
+ /**
2
+ * #2307: every spec declares a board scope, so none drops out of the measure.
3
+ *
4
+ * Since ADR-018 (SC-2776) a spec counts only when its frontmatter opts in with
5
+ * a `board:` block. A spec with no block is neither measured nor banked, so a
6
+ * spec that never had one, or lost it, leaves the engine's view without a
7
+ * word. Jason's call of 2026-11-17 on #2301: scaffold writes the frontmatter,
8
+ * so the readings are accurate.
9
+ *
10
+ * **Deferred is the only value written.** ADR-018 Decision 8 makes opt-in a
11
+ * person's choice, because a consumer's checkboxes do not say what is done.
12
+ * Deferred says "known, held back", which is true of every spec nobody has
13
+ * opted in, and it keeps the spec visible: `board-conformance` banks it.
14
+ *
15
+ * Three things are never written: a spec that already declares a scope
16
+ * (active, deferred, or a declaration the engine cannot read, which
17
+ * `board-conformance` already names), the spec template, and a spec a
18
+ * generator owns. The last is `writeSpec`'s refusal (#1552), asked before any
19
+ * work is planned.
20
+ *
21
+ * **The bank moves in the same run.** SC-2734 refuses a deferred spec the
22
+ * deferral bank does not hold at its criteria count, so a scaffold that wrote
23
+ * the line without the bank would turn the next pull request red on a file
24
+ * its author never opened. Specs and bank are written all or nothing.
25
+ */
26
+ import { existsSync, mkdirSync, readFileSync } from "fs";
27
+ import { dirname, join } from "path";
28
+ import { specFilesIn } from "../board-mirror";
29
+ import { readBoardInputs } from "../config-readers";
30
+ import { isTemplateSpec } from "../sc-ids";
31
+ import { boardDeclaration, placementReading } from "../spec-placement";
32
+ import { maySpecBeWritten, writeSpec } from "../write-spec";
33
+
34
+ /** The one line this step writes. */
35
+ export const DEFERRED_LINE = "board: { scope: deferred }";
36
+
37
+ /** The spec with {@link DEFERRED_LINE} as its frontmatter's last key, or null when it has no frontmatter to add it to. */
38
+ export function withDeferredScope(content: string): string | null {
39
+ const m = /^---(\r?\n)([\s\S]*?)(\r?\n)---(?=\r?\n|$)/.exec(content);
40
+ if (m === null) return null;
41
+ const [whole, nl, body, close] = m;
42
+ return `---${nl}${body}${close}${DEFERRED_LINE}${close}---${content.slice(whole.length)}`;
43
+ }
44
+
45
+ export interface ScopeWrite {
46
+ path: string;
47
+ before: string;
48
+ after: string;
49
+ criteria: number;
50
+ }
51
+
52
+ /**
53
+ * What a scaffold would write: each undeclared spec with the line added, and
54
+ * the specs it leaves alone with the reason. Reads only.
55
+ */
56
+ export function planDeferredScopes(root: string): { refusal: string } | { writes: ScopeWrite[]; skipped: string[] } {
57
+ const sweep = specFilesIn(root);
58
+ if (sweep.reading === "UNMEASURED") return { refusal: `the specs/ listing failed: ${sweep.reasons.join("; ")}` };
59
+ const writes: ScopeWrite[] = [];
60
+ const skipped: string[] = [];
61
+ // The configured engine spec is never deferred. Deferring it would take the
62
+ // engine family out of every reading, which is the opposite of what this
63
+ // step is for. It is named with the block that opts it in, and opting in
64
+ // stays a person's choice (ADR-018 Decision 8). Raised by the consumer that
65
+ // hit it, before #2335 merged.
66
+ const { engineSpec, milestonePrefix } = readBoardInputs(root);
67
+ for (const path of sweep.paths) {
68
+ if (isTemplateSpec(path)) continue;
69
+ const before = readFileSync(join(root, path), "utf-8");
70
+ if (boardDeclaration(before).scope !== "undeclared") continue;
71
+ // A generated copy is never rewritten here, but it is named: a scaffold
72
+ // that skipped it in silence would leave it out of the measure forever,
73
+ // which is what this step exists to stop (review of #2335).
74
+ const owned = maySpecBeWritten(before);
75
+ if (!owned.allowed) {
76
+ const reading = owned.reading;
77
+ skipped.push(
78
+ reading.status === "derived"
79
+ ? `${path} is generated by ${reading.generator} and declares no board scope; add the scope where ${reading.generator} writes it, not here`
80
+ : // Only prose says it is generated, so there is no generator to name: quote the prose, as skipLine does (review of #2335).
81
+ `${path} reads as generated from prose only (${reading.evidence}) and declares no board scope, so it was not deferred; ` +
82
+ "add generated-by: <generator> to its frontmatter and the scope where that generator writes it",
83
+ );
84
+ continue;
85
+ }
86
+ if (engineSpec !== null && path === engineSpec.replace(/^\.\//, "")) {
87
+ skipped.push(
88
+ `${path} is the configured engine spec (board.engineSpec) and declares no board scope, so it was not deferred; ` +
89
+ `add board: { scope: active, prefix: ${milestonePrefix ?? "<board.milestonePrefix>"} } to its frontmatter to opt it in`,
90
+ );
91
+ continue;
92
+ }
93
+ const after = withDeferredScope(before);
94
+ if (after === null) {
95
+ skipped.push(`${path} has no frontmatter, so no board scope was added; the engine ignores it until it declares one`);
96
+ continue;
97
+ }
98
+ // The line must read back as deferred. A frontmatter the parser refuses
99
+ // would read the new line as `invalid`, which is a different problem from
100
+ // the one this step exists for and is not this step's to paper over.
101
+ if (boardDeclaration(after).scope !== "deferred") {
102
+ skipped.push(`${path}: its frontmatter cannot be read, so a board scope added to it would not read as deferred`);
103
+ continue;
104
+ }
105
+ writes.push({ path, before, after, criteria: placementReading(after).criteria.length });
106
+ }
107
+ return { writes, skipped };
108
+ }
109
+
110
+ /**
111
+ * The deferral bank with each newly deferred spec added at its count.
112
+ *
113
+ * An absent bank is created: a consumer that has never deferred a spec has
114
+ * none. A bank that is present and unreadable refuses, and so does one that
115
+ * already holds a spec this step is about to defer. That row belongs to a spec
116
+ * the engine does not read as deferred, which is drift somebody has to look
117
+ * at, and overwriting it would hide it.
118
+ */
119
+ export function bankWithNewDeferrals(
120
+ bankText: string | null,
121
+ rows: readonly { path: string; criteria: number }[],
122
+ ): { ok: true; text: string } | { ok: false; why: string } {
123
+ let bank: { deferred?: unknown } = { deferred: [] };
124
+ if (bankText !== null) {
125
+ try {
126
+ bank = JSON.parse(bankText);
127
+ } catch (e) {
128
+ return { ok: false, why: `the deferral bank is not JSON (${(e as Error).message})` };
129
+ }
130
+ if (typeof bank !== "object" || bank === null || !Array.isArray(bank.deferred)) {
131
+ return { ok: false, why: "the deferral bank has no `deferred` list" };
132
+ }
133
+ }
134
+ const held = bank.deferred as { path: string; criteria: number }[];
135
+ const clash = rows.filter(r => held.some(d => d.path === r.path)).map(r => r.path);
136
+ if (clash.length > 0) {
137
+ return { ok: false, why: `the deferral bank already holds ${clash.join(", ")}, which declare no scope; reconcile it first` };
138
+ }
139
+ const deferred = [...held, ...rows.map(r => ({ path: r.path, criteria: r.criteria }))].sort((a, b) =>
140
+ a.path < b.path ? -1 : a.path > b.path ? 1 : 0,
141
+ );
142
+ return { ok: true, text: `${JSON.stringify({ ...bank, deferred }, null, 2)}\n` };
143
+ }
144
+
145
+ /**
146
+ * The scaffold step: add {@link DEFERRED_LINE} to every undeclared spec, bank
147
+ * each one, and name every file written. A re-scaffold over specs that all
148
+ * declare a scope writes nothing and reports nothing.
149
+ */
150
+ /** The writer the step writes through: `writeSpec`, or a stand-in in a test. */
151
+ export type ScopeWriter = (path: string, content: string) => { written: boolean; refusal?: string | null };
152
+
153
+ export function deferUndeclaredSpecs(root: string, actions: string[], writer?: ScopeWriter): void {
154
+ if (!existsSync(join(root, "specs"))) return;
155
+ const plan = planDeferredScopes(root);
156
+ if ("refusal" in plan) {
157
+ actions.push(`REFUSED: spec board scopes (${plan.refusal}) — nothing was written`);
158
+ return;
159
+ }
160
+ for (const s of plan.skipped) actions.push(`SKIP: ${s}`);
161
+ if (plan.writes.length === 0) return;
162
+
163
+ // A literal path, so the spec-write sweep (#1584) resolves this write to
164
+ // the bank rather than reading an opaque target.
165
+ const bankPath = join(root, ".claude/spec-deferral-ratchet.json");
166
+ const banked = bankWithNewDeferrals(existsSync(bankPath) ? readFileSync(bankPath, "utf-8") : null, plan.writes);
167
+ if (!banked.ok) {
168
+ actions.push(`REFUSED: spec board scopes (${banked.why}) — nothing was written`);
169
+ return;
170
+ }
171
+ // Spelled `writeSpec(bankPath, …)` so write accountability (#624) resolves
172
+ // the bank write to the bank, as create-sc's does.
173
+ const write: ScopeWriter = writer ?? ((p, c) => (p === bankPath ? writeSpec(bankPath, c) : writeSpec(p, c)));
174
+
175
+ // All or nothing: a spec written without its bank row reddens SC-2734, so a
176
+ // failed write puts back every spec already written.
177
+ const written: ScopeWrite[] = [];
178
+ const undo = (why: string) => {
179
+ // A restore can fail for the same reason the write did (a full disk, a
180
+ // read-only tree). It is caught and counted, never thrown, so the run ends
181
+ // in a refusal naming every spec left deferred without a bank row
182
+ // (review of #2335).
183
+ const putBack = (w: ScopeWrite) => {
184
+ try {
185
+ return write(join(root, w.path), w.before).written;
186
+ } catch {
187
+ return false;
188
+ }
189
+ };
190
+ const stuck = written.filter(w => !putBack(w)).map(w => w.path);
191
+ actions.push(
192
+ stuck.length === 0
193
+ ? `REFUSED: spec board scopes (${why}) — nothing was written`
194
+ : `REFUSED: spec board scopes (${why}), and ${stuck.join(", ")} could not be put back: each declares a deferred scope the bank does not hold`,
195
+ );
196
+ };
197
+ // A throw is a failed write too: one that escaped would leave the specs
198
+ // already written with no bank row, which is the state this step exists
199
+ // to prevent.
200
+ try {
201
+ mkdirSync(dirname(bankPath), { recursive: true });
202
+ for (const w of plan.writes) {
203
+ const r = write(join(root, w.path), w.after);
204
+ if (!r.written) return undo(`${w.path} was not written: ${r.refusal ?? "no reason given"}`);
205
+ written.push(w);
206
+ }
207
+ const bankWrite = write(bankPath, banked.text);
208
+ if (!bankWrite.written) return undo(`the deferral bank was not written: ${bankWrite.refusal ?? "no reason given"}`);
209
+ } catch (e) {
210
+ return undo(`a write threw: ${(e as Error).message}`);
211
+ }
212
+
213
+ for (const w of plan.writes) actions.push(`UPDATED: ${w.path} (${DEFERRED_LINE} — it declared no scope)`);
214
+ actions.push(`UPDATED: .claude/spec-deferral-ratchet.json (${plan.writes.length} spec(s) banked as deferred)`);
215
+ }
@@ -0,0 +1,249 @@
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
+ import { boardProjectRun } from "./board-project-step";
53
+
54
+ /** The file this module generates, under `.github/workflows/`. */
55
+ export const SPECS_PLACED_WORKFLOW_FILE = "specs-placed.yml";
56
+
57
+ /** The one job in it. */
58
+ export const SPECS_PLACED_JOB = "run-the-engine";
59
+
60
+ /**
61
+ * Every command the job calls, in run order. Each must be registered in
62
+ * `lib/cli-commands.ts`, or the workflow calls a command `bin/rungate.ts`
63
+ * refuses (#675's defect).
64
+ */
65
+ export const SPECS_PLACED_COMMANDS = ["plan-issues", "plan-spec", "plan-deps", "board-mirror"] as const;
66
+
67
+ /** Its own group: it cancels only its own pending runs, each of which re-reads the tree. */
68
+ export const SPECS_PLACED_GROUP = "specs-placed";
69
+
70
+ /** How long the first step waits for an earlier ADR placement, in 20-second polls. */
71
+ export const WAIT_POLLS = 90;
72
+
73
+ export interface SpecsPlacedWorkflowOptions {
74
+ /** The `runs-on:` value, already JSON-quoted by the caller. */
75
+ runsOn: string;
76
+ /** The pinned `actions/checkout` reference. */
77
+ checkout: string;
78
+ /** The pinned `oven-sh/setup-bun` reference. */
79
+ setupBun: string;
80
+ /** The `with:` body of that step, at ten spaces — the project's single bun declaration (#622). */
81
+ setupBunWith: string;
82
+ /** The step's `env:` block, from `setupBunEnv` (#2039). */
83
+ setupBunEnv: string;
84
+ /** The published harness version every step runs through `bunx`. */
85
+ version: string;
86
+ }
87
+
88
+ /**
89
+ * The wait step's script. The GitHub API lists the ADR workflow's runs; any
90
+ * not yet `completed` and created before this run is waited for. Runs created
91
+ * AFTER this one are not, so the two workflows can never wait on each other.
92
+ * Every page is read: the list is newest-first, so an earlier run still going
93
+ * falls off page one once 100 newer runs exist. A list it cannot read fails
94
+ * the step, through `pipefail`, rather than reading as "none unfinished".
95
+ */
96
+ export function buildWaitScript(): string {
97
+ return `set -euo pipefail
98
+ mine=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .created_at)
99
+ for poll in $(seq 1 ${WAIT_POLLS}); do
100
+ 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 ' ' -)
101
+ if [ -z "$earlier" ]; then
102
+ echo "No earlier ${ADR_ACCEPTED_WORKFLOW_FILE} run is unfinished; going ahead."
103
+ exit 0
104
+ fi
105
+ echo "Waiting for ${ADR_ACCEPTED_WORKFLOW_FILE} run(s) $earlier to finish (poll $poll of ${WAIT_POLLS})."
106
+ sleep 20
107
+ done
108
+ 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."
109
+ exit 1`;
110
+ }
111
+
112
+ /**
113
+ * A loop over the families file, one command per family. It reads the file on
114
+ * descriptor 3, so a command inside the loop that reads standard input cannot
115
+ * swallow the families after it. One family's refusal does not stop the next;
116
+ * the step exits red at the end, naming every family that refused.
117
+ */
118
+ export function buildFamilyLoop(version: string, command: (cli: string) => string, what: string): string {
119
+ const cli = `bunx rungate@${version}`;
120
+ return `set -uo pipefail
121
+ refused=""
122
+ while IFS=$'\\t' read -r prefix spec <&3; do
123
+ [ -n "$prefix" ] || continue
124
+ echo "== $prefix ($spec)"
125
+ if ! ${command(cli)}; then
126
+ refused="$refused [$prefix]"
127
+ fi
128
+ done 3< families.tsv
129
+ if [ -n "$refused" ]; then
130
+ echo "::error::${what} refused for$refused. Every other family was still run."
131
+ exit 1
132
+ fi`;
133
+ }
134
+
135
+ /** The whole `specs-placed.yml` body. */
136
+ export function buildSpecsPlacedWorkflow(opts: SpecsPlacedWorkflowOptions): string {
137
+ const cli = `bunx rungate@${opts.version}`;
138
+ const indent = (script: string) => script.split("\n").map(l => (l === "" ? "" : ` ${l}`)).join("\n");
139
+ const milestones = buildFamilyLoop(
140
+ opts.version,
141
+ c => `${c} plan-spec "$spec" --repo "$GITHUB_REPOSITORY" --prefix "$prefix" --write`,
142
+ "plan-spec",
143
+ );
144
+ const links = buildFamilyLoop(
145
+ opts.version,
146
+ c => `${c} plan-deps --repo "$GITHUB_REPOSITORY" --milestone-prefix "$prefix" --write`,
147
+ "plan-deps",
148
+ );
149
+
150
+ return `# Managed by rungate — do not edit. Opt a spec in with
151
+ # board: { scope: active, prefix: <Name> } in its frontmatter and give it a
152
+ # placement table; nothing here names a spec.
153
+ #
154
+ # SC-2780 (ADR-018 Decision 1): a push to main that changes specs/ runs every
155
+ # opted-in family through the engine, with no command typed by hand.
156
+ #
157
+ # plan-issues --families which specs are on the board, read at run time
158
+ # plan-spec each family's milestones
159
+ # plan-issues --place each open issue into the phase its criteria hold
160
+ # plan-deps each family's phase-order links, after the moves
161
+ # board-mirror the queue label, then the Criteria column
162
+ #
163
+ # Every command is idempotent, so a re-run writes only what is missing.
164
+ #
165
+ # CREDENTIALS, SPLIT BY STEP. Issue, milestone, label and link writes use the
166
+ # job's own GITHUB_TOKEN. RUNGATE_PROJECT_TOKEN reaches only the board step.
167
+ name: Specs changed — run every opted-in family through the engine
168
+
169
+ on:
170
+ push:
171
+ branches: [main]
172
+ paths: ["specs/**"]
173
+
174
+ permissions:
175
+ contents: read
176
+ # Milestones, issues, labels and blocked-by links.
177
+ issues: write
178
+ # The wait step lists adr-accepted.yml's runs.
179
+ actions: read
180
+
181
+ # Its own group, never adr-accepted's: a shared group cancels the run pending
182
+ # behind the running one, and a cancelled adr-accepted run is a plan that is
183
+ # never placed. The wait step below keeps the two from writing at once.
184
+ concurrency:
185
+ group: ${SPECS_PLACED_GROUP}
186
+ cancel-in-progress: false
187
+
188
+ jobs:
189
+ ${SPECS_PLACED_JOB}:
190
+ runs-on: ${opts.runsOn}
191
+ steps:
192
+ - name: Wait for an earlier ADR placement to finish
193
+ env:
194
+ GH_TOKEN: \${{ github.token }}
195
+ run: |
196
+ ${indent(buildWaitScript())}
197
+
198
+ - uses: ${opts.checkout}
199
+ - uses: ${opts.setupBun}
200
+ with:
201
+ ${opts.setupBunWith}
202
+ ${opts.setupBunEnv}
203
+ # No token: the package is fetched before any step that holds one.
204
+ - id: families
205
+ name: Which specs are on the board?
206
+ run: |
207
+ ${cli} plan-issues --families > families.tsv
208
+ echo "Opted-in families:"
209
+ cat families.tsv
210
+ if [ -s families.tsv ]; then echo "any=true" >> "$GITHUB_OUTPUT"; else echo "any=false" >> "$GITHUB_OUTPUT"; fi
211
+
212
+ - name: Milestones from each family's placement table
213
+ if: steps.families.outputs.any == 'true'
214
+ env:
215
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
216
+ run: |
217
+ ${indent(milestones)}
218
+
219
+ - name: Each open issue into the phase its criteria hold
220
+ if: steps.families.outputs.any == 'true'
221
+ env:
222
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
223
+ run: ${cli} plan-issues --place --repo "$GITHUB_REPOSITORY" --write
224
+
225
+ # \`!cancelled()\`: each of these reads the whole tracker and writes only
226
+ # what is missing, so it never depends on an earlier step succeeding
227
+ # (#2239). The run is still red when one of those failed.
228
+ - name: Phase-order links for each family
229
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
230
+ env:
231
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
232
+ run: |
233
+ ${indent(links)}
234
+
235
+ - name: Queue label on every opted-in family's phase issue
236
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
237
+ env:
238
+ GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
239
+ run: ${cli} board-mirror --queue-label --repo "$GITHUB_REPOSITORY" --write
240
+
241
+ - name: Criteria column on the board
242
+ if: \${{ !cancelled() && steps.families.outputs.any == 'true' }}
243
+ env:
244
+ GITHUB_TOKEN: \${{ secrets.RUNGATE_PROJECT_TOKEN }}
245
+ PROJECT_ID: \${{ vars.RUNGATE_PROJECT_ID }}
246
+ run: |
247
+ ${indent(boardProjectRun(cli, "Criteria column", `${cli} board-mirror --project "$project" --write`))}
248
+ `;
249
+ }
@@ -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
@@ -50,9 +50,11 @@ import {
50
50
  addFrontmatterToSpecs, addFrontmatterToAdrs, detectOversizedSpecs,
51
51
  checkGovernsAlignment, detectMisplacedSpecs, detectUnconvertedSpecs,
52
52
  } from "../validators/spec-validators";
53
- import { ensureConfigTrackable } from "../config-trackable";
53
+ import { ensureConfigTrackable, reportIgnoredOwnedFiles } from "../config-trackable";
54
54
  import type { ProjectType } from "../generators/types";
55
55
  import { DEFAULT_PROFILE, isStepIncluded, type ScaffoldProfile } from "./profiles";
56
+ import { deferUndeclaredSpecs } from "./spec-scope";
57
+ import { OWNED_FILES } from "./owned-files";
56
58
 
57
59
  export interface WriteStepOptions {
58
60
  force?: boolean;
@@ -190,6 +192,9 @@ What does this workflow produce?
190
192
 
191
193
  // Phase 3: Final setup
192
194
  copySpecTemplateIfEmpty(join(projectPath, "specs"), actions);
195
+ // #2307: a spec with no board scope is out of every measurement, silently.
196
+ // Both profiles: the measurement is wrong either way.
197
+ deferUndeclaredSpecs(projectPath, actions);
193
198
  generateProjectState(projectPath, actions);
194
199
  // Both profiles. #485 is about the file existing at all, and `minimal` is
195
200
  // the profile the consumer that found the gap was scaffolded with.
@@ -213,6 +218,9 @@ What does this workflow produce?
213
218
  generateCodeMapStep(projectPath, actions);
214
219
  }
215
220
 
221
+ // Last before the commit, so it reads every file this run wrote (#2347).
222
+ reportIgnoredOwnedFiles(projectPath, actions, OWNED_FILES.map(f => f.path));
223
+
216
224
  // Leaves the tree. See STEPS_NOT_REHEARSED.
217
225
  if (!rehearsing) postScaffoldCommit(projectPath, actions, { commit });
218
226
  }
@@ -349,8 +349,60 @@ export interface BoardDeclaration {
349
349
  export const BOARD_KEYS: Readonly<Record<string, { what: string; values?: readonly string[] }>> = {
350
350
  scope: { what: "whether the engine consumes this spec", values: ["active", "deferred"] },
351
351
  prefix: { what: "the milestone family the spec's phases are named in" },
352
+ // Jason's call of 2026-11-17, a stopgap ahead of #2331. It is read by
353
+ // `plan-deps` through {@link phaseOrderFor}.
354
+ phaseOrder: {
355
+ what:
356
+ "whether plan-deps writes the family's phase order as blocked-by links; false means phases set priority " +
357
+ "and only real blocked-by links hold work back",
358
+ values: ["true", "false"],
359
+ },
352
360
  };
353
361
 
362
+ /**
363
+ * Whether `plan-deps` writes a family's phase order, read from every spec that
364
+ * names the family as its `board.prefix`. Absent means on, which is how
365
+ * every family behaved before the key existed.
366
+ *
367
+ * Specs of one family that disagree are unreadable, not resolved: picking
368
+ * either is the guess {@link boardDeclaration} exists not to make.
369
+ */
370
+ export function phaseOrderFor(
371
+ specs: readonly { path: string; text: string }[],
372
+ prefix: string,
373
+ ): { kind: "on" } | { kind: "off"; spec: string } | { kind: "unreadable"; why: string } {
374
+ const family = specs
375
+ .map(s => ({ path: s.path, board: boardDeclaration(s.text) }))
376
+ .filter(s => s.board.settings.prefix === prefix);
377
+ // A declaration the engine cannot read — `phaseOrder: flase` among them, since
378
+ // `boardDeclaration` checks every key's values — refuses rather than reading
379
+ // the raw text as "not false", which would be on (review of #2352).
380
+ // A deferred spec is shelved, so its problems are not the family's (round 2
381
+ // of the same review). One whose scope cannot be read may be active, so it counts.
382
+ const unreadable = family.find(s => s.board.problems.length > 0 && s.board.scope !== "deferred");
383
+ if (unreadable !== undefined) {
384
+ return {
385
+ kind: "unreadable",
386
+ why: `${unreadable.path}: its board: declaration cannot be read, so family ${prefix}'s phaseOrder cannot be — ${unreadable.board.problems.join("; ")}`,
387
+ };
388
+ }
389
+ // Only an active spec is the family; a deferred one carrying the prefix is shelved (review of #2352).
390
+ const declared = family
391
+ .filter(s => s.board.scope === "active")
392
+ .map(s => ({ path: s.path, value: s.board.settings.phaseOrder ?? "true" }));
393
+ const off = declared.filter(d => d.value === "false");
394
+ const on = declared.filter(d => d.value !== "false");
395
+ if (off.length > 0 && on.length > 0) {
396
+ return {
397
+ kind: "unreadable",
398
+ why:
399
+ `the specs of family ${prefix} disagree on board.phaseOrder: ${off[0]!.path} says false and ${on[0]!.path} says ` +
400
+ `${on[0]!.value}, so whether to write its phase order cannot be read`,
401
+ };
402
+ }
403
+ return off.length > 0 ? { kind: "off", spec: off[0]!.path } : { kind: "on" };
404
+ }
405
+
354
406
  /**
355
407
  * One frontmatter entry's value, parsed as YAML — only that entry, never the
356
408
  * whole block. Whole-block YAML is not available here: the engine spec's own
@@ -927,3 +979,40 @@ export function uncoveredByMilestone(
927
979
  uncovered: a.criteria.filter(id => !names(id)),
928
980
  }));
929
981
  }
982
+
983
+ /**
984
+ * Whether a spec's criteria reach the board — #2275. Only an active `board:`
985
+ * scope opts a spec in (SC-2776); deferred and undeclared are both outside,
986
+ * and `rungate board-scope` names them as NOT TRACKED so "not on the board"
987
+ * never reads as "done".
988
+ */
989
+ export function tracksOnBoard(board: BoardDeclaration): boolean {
990
+ return board.scope === "active";
991
+ }
992
+
993
+ /** The looks-done hint for one unticked criterion — see {@link onboardingHint}. */
994
+ export type OnboardingHint =
995
+ | { kind: "looks-done" }
996
+ | { kind: "ambiguous"; others: string[] }
997
+ | { kind: "cannot-tell"; why: string };
998
+
999
+ /**
1000
+ * A HINT, never a tick, for one unticked criterion of `specPath` — #2275.
1001
+ *
1002
+ * `claimed` is the credit rule's own answer (`claimedScKeys` in
1003
+ * scripts/sync-sc-status.ts, read through the caller), so what counts as a
1004
+ * test claiming an id is decided in one place. An id that another spec also
1005
+ * states is ambiguous and is never matched, even when a test claims it: the
1006
+ * claim may be about the other spec's criterion.
1007
+ */
1008
+ export function onboardingHint(
1009
+ id: string,
1010
+ specPath: string,
1011
+ claimed: (id: string) => boolean,
1012
+ declaredBy: ReadonlyMap<string, readonly string[]>,
1013
+ ): OnboardingHint {
1014
+ const others = (declaredBy.get(id) ?? []).filter(p => p !== specPath);
1015
+ if (others.length > 0) return { kind: "ambiguous", others };
1016
+ if (claimed(id)) return { kind: "looks-done" };
1017
+ return { kind: "cannot-tell", why: "no test claims it in a declaring position" };
1018
+ }
@@ -125,7 +125,7 @@ const STANDING_ROW = /^\|\s*(\d+)\s*(?:[—–-][^|]*)?\|/;
125
125
  */
126
126
  const UNFILLED = /^(TODO|TBD|FIXME|XXX|N\/?A)\b|^(\?+|-+|—|\.+)$/i;
127
127
  const MIN_MEANINGFUL = 10;
128
- function unfilled(text: string): boolean {
128
+ export function unfilled(text: string): boolean {
129
129
  const t = text.trim();
130
130
  return t.length < MIN_MEANINGFUL || UNFILLED.test(t);
131
131
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.8.26",
3
+ "version": "0.8.28",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {
@@ -32,8 +32,11 @@
32
32
  "scripts/board-mirror.ts",
33
33
  "scripts/board-conformance.ts",
34
34
  "scripts/board-snapshot.ts",
35
+ "scripts/board-scope.ts",
36
+ "scripts/status-view.ts",
35
37
  "scripts/plan-deps.ts",
36
38
  "scripts/plan-issues.ts",
39
+ "scripts/consumer-triage.ts",
37
40
  "scripts/board-ready.ts",
38
41
  "scripts/board-id.ts",
39
42
  "scripts/ci-reading.ts",