@stravica-ai/digital-operator-pa 0.1.64 → 0.1.66

package/dist/engineering-pa-cli/src/research/README.md

@@ -167,6 +167,26 @@ of `--list`/`--retry`/`--append` is given, an invalid `<sessionId>`, bad JSON, o
 invalid record; `2` if an explicitly named session does not exist, or `--append` was
 handed zero records; `3` disk read/write failure.
 
+### `sources`: merge into the source registry
+
+```
+research sources --merge <sessionId> [--json]
+```
+
+Reads a source registry on stdin (`{ "items": [...] }` or a bare array of items) and
+merges it into the session's `sources.json` (w-2026-10-19-dave-009). The registry
+never loses items: every existing item is kept in place, an item with a new `id` is
+appended, and an item whose `id` is already present only fills fields the existing
+one lacks. Merging the same set twice adds nothing, so every workflow writer (the
+registry checkpoint, the finaliser, deep's finaliser) sends the full set through this
+verb instead of overwriting the file. The write goes through the store chokepoint
+(`store.writeSources` -> `validateSources`).
+
+Exit: `0` merged (prints `merged N new source(s) into <id> (M total)`, or
+`{ added, total }` with `--json`); `1` no `--merge`, a missing or invalid
+`<sessionId>`, bad JSON, or an item that fails the sources schema (nothing written);
+`2` the session does not exist; `3` disk read/write failure.
+
 ### `prune` — delete old / matching sessions
 
 ```
@@ -198,10 +218,25 @@ Sets `manifest.status` to a terminal value and bumps `updatedAt`:
 - **`done`** — the session finalised successfully. A completed research run (light
   recipe or the `research-normal.js` workflow) calls it to move the session out of
   `draft`/`in-progress` so `list --status done` becomes meaningful.
-- **`aborted`** — the session was abandoned before a usable answer. The
-  `research-normal.js` workflow's `>10%`-unsourced guardrail (build-spec §8) stamps a
-  run `aborted` so it reads correctly in `list`/`show` instead of lingering as
-  `in-progress`.
+- **`aborted`**: the run stopped short of a finished answer. The
+  `research-normal.js` workflow stamps `aborted` itself on every abort path, so the
+  session reads correctly in `list`/`show` instead of lingering as `draft`
+  (w-2026-10-19-dave-009):
+  - **Early unsourced guard** (after Search+Extract, before Rank, Verify, Deepen,
+    Synthesize and Finalise): more than 25 percent of the extracted assertions on
+    sourced-class sub-questions could not be grounded in a quote. The registry
+    checkpoint has already merged every searcher source into `sources.json` and
+    appended every `gatedDropped` record to `gates.json`; the same agent runs
+    `mark aborted`. No synthesis ran, so there is no `answer.md`.
+  - **Late abort** (after synthesis): the synth receipts show more than 10 percent
+    unsourced claims on sourced-class sub-questions (build-spec §8), or a planned
+    sub-question has no finding (coverage gap). The finaliser still merges the
+    registry, writes a partial `answer.md` (headed `# Partial answer (run aborted)`,
+    unsourced assertions tagged `[UNSOURCED]`, a `## Unsourced claims` section),
+    round-trips `show --json`, and runs `mark aborted`. The work is never discarded.
+
+  Sub-questions the planner classed `claimClass: "analysis"` (allocation shapes,
+  trade-offs, recommendations) are left out of both guards.
 
 This is the one verb that mutates an existing session's status. Both transitions are
 **one-way**: a session already `done` or `aborted` is refused (exit `2`), the same
@@ -295,9 +330,9 @@ All camelCase.
 | File | Location | Written by | Purpose |
 |---|---|---|---|
 | `manifest.json` | session root | this tool (`run`) | session identity, mode, gate policy, status, budget, assumptions |
-| `plan.json` | session root | `run` (skeleton) → workflow (subQuestions) | dependency-classified decomposition, rounds, verification tier |
+| `plan.json` | session root | `run` (skeleton) → workflow (subQuestions) | dependency-classified decomposition (each sub-question may carry `claimClass`: `sourced`, the default, or `analysis`), rounds, verification tier |
 | `findings/sq-<id>.json` | `findings/` | **workers** | one finding per sub-question: summary, quotes, sources, confidence, votes |
-| `sources.json` | session root | workflow | aggregated source registry referenced by findings |
+| `sources.json` | session root | `run` (empty) → `sources --merge` (workflow registry checkpoint after Search, after a deepen round, and the finaliser) | aggregated source registry referenced by findings; merged, never overwritten |
 | `gates.json` | session root | `gates --append` / `gates --retry` | human-gate retry queue |
 
 Enum values follow the build-spec's own spelling: `gatePolicy` is
@@ -322,7 +357,7 @@ packages/cli/src/research/
     validate.mjs             # shared hand-rolled validation primitives (zero-dep)
     manifest.mjs plan.mjs findings.mjs sources.mjs gates.mjs
   commands/
-    run.mjs list.mjs show.mjs gates.mjs prune.mjs mark.mjs paths.mjs
+    run.mjs list.mjs show.mjs gates.mjs sources.mjs prune.mjs mark.mjs paths.mjs
   schema/
     *.schema.json            # documentation-grade JSON Schemas (camelCase)
   briefs/                    # dispatch briefs the /research skill workflow feeds to subagents

package/dist/engineering-pa-cli/src/research/cli.mjs

@@ -41,6 +41,11 @@ Usage:
       --append reads gate records (JSON array on stdin, or --record '<json>' for a
       single one) and appends them to the session's gates.json with fresh g-N ids.
 
+  research sources --merge <sessionId> [--json]
+      Merge a source registry ({ "items": [...] } or an array, on stdin) into the
+      session's sources.json. Existing items are never dropped or overwritten; new
+      ids are appended. Idempotent, so every workflow writer can send the full set.
+
   research prune [--older-than <days>] [--status <status>] [--dry-run]
       Delete sessions older than N days and/or matching a status. At least one
       filter is required. --dry-run prints what would be deleted without deleting.
@@ -92,6 +97,10 @@ export async function main(argv) {
         const { gatesCommand } = await import('./commands/gates.mjs');
         return (await gatesCommand(rest)) ?? 0;
       }
+      case 'sources': {
+        const { sourcesCommand } = await import('./commands/sources.mjs');
+        return (await sourcesCommand(rest)) ?? 0;
+      }
       case 'prune': {
         const { pruneCommand } = await import('./commands/prune.mjs');
         return (await pruneCommand(rest)) ?? 0;

package/dist/engineering-pa-cli/src/research/commands/sources.mjs

@@ -0,0 +1,64 @@
+// research sources --merge <sessionId> [--json]
+//
+// Reads a source registry from stdin ({ "items": [...] } or a bare array of items)
+// and merges it into the session's sources.json (w-2026-10-19-dave-009). Existing
+// items are never dropped or overwritten: new ids are appended, a known id only gains
+// fields it lacked. Merging the same set twice is a no-op, so the workflow's
+// persister and finaliser can both send the full registry. The write goes through
+// the store chokepoint (store.writeSources -> validateSources).
+import { parseArgs } from 'node:util';
+import { getDefaultStore } from '../store/index.mjs';
+import { mergeSources } from '../store/sources.mjs';
+
+function usage(msg) {
+  return Object.assign(new Error(`usage: research sources --merge <sessionId> [--json]${msg ? `\n${msg}` : ''}`), { exitCode: 1 });
+}
+function notFound(msg) {
+  return Object.assign(new Error(msg), { exitCode: 2 });
+}
+
+async function readAllStdin(stream = process.stdin) {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export async function sourcesCommand(argv, { store, stdout = process.stdout, readStdin = readAllStdin } = {}) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: { merge: { type: 'boolean' }, json: { type: 'boolean' } }, allowPositionals: true, strict: true });
+  } catch (e) {
+    throw usage(e.message);
+  }
+  if (!parsed.values.merge) throw usage('--merge is required');
+  const id = parsed.positionals[0];
+  if (!id) throw usage('--merge requires a <sessionId>');
+  if (parsed.positionals.length > 1) throw usage('--merge takes exactly one <sessionId>');
+  if (!store) store = await getDefaultStore();
+  if (!store.isValidSessionId(id)) throw usage(`"${id}" is not a valid sessionId`);
+  if (!store.exists(id)) throw notFound(`session ${id} not found`);
+
+  const text = await readStdin();
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw usage(`invalid JSON on stdin: ${e.message}`);
+  }
+  const incoming = Array.isArray(raw) ? { items: raw } : raw;
+  const existing = await store.readSources(id);
+  let merged;
+  try {
+    merged = mergeSources(existing, incoming, `session ${id} sources`);
+  } catch (e) {
+    // A malformed incoming registry is caller input: usage error, nothing written.
+    throw usage(e.message);
+  }
+  await store.writeSources(id, merged.sources);
+  if (parsed.values.json) {
+    stdout.write(JSON.stringify({ added: merged.added, total: merged.sources.items.length }, null, 2) + '\n');
+    return 0;
+  }
+  stdout.write(`merged ${merged.added} new source(s) into ${id} (${merged.sources.items.length} total)\n`);
+  return 0;
+}

package/dist/engineering-pa-cli/src/research/engine/deep.mjs

@@ -17,7 +17,7 @@ import { flattenClaims, rankAndCapPerSq } from './rank.mjs';
 import { adjudicate } from './verify.mjs';
 import { verifyAgent } from './agents.mjs';
 import { runDeepenRound, deepenStopReason } from './deepen.mjs';
-import { buildSourcesJson, buildGateRecords, bucketsFor, synthOrDegrade } from './finalise.mjs';
+import { buildSourcesJson, buildGateRecords, bucketsFor, synthOrDegrade, sourcesMergeStep } from './finalise.mjs';
 
 // Guaranteed floor of top claims kept per sub-question when the claim budget is capped
 // (deep-mode fix for SQ starvation). 1 = every planned sub-question keeps its single best
@@ -401,8 +401,7 @@ export async function runDeepFinalise(ctx, { sqResults, roundsJson, costFields,
     `You are the **finaliser** for deep-research session \`${ctx.sessionId}\` (output mode: \`${ctx.baseOutputMode}\`).`,
     `Do these in order; every JSON below is already validated by the workflow — write it VERBATIM.`,
     `1. ${gatesStep}`,
-    `2. Write this EXACT JSON to \`${ctx.sessionDir}/sources.json\`:`,
-    '```json', sourcesJson, '```',
+    sourcesMergeStep(ctx, sourcesJson, 2),
     `3. Write this EXACT JSON to \`${ctx.sessionDir}/rounds.json\` (the deepen audit trail):`,
     '```json', roundsJson, '```',
     `4. Compose cost.json. Take these workflow-measured fields VERBATIM:`,

package/dist/engineering-pa-cli/src/research/engine/deepen.mjs

@@ -37,6 +37,25 @@ export function deepenStopReason({ sufficient, round, roundCap, budgetRemaining,
   return null;
 }
 
+// Give every deepen proposal an id no live sub-question holds (w-2026-10-19-dave-009).
+// A reused id (deep round 2 proposing sq-d1 again, or a clash with a planner id) would
+// overwrite that sub-question's entry in sqResults, and its searcher sources with it,
+// so the registry built from sqResults would lose them. Clashing ids take the next free
+// sq-dN; fresh ids are kept. Pure.
+export function uniqueDeepenIds(proposals, liveIds) {
+  const taken = new Set(liveIds);
+  for (const p of proposals) if (!taken.has(p.id)) taken.add(p.id);
+  const seen = new Set(liveIds);
+  let n = 1;
+  return proposals.map((p) => {
+    if (!seen.has(p.id)) { seen.add(p.id); return p; }
+    while (taken.has(`sq-d${n}`)) n += 1;
+    const id = `sq-d${n}`;
+    taken.add(id); seen.add(id);
+    return { ...p, id };
+  });
+}
+
 // One gap-driven deepen round. Asks the deepener whether a real gap remains; if so,
 // searches+extracts the proposed facets, appends their claims to `state.retained`,
 // and re-verifies newly-central claims. Mutates state.{sqResults,urlBySourceId,
@@ -64,7 +83,8 @@ export async function runDeepenRound(ctx, state, { lenses = VERIFY_LENSES, quoru
   let deepenAdded = 0;
   let newSqs = [];
   if (!deepen.sufficient && (deepen.newSubQuestions || []).length) {
-    newSqs = deepen.newSubQuestions.slice(0, 4).map((s) => ({ ...s, kind: 'independent', dependsOn: [] }));
+    const liveIds = [...subQuestions.map((s) => s.id), ...sqResults.keys()];
+    newSqs = uniqueDeepenIds(deepen.newSubQuestions.slice(0, 4), liveIds).map((s) => ({ ...s, kind: 'independent', dependsOn: [] }));
     deepenAdded = newSqs.length;
     log(`deepen: gap round — ${deepenAdded} new sub-question(s)`);
     const deepPairs = await pipeline(

package/dist/engineering-pa-cli/src/research/engine/finalise.mjs

@@ -1,9 +1,67 @@
 // Shared research engine — synthesis bucketing, deterministic aggregation
 // (sources.json / gate records), and the synth + finalise phases.
 import { synthAgent, SYNTH_SCHEMA } from './agents.mjs';
+import { effectiveClaimClass } from './plan.mjs';
 
 export const UNSOURCED_ABORT_RATIO = 0.10;      // §8 guardrail: >10% unsourced fails the run
 
+// Early unsourced guard (w-2026-10-19-dave-009). Runs on the extractor returns,
+// before Verify and the deepen round, so an abort skips the expensive stages. Its
+// measure is the share of answer-relevant assertions the extractors could not ground
+// in a quote: unsourcedClaims / (claims emitted + unsourcedClaims), over sourced-class
+// sub-questions only. Those assertions are dropped, not answered, so the bar is not
+// the answer's 10 percent: across the nine normal runs journalled to 2026-10-19 the
+// runs that synthesized cleanly measured 7 to 17 percent here, and the two that
+// failed measured 30 and 37 percent. 0.25 separates them; tune it from new runs.
+export const EXTRACT_UNSOURCED_ABORT_RATIO = 0.25;
+
+// Pure: extractor-level unsourced counts over the planner's sub-questions. Analysis
+// sub-questions (claimClass 'analysis') are left out of both sides of the ratio and
+// listed in `ignored`.
+export function extractUnsourcedReport(subQuestions, sqResults) {
+  let sourcedCount = 0;
+  let unsourcedCount = 0;
+  const ignored = [];
+  const unsourcedBySq = {};
+  for (const sq of subQuestions) {
+    if (effectiveClaimClass(sq) === 'analysis') { ignored.push(sq.id); continue; }
+    const r = sqResults.get(sq.id);
+    if (!r || !r.extract) continue;
+    const emitted = (r.extract.claims || []).length;
+    const unsourced = Number.isInteger(r.extract.unsourcedClaims) ? r.extract.unsourcedClaims : 0;
+    sourcedCount += emitted;
+    unsourcedCount += unsourced;
+    if (unsourced) unsourcedBySq[sq.id] = unsourced;
+  }
+  const total = sourcedCount + unsourcedCount;
+  return { sourcedCount, unsourcedCount, ratio: total ? unsourcedCount / total : 0, ignored, unsourcedBySq };
+}
+
+// Pure: synthesis-level unsourced counts from the synth receipts (claimCount and
+// unsourcedCount), with analysis sub-questions left out. Used after synthesis, where an
+// over-threshold ratio no longer discards the work: the finaliser writes a partial
+// answer.md with the unsourced claims marked and stamps the session aborted.
+export function synthUnsourcedReport(subQuestions, synthReceipts) {
+  const analysis = new Set(subQuestions.filter((sq) => effectiveClaimClass(sq) === 'analysis').map((sq) => sq.id));
+  let claimCount = 0;
+  let unsourcedCount = 0;
+  const ignored = [];
+  const unsourcedBySq = {};
+  for (const r of synthReceipts || []) {
+    if (!r || !r.subQuestionId) continue;
+    if (analysis.has(r.subQuestionId)) { ignored.push(r.subQuestionId); continue; }
+    claimCount += r.claimCount || 0;
+    unsourcedCount += r.unsourcedCount || 0;
+    if (r.unsourcedCount) unsourcedBySq[r.subQuestionId] = r.unsourcedCount;
+  }
+  return { claimCount, unsourcedCount, ratio: claimCount ? unsourcedCount / claimCount : 0, ignored, unsourcedBySq };
+}
+
+// The guard decision: strictly over the threshold aborts; equal does not.
+export function unsourcedAbort(report, threshold) {
+  return report.ratio > threshold;
+}
+
 export const FINALISE_SCHEMA = {
   type: 'object', additionalProperties: false,
   required: ['wroteSources', 'wroteAnswer', 'roundTripOk', 'markedDone'],
@@ -13,6 +71,19 @@ export const FINALISE_SCHEMA = {
     roundTripOk: { type: 'boolean' },
     markedDone: { type: 'boolean' },
     gatesAppended: { type: 'integer' }, // count of gatedDropped records persisted to gates.json (w-018)
+    markedAborted: { type: 'boolean' }, // partial finalise only: `research mark aborted` exited 0
+    note: { type: 'string' },
+  },
+};
+
+export const PERSIST_SCHEMA = {
+  type: 'object', additionalProperties: false,
+  required: ['mergedSources', 'gatesAppended', 'roundTripOk'],
+  properties: {
+    mergedSources: { type: 'boolean' },
+    gatesAppended: { type: 'integer' },
+    roundTripOk: { type: 'boolean' },
+    markedAborted: { type: 'boolean' },
     note: { type: 'string' },
   },
 };
@@ -165,43 +236,110 @@ export function coverageReport(subQuestionIds, synthReceipts) {
   };
 }
 
-// -- Finalise (persist gate records, write sources.json + the session answer, round-trip, mark done) --
-export async function runFinalise(ctx, { gateRecords, sourcesJson, runStats }) {
-  // 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
+// Prompt step: merge the registry through `research sources --merge` (never an
+// overwrite of sources.json, so an item another writer already put there survives).
+export function sourcesMergeStep(ctx, sourcesJson, n) {
+  return [
+    `${n}. Merge the source registry. Pipe this EXACT JSON to \`research sources --merge\` (use a heredoc so it`,
+    `   reaches stdin verbatim). It merges into \`${ctx.sessionDir}/sources.json\`; never write that file directly:`,
+    '```bash',
+    `cat <<'SOURCES_EOF' | ${ctx.cli} sources --merge ${ctx.sessionId}`,
+    sourcesJson,
+    `SOURCES_EOF`,
+    '```',
+    `   Expect exit 0 and a "merged N new source(s)" line.`,
+  ].join('\n');
+}
+
+// Prompt step: append gate records through `research gates --append`, or skip. A
+// non-zero append exit is reported but not fatal (a missed gate log is degraded).
+export function gateAppendStep(ctx, gateRecords, n) {
+  if (!gateRecords.length) return `${n}. No gate records to persist at this step. SKIP gate persistence and set \`gatesAppended\` to 0.`;
+  return [
+    `${n}. 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' | ${ctx.cli} gates --append ${ctx.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 over it.`,
+  ].join('\n');
+}
+
+// True when a receipt shows every record of this batch landed in gates.json
+// (`gates --append` validates the whole file before writing, so it is all or none).
+export function gatesPersisted(receipt, gateRecords) {
+  return !gateRecords.length || (receipt && receipt.gatesAppended === gateRecords.length);
+}
+
+// -- Registry checkpoint (w-2026-10-19-dave-009) --
+// The workflow has no fs, so the sources and gate records the searchers return live
+// only in memory until an agent persists them. Before this checkpoint they were
+// written by the finaliser alone, after the unsourced guard, so a guard abort lost
+// them all. The persister runs right after Search+Extract (and after a deepen round
+// that added sub-questions): it merges the registry, appends the gate records and,
+// when the early guard fired, stamps the session aborted. Mechanical, so a cheap tier.
+export async function runPersistRegistry(ctx, { sourcesJson, gateRecords, markAborted = false, reason = '', label = 'persist', phase: agentPhase = 'Search' }) {
+  const steps = [
+    `You are the **registry persister** for research session \`${ctx.sessionId}\`. Do these in order:`,
+    sourcesMergeStep(ctx, sourcesJson, 1),
+    gateAppendStep(ctx, gateRecords, 2),
+    `3. Round-trip: run \`${ctx.cli} show ${ctx.sessionId} --json\` and confirm exit 0; set \`roundTripOk\`.`,
+  ];
+  if (markAborted) {
+    steps.push(`4. The run is aborting (${reason}). Run \`${ctx.cli} mark aborted ${ctx.sessionId}\` (expect exit 0) and set \`markedAborted\`.`);
+  }
+  steps.push(`Return the structured receipt (mergedSources, gatesAppended, roundTripOk${markAborted ? ', markedAborted' : ''}).`);
+  // A failed persister agent (null return) reads as nothing persisted, so the caller
+  // keeps the gate records pending for the finaliser instead of throwing.
+  const receipt = await agent(steps.join('\n'), { model: ctx.modelOverride || 'haiku', effort: 'low', phase: agentPhase, label, schema: PERSIST_SCHEMA });
+  return receipt || { mergedSources: false, gatesAppended: 0, roundTripOk: false, markedAborted: false };
+}
+
+// -- Finalise (merge sources.json, persist pending gate records, write the session answer, round-trip, mark) --
+// `gateRecords` are the records the registry checkpoints could not persist (normally
+// none). With `partial` set, the run is aborting after synthesis: the finaliser still
+// writes answer.md, as a partial answer with the unsourced claims marked, and stamps
+// the session aborted instead of done, so the work is never discarded.
+export async function runFinalise(ctx, { gateRecords, sourcesJson, runStats, partial = null }) {
+  const answerStep = partial
     ? [
-        `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' | ${ctx.cli} gates --append ${ctx.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.`,
+        `3. This run is ABORTING after synthesis: ${partial.reason}. Do not discard the work. Read every`,
+        `   \`${ctx.sessionDir}/findings/*.json\` and write a PARTIAL answer to \`${ctx.sessionDir}/answer.md\`:`,
+        `   - First line: \`# Partial answer (run aborted)\`, then a line \`> Run aborted: ${partial.reason}. Claims marked [UNSOURCED] have no supporting quote.\``,
+        `   - Then the answer in the \`${ctx.baseOutputMode}\` form, built only from the findings on disk.`,
+        `   - Mark every assertion from a finding with \`"unsourced": true\` that has no quote behind it with the literal tag \`[UNSOURCED]\`.`,
+        `   - A "## Unsourced claims" section listing the per-sub-question unsourced counts ${JSON.stringify(partial.unsourcedBySq || {})}`,
+        `     and the analysis sub-questions the guard ignored ${JSON.stringify(partial.ignored || [])}.`,
+        `   - ALWAYS a "## Refuted / unverified claims" section (write "none" if there were none) and a "## Run stats" footer`,
+        `     with: ${JSON.stringify(runStats)}.`,
       ].join('\n')
-    : `1. No gated sources were dropped this run — SKIP gate persistence entirely and set \`gatesAppended\` to 0.`;
+    : [
+        `3. Read every \`${ctx.sessionDir}/findings/*.json\` and compose the session answer, writing it to \`${ctx.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 \`${ctx.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)}.`,
+      ].join('\n');
+  const markStep = partial
+    ? `5. Only if the round-trip is green, run \`${ctx.cli} mark aborted ${ctx.sessionId}\` (expect exit 0; sets status=aborted, never promoted) and set \`markedAborted\`; set \`markedDone\` to false.`
+    : `5. Only if the round-trip is green, run \`${ctx.cli} mark done ${ctx.sessionId}\` (expect exit 0; sets status=done).`;
 
   return await agent([
     `You are the **finaliser** for session \`${ctx.sessionId}\` (output mode: \`${ctx.baseOutputMode}\`).`,
     `Do these in order:`,
-    gatesStep,
-    `2. Write this EXACT JSON to \`${ctx.sessionDir}/sources.json\` (already URL-deduped by the workflow — write verbatim):`,
-    '```json', sourcesJson, '```',
-    `3. Read every \`${ctx.sessionDir}/findings/*.json\` and compose the session answer, writing it to \`${ctx.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 \`${ctx.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)}.`,
+    gateAppendStep(ctx, gateRecords, 1),
+    sourcesMergeStep(ctx, sourcesJson, 2),
+    answerStep,
     `4. Round-trip: run \`${ctx.cli} show ${ctx.sessionId} --json\` — it must exit 0 (validates plan, findings, sources, gates).`,
-    `5. Only if the round-trip is green, run \`${ctx.cli} mark done ${ctx.sessionId}\` (expect exit 0; sets status=done).`,
+    markStep,
     `Return the structured receipt (including \`gatesAppended\`).`,
   ].join('\n'), { model: 'sonnet', effort: 'medium', phase: 'Finalise', label: 'finalise', schema: FINALISE_SCHEMA });
 }

package/dist/engineering-pa-cli/src/research/engine/plan.mjs

@@ -53,6 +53,14 @@ export function topoOrder(subQuestions) {
   return order;
 }
 
+// Claim class per sub-question (w-2026-10-19-dave-009). 'analysis' marks an
+// allocation shape, trade-off or recommendation: its claims are inference over other
+// findings, so the unsourced guard ignores it. Anything else counts as 'sourced'.
+export const CLAIM_CLASSES = ['sourced', 'analysis'];
+export function effectiveClaimClass(sq) {
+  return sq && sq.claimClass === 'analysis' ? 'analysis' : 'sourced';
+}
+
 // The plan schema, parameterised by facet band (normal 2–4, deep 4–12).
 export function makePlanSchema({ minItems = 2, maxItems = 4 } = {}) {
   return {
@@ -68,12 +76,13 @@ export function makePlanSchema({ minItems = 2, maxItems = 4 } = {}) {
         type: 'array', minItems, maxItems,
         items: {
           type: 'object', additionalProperties: false,
-          required: ['id', 'text', 'kind', 'dependsOn'],
+          required: ['id', 'text', 'kind', 'dependsOn', 'claimClass'],
           properties: {
             id: { type: 'string' },
             text: { type: 'string' },
             kind: { enum: ['independent', 'dependent'] },
             dependsOn: { type: 'array', items: { type: 'string' } },
+            claimClass: { enum: CLAIM_CLASSES },
           },
         },
       },
@@ -97,8 +106,12 @@ export async function runPlan(ctx, { min = 2, max = 4 } = {}) {
     `   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.`,
+    `   Set each sub-question's \`claimClass\` from its shape: \`analysis\` when it asks for an allocation shape, a`,
+    `   trade-off or a recommendation (typically a dependent facet that weighs the others' findings), because its`,
+    `   claims are inference and the unsourced guard ignores them; \`sourced\` for every facet answered from quotable`,
+    `   sources (facts, figures, rules, prices, mechanisms). When unsure, use \`sourced\`.`,
     `3. WRITE the filled plan back to \`${ctx.sessionDir}/plan.json\`: keep the existing \`deepeningRounds\` and`,
-    `   \`verificationTier\`, replace \`subQuestions\` with your list (each {id,text,kind,dependsOn}). No extra fields.`,
+    `   \`verificationTier\`, replace \`subQuestions\` with your list (each {id,text,kind,dependsOn,claimClass}). No extra fields.`,
     `4. Round-trip: run \`${ctx.cli} show ${ctx.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.`,
@@ -124,6 +137,8 @@ export async function runPlan(ctx, { min = 2, max = 4 } = {}) {
     if (errs.length) throw new Error(`${ctx.workflow}: planner produced an invalid plan twice (${errs.join('; ')}) — escalating`);
   }
   log(`plan: ${subQuestions.length} sub-questions — ${subQuestions.map((s) => s.id).join(', ')}`);
+  const analysisIds = subQuestions.filter((s) => effectiveClaimClass(s) === 'analysis').map((s) => s.id);
+  if (analysisIds.length) log(`plan: claimClass analysis (ignored by the unsourced guard): ${analysisIds.join(', ')}`);
   ctx.subQuestions = subQuestions;
   return subQuestions;
 }

package/dist/engineering-pa-cli/src/research/schema/plan.schema.json

@@ -22,6 +22,12 @@
             "type": "array",
             "items": { "type": "string" },
             "description": "Sub-question ids this one depends on. Empty for independent facets."
+          },
+          "claimClass": {
+            "type": "string",
+            "enum": ["sourced", "analysis"],
+            "default": "sourced",
+            "description": "Set by the planner from the sub-question shape. analysis = an allocation shape, trade-off or recommendation whose claims are inference; the unsourced guard ignores it. Optional; absent means sourced (w-2026-10-19-dave-009)."
           }
         }
       }

package/dist/engineering-pa-cli/src/research/store/plan.mjs

@@ -6,10 +6,15 @@ import {
 } from './validate.mjs';
 
 export const SQ_KINDS = ['independent', 'dependent'];
+// claimClass (w-2026-10-19-dave-009): 'analysis' marks an allocation, trade-off or
+// recommendation sub-question whose claims are inference, so the unsourced guard
+// ignores it. Optional; absent means 'sourced', so every older plan.json validates.
+export const CLAIM_CLASSES = ['sourced', 'analysis'];
 export const VERIFICATION_TIERS = ['none', 'central-3vote', 'diverse-lens-3vote'];
 
 const TOP = ['subQuestions', 'deepeningRounds', 'verificationTier'];
 const SQ_FIELDS = ['id', 'text', 'kind', 'dependsOn'];
+const SQ_OPTIONAL = ['claimClass'];
 
 // Mode-derived plan defaults. `run` writes the skeleton; the workflow (w-017)
 // fills subQuestions. Single source of truth for the light/normal/deep mapping.
@@ -41,12 +46,13 @@ export function validatePlan(p, where = 'plan') {
     const w = `${where}.subQuestions[${i}]`;
     requireObject(sq, w);
     requireFields(sq, SQ_FIELDS, w);
-    noExtraFields(sq, SQ_FIELDS, w);
+    noExtraFields(sq, [...SQ_FIELDS, ...SQ_OPTIONAL], w);
     const id = requireString(sq, 'id', w);
     if (seen.has(id)) fail(`duplicate sub-question id "${id}"`, w);
     seen.add(id);
     requireString(sq, 'text', w);
     requireEnum(sq, 'kind', SQ_KINDS, w);
+    if (sq.claimClass !== undefined) requireEnum(sq, 'claimClass', CLAIM_CLASSES, w);
     const deps = requireArray(sq, 'dependsOn', w);
     deps.forEach((d, j) => {
       if (typeof d !== 'string') fail(`dependsOn[${j}] must be a string`, w);

package/dist/engineering-pa-cli/src/research/store/sources.mjs

@@ -42,3 +42,32 @@ export function validateSources(s, where = 'sources') {
   });
   return s;
 }
+
+// Merge an incoming registry into an existing one (w-2026-10-19-dave-009). The
+// registry never loses items: every existing item is kept in its place, an incoming
+// item with a new id is appended, and an incoming item whose id is already present
+// only fills fields the existing item lacks (an existing field is never overwritten).
+// Pure; both inputs are validated, and the merged result is validated before return.
+// Merging the same set twice adds nothing, so writers can re-send the full registry.
+export function mergeSources(existing, incoming, where = 'sources') {
+  validateSources(existing, `${where} (existing)`);
+  validateSources(incoming, `${where} (incoming)`);
+  const items = existing.items.map((it) => ({ ...it }));
+  const byId = new Map(items.map((it) => [it.id, it]));
+  let added = 0;
+  for (const it of incoming.items) {
+    const have = byId.get(it.id);
+    if (!have) {
+      const copy = { ...it };
+      items.push(copy);
+      byId.set(copy.id, copy);
+      added += 1;
+      continue;
+    }
+    for (const k of ITEM_FIELDS) {
+      if (have[k] === undefined && it[k] !== undefined) have[k] = it[k];
+    }
+  }
+  const sources = validateSources({ items }, where);
+  return { sources, added };
+}