rungate 0.4.0 → 0.4.1

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.
@@ -5,6 +5,7 @@
5
5
  */
6
6
 
7
7
  import { readFileSync, writeFileSync, existsSync } from "fs";
8
+ import { writeRoleConfig } from "./config-loader";
8
9
  import type { AgentMeta } from "./generators/types";
9
10
 
10
11
  /**
@@ -83,22 +84,9 @@ export function writeBriefTemplate(templatesDir: string, roleName: string, descr
83
84
  return filePath;
84
85
  }
85
86
 
86
- /**
87
- * Add a new role to the project's rungate.json config.
88
- * Adds brief path, isolation: worktree, and a standardTask.
89
- */
90
- export function addRoleToConfig(configPath: string, roleName: string, description: string): void {
91
- if (!existsSync(configPath)) {
92
- throw new Error(`Config file not found: ${configPath}`);
93
- }
94
- const config = JSON.parse(readFileSync(configPath, "utf-8"));
95
- if (!config.roles) {
96
- config.roles = {};
97
- }
98
- if (config.roles[roleName]) {
99
- throw new Error(`Role '${roleName}' already exists in ${configPath}`);
100
- }
101
- config.roles[roleName] = {
87
+ /** The entry a newly created role gets: brief path, isolation, standardTask. */
88
+ export function buildRoleEntry(roleName: string, description: string) {
89
+ return {
102
90
  brief: `.claude/agents/${roleName}.md`,
103
91
  isolation: "worktree",
104
92
  standardTask: `Perform ${description.toLowerCase()} tasks as assigned`,
@@ -106,7 +94,24 @@ export function addRoleToConfig(configPath: string, roleName: string, descriptio
106
94
  tools: "[Bash, Read]",
107
95
  model: "sonnet",
108
96
  };
109
- writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
97
+ }
98
+
99
+ /**
100
+ * Register a new role in the project's config, whichever layout it is on.
101
+ *
102
+ * This file decides what a role ENTRY looks like; `writeRoleConfig` decides
103
+ * which file it belongs in. Keeping the second half in the loader is #415:
104
+ * the predecessor took a `configPath` from its caller, and every caller built
105
+ * `.claude/rungate.json` by hand.
106
+ *
107
+ * Returns the file the role was written to.
108
+ */
109
+ export function registerRole(
110
+ projectRoot: string,
111
+ roleName: string,
112
+ description: string,
113
+ ): string {
114
+ return writeRoleConfig(projectRoot, roleName, buildRoleEntry(roleName, description));
110
115
  }
111
116
 
112
117
  export const DEFAULT_AGENT_META: Record<string, AgentMeta> = {
package/lib/create-sc.ts CHANGED
@@ -9,6 +9,7 @@ import { join, dirname } from "path";
9
9
  import { fileURLToPath } from "url";
10
10
 
11
11
  import type { ScRegistry } from "./sc-ids";
12
+ import { isFixtureScId } from "./sc-ids";
12
13
  import { tryLoadRungateConfig } from "./config-loader";
13
14
 
14
15
  // ── Types ─────────────────────────────────────────────────────
@@ -243,18 +244,44 @@ export function listPatterns(): string {
243
244
  * that has no registry to hand; silently changing that would be a different
244
245
  * bug. It is the wrong answer in a shared namespace, which is why
245
246
  * `scripts/create-sc.ts` passes one.
247
+ *
248
+ * ## The namespace has a second half, and #392 only fixed the first
249
+ *
250
+ * Consulting the registry stopped two specs minting the same number. It did
251
+ * nothing about test fixtures, which spell SC ids inside the SAME namespace
252
+ * and appear in no registry: `test/sync-sc-status.test.ts:61` is literally
253
+ * `- [ ] SC-9441: AGENTS.md exists`, a checkbox declaration in a string
254
+ * literal. Allocating 900 would mint a criterion out of a scratch number and
255
+ * hand a live claim to a fixture — the shape #392 closed, arriving from the
256
+ * side nothing looks at.
257
+ *
258
+ * So `spelledInSource` is the other half — and only there is the reserved
259
+ * range ignored. The 9000s exist to be safe for fixtures, so counting a
260
+ * FIXTURE at 9450 as taken would push every future criterion past 9000 and
261
+ * destroy the reservation it was built on. That is the one case where a
262
+ * higher number is the wrong answer.
263
+ *
264
+ * A SPEC declaration is authoritative at any number, reserved or not. If a
265
+ * spec has already claimed 9150 then 9150 is claimed, whatever the
266
+ * convention says it should have been, and allocating it again is the
267
+ * collision this function exists to prevent. The reservation is enforced
268
+ * against specs by SC-1524, not by making the allocator pretend.
246
269
  */
247
- export function nextSCNumber(specContent: string, reg?: ScRegistry): number {
270
+ export function nextSCNumber(
271
+ specContent: string,
272
+ reg?: ScRegistry,
273
+ spelledInSource?: Iterable<string>,
274
+ ): number {
248
275
  const ids: number[] = [];
276
+ const take = (raw: string): void => {
277
+ const n = Number(raw.replace(/^SC-[A-Z]?/, ""));
278
+ if (Number.isFinite(n)) ids.push(n);
279
+ };
249
280
  const pattern = /SC-(\d+)/g;
250
281
  let match;
251
- while ((match = pattern.exec(specContent)) !== null) {
252
- ids.push(parseInt(match[1]));
253
- }
254
- for (const id of reg?.declaredById.keys() ?? []) {
255
- const n = Number(id.replace(/^SC-[A-Z]?/, ""));
256
- if (Number.isFinite(n)) ids.push(n);
257
- }
282
+ while ((match = pattern.exec(specContent)) !== null) take(match[0]);
283
+ for (const id of reg?.declaredById.keys() ?? []) take(id);
284
+ for (const id of spelledInSource ?? []) if (!isFixtureScId(id)) take(id);
258
285
  if (ids.length === 0) return 1;
259
286
  return Math.max(...ids) + 1;
260
287
  }
@@ -0,0 +1,435 @@
1
+ /**
2
+ * Where a project's documentation actually lives (#440).
3
+ *
4
+ * `collectScanTargets` was four flat `readdirSync` loops — `*.md`, `docs/*.md`
5
+ * (skipping `archive`), `docs/adr/*.md`, `specs/*.md` — with no recursion.
6
+ * Measured on a consumer project: 84 files scanned, **28 missed**, and every
7
+ * one of the 28 sat in a directory that project's own
8
+ * `.claude/rules/docs-routing.md` names as a documentation location.
9
+ *
10
+ * | Missed | files |
11
+ * |---|---|
12
+ * | `docs/specs/` | 17 |
13
+ * | `reference/` | 5 |
14
+ * | `docs/designs/` | 3 |
15
+ * | `docs/agents/` | 3 |
16
+ *
17
+ * `docs/specs/` is the headline: specs are the densest source of hard
18
+ * constraints in a repo, and the extractor scanned `specs/` (2 files) while
19
+ * skipping `docs/specs/` (17). Same word, different directory, silently
20
+ * dropped.
21
+ *
22
+ * The fix that makes it self-correcting is to stop hardcoding. Every
23
+ * scaffolded project already has a routing table enumerating where its
24
+ * documentation lives — scaffold WRITES that file — so deriving the scan from
25
+ * it makes the extractor track each project's actual layout instead of a list
26
+ * someone has to remember to update.
27
+ */
28
+
29
+ import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "fs";
30
+ import { isAbsolute, join, relative, resolve } from "path";
31
+
32
+ /**
33
+ * Directory names never descended into, wherever they appear.
34
+ *
35
+ * ONE exported list, so there is one thing to mutate and one place to add to.
36
+ * `worktrees` covers `.claude/worktrees`, which is the case the issue names:
37
+ * a worktree is a second copy of the whole repo, so descending into one
38
+ * doubles every constraint and attributes half of them to a path that will
39
+ * not exist tomorrow.
40
+ */
41
+ export const SCAN_EXCLUDE_DIRS: readonly string[] = [
42
+ "archive", "node_modules", ".git", "worktrees", "dist", "build", "coverage",
43
+ ];
44
+
45
+ /**
46
+ * How deep recursion goes beneath a named root.
47
+ *
48
+ * Bounded because the roots come from a file in the repo, and an unbounded
49
+ * walk driven by repo content is a denial of service with extra steps. Six is
50
+ * well past anything observed: the deepest documentation path measured was
51
+ * `specs/bootstrap-data-flow/<file>.md`, at two.
52
+ */
53
+ export const MAX_SCAN_DEPTH = 6;
54
+
55
+ /**
56
+ * Scanned when a project has no routing table.
57
+ *
58
+ * Exactly the four the hardcoded version used, so a project without a routing
59
+ * table sees no change in behaviour — the fallback is the old code, named and
60
+ * reported rather than assumed.
61
+ */
62
+ /**
63
+ * How many directories may be walked.
64
+ *
65
+ * Depth was bounded from the start; breadth was not, and the roots come from
66
+ * a file in the repo — so a table naming thousands of directories is still a
67
+ * walk driven by repo content with no ceiling. Twenty is well past anything
68
+ * observed: this repo declares six.
69
+ */
70
+ export const MAX_SCAN_ROOTS = 20;
71
+
72
+ /**
73
+ * How many files the scan may collect.
74
+ *
75
+ * A cap on roots is not a cap on work — twenty roots times six levels of
76
+ * unbounded fanout is still unbounded — so the bound belongs on the thing
77
+ * that actually grows. This repo's own scan collects 92.
78
+ */
79
+ export const MAX_SCAN_FILES = 2000;
80
+
81
+ export const DEFAULT_SCAN_DIRS: readonly string[] = ["docs", "docs/adr", "specs"];
82
+
83
+ export const ROUTING_RELATIVE_PATH = join(".claude", "rules", "docs-routing.md");
84
+
85
+ export interface DocScanPlan {
86
+ /** Which list the roots came from. Never inferred by the caller. */
87
+ source: "routing" | "default";
88
+ /** Why, in a sentence — so a report can say it rather than imply it. */
89
+ reason: string;
90
+ /** Directories, relative to the project, that exist and were walked. */
91
+ roots: string[];
92
+ /**
93
+ * Directories the routing table names that are NOT on disk.
94
+ *
95
+ * UNMEASURED, not skipped. A routing table that has drifted from the tree
96
+ * is a finding about the project, and `0`, `[]` and "fine" are
97
+ * indistinguishable if it is dropped — which is the whole subject of
98
+ * `.claude/rules/config-access.md`'s *Silent Default Substitution*.
99
+ */
100
+ unmeasured: string[];
101
+ /** Absolute paths, root-level flat plus each root walked. */
102
+ files: string[];
103
+ /**
104
+ * Paths refused because they resolve outside the project (BUG-440-A).
105
+ *
106
+ * Reported rather than dropped, for the same reason `unmeasured` is: a
107
+ * symlinked documentation root that silently contributes nothing is
108
+ * indistinguishable from one that was read and happened to be empty.
109
+ */
110
+ refused: string[];
111
+ /**
112
+ * How many directories the walk entered.
113
+ *
114
+ * On the plan so that the file cap stopping the WALK is checkable rather
115
+ * than asserted in prose — a cap that only stops pushing bounds the output
116
+ * while the traversal keeps costing.
117
+ */
118
+ walked: number;
119
+ }
120
+
121
+ /**
122
+ * The resolved path, if it is really inside the project. Otherwise null.
123
+ *
124
+ * Lexical checks — `startsWith("/")`, `includes("..")` — cannot see a
125
+ * symlink, and recursion is what made that matter: the flat scan this
126
+ * replaces could not descend into `docs/elsewhere -> /somewhere`, so the
127
+ * exposure arrived with the walk. `extract-constraints` turns every `.md`
128
+ * sentence it reaches into a candidate constraint written to AGENTS.md, so
129
+ * one symlink in a cloned repo would copy markdown from anywhere the process
130
+ * can read into this project's rules.
131
+ *
132
+ * Containment, not a symlink ban: a link within the repo is ordinary, and
133
+ * refusing it would be a narrower detector than the thing being detected.
134
+ */
135
+ /**
136
+ * Whether a resolved path lies in or under an excluded directory.
137
+ *
138
+ * Keyed on the RESOLVED path, not the entry name. Measured before this was
139
+ * fixed: `docs/vendor -> node_modules` produced
140
+ * `node_modules/pkg/README.md`, because the exclusion saw the label
141
+ * `vendor`. ONE decider for "is this excluded", so there is one binding to
142
+ * mutate and no second copy that could hold a case up after the first is
143
+ * broken.
144
+ */
145
+ function excludedByPath(rootReal: string, real: string): boolean {
146
+ const rel = relative(rootReal, real);
147
+ if (rel === "") return false;
148
+ // Case-insensitive, always — not "when the filesystem is". On macOS and
149
+ // Windows `NODE_MODULES` and `node_modules` are one directory, and keying
150
+ // on the exact bytes let the whole list be bypassed by changing a letter.
151
+ // Measured before this: `docs/vendor -> NODE_MODULES` was scanned.
152
+ const lowered = SCAN_EXCLUDE_DIRS.map(d => d.toLowerCase());
153
+ return rel.split("/").some(seg => lowered.includes(seg.toLowerCase()));
154
+ }
155
+
156
+ function containedReal(rootReal: string, path: string): string | null {
157
+ let real: string;
158
+ try {
159
+ real = realpathSync(path);
160
+ } catch {
161
+ return null;
162
+ }
163
+ const rel = relative(rootReal, real);
164
+ if (rel !== "" && (rel.startsWith("..") || isAbsolute(rel))) return null;
165
+ return real;
166
+ }
167
+
168
+ /**
169
+ * Everything from the "Where to Create Things" heading onwards.
170
+ *
171
+ * The routing file has TWO tables and they mean different things. The first
172
+ * answers "where do I read about X"; the second answers "where do I put a new
173
+ * X", and it includes `src/` and `test/`. Reading both conflates
174
+ * documentation with source — measured on this repo, it pulled 36 files out
175
+ * of `test/fixtures/`, which is a synthetic project whose "constraints" would
176
+ * then be extracted and attributed to the real one.
177
+ *
178
+ * The cut is by SECTION rather than by column position. A parser tied to a
179
+ * column layout would silently read half when one table changed shape; a
180
+ * heading is what actually separates the two meanings.
181
+ */
182
+ const CREATE_SECTION = /^##\s+Where to Create Things\s*$/m;
183
+
184
+ /**
185
+ * The directories a routing table names as places documentation is READ from.
186
+ *
187
+ * Tokens ending in `/` are directories; `CODE-MAP.md` and friends are single
188
+ * files already caught by the flat root scan.
189
+ */
190
+ export function routedDirectories(routingText: string): string[] {
191
+ const cut = CREATE_SECTION.exec(routingText);
192
+ const readSection = cut ? routingText.slice(0, cut.index) : routingText;
193
+ const out: string[] = [];
194
+ for (const m of readSection.matchAll(/`([^`]+)`/g)) {
195
+ const token = m[1]!.trim();
196
+ if (!token.endsWith("/")) continue;
197
+ const dir = token.replace(/\/+$/, "");
198
+ if (dir === "" || dir.startsWith("/") || dir.includes("..")) continue;
199
+ // "(6 specs)" and similar annotations live outside the backticks, but a
200
+ // token with whitespace in it is prose, not a path.
201
+ if (/\s/.test(dir)) continue;
202
+ if (!out.includes(dir)) out.push(dir);
203
+ }
204
+ return out;
205
+ }
206
+
207
+ interface WalkState {
208
+ projectPath: string;
209
+ rootReal: string;
210
+ /**
211
+ * Resolved paths already handled.
212
+ *
213
+ * Keyed on the RESOLVED path, which is what makes it do two jobs: it stops
214
+ * a symlink loop, and it stops one file reachable under two names from
215
+ * being collected twice. A file counted twice reads as two independent
216
+ * sources agreeing, which is the evidence a reader weighs most heavily.
217
+ */
218
+ seen: Set<string>;
219
+ files: string[];
220
+ refused: string[];
221
+ truncatedFiles: number;
222
+ walked: number;
223
+ }
224
+
225
+ /**
226
+ * The project-anchored canonical spelling of a contained path.
227
+ *
228
+ * `real` is correct but anchored on the resolved root, and on macOS that is
229
+ * `/private/var/...` where the caller said `/var/...`. Callers do
230
+ * `relative(projectPath, file)`, so the path has to keep the caller's
231
+ * spelling of the root while taking the resolved spelling of everything
232
+ * below it.
233
+ *
234
+ * Reporting the canonical name also makes the list deterministic: a file
235
+ * reachable both directly and through an internal symlink was otherwise
236
+ * recorded under whichever name `readdirSync` happened to return first.
237
+ */
238
+ function anchored(projectPath: string, rootReal: string, real: string): string {
239
+ const rel = relative(rootReal, real);
240
+ return rel === "" ? projectPath : join(projectPath, rel);
241
+ }
242
+
243
+ function walkMarkdown(dir: string, depth: number, st: WalkState): void {
244
+ if (depth > MAX_SCAN_DEPTH) return;
245
+ // The cap stops the WALK. Stopping only the push bounds `files` while the
246
+ // traversal and `st.seen` keep growing, which caps the output and not the
247
+ // work.
248
+ if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; return; }
249
+ st.walked++;
250
+ let entries: string[];
251
+ try {
252
+ entries = readdirSync(dir);
253
+ } catch {
254
+ return;
255
+ }
256
+ for (const entry of entries) {
257
+ const path = join(dir, entry);
258
+ const isMarkdown = entry.endsWith(".md");
259
+ let isDir: boolean;
260
+ try {
261
+ isDir = statSync(path).isDirectory();
262
+ } catch {
263
+ continue;
264
+ }
265
+ if (!isDir && !isMarkdown) continue;
266
+
267
+ const real = containedReal(st.rootReal, path);
268
+ if (real === null) {
269
+ st.refused.push(path);
270
+ continue;
271
+ }
272
+ if (excludedByPath(st.rootReal, real)) {
273
+ st.refused.push(real);
274
+ continue;
275
+ }
276
+ if (st.seen.has(real)) continue;
277
+ st.seen.add(real);
278
+ if (!isDir && st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
279
+
280
+
281
+ // The RESOLVED path is what gets walked and recorded, not the path that
282
+ // was validated a moment ago. Validating one value and using another is
283
+ // a window, however narrow, and using `real` closes it for free.
284
+ if (isDir) walkMarkdown(real, depth + 1, st);
285
+ else st.files.push(anchored(st.projectPath, st.rootReal, real));
286
+ }
287
+ }
288
+
289
+ /**
290
+ * Plan the scan for one project.
291
+ *
292
+ * Root-level `.md` files are read FLAT, exactly as before — recursing from
293
+ * the project root would reach `test/`, `lib/` and every fixture in the tree.
294
+ * Only the named documentation directories are walked.
295
+ */
296
+ export function planDocScan(projectPath: string): DocScanPlan {
297
+ const routingPath = join(projectPath, ROUTING_RELATIVE_PATH);
298
+ const hasRouting = existsSync(routingPath);
299
+
300
+ let declared: string[];
301
+ let source: DocScanPlan["source"];
302
+ let reason: string;
303
+
304
+ if (hasRouting) {
305
+ const routed = routedDirectories(readFileSync(routingPath, "utf-8"));
306
+ // UNION with the defaults, never replacement. This repo's own routing
307
+ // table names `docs/adr/` and `docs/research/` but not `docs/` — so a
308
+ // routing-only scan would have LOST the top-level `docs/*.md` the old
309
+ // code read. A fix for a scan that missed 28 files must not miss
310
+ // different ones.
311
+ declared = [...new Set([...routed, ...DEFAULT_SCAN_DIRS])];
312
+ // `source` answers "did the routing table contribute anything", which is
313
+ // not the same question as "does the file exist". A table naming nothing
314
+ // leaves the defaults doing all the work, and saying "routing" there
315
+ // would report a derivation that did not happen.
316
+ source = routed.length > 0 ? "routing" : "default";
317
+ reason = routed.length > 0
318
+ ? `${routed.length} directories named in ${ROUTING_RELATIVE_PATH}, unioned with the default set`
319
+ : `${ROUTING_RELATIVE_PATH} exists but names no directories — the default set only`;
320
+ } else {
321
+ declared = [...DEFAULT_SCAN_DIRS];
322
+ source = "default";
323
+ reason = `no ${ROUTING_RELATIVE_PATH} — scanning the documented default set`;
324
+ }
325
+
326
+ let rootReal: string;
327
+ try {
328
+ rootReal = realpathSync(resolve(projectPath));
329
+ } catch {
330
+ // Loud, not empty. A project root that cannot be resolved has nothing to
331
+ // scan, and returning zero files would be indistinguishable from a
332
+ // project whose documentation is genuinely empty — Silent Default
333
+ // Substitution, in `.claude/rules/config-access.md`'s terms.
334
+ throw new Error(`cannot scan documentation: ${projectPath} does not resolve to a directory`);
335
+ }
336
+
337
+ const st: WalkState = {
338
+ projectPath,
339
+ rootReal,
340
+ seen: new Set<string>(),
341
+ files: [],
342
+ refused: [],
343
+ truncatedFiles: 0,
344
+ walked: 0,
345
+ };
346
+
347
+ const roots: string[] = [];
348
+ const unmeasured: string[] = [];
349
+ let truncated = 0;
350
+ for (const dir of declared) {
351
+ // The exclusion list has to cover the roots as well as the entries.
352
+ // Applying it only inside the walk left a routing table naming
353
+ // `node_modules/` or `worktrees/` walked outright — the exact case the
354
+ // list exists to stop, reached by the one path the list did not cover.
355
+ const abs = join(projectPath, dir);
356
+ const declaredReal = containedReal(st.rootReal, abs);
357
+ if (declaredReal !== null && excludedByPath(st.rootReal, declaredReal)) {
358
+ st.refused.push(abs);
359
+ continue;
360
+ }
361
+ if (roots.length >= MAX_SCAN_ROOTS) { truncated++; continue; }
362
+ let present: boolean;
363
+ try {
364
+ present = statSync(abs).isDirectory();
365
+ } catch {
366
+ present = false;
367
+ }
368
+ if (present && declaredReal === null) {
369
+ // A routed root that leaves the project is neither walked nor silently
370
+ // treated as missing — "the project does not have this" and "the
371
+ // project points this somewhere I will not follow" are different facts.
372
+ st.refused.push(abs);
373
+ continue;
374
+ }
375
+ // Only a ROUTING entry can be unmeasured. A default directory a project
376
+ // simply does not have is not drift; the routing table is a claim the
377
+ // project made about itself, and a claim that does not hold is a finding.
378
+ if (present) roots.push(dir);
379
+ else if (source === "routing" && !DEFAULT_SCAN_DIRS.includes(dir)) unmeasured.push(dir);
380
+ }
381
+
382
+ if (truncated > 0) {
383
+ // Loud, not silent: a scan that quietly stopped at twenty directories
384
+ // reads as a scan that covered everything.
385
+ reason += ` — bounded at ${MAX_SCAN_ROOTS} roots, ${truncated} not walked`;
386
+ }
387
+
388
+ try {
389
+ for (const f of readdirSync(projectPath)) {
390
+ if (!f.endsWith(".md")) continue;
391
+ const path = join(projectPath, f);
392
+ const real = containedReal(st.rootReal, path);
393
+ if (real === null) { st.refused.push(path); continue; }
394
+ if (st.seen.has(real)) continue;
395
+ st.seen.add(real);
396
+ if (st.files.length >= MAX_SCAN_FILES) { st.truncatedFiles++; continue; }
397
+ st.files.push(anchored(projectPath, st.rootReal, real));
398
+ }
399
+ } catch {
400
+ // An unreadable project root is the caller's problem, not a silent empty
401
+ // scan — it will show as zero files against a reason that says otherwise.
402
+ }
403
+ for (const dir of roots) walkMarkdown(join(projectPath, dir), 1, st);
404
+
405
+ if (st.truncatedFiles > 0) {
406
+ // Loud, not silent: a scan that quietly stopped reading files reads as
407
+ // a scan that covered everything it was pointed at.
408
+ reason += ` — bounded at ${MAX_SCAN_FILES} files, ${st.truncatedFiles} not read`;
409
+ }
410
+
411
+ st.files.sort();
412
+ st.refused.sort();
413
+ return {
414
+ source, reason, roots, unmeasured,
415
+ files: st.files, refused: st.refused, walked: st.walked,
416
+ };
417
+ }
418
+
419
+ /** Relative paths, for a report that a human reads. */
420
+ export function planSummary(projectPath: string, plan: DocScanPlan): string {
421
+ const parts = [
422
+ `scan: ${plan.files.length} files from ${plan.roots.length} directories (${plan.source} — ${plan.reason})`,
423
+ ];
424
+ if (plan.refused.length > 0) {
425
+ parts.push(
426
+ `REFUSED: ${plan.refused.map(r => relative(projectPath, r) || r).join(", ")} — resolves outside the project`,
427
+ );
428
+ }
429
+ if (plan.unmeasured.length > 0) {
430
+ parts.push(
431
+ `UNMEASURED: ${plan.unmeasured.join(", ")} — named in ${ROUTING_RELATIVE_PATH} but not present in ${relative(projectPath, projectPath) || "the project"}`,
432
+ );
433
+ }
434
+ return parts.join("\n");
435
+ }
@@ -46,16 +46,16 @@ export const WARN_TIER_CHECKS: Readonly<Record<string, string>> = Object.freeze(
46
46
  "spec-decision-compliance: AC language aligns with spec decisions":
47
47
  "#409 Decision #9 placed this in the WARN tier explicitly: it matches AC prose against " +
48
48
  "regex anti-patterns, and a regex over prose is not a basis for refusing a run.",
49
- "outcome-evidence-behavioral: OUTCOME AC evidence is not just a number":
50
- "#183 — reported, not fixed. This one is NOT a documented decision like the two above; " +
51
- "it is `tsc-pass`'s shape with a console.warn where the assertion should be, and the " +
52
- "sibling check `outcome-acs-no-skip` two tests above it does assert. Tightening it is a " +
53
- "behaviour change to a live gate and belongs to its own issue.",
54
49
  "ac-issue-alignment: ACs cover goal keywords":
55
- "#183 — reported, not fixed. Found by this audit, not by #176. ADR-009 C4 asks that ACs " +
56
- "cover the goal's keywords; the body computes a coverage ratio and warns under 50%. A " +
57
- "stopword-filtered substring match is not a basis for refusing a run, but nothing said " +
58
- "so until this entry, which is the whole point of the list.",
50
+ "#423 Decision — measured, then kept as a warning. ADR-009 C4 asks that ACs cover the " +
51
+ "goal's keywords and the body warns under 50% coverage. Measured over the 153 " +
52
+ "workflow-state.json files under ~/.rungate carrying a goal: 71% fall under that " +
53
+ "threshold, median coverage 38%. Restricted to states whose ACs carry real statements " +
54
+ "the figure is 66% of 131, median 41%; for substantial ones, 73% of 101. The number does " +
55
+ "not move, and a check that would refuse two runs in three is an outage rather than a " +
56
+ "gate. Same basis #409 Decision #9 rejected for spec-decision-compliance: a match over " +
57
+ "prose is not grounds for refusing a run. The reading is lib/ac-quality.ts's " +
58
+ "goalKeywordCoverage so the threshold is drivable from both sides by a test.",
59
59
  });
60
60
 
61
61
  /**