@mcptoolshop/research-os 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+<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.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
+
+Local-first CLI that turns an open-ended topic into a gated **research-pack** — a structured repo where Claude, Cowork, or a swarm can work for hours without hallucinating or flattening the investigation.
+
+## What it is
+
+`research-os` is the control plane between "I want to research X" and a frozen, claim-traceable evidence base. It separates discovery leads from fetch evidence, raw extraction from triaged claims, contradiction detection from contradiction resolution, and review decisions from synthesis dispositions. Every step writes to an append-only ledger; every readiness verdict is computed from those ledgers, not asserted.
+
+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/>.
+
+## The 16 load-bearing laws
+
+| # | Law |
+|---|-----|
+| 1 | No synthesis before source truth. |
+| 2 | Fetch is evidence; extraction is interpretation. |
+| 3 | Models may interpret source spans; they may not author evidence spans. |
+| 4 | Extraction may overproduce; synthesis may not inherit abundance. |
+| 5 | Contradiction mapping surfaces tension; it does not resolve, synthesize, or decide which claim wins. |
+| 6 | Gates decide whether a section is eligible for synthesis. They do not synthesize or hide failure. |
+| 7 | Adversarial review judges research integrity. It does not synthesize or rewrite source truth. |
+| 8 | Indexing makes research truth queryable. It does not create new truth or become the source of record. |
+| 9 | Cowork handoff renders operational instructions from research truth. It does not create truth or bypass gates. |
+| 10 | Synthesis workspace organizes accepted research truth for Cowork. It does not create synthesis or bypass handoff mode. |
+| 11 | Pack audit aggregates existing research truth. It does not create new truth or hide section-level evidence. |
+| 12 | Discovery proposes leads; only fetch produces evidence. |
+| 13 | A reviewer is not trusted until seeded failures prove recall. |
+| 14 | Claim abundance is not research quality. Claims must be triaged before they can compete for synthesis. |
+| 15 | Freeze locks completed research truth. It does not complete unfinished research or convert repair state into evidence. |
+| 16 | Waivers relax source constraints; they cannot manufacture evidence. |
+
+**Law 3** — the LLM never authors evidence text. research-os builds a deterministic excerpt ledger (stable IDs like `ex_<source_id_hex>_001`); the LLM picks excerpt IDs; research-os copies the literal text. The "paraphrase-as-quote" failure class is structurally impossible.
+
+**Law 14** — between extraction and review, `research-os claim triage` deduplicates, caps per-source contribution, and parks low-leverage candidates. Triage does NOT mutate `claims.jsonl`; parked claims remain on the canonical ledger.
+
+## The v0.1 workflow chain
+
+```
+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
+```
+
+Each step is a CLI command. Each step writes to append-only artifacts. No step synthesizes, resolves, or creates new truth — those invariants are enforced, not trusted. Review accepts/rejects/requests-repair on candidate claims; gate consumes those review decisions to compute `synthesis_eligible`; freeze is the final integrity lock that refuses to mark a pack done unless every layer agrees. See [docs/dogfood-proof.md](docs/dogfood-proof.md) for the v0.1 proof that the chain holds end-to-end.
+
+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 |
+|------|---------|
+| `research-os` | The control plane / CLI / gates / orchestration law (this repo) |
+| `research-pack` | The generated repo artifact for one research effort |
+| `research section` | A bounded unit of investigation inside a pack |
+| `research receipt` | Proof a section passed source/claim/gate checks |
+
+## Security
+
+`research-os` is a local-first CLI. It reads and writes files within the research-pack directory you point it at, and (when using `gather`) issues outbound HTTP requests to fetch source URLs you provide. It does not: run a server, accept inbound connections, store credentials, or send telemetry. No secrets are written to pack artifacts. See [SECURITY.md](SECURITY.md) for the vulnerability reporting policy.
+
+## 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.
+
+### What v0.1 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 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.
+
+### 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.
+
+## 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.
+
+## License
+
+MIT

package/README.pt-BR.md

@@ -0,0 +1,164 @@
+<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.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.md">English</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
+
+Uma ferramenta de linha de comando (CLI) que transforma um tópico amplo em um "pacote de pesquisa" estruturado — um repositório organizado onde Claude, Cowork ou um sistema podem trabalhar por horas sem gerar informações falsas ou comprometer a investigação.
+
+## O que é
+
+`research-os` é a camada de controle entre "quero pesquisar X" e uma base de evidências precisa e rastreável. Ele separa as etapas de descoberta das etapas de coleta de evidências, a extração bruta da análise crítica, a detecção de contradições da resolução de contradições e as decisões de revisão das etapas de síntese. Cada etapa registra as informações em um registro de auditoria imutável; cada verificação de prontidão é calculada a partir desses registros, e não baseada em afirmações.
+
+Não é um gerador de relatórios. Não é um framework de orquestração de LLMs (Large Language Models). Não escreve a síntese para você. Ele impõe as condições sob as quais a síntese pode começar.
+
+**A versão 0.1 foi usada apenas uma vez: por si só, em si mesma.** Essa única utilização identificou sete falhas na `research-os`, todas corrigidas antes desta versão. O histórico de validação — sete sessões, dois padrões de integração implementados, 463 casos de teste `vitest`, um pacote finalizado — está disponível em [`docs/dogfood-proof.md`](docs/dogfood-proof.md). Manual completo: <https://mcp-tool-shop-org.github.io/research-os/handbook/>.
+
+## As 16 leis fundamentais
+
+| # | Lei |
+|---|-----|
+| 1 | Nenhuma síntese antes da verificação da fonte original. |
+| 2 | Coleta é evidência; interpretação é análise. |
+| 3 | Os modelos podem interpretar trechos da fonte; eles não podem criar trechos de evidência. |
+| 4 | A extração pode gerar informações em excesso; a síntese não pode herdar essa abundância. |
+| 5 | O mapeamento de contradições revela tensões; ele não resolve, sintetiza ou decide qual afirmação é válida. |
+| 6 | Os "gates" (portões) decidem se uma seção é elegível para síntese. Eles não sintetizam nem escondem falhas. |
+| 7 | A revisão crítica avalia a integridade da pesquisa. Ela não sintetiza nem reescreve a fonte original. |
+| 8 | A indexação torna a pesquisa acessível por consulta. Ela não cria novas informações nem se torna a fonte oficial. |
+| 9 | A transferência para o Cowork transforma as informações da pesquisa em instruções operacionais. Ela não cria informações nem ignora os "gates". |
+| 10 | O espaço de trabalho de síntese organiza as informações da pesquisa aceitas para o Cowork. Ele não cria a síntese nem ignora a etapa de transferência. |
+| 11 | A auditoria do pacote agrega as informações da pesquisa existentes. Ela não cria novas informações nem oculta as evidências de cada seção. |
+| 12 | A descoberta propõe hipóteses; apenas a coleta produz evidências. |
+| 13 | Um revisor não é considerado confiável até que falhas simuladas comprovem a precisão. |
+| 14 | A quantidade de afirmações não é sinônimo de qualidade da pesquisa. As afirmações devem ser analisadas criticamente antes de poderem ser consideradas para a síntese. |
+| 15 | O "freeze" (congelamento) fixa as informações da pesquisa concluídas. Ele não completa pesquisas inacabadas nem converte o estado de correção em evidências. |
+| 16 | As "waivers" (dispensas) relaxam as restrições da fonte original; elas não podem criar evidências. |
+
+**Lei 3** — o LLM nunca cria o texto da evidência. A `research-os` cria um registro de trechos determinístico (com IDs estáveis como `ex_<source_id_hex>_001`); o LLM escolhe os IDs dos trechos; a `research-os` copia o texto literal. A classe de falha "paráfrase como citação" é estruturalmente impossível.
+
+**Lei 14** — entre a extração e a revisão, a `research-os claim triage` (triagem de afirmações) remove duplicatas, limita a contribuição por fonte e armazena temporariamente candidatos de baixo valor. A triagem NÃO modifica o arquivo `claims.jsonl`; as afirmações armazenadas temporariamente permanecem no registro oficial.
+
+## O fluxo de trabalho da versão 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 etapa é um comando de linha de comando (CLI). Cada etapa grava informações em arquivos que só podem ser adicionados, não modificados. Nenhuma etapa sintetiza, resolve ou cria novas informações — esses princípios são aplicados, não confiados. A revisão aceita, rejeita ou solicita correções em relação às afirmações candidatas; o sistema de "gates" utiliza essas decisões de revisão para calcular a elegibilidade para síntese; o "freeze" é o bloqueio final de integridade que impede que um pacote seja considerado finalizado, a menos que todas as camadas concordem. Consulte [docs/dogfood-proof.md](docs/dogfood-proof.md) para a documentação da versão 0.1 que comprova que a cadeia funciona de ponta a ponta.
+
+Esta é a alternativa estrutural para *pesquisar → resumir → gerar relatório detalhado*. A cadeia é o produto.
+
+## Instalação
+
+**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
+```
+
+## Início 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 um exemplo prático**, veja o pacote de teste em `research-os-packs/research-os-spec/` — todos os arquivos, todos os registros, todas as disposições, todas as "impressões digitais" do "freeze", tudo armazenado em arquivos que só podem ser adicionados. Esse pacote gerou o arquivo `docs/dogfood-proof.md`.
+
+**Requer que o [ollama-intern-mcp](https://github.com/mcp-tool-shop-org/ollama-intern-mcp) esteja em execução localmente** para extração, triagem, revisão e descoberta de modelos de linguagem (LLM). O modelo padrão é `hermes3:8b`; você pode alterá-lo definindo a variável de ambiente `OLLAMA_INTERN_MODEL=<modelo>`. Defina a variável de ambiente `OLLAMA_HOST` se o Ollama não estiver no endereço padrão `localhost:11434`.
+
+## Vocabulário
+
+| Termo | Significado |
+|------|---------|
+| `research-os` | O plano de controle / CLI / sistema de "gates" / a lei da orquestração (este repositório) |
+| `research-pack` | O arquivo gerado para um esforço de pesquisa. |
+| `research section` | Uma unidade de investigação delimitada dentro de um pacote. |
+| `research receipt` | Comprovação de que uma seção passou nas verificações de origem/afirmação/sistema de "gates". |
+
+## Segurança
+
+`research-os` é uma ferramenta de linha de comando que opera localmente. Ela lê e grava arquivos dentro do diretório do pacote de pesquisa que você especificar e, quando usa o comando `gather`, faz solicitações HTTP para buscar URLs de origem que você fornecer. Ela não: executa um servidor, aceita conexões de entrada, armazena credenciais ou envia dados de telemetria. Nenhum segredo é gravado nos arquivos do pacote. Consulte [SECURITY.md](SECURITY.md) para a política de relatório de vulnerabilidades.
+
+## Status
+
+**v0.1.0** — bloqueado em 2026-05-08. O pacote de teste em `research-os-packs/research-os-spec/` (repositório relacionado) atingiu o estado de bloqueio com 296 afirmações aceitas em 8 seções, 17 dispostas, 30 substituídas por operadores, 0 bloqueadores de correção ativos, 0 contradições não resolvidas, todos os "gates" com `synthesis_eligible=true`. 463/463 testes "vitest" passaram. Dezesseis leis fundamentais foram implementadas. Consulte [`docs/dogfood-proof.md`](docs/dogfood-proof.md) para as sete descobertas e as "impressões digitais" dos registros de bloqueio.
+
+### O que a versão 0.1 não é
+
+- Não foi testada por usuários externos. A única execução de teste encontrou sete bugs.
+- Ainda não está disponível no npm. Instale a partir do código-fonte até que a publicação no npm ocorra.
+- Não é um gerador de conteúdo. O comando `synth workspace` gera o ambiente de trabalho estruturado; humanos (ou Cowork) escrevem o texto em relação aos IDs das afirmações aceitas.
+- Não tem estabilidade de API compatível com a versão semântica. A versão 1.0.0 é um estado alcançado, não uma data no calendário — consulte [`docs/roadmap.md`](docs/roadmap.md) para os cinco experimentos que preencherão essa lacuna.
+
+### Limitações conhecidas
+
+- **A origem do extrator não é visível na junção da porta.** Uma seção pode passar pelo limite aceitável, mesmo utilizando mecanismos de fallback heurísticos, quando o extrator calibrado (Ollama com o modelo configurado) não está disponível. Isso foi registrado como uma vulnerabilidade conhecida; as futuras melhorias reportarão as reivindicações aceitas pelo extrator e exigirão um número de reivindicações aceitas equivalente ao limite definido, provenientes do caminho calibrado.
+- **A seleção do modelo de revisão, além da linha de base calibrada `hermes-two-pass`, ainda não foi resolvida.** O ambiente de testes internos validou uma configuração de revisão; modelos alternativos precisam de sua própria calibração para cenários de falha simulada antes de poderem ser considerados confiáveis.
+- **O pacote de testes internos utilizou `mistral-nemo:12b` para a extração (o padrão é `hermes3:8b`).** O sistema apresentou alucinações, gerando resultados para domínios incorretos para nomes de seções que se referiam a si mesmas. Isso foi corrigido através de uma disciplina de precisão na consulta (ver manual) e URLs pré-definidas pelos operadores para tópicos ambíguos.
+
+## Roteiro para a versão 1.0
+
+A versão 1.0 é um estado alcançado, não uma data de lançamento. Cinco experimentos estão em andamento entre a versão 0.1 e a versão 1.0: estabilidade da API sob pressão externa, um pacote de testes internos que não se refere a si mesmo, fechamento da lacuna de rastreabilidade do extrator, generalização da calibração do revisor além do `hermes-two-pass` e uma execução de linha de base limpa no `hermes3:8b`. O plano completo está disponível em [`docs/roadmap.md`](docs/roadmap.md). A arquitetura permanece fixa; a versão 1.0 aprofunda o que a versão 0.1 demonstrou, em vez de reabri-lo.
+
+## Licença
+
+MIT

package/README.zh.md

@@ -0,0 +1,160 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.md">English</a> | <a href="README.es.md">Español</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
+
+`research-os` 是一个本地优先的命令行工具，它将一个开放性的主题转化为一个结构化的**研究包**，在这个结构化的代码仓库中，Claude、Cowork或其他系统可以工作数小时，而不会出现幻觉或偏离研究方向。
+
+## 它是什么
+
+`research-os` 是“我想研究 X”和“一个经过验证、可追溯证据的基础”之间的控制层。它将发现线索与获取证据、原始提取与筛选后的论点、矛盾检测与矛盾解决、审查决策与综合结论等环节分开。每个步骤都会写入一个只追加的日志；每个准备就绪的判断都是基于这些日志计算得出的，而不是主观臆断。
+
+它不是一个报告生成器。它不是一个大型语言模型（LLM）编排的**框架**。它不会为你自动生成综合结论。它强制执行在开始综合之前必须满足的条件。
+
+**v0.1 版本** 仅被使用过一次：它本身被用于测试自身。这次测试发现了 `research-os` 中的七个正确性问题，并在本次**发布**之前都已修复。完整的验证过程——七个会话、两种集成模式、463 个 `vitest` 测试用例、一个冻结的**研究包**——都记录在 [`docs/dogfood-proof.md`](docs/dogfood-proof.md) 文件中。 详细指南：<https://mcp-tool-shop-org.github.io/research-os/handbook/>。
+
+## 16 条核心原则
+
+| # | 原则 |
+|---|-----|
+| 1 | 在获得原始数据之前，不能进行综合。 |
+| 2 | 获取是证据；提取是解释。 |
+| 3 | 模型可以解释原始数据的片段，但不能生成证据片段。 |
+| 4 | 提取可能会产生过多的信息；综合不能简单地继承这些信息。 |
+| 5 | 矛盾映射会暴露潜在的冲突，但它不会解决、综合或决定哪个论点更胜一筹。 |
+| 6 | 闸门决定一个部分是否符合综合的条件。它们不进行综合，也不隐藏失败。 |
+| 7 | 对抗性审查用于评估研究的完整性。它不进行综合，也不重写原始数据。 |
+| 8 | 索引使研究结果可以被查询。它不创造新的事实，也不成为官方记录。 |
+| 9 | Cowork 模式将研究结果转化为可操作的指令。它不创造事实，也不绕过闸门。 |
+| 10 | 综合工作区用于组织 Cowork 模式中接受的研究结果。它不进行综合，也不绕过 Cowork 模式。 |
+| 11 | **研究包**审计汇总现有的研究结果。它不创造新的事实，也不隐藏部分级别的证据。 |
+| 12 | 发现阶段提出线索；只有获取阶段才能产生证据。 |
+| 13 | 只有当经过测试证明其能够准确回忆时，审查者才会被信任。 |
+| 14 | 论点的数量并不能代表研究的质量。在进行综合之前，必须对论点进行筛选。 |
+| 15 | 冻结锁定已完成的研究结果。它不完成未完成的研究，也不将修复状态转化为证据。 |
+| 16 | 豁免可以放宽对原始数据的限制，但不能制造证据。 |
+
+**第 3 条原则**：大型语言模型（LLM）绝不能生成证据文本。`research-os` 构建了一个确定性的摘录日志（具有稳定 ID，例如 `ex_<source_id_hex>_001`）；大型语言模型选择摘录 ID；`research-os` 复制原始文本。 “释义作为引用”的错误类型在结构上是无法实现的。
+
+**第 14 条原则**：在提取和审查之间，`research-os claim triage`（论点筛选）会去重、限制每个来源的贡献，并将低价值的候选论点放入待处理队列。 论点筛选不会修改 `claims.jsonl` 文件；待处理的论点仍然保留在原始日志中。
+
+## v0.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
+```
+
+每个步骤都是一个命令行指令。每个步骤都会写入只追加的记录。没有哪个步骤会合成、解决或创建新的事实——这些不变性是被强制执行的，而不是被信任的。审查环节会接受、拒绝或要求修复候选声明；“gate”会根据审查结果计算“synthesis_eligible”（合成资格）。“freeze”（冻结）是最终的完整性锁，只有当所有层都同意时，才会标记一个包为完成。请参阅[docs/dogfood-proof.md](docs/dogfood-proof.md)，了解v0.1版本的证明，该证明表明整个流程是端到端的。
+
+这是一种替代 *搜索 → 摘要 → 精美报告* 的结构化方法。这个流程是最终产品。
+
+## 安装
+
+**要求：** 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
+```
+
+## 快速开始
+
+```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
+```
+
+**要查看一个实际的示例，**请查看 `research-os-packs/research-os-spec/` 目录下的“dogfood”包——每个记录、每个凭证、每个处理结果、每个冻结指纹，都存储在只追加的日志文件中。该包生成了 `docs/dogfood-proof.md`。
+
+**需要本地运行 [ollama-intern-mcp](https://github.com/mcp-tool-shop-org/ollama-intern-mcp)**，用于LLM提取、分诊、审查和发现。默认模型是 `hermes3:8b`；可以使用 `OLLAMA_INTERN_MODEL=<模型>` 来覆盖。如果Ollama没有安装在默认的 `localhost:11434` 上，请设置 `OLLAMA_HOST`。
+
+## 词汇表
+
+| 术语 | 含义 |
+|------|---------|
+| `research-os` | 控制平面 / 命令行 / 闸门 / 编排规则 (此仓库) |
+| `research-pack` | 用于一个研究项目的生成的仓库记录 |
+| `research section` | 在某个包内部的有限的调查单元 |
+| `research receipt` | 证明某个部分通过了源/声明/闸门检查 |
+
+## 安全性
+
+`research-os` 是一个本地优先的命令行工具。它在您指定的 research-pack 目录下读取和写入文件，并在使用 `gather` 命令时，会向您提供的源 URL 发送 HTTP 请求。它不会：运行服务器、接受入站连接、存储凭据或发送遥测数据。任何敏感信息都不会写入到包的记录中。请参阅 [SECURITY.md](SECURITY.md)，了解漏洞报告政策。
+
+## 状态
+
+**v0.1.0** — 冻结于 2026-05-08。`research-os-packs/research-os-spec/` (兄弟仓库) 中的“dogfood”包已完成冻结，共接受了 8 个部分中的 296 个声明，17 个已处理，30 个被操作员覆盖，0 个活动修复阻塞，0 个未解决的矛盾，所有闸门 `synthesis_eligible=true`。463/463 个 vitest 测试通过。共有 16 条关键规则。请参阅 [`docs/dogfood-proof.md`](docs/dogfood-proof.md)，了解 7 个发现和冻结凭证指纹。
+
+### v0.1 的局限性
+
+- 尚未经过外部用户的严格测试。在一次内部测试中发现了 7 个 bug。
+- 尚未发布到 npm。在 `npm publish` 之前，请从源代码安装。
+- 不是一个合成器。`synth workspace` 命令会生成结构化的工作区；人类（或 Cowork）会根据已接受的声明 ID 编写文本内容。
+- 在语义版本控制下，API 稳定性尚未确定。v1.0.0 版本将在外部用户验证了该接口之后发布。
+
+### 已知限制
+
+- **提取器的来源信息在网关接缝处不可见。** 在校准后的提取器（配置了模型的 Ollama）不可用时，某些部分可能会通过“可接受声明”的阈值，但这依赖于启发式方法的备用方案。这被记录为已知的弱点；未来的改进将报告提取器提供的“可接受声明”数量，并要求校准路径必须达到阈值所需的“可接受声明”数量。
+- **关于超出校准的 `hermes-two-pass` 基准线的评审模型选择问题尚未解决。** 内部测试验证了一种评审模型配置；其他模型需要在被信任之前，进行独立的、基于预设失败情况的校准。
+- **内部测试使用的提取模型是 `mistral-nemo:12b`（默认配置是 `hermes3:8b`）。** 在发现过程中，系统会产生与当前主题不相关的错误结果，针对自指部分名称的问题，通过查询精度控制（参见手册）以及操作员预先设置的 URL 来进行修正，以解决模糊主题的问题。
+
+## 许可证
+
+MIT

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security issue in `research-os`, please report it privately:
+
+- **GitHub Security Advisory:** Open a private advisory on the repository (preferred).
+- **Email:** 64996768+mcp-tool-shop@users.noreply.github.com
+
+Do not file a public issue for security reports.
+
+**Response timeline:** We aim to acknowledge reports within 72 hours and provide a resolution timeline within 7 days.
+
+## Scope
+
+`research-os` is a local-first CLI that operates on the user's filesystem and (when configured) issues outbound network requests to fetch sources. It does not run a server, accept inbound connections, or store credentials.
+
+Reports about the following are in scope:
+
+- Path-traversal in pack scaffolding or template rendering
+- Schema validation bypasses that allow malformed packs
+- Issues in source-fetching adapters that could leak local data
+- Supply-chain risks in published artifacts
+
+## Supported Versions
+
+Until v1.0.0, only the latest release is supported.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node