@dogfood-lab/study-swarm 1.3.0 → 2.1.0

package/bin/study-swarm.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // study-swarm — thin CLI for the research-grounded design protocol.
 // Zero runtime dependencies. Commands: protocol | new | lint | help | version.
-import { readFileSync, writeFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, statSync, readdirSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve, join } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -19,12 +19,23 @@ USAGE
 COMMANDS
   protocol                 Print the locked protocol (the five steps + halt rules).
   new <slug>               Scaffold a dispatch file <slug>.dispatch.md to fill in.
-  lint [--json] <path...>  Check dispatches' citations against the sourcing standard.
+  return <dispatch> [--check]
+                           Write the results of a dispatch: a sheet you can hand someone
+                           (<stem>.results.md) and the same facts kept beside it
+                           (<stem>.results.json) for the next run to open. --check fails
+                           if either copy has drifted from the dispatch.
+  lint [--json] [--strict] <path...>
+                           Check dispatches' citations against the sourcing standard.
                            A <path> may be a file, a directory (linted recursively for
                            *.dispatch.md), or "-" to read one dispatch from stdin.
+                           --strict also flags orphan citations (a finding no Step-5 choice
+                           references by number or author — "citations without a connection
+                           are noise"); opt-in, so the default CI gate is unchanged.
+  lock --init <dispatch>   Scaffold <dispatch>.orchestration.json — a fill-in-the-blanks
+                           harness record to feed to "lock <dispatch> --from".
   lock <dispatch> --from <orchestration.json>
                            Emit <dispatch>.lock.json — pin (per Step-2 agent) the resolved
-                           model + SHA-256 of the byte-exact prompt + SHA-256 of the tool
+                           model + SHA-256 of the text-normalized prompt + SHA-256 of the tool
                            schema, plus the verifier receipt, rolled into one lock_sha256.
   lock --verify <dispatch> [--from <orchestration.json>]
                            Re-derive the deterministic hashes and assert they match the lock;
@@ -39,6 +50,10 @@ COMMANDS
                            Fail closed (exit 1) for any dispatch carrying an unresolved
                            evidence-withdrawn flag — the andon that HALTS a withdrawn finding's
                            dependents until it is removed or re-grounded. Gates CI.
+  requalify --status <corpus-dir> [--json]
+                           Read-only evidence-health VIEW of a corpus: withdrawn vs resolved
+                           counts, a breakdown by reason and resolution mode, per-dispatch
+                           lines. Informational (exit 0), unlike the --check gate.
   requalify --resolve <dispatch> <identifier> --mode removed|regrounded [--note <text>]
                            Clear a flag once the finding is removed (the citation is gone) or
                            re-grounded (re-verified clean by the sibling runner; --note records
@@ -47,12 +62,14 @@ COMMANDS
   version                  Print the version.
 
 EXIT CODES
-  0  ok / lint clean
-  1  lint found sourcing violations
+  0  ok / lint clean / verify clean
+  1  a gate failed: a lint sourcing violation, lock --verify drift, or
+     requalify --check (an unresolved evidence-withdrawn flag, or a sidecar
+     the check could not trust)
   2  usage or runtime error
 
 NOTE
-  lint checks citation FORM (Step 3: author + year + a resolvable arXiv/DOI/URL,
+  lint checks citation FORM (Step 3: author + year + a resolvable arXiv/DOI/URL/RFC,
   no "studies show…" gestures) — it does not judge whether a source is legitimate
   or actually supports the claim. That is Step 4, below.
 
@@ -103,7 +120,7 @@ const template = (slug, stamp) => `<!-- ${stamp} -->
 
 ## Step 4 — External verification
 <!-- Different model family, reasoning-stripped. Run:  roleos verify-citations ${slug}.dispatch.md
-     HALT on fabricated/misattributed; halt-and-escalate if the verifier or oracle is unavailable. -->
+     Drop a fabricated citation; correct a misattribution once and re-verify; halt-and-escalate only if the verifier or oracle is unavailable. -->
 - [ ] every citation resolved by retrieval (arXiv/DOI), not model memory
 - [ ] every finding matches what its source actually claims (groundedness)
 - [ ] >= 3 decorrelated lenses (retrieval oracle + >= 2 different model families)
@@ -135,17 +152,93 @@ function cmdNew(slug) {
 // --- lint core ------------------------------------------------------------
 
 const YEAR = /\b(19|20)\d{2}\b/;
-const ID = /(arxiv:\s*\d{4}\.\d{4,5}|10\.\d{4,9}\/\S+|https?:\/\/\S+)/i;
+// A resolvable identifier: an arXiv id, a DOI, a direct URL, or a bare RFC number
+// (RFC parity keeps `lint` in step with the sourcing standard and with normIdent, which
+// already treats `RFC NNNN` as first-class in withdraw/requalify).
+const ID = /(arxiv:\s*\d{4}\.\d{4,5}|10\.\d{4,9}\/\S+|https?:\/\/\S+|\brfc[\s/-]?\d{3,5}\b)/i;
 const PLACEHOLDER = /arXiv:_{2,}|<finding>|<authors>|<year>|<implication>/i;
 const BANNED = /\b(studies show|research suggests|it'?s well[- ]established|well[- ]established that)\b/i;
 // An author cite: a capitalized name (Unicode-aware, so "Buçinca" counts), optionally
 // followed by "et al.", "&", "and", or further surnames, immediately before the year.
-// Accepts "Huang et al. 2023", "Walters & Wilder 2023", "Panickssery, Bowman & Feng 2024";
+// Accepts "Huang et al. 2023", "Walters & Wilder 2023", "Panickssery, Bowman & Feng 2024",
+// and space-separated org authors ("OASIS CSAF Technical Committee 2022");
 // flags an author-less finding like "**Foo.** 2024 (arXiv:…)".
-const AUTHOR = /\p{Lu}[\p{L}.'’-]+(?:\s*,?\s*(?:&|and|et al\.?|\p{Lu}[\p{L}.'’-]+))*\s+\(?(?:19|20)\d{2}/u;
+// The inner group requires a non-empty separator per iteration (`,?\s+`, never the old
+// empty-matchable `\s*,?\s*`) and is bounded ({0,24}), so it is linear-time — the previous
+// form had catastrophic backtracking (ReDoS) on a long capitalized/`and`-joined run with no
+// trailing year, hanging the CI-gating `lint` command.
+const AUTHOR = /\p{Lu}[\p{L}.'’-]+(?:,?\s+(?:&|and|et al\.?|\p{Lu}[\p{L}.'’-]+)){0,24}(?:,\s*|\s+)\(?(?:19|20)\d{2}/u;
+// A single function word before a year is not an author ("The 2024"). A name, "et al.", or a
+// multi-word organization still is. Checked after the regex so the stop-list cannot reintroduce
+// the empty-match backtracking the quantified group above was rewritten to avoid.
+const AUTHOR_STOP = new Set('the a an this that these those it its in on for with from and but or of to as at by we our'.split(' '));
+function authorOk(text) {
+  const re = new RegExp(AUTHOR.source, 'gu');
+  for (const m of text.matchAll(re)) {
+    const phrase = m[0].replace(/(?:,\s*|\s+)\(?((?:19|20)\d{2})\s*$/, '').trim();
+    const words = phrase.split(/\s+/).map((w) => w.replace(/[.,]+$/u, '').replace(/(?:['’]s)$/iu, ''));
+    const bareStop = words.length === 1 && AUTHOR_STOP.has(words[0].toLowerCase());
+    if (!bareStop) return true;
+  }
+  return false;
+}
+
+// --- strict mode: Step-5 connection / orphan-citation check (opt-in --strict) --------------
+// Step 5 requires each finding to inform a design choice — "citations without a connection are
+// noise" (PROTOCOL.md). This makes the protocol's one otherwise-unexecutable failure mode ("orphan
+// citation") deterministic: a Step-3 finding whose number OR first-author token is never referenced
+// in the "Step 5 / Architecture" section is flagged. Deliberately LIBERAL about what counts as a
+// reference — a missed orphan is safer than a false orphan — so it never fails a dispatch that
+// connected a finding in any reasonable numeric ("(findings 1, 3)") or prose ("Kim 2025") form.
+const escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// The first-author surname token of a finding: the first Capitalized word after the bold **title**.
+function authorTokenOf(findingText) {
+  const afterBold = String(findingText).replace(/^\s*\d+\.\s*/, '').replace(/^\s*\*\*[^*]*\*\*/, '');
+  const m = afterBold.match(/\p{Lu}[\p{L}.'’-]+/u);
+  return m ? m[0] : null;
+}
+// Finding numbers referenced in a Step-5 body: any "#N", plus every integer following the word
+// "finding"/"findings" (covers "(findings 1, 3 and 5)"). Liberal.
+function referencedNumbers(body) {
+  const nums = new Set();
+  for (const m of body.matchAll(/#\s*(\d+)/g)) nums.add(Number(m[1]));
+  for (const m of body.matchAll(/\bfindings?\b[\s:#-]*((?:\d+[\s,#&-]*(?:and\s+)?)+)/gi)) {
+    for (const d of m[1].match(/\d+/g) || []) nums.add(Number(d));
+  }
+  return nums;
+}
+function headingLevel(line) {
+  const m = /^(#{1,6})\s/.exec(line);
+  return m ? m[1].length : 0;
+}
+// A section runs until the next heading of the same or higher level. A ### inside ## stays inside.
+function sectionEnd(lines, start) {
+  const level = headingLevel(lines[start]) || 6;
+  for (let i = start + 1; i < lines.length; i++) {
+    const lv = headingLevel(lines[i]);
+    if (lv && lv <= level) return i;
+  }
+  return lines.length;
+}
+function isStep5Heading(text) {
+  const t = String(text || '').trim();
+  // The section title, not a later note that mentions the words.
+  return /^step\s*5\b/i.test(t) || /^architecture$/i.test(t);
+}
+// The Step-5 / Architecture section body (last real Step 5 heading → next same-or-higher heading), or null.
+function step5Body(lines) {
+  let s = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const h = lines[i].match(/^#{1,6}\s+(.*?)\s*$/);
+    if (h && isStep5Heading(h[1])) s = i;
+  }
+  if (s === -1) return null;
+  return lines.slice(s + 1, sectionEnd(lines, s)).join('\n');
+}
 
-// Check one dispatch's text. Returns a structured result; never exits.
-function lintText(label, raw) {
+// Check one dispatch's text. Returns a structured result; never exits. `strict` adds the Step-5
+// orphan-citation check (opt-in, so the default CI gate stays stable).
+function lintText(label, raw, strict) {
   const lines = raw.split(/\r?\n/);
   const problems = []; // { finding, line, rule, message }
   const add = (rule, message, line = null, finding = null) => problems.push({ finding, line, rule, message });
@@ -161,10 +254,7 @@ function lintText(label, raw) {
     add('no-section', 'no "Research grounding" section found — every dispatch needs one (Step 3).');
     return { file: label, ok: false, findingCount: 0, problems, findings: [] };
   }
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i++) {
-    if (/^#{1,6}\s/.test(lines[i])) { end = i; break; }
-  }
+  const end = sectionEnd(lines, start);
   const section = lines.slice(start + 1, end);
 
   // Split into findings (numbered items + continuation lines), ignoring fenced code blocks
@@ -179,23 +269,36 @@ function lintText(label, raw) {
     else if (cur && l.trim()) cur.text += ' ' + l.trim();
   });
   if (cur) findings.push(cur);
+  if (inFence) add('unclosed-fence', 'Research grounding has an unclosed code fence, so the lines after it were not checked.', start + 1 + section.length);
 
   if (findings.length === 0) add('no-findings', 'Research grounding has no numbered findings.');
 
   const parsed = [];
+  const seenNumbers = new Set();
   findings.forEach((f, i) => {
-    const n = i + 1;
+    // The citation number is the integer the author wrote, not this array's index.
+    // "2." then "4." are findings 2 and 4. Step 5 and requalify both use that number.
+    const declared = /^(\d+)\.\s/.exec(f.text.trim());
+    const n = declared ? Number(declared[1]) : i + 1;
+    if (seenNumbers.has(n)) add('duplicate-finding-number', `finding number ${n} is used more than once.`, f.line, n);
+    seenNumbers.add(n);
     if (PLACEHOLDER.test(f.text)) add('placeholder', `finding ${n}: still has template placeholders — fill it in.`, f.line, n);
-    // Strip identifiers before the year check so an arXiv id's YYMM prefix
-    // (e.g. 2402 in arXiv:2402.01817) can't masquerade as a publication year.
-    const fNoIds = f.text.replace(/arxiv:\s*\d{4}\.\d{4,5}/gi, '').replace(/10\.\d{4,9}\/\S+/g, '');
+    // Strip identifiers before the year check so digits inside a citation can't masquerade
+    // as a publication year: an arXiv id's YYMM prefix (e.g. 2402 in arXiv:2402.01817), a DOI,
+    // or a year-like URL path segment (e.g. /2024/ in https://host/2024/paper). URLs are
+    // stripped first so a DOI-bearing URL is removed whole.
+    const fNoIds = f.text.replace(/https?:\/\/\S+/gi, '').replace(/arxiv:\s*\d{4}\.\d{4,5}/gi, '').replace(/10\.\d{4,9}\/\S+/g, '');
     if (!YEAR.test(fNoIds)) add('missing-year', `finding ${n}: missing a year (spell it out, e.g. "2024" — an arXiv id alone is not a year).`, f.line, n);
-    if (!AUTHOR.test(f.text)) add('missing-author', `finding ${n}: missing an author before the year (e.g. "Huang et al. 2023").`, f.line, n);
-    const idm = f.text.match(ID);
-    if (!idm) add('missing-id', `finding ${n}: missing an identifier (arXiv:NNNN.NNNNN, DOI, or URL).`, f.line, n);
+    if (!authorOk(f.text)) add('missing-author', `finding ${n}: missing an author before the year (e.g. "Huang et al. 2023").`, f.line, n);
+    // Every identifier, not the first. A URL earlier in the sentence must not hide a later arXiv
+    // or DOI from withdraw / requalify --resolve --mode removed.
+    const identifiers = [];
+    for (const m of f.text.matchAll(new RegExp(ID.source, 'gi'))) {
+      identifiers.push(cleanIdent(m[0]));
+    }
+    if (identifiers.length === 0) add('missing-id', `finding ${n}: missing an identifier (arXiv:NNNN.NNNNN, DOI, URL, or RFC number).`, f.line, n);
     const ym = fNoIds.match(YEAR);
-    const ident = idm ? idm[0].replace(/\s+/g, '').replace(/[).,;]+$/, '') : null;
-    parsed.push({ finding: n, year: ym ? ym[0] : null, identifier: ident });
+    parsed.push({ finding: n, year: ym ? ym[0] : null, identifier: identifiers[0] || null, identifiers });
   });
 
   // Banned gesture anywhere in the section (outside fences): a finding STATES its result,
@@ -208,30 +311,97 @@ function lintText(label, raw) {
     }
   });
 
+  // --strict: flag orphan citations — a finding no Step-5 choice connects to (Step 5 / orphan-citation).
+  if (strict) {
+    const body = step5Body(lines);
+    if (body === null) {
+      add('no-step5', 'strict: no "Step 5" / "Architecture" section found to check finding connections against.');
+    } else {
+      const refs = referencedNumbers(body);
+      findings.forEach((f, i) => {
+        const n = parsed[i].finding;
+        const tok = authorTokenOf(f.text);
+        // Match the author token OR (for a hyphenated surname like "Garcia-Molina") its first
+        // component, so a Step-5 reference to just "Garcia" still connects — the liberal direction.
+        const alts = tok ? [...new Set([tok, tok.split('-')[0]])].filter((t) => t.length >= 2) : [];
+        const tokHit = alts.some((t) => new RegExp('(?<![\\p{L}])' + escRe(t) + '(?![\\p{L}])', 'iu').test(body));
+        if (!refs.has(n) && !tokHit) {
+          add('orphan-citation', `finding ${n}: no Step-5 choice references it (by number or author) — a citation without a connection is noise (Step 5).`, f.line, n);
+        }
+      });
+    }
+  }
+
   return { file: label, ok: problems.length === 0, findingCount: findings.length, problems, findings: parsed };
 }
 
-// Recursively collect *.dispatch.md files under a directory (skips node_modules/.git).
-function walkDispatches(dir) {
+// Recursively collect files whose name matches `re` under `dir`, sorted for determinism.
+// A gate that could not read part of the tree must not report the rest as clean:
+//  - an unreadable directory is recorded on `report.unreadable` (the caller fails the gate);
+//  - a symlink or junction whose name matches `re`, or that points at a directory, is not followed
+//    and is recorded on `report.skippedLinks`. A link to an ordinary non-matching file is ignored.
+// A realpath `seen` set still breaks a cycle if a real directory is reached twice (PH-03).
+// Skips node_modules/.git by name, before the link check.
+function newWalkReport() {
+  return { unreadable: [], skippedLinks: [] };
+}
+function walkFiles(dir, re, seen, report) {
+  seen = seen || new Set();
+  report = report || newWalkReport();
+  let real; try { real = realpathSync(dir); } catch { real = dir; }
+  if (seen.has(real)) return [];
+  seen.add(real);
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); }
+  catch (err) {
+    const code = err && err.code ? err.code : String(err && err.message || err);
+    report.unreadable.push({ dir, code });
+    process.stderr.write(`study-swarm: cannot list ${dir}: ${code}\n`);
+    return [];
+  }
   const out = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+  for (const entry of entries) {
     if (entry.name === 'node_modules' || entry.name === '.git') continue;
     const full = join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walkDispatches(full));
-    else if (/\.dispatch\.md$/i.test(entry.name)) out.push(full);
+    if (entry.isSymbolicLink()) {
+      let followed = null;
+      try { followed = statSync(full); } catch { followed = null; }
+      if (re.test(entry.name) || !followed || followed.isDirectory()) {
+        report.skippedLinks.push(full);
+        process.stderr.write(`study-swarm: not following ${full}\n`);
+      }
+      continue;
+    }
+    if (entry.isDirectory()) out.push(...walkFiles(full, re, seen, report));
+    else if (re.test(entry.name)) out.push(full);
   }
   return out.sort();
 }
+function walkBlockedMessage(report) {
+  if (!report) return null;
+  const parts = [];
+  if (report.unreadable.length) {
+    parts.push(`${report.unreadable.length} unlistable director${report.unreadable.length === 1 ? 'y' : 'ies'} (${report.unreadable.map((u) => u.dir).join(', ')})`);
+  }
+  if (report.skippedLinks.length) {
+    parts.push(`${report.skippedLinks.length} skipped symlink(s) (${report.skippedLinks.join(', ')})`);
+  }
+  return parts.length ? `refusing a clean result — the walk could not read everything under the path you passed: ${parts.join('; ')}` : null;
+}
+function walkDispatches(dir, report) { return walkFiles(dir, /\.dispatch\.md$/i, undefined, report); }
 
 function readTarget(p) {
   try { return { label: p, raw: readFileSync(p, 'utf8') }; }
   catch (err) { fail(2, `cannot read ${p}: ${err && err.code ? err.code : err.message}`); }
 }
 
+const LINT_SCHEMA = 'study-swarm.lint/v1'; // versioned handle for --json consumers (FG-03)
+
 function cmdLint(args) {
   const json = args.includes('--json');
-  const paths = args.filter((a) => a !== '--json');
-  if (paths.length === 0) fail(2, 'usage: study-swarm lint [--json] <file|dir|-> [more...]');
+  const strict = args.includes('--strict'); // opt-in: also flag Step-5 orphan citations (FG-01)
+  const paths = args.filter((a) => a !== '--json' && a !== '--strict');
+  if (paths.length === 0) fail(2, 'usage: study-swarm lint [--json] [--strict] <file|dir|-> [more...]');
 
   const targets = [];
   for (const p of paths) {
@@ -244,7 +414,10 @@ function cmdLint(args) {
     }
     if (!existsSync(p)) fail(2, `path not found: ${p}`);
     if (statSync(p).isDirectory()) {
-      const files = walkDispatches(p);
+      const report = newWalkReport();
+      const files = walkDispatches(p, report);
+      const blocked = walkBlockedMessage(report);
+      if (blocked) fail(1, blocked);
       if (files.length === 0) fail(2, `no .dispatch.md files found under ${p}`);
       for (const f of files) targets.push(readTarget(f));
     } else {
@@ -252,20 +425,23 @@ function cmdLint(args) {
     }
   }
 
-  const results = targets.map((t) => lintText(t.label, t.raw));
+  const results = targets.map((t) => lintText(t.label, t.raw, strict));
   const anyFail = results.some((r) => !r.ok);
 
   if (json) {
-    const payload = results.length === 1 ? results[0] : { ok: !anyFail, files: results };
+    // A versioned envelope so a CI/roleos consumer can detect a shape change (FG-03), matching the
+    // schema/version pattern the lock, sidecar, and receipt objects already carry.
+    const meta = { schema: LINT_SCHEMA, study_swarm_version: VERSION };
+    const payload = results.length === 1 ? { ...meta, ...results[0] } : { ...meta, ok: !anyFail, files: results };
     process.stdout.write(JSON.stringify(payload) + '\n');
     process.exit(anyFail ? 1 : 0);
   }
 
   for (const r of results) {
     if (r.ok) {
-      process.stdout.write(`ok ${r.file}: ${r.findingCount} finding(s), all sourced.\n`);
+      process.stdout.write(`ok ${r.file}: ${r.findingCount} finding(s), all sourced${strict ? ' and connected' : ''}.\n`);
     } else {
-      process.stderr.write(`x ${r.file}: ${r.problems.length} sourcing issue(s)\n`);
+      process.stderr.write(`x ${r.file}: ${r.problems.length} ${strict ? 'issue(s)' : 'sourcing issue(s)'}\n`);
       for (const pr of r.problems) process.stderr.write(`  - ${pr.message}\n`);
     }
   }
@@ -274,6 +450,10 @@ function cmdLint(args) {
       `\nStep 3 (sourcing FORM) is satisfied — this does NOT confirm the citations exist or support the claim.\n` +
       `Run Step 4 (existence + groundedness, a different model family):  roleos verify-citations <file>\n`,
     );
+  } else {
+    // Symmetry with the clean-path nudge: tell the user what to do next (H1).
+    const again = ['study-swarm', 'lint', ...(strict ? ['--strict'] : []), ...paths].join(' ');
+    process.stderr.write(`\nFix the issue(s) above, then re-run ${again}.\n(This checks Step 3 sourcing FORM${strict ? ' + Step 5 connections' : ''} only.)\n`);
   }
   process.exit(anyFail ? 1 : 0);
 }
@@ -281,20 +461,34 @@ function cmdLint(args) {
 // --- lock core (dispatch.lock.json — the PIN_PER_STEP feature) ------------------
 // Design + research grounding: examples/study-swarm-lock.dispatch.md (choices L1-L11).
 // The CLI is a PURE FUNCTION of provided bytes: the orchestration harness emits the record
-// (resolved models + byte-exact prompts + tool schemas + verifier receipt); the CLI only
+// (resolved models + text-normalized prompts + tool schemas + verifier receipt); the CLI only
 // canonicalizes + hashes + validates it. No network, no model calls (L2).
 
-const LOCK_SCHEMA = 'dispatch.lock/v1';
+const LOCK_SCHEMA = 'dispatch.lock/v2';
 
 // Self-describing digest "sha256-<base64>" — the W3C Subresource Integrity form: algorithm-
 // prefixed (so it's algorithm-agile) and used fail-closed on mismatch (L9; lock dispatch finding 38).
 function sriBytes(buf) { return 'sha256-' + createHash('sha256').update(buf).digest('base64'); }
+function sha256DigestOk(value) {
+  const m = /^sha256-([A-Za-z0-9+/]+)=*$/.exec(value);
+  if (!m) return false;
+  return Buffer.from(m[1], 'base64').length === 32;
+}
+// Domain-separation tags (v2): a TEXT preimage and a structured-JSON (JCS) preimage are hashed in
+// DISJOINT spaces, so a prompt whose literal text happens to equal some tool schema's canonical JSON
+// can never produce the same digest as that schema (the tagged-hash / DSSE "hash known bytes with a
+// context" rule the lock dispatch cites — TUF/Rekor/CT). Without a tag, jcsDigest({}) === sriText('{}').
+// The tag carries the schema major, so bumping it is itself a lock-format change — hence the v1 -> v2
+// bump on LOCK_SCHEMA / WITHDRAWN_SCHEMA / RECEIPT_SCHEMA, and the schema gate on read that turns a
+// stale-format lock into a clear "regenerate" message instead of a confusing hash mismatch.
+const DOMAIN_TEXT = 'study-swarm/v2/text\n';
+const DOMAIN_JCS = 'study-swarm/v2/jcs\n';
 // Normalize TEXT before hashing so the same content hashes identically across platforms — strip a
 // BOM, fold CRLF/CR -> LF, NFC-normalize. Without this, a CRLF working tree (Windows) and an LF
 // checkout (git/CI) produce different hashes — the exact cross-platform drift our Q2 findings warn
 // about (RFC 8259 BOM, UAX #15 NFC, and CRLF/LF). Applied to every text input that gets hashed.
 function normText(s) { s = String(s); if (s.charCodeAt(0) === 0xFEFF) s = s.slice(1); return s.replace(/\r\n?/g, '\n').normalize('NFC'); }
-function sriText(str) { return sriBytes(Buffer.from(normText(str), 'utf8')); }
+function sriText(str) { return sriBytes(Buffer.from(DOMAIN_TEXT + normText(str), 'utf8')); }
 
 // RFC 8785 (JCS) canonical JSON, for the structured JSON the CLI assembles ITSELF (the tool
 // surface and the lock body): NFC-normalize strings, sort object keys by UTF-16 code unit (JS
@@ -321,7 +515,7 @@ function jcs(value) {
   };
   return ser(value);
 }
-function jcsDigest(value) { return sriBytes(Buffer.from(jcs(value), 'utf8')); }
+function jcsDigest(value) { return sriBytes(Buffer.from(DOMAIN_JCS + jcs(value), 'utf8')); }
 
 // The lock sits beside its dispatch: <dir>/<stem>.lock.json (stem strips a trailing .dispatch.md).
 function lockPathFor(dispatch) {
@@ -341,18 +535,52 @@ function buildLockObject(dispatchPath, orchestration) {
       if (s == null || s[k] === undefined || s[k] === null) fail(2, `orchestration step ${i + 1} is missing "${k}"`);
       return s[k];
     };
+    const model = need('resolved_model');
+    const prompt = need('prompt');
+    if (typeof model !== 'string' || !model.trim()) fail(2, `orchestration step ${i + 1} resolved_model must be a non-empty string`);
+    if (typeof prompt !== 'string') fail(2, `orchestration step ${i + 1} prompt must be a string`);
+    const qid = need('question_id');
+    if (typeof qid !== 'string' || !qid.trim()) fail(2, `orchestration step ${i + 1} question_id must be a non-empty string`);
     const rec = {
-      question_id: String(need('question_id')),
-      resolved_model: String(need('resolved_model')),       // L6 — the resolved id, never an alias
-      prompt_sha256: sriText(String(need('prompt'))),       // L3 — text-normalized (LF/NFC/BOM), not JCS-restructured
-      tool_schema_sha256: jcsDigest(need('tool_schema')),   // L5 — canonicalized tool surface
+      question_id: qid,
+      resolved_model: model,                                 // L6 — the resolved id, never an alias
+      prompt_sha256: sriText(prompt),                       // L3 — text-normalized (LF/NFC/BOM), not JCS-restructured
+      tool_schema_sha256: (() => {
+        const schema = need('tool_schema');
+        if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+          fail(2, `orchestration step ${i + 1} tool_schema must be a JSON object`);
+        }
+        return jcsDigest(schema);
+      })(),
     };
-    if (s.schema_dialect) rec.schema_dialect = String(s.schema_dialect); // L5 — dialect is contract
-    if (s.params && typeof s.params === 'object') rec.params = s.params;
+    if (s.schema_dialect !== undefined) {
+      if (typeof s.schema_dialect !== 'string' || !s.schema_dialect.trim()) fail(2, `orchestration step ${i + 1} schema_dialect must be a non-empty string`);
+      rec.schema_dialect = s.schema_dialect;
+    }
+    if (s.params !== undefined) {
+      if (!s.params || typeof s.params !== 'object' || Array.isArray(s.params)) fail(2, `orchestration step ${i + 1} params must be a JSON object`);
+      rec.params = s.params;
+    }
     // L7 — output hash for DRIFT DETECTION only (not determinism). The harness may ship the raw
     // output (the CLI hashes it) OR a pre-computed output_sha256 (large outputs needn't be shipped).
-    if (typeof s.output_sha256 === 'string') rec.output_sha256 = s.output_sha256;
-    else if (s.output !== undefined) rec.output_sha256 = typeof s.output === 'string' ? sriText(s.output) : jcsDigest(s.output);
+    // A caller-supplied digest is validated to the SRI sha256- shape here, so a malformed hash is
+    // rejected where it enters rather than mis-surfacing as "drift" on a later verify (PH-05).
+    const hashed = s.output !== undefined ? (typeof s.output === 'string' ? sriText(s.output) : jcsDigest(s.output)) : null;
+    if (s.output_sha256 !== undefined && typeof s.output_sha256 !== 'string') {
+      fail(2, `orchestration step ${i + 1} output_sha256 must be a string`);
+    }
+    if (typeof s.output_sha256 === 'string') {
+      if (!sha256DigestOk(s.output_sha256)) {
+        fail(2, `orchestration step ${i + 1} output_sha256 is not a sha256 digest of 32 bytes: "${s.output_sha256}"`);
+      }
+      if (hashed !== null && hashed !== s.output_sha256) {
+        const preimage = typeof s.output === 'string'
+          ? 'the text-normalized digest under study-swarm/v2/text (BOM stripped, newlines folded to LF, NFC), not a raw SHA-256 of the output bytes'
+          : 'the canonical-JSON digest under study-swarm/v2/jcs';
+        fail(2, `orchestration step ${i + 1} output_sha256 does not match ${preimage}. Recomputed ${hashed}.`);
+      }
+      rec.output_sha256 = s.output_sha256;
+    } else if (hashed !== null) rec.output_sha256 = hashed;
     return rec;
   });
   const lock = {
@@ -362,8 +590,10 @@ function buildLockObject(dispatchPath, orchestration) {
     dispatch_sha256: sriText(dispatchText),  // pins the dispatch text (text-normalized)
     steps,
   };
-  if (orchestration.verification && typeof orchestration.verification === 'object') {
-    lock.verification = orchestration.verification; // L10 — the external-verifier receipt
+  if (orchestration.verification !== undefined) {
+    const v = orchestration.verification;
+    if (!v || typeof v !== 'object' || Array.isArray(v)) fail(2, 'orchestration verification must be a JSON object');
+    lock.verification = v; // L10 — the external-verifier receipt
   }
   // L1/L9 — rollup over the whole body (this object, before lock_sha256 is added) as ONE flat
   // canonical object: distinct keys give domain separation, the steps array's explicit length
@@ -372,12 +602,27 @@ function buildLockObject(dispatchPath, orchestration) {
   return lock;
 }
 
+// A forward-compat guard (PH-04): an artifact whose `schema` string names a version this CLI does
+// not write is reported as "regenerate", not as a confusing hash/integrity mismatch — because the
+// hash preimage (the domain tag) changes with the schema major, a v1 artifact read by a v2 CLI would
+// otherwise fail self-integrity with a misleading "the body was edited" accusation. Absent schema =
+// no gate (the self-integrity check still applies). Returns a message string, or null when in-version.
+function staleSchema(stored, expected, kind, path) {
+  if (stored && typeof stored === 'object' && typeof stored.schema === 'string' && stored.schema !== expected) {
+    return `${path}: ${kind} is schema "${stored.schema}"; this study-swarm v${VERSION} understands "${expected}" — regenerate it (the hash format changed between schema versions).`;
+  }
+  return null;
+}
+
 // Verify a lock: self-integrity always; source-drift too when an orchestration record is supplied.
 // Strict-match, fail-closed (L8): returns a list of problems (empty = clean).
 function verifyLockObject(dispatchPath, lockPath, orchestration) {
   let stored;
   try { stored = JSON.parse(readFileSync(lockPath, 'utf8')); }
   catch (err) { fail(2, `cannot read lock ${lockPath}: ${err && err.code ? err.code : err.message}`); }
+  // 0) Stale-format gate — a wrong-schema lock is "regenerate", not a hash mismatch (PH-04).
+  const stale = staleSchema(stored, LOCK_SCHEMA, 'lock', lockPath);
+  if (stale) return [stale];
   const problems = [];
   // 1) Self-integrity — recompute lock_sha256 over the stored body (detects a hand-edited lock).
   if (!stored || typeof stored !== 'object' || typeof stored.lock_sha256 !== 'string') {
@@ -408,7 +653,46 @@ function verifyLockObject(dispatchPath, lockPath, orchestration) {
   return problems;
 }
 
+// FG-05 — scaffold the orchestration.json the harness must supply, mirroring what `new` does for a
+// dispatch. A deterministic Write of a template (no network, no models); refuses to overwrite. The
+// orchestration record is the harder artifact to hand-author, and its shape was documented only in
+// the large worked examples — this gives a fill-in-the-blanks starting point.
+const orchTemplate = () => JSON.stringify({
+  _note: 'study-swarm orchestration record — the harness-emitted input to `study-swarm lock <dispatch> --from <this file>`. One steps[] entry per Step-2 research agent; replace every <...> placeholder. A full worked record: examples/study-swarm-lock.orchestration.json. Optional per step: params, schema_dialect, output_sha256 (an "sha256-<base64>" digest for drift detection).',
+  steps: [
+    {
+      question_id: '<Q1-short-slug>',
+      resolved_model: '<resolved model id, e.g. claude-opus-4-8 — never a floating alias>',
+      prompt: '<the prompt string this research agent was given; the lock hashes it text-normalized: BOM stripped, CR/CRLF folded to LF, NFC>',
+      tool_schema: { type: 'object', properties: {} },
+      schema_dialect: 'https://json-schema.org/draft/2020-12/schema',
+    },
+  ],
+  verification: {
+    runner: 'roleos verify-citations',
+    tool: 'prism verify --type citations',
+    verifier_family: '<a DIFFERENT model family than the synthesizer>',
+    receipt_id: '<prism-receipt-id>',
+    receipt_chain_sha256: '<the verifier receipt chain hash>',
+  },
+}, null, 2) + '\n';
+
+function orchPathFor(dispatch) {
+  const base = dispatch.split(/[\\/]/).pop().replace(/(\.dispatch)?\.md$/i, '');
+  return join(dirname(dispatch), `${base}.orchestration.json`);
+}
+
 function cmdLock(args) {
+  if (args.includes('--init')) { // FG-05 — scaffold the orchestration record for a dispatch
+    const dispatch = args.filter((a) => a !== '--init')[0];
+    if (!dispatch) fail(2, 'usage: study-swarm lock --init <dispatch>');
+    if (!existsSync(dispatch)) fail(2, `dispatch not found: ${dispatch}`);
+    const out = orchPathFor(dispatch);
+    if (existsSync(out)) fail(2, `refusing to overwrite existing ${out}`);
+    writeFileSync(out, orchTemplate(), 'utf8');
+    process.stdout.write(`Created ${out}\nFill in each step (one per Step-2 research agent), then:  study-swarm lock ${dispatch} --from ${out}\n`);
+    return;
+  }
   const verify = args.includes('--verify');
   const rest = args.filter((a) => a !== '--verify');
   let orchPath = null;
@@ -445,7 +729,7 @@ function cmdLock(args) {
   }
 
   if (!orchestration) {
-    fail(2, 'study-swarm lock <dispatch> requires --from <orchestration.json> — the harness-emitted record of resolved models + byte-exact prompts + tool schemas + the verifier receipt');
+    fail(2, 'study-swarm lock <dispatch> requires --from <orchestration.json> — the harness-emitted record of resolved models + text-normalized prompts + tool schemas + the verifier receipt');
   }
   const lock = buildLockObject(dispatch, orchestration);
   writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf8');
@@ -460,8 +744,8 @@ function cmdLock(args) {
 // receipts deterministically (file reads, JSON I/O, SHA-256); the actual re-verification of a
 // re-grounded finding defers to the sibling runner (C12, honest ceiling). No network, no models.
 
-const WITHDRAWN_SCHEMA = 'dispatch.withdrawn/v1';
-const RECEIPT_SCHEMA = 'withdrawal-receipt/v1';
+const WITHDRAWN_SCHEMA = 'dispatch.withdrawn/v2';
+const RECEIPT_SCHEMA = 'withdrawal-receipt/v2';
 // A CLOSED, machine-readable reason enum — never free text (C3; OpenVEX/CSAF/CycloneDX: a status
 // must carry a structured justification, a bare flag is non-conformant).
 const WITHDRAW_REASONS = ['fabricated', 'misattributed', 'retracted', 'verifier-flipped', 'other'];
@@ -471,12 +755,23 @@ const WITHDRAW_REASONS = ['fabricated', 'misattributed', 'retracted', 'verifier-
 // URL), RFC (RFC NNNN / rfc-editor / datatracker), else a trimmed lowercased URL. Used on BOTH the
 // dispatch's extracted identifier and the user's <identifier> argument so `withdraw arXiv:2402.15089`
 // flags a finding citing `https://arxiv.org/abs/2402.15089v2` (C2).
+// Peel markdown wrappers off an identifier's edges so `<https://…>` and `**10.x/y**` match the
+// bare DOI or URL a caller passes to withdraw. Loops because wrappers nest (`**<url>**`).
+function cleanIdent(raw) {
+  let s = String(raw || '').replace(/\s+/g, '');
+  let prev;
+  do {
+    prev = s;
+    s = s.replace(/^[<*_`"'\u201c\u2018\[]+/, '').replace(/[>*_`"'\u201d\u2019\]).,;]+$/, '');
+  } while (s !== prev && s.length);
+  return s;
+}
 function normIdent(raw) {
-  let s = String(raw || '').trim().toLowerCase().replace(/[).,;]+$/, '');
-  let m = s.match(/arxiv\.org\/(?:abs|pdf)\/(\d{4}\.\d{4,5})/) || s.match(/arxiv:\s*(\d{4}\.\d{4,5})/);
+  let s = cleanIdent(raw).toLowerCase();
+  let m = s.match(/arxiv\.org\/(?:abs|pdf|html)\/(\d{4}\.\d{4,5})/) || s.match(/arxiv:\s*(\d{4}\.\d{4,5})/);
   if (m) return 'arxiv:' + m[1];
   m = s.match(/(?:doi\.org\/|dx\.doi\.org\/|doi:\s*)?(10\.\d{4,9}\/\S+)/);
-  if (m) return 'doi:' + m[1].replace(/[).,;]+$/, '');
+  if (m) return 'doi:' + cleanIdent(m[1]).toLowerCase().replace(/\/+$/, '');
   m = s.match(/rfc[\s/-]?(\d{3,5})/);
   if (m) return 'rfc:' + m[1];
   return s.replace(/\/+$/, '');
@@ -484,34 +779,52 @@ function normIdent(raw) {
 
 // The tombstone sits beside its dispatch: <dir>/<stem>.withdrawn.json (C4 — status travels WITH
 // the artifact, the OCSP-stapling property; stem strips a trailing .dispatch.md).
+function shQuote(s) {
+  const t = String(s);
+  return /[\s"]/.test(t) ? `"${t.replace(/"/g, '\\"')}"` : t;
+}
+function resolveCommands(dispatchPath, identifier) {
+  const d = shQuote(dispatchPath);
+  const id = shQuote(identifier);
+  return [
+    `study-swarm requalify --resolve ${d} ${id} --mode removed`,
+    `study-swarm requalify --resolve ${d} ${id} --mode regrounded --note "<attestation>"`,
+  ];
+}
+function openableDispatch(sidecarPath, storedName) {
+  const name = String(storedName || '');
+  if (!name) return sidecarPath;
+  if (name.includes('/') || name.includes('\\')) return name;
+  return join(dirname(sidecarPath), name);
+}
 function withdrawnPathFor(dispatch) {
   const base = dispatch.split(/[\\/]/).pop().replace(/(\.dispatch)?\.md$/i, '');
   return join(dirname(dispatch), `${base}.withdrawn.json`);
 }
 
-// Recursively collect files matching a regex (skips node_modules/.git), sorted for determinism.
-function walkByExt(dir, re) {
-  const out = [];
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.name === 'node_modules' || entry.name === '.git') continue;
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walkByExt(full, re));
-    else if (re.test(entry.name)) out.push(full);
-  }
-  return out.sort();
-}
+// Recursively collect files matching a regex (delegates to the resilient shared walker).
+function walkByExt(dir, re, report) { return walkFiles(dir, re, undefined, report); }
 
 // The finding numbers in one dispatch whose citation normalizes to `want` (reuses the lint parser,
 // so Step 3 and the compensator agree on what a citation is).
 function findingsCiting(dispatchPath, want) {
   const res = lintText(dispatchPath, readFileSync(dispatchPath, 'utf8'));
-  return (res.findings || []).filter((f) => f.identifier && normIdent(f.identifier) === want).map((f) => f.finding);
+  if ((res.problems || []).some((p) => p.rule === 'unclosed-fence')) {
+    fail(1, `${dispatchPath}: Research grounding has an unclosed code fence, so citations after it were not scanned. Refusing to treat them as absent.`);
+  }
+  return (res.findings || []).filter((f) => {
+    const ids = Array.isArray(f.identifiers) && f.identifiers.length ? f.identifiers : (f.identifier ? [f.identifier] : []);
+    return ids.some((id) => normIdent(id) === want);
+  }).map((f) => f.finding);
 }
 
 // Every dispatch in the corpus citing `target`, with the finding numbers + a content hash each.
 function findDependents(corpus, target) {
   const want = normIdent(target);
-  const files = statSync(corpus).isDirectory() ? walkDispatches(corpus) : [corpus];
+  const report = newWalkReport();
+  const files = statSync(corpus).isDirectory() ? walkDispatches(corpus, report) : [corpus];
+  const blocked = walkBlockedMessage(report);
+  if (blocked) fail(1, blocked);
   const deps = [];
   for (const f of files) {
     const hits = findingsCiting(f, want);
@@ -547,6 +860,8 @@ function loadSidecar(dispatchPath) {
 
 // Recompute the rolled-up hash and write the sidecar; returns the finalized object.
 function writeSidecar(dispatchPath, body) {
+  body.schema = WITHDRAWN_SCHEMA;
+  body.study_swarm_version = VERSION;
   body.dispatch_sha256 = sriText(readFileSync(dispatchPath, 'utf8')); // reconcile to current content
   const finalized = withSha(body, 'withdrawn_sha256');
   writeFileSync(withdrawnPathFor(dispatchPath), JSON.stringify(finalized, null, 2) + '\n', 'utf8');
@@ -578,14 +893,26 @@ function cmdWithdraw(args) {
   const detail = f.detail ? String(f.detail) : '';
 
   const deps = findDependents(corpus, identifier);
-  if (deps.length === 0) fail(2, `no dispatch in ${corpus} cites ${identifier} (normalized: ${want}) — nothing to withdraw`);
+  if (deps.length === 0) fail(2, `no dispatch in ${corpus} cites ${identifier} (normalized: ${want}) — nothing to withdraw. Check the identifier spelling and the --from directory. "study-swarm lint --json ${corpus}" lists the identifiers the parser saw (findings[].identifiers).`);
 
   const dependents = [];
   for (const d of deps) {
     const body = loadSidecar(d.path);
-    const existing = body.withdrawals.find((w) => w.identifier === want);
-    // Idempotent: an identical withdrawal (same id + reason + detail, still withdrawn) is a no-op.
-    const identical = existing && existing.status === 'withdrawn' && existing.reason === String(f.reason) && (existing.detail || '') === detail;
+    const sidePath = withdrawnPathFor(d.path);
+    if (existsSync(sidePath)) {
+      if (!body || typeof body !== 'object' || Array.isArray(body)) fail(2, `sidecar is not a JSON object: ${sidePath}`);
+      if (typeof body.withdrawn_sha256 !== 'string' || body.withdrawn_sha256 !== withSha(body, 'withdrawn_sha256').withdrawn_sha256) {
+        fail(1, `${sidePath}: withdrawn_sha256 self-integrity mismatch (the sidecar was hand-edited). Refusing to withdraw over it.`);
+      }
+    }
+    const existing = (body.withdrawals || []).find((w) => w && w.identifier === want);
+    // Idempotent: an identical withdrawal (same id + reason + detail + finding numbers, still
+    // withdrawn) is a no-op. The findings array is part of the identity so that re-withdrawing
+    // after the dispatch was edited (a citation moved to a different finding #) refreshes the
+    // stale numbers instead of being skipped as "identical".
+    const sameFindings = existing && Array.isArray(existing.findings) &&
+      existing.findings.length === d.findings.length && existing.findings.every((v, i) => v === d.findings[i]);
+    const identical = existing && existing.status === 'withdrawn' && existing.reason === String(f.reason) && (existing.detail || '') === detail && sameFindings;
     if (!identical) {
       if (existing) {
         existing.reason = String(f.reason); existing.detail = detail; existing.status = 'withdrawn'; existing.resolution = null; existing.findings = d.findings;
@@ -594,9 +921,11 @@ function cmdWithdraw(args) {
       }
       body.version += 1;
       body.audit_trail.push({ seq: body.audit_trail.length + 1, event: 'withdraw', identifier: want, reason: String(f.reason), findings: d.findings });
+      const finalized = writeSidecar(d.path, body);
+      dependents.push({ dispatch: finalized.dispatch, path: d.path, dispatch_sha256: finalized.dispatch_sha256, findings: d.findings, sidecar: withdrawnPathFor(d.path).split(/[\\/]/).pop() });
+    } else {
+      dependents.push({ dispatch: body.dispatch, path: d.path, dispatch_sha256: body.dispatch_sha256, findings: d.findings, sidecar: sidePath.split(/[\\/]/).pop() });
     }
-    const finalized = writeSidecar(d.path, body);
-    dependents.push({ dispatch: finalized.dispatch, dispatch_sha256: finalized.dispatch_sha256, findings: d.findings, sidecar: withdrawnPathFor(d.path).split(/[\\/]/).pop() });
   }
 
   const receipt = withSha({
@@ -606,7 +935,7 @@ function cmdWithdraw(args) {
     reason: String(f.reason),
     detail,
     corpus: corpus.split(/[\\/]/).pop() || corpus,
-    dependents,
+    dependents: dependents.map(({ path: _path, ...rest }) => rest),
     post_rollback_state: `${dependents.length} dependent(s) flagged evidence-withdrawn; "study-swarm requalify --check" fails closed until each is removed or re-grounded.`,
   }, 'receipt_sha256');
 
@@ -618,18 +947,79 @@ function cmdWithdraw(args) {
   }
   // Contrastive surfacing — never a silent drop (C10; Buçinca 2024, Bansal 2021).
   process.stdout.write(`Withdrew ${want} (reason: ${f.reason}). ${dependents.length} dependent(s) flagged evidence-withdrawn:\n`);
-  for (const d of dependents) process.stdout.write(`  - ${d.dispatch} (findings ${d.findings.map((n) => '#' + n).join(', ')})\n`);
+  for (const d of dependents) {
+    const where = d.path || d.dispatch;
+    process.stdout.write(`  - ${where} (findings ${d.findings.map((n) => '#' + n).join(', ')})\n`);
+    for (const cmd of resolveCommands(where, want)) process.stdout.write(`    ${cmd}\n`);
+  }
   process.stdout.write(
     `\nYou may have relied on this finding. Each flagged dispatch now HALTS "study-swarm requalify --check"\n` +
-    `until the finding is removed or re-grounded — re-ground or override.\n` +
-    `Receipt ${f.receipt ? String(f.receipt) : '(stdout: pass --json)'} — receipt_sha256 ${receipt.receipt_sha256}\n`);
+    `until you run one of the commands above. Delete the citation before --mode removed.\n` +
+    `${f.receipt ? `Receipt written to ${String(f.receipt)}` : 'No receipt file written — re-run with --receipt <path> or --json to capture it'} — receipt_sha256 ${receipt.receipt_sha256}\n`);
   process.exit(0);
 }
 
 function cmdRequalify(args) {
   if (args.includes('--check')) return requalifyCheck(args.filter((a) => a !== '--check'));
   if (args.includes('--resolve')) return requalifyResolve(args.filter((a) => a !== '--resolve'));
-  fail(2, 'usage: study-swarm requalify --check <corpus-dir>  |  study-swarm requalify --resolve <dispatch> <identifier> --mode removed|regrounded [--note <text>]');
+  if (args.includes('--status')) return requalifyStatus(args.filter((a) => a !== '--status'));
+  fail(2, 'usage: study-swarm requalify --check <corpus-dir>  |  study-swarm requalify --status <corpus-dir> [--json]  |  study-swarm requalify --resolve <dispatch> <identifier> --mode removed|regrounded [--note <text>]');
+}
+
+const STATUS_SCHEMA = 'study-swarm.status/v1';
+
+// FG-04 — the read-only evidence-health VIEW of a corpus (distinct from --check, the CI gate). Walks
+// the .withdrawn.json sidecars and aggregates: withdrawn vs resolved counts, a breakdown by reason
+// and by resolution mode, and a per-dispatch line. Informational — it never fails closed (exit 0),
+// so it composes in a report without gating a build the way --check does.
+function requalifyStatus(args) {
+  const f = parseFlags(args, new Set());
+  const corpus = f._[0];
+  if (!corpus) fail(2, 'usage: study-swarm requalify --status <corpus-dir> [--json]');
+  if (!existsSync(corpus)) fail(2, `corpus not found: ${corpus}`);
+  const walk = newWalkReport();
+  const sidecars = statSync(corpus).isDirectory() ? walkByExt(corpus, /\.withdrawn\.json$/i, walk) : [corpus];
+  const totals = { withdrawn: 0, resolved: 0 };
+  const by_reason = {};
+  const by_mode = {};
+  const dispatches = [];
+  const problems = [];
+  const statusBlocked = walkBlockedMessage(walk);
+  if (statusBlocked) problems.push(statusBlocked);
+  for (const sc of sidecars) {
+    let stored;
+    try { stored = JSON.parse(readFileSync(sc, 'utf8')); }
+    catch (err) { problems.push(`${sc}: not valid JSON (${err.message})`); continue; }
+    if (!stored || typeof stored !== 'object' || Array.isArray(stored)) { problems.push(`${sc}: sidecar is not a JSON object`); continue; }
+    const entries = [];
+    for (const w of stored.withdrawals || []) {
+      if (!w || typeof w !== 'object') { problems.push(`${sc}: a withdrawals entry is not an object`); continue; }
+      const status = w.status === 'resolved' ? 'resolved' : 'withdrawn';
+      totals[status] += 1;
+      if (w.reason) by_reason[w.reason] = (by_reason[w.reason] || 0) + 1;
+      const mode = status === 'resolved' && w.resolution ? w.resolution.mode : null;
+      if (mode) by_mode[mode] = (by_mode[mode] || 0) + 1;
+      entries.push({ identifier: w.identifier, reason: w.reason, status, mode, findings: w.findings || [] });
+    }
+    dispatches.push({ dispatch: openableDispatch(sc, stored.dispatch), sidecar: sc, withdrawals: entries });
+  }
+  const kv = (o) => Object.keys(o).sort().map((k) => `${k}=${o[k]}`).join(', ') || '(none)';
+  if (f.json) {
+    process.stdout.write(JSON.stringify({ schema: STATUS_SCHEMA, study_swarm_version: VERSION, corpus, totals, by_reason, by_mode, dispatches, problems }) + '\n');
+    process.exit(0);
+  }
+  process.stdout.write(`study-swarm requalify --status ${corpus}: ${dispatches.length} sidecar(s), ${totals.withdrawn + totals.resolved} withdrawal(s)\n`);
+  process.stdout.write(`  ${totals.withdrawn} unresolved (evidence-withdrawn), ${totals.resolved} resolved\n`);
+  process.stdout.write(`  by reason: ${kv(by_reason)}\n`);
+  process.stdout.write(`  by resolution mode: ${kv(by_mode)}\n`);
+  for (const d of dispatches) {
+    for (const w of d.withdrawals) {
+      const tag = w.status === 'resolved' ? `resolved: ${w.mode}` : 'withdrawn';
+      process.stdout.write(`  - ${d.dispatch}: ${w.identifier} (${w.reason}) [${tag}] findings ${(w.findings || []).map((n) => '#' + n).join(', ')}\n`);
+    }
+  }
+  for (const p of problems) process.stderr.write(`  ! ${p}\n`);
+  process.exit(0);
 }
 
 function requalifyCheck(args) {
@@ -637,20 +1027,32 @@ function requalifyCheck(args) {
   const corpus = f._[0];
   if (!corpus) fail(2, 'usage: study-swarm requalify --check <corpus-dir> [--json]');
   if (!existsSync(corpus)) fail(2, `corpus not found: ${corpus}`);
-  const sidecars = statSync(corpus).isDirectory() ? walkByExt(corpus, /\.withdrawn\.json$/i) : [corpus];
+  const walk = newWalkReport();
+  const sidecars = statSync(corpus).isDirectory() ? walkByExt(corpus, /\.withdrawn\.json$/i, walk) : [corpus];
   const halts = []; // { sidecar, dispatch, identifier, reason, findings }
   const problems = [];
+  const checkBlocked = walkBlockedMessage(walk);
+  if (checkBlocked) problems.push(checkBlocked);
   let resolvedCount = 0;
   for (const sc of sidecars) {
     let stored;
     try { stored = JSON.parse(readFileSync(sc, 'utf8')); }
     catch (err) { problems.push(`${sc}: not valid JSON (${err.message})`); continue; }
+    // A non-object sidecar (null / array / scalar) is a reportable problem, not a crash — the per-file
+    // loop keeps checking the rest of the corpus and the offending file is named (PH-01).
+    if (!stored || typeof stored !== 'object' || Array.isArray(stored)) {
+      problems.push(`${sc}: sidecar is not a JSON object`); continue;
+    }
+    // Stale-format gate — a wrong-schema sidecar is "regenerate", not a self-integrity failure (PH-04).
+    const stale = staleSchema(stored, WITHDRAWN_SCHEMA, 'sidecar', sc);
+    if (stale) { problems.push(stale); continue; }
     // Self-integrity: a hand-edited sidecar (e.g. a status forged to "resolved") fails closed.
     if (typeof stored.withdrawn_sha256 !== 'string' || stored.withdrawn_sha256 !== withSha(stored, 'withdrawn_sha256').withdrawn_sha256) {
       problems.push(`${sc}: withdrawn_sha256 self-integrity mismatch (the sidecar was hand-edited)`);
     }
     for (const w of stored.withdrawals || []) {
-      if (w.status === 'withdrawn') halts.push({ sidecar: sc.split(/[\\/]/).pop(), dispatch: stored.dispatch, identifier: w.identifier, reason: w.reason, findings: w.findings });
+      if (!w || typeof w !== 'object') { problems.push(`${sc}: a withdrawals entry is not an object`); continue; }
+      if (w.status === 'withdrawn') halts.push({ sidecar: sc, dispatch: openableDispatch(sc, stored.dispatch), identifier: w.identifier, reason: w.reason, findings: w.findings });
       else if (w.status === 'resolved') resolvedCount += 1;
     }
   }
@@ -663,8 +1065,12 @@ function requalifyCheck(args) {
     process.stdout.write(`ok ${corpus}: no unresolved evidence-withdrawn flags (${resolvedCount} resolved).\n`);
     process.exit(0);
   }
-  process.stderr.write(`x requalify --check ${corpus}: ${halts.length} unresolved evidence-withdrawn flag(s) — HALT\n`);
-  for (const h of halts) process.stderr.write(`  - ${h.dispatch}: ${h.identifier} withdrawn (reason: ${h.reason}) — findings ${(h.findings || []).map((n) => '#' + n).join(', ')}. You may have relied on it; re-ground or override.\n`);
+  if (halts.length) process.stderr.write(`x requalify --check ${corpus}: ${halts.length} unresolved evidence-withdrawn flag(s) — HALT\n`);
+  else process.stderr.write(`x requalify --check ${corpus}: ${problems.length} problem(s) — the check could not trust the corpus\n`);
+  for (const h of halts) {
+    process.stderr.write(`  - ${h.dispatch}: ${h.identifier} withdrawn (reason: ${h.reason}) — findings ${(h.findings || []).map((n) => '#' + n).join(', ')}. You may have relied on it.\n`);
+    for (const cmd of resolveCommands(h.dispatch, h.identifier)) process.stderr.write(`    ${cmd}\n`);
+  }
   for (const p of problems) process.stderr.write(`  - ${p}\n`);
   process.exit(1);
 }
@@ -683,7 +1089,11 @@ function requalifyResolve(args) {
   let body;
   try { body = JSON.parse(readFileSync(scPath, 'utf8')); }
   catch (err) { fail(2, `cannot read sidecar ${scPath}: ${err && err.code ? err.code : err.message}`); }
-  const entry = (body.withdrawals || []).find((w) => w.identifier === want);
+  if (!body || typeof body !== 'object' || Array.isArray(body)) fail(2, `sidecar is not a JSON object: ${scPath}`);
+  if (typeof body.withdrawn_sha256 !== 'string' || body.withdrawn_sha256 !== withSha(body, 'withdrawn_sha256').withdrawn_sha256) {
+    fail(1, `${scPath}: withdrawn_sha256 self-integrity mismatch (the sidecar was hand-edited). Refusing to resolve it.`);
+  }
+  const entry = (body.withdrawals || []).find((w) => w && w.identifier === want);
   if (!entry) fail(2, `no evidence-withdrawn flag for ${identifier} (normalized: ${want}) on ${dispatch}`);
 
   if (entry.status === 'resolved') { // Idempotent: re-resolving is a no-op, no new audit entry (C7).
@@ -692,7 +1102,7 @@ function requalifyResolve(args) {
   }
   if (mode === 'removed') {
     const still = findingsCiting(dispatch, want);
-    if (still.length) fail(1, `${dispatch} still cites ${want} (findings ${still.map((n) => '#' + n).join(', ')}) — cannot resolve --mode removed until the finding is removed; use --mode regrounded with --note <attestation> if it was re-verified in place`);
+    if (still.length) fail(1, `${dispatch} still cites ${want} (findings ${still.map((n) => '#' + n).join(', ')}) — cannot resolve --mode removed while the citation is present.\n  Two ways forward:\n    • remove the citation from the dispatch, then re-run --mode removed; or\n    • if it was re-verified in place, use --mode regrounded --note "<attestation>".`);
   } else if (mode === 'regrounded' && !f.note) {
     fail(2, '--mode regrounded requires --note <attestation> — the CLI records that the sibling runner re-verified the finding, it does not itself re-verify');
   }
@@ -705,12 +1115,146 @@ function requalifyResolve(args) {
   process.exit(0);
 }
 
+const RESULTS_SCHEMA = 'study-swarm.results/v1';
+
+function resultsPaths(dispatch) {
+  const base = dispatch.split(/[\\/]/).pop().replace(/(\.dispatch)?\.md$/i, '');
+  return {
+    md: join(dirname(dispatch), `${base}.results.md`),
+    json: join(dirname(dispatch), `${base}.results.json`),
+  };
+}
+
+function firstHeading(raw) {
+  const m = raw.match(/^#{1,6}\s+(.*?)\s*$/m);
+  return m ? m[1].replace(/\*\*/g, '').trim() : '';
+}
+
+function sentenceOf(raw, n) {
+  for (const line of raw.split(/\r?\n/)) {
+    const m = new RegExp('^\\s*' + n + '\\.\\s+(.*)$').exec(line);
+    if (m) return m[1].replace(/\*\*/g, '').replace(/\s+/g, ' ').trim().slice(0, 280);
+  }
+  return '';
+}
+
+function buildResults(dispatchPath) {
+  const raw = readFileSync(dispatchPath, 'utf8');
+  const lint = lintText(dispatchPath, raw, false);
+  const lines = raw.split(/\r?\n/);
+  const body = step5Body(lines);
+  const connected = body === null ? [] : [...referencedNumbers(body)].sort((a, b) => a - b);
+  let lock = { present: false };
+  const lp = lockPathFor(dispatchPath);
+  if (existsSync(lp)) {
+    try {
+      const obj = JSON.parse(readFileSync(lp, 'utf8'));
+      lock = { present: true, schema: obj.schema || null, lock_sha256: obj.lock_sha256 || null };
+    } catch { lock = { present: true, unreadable: true }; }
+  }
+  let withdrawn = [];
+  const sp = withdrawnPathFor(dispatchPath);
+  if (existsSync(sp)) {
+    try {
+      const side = JSON.parse(readFileSync(sp, 'utf8'));
+      withdrawn = (side.withdrawals || []).filter((w) => w && typeof w === 'object').map((w) => ({
+        identifier: w.identifier || null,
+        status: w.status || null,
+        reason: w.reason || null,
+      }));
+    } catch { withdrawn = [{ identifier: null, status: 'unreadable', reason: null }]; }
+  }
+  const record = {
+    schema: RESULTS_SCHEMA,
+    study_swarm_version: VERSION,
+    dispatch: dispatchPath.split(/[\\/]/).pop(),
+    dispatch_sha256: sriText(raw),
+    title: firstHeading(raw),
+    lint: {
+      ok: lint.ok,
+      finding_count: lint.findingCount,
+      problems: (lint.problems || []).map((p) => ({ rule: p.rule, message: p.message })),
+    },
+    findings: (lint.findings || []).map((f) => ({
+      finding: f.finding,
+      year: f.year,
+      identifier: f.identifier,
+      identifiers: f.identifiers || [],
+      line: sentenceOf(raw, f.finding),
+    })),
+    step5_finding_numbers: connected,
+    lock,
+    withdrawn,
+  };
+  return withSha(record, 'results_sha256');
+}
+
+function renderResultsMd(rec, jsonName) {
+  const out = [];
+  out.push(`# ${rec.title || rec.dispatch}`);
+  out.push('');
+  out.push(`Dispatch \`${rec.dispatch}\` (\`${rec.dispatch_sha256}\`). Lint ${rec.lint.ok ? 'clean' : 'failed'}, ${rec.lint.finding_count} finding(s).`);
+  out.push(rec.lock.present && rec.lock.lock_sha256 ? `Lock \`${rec.lock.lock_sha256}\`.` : 'No lock beside this dispatch.');
+  if (rec.withdrawn.length) {
+    out.push('Withdrawn:');
+    for (const w of rec.withdrawn) out.push(`- ${w.identifier} — ${w.status} (${w.reason})`);
+  } else out.push('No withdrawal flags.');
+  out.push('');
+  out.push('## Findings');
+  out.push('');
+  if (!rec.findings.length) out.push('No numbered findings.');
+  for (const f of rec.findings) {
+    out.push(`${f.finding}. ${f.year || 'no year'} — ${f.identifier || 'no identifier'}`);
+    if (f.line) out.push(`   ${f.line}`);
+    out.push('');
+  }
+  if (rec.lint.problems.length) {
+    out.push('## Lint problems');
+    out.push('');
+    for (const p of rec.lint.problems) out.push(`- ${p.rule}: ${p.message}`);
+    out.push('');
+  }
+  out.push('## Kept record');
+  out.push('');
+  out.push(`This sheet is the copy to hand someone. The same facts are kept in \`${jsonName}\` (\`${rec.results_sha256}\`). A later run opens that file. \`study-swarm return --check ${rec.dispatch}\` fails if either copy has drifted from the dispatch.`);
+  out.push('');
+  return out.join('\n');
+}
+
+function cmdReturn(args) {
+  const check = args.includes('--check');
+  const dispatch = args.filter((a) => a !== '--check')[0];
+  if (!dispatch) fail(2, 'usage: study-swarm return <dispatch> [--check]');
+  if (!existsSync(dispatch)) fail(2, `dispatch not found: ${dispatch}`);
+  const rec = buildResults(dispatch);
+  const paths = resultsPaths(dispatch);
+  const jsonName = paths.json.split(/[\\/]/).pop();
+  const md = renderResultsMd(rec, jsonName);
+  if (!check) {
+    writeFileSync(paths.json, JSON.stringify(rec, null, 2) + '\n', 'utf8');
+    writeFileSync(paths.md, md, 'utf8');
+    process.stdout.write(`Results for ${rec.dispatch}: ${paths.md}\nKept record: ${paths.json} (${rec.results_sha256})\n`);
+    process.exit(0);
+  }
+  if (!existsSync(paths.json) || !existsSync(paths.md)) fail(2, `no results beside ${dispatch} — run study-swarm return ${dispatch}`);
+  let kept;
+  try { kept = JSON.parse(readFileSync(paths.json, 'utf8')); }
+  catch (err) { fail(2, `cannot read ${paths.json}: ${err.message}`); }
+  const sheet = readFileSync(paths.md, 'utf8');
+  if (kept.results_sha256 !== rec.results_sha256 || !sheet.includes(rec.results_sha256)) {
+    fail(1, `${jsonName}: results have drifted from ${dispatch}. Re-run study-swarm return ${dispatch}.`);
+  }
+  process.stdout.write(`ok ${jsonName}: ${rec.results_sha256}\n`);
+  process.exit(0);
+}
+
 function main(argv) {
   const [cmd, ...rest] = argv;
   switch (cmd) {
     case 'protocol': return cmdProtocol();
     case 'new': return cmdNew(rest[0]);
     case 'lint': return cmdLint(rest);
+    case 'return': return cmdReturn(rest);
     case 'lock': return cmdLock(rest);
     case 'withdraw': return cmdWithdraw(rest);
     case 'requalify': return cmdRequalify(rest);