@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/agent/council-lesson-proposer.d.ts

@@ -1,21 +1,27 @@
 /**
  * Council → lesson-candidate bridge (closes autonomy loop link [1]).
  *
- * The Fleet Council asks the same goal to N peers and produces a deterministic
- * consensus summary (agreement score + divergences). A council outcome that
- * DIVERGED — or only reached sub-threshold agreement — is a learnable signal:
- * the peers disagreed, so there's something worth capturing. This helper turns
- * such an outcome into a PROPOSED lesson candidate for human review.
+ * The council asks the same goal to N members/peers; a divergence CAN be a
+ * learnable signal — but replaying real transcripts showed the naive version
+ * produced mostly noise: 3 of 4 proposals existed only because the judge DIED
+ * (infrastructure, not knowledge), every candidate was the same
+ * metadata-plus-TODO template ("consensus 8%, X and Y diverged, review which
+ * position was correct") carrying none of the actual positions, and the one
+ * run with a genuinely reusable RESOLVED disagreement was skipped.
  *
- * It deliberately reuses the same "propose → review → approve, no silent write"
- * discipline as the rest of the learning loop: it only ever calls
- * `LessonCandidateQueue.propose()` (never writes `lessons.md`), so the operator
- * still gates what becomes durable procedural memory. Approved lessons are then
- * re-injected into future sagas via `loadRelevantSagaLessons` — the loop closes.
+ * The bridge now extracts SUBSTANCE and scores PEDAGOGICAL VALUE:
+ *  - a candidate carries the opposing positions (VERDICT lines / previews)
+ *    and the resolution (winner, rationale, what the judge re-verified);
+ *  - `scorePedagogicalValue()` rates generalizability, non-contingency,
+ *    testability, substance and real stance divergence — pure TS, no LLM,
+ *    deterministic and auditable (same philosophy as the DHI);
+ *  - infra noise (judge abstained) NEVER proposes — that signal belongs to
+ *    the scoreboard's failure ledger, not to procedural memory;
+ *  - the score is stored in the candidate's provenance so the human reviewer
+ *    can triage the queue by value.
  *
- * Pure and host-agnostic: callers (Cowork's saga-runner today, a CLI/server
- * hook later) pass primitives + an explicit `workDir`, so this never depends on
- * `process.cwd()`.
+ * Same "propose → review → approve, no silent write" discipline as before:
+ * only `LessonCandidateQueue.propose()`, never `lessons.md`.
  *
  * @module agent/council-lesson-proposer
  */
@@ -42,8 +48,69 @@ export interface ProposeFromCouncilResult {
     reason?: string;
     candidate?: LessonCandidate;
 }
+/** One member's position — label (role or model) + its stance (VERDICT line / preview). */
+export interface CouncilPosition {
+    label: string;
+    stance: string;
+}
+/** How the disagreement was settled, when it was. */
+export interface CouncilResolution {
+    winner?: string;
+    rationale?: string;
+    /** What the judge re-verified itself (counts, computations). */
+    verified?: string;
+}
+export interface PedagogicalValue {
+    /** 0..1 — 0 = pure noise, ≥ MIN_PEDAGOGICAL_VALUE = worth a human read. */
+    score: number;
+    factors: {
+        substance: number;
+        resolution: number;
+        testability: number;
+        generalizability: number;
+        stanceDivergence: number;
+    };
+}
+/** Below this, a CLI-council divergence is journal noise, not a lesson. */
+export declare const MIN_PEDAGOGICAL_VALUE = 0.35;
+export interface PedagogicalValueInput {
+    verdictKind: 'judged' | 'abstained';
+    positions: CouncilPosition[];
+    resolution?: CouncilResolution;
+}
+/**
+ * Rate how much a divergence is worth to a human reviewer. Pure and
+ * deterministic (no LLM): the score must be auditable and reproducible.
+ *
+ * Criteria (from the transcript-corpus analysis):
+ *  - substance        — the candidate carries actual opposing positions,
+ *                       not just who diverged;
+ *  - resolution       — a divergence SETTLED by a neutral judge (rationale,
+ *                       self-verified facts) teaches more than an open one;
+ *  - testability      — falsifiable content (WOULD CHANGE MY MIND, suggested
+ *                       fixes, si/alors conditions) makes the lesson checkable;
+ *  - generalizability — normative, principle-level language generalizes;
+ *                       paths/ids/version numbers bind it to one case;
+ *  - stanceDivergence — the positions must actually contradict (different
+ *                       polarity or genuinely different content).
+ * Hard gate: an ABSTAINED verdict is infrastructure noise (dead judge,
+ * timeout) — score 0, never a lesson.
+ */
+export declare function scorePedagogicalValue(input: PedagogicalValueInput): PedagogicalValue;
 /**
  * Propose a review lesson candidate from a council outcome, gated and deduped.
  * Never throws — returns a structured result the caller can log/surface.
  */
 export declare function proposeFromCouncilOutcome(input: CouncilOutcomeInput, workDir: string): ProposeFromCouncilResult;
+export interface CouncilRunLessonInput {
+    task: string;
+    planMode: 'direct' | 'collective';
+    confidence: 'high' | 'medium' | 'low';
+    verdictKind: 'judged' | 'abstained';
+    consensus: CouncilConsensusInput;
+    /** Members' positions (VERDICT lines / first lines) — the lesson's substance. */
+    positions?: CouncilPosition[];
+    /** How the judge settled it, when it did. */
+    resolution?: CouncilResolution;
+}
+export declare function proposeFromCouncilRunResult(input: CouncilRunLessonInput, workDir: string): ProposeFromCouncilResult;

package/dist/agent/council-lesson-proposer.js

@@ -1,26 +1,145 @@
 /**
  * Council → lesson-candidate bridge (closes autonomy loop link [1]).
  *
- * The Fleet Council asks the same goal to N peers and produces a deterministic
- * consensus summary (agreement score + divergences). A council outcome that
- * DIVERGED — or only reached sub-threshold agreement — is a learnable signal:
- * the peers disagreed, so there's something worth capturing. This helper turns
- * such an outcome into a PROPOSED lesson candidate for human review.
+ * The council asks the same goal to N members/peers; a divergence CAN be a
+ * learnable signal — but replaying real transcripts showed the naive version
+ * produced mostly noise: 3 of 4 proposals existed only because the judge DIED
+ * (infrastructure, not knowledge), every candidate was the same
+ * metadata-plus-TODO template ("consensus 8%, X and Y diverged, review which
+ * position was correct") carrying none of the actual positions, and the one
+ * run with a genuinely reusable RESOLVED disagreement was skipped.
  *
- * It deliberately reuses the same "propose → review → approve, no silent write"
- * discipline as the rest of the learning loop: it only ever calls
- * `LessonCandidateQueue.propose()` (never writes `lessons.md`), so the operator
- * still gates what becomes durable procedural memory. Approved lessons are then
- * re-injected into future sagas via `loadRelevantSagaLessons` — the loop closes.
+ * The bridge now extracts SUBSTANCE and scores PEDAGOGICAL VALUE:
+ *  - a candidate carries the opposing positions (VERDICT lines / previews)
+ *    and the resolution (winner, rationale, what the judge re-verified);
+ *  - `scorePedagogicalValue()` rates generalizability, non-contingency,
+ *    testability, substance and real stance divergence — pure TS, no LLM,
+ *    deterministic and auditable (same philosophy as the DHI);
+ *  - infra noise (judge abstained) NEVER proposes — that signal belongs to
+ *    the scoreboard's failure ledger, not to procedural memory;
+ *  - the score is stored in the candidate's provenance so the human reviewer
+ *    can triage the queue by value.
  *
- * Pure and host-agnostic: callers (Cowork's saga-runner today, a CLI/server
- * hook later) pass primitives + an explicit `workDir`, so this never depends on
- * `process.cwd()`.
+ * Same "propose → review → approve, no silent write" discipline as before:
+ * only `LessonCandidateQueue.propose()`, never `lessons.md`.
  *
  * @module agent/council-lesson-proposer
  */
+import { createHash } from 'node:crypto';
 import { getLessonCandidateQueue } from './lesson-candidate-queue.js';
 import { logger } from '../utils/logger.js';
+/** Below this, a CLI-council divergence is journal noise, not a lesson. */
+export const MIN_PEDAGOGICAL_VALUE = 0.35;
+const FALSIFIABLE_MARKERS = /would change my mind|réfut|refut|falsif|suggested fix|fix:|vérifi|verifi|\bsi\b[^.]{0,80}\b(alors|sinon)\b|\bif\b[^.]{0,80}\bthen\b|\bunless\b|\btant que\b/i;
+const NORMATIVE_MARKERS = /\b(toujours|jamais|should|always|never|must|préf[ée]r\w*|prefer\w*|éviter|eviter|avoid|require\w*|exiger?)\b/i;
+/** Case-bound tokens: paths, hex ids, long numbers, versions — contingency signals. */
+const CONTINGENT_TOKENS = /(?:[\w.-]*[/\\][\w.-]+)|\b[0-9a-f]{8,}\b|\b\d{4,}\b|\bv?\d+\.\d+(?:\.\d+)?\b/gi;
+function clamp01(n) {
+    return Number.isFinite(n) ? Math.max(0, Math.min(1, n)) : 0;
+}
+function tokenSet(text) {
+    return new Set(text.toLowerCase().match(/[\p{L}\p{N}_-]{3,}/gu) ?? []);
+}
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 0 : inter / union;
+}
+/**
+ * Rate how much a divergence is worth to a human reviewer. Pure and
+ * deterministic (no LLM): the score must be auditable and reproducible.
+ *
+ * Criteria (from the transcript-corpus analysis):
+ *  - substance        — the candidate carries actual opposing positions,
+ *                       not just who diverged;
+ *  - resolution       — a divergence SETTLED by a neutral judge (rationale,
+ *                       self-verified facts) teaches more than an open one;
+ *  - testability      — falsifiable content (WOULD CHANGE MY MIND, suggested
+ *                       fixes, si/alors conditions) makes the lesson checkable;
+ *  - generalizability — normative, principle-level language generalizes;
+ *                       paths/ids/version numbers bind it to one case;
+ *  - stanceDivergence — the positions must actually contradict (different
+ *                       polarity or genuinely different content).
+ * Hard gate: an ABSTAINED verdict is infrastructure noise (dead judge,
+ * timeout) — score 0, never a lesson.
+ */
+export function scorePedagogicalValue(input) {
+    const zero = {
+        substance: 0,
+        resolution: 0,
+        testability: 0,
+        generalizability: 0,
+        stanceDivergence: 0,
+    };
+    if (input.verdictKind === 'abstained') {
+        return { score: 0, factors: zero };
+    }
+    const stances = input.positions.map((p) => p.stance.trim()).filter((s) => s.length > 0);
+    const meaty = stances.filter((s) => s.length >= 20);
+    const substance = clamp01(meaty.length / 2);
+    const resolution = input.resolution?.rationale
+        ? clamp01(0.7 + (input.resolution.verified ? 0.3 : 0))
+        : 0;
+    const testableBits = [...stances, input.resolution?.rationale ?? '', input.resolution?.verified ?? ''].filter((s) => FALSIFIABLE_MARKERS.test(s));
+    const testability = clamp01(testableBits.length / 2);
+    const allText = stances.join(' ');
+    const tokens = allText.match(/\S+/g)?.length ?? 0;
+    const contingent = allText.match(CONTINGENT_TOKENS)?.length ?? 0;
+    const contingencyRatio = tokens === 0 ? 1 : clamp01(contingent / Math.max(4, tokens / 4));
+    const normativeBoost = NORMATIVE_MARKERS.test(allText) ? 0.2 : 0;
+    const generalizability = clamp01(1 - contingencyRatio + normativeBoost);
+    let stanceDivergence = 0;
+    if (meaty.length >= 2) {
+        const sets = meaty.map((s) => tokenSet(s));
+        let minSim = 1;
+        for (let i = 0; i < sets.length; i++) {
+            for (let j = i + 1; j < sets.length; j++) {
+                minSim = Math.min(minSim, jaccard(sets[i], sets[j]));
+            }
+        }
+        stanceDivergence = clamp01(1 - minSim);
+    }
+    const factors = { substance, resolution, testability, generalizability, stanceDivergence };
+    const score = clamp01(0.25 * substance + 0.2 * resolution + 0.2 * testability + 0.2 * generalizability + 0.15 * stanceDivergence);
+    return { score, factors };
+}
+// ---------------------------------------------------------------------------
+// Content — the candidate must be readable WITHOUT reopening the transcript.
+// ---------------------------------------------------------------------------
+const MAX_CONTENT_CHARS = 900;
+function trimTo(text, max) {
+    const t = text.trim().replace(/\s+/g, ' ');
+    return t.length <= max ? t : `${t.slice(0, max - 1)}…`;
+}
+function buildRichContent(goal, positions, resolution, consensus) {
+    const parts = [
+        `Fleet Council on "${trimTo(goal, 110)}" (agreement ${Math.round(consensus.score * 100)}%, ${consensus.total} voices).`,
+    ];
+    const shown = positions.filter((p) => p.stance.trim()).slice(0, 3);
+    if (shown.length > 0) {
+        parts.push('Positions: ' + shown.map((p) => `«${p.label}» ${trimTo(p.stance, 180)}`).join(' ⇄ ') + '.');
+    }
+    if (resolution?.rationale) {
+        parts.push(`Settled${resolution.winner ? ` for «${resolution.winner}»` : ''}: ${trimTo(resolution.rationale, 200)}` +
+            (resolution.verified ? ` [judge verified: ${trimTo(resolution.verified, 120)}]` : '') +
+            '.');
+    }
+    else {
+        parts.push('Unsettled — an open question, not a resolved rule: validate before relying on either side.');
+    }
+    return trimTo(parts.join(' '), MAX_CONTENT_CHARS);
+}
+// ---------------------------------------------------------------------------
+// Saga path (Cowork SagaRunner) — real peers answering the SAME prompt, so a
+// lexical divergence is already meaningful. Gates unchanged; content and
+// provenance enriched (previews become positions, score attached for triage —
+// informational, not gating, to keep the saga behavior stable).
+// ---------------------------------------------------------------------------
 /**
  * Propose a review lesson candidate from a council outcome, gated and deduped.
  * Never throws — returns a structured result the caller can log/surface.
@@ -40,6 +159,61 @@ export function proposeFromCouncilOutcome(input, workDir) {
     if (!hasDivergence && !lowConsensus) {
         return { proposed: false, reason: 'full agreement — nothing to learn' };
     }
+    const positions = disagreements
+        .filter((d) => d.preview?.trim())
+        .map((d) => ({ label: `${d.peerId}×${d.model}`, stance: d.preview }));
+    return proposeCandidate(input, workDir, positions, undefined, { gateOnValue: false });
+}
+export function proposeFromCouncilRunResult(input, workDir) {
+    // Infra noise is NEVER a lesson: an abstained verdict (dead judge, timeout)
+    // says nothing about the CONTENT — replaying real transcripts showed these
+    // were the majority of proposals. The scoreboard's failure ledger already
+    // captures that signal on the right channel.
+    if (input.verdictKind === 'abstained') {
+        return { proposed: false, reason: 'judge abstained — infrastructure noise, not knowledge' };
+    }
+    const disagreements = input.consensus?.disagreements ?? [];
+    const lexicalDisagreement = disagreements.length > 0 ||
+        (typeof input.consensus?.score === 'number' &&
+            typeof input.consensus?.threshold === 'number' &&
+            input.consensus.score < input.consensus.threshold);
+    if (!lexicalDisagreement) {
+        return { proposed: false, reason: 'full agreement — nothing to learn' };
+    }
+    // Positions: prefer the members' explicit stances; fall back to the
+    // disagreement previews when the caller has nothing richer.
+    const positions = input.positions?.filter((p) => p.stance.trim()).slice(0, 4) ??
+        [];
+    if (positions.length === 0) {
+        for (const d of disagreements) {
+            if (d.preview?.trim())
+                positions.push({ label: `${d.peerId}×${d.model}`, stance: d.preview });
+        }
+    }
+    // Value gate: a divergence must be worth a human read — substance,
+    // resolution, testability, generalizability. Fixes both failure modes seen
+    // on real data: metadata-only noise proposed, resolved substantive
+    // disagreements skipped.
+    const value = scorePedagogicalValue({
+        verdictKind: input.verdictKind,
+        positions,
+        ...(input.resolution ? { resolution: input.resolution } : {}),
+    });
+    if (value.score < MIN_PEDAGOGICAL_VALUE) {
+        return {
+            proposed: false,
+            reason: `pedagogical value ${value.score.toFixed(2)} below ${MIN_PEDAGOGICAL_VALUE} — journal noise, not a lesson`,
+        };
+    }
+    // Stable per-question id: re-running the same task must hit the saga-level
+    // dedup instead of piling up near-duplicate candidates.
+    const sagaId = `cli:${createHash('sha256').update(input.task.trim().toLowerCase()).digest('hex').slice(0, 16)}`;
+    return proposeCandidate({ sagaId, goal: input.task, aggregation: 'consensus', consensus: input.consensus }, workDir, positions, input.resolution, { gateOnValue: true, value });
+}
+// ---------------------------------------------------------------------------
+// Shared propose (dedup + queue + provenance with the triage score).
+// ---------------------------------------------------------------------------
+function proposeCandidate(input, workDir, positions, resolution, opts) {
     if (!workDir) {
         return { proposed: false, reason: 'no workDir' };
     }
@@ -53,13 +227,9 @@ export function proposeFromCouncilOutcome(input, workDir) {
         });
         return { proposed: false, reason: 'queue unavailable' };
     }
-    // Gate 3 — saga-level dedup. The queue's content-level dedup won't catch
-    // re-finalisations/retries (content can vary), so skip if this saga already
-    // has a pending candidate.
+    // Saga-level dedup: one pending candidate per saga/question.
     try {
-        const existing = queue
-            .list('pending')
-            .find((c) => c.provenance?.sagaId === input.sagaId);
+        const existing = queue.list('pending').find((c) => c.provenance?.sagaId === input.sagaId);
         if (existing) {
             return { proposed: false, reason: 'already proposed for this saga', candidate: existing };
         }
@@ -67,13 +237,21 @@ export function proposeFromCouncilOutcome(input, workDir) {
     catch {
         // Non-fatal — fall through and let propose() de-dup on content.
     }
+    const value = opts.value ??
+        scorePedagogicalValue({ verdictKind: 'judged', positions, ...(resolution ? { resolution } : {}) });
     try {
         const { candidate } = queue.propose({
-            category: 'INSIGHT',
-            content: buildContent(input),
-            context: `Fleet council · saga ${input.sagaId}`,
+            // A settled, verified disagreement is closer to a rule; an open one is an insight to validate.
+            category: resolution?.rationale ? 'RULE' : 'INSIGHT',
+            content: buildRichContent(input.goal, positions, resolution, input.consensus),
+            context: `Fleet council · saga ${input.sagaId} · value ${value.score.toFixed(2)}`,
             source: 'self_observed',
-            provenance: { sagaId: input.sagaId, note: 'auto-proposed from fleet council outcome' },
+            provenance: {
+                sagaId: input.sagaId,
+                note: 'auto-proposed from council divergence',
+                pedagogicalValue: value.score,
+                valueFactors: value.factors,
+            },
         });
         return { proposed: true, candidate };
     }
@@ -84,24 +262,4 @@ export function proposeFromCouncilOutcome(input, workDir) {
         return { proposed: false, reason: 'propose failed' };
     }
 }
-function buildContent(input) {
-    const pct = (n) => `${Math.round((n ?? 0) * 100)}%`;
-    const goal = input.goal.length > 80 ? `${input.goal.slice(0, 77)}...` : input.goal;
-    const parts = [
-        `Fleet Council on "${goal}": consensus ${pct(input.consensus.score)} ` +
-            `(threshold ${pct(input.consensus.threshold)}) across ${input.consensus.total} peers.`,
-    ];
-    const disagreements = input.consensus.disagreements ?? [];
-    if (disagreements.length > 0) {
-        const who = disagreements
-            .slice(0, 2)
-            .map((d) => `${d.peerId}×${d.model}`)
-            .join(', ');
-        parts.push(`Diverging: ${who}. Review which position was correct and capture the resolution as a durable lesson.`);
-    }
-    else {
-        parts.push('Consensus stayed below threshold — verify the agreed answer before relying on it.');
-    }
-    return parts.join(' ');
-}
 //# sourceMappingURL=council-lesson-proposer.js.map

package/dist/agent/deep-research-ckg.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Deep Research — Phase D (Collective Knowledge Graph bridge).
+ *
+ * Phases A/B/C produce a self-contained cited report from FRESH web sources and
+ * then forget everything. The Collective Knowledge Graph (`memory/collective-
+ * knowledge-graph.ts`) is the collective's SHARED, cross-run/cross-agent memory
+ * — an append-only ledger whose `ingest()` auto-links a discovery to its nearest
+ * neighbours (supports / contradicts / related_to) and CORROBORATES a fact that
+ * several independent agents find, and whose `recallHybrid()` retrieves prior
+ * knowledge with local embeddings ($0, no LLM at retrieval).
+ *
+ * Today the two are DISCONNECTED: a Deep Research run neither feeds the graph nor
+ * consults what the collective already knows. Phase D bridges them, both ways and
+ * both OPT-IN:
+ *
+ *   1. INGEST (write)  — at the END of a run, the deduped web sources are ingested
+ *                        into the CKG (one `discovery` node each, url as stable
+ *                        name + a bounded excerpt as text). Benefits: accumulation
+ *                        across runs, auto-linking, and corroboration when several
+ *                        runs/agents surface the same fact. Idempotent by design:
+ *                        the CKG dedups on contentHash (same url + same excerpt →
+ *                        reinforce, not duplicate), and we fingerprint-dedup the
+ *                        batch first (reusing Phase-A `contentFingerprint`).
+ *   2. RECALL (read)   — at the START of a run, the collective's prior knowledge
+ *                        for the question is recalled (bounded top-K) and injected
+ *                        into the produced report as a DISTINCTLY-MARKED
+ *                        "## Mémoire collective" section with its own `[Mk]`
+ *                        citation namespace — never confused with a fresh web
+ *                        source.
+ *
+ * STRICTLY ADDITIVE / never-throws: with the bridge absent or `enabled: false`
+ * the wrapper delegates to the base A/B/C runner VERBATIM — no recall, no ingest,
+ * an untouched report/sources (byte-identical). The single side-effecting edge —
+ * the CKG itself — is the INJECTABLE `CkgBridge`, so the whole pipeline is unit-
+ * testable with zero ledger / zero network. Any bridge failure (recall or ingest)
+ * degrades silently: the research continues normally. The CKG is a bonus, never a
+ * hard dependency.
+ *
+ * @module agent/deep-research-ckg
+ */
+import { type DeepResearchResult } from './deep-research.js';
+/** A piece of prior collective knowledge recalled from the CKG (already-collected). */
+export interface CkgMemorySource {
+    /** The CKG node id (provenance). */
+    id: string;
+    /** The knowledge text. */
+    text: string;
+    /** Node type ('discovery' | 'fact' | 'lesson' | …). */
+    type?: string;
+    /** The agent that contributed it (attribution). */
+    agentId?: string;
+    /** Provenance tag ('deep-research' | 'publication' | …). */
+    source?: string;
+    /** Semantic similarity to the query (0..1) when the recall provided it. */
+    similarity?: number;
+}
+/** A deduped web source (with a content excerpt) that a run will ingest into the CKG. */
+export interface CkgIngestableSource {
+    url: string;
+    title: string;
+    content: string;
+}
+/** Metadata attached to every ingested node. */
+export interface CkgIngestMeta {
+    /** The research question (audit / provenance). */
+    question: string;
+    /** Provenance tag written on each node. */
+    source: string;
+    /** Contributing agent id (attribution). */
+    agentId?: string;
+}
+/**
+ * The ONLY seam Phase D needs — an injectable adapter over the Collective
+ * Knowledge Graph. The real implementation wraps `CollectiveKnowledgeGraph`
+ * (`recallHybrid` / `ingest`); tests inject a fake so nothing touches a ledger.
+ * Both methods are expected to never throw (impls guard), but the wrapper guards
+ * them anyway.
+ */
+export interface CkgBridge {
+    /** Recall up to `k` prior knowledge entries for `query`. Returns [] on any failure. */
+    recall(query: string, k: number): Promise<CkgMemorySource[]>;
+    /** Ingest the deduped sources as discovery nodes. Returns how many were stored. */
+    ingest(sources: CkgIngestableSource[], meta: CkgIngestMeta): Promise<number>;
+}
+/** Phase-D activation + tuning (all bounded). */
+export interface CkgRunOptions {
+    /** Master switch. `false`/absent ⇒ the base A/B/C run is byte-identical. */
+    enabled: boolean;
+    /** The CKG adapter. Absent ⇒ Phase D is inert even when `enabled` (fail-open). */
+    bridge?: CkgBridge;
+    /** Top-K recall bound (default 6, clamped [1, 20]). */
+    recallLimit?: number;
+    /** Per-source excerpt chars fed to ingest (default 600, clamped [120, 4000]). */
+    ingestExcerptChars?: number;
+    /** Contributing agent id written on ingested nodes (attribution). */
+    agentId?: string;
+    /** Provenance tag written on ingested nodes (default 'deep-research'). */
+    sourceTag?: string;
+}
+/** What Phase D did on a run (surfaced on the result for CLI rendering / tests). */
+export interface CkgOutcome {
+    enabled: boolean;
+    /** Number of prior-knowledge entries recalled + injected into the report. */
+    recalled: number;
+    /** Number of web sources ingested into the collective graph. */
+    ingested: number;
+    /** The recalled knowledge (for rendering / assertions). */
+    memory: CkgMemorySource[];
+}
+/**
+ * Recall prior collective knowledge for `query`, bounded to top-K. Never throws:
+ * a bridge failure (or an unusable payload) yields []. The results are cleaned
+ * (non-empty text) and hard-capped at K.
+ */
+export declare function recallCollectiveMemory(bridge: CkgBridge, query: string, limit?: number): Promise<CkgMemorySource[]>;
+/**
+ * Fingerprint-dedup + excerpt-bound an ingest batch (reuses the Phase-A
+ * `contentFingerprint`/Jaccard so a near-duplicate excerpt is not re-ingested).
+ * The batch is already URL-unique and Phase-A-deduped upstream; this is a cheap
+ * belt-and-suspenders pass. Fail-open: an unfingerprintable source is kept.
+ */
+export declare function prepareIngestBatch(sources: CkgIngestableSource[], excerptChars: number): CkgIngestableSource[];
+/**
+ * Ingest the deduped sources into the collective graph. Bounded to the batch
+ * size (itself capped by Phase A), never throws (a bridge failure yields 0).
+ */
+export declare function ingestCollectedSources(bridge: CkgBridge, sources: CkgIngestableSource[], meta: CkgIngestMeta, excerptChars?: number): Promise<number>;
+/**
+ * Inject the recalled collective knowledge into the report as a DISTINCT
+ * "## Mémoire collective" section, placed just before "## Références" so the web
+ * references stay last. Each entry gets a `[Mk]` marker — a separate citation
+ * namespace from the web `[n]` markers — and carries its provenance (agent /
+ * source / similarity), so recalled knowledge is never confused with a fresh web
+ * source. Empty memory ⇒ the report is returned untouched.
+ */
+export declare function augmentReportWithMemory(report: string, memory: CkgMemorySource[]): string;
+export interface RunWithCkgParams<TResult extends DeepResearchResult> {
+    /** The research question (recall query + ingest provenance). */
+    question: string;
+    /** Phase-D activation + tuning. */
+    options: CkgRunOptions;
+    /** Runs the base A/B/C pipeline (already wired with real/teed boundaries). */
+    runBase: () => Promise<TResult>;
+    /** Maps the base result to the ingestable web sources (url + title + captured content). */
+    collectSourcesForIngest: (result: TResult) => CkgIngestableSource[];
+}
+/**
+ * Wrap a base Deep Research run (Phase A/B/C) with the CKG bridge. When Phase D
+ * is OFF (bridge absent or `enabled: false`) the base runner is delegated to
+ * VERBATIM — no recall, no ingest, the report/sources untouched (byte-identical).
+ * When ON: recall (start) → base run → ingest the deduped sources (end) → augment
+ * the report with the recalled memory, and attach a `ckg` outcome. Never throws:
+ * recall and ingest degrade silently, the base research is always returned.
+ */
+export declare function runDeepResearchWithCkg<TResult extends DeepResearchResult>(params: RunWithCkgParams<TResult>): Promise<TResult & {
+    ckg?: CkgOutcome;
+}>;
+/**
+ * Resolve Phase-D activation from the CLI flag and/or the shared env gate.
+ * `--ckg` OR `CODEBUDDY_COLLECTIVE_MEMORY=true` enables the bridge — the SAME
+ * gate the rest of the app uses, so activation is consistent. Absent ⇒ off.
+ */
+export declare function resolveCkgEnabled(opts?: {
+    ckg?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Wrap a boundaries object so its `scrape` TEES the fetched content into `sink`
+ * (keyed by url), leaving every other boundary (llm/search/fingerprint/mapBatched
+ * and the STORM seams) untouched. This is how Phase D captures the per-source
+ * content the base pipeline drops from its `SourceRef[]` result — WITHOUT
+ * touching the A/B/C pipeline. Applied only on the CKG-enabled path. Never throws
+ * beyond what the underlying scrape throws (which the pipeline already guards).
+ */
+export declare function teeScrapeBoundary<B extends {
+    scrape: (url: string) => Promise<string>;
+}>(boundaries: B, sink: Map<string, string>): B;