@event4u/agent-config 16.3.0 → 16.5.0

package/src/scripts/_lib/module_reach.ts

@@ -0,0 +1,456 @@
+/**
+ * Module-level reach — which `_lib` modules does nothing in production call?
+ *
+ * `check_gate_reachability.ts` already answers this question at TASK-target
+ * granularity (is a gate wired into `task ci`) and at EXPORT granularity for
+ * the declared loop instruments (`loop_surfaces.ts`). Neither axis sees a
+ * whole MODULE under `src/scripts/_lib/` that nothing imports and nothing
+ * runs by path — that is the gap this module closes.
+ *
+ * Two independent readings, by design, because they answer different
+ * questions and conflating them either over- or under-counts:
+ *
+ * - **Name occurrence** ({@link buildNameIndex}) — the GENEROUS reading. A
+ *   module named only in a comment or a prose file counts as referenced.
+ *   This is the floor: it can only under-count how dead a module is.
+ * - **Import-graph reach** ({@link computeReach}) — follows actual import
+ *   edges (plus run-by-path targets) from every file OUTSIDE `_lib/`,
+ *   treated as live by construction. A module imported only by another
+ *   module that is itself unreached stays unreached — reachability does
+ *   not propagate through a dead node.
+ *
+ * Both are regex-based line scans, matching every other gate in this family
+ * (`check_gate_reachability.ts`'s own `parseTargets`) rather than a full TS
+ * parse: the failure mode of a missed edge is "reports live code as dead",
+ * which a human catches in the one-reading-per-module report; a full parser
+ * would cost a dependency this family has deliberately avoided everywhere
+ * else.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const LIB_DIR_REL = 'src/scripts/_lib';
+export const SCRIPTS_DIR_REL = 'src/scripts';
+export const ROADMAPS_DIR_REL = 'agents/roadmaps';
+export const TASKFILES_DIR_REL = 'taskfiles';
+export const ROOT_TASKFILE_REL = 'Taskfile.yml';
+export const WORKFLOWS_DIR_REL = '.github/workflows';
+export const DISPATCH_REL = 'src/scripts/_dispatch.bash';
+export const CONFIG_DIR_REL = 'src/config';
+export const CONTRACTS_TESTS_DIR_REL = 'tests/contracts';
+
+/** Roots the GENEROUS name-occurrence reading scans — per the roadmap's own list. */
+export const NAME_SCAN_ROOTS: readonly string[] = [
+    'src',
+    TASKFILES_DIR_REL,
+    ROOT_TASKFILE_REL,
+    '.github',
+    'package.json',
+    'docs/contracts',
+];
+
+const IGNORE_DIR_NAMES = new Set(['node_modules', '.git', 'dist', 'coverage']);
+const TEXT_EXTS = new Set(['.ts', '.tsx', '.js', '.mjs', '.yml', '.yaml', '.json', '.md', '.bash', '.sh']);
+
+function isTestFile(relPath: string): boolean {
+    return (
+        relPath.endsWith('.test.ts') ||
+        relPath.endsWith('.test.tsx') ||
+        relPath.endsWith('.d.ts') ||
+        relPath.startsWith('tests/')
+    );
+}
+
+/** Recursively list files under `root`-relative `rel`, filtered to text-ish extensions. */
+function walk(root: string, rel: string, out: string[]): void {
+    const abs = path.join(root, rel);
+    let stat: fs.Stats;
+    try {
+        stat = fs.statSync(abs);
+    } catch {
+        return;
+    }
+    if (stat.isFile()) {
+        if (TEXT_EXTS.has(path.extname(rel))) out.push(rel);
+        return;
+    }
+    if (!stat.isDirectory()) return;
+    for (const entry of fs.readdirSync(abs).sort()) {
+        if (IGNORE_DIR_NAMES.has(entry)) continue;
+        walk(root, path.join(rel, entry), out);
+    }
+}
+
+function listFiles(root: string, rels: readonly string[]): string[] {
+    const out: string[] = [];
+    for (const r of rels) walk(root, r, out);
+    return out;
+}
+
+export interface LibModule {
+    /** Basename without extension — e.g. `module_reach`. */
+    name: string;
+    /** Repo-relative path — e.g. `src/scripts/_lib/module_reach.ts`. */
+    relPath: string;
+    lines: number;
+}
+
+/** Every module directly under `_lib`, excluding test files and declaration files. */
+export function listLibModules(root: string): LibModule[] {
+    const dir = path.join(root, LIB_DIR_REL);
+    if (!fs.existsSync(dir)) return [];
+    const out: LibModule[] = [];
+    for (const entry of fs.readdirSync(dir).sort()) {
+        if (!entry.endsWith('.ts')) continue;
+        const relPath = path.posix.join(LIB_DIR_REL, entry);
+        if (isTestFile(relPath)) continue;
+        const abs = path.join(root, relPath);
+        if (!fs.statSync(abs).isFile()) continue;
+        const text = fs.readFileSync(abs, 'utf-8');
+        out.push({ name: entry.replace(/\.ts$/, ''), relPath, lines: text.split('\n').length });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+const IMPORT_RE = /\bfrom\s+['"]([^'"]+)['"]/g;
+const REQUIRE_RE = /\brequire\(\s*['"]([^'"]+)['"]\s*\)/g;
+const DYNAMIC_IMPORT_RE = /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+/** Resolve a relative import specifier to a repo-relative `.ts` file, or `null`. */
+function resolveImport(root: string, importerRel: string, specifier: string): string | null {
+    if (!specifier.startsWith('.')) return null; // bare specifier — an npm package or node: builtin
+    const importerDir = path.dirname(path.join(root, importerRel));
+    const target = path.resolve(importerDir, specifier);
+    const candidates = [
+        `${target}.ts`,
+        `${target}.tsx`,
+        target.endsWith('.js') ? target.replace(/\.js$/, '.ts') : null,
+        path.join(target, 'index.ts'),
+    ].filter((c): c is string => c !== null);
+    for (const c of candidates) {
+        if (fs.existsSync(c) && fs.statSync(c).isFile()) {
+            return path.relative(root, c).split(path.sep).join('/');
+        }
+    }
+    return null;
+}
+
+/** Directed import edges: importer (non-test `.ts` file) → every `.ts` file it resolves to. */
+export function buildImportGraph(root: string): Map<string, Set<string>> {
+    const graph = new Map<string, Set<string>>();
+    const files = listFiles(root, ['src']).filter(
+        (f) => (f.endsWith('.ts') || f.endsWith('.tsx')) && !isTestFile(f),
+    );
+    for (const rel of files) {
+        const text = fs.readFileSync(path.join(root, rel), 'utf-8');
+        const edges = new Set<string>();
+        for (const re of [IMPORT_RE, REQUIRE_RE, DYNAMIC_IMPORT_RE]) {
+            re.lastIndex = 0;
+            let m: RegExpExecArray | null;
+            while ((m = re.exec(text)) !== null) {
+                const resolved = resolveImport(root, rel, m[1] as string);
+                if (resolved !== null) edges.add(resolved);
+            }
+        }
+        graph.set(rel, edges);
+    }
+    return graph;
+}
+
+/** A literal `_lib` module path mentioned in a taskfile / workflow / the dispatcher, run by path. */
+export function runByPathTargets(root: string): Set<string> {
+    const sources: string[] = [];
+    for (const rel of [ROOT_TASKFILE_REL, DISPATCH_REL]) {
+        const abs = path.join(root, rel);
+        if (fs.existsSync(abs)) sources.push(fs.readFileSync(abs, 'utf-8'));
+    }
+    const tfDir = path.join(root, TASKFILES_DIR_REL);
+    if (fs.existsSync(tfDir)) {
+        for (const f of fs.readdirSync(tfDir).sort()) {
+            if (f.endsWith('.yml') || f.endsWith('.yaml')) sources.push(fs.readFileSync(path.join(tfDir, f), 'utf-8'));
+        }
+    }
+    const wfDir = path.join(root, WORKFLOWS_DIR_REL);
+    if (fs.existsSync(wfDir)) {
+        for (const f of fs.readdirSync(wfDir).sort()) {
+            if (f.endsWith('.yml') || f.endsWith('.yaml')) sources.push(fs.readFileSync(path.join(wfDir, f), 'utf-8'));
+        }
+    }
+    const text = sources.join('\n');
+    const targets = new Set<string>();
+    // The dispatcher also reaches `_lib` via `$SCRIPT_DIR/_lib/<name>.ts` —
+    // `$SCRIPT_DIR` resolves to `src/scripts` at runtime, so the literal
+    // `src/scripts/` prefix is optional here.
+    const re = /(?:src\/scripts\/)?_lib\/([a-zA-Z0-9_]+)(?:\.ts)?/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(text)) !== null) {
+        targets.add(path.posix.join(LIB_DIR_REL, `${m[1] as string}.ts`));
+    }
+    return targets;
+}
+
+export interface ReachResult {
+    /** Every file (not only `_lib`) reached, starting from non-`_lib` files + run-by-path targets. */
+    reached: Set<string>;
+}
+
+/**
+ * BFS from every file OUTSIDE `_lib/` (treated as live, per the roadmap's
+ * "every top-level script as live" reading, generalised to every non-`_lib`
+ * file in `src/`) plus run-by-path targets. A `_lib` module reached only
+ * through another unreached `_lib` module never enters the visited set,
+ * which is what makes "eight that only other unreached modules import" a
+ * distinguishable outcome rather than an automatic pass.
+ */
+export function computeReach(root: string): ReachResult {
+    const graph = buildImportGraph(root);
+    const libDir = `${LIB_DIR_REL}/`;
+    const roots: string[] = [...graph.keys()].filter((f) => !f.startsWith(libDir));
+    for (const t of runByPathTargets(root)) roots.push(t);
+
+    const visited = new Set<string>();
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const n = stack.pop() as string;
+        if (visited.has(n)) continue;
+        visited.add(n);
+        for (const e of graph.get(n) ?? []) if (!visited.has(e)) stack.push(e);
+    }
+    return { reached: visited };
+}
+
+/** `\w` includes `_`, so a snake_case module name tokenises as one identifier. */
+const TOKEN_RE = /[A-Za-z0-9_]+/g;
+
+/**
+ * token → set of repo-relative files mentioning it.
+ *
+ * Scans {@link NAME_SCAN_ROOTS} plus `tests/` — the latter never counts
+ * toward `namedByProduction` ({@link namingFiles} filters test files out),
+ * it exists so {@link importingTests} can see which tests mention a module
+ * at all, including the `tests/contracts/` subset.
+ */
+export function buildNameIndex(root: string): Map<string, Set<string>> {
+    const files = listFiles(root, [...NAME_SCAN_ROOTS, 'tests']);
+    const index = new Map<string, Set<string>>();
+    for (const rel of files) {
+        let text: string;
+        try {
+            text = fs.readFileSync(path.join(root, rel), 'utf-8');
+        } catch {
+            continue;
+        }
+        const seen = new Set<string>();
+        TOKEN_RE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = TOKEN_RE.exec(text)) !== null) seen.add(m[0]);
+        for (const tok of seen) {
+            let set = index.get(tok);
+            if (set === undefined) {
+                set = new Set();
+                index.set(tok, set);
+            }
+            set.add(rel);
+        }
+    }
+    return index;
+}
+
+/** Non-self, non-test files (from the name index) mentioning `moduleName`. */
+export function namingFiles(nameIndex: Map<string, Set<string>>, moduleName: string, selfRelPath: string): string[] {
+    const hits = nameIndex.get(moduleName) ?? new Set<string>();
+    return [...hits].filter((f) => f !== selfRelPath && !isTestFile(f)).sort();
+}
+
+/** Every `tests/**` file (from the name index) mentioning `moduleName`. */
+export function importingTests(nameIndex: Map<string, Set<string>>, moduleName: string): string[] {
+    const hits = nameIndex.get(moduleName) ?? new Set<string>();
+    return [...hits].filter((f) => f.startsWith('tests/')).sort();
+}
+
+export function hasOwnEntryPoint(root: string, relPath: string): boolean {
+    const text = fs.readFileSync(path.join(root, relPath), 'utf-8');
+    return text.startsWith('#!/usr/bin/env') || /\bprocess\.argv\[1\]/.test(text) || /_isCliEntry/.test(text);
+}
+
+/** Config files under `src/config/` (json/yaml) mentioning the module by name or path. */
+export function registryDeclared(root: string, moduleName: string): string[] {
+    const dir = path.join(root, CONFIG_DIR_REL);
+    if (!fs.existsSync(dir)) return [];
+    const out: string[] = [];
+    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json') || f.endsWith('.yaml') || f.endsWith('.yml'));
+    for (const f of files.sort()) {
+        const rel = path.posix.join(CONFIG_DIR_REL, f);
+        const text = fs.readFileSync(path.join(root, rel), 'utf-8');
+        if (new RegExp(`\\b${moduleName}\\b`).test(text)) out.push(rel);
+    }
+    return out;
+}
+
+export type RoadmapEstate = 'active' | 'later' | 'stubs';
+
+export interface RoadmapStepHit {
+    roadmapRelPath: string;
+    estate: RoadmapEstate;
+    /** `' '` open, `'x'` done, `'~'` deferred, `'-'` cancelled, or `null` for prose outside any step. */
+    glyph: string | null;
+    stepLine: string;
+}
+
+function roadmapFiles(root: string): { relPath: string; estate: RoadmapEstate }[] {
+    const dir = path.join(root, ROADMAPS_DIR_REL);
+    if (!fs.existsSync(dir)) return [];
+    const out: { relPath: string; estate: RoadmapEstate }[] = [];
+    for (const f of fs.readdirSync(dir).sort()) {
+        if (f === 'template.md') continue;
+        const abs = path.join(dir, f);
+        if (!fs.statSync(abs).isFile()) continue;
+        if (!f.endsWith('.md')) continue;
+        out.push({ relPath: path.posix.join(ROADMAPS_DIR_REL, f), estate: 'active' });
+    }
+    for (const [sub, estate] of [
+        ['later', 'later'],
+        ['stubs', 'stubs'],
+    ] as const) {
+        const subDir = path.join(dir, sub);
+        if (!fs.existsSync(subDir)) continue;
+        for (const f of fs.readdirSync(subDir).sort()) {
+            if (!f.endsWith('.md')) continue;
+            out.push({ relPath: path.posix.join(ROADMAPS_DIR_REL, sub, f), estate });
+        }
+    }
+    return out;
+}
+
+const STEP_LINE_RE = /^- \[([ x~-])\]/;
+
+/**
+ * Find where `moduleName` is named across the live roadmap estate
+ * (active, `later/`, `stubs/`) — per-step when inside a step block,
+ * `glyph: null` when the mention sits in prose outside any step.
+ */
+export function findRoadmapMentions(root: string, moduleName: string): RoadmapStepHit[] {
+    const hits: RoadmapStepHit[] = [];
+    const nameRe = new RegExp(`\\b${moduleName}\\b`);
+    for (const { relPath, estate } of roadmapFiles(root)) {
+        const lines = fs.readFileSync(path.join(root, relPath), 'utf-8').split('\n');
+        let currentGlyph: string | null = null;
+        let currentStepLine = '';
+        for (const line of lines) {
+            const stepMatch = STEP_LINE_RE.exec(line);
+            if (stepMatch !== null) {
+                currentGlyph = stepMatch[1] as string;
+                currentStepLine = line.trim();
+            } else if (/^#{1,6}\s/.test(line) || line.trim() === '') {
+                // A heading OR a blank line ends the current step's block for our
+                // purposes (kept conservative: a step's cited paths/notes are
+                // usually within a few indented lines of its bullet, not past
+                // the next heading). Both branches reset — an R2 review found
+                // the blank-line case was a no-op here despite this comment
+                // already claiming it reset, which let a mention several lines
+                // below a CLOSED step, separated only by a blank line, still
+                // read as evidence for that step. `#{1,6}` matches
+                // `_lib/md_section.ts`'s own ATX-heading pattern; the prior
+                // `(#|##|###)` here missed level-4+ headings.
+                currentGlyph = null;
+                currentStepLine = '';
+            }
+            if (nameRe.test(line)) {
+                hits.push({ roadmapRelPath: relPath, estate, glyph: currentGlyph, stepLine: currentStepLine });
+            }
+        }
+    }
+    return hits;
+}
+
+export type ReachGroup = 'contract-test' | 'open-or-deferred-step' | 'named-outside-open-step' | 'named-in-none';
+
+export interface ModuleFact {
+    name: string;
+    relPath: string;
+    lines: number;
+    importingTests: string[];
+    namedByProduction: boolean;
+    namingFiles: string[];
+    hasOwnEntryPoint: boolean;
+    registryDeclared: string[];
+    reachedByImportOrPath: boolean;
+    /** Only set when `namedByProduction` is false — the roadmap-based group. */
+    group: ReachGroup | null;
+    /** The step/file citation backing `group`, when roadmaps were available. */
+    groupEvidence: string | null;
+    roadmapsAvailable: boolean;
+}
+
+export interface ModuleReachReport {
+    modules: ModuleFact[];
+    roadmapsAvailable: boolean;
+}
+
+export function analyseModuleReach(root: string): ModuleReachReport {
+    const modules = listLibModules(root);
+    const nameIndex = buildNameIndex(root);
+    const reach = computeReach(root);
+    const roadmapsAvailable = fs.existsSync(path.join(root, ROADMAPS_DIR_REL));
+
+    const facts: ModuleFact[] = modules.map((mod) => {
+        const nf = namingFiles(nameIndex, mod.name, mod.relPath);
+        const namedByProduction = nf.length > 0;
+        let group: ReachGroup | null = null;
+        let groupEvidence: string | null = null;
+
+        if (!namedByProduction) {
+            const contractHit = importingTests(nameIndex, mod.name).find((f) => f.startsWith(CONTRACTS_TESTS_DIR_REL));
+            if (contractHit !== undefined) {
+                group = 'contract-test';
+                groupEvidence = contractHit;
+            } else if (roadmapsAvailable) {
+                const mentions = findRoadmapMentions(root, mod.name);
+                const openOrDeferred = mentions.find((h) => h.glyph === ' ' || h.glyph === '~');
+                if (openOrDeferred !== undefined) {
+                    group = 'open-or-deferred-step';
+                    groupEvidence = `${openOrDeferred.roadmapRelPath} (${openOrDeferred.estate}): ${openOrDeferred.stepLine}`;
+                } else if (mentions.length > 0) {
+                    group = 'named-outside-open-step';
+                    const m = mentions[0] as RoadmapStepHit;
+                    groupEvidence = `${m.roadmapRelPath} (${m.estate})${m.stepLine !== '' ? `: ${m.stepLine}` : ''}`;
+                } else {
+                    group = 'named-in-none';
+                    groupEvidence = null;
+                }
+            } else {
+                // Published package: no roadmaps directory to check against.
+                group = 'named-in-none';
+                groupEvidence = 'no roadmaps directory present — roadmap groups skipped';
+            }
+        }
+
+        return {
+            name: mod.name,
+            relPath: mod.relPath,
+            lines: mod.lines,
+            importingTests: importingTests(nameIndex, mod.name),
+            namedByProduction,
+            namingFiles: nf,
+            hasOwnEntryPoint: hasOwnEntryPoint(root, mod.relPath),
+            registryDeclared: registryDeclared(root, mod.name),
+            reachedByImportOrPath: reach.reached.has(mod.relPath),
+            group,
+            groupEvidence,
+            roadmapsAvailable,
+        };
+    });
+
+    return { modules: facts, roadmapsAvailable };
+}
+
+export function groupCounts(modules: readonly ModuleFact[]): Record<ReachGroup, number> {
+    const counts: Record<ReachGroup, number> = {
+        'contract-test': 0,
+        'open-or-deferred-step': 0,
+        'named-outside-open-step': 0,
+        'named-in-none': 0,
+    };
+    for (const m of modules) if (m.group !== null) counts[m.group] += 1;
+    return counts;
+}

package/src/scripts/_lib/neighbour_contradictions.ts

@@ -0,0 +1,236 @@
+/**
+ * Contradiction review between a project's instructions and its neighbours'
+ * (road-to-neighbours-that-pull-their-weight step 2.2).
+ *
+ * REPORT-ONLY. Nothing here edits, gates or suppresses an instruction — the
+ * output is a table a human reads. `neighbour-precedence` (step 2.1) is the
+ * rubric: the "which wins" column is its source order applied to the two
+ * sources, computed here, and the verdict column is one council seat's reading
+ * of whether the pair actually disagrees.
+ *
+ * NO STATIC DETECTOR DECIDES ANYTHING. A static contradiction detector was
+ * measured at 67 % false positives (`docs/contracts/rule-interactions.md`), so
+ * this module only FORMS candidate pairs, and only from strong signals: a
+ * shared subject word with opposite modality, or a skill name collision the
+ * census already found. Whether a candidate is a contradiction is the seat's
+ * call, never this file's.
+ *
+ * A neighbour body the shape scan refused (step 1.3) is never read here: the
+ * caller passes only scanned sources, and a refused body contributes no line.
+ */
+import * as fs from 'node:fs';
+
+/** Rank in `neighbour-precedence`'s source order — lower wins. */
+export const RANK_PROJECT = 3;
+export const RANK_SUITE = 4;
+export const RANK_NEIGHBOUR_ALWAYS_ON = 6;
+export const RANK_NEIGHBOUR_SKILL = 7;
+
+const RANK_LABEL: Record<number, string> = {
+    [RANK_PROJECT]: 'project instruction file',
+    [RANK_SUITE]: "this suite's routed guidance",
+    [RANK_NEIGHBOUR_ALWAYS_ON]: "neighbour's always-on text",
+    [RANK_NEIGHBOUR_SKILL]: 'neighbour skill body (discoverable)',
+};
+
+export interface InstructionSource {
+    /** Where the text came from, as printed. */
+    label: string;
+    file: string;
+    rank: number;
+}
+
+export interface InstructionLine {
+    source: InstructionSource;
+    line: number;
+    text: string;
+    negative: boolean;
+    stems: Set<string>;
+}
+
+export interface CandidatePair {
+    kind: 'opposite-modality' | 'name-collision';
+    a: { label: string; rank: number; text: string };
+    b: { label: string; rank: number; text: string };
+    /** The shared subject word, or the colliding name. */
+    subject: string;
+}
+
+export type Verdict = 'contradiction' | 'compatible' | 'unclear';
+
+const NEGATION = /\b(never|don't|do not|must not|mustn't|should not|shouldn't|avoid|stop)\b/iu;
+const DIRECTIVE_WORD = /\b(always|must|should|never|don't|do not|avoid)\b/iu;
+const NON_IMPERATIVE_START = new Set([
+    'the', 'a', 'an', 'this', 'that', 'these', 'those', 'it', 'its', 'we', 'you', 'i', 'our',
+    'they', 'there', 'when', 'if', 'see', 'for', 'in', 'on', 'as', 'by', 'with', 'from',
+]);
+const STOP = new Set([
+    'always', 'never', 'must', 'should', 'avoid', 'stop', 'don', 'with', 'without', 'that', 'this',
+    'they', 'them', 'then', 'than', 'into', 'from', 'your', 'when', 'what', 'will', 'each', 'every',
+    'only', 'also', 'here', 'there', 'have', 'been', 'more', 'some', 'such', 'like', 'just',
+]);
+
+/** A crude stem — enough to meet `wait` and `waiting`, never a lemmatiser. */
+export function stem(word: string): string {
+    let w = word.toLowerCase().replace(/[^a-z]/gu, '');
+    for (const suffix of ['ing', 'ed', 'es', 's']) {
+        if (w.length > suffix.length + 3 && w.endsWith(suffix)) {
+            w = w.slice(0, -suffix.length);
+            break;
+        }
+    }
+    return w;
+}
+
+/** Is this line phrased as an instruction at all? */
+export function isDirective(text: string): boolean {
+    if (DIRECTIVE_WORD.test(text)) return true;
+    const first = (text.split(/\s+/u)[0] ?? '').toLowerCase().replace(/[^a-z']/gu, '');
+    return first.length > 0 && !NON_IMPERATIVE_START.has(first);
+}
+
+/** Directive lines of one markdown source, outside fences and frontmatter. */
+export function extractInstructions(source: InstructionSource, body?: string): InstructionLine[] {
+    let text: string;
+    try {
+        text = body ?? fs.readFileSync(source.file, 'utf-8');
+    } catch {
+        return [];
+    }
+    const out: InstructionLine[] = [];
+    let fenced = false;
+    let frontmatter = false;
+    text.split('\n').forEach((raw, i) => {
+        const line = raw.trim();
+        if (i === 0 && line === '---') {
+            frontmatter = true;
+            return;
+        }
+        if (frontmatter) {
+            if (line === '---') frontmatter = false;
+            return;
+        }
+        if (line.startsWith('```') || line.startsWith('~~~')) {
+            fenced = !fenced;
+            return;
+        }
+        if (fenced || line === '' || line.startsWith('#') || line.startsWith('|') || line.startsWith('>')) return;
+        const clean = line.replace(/^([-*+]|\d+\.)\s+/u, '').replace(/[*_`]/gu, '');
+        if (clean.split(/\s+/u).length < 3 || !isDirective(clean)) return;
+        const stems = new Set(
+            clean
+                .split(/\s+/u)
+                .map(stem)
+                .filter((s) => s.length >= 4 && !STOP.has(s)),
+        );
+        out.push({ source, line: i + 1, text: clean, negative: NEGATION.test(clean), stems });
+    });
+    return out;
+}
+
+function where(l: InstructionLine): string {
+    return `${l.source.label}:${l.line}`;
+}
+
+/**
+ * Candidate pairs from opposite modality over a shared subject word.
+ *
+ * Only ACROSS ranks — two lines of one source rank are one author's
+ * contradiction, which is not what this review is for — and only where one
+ * side is negative and the other is not. One pair per line pair, naming the
+ * first shared stem in sorted order so the output is stable.
+ */
+export function modalityPairs(lines: readonly InstructionLine[], cap = 20): CandidatePair[] {
+    const out: CandidatePair[] = [];
+    for (let i = 0; i < lines.length && out.length < cap; i += 1) {
+        for (let j = i + 1; j < lines.length && out.length < cap; j += 1) {
+            const x = lines[i] as InstructionLine;
+            const y = lines[j] as InstructionLine;
+            if (x.source.rank === y.source.rank || x.negative === y.negative) continue;
+            const shared = [...x.stems].filter((s) => y.stems.has(s)).sort();
+            if (shared.length === 0) continue;
+            const [hi, lo] = x.source.rank <= y.source.rank ? [x, y] : [y, x];
+            out.push({
+                kind: 'opposite-modality',
+                a: { label: where(hi), rank: hi.source.rank, text: hi.text },
+                b: { label: where(lo), rank: lo.source.rank, text: lo.text },
+                subject: shared[0] as string,
+            });
+        }
+    }
+    return out;
+}
+
+/** A neighbour skill that shares a name with one of ours — the census's `shadowed`. */
+export function collisionPair(neighbourQualified: string, ourName: string): CandidatePair {
+    return {
+        kind: 'name-collision',
+        a: { label: `suite:${ourName}`, rank: RANK_SUITE, text: `this suite's skill \`${ourName}\`` },
+        b: {
+            label: neighbourQualified,
+            rank: RANK_NEIGHBOUR_SKILL,
+            text: `neighbour skill \`${neighbourQualified}\``,
+        },
+        subject: ourName,
+    };
+}
+
+/** "Which wins by 2.1" — the lower rank, named. */
+export function winnerBy21(p: CandidatePair): string {
+    const w = p.a.rank <= p.b.rank ? p.a : p.b;
+    return `${w.label} (rank ${w.rank}, ${RANK_LABEL[w.rank] ?? 'unranked'})`;
+}
+
+/** The single-seat prompt. States no expected verdict (evaluator-independence). */
+export function seatPrompt(pairs: readonly CandidatePair[], rubric: string): string {
+    const rows = pairs.map(
+        (p, i) => `PAIR ${i + 1} (${p.kind}, subject "${p.subject}")\n  A [${p.a.label}]: ${p.a.text}\n  B [${p.b.label}]: ${p.b.text}`,
+    );
+    return [
+        '# Neighbour contradiction review',
+        '',
+        'For each pair, decide whether A and B give an agent instructions that cannot both be followed.',
+        'Answer one line per pair, exactly `PAIR <n>: contradiction`, `PAIR <n>: compatible` or `PAIR <n>: unclear`,',
+        'then at most one sentence of reason on the same line. The rubric for which source wins is below; you do not',
+        'need to restate it.',
+        '',
+        '## Rubric — neighbour-precedence',
+        '',
+        rubric.trim(),
+        '',
+        '## Pairs',
+        '',
+        ...rows,
+        '',
+    ].join('\n');
+}
+
+/** Read `PAIR <n>: <verdict>` lines; a pair the seat did not answer is `unclear`. */
+export function parseVerdicts(text: string, count: number): Verdict[] {
+    const out: Verdict[] = Array.from({ length: count }, () => 'unclear');
+    for (const m of text.matchAll(/PAIR\s+(\d+)\s*:\s*(contradiction|compatible|unclear)/giu)) {
+        const n = Number(m[1]) - 1;
+        if (n >= 0 && n < count) out[n] = (m[2] ?? 'unclear').toLowerCase() as Verdict;
+    }
+    return out;
+}
+
+export interface ReviewRow {
+    pair: string;
+    verdict: Verdict;
+    wins: string;
+}
+
+/** The table, from pairs and a seat's verdicts. */
+export function reviewRows(pairs: readonly CandidatePair[], verdicts: readonly Verdict[]): ReviewRow[] {
+    return pairs.map((p, i) => ({
+        pair: `${p.a.label} "${p.a.text}" × ${p.b.label} "${p.b.text}"`,
+        verdict: verdicts[i] ?? 'unclear',
+        wins: winnerBy21(p),
+    }));
+}
+
+export function renderReview(rows: readonly ReviewRow[]): string[] {
+    if (rows.length === 0) return ['  no candidate pairs — nothing to review'];
+    return ['  pair | verdict | which wins by 2.1', ...rows.map((r) => `  ${r.pair} | ${r.verdict} | ${r.wins}`)];
+}