mapify-cli 3.27.0__tar.gz → 3.28.0__tar.gz

{mapify_cli-3.27.0 → mapify_cli-3.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mapify-cli
-Version: 3.27.0
+Version: 3.28.0
 Summary: MAP Framework installer - Modular Agentic Planner for Claude Code
 Project-URL: Homepage, https://github.com/azalio/map-framework
 Project-URL: Repository, https://github.com/azalio/map-framework.git
@@ -43,8 +43,6 @@ Requires-Dist: pytest>=7.0.0; extra == 'test'
 Requires-Dist: pyyaml>=6.0.0; extra == 'test'
 Description-Content-Type: text/markdown
 
-# MAP Framework
-
 <p align="center">
   <img src="./assets/readme/hero.svg" width="100%" alt="MAP Framework — Plan-then-build AI coding. You approve the plan before the model writes a line of code.">
 </p>

{mapify_cli-3.27.0 → mapify_cli-3.28.0}/README.md

@@ -1,5 +1,3 @@
-# MAP Framework
-
 <p align="center">
   <img src="./assets/readme/hero.svg" width="100%" alt="MAP Framework — Plan-then-build AI coding. You approve the plan before the model writes a line of code.">
 </p>

{mapify_cli-3.27.0 → mapify_cli-3.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "3.27.0"
+version = "3.28.0"
 description = "MAP Framework installer - Modular Agentic Planner for Claude Code"
 authors = [{ name = "MAP Framework Contributors" }]
 readme = "README.md"

{mapify_cli-3.27.0 → mapify_cli-3.28.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.27.0"
+__version__ = "3.28.0"
 
 import contextlib
 import functools

{mapify_cli-3.27.0 → mapify_cli-3.28.0}/src/mapify_cli/schemas.py

@@ -1942,9 +1942,15 @@ REVIEW_VERDICT_LEDGER_SCHEMA: dict[str, Any] = {
                     "id": {"type": "string"},
                     "source_agent": {
                         "type": "string",
+                        # Keep in sync with _LEDGER_SOURCE_AGENTS in
+                        # map_step_runner.py — the runner maps every
+                        # caller-supplied source through that frozenset, so a
+                        # value it accepts must be declared here or the ledger
+                        # fails its own schema. "role" covers the
+                        # user_experience / maintainer reviewers.
                         "enum": [
                             "monitor", "predictor", "evaluator",
-                            "adversarial", "ordering", "operator",
+                            "adversarial", "ordering", "operator", "role",
                         ],
                     },
                     "category": {
@@ -1981,7 +1987,10 @@ REVIEW_VERDICT_LEDGER_SCHEMA: dict[str, Any] = {
                             "new_evidence", "quote_absent", "wrong_category",
                             "different_version", "pre_existing_backlog",
                             "human_escalation", "pressure_without_new_fact",
-                            "input_integrity", "not_applicable", None,
+                            "input_integrity", "not_applicable",
+                            # A role finding that did not fill all five output
+                            # contract parts: tombstoned, never counted.
+                            "contract_incomplete", None,
                         ],
                     },
                     "transition_evidence": {"type": ["string", "null"]},

{mapify_cli-3.27.0 → mapify_cli-3.28.0}/src/mapify_cli/templates/codex/skills/map-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: map-review
-description: "Interactive 4-section code review using monitor, predictor, and evaluator agents on current changes. Use when reviewing a diff, PR, or staged work before merge. Do NOT use to plan or implement; use map-plan or map-efficient."
+description: "Interactive 4-section code review using monitor, predictor, and evaluator agents plus the user and maintainer role reviewers on current changes. Use when reviewing a diff, PR, or staged work before merge. Do NOT use to plan or implement; use map-plan or map-efficient."
 ---
 ## MAP update preflight
 
@@ -12,7 +12,9 @@ For `updated`, re-read this invoked skill's installed `SKILL.md`, skip its alrea
 # $map-review - MAP Review Workflow
 
 Interactive, structured code review of current changes using monitor,
-predictor, and evaluator agents. This skill is the Codex counterpart to
+predictor, and evaluator agents, plus two role reviewers — `user_experience`
+(did the already-shipped path get worse?) and `maintainer` (what rot survives
+the merge?). This skill is the Codex counterpart to
 Claude `/map-review`: it uses Codex-native dispatch (`spawn_agent`) for
 independent reviewer passes, and the current Codex session drives bundle
 setup, verification gates, and presentation.
@@ -66,8 +68,9 @@ These constraints apply before any write-capable step:
 4. Build the review bundle before launching reviewer agents.
 5. Build bounded review prompts before launching reviewer agents.
 6. Launch each reviewer agent once per fan-out (full mode: monitor +
-   predictor + evaluator; lightweight mode: monitor only) — the single
-   truncation retry in Step A.2b is the only exception.
+   predictor + evaluator + the `user_experience` and `maintainer` role
+   reviewers; lightweight mode: monitor only) — the single truncation
+   retry in Step A.2b is the only exception.
 7. Monitor `valid=false` requires verification, not immediate publication —
    every finding needs evidence and must be introduced by this change
    before it reaches presentation.
@@ -162,7 +165,7 @@ Extract each role's prompt from `REVIEW_PROMPTS_JSON`, then dispatch with
 `spawn_agent(agent_type=...)` — see
 [review-reference.md](review-reference.md#dispatch) for the exact prompt
 extraction shell one-liners. Full mode runs monitor + predictor +
-evaluator; lightweight mode runs monitor only. When
+evaluator + both role reviewers; lightweight mode runs monitor only. When
 `COMPLEXITY_LENS_ENABLED=true` (i.e. `.map/config.yaml` sets `minimality`
 to `lite`/`full`/`ultra`), also dispatch the complexity lens using the
 `evaluator` agent type with the `complexity_lens` prompt.
@@ -182,6 +185,18 @@ spawn_agent(
   agent_type="evaluator",
   message=EVALUATOR_PROMPT
 )
+# Full mode only — role reviewers run with isolated context (diff + bundle).
+# They reuse the `evaluator` agent type the same way the complexity lens does:
+# the configured Codex agents are decomposer/monitor/researcher/predictor/
+# evaluator, and what the pass does is defined by its prompt, not by the type.
+spawn_agent(
+  agent_type="evaluator",
+  message=USER_EXPERIENCE_PROMPT
+)
+spawn_agent(
+  agent_type="evaluator",
+  message=MAINTAINER_PROMPT
+)
 # When COMPLEXITY_LENS_ENABLED=true only:
 spawn_agent(
   agent_type="evaluator",
@@ -189,6 +204,16 @@ spawn_agent(
 )
 ```
 
+The role reviewers read the repository (including `git show
+<default-branch>:<file>` for the pre-change surface) and answer to the
+five-part output contract — `problem`, `current_code`, `proposed_code`,
+`why_better`, `cost`. A finding missing any part never gates the change and
+never disappears: on the normal fan-out the ledger tombstones it as
+`contract_incomplete` and names it in `not_verified`, and above `minor` it
+also sets `escalation_required` so PROCEED is unavailable; under
+`--adversarial` the aggregator drops it before the ledger and lists it under
+`contract_incomplete` in the report.
+
 When enabled, the complexity lens is advisory only. It lists
 over-engineering as `delete:`, `stdlib:`, `native:`, `yagni:`, or `shrink:`
 findings, ends with `net: -<N> lines possible.` or `Lean already. Ship.`,
@@ -205,7 +230,8 @@ printf '%s' "$MONITOR_RESPONSE" | \
   python3 .map/scripts/map_step_runner.py detect_truncated_agent_output --agent review-monitor
 ```
 
-Use `--agent predictor` / `--agent evaluator` for the other roles. On
+Use `--agent predictor` / `--agent evaluator` / `--agent user_experience` /
+`--agent maintainer` for the other roles. On
 truncation, log the failure and re-invoke that reviewer once using the
 retry prompt built from the same stdin-piped pattern; if still malformed,
 stop with CLARIFICATION_NEEDED. See
@@ -375,5 +401,5 @@ detached, shuffle, and compare-ordering examples.
 ## Troubleshooting
 
 See [review-reference.md](review-reference.md#troubleshooting) for
-unavailable detached worktrees, missing review bundles, review prompt
-clipping, and ordering drift.
+unavailable detached worktrees, missing review bundles, oversized reviewer
+prompts, and ordering drift.

{mapify_cli-3.27.0 → mapify_cli-3.28.0}/src/mapify_cli/templates/codex/skills/map-review/adversarial-reference.md

@@ -2,7 +2,7 @@
 
 Detailed workflow for `$map-review --adversarial`. See [SKILL.md](SKILL.md)
 for context and integration points. This is the Codex counterpart to Claude
-`--adversarial`: the same three-reviewer contract, run as three SEQUENTIAL
+`--adversarial`: the same five-reviewer contract, run as SEQUENTIAL
 IN-SESSION passes by the current Codex session instead of a parallel agent
 fan-out.
 
@@ -19,7 +19,7 @@ registered Codex agent types.
 (one outside the five above) is an UNVERIFIED ASSUMPTION carried over from
 discovery, not a proven platform limitation.** This file deliberately does
 NOT resolve that assumption — it picks the simpler, verifiably-correct
-option instead: run the three reviewer passes sequentially in the current
+option instead: run the five reviewer passes sequentially in the current
 Codex session, with the session itself switching context/persona between
 passes, rather than betting on an unconfirmed dispatch capability.
 
@@ -40,7 +40,7 @@ works today.
 
 ## Overview
 
-Three reviewer passes, each with only its permitted inputs, run ONE AFTER
+Five reviewer passes, each with only its permitted inputs, run ONE AFTER
 ANOTHER in the current session (never in parallel, never via a new
 agent-dispatch primitive):
 
@@ -49,12 +49,22 @@ agent-dispatch primitive):
 | **Blind Hunter** | diff only | Typos, dead code, logic errors visible in isolation |
 | **Edge Case Hunter** | diff + repo read access | Null handling, boundary conditions, error paths, codebase consistency |
 | **Acceptance Auditor** | diff + spec + plan + artifacts | Missed requirements, spec violations, AC gaps, extra/unplanned work |
+| **User (`user_experience`)** | diff + repo read access | Regressions in the already-shipped path: extra mandatory steps, confusable flags, an explicit value silently overridden |
+| **Maintainer (`maintainer`)** | diff + repo read access | Branch-scoped litter in comments, implementation leaking into user-facing text, copy-paste, split sources of truth, version predicates by number, embedded foreign-language code |
 
-With `--quick`: skip the Edge Case Hunter pass (Blind + Acceptance only).
+With `--quick`: skip the Edge Case Hunter pass (Blind + Acceptance + both
+role passes).
+
+The two role passes answer to the five-part output contract (`problem`,
+`current_code`, `proposed_code`, `why_better`, `cost`); a finding that
+cannot fill all five is dropped into `contract_incomplete` by the
+aggregator — reported, never counted. See
+[review-reference.md](review-reference.md#role-reviewers) for what each role
+checks.
 
 Between passes, deliberately narrow the session's working context to match
 the pass's permitted inputs (e.g. do not consult the spec while running the
-Blind Hunter pass) so the three passes stay as independent as a sequential,
+Blind Hunter pass) so the passes stay as independent as a sequential,
 single-session execution allows.
 
 ## Step B.adversarial.0: Build adversarial review prompts
@@ -75,25 +85,31 @@ EDGE_DESC=$(printf '%s' "$ADV_PROMPTS_JSON" | python3 -c 'import json,sys; d=jso
 
 ACCEPTANCE_PROMPT=$(printf '%s' "$ADV_PROMPTS_JSON" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("prompts",{}).get("acceptance",{}).get("prompt",""))')
 ACCEPTANCE_DESC=$(printf '%s' "$ADV_PROMPTS_JSON" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("prompts",{}).get("acceptance",{}).get("description",""))')
+
+USER_EXPERIENCE_PROMPT=$(printf '%s' "$ADV_PROMPTS_JSON" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("prompts",{}).get("user_experience",{}).get("prompt",""))')
+MAINTAINER_PROMPT=$(printf '%s' "$ADV_PROMPTS_JSON" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("prompts",{}).get("maintainer",{}).get("prompt",""))')
 ```
 
 `build_adversarial_review_prompts` is the exact same CLI verb the Claude
 port calls — payload flows out via stdout JSON only, never via argv, per
 the stdin-safe piping convention used throughout this skill.
 
-## Step B.adversarial.1: Run all three passes sequentially, in-session
+## Step B.adversarial.1: Run all five passes sequentially, in-session
 
 ```text
-# Run the three adversarial reviewer passes ONE AFTER ANOTHER in the
+# Run the five adversarial reviewer passes ONE AFTER ANOTHER in the
 # current Codex session. Do NOT call spawn_agent() for these passes and do
 # NOT invent a new agent-dispatch primitive — see "Design note" above for
 # why. Each pass consumes only its permitted context (BLIND_PROMPT /
-# EDGE_PROMPT / ACCEPTANCE_PROMPT) and produces its own JSON finding
-# report before the next pass begins.
+# EDGE_PROMPT / ACCEPTANCE_PROMPT / USER_EXPERIENCE_PROMPT /
+# MAINTAINER_PROMPT) and produces its own JSON finding report before the
+# next pass begins.
 
 Pass 1 (Blind Hunter):      execute BLIND_PROMPT in-session -> BLIND_OUTPUT
 Pass 2 (Edge Case Hunter):  execute EDGE_PROMPT in-session -> EDGE_OUTPUT   (skip if --quick)
 Pass 3 (Acceptance Auditor): execute ACCEPTANCE_PROMPT in-session -> ACCEPTANCE_OUTPUT
+Pass 4 (User):               execute USER_EXPERIENCE_PROMPT in-session -> USER_EXPERIENCE_OUTPUT
+Pass 5 (Maintainer):         execute MAINTAINER_PROMPT in-session -> MAINTAINER_OUTPUT
 ```
 
 ## Step B.adversarial.2: Validate reviewer outputs
@@ -119,24 +135,39 @@ Write each pass's raw JSON output to a temp file, then aggregate:
 
 ```bash
 printf '%s' "$BLIND_OUTPUT" > .map/$BRANCH/adversarial-blind.json
-printf '%s' "$EDGE_OUTPUT" > .map/$BRANCH/adversarial-edge.json
 printf '%s' "$ACCEPTANCE_OUTPUT" > .map/$BRANCH/adversarial-acceptance.json
+printf '%s' "$USER_EXPERIENCE_OUTPUT" > .map/$BRANCH/adversarial-user-experience.json
+printf '%s' "$MAINTAINER_OUTPUT" > .map/$BRANCH/adversarial-maintainer.json
+
+# The Edge Case Hunter pass did not run under --quick. Writing its file
+# anyway would leave an EMPTY payload (or a stale one from an earlier full
+# run) that the `-f` test below happily forwards; the aggregator then
+# reports edge_case as parse_error, or folds in findings from another
+# review. Remove it, then write it only when the pass actually ran.
+rm -f .map/$BRANCH/adversarial-edge.json
+if [ "$QUICK_FLAG" != "true" ]; then
+  printf '%s' "$EDGE_OUTPUT" > .map/$BRANCH/adversarial-edge.json
+fi
 
-BLIND_ARG=""
-EDGE_ARG=""
-ACCEPTANCE_ARG=""
+ADV_ARGS=""
 if [ -f .map/$BRANCH/adversarial-blind.json ]; then
-  BLIND_ARG="--blind .map/$BRANCH/adversarial-blind.json"
+  ADV_ARGS="$ADV_ARGS --blind .map/$BRANCH/adversarial-blind.json"
 fi
 if [ -f .map/$BRANCH/adversarial-edge.json ]; then
-  EDGE_ARG="--edge-case .map/$BRANCH/adversarial-edge.json"
+  ADV_ARGS="$ADV_ARGS --edge-case .map/$BRANCH/adversarial-edge.json"
 fi
 if [ -f .map/$BRANCH/adversarial-acceptance.json ]; then
-  ACCEPTANCE_ARG="--acceptance .map/$BRANCH/adversarial-acceptance.json"
+  ADV_ARGS="$ADV_ARGS --acceptance .map/$BRANCH/adversarial-acceptance.json"
+fi
+if [ -f .map/$BRANCH/adversarial-user-experience.json ]; then
+  ADV_ARGS="$ADV_ARGS --user-experience .map/$BRANCH/adversarial-user-experience.json"
+fi
+if [ -f .map/$BRANCH/adversarial-maintainer.json ]; then
+  ADV_ARGS="$ADV_ARGS --maintainer .map/$BRANCH/adversarial-maintainer.json"
 fi
 
 ADV_AGGREGATED=$(python3 .map/scripts/map_step_runner.py aggregate_adversarial_findings \
-  $BLIND_ARG $EDGE_ARG $ACCEPTANCE_ARG)
+  $ADV_ARGS)
 ```
 
 `aggregate_adversarial_findings` is the exact same CLI verb the Claude port
@@ -153,8 +184,9 @@ Parse the aggregated JSON and present the report in this structure:
 ## Summary
 - Total findings: N (C CRITICAL, I IMPORTANT, M MINOR)
 - Corroborated (found by 2+ passes): K — highest confidence
-- Per-pass: Blind: B, Edge Case: E, Acceptance: A
+- Per-pass: Blind: B, Edge Case: E, Acceptance: A, User: U, Maintainer: M
 - All-clear: [passes that reported all_clear=true]
+- Dropped for an incomplete output contract: [contract_incomplete entries]
 
 ## CRITICAL
 [per finding: severity, category, file:line, failure_mode, evidence, reported_by, corroborated flag]
@@ -190,8 +222,8 @@ Artifacts.
 ## Flow summary for adversarial
 
 When `ADVERSARIAL_FLAG=true`, the workflow is:
-Phase A (all steps) → Phase B: Adversarial Review (3 sequential in-session
-passes) → Final Verdict → Handoff Artifacts. Do NOT run the normal
+Phase A (all steps) → Phase B: Adversarial Review (5 sequential in-session
+passes, 4 with `--quick`) → Final Verdict → Handoff Artifacts. Do NOT run the normal
 Monitor/Predictor/Evaluator fan-out or the 4-section walkthrough.
 
 ## Examples
@@ -205,7 +237,7 @@ See [review-reference.md](review-reference.md#examples) for adversarial examples
 Re-run that specific pass ONCE. If still invalid, record `parse_error` and
 continue — two valid passes are better than zero.
 
-### All three passes fail
+### All passes fail
 
 Stop with CLARIFICATION_NEEDED. The diff may be too large or the context
 too complex for adversarial review.

{mapify_cli-3.27.0 → mapify_cli-3.28.0}/src/mapify_cli/templates/codex/skills/map-review/review-reference.md

@@ -32,7 +32,9 @@ with open(f".map/{branch}/review-mode.json", "w") as f:
 ```
 
 Mode semantics:
-- **`full`** (default): three reviewer fan-out, all four sections.
+- **`full`** (default): five-reviewer fan-out in total — monitor, predictor,
+  evaluator + the two role passes (`user_experience`, `maintainer`), all four
+  sections. The complexity lens is advisory and extra.
 - **`lightweight`**: monitor only, diff-only, two sections (Code Quality +
   Tests), every finding must carry `reach_evidence`. Bundle is empty so
   reviewers have nothing to synthesize from — staying minimal prevents
@@ -105,6 +107,8 @@ PREDICTOR_PROMPT=$(printf '%s' "$REVIEW_PROMPTS_JSON" | python3 -c 'import json,
 EVALUATOR_PROMPT=$(printf '%s' "$REVIEW_PROMPTS_JSON" | python3 -c 'import json,sys; print(json.load(sys.stdin)["prompts"]["evaluator"]["prompt"])')
 COMPLEXITY_LENS_PROMPT=$(printf '%s' "$REVIEW_PROMPTS_JSON" | python3 -c 'import json,sys; data=json.load(sys.stdin); print(data.get("prompts",{}).get("complexity_lens",{}).get("prompt", ""))')
 COMPLEXITY_LENS_ENABLED=$(printf '%s' "$REVIEW_PROMPTS_JSON" | python3 -c 'import json,sys; data=json.load(sys.stdin); print("true" if data.get("prompts",{}).get("complexity_lens") else "false")')
+USER_EXPERIENCE_PROMPT=$(printf '%s' "$REVIEW_PROMPTS_JSON" | python3 -c 'import json,sys; print(json.load(sys.stdin)["prompts"]["user_experience"]["prompt"])')
+MAINTAINER_PROMPT=$(printf '%s' "$REVIEW_PROMPTS_JSON" | python3 -c 'import json,sys; print(json.load(sys.stdin)["prompts"]["maintainer"]["prompt"])')
 ```
 
 ```text
@@ -113,12 +117,20 @@ spawn_agent(agent_type="monitor", message=MONITOR_PROMPT)
 spawn_agent(agent_type="predictor", message=PREDICTOR_PROMPT)
 # Full mode only — skip in lightweight mode (monitor-only):
 spawn_agent(agent_type="evaluator", message=EVALUATOR_PROMPT)
+# Full mode only — role reviewers. Isolated means: no other reviewer's
+# output. They DO get read-only repo access on top of diff + bundle —
+# both roles must run `git show <default-branch>:<file>` and grep the base.
+spawn_agent(agent_type="evaluator", message=USER_EXPERIENCE_PROMPT)
+spawn_agent(agent_type="evaluator", message=MAINTAINER_PROMPT)
 # When COMPLEXITY_LENS_ENABLED=true only:
 spawn_agent(agent_type="evaluator", message=COMPLEXITY_LENS_PROMPT)
 ```
 
-Full mode runs monitor + predictor + evaluator; lightweight mode runs
-monitor only. Reviewer prompts reference `review-bundle.json`,
+Full mode runs monitor + predictor + evaluator + both role reviewers;
+lightweight mode runs monitor only. The role reviewers reuse the
+`evaluator` agent type exactly as the complexity lens does — the
+configured Codex agents are decomposer/monitor/researcher/predictor/
+evaluator, and what a pass does is defined by its prompt, not by the type. Reviewer prompts reference `review-bundle.json`,
 `review-bundle.md`, the raw diff as secondary context, and the expected
 output schema (Monitor evidence/valid/verdict/issues,
 Predictor evidence/risk_assessment/landmine_evidence, Evaluator
@@ -140,6 +152,10 @@ printf '%s' "$PREDICTOR_RESPONSE" | \
   python3 .map/scripts/map_step_runner.py detect_truncated_agent_output --agent predictor
 printf '%s' "$EVALUATOR_RESPONSE" | \
   python3 .map/scripts/map_step_runner.py detect_truncated_agent_output --agent evaluator
+printf '%s' "$USER_EXPERIENCE_RESPONSE" | \
+  python3 .map/scripts/map_step_runner.py detect_truncated_agent_output --agent user_experience
+printf '%s' "$MAINTAINER_RESPONSE" | \
+  python3 .map/scripts/map_step_runner.py detect_truncated_agent_output --agent maintainer
 ```
 
 On truncation: log via
@@ -169,6 +185,12 @@ walkthrough item:
    the twin.
 4. **Precheck duplication check.** If the finding matches a precheck error
    line, cite the precheck and stop — do NOT raise a second instance.
+4b. **Role contract check.** A `user_experience` / `maintainer` finding is
+   published only with all five contract parts filled (`problem`,
+   `current_code`, `proposed_code`, `why_better`, `cost`). An incomplete
+   one is not softened into an advisory: the ledger tombstones it as
+   `contract_incomplete` and names it in `not_verified` — and above `minor`
+   it escalates, so PROCEED is unavailable until a human rules on it.
 5. **Reachability check** (defensive branches): guard-branch patterns
    usually exist by convention and their absence of tests is not a
    "missing test" finding unless the surrounding logic actually depends
@@ -261,6 +283,72 @@ When `--compare-orderings` is set, collect one run with
 aggregate with `compare-review-runs`, then persist with
 `record-review-ordering`. Treat verdict drift as review evidence.
 
+## Role Reviewers
+
+Two perspective roles run in BOTH review paths — the normal fan-out and
+`--adversarial`. They answer questions nobody else in the fan-out is asked.
+
+**`user_experience` — the person or script that CALLS this.** One question:
+did the change make the ALREADY SHIPPED functionality harder or less
+convenient?
+
+- Convenience regression: do the pre-diff scenarios still take the same
+  number of steps? Did the old path gain a mandatory flag or ordering rule?
+- Distinguishability: two confusable flags/options/fields (`--release` vs
+  `--from-release`)? Does the name alone say what it does?
+- Explicit input beats a default: an explicitly supplied value that is
+  incompatible with the new mode must be REJECTED with a clear error, never
+  silently overridden.
+- The current flag set is not a given — propose the ideal one when it confuses.
+- Judged from two sub-roles: a human in a terminal, and a CI script.
+
+**`maintainer` — the person extending this a quarter from now.** Checks:
+
+| Class | What it hunts |
+|---|---|
+| A1 | Branch-scoped litter in comments (plan/tracker IDs, `.map/` paths, "step N") |
+| A2 | Implementation vocabulary leaking into help/error/log/doc text |
+| B | Copy-paste: near-identical logic in 2+ places that must change in sync |
+| C | Single source of truth: one decision computed in more than one place |
+| D | Overcomplication: twisted booleans, deep nesting, mixed responsibilities |
+| E | Order of logic: validation / defaults / execution readable top to bottom |
+| F | Dead or idle work: built-but-unused structures, duplicated guards |
+| G | Extensibility: how many places the next similar case touches — exact N |
+| H | Version/capability predicates: one module, named by capability not number, one comparison style — found by whole-base grep, not in the diff |
+| I | Embedded shell/YAML/SQL/HCL inside string literals — unreviewable, untestable |
+
+For B, C and H one site is not a finding: the finding is the number of sites
+and the point where they collapse.
+
+### The output contract
+
+Every role finding carries five parts, or it is not reported:
+
+| Part | Requirement |
+|---|---|
+| `problem` | one line + exact `file:line` |
+| `current_code` | the lines as they are, copied verbatim |
+| `proposed_code` | applicable as a patch — the helper itself, not "extract a helper" |
+| `why_better` | measurable delta ("3 edit sites -> 1", "-1 responsibility"); bare "cleaner" is rejected |
+| `cost` | the downside of the fix, or `none` |
+
+A finding missing any part is NOT softened into an advisory, but where it
+lands depends on the path that ran: on the normal fan-out the ledger
+tombstones it with `transition_reason: contract_incomplete` — at ANY
+severity, and when that severity is above `minor` it also sets
+`escalation_required`, so a CRITICAL dropped for a missing `cost` costs the
+run its PROCEED instead of vanishing; under `--adversarial` the aggregator
+removes it first, so it appears only under `contract_incomplete` in the
+report and the ledger never sees it. Either way it cannot gate the change,
+and it cannot disappear either.
+
+Standalone prompt build (the normal fan-out builds these automatically):
+
+```bash
+python3 .map/scripts/map_step_runner.py build_role_review_prompts \
+  [--roles user_experience,maintainer]
+```
+
 ## Cross-AI
 
 See the "Phase B: Cross-AI Peer Review" section in [SKILL.md](SKILL.md) for
@@ -361,7 +449,8 @@ $map-review --compare-orderings
 - Detached prep unavailable: continue from the in-place review bundle; do
   not mutate the source branch.
 - Missing bundle: rerun `create_review_bundle` before agents.
-- Prompt clipping: inspect `.map/<branch>/token_budget.json`, then raise
-  `MAP_REVIEW_PROMPT_BUDGET_TOKENS` only when the bundle evidence is
-  actually missing.
+- Oversized reviewer prompt: nothing is clipped and no `token_budget.json`
+  entry is written for review — `MAP_REVIEW_PROMPT_BUDGET_TOKENS` is
+  reported, not enforced. Reduce the input yourself (compact the session,
+  or split the change); raising the variable changes nothing.
 - Monitor invalid: treat as hard stop and record `REVISE` or `BLOCK`.