Research Harness

One distributable template repository that a user clones (or instantiates with Copier) to get a complete, self-contained research harness: the orchestration engine, the methodology skills, the workflows, the contracts, the knowledge graph, multi-topic support, and the research→blog and research→book output pipelines — all in one package.

Important

This is not a chatbot "deep research" button. It is a falsified deep exploration and a persistent knowledge graph — not a one-shot answer. It deliberately exchanges tokens for adversarial falsification (every finding survives a falsification gate or is recorded as disproven), extreme depth of detail, and reusable, typed research results that accrete into an ever-expanding knowledge tree. Expect higher token cost and longer runs than a conversational summary; what you get back is a durable, citable, MIF-native corpus you can build on, not a transient reply.

And be clear-eyed about what's underneath: this is an AI tool. It doesn't just can make mistakes — it will make mistakes. That is precisely why the rigor is here: schemas, the ontology spine, MIF conformance, and an adversarial falsification gate exist to catch, type-check, and disprove what the model gets wrong, so what survives is something you can actually trust.

New here? Reading the research explains what a research topic produces, how to navigate it, how to read a report, and what each report genre is for — the fastest way to understand the value.

Status

This template is evolving and should not be considered stable. Interfaces, schemas and pack contracts may change between releases.

It is also a primary tool in the author's daily workflow, and it is maintained with corresponding care. Changes will favor backward compatibility, and every reasonable effort will go toward minimizing disruption for existing clones. Breaking changes will be recorded in CHANGELOG.md and reflected in the version.

Layout

The repository has four layers, all present on clone (design spec §5):

1. Engine — .claude/agents/ orchestrator + dimension-analyst + falsification-analyst + source-chunker + report-synthesizer + harness-configurator + corpus-synthesizer, and the .claude/commands/ that delegate to them. .mcp.json also wires an optional mif-rh MCP server over this same engine.
2. Contracts — schemas/: the MIF-backed findings schema, the harness.config.json manifest schema, the pack contract, and the Structured Data Protocol.
3. Harness services — multi-topic registry, knowledge graph, search, discovery, reindex — operating directly on the MIF substrate.
4. Outputs — the generic report channel is the canonical MIF Level-3 source of truth (reports/<topic>/<slug>.md); blog is the first-class published projection; book, other channels, and all deliverable genres arrive as optional plugins — one per skill under packs/<family>/<skill>/, enabled selectively (see docs/explanation/pack-structure.md). All information in and out of the harness is MIF (see docs/explanation/mif-io-conformance.md). Findings are typed against per-topic ontologies (an always-on generic core plus optional domain ontology packs), enforced deterministically — see docs/explanation/ontology-conformance.md. Those types compose into a unified, fail-closed cross-topic concordance (the ontological spine) — see docs/explanation/ontological-spine.md.

Cross-cutting: bundled enforcement hooks (.claude/hooks/), bundled docs (docs/, Diataxis), and evals/.

The one file you edit

harness.config.json is the deploy contract: it declares your topics, research dimensions, output targets, which packs are enabled, and the site projection. It is validated by harness.config.schema.json.

Reading your reports

The bundled Astro/Starlight site renders reports/ (and the Diátaxis docs/) for human reading — npm install && npm run dev. A clone is activated reports-primary at instantiation; flip the leading surface or toggle optional site plugins with scripts/site-toggle.sh (or ask /configure). See How to configure the reports site.

Quality gate

bash scripts/verify.sh runs the full build gate (schema validation, the citation-integrity gate, and each milestone's acceptance gate). markdownlint-cli2 "**/*.md" must report zero errors. Both run in CI on every push and pull request. Toolchain: jq and yq (the YAML analog of jq, used by the MIF report projector), ajv-cli + ajv-formats, copier for the distribution gate, and mif-rh-cli (the compiled ontology engine, installed by scripts/fetch-engine.sh; its ontology-resolution gates delegate to it, ADR-0016). Document-shaped deliverables (frontmatter, MIF conformance, provenance) are authored and validated through mif-docs-plugin — see Reference: dependencies and requirements.

Supply-chain verification

Every dependency or tool the harness downloads is cryptographically verified, via a waterfall: prefer a GitHub build-provenance attestation (gh attestation verify); when upstream publishes none, relax to the minimum — a pinned version plus a SHA-256 cross-checked against the upstream signed checksums. A verification miss fails the build; nothing installs unverified. Package-manager installs (npm, pip/pipx) are integrity-verified against the registry by the manager itself. The raw yq binary is downloaded with this waterfall in .github/workflows/ci.yml (yq publishes no attestation, so it lands on the pinned-SHA-256 floor).

Documentation

See docs/ for the merged Diataxis set: tutorials, how-to guides, reference, and explanation. The org's shared governance, CI, and release runbooks (release, branch-protection, Dependabot auto-merge, labels) are cross-linked from org governance & release runbooks.