@mcptoolshop/research-os 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 All notable changes to `research-os` are documented here.
 
+## [0.3.0] — 2026-05-09
+
+Tight release. One real, tested, dogfooded improvement: `--detector` flag on
+`research-os contradict map`. F-09 from Experiment 3 Session 1 (XRPL pack)
+earned the fix. No other v0.3 candidates shipped — F-01 (init version-stamp),
+F-02 (packs-dir docs), F-05 (discover --query example), F-08 (Windows process
+recovery) are deferred to v0.3.x.
+
+### Added
+
+- **`--detector <auto|heuristic|ollama-intern>`** flag on
+  `research-os contradict map`. Three explicit modes:
+
+  - `auto` (default) — preserves env-var-driven behavior. When the
+    configured Ollama model is available, runs the LLM detector;
+    otherwise falls through to heuristic. Mirrors v0.2.x behavior.
+  - `heuristic` — bypasses Ollama entirely. No model availability check,
+    no LLM calls. Always works. Always completes quickly.
+  - `ollama-intern` — requires the configured model. Exits with code 2
+    and a visible failure message if the model is unavailable, instead
+    of silently falling back to heuristic.
+
+  Invalid `--detector` values exit with code 2. The mode chosen is
+  announced visibly on the first output line of every run; there are no
+  silent shifts. Full reference: [`docs/contradict-map.md`](docs/contradict-map.md).
+
+- **12 new tests** in `test/contradictions-detector-flag.test.ts` covering
+  all three modes (heuristic never instantiates the Ollama client;
+  ollama-intern errors visibly when model unavailable; auto preserves
+  existing behavior; invalid value fails fast), heuristic ledger validity,
+  and a regression fixture that mirrors the XRPL Section 01 pattern (~60
+  claims with ~5-token shared vocabulary completes via heuristic in well
+  under 30 seconds).
+
+- **`docs/contradict-map.md`** — full CLI reference: detector modes, mode
+  announcements (verbatim strings), when-to-use-which guidance, and the
+  release thesis.
+
+- **Handbook page** at `/handbook/contradict-map` — condensed reference
+  matching the docs page.
+
+### Changed
+
+- **CLI `--help`** for `contradict map` now lists the three `--detector`
+  choices.
+- **Reference page** in the handbook updated to mention the flag and
+  link to the new contradict-map page.
+
+### Documentation
+
+- README status block updated to v0.3.0; version badge updated.
+- `docs/roadmap.md` Experiment 3 entry: F-09 chain blocker noted as
+  resolved in v0.3.0 (Experiment 3 itself remains in progress; closure
+  requires a third external-domain pack).
+- **Cross-repo:** `research-packs/docs/operator-playbook.md` updated in
+  the same release window. The earlier "clear `OLLAMA_INTERN_MODEL` to
+  force heuristic" workaround is replaced with `--detector heuristic`
+  as the canonical operator surface. The handbook mirror in this repo
+  is kept consistent with the canonical.
+- `SHIP_GATE.md` D2 updated: version bump + tag for v0.3.0.
+
+### Tests
+
+- **527 total** (515 at v0.2.0 → 527 at v0.3.0, +12 from
+  `test/contradictions-detector-flag.test.ts`).
+
+### Migration notes
+
+No code-level migration required. Existing scripts that don't pass
+`--detector` continue to work via `auto` mode.
+
+For operators who previously cleared `OLLAMA_INTERN_MODEL` to force the
+heuristic detector: that pattern still works in environments where the
+default model isn't installed, but the flag is the canonical surface
+and is environment-independent. Switch to `--detector heuristic` when
+re-running narrow-topic sections; the v0.3.0 operator-playbook update
+in `research-packs` documents the rationale.
+
 ## [0.2.0] — 2026-05-09
 
 Tight release. Two real, tested, dogfooded improvements: `research-os pack publish`

package/README.md

@@ -7,7 +7,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/mcp-tool-shop-org/research-os/releases/tag/v0.2.0"><img src="https://img.shields.io/badge/version-0.2.0-blue" alt="version 0.2.0"></a>
+  <a href="https://github.com/mcp-tool-shop-org/research-os/releases/tag/v0.3.0"><img src="https://img.shields.io/badge/version-0.3.0-blue" alt="version 0.3.0"></a>
   <a href="https://github.com/mcp-tool-shop-org/research-os/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/research-os/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
   <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen" alt="Node ≥20">
@@ -151,9 +151,11 @@ This is the structural alternative to *search → summarize → pretty report*.
 
 ## Status
 
-**v0.2.0** — published to npm as `@mcptoolshop/research-os@0.2.0`, 2026-05-09. Ships `research-os pack publish` (Experiment 2) and the Pattern 2 readiness predicate fix. 515/515 vitest passing. See [CHANGELOG.md](CHANGELOG.md).
+**v0.3.0** — published to npm as `@mcptoolshop/research-os@0.3.0`, 2026-05-09. Ships the `--detector <auto|heuristic|ollama-intern>` flag on `contradict map` (F-09 chain-blocker fix from Experiment 3 Session 1, XRPL pack). 527/527 vitest passing. See [CHANGELOG.md](CHANGELOG.md) and [`docs/contradict-map.md`](docs/contradict-map.md).
 
-**`research-os pack publish`** — Frozen packs export to the canonical `research-packs` archive with a single command. Derives `pack.manifest.json`, generates `README.md`, provisions `docs/how-to-read-this.md`, verifies the admission contract. See [`docs/pack-publish.md`](docs/pack-publish.md). Dogfood: both existing packages re-derived and `verify-pack.mjs` PASS — see [`docs/pack-publish-dogfood.md`](docs/pack-publish-dogfood.md).
+**`contradict map --detector`** — Detector selection is now an explicit operator choice instead of a state-dependent env-var dance. `auto` (default) preserves prior behavior; `heuristic` always works without LLM and completes quickly on narrow-topic documentation sections; `ollama-intern` requires the configured model and exits visibly if unavailable. Mode is announced visibly on every run. The earlier "clear `OLLAMA_INTERN_MODEL` to force heuristic" workaround is superseded by `--detector heuristic` as the canonical operator surface; see the [research-packs operator playbook](https://github.com/mcp-tool-shop-org/research-packs/blob/main/docs/operator-playbook.md) and the [handbook contradict-map page](https://mcp-tool-shop-org.github.io/research-os/handbook/contradict-map/).
+
+**v0.2.0** — published 2026-05-09. Shipped `research-os pack publish` (Experiment 2) and the Pattern 2 readiness predicate fix. 515/515 vitest passing then. See [CHANGELOG.md](CHANGELOG.md). Frozen packs export to the canonical `research-packs` archive with a single command; admission contract is enforced by code, not checklist. See [`docs/pack-publish.md`](docs/pack-publish.md).
 
 **v0.1.0** — dogfood pack frozen 2026-05-08. The pack at `research-os-packs/research-os-spec/` (sibling repo) reached freeze with 296 accepted claims across 8 sections, 17 dispositioned, 30 operator-overridden, 0 active repair blockers, 0 unresolved contradictions, all gates `synthesis_eligible=true`. Sixteen load-bearing laws cumulative. See [`docs/dogfood-proof.md`](docs/dogfood-proof.md) for the seven findings and freeze receipt fingerprints.
 
@@ -161,9 +163,9 @@ This is the structural alternative to *search → summarize → pretty report*.
 
 **v1 Experiment 1 (ComfyUI workflow durability)** — CLOSED 2026-05-09. All 8 sections at Terminal A, pack frozen, archive live. See [`docs/experiment-1-proof.md`](docs/experiment-1-proof.md) and [`docs/roadmap.md`](docs/roadmap.md).
 
-### What v0.2 is not
+### What v0.3 is not
 
-- Not battle-tested by external users. Two dogfood arcs have run — one self-referential, one external-domain. External user pressure is Experiment 3 (API stability) in the v1.0 roadmap.
+- Not battle-tested by external users. Two dogfood arcs have closed — one self-referential, one external-domain — and Experiment 3 (API stability under external pressure) is in progress: pack #1 of 3 (XRPL creator-token durability) earned the v0.3.0 `--detector` flag. Two more external-domain packs required for Experiment 3 closure.
 - Not a synthesis writer. The `synth workspace` command generates the structured workspace; humans (or Cowork) write the prose against accepted claim IDs.
 - Not API-stable under semver. v1.0.0 is an earned state, not a calendar date — see [`docs/roadmap.md`](docs/roadmap.md) for the six experiments that close the gap.
 

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"];
   }
 });
 
@@ -11692,7 +11734,7 @@ var init_src = __esm({
     init_triage();
     init_discover();
     init_errors();
-    RESEARCH_OS_VERSION = "0.2.0";
+    RESEARCH_OS_VERSION = "0.3.0";
   }
 });
 
@@ -12123,7 +12165,7 @@ init_synth();
 init_audit();
 init_freeze();
 init_invalidate();
-import { Command } from "commander";
+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";
@@ -13054,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}