@mcptoolshop/research-os 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,102 @@
 
 All notable changes to `research-os` are documented here.
 
+## [0.2.0] — 2026-05-09
+
+Tight release. Two real, tested, dogfooded improvements: `research-os pack publish`
+(Experiment 2) and the Pattern 2 readiness predicate fix (Session 11 escalation).
+No other v0.2 candidates shipped — remaining 7 items (large-page chunker, JSON-aware
+excerpt chunker, publisher derivation, model-fallback warnings, contradict detector
+strategy, GitHub source guidance, llms.txt guard) are deferred to v0.3/v0.x.
+
+### Added
+
+- **`research-os pack publish`** — exports a frozen pack into the canonical
+  [`research-packs`](https://github.com/mcp-tool-shop-org/research-packs) archive format.
+  CLI: `research-os pack publish --to <path> [--from <path>] [--operator-notes <text>] [--force] [--dry-run]`.
+  Exit 0 on PASS, 2 on refusal. Derives `pack.manifest.json` from pack artifacts,
+  generates `README.md` from `synthesis/final-report.md`, provisions `docs/how-to-read-this.md`
+  scaffold, verifies the admission contract (5 required files, sha256 receipt reproduction,
+  all fingerprinted artifacts). See [`docs/pack-publish.md`](docs/pack-publish.md).
+
+- **48 new tests** under `test/pack-publish/` covering all 8 minimum-scope behaviors
+  (copy, manifest derivation, sha256 verification, accepted-claims derivation,
+  preserved-contradiction-records derivation, README generation, how-to-read scaffold,
+  inline verify-pack) plus refusal cases (missing receipt, missing synthesis,
+  freeze-refusal present, non-empty target without --force, tampered artifacts).
+
+- **`docs/pack-publish.md`** — full CLI reference: flags, refusal cases, produced layout,
+  what the command does NOT do, typical operator workflow.
+
+- **`docs/pack-publish-dogfood.md`** — dogfood receipt: both existing `research-packs`
+  packages re-derived via `pack publish` and verified by `research-packs/scripts/verify-pack.mjs`.
+  `comfyui-workflow-durability` PASS (302 claims, 124 artifacts); `research-os-self-dogfood`
+  PASS (296 claims, 131 artifacts).
+
+- **Handbook page** at `/handbook/pack-publish` — condensed reference with flags, refusal
+  cases, typical workflow, and links to the full reference doc and dogfood receipt.
+
+### Changed
+
+- **Pattern 2 readiness predicate enforcement completed** (commit `22b5dba`).
+  `src/cowork/derive.ts:determineMode` and `src/audit/aggregate.ts:buildReadinessSummary`
+  now use `active_blockers.length === 0` semantics instead of `repair_claim_ids.length === 0`
+  and `repair_claims === 0`. Under Pattern 2, `needs_scope_repair`, `needs_source_repair`,
+  and `needs_human_review` decisions are settled state (review ran, gate passed with
+  sufficient accepted claims) — they are not active blockers.
+
+  **Behavioral change:** packs that previously returned `audit: repair_required` or
+  `handoff: repair_required` solely because claims carry intermediate reviewer decisions
+  (not because any active gate blocker remains) now correctly return
+  `audit: ready_for_synthesis` / `handoff: synthesis_ready`. The `active_blockers` field
+  is now the authoritative readiness signal; it was already correctly computed but was
+  not wired into the verdict in v0.1.
+
+  The v0.1 dogfood pack (`research-os-self-dogfood`) is regression-clean under the new
+  predicate — it used the heuristic reviewer (only `accepted_for_synthesis` and `rejected`
+  decisions), so `repair_claim_ids.length === 0` was equivalent to `active_blockers.length === 0`
+  by coincidence. That coincidence is gone; the intent is now enforced directly.
+
+### Documentation
+
+- README status block updated to v0.2.0; `pack publish` mentioned in the workflow chain.
+- `docs/roadmap.md` Experiment 2 entry updated: `IMPLEMENTED → CLOSED 2026-05-09`.
+- `SHIP_GATE.md` D2 updated: version bump + tag for v0.2.0.
+
+### Tests
+
+- **515 total** (467 at v0.1.1 → 515 at v0.2.0, +48 from `test/pack-publish/`).
+
+### Migration notes
+
+No migration required for existing v0.1.x packs. The Pattern 2 predicate change is
+forward-only: if your pack previously returned `repair_required` and the verdict was
+wrong (all active gate blockers were already resolved), re-running `research-os audit`
+or `research-os cowork handoff` after upgrading to v0.2.0 will return the correct
+`ready_for_synthesis` / `synthesis_ready` verdict. Existing freeze receipts remain valid.
+
+## [0.1.1] — 2026-05-08
+
+Documentation and release-alignment patch. No code or behavior changes — all production source and tests are identical to v0.1.0 (463 vitest cases, all passing).
+
+### Added
+- `docs/roadmap.md` — five experiments that stand between v0.1 and v1.0 (API stability under external pressure, non-self-referential dogfood, extractor-provenance gap closure, reviewer-calibration generalization, hermes3 baseline).
+- README "What v0.1 is not" section disclosing what hasn't been validated yet.
+- README "Known limitations" section naming the extractor-provenance gap and the model-substitution caveat.
+- README "Roadmap to v1.0" section linking to the roadmap doc.
+- Centered logo in README, hosted at `mcp-tool-shop-org/brand`.
+- Status badges: version, CI, license, Node ≥20, handbook.
+- Translated READMEs in 7 languages (ja, zh, es, fr, hi, it, pt-BR) plus the language nav bar.
+- `publishConfig.access=public` in `package.json` for the scoped npm package.
+
+### Fixed
+- README workflow chain order: `review`/`review-promote` come before `gate` (gate consumes review decisions, not the other way around). Quick-start commands updated to match.
+- README CLI invocation: `--triaged-only --preset hermes-two-pass --profile hermes-two-pass` matches the actual demonstrated workflow.
+- `pages.yml` workflow trigger: `branches: [master]` (was `[main]`); the deploy never fired on the v0.1.0 push because of this. Site is now live at <https://mcp-tool-shop-org.github.io/research-os/>.
+
+### Why a patch release
+The v0.1.0 tag was created before the documentation pass landed. The npm tarball at `0.1.0` already includes the corrected README (it was published after the doc commits), but the GitHub tag/release pointed to the pre-doc commit. v0.1.1 realigns everything: tag, GitHub Release, and npm tarball all point at the same coherent state.
+
 ## [0.1.0] — 2026-05-08
 
 ### Added

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.1.0"><img src="https://img.shields.io/badge/version-0.1.0-blue" alt="version 0.1.0"></a>
+  <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/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">
@@ -24,7 +24,67 @@ Local-first CLI that turns an open-ended topic into a gated **research-pack**
 
 It is not a report generator. It is not an LLM-orchestration framework. It does not write your synthesis for you. It enforces the conditions under which synthesis can begin.
 
-**v0.1 has been used exactly once: by itself, on itself.** That single use found seven correctness gaps in `research-os`, each fixed before this release. The proof trail — seven sessions, two integration patterns earned, 463 vitest cases, one frozen pack — lives in [`docs/dogfood-proof.md`](docs/dogfood-proof.md). Live handbook: <https://mcp-tool-shop-org.github.io/research-os/handbook/>.
+Frozen packs are archived in [`mcp-tool-shop-org/research-packs`](https://github.com/mcp-tool-shop-org/research-packs) — live, with two day-one packages. See [`docs/roadmap.md`](docs/roadmap.md) for the v1.0 path.
+
+v0.1 has been pressure-tested in two dogfood arcs. The first — research-os researching its own spec — found seven correctness gaps before the v0.1.0 release, each requiring a real code fix and earning a law or integration pattern. The second (v1 Experiment 1: ComfyUI workflow durability, 11 sessions, a domain with no vocabulary overlap with research-os) closed 2026-05-09: pack frozen, archive live, Pattern 2 enforcement completed via commit `22b5dba`. The v0.1 proof trail lives in [`docs/dogfood-proof.md`](docs/dogfood-proof.md); the Experiment 1 proof lives in [`docs/experiment-1-proof.md`](docs/experiment-1-proof.md). Live handbook: <https://mcp-tool-shop-org.github.io/research-os/handbook/>.
+
+## Install
+
+**Requirements:** Node.js ≥ 20.
+
+```bash
+npm install -g @mcptoolshop/research-os
+```
+
+For contributors building from source:
+
+```bash
+git clone https://github.com/mcp-tool-shop-org/research-os.git
+cd research-os
+npm install
+npm run build
+npm link
+```
+
+## Quick start
+
+```bash
+# Create a new research-pack
+research-os init "How should X be structured?"
+
+# Add a section
+research-os section add 01-landscape --purpose "Map the current landscape"
+
+# Discover and approve sources, then gather
+research-os discover run 01-landscape
+research-os discover approve 01-landscape --top 8
+research-os gather 01-landscape --approved
+
+# Run the per-section chain
+research-os claim extract 01-landscape
+research-os claim audit-density 01-landscape
+research-os claim triage 01-landscape
+research-os contradict map 01-landscape --triaged-only
+research-os review 01-landscape --triaged-only --preset hermes-two-pass --profile hermes-two-pass
+research-os review-promote 01-landscape --profile hermes-two-pass
+research-os gate 01-landscape
+research-os section report 01-landscape
+
+# Pack-level finish
+research-os audit
+research-os index build --all
+research-os cowork handoff
+research-os synth workspace   # only if handoff returned synthesis_ready
+research-os freeze
+
+# Export to the research-packs archive
+research-os pack publish \
+  --to <research-packs>/packages/<name>
+```
+
+**For a real worked example**, see the dogfood pack at `research-os-packs/research-os-spec/` — every artifact, every receipt, every disposition, every freeze fingerprint, all on disk in append-only ledgers. That pack is what produced `docs/dogfood-proof.md`.
+
+**Requires [ollama-intern-mcp](https://github.com/mcp-tool-shop-org/ollama-intern-mcp) running locally** for LLM extraction, triage, review, and discovery. Default model is `hermes3:8b`; override with `OLLAMA_INTERN_MODEL=<model>`. Set `OLLAMA_HOST` if Ollama is not on the default `localhost:11434`.
 
 ## The 16 load-bearing laws
 
@@ -76,55 +136,6 @@ Each step is a CLI command. Each step writes to append-only artifacts. No step s
 
 This is the structural alternative to *search → summarize → pretty report*. The chain is the product.
 
-## Install
-
-**Requirements:** Node.js ≥ 20.
-
-```bash
-# From source (v0.1.0 is not yet published to npm)
-git clone https://github.com/mcp-tool-shop-org/research-os.git
-cd research-os
-npm install
-npm run build
-npm link   # makes `research-os` available on your PATH
-```
-
-## Quick start
-
-```bash
-# Create a new research-pack
-research-os init "How should X be structured?"
-
-# Add a section
-research-os section add 01-landscape --purpose "Map the current landscape"
-
-# Discover and approve sources, then gather
-research-os discover run 01-landscape
-research-os discover approve 01-landscape --top 8
-research-os gather 01-landscape --approved
-
-# Run the per-section chain
-research-os claim extract 01-landscape
-research-os claim audit-density 01-landscape
-research-os claim triage 01-landscape
-research-os contradict map 01-landscape --triaged-only
-research-os review 01-landscape --triaged-only --preset hermes-two-pass --profile hermes-two-pass
-research-os review-promote 01-landscape --profile hermes-two-pass
-research-os gate 01-landscape
-research-os section report 01-landscape
-
-# Pack-level finish
-research-os audit
-research-os index build --all
-research-os cowork handoff
-research-os synth workspace   # only if handoff returned synthesis_ready
-research-os freeze
-```
-
-**For a real worked example**, see the dogfood pack at `research-os-packs/research-os-spec/` — every artifact, every receipt, every disposition, every freeze fingerprint, all on disk in append-only ledgers. That pack is what produced `docs/dogfood-proof.md`.
-
-**Requires [ollama-intern-mcp](https://github.com/mcp-tool-shop-org/ollama-intern-mcp) running locally** for LLM extraction, triage, review, and discovery. Default model is `hermes3:8b`; override with `OLLAMA_INTERN_MODEL=<model>`. Set `OLLAMA_HOST` if Ollama is not on the default `localhost:11434`.
-
 ## Vocabulary
 
 | Term | Meaning |
@@ -140,24 +151,31 @@ research-os freeze
 
 ## Status
 
-**v0.1.0** — frozen 2026-05-08. The dogfood 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`. 463/463 vitest passing. Sixteen load-bearing laws cumulative. See [`docs/dogfood-proof.md`](docs/dogfood-proof.md) for the seven findings and the freeze receipt fingerprints.
+**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).
+
+**`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).
+
+**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.
+
+**research-packs archive monorepo** — live at [`mcp-tool-shop-org/research-packs`](https://github.com/mcp-tool-shop-org/research-packs) with two day-one packages. `comfyui-workflow-durability` (Experiment 1, 302 accepted claims, 8 sections) and `research-os-self-dogfood` (v0.1 dogfood backfill, 296 accepted claims, 8 sections). Both packages PASS `verify-pack.mjs`.
+
+**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.1 is not
+### What v0.2 is not
 
-- Not battle-tested by external users. The single dogfood run found seven bugs.
-- Not yet on npm. Install from source until `npm publish` happens.
+- 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 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 five experiments that close the gap.
+- 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.
 
 ### Known limitations
 
-- **Extractor provenance is not visible at the gate seam.** A section can pass the accepted-claim floor while relying on heuristic-fallback claims when the calibrated extractor (Ollama with the configured model) is unavailable. Recorded as a known weakness; future hardening will report accepted claims by extractor and require the floor's worth of accepted claims from the calibrated path.
-- **Reviewer model selection beyond the calibrated `hermes-two-pass` baseline is unresolved.** The dogfood arc validated one reviewer config; alternative models need their own seeded-failure recall calibration before they can be trusted.
-- **The dogfood pack used `mistral-nemo:12b` for extraction (canonical default is `hermes3:8b`).** Discovery hallucinated wrong-domain results for self-referential section names — corrected by query-precision discipline (see handbook) and operator-pre-staged URLs for ambiguous topics.
+- **Extractor provenance is not visible at the gate seam.** A section can pass the accepted-claim floor while relying on heuristic-fallback claims when the calibrated extractor (Ollama with the configured model) is unavailable. Recorded as Experiment 4 in the roadmap; future hardening will report accepted claims by extractor and require the floor's worth of accepted claims from the calibrated path.
+- **Reviewer model selection beyond the calibrated `hermes-two-pass` baseline is unresolved.** The dogfood arc validated one reviewer config; alternative models need their own seeded-failure recall calibration before they can be trusted. Experiment 5 in the roadmap.
+- **The v0.1 self-dogfood pack used `mistral-nemo:12b` for extraction (canonical default is `hermes3:8b`).** `hermes3:8b` was not available on this rig during the v0.1 arc. The substitution disclosure stands until a hermes3-based receipt is produced — Experiment 6 in the roadmap. For operators on rigs without `hermes3:8b`, set `OLLAMA_INTERN_MODEL` to an available model; operator-pre-staged URLs and query-precision discipline (see handbook) mitigate discovery hallucination on ambiguous topics.
 
 ## Roadmap to v1.0
 
-v1.0 is an earned state, not a release date. Five open experiments stand between v0.1 and v1.0 — API stability under external pressure, a non-self-referential dogfood pack, closing the extractor-provenance gap, generalizing reviewer calibration beyond `hermes-two-pass`, and a clean baseline run on `hermes3:8b`. Full plan in [`docs/roadmap.md`](docs/roadmap.md). The architecture lock holds throughout; v1.0 deepens what v0.1 proved rather than reopening it.
+v1.0 is an earned state, not a release date. Six open experiments stand between v0.1 and v1.0 — non-self-referential dogfood (currently in progress as the ComfyUI workflow durability pack), a `research-os pack publish` command that automates export into the canonical `research-packs` monorepo (Experiment 2, scoped behind Experiment 1's manual closeout), API stability under external pressure, closing the extractor-provenance gap, generalizing reviewer calibration beyond `hermes-two-pass`, and a clean baseline run on `hermes3:8b`. Experiment 1 is not done at pack freeze — it closes when the frozen pack ships as the first package in the `research-packs` monorepo alongside the v0.1 self-dogfood backfill. Full plan in [`docs/roadmap.md`](docs/roadmap.md). The architecture lock holds throughout; v1.0 deepens what v0.1 proved rather than reopening it.
 
 ## License