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 +1 -1
- package/lib/board-mirror.ts +28 -9
- package/lib/cli-commands.ts +11 -3
- package/lib/scaffold/owned-files.ts +14 -4
- package/lib/scaffold/specs-placed-workflow.ts +252 -0
- package/lib/scaffold/steps.ts +14 -1
- package/lib/spec-placement.ts +37 -0
- package/package.json +2 -1
- package/scripts/board-conformance.ts +43 -8
- package/scripts/board-scope.ts +149 -0
- package/scripts/board-snapshot.ts +64 -3
package/gates/.gate-salt
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
c383a2a597db75009eb5771282d36d447270d59c07518a035e13962da1d45801
|
package/lib/board-mirror.ts
CHANGED
|
@@ -170,9 +170,17 @@ function unmeasuredSweep(reasons: string[]): SpecSweep {
|
|
|
170
170
|
return { reading: "UNMEASURED", specs: [], ids: [], collisions: [], unmeasuredReasons: reasons };
|
|
171
171
|
}
|
|
172
172
|
|
|
173
|
-
|
|
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
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
`
|
|
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
|
-
|
|
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
|
|
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[] = [];
|
package/lib/cli-commands.ts
CHANGED
|
@@ -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: "
|
|
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
|
|
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
|
|
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` —
|
|
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
|
|
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` —
|
|
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}
|
|
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
|
+
}
|
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
|
package/lib/spec-placement.ts
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
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
|
-
|
|
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")
|
|
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)
|
|
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 =
|
|
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
|