@dogfood-lab/study-swarm 1.1.0 → 1.3.0

package/README.zh.md

@@ -76,6 +76,11 @@ npm i -g @dogfood-lab/study-swarm     # or run ad-hoc: npx @dogfood-lab/study-sw
 | `study-swarm protocol` | 打印完整的协议——五个步骤、停止表以及来源标准。 |
 | `study-swarm new <slug>` | 创建一个`<slug>.dispatch.md`文件，其中包含五步流程的框架，以便进行填充。 |
 | `study-swarm lint [--json] <path…>` | 根据来源标准检查工作流程的*研究扎实性*——每条研究结果都需要作者、年份和一个可解析的标识符（arXiv / DOI / URL）；“研究表明……”这种含糊其辞的方式将被拒绝。如果存在违规行为，则退出代码为`1`，以便在CI中进行筛选。`<path>`可以是文件、目录（递归地检查所有`.dispatch.md`文件），或者`-`表示标准输入；`--json`会输出机器可读的报告。 |
+| `study-swarm lock <dispatch> --from <orchestration.json>` | 将一个调度固定下来以便重放——编写 `<dispatch>.lock.json`，其中包含基于内容的哈希值，按照步骤 2 中的代理进行操作，包括**已解析的模型 ID** + **字节级精确提示的 SHA-256 值** + **工具模式的 SHA-256 值**，以及步骤 4 中的**验证者凭证**，并将它们组合成一个 `lock_sha256`。 |
+| `study-swarm lock --verify <dispatch> [--from …]` | 重新计算这些哈希值并确认它们与锁匹配；如果出现任何偏差，则退出并返回 1，因此它就像软件包的 lock 文件一样，可以控制 CI 流程。如果不使用 `--from` 参数，则会检查锁自身的完整性。 |
+| `study-swarm withdraw <id> --reason <reason> [--from <dir>] [--receipt <path>]` | **规范回滚补偿器。** 标记语料库中每个引用 `<id>` 作为“证据已撤回”（一个墓碑侧文件 `<slug>.withdrawn.json`——标记，永不删除）的文档，并生成基于内容的撤回凭证。 `--reason` ∈ `fabricated · misattributed · retracted · verifier-flipped · other`。 |
+| `study-swarm requalify --check <corpus-dir>` | 对于任何带有未解决的“证据已撤回”标志的文档，执行失败安全机制（退出代码为 `1`）——这是一种“andon”（警报），它会**阻止**已撤回结论的依赖项，直到该结论被删除或重新验证。用于门控 CI。 |
+| `study-swarm requalify --resolve <dispatch> <id> --mode removed\ | regrounded [--note …]` | 一旦该结论被删除（引用消失）或重新验证（由辅助运行器重新验证；`--note` 记录证明），则清除标志。幂等性；附加到侧文件的审计跟踪中。 |
 
 `lint`是确定性的——不调用任何模型——因此可以在CI中安全使用。它在本地强制执行**第3步的来源标准**；基于模型的**第4步**验证仍然依赖于[`roleos verify-citations`](https://github.com/mcp-tool-shop-org/role-os) → prism。
 
@@ -88,7 +93,7 @@ study-swarm lint my-decision.dispatch.md         # enforce the sourcing standard
 roleos verify-citations my-decision.dispatch.md  # model-based Step 4 (different family, via prism)
 ```
 
-两个完整的、符合“lint”规范的工作流程示例以供参考：[`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md)（协议的核心决策，简洁）和[`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md）（完整的v1.1设计流程——27条引用，每一条都经过外部验证）。
+四个完整的、经过代码检查的文档作为参考发布：[`examples/study-swarm-self.dispatch.md`](examples/study-swarm-self.dispatch.md)（协议的核心决策，简洁），[`examples/study-swarm-v1_1.dispatch.md`](examples/study-swarm-v1_1.dispatch.md)（完整的 v1.1 设计版本——27 个引用，每个引用都经过外部验证），[`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md)（v1.2 锁定设计——39 个引用，通过运行器进行门控，并且是第一个发布其自身锁定的文档），以及 [`examples/study-swarm-canon-rollback.dispatch.md`](examples/study-swarm-canon-rollback.dispatch.md)（v1.3 规范回滚设计——27 个引用，涵盖撤销、撤稿、连续事件和构建失效，并且是第一个被撤回然后重新验证的文档）。
 
 ### 在CI中进行筛选
 
@@ -114,6 +119,26 @@ jobs:
       - run: npx @dogfood-lab/study-swarm@latest lint dispatches/
 ```
 
+### 将一个调度固定下来以便重放 (`dispatch.lock.json`)
+
+只有当你能够说明*是什么产生了它*时，才能对经过验证的调度进行审计。`study-swarm lock` 编写一个配套的锁文件，该文件基于内容进行哈希处理，按照研究代理进行操作，包括**已解析的模型 ID（绝不使用浮动别名）**、**字节级精确提示的 SHA-256 值**以及**工具模式的 SHA-256 值**，以及外部**验证者凭证**——所有这些都组合成一个 `lock_sha256`。`study-swarm lock --verify` 重新计算这些哈希值，并且如果出现任何偏差，则会失败并停止，因此，如果提示、模型或工具发生更改，系统都会检测到——这是 [PIN_PER_STEP](https://github.com/dogfood-lab/study-swarm) 可重复性标准的可执行版本。该框架会输出记录；CLI 保持零依赖和无网络状态，仅进行规范化（RFC 8785）、哈希处理和验证。
+
+**它固定输入，而不是输出。** 固定模型 + 提示 + 温度并不能使 LLM 的输出完全相同——批处理不变性、浮点数非结合律、混合专家路由以及无声提供者漂移都超出了离线工具的控制范围。因此，该锁为您提供**可重放的输入和可检测偏差的输出**，而不是“确定性重放”。该设计基于 [`examples/study-swarm-lock.dispatch.md`](examples/study-swarm-lock.dispatch.md) 中的每一处引用，并且是第一个发布其自身锁（[`examples/study-swarm-lock.lock.json`](examples/study-swarm-lock.lock.json)）的调度文件。
+
+### 回滚已撤回的结论 (`withdraw` / `requalify`)
+
+经过验证的结论成为**规范**——它会影响下游决策。那么，如果稍后该结论被**撤回**（在重新运行时发现引用是捏造/错误归因，引用的论文被撤稿，或者门控机制将其标记），会发生什么？简单的 `git revert` 并不足以解决问题，因为该结论已经传播开来。规范回滚补偿器使清理过程可执行：
+
+```bash
+study-swarm withdraw arXiv:2402.15089 --reason misattributed --from dispatches/ --receipt rollback.json
+#   → flags every dispatch citing it `evidence-withdrawn` (a tombstone sidecar — flag, never delete)
+#     and writes a content-addressed withdrawal receipt naming every dependent.
+study-swarm requalify --check dispatches/          # exit 1 while any flag is unresolved — the andon HALT
+study-swarm requalify --resolve d.dispatch.md arXiv:2402.15089 --mode removed   # or: --mode regrounded --note "<attestation>"
+```
+
+`requalify --check` 在每个带有标志的结论被删除或**重新验证**（由辅助运行器重新验证——CLI 记录证明，它本身不会重新验证）之前，将**失败安全**。撤回以**对比方式**呈现，而不是默默地删除。所有内容——墓碑和凭证——都基于内容进行寻址且可检测漂移，并且仅对*证据*层进行操作：`lock --verify` 不受撤回的影响。该设计基于 [`examples/study-swarm-canon-rollback.dispatch.md`](examples/study-swarm-canon-rollback.dispatch.md)，并且 [PROTOCOL.md](PROTOCOL.md) §“补偿已撤回的结论”是可执行的形式。这是**NAMED_COMPENSATORS** 标准的可执行版本：一种命名的、幂等的撤销操作，它会留下一个已知的后期状态和一个凭证。
+
 ## 用一句话概括其工作原理
 
 **及时性**——该领域发展迅速；要求提供具体的带有年份的研究，可以防止设计落后18个月。**功能性**——证据表明哪些*方法失败*，而不仅仅是哪些有效（解释可能会增加对*错误*人工智能的过度依赖——Bansal等人，2021年，[arXiv:2006.14779](https://arxiv.org/abs/2006.14779)）。**安全性**——受验证器保护的范围是证据支持的架构，并且协议对其自身的输出进行强制执行。来源不是学术上的形式主义；它是证据链。
@@ -124,7 +149,7 @@ jobs:
 
 ## 状态
 
-一个可用的协议，其自身的机制对其进行了外部验证——不同的模型系列检查其引用（参见上面的证明）。**v1.1**改进了验证器，弥补了第一个版本中存在的不足：分解/三元扎实性、生成时扎实性、由预言机控制的级联机制以及经过校准的弃权——每项都基于经过验证的v1.1工作流程。此仓库是公共参考；[PROTOCOL.md](PROTOCOL.md)是可执行的形式。它是[dogfood-lab](https://github.com/dogfood-lab)系列的一部分——用于在人工智能时代构建方法和示例。
+一个可工作的协议，由其自身的机制进行外部验证——不同的模型系列检查其引用（参见上面的证明）。**v1.1** 改进了验证器，而第一个版本是静默的：分解/三元验证、生成时验证、用于组合透镜的基于 oracle 的级联以及校准后的弃权——每个都基于经过验证的 v1.1 文档。**v1.2** 使文档可重放：`study-swarm lock` 为每个步骤固定已解决的模型、提示和工具模式，以及验证器凭证，并且 `lock --verify` 在检测到漂移时会失败安全。**v1.3** 使回滚操作可执行：当已经成为规范的结论被撤回时，`study-swarm withdraw` 会标记所有依赖项，并且 `requalify --check` 会阻止它们，直到它们被删除或重新验证——这是一种命名的、带有凭证的、幂等的补偿器。此仓库是公共参考；[PROTOCOL.md](PROTOCOL.md) 是可执行的形式。它是 [dogfood-lab](https://github.com/dogfood-lab) 系列的一部分——用于在人工智能时代构建的方法和示例。
 
 采用MIT许可证。
 

package/bin/study-swarm.mjs

@@ -22,6 +22,27 @@ COMMANDS
   lint [--json] <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.
+  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
+                           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;
+                           drift exits 1 (gates CI). Without --from, checks lock self-integrity.
+  withdraw <identifier> --reason <reason> [--detail <text>] [--from <dir>] [--receipt <path>]
+                           Canon-rollback compensator. Flag every dispatch in the corpus whose
+                           Research grounding cites <identifier> as "evidence-withdrawn" (a
+                           tombstone sidecar <slug>.withdrawn.json — flag, never delete), and emit
+                           a content-addressed withdrawal receipt. --reason is one of:
+                           fabricated | misattributed | retracted | verifier-flipped | other.
+  requalify --check <corpus-dir>
+                           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 --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
+                           the attestation). Idempotent; appends to the sidecar's audit trail.
   help                     Show this help.
   version                  Print the version.
 
@@ -47,7 +68,7 @@ function fail(code, msg) {
 // Short hash of the vendored PROTOCOL.md, so a scaffolded dispatch records the exact
 // methodology version it was authored against (the package vendors PROTOCOL.md for this).
 function protocolHash() {
-  try { return createHash('sha256').update(readFileSync(PROTOCOL_PATH)).digest('hex').slice(0, 16); }
+  try { return createHash('sha256').update(normText(readFileSync(PROTOCOL_PATH, 'utf8'))).digest('hex').slice(0, 16); }
   catch { return 'unknown'; }
 }
 
@@ -257,12 +278,442 @@ function cmdLint(args) {
   process.exit(anyFail ? 1 : 0);
 }
 
+// --- 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
+// canonicalizes + hashes + validates it. No network, no model calls (L2).
+
+const LOCK_SCHEMA = 'dispatch.lock/v1';
+
+// 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'); }
+// 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')); }
+
+// 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
+// default string sort), no inter-token whitespace, ECMAScript-shortest numbers, UTF-8 (L4).
+// The PROMPT is NOT JCS-restructured — it is the literal string the model conditioned on, so it is
+// hashed as text (L3; JWS/DSSE hash-known-bytes rule, findings 12/23) under the SAME newline/BOM/NFC
+// normalization (normText) so the same prompt hashes identically across platforms (findings 10/11).
+function jcs(value) {
+  const ser = (v) => {
+    if (v === null) return 'null';
+    const t = typeof v;
+    if (t === 'boolean') return v ? 'true' : 'false';
+    if (t === 'number') {
+      if (!Number.isFinite(v)) throw new Error('JCS: non-finite number not allowed');
+      return JSON.stringify(v); // ECMAScript Number->String shortest round-trip
+    }
+    if (t === 'string') return JSON.stringify(normText(v));
+    if (Array.isArray(v)) return '[' + v.map(ser).join(',') + ']';
+    if (t === 'object') {
+      return '{' + Object.keys(v).sort()
+        .map((k) => JSON.stringify(normText(k)) + ':' + ser(v[k])).join(',') + '}';
+    }
+    throw new Error(`JCS: unsupported type ${t}`);
+  };
+  return ser(value);
+}
+function jcsDigest(value) { return sriBytes(Buffer.from(jcs(value), 'utf8')); }
+
+// The lock sits beside its dispatch: <dir>/<stem>.lock.json (stem strips a trailing .dispatch.md).
+function lockPathFor(dispatch) {
+  const base = dispatch.split(/[\\/]/).pop().replace(/(\.dispatch)?\.md$/i, '');
+  return join(dirname(dispatch), `${base}.lock.json`);
+}
+
+// Build the lock object from the dispatch bytes + the harness-emitted orchestration record.
+function buildLockObject(dispatchPath, orchestration) {
+  const dispatchText = readFileSync(dispatchPath, 'utf8');
+  const protocolText = readFileSync(PROTOCOL_PATH, 'utf8');
+  if (!orchestration || !Array.isArray(orchestration.steps) || orchestration.steps.length === 0) {
+    fail(2, 'orchestration record has no non-empty "steps" array');
+  }
+  const steps = orchestration.steps.map((s, i) => {
+    const need = (k) => {
+      if (s == null || s[k] === undefined || s[k] === null) fail(2, `orchestration step ${i + 1} is missing "${k}"`);
+      return s[k];
+    };
+    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
+    };
+    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;
+    // 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);
+    return rec;
+  });
+  const lock = {
+    schema: LOCK_SCHEMA,
+    study_swarm_version: VERSION,
+    protocol_sha256: sriText(protocolText),  // pins the methodology version (text-normalized)
+    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
+  }
+  // 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
+  // commits to exactly N steps (no odd-leaf duplication).
+  lock.lock_sha256 = jcsDigest(lock);
+  return lock;
+}
+
+// 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}`); }
+  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') {
+    problems.push('lock has no lock_sha256 string');
+  } else {
+    const { lock_sha256, ...body } = stored;
+    const recomputed = jcsDigest(body);
+    if (lock_sha256 !== recomputed) {
+      problems.push(`lock_sha256 mismatch (the lock body was edited): stored ${lock_sha256} != recomputed ${recomputed}`);
+    }
+  }
+  // 2) Source drift — re-derive the deterministic hashes from the live inputs and strict-compare.
+  if (orchestration) {
+    const fresh = buildLockObject(dispatchPath, orchestration);
+    const cmp = (label, a, b) => { if (a !== b) problems.push(`${label} drift: lock ${b} != re-derived ${a}`); };
+    cmp('lock_sha256', fresh.lock_sha256, stored.lock_sha256); // the authoritative rollup guard
+    cmp('protocol_sha256', fresh.protocol_sha256, stored.protocol_sha256);
+    cmp('dispatch_sha256', fresh.dispatch_sha256, stored.dispatch_sha256);
+    const a = fresh.steps || [], b = Array.isArray(stored.steps) ? stored.steps : [];
+    if (a.length !== b.length) problems.push(`step count drift: re-derived ${a.length} != lock ${b.length}`);
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+      for (const k of ['question_id', 'resolved_model', 'prompt_sha256', 'tool_schema_sha256']) {
+        cmp(`steps[${i}].${k}`, a[i][k], b[i][k]);
+      }
+      if (a[i].output_sha256 || b[i].output_sha256) cmp(`steps[${i}].output_sha256`, a[i].output_sha256, b[i].output_sha256);
+    }
+  }
+  return problems;
+}
+
+function cmdLock(args) {
+  const verify = args.includes('--verify');
+  const rest = args.filter((a) => a !== '--verify');
+  let orchPath = null;
+  const fromIdx = rest.indexOf('--from');
+  if (fromIdx !== -1) {
+    orchPath = rest[fromIdx + 1];
+    if (!orchPath) fail(2, 'usage: --from <orchestration.json>');
+    rest.splice(fromIdx, 2);
+  }
+  const dispatch = rest[0];
+  if (!dispatch) {
+    fail(2, 'usage: study-swarm lock <dispatch> --from <orchestration.json>  |  study-swarm lock --verify <dispatch> [--from <orchestration.json>]');
+  }
+  if (!existsSync(dispatch)) fail(2, `dispatch not found: ${dispatch}`);
+  let orchestration = null;
+  if (orchPath) {
+    if (!existsSync(orchPath)) fail(2, `orchestration record not found: ${orchPath}`);
+    try { orchestration = JSON.parse(readFileSync(orchPath, 'utf8')); }
+    catch (err) { fail(2, `orchestration record is not valid JSON: ${err.message}`); }
+  }
+  const lockPath = lockPathFor(dispatch);
+
+  if (verify) {
+    if (!existsSync(lockPath)) fail(2, `no lock at ${lockPath} — create it with:  study-swarm lock ${dispatch} --from <orchestration.json>`);
+    const problems = verifyLockObject(dispatch, lockPath, orchestration);
+    if (problems.length === 0) {
+      const scope = orchestration ? 'lock integrity verified + no source drift' : 'lock self-integrity verified (pass --from to also check source drift)';
+      process.stdout.write(`ok ${lockPath}: ${scope}.\n`);
+      process.exit(0);
+    }
+    process.stderr.write(`x ${lockPath}: ${problems.length} drift/integrity issue(s)\n`);
+    for (const p of problems) process.stderr.write(`  - ${p}\n`);
+    process.exit(1);
+  }
+
+  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');
+  }
+  const lock = buildLockObject(dispatch, orchestration);
+  writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf8');
+  process.stdout.write(`Created ${lockPath}\nlock_sha256: ${lock.lock_sha256}\nVerify with:  study-swarm lock --verify ${dispatch} --from ${orchPath}\n`);
+}
+
+// --- canon-rollback core (the requalify_dependent_slices compensator) -----------
+// Design + research grounding: examples/study-swarm-canon-rollback.dispatch.md (choices C1-C12).
+// The compensator operates on the VOLATILE evidence layer (a per-dispatch tombstone sidecar),
+// never the STABLE protocol/lock shape — `lock --verify` is unaffected by withdraw/resolve (C11,
+// the Parnas boundary). Like `lock`, the CLI is a PURE FUNCTION of bytes: it flags, gates, and
+// 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';
+// 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'];
+
+// Normalize a citation identifier to ONE canonical key so the SAME source matches across the forms
+// a finding might cite it in: arXiv (bare / arxiv.org URL / version suffix), DOI (bare / doi.org
+// 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).
+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})/);
+  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(/[).,;]+$/, '');
+  m = s.match(/rfc[\s/-]?(\d{3,5})/);
+  if (m) return 'rfc:' + m[1];
+  return s.replace(/\/+$/, '');
+}
+
+// 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 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();
+}
+
+// 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);
+}
+
+// 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 deps = [];
+  for (const f of files) {
+    const hits = findingsCiting(f, want);
+    if (hits.length) deps.push({ path: f, dispatch_sha256: sriText(readFileSync(f, 'utf8')), findings: hits });
+  }
+  return deps;
+}
+
+// Content-address the sidecar/receipt exactly like the lock: jcsDigest over the body with the hash
+// field omitted (C8/C9 — TUF/Rekor/CT/Git content-addressing; self-integrity catches a hand-edit).
+function withSha(body, key) {
+  const { [key]: _omit, ...rest } = body;
+  return { ...rest, [key]: jcsDigest(rest) };
+}
+
+// Load an existing tombstone sidecar, or seed a fresh one for `dispatch`.
+function loadSidecar(dispatchPath) {
+  const p = withdrawnPathFor(dispatchPath);
+  if (existsSync(p)) {
+    try { return JSON.parse(readFileSync(p, 'utf8')); }
+    catch (err) { fail(2, `cannot read sidecar ${p}: ${err && err.code ? err.code : err.message}`); }
+  }
+  return {
+    schema: WITHDRAWN_SCHEMA,
+    study_swarm_version: VERSION,
+    dispatch: dispatchPath.split(/[\\/]/).pop(),
+    dispatch_sha256: sriText(readFileSync(dispatchPath, 'utf8')),
+    version: 0,
+    withdrawals: [],
+    audit_trail: [],
+  };
+}
+
+// Recompute the rolled-up hash and write the sidecar; returns the finalized object.
+function writeSidecar(dispatchPath, body) {
+  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');
+  return finalized;
+}
+
+function parseFlags(args, withValue) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      if (withValue.has(k)) { out[k] = args[++i]; }
+      else out[k] = true;
+    } else out._.push(a);
+  }
+  return out;
+}
+
+function cmdWithdraw(args) {
+  const f = parseFlags(args, new Set(['reason', 'detail', 'from', 'receipt']));
+  const identifier = f._[0];
+  if (!identifier) fail(2, 'usage: study-swarm withdraw <identifier> --reason <reason> [--detail <text>] [--from <corpus-dir>] [--receipt <path>] [--json]');
+  if (!f.reason) fail(2, `withdraw requires --reason <${WITHDRAW_REASONS.join('|')}> — a withdrawal with no machine-readable cause is not allowed`);
+  if (!WITHDRAW_REASONS.includes(String(f.reason))) fail(2, `invalid --reason "${f.reason}" — use one of: ${WITHDRAW_REASONS.join(', ')}`);
+  const corpus = f.from || '.';
+  if (!existsSync(corpus)) fail(2, `corpus not found: ${corpus}`);
+  const want = normIdent(identifier);
+  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`);
+
+  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;
+    if (!identical) {
+      if (existing) {
+        existing.reason = String(f.reason); existing.detail = detail; existing.status = 'withdrawn'; existing.resolution = null; existing.findings = d.findings;
+      } else {
+        body.withdrawals.push({ identifier: want, reason: String(f.reason), detail, findings: d.findings, status: 'withdrawn', resolution: null });
+      }
+      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, dispatch_sha256: finalized.dispatch_sha256, findings: d.findings, sidecar: withdrawnPathFor(d.path).split(/[\\/]/).pop() });
+  }
+
+  const receipt = withSha({
+    schema: RECEIPT_SCHEMA,
+    study_swarm_version: VERSION,
+    identifier: want,
+    reason: String(f.reason),
+    detail,
+    corpus: corpus.split(/[\\/]/).pop() || corpus,
+    dependents,
+    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');
+
+  if (f.receipt) writeFileSync(String(f.receipt), JSON.stringify(receipt, null, 2) + '\n', 'utf8');
+
+  if (f.json) {
+    process.stdout.write(JSON.stringify(receipt) + '\n');
+    process.exit(0);
+  }
+  // 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`);
+  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`);
+  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>]');
+}
+
+function requalifyCheck(args) {
+  const f = parseFlags(args, new Set());
+  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 halts = []; // { sidecar, dispatch, identifier, reason, findings }
+  const problems = [];
+  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; }
+    // 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 });
+      else if (w.status === 'resolved') resolvedCount += 1;
+    }
+  }
+  const red = halts.length > 0 || problems.length > 0;
+  if (f.json) {
+    process.stdout.write(JSON.stringify({ ok: !red, halts, resolved: resolvedCount, problems }) + '\n');
+    process.exit(red ? 1 : 0);
+  }
+  if (!red) {
+    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`);
+  for (const p of problems) process.stderr.write(`  - ${p}\n`);
+  process.exit(1);
+}
+
+function requalifyResolve(args) {
+  const f = parseFlags(args, new Set(['mode', 'note']));
+  const dispatch = f._[0];
+  const identifier = f._[1];
+  if (!dispatch || !identifier) fail(2, 'usage: study-swarm requalify --resolve <dispatch> <identifier> --mode removed|regrounded [--note <text>]');
+  if (!existsSync(dispatch)) fail(2, `dispatch not found: ${dispatch}`);
+  const scPath = withdrawnPathFor(dispatch);
+  if (!existsSync(scPath)) fail(2, `no tombstone sidecar at ${scPath} — nothing to resolve`);
+  const mode = f.mode ? String(f.mode) : null;
+  if (mode !== 'removed' && mode !== 'regrounded') fail(2, 'requalify --resolve requires --mode removed|regrounded');
+  const want = normIdent(identifier);
+  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 (!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).
+    process.stdout.write(`ok ${scPath}: ${want} already resolved (mode: ${entry.resolution && entry.resolution.mode}) — no-op.\n`);
+    process.exit(0);
+  }
+  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`);
+  } 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');
+  }
+  entry.status = 'resolved';
+  entry.resolution = { mode, note: f.note ? String(f.note) : '' };
+  body.version += 1;
+  body.audit_trail.push({ seq: (body.audit_trail || []).length + 1, event: 'resolve', identifier: want, mode, note: f.note ? String(f.note) : '' });
+  const finalized = writeSidecar(dispatch, body);
+  process.stdout.write(`Resolved ${want} on ${finalized.dispatch} (mode: ${mode}). Sidecar version ${finalized.version}; withdrawn_sha256 ${finalized.withdrawn_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 'lock': return cmdLock(rest);
+    case 'withdraw': return cmdWithdraw(rest);
+    case 'requalify': return cmdRequalify(rest);
     case 'version': case '--version': case '-v':
       return void process.stdout.write(VERSION + '\n');
     case 'help': case '--help': case '-h': case undefined: