@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/ai_council/disagreement_signal.ts

@@ -0,0 +1,338 @@
+/**
+ * The zero-cost structural disagreement signal.
+ *
+ * `road-to-inbox-harvest-2026-08-e-council-topology-evidence` Phase 6.1: six
+ * components — stance divergence, finding overlap, contradiction count,
+ * confidence spread, rank uncertainty, novelty / self-similarity — computed from
+ * outputs the run **already paid for**.
+ *
+ * ## The contract is the absence of a call
+ *
+ * The step's verify is not "the numbers look right"; it is *"no extra model call
+ * is issued; call count is unchanged"*. So this module is a pure function of
+ * retained output: it imports no client, opens no socket, spawns no process, and
+ * reads no file. `argument_exhaustion.ts:40-42` already states that property as
+ * 6.1's contract while consuming it; this is the module it was pointing at.
+ *
+ * Purity is enforced structurally rather than by discipline: every input arrives
+ * as an argument, so there is no path from here to a provider even if a future
+ * edit wanted one. A test asserts the import surface directly, because a
+ * regression here is silent — an added import spends money without changing a
+ * single number this module returns.
+ *
+ * ## Nothing is re-derived
+ *
+ * Each component reads the verdict the tree already computes rather than a second
+ * opinion about the same bytes:
+ *
+ * - stance divergence and confidence spread read `StanceTallyResult`
+ *   (`stance_tally.ts:146`) — never a re-parse of the stance lines. Two parses
+ *   are two chances to disagree.
+ * - contradiction count and rank uncertainty read the `ConsensusMetadata` map
+ *   `aggregate_scores` (`consensus.ts:157`) produced — self-scores already
+ *   dropped, strengths already rounded.
+ * - finding overlap and self-similarity reuse `jaccardSimilarity`
+ *   (`_lib/text_similarity.ts:33`), the same primitive `debate_gates.ts:40` and
+ *   `recouncil_guard.ts:29` consume.
+ *
+ * ## An unavailable component is a result, never a zero
+ *
+ * A component whose evidence the run does not carry returns
+ * `{ available: false, reason }`. It does **not** return `0`, and the reason is
+ * an enumerated value rather than prose. A fabricated zero is worse than a
+ * declared gap in both directions this signal can be read: `0` divergence reads
+ * as unanimity and `0` contradictions reads as agreement, so silently defaulting
+ * would make an unmeasured round look like the most convergent one — the same
+ * inversion `argument_exhaustion.ts:91-95` guards against for an empty council.
+ *
+ * ## No composite score, deliberately
+ *
+ * The six are returned separately and are **not** combined. Two of them —
+ * `findingOverlap` and `selfSimilarity` — rise with AGREEMENT while the other
+ * four rise with DISAGREEMENT, so a consumer summing them would be adding
+ * opposing axes; and weighting them against each other needs numbers no
+ * measurement in this tree supplies. Phase 8.4 asks for a score that is
+ * "deterministic and inspectable to start" and Phase 10.3 asks which of finding,
+ * stance, confidence or evidence a call moved — both want the components, not a
+ * scalar that has already discarded which axis moved.
+ *
+ * `revisit-if`: a benchmark arm produces measured weights for a composite. Then
+ * the composite belongs in the consumer that has the measurement, still reading
+ * these components as its inputs.
+ */
+
+import { findMostSimilar, jaccardSimilarity, MERGE_THRESHOLD } from '../_lib/text_similarity.js';
+
+import type { ConsensusMetadata, Finding } from './consensus.js';
+import { CONFIDENCE_FACTOR, type StanceTallyResult } from './stance_tally.js';
+
+/**
+ * The bar at which two members' findings count as the same finding — and it is
+ * REUSED, not chosen. `MERGE_THRESHOLD` was fixed by the 2026-07-05 council
+ * verdict as the point at which two texts are duplicates, long before this
+ * signal existed, which is the same pre-registration argument
+ * `recouncil_guard.ts:50` makes for reusing it there.
+ *
+ * It is a strict bar for prose that says the same thing in different words, so
+ * `findingOverlap` UNDER-estimates agreement. That is the fail-safe direction
+ * here and the reason a stricter-than-ideal number is acceptable rather than
+ * merely tolerated: under-estimating overlap over-estimates disagreement, and
+ * Phase 6's failure mode is stopping deliberation too early, not too late.
+ *
+ * `revisit-if`: two members raise a finding a human calls identical and it
+ * scores below this value. The fix then belongs in `text_similarity.ts` where
+ * every other consumer can see the number move.
+ */
+export const FINDING_MATCH_THRESHOLD = MERGE_THRESHOLD;
+
+/** Why a component carries no value. Enumerated — never free prose. */
+export type SignalGap =
+    /** Stance tallying is off for this run, so there is no tally to read. */
+    | 'no-stance-tally'
+    /** A tally exists and no member backed an option (all abstained or unparsed). */
+    | 'no-parsed-stances'
+    /** Fewer than two confidence observations; a spread needs two points. */
+    | 'too-few-confidence-observations'
+    /** Fewer than two sources carried a finding, so there is no pair to compare. */
+    | 'too-few-sourced-findings'
+    /** No finding was scored by anyone, so no contradiction was observable. */
+    | 'no-scored-findings'
+    /** Fewer than two scored findings; a ranking needs two positions. */
+    | 'too-few-ranked-findings'
+    /** No member had a non-empty prior round to be compared against. */
+    | 'no-prior-round';
+
+/**
+ * One component. `basis` is the observation count the value rests on, so a
+ * consumer can tell a 0 measured over 40 pairs from a 0 measured over one — the
+ * distinction a bare number destroys, and the reason a degenerate-but-real
+ * measurement is reported rather than suppressed.
+ */
+export type SignalComponent =
+    | { readonly available: true; readonly value: number; readonly basis: number }
+    | { readonly available: false; readonly reason: SignalGap };
+
+/** Per present member: this round's text, and its own prior round's. */
+export interface MemberRound {
+    readonly member: string;
+    readonly current: string;
+    /** `null` on round 1 — there is no prior round, which is not an empty one. */
+    readonly prior: string | null;
+}
+
+export interface DisagreementInputs {
+    /** The ONE tally of the round (`tallyFromResponses`), or `null` when off. */
+    readonly stance: StanceTallyResult | null;
+    /** Findings as already extracted, each carrying its authoring source. */
+    readonly findings: readonly Finding[];
+    /** The ONE `aggregate_scores` map, keyed by finding id. */
+    readonly consensus: ReadonlyMap<string, ConsensusMetadata>;
+    /** Present members with their current and prior round texts. */
+    readonly memberRounds: readonly MemberRound[];
+}
+
+export interface DisagreementSignal {
+    /**
+     * 0..1, rising with disagreement. `1 − topOptionWeight / backedWeight`:
+     * 0 when every backer chose one option.
+     */
+    readonly stanceDivergence: SignalComponent;
+    /**
+     * 0..1, rising with AGREEMENT. Mean symmetric share of one source's findings
+     * that another source also raised.
+     */
+    readonly findingOverlap: SignalComponent;
+    /** A count ≥ 0, rising with disagreement: scored `agree: false` votes. */
+    readonly contradictionCount: SignalComponent;
+    /** 0..1, rising with disagreement: normalised range of backer confidences. */
+    readonly confidenceSpread: SignalComponent;
+    /** 0..1, rising with disagreement: share of adjacent ranked pairs that tie. */
+    readonly rankUncertainty: SignalComponent;
+    /**
+     * 0..1, rising with AGREEMENT (and with exhaustion): mean similarity of each
+     * member's round to its own prior round.
+     */
+    readonly selfSimilarity: SignalComponent;
+    /** How many of the six carry a value. 0..6. */
+    readonly availableCount: number;
+}
+
+const gap = (reason: SignalGap): SignalComponent => ({ available: false, reason });
+const ok = (value: number, basis: number): SignalComponent => ({ available: true, value, basis });
+
+/**
+ * Spread among the options members actually BACKED.
+ *
+ * The denominator is the summed option weight, deliberately not the tally's own
+ * `w_total`: `w_total` counts abstainers and unparsed responses (see the
+ * refusal-preservation invariant at `stance_tally.ts:160-176`), and dividing by
+ * it would make a council where half abstained look MORE divergent than one
+ * where half disagreed. Abstention and unparsed responses are already surfaced
+ * separately by the tally; conflating them into divergence here would double-count
+ * them as a position.
+ */
+function stanceDivergence(stance: StanceTallyResult | null): SignalComponent {
+    if (stance === null) return gap('no-stance-tally');
+    const backedWeight = stance.options.reduce((acc, o) => acc + o.weight, 0);
+    const top = stance.options[0];
+    if (top === undefined || backedWeight <= 0) return gap('no-parsed-stances');
+    const backers = stance.options.reduce((acc, o) => acc + o.backers.length, 0);
+    return ok(1 - top.weight / backedWeight, backers);
+}
+
+/**
+ * Normalised range of the confidence tiers the backers declared.
+ *
+ * Only BACKERS are observable: `tally_stances` counts an abstention and drops
+ * its confidence (`stance_tally.ts:182-185`), so an abstainer's declared
+ * confidence is not in the tally and is not reconstructed here — re-parsing the
+ * reply to recover it would fork the one parse this module refuses to duplicate.
+ * The scope is therefore "spread among members who took a position", which is
+ * stated rather than implied.
+ *
+ * The denominator comes from `CONFIDENCE_FACTOR` rather than a literal, so a
+ * change to the tier table moves this number with it instead of forking it.
+ */
+function confidenceSpread(stance: StanceTallyResult | null): SignalComponent {
+    if (stance === null) return gap('no-stance-tally');
+    const factors = stance.options.flatMap((o) => o.backers.map((b) => CONFIDENCE_FACTOR[b.confidence]));
+    if (factors.length < 2) return gap('too-few-confidence-observations');
+    const span = CONFIDENCE_FACTOR.high - CONFIDENCE_FACTOR.low;
+    return ok((Math.max(...factors) - Math.min(...factors)) / span, factors.length);
+}
+
+/**
+ * How much of what one source raised, another source raised too.
+ *
+ * Symmetric per pair, because the one-directional share is a different question
+ * for each side when the two sources produced different numbers of findings: a
+ * source with one finding matched inside a source with twenty scores 1.0 in one
+ * direction and 0.05 in the other, and neither alone describes the pair.
+ */
+function findingOverlap(findings: readonly Finding[]): SignalComponent {
+    const bySource = new Map<string, Finding[]>();
+    for (const f of findings) {
+        const bucket = bySource.get(f.source);
+        if (bucket === undefined) bySource.set(f.source, [f]);
+        else bucket.push(f);
+    }
+    const sources = [...bySource.values()];
+    if (sources.length < 2) return gap('too-few-sourced-findings');
+
+    /** Share of `from`'s findings with a match at or above the threshold in `to`. */
+    const matchedShare = (from: readonly Finding[], to: readonly Finding[]): number => {
+        if (from.length === 0) return 0;
+        const candidates = to.map((f) => ({ id: f.id, text: f.text }));
+        let matched = 0;
+        for (const f of from) {
+            const best = findMostSimilar(f.text, candidates);
+            if (best !== null && best.score >= FINDING_MATCH_THRESHOLD) matched += 1;
+        }
+        return matched / from.length;
+    };
+
+    let total = 0;
+    let pairs = 0;
+    for (let i = 0; i < sources.length; i += 1) {
+        for (let j = i + 1; j < sources.length; j += 1) {
+            const a = sources[i] as Finding[];
+            const b = sources[j] as Finding[];
+            total += (matchedShare(a, b) + matchedShare(b, a)) / 2;
+            pairs += 1;
+        }
+    }
+    return ok(total / pairs, pairs);
+}
+
+/**
+ * Scored findings only — an entry with no scorer is not a zero-contradiction
+ * finding, it is an unmeasured one.
+ *
+ * `aggregate_scores` writes an entry for EVERY finding, including ones nobody
+ * scored (`consensus.ts:179-194` sets `dissent_count: 0`). Summing the map
+ * wholesale would therefore report a confident `0` for a round where no scoring
+ * happened at all, which is the fabricated zero this module exists not to emit.
+ */
+function scoredEntries(consensus: ReadonlyMap<string, ConsensusMetadata>): ConsensusMetadata[] {
+    return [...consensus.values()].filter((m) => m.scorers.length > 0);
+}
+
+function contradictionCount(consensus: ReadonlyMap<string, ConsensusMetadata>): SignalComponent {
+    const scored = scoredEntries(consensus);
+    if (scored.length === 0) return gap('no-scored-findings');
+    return ok(
+        scored.reduce((acc, m) => acc + m.dissent_count, 0),
+        scored.length,
+    );
+}
+
+/**
+ * How much of the finding ranking the record cannot resolve.
+ *
+ * The ranking is by `consensus_strength` descending (`consensus.ts:272-274`), and
+ * two findings whose strengths are EQUAL have an order that comes from input
+ * position rather than from evidence. So the measure is the share of adjacent
+ * pairs that tie: 0 when every neighbour is separated, 1 when the whole order is
+ * arbitrary.
+ *
+ * Equality is used rather than a tolerance on purpose — no new tunable. The
+ * strengths arrive already rounded to three places by `pyRound`
+ * (`consensus.ts:211`), so the record's own resolution is what decides a tie and
+ * this module adds no threshold of its own to argue about.
+ *
+ * Unscored findings are excluded for the same reason as above: they all sit at
+ * strength 0 and would report as a near-total tie, which measures the absence of
+ * scoring rather than the uncertainty of a ranking.
+ */
+function rankUncertainty(consensus: ReadonlyMap<string, ConsensusMetadata>): SignalComponent {
+    const strengths = scoredEntries(consensus)
+        .map((m) => m.consensus_strength)
+        .sort((a, b) => b - a);
+    if (strengths.length < 2) return gap('too-few-ranked-findings');
+    let ties = 0;
+    for (let i = 1; i < strengths.length; i += 1) {
+        if (strengths[i] === strengths[i - 1]) ties += 1;
+    }
+    return ok(ties / (strengths.length - 1), strengths.length);
+}
+
+/**
+ * Each member against its own prior round — the novelty axis, as a scalar.
+ *
+ * The boolean gate over the same primitive stays in `debate_gates.ts:32`
+ * (`is_near_duplicate`) and is not duplicated here; what this adds is the
+ * underlying magnitude, which a stop predicate does not need and an
+ * information-gain estimate does.
+ *
+ * A member with an empty current or prior text contributes nothing rather than a
+ * value. That mirrors `is_near_duplicate`'s own guard (`debate_gates.ts:37-39`)
+ * and it matters arithmetically: `jaccardSimilarity` defines two empty strings as
+ * identical (1.0, `text_similarity.ts:36`), so an errored member would otherwise
+ * enter the mean as maximal self-repetition.
+ */
+function selfSimilarity(memberRounds: readonly MemberRound[]): SignalComponent {
+    const scores: number[] = [];
+    for (const r of memberRounds) {
+        if (r.prior === null) continue;
+        if (r.prior.trim().length === 0 || r.current.trim().length === 0) continue;
+        scores.push(jaccardSimilarity(r.prior, r.current));
+    }
+    if (scores.length === 0) return gap('no-prior-round');
+    return ok(scores.reduce((acc, s) => acc + s, 0) / scores.length, scores.length);
+}
+
+/** Compute all six components. Pure: no I/O, no client, no model call. */
+export function computeDisagreementSignal(x: DisagreementInputs): DisagreementSignal {
+    const components = {
+        stanceDivergence: stanceDivergence(x.stance),
+        findingOverlap: findingOverlap(x.findings),
+        contradictionCount: contradictionCount(x.consensus),
+        confidenceSpread: confidenceSpread(x.stance),
+        rankUncertainty: rankUncertainty(x.consensus),
+        selfSimilarity: selfSimilarity(x.memberRounds),
+    };
+    return {
+        ...components,
+        availableCount: Object.values(components).filter((c) => c.available).length,
+    };
+}

package/src/scripts/ai_council/inline_findings.ts

@@ -0,0 +1,340 @@
+// Phase 1B — inline findings, the whole concern in one module.
+//
+// The consensus round's pass 1 asks every member a SECOND time, in a separate
+// paid call, to restate its own analysis as a JSON findings array. Phase 1B of
+// `road-to-inbox-harvest-2026-08-e-council-topology-evidence` asks for that
+// array in the FIRST reply instead, and keeps the extraction call as the
+// repair path.
+//
+// It lives here rather than spread across `orchestrator.ts`, `consensus.ts` and
+// `council_cli.ts` for a reason the source-size budget made concrete: all three
+// are far past the 1500-line ceiling, so a new concern added to them is new
+// budget excess with nowhere to go. Concentrating it also puts the four pieces
+// that have to agree — the contract text's promise, the locator, the harvest
+// and the config predicate — where a reader meets them together.
+import type { ExternalAIClient, CouncilResponse } from './clients.js';
+import type { Finding, FindingsExtraction } from './consensus.js';
+import { _BARE_ARRAY_SRC, _JSON_BLOCK_SRC, parse_findings_outcome } from './consensus.js';
+import { INLINE_FINDINGS_CONTRACT, STANCE_LINE_CONTRACT } from './prompts.js';
+
+/** Python `str.strip()` parity, as everywhere else in this package. */
+const _strip = (s: string): string => s.replace(/^\s+|\s+$/g, '');
+
+/**
+ * Phase 1B — the deliberation reply split into argument and findings block.
+ *
+ * `deliberation_text` is what every downstream consumer should see: peer
+ * review, chairman synthesis, and the rendered artifact evaluate the member's
+ * REASONING, and a schema block restating selected conclusions is scaffolding,
+ * not argument. Leaving it in amplifies a concise finding simply because it
+ * appears twice — the AI council's stated reason (2026-08-30, 2 of 2 seats) for
+ * choosing to strip.
+ *
+ * `block` is the exact consumed span. One locator produces both halves, so the
+ * text that is parsed and the text that is removed cannot disagree — the
+ * council's other requirement, and the reason there is no separate
+ * "find and remove a JSON fence" function anywhere in this change.
+ */
+export interface InlineFindingsSplit {
+    /** The reply with the consumed block removed. Equals the input when `found` is false. */
+    readonly deliberation_text: string;
+    /** The consumed span, ready for `parse_findings_outcome`. `''` when `found` is false. */
+    readonly block: string;
+    readonly found: boolean;
+}
+
+/**
+ * Split a full analysis reply at its TRAILING findings block.
+ *
+ * A locator, deliberately not a second parser: `parse_findings_outcome` stays
+ * the only thing that decides whether a candidate IS a findings block, and this
+ * narrows where it looks.
+ *
+ * The narrowing is not cosmetic. `_extract_json_array` returns the FIRST match,
+ * which is correct for an extraction reply (the reply IS the array) and wrong
+ * for an analysis reply, where the prose above may legitimately quote a JSON
+ * array — the analysis lens exists to critique analyser OUTPUT, so a quoted
+ * array is an ordinary thing to find there. First-match would read the quoted
+ * array as the member's findings and never reach the real block.
+ *
+ * `INLINE_FINDINGS_CONTRACT` asks for the block LAST, so LAST is what this
+ * reads. `found: false` when nothing array-shaped is present, which the caller
+ * treats as "no inline block" and repairs with the extraction call — the same
+ * outcome as today, never worse.
+ *
+ * **Precisely: "last FENCED, else last bare" — not "last in the text."** The
+ * two patterns are tried in `_extract_json_array`'s precedence order and the
+ * first pattern that matches at all wins, so a reply carrying a quoted FENCED
+ * array above its own trailing BARE array selects the quoted one. Stated
+ * because the docstring used to claim the simpler rule, which a completion
+ * review of 2026-08-30 found untrue against that ordering; the precedence test
+ * puts the bare array first and so never exercises the collision.
+ *
+ * The consequence is bounded rather than eliminated. `_isOwnFindingsBlock`
+ * below now rejects any array whose items are not all well-formed findings, so
+ * the common shape of a quoted array — evidence rows, log lines, a schema
+ * fragment — no longer wins. What survives is a quoted array of well-formed
+ * findings sitting fenced above the member's own bare one, and that is recorded
+ * as a known residual of 1B.4's gate rather than claimed away.
+ */
+export function split_inline_findings(text: string): InlineFindingsSplit {
+    const none: InlineFindingsSplit = { deliberation_text: text, block: '', found: false };
+    if (!text) {
+        return none;
+    }
+    // Deliberately the same two patterns `_extract_json_array` uses, in the same
+    // precedence order — fenced beats bare — so a block this locator returns is
+    // one that function can also read. Only the match SELECTION differs: last,
+    // not first.
+    for (const src of [_JSON_BLOCK_SRC, _BARE_ARRAY_SRC]) {
+        const re = new RegExp(src, 'gs');
+        let last: RegExpExecArray | null = null;
+        let m: RegExpExecArray | null;
+        while ((m = re.exec(text)) !== null) {
+            last = m;
+            // A zero-length match would spin forever; the patterns cannot produce
+            // one (both require at least `[]`), but the guard costs nothing and a
+            // future pattern edit is exactly when it would matter.
+            if (m.index === re.lastIndex) {
+                re.lastIndex += 1;
+            }
+        }
+        if (last) {
+            const start = last.index;
+            const end = start + last[0].length;
+            return {
+                deliberation_text: `${text.slice(0, start)}${text.slice(end)}`,
+                block: text.slice(start, end),
+                found: true,
+            };
+        }
+    }
+    return none;
+}
+
+/**
+ * How a member's findings were obtained — the RECORDED provenance, wider than
+ * `FindingsParseOutcome`, which describes one parse of one piece of text.
+ *
+ * Typed rather than a bare string because Phase 1B's promotion gate is computed
+ * off exactly these values: an untyped `Map<string, string>` makes the number
+ * that decides the experiment vulnerable to a misspelling no compiler would
+ * catch. The AI council (2026-08-30, 2 of 2 seats) called the pre-existing bare
+ * `'parsed-after-reask'` technical debt rather than a precedent to extend.
+ *
+ * `'parsed'` keeps its shipped meaning — read from the separate extraction
+ * call — and is unambiguous now that `'parsed-inline'` names the other source.
+ * One seat asked for a rename to `'parsed-extraction'`; renaming a value that
+ * is already recorded and compared against is a separate change with its own
+ * migration, and is recorded here as declined-with-a-reason, not overlooked.
+ */
+export type RecordedExtractionOutcome =
+    | 'parsed'
+    | 'empty'
+    | 'parse_failed'
+    | 'parsed-after-reask'
+    | 'parsed-inline';
+
+/**
+ * Phase 1B — harvest the inline findings block out of each deliberation reply.
+ *
+ * Runs BETWEEN the deliberation and every consumer of its text. That placement
+ * is the load-bearing part and it was a defect the AI council caught
+ * (2026-08-30, 2 of 2 seats): peer review and chairman synthesis read the
+ * responses BEFORE the consensus round does, so parsing inside
+ * `run_consensus_scoring` would have left the schema block in the text those
+ * two evaluate — which is precisely the amplification the strip exists to
+ * prevent.
+ *
+ * MUTATES `text` on each response whose block parsed, replacing the consumed
+ * span with a one-line marker. Mutation rather than a parallel clean copy
+ * because two representations of one response means every downstream consumer
+ * has to know which one it holds, and the one that forgets is a silent bug.
+ * `CouncilResponse.text` is already mutated on the stance-repair path, so this
+ * is the established seam rather than a new one.
+ *
+ * The marker is deliberately visible. Stripping without an observable trace is
+ * a silent mutation of the artifact a reader takes for a transcript, and one
+ * seat made an observable marker a condition of its verdict; the other reached
+ * the same concern from the auditability side. ~90 characters replaces ~300 of
+ * JSON, so the scaffolding is gone and the fact of its removal is not.
+ *
+ * Returns the per-member extraction keyed by `provider:model` — the same key
+ * `run_consensus_scoring` records outcomes under. A member whose block did not
+ * parse gets NO entry and its `text` is left exactly as the model wrote it, so
+ * the repair extraction call downstream still sees the raw reply.
+ */
+/**
+ * Is this extraction the member's OWN findings block, or just some JSON it quoted?
+ *
+ * `outcome === 'parsed'` was the whole test until a completion review of
+ * 2026-08-30 showed it decides nothing: `parse_findings_outcome` returns
+ * `'parsed'` for ANY syntactically valid JSON array, and `_collect_findings`
+ * silently skips items missing `id` or `text` while the outcome stays `'parsed'`.
+ * So a reply carrying no findings block at all, but quoting
+ * `[{"file":"src/a.ts","line":42}]` as evidence, was recorded as a successful
+ * inline extraction with zero findings — and its quoted evidence was DELETED
+ * from the text the peer review, the chairman and the artifact read. Worse, the
+ * failure was recorded as a success in the rate the 1B.4 promotion gate reads,
+ * so the gate could not see it.
+ *
+ * Two conjuncts, and both are needed:
+ *
+ * - **it parsed** — unchanged;
+ * - **every item it saw became a finding** — `findings.length === item_count`.
+ *   A findings block from a member following the contract has well-formed items
+ *   throughout. An array where some or all items lack `id`/`text` is something
+ *   else, whatever it parsed to.
+ *
+ * The bare-`[]` answer keeps working: `item_count` is 0 and `findings.length`
+ * is 0, so the conjunction holds and "I found nothing" is still an answer
+ * rather than a re-ask.
+ *
+ * **What this does NOT decide, stated rather than implied away.** A member that
+ * quotes ANOTHER member's well-formed `[{"id":…,"text":…}]` array, as the last
+ * block in its reply, is indistinguishable from its own by shape — and would
+ * still be attributed to the quoting member. Shape cannot separate those; only
+ * provenance could, and the reply carries none. It is narrower than the case
+ * fixed here (the quote must be well-formed AND last AND the member must have
+ * emitted no block of its own), it is visible in the emitted marker, and it is
+ * carried into 1B.4's gate as a known residual rather than counted as a success.
+ */
+function _isOwnFindingsBlock(ex: {
+    outcome: string;
+    findings: readonly unknown[];
+    item_count: number;
+}): boolean {
+    return ex.outcome === 'parsed' && ex.findings.length === ex.item_count;
+}
+
+export function harvest_inline_findings(
+    members: readonly ExternalAIClient[],
+    responses: readonly CouncilResponse[],
+): Map<string, FindingsExtraction> {
+    const out = new Map<string, FindingsExtraction>();
+    const model_by_name = new Map<string, string>();
+    for (const m of members) {
+        model_by_name.set(m.name, m.model);
+    }
+    for (const resp of responses) {
+        const model = model_by_name.get(resp.provider);
+        if (model === undefined || resp.error || !_strip(resp.text)) {
+            continue;
+        }
+        const split = split_inline_findings(resp.text);
+        if (!split.found) {
+            continue;
+        }
+        const source = `${resp.provider}:${model}`;
+        const ex = parse_findings_outcome(split.block, { source });
+        if (!_isOwnFindingsBlock(ex)) {
+            // Not a findings block after all — most likely a JSON array the member
+            // quoted from the artifact. Leave the reply untouched: stripping text
+            // we could not read would remove evidence and buy nothing.
+            continue;
+        }
+        out.set(source, ex);
+        // Retain the reply BEFORE rewriting it — this is the single write of
+        // `CouncilResponse.raw_text`, and the reason that field exists.
+        //
+        // The marker appended below promises "the raw reply is retained in the
+        // session record". Until 2026-08-30 that promise was false, and a
+        // completion review is what caught it: the persisted record is
+        // serialized from these same objects AFTER this harvest runs
+        // (`council_cli._serialise_responses`), so the stripped text was the
+        // only text that survived anywhere, and the auditability condition the
+        // council attached to this feature was unmet.
+        //
+        // `null` stays the honest value for a reply nothing rewrote — it means
+        // "`text` IS the raw reply", never "the raw reply was lost" — which is
+        // also why the serializer omits the key entirely in that case rather
+        // than writing a duplicate of the reply into every session record.
+        resp.raw_text = resp.text;
+        const marker = `_[inline findings block extracted: ${String(ex.findings.length)} item(s); the raw reply is retained in the session record.]_`;
+        resp.text = `${_strip(split.deliberation_text)}\n\n${marker}`;
+    }
+    return out;
+}
+
+
+/**
+ * The FINAL deliberation round's volatile suffix.
+ *
+ * Two opt-in contracts ride it and their ORDER is load-bearing:
+ * `STANCE_LINE_CONTRACT` requires the stance to be the last line of the reply,
+ * so it is appended last and the findings block sits above it. A findings block
+ * appended after the stance line would contradict the instruction the member is
+ * reading, which is the one composition bug this function exists to make
+ * impossible to reintroduce.
+ *
+ * Both off → the caller's suffix is returned unchanged, so the composed default
+ * is byte-identical to a run without either feature.
+ */
+export function composeFinalRoundSuffix(
+    suffix: string,
+    opts: { is_final: boolean; inline_findings: boolean; stance_tally: boolean },
+): string {
+    if (!opts.is_final) {
+        return suffix;
+    }
+    let out = suffix;
+    if (opts.inline_findings) {
+        out = `${out}\n\n---\n\n${INLINE_FINDINGS_CONTRACT}`;
+    }
+    if (opts.stance_tally) {
+        out = `${out}\n\n---\n\n${STANCE_LINE_CONTRACT}`;
+    }
+    return out;
+}
+
+/**
+ * Consume a member's harvested findings, or report that it has none.
+ *
+ * Returns `true` when the caller should SKIP its extraction call. An entry in
+ * the map is always a short-circuit and never a partial one, because
+ * `harvest_inline_findings` records only a member whose block PARSED — a member
+ * with no entry had its reply left raw and takes the shipped extraction path
+ * over the full text.
+ */
+export function takeInlineFindings(
+    inline_extractions: ReadonlyMap<string, FindingsExtraction> | null,
+    source: string,
+    parse_outcomes: Map<string, RecordedExtractionOutcome>,
+    all_findings: Finding[],
+): boolean {
+    const inline = inline_extractions?.get(source);
+    if (inline === undefined) {
+        return false;
+    }
+    parse_outcomes.set(source, 'parsed-inline');
+    all_findings.push(...inline.findings);
+    return true;
+}
+
+/**
+ * Is the inline-findings contract active for this run?
+ *
+ * Read BEFORE the deliberation, because the contract is a prompt change and the
+ * prompt is built first; the harvest reads the same predicate so the two cannot
+ * disagree about whether a member was asked for the block. Three conjuncts, all
+ * required: consensus scoring on, this lens in its lens list, and
+ * `inline_findings` explicitly on. Any missing → `false`, and `false` is a
+ * byte-identical prompt.
+ *
+ * Reads the SYNTHESISED settings dict, not the typed config. That distinction
+ * is not academic: `_lib/council_settings_block.ts` projects the typed config
+ * into this dict, and when it did not carry the key a `true` in the YAML
+ * resolved to `undefined` and the feature was silently off with every unit test
+ * green — found by a live analysis run on 2026-08-30, not by review.
+ */
+export function inlineFindingsActive(
+    ai_cfg: Record<string, unknown>,
+    mode: string,
+): boolean {
+    const cs = (ai_cfg['consensus_scoring'] as Record<string, unknown> | undefined) ?? {};
+    if (cs['enabled'] !== true || cs['inline_findings'] !== true) {
+        return false;
+    }
+    const lenses = (cs['lenses'] as string[] | undefined) ?? ['analysis'];
+    return lenses.includes(mode);
+}