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.
Files changed (55) hide show
  1. package/lib/agents-md-sections.ts +144 -0
  2. package/lib/branch-diff.ts +139 -0
  3. package/lib/bun-version.ts +268 -0
  4. package/lib/ci-checkout.ts +1 -1
  5. package/lib/compliance.ts +13 -11
  6. package/lib/config-loader.ts +12 -0
  7. package/lib/conformity.ts +184 -88
  8. package/lib/context-docs.ts +143 -28
  9. package/lib/create-brief.ts +2 -1
  10. package/lib/create-sc.ts +90 -4
  11. package/lib/doc-scan-targets.ts +9 -0
  12. package/lib/evidence-command-transport.ts +160 -0
  13. package/lib/evidence-prevalidator.ts +22 -0
  14. package/lib/fallow-availability.ts +129 -0
  15. package/lib/gate-refusal-currency.ts +112 -0
  16. package/lib/gate-timeouts.ts +82 -0
  17. package/lib/generators/agent-briefs.ts +4 -1
  18. package/lib/generators/agents-md.ts +71 -23
  19. package/lib/generators/code-map.ts +2 -1
  20. package/lib/generators/types.ts +8 -0
  21. package/lib/git-dates.ts +55 -0
  22. package/lib/junit-checks.ts +484 -0
  23. package/lib/local-calendar-day.ts +78 -0
  24. package/lib/project-state-shape.ts +59 -0
  25. package/lib/promote-outputs.ts +6 -2
  26. package/lib/report-provenance.ts +156 -0
  27. package/lib/sc-claim-forms.ts +75 -0
  28. package/lib/sc-id-cross-tree.ts +311 -0
  29. package/lib/scaffold/ai-review-step.ts +180 -0
  30. package/lib/scaffold/owned-files.ts +42 -2
  31. package/lib/scaffold/rehearsal.ts +205 -71
  32. package/lib/scaffold/steps.ts +128 -73
  33. package/lib/scaffold/write-steps.ts +6 -4
  34. package/lib/scanner.ts +38 -12
  35. package/lib/spec-listing.ts +148 -0
  36. package/lib/spec-requirements.ts +209 -0
  37. package/lib/suite-run-reading.ts +170 -0
  38. package/lib/test-command.ts +133 -0
  39. package/lib/test-suite-lock.ts +166 -10
  40. package/lib/tool-probe.ts +120 -0
  41. package/lib/tracked-vs-ignored.ts +234 -0
  42. package/lib/validators/spec-validators.ts +3 -2
  43. package/package.json +1 -1
  44. package/scripts/audit-specs.ts +247 -12
  45. package/scripts/audit-transcript.ts +2 -1
  46. package/scripts/convert-spec.ts +2 -1
  47. package/scripts/create-sc.ts +17 -7
  48. package/scripts/create-spec.ts +2 -1
  49. package/scripts/create-success.ts +2 -1
  50. package/scripts/extract-constraints.ts +90 -19
  51. package/scripts/generate-code-map.ts +53 -12
  52. package/scripts/scaffold-project.ts +4 -1
  53. package/scripts/split-spec.ts +2 -1
  54. package/scripts/sync-sc-status.ts +57 -5
  55. package/scripts/sync-spec-tests.ts +2 -1
@@ -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
- let testCmd = "bun test";
480
- if (existsSync(pkgPath)) {
481
- try {
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 `updateSpecsTable` and `injectEnvironmentSection` by this point, and
665
- * rewriting it would undo both.
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
- const specsDir = join(root, "specs");
729
- if (existsSync(specsDir)) {
730
- const actualSpecs = readdirSync(specsDir).filter(f => f.endsWith(".md"));
731
- const unlisted = actualSpecs.filter(f => !content.includes(f));
732
- if (unlisted.length > 0) {
733
- issues.push(`UNLISTED specs: ${unlisted.join(", ")} (in specs/ but not in AGENTS.md)`);
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
- if (existsSync(join(root, "CODE-MAP.md")) && !content.includes("CODE-MAP")) {
739
- issues.push("CODE-MAP.md exists but not referenced in AGENTS.md routing table");
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: harness?.dev?.testCmd || "bun test",
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
- // Scan test commands
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
- bunVersion: "latest",
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
- return requiredGitignorePatterns().filter(p => !present.has(p));
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 = new Date().toISOString().split("T")[0];
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 = new Date().toISOString().slice(0, 10);
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
- const bunVersion = harness?.ci?.bunVersion || "latest";
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
- bun-version: "${bunVersion}"
2471
+ ${bunStep}
2450
2472
  - run: bun install
2451
- - run: bun test${typecheckStep}
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
- bun-version: "${bunVersion}"
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
- bun node_modules/rungate/scripts/update-project-state.ts --skip-tests 2>/dev/null || true
2717
- git add PROJECT-STATE.md project-state.json 2>/dev/null || true
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(join(projectPath, "AGENTS.md"), agentsMd);
115
- actions.push("REGENERATED: AGENTS.md");
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
- const specFiles = readdirSync(specsDir).filter(f => f.endsWith(".md") && f !== "SPEC-TEMPLATE.md");
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
- specs.push({ file: f, governs, testable });
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
- specs.push({ file: `${sub}/ (${subFiles.length} specs)`, governs: groupGoverns, testable: "yes" });
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
- const pkgPath = join(root, "package.json");
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
+ }