@event4u/agent-config 8.10.0 → 8.12.0

package/src/scripts/ai_council/prompts.ts

@@ -148,6 +148,28 @@ one of several independent reviewers. Round-specific instructions:
 End each round with: a one-line position summary and the single
 piece of evidence that would change your mind.`;
 
+/**
+ * Mandatory closing-line contract appended to the FINAL round when
+ * `ai_council.stance_tally` is enabled (Phase 1). Peers backing the same option
+ * MUST reuse the same label so the deterministic tally can canonicalise it;
+ * `abstain` is allowed. Parsed by `stance_tally.parse_stance_line` — the tally
+ * never infers a stance from the surrounding prose, so an omitted or malformed
+ * line becomes a repair-marker, not a guess.
+ */
+export const STANCE_LINE_CONTRACT = `Close your reply with EXACTLY this line, and nothing after it:
+STANCE: <option-label> | CONFIDENCE: high|med|low | DEALBREAKER: yes|no
+Reuse the SAME <option-label> as any peer backing the same option (match their wording); use \`abstain\` only if you genuinely cannot choose. CONFIDENCE is your certainty in the pick; DEALBREAKER is \`yes\` only if you would block on the alternative.`;
+
+/**
+ * Anti-conformity directive appended to round-2+ debate prompts when
+ * `ai_council.debate_gates` is enabled (road-to-opt-council-deliberation
+ * Phase 3). Counters the round-over-round convergence-to-consensus drift the
+ * `rounds:N` path otherwise invites. Byte-identical across the api / cli /
+ * manual transports (it becomes part of the shared `user_prompt`, which every
+ * client's `ask()` receives verbatim), so no per-transport special-casing.
+ */
+export const ANTI_CONFORMITY_DIRECTIVE = `Anti-conformity rule for this round: defend a position you still believe is correct. Change your position ONLY when a specific, named flaw in it has been identified — and you must name that flaw explicitly to justify the change. Do not soften or converge merely because other reviewers disagree; agreement without a named reason is conformity, not reasoning.`;
+
 const _MODE_TABLE: Record<string, string> = {
     prompt: PROMPT_MODE,
     roadmap: ROADMAP_MODE,
@@ -233,8 +255,15 @@ read it directly from a response.
 A single sentence: which course the host agent should advise the
 user to take, grounded in the strongest converged point.
 
-### Next step
-One concrete next action the user can take in their current turn.`;
+### Kill criteria
+Observable conditions that would falsify this recommendation without
+re-convening the council. Each entry names a threshold or a specific
+event — never a vague "if it goes wrong". Omit only if genuinely none
+exist, and say so explicitly.
+
+### Concrete next step
+Exactly one artefact-producing action the user can take in their
+current turn.`;
 
 export const PR_SYNTHESIS = `Summarise the council with the PR-review shape below.
 
@@ -251,7 +280,17 @@ and the host agent confirms are load-bearing. Maximum five.
 
 ### Recommendation
 APPROVE / REQUEST_CHANGES / REJECT and a single sentence justifying
-the verdict, anchored on the strongest consensus or must-fix line.`;
+the verdict, anchored on the strongest consensus or must-fix line.
+
+### Kill criteria
+Observable conditions that would falsify this verdict without re-convening
+the council (a failing check, a missing test, a regression signal). Each
+entry names a threshold or a specific event. Omit only if genuinely none
+exist, and say so.
+
+### Concrete next step
+Exactly one artefact-producing action the author can take in their current
+turn.`;
 
 export const ANALYSIS_SYNTHESIS = `Summarise the council with the analysis-lens shape below.
 
@@ -270,19 +309,41 @@ metadata shape as Top-10.
 ### Outliers
 Single-reviewer findings the others did not engage with. Keep them
 — they are signal for a future deeper analysis pass — but mark each
-as \`unverified-by-council\`.`;
-
-// Creative lenses — open-ended prose, no template. The renderer keeps
-// the bare "Convergence / Divergence" slot so the host agent can write
-// free-form synthesis.
-const _CREATIVE_PASSTHROUGH = '';
+as \`unverified-by-council\`.
+
+### Kill criteria
+Observable conditions that would falsify the analysis's leading finding
+without re-convening the council. Each entry names a threshold or event.
+Omit only if genuinely none exist, and say so.
+
+### Concrete next step
+Exactly one artefact-producing action the user can take in their current
+turn.`;
+
+// Creative lenses — free-form prose synthesis, then the two required
+// verdict-discipline sections. The body stays open-ended (the host agent
+// writes the Convergence / Divergence prose on its own merits); only the
+// falsifiable close is mandated, so every lens carries Kill criteria +
+// Concrete next step (road-to-opt-council-deliberation Phase 0).
+export const CREATIVE_SYNTHESIS = `Write a free-form convergence / divergence
+synthesis of the council in prose — no fixed section shape for the body.
+Then close with exactly these two sections:
+
+### Kill criteria
+Observable conditions that would falsify the direction you converged on,
+without re-convening the council. Each entry names a threshold or event.
+Omit only if genuinely none exist, and say so.
+
+### Concrete next step
+Exactly one artefact-producing action the user can take in their current
+turn.`;
 
 const _SYNTHESIS_TABLE: Record<string, string> = {
     default: DEFAULT_SYNTHESIS,
     pr: PR_SYNTHESIS,
     analysis: ANALYSIS_SYNTHESIS,
-    design: _CREATIVE_PASSTHROUGH,
-    optimize: _CREATIVE_PASSTHROUGH,
+    design: CREATIVE_SYNTHESIS,
+    optimize: CREATIVE_SYNTHESIS,
 };
 
 // Input modes inherit the `default` decision template. Lens overrides
@@ -371,6 +432,55 @@ export function all_synthesis_modes(): string[] {
     return Object.keys(_SYNTHESIS_TABLE).sort();
 }
 
+/**
+ * Raised when a completed synthesis is missing a required verdict-discipline
+ * section (Kill criteria / Concrete next step) or carries it empty. Named so
+ * the render step fails loudly rather than emitting an unfalsifiable verdict.
+ * Mirrors the `CouncilConfigError` named-error precedent in `config.ts`.
+ */
+export class SynthesisRenderError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'SynthesisRenderError';
+    }
+}
+
+/** The two sections every lens synthesis must close with (Phase 0). */
+export const REQUIRED_SYNTHESIS_SECTIONS = ['Kill criteria', 'Concrete next step'] as const;
+
+/**
+ * Validate a **completed** synthesis (the host- or chairman-authored text that
+ * fills the Convergence / Divergence slot) — not the template prompt. Every
+ * lens must close with a non-empty `### Kill criteria` and `### Concrete next
+ * step`; a missing or placeholder-empty section throws `SynthesisRenderError`
+ * naming the first offender. Called on the synthesis-emit path (the chairman
+ * synthesis in Phase 2, and any future synthesis-record step); safe to call on
+ * decision and creative lenses alike, since both now require the two sections.
+ */
+export function assert_synthesis_sections(text: string): void {
+    const lines = text.split('\n');
+    const isHeading = (l: string): boolean => /^#{2,4}\s/.test(l);
+    for (const section of REQUIRED_SYNTHESIS_SECTIONS) {
+        const headingRe = new RegExp(`^#{2,4}\\s+${section}\\s*$`, 'i');
+        const idx = lines.findIndex((l) => headingRe.test(l));
+        if (idx === -1) {
+            throw new SynthesisRenderError(
+                `synthesis is missing the required "### ${section}" section`,
+            );
+        }
+        let body = '';
+        for (let i = idx + 1; i < lines.length; i++) {
+            if (isHeading(lines[i] as string)) break;
+            body += lines[i];
+        }
+        if (body.trim().length === 0) {
+            throw new SynthesisRenderError(
+                `synthesis "### ${section}" section is empty (placeholder)`,
+            );
+        }
+    }
+}
+
 /**
  * Drop any *whole line* containing a host-agent identity substring.
  *

package/src/scripts/ai_council/replay.ts

@@ -308,6 +308,23 @@ export function render_decision_replay(inputs: DecisionReplayInputs): string {
         }
         lines.push(`**Synthesis verdict**: ${verdict} consensus — ${f.source} sourced.\n`);
     }
+    // Aggregate render lines (Phase 0 fold): one evidence-label line + one
+    // provider-spread line — folded into the trailer, not a new template
+    // section (gap-table FOLD row: evidence labels + provider spread → replay).
+    const evTally: Record<string, number> = { H: 0, M: 0, L: 0 };
+    for (const f of ranked) {
+        const em = _metaGet(inputs.metadata, f.id);
+        const q = (em?.evidence_quality ?? '').toUpperCase().charAt(0);
+        if (q === 'H' || q === 'M' || q === 'L') {
+            evTally[q] = (evTally[q] as number) + 1;
+        }
+    }
+    const providers = new Set(inputs.deliberation.map((r) => r.provider));
+    lines.push(
+        `- **Evidence spread**: ${evTally.H} high · ${evTally.M} medium · ` +
+            `${evTally.L} low (across ${ranked.length} finding(s))\n` +
+            `- **Provider spread**: ${providers.size} distinct provider(s) deliberated\n`,
+    );
     const mode_label = inputs.include_member_arguments ? 'full' : 'redacted (counts only)';
     lines.push(`---\n\n_artefact mode: ${mode_label}_\n`);
     return _pyRStrip(lines.join('\n')) + '\n';

package/src/scripts/ai_council/stance_tally.ts

@@ -0,0 +1,184 @@
+// Option-level stance tally (road-to-opt-council-deliberation Phase 1).
+//
+// `consensus.ts` scores *findings*; nothing here produces an *option-level*
+// verdict for "A or B?" questions. This module engineers Source G's prose
+// tally deterministically: parse each member's mandatory final-round stance
+// line, weight by confidence, and decide consensus vs. an honest split against
+// a ⅔ threshold. Everything countable lands in TS with tests — never inferred
+// from prose (an unparseable line is a repair-marker, not a guess).
+//
+// Default-off behind `ai_council.stance_tally.enabled`; additive — with the key
+// false the council path is byte-identical to today.
+
+/** Confidence tier from a stance line. */
+export type Confidence = 'high' | 'med' | 'low';
+
+/** Contribution weight per confidence tier (Source G's factors). */
+export const CONFIDENCE_FACTOR: Record<Confidence, number> = {
+    high: 1.0,
+    med: 0.75,
+    low: 0.5,
+};
+
+/** Consensus requires an option to clear two-thirds of the base-weight total. */
+export const CONSENSUS_FRACTION = 2 / 3;
+
+/** The canonical label for an explicit abstention. */
+export const ABSTAIN_LABEL = 'abstain';
+
+/** A parsed stance line bound to its member. */
+export interface StanceLine {
+    member: string; // e.g. "openai:gpt-4o"
+    label: string; // canonical (casefolded) key; `abstain` is special
+    display: string; // first-seen original label text (rendering)
+    confidence: Confidence;
+    dealbreaker: boolean;
+}
+
+/** Per-option accumulation across members. */
+export interface OptionTally {
+    label: string; // display label (first-seen casing)
+    weight: number; // sum of confidence factors of backers
+    backers: Array<{ member: string; confidence: Confidence }>;
+    dealbreakers: number;
+}
+
+/** The full tally verdict. `consensus` is null on a split — never a forced winner. */
+export interface StanceTallyResult {
+    options: OptionTally[]; // non-abstain options, weight desc
+    w_total: number; // base-weight denominator (every voting member, abstain included)
+    threshold: number; // CONSENSUS_FRACTION * w_total
+    consensus: OptionTally | null; // the option clearing the threshold, or null
+    split: boolean; // true when no option clears the threshold
+    abstain_count: number;
+    needs_repair: string[]; // members whose stance line was missing/unparseable
+}
+
+// Tolerant of whitespace and case; requires the three explicit fields in order.
+// `medium` is accepted as an alias for `med`.
+const _STANCE_RE =
+    /STANCE:\s*(.+?)\s*\|\s*CONFIDENCE:\s*(high|med(?:ium)?|low)\s*\|\s*DEALBREAKER:\s*(yes|no)/gi;
+
+/**
+ * Parse the member's stance line from their reply text. Returns the LAST stance
+ * line if several appear (the final, most-authoritative one), or `null` when no
+ * well-formed line exists — the caller treats null as a repair-marker and never
+ * infers a stance from the surrounding prose.
+ */
+export function parse_stance_line(text: string): Omit<StanceLine, 'member'> | null {
+    _STANCE_RE.lastIndex = 0;
+    let last: RegExpExecArray | null = null;
+    let m: RegExpExecArray | null;
+    while ((m = _STANCE_RE.exec(text)) !== null) {
+        last = m;
+    }
+    if (last === null) {
+        return null;
+    }
+    const rawLabel = (last[1] ?? '').trim();
+    if (rawLabel.length === 0) {
+        return null;
+    }
+    let conf = (last[2] ?? '').toLowerCase();
+    if (conf === 'medium') {
+        conf = 'med';
+    }
+    return {
+        label: rawLabel.toLowerCase(),
+        display: rawLabel,
+        confidence: conf as Confidence,
+        dealbreaker: (last[3] ?? '').toLowerCase() === 'yes',
+    };
+}
+
+/**
+ * Tally option-level stances across members. Base weight is 1.0 per member;
+ * `W_total` sums those base weights over every member with a parseable stance
+ * (abstentions included — they raise the bar without backing any option). An
+ * option's weight is the sum of its backers' confidence factors. Consensus iff
+ * the leading option's weight ≥ ⅔ × W_total; otherwise a structured split is
+ * returned — never a forced winner, never an auto-added round.
+ */
+export function tally_stances(
+    members: ReadonlyArray<{ member: string; text: string }>,
+): StanceTallyResult {
+    const parsed: StanceLine[] = [];
+    const needs_repair: string[] = [];
+    for (const { member, text } of members) {
+        const p = parse_stance_line(text);
+        if (p === null) {
+            needs_repair.push(member);
+            continue;
+        }
+        parsed.push({ member, ...p });
+    }
+
+    const w_total = parsed.length; // base weight 1.0 each, abstain included
+    const threshold = CONSENSUS_FRACTION * w_total;
+    let abstain_count = 0;
+
+    const byLabel = new Map<string, OptionTally>();
+    for (const p of parsed) {
+        if (p.label === ABSTAIN_LABEL) {
+            abstain_count += 1;
+            continue;
+        }
+        let o = byLabel.get(p.label);
+        if (o === undefined) {
+            o = { label: p.display, weight: 0, backers: [], dealbreakers: 0 };
+            byLabel.set(p.label, o);
+        }
+        o.weight += CONFIDENCE_FACTOR[p.confidence];
+        o.backers.push({ member: p.member, confidence: p.confidence });
+        if (p.dealbreaker) {
+            o.dealbreakers += 1;
+        }
+    }
+
+    const options = [...byLabel.values()].sort(
+        (a, b) => b.weight - a.weight || a.label.localeCompare(b.label),
+    );
+    const top = options[0] ?? null;
+    // Strict-≥ against the threshold; a floating-point epsilon guards the
+    // exact-boundary case (e.g. 2.0 ≥ ⅔×3) from representation drift.
+    const consensus = top !== null && top.weight + 1e-9 >= threshold ? top : null;
+
+    return {
+        options,
+        w_total,
+        threshold,
+        consensus,
+        split: consensus === null,
+        abstain_count,
+        needs_repair,
+    };
+}
+
+/**
+ * Render the **Vote Tally** verdict section: one line per option, the threshold,
+ * and a cleared-or-escalated line. Deterministic — pure projection of the tally.
+ */
+export function render_vote_tally(result: StanceTallyResult): string {
+    const lines: string[] = ['### Vote Tally'];
+    if (result.options.length === 0) {
+        lines.push('- (no option-level stances parsed)');
+    }
+    for (const o of result.options) {
+        const backers = o.backers.map((b) => `${b.member} (${b.confidence})`).join(', ');
+        const db = o.dealbreakers > 0 ? ` · ${o.dealbreakers} dealbreaker(s)` : '';
+        lines.push(`- ${o.label} — ${o.weight.toFixed(2)} (${backers})${db}`);
+    }
+    if (result.abstain_count > 0) {
+        lines.push(`- abstain — ${result.abstain_count} member(s) (raises the bar)`);
+    }
+    lines.push(`Threshold: ⅔ × ${result.w_total} = ${result.threshold.toFixed(2)}`);
+    lines.push(
+        result.consensus !== null
+            ? `Cleared: ${result.consensus.label} (${result.consensus.weight.toFixed(2)})`
+            : 'Escalated: no option cleared the threshold — the split is returned to the user, not forced.',
+    );
+    if (result.needs_repair.length > 0) {
+        lines.push(`Unparsed stance (repair needed): ${result.needs_repair.join(', ')}`);
+    }
+    return lines.join('\n');
+}