rebuild-dossier

# rebuild-dossier

[![DOI](https://zenodo.org/badge/1308271634.svg)](https://doi.org/10.5281/zenodo.22036801)
[![arXiv:2608.23616](https://img.shields.io/badge/arXiv-2608.23616-b31b1b.svg)](https://arxiv.org/abs/2608.23616)
[![smithery badge](https://smithery.ai/badge/parkerscottfawcett/rebuild-dossier)](https://smithery.ai/servers/parkerscottfawcett/rebuild-dossier)
[![M8ven Score](https://m8ven.ai/badge/mcp/businessfawcett-cloud-rebuild-dossier-17tqsh)](https://m8ven.ai/mcp/businessfawcett-cloud-rebuild-dossier-17tqsh)
[![CI](https://github.com/Parker-Fawcett/rebuild-dossier/actions/workflows/ci.yml/badge.svg)](https://github.com/Parker-Fawcett/rebuild-dossier/actions/workflows/ci.yml)

An MCP server that reverse-engineers a trustworthy **rebuild spec** — a locked `CLAUDE.md`,
`.claude/` config, and a mutation-tested test suite — out of an existing app, so any coding
agent can rebuild it cleanly against that spec instead of guessing.

**It does not rebuild the app.** It produces the spec, contracts, and tests a coding agent
consumes to do that separately. This boundary is deliberate — see [Why](#why) below.

> **Status: v0.** The core loop works and has been validated end-to-end against one real,
> messy repo, including two independent fresh-agent handoffs on two model tiers. Read
> [docs/v0-findings.md](docs/v0-findings.md) for the honest result, including what broke.

## Why

Prior research ([AgentModernize, arXiv:2605.17535](https://arxiv.org/abs/2605.17535)) found
that a rebuild pipeline scores **0%** behavioral equivalence with no verified feedback loop,
and only **9–19%** with a coarse one. The bet behind this tool: locking interface contracts
*before* running tests, plus a strict one-test-at-a-time retry loop instead of batch
regeneration, does meaningfully better.

The riskiest part of any such pipeline is silently validating a bug as intentional — four
sources of evidence can quietly agree on the same mistake with nobody ever having said why.
So the single non-negotiable rule in this tool: **auto-resolving an ambiguity requires both
signal agreement *and* an affirmative signal that someone actually decided** (a stated
comment, a TODO admitting a bug, or a direct human answer). Silent agreement alone — code and
observed behavior simply matching, with no one ever having said why — always becomes a
question, never an auto-resolution, no matter how high the apparent confidence.

## How it works

Six MCP tools, run from inside a normal Claude Code (or any MCP-compatible) session:

| Tool | What it does |
|---|---|
| `ingest_repo(path)` | Static analysis only, no LLM call: routes, `package.json`, build config (via AST, never executed), existing tests, and structural-smell detectors (e.g. a client-side-only credential check with no server-side verification) that surface real ambiguity even when nobody ever commented on it. |
| `crawl_site(url)` | Headless Playwright crawl of reachable routes, with progress notifications so long crawls don't get killed as unresponsive. |
| `flag_known_bug(description)` | Free text, stored verbatim. Always overrides auto-resolve for anything it matches — the cheapest, most authoritative signal in the system. |
| `get_case_queue()` / `resolve_case(id, decision)` | The ambiguity queue. Surfaces open questions via MCP elicitation when the client supports it; `resolve_case` is always available as a scripted fallback. |
| `generate_spec()` | Only callable once the case queue is empty. Writes `CLAUDE.md`, `.claude/rules/`, `.claude/settings.json` (hooks that *mechanically* enforce the discipline — see below), `spec/contracts/*.md`, `tests/visible/` + `tests/held-out/`, and `kickoff-prompt.txt` to a clean sibling `<repo>-rebuild/` directory — never into the original repo. Runs a real mutation check before finalizing tests: deliberately breaks the original code and confirms each generated test actually catches it, downgrading any that don't. |

`crawl_site` needs Chromium (`npx playwright install chromium`, below) — it isn't bundled with the server, including when installed via Smithery, so run it once first or the tool will fail.

### Rails that are mechanically enforced, not just written down

A comparison run across two model tiers found that a weaker model will happily read
`CLAUDE.md`, understand "only build what's currently failing, don't batch-regenerate," and
then quietly violate it anyway — because nothing *checked* it. Two rules in this tool are now
enforced by real hooks, not prose, for exactly that reason:

- **`spec/` is locked.** A `PreToolUse` hook blocks any edit under `spec/`.
- **Contracts without tests don't get built ahead of schedule.** `generate_spec` writes
  `spec/untested-contracts.json` (every route/contract with no covering test), and a second
  `PreToolUse` hook blocks writes to anything on that list — the same enforcement shape as the
  `spec/`-edit block, closing a gap that used to be advisory only.

A `PostToolUse` hook runs the visible test suite after every edit.

![rebuild-dossier demo](demo.gif)

## Quick start

Available on npm:

```bash
npx rebuild-dossier@latest --help    # pull the MCP server (stdio), or:
npm install -g rebuild-dossier        # install the CLI globally
```

`crawl_site` needs Chromium — run once so the server can drive headless Playwright:

```bash
npx playwright install chromium
```

Requires **Node 20.12+** (set in `package.json` `engines`). To run from source instead, clone the
repo, `npm install`, and use `npm start`.

Add it as an MCP server in Claude Code (or any MCP-compatible client), then in a session:

```
ingest_repo({ path: "/path/to/some-app" })
get_case_queue({ repoPath: "/path/to/some-app", interactive: true })
# ...resolve whatever the queue surfaces...
generate_spec({ repoPath: "/path/to/some-app" })
```

This writes a clean `some-app-rebuild/` sibling directory. `cd` into it, start a **fresh**
Claude Code session (nothing else should be in scope), and paste the contents of its
`kickoff-prompt.txt`.

## Operating guide

The full lifecycle, in order — each step's actual behavior, not just the call signature.

### 1. Ingest the repo

```
ingest_repo({ path: "/absolute/path/to/some-app" })
```

Static analysis only — no LLM call, nothing executed. Parses `package.json`, route files
(Express and Next.js App Router today — see [scope](#current-scope-and-whats-deliberately-not-built-yet)),
build config (Tailwind/Vite/Next, via AST, never executed), existing tests, and scans for
comment/TODO signals plus structural smells (e.g. a hardcoded client-side credential check with
no server-side verification — the kind of thing nobody ever comments on, which is exactly why
it needs its own detector rather than relying on comments existing). Everything lands in
`<repo>/.dossier/` — this tool's own scratch state, inside the *original* repo, never shared or
uploaded anywhere. You'll get back a summary:

```json
{
  "routes": 8,
  "existingTests": 0,
  "signals": 3,
  "buildConfig": ["tailwind", "next"],
  "openCases": 3,
  "savedTo": "/absolute/path/to/some-app/.dossier/evidence.json"
}
```

`openCases` here already reflects reconciliation — comment/TODO signals and structural smells
that didn't auto-resolve become case-queue entries automatically.

If `routes` comes back `0`, check for a `monorepoHint` field before assuming the app has none —
`ingest_repo` needs to be pointed at the actual app directory, not a monorepo's root wrapper
(a `package.json` with `apps/*`/`packages/*` next to it, common with Turborepo/Nx/workspace
layouts, including ones that never actually declare a `workspaces` field). The hint lists real
candidate directories found under `apps/`/`packages/` so you don't have to hunt for the real app
yourself — re-run `ingest_repo` pointed at one of those instead.

If your client supports MCP elicitation, you can skip the manual re-run entirely: pass
`interactive: true` and, when a monorepo root with candidates is detected, `ingest_repo` asks
which one is the real app and ingests it directly — it never silently guesses on its own, the
same way `get_case_queue`'s interactive mode always asks rather than resolving anything without
you. Declining, an unsupported client, or an answer that isn't one of the real candidates all
fall back to the plain hint above, unchanged.

### 2. (Optional) Crawl the live site

```
crawl_site({ url: "http://localhost:3000", repoPath: "/absolute/path/to/some-app" })
```

Only useful if the app is actually running somewhere. Headless Playwright crawl of reachable
routes, emitting progress notifications periodically — long crawls get auto-backgrounded by
most MCP clients, and a silent multi-minute call risks being killed as unresponsive without them.

### 3. (Optional, but do this before step 4) Flag anything you already know is broken

```
flag_known_bug({
  repoPath: "/absolute/path/to/some-app",
  description: "The login gate secret check runs entirely client-side and is bypassable"
})
```

The cheapest, most authoritative signal in the whole system — a direct human statement always
outranks inference. It overrides auto-resolve for anything it matches, *even if* every other
signal quietly agrees the behavior looks intentional. Do this before resolving the queue, since
it changes what shows up there (and can seed a case entirely on its own, with zero other
evidence — see [docs/v0-findings.md](docs/v0-findings.md) for why that matters).

Matching is plain token overlap against each open case's file path and claim text, not fuzzy or
semantic — so one bug description can match (and auto-resolve) more open cases than you intended
if your codebase has several similarly-named components. In the validated example, one bug about
"the login gate" matched and closed all three of Madeline's near-duplicate gate components in a
single call, before any of them were reviewed individually. `resolve_case` overwrites a case's
decision regardless of its current status, so if that's not what you meant, call