@dogfood-lab/study-swarm 2.0.0 → 2.1.0

package/bin/study-swarm.mjs

@@ -19,6 +19,11 @@ USAGE
 COMMANDS
   protocol                 Print the locked protocol (the five steps + halt rules).
   new <slug>               Scaffold a dispatch file <slug>.dispatch.md to fill in.
+  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
@@ -30,7 +35,7 @@ COMMANDS
                            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;
@@ -58,8 +63,9 @@ COMMANDS
 
 EXIT CODES
   0  ok / lint clean / verify clean
-  1  a gate failed: a lint sourcing violation, lock --verify drift, or an
-     unresolved evidence-withdrawn flag (requalify --check)
+  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
@@ -114,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)
@@ -161,7 +167,21 @@ const BANNED = /\b(studies show|research suggests|it'?s well[- ]established|well
 // 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+\(?(?:19|20)\d{2}/u;
+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
@@ -187,17 +207,33 @@ function referencedNumbers(body) {
   }
   return nums;
 }
-// The Step-5 / Architecture section body (last matching heading → next heading/EOF), or null.
+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 && /(step\s*5|architecture)/i.test(h[1])) s = i;
+    if (h && isStep5Heading(h[1])) s = i;
   }
   if (s === -1) return null;
-  let e = lines.length;
-  for (let i = s + 1; i < lines.length; i++) { if (/^#{1,6}\s/.test(lines[i])) { e = i; break; } }
-  return lines.slice(s + 1, e).join('\n');
+  return lines.slice(s + 1, sectionEnd(lines, s)).join('\n');
 }
 
 // Check one dispatch's text. Returns a structured result; never exits. `strict` adds the Step-5
@@ -218,10 +254,7 @@ function lintText(label, raw, strict) {
     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
@@ -236,12 +269,19 @@ function lintText(label, raw, strict) {
     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 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,
@@ -249,12 +289,16 @@ function lintText(label, raw, strict) {
     // 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, URL, or RFC number).`, 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,
@@ -275,7 +319,7 @@ function lintText(label, raw, strict) {
     } else {
       const refs = referencedNumbers(body);
       findings.forEach((f, i) => {
-        const n = i + 1;
+        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.
@@ -292,31 +336,59 @@ function lintText(label, raw, strict) {
 }
 
 // Recursively collect files whose name matches `re` under `dir`, sorted for determinism.
-// Resilient by design:
-//  - an unreadable directory (EACCES/EPERM/ENOTDIR) is SKIPPED with a stderr note, never fatal, so a
-//    single bad node does not abort a whole-corpus lint / withdraw / requalify (PH-02);
-//  - symlinked entries are not followed, and a realpath `seen` set breaks directory-junction cycles
-//    (common on Windows) that would otherwise recurse until stack / path-length exhaustion (PH-03).
-// Skips node_modules/.git.
-function walkFiles(dir, re, seen) {
+// 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 []; // already visited via another path — junction/symlink cycle guard
+  if (seen.has(real)) return [];
   seen.add(real);
   let entries;
   try { entries = readdirSync(dir, { withFileTypes: true }); }
-  catch (err) { process.stderr.write(`study-swarm: skipping ${dir}: ${err && err.code ? err.code : err.message}\n`); return []; }
+  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 entries) {
     if (entry.name === 'node_modules' || entry.name === '.git') continue;
-    if (entry.isSymbolicLink()) continue; // don't follow symlinks (cycle + directory-escape safety)
     const full = join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walkFiles(full, re, seen));
+    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 walkDispatches(dir) { return walkFiles(dir, /\.dispatch\.md$/i); }
+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') }; }
@@ -342,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 {
@@ -377,7 +452,8 @@ function cmdLint(args) {
     );
   } else {
     // Symmetry with the clean-path nudge: tell the user what to do next (H1).
-    process.stderr.write(`\nFix the issue(s) above, then re-run study-swarm lint. (This checks Step 3 sourcing FORM${strict ? ' + Step 5 connections' : ''} only.)\n`);
+    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);
 }
@@ -385,7 +461,7 @@ 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/v2';
@@ -393,6 +469,11 @@ 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
@@ -454,24 +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).
     // 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 (!/^sha256-[A-Za-z0-9+/]+=*$/.test(s.output_sha256)) {
-        fail(2, `orchestration step ${i + 1} output_sha256 is not an "sha256-<base64>" digest: "${s.output_sha256}"`);
+      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 (s.output !== undefined) rec.output_sha256 = typeof s.output === 'string' ? sriText(s.output) : jcsDigest(s.output);
+    } else if (hashed !== null) rec.output_sha256 = hashed;
     return rec;
   });
   const lock = {
@@ -481,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
@@ -552,7 +663,7 @@ const orchTemplate = () => JSON.stringify({
     {
       question_id: '<Q1-short-slug>',
       resolved_model: '<resolved model id, e.g. claude-opus-4-8 — never a floating alias>',
-      prompt: '<the byte-exact prompt string this research agent was given>',
+      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',
     },
@@ -618,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');
@@ -644,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(/\/+$/, '');
@@ -657,25 +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 (delegates to the resilient shared walker).
-function walkByExt(dir, re) { return walkFiles(dir, re); }
+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);
@@ -711,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');
@@ -742,12 +893,19 @@ 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. Check the identifier spelling and the --from directory; "study-swarm lint ${corpus}" lists the citations the tool can see.`);
+  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);
+    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
@@ -763,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({
@@ -775,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');
 
@@ -787,10 +947,14 @@ 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` +
+    `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);
 }
@@ -813,12 +977,15 @@ function requalifyStatus(args) {
   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 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 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')); }
@@ -826,6 +993,7 @@ function requalifyStatus(args) {
     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;
@@ -833,7 +1001,7 @@ function requalifyStatus(args) {
       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: stored.dispatch, sidecar: sc.split(/[\\/]/).pop(), withdrawals: entries });
+    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) {
@@ -859,9 +1027,12 @@ 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;
@@ -880,7 +1051,8 @@ function requalifyCheck(args) {
       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;
     }
   }
@@ -893,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);
 }
@@ -913,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).
@@ -935,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);