@mcptoolshop/research-os 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,200 @@
 
 All notable changes to `research-os` are documented here.
 
+## [0.3.1] — 2026-05-09
+
+Tight release. One real, tested, dogfooded improvement: section-scoped
+source-floor waivers + reviewer-side acknowledgement. Earned by Experiment 3
+XRPL pack Session 2 — canonical-protocol sections (XRPL XLS standards,
+single-foundation chain documentation, walled-garden API specs) inverted
+the assumption that publisher diversity is a proxy for truth quality. No
+other v0.3.x candidates shipped — F-01 (init version-stamp), F-02
+(packs-dir docs), F-05 (discover --query example), F-08 (Windows process
+recovery), F-16 (unused SectionSchema fields), F-17 (sections/<id>/gates.yaml
+runtime wiring) are deferred to their own scoped releases.
+
+### Added
+
+- **`primary_source_waiver.section_waivers[]`** — section-scoped source-floor
+  waivers. Each entry carries `section_id`, `scope` (`min_independent_publishers`
+  or `primary_sources_required`), `reason` (non-empty), and
+  `compensating_controls[]` (at least one entry). Schema enforcement: empty
+  `reason` or empty `compensating_controls[]` fail validation. Pack policy
+  `gates.source_floor.primary_source_waiver_allowed: false` blocks both
+  pack-level and section-scoped waivers — operators cannot smuggle a waiver
+  past pack policy by rerouting it to section scope.
+
+  Multiple entries can target different sections, or the same section with
+  different scopes. Pack-level `primary_source_waiver` semantics unchanged;
+  the new `section_waivers[]` is additive and defaults to `[]` for backward
+  compatibility. Existing packs unaffected. Full reference:
+  [`docs/section-scoped-waivers.md`](docs/section-scoped-waivers.md).
+
+- **Reviewer-side acknowledgement** — when a section has a matching
+  `min_independent_publishers` waiver in effect, the calibrated reviewer's
+  section-wide `source_cluster_monopoly` finding remains visible in the
+  findings ledger but does NOT, by itself, route claims to
+  `needs_source_repair`. The finding is annotated as
+  `(severity, waived)` in the claim-review's reason string so operators
+  reading the ledger can see the finding is present but neutralised. Other
+  source-quality findings (per-claim `source_quality_problem`,
+  `scope_widening`, `overgeneralized_claim`, etc.) continue to drive their
+  own routing normally.
+
+- **Audit-side disclosure** — `weak-sources.{json,md}` and
+  `source-diversity-gaps.{json,md}` rollups annotate waived rows with
+  `waived: true` and `waiver_reason: <verbatim>` when a matching section
+  waiver is active. Rows are NOT removed (Law 16: waivers do not hide
+  evidence). The publisher-monopoly fact is still surfaced in the rollup;
+  it's disclosed as deliberately accepted rather than as an open blocker.
+
+- **13 new tests** in `test/section-scoped-waivers.test.ts` covering
+  schema validation (valid shape, missing reason, empty compensating
+  controls, invalid scope enum, bad section_id regex), gate-side
+  conversion (section_id match, section_id mismatch, primary_sources_required
+  scope, pack-level regression, pack-policy refusal, multiple sections,
+  multiple scopes for same section, disclosure in WaiverApplication),
+  reviewer-side acknowledgement (waived monopoly → accepted, per-claim
+  quality still routes, regression without waiver), and audit-side
+  annotation.
+
+- **`docs/section-scoped-waivers.md`** — full operator reference: schema,
+  behavior contract, valid-cases / invalid-cases enumeration, required
+  operator discipline (synthesis-time disclosure beyond the schema), and
+  the release thesis. Opens with the canonical phrasing:
+  *"Use section-scoped source waivers when publisher diversity is
+  structurally incompatible with the section's truth source, not when a
+  section merely failed to find enough sources."*
+
+- **Handbook page** at `/handbook/section-scoped-waivers` — condensed
+  reference matching the docs page.
+
+### Changed
+
+- **Pack-level `min_independent_publishers: 0` workaround DEPRECATED**
+  in the canonical `research-packs/docs/operator-playbook.md` and the
+  research-os handbook mirror. The pack-level pattern remains valid for
+  already-frozen packs (e.g., `packages/comfyui-workflow-durability/`)
+  whose freeze receipts are unchanged; new packs should prefer the
+  section-scoped pattern. Forward notes added to
+  [`docs/experiment-1-proof.md`](docs/experiment-1-proof.md) at the
+  references to the deprecated workaround — historical content
+  preserved, not rewritten.
+
+### Documentation
+
+- README status block updated to v0.3.1; version badge updated.
+- `docs/roadmap.md` Experiment 3 progress: section-scoped source waivers
+  shipped in v0.3.1; pack #2 of 3 (XRPL) earned both v0.3.0 and v0.3.1
+  fixes. Two more external-domain packs required for closure.
+- **Cross-repo:** `research-packs/docs/operator-playbook.md` updated in
+  the same release window. Adds the section-scoped waiver pattern as the
+  canonical guidance with the same anti-misuse framing as the research-os
+  docs page (public guidance is consistent across the surface by design).
+  Deprecates the `min_independent_publishers: 0` pack-level workaround.
+
+### Tests
+
+- **540 total** (527 at v0.3.0 → 540 at v0.3.1, +13 from
+  `test/section-scoped-waivers.test.ts`).
+
+### Migration notes
+
+No code-level migration required. Existing packs continue to work
+unchanged — `section_waivers` defaults to `[]`. Frozen packs' freeze
+receipts remain valid (the schema addition is additive).
+
+For new canonical-protocol packs: prefer section-scoped waivers over the
+deprecated pack-level `min_independent_publishers: 0` workaround. The
+section-scoped pattern preserves the publisher-diversity floor on every
+section that doesn't waive it explicitly.
+
+For operators with packs already using the deprecated pack-level
+workaround: the pattern remains valid; no migration is required. If you
+want to tighten the global default and waive specific sections instead,
+that's a clean per-section migration — set
+`min_independent_publishers` back to its non-zero pack default and add
+section_waivers entries for the sections that need them, with
+`reason` and `compensating_controls[]` documented.
+
+## [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.1"><img src="https://img.shields.io/badge/version-0.3.1-blue" alt="version 0.3.1"></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,13 @@ 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.1** — published to npm as `@mcptoolshop/research-os@0.3.1`, 2026-05-09. Ships section-scoped source-floor waivers (`primary_source_waiver.section_waivers[]`) plus reviewer-side acknowledgement so a waived section-wide `source_cluster_monopoly` finding becomes a visible caveat rather than auto-routing all claims to `needs_source_repair`. Earned by Experiment 3 XRPL pack Session 2 — canonical-protocol sections (single-foundation chains, walled-garden API specs, standards-body docs) inverted the assumption that publisher diversity is a proxy for truth quality. 540/540 vitest passing. See [CHANGELOG.md](CHANGELOG.md) and [`docs/section-scoped-waivers.md`](docs/section-scoped-waivers.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).
+**Section-scoped source waivers** — Use them when publisher diversity is structurally incompatible with the section's truth source, not when a section merely failed to find enough sources. Schema-enforced `reason` + non-empty `compensating_controls[]`. Pack policy `primary_source_waiver_allowed: false` blocks both pack-level and section-scoped waivers. The pre-v0.3.1 pack-level `min_independent_publishers: 0` workaround is now deprecated; existing frozen packs remain valid under their existing receipts. See [`docs/section-scoped-waivers.md`](docs/section-scoped-waivers.md) and the [research-packs operator playbook](https://github.com/mcp-tool-shop-org/research-packs/blob/main/docs/operator-playbook.md).
+
+**v0.3.0** — published 2026-05-09. Shipped 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 then. Detector selection is now an explicit operator choice instead of a state-dependent env-var dance; mode is announced visibly on every run. See [`docs/contradict-map.md`](docs/contradict-map.md).
+
+**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 +165,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 both the v0.3.0 `--detector` flag and the v0.3.1 section-scoped source waivers. 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.