@mcptoolshop/research-os 0.1.1 → 0.3.0

package/dist/cli.js

@@ -2774,9 +2774,6 @@ Hard rules:
 });
 
 // src/contradictions/detectors/index.ts
-function defaultContradictionDetectors() {
-  return [new OllamaInternContradictionDetector(), new HeuristicContradictionDetector()];
-}
 async function pickContradictionDetector(detectors) {
   for (const d of detectors) {
     if (await d.available()) return d;
@@ -3250,6 +3247,48 @@ function buildContradiction(args) {
     created_at: (/* @__PURE__ */ new Date()).toISOString()
   });
 }
+async function resolveDetector(options) {
+  const mode = options.detectorMode ?? "auto";
+  if (!VALID_DETECTOR_MODES.includes(mode)) {
+    throw new Error(
+      `contradict map: invalid --detector value "${mode}"; valid values are: auto, heuristic, ollama-intern`
+    );
+  }
+  if (mode === "heuristic") {
+    return {
+      detector: new HeuristicContradictionDetector(),
+      announcement: "contradict map: using heuristic detector"
+    };
+  }
+  if (mode === "ollama-intern") {
+    const d = new OllamaInternContradictionDetector(options.ollamaConfig ?? {});
+    if (!await d.available()) {
+      throw new Error(
+        `contradict map: ollama-intern detector requested but model ${d.model} is unavailable; aborting (use --detector heuristic to bypass)`
+      );
+    }
+    return {
+      detector: d,
+      announcement: `contradict map: using ollama-intern detector with model ${d.model}`
+    };
+  }
+  const detectors = options.detectors ?? [
+    new OllamaInternContradictionDetector(options.ollamaConfig ?? {}),
+    new HeuristicContradictionDetector()
+  ];
+  const detector = await pickContradictionDetector(detectors);
+  if (detector.name === "ollama-intern") {
+    const modelName = detector instanceof OllamaInternContradictionDetector ? detector.model : process.env.OLLAMA_INTERN_MODEL ?? "hermes3:8b";
+    return {
+      detector,
+      announcement: `contradict map: using ollama-intern detector with model ${modelName}`
+    };
+  }
+  return {
+    detector,
+    announcement: "contradict map: ollama-intern unavailable; using heuristic detector"
+  };
+}
 async function map(options) {
   const packPath = options.packPath ? resolve7(options.packPath) : process.cwd();
   if (!existsSync9(join10(packPath, "research.yaml"))) throw new PackNotFoundError(packPath);
@@ -3261,8 +3300,7 @@ async function map(options) {
     const allowed = await readTriagedClaimIds2(packPath, options.sectionId);
     candidateClaims = candidateClaims.filter((c) => allowed.has(c.claim_id));
   }
-  const adapters = options.detectors ?? defaultContradictionDetectors();
-  const detector = await pickContradictionDetector(adapters);
+  const { detector, announcement } = await resolveDetector(options);
   const summary = {
     sectionId: options.sectionId,
     detector: detector.name,
@@ -3272,7 +3310,8 @@ async function map(options) {
     contradictionsAdded: 0,
     contradictionsDeduped: 0,
     contradictionIds: [],
-    detectorError: null
+    detectorError: null,
+    detectorAnnouncement: announcement
   };
   const ledgerPath = join10(sectionDir, "contradictions.jsonl");
   const mdPath = join10(sectionDir, "contradictions.md");
@@ -3336,7 +3375,7 @@ async function map(options) {
   await writeFile9(mdPath, md, "utf8");
   return summary;
 }
-var DETECTOR_ID_PART;
+var DETECTOR_ID_PART, VALID_DETECTOR_MODES;
 var init_map = __esm({
   "src/contradictions/map.ts"() {
     "use strict";
@@ -3344,11 +3383,14 @@ var init_map = __esm({
     init_schema5();
     init_schema7();
     init_detectors();
+    init_heuristic3();
+    init_ollama_intern3();
     init_markdown();
     DETECTOR_ID_PART = {
       heuristic: "heuristic",
       "ollama-intern": "ollama_intern"
     };
+    VALID_DETECTOR_MODES = ["auto", "heuristic", "ollama-intern"];
   }
 });
 
@@ -7265,6 +7307,7 @@ function buildSectionState(args) {
     candidate_claims_total: candidateClaims.length,
     unresolved_contradiction_ids: unresolved.map((c) => c.contradiction_id),
     blocking_reasons: gate2?.blocking_reasons ?? [],
+    active_blockers: gate2?.blocking_reasons ?? [],
     blocking_contradictions_unresolved: blocking.length,
     provenance_summary: provenanceSummary
   };
@@ -7308,7 +7351,7 @@ function determineMode(sections, waivers, warnings) {
     return "human_review_required";
   }
   const allReady = sections.every(
-    (s) => s.has_gate_run && s.synthesis_eligible && s.has_review_run && s.candidate_claims_total > 0 && s.repair_claim_ids.length === 0 && s.unresolved_contradiction_ids.length === 0
+    (s) => s.has_gate_run && s.synthesis_eligible && s.has_review_run && s.candidate_claims_total > 0 && s.active_blockers.length === 0 && s.unresolved_contradiction_ids.length === 0
   );
   if (allReady && sections.length > 0) return "synthesis_ready";
   return "repair_required";
@@ -7517,6 +7560,7 @@ var init_schema13 = __esm({
       candidate_claims_total: z14.number().int().nonnegative(),
       unresolved_contradiction_ids: z14.array(z14.string()),
       blocking_reasons: z14.array(z14.string()),
+      active_blockers: z14.array(z14.string()).default([]),
       blocking_contradictions_unresolved: z14.number().int().nonnegative(),
       provenance_summary: ProvenanceSummarySchema.optional()
     });
@@ -9133,7 +9177,7 @@ function buildReadinessSummary(rows, handoff2, unresolvedContradictions) {
     if (!r.has_gate_run) noGate += 1;
     if (!r.has_review_run) noReview += 1;
     const unresolvedCount = unresolvedBySection.get(r.section_id) ?? 0;
-    if (r.synthesis_eligible && r.has_review_run && r.candidate_claims > 0 && r.repair_claims === 0 && unresolvedCount === 0) {
+    if (r.synthesis_eligible && r.has_review_run && r.candidate_claims > 0 && r.blocking_reasons.length === 0 && unresolvedCount === 0) {
       ready += 1;
     } else if (r.has_gate_run && r.gate_verdict === "blocked" && !r.synthesis_eligible) {
       blocked += 1;
@@ -11690,7 +11734,7 @@ var init_src = __esm({
     init_triage();
     init_discover();
     init_errors();
-    RESEARCH_OS_VERSION = "0.1.0";
+    RESEARCH_OS_VERSION = "0.3.0";
   }
 });
 
@@ -12121,9 +12165,507 @@ init_synth();
 init_audit();
 init_freeze();
 init_invalidate();
+import { Command, Option } from "commander";
+
+// src/pack/publish/index.ts
+import { existsSync as existsSync30, mkdirSync as mkdirSync3, writeFileSync as writeFileSync2, readFileSync as readFileSync3, readdirSync as readdirSync2 } from "fs";
+import { join as join31, basename, resolve as resolve24 } from "path";
+
+// src/pack/publish/manifest.ts
+init_schema();
+import { createHash as createHash11 } from "crypto";
+import { readFileSync, existsSync as existsSync28 } from "fs";
+import { join as join28 } from "path";
+import { parse as parseYaml } from "yaml";
+import { z as z23 } from "zod";
+
+// src/pack/publish/schema.ts
+import { z as z22 } from "zod";
+var SectionSummarySchema = z22.object({
+  id: z22.string().min(1),
+  accepted_claims: z22.number().int().min(0),
+  gate: z22.enum(["pass", "warn", "fail", "blocked", "pass_with_waiver"]),
+  synthesis_eligible: z22.boolean()
+});
+var TotalsSchema = z22.object({
+  sections: z22.number().int().min(1),
+  accepted_claims: z22.number().int().min(0),
+  dispositioned: z22.number().int().min(0),
+  unresolved_contradictions: z22.number().int().min(0),
+  preserved_contradiction_records: z22.number().int().min(0).optional()
+});
+var PackManifestSchema = z22.object({
+  name: z22.string().min(1),
+  topic: z22.string().min(1),
+  frozen_at: z22.string().datetime(),
+  research_os_version: z22.string().min(1),
+  sections: z22.array(SectionSummarySchema).min(1),
+  totals: TotalsSchema,
+  freeze_receipt_sha256: z22.string().regex(/^[a-f0-9]{64}$/, "Must be a 64-char hex sha256"),
+  operator_notes: z22.string().default("")
+});
+
+// src/pack/publish/manifest.ts
+var GateResultMinimalSchema = z23.object({
+  verdict: z23.enum(["pass", "warn", "fail", "blocked"]),
+  synthesis_eligible: z23.boolean()
+});
+function sha256Bytes(buf) {
+  return createHash11("sha256").update(buf).digest("hex");
+}
+function parseJsonl(content) {
+  return content.split("\n").filter((l) => l.trim().length > 0).map((l) => JSON.parse(l));
+}
+function readJsonlSafe(filePath) {
+  if (!existsSync28(filePath)) return [];
+  return parseJsonl(readFileSync(filePath, "utf8"));
+}
+function latestClaimDecisions(reviews) {
+  const m = /* @__PURE__ */ new Map();
+  const sorted = [...reviews].sort((a, b) => a.created_at.localeCompare(b.created_at));
+  for (const r of sorted) m.set(r.claim_id, r.decision);
+  return m;
+}
+function latestContradictionStatuses(resolutions) {
+  const m = /* @__PURE__ */ new Map();
+  const sorted = [...resolutions].sort((a, b) => a.resolved_at.localeCompare(b.resolved_at));
+  for (const r of sorted) m.set(r.contradiction_id, r.status);
+  return m;
+}
+function latestDispositionStatuses(dispositions) {
+  const m = /* @__PURE__ */ new Map();
+  const sorted = [...dispositions].sort((a, b) => a.created_at.localeCompare(b.created_at));
+  for (const d of sorted) m.set(d.claim_id, "dispositioned");
+  return m;
+}
+function deriveManifest(packDir, packageName, operatorNotes = "") {
+  const yamlPath = join28(packDir, "research.yaml");
+  if (!existsSync28(yamlPath)) throw new Error(`research.yaml not found in ${packDir}`);
+  const research = ResearchYamlSchema.parse(parseYaml(readFileSync(yamlPath, "utf8")));
+  if (!research.frozen_at) {
+    throw new Error(`Pack is not frozen: research.yaml.frozen_at is null \u2014 run research-os freeze first`);
+  }
+  const receiptPath = join28(packDir, "audits/freeze-receipt.json");
+  if (!existsSync28(receiptPath)) {
+    throw new Error(`audits/freeze-receipt.json not found \u2014 pack is not frozen`);
+  }
+  const receiptBytes = readFileSync(receiptPath);
+  const freeze_receipt_sha256 = sha256Bytes(receiptBytes);
+  const receipt = JSON.parse(receiptBytes.toString("utf8"));
+  const frozen_at = receipt.frozen_at ?? research.frozen_at;
+  const packAuditPath = join28(packDir, "audits/pack-audit.json");
+  if (!existsSync28(packAuditPath)) throw new Error(`audits/pack-audit.json not found`);
+  const packAudit = JSON.parse(readFileSync(packAuditPath, "utf8"));
+  const auditSectionMap = new Map(
+    (packAudit.section_summaries ?? []).map((s) => [s.section_id, s.accepted_claims])
+  );
+  const sectionIds = research.sections.map((s) => s.id);
+  const sections = [];
+  let totalAccepted = 0;
+  let totalDispositioned = 0;
+  let totalPreserved = 0;
+  for (const sectionId of sectionIds) {
+    const sectionDir = join28(packDir, "sections", sectionId);
+    const reviews = readJsonlSafe(join28(sectionDir, "claim-reviews.jsonl"));
+    const decisionMap = latestClaimDecisions(reviews);
+    const acceptedCount = [...decisionMap.values()].filter(
+      (d) => d === "accepted_for_synthesis"
+    ).length;
+    const auditAccepted = auditSectionMap.get(sectionId);
+    if (auditAccepted !== void 0 && auditAccepted !== acceptedCount) {
+      throw new Error(
+        `Section ${sectionId}: accepted_claims mismatch between claim-reviews.jsonl (${acceptedCount}) and pack-audit.json (${auditAccepted}). Closure-ledger seam disagreement \u2014 investigate before publishing.`
+      );
+    }
+    const gateResultPath = join28(packDir, "audits", `${sectionId}-gate.json`);
+    if (!existsSync28(gateResultPath)) {
+      throw new Error(`audits/${sectionId}-gate.json not found \u2014 section not gated`);
+    }
+    const gateResult = GateResultMinimalSchema.parse(
+      JSON.parse(readFileSync(gateResultPath, "utf8"))
+    );
+    const dispositions = readJsonlSafe(
+      join28(sectionDir, "claim-synthesis-dispositions.jsonl")
+    );
+    const dispositionMap = latestDispositionStatuses(dispositions);
+    totalDispositioned += dispositionMap.size;
+    const resolutions = readJsonlSafe(
+      join28(sectionDir, "contradiction-resolutions.jsonl")
+    );
+    const resolutionMap = latestContradictionStatuses(resolutions);
+    const stillUnresolved = [...resolutionMap.values()].filter((s) => s === "unresolved").length;
+    if (stillUnresolved > 0) {
+      throw new Error(
+        `Section ${sectionId} has ${stillUnresolved} unresolved contradictions. Freeze should have blocked this \u2014 investigate before publishing.`
+      );
+    }
+    totalPreserved += [...resolutionMap.values()].filter((s) => s !== "unresolved").length;
+    totalAccepted += acceptedCount;
+    sections.push({
+      id: sectionId,
+      accepted_claims: acceptedCount,
+      gate: gateResult.verdict,
+      synthesis_eligible: gateResult.synthesis_eligible
+    });
+  }
+  const totalsBase = {
+    sections: sections.length,
+    accepted_claims: totalAccepted,
+    dispositioned: totalDispositioned,
+    unresolved_contradictions: 0
+  };
+  return PackManifestSchema.parse({
+    name: packageName,
+    topic: research.topic,
+    frozen_at,
+    research_os_version: research.research_os_version,
+    sections,
+    totals: totalPreserved > 0 ? { ...totalsBase, preserved_contradiction_records: totalPreserved } : totalsBase,
+    freeze_receipt_sha256,
+    operator_notes: operatorNotes
+  });
+}
+
+// src/pack/publish/readme.ts
+function extractSummary(markdown) {
+  const lines = markdown.split("\n");
+  let inSummary = false;
+  const summaryLines = [];
+  for (const line of lines) {
+    if (/^## Summary\s*$/.test(line)) {
+      inSummary = true;
+      continue;
+    }
+    if (inSummary && /^## /.test(line)) break;
+    if (inSummary) summaryLines.push(line);
+  }
+  return summaryLines.join("\n").trim();
+}
+function generateReadme(manifest, finalReport) {
+  const m = manifest;
+  const frozenDate = m.frozen_at.slice(0, 10);
+  const summary = extractSummary(finalReport);
+  const sectionTable = m.sections.map((s) => `| ${s.id} | ${s.accepted_claims} | ${s.gate} | ${s.synthesis_eligible ? "yes" : "no"} |`).join("\n");
+  const totalsLine = m.totals.preserved_contradiction_records != null ? `Preserved contradiction records: ${m.totals.preserved_contradiction_records}` : `${m.totals.unresolved_contradictions} unresolved contradictions`;
+  const operatorSection = m.operator_notes ? `
+---
+
+## Operator notes
+
+${m.operator_notes}
+` : "";
+  return `# ${m.name}
+
+**Topic:** ${m.topic}
+
+**Frozen:** ${frozenDate} | **research-os version:** ${m.research_os_version} | **Accepted claims:** ${m.totals.accepted_claims} across ${m.totals.sections} sections
+
+---
+
+## Executive summary
+
+${summary}
+
+---
+
+## Sections
+
+| Section | Accepted claims | Gate | Synthesis eligible |
+|---------|-----------------|------|-------------------|
+${sectionTable}
+
+**Totals:** ${m.totals.accepted_claims} accepted, ${m.totals.dispositioned} dispositioned, ${totalsLine}
+
+---
+
+## How to read this pack
+
+This package is part of the [\`research-packs\`](../../README.md) archive.
+
+- **Lane 1 (synthesis):** You are here. See [\`synthesis/final-report.md\`](synthesis/final-report.md) for the full citation-clean prose.
+- **Lane 2 (evidence):** [\`pack/\`](pack/) \u2014 full frozen ledgers, source cards, excerpts, claim reviews, gate results, and \`audits/freeze-receipt.json\`.
+- **Lane 3 (method):** [\`../../docs/\`](../../docs/) \u2014 artifact contract, how-to-read, source quality notes.
+
+To verify this pack's integrity: \`node ../../scripts/verify-pack.mjs .\` from this directory.
+
+See [\`docs/how-to-read-this.md\`](docs/how-to-read-this.md) for pack-specific reading notes.${operatorSection}`;
+}
+
+// src/pack/publish/how-to-read.ts
+function generateHowToReadScaffold(manifest) {
+  const frozenDate = manifest.frozen_at.slice(0, 10);
+  const contradictionNote = manifest.totals.preserved_contradiction_records != null ? `This pack has ${manifest.totals.preserved_contradiction_records} preserved contradiction records. These are not active blockers \u2014 freeze validated zero unresolved contradictions across all sections. The records are preserved for provenance in \`pack/sections/<id>/contradiction-resolutions.jsonl\`.` : "This pack has no preserved contradiction records.";
+  return `# How to read: ${manifest.name}
+
+<!-- SCAFFOLD: Pre-filled with pack-specific metadata by \`research-os pack publish\`.
+     Final prose is human-authored. Edit freely \u2014 this file is NOT covered by the freeze receipt. -->
+
+**Pack:** \`${manifest.name}\`
+**Topic:** ${manifest.topic}
+**Frozen:** ${frozenDate}
+**Accepted claims:** ${manifest.totals.accepted_claims} accepted claims across ${manifest.totals.sections} section${manifest.totals.sections !== 1 ? "s" : ""}
+
+---
+
+## What this pack answers
+
+<!-- human-authored: describe what the synthesis delivers -->
+
+## How the evidence is structured
+
+<!-- human-authored: explain section breakdown, what each section investigated -->
+
+## Interpreting claim IDs
+
+Claims are referenced as \`[claim:clm_<hex>]\` in the synthesis prose. To look up a claim:
+
+1. Open \`pack/sections/<section-id>/claims.jsonl\`
+2. Find the entry with matching \`claim_id\`
+3. The \`asserts\` field is the claim; \`evidence_excerpt\` is the literal source span
+
+Accepted vs rejected: \`pack/sections/<section-id>/claim-reviews.jsonl\` \u2014 latest entry per \`claim_id\` wins.
+
+## Preserved contradiction records
+
+${contradictionNote}
+
+## Verifying integrity
+
+From this directory:
+
+\`\`\`bash
+node ../../scripts/verify-pack.mjs .
+\`\`\`
+
+Expected output: PASS with artifact count and receipt sha256.
+
+See [\`../../docs/how-to-read-a-pack.md\`](../../docs/how-to-read-a-pack.md) for the general guide.
+`;
+}
+
+// src/pack/publish/copy.ts
+import { mkdirSync as mkdirSync2, copyFileSync, readdirSync } from "fs";
+import { join as join29 } from "path";
+function copyDir(src, dst) {
+  mkdirSync2(dst, { recursive: true });
+  let count = 0;
+  const entries = readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join29(src, entry.name);
+    const dstPath = join29(dst, entry.name);
+    if (entry.isDirectory()) {
+      count += copyDir(srcPath, dstPath);
+    } else if (entry.isFile()) {
+      copyFileSync(srcPath, dstPath);
+      count++;
+    }
+  }
+  return count;
+}
+
+// src/pack/publish/verify.ts
+import { createHash as createHash12 } from "crypto";
+import { readFileSync as readFileSync2, existsSync as existsSync29 } from "fs";
+import { join as join30 } from "path";
+var REQUIRED_FILES = [
+  "pack/audits/freeze-receipt.json",
+  "synthesis/final-report.md",
+  "synthesis/decision-brief.md",
+  "pack.manifest.json",
+  "README.md"
+];
+function sha256File(filePath) {
+  return createHash12("sha256").update(readFileSync2(filePath)).digest("hex");
+}
+function verifyPack(packageDir) {
+  for (const rel of REQUIRED_FILES) {
+    const full = join30(packageDir, rel);
+    if (!existsSync29(full)) {
+      return { pass: false, reason: `MISSING required file: ${rel}` };
+    }
+  }
+  let rawManifest;
+  try {
+    rawManifest = JSON.parse(readFileSync2(join30(packageDir, "pack.manifest.json"), "utf8"));
+  } catch (e) {
+    return { pass: false, reason: `pack.manifest.json parse error: ${e.message}` };
+  }
+  const parsed = PackManifestSchema.safeParse(rawManifest);
+  if (!parsed.success) {
+    const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
+    return { pass: false, reason: `pack.manifest.json schema violation: ${issues}` };
+  }
+  const m = parsed.data;
+  const receiptPath = join30(packageDir, "pack/audits/freeze-receipt.json");
+  const actualReceiptHash = sha256File(receiptPath);
+  if (actualReceiptHash !== m.freeze_receipt_sha256) {
+    return {
+      pass: false,
+      reason: `freeze-receipt.json hash mismatch.
+  manifest: ${m.freeze_receipt_sha256}
+  actual:   ${actualReceiptHash}`,
+      name: m.name
+    };
+  }
+  let receipt;
+  try {
+    receipt = JSON.parse(readFileSync2(receiptPath, "utf8"));
+  } catch (e) {
+    return {
+      pass: false,
+      reason: `freeze-receipt.json parse error: ${e.message}`,
+      name: m.name
+    };
+  }
+  const allFingerprints = [
+    ...receipt.canonical_artifact_hashes ?? [],
+    ...receipt.synthesis_hashes ?? []
+  ];
+  let verified = 0;
+  const softWarnings = [];
+  for (const entry of allFingerprints) {
+    const artifactPath = join30(packageDir, "pack", entry.path);
+    if (!existsSync29(artifactPath)) {
+      return {
+        pass: false,
+        reason: `Fingerprinted artifact missing: pack/${entry.path}`,
+        name: m.name
+      };
+    }
+    const actualHash = sha256File(artifactPath);
+    if (actualHash !== entry.sha256) {
+      if (entry.path === "research.yaml") {
+        softWarnings.push(
+          `WARN  pack/research.yaml hash reflects pre-freeze state (known: freeze writes frozen_at + status after fingerprinting)`
+        );
+        verified++;
+        continue;
+      }
+      return {
+        pass: false,
+        reason: `Hash mismatch for pack/${entry.path}.
+  receipt: ${entry.sha256}
+  actual:  ${actualHash}`,
+        name: m.name
+      };
+    }
+    verified++;
+  }
+  return { pass: true, name: m.name, artifactsVerified: verified, softWarnings };
+}
+
+// src/pack/publish/index.ts
+var REQUIRED_SOURCE_FILES = [
+  "research.yaml",
+  "audits/freeze-receipt.json",
+  "audits/pack-audit.json",
+  "synthesis/final-report.md",
+  "synthesis/decision-brief.md"
+];
+async function publish(input) {
+  const fromDir = resolve24(input.fromDir);
+  const toDir = resolve24(input.toDir);
+  const packageName = basename(toDir);
+  const warnings = [];
+  for (const rel of REQUIRED_SOURCE_FILES) {
+    if (!existsSync30(join31(fromDir, rel))) {
+      throw new Error(
+        `Source pack missing required file: ${rel}
+  Hint: run research-os freeze before publish
+  Pack: ${fromDir}`
+      );
+    }
+  }
+  if (existsSync30(join31(fromDir, "audits/freeze-refusal.json")) || existsSync30(join31(fromDir, "audits/freeze-refusal.md"))) {
+    throw new Error(
+      `Source pack has freeze-refusal artifacts \u2014 pack did not freeze cleanly.
+  Resolve blocking reasons then re-run research-os freeze.
+  Pack: ${fromDir}`
+    );
+  }
+  if (existsSync30(toDir)) {
+    const entries = readdirSync2(toDir);
+    if (entries.length > 0 && !input.force) {
+      throw new Error(
+        `Target directory already exists and is non-empty: ${toDir}
+  Use --force to overwrite.`
+      );
+    }
+  }
+  const manifest = deriveManifest(fromDir, packageName, input.operatorNotes ?? "");
+  if (input.dryRun) {
+    const finalReportPath2 = join31(fromDir, "synthesis/final-report.md");
+    const finalReport2 = existsSync30(finalReportPath2) ? readFileSync3(finalReportPath2, "utf8") : "";
+    const readme2 = generateReadme(manifest, finalReport2);
+    return {
+      packageName,
+      filesWritten: [],
+      warnings: ["dry-run: no files written"],
+      verifyPassed: false,
+      dryRun: true,
+      dryRunManifest: manifest,
+      dryRunReadme: readme2
+    };
+  }
+  mkdirSync3(toDir, { recursive: true });
+  const filesWritten = [];
+  const packTarget = join31(toDir, "pack");
+  const packFileCount = copyDir(fromDir, packTarget);
+  filesWritten.push(`pack/ (${packFileCount} files)`);
+  const synthSrc = join31(fromDir, "synthesis");
+  if (existsSync30(synthSrc)) {
+    const synthTarget = join31(toDir, "synthesis");
+    const synthFileCount = copyDir(synthSrc, synthTarget);
+    filesWritten.push(`synthesis/ (${synthFileCount} files)`);
+  } else {
+    warnings.push(
+      "No synthesis/ directory in source pack \u2014 Lane 1 synthesis files not written"
+    );
+  }
+  writeFileSync2(
+    join31(toDir, "pack.manifest.json"),
+    JSON.stringify(manifest, null, 2) + "\n",
+    "utf8"
+  );
+  filesWritten.push("pack.manifest.json");
+  const finalReportPath = join31(fromDir, "synthesis/final-report.md");
+  const finalReport = existsSync30(finalReportPath) ? readFileSync3(finalReportPath, "utf8") : "";
+  const readme = generateReadme(manifest, finalReport);
+  writeFileSync2(join31(toDir, "README.md"), readme, "utf8");
+  filesWritten.push("README.md");
+  const docsDir = join31(toDir, "docs");
+  mkdirSync3(docsDir, { recursive: true });
+  const howToReadPath = join31(docsDir, "how-to-read-this.md");
+  if (existsSync30(howToReadPath)) {
+    warnings.push(
+      "docs/how-to-read-this.md already exists \u2014 not overwritten (operator-authored content preserved)"
+    );
+  } else {
+    const scaffold = generateHowToReadScaffold(manifest);
+    writeFileSync2(howToReadPath, scaffold, "utf8");
+    filesWritten.push("docs/how-to-read-this.md");
+  }
+  const verifyResult = verifyPack(toDir);
+  for (const w of verifyResult.softWarnings ?? []) warnings.push(w);
+  if (!verifyResult.pass) {
+    throw new Error(
+      `Pack verification FAILED after publish \u2014 the published package does not meet the admission contract.
+  ${verifyResult.reason}
+  Target: ${toDir}`
+    );
+  }
+  return {
+    packageName,
+    filesWritten,
+    warnings,
+    verifyPassed: true,
+    dryRun: false
+  };
+}
+
+// src/cli.ts
 init_errors();
 init_src();
-import { Command } from "commander";
 function reportError(err) {
   if (err instanceof ResearchOSError) {
     process.stderr.write(`research-os: ${err.code}: ${err.message}
@@ -12554,13 +13096,21 @@ contradictCmd.command("map").description("Detect contradiction candidates among
   "--triaged-only",
   "Only consider claims that triage selected_for_review; reduces N\xB2 pair classification on dense sections",
   false
+).addOption(
+  new Option(
+    "--detector <mode>",
+    "Detector to use: auto (default, env-var-driven), heuristic (always fast, no LLM), ollama-intern (require LLM, fail visibly if unavailable)"
+  ).choices(["auto", "heuristic", "ollama-intern"]).default("auto")
 ).action(async (section, opts) => {
   try {
     const result = await map({
       sectionId: section,
       packPath: opts.pack,
-      triagedOnly: opts.triagedOnly
+      triagedOnly: opts.triagedOnly,
+      detectorMode: opts.detector
     });
+    process.stdout.write(`${result.detectorAnnouncement}
+`);
     process.stdout.write(`contradiction map complete
 `);
     process.stdout.write(`  section:                 ${result.sectionId}
@@ -13181,5 +13731,59 @@ program.command("review-promote").description(
     reportError(err);
   }
 });
+var packCmd = program.command("pack").description("Pack-level publication and archive operations");
+packCmd.command("publish").description(
+  "Export a frozen pack into the research-packs archive format. Copies the pack, derives pack.manifest.json, generates README.md, provisions docs/how-to-read-this.md, and verifies the admission contract."
+).requiredOption("--to <path>", "Target package directory, e.g. <research-packs>/packages/<name>").option("--from <path>", "Source frozen pack directory (defaults to cwd)", process.cwd()).option("--operator-notes <text>", "Operator notes recorded in pack.manifest.json", "").option("--force", "Overwrite an existing non-empty target directory", false).option("--dry-run", "Print derived manifest and README plan; write nothing", false).action(async (opts) => {
+  try {
+    const result = await publish({
+      fromDir: opts.from,
+      toDir: opts.to,
+      operatorNotes: opts.operatorNotes,
+      force: Boolean(opts.force),
+      dryRun: Boolean(opts.dryRun)
+    });
+    if (result.dryRun) {
+      process.stdout.write(`pack publish: DRY-RUN \u2014 no files written
+`);
+      process.stdout.write(`  package name:  ${result.packageName}
+`);
+      if (result.dryRunManifest) {
+        const m = result.dryRunManifest;
+        process.stdout.write(`  topic:         ${m.topic.slice(0, 80)}
+`);
+        process.stdout.write(`  frozen_at:     ${m.frozen_at}
+`);
+        process.stdout.write(`  sections:      ${m.totals.sections}
+`);
+        process.stdout.write(`  accepted:      ${m.totals.accepted_claims}
+`);
+        process.stdout.write(`  receipt sha256:${m.freeze_receipt_sha256.slice(0, 16)}\u2026
+`);
+      }
+      return;
+    }
+    process.stdout.write(`pack publish: DONE
+`);
+    process.stdout.write(`  package name:  ${result.packageName}
+`);
+    process.stdout.write(`  files written: ${result.filesWritten.length}
+`);
+    for (const f of result.filesWritten) process.stdout.write(`    ${f}
+`);
+    process.stdout.write(`  verify:        ${result.verifyPassed ? "PASS" : "FAIL"}
+`);
+    if (result.warnings.length > 0) {
+      process.stdout.write(`
+warnings:
+`);
+      for (const w of result.warnings) process.stdout.write(`  - ${w}
+`);
+    }
+    if (!result.verifyPassed) process.exitCode = 2;
+  } catch (err) {
+    reportError(err);
+  }
+});
 program.parseAsync(process.argv);
 //# sourceMappingURL=cli.js.map