@event4u/agent-config 9.1.0 → 9.2.0

package/docs/guidelines/agent-infra/cross-source-consistency-mechanics.md

@@ -0,0 +1,109 @@
+# Cross-Source Consistency — Mechanics
+
+> The discrepancy taxonomy, the scan procedure, the confidence-tiered noise control, worked examples, and the precedence table for the `cross-source-consistency` rule
+
+_Companion to `src/rules/cross-source-consistency.md` (P4 pattern of `road-to-kernel-and-router.md`). The Iron Law, the fire/not-fire scope, and the subordination clauses stay in the rule; this file carries the taxonomy detail, the scan procedure, and the examples._
+
+## The discrepancy taxonomy
+
+| # | Class | Definition | Canonical example |
+|---|---|---|---|
+| a | **text ↔ image** | The ticket/spec text contradicts an attached mockup, screenshot, or diagram. | Text: "show birthdays **today**". Mockup: a birthday from two days ago. |
+| b | **silent-but-needed** | The spec is silent on a behavior that is clearly required for the feature to be correct. | Spec: weekend-shifting only. Clearly also needed: public-holiday shifting — but never specified. |
+| c | **spec ↔ codebase/reality** | The spec contradicts what the code, DB, API, or a real source actually does. | Spec: "the endpoint returns `dueDate`". The DTO has no such field. |
+| d | **intra-ticket** | Acceptance criteria, description, and comments contradict each other. | Description: real-time. AC: "nightly batch is fine." |
+
+Type (a) and (d) are **contradictions between present sources** — the agent
+must not pick one silently. Type (b) is a **scope decision** — the inferred
+behavior may be right, but adding it is a scope expansion the user owns. Type
+(c) routes the *verification* to `source-discovery` (read the real source); this
+rule only owns *surfacing the conflict and asking*.
+
+## The scan procedure
+
+Run this whenever planning, refining, estimating, roadmapping, or implementing
+from a ticket/spec that carries a second source:
+
+1. **Enumerate the sources.** Ticket text, every attachment (mockup / screenshot
+   / diagram), the AC block, description, comments, and — for implementation —
+   the relevant codebase/DB/API surface. If an attachment cannot be read,
+   say so; do not assume it agrees.
+2. **Compare pairwise for type (a), (c), (d).** For each pair, ask: do they state
+   the same thing about the same requirement? A mismatch is a discrepancy.
+3. **Scan for type (b) — silence.** List the behaviors the feature obviously
+   needs but the spec never mentions (weekend/holiday shifts, empty states,
+   error paths, permission edges, pagination, timezone). Each unstated-but-needed
+   behavior is a candidate to surface — not to implement.
+4. **Classify confidence.** High = the sources plainly disagree, or the missing
+   behavior is clearly load-bearing. Low = the "conflict" is a plausible
+   re-reading, or the missing behavior may be intentionally out of scope.
+5. **Decide per the setting** (below), then **batch** every surviving discrepancy
+   into ONE question folded into this turn's single `ask-when-uncertain` prompt.
+
+## Confidence-tiered noise control (`consistency.cross_source`)
+
+The rule fires only under a real trade-off (it must pass the
+`no-cheap-questions` Pre-Send Self-Check). The setting tunes how aggressively:
+
+| Value | High-confidence discrepancy | Low-confidence discrepancy |
+|---|---|---|
+| `on` (default) | Surface + ask before proceeding. | Surface + ask (batched into the same question). |
+| `auto` | Surface + ask. | State as an explicit assumption and proceed (no question). |
+| `off` | No cross-source checking — legacy behavior. | No cross-source checking. |
+
+Batching is the anti-noise mechanism: N discrepancies for one artefact become
+one numbered-options block, never N prompts. Plain vagueness (a single unclear
+source, no second source to compare) is **not** a discrepancy — it stays with
+`ask-when-uncertain` so the two disciplines never double-fire on the same input.
+
+## Worked examples
+
+### Example 1 — text ↔ image (type a)
+
+Ticket: *"The tile shows employees who have their birthday **today**."* Attached
+mockup: a card with a birthday dated **two days ago**.
+
+- Wrong: implement "today" (or implement "recent, like the mockup") and move on.
+  Both are silent guesses on a real contradiction — a violation even if the
+  chosen reading turns out correct.
+- Right: *"The ticket text says 'today' but the mockup shows a birthday from two
+  days ago. Which is authoritative — (1) strictly today, (2) a recent window as
+  the mockup implies, (3) something else?"* Then implement the confirmed reading;
+  `design-fidelity` governs building it 1:1 afterwards.
+
+### Example 2 — silent-but-needed (type b)
+
+Ticket update: *"If a birthday falls on the weekend, show it on the next
+workday."* The spec never mentions public holidays.
+
+- Wrong: also shift birthdays that fall on a public holiday, because it is
+  "obviously" consistent with the weekend rule — a silent scope expansion.
+- Right: *"The spec covers weekend-shifting but is silent on public holidays.
+  Should birthdays on a public holiday also shift to the next workday? (1) yes,
+  same as weekends, (2) no, holidays are out of scope, (3) only regional
+  holidays."* Obvious-to-the-agent ≠ in-scope; `scope-control` owns the
+  expansion permission.
+
+## Precedence & subordination
+
+| Neighbour rule | Relationship |
+|---|---|
+| `ask-when-uncertain` | **Parent ask discipline.** This rule folds its discrepancy into that rule's single question. `ask-when-uncertain` fires on *missing* info; this adds *conflicting present* sources. Never a second question block. |
+| `scope-control` | **Permission authority** for the type-(b) silent-scope-expansion. This rule surfaces the expansion; `scope-control` gates it. |
+| `design-fidelity` | **Fires after** this rule. This rule resolves a text↔image conflict at decision time; `design-fidelity` then enforces build-time 1:1 fidelity to the resolved design. |
+| `source-discovery` / `source-discovery-gate` | **Owns verification** for type (c). This rule surfaces the spec↔code conflict; `source-discovery` provides the evidence procedure. |
+| `no-cheap-questions` | **Floor.** A discrepancy ask must carry a real trade-off; batch, never nag. |
+| `active-remediation` | **Sibling shape.** Its never-silently-ignore ladder is the response model this rule applies to source discrepancies rather than code issues. |
+
+## Failure modes
+
+- **Silent-correct-guess.** Picking the right reading of a contradiction without
+  asking. Correct output, wrong process — still a violation.
+- **Double-firing.** Emitting a discrepancy question AND a separate
+  `ask-when-uncertain` / `improve-before-implement` question about the same
+  underlying uncertainty. Fold into one turn's one question.
+- **Noise creep.** Surfacing plausible re-readings as if they were hard
+  contradictions. Use the confidence tier; `auto` states low-confidence as an
+  assumption instead of asking.
+- **Silent scope expansion.** Implementing an inferred-but-unspecified behavior
+  because it seems obvious. It is a scope decision the user owns.

package/docs/proof.md

@@ -41,7 +41,7 @@ evidence pointer, or `task check-claims` fails the build.
 | The whole layer is compiled into host agents with zero runtime daemon. | qual | `docs/contracts/no-runtime-boundary.md#file-first, no-runtime suite` | ✅ |
 | On a 12-fixture option-decision corpus (3 arms × 2 providers, blind rubric judge claude-opus-4-8, pre-registered hypotheses), famous-figure identity framing added nothing beyond the underlying method text (method 5.04 vs figure 4.88, Δ=0.17, sign-test p=0.607), and provider diversity moved judged quality ~15× more than persona identity (provider Δ=2.58 vs identity Δ=0.17); the whole persona layer lifted only +0.08 over bare prompts. Honest null — persona panel-mode stays CUT, evidence-closed. | quant | `internal/bench/reports/persona-placebo.json#honest-null` | ✅ |
 | On the live end-to-end retrieval benchmark (9 tasks × 3 arms × 3 seeds on claude-haiku, fixture store with keyword-overlapping confusers), the memory retrieval substrate scored precision@5 = 100% (9/9) with 100% poisoned-entry rejection, and the retrieval-on arm passed 27/27 model-scored tasks vs 2/27 with retrieval off and 4/27 with a placebo injection. Known limit stays published: mean tie-set 4.1 means top-k ties break by store order, not relevance (the ADR-116/FTS5 signal). | quant | `internal/bench/reports/second-brain-retrieval.json#retrieval-on` | ✅ |
-| 104 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 105 governed rules. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | On a deterministic multi-session recall corpus, the memory substrate produces a measured, placebo-controlled recall lift — memory-on 27/27 vs no-memory 10/27 and vs equal-byte placebo 9/27 (claude-haiku-4-5, n=9 tasks x 3 seeds, sign test p=0.031 for BOTH pairings). Scoped honestly: this is the context-value upper bound (perfect retrieval on a one-fact-per-task corpus), not retrieval precision under a large store. | quant | `internal/bench/reports/second-brain-delta.json` | ✅ |
 | Removing the perfect-retrieval assumption, the substrate's REAL keyword retrieval recalls the needed decision into the top-5 under keyword-overlapping confusers (precision@5 9/9) and the model disambiguates it from the co-injected confusers — retrieval-on 27/27 vs no-memory 5/27 and vs equal-count placebo 5/27 (claude-haiku-4-5, 9 tasks x 3 seeds, sign test p=0.008 both). Named limit: retrieval RECALLS but does not RANK (mean tie-set 3.3, ties broken by store order, not relevance) — the discrimination gap that motivates the SQLite-FTS5 activation path (ADR-116) at larger scale. | quant | `internal/bench/reports/second-brain-retrieval.json` | ✅ |
 | Every artifact the package ships — source AND the condensed projection that reaches consumers — is machine-scanned in CI for hidden-Unicode, mixed-script-confusable, and instruction-smuggling payloads (the rules-file-backdoor class); a finding blocks the release before `npm publish`, not just the merge. | qual | `.github/workflows/publish-npm.yml#lint_agent_security` | ✅ |
@@ -56,7 +56,7 @@ guidelines, personas) are **generated from source and CI-drift-checked**:
 fails the build on any count-shaped prose mention that drifts from the
 source count — or on two different numbers for the same artefact kind.
 
-We also publish our **debt**: 4 claim(s) are logged as
+We also publish our **debt**: 5 claim(s) are logged as
 `unbacked` inventory in the ledger — not yet bound, and therefore not
 allowed to carry a marker in public prose. Hiding them would be the
 opposite of the point.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "9.1.0",
+    "version": "9.2.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/src/config/agent-settings.template.yml

@@ -518,6 +518,34 @@ design:
   #              autonomy setting, roadmap, or standing instruction lifts it).
   fidelity_mode: strict
 
+# --- Cross-source consistency ---
+#
+# When the agent plans, refines, roadmaps, or implements from multiple
+# sources — ticket text, an attached image / mockup / screenshot, the spec,
+# the codebase — it actively checks them AGAINST each other and STOPS to ask
+# before proceeding on a detected discrepancy, instead of silently guessing
+# (even a correct guess). Consumed by the `cross-source-consistency` rule.
+# Catches: (a) ticket text vs an attached image/mockup, (b) a spec silent on
+# a clearly-needed behavior (weekend/holiday shifting, empty/error states),
+# (c) spec vs the codebase, (d) intra-ticket contradiction (AC vs description).
+#
+# The discipline is deliberately subordinate to `ask-when-uncertain` (it folds
+# a detected discrepancy into the same turn's single question — never a second
+# prompt) and defers to `scope-control` for the permission to expand scope.
+consistency:
+  # on | auto | off  (default: on)
+  #
+  # on   = default. Detect discrepancies across sources and surface ONE
+  #        numbered-options question before proceeding. A silent guess on a
+  #        real contradiction is a rule violation, even when the guess is
+  #        correct. An inferred-but-unspecified behavior is a scope expansion:
+  #        ask before implementing it.
+  # auto = detect + surface only HIGH-confidence contradictions; low-confidence
+  #        ones are stated as an assumption and proceed (noise control).
+  # off  = no cross-source checking (legacy: the agent may proceed on its own
+  #        reading of whichever source it happened to read).
+  cross_source: "on"
+
 code_style:
   # minimal | full  (default: minimal)
   #
@@ -604,6 +632,20 @@ subagents:
   # Integer, default 3. Set to 1 to serialize. Hard cap enforced by runtime.
   max_parallel: 3
 
+  # Opt-in adversarial-verification-council (subagent-orchestration Mode 9,
+  # ADR-122):  off | ask | on
+  #
+  # off (default) = never runs. ask = offer it on an explicit high-risk change.
+  # on = auto-run on high-risk changes (security, tenant, migration, public API).
+  #
+  # A panel of distinct-model skeptics red-teams a real, already-verified change
+  # for defect FINDING coverage (not a go/no-go decision) and returns an advisory
+  # findings-by-severity verdict. ADVISORY ONLY — it NEVER auto-gates the change
+  # (Hard Floor). The registered claim + high-risk tier use cross-vendor skeptics.
+  # Stays default-off until the adversarial-council-finding-coverage claim is
+  # backed by the two-stage residual-detection benchmark (prove-or-drop).
+  adversarial_council: off
+
 # --- Git worktrees ---
 #
 # Controls how the `using-git-worktrees` skill and `subagent-orchestration`

package/src/scripts/_lib/adversarial_council_gate.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Adversarial council prove-or-drop gate — coverage (Phase 4).
+ *
+ * Locks the pre-registered dual-threshold semantics: BOTH relative (>=+25%) and
+ * absolute (>=+8pp) residual-recall lift, AND panel FP not worse than baseline
+ * within noise. Guards the base-rate-compression case the council flagged
+ * (high single-judge baseline → relative easy but absolute must still clear).
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+    ABSOLUTE_LIFT_THRESHOLD_PP,
+    RELATIVE_LIFT_THRESHOLD,
+    evaluateCouncilBench,
+} from './adversarial_council_gate.js';
+
+const CLEAN_FP = { single_judge_fp_rate: 0.05, panel_fp_rate: 0.05, fp_noise_margin: 0.03 };
+
+describe('evaluateCouncilBench', () => {
+    it('exposes the locked thresholds', () => {
+        expect(RELATIVE_LIFT_THRESHOLD).toBe(0.25);
+        expect(ABSOLUTE_LIFT_THRESHOLD_PP).toBe(0.08);
+    });
+
+    it('backs the claim when both recall thresholds and FP pass', () => {
+        const v = evaluateCouncilBench({
+            single_judge_residual_recall: 0.5,
+            panel_residual_recall: 0.65, // +30% relative, +15pp absolute
+            ...CLEAN_FP,
+        });
+        expect(v.relative_pass).toBe(true);
+        expect(v.absolute_pass).toBe(true);
+        expect(v.fp_pass).toBe(true);
+        expect(v.verdict).toBe('backed');
+    });
+
+    it('honest-null when relative passes but absolute fails (base-rate compression)', () => {
+        // baseline 0.90; +0.05 → relative 5.5% (fails) — the high-baseline trap.
+        const v = evaluateCouncilBench({
+            single_judge_residual_recall: 0.9,
+            panel_residual_recall: 0.95,
+            ...CLEAN_FP,
+        });
+        expect(v.verdict).toBe('honest-null');
+        expect(v.reasons.join(' ')).toMatch(/relative lift/);
+    });
+
+    it('honest-null when absolute passes but relative fails', () => {
+        // baseline 0.6; +0.09 absolute (passes) but +15% relative (fails at 25%).
+        const v = evaluateCouncilBench({
+            single_judge_residual_recall: 0.6,
+            panel_residual_recall: 0.69,
+            ...CLEAN_FP,
+        });
+        expect(v.absolute_pass).toBe(true);
+        expect(v.relative_pass).toBe(false);
+        expect(v.verdict).toBe('honest-null');
+    });
+
+    it('honest-null when recall passes but FP regresses beyond noise', () => {
+        const v = evaluateCouncilBench({
+            single_judge_residual_recall: 0.5,
+            panel_residual_recall: 0.7,
+            single_judge_fp_rate: 0.05,
+            panel_fp_rate: 0.12, // +7pp > 3pp noise
+            fp_noise_margin: 0.03,
+        });
+        expect(v.relative_pass).toBe(true);
+        expect(v.absolute_pass).toBe(true);
+        expect(v.fp_pass).toBe(false);
+        expect(v.verdict).toBe('honest-null');
+    });
+
+    it('allows a within-noise FP increase', () => {
+        const v = evaluateCouncilBench({
+            single_judge_residual_recall: 0.5,
+            panel_residual_recall: 0.7,
+            single_judge_fp_rate: 0.05,
+            panel_fp_rate: 0.075, // +2.5pp <= 3pp noise
+            fp_noise_margin: 0.03,
+        });
+        expect(v.fp_pass).toBe(true);
+        expect(v.verdict).toBe('backed');
+    });
+
+    it('handles a zero baseline (infinite relative lift, absolute still gates)', () => {
+        const backed = evaluateCouncilBench({
+            single_judge_residual_recall: 0,
+            panel_residual_recall: 0.2,
+            ...CLEAN_FP,
+        });
+        expect(backed.relative_lift).toBe(Infinity);
+        expect(backed.verdict).toBe('backed'); // +20pp absolute clears
+
+        const nullAbs = evaluateCouncilBench({
+            single_judge_residual_recall: 0,
+            panel_residual_recall: 0.05, // +5pp < 8pp
+            ...CLEAN_FP,
+        });
+        expect(nullAbs.verdict).toBe('honest-null');
+    });
+
+    it('rejects out-of-range inputs', () => {
+        expect(() =>
+            evaluateCouncilBench({
+                single_judge_residual_recall: 1.5,
+                panel_residual_recall: 0.5,
+                ...CLEAN_FP,
+            }),
+        ).toThrow(/\[0,1\]/);
+    });
+});

package/src/scripts/_lib/adversarial_council_gate.ts

@@ -0,0 +1,98 @@
+/**
+ * Adversarial verification council — prove-or-drop gate (Phase 4).
+ *
+ * Pure, deterministic. Encodes the pre-registered `adversarial-council-finding-
+ * coverage` claim (docs/CLAIMS.md, ADR-122) as a machine-checkable verdict on
+ * the two-stage residual-detection benchmark: does a cross-vendor skeptic panel
+ * out-find a single strong judge on the RESIDUAL defect pool (defects that
+ * survived stage 1), at a false-positive rate no worse than baseline on the
+ * controversial-but-correct control?
+ *
+ * Dual threshold, both required, to guard against base-rate compression when the
+ * single-judge residual recall is already high (the council's Round-1 critique):
+ *   (a) relative residual-recall lift >= +25%
+ *   (b) absolute residual-recall lift >= +8 percentage points
+ *   AND panel FP not worse than single-judge FP within the noise margin.
+ *
+ * Thresholds are LOCKED at pre-registration (roadmap Phase 0). This module is the
+ * "countable logic in TS with tests" the anti-lesson mandates — never LLM-computed.
+ *
+ * Design: docs/design/adversarial-council-eval.md
+ */
+
+/** Relative residual-recall lift threshold (fraction). */
+export const RELATIVE_LIFT_THRESHOLD = 0.25;
+/** Absolute residual-recall lift threshold (percentage points, as a fraction). */
+export const ABSOLUTE_LIFT_THRESHOLD_PP = 0.08;
+
+export interface CouncilBenchInputs {
+    /** Single-judge recall on the judge-passed residual pool (0..1). */
+    single_judge_residual_recall: number;
+    /** Panel recall on the same judge-passed residual pool (0..1). */
+    panel_residual_recall: number;
+    /** Single-judge false-positive rate on the controversial-clean control (0..1). */
+    single_judge_fp_rate: number;
+    /** Panel false-positive rate on the same control (0..1). */
+    panel_fp_rate: number;
+    /** Noise margin within which a higher panel FP still counts as "not worse" (0..1). */
+    fp_noise_margin: number;
+}
+
+export type CouncilVerdict = 'backed' | 'honest-null';
+
+export interface CouncilBenchVerdict {
+    relative_lift: number;
+    absolute_lift_pp: number;
+    relative_pass: boolean;
+    absolute_pass: boolean;
+    fp_pass: boolean;
+    verdict: CouncilVerdict;
+    reasons: string[];
+}
+
+function assertUnit(name: string, v: number): void {
+    if (typeof v !== 'number' || Number.isNaN(v) || v < 0 || v > 1) {
+        throw new Error(`${name} must be a number in [0,1], got ${JSON.stringify(v)}`);
+    }
+}
+
+/**
+ * Evaluate the pre-registered dual-threshold gate. Returns `backed` only when
+ * BOTH recall thresholds AND the FP constraint pass; otherwise `honest-null`
+ * (which keeps the surface default-off permanently, like recursive-verification).
+ */
+export function evaluateCouncilBench(inputs: CouncilBenchInputs): CouncilBenchVerdict {
+    assertUnit('single_judge_residual_recall', inputs.single_judge_residual_recall);
+    assertUnit('panel_residual_recall', inputs.panel_residual_recall);
+    assertUnit('single_judge_fp_rate', inputs.single_judge_fp_rate);
+    assertUnit('panel_fp_rate', inputs.panel_fp_rate);
+    assertUnit('fp_noise_margin', inputs.fp_noise_margin);
+
+    const single = inputs.single_judge_residual_recall;
+    const panel = inputs.panel_residual_recall;
+    const absolute_lift_pp = panel - single;
+    // A zero baseline makes the ratio undefined — any positive panel recall is an
+    // infinite relative lift; no lift is zero. This never masks the absolute gate.
+    const relative_lift = single === 0 ? (panel > 0 ? Infinity : 0) : absolute_lift_pp / single;
+
+    const relative_pass = relative_lift >= RELATIVE_LIFT_THRESHOLD;
+    const absolute_pass = absolute_lift_pp >= ABSOLUTE_LIFT_THRESHOLD_PP;
+    const fp_pass = inputs.panel_fp_rate <= inputs.single_judge_fp_rate + inputs.fp_noise_margin;
+
+    const reasons: string[] = [];
+    if (!relative_pass) {
+        reasons.push(`relative lift ${(relative_lift * 100).toFixed(1)}% < ${RELATIVE_LIFT_THRESHOLD * 100}%`);
+    }
+    if (!absolute_pass) {
+        reasons.push(`absolute lift ${(absolute_lift_pp * 100).toFixed(1)}pp < ${ABSOLUTE_LIFT_THRESHOLD_PP * 100}pp`);
+    }
+    if (!fp_pass) {
+        reasons.push(
+            `panel FP ${(inputs.panel_fp_rate * 100).toFixed(1)}% > baseline ${(inputs.single_judge_fp_rate * 100).toFixed(1)}% + noise ${(inputs.fp_noise_margin * 100).toFixed(1)}%`,
+        );
+    }
+
+    const verdict: CouncilVerdict = relative_pass && absolute_pass && fp_pass ? 'backed' : 'honest-null';
+    if (verdict === 'backed') reasons.push('all thresholds met');
+    return { relative_lift, absolute_lift_pp, relative_pass, absolute_pass, fp_pass, verdict, reasons };
+}

package/src/scripts/_lib/adversarial_reconcile.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Adversarial reconciliation core — deterministic coverage (Phase 1).
+ *
+ * Covers: dedup across skeptics, severity aggregation (strict-er wins),
+ * quorum-confidence math, false-positive suppression (demote, never drop),
+ * empty panel, single-finding, unanimous vs split, malformed-input rejection,
+ * and hand-rolled validation of every output against
+ * adversarial-findings.json (no jsonschema runtime dep — mirrors
+ * test_subagent_status_schema.py's approach).
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+    type AdversarialFindings,
+    type RawFinding,
+    type SkepticReturn,
+    assertValidRawFinding,
+    findingKey,
+    isSuppressedFalsePositive,
+    reconcileFindings,
+    severityQuorum,
+} from './adversarial_reconcile.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+    HERE,
+    '../../skills/subagent-orchestration/schemas/adversarial-findings.json',
+);
+
+const SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
+const CONFIDENCES = new Set(['high', 'medium', 'low']);
+
+/** Minimal hand-rolled validator matching the schema's required keys + enums. */
+function validateEnvelope(env: AdversarialFindings): void {
+    expect(env).toHaveProperty('panel');
+    expect(env.panel.models.length).toBeGreaterThanOrEqual(1);
+    expect(env.panel.skeptic_count).toBe(env.panel.models.length);
+    for (const bucket of [env.findings, env.false_positives_suppressed]) {
+        for (const f of bucket) {
+            for (const val of [f.id, f.severity, f.category, f.location, f.description, f.confidence]) {
+                expect(typeof val).toBe('string');
+                expect(val.length).toBeGreaterThan(0);
+            }
+            expect(SEVERITIES.has(f.severity)).toBe(true);
+            expect(CONFIDENCES.has(f.confidence)).toBe(true);
+            expect(Array.isArray(f.raised_by)).toBe(true);
+            expect(f.raised_by.length).toBeGreaterThanOrEqual(1);
+            expect(Array.isArray(f.refuted_by)).toBe(true);
+        }
+    }
+}
+
+function raw(over: Partial<RawFinding> = {}): RawFinding {
+    return {
+        severity: 'high',
+        category: 'correctness',
+        location: 'src/a.ts:42',
+        description: 'off-by-one in loop bound',
+        ...over,
+    };
+}
+
+describe('adversarial-findings.json schema', () => {
+    it('parses and declares the finding contract', () => {
+        const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
+        expect(schema.required).toEqual(['panel', 'findings', 'false_positives_suppressed']);
+        expect(schema.additionalProperties).toBe(false);
+        expect(schema.definitions.finding.required).toContain('raised_by');
+        expect(schema.definitions.finding.required).toContain('confidence');
+        expect(schema.definitions.finding.properties.severity.enum).toEqual([
+            'critical',
+            'high',
+            'medium',
+            'low',
+        ]);
+    });
+});
+
+describe('findingKey', () => {
+    it('is location + normalized category', () => {
+        expect(findingKey({ location: 'src/a.ts:42 ', category: 'Security' })).toBe(
+            'src/a.ts:42::security',
+        );
+    });
+});
+
+describe('assertValidRawFinding', () => {
+    it('rejects a bad severity', () => {
+        expect(() => assertValidRawFinding(raw({ severity: 'blocker' as never }))).toThrow(/severity/);
+    });
+    it('rejects an empty location', () => {
+        expect(() => assertValidRawFinding(raw({ location: '  ' }))).toThrow(/location/);
+    });
+    it('accepts a well-formed finding', () => {
+        expect(() => assertValidRawFinding(raw())).not.toThrow();
+    });
+});
+
+describe('severityQuorum', () => {
+    it('high when corroborated by a panel quorum', () => {
+        expect(severityQuorum(2, 0, 2)).toBe('high');
+        expect(severityQuorum(2, 0, 3)).toBe('high');
+    });
+    it('medium when corroborated below quorum', () => {
+        expect(severityQuorum(2, 0, 5)).toBe('medium');
+    });
+    it('medium for a lone raiser on a solo panel', () => {
+        expect(severityQuorum(1, 0, 1)).toBe('medium');
+    });
+    it('low for a single raiser on a multi-skeptic panel', () => {
+        expect(severityQuorum(1, 0, 3)).toBe('low');
+    });
+});
+
+describe('isSuppressedFalsePositive', () => {
+    it('suppresses a lone finding refuted by a strict majority of the rest', () => {
+        expect(isSuppressedFalsePositive(1, 1, 2)).toBe(true); // rest=1, refuted=1 > 0.5
+        expect(isSuppressedFalsePositive(1, 2, 3)).toBe(true); // rest=2, refuted=2 > 1
+    });
+    it('does not suppress when refutation is not a strict majority', () => {
+        expect(isSuppressedFalsePositive(1, 1, 3)).toBe(false); // rest=2, refuted=1 == 1, not > 1
+    });
+    it('never suppresses a corroborated finding', () => {
+        expect(isSuppressedFalsePositive(2, 5, 7)).toBe(false);
+    });
+});
+
+describe('reconcileFindings', () => {
+    it('handles an empty panel', () => {
+        const env = reconcileFindings([]);
+        expect(env.panel).toEqual({ models: [], skeptic_count: 0 });
+        expect(env.findings).toEqual([]);
+        expect(env.false_positives_suppressed).toEqual([]);
+    });
+
+    it('dedups the same defect across skeptics and records both as raisers', () => {
+        const env = reconcileFindings([
+            { model: 'anthropic:x', findings: [raw()] },
+            { model: 'openai:y', findings: [raw({ description: 'the loop reads one past the end of the array' })] },
+        ]);
+        expect(env.findings).toHaveLength(1);
+        expect(env.findings[0]!.raised_by.sort()).toEqual(['anthropic:x', 'openai:y']);
+        expect(env.findings[0]!.confidence).toBe('high'); // 2/2 = quorum
+        // Longest description wins.
+        expect(env.findings[0]!.description).toMatch(/one past the end/);
+        validateEnvelope(env);
+    });
+
+    it('aggregates severity strict-er-wins', () => {
+        const env = reconcileFindings([
+            { model: 'a', findings: [raw({ severity: 'medium' })] },
+            { model: 'b', findings: [raw({ severity: 'critical' })] },
+        ]);
+        expect(env.findings[0]!.severity).toBe('critical');
+    });
+
+    it('takes the union of distinct findings and orders by severity then key', () => {
+        const env = reconcileFindings([
+            { model: 'a', findings: [raw({ location: 'src/a.ts:1', severity: 'low', category: 'quality' })] },
+            { model: 'b', findings: [raw({ location: 'src/b.ts:9', severity: 'critical', category: 'security' })] },
+        ]);
+        expect(env.findings.map((f) => f.severity)).toEqual(['critical', 'low']);
+        expect(env.findings.map((f) => f.id)).toEqual(['avc-001', 'avc-002']);
+        validateEnvelope(env);
+    });
+
+    it('demotes a lone finding refuted by a majority into false_positives_suppressed', () => {
+        const loneKey = findingKey({ location: 'src/c.ts:5', category: 'security' });
+        const env = reconcileFindings([
+            { model: 'a', findings: [raw({ location: 'src/c.ts:5', category: 'security' })] },
+            { model: 'b', findings: [], refutes: [loneKey] },
+        ]);
+        expect(env.findings).toHaveLength(0);
+        expect(env.false_positives_suppressed).toHaveLength(1);
+        expect(env.false_positives_suppressed[0]!.refuted_by).toEqual(['b']);
+        validateEnvelope(env);
+    });
+
+    it('is deterministic across input order', () => {
+        const a: SkepticReturn = { model: 'a', findings: [raw({ location: 'src/z.ts:1', severity: 'high' })] };
+        const b: SkepticReturn = { model: 'b', findings: [raw({ location: 'src/a.ts:1', severity: 'high', category: 'security' })] };
+        const one = reconcileFindings([a, b]);
+        const two = reconcileFindings([b, a]);
+        expect(one.findings.map((f) => f.location)).toEqual(two.findings.map((f) => f.location));
+        expect(one.findings.map((f) => f.id)).toEqual(two.findings.map((f) => f.id));
+    });
+
+    it('rejects malformed findings from a skeptic', () => {
+        expect(() =>
+            reconcileFindings([{ model: 'a', findings: [raw({ severity: 'nope' as never })] }]),
+        ).toThrow(/severity/);
+    });
+});