@event4u/agent-config 9.33.0 → 9.34.0

package/src/scripts/build_discovery_manifest.ts

@@ -38,6 +38,7 @@
  *
  * Schema: docs/contracts/discovery-manifest.schema.json
  */
+import * as child_process from 'node:child_process';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -83,6 +84,7 @@ interface ModuleConfig {
     DEFAULT_DEPRECATION_REPORT: string;
     DEFAULT_TRUST_REPORT: string;
     DEFAULT_ORPHAN_REPORT: string;
+    DEFAULT_DORMANCY_REPORT: string;
     DEFAULT_WORKSPACES_JSON: string;
     DEFAULT_PACKS_JSON: string;
     // Patchable seams (Python monkeypatches these module attributes).
@@ -101,6 +103,7 @@ function _deriveConfig(root: string): ModuleConfig {
         DEFAULT_DEPRECATION_REPORT: path.join(disc, 'deprecation-report.md'),
         DEFAULT_TRUST_REPORT: path.join(disc, 'trust-report.md'),
         DEFAULT_ORPHAN_REPORT: path.join(disc, 'orphan-report.md'),
+        DEFAULT_DORMANCY_REPORT: path.join(disc, 'dormancy-report.md'),
         DEFAULT_WORKSPACES_JSON: path.join(disc, 'workspaces.json'),
         DEFAULT_PACKS_JSON: path.join(disc, 'packs.json'),
         artefact_roots: _artefact_roots,
@@ -937,6 +940,156 @@ function _deprecation_report(manifest: JsonObject): string {
     return lines.join('\n') + '\n';
 }
 
+/** Dormancy window, in months. `docs/governance.md` § Skill lifecycle policy. */
+const _DORMANCY_MONTHS = 6;
+
+/**
+ * What the dormancy report could actually establish from git in this checkout.
+ *
+ * `ok: false` is a first-class outcome, not an error: a shallow clone or a
+ * repository younger than the window cannot distinguish "untouched for six
+ * months" from "history truncated three months ago", and CI clones are shallow
+ * by default. The report NAMES that instead of emitting a list built on it.
+ */
+export interface DormancyProbe {
+    ok: boolean;
+    /** Why the signal is unavailable — set iff `ok` is false. */
+    reason?: string;
+    /** Repo-relative paths with at least one commit inside the window. */
+    touched: Set<string>;
+}
+
+function _git(root: string, args: readonly string[]): string | null {
+    try {
+        return child_process.execFileSync('git', [...args], {
+            cwd: root,
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Probe git once for the whole estate: one bounded `--since` walk, exactly the
+ * command `governance.md` names, rather than one `git log` per artefact.
+ */
+function _dormancy_probe(root: string, now: Date = new Date()): DormancyProbe {
+    const since = `${String(_DORMANCY_MONTHS)} months ago`;
+    if (_git(root, ['rev-parse', '--git-dir']) === null) {
+        return { ok: false, reason: 'not a git checkout — commit history is unavailable', touched: new Set() };
+    }
+    if ((_git(root, ['rev-parse', '--is-shallow-repository']) ?? '').trim() === 'true') {
+        return {
+            ok: false,
+            reason:
+                'shallow clone — a truncated history is indistinguishable from a dormant artefact. ' +
+                'Re-run after `git fetch --unshallow`.',
+            touched: new Set(),
+        };
+    }
+    const oldest = (_git(root, ['log', '--reverse', '--format=%cI', '--max-count=1']) ?? '').trim();
+    if (oldest !== '') {
+        const cutoff = new Date(now);
+        cutoff.setMonth(cutoff.getMonth() - _DORMANCY_MONTHS);
+        if (new Date(oldest) > cutoff) {
+            return {
+                ok: false,
+                reason:
+                    `repository history starts ${oldest.slice(0, 10)}, inside the ` +
+                    `${String(_DORMANCY_MONTHS)}-month window — every artefact would read as dormant`,
+                touched: new Set(),
+            };
+        }
+    }
+    const out = _git(root, ['log', `--since=${since}`, '--name-only', '--format=']);
+    if (out === null) {
+        return { ok: false, reason: 'git log failed', touched: new Set() };
+    }
+    const touched = new Set(out.split('\n').map((l) => l.trim()).filter((l) => l !== ''));
+    return { ok: true, touched };
+}
+
+/**
+ * The unit dormancy is measured over. A skill is a directory (governance names
+ * `git log -- src/skills/<name>/`), so a commit touching its `reference.md`
+ * keeps the skill alive; every other artefact is its own file.
+ */
+function _dormancy_unit(artefactPath: string): string {
+    return path.basename(artefactPath) === 'SKILL.md' ? path.dirname(artefactPath) : artefactPath;
+}
+
+/**
+ * Artefacts with no commit inside the dormancy window.
+ *
+ * Report-only by construction: `governance.md` § Skill lifecycle policy says
+ * dormancy triggers review, never auto-deprecation — and a finished artefact is
+ * indistinguishable from an abandoned one from commit dates, so the
+ * false-positive class is not empty and no argument makes it so.
+ */
+function _dormant_artefacts(manifest: JsonObject, probe: DormancyProbe): JsonObject[] {
+    if (!probe.ok) {
+        return [];
+    }
+    const alive = new Set<string>();
+    for (const p of probe.touched) {
+        alive.add(p);
+        // A touched file keeps its containing directory-shaped artefact alive.
+        for (let d = path.dirname(p); d !== '.' && d !== path.sep; d = path.dirname(d)) {
+            alive.add(d);
+        }
+    }
+    const out: JsonObject[] = [];
+    for (const a of manifest['artefacts'] as JsonObject[]) {
+        const unit = _dormancy_unit(a['path'] as string);
+        if (!alive.has(unit)) {
+            out.push({ path: a['path'], unit, category: a['category'] });
+        }
+    }
+    out.sort((a, b) => _cmpStr(a['path'] as string, b['path'] as string));
+    return out;
+}
+
+/** The dormancy section of the discovery report family (governance.md § Skill lifecycle policy). */
+function _dormancy_report(manifest: JsonObject, probe: DormancyProbe): string {
+    const lines = ['# Discovery — Dormancy Report', ''];
+    lines.push(`- Generated: \`${String(manifest['generated_at'])}\``);
+    lines.push(`- Window: **${String(_DORMANCY_MONTHS)} months** without a commit`);
+    lines.push('');
+    lines.push('> Dormancy triggers **review, never auto-deprecation**');
+    lines.push('> (`docs/governance.md` § Skill lifecycle policy). A finished artefact and an');
+    lines.push('> abandoned one look identical from commit dates, so this is a prompt to ask');
+    lines.push('> "still earning its slot?" — never a removal list, and never a gate.');
+    lines.push('');
+    if (!probe.ok) {
+        lines.push('## Signal unavailable');
+        lines.push('');
+        lines.push(`**No dormancy list is published**: ${String(probe.reason)}`);
+        lines.push('');
+        lines.push('An empty section here would read as "nothing is dormant", which is a');
+        lines.push('different claim from "the signal could not be computed".');
+        lines.push('');
+        return lines.join('\n') + '\n';
+    }
+    const items = _dormant_artefacts(manifest, probe);
+    lines.push(`- Dormant artefacts: **${items.length}**`);
+    lines.push('');
+    if (items.length === 0) {
+        lines.push('_None. Every artefact was touched inside the window._');
+        lines.push('');
+        return lines.join('\n') + '\n';
+    }
+    lines.push('| Path | Unit | Category |');
+    lines.push('|---|---|---|');
+    for (const a of items) {
+        lines.push(`| \`${String(a['path'])}\` | \`${String(a['unit'])}\` | ${String(a['category'])} |`);
+    }
+    lines.push('');
+    return lines.join('\n') + '\n';
+}
+
 /** Trust-level breakdown by workspace + human-review sanity flag. Mirrors `_trust_report`. */
 function _trust_report(manifest: JsonObject): string {
     const byWs = new Map<string, JsonObject>();
@@ -1195,6 +1348,7 @@ interface ParsedArgs {
     deprecation_report: string;
     trust_report: string;
     orphan_report: string;
+    dormancy_report: string;
     workspaces_json: string;
     packs_json: string;
     strict: boolean;
@@ -1231,6 +1385,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         deprecation_report: _config.DEFAULT_DEPRECATION_REPORT,
         trust_report: _config.DEFAULT_TRUST_REPORT,
         orphan_report: _config.DEFAULT_ORPHAN_REPORT,
+        dormancy_report: _config.DEFAULT_DORMANCY_REPORT,
         workspaces_json: _config.DEFAULT_WORKSPACES_JSON,
         packs_json: _config.DEFAULT_PACKS_JSON,
         strict: false,
@@ -1242,6 +1397,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         '                                   [--deprecation-report DEPRECATION_REPORT]\n' +
         '                                   [--trust-report TRUST_REPORT]\n' +
         '                                   [--orphan-report ORPHAN_REPORT]\n' +
+        '                                   [--dormancy-report DORMANCY_REPORT]\n' +
         '                                   [--workspaces-json WORKSPACES_JSON]\n' +
         '                                   [--packs-json PACKS_JSON] [--strict]\n' +
         '                                   [--quiet]\n';
@@ -1252,6 +1408,7 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         '--deprecation-report': 'deprecation_report',
         '--trust-report': 'trust_report',
         '--orphan-report': 'orphan_report',
+        '--dormancy-report': 'dormancy_report',
         '--workspaces-json': 'workspaces_json',
         '--packs-json': 'packs_json',
     };
@@ -1324,6 +1481,10 @@ function main(argv: readonly string[]): number {
         _writeFileMkdir(args.deprecation_report, _deprecation_report(manifest));
         _writeFileMkdir(args.trust_report, _trust_report(manifest));
         _writeFileMkdir(args.orphan_report, _orphan_report(manifest));
+        _writeFileMkdir(
+            args.dormancy_report,
+            _dormancy_report(manifest, _dormancy_probe(_config.ROOT)),
+        );
         // Phase 5 sub-views.
         _writeFileMkdir(
             args.workspaces_json,
@@ -1425,6 +1586,10 @@ export {
     _trust_report,
     _orphan_artefacts,
     _orphan_report,
+    _dormancy_probe,
+    _dormancy_unit,
+    _dormant_artefacts,
+    _dormancy_report,
     _workspaces_view,
     _packs_view,
     _summary,

package/src/scripts/check_claims.ts

@@ -55,7 +55,14 @@ const LEDGER_REL = 'docs/CLAIMS.md';
 const SURFACE_ROOTS = ['README.md', 'docs'];
 
 const CLAIM_MARKER = /<!--\s*claim:([A-Za-z0-9._-]+)\s*-->/g;
-const URL_DATED = /^https?:\/\/\S+\(\d{4}-\d{2}-\d{2}\)\s*$/;
+// The documented grammar is `https://… (YYYY-MM-DD)` — with a space, in both
+// docs/CLAIMS.md § Evidence-pointer grammar and this file's own header. The
+// original pattern required the stamp to abut the URL (`\S+\(`), so every
+// pointer written the documented way was rejected. That went unnoticed because
+// the form had zero usage until the external research citations were bound;
+// the space is now optional, which accepts both spellings and keeps the
+// enforcement matching the spec rather than the other way round.
+const URL_DATED = /^https?:\/\/\S+\s*\(\d{4}-\d{2}-\d{2}\)\s*$/;
 
 /** Witness sweep (P1.2) — marketing-class surfaces where a bare number must
  *  not appear as a capability claim. docs/proof.md and docs/comparison.yaml
@@ -118,6 +125,17 @@ export interface LedgerEntry {
     evidence: string;
     status: string;
     last_verified: string;
+    /**
+     * Optional forward link on a `resolved-null` entry: the id of the claim that
+     * reopened the same question by a different mechanism. The retire-never-delete
+     * lifecycle keeps the null readable forever, but a reader arriving at a closed
+     * question has no way to learn it was later reopened — this is that link.
+     *
+     * Parsed and gated rather than merely documented: an unparsed field would be a
+     * documented claim the code does not honour, which is the defect class this
+     * ledger exists to make impossible.
+     */
+    superseded_by: string;
 }
 
 interface Args {
@@ -158,6 +176,7 @@ function load_ledger(): Map<string, LedgerEntry> {
                 evidence: cur.evidence ?? '',
                 status: cur.status ?? '',
                 last_verified: cur.last_verified ?? '',
+                superseded_by: cur.superseded_by ?? '',
             });
         }
         cur = {};
@@ -170,7 +189,7 @@ function load_ledger(): Map<string, LedgerEntry> {
             continue;
         }
         if (!cur.id) continue;
-        const field = line.match(/^-\s+(claim|kind|evidence|status|last_verified):\s*(.*)$/);
+        const field = line.match(/^-\s+(claim|kind|evidence|status|last_verified|superseded_by):\s*(.*)$/);
         if (field) {
             const key = field[1] as keyof LedgerEntry;
             (cur as Record<string, string>)[key] = (field[2] ?? '').trim();
@@ -320,6 +339,36 @@ function main(argv: string[] = process.argv.slice(2)): number {
         if (un) findings.push({ id: entry.id, file: LEDGER_REL, reason: `backed entry has dangling evidence — ${un}` });
     }
 
+    // 2b. Successor pointers: a `superseded_by` must name a real ledger entry,
+    //     and only a closed question can have a successor. The field exists so a
+    //     reader arriving at a `resolved-null` learns the question was reopened
+    //     by a different mechanism — a dangling id would send them nowhere, and
+    //     the field on a live entry would claim a closure that never happened.
+    for (const entry of ledger.values()) {
+        if (!entry.superseded_by) continue;
+        if (entry.status !== 'resolved-null') {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: `superseded_by is only meaningful on a resolved-null entry (status: ${entry.status || 'missing'})`,
+            });
+            continue;
+        }
+        if (!ledger.has(entry.superseded_by)) {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: `superseded_by names claim:${entry.superseded_by}, which is not in the ledger`,
+            });
+        } else if (entry.superseded_by === entry.id) {
+            findings.push({
+                id: entry.id,
+                file: LEDGER_REL,
+                reason: 'superseded_by points at its own entry',
+            });
+        }
+    }
+
     // 3. Witness sweep (road-to-opt-subagent-harvest P1.2): a QUANTIFIED
     //    capability claim on a marketing-class surface must be witnessed — a
     //    `<!-- claim:ID -->` marker on the same line, or an explicit

package/src/scripts/ci_time_ratio.ts

@@ -20,7 +20,9 @@
  * - Median ratio < 3× across all classes      → structural overhead acceptable
  *
  * Output: human-readable table on stdout + JSON to
- * `agents/runtime/reports/ci-time-ratio.json`.
+ * `agents/reports/ci-time-ratio.json` — the tracked report directory, and
+ * the path `DEFAULT_OUT` has always written. This docstring named a
+ * different, untracked directory until 2026-08-11; the code never did.
  *
  * Usage:
  *   node ci_time_ratio.js --limit 30

package/src/scripts/discovery_graph.ts

@@ -23,6 +23,18 @@
  *   build   [--manifest P] [--out P] [--force]     (re)build the graph cache
  *   affected <artefact> [--depth N] [--manifest P]  relation-filtered BFS
  *   explain  <concept>   [--budget N] [--manifest P] seed + 2-hop + budget-cut
+ *   orphans [--manifest P]                          zero-inbound artefact REPORT
+ *
+ * `orphans` is a **report, never a gate** (road-to-inbox-harvest-2026-08-b
+ * estate-lifecycle 3.2): the relation set above is five typed edges and sees a
+ * strictly narrower graph than `check_references.ts`, so a prose-only
+ * cross-reference produces no edge and a reachable artefact reads as
+ * zero-inbound. The false-positive class is provably non-empty, which is why
+ * the command exits 0 on hits and points at review rather than removal.
+ *
+ * Per-pass `stats` accompany the graph: each edge-extraction pass is wrapped in
+ * its own `try`, so one malformed field records `"error"` for that pass instead
+ * of failing the whole build silently or loudly.
  *
  * Exit codes: 0 ok, 1 not-found, 2 usage error, 3 internal error.
  */
@@ -33,14 +45,35 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { reportScanned } from './_lib/scan_scope.js';
 import { scanCached } from './_lib/stat_index.js';
 
 const PROG = 'discovery_graph.ts';
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 // discovery-graph-v<N>.json → version namespace in the path (versioned-cache B5b).
+// The FILE name stays v1 on purpose: `complexity_report.ts:234` reads this exact
+// path. `schema_version` inside the payload carries the shape version instead,
+// and `getGraph` forces a rebuild when a cached payload predates it.
 export const GRAPH_CACHE = path.join(REPO_ROOT, 'agents', 'runtime', 'state', 'discovery-graph-v1.json');
 
+/** Payload shape version. Bumped when `Graph` gains or changes a field. */
+export const GRAPH_SCHEMA_VERSION = 2;
+
+/**
+ * Prefixes that mark a node as SYNTHETIC — a pack or workspace container the
+ * graph invents, not an artefact on disk. Artefact ids are bare repo-relative
+ * paths (`idOf`), so the two live in one id space; anything reasoning over
+ * "artefacts" must exclude these explicitly rather than assume no path ever
+ * starts with `pack:`.
+ */
+export const SYNTHETIC_NODE_PREFIXES = ['pack:', 'workspace:'] as const;
+
+/** True when `id` names a pack/workspace container rather than an artefact. */
+export function isSyntheticNode(id: string): boolean {
+    return SYNTHETIC_NODE_PREFIXES.some((p) => id.startsWith(p));
+}
+
 export type EdgeConfidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
 export interface Edge {
     from: string;
@@ -48,11 +81,14 @@ export interface Edge {
     rel: string;
     confidence: EdgeConfidence;
 }
+/** Per-pass edge counts; `"error"` marks a pass that threw and produced nothing. */
+export type GraphStats = Record<string, number | 'error'>;
 export interface Graph {
     schema_version: number;
     source_checksum: string;
     nodes: string[];
     edges: Edge[];
+    stats: GraphStats;
 }
 
 interface Artefact {
@@ -94,43 +130,92 @@ export function loadManifest(manifestPath: string | null): Manifest {
     return parsed;
 }
 
+/** The five independent edge-extraction passes, in stats-key order. */
+const _PASSES = ['supersedes', 'routes_to', 'references_adr', 'member_of_pack', 'member_of_workspace'] as const;
+type PassName = (typeof _PASSES)[number];
+
 /** Deterministic edge extraction from the manifest's structured fields. */
 export function buildGraph(manifest: Manifest): Graph {
     const nodeSet = new Set<string>();
     const edges: Edge[] = [];
     const idOf = (a: Artefact): string => a.path;
 
+    // Per-pass counters + error containment. One malformed field must not cost
+    // the other four passes: a pass that throws is recorded as `"error"` and
+    // contributes no edges, instead of aborting the build or — worse — being
+    // swallowed into a silently smaller graph nobody can distinguish from a
+    // correct one.
+    const counts = new Map<PassName, number>(_PASSES.map((p) => [p, 0]));
+    const failed = new Set<PassName>();
+    const run = (pass: PassName, fn: () => number): void => {
+        if (failed.has(pass)) return;
+        try {
+            counts.set(pass, (counts.get(pass) ?? 0) + fn());
+        } catch {
+            failed.add(pass);
+        }
+    };
+
     for (const a of manifest.artefacts) {
         const id = idOf(a);
         nodeSet.add(id);
-        for (const r of _asStrings(a.replaces)) {
-            edges.push({ from: id, to: r, rel: 'supersedes', confidence: 'EXTRACTED' });
-            edges.push({ from: r, to: id, rel: 'superseded_by', confidence: 'EXTRACTED' });
-            nodeSet.add(r);
-        }
-        for (const t of _asStrings(a.routes_to)) {
-            edges.push({ from: id, to: t, rel: 'routes_to', confidence: 'EXTRACTED' });
-            nodeSet.add(t);
-        }
-        // ADR references surfaced through any structured target field.
-        for (const t of [..._asStrings(a.replaces), ..._asStrings(a.routes_to)]) {
-            if (/(^|\/)docs\/(decisions|adr)\/ADR-/i.test(t) || /\bADR-\d+/.test(t)) {
-                edges.push({ from: id, to: t, rel: 'references_adr', confidence: 'EXTRACTED' });
+        run('supersedes', () => {
+            let n = 0;
+            for (const r of _asStrings(a.replaces)) {
+                edges.push({ from: id, to: r, rel: 'supersedes', confidence: 'EXTRACTED' });
+                edges.push({ from: r, to: id, rel: 'superseded_by', confidence: 'EXTRACTED' });
+                nodeSet.add(r);
+                n += 2;
+            }
+            return n;
+        });
+        run('routes_to', () => {
+            let n = 0;
+            for (const t of _asStrings(a.routes_to)) {
+                edges.push({ from: id, to: t, rel: 'routes_to', confidence: 'EXTRACTED' });
                 nodeSet.add(t);
+                n += 1;
             }
-        }
-        for (const p of _asStrings(a.packs)) {
-            const node = `pack:${p}`;
-            edges.push({ from: id, to: node, rel: 'member_of', confidence: 'INFERRED' });
-            nodeSet.add(node);
-        }
-        for (const w of _asStrings(a.workspaces)) {
-            const node = `workspace:${w}`;
-            edges.push({ from: id, to: node, rel: 'member_of', confidence: 'INFERRED' });
-            nodeSet.add(node);
-        }
+            return n;
+        });
+        // ADR references surfaced through any structured target field.
+        run('references_adr', () => {
+            let n = 0;
+            for (const t of [..._asStrings(a.replaces), ..._asStrings(a.routes_to)]) {
+                if (/(^|\/)docs\/(decisions|adr)\/ADR-/i.test(t) || /\bADR-\d+/.test(t)) {
+                    edges.push({ from: id, to: t, rel: 'references_adr', confidence: 'EXTRACTED' });
+                    nodeSet.add(t);
+                    n += 1;
+                }
+            }
+            return n;
+        });
+        run('member_of_pack', () => {
+            let n = 0;
+            for (const p of _asStrings(a.packs)) {
+                const node = `pack:${p}`;
+                edges.push({ from: id, to: node, rel: 'member_of', confidence: 'INFERRED' });
+                nodeSet.add(node);
+                n += 1;
+            }
+            return n;
+        });
+        run('member_of_workspace', () => {
+            let n = 0;
+            for (const w of _asStrings(a.workspaces)) {
+                const node = `workspace:${w}`;
+                edges.push({ from: id, to: node, rel: 'member_of', confidence: 'INFERRED' });
+                nodeSet.add(node);
+                n += 1;
+            }
+            return n;
+        });
     }
 
+    const stats: GraphStats = {};
+    for (const p of _PASSES) stats[p] = failed.has(p) ? 'error' : (counts.get(p) ?? 0);
+    const artefactIds = new Set(manifest.artefacts.map(idOf));
+
     // Stable, de-duplicated ordering → byte-stable output.
     const seen = new Set<string>();
     const uniq = edges.filter((e) => {
@@ -140,15 +225,28 @@ export function buildGraph(manifest: Manifest): Graph {
         return true;
     });
     uniq.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.rel.localeCompare(b.rel));
+    // Distinct EXTRACTED targets that name no artefact in the manifest. The
+    // structured fields carry LOGICAL names (`commit:in-chunks`) while node ids
+    // are repo-relative paths, so a non-zero count here means inbound degree is
+    // systematically under-counted — the fact any inverse traversal has to know
+    // before it presents a list. Measured, not assumed: see
+    // `agents/evidence/analysis/discovery-graph-inbound-degree.md`.
+    const danglingTargets = new Set(
+        uniq.filter((e) => e.confidence === 'EXTRACTED' && !artefactIds.has(e.to)).map((e) => e.to),
+    );
+    stats['dangling_targets'] = danglingTargets.size;
     const checksum =
         typeof manifest.checksum === 'string' && manifest.checksum
             ? manifest.checksum
             : 'sha256:' + createHash('sha256').update(JSON.stringify(manifest.artefacts)).digest('hex');
     return {
-        schema_version: 1,
+        schema_version: GRAPH_SCHEMA_VERSION,
         source_checksum: checksum,
         nodes: [...nodeSet].sort(),
         edges: uniq,
+        // Counts are edges EXTRACTED per pass, before the de-duplication above —
+        // so they sum to ≥ `edges.length` and stay attributable to one pass.
+        stats,
     };
 }
 
@@ -188,7 +286,39 @@ export function getGraph(manifestPath: string | null, force: boolean): Graph {
     if (manifestPath !== null) {
         return buildGraph(loadManifest(manifestPath));
     }
-    return scanCached<Graph>(GRAPH_CACHE, _sourceFiles(), () => buildGraph(loadManifest(null)), force);
+    const files = _sourceFiles();
+    const graph = scanCached<Graph>(GRAPH_CACHE, files, () => buildGraph(loadManifest(null)), force);
+    // A cache written before the current payload shape is a stale shape, not a
+    // stale signature — `scanCached` compares signatures only, so the guard is
+    // here. One forced rebuild costs a manifest pass; serving a payload missing
+    // fields the caller's type promises costs a wrong answer.
+    if (graph.schema_version !== GRAPH_SCHEMA_VERSION) {
+        return scanCached<Graph>(GRAPH_CACHE, files, () => buildGraph(loadManifest(null)), true);
+    }
+    return graph;
+}
+
+/**
+ * Artefact nodes with zero inbound EXTRACTED edges — the estate's "nothing
+ * points at this" question, as an inverse traversal of the existing edge set.
+ *
+ * Two exclusions, both load-bearing:
+ *
+ * - `member_of` is INFERRED (`packs`/`workspaces`), and every packed artefact
+ *   has one. Counting it would make almost everything look reachable via its
+ *   own pack node and reduce the report to noise.
+ * - Synthetic pack/workspace nodes are not artefacts and are never the subject
+ *   of the question.
+ *
+ * The result is a REVIEW list, never a removal list — see the module header.
+ */
+export function inboundZero(graph: Graph): string[] {
+    const withInbound = new Set<string>();
+    for (const e of graph.edges) {
+        if (e.confidence !== 'EXTRACTED') continue;
+        withInbound.add(e.to);
+    }
+    return graph.nodes.filter((n) => !isSyntheticNode(n) && !withInbound.has(n)).sort();
 }
 
 /** Relation-filtered BFS from a start node. Returns reachable nodes + hop depth. */
@@ -247,6 +377,50 @@ export function main(argv: string[]): number {
         if (sub === 'build') {
             const graph = getGraph(manifestPath, rest.includes('--force'));
             process.stdout.write(`${PROG}: graph — ${graph.nodes.length} nodes, ${graph.edges.length} edges\n`);
+            for (const [pass, n] of Object.entries(graph.stats)) {
+                process.stdout.write(`  ${pass}: ${String(n)}\n`);
+            }
+            reportScanned({
+                gate: PROG,
+                scanned: graph.nodes.length,
+                units: 'node(s)',
+                roots: ['src', 'docs/decisions', 'docs/adr'],
+            });
+            return 0;
+        }
+        if (sub === 'orphans') {
+            const graph = getGraph(manifestPath, false);
+            const hits = inboundZero(graph);
+            const dangling = graph.stats['dangling_targets'];
+            // Degraded path, NAMED rather than papered over: while EXTRACTED
+            // targets do not resolve to artefact paths, inbound degree is
+            // under-counted for every artefact and the list below is the whole
+            // estate, not a finding. Printing it anyway would be a report that
+            // looks like evidence and is not.
+            if (typeof dangling === 'number' && dangling > 0) {
+                process.stdout.write(
+                    `${PROG}: inbound degree is DEGRADED — ${String(dangling)} EXTRACTED edge target(s)\n` +
+                        'name no artefact path in the manifest (the structured fields carry logical\n' +
+                        'names, node ids are repo-relative paths). Every artefact therefore reads as\n' +
+                        `zero-inbound (${String(hits.length)} of ${String(graph.nodes.length)} nodes), which is a\n` +
+                        'property of the edge set, not of the estate. No list is printed.\n' +
+                        'See `agents/evidence/analysis/discovery-graph-inbound-degree.md`.\n',
+                );
+                return 0;
+            }
+            process.stdout.write(`zero-inbound artefacts (${hits.length} of ${graph.nodes.length} nodes):\n`);
+            for (const h of hits) process.stdout.write(`  ${h}\n`);
+            // 3.3 — the disposition line travels WITH the list, so a reader who
+            // sees only the output still sees what it licenses.
+            process.stdout.write(
+                '\nThis is a review prompt, not a removal list. The graph sees five typed\n' +
+                    'edge kinds and no prose cross-references, so a referenced artefact can\n' +
+                    'appear here; `check_references.ts` is the cross-reference gate, not this.\n' +
+                    'Sunset stays explicit and recorded in the removing commit, with no\n' +
+                    'tombstone files (`docs/governance.md` § Skill lifecycle policy), and the\n' +
+                    'shipped precedent for stale artefacts is archive-not-delete\n' +
+                    '(`src/scripts/janitor.ts:10` — never auto-sweeps).\n',
+            );
             return 0;
         }
         if (sub === 'affected') {
@@ -279,7 +453,7 @@ export function main(argv: string[]): number {
             for (const n of nodes) process.stdout.write(`  [${n.depth}] ${n.node}  (via ${n.via})\n`);
             return 0;
         }
-        process.stderr.write(`usage: ${PROG} <build|affected|explain> [args]\n`);
+        process.stderr.write(`usage: ${PROG} <build|affected|explain|orphans> [args]\n`);
         return 2;
     } catch (exc) {
         process.stderr.write(`${PROG}: error: ${String(exc)}\n`);