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.
- package/bin/rungate.ts +5 -1
- package/gates/.gate-salt +1 -1
- package/lib/ai-review-threads.ts +152 -9
- package/lib/blocked-by-write.ts +95 -0
- package/lib/board-mirror.ts +28 -9
- package/lib/cli-commands.ts +40 -4
- package/lib/config-trackable.ts +91 -6
- package/lib/consumer-triage.ts +214 -0
- package/lib/issue-filing-gate.ts +84 -23
- package/lib/live-issues.ts +5 -0
- package/lib/scaffold/adr-accepted-workflow.ts +5 -6
- package/lib/scaffold/board-project-step.ts +49 -0
- package/lib/scaffold/human-steps.ts +39 -3
- package/lib/scaffold/owned-files.ts +14 -4
- package/lib/scaffold/spec-scope.ts +215 -0
- package/lib/scaffold/specs-placed-workflow.ts +249 -0
- package/lib/scaffold/steps.ts +14 -1
- package/lib/scaffold/write-steps.ts +9 -1
- package/lib/spec-placement.ts +89 -0
- package/lib/success-doc.ts +1 -1
- package/package.json +4 -1
- package/scripts/ai-review-threads.ts +42 -8
- package/scripts/board-conformance.ts +142 -8
- package/scripts/board-scope.ts +149 -0
- package/scripts/board-snapshot.ts +121 -5
- package/scripts/consumer-triage.ts +235 -0
- package/scripts/plan-deps.ts +58 -8
- package/scripts/plan-issues.ts +9 -3
- package/scripts/status-view.ts +955 -0
- package/scripts/sync-sc-status.ts +64 -4
|
@@ -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
|
+
}
|
package/lib/scaffold/steps.ts
CHANGED
|
@@ -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
|
}
|
package/lib/spec-placement.ts
CHANGED
|
@@ -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
|
+
}
|
package/lib/success-doc.ts
CHANGED
|
@@ -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.
|
|
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",
|