@stravica-ai/digital-operator-pa 0.1.5 → 0.1.7

package/dist/engineering-pa-cli/package.json

@@ -31,6 +31,8 @@
     "node": ">=24"
   },
   "scripts": {
+    "assemble": "node src/research/assemble.mjs",
+    "pretest": "node src/research/assemble.mjs --check",
     "test": "node --test --test-isolation=none 'test/**/*.test.mjs'"
   },
   "//": "test pins --test-isolation=none: default process-isolation mode silently undercounts (drops passed tests from totals) when a test awaits async work while stdout is patched by a capture() helper — see packages/cli/test/secrets. Counts must never lie."

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

@@ -0,0 +1,281 @@
+// Zero-dependency assembler: wrappers/<mode>.mjs + engine/*.mjs → workflows/research-<mode>.js
+//
+// A wrapper is a real ES module (named imports from ../engine/*.mjs, one
+// `export const meta = {…}` literal, and the run body). The assembler transitively
+// closes the engine graph from the wrapper's imports, emits the reachable modules
+// deps-first (Kahn, lexicographic tie-break), strips import/export syntax, and
+// prepends the meta literal + a provenance header. Output is a single self-contained
+// script the harness can run: plain JS, `export const meta` the sole export, zero
+// imports, no Node APIs, no clock/randomness.
+//
+// Determinism: no clock, no randomness, no readdir-order dependence in the emit
+// (module order is the topo sort). Same sources → byte-identical output → the
+// pretest git-clean gate can detect drift, and normal's parity diff stays meaningful.
+//
+// Refusals (§2.8): import cycle, duplicate top-level identifier, >1 export / export
+// ≠ meta, dynamic import()/Node builtin, Date.now()/Math.random()/argless new Date(),
+// non-relative specifier, or a syntax-invalid output — each throws with no partial file.
+import { readFileSync, writeFileSync, unlinkSync, readdirSync, existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ENGINE_DIR = join(HERE, 'engine');
+const WRAPPERS_DIR = join(HERE, 'wrappers');
+const WORKFLOWS_DIR = join(HERE, 'workflows');
+
+// ── source scans ────────────────────────────────────────────────────────────────
+
+const IMPORT_RE = /^[ \t]*import\s*(?:\{([^}]*)\}|[\w$]+|\*\s+as\s+[\w$]+)\s*from\s*['"]([^'"]+)['"]\s*;?[ \t]*$/gm;
+const ANY_IMPORT_LINE_RE = /^[ \t]*import\b.*$/gm;
+
+// Parse `import { a, b } from '<spec>'` lines into { names, spec } records.
+export function parseImports(source) {
+  const out = [];
+  for (const m of source.matchAll(IMPORT_RE)) {
+    const names = (m[1] || '').split(',').map((s) => s.trim()).filter(Boolean).map((s) => s.split(/\s+as\s+/)[0].trim());
+    out.push({ names, spec: m[2] });
+  }
+  return out;
+}
+
+// Reject anything that cannot run in the harness (§2.8). `label` names the file.
+export function assertNoForbidden(source, label) {
+  if (/\bimport\s*\(/.test(source)) throw new Error(`assemble: dynamic import() in ${label} — the harness cannot resolve it`);
+  if (/\brequire\s*\(/.test(source)) throw new Error(`assemble: require() in ${label} — engine must be self-contained`);
+  if (/\bnode:[a-z/]+/.test(source)) throw new Error(`assemble: Node builtin (node:*) referenced in ${label} — not available at runtime`);
+  if (/\bDate\.now\s*\(/.test(source)) throw new Error(`assemble: Date.now() in ${label} — harness-forbidden (non-determinism)`);
+  if (/\bMath\.random\s*\(/.test(source)) throw new Error(`assemble: Math.random() in ${label} — harness-forbidden (non-determinism)`);
+  if (/\bnew\s+Date\s*\(\s*\)/.test(source)) throw new Error(`assemble: argless new Date() in ${label} — harness-forbidden (non-determinism)`);
+  for (const { spec } of parseImports(source)) {
+    if (!spec.startsWith('./') && !spec.startsWith('../')) {
+      throw new Error(`assemble: non-relative import "${spec}" in ${label} — engine must be self-contained`);
+    }
+  }
+}
+
+const moduleKey = (spec) => basename(spec, '.mjs');
+
+// The engine modules a source depends on (relative specifiers resolving into engine/).
+function engineDepsOf(source, engineKeys) {
+  const deps = [];
+  for (const { spec } of parseImports(source)) {
+    const key = moduleKey(spec);
+    if (engineKeys.has(key)) deps.push(key);
+  }
+  return [...new Set(deps)];
+}
+
+// ── module syntax stripping ───────────────────────────────────────────────────
+
+// Drop every import line and the leading `export ` keyword; nothing else changes.
+export function stripModuleSyntax(source) {
+  return source.replace(ANY_IMPORT_LINE_RE, '').replace(/^export\s+/gm, '');
+}
+
+// Refuse if two inlined units declare the same top-level identifier (§2.3). This is
+// what makes "one engine, many wrappers" collision-free. units: [{ label, ids }].
+export function assertDisjointIdentifiers(units) {
+  const seen = new Map();
+  for (const { label, ids } of units) {
+    for (const id of ids) {
+      if (seen.has(id)) throw new Error(`assemble: duplicate identifier "${id}" from ${seen.get(id)} and ${label}`);
+      seen.set(id, label);
+    }
+  }
+}
+
+// Top-level declared identifiers (for cross-module collision detection).
+export function topLevelIdentifiers(strippedSource) {
+  const ids = [];
+  const patterns = [
+    /^(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/gm,
+    /^const\s+([A-Za-z_$][\w$]*)/gm,
+    /^let\s+([A-Za-z_$][\w$]*)/gm,
+    /^var\s+([A-Za-z_$][\w$]*)/gm,
+    /^class\s+([A-Za-z_$][\w$]*)/gm,
+  ];
+  for (const re of patterns) for (const m of strippedSource.matchAll(re)) ids.push(m[1]);
+  return ids;
+}
+
+// ── wrapper meta extraction ───────────────────────────────────────────────────
+
+// Find the matching close brace for the `{` at `open`, honouring string literals.
+function matchBrace(source, open) {
+  let depth = 0, i = open, quote = null;
+  for (; i < source.length; i++) {
+    const ch = source[i];
+    if (quote) {
+      if (ch === '\\') { i++; continue; }
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') { quote = ch; continue; }
+    if (ch === '{') depth++;
+    else if (ch === '}') { depth--; if (depth === 0) return i; }
+  }
+  throw new Error('assemble: unterminated meta object literal in wrapper');
+}
+
+// Split a wrapper into { metaText, residual } — residual is the wrapper with all
+// import lines and the `export const meta = {…};` declaration removed.
+export function extractMeta(wrapperSource, label) {
+  const exports = [...wrapperSource.matchAll(/^export\s+(?:const\s+([\w$]+)|.*)/gm)].map((m) => m[1]);
+  if (exports.length !== 1 || exports[0] !== 'meta') {
+    throw new Error(`assemble: wrapper ${label} must export exactly one symbol (meta), found: ${exports.map((e) => e || '<non-const>').join(', ') || 'none'}`);
+  }
+  const declIdx = wrapperSource.indexOf('export const meta');
+  const braceOpen = wrapperSource.indexOf('{', declIdx);
+  if (declIdx < 0 || braceOpen < 0) throw new Error(`assemble: wrapper ${label} must declare "export const meta = { … }"`);
+  const braceClose = matchBrace(wrapperSource, braceOpen);
+  let end = braceClose + 1;
+  while (end < wrapperSource.length && wrapperSource[end] !== ';') end++;
+  end++; // consume the ';'
+  const metaText = wrapperSource.slice(braceOpen, braceClose + 1);
+  const residual = (wrapperSource.slice(0, declIdx) + wrapperSource.slice(end))
+    .replace(ANY_IMPORT_LINE_RE, '');
+  return { metaText, residual };
+}
+
+// ── topological order (Kahn, lexicographic tie-break) ─────────────────────────
+
+export function topoSort(reachable, depsOf) {
+  const emitted = [];
+  const done = new Set();
+  const remaining = new Set(reachable);
+  while (remaining.size) {
+    const ready = [...remaining].filter((k) => depsOf(k).every((d) => done.has(d))).sort();
+    if (!ready.length) {
+      throw new Error(`assemble: import cycle among engine modules: ${[...remaining].sort().join(', ')}`);
+    }
+    const next = ready[0];
+    emitted.push(next);
+    done.add(next);
+    remaining.delete(next);
+  }
+  return emitted;
+}
+
+// ── syntax gate ───────────────────────────────────────────────────────────────
+
+// `node --check` the emitted artifact. The harness runs a workflow inside an async
+// wrapper (top-level `return`/`await` + injected `agent`/`args`/… globals), so a raw
+// `node --check` on the file rejects the legal top-level `return`. We check the same
+// harness shape: strip the sole `export`, wrap the body, and syntax-check that.
+export function checkWorkflowSyntax(source, label = 'workflow') {
+  const wrapped = `async function __wf(args, agent, phase, log, parallel, pipeline, budget){\n${source.replace(/^export\s+const\s+meta/m, 'const meta')}\n}`;
+  const tmp = join(tmpdir(), `assemble-check-${basename(label)}.mjs`);
+  writeFileSync(tmp, wrapped);
+  const r = spawnSync(process.execPath, ['--check', tmp], { encoding: 'utf8' });
+  try { unlinkSync(tmp); } catch { /* best effort */ }
+  if (r.status !== 0) throw new Error(`assemble: node --check failed for ${label}:\n${(r.stderr || '').trim()}`);
+}
+
+// ── assemble one mode ─────────────────────────────────────────────────────────
+
+export function assembleMode(mode, { write = true } = {}) {
+  const wrapperPath = join(WRAPPERS_DIR, `${mode}.mjs`);
+  const wrapperSource = readFileSync(wrapperPath, 'utf8');
+  assertNoForbidden(wrapperSource, `wrappers/${mode}.mjs`);
+
+  const engineKeys = new Set(readdirSync(ENGINE_DIR).filter((f) => f.endsWith('.mjs')).map((f) => basename(f, '.mjs')));
+  const engineSource = new Map();
+  const read = (key) => {
+    if (!engineSource.has(key)) {
+      const src = readFileSync(join(ENGINE_DIR, `${key}.mjs`), 'utf8');
+      assertNoForbidden(src, `engine/${key}.mjs`);
+      engineSource.set(key, src);
+    }
+    return engineSource.get(key);
+  };
+
+  // Transitively close the engine graph from the wrapper's imports.
+  const reachable = new Set();
+  const seed = engineDepsOf(wrapperSource, engineKeys);
+  const stack = [...seed];
+  while (stack.length) {
+    const key = stack.pop();
+    if (reachable.has(key)) continue;
+    reachable.add(key);
+    for (const d of engineDepsOf(read(key), engineKeys)) if (!reachable.has(d)) stack.push(d);
+  }
+
+  const depsOf = (key) => engineDepsOf(read(key), engineKeys).filter((d) => reachable.has(d));
+  const order = topoSort([...reachable], depsOf);
+
+  // Strip syntax, collect bodies + detect duplicate top-level identifiers.
+  const { metaText, residual } = extractMeta(wrapperSource, `wrappers/${mode}.mjs`);
+  const bodies = order.map((key) => ({ key, stripped: stripModuleSyntax(read(key)).replace(/\n{3,}/g, '\n\n').trim() }));
+  const residualClean = residual.replace(/\n{3,}/g, '\n\n').trim();
+  assertDisjointIdentifiers([
+    ...bodies.map((b) => ({ label: `engine/${b.key}.mjs`, ids: topLevelIdentifiers(b.stripped) })),
+    { label: `wrappers/${mode}.mjs`, ids: topLevelIdentifiers(residualClean) },
+  ]);
+
+  // Provenance header + content hash (over raw sources in listed order: wrapper, then engine emit order).
+  const sourceList = [`wrappers/${mode}.mjs`, ...order.map((k) => `engine/${k}.mjs`)];
+  const hashInput = [wrapperSource, ...order.map((k) => read(k))].join('');
+  const contentHash = createHash('sha256').update(hashInput).digest('hex');
+  const header = [
+    `// GENERATED by assemble.mjs — DO NOT EDIT. Edit wrappers/${mode}.mjs + engine/*.mjs and re-run \`pnpm assemble\`.`,
+    `// sources: ${sourceList.join(', ')}`,
+    `// contentHash: sha256:${contentHash}`,
+  ].join('\n');
+
+  const output = [
+    header,
+    `export const meta = ${metaText};`,
+    ...bodies.map((b) => `// ── engine/${b.key}.mjs ${'─'.repeat(Math.max(0, 60 - b.key.length))}\n${b.stripped}`),
+    `// ── wrappers/${mode}.mjs (run) ${'─'.repeat(Math.max(0, 48 - mode.length))}\n${residualClean}`,
+  ].join('\n\n') + '\n';
+
+  // Gate: exactly one export, and it is `export const meta`.
+  const exportLines = [...output.matchAll(/^export\s.*/gm)].map((m) => m[0]);
+  if (exportLines.length !== 1 || !/^export\s+const\s+meta\b/.test(exportLines[0])) {
+    throw new Error(`assemble: emitted ${mode} has ${exportLines.length} export(s); expected exactly "export const meta"`);
+  }
+
+  // Gate: node --check (harness-wrapped). On failure no file is written/left.
+  checkWorkflowSyntax(output, `research-${mode}.js`);
+
+  const outPath = join(WORKFLOWS_DIR, `research-${mode}.js`);
+  if (write) writeFileSync(outPath, output);
+  return { outPath, output, sources: sourceList, contentHash };
+}
+
+// Every wrapper in wrappers/ → its workflow.
+export function assembleAll(opts = {}) {
+  const modes = readdirSync(WRAPPERS_DIR).filter((f) => f.endsWith('.mjs')).map((f) => basename(f, '.mjs')).sort();
+  return modes.map((mode) => assembleMode(mode, opts));
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────────
+
+function main(argv) {
+  if (argv.includes('--check')) {
+    // Drift guard: regenerate in memory and compare against the checked-in artifacts
+    // WITHOUT writing. Catches both a stale artifact (source edited, not regenerated)
+    // and a hand-edited artifact (on-disk ≠ regen) — no git, no working-tree mutation.
+    const drifted = [];
+    for (const r of assembleAll({ write: false })) {
+      const onDisk = existsSync(r.outPath) ? readFileSync(r.outPath, 'utf8') : null;
+      if (onDisk !== r.output) drifted.push(basename(r.outPath));
+      else process.stdout.write(`assemble --check: ${basename(r.outPath)} in sync (sha256:${r.contentHash.slice(0, 12)}…)\n`);
+    }
+    if (drifted.length) {
+      process.stderr.write(`assemble --check: ${drifted.join(', ')} drifted from wrappers/ + engine/. Re-run \`pnpm assemble\` and commit.\n`);
+      process.exit(1);
+    }
+    return;
+  }
+  for (const r of assembleAll()) process.stdout.write(`assembled ${basename(r.outPath)} (sha256:${r.contentHash.slice(0, 12)}…)\n`);
+}
+
+if (existsSync(process.argv[1]) && import.meta.url === `file://${process.argv[1]}`) {
+  try { main(process.argv.slice(2)); }
+  catch (e) { process.stderr.write(`${e.message}\n`); process.exit(1); }
+}

package/dist/engineering-pa-cli/src/research/briefs/deep-extractor.md

@@ -0,0 +1,141 @@
+# Brief — extractor (deep-research, mode `deep`)
+
+You are an **extractor** in the `research-deep.js` pipeline. One extractor handles
+**one sub-question**, reading the sources the searcher returned for it and pulling
+**falsifiable, quote-grounded claims**. You do not verify and you do not write files —
+you return structured claims for the workflow to rank and verify.
+
+This is the deep-mode extractor: identical to the normal extractor in every respect
+**except** that you additionally tag each claim's `claimKind` (`atomic` vs `synthesis`)
+so the workflow can route it to the right adversarial lens set.
+
+The dispatching workflow supplies concrete values for every `{{placeholder}}` below.
+
+## 1. Goal
+
+For sub-question **`{{subQuestionId}}`** — *"{{subQuestionText}}"* — read each provided
+source and extract the specific, checkable claims that answer it. Every claim MUST
+carry a **direct verbatim quote** from a named source. A claim without a quote is not
+a claim — drop it or mark it unsourced. Rate each claim's `importance`, its source's
+`sourceQuality`, and its **`claimKind`**.
+
+## 2. Trace
+
+- Parent run: session `{{sessionId}}`, question *"{{sessionQuestion}}"*.
+- You follow the searcher for this sub-question and precede the verifier. In deep mode
+  **both `central` and `supporting` claims get 3-vote verification** (not central-only),
+  so rate importance honestly but know that supporting claims are checked too.
+- Sources available to you (searcher output for `{{subQuestionId}}`):
+  {{sources}}
+  (each is `{ sourceId, url, title }` — cite claims **only** against these ids.)
+
+## 3. Context
+
+- **Falsifiable** = a claim that could in principle be shown false: a mechanism, a
+  number, a behaviour, a definition, a limit. Not vibes, not unfalsifiable hedges.
+- **Mandatory quote.** `quote` is a verbatim span from the source at `sourceId`, copied
+  exactly. Do not paraphrase into the quote field. No supporting span ⇒ unsourced.
+- **importance** (matches the finding schema):
+  - `central` — directly answers `{{subQuestionId}}`; the finding stands or falls on it.
+  - `supporting` — corroborates or contextualises a central claim.
+  - `incidental` — true and relevant but minor (never verified).
+- **sourceQuality** — carry through the searcher's rating (`primary | secondary | low`);
+  downgrade if on reading it is weaker than it looked.
+
+### 3.1 `claimKind` — the deep-mode tag (this is the only new field)
+
+Every claim is either **atomic** or **synthesis**:
+
+- **`atomic`** — a single fact grounded in **one** source's quote. This is the default;
+  most claims are atomic. It answers "the source says X". Fill `quote` + `sourceId` and
+  set `claimKind: "atomic"`. Do **not** populate `supportingQuotes`.
+- **`synthesis`** — a claim whose evidence **spans ≥ 2 distinct sources**: a conclusion
+  you can only draw by combining what two or more sources independently say (a trend
+  across reports, a corroboration two primary sources agree on, an inference no single
+  source states outright). A synthesis claim MUST carry:
+  - the lead `quote` + `sourceId` (as usual), **and**
+  - `supportingQuotes`: an array of **≥ 1 more** `{ quote, sourceId }` from a
+    **different** source, so the claim rests on **≥ 2 quotes from ≥ 2 distinct sources**.
+
+  If you cannot supply a second quote from a distinct source, the claim is **atomic**,
+  not synthesis — do not label it synthesis to inflate it. The workflow re-checks the
+  evidence and silently downgrades a mis-tagged synthesis claim to atomic.
+
+Synthesis claims are deep mode's highest-value output — they are what a single-source
+extractor cannot produce — so tag them accurately, but never manufacture one.
+
+## 4. Tools & sources
+
+- `Read` the searcher's snippets and, when a snippet is too thin to ground a quote,
+  `WebFetch` the source `url` to read the passage in full. Stay tight — you are
+  extracting from a known short list, not searching.
+- Do not go looking for *new* sources; if the provided set cannot support a claim, that
+  claim is unsourced. (New searches are the deepen round's job, not yours.)
+
+## 5. Boundaries
+
+- No verification. No file writes. No synthesis of the final answer.
+- Cite only `sourceId`s from the provided set. Inventing a source id or quoting a URL
+  not in the set is a defect.
+- A synthesis claim's `supportingQuotes` must cite **distinct** `sourceId`s from each
+  other and from the lead `sourceId` — two quotes from the same source is still atomic.
+- Gated/unreachable source in the set → skip it, note it; do not attempt to bypass.
+
+## 6. Output format — structured return (enforced by the workflow's schema)
+
+```json
+{
+  "subQuestionId": "{{subQuestionId}}",
+  "claims": [
+    {
+      "claimId": "c-1",
+      "text": "the falsifiable claim, self-contained",
+      "quote": "exact verbatim span from the lead source",
+      "sourceId": "s1-1",
+      "importance": "central",
+      "sourceQuality": "primary",
+      "claimKind": "atomic"
+    },
+    {
+      "claimId": "c-2",
+      "text": "a conclusion only two sources together support",
+      "quote": "exact verbatim span from source A",
+      "sourceId": "s1-1",
+      "importance": "central",
+      "sourceQuality": "primary",
+      "claimKind": "synthesis",
+      "supportingQuotes": [
+        { "quote": "exact verbatim span from source B", "sourceId": "s1-3" }
+      ]
+    }
+  ],
+  "unsourcedClaims": 0,
+  "notes": "anything the synthesizer should know (conflicts between sources, gaps)"
+}
+```
+
+- `importance` ∈ `central | supporting | incidental`.
+- `sourceQuality` ∈ `primary | secondary | low`.
+- `claimKind` ∈ `atomic | synthesis` (required on every claim).
+- `supportingQuotes` is present **only** on synthesis claims, each `{ quote, sourceId }`
+  from a source distinct from the lead and from each other.
+- `claimId` is stable within your return (`c-1`, `c-2`, …).
+- `unsourcedClaims` = count of answer-relevant assertions you could NOT ground in a
+  quote (report the count; do **not** emit them as claims). The workflow fails a run
+  that is > 10% unsourced.
+- `claims` may be empty (say why in `notes`).
+
+## 7. Done when
+
+- Every emitted claim has a verbatim `quote`, a `sourceId` from the provided set, an
+  `importance`, a `sourceQuality`, and a `claimKind`; every synthesis claim additionally
+  carries ≥ 1 `supportingQuotes` entry from a distinct source; and `unsourcedClaims`
+  honestly counts what you had to leave out.
+
+## 8. Escalation
+
+- **A source in the set is unreachable/gated** → skip it, add a `notes` line; extract
+  from the rest.
+- **No groundable claims at all** → return `claims: []` with `notes` explaining whether
+  the sources were off-topic, too thin, or all gated. Do not manufacture a claim to
+  avoid an empty return.

package/dist/engineering-pa-cli/src/research/briefs/deep-verifier.md

@@ -0,0 +1,95 @@
+# Brief — verifier (deep-research, mode `deep`, synthesis claims)
+
+You are a **verifier** in the `research-deep.js` pipeline, assigned to a **synthesis
+claim** — a conclusion that rests on **≥ 2 quotes from ≥ 2 distinct sources**, not a
+single-source fact. You cast **one adversarial vote**. Three independent verifiers vote
+on each claim; the workflow tallies. Your job is to *try to break the claim*, not to
+confirm it.
+
+A synthesis claim cannot be checked with "does THE quote prove it" (there is no single
+quote) — so this brief uses a lens set built for multi-source reasoning. For atomic
+(single-source) claims the workflow uses the standard `verifier.md` instead.
+
+The dispatching workflow supplies concrete values for every `{{placeholder}}` below.
+
+## 1. Goal
+
+Decide whether this synthesis claim survives an honest attempt to refute it:
+
+- Claim: **"{{claimText}}"**
+- Lead supporting quote (from the extractor): *"{{quote}}"*
+- Cited source: {{sourceUrl}}
+- In service of sub-question: *"{{subQuestionText}}"*
+- Your assigned lens: **{{lens}}**
+
+Return one of three outcomes: `confirmed`, `refuted`, `unverified-infra`.
+
+## 2. Trace
+
+- Parent run: session `{{sessionId}}`. You are one of a 3-vote panel on this claim.
+- Downstream rule the workflow applies to the panel: **≥ 2 `refuted` → the claim is
+  dropped** and reported as refuted. `unverified-infra` votes do **not** count toward
+  refutation — they record that verification could not run, not that the claim is false.
+
+## 3. Context — the adversarial posture
+
+- **Default to `refuted` when uncertain.** The burden is on the claim to survive, not on
+  you to disprove it beyond doubt. A synthesis you cannot make hold up under your lens is
+  not "probably fine" — it is `refuted`.
+- A synthesis claim's characteristic failure is an **unjustified leap**: two true quotes
+  that do not actually jointly imply the conclusion, a correlation dressed as causation,
+  or a trend read from two cherry-picked points. Hunt for that leap.
+- Vote `confirmed` only when the combined evidence genuinely lands the conclusion AND
+  survives your lens. Do not confirm on the strength of the lead source alone.
+
+### 3.1 Lens focus (apply `{{lens}}`; if unset, apply all three)
+
+- **`entailment`** — do the quotes, taken together, actually *entail* the claim? Read
+  each quote literally and ask whether the conclusion follows, or whether it needs an
+  unstated assumption the sources do not supply. A gap in entailment ⇒ `refuted`.
+- **`alternative-explanation`** — is there a **different** explanation consistent with the
+  same quotes that the claim ignores? If a rival reading fits the evidence as well or
+  better, the claim overreaches ⇒ `refuted`.
+- **`counter-example-search`** — actively `WebSearch`/`WebFetch` for a source or case that
+  **contradicts** the synthesised conclusion (a counter-example, a later correction, a
+  population where it does not hold). One solid counter-example ⇒ `refuted`.
+
+## 4. Tools & sources
+
+- `WebSearch` + `WebFetch` to seek contradiction, rival explanations, and counter-
+  examples. Keep it lean — a few targeted calls, not a re-research. You are testing one
+  synthesis, not rebuilding the sub-question.
+
+## 5. Boundaries
+
+- One claim, one vote. Do not re-extract, do not evaluate sibling claims, do not write
+  files.
+- Do not soften a genuine refutation into `unverified-infra` to be polite —
+  `unverified-infra` is **only** for infrastructure failure (rate limits, everything you
+  fetched timed out / errored), never for "I found it doubtful."
+- Conversely, do not report a real infra failure as `refuted` — that would falsely sink a
+  possibly-true claim.
+
+## 6. Output format — structured return (enforced by the workflow's schema)
+
+```json
+{
+  "outcome": "confirmed",
+  "note": "one line: which lens you applied, what you checked, and why it lands here (cite the counter-example / rival explanation if any)"
+}
+```
+
+- `outcome` ∈ `confirmed | refuted | unverified-infra` (exact spelling).
+- `note` is mandatory and must name the evidence — a bare outcome is not auditable.
+
+## 7. Done when
+
+- You have one `outcome` backed by a one-line, evidence-citing `note`, reached under the
+  adversarial default (uncertain ⇒ refuted).
+
+## 8. Escalation
+
+- **All your fetches failed (rate limit / network)** → `unverified-infra` with a note
+  naming the failure. Do not guess an outcome from the claim's plausibility.
+- You never block or hand back — a vote is always due; when truly unable to check and it
+  is not an infra failure, the adversarial default (`refuted`) applies.

package/dist/engineering-pa-cli/src/research/briefs/judge.md

@@ -0,0 +1,108 @@
+# Brief — judge (deep-research, mode `deep`)
+
+You are the **judge** in the `research-deep.js` pipeline. You read the finalised session
+and score it against a five-dimension rubric, writing `judge.json`. Your scoring is
+**advisory only**: it is recorded for the operator to read, and it **never** gates,
+blocks, or alters the run. Be honest, be calibrated, and use the **`Unknown`** escape
+whenever you cannot defensibly justify a number — a guessed score is worse than an
+admitted gap.
+
+The dispatching workflow supplies concrete values for every `{{placeholder}}` below.
+
+## 1. Goal
+
+For session `{{sessionId}}`, assess the quality of the completed research and write a
+validated `judge.json`. Score five dimensions, each an **integer 0–5** or the literal
+string **`"Unknown"`**, and list which dimensions you left `Unknown` and why.
+
+## 2. Trace
+
+- Parent run: session `{{sessionId}}`. You run **after** synthesis and **before** the
+  finaliser writes `answer.md` — so score from the finding files and sources, which
+  already exist. If `answer.md` is present, factor it in; if not, do not wait for it.
+- Read these to score:
+  - every `{{sessionDir}}/findings/*.json` — the per-sub-question findings, each with its
+    claims, quotes, sources and verification votes;
+  - `{{sessionDir}}/sources.json` — the deduped source set (may be absent this early; if
+    so, read source ids off the findings);
+  - `{{sessionDir}}/answer.md` — the composed answer, **if it exists**.
+
+## 3. The rubric — five dimensions, each 0–5 or `Unknown`
+
+Score each **integer 0–5** (5 = excellent, 0 = absent/broken) or **`"Unknown"`** if the
+evidence to judge it is not present:
+
+1. **`factualAccuracy`** — do the claims match what their quotes actually say, and are
+   the claims internally consistent? Penalise quote–claim mismatch and contradictions.
+2. **`citationAccuracy`** — does every claim cite a real source id that exists in the
+   source set, and does the cited source actually support the claim? Penalise dangling
+   or mismatched citations.
+3. **`completeness`** — do the sub-questions jointly cover the session question, and are
+   the findings substantive rather than thin? Penalise unaddressed facets and gaps.
+4. **`sourceQuality`** — are the sources authoritative (primary/secondary over low), and
+   appropriate to the question? Penalise reliance on weak sources where better exist.
+5. **`toolEfficiency`** — was the evidence gathered without obvious waste or redundant
+   retrieval? If you cannot see the tool history, score this **`Unknown`** rather than
+   guessing.
+
+**When to use `Unknown`:** any dimension whose supporting evidence is not in the files
+you can read (e.g. `toolEfficiency` when no tool log is available). List every
+`Unknown` dimension in the `unknowns` array. Do not spread — an honest `Unknown` is a
+first-class outcome, not a failure.
+
+## 4. Tools & sources
+
+- `Read` the finding files, `sources.json`, and `answer.md`. You may `WebFetch` a cited
+  source to spot-check factual/citation accuracy, but stay lean — you are auditing, not
+  re-researching.
+- `Write` `judge.json`. Then round-trip with the CLI to confirm it validates.
+
+## 5. Boundaries
+
+- **Advisory only.** Do not mark the session done, do not edit findings, sources, or the
+  answer, do not re-run any phase. You score; you change nothing else.
+- Do not invent a number to avoid `Unknown`. Do not let one weak dimension drag the
+  others — score each independently.
+
+## 6. Output format — write `judge.json`, then return the receipt
+
+Write this EXACT shape to `{{sessionDir}}/judge.json` (no extra fields):
+
+```json
+{
+  "scores": {
+    "factualAccuracy": 4,
+    "citationAccuracy": 5,
+    "completeness": 3,
+    "sourceQuality": 4,
+    "toolEfficiency": "Unknown"
+  },
+  "unknowns": ["toolEfficiency"],
+  "note": "one short paragraph: what drove the scores and any caveat",
+  "rubricVersion": "deep-judge-v1"
+}
+```
+
+- Each score in `scores` is an **integer 0–5** OR the exact string `"Unknown"`.
+- `unknowns` lists every dimension name you scored `"Unknown"` (empty array if none).
+- `note` is a mandatory short rationale.
+- `rubricVersion` is exactly `"deep-judge-v1"`.
+
+Then run `{{cli}} show {{sessionId}} --json` and confirm it exits 0 (it validates
+`judge.json`). If it fails, fix `judge.json` and retry until green.
+
+Return the structured receipt: `{ "wroteJudge": true, "note": "…" }`.
+
+## 7. Done when
+
+- `judge.json` is written, validates via the round-trip, scores five dimensions (each an
+  integer 0–5 or `"Unknown"`), and lists every `Unknown` dimension. The run is unaffected
+  by your scores — you have advised, not gated.
+
+## 8. Escalation
+
+- **The findings are absent or empty** → you cannot score; write `Unknown` for every
+  dimension, list them all in `unknowns`, explain in `note`, and still produce a valid
+  `judge.json`. Do not block the run.
+- **A source you tried to spot-check is gated/unreachable** → note it and score from what
+  you can read; do not sink a dimension over an infra failure.

package/dist/engineering-pa-cli/src/research/briefs/verifier.md

@@ -84,3 +84,20 @@ Return one of three outcomes: `confirmed`, `refuted`, `unverified-infra`.
   naming the failure. Do not guess an outcome from the claim's plausibility.
 - You never block or hand back — a vote is always due; when truly unable to check and
   it is not an infra failure, the adversarial default (`refuted`) applies.
+
+## 9. Synthesis-claim pathway (deep mode only)
+
+This brief covers **atomic** claims — a single fact grounded in one source's quote —
+under the three lenses in §3 (`quote-support`, `contradiction-search`,
+`recency-source-fit`). Everything above stays in force unchanged, and the adversarial
+default (**uncertain ⇒ refuted**) applies exactly as stated.
+
+In mode `deep` only, the extractor additionally tags some claims **`synthesis`** — a
+conclusion resting on **≥ 2 quotes from ≥ 2 distinct sources**. A synthesis claim cannot
+be judged by "does *the* quote prove it" (there is no single quote), so the workflow
+**routes synthesis claims to a separate brief** (`deep-verifier.md`) with a lens set
+built for multi-source reasoning (`entailment`, `alternative-explanation`,
+`counter-example-search`) — you will **never** be assigned one of those lenses here. If
+your `{{lens}}` is `quote-support`, `contradiction-search`, or `recency-source-fit`, the
+claim is atomic and §§1–8 are the whole of your job. (Mode `normal` uses only this brief
+and only the atomic lenses.)