@event4u/agent-config 10.2.0 → 10.3.0

package/src/scripts/lint_skill_router_head.ts

@@ -0,0 +1,254 @@
+#!/usr/bin/env tsx
+/**
+ * Router-head gate — makes the published K6 cap true for NEW skills.
+ *
+ * `src/agent-src/templates/skill.md` has carried "K6: Under 400 lines" as a
+ * checklist item since long before this gate. A checklist item is a statement
+ * of intent that nothing checks; four skills exceed it today. This gate turns
+ * the existing contract into an enforced one, without re-litigating the number.
+ *
+ * The rule: a SKILL.md over MAX_HEAD_LINES must be a router head — an entry
+ * file (when-to-use, mode table, routing) plus per-mode bodies in `tasks/` or
+ * `references/` inside the skill folder. Over the cap with neither directory
+ * present is a monolith and fails.
+ *
+ * WHAT THIS GATE DOES NOT CLAIM. It is not an activation or token argument.
+ * The host loads SKILL.md whole on trigger, and whether it then follows a
+ * pointer into `tasks/` is host behaviour nothing in this tree observes — so
+ * "splitting saves tokens on trigger" is unmeasurable here and is not asserted.
+ * ADR-202's lesson binds: an activation claim goes behind a measured instrument
+ * or it is not made. The defensible claim is narrower and sufficient: the cap
+ * was already the repo's position, and now a new skill cannot quietly ignore it.
+ *
+ * GRANDFATHERING is a shrink-only ratchet. GRANDFATHERED below is seeded with
+ * the measured offender set. Entries may be REMOVED when a skill is
+ * restructured or drops under the cap; adding one is the move this gate exists
+ * to prevent, and the diff makes any addition visible in review. The list is an
+ * inline constant rather than a JSON baseline on purpose — a baseline file
+ * grows without anyone reading it, and this one should be read every time.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/lint_skill_router_head
+ *     ./scripts-run src/scripts/lint_skill_router_head --quiet
+ *
+ * Exit codes: 0 = clean · 2 = any finding OR usage error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
+const _FILE = fileURLToPath(import.meta.url);
+const _HERE = path.dirname(_FILE);
+const REPO = path.resolve(_HERE, '..', '..');
+const SKILLS_REL = 'src/skills';
+
+/** The K6 cap, in lines. Mirrors src/agent-src/templates/skill.md § K6. */
+export const MAX_HEAD_LINES = 400;
+
+/** Directories a router head may route into. `references/` is the established
+ *  convention (9 skills use it today); `tasks/` is permitted by the contract
+ *  for per-mode procedure bodies. */
+export const MODE_BODY_DIRS: readonly string[] = ['tasks', 'references'];
+
+/**
+ * Shrink-only allowlist — skills already over the cap when the gate landed.
+ * Measured, not guessed. REMOVE entries as skills are restructured; never add.
+ */
+export const GRANDFATHERED: readonly string[] = [
+    'ai-council',          // 1055
+    'skill-writing',       //  767
+    'roadmap-management',  //  552
+    'quality-tools',       //  445
+];
+
+export interface Finding {
+    readonly skill: string;
+    readonly lines: number;
+    readonly message: string;
+}
+
+/** Count lines the way `wc -l` does, so the gate and a shell check agree. */
+export function countLines(text: string): number {
+    if (text.length === 0) return 0;
+    const n = text.split('\n').length;
+    return text.endsWith('\n') ? n - 1 : n;
+}
+
+/** Does this skill folder carry at least one mode-body directory? */
+export function hasModeBodies(skillDir: string, dirs: readonly string[] = MODE_BODY_DIRS): boolean {
+    return dirs.some((d) => {
+        try {
+            return fs.statSync(path.join(skillDir, d)).isDirectory();
+        } catch {
+            return false;
+        }
+    });
+}
+
+export interface SkillHead {
+    readonly name: string;
+    readonly lines: number;
+    readonly hasBodies: boolean;
+}
+
+/** Read every `<skillsRoot>/<name>/SKILL.md`. */
+export function collectSkillHeads(skillsRoot: string): SkillHead[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const heads: SkillHead[] = [];
+    for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        const dir = path.join(skillsRoot, e.name);
+        const head = path.join(dir, 'SKILL.md');
+        let text: string;
+        try {
+            text = fs.readFileSync(head, 'utf-8');
+        } catch {
+            continue;
+        }
+        heads.push({ name: e.name, lines: countLines(text), hasBodies: hasModeBodies(dir) });
+    }
+    return heads.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * A head fails when it is over the cap, carries no mode-body directory, and is
+ * not grandfathered. Two separate results are reported so the caller can
+ * distinguish a live violation from allowlist drift.
+ */
+export function evaluate(
+    heads: readonly SkillHead[],
+    grandfathered: readonly string[] = GRANDFATHERED,
+    max: number = MAX_HEAD_LINES,
+): { readonly findings: Finding[]; readonly staleAllowlist: string[] } {
+    const allow = new Set(grandfathered);
+    const findings: Finding[] = [];
+    const stillOver = new Set<string>();
+
+    for (const h of heads) {
+        if (h.lines <= max) continue;
+        stillOver.add(h.name);
+        if (allow.has(h.name)) continue;
+        if (h.hasBodies) continue;
+        findings.push({
+            skill: h.name,
+            lines: h.lines,
+            message:
+                `SKILL.md is ${h.lines} lines (cap ${max}) with no ${MODE_BODY_DIRS.map((d) => `${d}/`).join(' or ')} ` +
+                'directory — over the cap a skill restructures as a router head (entry head + one file per mode), ' +
+                'per templates/skill.md § The router-head contract. The allowlist is shrink-only and does not accept new entries.',
+        });
+    }
+
+    // An allowlist entry for a skill that no longer exceeds the cap (or no
+    // longer exists) is the ratchet failing to tighten: the entry silently
+    // buys nothing and would re-permit a regression. Reported, not fatal —
+    // removing it is a one-line follow-up, not a reason to red the build.
+    const staleAllowlist = grandfathered.filter((g) => !stillOver.has(g));
+
+    return { findings, staleAllowlist };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+class ExitCode extends Error {
+    readonly code: number;
+    constructor(code: number) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+
+function parseArgs(argv: string[]): { readonly quiet: boolean } {
+    let quiet = false;
+    for (const a of argv) {
+        if (a === '--quiet') {
+            quiet = true;
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: lint_skill_router_head [--quiet]\n');
+            throw new ExitCode(0);
+        } else {
+            process.stderr.write(`❌  lint_skill_router_head: unrecognized argument: ${a}\n`);
+            throw new ExitCode(2);
+        }
+    }
+    return { quiet };
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const args = parseArgs(argv);
+
+    // The scanned root is the scope signal. A moved or renamed src/skills would
+    // otherwise produce zero heads and a clean green over nothing at all.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_skill_router_head',
+            candidates: [`${SKILLS_REL}/skill-writing/SKILL.md`],
+            repoRoot: REPO,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
+    const heads = collectSkillHeads(path.join(REPO, SKILLS_REL));
+    const { findings, staleAllowlist } = evaluate(heads);
+
+    for (const s of staleAllowlist) {
+        process.stderr.write(
+            `⚠️   lint_skill_router_head: '${s}' is grandfathered but no longer over the cap — remove it from GRANDFATHERED so the ratchet keeps its teeth\n`,
+        );
+    }
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stderr.write(`❌  ${SKILLS_REL}/${f.skill}/SKILL.md: ${f.message}\n`);
+        }
+        process.stderr.write(`❌  lint_skill_router_head: ${findings.length} finding(s)\n`);
+        return 2;
+    }
+
+    if (!args.quiet) {
+        const over = heads.filter((h) => h.lines > MAX_HEAD_LINES).length;
+        process.stdout.write(
+            `✅  lint_skill_router_head: ${heads.length} skill head(s) scanned · ` +
+            `${over} over the ${MAX_HEAD_LINES}-line cap, all grandfathered or routed · ` +
+            `allowlist holds ${GRANDFATHERED.length} entry(ies), shrink-only\n`,
+        );
+    }
+    return 0;
+}
+
+/** Robust "am I the entry script?" — realpath-compares argv[1] to this file. */
+function _isCliEntry(): boolean {
+    const a = process.argv[1];
+    if (!a) return false;
+    if (a === _FILE || pathToFileURL(path.resolve(a)).href === import.meta.url) return true;
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(_FILE);
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        if (exc instanceof ExitCode) {
+            process.exit(exc.code);
+        }
+        throw exc;
+    }
+}
+
+export { REPO, SKILLS_REL, ExitCode };

package/src/scripts/report_consultation_rate.ts

@@ -48,6 +48,7 @@ import { fileURLToPath } from 'node:url';
 
 import { projectStoreSlug } from './_lib/cc_transcript.js';
 import {
+    isArtifactRead,
     isConsultation,
     isUiWrite,
     type ToolEvent,
@@ -81,6 +82,24 @@ export interface SessionMeasurement {
     consulted: number;
     /** Those turns followed later by opening the review skill. */
     reviewOpenedAfter: number;
+    /**
+     * Those turns that followed reading a provided design artifact.
+     *
+     * Shares this function's denominator on purpose — the two rates answer
+     * different questions over the SAME population ("did it consult the design
+     * surface" vs "did it read the handed-over source"), and measuring them on
+     * separate denominators is how two instruments about one behaviour stop
+     * being comparable.
+     */
+    artifactRead: number;
+    /** True when this session read a provided artifact at any point. */
+    sawArtifact: boolean;
+    /**
+     * True when this session's FIRST UI write came after an artifact read —
+     * the metric named "artifact read before first UI write". Meaningless
+     * unless `sawArtifact`, which is why it is reported over that denominator.
+     */
+    readBeforeFirstWrite: boolean;
 }
 
 export interface RateReport {
@@ -96,6 +115,16 @@ export interface RateReport {
     uiWriteTurns: number;
     consulted: number;
     reviewOpenedAfter: number;
+    /** UI-write turns preceded by reading a provided design artifact. */
+    artifactRead: number;
+    /**
+     * Sessions that read a provided artifact at all — the ONLY honest
+     * denominator for the read-before-write rate. A session with no handover
+     * cannot fail to read one.
+     */
+    handoverSessions: number;
+    /** Of those, the ones whose first UI write came after the read. */
+    handoverReadFirst: number;
 }
 
 /**
@@ -139,10 +168,20 @@ export function toolUseToEvent(part: Record<string, unknown>): ToolEvent | null
  * consult for the file it already wrote.
  */
 export function measureSession(timed: readonly TimedEvent[]): SessionMeasurement {
-    const out: SessionMeasurement = { uiWriteTurns: 0, consulted: 0, reviewOpenedAfter: 0 };
+    const out: SessionMeasurement = {
+        uiWriteTurns: 0,
+        consulted: 0,
+        reviewOpenedAfter: 0,
+        artifactRead: 0,
+        sawArtifact: false,
+        readBeforeFirstWrite: false,
+    };
     let consulted = false;
+    let artifactRead = false;
     /** turn -> was the session already consulted when that turn first wrote UI */
     const writeTurns = new Map<number, boolean>();
+    /** turn -> had an artifact been read when that turn first wrote UI */
+    const artifactTurns = new Map<number, boolean>();
     let lastReviewOpenAt = -1;
     const reviewOpenPositions: number[] = [];
     const writePositions: Array<{ position: number; turn: number }> = [];
@@ -151,10 +190,18 @@ export function measureSession(timed: readonly TimedEvent[]): SessionMeasurement
         if (isUiWrite(event)) {
             if (!writeTurns.has(turn)) {
                 writeTurns.set(turn, consulted);
+                artifactTurns.set(turn, artifactRead);
                 writePositions.push({ position, turn });
             }
             return;
         }
+        // Evaluated INDEPENDENTLY of the consultation branch, never as an
+        // early return before it. The two predicates are not disjoint —
+        // `skills/design-review/references/design.html` satisfies both — so a
+        // `return` here would remove such an event from the consultation
+        // numerator and from the discharge-proxy latch. An earlier revision did
+        // exactly that while claiming in its comment to prevent it.
+        if (isArtifactRead(event)) artifactRead = true;
         if (isConsultation(event)) {
             consulted = true;
             if (event.file.replace(/\\/g, '/').toLowerCase().includes(`skills/${REVIEW_SURFACE}/`)) {
@@ -166,6 +213,20 @@ export function measureSession(timed: readonly TimedEvent[]): SessionMeasurement
 
     out.uiWriteTurns = writeTurns.size;
     for (const wasConsulted of writeTurns.values()) if (wasConsulted) out.consulted += 1;
+    for (const wasRead of artifactTurns.values()) if (wasRead) out.artifactRead += 1;
+    out.sawArtifact = artifactRead;
+    // KNOWN IMPRECISION, accepted: ordering inside ONE assistant message comes
+    // from the `tool_use` part index, and parallel tool calls in a single
+    // message carry no real order. A read and a write issued together can
+    // therefore score either way. Not repaired here — a transcript carries no
+    // per-call timestamp, so the fix is a different data source rather than a
+    // different loop, and the error is bounded to same-message pairs. It is a
+    // third reason the published rate is a ceiling.
+    //
+    // The FIRST write's outcome — `artifactTurns` is insertion-ordered on the
+    // first UI write of each turn, so its first value is that write's state.
+    const firstWrite = artifactTurns.values().next();
+    out.readBeforeFirstWrite = firstWrite.done !== true && firstWrite.value === true;
     // A single max comparison, not a scan per write: the proxy asks only whether
     // ANY review-open follows, so the last one decides every earlier write.
     void reviewOpenPositions;
@@ -216,6 +277,9 @@ export function measureStore(store: string, limit: number): RateReport {
         uiWriteTurns: 0,
         consulted: 0,
         reviewOpenedAfter: 0,
+        artifactRead: 0,
+        handoverSessions: 0,
+        handoverReadFirst: 0,
     };
     // A store that is not there and a store with nothing in it are different
     // findings, and only one of them is about the agent. Collapsing them into
@@ -255,6 +319,11 @@ export function measureStore(store: string, limit: number): RateReport {
         report.uiWriteTurns += measured.uiWriteTurns;
         report.consulted += measured.consulted;
         report.reviewOpenedAfter += measured.reviewOpenedAfter;
+        report.artifactRead += measured.artifactRead;
+        if (measured.sawArtifact) {
+            report.handoverSessions += 1;
+            if (measured.readBeforeFirstWrite) report.handoverReadFirst += 1;
+        }
     }
     return report;
 }
@@ -285,6 +354,62 @@ export function render(report: RateReport, threshold: number): string {
     lines.push(
         `  discharge PROXY (review opened)  ${pct(report.reviewOpenedAfter, report.uiWriteTurns)}  (${report.reviewOpenedAfter}/${report.uiWriteTurns})`,
     );
+    lines.push(
+        `  artifact read (all UI turns)     ${pct(report.artifactRead, report.uiWriteTurns)}  (${report.artifactRead}/${report.uiWriteTurns})`,
+    );
+    lines.push(
+        `  READ BEFORE FIRST WRITE          ${pct(report.handoverReadFirst, report.handoverSessions)}  (${report.handoverReadFirst}/${report.handoverSessions} handover session(s))`,
+    );
+    lines.push('');
+    lines.push(
+        '  READ BEFORE FIRST WRITE is the rate to quote. Its denominator is',
+    );
+    lines.push(
+        '  sessions that read a provided artifact at all — a session with no',
+    );
+    lines.push(
+        '  handover cannot fail to read one, so including it would dilute the',
+    );
+    lines.push(
+        '  rate toward the size of the estate rather than the behaviour.',
+    );
+    lines.push(
+        '  That denominator is narrower than it sounds, twice: "artifact" means',
+    );
+    lines.push(
+        '  a path ending design.html or under .claude/design-system/ — a handover',
+    );
+    lines.push(
+        '  under any other name is not counted — and a session that read one but',
+    );
+    lines.push(
+        '  wrote no UI is excluded, since it had nothing to be late for.',
+    );
+    lines.push(
+        '  The line above it shares the consultation denominator and is kept for',
+    );
+    lines.push(
+        '  comparability with that rate only.',
+    );
+    lines.push('');
+    lines.push(
+        '  A CEILING, NOT A MEASUREMENT, for two reasons. A session handed an',
+    );
+    lines.push(
+        '  artifact that NEVER reads it is invisible — nothing in a transcript',
+    );
+    lines.push(
+        '  marks a handover that was ignored, and that case IS the defect. And a',
+    );
+    lines.push(
+        '  search whose path argument happens to be the artifact counts as a read',
+    );
+    lines.push(
+        '  although nothing was read. Both errors point the same way: the true',
+    );
+    lines.push(
+        '  read-before-write rate is at most what is printed here.',
+    );
     lines.push('');
 
     if (report.sessionsWithUiWrite < threshold) {

package/src/scripts/run_skill_evals.ts

@@ -10,10 +10,13 @@
  * JSON files (json.dumps indent=2 + trailing newline). No behaviour
  * changes.
  *
- * The `.agent-src.uncondensed/skills/` literal below is part of the
- * mirrored .py source — this is a faithful twin, so the legacy path is
- * replicated verbatim, not modernized (ADR-051 carve-out for faithful
- * twins).
+ * SKILLS_ROOT diverges from the mirrored .py source: it resolves the live
+ * skills tree through the shared resolver instead of replicating the retired
+ * container literal. Replicating it made every subcommand fail in
+ * `_skill_dir()` before doing any work — the twin was byte-faithful to a
+ * source that no longer exists and runnable against nothing. Documented per
+ * ADR-200 § 6 in `docs/migration/divergences/src-scripts-run_skill_evals.md`;
+ * an undocumented difference would be a regression by definition.
  *
  * Sub-agent SPAWNING is per-environment (Claude Code, Augment Code,
  * council) and is left as a stub `_spawn_subagent(...)` that authors
@@ -25,11 +28,13 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { SRC_SKILLS } from './_lib/agent_src.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/run_skill_evals.ts → parents[2] is the repo root (mirrors
 // `Path(__file__).resolve().parent.parent.parent` in the .py).
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-export const SKILLS_ROOT = path.join(REPO_ROOT, '.agent-src.uncondensed', 'skills');
+export const SKILLS_ROOT = SRC_SKILLS();
 
 /** JSON value type for eval specs / grades. */
 type JsonValue =

package/src/scripts/schemas/persona.schema.json

@@ -44,6 +44,14 @@
       "type": "string",
       "enum": ["package", "project"],
       "default": "package"
+    },
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "description": "Optional harvest_id list (provenance/harvests.jsonl) this persona may cite as external doctrine. Three distinct states, and the difference is the point: ABSENT = unscoped, today's behaviour for every persona that does not opt in; [] = explicitly declares it asserts only from its own reasoning, nothing harvested; a non-empty list = scoped to exactly those ids. Every declared id must resolve to a ledger row — checked by lint_harvest_provenance.ts, which treats a persona entry as a citation exactly like an inline harvest marker. Not to be confused with the singular `source` field above, which records package-vs-project origin."
     }
   }
 }

package/src/scripts/schemas/provenance-harvest.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "provenance-harvest.schema.json",
+  "title": "Provenance ledger harvest record",
+  "description": "One line of provenance/harvests.jsonl — a single knowledge claim adopted from an external source into this repo's own artefacts. Sibling of provenance-borrow.schema.json, which covers borrowed CODE; this one covers borrowed IDEAS. Contract: provenance/README.md. Enforced by src/scripts/lint_harvest_provenance.ts (hand-rolled validator, following the provenance-borrow precedent — this file documents the contract; it is not loaded at runtime).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["harvest_id", "stated_in", "source_ref", "evidence_locator", "harvested_at", "verdict"],
+  "properties": {
+    "harvest_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Kebab-case slug naming the harvested mechanism. This is the id an artefact cites; it must be unique across the ledger."
+    },
+    "stated_in": {
+      "type": "string",
+      "description": "Repo-relative path of the artefact asserting the claim, optionally suffixed ':<line>'. The path must exist."
+    },
+    "source_ref": {
+      "type": "string",
+      "description": "Either a public source pinned to a revision ('<url>@<sha>'), or an opaque token ('opaque:<id>' / 'ENC1:<payload>') when source-confidentiality keeps the source name out of the tracked tree. A bare URL with no revision is rejected — an unpinned reference cannot be re-verified."
+    },
+    "evidence_locator": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Where inside the source the claim was read — a file:line, a section anchor, or an equivalent locator. Free-form because sources differ, but never empty: a claim whose evidence cannot be located again is not a citation."
+    },
+    "harvested_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO-8601 date (YYYY-MM-DD) the harvest landed."
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["adopt", "adapt"],
+      "description": "How the mechanism entered this repo. Only adopt and adapt produce a row — a rejected, already-present, or unclear finding is recorded in the analysis document, never in the ledger, because nothing in the tree cites it."
+    }
+  }
+}

package/src/scripts/sweep_dead_scan_roots.ts

@@ -148,6 +148,36 @@ export function classify(rel: string): TriageClass {
     return 'C';
 }
 
+/**
+ * Non-gate scripts eligible for the Class-A advisory pass.
+ *
+ * WHY A SECOND POPULATION EXISTS AT ALL. The gate population above is
+ * deliberately shared with the ratchet and the registration test, because three
+ * sites once carried their own regex and disagreed. That sharing is worth
+ * keeping — but it means the sweep's reach is a FILENAME PREFIX, and a script
+ * reading a retired container is dead whether or not its name starts with one
+ * of five words. Measured: `run_skill_evals.ts` roots its `SKILLS_ROOT` at the
+ * skills subtree of the container ADR-051 retired (see `CLASS_A_RETIRED`), and
+ * every subcommand fails in `_skill_dir()` before doing any work — while its
+ * sibling `skill_trigger_eval.ts`, same retired root and a `skill_` prefix, is
+ * reported. One visible, one not, on the prefix alone.
+ *
+ * So this pass widens the READING, never the shared population: it is
+ * Class-A-only (a closed set of retired containers, needing no allowlist to stay
+ * honest), it is advisory, and it feeds neither the ratchet count nor the exit
+ * code. Widening `matchesGatePattern` instead would move the ratchet base for a
+ * reason unrelated to any gate.
+ */
+export function isNonGateScript(filename: string): boolean {
+    if (!filename.endsWith('.ts')) return false;
+    if (filename.endsWith('.d.ts') || filename.endsWith('.test.ts')) return false;
+    // This file declares the retired containers as a classification table
+    // (`CLASS_A_RETIRED`); reading its own constant back as a dead root is a
+    // self-report, not a finding.
+    if (filename === 'sweep_dead_scan_roots.ts') return false;
+    return !isGateFile(filename);
+}
+
 export interface Finding {
     rel: string;
     names: string;
@@ -827,6 +857,20 @@ export function main(argv: string[]): number {
         if (r.confirmed.length || r.unproven.length) results.set(f, r);
     }
 
+    // Class-A advisory over the scripts the shared gate population cannot reach.
+    // Reuses the same extractor, so a prose mention or a report string is not a
+    // finding — only a literal join over a recognised root base is.
+    const advisory: string[] = [];
+    const advisoryPop = fs.existsSync(args.scripts)
+        ? fs.readdirSync(args.scripts).filter(isNonGateScript).sort()
+        : [];
+    for (const f of advisoryPop) {
+        const r = analyze(fs.readFileSync(path.join(args.scripts, f), 'utf-8'), repoRoot);
+        for (const h of [...r.confirmed, ...r.unproven]) {
+            if (classify(h.rel) === 'A') advisory.push(`  advisory  [A] ${f}: ${h.rel} (${h.names})`);
+        }
+    }
+
     const used = new Set<Disposition>();
     const disposed = (script: string, rel: string): Disposition | undefined => {
         const hit = ledger.find((l) => l.script === script && l.rel === rel);
@@ -899,6 +943,13 @@ export function main(argv: string[]): number {
     if (!args.quiet) {
         process.stdout.write(`sweep_dead_scan_roots: ${pop.length} gate script(s) scanned\n`);
         for (const l of lines) process.stdout.write(`${l}\n`);
+        if (advisory.length) {
+            process.stdout.write(
+                `sweep_dead_scan_roots: ${advisoryPop.length} non-gate script(s) scanned ` +
+                    '(Class-A advisory — not counted, not gated)\n',
+            );
+            for (const l of advisory) process.stdout.write(`${l}\n`);
+        }
     }
 
     if (stale.length) {