@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/research/workflows/research-normal.js

@@ -0,0 +1,573 @@
+export const meta = {
+  name: 'research-normal',
+  description: 'Run a mode-normal research session end-to-end: plan → search+extract → rank → 3-vote verify → deepen (1 round) → synthesize → finalise (mark done).',
+  phases: [
+    { title: 'Plan', detail: 'decompose into 2–4 sub-questions, write plan.json' },
+    { title: 'Search', detail: 'one searcher per sub-question (dependents chained)' },
+    { title: 'Extract', detail: 'quote-grounded claim extraction per sub-question' },
+    { title: 'Verify', detail: '3-vote adversarial verify on central claims' },
+    { title: 'Deepen', detail: '1 gap-driven round (reflection stop when sufficient)' },
+    { title: 'Synthesize', detail: 'write findings/sq-N.json + the session answer' },
+    { title: 'Finalise', detail: 'persist gate records, write sources.json, round-trip, research mark done' },
+  ],
+};
+
+// ── deterministic plumbing (build-spec §4.1: dedup / ranking / budget math = code) ──
+
+const CLAIM_BUDGET = 25;                 // harness-skill cap; §4 does not override for normal
+const IMPORTANCE_W = { central: 3, supporting: 2, incidental: 1 };
+const QUALITY_W = { primary: 3, secondary: 2, low: 1 };
+const VERIFY_LENSES = ['quote-support', 'contradiction-search', 'recency-source-fit'];
+const UNSOURCED_ABORT_RATIO = 0.10;      // §8 guardrail: >10% unsourced fails the run
+
+// `args` normally arrives as the object passed to Workflow(); tolerate a
+// JSON-string-encoded form too (some dispatch paths stringify it).
+let _args = args;
+if (typeof _args === 'string') { try { _args = JSON.parse(_args); } catch { _args = {}; } }
+
+// After the tool moved into `@stravica-ai/digital-operator-pa` (2026-07-08), sessions
+// live in the operator repo (`<repoRoot>/.cache/research/sessions/`) but the
+// briefs and this workflow ship inside the installed package under
+// `node_modules/`. One `toolRoot` no longer maps to both, so the skill now
+// gets all four paths from `research paths --json` and passes them in
+// explicitly. The legacy `toolRoot` arg still works — if it's the only thing
+// given, we derive the same three paths from it (v1 shape).
+const { sessionId, sessionsDir: sessionsDirArg, briefsDir: briefsDirArg, schemaDir: schemaDirArg, cli: cliArg, toolRoot } = _args || {};
+if (!sessionId) throw new Error('research-normal: args.sessionId is required');
+if (!sessionsDirArg && !toolRoot) {
+  throw new Error('research-normal: args.sessionsDir (or legacy args.toolRoot) is required — get it from `research paths --json`');
+}
+if (!briefsDirArg && !toolRoot) {
+  throw new Error('research-normal: args.briefsDir (or legacy args.toolRoot) is required — get it from `research paths --json`');
+}
+
+const sessionsDir = sessionsDirArg || `${toolRoot}/sessions`;
+const briefsDir = briefsDirArg || `${toolRoot}/briefs`;
+const schemaDir = schemaDirArg || `${toolRoot}/src/schema`;
+const cli = cliArg || `node ${toolRoot}/bin/research`;
+const sessionDir = `${sessionsDir}/${sessionId}`;
+
+// Build an agent prompt that points the worker at its on-disk brief + concrete values.
+// The workflow has no fs; the agent (Read/Bash/Write/WebSearch) is what touches disk.
+function brief(role, values) {
+  const vals = Object.entries(values)
+    .map(([k, v]) => `- ${k}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+    .join('\n');
+  return [
+    `You are the **${role}** in the deep-research \`research-normal.js\` pipeline.`,
+    `Read and follow the brief at \`${briefsDir}/${role}.md\` in full.`,
+    `The brief's {{placeholder}} values for this dispatch are:`,
+    vals,
+    `Return ONLY the structured object the brief's §6 (Output format) specifies — nothing else.`,
+  ].join('\n\n');
+}
+
+// Reject circular / self-referential / malformed plans (§8: workflow-code validator).
+function validatePlanShape(subQuestions) {
+  const errs = [];
+  if (!Array.isArray(subQuestions) || subQuestions.length < 2 || subQuestions.length > 4) {
+    errs.push(`expected 2–4 sub-questions, got ${Array.isArray(subQuestions) ? subQuestions.length : 'none'}`);
+    return errs;
+  }
+  const ids = new Set();
+  for (const sq of subQuestions) {
+    if (!sq || typeof sq.id !== 'string') { errs.push('a sub-question is missing a string id'); continue; }
+    if (ids.has(sq.id)) errs.push(`duplicate sub-question id "${sq.id}"`);
+    ids.add(sq.id);
+  }
+  for (const sq of subQuestions) {
+    const deps = Array.isArray(sq.dependsOn) ? sq.dependsOn : [];
+    for (const d of deps) {
+      if (d === sq.id) errs.push(`sub-question "${sq.id}" depends on itself`);
+      if (!ids.has(d)) errs.push(`sub-question "${sq.id}" depends on unknown "${d}"`);
+    }
+  }
+  // cycle detection (DFS)
+  const byId = new Map(subQuestions.map((s) => [s.id, Array.isArray(s.dependsOn) ? s.dependsOn : []]));
+  const state = new Map(); // 0=visiting,1=done
+  const visit = (id, stack) => {
+    if (state.get(id) === 1) return;
+    if (stack.has(id)) { errs.push(`dependency cycle through "${id}"`); return; }
+    stack.add(id);
+    for (const d of (byId.get(id) || [])) if (byId.has(d)) visit(d, stack);
+    stack.delete(id);
+    state.set(id, 1);
+  };
+  for (const id of byId.keys()) visit(id, new Set());
+  return errs;
+}
+
+// Kahn topological order over the dependent sub-questions (deps already validated).
+function topoOrder(subQuestions) {
+  const byId = new Map(subQuestions.map((s) => [s.id, s]));
+  const order = [];
+  const done = new Set();
+  let guard = 0;
+  while (order.length < subQuestions.length && guard++ < subQuestions.length + 1) {
+    for (const sq of subQuestions) {
+      if (done.has(sq.id)) continue;
+      const deps = (sq.dependsOn || []).filter((d) => byId.has(d));
+      if (deps.every((d) => done.has(d))) { order.push(sq); done.add(sq.id); }
+    }
+  }
+  return order;
+}
+
+// ── JSON schemas for structured agent returns ──────────────────────────────────
+
+const PLAN_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['question', 'outputMode', 'gatePolicy', 'subQuestions', 'wrotePlan'],
+  properties: {
+    question: { type: 'string' },
+    intent: { type: 'string' },
+    outputMode: { enum: ['shortAnswer', 'article', 'structured'] },
+    gatePolicy: { enum: ['operatorPresent', 'background', 'worker'] },
+    wrotePlan: { type: 'boolean' },
+    subQuestions: {
+      type: 'array', minItems: 2, maxItems: 4,
+      items: {
+        type: 'object', additionalProperties: false,
+        required: ['id', 'text', 'kind', 'dependsOn'],
+        properties: {
+          id: { type: 'string' },
+          text: { type: 'string' },
+          kind: { enum: ['independent', 'dependent'] },
+          dependsOn: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+  },
+};
+
+const SEARCH_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['subQuestionId', 'sources', 'toolCallsUsed'],
+  properties: {
+    subQuestionId: { type: 'string' },
+    sources: {
+      type: 'array',
+      items: {
+        type: 'object', additionalProperties: false,
+        required: ['sourceId', 'url', 'title', 'kind', 'sourceQuality'],
+        properties: {
+          sourceId: { type: 'string' },
+          url: { type: 'string' },
+          title: { type: 'string' },
+          kind: { enum: ['web', 'playwright', 'kb', 'codebase', 'prior-session'] },
+          sourceQuality: { enum: ['primary', 'secondary', 'low'] },
+          snippet: { type: 'string' },
+        },
+      },
+    },
+    toolCallsUsed: { type: 'integer' },
+    gatedDropped: {
+      type: 'array',
+      items: {
+        type: 'object', additionalProperties: false,
+        required: ['url', 'gateType', 'whatIsNeeded'],
+        properties: { url: { type: 'string' }, gateType: { type: 'string' }, whatIsNeeded: { type: 'string' } },
+      },
+    },
+    notes: { type: 'string' },
+  },
+};
+
+const EXTRACT_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['subQuestionId', 'claims', 'unsourcedClaims'],
+  properties: {
+    subQuestionId: { type: 'string' },
+    claims: {
+      type: 'array',
+      items: {
+        type: 'object', additionalProperties: false,
+        required: ['claimId', 'text', 'quote', 'sourceId', 'importance', 'sourceQuality'],
+        properties: {
+          claimId: { type: 'string' },
+          text: { type: 'string' },
+          quote: { type: 'string' },
+          sourceId: { type: 'string' },
+          importance: { enum: ['central', 'supporting', 'incidental'] },
+          sourceQuality: { enum: ['primary', 'secondary', 'low'] },
+        },
+      },
+    },
+    unsourcedClaims: { type: 'integer' },
+    notes: { type: 'string' },
+  },
+};
+
+const VERIFY_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['outcome', 'note'],
+  properties: {
+    outcome: { enum: ['confirmed', 'refuted', 'unverified-infra'] },
+    note: { type: 'string' },
+  },
+};
+
+const DEEPEN_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['sufficient', 'newSubQuestions'],
+  properties: {
+    sufficient: { type: 'boolean' },
+    gaps: { type: 'array', items: { type: 'string' } },
+    newSubQuestions: {
+      type: 'array', maxItems: 4,
+      items: {
+        type: 'object', additionalProperties: false,
+        required: ['id', 'text'],
+        properties: { id: { type: 'string' }, text: { type: 'string' } },
+      },
+    },
+  },
+};
+
+const SYNTH_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['subQuestionId', 'written', 'path', 'confidence', 'claimCount', 'centralConfirmed', 'centralRefuted', 'unsourcedCount'],
+  properties: {
+    subQuestionId: { type: 'string' },
+    written: { type: 'boolean' },
+    path: { type: 'string' },
+    confidence: { enum: ['low', 'medium', 'high'] },
+    claimCount: { type: 'integer' },
+    centralConfirmed: { type: 'integer' },
+    centralRefuted: { type: 'integer' },
+    unsourcedCount: { type: 'integer' },
+    refutedTransparency: { type: 'string' },
+  },
+};
+
+const FINALISE_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['wroteSources', 'wroteAnswer', 'roundTripOk', 'markedDone'],
+  properties: {
+    wroteSources: { type: 'boolean' },
+    wroteAnswer: { type: 'boolean' },
+    roundTripOk: { type: 'boolean' },
+    markedDone: { type: 'boolean' },
+    gatesAppended: { type: 'integer' }, // count of gatedDropped records persisted to gates.json (w-018)
+    note: { type: 'string' },
+  },
+};
+
+// ── agent wrappers (model/effort per build-spec §4.1 — explicit, never inherited) ──
+
+function searchAgent(sq, siblings, priorContext) {
+  return agent(brief('searcher', {
+    sessionId, sessionQuestion: baseQuestion, intent: baseIntent, gatePolicy: basePolicy,
+    subQuestionId: sq.id, subQuestionText: sq.text,
+    siblingSubQuestions: siblings.filter((s) => s.id !== sq.id).map((s) => `${s.id}: ${s.text}`).join(' | ') || 'none',
+    sourceIdPrefix: sq.id.replace(/[^a-zA-Z0-9]/g, ''), toolCallCap: 12, sessionDir,
+    dependencyContext: priorContext || 'none (independent sub-question)',
+  }), { model: 'sonnet', effort: 'medium', phase: 'Search', label: `search:${sq.id}`, schema: SEARCH_SCHEMA });
+}
+
+function extractAgent(sq, searchRes, priorContext) {
+  const sources = (searchRes && searchRes.sources) || [];
+  return agent(brief('extractor', {
+    sessionId, sessionQuestion: baseQuestion,
+    subQuestionId: sq.id, subQuestionText: sq.text,
+    sources: sources.map((s) => ({ sourceId: s.sourceId, url: s.url, title: s.title, sourceQuality: s.sourceQuality })),
+    sessionDir, dependencyContext: priorContext || 'none',
+  }), { model: 'sonnet', effort: 'medium', phase: 'Extract', label: `extract:${sq.id}`, schema: EXTRACT_SCHEMA });
+}
+
+function verifyAgent(claim, lens) {
+  return agent(brief('verifier', {
+    sessionId, claimText: claim.text, quote: claim.quote, sourceUrl: claim.url || claim.sourceId,
+    subQuestionText: claim.sqText, lens,
+  }), { model: 'sonnet', effort: 'high', phase: 'Verify', label: `verify:${claim.claimId}:${lens}`, schema: VERIFY_SCHEMA });
+}
+
+function synthAgent(sq, buckets) {
+  return agent(brief('synthesizer', {
+    sessionId, subQuestionId: sq.id, subQuestionText: sq.text, outputMode: baseOutputMode,
+    findingFilename: `${sq.id}.json`, sessionDir, schemaDir, cli,
+    verifiedClaims: buckets.verified, supportingClaims: buckets.supporting, refutedClaims: buckets.refuted,
+  }), { model: 'opus', effort: 'high', phase: 'Synthesize', label: `synth:${sq.id}`, schema: SYNTH_SCHEMA });
+}
+
+// ── run ─────────────────────────────────────────────────────────────────────
+
+// -- Plan --
+phase('Plan');
+let baseQuestion = '', baseIntent = 'none', basePolicy = 'worker', baseOutputMode = 'shortAnswer';
+let subQuestions;
+{
+  let plan = await agent([
+    `You are the **planner** for a mode-\`normal\` research run. Lead-tier reasoning.`,
+    `1. Read \`${sessionDir}/manifest.json\` and \`${sessionDir}/plan.json\`.`,
+    `2. Decompose the manifest's \`question\` (honouring \`intent\`) into **2–4 sub-questions**.`,
+    `   Classify each \`independent\` or \`dependent\`; a dependent one lists its \`dependsOn\` ids.`,
+    `   Prefer independent facets (they parallelise). Use ids \`sq-1\`,\`sq-2\`,… (these become finding filenames).`,
+    `   44% of multi-agent failures start at planning — make the facets genuinely distinct and jointly cover the question.`,
+    `3. WRITE the filled plan back to \`${sessionDir}/plan.json\`: keep the existing \`deepeningRounds\` and`,
+    `   \`verificationTier\`, replace \`subQuestions\` with your list (each {id,text,kind,dependsOn}). No extra fields.`,
+    `4. Round-trip: run \`${cli} show ${sessionId} --json\` and confirm exit 0 (it validates plan.json).`,
+    `Return the structured object: question, intent, outputMode, gatePolicy (echo from the manifest),`,
+    `subQuestions, and wrotePlan=true once the round-trip is green.`,
+  ].join('\n'), { model: 'opus', effort: 'high', phase: 'Plan', label: 'plan', schema: PLAN_SCHEMA });
+
+  baseQuestion = plan.question;
+  baseIntent = plan.intent || 'none';
+  basePolicy = plan.gatePolicy;
+  baseOutputMode = plan.outputMode;
+  subQuestions = plan.subQuestions;
+
+  let errs = validatePlanShape(subQuestions);
+  if (errs.length) {
+    log(`plan rejected (${errs.join('; ')}) — re-planning once`);
+    plan = await agent([
+      `Your previous plan was rejected by the workflow validator: ${errs.join('; ')}.`,
+      `Re-read \`${sessionDir}/manifest.json\`, produce a corrected 2–4 sub-question decomposition with no`,
+      `self-references, no cycles, and only valid dependsOn ids, rewrite \`${sessionDir}/plan.json\`, round-trip`,
+      `\`${cli} show ${sessionId} --json\`, and return the structured object.`,
+    ].join('\n'), { model: 'opus', effort: 'high', phase: 'Plan', label: 'plan-retry', schema: PLAN_SCHEMA });
+    subQuestions = plan.subQuestions;
+    errs = validatePlanShape(subQuestions);
+    if (errs.length) throw new Error(`research-normal: planner produced an invalid plan twice (${errs.join('; ')}) — escalating`);
+  }
+  log(`plan: ${subQuestions.length} sub-questions — ${subQuestions.map((s) => s.id).join(', ')}`);
+}
+
+// -- Search + Extract --
+// Independent facets flow search→extract with no cross-facet barrier (pipeline).
+// Dependent facets are chained AFTER their dependsOn extract completes (the DAG that
+// pipeline() cannot express — documented fallback, §8).
+phase('Search');
+const independent = subQuestions.filter((sq) => sq.kind !== 'dependent' || (sq.dependsOn || []).length === 0);
+const dependents = subQuestions.filter((sq) => sq.kind === 'dependent' && (sq.dependsOn || []).length > 0);
+
+const sqResults = new Map(); // sq.id -> { sq, search, extract }
+
+const indepPairs = await pipeline(
+  independent,
+  (sq) => searchAgent(sq, subQuestions),
+  (searchRes, sq) => extractAgent(sq, searchRes).then((extract) => ({ sq, search: searchRes, extract })),
+);
+for (const r of indepPairs.filter(Boolean)) sqResults.set(r.sq.id, r);
+
+for (const sq of topoOrder(dependents)) {
+  const priorContext = (sq.dependsOn || [])
+    .map((d) => sqResults.get(d))
+    .filter(Boolean)
+    .map((r) => `${r.sq.id}: ${(r.extract.claims || []).map((c) => c.text).slice(0, 3).join('; ')}`)
+    .join(' || ') || 'dependencies produced no claims';
+  const searchRes = await searchAgent(sq, subQuestions, priorContext);
+  const extract = await extractAgent(sq, searchRes, priorContext);
+  sqResults.set(sq.id, { sq, search: searchRes, extract });
+}
+
+// -- Rank + budget cap (deterministic code — §4.1) --
+// Flatten claims, tag with their sq + the url of their cited source, rank by
+// importance×sourceQuality, keep the top CLAIM_BUDGET; the rest are budgetDropped.
+const urlBySourceId = new Map();
+for (const { search } of sqResults.values()) {
+  for (const s of (search.sources || [])) urlBySourceId.set(s.sourceId, s.url);
+}
+let allClaims = [];
+for (const { sq, extract } of sqResults.values()) {
+  for (const c of (extract.claims || [])) {
+    allClaims.push({ ...c, sqId: sq.id, sqText: sq.text, url: urlBySourceId.get(c.sourceId) || null });
+  }
+}
+allClaims.sort((a, b) =>
+  (IMPORTANCE_W[b.importance] * QUALITY_W[b.sourceQuality]) - (IMPORTANCE_W[a.importance] * QUALITY_W[a.sourceQuality]));
+const extractedCount = allClaims.length;
+const retained = allClaims.slice(0, CLAIM_BUDGET);
+const budgetDropped = extractedCount - retained.length;
+log(`extracted ${extractedCount} claims; retained ${retained.length} (budgetDropped ${budgetDropped})`);
+
+// -- Verify (3-vote adversarial on central claims only — §4 normal row) --
+phase('Verify');
+const centralClaims = retained.filter((c) => c.importance === 'central');
+const verifyResults = await parallel(centralClaims.map((claim) => () =>
+  parallel(VERIFY_LENSES.map((lens) => () => verifyAgent(claim, lens)))
+    .then((votes) => ({ claim, votes: votes.filter(Boolean) }))));
+
+let confirmedN = 0, refutedN = 0, infraN = 0, infraCollapsedClaims = 0;
+const verdictByClaimId = new Map();
+for (const r of verifyResults.filter(Boolean)) {
+  const outcomes = r.votes.map((v) => v.outcome);
+  const refutes = outcomes.filter((o) => o === 'refuted').length;
+  const infra = outcomes.filter((o) => o === 'unverified-infra').length;
+  confirmedN += outcomes.filter((o) => o === 'confirmed').length;
+  refutedN += refutes; infraN += infra;
+  if (infra >= 2) infraCollapsedClaims++;
+  // ≥2 refutes → dropped; unverified-infra does NOT count toward refutation (§5).
+  const verdict = refutes >= 2 ? 'refuted' : 'confirmed';
+  verdictByClaimId.set(r.claim.claimId + '@' + r.claim.sqId, { verdict, votes: r.votes });
+}
+// §8: whole-run verify collapse → escalate rather than ship unverified-as-confirmed.
+if (centralClaims.length > 0 && infraCollapsedClaims / centralClaims.length > 0.5) {
+  throw new Error(`research-normal: verify tier collapsed — ${infraCollapsedClaims}/${centralClaims.length} central claims were unverified-infra (>50%). Escalating; not shipping unverified findings.`);
+}
+log(`verify: central=${centralClaims.length} votes(confirmed=${confirmedN} refuted=${refutedN} infra=${infraN})`);
+
+// -- Deepen (1 gap-driven round; reflection stop when sufficient — §4 normal cap=1) --
+phase('Deepen');
+const refutedCentral = centralClaims.filter((c) => (verdictByClaimId.get(c.claimId + '@' + c.sqId) || {}).verdict === 'refuted');
+const deepen = await agent([
+  `You are the **deepener** (lead tier). One gap round is allowed for mode normal.`,
+  `Current sub-questions: ${JSON.stringify(subQuestions.map((s) => ({ id: s.id, text: s.text })))}.`,
+  `Confirmed central claims: ${confirmedN}. Refuted central claims (need care, not silence): ${JSON.stringify(refutedCentral.map((c) => c.text))}.`,
+  `Supporting claims retained: ${retained.filter((c) => c.importance !== 'central').length}.`,
+  `Decide whether the evidence sufficiently answers the question. If a real gap remains (a facet unaddressed,`,
+  `a refuted-but-central point needing a replacement source), propose AT MOST 4 new sub-questions (ids sq-d1,sq-d2,…).`,
+  `If the evidence is sufficient, set sufficient=true and newSubQuestions=[] (reflection stop — do not invent busywork).`,
+].join('\n'), { model: 'opus', effort: 'high', phase: 'Deepen', label: 'deepen', schema: DEEPEN_SCHEMA });
+
+let deepenAdded = 0;
+if (!deepen.sufficient && (deepen.newSubQuestions || []).length) {
+  const newSqs = deepen.newSubQuestions.slice(0, 4).map((s) => ({ ...s, kind: 'independent', dependsOn: [] }));
+  deepenAdded = newSqs.length;
+  log(`deepen: gap round — ${deepenAdded} new sub-question(s)`);
+  const deepPairs = await pipeline(
+    newSqs,
+    (sq) => searchAgent(sq, subQuestions),
+    (searchRes, sq) => extractAgent(sq, searchRes).then((extract) => ({ sq, search: searchRes, extract })),
+  );
+  for (const r of deepPairs.filter(Boolean)) {
+    sqResults.set(r.sq.id, r);
+    for (const s of (r.search.sources || [])) urlBySourceId.set(s.sourceId, s.url);
+    for (const c of (r.extract.claims || [])) {
+      const claim = { ...c, sqId: r.sq.id, sqText: r.sq.text, url: urlBySourceId.get(c.sourceId) || null };
+      retained.push(claim); // deepen claims join the retained set (round-capped, so no re-cap loop)
+      if (claim.importance === 'central') {
+        const votes = (await parallel(VERIFY_LENSES.map((lens) => () => verifyAgent(claim, lens)))).filter(Boolean);
+        const refutes = votes.filter((v) => v.outcome === 'refuted').length;
+        verdictByClaimId.set(claim.claimId + '@' + claim.sqId, { verdict: refutes >= 2 ? 'refuted' : 'confirmed', votes });
+      }
+    }
+  }
+  subQuestions = subQuestions.concat(newSqs);
+} else {
+  log('deepen: reflection stop — evidence sufficient, no gap round');
+}
+
+// -- Synthesize (per-SQ finding files, then the session answer — §4.1 lead tier) --
+phase('Synthesize');
+function bucketsFor(sqId) {
+  const mine = retained.filter((c) => c.sqId === sqId);
+  const verified = [], refuted = [], supporting = [];
+  for (const c of mine) {
+    if (c.importance === 'central') {
+      const v = verdictByClaimId.get(c.claimId + '@' + c.sqId);
+      const entry = { claimId: c.claimId, text: c.text, quote: c.quote, sourceId: c.sourceId, votes: (v && v.votes) || [] };
+      (v && v.verdict === 'refuted' ? refuted : verified).push(entry);
+    } else {
+      supporting.push({ claimId: c.claimId, text: c.text, quote: c.quote, sourceId: c.sourceId, importance: c.importance });
+    }
+  }
+  return { verified, refuted, supporting };
+}
+const synthReceipts = (await parallel(
+  subQuestions
+    .filter((sq) => retained.some((c) => c.sqId === sq.id))
+    .map((sq) => () => synthAgent(sq, bucketsFor(sq.id))),
+)).filter(Boolean);
+
+// Unsourced ratio guard (§8): >10% unsourced → abort (do not mark done). mark-done is
+// the only status verb shipped, so "abort" = leave the session unfinalised + report.
+const totalClaimCount = synthReceipts.reduce((n, r) => n + (r.claimCount || 0), 0);
+const totalUnsourced = synthReceipts.reduce((n, r) => n + (r.unsourcedCount || 0), 0);
+const unsourcedRatio = totalClaimCount ? totalUnsourced / totalClaimCount : 0;
+
+// Aggregate sources.json deterministically (dedup = code, §4.1). Dedup by sourceId
+// (prefix-unique per searcher, so collisions are impossible) rather than by url:
+// that guarantees every id a finding references is present, which url-dedup could
+// break (the finding validator does not cross-check, but referential integrity is
+// cheap to keep). Searchers already de-dup within their own sub-question.
+const seenId = new Set();
+const sourceItems = [];
+for (const { search } of sqResults.values()) {
+  for (const s of (search.sources || [])) {
+    if (seenId.has(s.sourceId)) continue;
+    seenId.add(s.sourceId);
+    sourceItems.push({ id: s.sourceId, kind: s.kind, url: s.url, title: s.title });
+  }
+}
+const sourcesJson = JSON.stringify({ items: sourceItems }, null, 2);
+
+// Aggregate every searcher's gatedDropped[] into gate records for persistence
+// (w-018). The workflow has no fs, so the finaliser agent shells the record set to
+// `research gates --append`; the append happens here in Finalise, well after all
+// searchers have returned, so there is no write race with the search phase. Each
+// record carries its sub-question id so the swept queue stays traceable.
+const gateRecords = [];
+for (const { sq, search } of sqResults.values()) {
+  for (const g of (search.gatedDropped || [])) {
+    if (!g || !g.url || !g.gateType || !g.whatIsNeeded) continue;
+    gateRecords.push({ url: g.url, gateType: g.gateType, whatIsNeeded: g.whatIsNeeded, subQuestionId: sq.id });
+  }
+}
+
+const runStats = {
+  extracted: extractedCount, central: centralClaims.length,
+  confirmed: confirmedN, refuted: refutedN, unverifiedInfra: infraN,
+  budgetDropped, deepenAdded, unsourcedCount: totalUnsourced,
+  unsourcedRatio: Number(unsourcedRatio.toFixed(3)),
+  gatedDropped: gateRecords.length,
+};
+
+if (unsourcedRatio > UNSOURCED_ABORT_RATIO) {
+  log(`ABORT: unsourced ratio ${(unsourcedRatio * 100).toFixed(1)}% > 10% (§8 guardrail) — not marking done`);
+  return { sessionId, status: 'aborted', reason: 'unsourced ratio exceeded 10%', runStats, subQuestions: subQuestions.map((s) => s.id) };
+}
+
+// -- Finalise (persist gate records, write sources.json + the session answer, round-trip, mark done) --
+phase('Finalise');
+// The gate-persistence step is present only when searchers actually dropped gated
+// sources; otherwise the finaliser is told to skip it. A non-zero append exit is
+// reported but not fatal (a missed gate log is degraded, not a failed run).
+const gatesStep = gateRecords.length
+  ? [
+      `1. Persist gate records. ${gateRecords.length} background-posture gate(s) were dropped by searchers`,
+      `   during retrieval and must be logged to \`gates.json\` so a later operator-present session can sweep`,
+      `   them. Append them by piping this EXACT JSON array to \`research gates --append\` (use a heredoc so`,
+      `   the JSON reaches stdin verbatim):`,
+      '```bash',
+      `cat <<'GATES_EOF' | ${cli} gates --append ${sessionId}`,
+      JSON.stringify(gateRecords),
+      `GATES_EOF`,
+      '```',
+      `   Expect exit 0 and an "appended N gate(s)" line; set \`gatesAppended\` to N in your receipt. If it exits`,
+      `   NON-ZERO, put the error in \`note\`, set \`gatesAppended\` to 0, and CONTINUE — a missed gate log is`,
+      `   degraded, not fatal. Do NOT abort the finalise over it.`,
+    ].join('\n')
+  : `1. No gated sources were dropped this run — SKIP gate persistence entirely and set \`gatesAppended\` to 0.`;
+
+const finalise = await agent([
+  `You are the **finaliser** for session \`${sessionId}\` (output mode: \`${baseOutputMode}\`).`,
+  `Do these in order:`,
+  gatesStep,
+  `2. Write this EXACT JSON to \`${sessionDir}/sources.json\` (already URL-deduped by the workflow — write verbatim):`,
+  '```json', sourcesJson, '```',
+  `3. Read every \`${sessionDir}/findings/*.json\` and compose the session answer, writing it to \`${sessionDir}/answer.md\`:`,
+  `   - \`shortAnswer\`: a terse 2–4 sentence answer.`,
+  `   - \`article\`: prose with inline \`[source-id]\` citations.`,
+  `   - \`structured\`: a JSON code block with named sections.`,
+  `   For output mode \`${baseOutputMode}\`, use that form. ALWAYS include a "## Refuted / unverified claims" section`,
+  `   listing any refuted central claims for transparency (write "none" if there were none), and a "## Run stats" footer`,
+  `   with: ${JSON.stringify(runStats)}.`,
+  `4. Round-trip: run \`${cli} show ${sessionId} --json\` — it must exit 0 (validates plan, findings, sources, gates).`,
+  `5. Only if the round-trip is green, run \`${cli} mark done ${sessionId}\` (expect exit 0; sets status=done).`,
+  `Return the structured receipt (including \`gatesAppended\`).`,
+].join('\n'), { model: 'sonnet', effort: 'medium', phase: 'Finalise', label: 'finalise', schema: FINALISE_SCHEMA });
+
+const status = finalise.markedDone ? 'done' : 'in-progress';
+log(`finalise: sources=${finalise.wroteSources} answer=${finalise.wroteAnswer} roundTrip=${finalise.roundTripOk} markedDone=${finalise.markedDone} gatesAppended=${finalise.gatesAppended ?? 0}/${gateRecords.length}`);
+
+return {
+  sessionId,
+  status,
+  question: baseQuestion,
+  outputMode: baseOutputMode,
+  subQuestions: subQuestions.map((s) => ({ id: s.id, text: s.text, kind: s.kind })),
+  findings: synthReceipts,
+  runStats,
+  answerPath: `sessions/${sessionId}/answer.md`,
+};