@event4u/agent-config 9.34.0 → 9.36.0

package/src/scripts/lint_framework_leakage.ts

@@ -299,14 +299,21 @@ interface AllowlistEntry {
     file?: string;
     lines?: number[] | '*';
     /**
-     * Content anchor — a substring of the exempted line.
+     * Content anchor — a substring of the exempted line. The only per-line key.
      *
-     * Position-keyed entries (`lines: [100]`) are drift-fragile by
-     * construction: inserting a paragraph above line 100 silently re-fires the
-     * ratchet on an entry nobody touched, which this repository has recorded as
-     * a real cost. An anchor keys the exemption to what is actually being
-     * exempted, so the entry survives the edit that moves it. Prefer it for new
-     * entries; `lines` stays supported for the existing ones.
+     * Position keying (`lines: [100]`) is retired, not merely discouraged.
+     * Inserting a paragraph above line 100 re-fires the ratchet on an entry
+     * nobody touched — recorded twice in one pull request — and, worse, it rots
+     * in silence: the migration that introduced this comment found three shipped
+     * entries that had stopped exempting anything, one naming line 100 of a
+     * 68-line file and two naming blank lines. Nothing reported it, because a
+     * drifted position key still parses.
+     *
+     * An anchor keys the exemption to the content being exempted, so it survives
+     * the edit that moves it and fails loudly when that content is gone.
+     * `validate_allowlist` additionally requires it to match exactly one line:
+     * `includes` is file-scoped, so a too-short anchor would silently exempt a
+     * second line nobody reviewed.
      */
     anchor?: string;
     reason?: string;
@@ -328,35 +335,124 @@ function _load_allowlist(): Allowlist {
     }
 }
 
-function _allowlisted(
+/**
+ * Every allowlist entry must still exempt something, and exactly one thing.
+ *
+ * A position-keyed entry rots in silence: the line it names drifts, the entry
+ * keeps parsing, and nothing reports that an exemption stopped exempting. This
+ * repository shipped three such entries — one naming line 100 of a 68-line file,
+ * two naming blank lines — and the rot was invisible until the whole set was read
+ * at once. An anchor cannot drift, but it can over-reach: `includes` is
+ * file-scoped, so an anchor occurring twice silently exempts a second line nobody
+ * reviewed.
+ *
+ * Both failures are decidable from the file, so they are checked rather than
+ * trusted. `lines: '*'` stays legal — a deliberate whole-file exemption is a
+ * different thing from a position key, and it cannot drift.
+ */
+/**
+ * The exact text `_allowlisted` compares an anchor against.
+ *
+ * The matcher sees `Hit.snippet`, not the raw line — trimmed and cut at 160
+ * chars. A validator reading the raw line would clear an anchor copied with its
+ * indentation, or drawn from past column 160, and the gate would then fail to
+ * suppress a hit the maintainer was told is exempt. One function, both callers.
+ */
+export function anchor_haystack(line: string): string {
+    return line.trim().slice(0, 160);
+}
+
+export function validate_allowlist(allowlist: Allowlist, repo_root?: string): string[] {
+    // Default to the MUTABLE root, not the real one: the scan resolves entry
+    // paths against `REPO_ROOT`, and a validator resolving them anywhere else
+    // would report every entry missing the moment a caller redirects the tree.
+    const root = repo_root ?? REPO_ROOT;
+    const problems: string[] = [];
+    for (const entry of allowlist.entries ?? []) {
+        const file = entry.file;
+        if (typeof file !== 'string' || file === '') {
+            problems.push('entry without a `file`');
+            continue;
+        }
+        if (Array.isArray(entry.lines)) {
+            problems.push(
+                `${file}: position-keyed (\`lines: [${entry.lines.join(', ')}]\`) — ` +
+                    'use `anchor` with a substring of the exempted line; a line number ' +
+                    'drifts out from under its own exemption on any edit above it',
+            );
+            continue;
+        }
+        if (entry.lines === '*') {
+            // A whole-file exemption never consults the anchor, so validating one
+            // here would stop every scan for a field the matcher does not read.
+            continue;
+        }
+        const anchor = entry.anchor;
+        if (typeof anchor !== 'string' || anchor === '') {
+            problems.push(`${file}: neither an \`anchor\` nor \`lines: "*"\``);
+            continue;
+        }
+        const abs = path.join(root, file);
+        if (!_isFile(abs)) {
+            problems.push(`${file}: anchored entry names a file that does not exist`);
+            continue;
+        }
+        const matches = fs
+            .readFileSync(abs, 'utf-8')
+            .split('\n')
+            .filter((l) => anchor_haystack(l).includes(anchor)).length;
+        if (matches === 0) {
+            problems.push(
+                `${file}: anchor matches no line — the exempted content is gone, so the ` +
+                    `entry exempts nothing: ${JSON.stringify(anchor.slice(0, 50))}`,
+            );
+        } else if (matches > 1) {
+            problems.push(
+                `${file}: anchor matches ${matches} lines — it would exempt more than the ` +
+                    `reviewed one; lengthen it: ${JSON.stringify(anchor.slice(0, 50))}`,
+            );
+        }
+    }
+    return problems;
+}
+
+/**
+ * Index of the entry that exempts this hit, or `-1`.
+ *
+ * Returns the index rather than a boolean so the run can report which
+ * exemptions were never used. An entry that suppresses nothing is the failure
+ * this gate shipped: three had rotted under position keys, and re-keying them to
+ * anchors preserved the rot, because an anchor resolving to a line says nothing
+ * about that line producing a hit.
+ */
+function _allowlist_index(
     rel_path: string,
     line_no: number,
     allowlist: Allowlist,
     line_text = '',
-): boolean {
+): number {
     const logical = strip_source_prefix(rel_path);
-    for (const entry of allowlist.entries ?? []) {
+    const entries = allowlist.entries ?? [];
+    for (let i = 0; i < entries.length; i += 1) {
+        const entry = entries[i] as AllowlistEntry;
         const entry_file = entry.file;
         const entry_logical =
             typeof entry_file === 'string' ? strip_source_prefix(entry_file) : null;
         if (entry_file !== rel_path && (logical === null || entry_logical !== logical)) {
             continue;
         }
-        const lines = entry.lines;
-        if (lines === '*') {
-            return true;
+        if (entry.lines === '*') {
+            return i;
         }
-        // Content anchor before line number: an anchored entry keeps matching
-        // after an insertion moves the line, which a position key cannot.
+        // Content anchor, and nothing else. A numeric `lines` entry never reaches
+        // this point — `validate_allowlist` stops the run on one — so matching it
+        // here would be a branch that only fires for input the gate rejects.
         const anchor = entry.anchor;
         if (typeof anchor === 'string' && anchor !== '' && line_text.includes(anchor)) {
-            return true;
-        }
-        if (Array.isArray(lines) && lines.includes(line_no)) {
-            return true;
+            return i;
         }
     }
-    return false;
+    return -1;
 }
 
 function _families_in_window(lines: string[], idx: number, radius = 10): Set<string> {
@@ -502,7 +598,12 @@ function* iter_md_files(paths: Iterable<string>): Generator<string> {
     }
 }
 
-function parse_args(argv: readonly string[]): { json: boolean; quiet: boolean; paths: string[] } {
+function parse_args(argv: readonly string[]): {
+    json: boolean;
+    quiet: boolean;
+    narrowed: boolean;
+    paths: string[];
+} {
     let json = false;
     let quiet = false;
     const paths: string[] = [];
@@ -535,16 +636,26 @@ function parse_args(argv: readonly string[]): { json: boolean; quiet: boolean; p
             process.exit(2);
         }
     }
-    return { json, quiet, paths: paths.length > 0 ? paths : _default_paths() };
+    // `narrowed` distinguishes an explicit `--paths` from the default full set.
+    // `paths.length === 0` cannot: the default is three subdirectories, so a full
+    // run also arrives here with a non-empty list — which silently disabled the
+    // unused-exemption check the first time it was written against that test.
+    return {
+        json,
+        quiet,
+        narrowed: paths.length > 0,
+        paths: paths.length > 0 ? paths : _default_paths(),
+    };
 }
 
 /**
  * The allowlist entry that would silence one finding, ready to paste.
  *
- * Anchored on the matched token rather than on the line number: a
- * position-keyed entry re-fires the moment an insertion above moves the line,
- * on an entry nobody touched, which `check_suppression_hygiene` counts every
- * run until the existing 18 migrate.
+ * Anchored on the matched token rather than on the line number: a position key
+ * re-fires the moment an insertion above moves the line, on an entry nobody
+ * touched. The form is no longer merely discouraged — `validate_allowlist`
+ * refuses it, and the last 18 position-keyed entries were migrated to anchors
+ * in the change that introduced the refusal.
  */
 export function suppressionKey(rel: string, hit: Hit): string {
     const anchor = hit.snippet.trim().slice(0, 60);
@@ -613,7 +724,19 @@ export function main(argv?: readonly string[]): number {
     const args = parse_args(raw);
 
     const allowlist = _load_allowlist();
+    // Judge the exemptions before judging any file. A rotted entry produces a
+    // green run that means nothing, which is the one failure mode a gate must
+    // not have. Structural problems are collected here and reported at the end,
+    // NOT returned on early: an early return skipped the `scanned:` line the
+    // gate-coverage collector consumes and left `--json` emitting nothing, so a
+    // consumer parsing the envelope threw on exactly the runs where the gate
+    // reports itself unusable.
+    const allowlist_problems = validate_allowlist(allowlist);
     const file_hits: Array<[string, Hit[]]> = [];
+    // Which exemptions actually suppressed something. Only meaningful over a full
+    // scan: with `--paths` narrowing the tree, an entry for a file outside the
+    // scope is unused for a reason that says nothing about the entry.
+    const used_entries = new Set<number>();
     let total_hits = 0;
     let allowlisted_total = 0;
     // Every enumerated file is planned up front, so the five exemption branches
@@ -661,7 +784,9 @@ export function main(argv?: readonly string[]): number {
             if (h.cross_stack) {
                 continue;
             }
-            if (_allowlisted(rel, h.line, allowlist, h.snippet)) {
+            const idx = _allowlist_index(rel, h.line, allowlist, h.snippet);
+            if (idx >= 0) {
+                used_entries.add(idx);
                 h.allowlisted = true;
                 allowlisted_total += 1;
                 continue;
@@ -679,10 +804,31 @@ export function main(argv?: readonly string[]): number {
         }
     }
 
+    // An exemption that suppressed nothing over a FULL scan exempts nothing at
+    // all — the rot the anchor migration was supposed to end, and which anchoring
+    // alone does not end: an anchor resolving to a line says nothing about that
+    // line producing a hit. Only checked on a full scan, because `--paths` makes
+    // "unused" mean "out of scope" instead.
+    if (!args.narrowed) {
+        const entries = allowlist.entries ?? [];
+        for (let i = 0; i < entries.length; i += 1) {
+            if (used_entries.has(i)) {
+                continue;
+            }
+            const e = entries[i] as AllowlistEntry;
+            allowlist_problems.push(
+                `${String(e.file)}: exemption suppressed nothing this run — the line it names ` +
+                    'produces no leakage hit, so it exempts nothing: ' +
+                    JSON.stringify(String(e.anchor ?? e.lines).slice(0, 50)),
+            );
+        }
+    }
+
     const summary = {
         total_hits,
         files: file_hits.length,
         allowlisted: allowlisted_total,
+        allowlist_problems: allowlist_problems.length,
     };
 
     // Finalize before either output branch: an unaccounted target must throw
@@ -696,10 +842,11 @@ export function main(argv?: readonly string[]): number {
                 hits.map((h) => ({ file: relToRepo(p), ...h })),
             ),
             summary,
+            allowlist_problems,
             ledger: tally,
         };
         process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
-        return total_hits ? 1 : 0;
+        return total_hits || allowlist_problems.length ? 1 : 0;
     }
 
     if (!args.quiet) {
@@ -731,6 +878,26 @@ export function main(argv?: readonly string[]): number {
     // judged) and is the same "reading M as coverage" trap the human summary
     // carries. The ledger makes the honest number the cheap one to publish.
     process.stderr.write(`scanned: ${String(tally.completed + tally.failed)}\n`);
+
+    // Reported AFTER the ledger and the `scanned:` line, so a broken allowlist
+    // still produces both output contracts. An exemption problem fails the run
+    // on its own: a gate that scans cleanly through unusable exemptions is
+    // reporting on a question nobody asked.
+    if (allowlist_problems.length > 0) {
+        process.stderr.write(
+            `\n❌  ${allowlist_problems.length} unusable allowlist entr` +
+                `${allowlist_problems.length === 1 ? 'y' : 'ies'}:\n`,
+        );
+        for (const p of allowlist_problems) {
+            process.stderr.write(`  · ${p}\n`);
+        }
+        process.stderr.write(
+            '  An exemption that names nothing, suppresses nothing, or reaches further\n' +
+                '  than the line it was reviewed for is not an exemption. Remove it or\n' +
+                '  re-anchor it to the content it is meant to cover.\n',
+        );
+        return 1;
+    }
     return total_hits ? 1 : 0;
 }
 

package/src/scripts/lint_framework_leakage_allowlist.json

@@ -1,152 +1,160 @@
 {
   "version": 1,
-  "_doc": "Each entry: { file: relative path from repo root, lines: [int,...] | \"*\" for whole file, reason: short justification }. Use sparingly — first ask whether the file should be neutralized or carved out. Policy cap: > 20 entries means the linter (or the content) is wrong — fix the tool or the text, never grow the list. Rebuilt 2026-07-12 (road-to-opt-hygiene-and-debt Phase 1): 104 → minimal set after heuristic upgrades + 25 content neutralizations + 2 carve-outs.",
+  "_doc": "Each entry: { file: relative path from repo root, anchor: a substring of the exempted line (the ONLY per-line key — position keys are refused by validate_allowlist), or lines: \"*\" for the whole file, reason: short justification }. Use sparingly — first ask whether the file should be neutralized or carved out. Policy cap: > 20 exempted FILES means the linter (or the content) is wrong — fix the tool or the text, never grow the list. The cap counts files because that is the unit it was written in, when one entry meant one file; entries are now per-line, so the two numbers differ on purpose (15 files / 31 entries as of the anchor migration) and the entry count is not the cap. Rebuilt 2026-07-12 (road-to-opt-hygiene-and-debt Phase 1): 104 -> minimal set after heuristic upgrades + 25 content neutralizations + 2 carve-outs. Re-keyed to content anchors 2026-08-12: 8 of the 39 exempted lines were found to exempt nothing — three named blank or out-of-range lines, five named lines that produce no hit — and were dropped rather than carried forward; the gate now refuses both shapes.",
   "entries": [
-    {
-      "file": "src/rules/code-comment-discipline.md",
-      "lines": [
-        100
-      ],
-      "reason": "Worked PHP docblock demo inside the rule's own wrong/right example block — quoted teaching content."
-    },
     {
       "file": "src/skills/api-testing/SKILL.md",
-      "lines": [
-        218
-      ],
+      "anchor": "- Don't test framework internals (e.g., \"does Laravel return",
       "reason": "Quoted example of a framework-internal behavior explicitly marked as what NOT to test — meta content, not a mandate."
     },
     {
       "file": "src/skills/learning-to-rule-or-skill/SKILL.md",
-      "lines": [
-        320,
-        322
-      ],
+      "anchor": "Decision: Create focused skill for Laravel route inspection ",
+      "reason": "Example learnings/decisions quoted verbatim in the promotion-flow walkthrough — meta content."
+    },
+    {
+      "file": "src/skills/learning-to-rule-or-skill/SKILL.md",
+      "anchor": "Learning: \"I forgot to run PHPStan once.\"",
       "reason": "Example learnings/decisions quoted verbatim in the promotion-flow walkthrough — meta content."
     },
     {
       "file": "src/skills/markitdown/SKILL.md",
-      "lines": [
-        74,
-        111
-      ],
+      "anchor": "uv pip install 'markitdown-mcp==0.0.1a4'",
       "reason": "Tool-intrinsic install lines — markitdown IS a pip package; the install command is the tool's identity, not stack leakage."
     },
+    {
+      "file": "src/skills/markitdown/SKILL.md",
+      "anchor": "Plugins enable arbitrary code paths inside the conversion pi",
+      "reason": "Tool-intrinsic install lines — markitdown IS a pip package; the install command is the tool's identity, not stack leakage."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "### Laravel HMVC carve-out",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "│   ├── api.php   web.php   console.php",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "**Auto-loading:** `app/Providers/ModuleServiceProvider.php` ",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "`app/Modules/` and registers routes (`Routes/api.php` → `/ap",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "`api` middleware; `Routes/web.php` → `web` middleware) plus ",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "// Routes/api.php — auto-prefixed /api",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
     {
       "file": "src/skills/module-management/SKILL.md",
-      "lines": [
-        87,
-        99,
-        107,
-        108,
-        109,
-        115,
-        124,
-        156,
-        172
-      ],
+      "anchor": "### Symfony DDD-lite carve-out",
+      "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
+    },
+    {
+      "file": "src/skills/module-management/SKILL.md",
+      "anchor": "metadata in `pyproject.toml`.",
       "reason": "Canonical multi-stack module catalogue (Laravel HMVC / Symfony DDD / Node / Python sections) — keep-in-place is a recorded council decision; per-stack sections sit farther apart than the ±10-line window."
     },
     {
       "file": "src/skills/po-discovery/SKILL.md",
-      "lines": [
-        45
-      ],
+      "anchor": "(\"upgrade Laravel to 11\") — discovery adds noise; skip.",
       "reason": "Quoted example ticket title ('upgrade Laravel to 11') illustrating when discovery adds noise — meta content."
     },
     {
       "file": "src/skills/repomix-packer/SKILL.md",
-      "lines": [
-        44
-      ],
+      "anchor": "npm install -g repomix",
       "reason": "Tool-intrinsic install line — repomix IS an npm package."
     },
     {
       "file": "src/skills/rule-writing/SKILL.md",
-      "lines": [
-        78
-      ],
+      "anchor": "description: \"Writing or reviewing PHP code — strict types, ",
       "reason": "Quoted rule-description example (the php-coding rule's own description string) — meta content. Re-anchored 76→78 after the description-cap edit above it."
     },
-    {
-      "file": "src/skills/security-audit/SKILL.md",
-      "lines": [
-        122
-      ],
-      "reason": "Multi-ecosystem XSS row (Blade/JSX/Jinja peers on one line) + a quoted false-positive example ('Laravel's CSRF is already handled') — documentation, not a mandate."
-    },
     {
       "file": "src/skills/skill-reviewer/SKILL.md",
-      "lines": [
-        70
-      ],
+      "anchor": "- ❌  Describing how Laravel middleware works (in a middlewar",
       "reason": "Quoted anti-example ('❌ Describing how Laravel middleware works') — the line teaches what NOT to write."
     },
     {
       "file": "src/skills/skill-writing/SKILL.md",
-      "lines": [
-        148,
-        456
-      ],
+      "anchor": "Use when creating Laravel middleware for request filtering",
       "reason": "Quoted description examples + the 'too-broad skill (Laravel skill)' anti-pattern — meta content."
     },
     {
       "file": "src/skills/supply-chain-intake/SKILL.md",
-      "lines": [
-        80,
-        82
-      ],
+      "anchor": "rg -n '\"[^\"]+\":\\s*\"(\\^|~|\\*|latest)' package.json",
       "reason": "Per-ecosystem check commands in fenced blocks; the pip/composer siblings sit farther apart than the ±10-line window — genuine multi-ecosystem documentation."
     },
     {
-      "file": "src/skills/test-driven-development/SKILL.md",
-      "lines": [
-        197,
-        200,
-        208,
-        212
-      ],
-      "reason": "Worked Example A (PHP/Pest) paired with Example B (TypeScript/Jest) farther apart than the ±10-line window — canonical two-stack demo."
+      "file": "src/skills/supply-chain-intake/SKILL.md",
+      "anchor": "[ -f package.json ] && [ ! -f package-lock.json ] && echo \"n",
+      "reason": "Per-ecosystem check commands in fenced blocks; the pip/composer siblings sit farther apart than the ±10-line window — genuine multi-ecosystem documentation."
+    },
+    {
+      "file": "src/skills/testing-anti-patterns/SKILL.md",
+      "anchor": "Replacement: a `tests/Support/cleanupSession.php` helper or ",
+      "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
+    },
+    {
+      "file": "src/skills/testing-anti-patterns/SKILL.md",
+      "anchor": "**Concrete capture tools** for recording the real shape: `cu",
+      "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
     },
     {
       "file": "src/skills/testing-anti-patterns/SKILL.md",
-      "lines": [
-        87,
-        124,
-        185
-      ],
+      "anchor": "rg -n '\\b(it|test|describe)\\.skip\\b|\\.only\\b|xit\\(|xdescribe",
       "reason": "Multi-ecosystem capture-tools line and skip-marker grep spanning pytest/PHPUnit/JS in one pattern — documentation across stacks."
     },
     {
       "file": "src/skills/test-driven-development/SKILL.md",
-      "lines": [
-        228,
-        231,
-        239,
-        243
-      ],
+      "anchor": "### Example A — PHP / Pest",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "// tests/Unit/EmailValidatorTest.php — RED",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "Run: `./vendor/bin/pest --filter='rejects empty email'` → fa",
+      "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
+    },
+    {
+      "file": "src/skills/test-driven-development/SKILL.md",
+      "anchor": "// app/Validators/EmailValidator.php — GREEN (minimum)",
       "reason": "Example A of a deliberate A/B pair: '### Example A — PHP / Pest' (L228) sits opposite '### Example B — TypeScript / Vitest' (L259). That is framework-neutrality's textbook 'multi-stack peers' shape, but the two headings are 31 lines apart and the cross-stack window is +/-10, so the heuristic cannot see the sibling. Allowlisted rather than widening the window for a single document — if a second per-stack A/B skill appears, build the section-aware window instead of adding a second entry here."
     },
     {
       "file": "src/skills/image-editing/SKILL.md",
-      "lines": [
-        48
-      ],
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/ada",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     },
     {
       "file": "src/skills/image-generation/SKILL.md",
-      "lines": [
-        45
-      ],
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/ada",
+      "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
+    },
+    {
+      "file": "src/skills/prompt-engineering-image/SKILL.md",
+      "anchor": "`node_modules/@event4u/agent-config/src/scripts/ai-image/adapters/<provider>.sh`",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     },
     {
       "file": "src/skills/prompt-engineering-image/SKILL.md",
-      "lines": [
-        74,
-        115
-      ],
+      "anchor": "- `node_modules/@event4u/agent-config/src/scripts/ai-image/a",
       "reason": "npm install-location path of THIS package's own image-adapter scripts (node_modules/@event4u/agent-config/...) — the factual consumer path after the consumer-internal-ref decoupling (road-to-credible-install Phase 4), not a JS-stack mandate."
     }
   ]

package/src/scripts/lint_roadmap_complexity.ts

@@ -216,6 +216,7 @@ function lint_roadmap(
         _check_human_gate_steps(text, warnings);
         _check_human_gate_phase_headings(text, warnings);
         _check_human_gate_exit_criteria(text, warnings);
+        _check_external_population_gates(text, warnings);
     }
     return problems;
 }
@@ -383,6 +384,65 @@ function _check_human_gate_exit_criteria(text: string, warnings: string[]): void
     }
 }
 
+// A gate whose opening condition depends on a quantity the project cannot
+// produce is not a gate — it is a permanent no in the shape of an answer. The
+// measured case: a single-user private tool carried a roadmap gate on "external
+// installations with write activity", which held 33 steps closed and would have
+// held them closed forever. Matched only inside gate-shaped context (exit
+// criteria, acceptance criteria, a blocker's `Resolved when:`), because these
+// nouns are ordinary vocabulary in a roadmap for an actual product.
+const EXTERNAL_POPULATION_PATS: Array<[RegExp, string]> = [
+    [/\bexternal (users?|installs?|installations?|adopters?|consumers?)\b/i, 'an external user population'],
+    // Bare `adopters` is deliberately absent: measured against the real roadmap
+    // corpus it matched four internal counts ("4 adopters" of a gate helper),
+    // and an external adopter count is already covered by the pattern above.
+    [/\b(installations?|sign-?ups?|subscribers?|active users?)\b/i, 'an external adoption count'],
+    [/\bmarket (demand|validation|traction|fit|signal)\b/i, 'a market signal'],
+    [/\bchurn(ing|ed)?\b/i, 'a metric only a real user population produces'],
+    [/\buser (population|base|segment)\b/i, 'a user population'],
+    [/\b(?:at least |≥\s?)\d+ (people|users|customers|installs|adopters)\b/i, 'a headcount threshold of external people'],
+];
+
+const RESOLVED_WHEN_PAT = /^\s*(?:[-*]\s+)?\*{0,2}resolved when\*{0,2}\s*:/i;
+
+const AUDIENCE_HINT =
+    'is this project meant to have that population at all? A gate whose ' +
+    'condition depends on a quantity the project cannot produce is a permanent ' +
+    'no, not a gate — see project.audience and § 8-pre of ' +
+    'docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md';
+
+function _check_external_population_gates(text: string, warnings: string[]): void {
+    let inHeadingBlock = false;
+    let inInlineBlock = false;
+    for (const rawLine of text.split('\n')) {
+        const heading = /^#{1,6}\s+(.*)$/.exec(rawLine);
+        if (heading) {
+            inHeadingBlock = /\b(acceptance|exit criteria)\b/i.test(heading[1]!);
+            inInlineBlock = false;
+            continue;
+        }
+        if (rawLine.trim() === '') {
+            inInlineBlock = false;
+            continue;
+        }
+        if (EXIT_CRITERIA_OPENER_PAT.test(rawLine)) {
+            inInlineBlock = true;
+        }
+        const isResolvedWhen = RESOLVED_WHEN_PAT.test(rawLine);
+        if (!inHeadingBlock && !inInlineBlock && !isResolvedWhen) {
+            continue;
+        }
+        for (const [re, label] of EXTERNAL_POPULATION_PATS) {
+            if (re.test(rawLine)) {
+                warnings.push(
+                    `gate rests on ${label}: "${rawLine.trim().slice(0, 80)}" — ` + AUDIENCE_HINT,
+                );
+                break;
+            }
+        }
+    }
+}
+
 function _check_execution_mode(fm: string, problems: string[]): void {
     if (!fm || !/^execution:/m.test(fm)) {
         return; // absent field = interactive default — valid