research-md 0.2.0__tar.gz

research_md-0.2.0/.forge/manifest.yaml

@@ -0,0 +1,51 @@
+# .forge/manifest.yaml — research.md
+# The decision forge — evidence-graded, phase-gated, peer-reviewed decisions
+# Generated by /forge-manifest-init on 2026-03-22
+
+manifest_version: 1
+
+repo:
+  visibility: public
+  org: eidos-agi
+  topics: [mcp, research, decisions, evidence, agent-tools]
+
+packaging:
+  build_system: hatchling
+  pypi:
+    name: research-md
+    publish: true
+    trusted_publisher:
+      owner: eidos-agi
+      repo: research.md
+      workflow: publish.yml
+      environment: pypi
+  readme:
+    absolute_images: true
+
+quality:
+  required_files:
+    - LICENSE
+    - README.md
+    - CHANGELOG.md
+    - CONTRIBUTING.md
+    - SECURITY.md
+  min_grade:
+    foss_check: B
+    ship_check: pass
+    sec_audit: clean
+
+security:
+  secret_scanning: true
+  dependency_audit: true
+
+dependencies:
+  max_count: 3
+
+ci:
+  workflows:
+    ci: true
+    publish: true
+  permissions:
+    contents_read: true
+  pre_commit: true
+  build_verification: true

research_md-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Lint
+        run: |
+          pip install ruff
+          ruff check research_md/
+          ruff format --check research_md/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run fixture verification
+        run: python refactor/verify-fixtures.py || true
+      - name: Run tests
+        run: pytest tests/ -v || echo "No pytest tests yet"
+
+  build-verify:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          pip install build twine
+          python -m build
+      - name: Verify metadata
+        run: twine check dist/*
+      - name: Verify wheel installs
+        run: |
+          python -m venv /tmp/test-venv
+          /tmp/test-venv/bin/pip install dist/*.whl
+          /tmp/test-venv/bin/python -c "import research_md; print(research_md.__version__)"

research_md-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

research_md-0.2.0/.gitignore

@@ -0,0 +1,37 @@
+# Node (TypeScript original)
+node_modules/
+dist/
+*.js.map
+*.tsbuildinfo
+
+# Python (new primary)
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+*.egg
+*.whl
+
+.venv/
+venv/
+env/
+.env
+.env.local
+
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+.DS_Store
+Thumbs.db
+
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+.mcp.json

research_md-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+      - id: detect-private-key
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        args: [--skip, "*.lock,*.cast"]

research_md-0.2.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release

research_md-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to research-md
+
+Thanks for your interest in contributing.
+
+## Quick start
+
+```bash
+git clone https://github.com/eidos-agi/research.md.git
+cd research.md
+pip install -e ".[dev]"
+```
+
+## Development
+
+We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting:
+
+```bash
+ruff check .
+ruff format .
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+## For agent developers
+
+If you're building tools that AI agents will use, pay special attention to:
+
+1. **Tool descriptions** — Every `@tool` decorator must have a description that explains *when* to use it, not just *what* it does. An agent choosing between 20 tools needs clear differentiation.
+2. **Parameter descriptions** — Every parameter needs a `description` field. Agents don't have UI tooltips — the description is all they get.
+3. **Error messages** — When something fails, the error message must tell the agent what to do next. "Invalid input" is useless. "Expected ISO 8601 date string (e.g., 2026-03-22), got: 'yesterday'" is actionable.
+4. **Typed everything** — Type hints on all public functions. Agents parse types to understand contracts.
+
+## Pull requests
+
+- Keep PRs focused — one feature or fix per PR
+- Include tests for new functionality
+- Update CHANGELOG.md with your changes
+- Ensure `ruff check .` and `pytest` pass
+
+## Reporting issues
+
+Open an issue with:
+
+1. What you were trying to do
+2. What happened instead
+3. Steps to reproduce

research_md-0.2.0/DESIGN.md

@@ -0,0 +1,152 @@
+# Design: research.md
+
+## The Problem
+
+AI agents skip process when they're under time pressure or context is long. Advisory rules in markdown — "lock criteria before scoring," "do peer review first" — are ignored the moment they're inconvenient. The agent has good intentions but no guardrails.
+
+This is true for two categories of mistakes:
+
+1. **Process shortcuts** — scoring without peer review, accepting decisions without documenting alternatives
+2. **Wrong-target writes** — operating on the wrong research project because the agent guessed from its working directory
+
+Both categories share a root cause: the tooling trusts the agent to do the right thing. research.md doesn't.
+
+## Two Layers of Enforcement
+
+### Layer 1: Process Gates
+
+Certain research operations have prerequisites. research.md encodes these as hard failures:
+
+| Gate | Tool | Prerequisite |
+|------|------|-------------|
+| Criteria must be locked before scoring | `candidate_score` | `criteria_lock` must have been called |
+| Peer review must exist before scoring | `candidate_score` | `peer_review_log` must have been called |
+| No unresolved claims before scoring | `candidate_score` | All `_TBD_` items must be resolved Y/N |
+
+These aren't warnings. The tool returns an error with `isError: true`. The agent cannot proceed. The error message tells it exactly what's missing and which tool to call.
+
+The gates exist because research quality degrades silently. An unreviewed scoring matrix looks identical to a reviewed one. A score assigned before criteria were locked might have been anchored to a preferred candidate. The output looks fine. The process was wrong. By the time anyone notices, the decision is made.
+
+### Layer 2: GUID-Based Project Targeting
+
+Every research project gets a UUID at initialization:
+
+```json
+{
+  "id": "959b9b96-7f18-4ccb-8e22-76ab54301086",
+  "version": "0.1.0",
+  "projectName": "secrets-manager",
+  "created": "2026-03-18"
+}
+```
+
+Every tool call requires this GUID as `research_id`. No GUID, no operation.
+
+This solves a problem that most MCP servers ignore: **how does the server know which project the agent is talking about?**
+
+The common answer is working directory detection — walk up the filesystem looking for a config file, infer the project from `cwd`. This is fragile:
+
+- The agent doesn't control its own `cwd`. That's set by how the user launched their editor.
+- Moving a terminal tab, opening a second workspace, or renaming a folder silently changes which project the server operates on.
+- In a multi-project research repo, `cwd` is ambiguous — are you in the root or a subproject?
+- Detection failures are silent. The server finds the wrong config and writes to the wrong project. Nothing errors. The agent doesn't know.
+
+research.md rejects detection entirely. The agent must:
+
+1. **Call `project_set`** with an explicit path to register the project
+2. **Read the config file** to discover the GUID
+3. **Pass the GUID on every tool call**
+
+If the GUID is missing, the tool fails with:
+
+> Missing required parameter: research_id. Read the project's research-md.json file to find the 'id' field (a UUID). If the project hasn't been registered this session, call `project_set` with its path first.
+
+If the GUID is wrong or unregistered:
+
+> Unknown research_id '...'. This project hasn't been registered in this session. Call `project_set` with the project's path to register it.
+
+The error messages are instructional. They don't just say "failed" — they tell the agent exactly what to do next.
+
+## Why a GUID Instead of a Path
+
+A path would work mechanically. But a GUID forces the agent to read the config file before operating. This is the intentionality gate:
+
+- **Path**: the agent can construct it from convention (`/home/dev/repos/research/secrets-manager`). It might be right. It might be stale.
+- **GUID**: the agent must open `research-md.json` and extract the `id` field. This guarantees it has seen the current state of the project config before writing to it.
+
+The extra friction is the point. Making the agent work to obtain the targeting key ensures it knows exactly which project it's about to modify. Wrong-project writes become structurally impossible rather than merely unlikely.
+
+## Multi-Project, Multi-Window, No Singletons
+
+The GUID-to-path mapping lives in process memory, not on disk. Each Claude Code window spawns its own MCP server process. Each process maintains its own independent map.
+
+- Window 1 registers `secrets-manager` (GUID A) → operates on secrets-manager
+- Window 2 registers `cost-accounting` (GUID B) → operates on cost-accounting
+- Neither blocks the other. No shared state. No lock contention.
+
+A single session can also register multiple projects simultaneously:
+
+```
+project_set /home/dev/repos/research  → registers root + all subprojects
+```
+
+The root GUID is registered but can't be used directly for data operations — it points to a container, not a project. The agent must use a subproject's GUID. If it tries the root GUID on `finding_create`, it gets:
+
+> research_id '...' points to a multi-project root, not a specific project. Use the research_id of one of its subprojects: secrets-manager, cost-accounting.
+
+## Project Structure
+
+research.md supports standalone projects and multi-project roots:
+
+```
+# Standalone
+my-research/
+├── research-md.json    ← { id: "...", projectName: "my-research" }
+├── findings/
+├── candidates/
+└── evaluations/
+
+# Multi-project root
+research/
+├── research-md.json    ← { id: "...", projects: ["secrets-manager", "cost-accounting"] }
+├── secrets-manager/
+│   ├── research-md.json  ← { id: "...", projectName: "secrets-manager" }
+│   ├── findings/
+│   ├── candidates/
+│   └── evaluations/
+└── cost-accounting/
+    ├── research-md.json  ← { id: "...", projectName: "cost-accounting" }
+    └── ...
+```
+
+Each subproject is fully self-contained. Extract it to its own repo and it works standalone — it has its own config, its own GUID, its own folder structure. The root config is just a convenience for grouping related research.
+
+## Comparison to Backlog.md
+
+research.md is modeled on [Backlog.md](https://github.com/MrLesk/Backlog.md), the task management MCP. The structural patterns are aligned:
+
+| Pattern | Backlog.md | research.md |
+|---------|-----------|-------------|
+| Transport | stdio | stdio |
+| CLI structure | `backlog init` / `backlog mcp start` | `research-md init` / `research-md mcp start` |
+| Tool naming | `task_create`, `task_list` | `finding_create`, `candidate_list` |
+| Schema enforcement | `additionalProperties: false` | `additionalProperties: false` |
+| Error hierarchy | `McpError` → subtypes | `ResearchError` → subtypes |
+
+The key divergence is project targeting:
+
+| | Backlog.md | research.md |
+|--|-----------|-------------|
+| Project detection | `cwd` + `BACKLOG_CWD` env var | None — explicit GUID |
+| Multi-project | Not supported | Root + subprojects |
+| Concurrency | One project per process | Multiple projects per process |
+| Wrong-target protection | None (trusts cwd) | GUID mismatch = hard fail |
+
+## Summary
+
+research.md enforces two things:
+
+1. **You can't skip process.** The gates are in the code, not in a conventions doc.
+2. **You can't hit the wrong target.** The GUID is a targeting lock that requires intentional acquisition.
+
+Both follow the same principle: make the right thing automatic and the wrong thing impossible. Advisory rules get skipped. Tooling doesn't.

research_md-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Shanklin
+
+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.

research_md-0.2.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: research-md
+Version: 0.2.0
+Summary: The decision forge — evidence-graded, phase-gated, peer-reviewed decisions
+Project-URL: Homepage, https://github.com/eidos-agi/research.md
+Project-URL: Repository, https://github.com/eidos-agi/research.md
+Author-email: Daniel Shanklin <daniel@eidosagi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-tools,decisions,evidence,mcp,research
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# research.md
+
+MCP server for structured research workflows. Enforces process gates in code so agents cannot skip findings, peer review, or criteria locking under time pressure.
+
+## What it enforces
+
+| Gate | Trigger |
+|------|---------|
+| Criteria locked before scoring | `candidate_score` fails if `decision-criteria.md` not locked |
+| No TBD on scored candidates | `candidate_score` fails if candidate has `_TBD_` claims |
+| Peer review before scoring | `candidate_score` fails if no `evaluations/peer-review.md` |
+
+## Install
+
+Not yet published to npm. Install from local path.
+
+```bash
+npm install
+npm run build
+```
+
+Add to `.mcp.json` (use `node` with the local path, not `npx`):
+
+```json
+{
+  "mcpServers": {
+    "research-md": {
+      "command": "node",
+      "args": ["/absolute/path/to/research.md/dist/index.js"]
+    }
+  }
+}
+```
+
+Or for Claude Code:
+
+```bash
+claude mcp add research-md --scope user -- node /absolute/path/to/research.md/dist/index.js
+```
+
+## Trilogy conventions
+
+research.md follows shared conventions with ike.md and visionlog.md. See [CONVENTIONS.md](https://github.com/eidos-agi/ike.md/blob/main/CONVENTIONS.md) for the full standard: dot-dirs, git commitment, GUID routing, monorepo patterns.
+
+- Config lives at `.research/research.json` (committed to git)
+- Tools: `project_init` (new project) and `project_set` (register existing for session)
+
+## Targeting pattern: project_set + research_id
+
+Every tool call requires a `research_id` -- the GUID from the project's `.research/research.json`. This is an in-memory mapping that does not persist across MCP server restarts.
+
+**Session startup:**
+
+1. Call `project_set` with the project's absolute path
+2. It returns the project's `research_id` (a UUID)
+3. Pass that `research_id` on every subsequent tool call
+
+If you call a tool without a valid `research_id`, the server tells you exactly how to fix it.
+
+## Project structure
+
+### Single project
+
+```
+my-research/
+  .research/
+    research.json              <- config with project GUID (commit this)
+    findings/                  <- NNNN-slug.md
+    candidates/                <- slug.md
+    evaluations/
+      decision-criteria.md     <- criteria table (lock before scoring)
+      peer-review.md           <- reviewer log (required before scoring)
+      scoring-matrix.md        <- generated from locked criteria + candidates
+```
+
+### Multi-project root
+
+A root directory holds multiple research projects. Each subproject is a full project with its own GUID.
+
+```
+research-root/
+  .research/
+    research.json              <- root config (lists subprojects)
+  vendor-selection/
+    .research/
+      research.json            <- subproject GUID
+      findings/
+      candidates/
+      evaluations/
+  platform-comparison/
+    .research/
+      research.json            <- subproject GUID
+      findings/
+      candidates/
+      evaluations/
+```
+
+Initialize a root and add subprojects:
+
+```
+project_init { path: "/path/to/root", root: true }
+project_init { path: "/path/to/root", subproject: "vendor-selection" }
+project_init { path: "/path/to/root", subproject: "platform-comparison" }
+```
+
+When you `project_set` a root, all subprojects are registered automatically. Use each subproject's `research_id` for tool calls -- you cannot operate on the root directly.
+
+## Tools (16)
+
+### Session
+
+| Tool | Description |
+|------|-------------|
+| `project_set` | Register a project path, returns its GUID. Also registers subprojects if root. |
+| `project_get` | List all registered projects and their GUIDs for this session. |
+
+### Project
+
+| Tool | Description |
+|------|-------------|
+| `init` | Initialize project structure (single, root, or subproject). |
+| `status` | Project health: criteria locked, peer review done, TBD count, finding/candidate totals. |
+
+### Findings
+
+| Tool | Description |
+|------|-------------|
+| `finding_create` | Create finding with evidence grade and source. |
+| `finding_list` | List all findings with status and evidence grade. |
+| `finding_update` | Update status, evidence grade, or claim text. |
+
+### Candidates
+
+| Tool | Description |
+|------|-------------|
+| `candidate_create` | Create candidate for evaluation. |
+| `candidate_list` | List all candidates with verdict status. |
+| `candidate_update` | Update verdict (provisional/recommended/eliminated) or description. |
+| `candidate_add_claim` | Add binary testable claim to validation checklist. |
+| `candidate_resolve_claim` | Mark a claim Y or N (clears `_TBD_`). |
+
+### Scoring
+
+| Tool | Description |
+|------|-------------|
+| `criteria_lock` | Lock decision criteria weights. Required before scoring. |
+| `candidate_score` | Score a candidate against locked criteria. Gated on criteria lock + peer review + no TBD. |
+| `scoring_matrix_generate` | Generate `evaluations/scoring-matrix.md` comparison table. |
+
+### Peer Review
+
+| Tool | Description |
+|------|-------------|
+| `peer_review_log` | Log reviewer name and findings. Required before scoring. |
+
+## Evidence grades
+
+| Grade | Meaning |
+|-------|---------|
+| `HIGH` | Peer-reviewed, primary source, reproducible |
+| `MODERATE` | Secondary source, credible but not independently verified |
+| `LOW` | Anecdotal, single source, unverified claim |
+| `UNVERIFIED` | Not yet assessed |
+
+## Resources
+
+```
+research://workflow/overview   -> workflow guide (auto-loaded into agent context)
+research://findings/all        -> all findings as markdown
+research://candidates/all      -> all candidates with verdict
+research://scoring-matrix      -> current scoring matrix
+research://status              -> project health summary
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev
+```