ultra detailed design review

Task: ultra-detailed design review of the harnessed project

You are the review agent, running inside a claude_review-harness container. Everything below operates on the repository as mounted into this container — discover your layout with git, never assume host paths. When a precondition isn't met, your job is to stop and tell the operator, not to change how the container was launched: you didn't launch it and can't relaunch yourself. Nothing in this task requires knowing a host path or a harnessed launch flag — if you find yourself reaching for one, that's the signal to stop and hand it back to the operator.

"Operator" throughout means the person driving this session. Checkpoint with them at each phase boundary rather than pushing until you run out of context.

Preconditions — verify these before Phase 1

Run each check. If any fails, stop, report exactly what's missing, and wait for the operator.

1. Stack tools are live. bd (beads) and rtk on PATH, the caveman skill loaded, and codebase-memory-mcp's tools connected through the MCP hub. The phases assume these are real, not optional flourishes. If they're absent, switch to the Fallback section at the end.
2. The whole repository is reachable. This is a bare + linked-worktree layout: the shared git directory is a .bare/ repo, and each branch is its own sibling worktree directory, not a subdirectory of the trunk. Run git worktree list and git rev-parse --git-common-dir, then spot-check that a couple of the listed worktree paths exist and git -C <path> status works. If the sibling worktrees or the common dir aren't reachable, only part of the repo was mounted and Phase 1 is impossible — stop and tell the operator the container needs the full repo tree exposed. Do not try to work around a partial mount.

How to use the stack's tools across this review

• bd — the source of truth for tracked work, not markdown bullets. Every branch in Phase 1 becomes a bd issue (tested? merge-ready? blockers?). Every roadmap item in Phase 3 becomes a bd issue with real dependency edges where one thing blocks another. Markdown docs at the end should describe what's in bd, not duplicate it as a second source of truth that can drift.
• rtk — wrap the heavy investigation commands. Phase 1 runs git/fd/rg across every worktree; that output is exactly what rtk exists to compress before it reaches your context. Use rtk git status, rtk read <file>, etc. instead of the raw commands wherever you're doing broad exploration rather than a targeted single check.
• caveman — use it for your own working narration during Phases 1–3, not for Phase 4's deliverables. Terse output is a genuine win while you're grinding through branch inventories and roadmap reconciliation — you don't need prose there. But the actual files you write in Phase 4 (user-facing capability docs) need normal, readable prose regardless of how tersely you've been talking to the operator. Don't let caveman-mode leak into the deliverables.
• codebase-memory-mcp — your primary tool for Phase 2's structural questions, not a supplement to grep. Use search_graph/trace_path/get_architecture to answer "what calls what" and "is this actually referenced anywhere" instead of re-deriving it from raw file reads. detect_changes is specifically suited to Phase 1's "what did this branch actually touch" question — prefer it over a manual git diff read where it applies.

This review is resumable — use that

The five phases together are far more than one context window holds, and Phase 5 spawns a second full review. Don't try to finish in one shot. All durable state lives in bd (issues) and bd remember (notes), which persist outside your context across sessions — so you can stop between phases and a fresh session resumes from bd ready. Checkpoint with the operator at each phase boundary rather than pushing until you run out of room. Each phase has a concrete done-condition below; treat it as the gate before moving on.

Orientation — discover, don't assume

• Trunk is main. Enumerate branches with git worktree list — don't trust any branch list written outside this session, it will be stale by the time you read it. Some branches may exist only on the remote; git fetch first and compare against git branch -a if the inventory looks short.
• docs/ is a separate git repository (a live clone of the GitHub wiki, not a submodule) — git status in the main repo won't show docs changes; check git -C docs status separately. It carries real, recent work: an updated ROADMAP.md, guides, research docs, and design specs. Read what's there before assuming anything is missing or stale. It is also where your Phase 2 and Phase 3 outputs land (codebase map, updated ROADMAP.md) — those are commits to the wiki repo, separate from the main repo. Leave them staged/described; don't push (that's the operator's call).
• web/ is a real Astro site — a harness-comparison marketing page. This is the "user website" Phase 4 feeds into — don't invent a separate doc site.
• Several recipes exist only as unmerged feat/recipe-* branches and have never been build/test-verified end-to-end. "Exists in a branch" does not mean "works" — Phase 1 checks this explicitly. The recipes this stack itself runs on (beads, caveman, rtk, codebase-memory-mcp) are merged to main — verify them as shipped, not as branches — but "it worked for me just now" is still not the build + capability-test verification Phase 1 demands; verify them the same as any other.

Phase 1 — Inventory every branch before touching anything

For each worktree/branch: what it adds, whether it's been tested (build + capability test, not just pytest), and whether it conflicts with or duplicates another branch. Recipes sharing catalog/base/Dockerfile.harnessed-base or touching schema.py are the likely collision points; so are two recipes that declare each other in conflicts: (the recipe schema now enforces mutual-exclusion — flag any stack that trips it).

File one bd issue per branch, fields: adds-what, tested-how, merge-ready (y/n), blockers (as dependency edges to other issues where one branch blocks another). Use codebase-memory-mcp's detect_changes to characterize each branch's actual diff against main rather than reading it by hand. Use rtk for the git/fd/rg legwork.

Do not merge anything yet. This phase is inventory only.

Done when: every branch from git worktree list (and any remote-only branch from git branch -a) has exactly one bd issue, with no branch left uncharacterized.

Phase 2 — Re-map the codebase

Run the /map-codebase skill against main. This regenerates docs/codebase/{ARCHITECTURE,STRUCTURE,CONVENTIONS,INTEGRATIONS,STACK,TESTING,CONCERNS}.md.

Cross-check its output against codebase-memory-mcp's own graph (get_architecture, search_graph) where the two might disagree — /map-codebase's subagents read files fresh each time; cbm has a persisted index that can catch something a one-pass read misses, and vice versa. Note any discrepancy using bd remember rather than silently picking one source.

Map main only — annotate afterward with "also exists on branch X, unmerged" from Phase 1's bd issues, rather than trying to map a hypothetical merged-everything state that doesn't exist.

Done when: the seven docs/codebase/*.md files are regenerated and every point where cbm's graph and the fresh map disagree is captured as a bd remember note.

Phase 3 — Reconcile the roadmap

docs/ROADMAP.md has been substantially rewritten more than once this project's history after being found stale (describing as "planned" work that had already shipped). Don't assume it's still accurate now either. Cross-reference it against:

• Phase 1's bd issues (branch inventory)
• Phase 2's codebase map (what's actually implemented, not just documented)
• The full open issue list (GitHub Issues). Do not create a docs/todos/ directory or any dated planning-doc dumping ground — an open item goes straight to a GitHub Issue, never a new dated markdown file. Reference-only material belongs in research/.
• docs/research/*.md — first-hand technical research (home-folder layouts per harness, rules-directory support, plus recipe-stress-test.md and cross-harness-identity-and-rules.md since the 2026-07-05 migration) that the roadmap's technical claims need to stay consistent with.

Output: an updated ROADMAP.md whose content is a human-readable rendering of the bd issue graph plus decision history, not a parallel, driftable task list.

Done when: ROADMAP.md contains no open action items that aren't also filed as bd issues, and every bd issue this phase's cross-referencing surfaced as stale/superseded has been closed or updated.

Phase 4 — User-facing capability documentation

Drop caveman-mode for this phase. Using Phase 1's branch inventory and docs/guides/recipe-catalog.md (developer-facing categorization of every recipe, overlaps, and harness support) as source material, write user-facing content for the web/ Astro site: what harnessed does, which harnesses it supports, which tools/recipes are available, and the team-deployable-configuration story (see the "governing principle" section in docs/research/cross-harness-identity-and-rules.md — containerize configuration, not storage).

Stay factually accurate against Phase 1 and Phase 3's findings: don't claim a recipe works if Phase 1 found it untested; don't claim a feature exists if Phase 3 found it's still a spec.

Done when: the web/ content is written and every capability claim in it traces to a specific Phase 1 (tested) or Phase 3 (implemented, not just spec'd) finding.

Phase 5 — Independent deep review

Only after Phases 1–4 are complete. This must be a genuinely independent session, not a subagent that inherits your context. Ask the operator to start a fresh review session on this same stack, on the Opus model, with no memory of how this review was conducted — you can't spawn it yourself. Because bd and codebase-memory-mcp state persists across sessions, that fresh session sees the same issue graph and code index you built — it queries them directly rather than trusting your prose. (If it must instead run in-session as a subagent, force the Opus model and hand it only the artifacts to read/query — never your running summary.)

Hand it the final state (updated ROADMAP.md, codebase map, bd issue graph, the new user docs) as things to read/query itself — not a summary you write for it. It may read your bd remember notes for context, but its own verification must come from directly querying bd/cbm/the codebase, not from trusting what the notes claim.

Ask it to independently assess:

• Design coherence — does the roadmap's stated direction match what the codebase map shows is built? Any contradictions across docs?
• Dead code — anything cbm's graph shows with no incoming references that no bd issue, recipe, or test accounts for
• Unresolved concerns — re-check anything flagged "unverified"/"open question"/"TBD" across every doc touched in Phases 1–4; is any of it actually blocking something the roadmap now claims is ready?
• Scattered/orphaned scope — anything Phase 1's bd issues surfaced that isn't reflected anywhere in the reconciled roadmap

This agent should be adversarial, not confirmatory. Report its findings verbatim, not summarized into agreement.

Fallback — stack tools unavailable

If the Preconditions check finds the stack tools missing (no bd/rtk/caveman/codebase-memory-mcp), run the same five phases but: replace bd issues (and bd remember notes) with a plain TaskCreate/TaskUpdate list and markdown scratch notes, skip the rtk/caveman guidance entirely, and use whatever code-search tools are available for Phase 2's cross-check instead of codebase-memory-mcp. The repository-visibility precondition still holds: every worktree and the common dir must be reachable from wherever you're running — if that isn't the case, it's still a stop-and-tell-the-operator condition, not something to work around.