mapify-cli 3.25.0__tar.gz → 3.26.0__tar.gz

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mapify-cli
-Version: 3.25.0
+Version: 3.26.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
@@ -125,6 +125,7 @@ That's the whole golden path.
 - **Already scoped?** Go straight to `/map-efficient`.
 - **Tiny edit?** `/map-plan` off-ramps you to a direct edit or `/map-fast` instead of forcing full planning.
 - **Too foggy to plan?** `/map-wayfind` resolves open design decisions one at a time on a durable map, then hands settled decisions to `/map-plan`.
+- **Want one entry point?** `/map-auto` routes and drives the chain autonomously; hard-stops only on `dangerous_action`/`safety_guardrail` holds.
 
 > Codex CLI users invoke the same skills with `$`: `$map-plan`, `$map-efficient`, `$map-check`. See the [Usage Guide](docs/USAGE.md#codex-cli-provider).
 
@@ -155,6 +156,7 @@ The DevOpsConf 2026 case study applies this process to a production Kubernetes P
 
 | Command | Use For |
 |---------|---------|
+| `/map-auto` | Single-entry autonomous autopilot: routes a task through existing MAP workflows and drives the chain to a committed branch |
 | `/map-plan` | **Start here** for non-trivial work; clarify behavior and decompose tasks |
 | `/map-wayfind` | Too foggy to plan? Resolve design decisions on a durable map *before* `/map-plan` |
 | `/map-efficient` | **Implement** an approved plan or already-scoped task |

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/README.md

@@ -80,6 +80,7 @@ That's the whole golden path.
 - **Already scoped?** Go straight to `/map-efficient`.
 - **Tiny edit?** `/map-plan` off-ramps you to a direct edit or `/map-fast` instead of forcing full planning.
 - **Too foggy to plan?** `/map-wayfind` resolves open design decisions one at a time on a durable map, then hands settled decisions to `/map-plan`.
+- **Want one entry point?** `/map-auto` routes and drives the chain autonomously; hard-stops only on `dangerous_action`/`safety_guardrail` holds.
 
 > Codex CLI users invoke the same skills with `$`: `$map-plan`, `$map-efficient`, `$map-check`. See the [Usage Guide](docs/USAGE.md#codex-cli-provider).
 
@@ -110,6 +111,7 @@ The DevOpsConf 2026 case study applies this process to a production Kubernetes P
 
 | Command | Use For |
 |---------|---------|
+| `/map-auto` | Single-entry autonomous autopilot: routes a task through existing MAP workflows and drives the chain to a committed branch |
 | `/map-plan` | **Start here** for non-trivial work; clarify behavior and decompose tasks |
 | `/map-wayfind` | Too foggy to plan? Resolve design decisions on a durable map *before* `/map-plan` |
 | `/map-efficient` | **Implement** an approved plan or already-scoped task |

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/pyproject.toml

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

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.25.0"
+__version__ = "3.26.0"
 
 import json
 import os

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/src/mapify_cli/schemas.py

@@ -808,6 +808,7 @@ ARTIFACT_MANIFEST_SCHEMA = {
                 "workflow_fit": ARTIFACT_STAGE_SCHEMA,
                 "spec": ARTIFACT_STAGE_SCHEMA,
                 "plan": ARTIFACT_STAGE_SCHEMA,
+                "auto_route": ARTIFACT_STAGE_SCHEMA,
                 "test_contract": ARTIFACT_STAGE_SCHEMA,
                 "repro_probe": ARTIFACT_STAGE_SCHEMA,
                 "implementation": ARTIFACT_STAGE_SCHEMA,
@@ -829,6 +830,8 @@ ARTIFACT_MANIFEST_SCHEMA = {
                 "worktree": ARTIFACT_STAGE_SCHEMA,
                 "context_usefulness": ARTIFACT_STAGE_SCHEMA,
                 "wayfind_handoff": ARTIFACT_STAGE_SCHEMA,
+                "review_verdict_ledger": ARTIFACT_STAGE_SCHEMA,
+                "prd_review": ARTIFACT_STAGE_SCHEMA,
             },
             "required": [
                 "workflow_fit",
@@ -1521,7 +1524,15 @@ REVIEW_BUNDLE_SCHEMA = {
                             },
                             "status": {
                                 "type": "string",
-                                "enum": ["covered", "missing_evidence"],
+                                # planned_only: the owner subtask's validation_criteria
+                                # names the requirement but nothing downstream verified
+                                # it — a review gap, distinct from a requirement no
+                                # artifact ever mentions (missing_evidence).
+                                "enum": [
+                                    "covered",
+                                    "planned_only",
+                                    "missing_evidence",
+                                ],
                             },
                         },
                         "required": [
@@ -1539,7 +1550,11 @@ REVIEW_BUNDLE_SCHEMA = {
                     "properties": {
                         "total": {"type": "integer", "minimum": 0},
                         "covered": {"type": "integer", "minimum": 0},
+                        # `missing` stays the total un-covered count for backward
+                        # compatibility; `planned_only` breaks out the review-gap
+                        # subset so the two failure modes are separable.
                         "missing": {"type": "integer", "minimum": 0},
+                        "planned_only": {"type": "integer", "minimum": 0},
                     },
                     "required": ["total", "covered", "missing"],
                     "additionalProperties": False,
@@ -2055,3 +2070,171 @@ REVIEW_VERDICT_LEDGER_SCHEMA: dict[str, Any] = {
     ],
     "additionalProperties": True,
 }
+
+PRD_REVIEW_SCHEMA: dict[str, Any] = {
+    "$id": "prd-review.json",
+    "type": "object",
+    "description": "PRD/requirements-quality review artifact written by write_prd_review.",
+    "properties": {
+        "schema_version": {"type": "string"},
+        "branch": {"type": "string"},
+        "generated_at": {"type": "string", "description": "ISO-8601 UTC timestamp"},
+        "prd_source": {"type": "string", "description": "Path or label of the reviewed PRD"},
+        "verdict": {
+            "type": "string",
+            "enum": [
+                "ready_for_plan",
+                "needs_prd_revision",
+                "needs_user_decision",
+                "route_to_wayfind",
+            ],
+        },
+        "findings": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "dimension": {"type": "string"},
+                    "severity": {
+                        "type": "string",
+                        "enum": ["critical", "major", "minor", "info"],
+                    },
+                    "description": {"type": "string"},
+                    "suggested_revision": {"type": "string"},
+                },
+                "required": ["dimension", "severity", "description"],
+                "additionalProperties": False,
+            },
+        },
+        "blocking_questions": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "question": {"type": "string"},
+                    "category": {"type": "string"},
+                },
+                "required": ["question", "category"],
+                "additionalProperties": False,
+            },
+        },
+        "suggested_revisions": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+        "route_recommendation": {"type": "string"},
+        "summary": {"type": "string"},
+    },
+    "required": [
+        "schema_version",
+        "branch",
+        "generated_at",
+        "verdict",
+        "findings",
+        "blocking_questions",
+        "suggested_revisions",
+        "summary",
+    ],
+    "additionalProperties": True,
+}
+
+AUTO_ROUTE_SCHEMA: dict[str, Any] = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/auto-route.json",
+    "title": "MAP Auto Route Decision",
+    "description": (
+        "Autonomous routing decision and phase ledger stored in "
+        ".map/<branch>/auto-route.json (/map-auto)."
+    ),
+    "type": "object",
+    "properties": {
+        "schema_version": {"type": "string"},
+        "task_summary": {"type": "string"},
+        "selected_route": {
+            "type": "string",
+            "enum": [
+                "map-resume",
+                "map-check",
+                "map-fast",
+                "map-plan",
+                "map-efficient",
+            ],
+        },
+        "evidence": {
+            "type": "array",
+            "description": "Structured signals that justified the selected_route.",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "signal": {"type": "string"},
+                    "value": {"type": "string"},
+                    "source": {"type": "string"},
+                },
+                "required": ["signal", "value", "source"],
+                "additionalProperties": False,
+            },
+        },
+        "blocked_by": {
+            "type": "array",
+            "description": "Pending hard-stop hold ids blocking the chain, if any.",
+            "items": {"type": "string"},
+        },
+        "next_command": {"type": "string"},
+        "executed": {"type": "boolean"},
+        "chain_status": {
+            "type": "string",
+            "enum": [
+                "recommended_only",
+                "blocked",
+                "in_progress",
+                "completed",
+                "aborted",
+            ],
+        },
+        "phases": {
+            "type": "array",
+            "description": "Phase ledger; appended only by record_auto_phase.",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "phase": {"type": "string"},
+                    "status": {"type": "string"},
+                    "attempt": {"type": "integer", "minimum": 1},
+                    "evidence_refs": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                    },
+                    "reason": {"type": "string"},
+                    "recorded_at": {"type": "string", "format": "date-time"},
+                },
+                "required": [
+                    "phase",
+                    "status",
+                    "attempt",
+                    "evidence_refs",
+                    "reason",
+                    "recorded_at",
+                ],
+                "additionalProperties": False,
+            },
+        },
+        "route_history": {
+            "type": "array",
+            "description": "Prior selected_route values preserved across re-routes.",
+            "items": {"type": "string"},
+        },
+    },
+    "required": [
+        "schema_version",
+        "task_summary",
+        "selected_route",
+        "evidence",
+        "blocked_by",
+        "next_command",
+        "executed",
+        "chain_status",
+        "phases",
+        "route_history",
+    ],
+    "additionalProperties": True,
+}

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/src/mapify_cli/templates/CLAUDE.md

@@ -70,6 +70,13 @@ When you pipe through `head/tail/less/more`, the source command keeps running bu
 
 **Exception:** Filtering pipes are OK (grep, awk, sed) because they process all input.
 
+### Never pipe a captured variable through `echo`
+
+zsh's builtin `echo` interprets backslash escapes, so piping `echo "$JSON"` into `jq`
+turns the `\n` inside JSON string values into raw control bytes and jq aborts — inside
+`$(...)` the failure is swallowed and the variable lands empty. Use
+`printf '%s' "$VAR" | jq` (or `printf '%s\n'` when a `while read` loop consumes it).
+
 **Full guidelines:** `.claude/references/bash-guidelines.md`
 
 ## Progressive disclosure pointers

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/src/mapify_cli/templates/agents/final-verifier.md

@@ -5,8 +5,21 @@ description: Adversarial verifier with Root Cause Analysis (Ralph Loop)
 # gate before merge — false negatives here ship bugs to production.
 model: opus
 effort: high
-version: 1.1.0
-last_updated: 2026-04-28
+# 2026-08-14 (#424): a final-verifier run edited generated trees and committed
+# them mid-audit, despite the prompt contract being APPROVED/REJECTED-only.
+# Nested Agent is denied at the harness level. Edit/Write are NOT denied here:
+# this agent's own contract requires an in-place append to
+# .map/<branch>/progress_<branch>.md and a `[ ]` -> `[x]` update in the
+# task-plan Acceptance Criteria table — forcing those through whole-file Write
+# would drop surrounding content. The boundary is enforced by scope instead:
+# the safety-guardrails PreToolUse hook keys on agent_type and confines every
+# verifier Edit/Write/MultiEdit to `.map/` (normalized, so `.map/../src` cannot
+# escape) while blocking all git-mutating Bash. Runner-owned state inside
+# `.map/` stays protected for everyone by the workflow-gate tamper detector.
+disallowedTools:
+  - Agent
+version: 1.2.0
+last_updated: 2026-08-14
 ---
 
 # IDENTITY

{mapify_cli-3.25.0/src/mapify_cli/templates → mapify_cli-3.26.0/src/mapify_cli/templates/codex}/hooks/workflow-gate.py

@@ -55,6 +55,21 @@ EDITING_PHASES = {"ACTOR", "APPLY", "TEST_WRITER"}
 DOCS_ONLY_EXTENSIONS = {".md", ".mdx", ".rst", ".txt", ".adoc"}
 DOCS_ONLY_PATH_PREFIXES = ("docs/", "doc/", "documentation/", "CHANGELOG", "RELEASING", "README")
 
+# State-tamper detector (D3): runner-owned MAP state basenames that are
+# never hand-editable directly, even though the blanket `.map/` exemption
+# below (is_exempt_path) would otherwise allow them. Planning artifacts
+# (spec_*, task_plan_*, blueprint.json, research/, code-review-*,
+# compacted/, approval_hold_*.md) are NOT in this set and stay exempt as
+# today — only the runner's own durable state is protected.
+STATE_TAMPER_PROTECTED_BASENAMES = frozenset(
+    {
+        "step_state.json",
+        "approval_holds.json",
+        "auto-route.json",
+        "artifact_manifest.json",
+    }
+)
+
 # TERMINAL_PHASES contains phases where the workflow is considered closed.
 # Edits during COMPLETE are intentionally permissive because:
 #   1. Post-workflow polish (doc tweaks, follow-up review fixes) must not be gated —
@@ -204,6 +219,44 @@ def is_exempt_path(file_path: str) -> bool:
     )
 
 
+def is_state_tamper_path(file_path: str) -> bool:
+    """Return True if *file_path* is runner-owned MAP state protected from
+    direct hand-editing (the state-tamper detector, D3).
+
+    Mirrors is_exempt_path's PROJECT_DIR-relative resolution. Protected
+    under `.map/`:
+      - any path whose second segment is "scripts" (``.map/scripts/**`` —
+        the runner and its helper modules), or
+      - a basename in STATE_TAMPER_PROTECTED_BASENAMES anywhere under
+        `.map/` (branch-scoped durable state: `.map/<branch>/step_state.json`,
+        `approval_holds.json`, `auto-route.json`, `artifact_manifest.json`).
+
+    Everything else under `.map/` (spec_*, task_plan_*, blueprint.json,
+    research/, code-review-*, compacted/, approval_hold_*.md) is left
+    alone by this predicate — it stays exempt via is_exempt_path.
+    """
+    if not isinstance(file_path, str) or not file_path.strip():
+        return False
+
+    candidate = Path(file_path)
+    resolved = (
+        candidate.resolve(strict=False)
+        if candidate.is_absolute()
+        else (PROJECT_DIR / candidate).resolve(strict=False)
+    )
+    try:
+        rel = resolved.relative_to(PROJECT_DIR)
+    except ValueError:
+        return False
+
+    parts = rel.parts
+    if not parts or parts[0] != ".map":
+        return False
+    if len(parts) >= 2 and parts[1] == "scripts":
+        return True
+    return rel.name in STATE_TAMPER_PROTECTED_BASENAMES
+
+
 def sanitize_branch_name(branch: str) -> str:
     """Sanitize branch name for filesystem paths."""
     sanitized = branch.replace("/", "-")
@@ -248,6 +301,27 @@ def _current_phase_is_research(branch: str) -> bool:
     return isinstance(phase, str) and phase.upper() == "RESEARCH"
 
 
+def _is_workflow_active(branch: str) -> bool:
+    """Return True iff a MAP workflow is active on *branch*.
+
+    Active means `.map/<branch>/step_state.json` exists and its
+    `workflow_status` is not `WORKFLOW_COMPLETE`. Scopes the state-tamper
+    detector (D3): outside an active workflow — no step_state.json yet, a
+    corrupt/unreadable one, or a finished workflow — the detector no-ops
+    and today's exempt-path behavior applies unchanged.
+    """
+    step_file = PROJECT_DIR / ".map" / branch / "step_state.json"
+    if not step_file.exists():
+        return False
+    try:
+        with open(step_file, "r", encoding="utf-8") as f:
+            state = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return False
+    status = str(state.get("workflow_status", "")).strip().upper()
+    return status != "WORKFLOW_COMPLETE"
+
+
 def _load_blueprint_subtasks(branch: str) -> list | None:
     """Read blueprint.json subtasks for *branch* (stdlib-only, fail-soft).
 
@@ -510,6 +584,57 @@ def check_constraints(branch: str, target_paths: list[str]) -> str | None:
     return None
 
 
+def _create_safety_guardrail_hold(branch: str, rel_path: str) -> None:
+    """Best-effort creation of a `safety_guardrail` approval hold recording
+    a denied direct edit of runner-owned MAP state.
+
+    INV-4: the caller wraps this call in its own try/except — hold creation
+    is best-effort and must NEVER convert a tamper deny into an allow. Any
+    failure here (missing runner script, non-zero exit, a raised exception)
+    is swallowed by the caller; deny() still fires and the outer fail-open
+    handler is never reached from this path. Idempotency comes from the
+    stable request_summary (naming rel_path) plus create_approval_hold's
+    own dedup-by-(kind, request_summary, pending).
+    """
+    import subprocess
+
+    runner = PROJECT_DIR / ".map" / "scripts" / "map_step_runner.py"
+    reason = (
+        "Runner-owned MAP state must be mutated only through "
+        "map_step_runner.py subcommands; a direct Edit/Write bypasses "
+        "its validation and audit trail."
+    )
+    safe_continuation = (
+        "Revert the direct edit. Use the appropriate "
+        "`python3 .map/scripts/map_step_runner.py` subcommand instead "
+        "(e.g. record_step, create_approval_hold, decide_approval_hold)."
+    )
+    subprocess.run(
+        [
+            sys.executable,
+            str(runner),
+            "create_approval_hold",
+            "--kind",
+            "safety_guardrail",
+            "--reason",
+            reason,
+            "--request-summary",
+            f"Direct edit of runner-owned MAP state: {rel_path}",
+            "--source",
+            "workflow-gate",
+            "--safe-continuation",
+            safe_continuation,
+            "--branch",
+            branch,
+        ],
+        capture_output=True,
+        text=True,
+        cwd=PROJECT_DIR,
+        timeout=5,
+        check=False,
+    )
+
+
 def deny(reason: str) -> None:
     """Print deny response and exit."""
     print(
@@ -541,13 +666,44 @@ def main() -> None:
         if tool_name not in EDITING_TOOLS:
             allow()
 
-        # Exempt paths (.map/, ~/.claude/memory/) → always allow
         target_paths = extract_target_file_paths(tool_call)
+        branch = get_branch_name()
+
+        # State-tamper detector (D3): runner-owned MAP state
+        # (step_state.json, approval_holds.json, auto-route.json,
+        # artifact_manifest.json, and anything under .map/scripts/) is
+        # never hand-editable while a MAP workflow is active on this
+        # branch — even though the blanket `.map/` exemption below would
+        # otherwise allow it. Evaluated BEFORE is_exempt_path
+        # (blocklist-before-allowlist, per the learned security-pattern)
+        # so the exemption cannot mask tampering. A mixed batch (one
+        # protected path alongside ordinary ones) denies as a whole — fail
+        # closed on any protected target.
+        tamper_paths = [p for p in target_paths if is_state_tamper_path(p)]
+        if tamper_paths and _is_workflow_active(branch):
+            attempted = tamper_paths[0]
+            try:
+                attempted = _to_repo_relative(tamper_paths[0]) or tamper_paths[0]
+                _create_safety_guardrail_hold(branch, attempted)
+            except Exception:  # noqa: BLE001, S110 -- INV-4: producer/display-path failure must still reach deny(), never escape to the fail-open outer handler
+                pass
+            deny(
+                "Workflow gate: runner-owned MAP state is not "
+                f"hand-editable ('{attempted}').\n"
+                "This path is written exclusively by "
+                ".map/scripts/map_step_runner.py — use its CLI "
+                "subcommands (create_approval_hold, record_step, "
+                "decide_approval_hold, etc.) instead of editing it "
+                "directly.\n"
+                "A pending safety_guardrail approval hold has been "
+                "recorded for this attempt (best-effort; see "
+                f".map/{branch}/approval_holds.json)."
+            )
+
+        # Exempt paths (.map/, ~/.claude/memory/) → always allow
         if target_paths and all(is_exempt_path(p) for p in target_paths):
             allow()
 
-        branch = get_branch_name()
-
         # Phase check (step_state.json)
         allowed, error = is_editing_phase(branch)
         if not allowed:

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/src/mapify_cli/templates/codex/skills/map-efficient/SKILL.md

@@ -77,6 +77,16 @@ Empty `$TASK_ARGS` is a stop condition only when all of these are true:
 
 Otherwise proceed to resume detection.
 
+## Approval-hold preflight (MANDATORY — run BEFORE Step 0)
+
+Resolve pending approval holds before `resume_from_plan` initializes any execution state — full recipe in [efficient-reference.md](efficient-reference.md#approval-hold-preflight).
+
+```bash
+python3 .map/scripts/map_step_runner.py list_approval_holds --state pending
+```
+
+A pending `plan_approval` requires an explicit operator approve/deny, recorded via `decide_approval_hold <hold-id> <approved|denied> --note "<operator note>"`: approved continues into Step 0, denied STOPS here — revise the plan and re-run `$map-plan` (no staleness re-check); an autonomous chain never reaches this ask because its pre-phase `auto_decide_holds` poll approves `plan_approval` first. A pending `dangerous_action`/`safety_guardrail` hold refuses to proceed instead — surface the hold's `reason` and stop.
+
 ## Step 0: Resume Existing State Or Plan
 
 Run this before validating `$TASK_ARGS`.
@@ -90,7 +100,7 @@ if [ -f "$STATE_FILE" ]; then
   echo "Existing step_state.json found; continuing with get_next_step."
 elif [ -f "$PLAN_FILE" ]; then
   RESUME_RESULT=$(python3 .map/scripts/map_orchestrator.py resume_from_plan)
-  RESUME_STATUS=$(echo "$RESUME_RESULT" | jq -r '.status')
+  RESUME_STATUS=$(printf '%s' "$RESUME_RESULT" | jq -r '.status')
   if [ "$RESUME_STATUS" != "success" ]; then
     echo "resume_from_plan failed: $RESUME_RESULT" >&2
     exit 1
@@ -110,9 +120,9 @@ fi
 
 ```bash
 NEXT_STEP=$(python3 .map/scripts/map_orchestrator.py get_next_step)
-STEP_ID=$(echo "$NEXT_STEP" | jq -r '.step_id')
-PHASE=$(echo "$NEXT_STEP" | jq -r '.phase')
-IS_COMPLETE=$(echo "$NEXT_STEP" | jq -r '.is_complete')
+STEP_ID=$(printf '%s' "$NEXT_STEP" | jq -r '.step_id')
+PHASE=$(printf '%s' "$NEXT_STEP" | jq -r '.phase')
+IS_COMPLETE=$(printf '%s' "$NEXT_STEP" | jq -r '.is_complete')
 echo "$NEXT_STEP"
 ```
 

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/src/mapify_cli/templates/codex/skills/map-efficient/efficient-reference.md

@@ -3,6 +3,45 @@
 This file holds lower-frequency details for the Codex `$map-efficient` skill.
 Load only the section needed by the active phase.
 
+## Approval-Hold Preflight
+
+Resolve any pending approval hold BEFORE Step 0's `resume_from_plan`
+bootstraps execution state — a hold left pending means execution has not
+been explicitly authorized, and a denied plan must stop before any
+`step_state.json` exists.
+
+```bash
+python3 .map/scripts/map_step_runner.py list_approval_holds --state pending
+```
+
+Each pending hold's `kind` decides the branch:
+
+- **`plan_approval`** — the operator must explicitly approve or deny before
+  execution starts:
+  ```bash
+  python3 .map/scripts/map_step_runner.py decide_approval_hold \
+    <hold-id> approved --note "approved by operator; proceeding with plan"
+  # or:
+  python3 .map/scripts/map_step_runner.py decide_approval_hold \
+    <hold-id> denied --note "<why the plan was denied>"
+  ```
+  - **Approved** — continue into the pre-flight test baseline below.
+  - **Denied** — STOP. Tell the operator to revise the plan and re-run
+    `$map-plan`; there is no staleness re-check against the denied blueprint
+    — the operator who denied it is the same operator re-running
+    `$map-efficient`.
+- **`dangerous_action` / `safety_guardrail`** (hard stops) — never decide
+  these from inside the preflight. Refuse to proceed: surface the hold's
+  `reason` and `request_summary`, and stop. The operator resolves the
+  underlying issue out of band and decides the hold via `decide_approval_hold`
+  before retrying.
+
+An autonomous chain never reaches the interactive ask above: its pre-phase
+`auto_decide_holds` poll auto-approves `plan_approval` before `$map-efficient`
+starts, so the preflight here finds nothing pending. If the operator
+already decided the hold manually (CLI) before starting `$map-efficient`, the
+preflight likewise finds nothing pending and proceeds without asking.
+
 ## Pre-Monitor Gates
 
 Before Monitor, verify that Actor output and repository state agree.
@@ -47,7 +86,7 @@ python3 .map/scripts/map_step_runner.py validate_flaky_test_triage
 # Preferred close — the verdict path. Monitor emits valid:false plus
 # disposition {kind: deferred_nondeterministic, check_id: ...}; close 2.4 with
 # the same disposition piped through (see "Verdict-path route" below).
-echo "$MONITOR_JSON" | python3 .map/scripts/map_orchestrator.py \
+printf '%s' "$MONITOR_JSON" | python3 .map/scripts/map_orchestrator.py \
   validate_step 2.4 --disposition deferred_nondeterministic \
   --check-id "pytest::test_name" --monitor-envelope -
 ```

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/src/mapify_cli/templates/codex/skills/map-plan/SKILL.md

@@ -699,9 +699,13 @@ Record artifacts in the manifest:
 ```
 shell_command:
   cmd: |
-    python3 .map/scripts/map_step_runner.py record_plan_artifacts
+    PLAN_ARTIFACTS_RESULT=$(python3 .map/scripts/map_step_runner.py record_plan_artifacts)
+    echo "$PLAN_ARTIFACTS_RESULT"
+    PLAN_APPROVAL_HOLD_ID=$(printf '%s' "$PLAN_ARTIFACTS_RESULT" | jq -r '.plan_approval_hold_id // empty')
 ```
 
+`record_plan_artifacts` also opens a `plan_approval` hold at the plan-ready boundary and returns it as `plan_approval_hold_id` (idempotent — re-running finds the same pending hold instead of spamming a new one). Capture `PLAN_APPROVAL_HOLD_ID` for the Step 8 checkpoint. This hold does **not** block `$map-plan` itself: planning artifacts are written and Step 8 prints its checkpoint regardless of whether the hold is still pending. The decision (`decide_approval_hold <hold-id> approved|denied`) happens later, at the `$map-efficient` approval-hold preflight — or automatically via an autonomous chain's `auto_decide_holds` poll. If the result instead carries `plan_approval_hold_error: true`, the hold store failed — say so in the Step 8 checkpoint and have the operator create/decide the hold manually (`create_approval_hold --kind plan_approval ...`).
+
 ---
 
 ## Step 8: Output Checkpoint
@@ -726,6 +730,7 @@ shell_command:
     echo "[ok] Plan written to .map/${BRANCH}/task_plan_${BRANCH}.md"
     echo "[ok] artifact_manifest.json updated"
     echo "[ok] Mode: [standard | light | deep]"
+    echo "[ok] Plan approval hold: ${PLAN_APPROVAL_HOLD_ID:-none} — decide via decide_approval_hold <hold-id> <approved|denied> --note \"<operator note>\" before \$map-efficient will proceed"
     echo ""
     echo "Next steps:"
     echo "  1. Review .map/${BRANCH}/task_plan_${BRANCH}.md"

{mapify_cli-3.25.0 → mapify_cli-3.26.0}/src/mapify_cli/templates/codex/skills/map-review/SKILL.md

@@ -112,9 +112,21 @@ otherwise) and mode semantics.
 
 ### Step A.1: Gather changes
 
+Diff against the **merge-base with the default branch**, not `HEAD`. On a
+fully-committed branch — the normal `/map-check` → `/map-review` state —
+`git diff HEAD` is empty and under-reports the review scope to zero (#426).
+
 ```bash
-git diff HEAD
-git status
+BASE=""
+for ref in origin/main origin/master main master; do
+  git rev-parse --verify --quiet "$ref" >/dev/null && { BASE="$ref"; break; }
+done
+# No default-branch ref: diff the working tree. NEVER "HEAD...HEAD" — that range
+# is always empty and re-creates the very bug this step fixes.
+[ -n "$BASE" ] && RANGE="$BASE...HEAD" || RANGE="HEAD"
+git --no-pager diff --stat "$RANGE"
+git --no-pager diff "$RANGE"
+git status          # uncommitted work in progress — secondary signal
 ```
 
 ### Step A.1b: Load canonical review context (bundle + handoff)