@mcptoolshop/research-os 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+All notable changes to `research-os` are documented here.
+
+## [0.1.0] — 2026-05-08
+
+### Added
+- Initial scaffold matching mcp-tool-shop conventions
+- `research-os init <topic>` — Link 1 of the workflow chain
+- `research.yaml` schema with intake fields, gate config, and primary-source waiver model
+- Pack template with prompt contracts (`cowork-master.md`, `section-worker.md`, `adversarial-reviewer.md`)
+- Pack-local `CLAUDE.md` operating instructions
+- `research-os section add <id>` — Link 2 of the workflow chain
+- Per-section folder scaffold: `brief.md`, `sources.jsonl`, `claims.jsonl`, `contradictions.md`, `gates.yaml`, `open_questions.md`
+- `gates.yaml` schema for per-section budget and source/contradiction requirements; inherits pack-level defaults with per-section overrides
+- Section id format enforcement (`NN-slug`) and duplicate-id rejection
+- `research-os gather <section>` — Link 3 of the workflow chain
+- Direct-fetch acquisition layer: every fetch attempt produces a persistent `FetchReceipt` (URL, final URL, status, content-type, sha256, byte count, title, raw text path) appended to `evidence/fetch-log.jsonl`
+- `SourceCard` schema separating fetched truth from extracted interpretation, with the `asserts` / `scope` / `not` triple to prevent contextual claims from being promoted into universal rules
+- Extractor adapter interface: `HeuristicExtractor` (cheerio-based, always available) + `OllamaInternExtractor` (local Ollama HTTP, runtime-detected, never required for end users)
+- Failed fetches still write receipts but do not write source cards; failed extractions write a receipt with `extraction_outcome: failed` plus the error, no fake card
+- Load-bearing law added: **fetch is evidence; extraction is interpretation**
+- `research-os claim extract <section>` — Link 4 of the workflow chain
+- `Claim` schema (zod): `claim_id` / `source_ids` / `source_hashes` / `asserts` / `scope` / `not` / `evidence_excerpt` / `evidence_location` / `confidence` / `extractor` / `extraction_method` / `created_at` / `review_state`. Every emitted claim ships at `review_state: candidate` — extraction never promotes
+- `HeuristicClaimExtractor`: one candidate claim per source-card `key_point` with `extraction_method: heuristic_key_point`, `scope: null`, `not: null`, `confidence: low` — labelled honestly as shallow
+- `OllamaInternClaimExtractor`: 3-7 propositional claims per source via local Ollama HTTP, each with its own `asserts` / `scope` / `not` triple grounded in a literal `evidence_excerpt`. Falls back to heuristic when unavailable
+- `OLLAMA_HOST` host normalization: bare `127.0.0.1:11434` and `localhost:11434` are accepted alongside fully-qualified URLs; trailing slashes stripped
+- Re-runs of `claim extract` are idempotent — claim_ids dedupe by `clm_<source-hash>_<extractor>_<index>`
+- `NoSourcesGatheredError` when claim extraction is invoked on an empty section
+- 26 new tests (79 total)
+- `research-os contradict map <section>` — Link 5 of the workflow chain
+- `Contradiction` schema (zod) with six tension types: `direct_conflict` / `scope_conflict` / `temporal_conflict` / `definition_conflict` / `evidence_conflict` / `overgeneralization_risk`. Severity, confidence, scope_analysis, overlap_assessment, status (always `unresolved` at write), detector, detection_method
+- Pair-wise comparison of `review_state: candidate` claims within a single section. Section-scoped only; cross-section mapping is a later link
+- `HeuristicContradictionDetector`: scope-aware similarity + negation matching. Surfaces direct_conflict (token overlap + negation mismatch + overlapping/unknown scope) and overgeneralization_risk (asymmetric scope-tagging on claims that share substantive tokens). Conservative thresholds; only low/medium confidence
+- `OllamaInternContradictionDetector`: pair-wise LLM classification across all six tension types with explicit "none" path; falls back cleanly when unavailable
+- Stable `contradiction_id` = `cnt_<sha256(sorted_claim_pair)>_<detector>` — deterministic and dedup-friendly across re-runs
+- Markdown view written to `sections/<id>/contradictions.md` is regenerated each run; honest "0 candidates detected" when nothing fires; ledger appended to `sections/<id>/contradictions.jsonl`
+- Load-bearing law added: **contradiction mapping surfaces tension; it does not resolve, synthesize, or decide which claim wins**
+- `research-os gate <section>` — Link 6 of the workflow chain
+- Seven gate families: `source_floor` (min_sources, min_independent_publishers, primary_sources_required + waiver, failed-fetches visibility), `claim_integrity` (every_claim_needs_source, no_orphan_claims, source_hashes_present, evidence_excerpt_present, fetch_receipt_anchored, no_source_cluster_monopoly), `scope_integrity` (no_untagged_universal_claims, not_constraint_present, no_blocking_overgeneralization, low-severity overgen warning, scope-tagging summary), `freshness` (policy applicability, no_stale_sources, publication_date_known), `contradiction` (unresolved_visible, unresolved_blocks_synthesis, contradiction_required_by_policy), `section_budget` (budget_configured, runtime_tracking honest about not-yet-tracked), `waivers` (primary-source waiver post-pass that converts fail → pass_with_waiver only when reason + compensating_controls + pack-policy permission all present)
+- Verdict model: `pass` / `warn` / `fail` / `blocked`. `synthesis_eligible: boolean` is the real switch — failures with `blocks_synthesis: true` produce `blocked` verdict; non-blocking failures produce `fail` but remain synthesis-eligible
+- Structured gate result schema: section_id, verdict, summary, checked_at, gate_results[], failures[], warnings[], waivers_applied[], blocking_reasons[], synthesis_eligible, claim_counts, source_counts, contradiction_counts, freshness_summary, scope_integrity_summary, next_actions[]
+- Outputs: `audits/<section>-gate.json` (structured), `audits/<section>-gate.md` (human-readable)
+- `research.yaml.sections[]` status promoted to `gated` only when synthesis_eligible; never downgraded
+- Load-bearing law added: **gates decide whether a section is eligible for synthesis; they do not synthesize, rewrite claims, resolve contradictions, or hide failure**
+- `research-os review <section>` — Link 7 of the workflow chain
+- Thirteen finding categories: `unsupported_claim`, `ungrounded_excerpt`, `stale_claim`, `overgeneralized_claim`, `scope_widening`, `missing_not_constraint`, `source_quality_problem`, `source_cluster_monopoly`, `unmapped_contradiction`, `recommendation_exceeds_evidence`, `hidden_synthesis`, `definition_drift`, `temporal_mismatch`
+- Severity model: `info` / `warn` / `block`
+- Six review decisions: `accepted_for_synthesis`, `rejected`, `needs_scope_repair`, `needs_source_repair`, `needs_contradiction_mapping`, `needs_human_review`
+- `HeuristicReviewer`: missing-field detection, evidence-grounding re-verification against raw text, scope-null risk, unresolved-contradiction involvement, source-cluster monopoly per-claim, source-quality mismatch (high confidence + forum/unknown source type), stale-claim per pack freshness policy, hidden-synthesis flag when brief.md exceeds stub state
+- `OllamaInternReviewer`: pair-pass over candidate claims for `overgeneralized_claim`, `scope_widening`, `definition_drift`, `recommendation_exceeds_evidence`, `hidden_synthesis`, `temporal_mismatch`. **Critical guard**: any LLM finding citing a claim_id or source_id not in the input is rejected as ungrounded reviewer output (counted in `llmFindingsRejected`). Falls back to heuristic when unavailable
+- Append-only ledgers: `audits/<section>-findings.jsonl` and `sections/<id>/claim-reviews.jsonl`. **`claims.jsonl` is never mutated** — extraction truth and review truth are separate
+- Snapshot artifacts (regenerated each run): `audits/<section>-review.json` (structured) and `audits/<section>-review.md` (human-readable)
+- Section status promoted from `gated` → `reviewed` only when **every** candidate claim has decision=`accepted_for_synthesis`
+- Load-bearing law added: **adversarial review judges research integrity; it does not synthesize, rewrite source truth, or erase extraction history**
+- `research-os index build [section]` / `research-os index export-repo-knowledge` / `research-os index sync-repo-knowledge` / `research-os query <term>` — Link 8 of the workflow chain
+- Pack-local SQLite index at `.research-os/index.sqlite` (auto-gitignored). Schema: `sections`, `sources`, `claims`, `contradictions`, `review_findings`, `claim_reviews`, `gate_results`, `fetch_receipts`, `artifacts`, plus FTS5 virtual table `facts_fts` for human-queryable text. Every indexed row carries `artifact_path` so search results point back to canonical files; the SQLite row is a pointer + acceleration layer, not the evidence
+- Re-build is deterministic and idempotent — re-indexing a section deletes its rows then re-inserts from current artifact state. Canonical artifacts (`claims.jsonl`, `contradictions.jsonl`, `claim-reviews.jsonl`, `findings.jsonl`, `gate.json`, source-cards, fetch-log) are never mutated by index build or query
+- Snippet-based query results group by record type; FTS5 prefix queries supported (`prefix='2 3 4'`)
+- `export-repo-knowledge` writes `evidence/repo-knowledge/research-os-facts.jsonl` with one fact per row (`fact_type`, `id`, `section_id`, `text`, `artifact_path`, `metadata`, `pack_origin`, `exported_at`). The export is portable; no runtime dependency on `@mcptoolshop/repo-knowledge`
+- `sync-repo-knowledge` is optional and dynamic — when `@mcptoolshop/repo-knowledge` is locally installed and exposes `ingestFacts`, the index syncs in; when absent, the command exits cleanly with a clear "skipped, use export instead" message. **No hard runtime dependency on repo-knowledge**
+- `IndexNotBuiltError` when querying or exporting before a build has run
+- Load-bearing law added: **indexing makes research truth queryable; it does not create new truth, rewrite truth, or become the source of record**
+- `research-os cowork handoff` — Link 9 of the workflow chain
+- Renders the pack's current research-truth state into a runtime contract for Cowork. Outputs `handoffs/cowork-handoff.json` (structured) + `handoffs/cowork-master.md` (rendered runtime). The static template at `prompts/cowork-master.md` is the source template and is never mutated by handoff
+- Three handoff modes: `repair_required` (sections blocked, no accepted claims, or repair decisions outstanding — Cowork may gather/repair/re-run gates and review, may NOT write final synthesis); `synthesis_ready` (required sections synthesis-eligible, accepted claims exist, no unwaived blocking contradictions — Cowork may produce cross-section synthesis using accepted_claim_ids only); `human_review_required` (invalid waiver state, blocking contradictions, malformed artifacts, or ambiguous review states — Cowork prepares options, doesn't decide)
+- `synthesis_allowed: boolean` is the operational switch. Mode-specific `allowed_write_paths[]` constrain Cowork's write surface
+- `forbidden_actions[]` ships as pack invariants regardless of mode: never mutate claims.jsonl / source-cards / audits, never cite outside the source ledger, never widen scope, never flatten unresolved contradictions, never write final synthesis when mode != synthesis_ready
+- `recommended_next_actions[]` are mode-specific and concrete: in `repair_required` they enumerate per-section commands (`research-os gate <id>`, `research-os review <id>`, etc.); in `synthesis_ready` they walk through synthesis structure
+- `index_status` reported as `present` / `missing`. Missing index produces a warning but does not fail handoff generation — Cowork can still operate from canonical artifacts
+- Mode determination: any malformed artifact / invalid waiver (granted but missing reason or compensating_controls) / unresolved high-or-blocking contradiction → `human_review_required`. Else any not-ready section → `repair_required`. Else → `synthesis_ready`
+- Latest review decision per claim wins (claim-reviews.jsonl is append-only; effective state = claim + latest decision). Re-running cowork handoff is idempotent
+- Load-bearing law added: **cowork handoff renders operational instructions from research truth; it does not create truth, bless weak claims, or bypass gates**
+- `research-os synth workspace` — Link 10 of the workflow chain
+- **Refusal as feature, not error gap.** When `handoffs/cowork-handoff.json` is in `repair_required` or `human_review_required` mode, the workspace command refuses to create synthesis files and exits with code 2 plus a clear remediation message. No empty synthesis placeholders ever appear in repair mode
+- When mode is `synthesis_ready`: writes `synthesis/cross-section-map.json` (structured) and `synthesis/cross-section-map.md` (human-readable map). Both regenerated each run — they are derived state, not Cowork's drafts
+- Also writes `synthesis/decision-brief.md`, `synthesis/working-report.md`, `synthesis/final-report.md` as guardrail-headed writable workspaces — only created if absent so Cowork's drafts are preserved across re-runs. Each carries enforced citation rules in the front-matter (cite only `allowed_synthesis_inputs[]`, never widen scope, preserve unresolved contradictions, disclose all waivers)
+- `CrossSectionMap` schema: pack_id / pack_topic / pack_decision / generated_at / accepted_claim_ids / sections[] / claim_clusters[] / shared_sources[] / scope_overlaps[] / cross_section_contradictions[] / waiver_dependencies[] / open_questions[] / allowed_synthesis_inputs[] / forbidden_inputs[]
+- Claim-cluster derivation via union-find on shared `source_ids`; scope-overlap detection via Jaccard similarity on `scope` strings (threshold 0.3); cross-section contradictions identified by claim_ids spanning multiple sections
+- `forbidden_inputs[]` enumerates every non-accepted claim with its decision and reason — synthesis must not cite them
+- `HandoffNotFoundError` when handoff hasn't been generated yet; `SynthesisNotReadyError` carries the mode for diagnostic clarity
+- Load-bearing law added: **synthesis workspace organizes accepted research truth for Cowork; it does not create synthesis, bless repair-mode claims, or bypass handoff mode**
+- `research-os audit` — Link 11 of the workflow chain
+- Pack-level rollups derived from existing section truth (gate JSON, review JSON, claims, contradictions, claim-reviews, source-cards, fetch-log, handoff). Eight markdown rollups + JSON siblings: `pack-audit.{json,md}`, `orphan-claims.{json,md}`, `stale-sources.{json,md}`, `weak-sources.{json,md}`, `unresolved-contradictions.{json,md}`, `scope-widening-risks.{json,md}`, `source-diversity-gaps.{json,md}`, `synthesis-readiness.{json,md}`
+- Six audit categories: orphan_claims (missing source card / hash / excerpt / unresolvable source_id), stale_sources (too_old / missing_date / unparseable_date per pack policy), weak_sources (cluster monopoly / low publisher count / missing primary / type imbalance / failed-fetches reducing floor), unresolved_contradictions (with explicit "clean ledger ≠ proof of completeness" disclosure), scope_widening_risks (overgeneralization findings, scope=null in use, missing not), source_diversity_gaps (per-section monopoly + cross-section publisher overlap)
+- Pack verdict: `ready_for_synthesis` (every section ready), `repair_required` (some sections need work), `human_review_required` (invalid waivers / blocking contradictions / malformed artifacts), `blocked` (no section has been gated — foundational gap). Verdict never invents green state when section gates are missing
+- Every audit row carries `artifact_path` so rollups are pointers back to canonical evidence; canonical artifacts are never mutated. Idempotent: re-running with the same inputs produces the same rollups
+- `pack-audit.json` schema includes section_summaries / claim_summary / source_summary / contradiction_summary / review_summary / waiver_summary / readiness_summary / audit_files / blocking_reasons / warnings / next_actions
+- Audit rollups are themselves indexable by Link 8 — re-running `research-os index build --all` makes the audit JSON files queryable through `research-os query`
+- Load-bearing law added: **pack audit aggregates existing research truth; it does not create new truth, resolve failures, or hide section-level evidence**
+- `research-os freeze` — Link 12 of the workflow chain (final integrity lock)
+- **Refusal as feature, not error gap.** Freeze refuses unless every pass condition holds: pack-audit verdict=ready_for_synthesis, handoff mode=synthesis_ready, synthesis workspace exists, final-report.md cites accepted claim_ids only (via `[claim:clm_...]` references), unresolved contradictions disclosed in decision-brief or final-report, waivers disclosed similarly, every section has a gate result on file, all canonical artifacts parse cleanly. On refusal, exits with code 2 and writes `audits/freeze-refusal.json` + `audits/freeze-refusal.md`. Does NOT write freeze-receipt.* on refusal. Does NOT mark the pack frozen on refusal
+- On pass: writes `audits/freeze-receipt.json` + `audits/freeze-receipt.md`, sha256-fingerprints every canonical artifact + every synthesis file, sets `research.yaml.frozen_at = <ISO>`, bumps every section status to `frozen`. Removes any stale freeze-refusal artifact from a prior failed run
+- Receipt schema: pack_id / frozen_at / verdict='frozen' / pack_audit_hash / handoff_hash / synthesis_hashes[] / canonical_artifact_hashes[] / accepted_claim_ids[] / cited_claim_ids[] / uncited_accepted_claim_ids[] / unresolved_contradictions[] (with disclosed_in pointers) / waivers_disclosed[] (with disclosed_in pointers) / sections[] / counts / integrity_checks[]
+- Refusal schema: pack_id / checked_at / verdict='refused' / reasons[] / blocking_reasons[] / missing_artifacts[] / invalid_artifacts[] / next_actions[] / would_freeze=false. next_actions[] are concrete commands derived from reasons
+- Citation rule: synthesis markdown must use explicit `[claim:clm_<id>]` references for freeze-grade traceability. Plain prose, source URLs, or vague mentions don't count
+- `frozen_at: string | null` field added to research.yaml schema with default null; existing packs continue to validate
+- Load-bearing law added: **freeze locks completed research truth; it does not complete unfinished research, excuse missing synthesis, or convert repair state into evidence**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,160 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.md">English</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/research-os/readme.png" alt="research-os" width="400">
+</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/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">
+  <a href="https://mcp-tool-shop-org.github.io/research-os/handbook/"><img src="https://img.shields.io/badge/handbook-live-purple" alt="Handbook"></a>
+</p>
+
+# research-os
+
+Una herramienta de línea de comandos (CLI) que transforma un tema abierto en un **paquete de investigación estructurado**, un repositorio organizado donde Claude, Cowork o un conjunto de herramientas pueden trabajar durante horas sin generar información falsa ni distorsionar la investigación.
+
+## ¿Qué es?
+
+`research-os` es la capa de control entre "quiero investigar X" y una base de evidencia sólida y verificable. Separa las pistas de descubrimiento de la recopilación de evidencia, la extracción de datos de la validación de afirmaciones, la detección de contradicciones de la resolución de contradicciones, y las decisiones de revisión de las conclusiones. Cada paso se registra en un registro de solo escritura; cada decisión se calcula a partir de esos registros, no se afirma arbitrariamente.
+
+No es un generador de informes. No es un marco de orquestación de modelos de lenguaje (LLM). No escribe la síntesis por usted. Impone las condiciones bajo las cuales la síntesis puede comenzar.
+
+**La versión 0.1 se ha utilizado exactamente una vez: por sí misma, sobre sí misma.** Ese único uso reveló siete errores en `research-os`, cada uno corregido antes de esta versión. El registro de pruebas, que incluye siete sesiones, dos patrones de integración, 463 casos de prueba `vitest` y un paquete finalizado, se encuentra en [`docs/dogfood-proof.md`](docs/dogfood-proof.md). Manual de usuario: <https://mcp-tool-shop-org.github.io/research-os/handbook/>.
+
+## Las 16 leyes fundamentales
+
+| # | Ley |
+|---|-----|
+| 1 | No hay síntesis antes de la verdad de la fuente. |
+| 2 | La recopilación es evidencia; la extracción es interpretación. |
+| 3 | Los modelos pueden interpretar fragmentos de la fuente; no pueden crear fragmentos de evidencia. |
+| 4 | La extracción puede generar demasiada información; la síntesis no puede heredar esa abundancia. |
+| 5 | El mapeo de contradicciones revela tensiones; no resuelve, sintetiza ni decide qué afirmación es correcta. |
+| 6 | Las restricciones deciden si una sección es elegible para la síntesis. No sintetizan ni ocultan los fallos. |
+| 7 | La revisión crítica evalúa la integridad de la investigación. No sintetiza ni reescribe la verdad de la fuente. |
+| 8 | La indexación hace que la verdad de la investigación sea consultable. No crea nueva verdad ni se convierte en la fuente oficial. |
+| 9 | La transferencia a Cowork genera instrucciones operativas a partir de la verdad de la investigación. No crea verdad ni evita las restricciones. |
+| 10 | El espacio de trabajo de síntesis organiza la verdad de la investigación aceptada para Cowork. No crea síntesis ni evita el modo de transferencia. |
+| 11 | La auditoría del paquete agrega la verdad de la investigación existente. No crea nueva verdad ni oculta la evidencia a nivel de sección. |
+| 12 | El descubrimiento propone pistas; solo la recopilación produce evidencia. |
+| 13 | Un revisor no es confiable hasta que las pruebas de fallos demuestran su capacidad de recuperación. |
+| 14 | La abundancia de afirmaciones no es sinónimo de calidad de la investigación. Las afirmaciones deben ser validadas antes de poder competir para la síntesis. |
+| 15 | La congelación fija la verdad de la investigación completada. No completa la investigación inconclusa ni convierte el estado de reparación en evidencia. |
+| 16 | Las exenciones relajan las restricciones de la fuente; no pueden crear evidencia. |
+
+**Ley 3** — el modelo de lenguaje nunca crea texto de evidencia. `research-os` crea un registro de extractos determinista (con identificadores estables como `ex_<id_hex_de_la_fuente>_001`); el modelo de lenguaje elige los identificadores de los extractos; `research-os` copia el texto literal. La clase de error "parafrasear como cita" es estructuralmente imposible.
+
+**Ley 14** — entre la extracción y la revisión, `research-os claim triage` elimina duplicados, limita la contribución por fuente y reserva los candidatos de bajo rendimiento. El triage NO modifica `claims.jsonl`; las afirmaciones reservadas permanecen en el registro canónico.
+
+## La cadena de flujo de trabajo de la versión 0.1
+
+```
+discover
+→ gather
+→ claim extract
+→ claim audit-density
+→ claim triage
+→ contradict map
+→ contradict resolve
+→ review
+→ review-promote
+→ gate
+→ section report
+→ audit
+→ index build
+→ cowork handoff
+→ synth workspace
+→ freeze
+```
+
+Cada paso es un comando de la interfaz de línea de comandos (CLI). Cada paso escribe en archivos que solo se pueden añadir, no modificar. Ningún paso sintetiza, resuelve o crea nueva información verificable; esos invariantes se aplican, no se confían. La revisión acepta, rechaza o solicita correcciones para las afirmaciones propuestas; el proceso de "gate" utiliza estas decisiones de revisión para calcular la elegibilidad para la síntesis; la fase de "freeze" es el bloqueo final de integridad que impide marcar un paquete como completado a menos que todas las capas estén de acuerdo. Consulte [docs/dogfood-proof.md](docs/dogfood-proof.md) para la prueba de la versión 0.1 que demuestra la integridad de la cadena de principio a fin.
+
+Esta es la alternativa estructural a *búsqueda → resumen → informe detallado*. La cadena es el producto.
+
+## Instalación
+
+**Requisitos:** 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
+```
+
+## Inicio rápido
+
+```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
+```
+
+**Para un ejemplo práctico**, consulte el paquete de prueba en `research-os-packs/research-os-spec/`: cada archivo, cada registro, cada disposición, cada huella digital de la fase de "freeze", todo almacenado en el disco en registros de solo escritura. Ese paquete es el que generó `docs/dogfood-proof.md`.
+
+**Requiere [ollama-intern-mcp](https://github.com/mcp-tool-shop-org/ollama-intern-mcp) ejecutándose localmente** para la extracción, clasificación, revisión y descubrimiento de modelos de lenguaje. El modelo predeterminado es `hermes3:8b`; puede cambiarlo con `OLLAMA_INTERN_MODEL=<modelo>`. Establezca `OLLAMA_HOST` si Ollama no se ejecuta en el puerto predeterminado `localhost:11434`.
+
+## Glosario
+
+| Término | Significado |
+|------|---------|
+| `research-os` | El plano de control / CLI / mecanismos de control / ley de orquestación (este repositorio) |
+| `research-pack` | El archivo generado para un esfuerzo de investigación. |
+| `research section` | Una unidad de investigación delimitada dentro de un paquete. |
+| `research receipt` | Prueba de que una sección ha superado las comprobaciones de origen/afirmación/mecanismo de control. |
+
+## Seguridad
+
+`research-os` es una herramienta de línea de comandos que funciona principalmente localmente. Lee y escribe archivos dentro del directorio del paquete de investigación al que la apunta, y (cuando se utiliza `gather`) realiza solicitudes HTTP salientes para obtener las URL de origen que proporciona. No: ejecuta un servidor, acepta conexiones entrantes, almacena credenciales ni envía datos de telemetría. No se escriben secretos en los archivos del paquete. Consulte [SECURITY.md](SECURITY.md) para la política de notificación de vulnerabilidades.
+
+## Estado
+
+**v0.1.0** — Congelado el 08 de mayo de 2026. El paquete de prueba en `research-os-packs/research-os-spec/` (repositorio relacionado) alcanzó la fase de "freeze" con 296 afirmaciones aceptadas en 8 secciones, 17 dispuestas, 30 modificadas por el operador, 0 bloqueadores de corrección activos, 0 contradicciones sin resolver, y todos los mecanismos de control con `synthesis_eligible=true`. 463/463 pruebas de vitest superadas. Dieciséis leyes fundamentales acumuladas. Consulte [`docs/dogfood-proof.md`](docs/dogfood-proof.md) para conocer los siete hallazgos y las huellas digitales de la fase de "freeze".
+
+### Lo que la versión 0.1 no es
+
+- No ha sido probada por usuarios externos. La única ejecución de prueba encontró siete errores.
+- Todavía no está disponible en npm. Instale desde el código fuente hasta que se publique en npm.
+- No es un generador de contenido. El comando `synth workspace` genera el espacio de trabajo estructurado; los humanos (o Cowork) escriben el contenido en función de los ID de las afirmaciones aceptadas.
+- No tiene una API estable según las convenciones de versiones semánticas. La versión 1.0.0 se lanzará después de que los usuarios externos hayan validado la interfaz a lo largo del tiempo.
+
+### Limitaciones conocidas
+
+- **La información sobre el origen del extractor no es visible en la costura de la puerta.** Una sección puede superar el umbral de aceptación si se utilizan criterios de evaluación alternativos cuando el extractor calibrado (Ollama con el modelo configurado) no está disponible. Se ha registrado como una debilidad conocida; en el futuro, se informará sobre las reclamaciones aceptadas por el extractor y se requerirá un número de reclamaciones aceptadas equivalente al umbral desde la ruta calibrada.
+- **La selección del modelo de revisión, más allá de la línea de base calibrada `hermes-two-pass`, no está resuelta.** El ciclo de pruebas internas validó una configuración de revisión; otros modelos necesitan su propia calibración para detectar fallos antes de que puedan ser considerados fiables.
+- **El paquete de pruebas internas utilizó `mistral-nemo:12b` para la extracción (el valor predeterminado estándar es `hermes3:8b`).** El sistema generó resultados incorrectos para nombres de secciones que se referían a sí mismos; esto se corrigió mediante la precisión de las consultas (ver manual) y mediante URLs predefinidas por el operador para temas ambiguos.
+
+## Licencia
+
+MIT

package/README.fr.md

@@ -0,0 +1,160 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.md">English</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/research-os/readme.png" alt="research-os" width="400">
+</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/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">
+  <a href="https://mcp-tool-shop-org.github.io/research-os/handbook/"><img src="https://img.shields.io/badge/handbook-live-purple" alt="Handbook"></a>
+</p>
+
+# research-os
+
+Un outil en ligne de commande qui transforme un sujet ouvert en un **ensemble de ressources de recherche structuré** — un référentiel organisé où Claude, Cowork ou un groupe de personnes peuvent travailler pendant des heures sans produire d'hallucinations ni déformer l'investigation.
+
+## Qu'est-ce que c'est
+
+`research-os` est la couche de contrôle entre "Je veux étudier X" et une base de preuves structurée et vérifiable. Il sépare les pistes de découverte de la collecte de preuves, l'extraction brute des affirmations triées, la détection des contradictions de la résolution des contradictions, et les décisions de révision des dispositions de synthèse. Chaque étape est enregistrée dans un registre en écriture seule ; chaque verdict de validation est calculé à partir de ces registres, et non affirmé.
+
+Ce n'est pas un générateur de rapports. Ce n'est pas un framework d'orchestration de modèles de langage (LLM). Il ne rédige pas la synthèse pour vous. Il impose les conditions dans lesquelles la synthèse peut commencer.
+
+**La version 0.1 a été utilisée une seule fois : par elle-même, sur elle-même.** Cette seule utilisation a révélé sept lacunes de correction dans `research-os`, chacune étant corrigée avant cette version. La traçabilité des modifications — sept sessions, deux modèles d'intégration, 463 cas de tests `vitest`, un ensemble de ressources structuré — se trouve dans [`docs/dogfood-proof.md`](docs/dogfood-proof.md). Manuel d'utilisation : <https://mcp-tool-shop-org.github.io/research-os/handbook/>.
+
+## Les 16 lois fondamentales
+
+| # | Loi |
+|---|-----|
+| 1 | Pas de synthèse avant la vérification des sources. |
+| 2 | La collecte est une preuve ; l'extraction est une interprétation. |
+| 3 | Les modèles peuvent interpréter des extraits de sources ; ils ne peuvent pas créer de preuves. |
+| 4 | L'extraction peut produire trop d'informations ; la synthèse ne peut pas en hériter. |
+| 5 | La cartographie des contradictions révèle les tensions ; elle ne résout pas, ne synthétise pas et ne décide pas quelle affirmation est correcte. |
+| 6 | Les mécanismes de contrôle déterminent si une section est éligible à la synthèse. Ils ne synthétisent pas et ne masquent pas les échecs. |
+| 7 | L'examen par les pairs évalue l'intégrité de la recherche. Il ne synthétise pas et ne réécrit pas les sources vérifiées. |
+| 8 | L'indexation rend la recherche vérifiable. Elle ne crée pas de nouvelles informations et ne devient pas la source de référence. |
+| 9 | La transmission à Cowork transforme les instructions opérationnelles à partir des informations de recherche vérifiées. Elle ne crée pas de nouvelles informations et ne contourne pas les mécanismes de contrôle. |
+| 10 | L'espace de travail de synthèse organise les informations de recherche vérifiées pour Cowork. Il ne crée pas de synthèse et ne contourne pas le mode de transmission. |
+| 11 | L'audit de l'ensemble de ressources agrège les informations de recherche existantes. Il ne crée pas de nouvelles informations et ne masque pas les preuves au niveau des sections. |
+| 12 | La découverte propose des pistes ; seule la collecte produit des preuves. |
+| 13 | Un examinateur ne peut être considéré comme fiable tant que des échecs simulés n'ont pas prouvé sa capacité de rappel. |
+| 14 | L'abondance des affirmations ne garantit pas la qualité de la recherche. Les affirmations doivent être triées avant de pouvoir être prises en compte pour la synthèse. |
+| 15 | La "gelée" verrouille les informations de recherche vérifiées. Elle ne complète pas les recherches inachevées et ne convertit pas l'état de réparation en preuves. |
+| 16 | Les dérogations assouplissent les contraintes des sources ; elles ne peuvent pas créer de preuves. |
+
+**Loi 3** — le modèle de langage ne crée jamais de texte de preuve. `research-os` crée un registre d'extraits déterministes (identifiants stables comme `ex_<source_id_hex>_001`); le modèle de langage choisit les identifiants des extraits ; `research-os` copie le texte littéral. La classe d'erreur "paraphrase-as-quote" est structurellement impossible.
+
+**Loi 14** — entre l'extraction et l'examen, `research-os claim triage` déduplique, limite la contribution par source et met de côté les candidats à faible valeur ajoutée. Le triage NE modifie PAS `claims.jsonl`; les affirmations mises de côté restent dans le registre canonique.
+
+## La chaîne de flux de travail de la version 0.1
+
+```
+discover
+→ gather
+→ claim extract
+→ claim audit-density
+→ claim triage
+→ contradict map
+→ contradict resolve
+→ review
+→ review-promote
+→ gate
+→ section report
+→ audit
+→ index build
+→ cowork handoff
+→ synth workspace
+→ freeze
+```
+
+Chaque étape est une commande en ligne de commande. Chaque étape écrit des données dans des fichiers qui ne peuvent être modifiés qu'en ajoutant des informations. Aucune étape ne synthétise, ne résout ou ne crée de nouvelles informations vérifiées ; ces invariants sont appliqués, et non simplement considérés comme acquis. L'étape de revue accepte, rejette ou demande une correction des propositions candidates ; l'étape de validation utilise ces décisions pour calculer l'éligibilité à la synthèse ; l'étape de "gel" est le verrouillage final qui empêche de marquer un ensemble comme terminé, sauf si toutes les étapes sont d'accord. Consultez le fichier [docs/dogfood-proof.md](docs/dogfood-proof.md) pour la preuve de la version 0.1 qui démontre que la chaîne fonctionne de bout en bout.
+
+Ceci est une alternative structurée à *recherche → résumé → rapport détaillé*. La chaîne est le produit.
+
+## Installation
+
+**Prérequis :** 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
+```
+
+## Démarrage rapide
+
+```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
+```
+
+**Pour un exemple concret**, consultez l'ensemble de données "dogfood" situé dans `research-os-packs/research-os-spec/` : chaque fichier, chaque enregistrement, chaque disposition, chaque empreinte de "gel", le tout est stocké sur disque dans des fichiers qui ne peuvent être modifiés qu'en ajoutant des informations. Cet ensemble de données a généré le fichier `docs/dogfood-proof.md`.
+
+**Nécessite [ollama-intern-mcp](https://github.com/mcp-tool-shop-org/ollama-intern-mcp) en cours d'exécution localement** pour l'extraction, le tri, la revue et la découverte des modèles de langage. Le modèle par défaut est `hermes3:8b`; vous pouvez le modifier en utilisant la variable d'environnement `OLLAMA_INTERN_MODEL=<modèle>`. Définissez la variable d'environnement `OLLAMA_HOST` si Ollama n'est pas exécuté sur l'adresse par défaut `localhost:11434`.
+
+## Vocabulaire
+
+| Terme | Signification |
+|------|---------|
+| `research-os` | Le plan de contrôle / l'interface en ligne de commande / les étapes de validation / la loi d'orchestration (ce dépôt) |
+| `research-pack` | L'artefact de dépôt généré pour un effort de recherche. |
+| `research section` | Une unité d'investigation délimitée à l'intérieur d'un ensemble de données. |
+| `research receipt` | Preuve qu'une section a passé les vérifications de source/proposition/étape de validation. |
+
+## Sécurité
+
+`research-os` est une interface en ligne de commande qui fonctionne localement. Elle lit et écrit des fichiers dans le répertoire de l'ensemble de données que vous lui spécifiez, et (lorsque vous utilisez la commande `gather`), elle effectue des requêtes HTTP sortantes pour récupérer les URL de sources que vous fournissez. Elle ne : ne fait pas fonctionner de serveur, n'accepte pas de connexions entrantes, ne stocke pas de mots de passe, ni n'envoie de données de télémétrie. Aucun mot de passe n'est écrit dans les fichiers de l'ensemble de données. Consultez le fichier [SECURITY.md](SECURITY.md) pour connaître la politique de signalement des vulnérabilités.
+
+## Statut
+
+**v0.1.0** — gelée le 2026-05-08. L'ensemble de données "dogfood" situé dans `research-os-packs/research-os-spec/` (dépôt frère) a atteint l'état de "gel" avec 296 propositions acceptées réparties sur 8 sections, 17 dispositions, 30 propositions corrigées par l'utilisateur, 0 blocage de correction actif, 0 contradiction non résolue, toutes les étapes de validation indiquant `synthesis_eligible=true`. 463/463 tests Vitest réussis. Seize règles fondamentales cumulées. Consultez le fichier [`docs/dogfood-proof.md`](docs/dogfood-proof.md) pour connaître les sept découvertes et les empreintes des enregistrements de "gel".
+
+### Ce que la version 0.1 n'est pas
+
+- Non testée en conditions réelles par des utilisateurs externes. La seule exécution "dogfood" a révélé sept bogues.
+- Pas encore disponible sur npm. Installez à partir du code source jusqu'à ce que la publication `npm publish` ait lieu.
+- Pas un générateur de code. La commande `synth workspace` génère l'espace de travail structuré ; les humains (ou Cowork) écrivent le texte en fonction des identifiants des propositions acceptées.
+- Pas une API stable selon les règles de compatibilité sémantique. La version 1.0.0 sera publiée après que des utilisateurs externes auront validé l'interface au fil du temps.
+
+### Limitations connues
+
+- **L'origine de l'extracteur n'est pas visible au niveau de la jointure.** Une section peut passer le seuil de validité tout en s'appuyant sur des mécanismes de repli heuristiques lorsque l'extracteur calibré (Ollama avec le modèle configuré) n'est pas disponible. Ceci est enregistré comme une faiblesse connue ; les améliorations futures indiqueront les affirmations acceptées par l'extracteur et exigeront un nombre d'affirmations acceptées égal au seuil à partir du chemin calibré.
+- **Le choix du modèle de réviseur, au-delà de la base de référence calibrée `hermes-two-pass`, n'est pas encore résolu.** L'environnement de test interne a validé une configuration de réviseur ; les modèles alternatifs doivent être calibrés avec des tests de défaillance simulées avant de pouvoir être utilisés.
+- **Le pack de test interne a utilisé `mistral-nemo:12b` pour l'extraction (la valeur par défaut est `hermes3:8b`).** Le système a généré des résultats incorrects pour des noms de sections auto-référentielles, ce qui a été corrigé grâce à une discipline de précision des requêtes (voir le manuel) et à des URL pré-configurées par les opérateurs pour les sujets ambigus.
+
+## Licence
+
+MIT