Rebuild Dossier

rebuild-dossier

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 below.

Validated against a real app. The core loop (ingest, resolve cases, generate spec) has been tested end-to-end against a real, messy repo with two independent fresh-agent handoffs on two model tiers, plus a mutation-tested test suite. docs/v0-findings.md covers what worked, what broke, and what's still open.

Quick start

Available on npm:

npx rebuild-dossier@latest --help    # pulls and verifies the package, or:
npm install -g rebuild-dossier        # install the CLI globally

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

Then add it as an MCP server. In Claude Code, from the project you want to rebuild:

claude mcp add rebuild-dossier -- npx -y rebuild-dossier@latest

(or add this to your ~/.claude.json / project .mcp.json):

{
  "mcpServers": {
    "rebuild-dossier": {
      "command": "npx",
      "args": ["-y", "rebuild-dossier@latest"]
    }
  }
}

Then in a session. The first call, ingest_repo, runs instantly with zero setup: static analysis only, no browser, no Chromium, no LLM call. Run it on any app to confirm the server is alive before committing to the full workflow:

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.

If this looks useful, a star helps other developers find it.

Why

Prior research (AgentModernize, arXiv: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:

crawl_site needs Chromium (npx playwright install chromium, step 2 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. Writes under spec/ are blocked.
• 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 writes to anything on that list are blocked.

Both rules live in one generated guard script, .claude/hooks/rebuild-guard.mjs, run as a PreToolUse hook on Edit, Write, MultiEdit, NotebookEdit, and Bash. It resolves symlinks, .. segments and (on macOS/Windows) letter case before matching, parses write-shaped shell commands (redirects, heredocs, tee, sed -i, rm/mv/cp, git write subcommands, interpreter one-liners that write), locks its own script and settings.json, and fails closed if its input, the blocklist, or the script itself is missing or unreadable. Known limit: shell parsing is heuristic, so a write routed through a script the agent wrote earlier is not seen. (Releases before 0.2.10 shipped an untested-contracts hook that crashed under the shell and never blocked anything; upgrade.)

A PostToolUse hook runs the visible test suite after every edit and records a heartbeat in .claude/.hook-heartbeat.json, so you can check afterward that the hooks were actually live.

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), 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:

{
  "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.

This step is the only one that needs a browser. crawl_site drives headless Chromium, which isn't bundled with the server (including via Smithery), so run npx playwright install chromium once first or the tool will fail. Skip it and the rest of the workflow still works. ingest_repo, resolve_case, and generate_spec need no browser at all.

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 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 it directly on the ones it swept up too broadly — don't assume every case it touched was actually the same decision.

4. Resolve the case queue

get_case_queue({ repoPath: "/absolute/path/to/some-app", interactive: true })

interactive: true walks each open case via MCP elicitation — a real interactive prompt in your client, showing the evidence side by side, if your client supports it. If not (or you're scripting this), resolve cases one at a time instead:

resolve_case({ repoPath: "/absolute/path/to/some-app", id: "case:...", decision: "intentional", note: "..." })

This step doesn't have a shortcut. generate_spec refuses to run while any case is still open, by design — there's no partial or in-progress spec to hand a rebuild agent with caveats; phases 1–2 are literally what produce spec/ in the first place.

5. Generate the spec

generate_spec({ repoPath: "/absolute/path/to/some-app" })

Only callable once the queue is empty. Writes CLAUDE.md, .claude/ (rules, hooks, a spec-auditor subagent, and a verify-against-spec skill — all derived from this project's actual contracts and tests, not boilerplate), spec/ (contracts, locked decisions, test-dependencies.json, untested-contracts.json), and tests/ to a clean sibling some-app-rebuild/ directory — never into the original repo. Two more .claude/ artifacts are generated only when they'd earn their keep: a test-verifier subagent, only if there are held-out tests to guard; a parallel-test-fix workflow, only if the generated tests split into two or more independent clusters (by shared route files) worth fixing concurrently. A small app with a couple of tests covering the same routes — like the validated example above — gets neither; that's not a bug, it's the generator refusing to hand a rebuild agent tooling it has nothing real to do with. This step also runs a real mutation check: it deliberately breaks the original code (flips a comparison, drops a null check, off-by-ones a loop bound) in a scratch copy and confirms each generated test actually catches it — anything that doesn't gets moved to tests/weak/ instead of shipped as if it were trustworthy. You'll get back:

{
  "outputDir": "/absolute/path/to/some-app-rebuild",
  "mutationsChecked": 8,
  "weakTests": [],
  "unrunnableTests": []
}

Both weakTests and unrunnableTests land in the same tests/weak/ directory instead of tests/visible/, but for different reasons worth telling apart: a weak test ran fine and just never caught anything a mutation broke; an unrunnable test never passed even against the original, unmutated code (a broken import, a missing environment variable, infrastructure the bare repo doesn't have) — before this distinction existed, an unrunnable test looked indistinguishable from a 100%-effective one, since it "fails" identically whether or not the code under test was mutated. Neither is an error — it's the tool telling you honestly that a specific test didn't earn its place in tests/visible/, and why.

If every generated test lands in tests/weak/ with mutationsChecked: 0, check for a warning field before assuming something's structurally wrong — the far more common cause is that the target repo hasn't had npm install run in it, so the mutation-check scratch copy has none of the target's own real dependencies (next, @prisma/client, whatever the app actually needs) and every generated test fails to even import them. generate_spec checks for this directly and says so, rather than leaving you to debug a confusing all-unrunnable result.

Optional: vision-assisted page-content classification

For a Next.js target, page routes get real Playwright-captured tests (a screenshot plus DOM-text assertions) alongside the API-route tests described above. Whether a piece of captured text gets an exact-match assertion (static) or a loose shape check (dynamic) is decided by a small regex classifier by default — reliable most of the time, but confirmed capable of getting it backwards in both directions on a real app (a hardcoded dropdown legend read as live data; a live, comma-formatted database count read as fixed).

Setting both GROQ_API_KEY and REBUILD_DOSSIER_ENABLE_VISION_CLASSIFICATION=1 before calling generate_spec sends each captured page's screenshot and (secret-redacted) source code to a Groq vision model instead, which can see where a value actually comes from — a literal array in the source vs. a fetch/useState call — rather than only guessing from what the rendered string looks like. Both variables are required together on purpose: an ambient GROQ_API_KEY left over from some unrelated tool must never silently start sending this target repo's code to a third party. Neither variable set (the default) means zero behavior change and zero network calls beyond what generate_spec already does (the only one is a one-time download of the pinned vitest runner the mutation check uses, into ~/.cache/rebuild-dossier/, the first time it runs).

This is real added cost, not free: one Groq API call per captured page, plus a deliberate ~20s pacing delay between pages (Groq's free tier has a tight per-minute token budget, and firing requests back to back exhausts it fast) — generate_spec's own response states the exact added time for that run. A page that can't be classified this way for any reason (rate limit, network issue, an invalid response) falls back to the regex classifier for that page only, reported in pageVisionFallbacks — never a silent gap or a failed run. Groq's free tier (no credit card required, at console.groq.com) is enough to try this.

6. Hand it off

cd /absolute/path/to/some-app-rebuild
mv tests/held-out ../held-out-sealed   # keep the acceptance suite out of the agent's reach
claude                                 # a genuinely fresh, top-level session

Three things decide whether the result means anything:

1. Run it as a top-level Claude Code session opened in the package directory. The rails are Claude Code hooks in .claude/settings.json. A session started through another session's Agent tool (a subagent) never loads them, and nothing tells you. Other agents (opencode, oh-my-pi, Codex) can use the package, but without these hooks the rails are prose only.
2. Keep tests/held-out/ out of the agent's reach until it's done, then run it yourself, once: mv ../held-out-sealed tests/held-out && npx vitest run tests/held-out. An agent that can read or re-run a failing held-out test can copy the expected answers out of its error output. That has happened in this project's own evaluation.
3. Check the hooks were live afterward: cat .claude/.hook-heartbeat.json should exist with a count above zero. No file means no hook ever fired.

Paste the contents of kickoff-prompt.txt verbatim. Nothing else should be in that session's context — the directory is fully self-contained on purpose (see How it works), so there's nothing else for a rebuild agent to read, drift toward, or edit in place instead of building cleanly. Read docs/v0-findings.md for what actually happens when you do this against a real app, including exactly where it got stuck.

Connecting from other tools (oh-my-pi, opencode, etc.)

Two ways to run this, both entirely local — there is no hosted/shared instance, and none is required:

stdio (default) — each tool spawns its own copy of the server as a local subprocess. This is the standard way every MCP client (Claude Code, oh-my-pi, opencode) adds a local MCP server — point it at npx tsx src/index.ts (or a built node dist/index.js) from this repo's directory. No extra setup, no auth, nothing in this section applies.

HTTP (optional) — one persistent server on localhost that multiple tools/sessions connect to instead of each spawning their own. Useful if you want oh-my-pi and opencode (or several Claude Code sessions) sharing one running instance. Still fully local — MCP_ALLOWED_HOSTS only needs to include the hostname you'll actually connect to (localhost), not a real domain, unless you deliberately choose to expose this beyond your own machine.

npm run build
PORT=8080 \
MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
REBUILD_DOSSIER_ALLOWED_PATHS=/absolute/path/to/your/projects \
npm run start:http:prod

All three env vars are required — the server refuses to start without them, on purpose: MCP_AUTH_TOKEN gates every /mcp request (bearer auth), MCP_ALLOWED_HOSTS guards against DNS-rebinding, and REBUILD_DOSSIER_ALLOWED_PATHS (comma-separated absolute directories) is the only paths ingest_repo/generate_spec/etc. are allowed to touch — set it to whatever parent directory holds the repos you actually want to rebuild.

oh-my-pi (.omp/mcp.json or ~/.omp/agent/mcp.json):

{
  "mcpServers": {
    "rebuild-dossier": {
      "type": "http",
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer ${REBUILD_DOSSIER_TOKEN}" }
    }
  }
}

opencode (opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rebuild-dossier": {
      "type": "remote",
      "url": "http://localhost:8080/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:REBUILD_DOSSIER_TOKEN}" }
    }
  }
}

oauth: false disables opencode's automatic OAuth discovery on a 401 — this server only supports the static bearer token above, not a real OAuth flow. Set the referenced env var (REBUILD_DOSSIER_TOKEN in both examples) to the same value as MCP_AUTH_TOKEN above.

Development

npm test        # full suite
npm run typecheck

Small, single-purpose functions; TDD throughout (tests are written before the implementation they cover, including for the reconciliation logic itself — this is a tool that generates tests, so its own correctness matters as much as any feature).

Current scope, and what's deliberately not built yet

v0 is scoped to prove the core loop, not to be feature-complete. Deliberately deferred, and tracked as real backlog rather than silently skipped:

• Reconciliation on API-shaped ambiguity (a validation rule, an error-response shape) is still genuinely untested — the one differently-shaped real app validated so far (catchandtrade) happened to have zero comment/TODO signals to reconcile, so this specific question has no answer yet either way. See docs/v0-findings.md.
• Video/screen-recording ingestion and the video-LLM flagged-window review.
• Original-CLAUDE.md / auto-memory as an evidence source.
• Live Chrome MCP capture for auth-gated/multi-account flows a headless crawler can't reach.
• Asset-manifest extraction (binary files copied byte-verbatim + a hash manifest, locked contract tier) — real design exists, not yet built.
• A mutator that no-ops a handler entirely (the current three — flip comparison, drop null check, off-by-one — can't produce a "this branch never ran" mutant).

See docs/v0-findings.md for the full, honest write-up: the real bugs found and fixed during validation, the comparison across model tiers, and what's still open.

Contributing

Thanks for considering a contribution! This is an academic/research project — changes should align with the design described in the paper. See CONTRIBUTING.md for setup, testing, and PR guidelines. First-timers welcome — look for issues tagged good first issue or open one and ask what's most useful.

See How rebuild-dossier compares for how it differs from alternatives.

License

MIT

⭐ If rebuild-dossier helps you ship cleaner rebuilds, a star helps other developers find it.