@event4u/agent-config 16.3.0 → 16.5.0

package/src/install/installThinLayer.ts

@@ -57,13 +57,14 @@ import * as os from 'node:os';
 import {
     buildHostLimitRows,
     loadHostInstructionLimits,
+    ownershipLine,
     readLayer,
     renderHostLimitRows,
+    resolveLayerOwnership,
     type LayerReading,
 } from '../scripts/_lib/installed_layer.js';
 import { GLOBAL_RULE_DIRS, globalRuleLayerPath } from './globalRuleLayers.js';
 import { manifest_path } from '../scripts/_lib/installed_tools.js';
-import { NO_RECORDED_HASHES, readRecordedHashes } from './recordedOwnership.js';
 import {
     absoluteBodyLinkPrefix,
     build_thin,
@@ -271,6 +272,38 @@ export function describeThinInstalledLayer(res: ThinInstalledLayerResult): strin
     return out;
 }
 
+/**
+ * What {@link installReceiptBudgetLines} may be told about ownership evidence.
+ *
+ * Declared ABOVE that function's own doc block on purpose. It first sat between
+ * the doc block and the function, which silently re-attached the function's
+ * contract — "step 1.4's at install", "global layers only, deliberately",
+ * "never throws" — to this interface, and interfaces erase on emit, so the
+ * contract disappeared from the shipped JS and from IDE hover on the function.
+ */
+export interface InstallReceiptOwnershipOptions {
+    /**
+     * The installed-tools manifest. `undefined` uses `manifest_path(packageRoot)`;
+     * `null` reads none.
+     *
+     * Overridable so a test can be hermetic. That lock file is gitignored, so
+     * it is absent in CI and present on any checkout where a project-scoped
+     * install has run — a case reading it implicitly turns green-in-CI,
+     * red-on-a-maintainer's-machine, for a reason unrelated to what it tests.
+     */
+    readonly manifestPath?: string | null | undefined;
+    /** `deployed-files.json`. `undefined` reads the user-global default; `null` reads none. */
+    readonly inventoryPath?: string | null | undefined;
+    /**
+     * Anchor → anchor-relative paths this run just wrote.
+     *
+     * The installer holds exactly this set at the moment it prints the receipt,
+     * and `record_deploy` has not run yet, so on a FIRST install it is the only
+     * evidence the files are ours.
+     */
+    readonly thisDeploy?: ReadonlyMap<string, Iterable<string>> | null | undefined;
+}
+
 /**
  * The install receipt's instruction-budget block — step 1.4's "at install".
  *
@@ -289,15 +322,47 @@ export function describeThinInstalledLayer(res: ThinInstalledLayerResult): strin
  * Never throws. A receipt that cannot be measured is silent rather than fatal —
  * the deploy it describes has already happened correctly.
  */
-export function installReceiptBudgetLines(packageRoot: string, home: string = os.homedir()): string[] {
+export function installReceiptBudgetLines(
+    packageRoot: string,
+    home: string = os.homedir(),
+    opts: InstallReceiptOwnershipOptions = {},
+): string[] {
     try {
-        const recorded = (() => {
-            try {
-                return readRecordedHashes(manifest_path(packageRoot), packageRoot);
-            } catch {
-                return NO_RECORDED_HASHES;
-            }
-        })();
+        // ONE RESOLVER, SHARED WITH THE REPORT — step 1.2. This used to read
+        // `manifest_path(packageRoot)`, the PACKAGE root's lock, which on a
+        // global-only install names a file no global install ever writes; the
+        // receipt then printed `0 package-owned` for a layer it had itself just
+        // deployed. `resolveLayerOwnership` falls through to the inventory, and
+        // `thisDeploy` covers the first install, where the receipt prints
+        // before `record_deploy` has written anything.
+        const { recorded, sources } = resolveLayerOwnership({
+            manifestPath: opts.manifestPath === undefined ? manifest_path(packageRoot) : opts.manifestPath,
+            projectRoot: packageRoot,
+            // The same home the layers below are read from — the inventory's
+            // anchor is tilde-relative, so the two must agree or the receipt
+            // measures one install and claims ownership of another.
+            home,
+            // THE RECEIPT IS THE "ASKING PROCESS" CASE, so it names no home
+            // here. It runs inside the install that WROTE the inventory, and
+            // that writer resolves the path through `inventory_path()` —
+            // honouring `AGENT_CONFIG_DEPLOY_INVENTORY`, which names a FILE
+            // rather than a home, and `EVENT4U_CONFIG_HOME`. Passing `home`
+            // would take `defaultInventoryPath`'s stated-home branch and read
+            // `<home>/.event4u/...`, a file nothing wrote under either
+            // override, and the inventory evidence would be silently lost.
+            // UNDEFINED IS LEFT UNDEFINED so `resolveLayerOwnership` applies
+            // `defaultInventoryPath(home)` — the SAME resolution the report
+            // uses. Hardcoding `inventory_path()` here made the two readers
+            // step 1.2 exists to reconcile disagree for any home that is not
+            // the asking process's: the receipt read one install's inventory
+            // and then expanded its tilde-relative anchors against the OTHER
+            // home, which is the cross-home misattribution two docstrings in
+            // the resolver forbid. `defaultInventoryPath` already returns
+            // `inventory_path()` when the stated home IS this process's, which
+            // is the case that motivated the hardcode.
+            inventoryPath: opts.inventoryPath,
+            thisDeploy: opts.thisDeploy,
+        });
         const layers: LayerReading[] = [];
         for (const host of Object.keys(GLOBAL_RULE_DIRS).sort()) {
             const dir = globalRuleLayerPath(host, home);
@@ -305,7 +370,8 @@ export function installReceiptBudgetLines(packageRoot: string, home: string = os
             layers.push(readLayer(host, 'global', dir, recorded));
         }
         const rows = buildHostLimitRows(layers, loadHostInstructionLimits());
-        return rows.length === 0 ? [] : renderHostLimitRows(rows).map((l) => `  ${l}`);
+        if (rows.length === 0) return [];
+        return [`  ${ownershipLine(sources)}`, ...renderHostLimitRows(rows).map((l) => `  ${l}`)];
     } catch {
         return [];
     }

package/src/install/installedRuleLinks.ts

@@ -152,32 +152,90 @@ const EMPTY_COUNTS = (): Record<LinkVerdict, number> => ({
 });
 
 /**
- * Audit every link in every rule the plan installs.
+ * Every `.md` file under `dir`, as POSIX paths relative to it, sorted.
  *
- * `packageRoot` is the package checkout the installer copies FROM; the rule
- * bodies are read from the plan's own rules source, so the audit cannot drift
- * from what is shipped.
+ * Recursive because skills (`<name>/SKILL.md`), commands (`<cluster>/x.md`) and
+ * contexts nest.
  */
-export function auditInstalledRuleLinks(plan: DeployPlan, packageRoot: string): LinkAuditReport {
+function markdownFilesUnder(dir: string): string[] {
+    const out: string[] = [];
+    const walk = (rel: string): void => {
+        for (const e of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+            const child = rel === '' ? e.name : `${rel}/${e.name}`;
+            if (e.isDirectory()) walk(child);
+            else if (e.name.endsWith('.md')) out.push(child);
+        }
+    };
+    walk('');
+    return out.sort();
+}
+
+/**
+ * Does this link point into a tree no install ever carries — `docs/`, which
+ * holds the ADRs?
+ *
+ * Decided from where the file sits in the PACKAGE (`dist/agent-src/<kind>/…`),
+ * not from where the install puts it: an author linking `docs/` meant the
+ * repository, whatever the host does. Two shapes count — a target landing under
+ * the top-level `docs/`, and a target naming a `docs/` segment or an ADR file
+ * that resolves to nothing in the package (an author writing `../docs/x` from
+ * a rule meant the repository's `docs/`, not a sibling that does not exist).
+ * `guidelines/docs/` is a real projected directory, which is why existence
+ * decides the second shape rather than the word alone.
+ */
+export function isNonProjectedTarget(packageRoot: string, packageFromDir: string, target: string): boolean {
+    const bare = withoutAnchor(target);
+    const resolved = path.posix.normalize(path.posix.join(packageFromDir, bare));
+    if (resolved === 'docs' || resolved.startsWith('docs/')) return true;
+    if (!/(^|\/)(docs\/|ADR-\d)/.test(bare)) return false;
+    return resolved.startsWith('..') || !fs.existsSync(path.join(packageRoot, resolved));
+}
+
+/** A per-kind audit: the deployable reading, and the non-projected row apart. */
+export type KindLinkReport = LinkAuditReport & { non_projected: LinkAudit[] };
+
+/**
+ * Audit every link in every file of ONE installed kind.
+ *
+ * `kindSource` is the package directory the plan copies (`dist/agent-src/skills`).
+ * A file nested at `<rel>/x.md` is installed at `<dest>/<rel>/x.md`, so its links
+ * resolve from that directory — through the same {@link auditLink} the rule
+ * audit uses, because a second resolver would be the drift this count exists to
+ * catch.
+ *
+ * Returns null when the plan does not install the kind at all: "not installed"
+ * is a different answer from "installed with zero links".
+ */
+export function auditInstalledKindLinks(
+    plan: DeployPlan,
+    packageRoot: string,
+    kindSource: string,
+): KindLinkReport | null {
+    let dest: string | undefined;
+    for (const [d, source] of plan) if (source === kindSource) dest = d;
+    if (dest === undefined) return null;
+
     const audits: LinkAudit[] = [];
-    for (const [dest, source] of plan) {
-        if (!source.endsWith('/rules')) continue;
-        const dir = path.join(packageRoot, source);
-        if (!fs.existsSync(dir)) continue;
-        const files = fs
-            .readdirSync(dir, { withFileTypes: true })
-            .filter((e) => !e.isDirectory() && e.name.endsWith('.md'))
-            .map((e) => e.name)
-            .sort();
-        for (const file of files) {
-            const rule = file.replace(/\.md$/, '');
+    const nonProjected: LinkAudit[] = [];
+    const dir = path.join(packageRoot, kindSource);
+    if (fs.existsSync(dir)) {
+        for (const file of markdownFilesUnder(dir)) {
+            const relDir = path.posix.dirname(file);
+            const installedDir = relDir === '.' ? dest : dest === '' ? relDir : `${dest}/${relDir}`;
+            const packageDir = relDir === '.' ? kindSource : `${kindSource}/${relDir}`;
+            const id = file.replace(/\.md$/, '');
             const body = fs.readFileSync(path.join(dir, file), 'utf8');
             for (const target of relativeLinkTargets(body)) {
-                audits.push(auditLink(rule, target, dest, plan, packageRoot));
+                const audit = auditLink(id, target, installedDir, plan, packageRoot);
+                if (isNonProjectedTarget(packageRoot, packageDir, target)) nonProjected.push(audit);
+                else audits.push(audit);
             }
         }
     }
+    return { ...summarise(audits), non_projected: nonProjected };
+}
 
+function summarise(audits: LinkAudit[]): LinkAuditReport {
     const counts = EMPTY_COUNTS();
     for (const a of audits) counts[a.verdict] += 1;
 
@@ -196,6 +254,36 @@ export function auditInstalledRuleLinks(plan: DeployPlan, packageRoot: string):
     return { audits, counts, by_directory };
 }
 
+/**
+ * Audit every link in every rule the plan installs.
+ *
+ * `packageRoot` is the package checkout the installer copies FROM; the rule
+ * bodies are read from the plan's own rules source, so the audit cannot drift
+ * from what is shipped. Non-projected targets stay IN this reading: its
+ * recorded figures predate the per-kind split.
+ */
+export function auditInstalledRuleLinks(plan: DeployPlan, packageRoot: string): LinkAuditReport {
+    const audits: LinkAudit[] = [];
+    for (const [dest, source] of plan) {
+        if (!source.endsWith('/rules')) continue;
+        const dir = path.join(packageRoot, source);
+        if (!fs.existsSync(dir)) continue;
+        const files = fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => !e.isDirectory() && e.name.endsWith('.md'))
+            .map((e) => e.name)
+            .sort();
+        for (const file of files) {
+            const rule = file.replace(/\.md$/, '');
+            const body = fs.readFileSync(path.join(dir, file), 'utf8');
+            for (const target of relativeLinkTargets(body)) {
+                audits.push(auditLink(rule, target, dest, plan, packageRoot));
+            }
+        }
+    }
+    return summarise(audits);
+}
+
 /**
  * Standing-text cost of the rewrite option, in characters.
  *

package/src/scripts/_cli/cmd_analyze_session.ts

@@ -12,10 +12,10 @@
  *        - `changes`  — files touched (array of {kind, stack, file, summary}).
  *        - `outcomes` — directive → "success" / "blocked" / … .
  *        - `halts`    — array of recorded halts.
- *   2. `agents/runtime/state/context-hygiene.json` — fields read:
+ *   2. the context-hygiene hook's state file (`STATE_FILE`, imported from
+ *      `context_hygiene_hook.ts` rather than spelled here — two independent
+ *      spellings of this path drifted apart before). Fields read:
  *        - `tool_calls`           (int)
- *        - `consecutive_same_tool`(int)
- *        - `loop_detected`        (bool)
  *
  * There is NO general token/cost data source in this package (only
  * video-specific telemetry), so the report deliberately does NOT report
@@ -33,18 +33,16 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { ProjectRootError, resolve_project_root } from '../_lib/agent_settings.js';
+import { STATE_FILE as HYGIENE_STATE_FILE } from '../context_hygiene_hook.js';
 import { StateLoadError, load_state } from './explain_last/state_loader.js';
 
 type Dict = Record<string, unknown>;
 
 const _HERE = fileURLToPath(import.meta.url);
 
-const CONTEXT_HYGIENE_RELATIVE = path.join(
-    'agents',
-    'runtime',
-    'state',
-    'context-hygiene.json',
-);
+// Imported from the hook rather than spelled here — the hook is the writer,
+// so it is the single source of truth for the path it writes to.
+const CONTEXT_HYGIENE_RELATIVE = HYGIENE_STATE_FILE;
 
 /** Python `raise SystemExit(code)` analogue — propagates an explicit code. */
 class SystemExitError extends Error {
@@ -196,11 +194,7 @@ export function render_report(state: Dict, hygiene: Dict | null): string {
         lines.push('_Context-hygiene snapshot not available._');
     } else {
         const toolCalls = intOrUnknown(hygiene['tool_calls']);
-        const consecutive = intOrUnknown(hygiene['consecutive_same_tool']);
-        const loop = hygiene['loop_detected'] === true;
         lines.push(`- Tool calls: ${toolCalls}`);
-        lines.push(`- Consecutive same-tool calls: ${consecutive}`);
-        lines.push(`- Loop detected: ${loop ? 'yes' : 'no'}`);
     }
     lines.push('');
 
@@ -253,8 +247,8 @@ Sources read:
     · changes  — files touched
     · outcomes — per-directive success / blocked
     · halts    — recorded halts
-  agents/runtime/state/context-hygiene.json
-    · tool_calls · consecutive_same_tool · loop_detected
+  agents/state/context-hygiene.json
+    · tool_calls
 
 Token/cost is NOT reported — this package has no per-session token
 source (only video-specific telemetry).

package/src/scripts/_cli/cmd_conformance.ts

@@ -42,6 +42,7 @@ import { atomicAppendLine } from '../../install/atomic.js';
 import { readRecentEntries } from '../../install/txlog.js';
 import { detectToolPresence } from '../../install/detect.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
+import { THIN_ENTRY_MARKER } from '../_lib/thin_rules.js';
 import { routeTargetPathsPosix } from '../router_target_paths.mjs';
 import { buildFunnel, render as renderFunnel } from '../report_conformance_funnel.js';
 import {
@@ -74,8 +75,18 @@ export const CONFORMANCE_CHECK_IDS = [
     'host-manifest',
 ] as const;
 
-/** Marker emitted by `project_thin_rules.thin_entry()` — the thin-stub signature. */
-export const THIN_STUB_MARKER = 'Routed rule — load the body on trigger-match';
+/**
+ * Marker emitted by `project_thin_rules.thin_entry()` — the thin-stub signature.
+ *
+ * RE-EXPORTED, NEVER RE-SPELLED — step 2.1 of
+ * `road-to-a-thinned-layer-measured-in-one-unit`. This was its own literal, a
+ * substring of the writer's constant without the blockquote prefix and the full
+ * stop, which is exactly the drift `THIN_ENTRY_MARKER`'s own docstring warns
+ * about: shorten the writer and this detector keeps matching the old sentence,
+ * silently, in the direction where a stub it fails to recognise reads as a
+ * complete rule body. The name stays so existing callers are unchanged.
+ */
+export const THIN_STUB_MARKER = THIN_ENTRY_MARKER;
 
 /**
  * Rendering symbols for this verb's rows — doctor's table plus `unknown`.

package/src/scripts/_cli/cmd_doctor.ts

@@ -114,7 +114,7 @@ import {
     resolve_project_root,
     type TraceRecord,
 } from '../_lib/agent_settings.js';
-import { executionJson, forgeProtectionJsonFor } from './doctor_execution.js';
+import { executionJson, forgeDepsFor, forgeProtectionJsonFor, type ForgeDeps } from './doctor_execution.js';
 import { checkOfflineReadiness, trafficEnvironmentJson } from './doctor_network_posture.js';
 import * as ai_council_clients from '../ai_council/clients.js';
 import * as ai_council_config from '../ai_council/config.js';
@@ -2945,7 +2945,7 @@ function _run_no_manifest(
         checks.some((c) => c['id'] === opts.check && c['status'] === 'skipped');
 
     if (opts.json) {
-        _emit_json(project_root, [], [], [], [], checks, origin);
+        _emit_json(project_root, [], [], [], [], checks, origin, forgeDepsFor(opts));
     } else if (opts.check === null) {
         print(`  📍  project_root: ${project_root} (origin: ${origin})`);
         if (bridge_present) {
@@ -2998,7 +2998,7 @@ function _emit_json(
     foreign: Dict[],
     tag_drift: Dict[],
     checks: Dict[] | null = null,
-    origin: string | null = null,
+    origin: string | null = null, forge: ForgeDeps = {},
 ): void {
     const payload: Dict = {
         project_root: String(project_root),
@@ -3009,7 +3009,7 @@ function _emit_json(
     };
     if (origin !== null) payload['project_root_origin'] = origin;
     payload['execution'] = executionJson(() => iter_setting_overrides({ cwd: project_root }));
-    payload['forge_protection'] = forgeProtectionJsonFor(String(project_root)); // 3.2 · AC-5
+    payload['forge_protection'] = forgeProtectionJsonFor(String(project_root), forge); // 3.2 · AC-5
     payload['traffic_environment'] = trafficEnvironmentJson(process.env);
     if (checks !== null) {
         payload['checks'] = checks;
@@ -3066,7 +3066,7 @@ interface Options {
     ci: boolean;
     strict: boolean; strict_level: string; // see `_doctor_strict.ts`
     check: string | null;
-    trace_root: boolean;
+    trace_root: boolean; no_forge: boolean; online: boolean; // opt-out / opt-in; `forgeDepsFor`
     context: boolean;
     anatomy: boolean;
     repair: string | null;
@@ -3080,14 +3080,14 @@ const PROG = 'agent-config doctor';
 const USAGE =
     `usage: ${PROG} [-h] [--project PROJECT] [--json] [--ci] [--check ID]\n` +
     STRICT_USAGE +
-    '                           [--trace-root] [--context] [--anatomy]\n' +
-    '                           [--repair ID]\n';
+    '                           [--trace-root] [--context] [--anatomy] [--no-forge]\n' +
+    '                           [--online] [--repair ID]\n';
 
 const _STORE_TRUE_FLAGS: Record<string, keyof Options> = {
     '--json': 'json',
     '--ci': 'ci',
     ...STRICT_STORE_TRUE,
-    '--trace-root': 'trace_root',
+    '--trace-root': 'trace_root', '--no-forge': 'no_forge', '--offline': 'no_forge', '--online': 'online',
     '--context': 'context',
     '--anatomy': 'anatomy',
 };
@@ -3112,7 +3112,7 @@ function _parse(argv: string[]): Options {
         ci: false,
         ...STRICT_DEFAULTS,
         check: null,
-        trace_root: false,
+        trace_root: false, no_forge: false, online: false,
         context: false,
         anatomy: false,
         repair: null,
@@ -3390,7 +3390,7 @@ function main(argv: string[] | null = null): number {
     const fail_check = checks.some((c) => c['status'] === 'fail');
 
     if (opts.json) {
-        _emit_json(project_root, missing, modified, foreign, tag_drift, checks, origin);
+        _emit_json(project_root, missing, modified, foreign, tag_drift, checks, origin, forgeDepsFor(opts));
     } else {
         if (opts.check === null) {
             print(`  📍  project_root: ${project_root} (origin: ${origin})`);

package/src/scripts/_cli/cmd_doctor_neighbours.ts

@@ -16,8 +16,14 @@
  * the hook path, and `neighbour-overlap.json`, the cross-root pairs keyed by the
  * census digest. Nothing outside that directory is touched, and a failed write
  * is not a failed census.
+ *
+ * `--contradictions` (step 2.2) writes neither cache. It forms candidate pairs
+ * and hands them to ONE council seat, whose question and transcript land under
+ * gitignored `agents/runtime/council/`; with no council configured it prints
+ * `n/a` and asks nobody.
  */
 
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -32,6 +38,22 @@ import {
     type NeighbourCensus,
 } from '../_lib/neighbour_census.js';
 import { scanNeighbourBody, writeScanCache } from '../_lib/neighbour_scan.js';
+import {
+    RANK_NEIGHBOUR_ALWAYS_ON,
+    RANK_NEIGHBOUR_SKILL,
+    RANK_PROJECT,
+    collisionPair,
+    extractInstructions,
+    modalityPairs,
+    parseVerdicts,
+    renderReview,
+    reviewRows,
+    seatPrompt,
+    type CandidatePair,
+    type InstructionSource,
+    type ReviewRow,
+} from '../_lib/neighbour_contradictions.js';
+import { resolveAvailability } from '../council_availability_hook.js';
 import { resolvePackageRoot } from '../_lib/package_root.js';
 import {
     OVERLAP_THRESHOLD,
@@ -144,6 +166,109 @@ export function runCensus(
     return full;
 }
 
+/**
+ * Candidate pairs for `--contradictions` (step 2.2), READ-ONLY.
+ *
+ * Calls `census()` directly rather than `runCensus()`, because the latter
+ * writes the scan and overlap caches and this mode promises to change no file.
+ * The shape scan still runs, and a refused neighbour body contributes no line.
+ */
+export function contradictionCandidates(
+    projectRoot: string,
+    packageRoot: string,
+    homeRoot?: string,
+): CandidatePair[] {
+    const ours = ourSkillNames(packageRoot);
+    const c = census(projectRoot, {
+        gatedEvents: gatedEvents(packageRoot),
+        templatesRoot: path.join(packageRoot, 'src', 'agent-src', 'templates'),
+        ourSkillNames: ours,
+        packageRoot,
+        scan: (p) => scanNeighbourBody(p).kind,
+        ...(homeRoot === undefined ? {} : { homeRoot }),
+    });
+    const sources: InstructionSource[] = [];
+    for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+        const file = path.join(projectRoot, name);
+        if (fs.existsSync(file)) sources.push({ label: name, file, rank: RANK_PROJECT });
+    }
+    for (const r of c.rule_files) {
+        if (scanNeighbourBody(r.source).kind === null) {
+            sources.push({ label: r.id, file: r.source, rank: RANK_NEIGHBOUR_ALWAYS_ON });
+        }
+    }
+    for (const s of c.skills) {
+        if (s.unscanned === null) sources.push({ label: s.qualified, file: s.source, rank: RANK_NEIGHBOUR_SKILL });
+    }
+    const pairs = modalityPairs(sources.flatMap((src) => extractInstructions(src)));
+    for (const s of c.skills) {
+        const name = s.qualified.split(':').slice(1).join(':') || s.qualified;
+        if (ours.has(name)) pairs.push(collisionPair(s.qualified, name));
+    }
+    return pairs;
+}
+
+/** One council seat, run through the council CLI; `null` when it cannot answer. */
+export type Seat = (prompt: string) => string | null;
+
+function councilSeat(projectRoot: string): Seat {
+    return (prompt) => {
+        const stamp = new Date().toISOString().replace(/[:.]/gu, '-');
+        const q = path.join(projectRoot, 'agents', 'runtime', 'council', 'questions', `neighbour-contradictions-${stamp}.md`);
+        const out = path.join(projectRoot, 'agents', 'runtime', 'council', 'responses', `neighbour-contradictions-${stamp}.md`);
+        try {
+            fs.mkdirSync(path.dirname(q), { recursive: true });
+            fs.writeFileSync(q, prompt, 'utf-8');
+            const args = ['council', 'run', q, '--single', '--prompt-mode', 'analysis', '--output', out, '--confirm', '--invocation', 'user_explicit'];
+            const res = spawnSync('agent-config', args, { cwd: projectRoot, encoding: 'utf-8' });
+            if (res.status !== 0) return null;
+            const doc = JSON.parse(fs.readFileSync(out, 'utf-8')) as { responses?: { text?: string }[] };
+            return doc.responses?.map((r) => r.text ?? '').join('\n') ?? null;
+        } catch {
+            return null;
+        }
+    };
+}
+
+/**
+ * `--contradictions`: a verdict table, or `n/a` when no council is configured.
+ *
+ * Report-only — it edits nothing and gates nothing. The council transcript the
+ * seat writes lands under gitignored `agents/runtime/council/`; no tracked file
+ * changes.
+ */
+export function runContradictions(
+    projectRoot: string,
+    packageRoot: string,
+    opts: { homeRoot?: string; seat?: Seat; configured?: boolean } = {},
+): { lines: string[]; rows: ReviewRow[] | null } {
+    const configured =
+        opts.configured ?? resolveAvailability(projectRoot, process.env)?.configured ?? false;
+    const pairs = contradictionCandidates(projectRoot, packageRoot, opts.homeRoot);
+    if (!configured) {
+        return {
+            lines: [`  contradictions: n/a — no council configured (${pairs.length} candidate pair(s) formed, none reviewed)`],
+            rows: null,
+        };
+    }
+    if (pairs.length === 0) return { lines: renderReview([]), rows: [] };
+    let rubric = '';
+    for (const rel of [['dist', 'agent-src', 'rules'], ['src', 'rules']]) {
+        try {
+            rubric = fs.readFileSync(path.join(packageRoot, ...rel, 'neighbour-precedence.md'), 'utf-8');
+            break;
+        } catch {
+            // Try the next layout.
+        }
+    }
+    const answer = (opts.seat ?? councilSeat(projectRoot))(seatPrompt(pairs, rubric));
+    if (answer === null) {
+        return { lines: [`  contradictions: n/a — the council seat did not answer (${pairs.length} candidate pair(s) formed)`], rows: null };
+    }
+    const rows = reviewRows(pairs, parseVerdicts(answer, pairs.length));
+    return { lines: renderReview(rows), rows };
+}
+
 /** The one line the full `doctor` run prints, linking to this verb. */
 export function summaryLine(c: NeighbourCensus): string {
     const counts = [
@@ -218,10 +343,12 @@ export function renderText(c: NeighbourCensus): string[] {
 
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     let json = false;
+    let contradictions = false;
     let root = process.cwd();
     let home: string | undefined;
     for (let i = 0; i < argv.length; i += 1) {
         if (argv[i] === '--json') json = true;
+        else if (argv[i] === '--contradictions') contradictions = true;
         else if (argv[i] === '--project') {
             root = argv[i + 1] ?? root;
             i += 1;
@@ -237,6 +364,12 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
             return 2;
         }
     }
+    if (contradictions) {
+        const r = runContradictions(path.resolve(root), resolvePackageRoot(import.meta.url), home === undefined ? {} : { homeRoot: home });
+        if (json) process.stdout.write(`${JSON.stringify({ contradictions: r.rows })}\n`);
+        else for (const line of r.lines) process.stdout.write(`${line}\n`);
+        return 0;
+    }
     const c = runCensus(path.resolve(root), resolvePackageRoot(import.meta.url), home);
     if (json) {
         // Compact, not pretty-printed: this is the machine contract, and the