rungate 0.5.0 → 0.6.0
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/lib/agents-md-sections.ts +144 -0
- package/lib/branch-diff.ts +139 -0
- package/lib/bun-version.ts +268 -0
- package/lib/ci-checkout.ts +1 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +184 -88
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +90 -4
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +22 -0
- package/lib/fallow-availability.ts +129 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +71 -23
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/report-provenance.ts +156 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +311 -0
- package/lib/scaffold/ai-review-step.ts +180 -0
- package/lib/scaffold/owned-files.ts +42 -2
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +128 -73
- package/lib/scaffold/write-steps.ts +6 -4
- package/lib/scanner.ts +38 -12
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/suite-run-reading.ts +170 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +166 -10
- package/lib/tool-probe.ts +120 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/package.json +1 -1
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +17 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +4 -1
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- package/scripts/sync-spec-tests.ts +2 -1
package/lib/scaffold/steps.ts
CHANGED
|
@@ -28,9 +28,13 @@ import { organizeProjectReport } from "../organize";
|
|
|
28
28
|
import type { ProjectScan, ProjectType, SpecEntry, TestFile, RefFile, DocRoute, Category } from "../generators/types";
|
|
29
29
|
import { tier1Ere } from "../secret-patterns";
|
|
30
30
|
import { healthPathIn } from "../liveness-contradiction";
|
|
31
|
+
import { localCalendarDay } from "../local-calendar-day";
|
|
31
32
|
import { decideRuleWrite } from "../rule-provenance";
|
|
32
33
|
import { DEFAULT_PROFILE, isRuleIncluded, type ScaffoldProfile } from "./profiles";
|
|
33
34
|
import { referencedPaths } from "../agents-md-refs";
|
|
35
|
+
import { inferredTestCommand, testCommandDecision } from "../test-command";
|
|
36
|
+
import { declaredBunVersion, setupBunWith } from "../bun-version";
|
|
37
|
+
import { codeMapUnreferenced, unlistedSpecs } from "../spec-listing";
|
|
34
38
|
import {
|
|
35
39
|
readSuccessDoc,
|
|
36
40
|
readSuccessTemplate,
|
|
@@ -186,6 +190,15 @@ export function regenerateOwned(
|
|
|
186
190
|
);
|
|
187
191
|
return;
|
|
188
192
|
}
|
|
193
|
+
if (decision.action === "refuse") {
|
|
194
|
+
// Not the same thing as `preserve`, and the advice is the opposite:
|
|
195
|
+
// `preserve` means the file on disk is yours and the generator stood
|
|
196
|
+
// down, so deleting it accepts the generator. This means the generator
|
|
197
|
+
// cannot produce an output that keeps a promise the spec makes, and
|
|
198
|
+
// deleting the file would destroy exactly the content at issue.
|
|
199
|
+
actions.push(`${SCAFFOLD_REFUSE}: ${label} not written — ${decision.reason}`);
|
|
200
|
+
return;
|
|
201
|
+
}
|
|
189
202
|
if (decision.action === "unchanged") {
|
|
190
203
|
actions.push(`UNCHANGED: ${label} (${decision.reason})`);
|
|
191
204
|
return;
|
|
@@ -241,40 +254,6 @@ function loadHarnessConfig(root: string): any {
|
|
|
241
254
|
|
|
242
255
|
// ── AGENTS.md generation and updates ───────────────────────────
|
|
243
256
|
|
|
244
|
-
export function updateSpecsTable(agentsMdPath: string, actions: string[]): void {
|
|
245
|
-
if (!existsSync(agentsMdPath)) return;
|
|
246
|
-
const specsDir = join(dirname(agentsMdPath), "specs");
|
|
247
|
-
if (!existsSync(specsDir)) return;
|
|
248
|
-
|
|
249
|
-
const specFiles = readdirSync(specsDir).filter(f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md");
|
|
250
|
-
if (specFiles.length === 0) return;
|
|
251
|
-
|
|
252
|
-
const specRows: string[] = [];
|
|
253
|
-
for (const f of specFiles) {
|
|
254
|
-
const content = readFileSync(join(specsDir, f), "utf-8");
|
|
255
|
-
const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
|
|
256
|
-
let testable = "false";
|
|
257
|
-
let governs = f.replace(/\.md$/, "");
|
|
258
|
-
if (fmMatch) {
|
|
259
|
-
const tMatch = fmMatch[1].match(/testable:\s*(true|false)/);
|
|
260
|
-
if (tMatch) testable = tMatch[1];
|
|
261
|
-
const gMatch = fmMatch[1].match(/governs:\s*(.+)/);
|
|
262
|
-
if (gMatch) governs = gMatch[1].trim();
|
|
263
|
-
}
|
|
264
|
-
specRows.push(`| ${f} | ${governs} | ${testable === "true" ? "yes" : "no"} |`);
|
|
265
|
-
}
|
|
266
|
-
|
|
267
|
-
const existing = readFileSync(agentsMdPath, "utf-8");
|
|
268
|
-
const tablePattern = /(\|[^\n]*Spec[^\n]*\|\n\|[-| ]+\|\n)((?:\|[^\n]+\|\n)*)/;
|
|
269
|
-
const match = existing.match(tablePattern);
|
|
270
|
-
if (match) {
|
|
271
|
-
const newTable = match[1] + specRows.join("\n") + "\n";
|
|
272
|
-
const updated = existing.replace(tablePattern, newTable);
|
|
273
|
-
writeFileSync(agentsMdPath, updated);
|
|
274
|
-
actions.push("UPDATED: AGENTS.md specs table from frontmatter");
|
|
275
|
-
}
|
|
276
|
-
}
|
|
277
|
-
|
|
278
257
|
export function injectEnvironmentSection(root: string, actions: string[]): void {
|
|
279
258
|
const agentsMdPath = join(root, "AGENTS.md");
|
|
280
259
|
if (!existsSync(agentsMdPath)) return;
|
|
@@ -475,14 +454,10 @@ export function generateAgentsMdContent(
|
|
|
475
454
|
}
|
|
476
455
|
}
|
|
477
456
|
|
|
478
|
-
// Detect test command
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
483
|
-
if (pkg.scripts?.test) testCmd = pkg.scripts.test;
|
|
484
|
-
} catch {}
|
|
485
|
-
}
|
|
457
|
+
// Detect test command — through the one binding (#488). This copy read
|
|
458
|
+
// package.json and nothing else, so AGENTS.md's Commands row ignored a
|
|
459
|
+
// `dev.testCmd` the agent briefs honoured and CI ignored both.
|
|
460
|
+
const testCmd = testCommandDecision(projectPath).command;
|
|
486
461
|
|
|
487
462
|
// Scan reference files
|
|
488
463
|
const refDir = join(projectPath, "reference");
|
|
@@ -661,8 +636,14 @@ export function generateAgentsMdContent(
|
|
|
661
636
|
* Re-running the generator is safe and cheap: `generateAgentsMdContent` writes
|
|
662
637
|
* only the rules, and returns AGENTS.md content for its caller to write. The
|
|
663
638
|
* return value is discarded here on purpose — AGENTS.md has already been
|
|
664
|
-
* through `
|
|
665
|
-
*
|
|
639
|
+
* through `injectEnvironmentSection` by this point, and rewriting it would
|
|
640
|
+
* undo that.
|
|
641
|
+
*
|
|
642
|
+
* It used to say `updateSpecsTable` as well. That function ran immediately
|
|
643
|
+
* after the generator had rewritten AGENTS.md, edited an EXISTING table
|
|
644
|
+
* matched on a header row containing `Spec`, and the generator emits no such
|
|
645
|
+
* table — so the match never succeeded, the `if` had no `else`, and its
|
|
646
|
+
* action string never once appeared in a report. It is deleted (#382).
|
|
666
647
|
*/
|
|
667
648
|
export function refreshScopedRulesStep(
|
|
668
649
|
root: string,
|
|
@@ -724,19 +705,23 @@ export function refreshAgentsMd(root: string, type: ProjectType, actions: string
|
|
|
724
705
|
} catch (e: unknown) { console.warn('Staleness check failed for', ref, (e as Error).message); }
|
|
725
706
|
}
|
|
726
707
|
|
|
727
|
-
// Check specs table
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
708
|
+
// Check specs table.
|
|
709
|
+
//
|
|
710
|
+
// Across AGENTS.md AND `.claude/rules/`, because D-15 capped AGENTS.md at
|
|
711
|
+
// 100 lines and moved both tables there (#382). Asked of `lib/spec-listing.ts`
|
|
712
|
+
// rather than inline: this site had its own idea of what counts as a spec —
|
|
713
|
+
// every `.md` in `specs/`, including `SPEC-TEMPLATE.md` — and the routing
|
|
714
|
+
// generator had another, so the one entry that could never be listed
|
|
715
|
+
// anywhere was reported on every run.
|
|
716
|
+
const unlisted = unlistedSpecs(root);
|
|
717
|
+
if (unlisted.length > 0) {
|
|
718
|
+
issues.push(`UNLISTED specs: ${unlisted.join(", ")} (in specs/ but not in AGENTS.md or .claude/rules/)`);
|
|
735
719
|
}
|
|
736
720
|
|
|
737
|
-
// Check CODE-MAP.md reference
|
|
738
|
-
|
|
739
|
-
|
|
721
|
+
// Check CODE-MAP.md reference — same surfaces, same reason. It is named in
|
|
722
|
+
// the first row of `.claude/rules/docs-routing.md`.
|
|
723
|
+
if (codeMapUnreferenced(root)) {
|
|
724
|
+
issues.push("CODE-MAP.md exists but not referenced in AGENTS.md or .claude/rules/");
|
|
740
725
|
}
|
|
741
726
|
|
|
742
727
|
if (issues.length > 0 || staleFiles.length > 0) {
|
|
@@ -910,7 +895,7 @@ export function generateAgentBriefsStep(root: string, actions: string[]): void {
|
|
|
910
895
|
identity: projectIdentity,
|
|
911
896
|
techStack: [],
|
|
912
897
|
repoUrl: "",
|
|
913
|
-
testCmd:
|
|
898
|
+
testCmd: testCommandDecision(root).command,
|
|
914
899
|
keyFiles: [],
|
|
915
900
|
specs: [],
|
|
916
901
|
testFiles: [],
|
|
@@ -980,13 +965,12 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
|
|
|
980
965
|
}
|
|
981
966
|
}
|
|
982
967
|
|
|
983
|
-
//
|
|
968
|
+
// `inferredTestCommand`, not the full decision (#488). This value is what
|
|
969
|
+
// gets WRITTEN into `dev.testCmd`, so reading `dev.testCmd` to choose it
|
|
970
|
+
// is circular — and this step runs against trees whose config is
|
|
971
|
+
// malformed, which is what it exists to repair.
|
|
972
|
+
const testCmd = inferredTestCommand(root).command;
|
|
984
973
|
const pkgPath = join(root, "package.json");
|
|
985
|
-
let testCmd = "bun test";
|
|
986
|
-
if (existsSync(pkgPath)) {
|
|
987
|
-
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
988
|
-
if (pkg.scripts?.test) testCmd = pkg.scripts.test;
|
|
989
|
-
}
|
|
990
974
|
// #87 — this defaulted to `bunx tsc --noEmit` for every project, including
|
|
991
975
|
// one with no tsconfig, and `gates/gate-executor.ts` RUNS what lands here.
|
|
992
976
|
// Without a tsconfig that command prints 147 lines of help and exits 1, so
|
|
@@ -1158,7 +1142,14 @@ export function generateOrAuditProjectHarness(root: string, actions: string[], o
|
|
|
1158
1142
|
envVars: envVars || [],
|
|
1159
1143
|
ci: {
|
|
1160
1144
|
runner: "ubuntu-latest",
|
|
1161
|
-
|
|
1145
|
+
// Detected, never defaulted (#346, #622). `"latest"` here wrote an
|
|
1146
|
+
// UNPINNED runtime into every greenfield project's CI and called it a
|
|
1147
|
+
// configuration: the job installs whatever shipped this morning, so
|
|
1148
|
+
// re-running a red build is also a Bun upgrade. The bun that ran the
|
|
1149
|
+
// scaffold is a measurement of what this project has been built with,
|
|
1150
|
+
// which is the honest thing to write down, and the operator can change
|
|
1151
|
+
// it in one place afterwards.
|
|
1152
|
+
bunVersion: Bun.version,
|
|
1162
1153
|
branches: ["main"],
|
|
1163
1154
|
},
|
|
1164
1155
|
contextDocs: {},
|
|
@@ -1779,7 +1770,20 @@ export function missingGitignorePatterns(existing: string): string[] {
|
|
|
1779
1770
|
.map(l => l.trim())
|
|
1780
1771
|
.filter(l => l !== "" && !l.startsWith("#")),
|
|
1781
1772
|
);
|
|
1782
|
-
|
|
1773
|
+
// #586: `X/` is satisfied by an existing `X`, and ONLY in that direction.
|
|
1774
|
+
// This repo's `.gitignore` opens with `node_modules` and the required
|
|
1775
|
+
// pattern is `node_modules/`, so exact matching reported it absent and
|
|
1776
|
+
// every scaffold run re-added a line that changes nothing.
|
|
1777
|
+
//
|
|
1778
|
+
// The direction is the whole safety argument, and it is the opposite of
|
|
1779
|
+
// the trap the docstring above names. A bare `node_modules` matches files
|
|
1780
|
+
// AND directories, so it is STRICTLY BROADER than `node_modules/` — the
|
|
1781
|
+
// requirement is already met. `service-account` present against a required
|
|
1782
|
+
// `service-account*` is the reverse: the required pattern is broader, the
|
|
1783
|
+
// requirement is NOT met, and that case must keep failing.
|
|
1784
|
+
const satisfied = (p: string): boolean =>
|
|
1785
|
+
present.has(p) || (p.endsWith("/") && present.has(p.slice(0, -1)));
|
|
1786
|
+
return requiredGitignorePatterns().filter(p => !satisfied(p));
|
|
1783
1787
|
}
|
|
1784
1788
|
|
|
1785
1789
|
export function createGitignore(root: string, actions: string[]): void {
|
|
@@ -1809,7 +1813,7 @@ export function generateProjectState(root: string, actions: string[]): void {
|
|
|
1809
1813
|
return;
|
|
1810
1814
|
}
|
|
1811
1815
|
|
|
1812
|
-
const today =
|
|
1816
|
+
const today = localCalendarDay();
|
|
1813
1817
|
|
|
1814
1818
|
interface SC { id: string; what: string; done: boolean; }
|
|
1815
1819
|
const scs: SC[] = [];
|
|
@@ -1934,7 +1938,7 @@ export function seedSuccessDoc(root: string, actions: string[]): void {
|
|
|
1934
1938
|
return;
|
|
1935
1939
|
}
|
|
1936
1940
|
|
|
1937
|
-
const today =
|
|
1941
|
+
const today = localCalendarDay();
|
|
1938
1942
|
const owner = process.env.USER || "TODO-OWNER";
|
|
1939
1943
|
// The SHARED substitution. Writing the template raw here while
|
|
1940
1944
|
// `create-success` substituted meant one seed with two possible byte
|
|
@@ -2356,7 +2360,17 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
|
|
|
2356
2360
|
}
|
|
2357
2361
|
|
|
2358
2362
|
const harness = loadHarnessConfig(root);
|
|
2359
|
-
|
|
2363
|
+
// #622. This was `harness?.ci?.bunVersion || "latest"`, emitted at the two
|
|
2364
|
+
// sites below, while the two hand-owned workflow files this generator never
|
|
2365
|
+
// touches named versions of their own — four positions, three spellings,
|
|
2366
|
+
// and nothing comparing any of them. (Neither of those filenames is spelled
|
|
2367
|
+
// here: test/release-guard.test.ts asserts this module names no workflow it
|
|
2368
|
+
// does not write, and prose is indistinguishable from a write to it.) The
|
|
2369
|
+
// decision and the YAML it becomes are now `lib/bun-version.ts`'s, for the
|
|
2370
|
+
// same reason #87 took the typecheck step and #488 took the test step: two
|
|
2371
|
+
// sites that agree today are one decider too many, and only a mutation of a
|
|
2372
|
+
// SHARED binding can show the agreement is load-bearing.
|
|
2373
|
+
const bunStep = setupBunWith(declaredBunVersion(root), " ");
|
|
2360
2374
|
const runner = harness?.ci?.runner || "ubuntu-latest";
|
|
2361
2375
|
const branches = harness?.ci?.branches || ["main"];
|
|
2362
2376
|
// Branch patterns are globs: a bare `*` is a YAML alias indicator and `*-dev`
|
|
@@ -2422,6 +2436,14 @@ export function createCiWorkflows(root: string, actions: string[], opts: { force
|
|
|
2422
2436
|
// `dev.typeCheck` read (#87). This site used to check for
|
|
2423
2437
|
// `scripts/typecheck.ts` on disk, a branch `files:` makes unreachable for
|
|
2424
2438
|
// every consumer, and never looked at a project's own `typecheck` script.
|
|
2439
|
+
// #488. This was `- run: bun test`, hardcoded, while `harness` was in
|
|
2440
|
+
// scope and three of its siblings read `harness?.ci?.*` four lines above.
|
|
2441
|
+
// Same binding AGENTS.md's Commands row and the agent briefs read, for the
|
|
2442
|
+
// same reason the typecheck step below it got one in #87: two sites that
|
|
2443
|
+
// agree today are one decider too many, and only a mutation of a shared
|
|
2444
|
+
// binding can show the agreement is load-bearing.
|
|
2445
|
+
const test = testCommandDecision(root);
|
|
2446
|
+
|
|
2425
2447
|
const typecheck = typecheckDecision(root);
|
|
2426
2448
|
const typecheckStep = typecheck.command
|
|
2427
2449
|
? `\n - run: ${typecheck.command}`
|
|
@@ -2446,9 +2468,9 @@ jobs:
|
|
|
2446
2468
|
${baseRefStep}
|
|
2447
2469
|
- uses: oven-sh/setup-bun@v2
|
|
2448
2470
|
with:
|
|
2449
|
-
|
|
2471
|
+
${bunStep}
|
|
2450
2472
|
- run: bun install
|
|
2451
|
-
- run:
|
|
2473
|
+
- run: ${test.command}${typecheckStep}
|
|
2452
2474
|
`;
|
|
2453
2475
|
|
|
2454
2476
|
const gatesYml = `# Managed by rungate — do not edit. Customize the ci section of .claude/rungate/config.json.
|
|
@@ -2469,7 +2491,7 @@ jobs:
|
|
|
2469
2491
|
- uses: actions/checkout@v4
|
|
2470
2492
|
- uses: oven-sh/setup-bun@v2
|
|
2471
2493
|
with:
|
|
2472
|
-
|
|
2494
|
+
${bunStep}
|
|
2473
2495
|
- run: bun install
|
|
2474
2496
|
- name: Conformity + spec drift
|
|
2475
2497
|
run: bun test test/scaffold-conformity.test.ts
|
|
@@ -2709,17 +2731,50 @@ fi
|
|
|
2709
2731
|
# linked worktree. An unmeasured guard is indistinguishable from an absent
|
|
2710
2732
|
# one, so it is absent. git hooks run from the toplevel, and both calls share
|
|
2711
2733
|
# a cwd, so there was never a case that needed it.
|
|
2734
|
+
#
|
|
2735
|
+
# The primary arm had three fail-opens in two lines (#599), and the shape is
|
|
2736
|
+
# this file's recurring one: a check that passed because of what it never
|
|
2737
|
+
# looked at. The path was the CONSUMER layout, so in the harness's own
|
|
2738
|
+
# checkout — which has scripts/update-project-state.ts and no
|
|
2739
|
+
# node_modules/rungate at all — bun exited non-zero on a file that is not
|
|
2740
|
+
# there. 2>/dev/null threw the ENOENT away, || true threw the status away, and
|
|
2741
|
+
# the git add below then staged whatever happened to be on disk. A commit that
|
|
2742
|
+
# regenerated nothing was byte-indistinguishable from one that regenerated
|
|
2743
|
+
# everything, and the only reason anyone noticed is that the stamp is UTC, so
|
|
2744
|
+
# the stale copy differs from the fresh one for four hours an evening.
|
|
2745
|
+
#
|
|
2746
|
+
# Every message is on STDERR: stdout is what a caller captures as the
|
|
2747
|
+
# command's answer, and a decline, a reading and an updater's progress are all
|
|
2748
|
+
# diagnosis rather than output.
|
|
2712
2749
|
if [ -f "project-state.json" ]; then
|
|
2713
2750
|
gitdir=$(git rev-parse --git-dir)
|
|
2714
2751
|
commondir=$(git rev-parse --git-common-dir)
|
|
2715
2752
|
if [ -n "$gitdir" ] && [ "$gitdir" = "$commondir" ]; then
|
|
2716
|
-
|
|
2717
|
-
|
|
2753
|
+
# The order is deliberate. A checkout carrying its own scripts/ copy IS
|
|
2754
|
+
# the harness, and the harness must not regenerate its state with a stale
|
|
2755
|
+
# vendored duplicate of its own updater.
|
|
2756
|
+
updater=""
|
|
2757
|
+
if [ -f "scripts/update-project-state.ts" ]; then
|
|
2758
|
+
updater="scripts/update-project-state.ts"
|
|
2759
|
+
elif [ -f "node_modules/rungate/scripts/update-project-state.ts" ]; then
|
|
2760
|
+
updater="node_modules/rungate/scripts/update-project-state.ts"
|
|
2761
|
+
fi
|
|
2762
|
+
if [ -z "$updater" ]; then
|
|
2763
|
+
echo "project-state: UNMEASURED — project-state.json is here, but no update-project-state.ts was found at scripts/update-project-state.ts or node_modules/rungate/scripts/update-project-state.ts. Nothing was regenerated and nothing was staged." >&2
|
|
2764
|
+
elif bun "$updater" --skip-tests >&2; then
|
|
2765
|
+
# Staged only after the updater SUCCEEDED. Staging regardless is the
|
|
2766
|
+
# fail-open the readings above exist to replace: it puts yesterday's
|
|
2767
|
+
# PROJECT-STATE.md in today's commit, and the commit then looks exactly
|
|
2768
|
+
# like one that updated it.
|
|
2769
|
+
git add PROJECT-STATE.md project-state.json 2>/dev/null || true
|
|
2770
|
+
else
|
|
2771
|
+
echo "project-state: UNMEASURED — $updater exited non-zero, so PROJECT-STATE.md and project-state.json were NOT staged. Run it by hand to see why." >&2
|
|
2772
|
+
fi
|
|
2718
2773
|
else
|
|
2719
2774
|
# Announced, not silent. A developer who expected the state files to move
|
|
2720
2775
|
# would otherwise be left guessing, and SKIP that says nothing is
|
|
2721
2776
|
# indistinguishable from the update having happened.
|
|
2722
|
-
echo "project-state: SKIPPED — linked worktree. project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned (#296); update them from the primary checkout."
|
|
2777
|
+
echo "project-state: SKIPPED — linked worktree. project-state.json, PROJECT-STATE.md and SUCCESS.md are DA-owned (#296); update them from the primary checkout." >&2
|
|
2723
2778
|
fi
|
|
2724
2779
|
fi
|
|
2725
2780
|
|
|
@@ -24,7 +24,6 @@ import {
|
|
|
24
24
|
generateAgentsMdContent,
|
|
25
25
|
refreshScopedRulesStep,
|
|
26
26
|
refreshAgentsMd,
|
|
27
|
-
updateSpecsTable,
|
|
28
27
|
injectEnvironmentSection,
|
|
29
28
|
generateConformityTest,
|
|
30
29
|
generateAgentBriefsStep,
|
|
@@ -111,10 +110,13 @@ export function runScaffoldWriteSteps(
|
|
|
111
110
|
|
|
112
111
|
// Phase 0.5: Generate AGENTS.md
|
|
113
112
|
const agentsMd = generateAgentsMdContent(projectPath, projectType, actions, profile);
|
|
114
|
-
writeFileSync(
|
|
115
|
-
|
|
113
|
+
// Through the owned-file writer, not a bare `writeFileSync` (#568). Two
|
|
114
|
+
// things were missing here and both were invisible: the Hard Constraints
|
|
115
|
+
// section the spec guarantees survives regeneration, and the symlink
|
|
116
|
+
// refusal every other owned file has had since #507 — a raw write FOLLOWS
|
|
117
|
+
// a link, so an `AGENTS.md ->` anywhere was a write outside the project.
|
|
118
|
+
regenerateOwned(join(projectPath, "AGENTS.md"), agentsMd, "AGENTS.md", actions, "section-preserving");
|
|
116
119
|
refreshAgentsMd(projectPath, projectType, actions);
|
|
117
|
-
updateSpecsTable(join(projectPath, "AGENTS.md"), actions);
|
|
118
120
|
|
|
119
121
|
// Phase 0.6: Create copilot instructions
|
|
120
122
|
const copilotInstructions = `# Copilot Instructions\n\nRead [AGENTS.md](../AGENTS.md) for project context, key files, specs, and workflow.\n\nAll project knowledge lives in AGENTS.md. Start there.\n`;
|
package/lib/scanner.ts
CHANGED
|
@@ -16,6 +16,8 @@ import { resolveConfig } from "./config-loader";
|
|
|
16
16
|
// exists precisely so this module and the generators can share one answer
|
|
17
17
|
// instead of drifting apart (#380).
|
|
18
18
|
import { isHarnessItself } from "./harness-identity";
|
|
19
|
+
import { isSpecFile } from "./spec-listing";
|
|
20
|
+
import { testCommandDecision } from "./test-command";
|
|
19
21
|
import type {
|
|
20
22
|
ProjectScan,
|
|
21
23
|
ProjectType,
|
|
@@ -109,7 +111,11 @@ function scanSpecs(root: string): SpecEntry[] {
|
|
|
109
111
|
if (!existsSync(specsDir)) return [];
|
|
110
112
|
|
|
111
113
|
const specs: SpecEntry[] = [];
|
|
112
|
-
|
|
114
|
+
// `isSpecFile`, not an inline name comparison. The audit in
|
|
115
|
+
// `lib/scaffold/steps.ts` answered the same question with its own filter
|
|
116
|
+
// and reached the opposite verdict for `SPEC-TEMPLATE.md`, so the one file
|
|
117
|
+
// this table deliberately omits was reported as missing from it (#382).
|
|
118
|
+
const specFiles = readdirSync(specsDir).filter(isSpecFile);
|
|
113
119
|
|
|
114
120
|
for (const f of specFiles) {
|
|
115
121
|
const content = readFileSync(join(specsDir, f), "utf-8");
|
|
@@ -126,7 +132,13 @@ function scanSpecs(root: string): SpecEntry[] {
|
|
|
126
132
|
if (tMatch) testable = tMatch[1].trim();
|
|
127
133
|
}
|
|
128
134
|
|
|
129
|
-
|
|
135
|
+
// #579. A row in this table promises a reader that the document on the
|
|
136
|
+
// other end governs something. When the document says it states no
|
|
137
|
+
// criteria, the row says so too — see `lib/spec-requirements.ts` for why
|
|
138
|
+
// the declaration lives in frontmatter rather than in an allowlist.
|
|
139
|
+
const criteriaNone = /^criteria:\s*none\s*$/m.test(fmMatch?.[1] ?? "");
|
|
140
|
+
|
|
141
|
+
specs.push({ file: f, governs, testable, criteriaNone });
|
|
130
142
|
}
|
|
131
143
|
|
|
132
144
|
// Also scan specs subdirectories
|
|
@@ -151,7 +163,24 @@ function scanSpecs(root: string): SpecEntry[] {
|
|
|
151
163
|
}
|
|
152
164
|
}
|
|
153
165
|
}
|
|
154
|
-
|
|
166
|
+
// `"yes"` was a literal here, and every reader of this field compares
|
|
167
|
+
// against the string `"true"` — so the group row has always rendered
|
|
168
|
+
// a word that means false to the code and true to a reader (#579).
|
|
169
|
+
// Derived from the members instead: testable if any of them is.
|
|
170
|
+
const anyTestable = subFiles.some(sf => {
|
|
171
|
+
try {
|
|
172
|
+
return /^testable:\s*true\s*$/m.test(
|
|
173
|
+
readFileSync(join(subPath, sf), "utf-8").match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "",
|
|
174
|
+
);
|
|
175
|
+
} catch {
|
|
176
|
+
return false;
|
|
177
|
+
}
|
|
178
|
+
});
|
|
179
|
+
specs.push({
|
|
180
|
+
file: `${sub}/ (${subFiles.length} specs)`,
|
|
181
|
+
governs: groupGoverns,
|
|
182
|
+
testable: String(anyTestable),
|
|
183
|
+
});
|
|
155
184
|
}
|
|
156
185
|
}
|
|
157
186
|
} catch {}
|
|
@@ -608,16 +637,13 @@ function scanAgentMeta(harness: Record<string, any> | null): Record<string, { de
|
|
|
608
637
|
|
|
609
638
|
// ── Test command detection ─────────────────────────────────────
|
|
610
639
|
|
|
640
|
+
/**
|
|
641
|
+
* Through the one binding (#488). This knew only about package.json, so a
|
|
642
|
+
* consumer who set `dev.testCmd` got it honoured by the agent briefs and
|
|
643
|
+
* ignored by every scan-driven surface — and the CI generator read neither.
|
|
644
|
+
*/
|
|
611
645
|
function detectTestCmd(root: string): string {
|
|
612
|
-
|
|
613
|
-
if (!existsSync(pkgPath)) return "bun test";
|
|
614
|
-
|
|
615
|
-
try {
|
|
616
|
-
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
617
|
-
if (pkg.scripts?.test) return pkg.scripts.test;
|
|
618
|
-
} catch {}
|
|
619
|
-
|
|
620
|
-
return "bun test";
|
|
646
|
+
return testCommandDecision(root).command;
|
|
621
647
|
}
|
|
622
648
|
|
|
623
649
|
// ── Categories ─────────────────────────────────────────────────
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where a spec may be listed, and what counts as a spec (#382, #552).
|
|
3
|
+
*
|
|
4
|
+
* `refreshAgentsMd` warns when a file in `specs/` is not named in
|
|
5
|
+
* `AGENTS.md`. D-15 capped AGENTS.md at 100 lines and moved the specs table
|
|
6
|
+
* and the doc-routing table into `.claude/rules/`, and neither check
|
|
7
|
+
* followed. So both have warned on every `--fix` run since: 23 spec
|
|
8
|
+
* filenames on this repo, plus `CODE-MAP.md exists but not referenced`,
|
|
9
|
+
* every single time.
|
|
10
|
+
*
|
|
11
|
+
* **Both are unfixable from the document's side**, which is what makes them
|
|
12
|
+
* worse than noise. Satisfying `UNLISTED specs` means pasting 23 filenames
|
|
13
|
+
* back into AGENTS.md, which breaks the line cap D-15 moved them out to
|
|
14
|
+
* respect — the detector asking for the thing the architecture forbids. A
|
|
15
|
+
* consumer who adds the table by hand gets it deleted by the next
|
|
16
|
+
* `REGENERATED: AGENTS.md`, so the warning cannot be cleared at all.
|
|
17
|
+
*
|
|
18
|
+
* A standing false positive trains readers past the whole class. #380
|
|
19
|
+
* measured the neighbouring check at a true-positive rate of **zero** for
|
|
20
|
+
* the same underlying reason, and nobody had noticed in months because the
|
|
21
|
+
* output was always noisy.
|
|
22
|
+
*
|
|
23
|
+
* ## Is `SPEC-TEMPLATE.md` a spec?
|
|
24
|
+
*
|
|
25
|
+
* **No, and this module is where that is decided.** It is the file
|
|
26
|
+
* `create-spec` copies to start a new spec; it governs nothing and a reader
|
|
27
|
+
* sent to it by a routing table learns nothing about the project. The
|
|
28
|
+
* scanner has always excluded it from `specs-routing.md`, and the audit has
|
|
29
|
+
* always included it — which is how it ended up in the warning list as the
|
|
30
|
+
* one entry that was never going to be listed anywhere.
|
|
31
|
+
*
|
|
32
|
+
* It is a decision rather than a lookup, so it lives in one named constant
|
|
33
|
+
* that both sides import, rather than being absorbed by whichever file a
|
|
34
|
+
* check happens to read.
|
|
35
|
+
*
|
|
36
|
+
* ## Why the surfaces are a directory and not a filename
|
|
37
|
+
*
|
|
38
|
+
* `listingSurfaces` searches AGENTS.md and every `.claude/rules/*.md`, not
|
|
39
|
+
* `.claude/rules/specs-routing.md` by name. The generator chooses that
|
|
40
|
+
* filename and a check that hard-codes it is a second decider for the same
|
|
41
|
+
* question — the shape that put this defect here. A rule file renamed by the
|
|
42
|
+
* generator stays covered; a spec listed in no agent-facing document at all
|
|
43
|
+
* is still reported, which is the half that has to keep working.
|
|
44
|
+
*/
|
|
45
|
+
import { existsSync, readFileSync, readdirSync } from "fs";
|
|
46
|
+
import { join } from "path";
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Files that live in `specs/` and are not specs. See the module docstring —
|
|
50
|
+
* this is a judgement, and it is deliberately a list of exact names rather
|
|
51
|
+
* than a pattern, so adding to it is a visible decision.
|
|
52
|
+
*/
|
|
53
|
+
export const NON_SPEC_FILES: readonly string[] = ["SPEC-TEMPLATE.md"];
|
|
54
|
+
|
|
55
|
+
export function isSpecFile(name: string): boolean {
|
|
56
|
+
return name.endsWith(".md") && !NON_SPEC_FILES.includes(name);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Top-level spec files in `root/specs`, or `[]` when there is no `specs/`. */
|
|
60
|
+
export function specFilesIn(root: string): string[] {
|
|
61
|
+
const dir = join(root, "specs");
|
|
62
|
+
if (!existsSync(dir)) return [];
|
|
63
|
+
try {
|
|
64
|
+
return readdirSync(dir).filter(isSpecFile);
|
|
65
|
+
} catch {
|
|
66
|
+
return [];
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export interface Surface {
|
|
71
|
+
/** Project-relative, so a report can name it. */
|
|
72
|
+
path: string;
|
|
73
|
+
content: string;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Every agent-facing document in which a spec or a doc may be listed.
|
|
78
|
+
*
|
|
79
|
+
* AGENTS.md first because a consumer may still list specs there; then
|
|
80
|
+
* `.claude/rules/*.md`, which is where this project's generator puts the
|
|
81
|
+
* tables and where D-15 moved them.
|
|
82
|
+
*/
|
|
83
|
+
export function listingSurfaces(root: string): Surface[] {
|
|
84
|
+
const out: Surface[] = [];
|
|
85
|
+
const agents = join(root, "AGENTS.md");
|
|
86
|
+
if (existsSync(agents)) {
|
|
87
|
+
try { out.push({ path: "AGENTS.md", content: readFileSync(agents, "utf-8") }); } catch { /* unreadable */ }
|
|
88
|
+
}
|
|
89
|
+
const rulesDir = join(root, ".claude", "rules");
|
|
90
|
+
if (!existsSync(rulesDir)) return out;
|
|
91
|
+
let names: string[];
|
|
92
|
+
try { names = readdirSync(rulesDir).filter(f => f.endsWith(".md")).sort(); } catch { return out; }
|
|
93
|
+
for (const n of names) {
|
|
94
|
+
try {
|
|
95
|
+
out.push({ path: `.claude/rules/${n}`, content: readFileSync(join(rulesDir, n), "utf-8") });
|
|
96
|
+
} catch { /* unreadable */ }
|
|
97
|
+
}
|
|
98
|
+
return out;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* A line that puts a reader somewhere: a table row, or a list item.
|
|
103
|
+
*
|
|
104
|
+
* **A mention is not a listing**, and the difference is measurable here.
|
|
105
|
+
* `.claude/rules/checks-must-be-able-to-fail.md:407` discusses
|
|
106
|
+
* `specs/SPEC-TEMPLATE.md` in a paragraph about #484. A whole-document
|
|
107
|
+
* `includes` counts that as the template being listed — so the mutation
|
|
108
|
+
* that makes `SPEC-TEMPLATE.md` a spec again measured 1 red where 2 were
|
|
109
|
+
* predicted, and the one that did not fire was the live-tree case. Any spec
|
|
110
|
+
* any rule file happens to name in prose would have been waved through the
|
|
111
|
+
* same way.
|
|
112
|
+
*
|
|
113
|
+
* That is `.claude/rules/checks-must-be-able-to-fail.md`'s own *"search the
|
|
114
|
+
* slice, not the document"*, met in a function whose job is to decide
|
|
115
|
+
* whether a document points somewhere. The boundary is asserted in both
|
|
116
|
+
* directions rather than left to this comment, because narrowing a detector
|
|
117
|
+
* is the change most likely to buy green with blindness.
|
|
118
|
+
*
|
|
119
|
+
* Deliberately permissive about WHICH list: the generator writes table rows,
|
|
120
|
+
* a consumer may well write bullets, and the direction this is allowed to be
|
|
121
|
+
* wrong in is toward reporting a spec that is in fact listed — which costs a
|
|
122
|
+
* line in a table — rather than toward silence.
|
|
123
|
+
*/
|
|
124
|
+
const LISTING_LINE = /^\s*(\||[-*+]\s|\d+\.\s)/;
|
|
125
|
+
|
|
126
|
+
export function listsFile(content: string, name: string): boolean {
|
|
127
|
+
return content.split("\n").some(l => l.includes(name) && LISTING_LINE.test(l));
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** Spec files listed by no surface. Empty when every spec is listed somewhere. */
|
|
131
|
+
export function unlistedSpecs(root: string): string[] {
|
|
132
|
+
const specs = specFilesIn(root);
|
|
133
|
+
if (specs.length === 0) return [];
|
|
134
|
+
const surfaces = listingSurfaces(root);
|
|
135
|
+
return specs.filter(f => !surfaces.some(s => listsFile(s.content, f)));
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* `CODE-MAP.md` exists but no surface points at it.
|
|
140
|
+
*
|
|
141
|
+
* Matched on `CODE-MAP` rather than on the filename, because the routing
|
|
142
|
+
* table writes it in backticks and the key-files table writes it bare, and
|
|
143
|
+
* the question is whether a reader is sent there at all.
|
|
144
|
+
*/
|
|
145
|
+
export function codeMapUnreferenced(root: string): boolean {
|
|
146
|
+
if (!existsSync(join(root, "CODE-MAP.md"))) return false;
|
|
147
|
+
return !listingSurfaces(root).some(s => listsFile(s.content, "CODE-MAP"));
|
|
148
|
+
}
|