---
name: gmd:map-review
description: On-demand Graph Reviewer — dispatches gmd-map-reviewer over the generated code wiki (.planning/codebase) to emit a severity-ranked .review-report.md without re-running the mapper
argument-hint: "[optional: wiki root override]"
allowed-tools:
  - Read
  - Bash
  - Grep
  - Glob
  - Task
---

<objective>
Run `gmd-map-reviewer` against an EXISTING generated code wiki (`.planning/codebase`, or a
root override) WITHOUT re-running the full mapper, producing/refreshing
`.planning/codebase/.review-report.md` with the 7-check, severity-ranked findings:
**dangling wikilinks, stale `file:line` pointers, claim/evidence mismatch, orphan Deep-Dive
components, missing Boundary-Interfaces, unknown typed edges, malformed provenance** — ranked
**critical / warning / info** plus a load-bearing `## Checks Skipped` section.

**Why subagent:** the full 7-check pass (especially the LLM claim/evidence judgment over every
`[extracted file:line]` claim) burns context — a fresh 200k window per invocation keeps the main
session lean. Six checks are mechanical (ridden via `reviewCodeWiki` in `bin/lib/map-review.js`);
only check 3 (claim/evidence mismatch on a non-blank resolving line) is LLM judgment.

**Relationship to the end-of-run auto-fire:** `workflows/map-codebase.md` ALREADY reviews the wiki
at the end of every `gmd-map-codebase` run (a deterministic `reviewCodeWiki` baseline, fail-open).
This command does NOT replace that — it is the **on-demand / standalone** path: it upgrades the
baseline to the full 7-check pass (adding the LLM claim/evidence judgment), re-reviews after edits,
or runs a standalone integrity pass without a full remap. Like the auto-fire, it is **advisory-only
and fail-open** — a reviewer failure surfaces the error but NEVER blocks anything.
</objective>

<when_to_use>

**Use when:**

- A `map-codebase` run just finished and you want the FULL 7-check pass (the auto-fire emits only
  the mechanical baseline; this adds the LLM claim/evidence judgment)
- Investigating suspected referential drift — a renamed/moved module rotting a `file:line` citation
  or a `[[wikilink]]` in a Deep-Dive doc
- A standalone code-wiki integrity pass after hand-edits to the wiki, without paying for a full remap
- A second-opinion review after the baseline report looked thin

**Do NOT use for:**

- A pre-commit hook — out of SPEC scope (Open Q6, deferred). The reviewer is an advisory end-of-run /
  on-demand surface, not a gate.
- During active mapping — run this AFTER the wiki exists (`.planning/codebase/` with a `Deep-Dive`
  or `Boundary-Interfaces` tree). If no wiki exists, this command fails fast with a clear message.
- As a substitute for `/gmd:map-codebase` — it reviews an EXISTING wiki, it does not generate one.

</when_to_use>

<context>

User's optional wiki-root override: $ARGUMENTS (may be empty)

```bash
ROOT_ARG="${1:-$ARGUMENTS}"
ROOT_ARG=$(echo "$ROOT_ARG" | tr -d '[:space:]')
```

</context>

<process>

## 0. Initialize Context

```bash
INIT=$(node "${CLAUDE_PLUGIN_ROOT}/bin/gmd-tools.cjs" state load 2>/dev/null || echo "")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```

(STATE is optional here — the reviewer reads the wiki, not the plan state. Continue even if absent.)

Resolve the reviewer model:

```bash
reviewer_model=$(node "${CLAUDE_PLUGIN_ROOT}/bin/gmd-tools.cjs" resolve-model gmd-map-reviewer --complexity standard --raw 2>/dev/null || echo "")
```

## 1. Resolve the wiki root + fail fast if no wiki exists

```bash
WIKI_ROOT="${ROOT_ARG:-.planning/codebase}"

if [ ! -d "$WIKI_ROOT" ]; then
  echo "ERROR: no code wiki at '$WIKI_ROOT'. Run /gmd:map-codebase first, or pass a wiki root."
  exit 1
fi

if [ ! -d "$WIKI_ROOT/Deep-Dive" ] && [ ! -d "$WIKI_ROOT/Boundary-Interfaces" ]; then
  echo "ERROR: '$WIKI_ROOT' has no C4 wiki (no Deep-Dive/ or Boundary-Interfaces/ tree). Nothing to review."
  exit 1
fi
```

## 2. Dispatch gmd-map-reviewer

Dispatch the read-only, fail-open Graph Reviewer over the wiki. It rides `reviewCodeWiki` for the
6 mechanical checks and judges check 3 (claim/evidence) by LLM, then emits the severity-ranked
report. Pass the `<files_to_read>` block + the resolved root.

```
Task(
  subagent_type="gmd-map-reviewer",
  model="{reviewer_model}",
  description="On-demand Graph Review of {WIKI_ROOT}",
  prompt="
    <objective>
    On-demand full 7-check Graph Review of the code wiki at {WIKI_ROOT}.

    Run the 6 mechanical checks via reviewCodeWiki(\"{WIKI_ROOT}\") AND the LLM claim/evidence
    judgment (check 3) over the [extracted file:line] claims that RESOLVE (file exists, line
    in-range, line non-blank — no double-count with the mechanical stale_file_line). Render the
    severity-ranked report with the load-bearing ## Checks Skipped section.
    </objective>

    <wiki_root>{WIKI_ROOT}</wiki_root>

    <files_to_read>
    - {WIKI_ROOT}/SCHEMA.md
    - {WIKI_ROOT}/STRUCTURAL-SCHEMA.md
    - {WIKI_ROOT}/.structural.json
    - {WIKI_ROOT}/*.md
    - {WIKI_ROOT}/Deep-Dive/**/*.md
    - {WIKI_ROOT}/Boundary-Interfaces/**/*.md
    - bin/lib/map-review.js
    </files_to_read>

    <output>
    (Re)emit {WIKI_ROOT}/.review-report.md per gmd-map-reviewer.md workflow Step 4:
    frontmatter (generated_by / last_reviewed_at / wiki_root / findings-by-severity / checks_skipped)
    + ## Critical / ## Warning / ## Info (_None_ when empty) + the LOAD-BEARING ## Checks Skipped
    section + an 'N critical / M warning / K info / S skipped' header.
    </output>

    FAIL-OPEN / advisory-only: exit cleanly regardless of the critical count; NEVER rewrite a
    code-wiki doc — your ONLY write is .review-report.md. An empty/absent wiki -> an empty report,
    never an error.
  "
)
```

## 3. Report Summary

After `gmd-map-reviewer` returns, relay its severity summary + the report path to the user.
**FAIL-OPEN:** if the reviewer errored, surface the error but do NOT error this command out — the
review is advisory.

```
/gmd:map-review complete.

Report: {WIKI_ROOT}/.review-report.md
Findings: {N} critical / {M} warning / {K} info / {S} skipped

Advisory only — nothing was blocked or rewritten.
{If critical > 0:} Review the Critical section for dangling links / stale file:line / claim-evidence mismatches.
{If skipped > 0:} Note the ## Checks Skipped section — those checks could not run (not "clean").
```

</process>

<relationship_to_auto_fire>

The Graph Reviewer is wired at **two** surfaces, and a reviewer failure NEVER blocks the mapper at
either (SC3, fail-open):

- `workflows/map-codebase.md` end-of-run hook (`lint_code_edges`) — **automatic** at the end of
  every `gmd-map-codebase` run. Emits a deterministic `reviewCodeWiki` BASELINE report (the 6
  mechanical checks), or — under a team-lead orchestrator with `Task` — may dispatch
  `gmd-map-reviewer` inline for the full pass.
- `/gmd:map-review` (this command) — **on-demand / standalone**. The escape hatch for the FULL
  7-check pass (adds the LLM claim/evidence judgment), a re-review after edits, or a standalone
  integrity pass without a full remap.

Running both on the same wiki is fine — this command simply refreshes `.review-report.md` with the
fuller pass. Neither surface gates: both are advisory-only.

</relationship_to_auto_fire>

<success_criteria>

- [ ] Wiki-root resolved (from $1/$ARGUMENTS or default `.planning/codebase`)
- [ ] Fails fast with a clear message if no wiki / no C4 tree exists
- [ ] `gmd-map-reviewer` dispatched via Task with a `<files_to_read>` block + the wiki root
- [ ] `.review-report.md` produced/refreshed in the wiki root
- [ ] Severity summary + report path relayed to the user
- [ ] Fail-open: a reviewer failure surfaces but does NOT error the command out

</success_criteria>
