@stravica-ai/digital-operator-pa 0.1.0

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

@@ -0,0 +1,260 @@
+// Knowledge-library promotion (w-021).
+//
+// On `research mark done <id>` for a NORMAL or DEEP session, promote the
+// session's verbatim `answer.md` into the operator knowledge library as a
+// first-class queryable doc under `operator/knowledge/research/`, so
+// `pa knowledge` surfaces it alongside every other operator doc.
+//
+// Operator directive (2026-07-07):
+//   - normal + deep  → auto-promote.
+//   - light          → NEVER promote (hard rule; `--promote` on light is a
+//                      usage error, enforced in mark.mjs before we get here).
+//   - `--no-promote` → normal/deep skip with a one-line note (status still done).
+//   - aborted        → never promoted (mark aborted never calls this).
+//
+// This module is the ONE place that writes to `operator/knowledge/`. Session
+// reads fan out through the store (tooling standard §7: reads may scatter,
+// writes may not). `knowledgeDir` is injectable so tests bind a temp dir —
+// same posture as the store's `makeStore(dir)`.
+//
+// Graph shape the promoted doc must satisfy (discovered from
+// @stravica-ai/engineering-pa-core .../knowledge/retrieval/graph-builder.mjs +
+// the `pa knowledge` CLI graph.mjs — NEITHER reads front-matter):
+//   - node `title`  = the first `# ` heading in the file  → we prepend `# <question>`.
+//   - node `domain` = path segment under operator/knowledge → `research/` gives it.
+//   - edges         = `[[wiki]]` + `[md](rel.md)` links + .backlinks.json → we add
+//                     a provenance footer linking `./README.md` so `related` is non-empty.
+// The rich front-matter block below is honoured by no builder today; it is
+// human/Librarian metadata and forward-compat for a schema-aware builder.
+
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getRepoRoot } from '../pa/repo-root.mjs';
+
+// Where promoted answers land inside the operator repo. Historical shape: when
+// the tool lived at `operator/extensions/tools/research/`, this constant was
+// computed with `fileURLToPath(new URL('../../../../../', import.meta.url))` —
+// a fixed five-`../` walk that only worked at that anchor. Under
+// `@stravica-ai/digital-operator-pa`, the source lives inside `node_modules/`, so the
+// walk lands in the wrong tree. Instead we resolve the operator repo root the
+// same way `pa knowledge` / `pa work` do (env-var override, else walk up for
+// `.git`) and join `operator/knowledge/` under it. Async because getRepoRoot is.
+export const KNOWLEDGE_SUBPATH = 'operator/knowledge';
+export const RESEARCH_DOMAIN = 'research';
+
+export async function defaultKnowledgeDir() {
+  return join(await getRepoRoot(), KNOWLEDGE_SUBPATH);
+}
+
+// ── pure helpers ──────────────────────────────────────────────────────────────
+
+// Kebab-case slug from the question. Deterministic (same question → same slug →
+// same filename → idempotent promotion). Bounded length keeps filenames sane.
+export function slugify(text, maxLen = 60) {
+  const slug = String(text ?? '')
+    .toLowerCase()
+    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '') // strip accents
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, maxLen)
+    .replace(/-+$/g, '');
+  return slug || 'session';
+}
+
+// The promoted doc's filename: `<sessionId>-<slug>.md`. sessionId is unique and
+// stable, so the target path is deterministic — the basis for idempotency.
+export function promotedFileName(sessionId, question) {
+  return `${sessionId}-${slugify(question)}.md`;
+}
+
+// Derive counts the frontmatter records. manifest.json is FROZEN and carries
+// none of these — everything is derived from the session's other artifacts
+// (brief §5). A finding is the unit of "claim":
+//   refuted    — any verification vote refuted it.
+//   verified   — else, any vote confirmed it.
+//   unverified — else (only unverified-infra votes, or none, e.g. light mode).
+// gatedCount counts UNRESOLVED gates (pending/retrying) — the ones still owed a
+// human sweep; resolved/failed are closed out.
+export function deriveCounts({ sources, findings, gates }) {
+  const sourceCount = sources?.items?.length ?? 0;
+  let verifiedCount = 0;
+  let refutedCount = 0;
+  let unverifiedCount = 0;
+  for (const f of findings ?? []) {
+    const outcomes = (f.verificationVotes ?? []).map((v) => v.outcome);
+    if (outcomes.includes('refuted')) refutedCount++;
+    else if (outcomes.includes('confirmed')) verifiedCount++;
+    else unverifiedCount++;
+  }
+  const gatedCount = (gates?.queue ?? []).filter(
+    (g) => g.status === 'pending' || g.status === 'retrying',
+  ).length;
+  return { sourceCount, verifiedCount, refutedCount, unverifiedCount, gatedCount };
+}
+
+// First substantive paragraph of the answer body → doc description. Skips
+// front-matter, headings, blank lines, block markers and horizontal rules;
+// collapses whitespace; truncates. Falls back to the question when the answer
+// has no prose (e.g. a `structured` answer that is one JSON block).
+export function firstParagraph(answer, fallback, maxLen = 240) {
+  const body = stripFrontMatter(String(answer ?? ''));
+  const para = [];
+  let inFence = false;
+  for (const raw of body.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith('```')) {
+      // A fence before any prose → skip the whole block; after prose → stop.
+      if (para.length) break;
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue; // skip fenced content entirely
+    if (line === '') { if (para.length) break; else continue; }
+    if (line.startsWith('#')) { if (para.length) break; else continue; }
+    if (line === '---' || line.startsWith('|')) { if (para.length) break; else continue; }
+    para.push(line);
+  }
+  const text = para.join(' ').replace(/\s+/g, ' ').trim();
+  const chosen = text || String(fallback ?? '').replace(/\s+/g, ' ').trim();
+  return chosen.length > maxLen ? chosen.slice(0, maxLen - 1).trimEnd() + '…' : chosen;
+}
+
+function stripFrontMatter(content) {
+  if (!content.startsWith('---')) return content;
+  const lines = content.split(/\r?\n/);
+  if (lines[0].trim() !== '---') return content;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') return lines.slice(i + 1).join('\n');
+  }
+  return content;
+}
+
+// YAML-ish scalar escaping for the flat `key: value` front-matter we emit.
+// Double-quote and escape when the value could be misread (colons, leading
+// specials, quotes). Numbers pass through bare.
+function yamlScalar(value) {
+  if (typeof value === 'number') return String(value);
+  const s = String(value ?? '');
+  if (s === '') return '""';
+  if (/^[A-Za-z0-9][\w .\-/]*$/.test(s) && !/^\d/.test(s)) return s;
+  return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+// Assemble the promoted document: front-matter + `# <question>` H1 (so the
+// graph builder titles the node with the question) + the VERBATIM answer body
+// + a provenance footer that links `./README.md` (a real graph edge, so
+// `pa knowledge related` is non-empty). The answer body itself is untouched.
+export function buildDocument({ manifest, counts, slug, date, description, answer }) {
+  const fm = [
+    '---',
+    `name: ${yamlScalar(slug)}`,
+    `title: ${yamlScalar(manifest.question)}`,
+    `description: ${yamlScalar(description)}`,
+    `domain: ${yamlScalar(RESEARCH_DOMAIN)}`,
+    `type: ${yamlScalar('research-session')}`,
+    `mode: ${yamlScalar(manifest.mode)}`,
+    `sessionId: ${yamlScalar(manifest.sessionId)}`,
+    `date: ${yamlScalar(date)}`,
+    `sourceCount: ${yamlScalar(counts.sourceCount)}`,
+    `verifiedCount: ${yamlScalar(counts.verifiedCount)}`,
+    `refutedCount: ${yamlScalar(counts.refutedCount)}`,
+    `unverifiedCount: ${yamlScalar(counts.unverifiedCount)}`,
+    `gatedCount: ${yamlScalar(counts.gatedCount)}`,
+    `question: ${yamlScalar(manifest.question)}`,
+    '---',
+  ].join('\n');
+
+  const footer = `*Promoted from research session \`${manifest.sessionId}\` (\`${manifest.mode}\` mode, ${date}). ` +
+    `Part of the [research knowledge library](./README.md).*`;
+
+  const body = String(answer ?? '').replace(/\s+$/, '');
+  return `${fm}\n\n# ${manifest.question}\n\n${body}\n\n---\n\n${footer}\n`;
+}
+
+// ── the write chokepoint ────────────────────────────────────────────────────────
+
+// Promote a session's answer.md into the knowledge library. Reads via the
+// injected `store`; writes exactly one file under `knowledgeDir/research/`.
+//
+// Returns a result object; NEVER throws for expected skips (missing answer,
+// already promoted) so `mark done` still succeeds. `date` defaults to the
+// manifest's updatedAt date (the mark-done timestamp).
+//
+// Callers guarantee: only invoked for status===done, mode in {normal,deep},
+// and not when --no-promote / light (those decisions live in decidePromotion).
+export async function promoteSession(id, { store, knowledgeDir } = {}) {
+  // Resolve the write target lazily: if the caller didn't inject one, walk
+  // to the operator repo root and land under operator/knowledge/. The same
+  // resolver `pa knowledge` uses — `$DAVE_REPO_ROOT` / `$PA_REPO_ROOT` /
+  // walk-up-for-`.git`.
+  if (!knowledgeDir) knowledgeDir = await defaultKnowledgeDir();
+  const manifest = await store.readManifest(id);
+
+  const answer = await store.readAnswer(id);
+  if (answer == null) {
+    return { status: 'skipped-no-answer', reason: `session ${id} has no answer.md — nothing to promote` };
+  }
+
+  const domainDir = join(knowledgeDir, RESEARCH_DOMAIN);
+  const fileName = promotedFileName(id, manifest.question);
+  const relPath = `operator/knowledge/${RESEARCH_DOMAIN}/${fileName}`;
+  const absPath = join(domainDir, fileName);
+
+  // Idempotency, derived from filesystem state (no manifest field — schema is
+  // frozen). Same session → same deterministic filename; if it already exists
+  // we do not re-write, so a re-promotion is a no-op.
+  if (existsSync(absPath)) {
+    return { status: 'already-promoted', path: relPath };
+  }
+
+  const sources = await store.readSources(id);
+  const gates = await store.readGates(id);
+  const findings = await store.listFindings(id);
+  const counts = deriveCounts({ sources, findings, gates });
+
+  const date = (manifest.updatedAt || manifest.createdAt || '').slice(0, 10);
+  const slug = slugify(manifest.question);
+  const description = firstParagraph(answer, manifest.question);
+  const doc = buildDocument({ manifest, counts, slug, date, description, answer });
+
+  await mkdir(domainDir, { recursive: true });
+  await writeFile(absPath, doc, 'utf8');
+
+  return { status: 'promoted', path: relPath, counts };
+}
+
+// ── promotion decision (pure) ───────────────────────────────────────────────────
+
+// Decide what to do given the terminal transition + flags. Kept pure so the
+// mark command is thin glue and the rules are unit-testable in isolation.
+//   light + promote  → throw usage error (exit 1): light is NEVER promoted.
+//   light            → skip-silent (the point of light is quiet lookups).
+//   normal/deep + noPromote → skip-note (log one line, still success).
+//   normal/deep      → promote.
+//   status !== done  → skip-silent (aborted et al. never promote).
+export function decidePromotion({ mode, status, noPromote = false, promote = false }) {
+  if (mode === 'light') {
+    if (promote) {
+      throw Object.assign(
+        new Error('light-mode sessions are never promoted to the knowledge library (operator directive); --promote is not allowed on light mode'),
+        { exitCode: 1 },
+      );
+    }
+    return { action: 'skip-silent' };
+  }
+  if (status !== 'done') return { action: 'skip-silent' };
+  if (noPromote) return { action: 'skip-note' };
+  return { action: 'promote' };
+}
+
+// The one-line hint printed after a successful promotion. The knowledge graph
+// is rebuilt by a 6-hourly reindex job (see the `Knowledge reindex` cron); it
+// re-reads every doc in operator/knowledge/, so we do NOT shell into the
+// version-pinned builder from here (brief §5: global side effects → hint, don't
+// auto-run). There is no stable `pa knowledge rebuild` verb to call.
+export function refreshHint(relPath) {
+  return `promoted to ${relPath} — rebuild the knowledge graph (knowledge-reindex cron, ` +
+    `or run the graph/index builders) so \`pa knowledge search\`/\`related\` surface it`;
+}

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

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "ai.stravica.knowledge.research/finding.schema.json",
+  "title": "Research finding",
+  "description": "One finding per sub-question, written by workers at sessions/<sessionId>/findings/sq-<id>.json. We read/validate them, workers write them. Validator: src/store/findings.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["subQuestionId", "summary", "quotes", "sources", "confidence", "verificationVotes", "unsourced"],
+  "properties": {
+    "subQuestionId": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string", "description": "Synthesised answer to the sub-question." },
+    "quotes": {
+      "type": "array",
+      "description": "Direct supporting quotes, each tied to a source ref (build-spec §5 quote-grounded extraction).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["text", "sourceId"],
+        "properties": {
+          "text": { "type": "string", "minLength": 1 },
+          "sourceId": { "type": "string", "minLength": 1, "description": "References sources.json items[].id." },
+          "importance": { "type": "string", "enum": ["central", "supporting", "incidental"] }
+        }
+      }
+    },
+    "sources": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Source ids (sources.json items[].id) this finding draws on."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["low", "medium", "high"],
+      "description": "Bucketed confidence. Buckets chosen over a 0..1 float — LLM self-scored floats are false precision."
+    },
+    "verificationVotes": {
+      "type": "array",
+      "description": "Verify outcomes (build-spec §4/§5). Empty in light mode. Three outcomes per vote.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["outcome"],
+        "properties": {
+          "outcome": { "type": "string", "enum": ["confirmed", "refuted", "unverified-infra"] },
+          "lens": { "type": "string", "description": "Verifier lens (deep diverse-lens: quote-support | contradiction-search | recency-source-fit)." },
+          "note": { "type": "string" }
+        }
+      }
+    },
+    "unsourced": {
+      "type": "boolean",
+      "description": "True if the finding carries claims without a supporting quote (build-spec §8 unsourced-claim counter)."
+    }
+  }
+}

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

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "ai.stravica.knowledge.research/gates.schema.json",
+  "title": "Research human-gate queue",
+  "description": "gates.json at sessions/<sessionId>/gates.json — the retry queue for human-gated fetches (build-spec §6). Merges brief §3 status-tracking fields with spec §6 descriptive fields. Validator: src/store/gates.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["queue"],
+  "properties": {
+    "queue": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "url", "gateType", "whatIsNeeded", "status", "blockedAt"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "description": "Gate record id (unique within the session)." },
+          "url": { "type": "string", "minLength": 1, "description": "The gated URL." },
+          "gateType": { "type": "string", "description": "e.g. cloudflare, captcha, auth, paywall." },
+          "subQuestionId": { "type": "string", "description": "Which sub-question was blocked, if known." },
+          "whatIsNeeded": { "type": "string", "description": "Human-readable what-is-needed-to-clear (spec §6). Also the brief's `reason`." },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "retrying", "resolved", "failed"],
+            "description": "pending → retrying (marked eligible by `gates --retry`) → resolved/failed."
+          },
+          "blockedAt": { "type": "string", "description": "ISO 8601 UTC when the gate was hit (spec's loggedAt)." },
+          "resolution": { "type": "string", "description": "Note or outcome once resolved/failed." },
+          "artifactPath": { "type": "string", "description": "Path to the saved page content (sessions/<id>/gated/<hash>.md, spec §6.4)." }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "ai.stravica.knowledge.research/manifest.schema.json",
+  "title": "Research session manifest",
+  "description": "Root manifest.json for a research session, at sessions/<sessionId>/manifest.json. Hand-rolled validator: src/store/manifest.mjs. camelCase throughout.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "sessionId",
+    "mode",
+    "question",
+    "gatePolicy",
+    "status",
+    "outputMode",
+    "budget",
+    "assumptions",
+    "createdAt",
+    "updatedAt"
+  ],
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "ULID-like 26-char Crockford base32 id: 10-char ms timestamp + 16-char entropy. Lexicographically sortable by creation time.",
+      "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
+    },
+    "mode": { "type": "string", "enum": ["light", "normal", "deep"] },
+    "question": { "type": "string", "minLength": 1, "description": "Raw operator question." },
+    "intent": { "type": "string", "description": "Clarified intent, if the caller passed one." },
+    "gatePolicy": {
+      "type": "string",
+      "enum": ["operatorPresent", "background", "worker"],
+      "description": "Human-gate execution posture (build-spec §6)."
+    },
+    "status": { "type": "string", "enum": ["draft", "in-progress", "done", "aborted"] },
+    "outputMode": {
+      "type": "string",
+      "enum": ["shortAnswer", "article", "structured"],
+      "description": "Synthesis render target. Defaults to shortAnswer."
+    },
+    "budget": {
+      "type": "object",
+      "description": "Records what the run was scoped to. Not enforced by the CLI.",
+      "additionalProperties": false,
+      "required": ["maxSubQuestions", "maxDeepeningRounds", "wallClockMinutes"],
+      "properties": {
+        "maxSubQuestions": { "type": "integer", "minimum": 0 },
+        "maxDeepeningRounds": { "type": "integer", "minimum": 0 },
+        "wallClockMinutes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Scope-narrowing assumptions recorded when a background run cannot clarify (build-spec §4)."
+    },
+    "createdAt": { "type": "string", "description": "ISO 8601 UTC." },
+    "updatedAt": { "type": "string", "description": "ISO 8601 UTC." }
+  }
+}

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

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "ai.stravica.knowledge.research/plan.schema.json",
+  "title": "Research plan",
+  "description": "plan.json at sessions/<sessionId>/plan.json. `run` writes a skeleton (empty subQuestions, mode-derived rounds/tier); the workflow (w-017) fills subQuestions. Validator: src/store/plan.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["subQuestions", "deepeningRounds", "verificationTier"],
+  "properties": {
+    "subQuestions": {
+      "type": "array",
+      "description": "Dependency-classified decomposition (build-spec §4). Empty until the planner fills it.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "text", "kind", "dependsOn"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "text": { "type": "string", "minLength": 1 },
+          "kind": { "type": "string", "enum": ["independent", "dependent"] },
+          "dependsOn": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Sub-question ids this one depends on. Empty for independent facets."
+          }
+        }
+      }
+    },
+    "deepeningRounds": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 3,
+      "description": "0 for light, 1 for normal, up to 3 for deep."
+    },
+    "verificationTier": {
+      "type": "string",
+      "enum": ["none", "central-3vote", "diverse-lens-3vote"],
+      "description": "none (light), central-3vote (normal), diverse-lens-3vote (deep)."
+    }
+  }
+}

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

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "ai.stravica.knowledge.research/sources.schema.json",
+  "title": "Research sources",
+  "description": "Aggregated source registry at sessions/<sessionId>/sources.json. One entry per fetched source; finding.sources[] and quote.sourceId reference items[].id. Validator: src/store/sources.mjs.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["items"],
+  "properties": {
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1, "description": "Stable id referenced by findings." },
+          "kind": {
+            "type": "string",
+            "enum": ["web", "playwright", "kb", "codebase", "prior-session"],
+            "description": "Source capability (build-spec §2/§3)."
+          },
+          "url": { "type": "string" },
+          "title": { "type": "string" },
+          "fetchedAt": { "type": "string", "description": "ISO 8601 UTC." },
+          "checksum": { "type": "string", "description": "Optional content hash for dedup/change-detection." }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,61 @@
+// finding.json schema + validator (build-spec §5). Zero-dep, hand-rolled.
+// Workers write findings/sq-<id>.json; we read + validate them. We never write findings.
+// Schema doc: src/schema/finding.schema.json.
+import {
+  parseJson, requireObject, requireFields, noExtraFields,
+  requireString, optionalString, requireEnum, optionalEnum, requireArray, requireBoolean, fail,
+} from './validate.mjs';
+
+export const CONFIDENCE = ['low', 'medium', 'high'];
+export const IMPORTANCE = ['central', 'supporting', 'incidental'];
+export const VOTE_OUTCOMES = ['confirmed', 'refuted', 'unverified-infra'];
+
+const TOP = ['subQuestionId', 'summary', 'quotes', 'sources', 'confidence', 'verificationVotes', 'unsourced'];
+const QUOTE_FIELDS = ['text', 'sourceId', 'importance'];
+const QUOTE_REQUIRED = ['text', 'sourceId'];
+const VOTE_FIELDS = ['outcome', 'lens', 'note'];
+
+export function loadFinding(text, where = 'finding') {
+  return validateFinding(parseJson(text, where), where);
+}
+
+export function validateFinding(f, where = 'finding') {
+  requireObject(f, where);
+  requireFields(f, TOP, where);
+  noExtraFields(f, TOP, where);
+
+  requireString(f, 'subQuestionId', where);
+  requireString(f, 'summary', where, { nonEmpty: false });
+
+  const quotes = requireArray(f, 'quotes', where);
+  quotes.forEach((q, i) => {
+    const w = `${where}.quotes[${i}]`;
+    requireObject(q, w);
+    requireFields(q, QUOTE_REQUIRED, w);
+    noExtraFields(q, QUOTE_FIELDS, w);
+    requireString(q, 'text', w);
+    requireString(q, 'sourceId', w);
+    optionalEnum(q, 'importance', IMPORTANCE, w);
+  });
+
+  const sources = requireArray(f, 'sources', where);
+  sources.forEach((s, i) => {
+    if (typeof s !== 'string') fail(`sources[${i}] must be a string (source id)`, where);
+  });
+
+  requireEnum(f, 'confidence', CONFIDENCE, where);
+
+  const votes = requireArray(f, 'verificationVotes', where);
+  votes.forEach((v, i) => {
+    const w = `${where}.verificationVotes[${i}]`;
+    requireObject(v, w);
+    requireFields(v, ['outcome'], w);
+    noExtraFields(v, VOTE_FIELDS, w);
+    requireEnum(v, 'outcome', VOTE_OUTCOMES, w);
+    optionalString(v, 'lens', w);
+    optionalString(v, 'note', w);
+  });
+
+  requireBoolean(f, 'unsourced', where);
+  return f;
+}

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

@@ -0,0 +1,73 @@
+// gates.json schema + validator + pure queue transforms (build-spec §6). Zero-dep.
+// Schema doc: src/schema/gates.schema.json.
+//
+// Disk persistence for gates lives in store/index.mjs (the write chokepoint).
+// This module owns the schema, validation, and PURE transforms only — nothing
+// here touches the filesystem, so `gates --retry` composes read (index) →
+// transform (here) → write (index).
+import {
+  parseJson, requireObject, requireFields, noExtraFields,
+  requireString, optionalString, requireEnum, requireArray, fail,
+} from './validate.mjs';
+
+export const GATE_STATUSES = ['pending', 'retrying', 'resolved', 'failed'];
+
+const TOP = ['queue'];
+const ITEM_FIELDS = ['id', 'url', 'gateType', 'subQuestionId', 'whatIsNeeded', 'status', 'blockedAt', 'resolution', 'artifactPath'];
+const ITEM_REQUIRED = ['id', 'url', 'gateType', 'whatIsNeeded', 'status', 'blockedAt'];
+
+export function emptyGates() {
+  return { queue: [] };
+}
+
+export function loadGates(text, where = 'gates') {
+  return validateGates(parseJson(text, where), where);
+}
+
+export function validateGates(g, where = 'gates') {
+  requireObject(g, where);
+  requireFields(g, TOP, where);
+  noExtraFields(g, TOP, where);
+
+  const queue = requireArray(g, 'queue', where);
+  const seen = new Set();
+  queue.forEach((it, i) => {
+    const w = `${where}.queue[${i}]`;
+    requireObject(it, w);
+    requireFields(it, ITEM_REQUIRED, w);
+    noExtraFields(it, ITEM_FIELDS, w);
+    const id = requireString(it, 'id', w);
+    if (seen.has(id)) fail(`duplicate gate id "${id}"`, w);
+    seen.add(id);
+    requireString(it, 'url', w);
+    requireString(it, 'gateType', w);
+    optionalString(it, 'subQuestionId', w);
+    requireString(it, 'whatIsNeeded', w);
+    requireEnum(it, 'status', GATE_STATUSES, w);
+    requireString(it, 'blockedAt', w);
+    optionalString(it, 'resolution', w);
+    optionalString(it, 'artifactPath', w);
+  });
+  return g;
+}
+
+// A gate item is eligible for retry when it is still pending or already retrying
+// (idempotent re-mark). Resolved/failed items are terminal and left untouched.
+export function isRetryEligible(item) {
+  return item.status === 'pending' || item.status === 'retrying';
+}
+
+// PURE: return a new gates object with all eligible items marked `retrying`,
+// plus the list of items that were (re)marked. Does not mutate the input.
+export function markEligibleForRetry(gates) {
+  const marked = [];
+  const queue = gates.queue.map((it) => {
+    if (isRetryEligible(it)) {
+      const next = { ...it, status: 'retrying' };
+      marked.push(next);
+      return next;
+    }
+    return it;
+  });
+  return { gates: { ...gates, queue }, marked };
+}