mapify-cli 3.4.0__tar.gz → 3.5.0__tar.gz

{mapify_cli-3.4.0 → mapify_cli-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.4.0
+Version: 3.5.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

{mapify_cli-3.4.0 → mapify_cli-3.5.0}/pyproject.toml

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

{mapify_cli-3.4.0 → mapify_cli-3.5.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.4.0"
+__version__ = "3.5.0"
 
 import copy
 import os

{mapify_cli-3.4.0 → mapify_cli-3.5.0}/src/mapify_cli/templates/agents/actor.md

@@ -227,6 +227,52 @@ UserService -> register(email, password) -> creates user, returns 201 with JWT
 
 ---
 
+## TDD Mode Support
+
+Actor supports two TDD modes, activated by the `<TDD_Mode>` tag in the prompt:
+
+### TDD Mode: `test_writer`
+
+When `<TDD_Mode>test_writer</TDD_Mode>` is present:
+
+**You write ONLY test files.** No implementation code.
+
+Rules:
+1. Derive tests from the AAG contract, validation_criteria, and test_strategy — NOT from any implementation.
+2. You have NO knowledge of the implementation. Do not assume internal structure, class names, or method signatures beyond what the contract specifies.
+3. Test the PUBLIC interface/behavior described in the contract.
+4. Each `VCn:` validation criterion must have at least one corresponding test.
+5. Include edge cases from the spec's `## Edge Cases` section if available in the packet.
+6. Use standard test patterns for the project's language and framework.
+7. Tests SHOULD fail when run (implementation doesn't exist yet). This is expected.
+
+Output:
+- Test files created via Write tool
+- Evidence file: `.map/<branch>/evidence/test_writer_<subtask_id>.json`
+
+### TDD Mode: `code_only`
+
+When `<TDD_Mode>code_only</TDD_Mode>` is present:
+
+**You write ONLY implementation code.** Test files are READ-ONLY.
+
+Rules:
+1. Read the test files listed in `<TDD_Tests>` FIRST to understand expected behavior.
+2. Do NOT modify, delete, or rename any test file.
+3. Implement the minimum code needed to make ALL existing tests pass.
+4. Follow the AAG contract as your specification.
+5. If a test seems wrong (testing impossible behavior), flag it in trade-offs but still implement to satisfy it. Monitor will catch true test issues.
+
+Output:
+- Implementation files created/modified via Edit/Write tools
+- Standard Actor evidence file
+
+### No TDD Mode (default)
+
+When no `<TDD_Mode>` tag is present, Actor operates in standard mode: write both implementation and tests as described in sections 3-7 below.
+
+---
+
 ## 2. Approach
 Explain solution strategy in 2-3 sentences. Include:
 - Core idea and why this approach

{mapify_cli-3.4.0 → mapify_cli-3.5.0}/src/mapify_cli/templates/agents/task-decomposer.md

@@ -244,6 +244,7 @@ Return **ONLY** valid JSON in this exact structure:
   - `scope`: "function" | "endpoint" | "module"
   - Include when: security_critical OR complexity_score ≥ 5 OR API contracts
   - Omit when: simple CRUD, internal helpers, complexity_score < 5
+  - **Spec invariant linkage**: If a `spec_<branch>.md` file exists with an `## Invariants` section, each contract MUST trace back to at least one spec invariant. Add `"source": "spec-invariant-N"` to link the contract to the invariant it enforces. This ensures no spec invariant is left unguarded by contracts.
 **subtasks[].aag_contract**: REQUIRED one-line contract in `Actor -> Action(params) -> Goal` format
   - This is the primary handoff artifact to the Actor agent
   - Actor "compiles" this contract into code; Monitor verifies against it
@@ -543,6 +544,11 @@ If circular dependency detected (e.g., A→B→C→A):
 - [ ] All assumptions documented that could affect implementation
 - [ ] Open questions flagged that need clarification before proceeding
 
+**Spec Invariant Coverage** (when spec exists):
+- [ ] Read `spec_<branch>.md` if present — check for `## Invariants` section
+- [ ] Each spec invariant is covered by at least one contract across subtasks
+- [ ] Edge cases from spec's `## Edge Cases` section are reflected in validation_criteria
+
 **MCP Tool Usage Verification**:
 - [ ] Did you use insights from MCP tools in your decomposition?
 - [ ] If MCP tools unavailable, documented limitations in analysis

{mapify_cli-3.4.0 → mapify_cli-3.5.0}/src/mapify_cli/templates/commands/map-efficient.md

@@ -59,7 +59,32 @@ Both files must stay in sync. The orchestrator updates `step_state.json` on ever
 └─────────────────────────────────────────────────────────────┘
 ```
 
-**Task:** $ARGUMENTS
+## Flag Parsing
+
+Parse optional flags from `$ARGUMENTS`:
+
+- **`--tdd`**: Enable TDD mode (test-first workflow). Inserts TEST_WRITER and TEST_FAIL_GATE phases before ACTOR. Tests are written from spec before implementation.
+
+```bash
+# Extract flags and clean task description
+TASK_ARGS="$ARGUMENTS"
+TDD_FLAG=false
+if echo "$TASK_ARGS" | grep -q -- '--tdd'; then
+  TDD_FLAG=true
+  TASK_ARGS=$(echo "$TASK_ARGS" | sed 's/--tdd//g' | xargs)
+fi
+```
+
+**Task:** $TASK_ARGS
+
+**IMPORTANT:** Use `$TASK_ARGS` (not `$ARGUMENTS`) in all agent prompts below. The `--tdd` flag has been stripped from `$TASK_ARGS` so it won't leak into task descriptions.
+
+If `--tdd` is detected, enable TDD mode after state initialization:
+```bash
+if [ "$TDD_FLAG" = "true" ]; then
+  python3 .map/scripts/map_orchestrator.py set_tdd_mode true
+fi
+```
 
 ## Step 0: Detect Existing Plan from /map-plan
 
@@ -105,7 +130,7 @@ Task(
   description="Decompose task into subtasks",
   prompt=f"""Break down into ≤20 atomic subtasks and RETURN ONLY JSON.
 
-Task: $ARGUMENTS
+Task: $TASK_ARGS
 
 Hard requirements:
 - Use `blueprint.subtasks[].validation_criteria` (2-4 testable outcomes)
@@ -221,11 +246,18 @@ This is not optional — wave computation must run after every INIT_STATE.
 After INIT_STATE (1.6) completes, compute execution waves from the dependency DAG:
 
 ```bash
-python3 .map/scripts/map_orchestrator.py set_waves --blueprint .map/${BRANCH}/blueprint.json
+BRANCH=$(git rev-parse --abbrev-ref HEAD | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||')
+if [ -f ".map/${BRANCH}/blueprint.json" ]; then
+  python3 .map/scripts/map_orchestrator.py set_waves --blueprint .map/${BRANCH}/blueprint.json
+else
+  echo "WARNING: blueprint.json not found. Running subtasks sequentially."
+  echo "To enable parallel waves, re-run /map-plan (saves blueprint.json since v3.5)."
+fi
 ```
 
 This reads the blueprint, builds a dependency graph, computes topological waves,
 and splits waves by file conflicts. The result is stored in `step_state.json`.
+If `blueprint.json` is missing (e.g., plan was created before v3.5), subtasks execute sequentially — this is safe but slower.
 
 **Wave execution**: If waves are computed, subtasks within a wave run their Actor
 and Monitor phases in parallel. Check wave status with:
@@ -255,6 +287,14 @@ loop:
     for each subtask in WAVE.subtasks:
       build XML_PACKET, run CONTEXT_SEARCH, optional RESEARCH
 
+    # Phase A.5: TDD phases (if --tdd mode)
+    # When TDD is enabled, run TEST_WRITER + TEST_FAIL_GATE per subtask
+    # BEFORE launching Actors. These run sequentially per subtask.
+    if TDD_FLAG:
+      for each subtask in WAVE.subtasks:
+        run TEST_WRITER (2.25) → validate_wave_step SUBTASK_ID "2.25"
+        run TEST_FAIL_GATE (2.26) → validate_wave_step SUBTASK_ID "2.26"
+
     # Phase B: Parallel Actors
     # Launch ALL Task(subagent_type="actor") calls in ONE message
     # Example: Task(actor, "Implement ST-002") + Task(actor, "Implement ST-004")
@@ -322,8 +362,64 @@ This file is the SOLE research artifact passed to Actor and future steps."""
     )
 ```
 
+### Phase: TEST_WRITER (2.25) — TDD Mode Only
+
+Auto-skipped when TDD mode is disabled. When active:
+
+```python
+Task(
+  subagent_type="actor",
+  description="TDD: Write tests for subtask [ID]",
+  prompt=f"""You are in TDD TEST_WRITER mode.
+
+<MAP_Packet subtask="[ID]" v="1.0" risk="[risk_level]">
+[paste from .map/<branch>/current_packet.xml]
+</MAP_Packet>
+
+<MAP_Contract>
+[AAG contract from decomposition]
+</MAP_Contract>
+
+<TDD_Mode>test_writer</TDD_Mode>
+
+STRICT RULES:
+1. Write ONLY test files. Do NOT create or modify implementation files.
+2. Tests must be derived from the SPECIFICATION (AAG contract + validation_criteria).
+3. You have NO knowledge of the implementation.
+4. Each VCn: validation criterion must have at least one corresponding test.
+5. Tests SHOULD fail when run (implementation doesn't exist yet).
+6. Test files MUST be lint-clean. Use proper imports at the top of the file
+   (not inside type annotations). Run the project linter on test files before finishing.
+
+Write evidence: .map/<branch>/evidence/test_writer_<subtask_id>.json"""
+)
+```
+
+### Phase: TEST_FAIL_GATE (2.26) — TDD Mode Only
+
+Auto-skipped when TDD mode is disabled. When active:
+
+**First:** lint-check test files (ACTOR cannot fix them later):
+```bash
+# Lint ONLY the test files from TEST_WRITER evidence
+ruff check <test_files> 2>&1 || true
+# If lint errors → go back to TEST_WRITER with feedback to fix lint
+```
+
+**Then:** run the tests — they MUST fail:
+```bash
+# Run tests — expect failures (Red phase)
+pytest --tb=short 2>&1 || true
+# If tests PASS → go back to TEST_WRITER (tests are trivial)
+# If tests FAIL with assertion errors → proceed to ACTOR (expected TDD state)
+```
+
+Write evidence: `.map/<branch>/evidence/test_fail_gate_<subtask_id>.json`
+
 ### Phase: ACTOR (2.3)
 
+When TDD mode is active, Actor receives `<TDD_Mode>code_only</TDD_Mode>` and must NOT modify test files. When TDD is off, standard behavior.
+
 ```python
 Task(
   subagent_type="actor",
@@ -527,10 +623,16 @@ Question 2: For EACH subtask, did I:
   - Run linter gate? [YES/NO per subtask]
 Answer: [List each subtask and answers]
 
-Question 3: Did I ever write code directly without Actor?
+Question 3: (TDD mode only) For EACH subtask, did I:
+  - Call TEST_WRITER before Actor? [YES/NO/N/A per subtask]
+  - Verify tests failed at TEST_FAIL_GATE? [YES/NO/N/A per subtask]
+  - Use code_only mode for Actor (no test modifications)? [YES/NO/N/A]
+Answer: [List answers, or N/A if TDD mode is not active]
+
+Question 4: Did I ever write code directly without Actor?
 Answer: [YES/NO - if YES, this is a VIOLATION]
 
-Question 4: Did I output CHECKPOINT blocks before agent calls?
+Question 5: Did I output CHECKPOINT blocks before agent calls?
 Answer: [YES/NO - if NO, add them now]
 
 EVALUATION: [PASSED/FAILED]

{mapify_cli-3.4.0 → mapify_cli-3.5.0}/src/mapify_cli/templates/commands/map-plan.md

@@ -106,7 +106,7 @@ Read the user's requirements and decide if deep interview is needed.
 - Small isolated change (single bug fix, test update)
 - User explicitly provided a spec or detailed description
 
-If interview is not needed, skip to Step 3.
+If interview is not needed, skip to Step 2a (write spec without interview).
 
 ### Step 2: Deep Interview (Spec Discovery)
 
@@ -169,6 +169,45 @@ AskUserQuestion(questions=[
 | 1 | Token storage | Server-side (Redis) | Need revocation support |
 | 2 | Session expiry UX | Silent refresh | Better UX, no data loss |
 
+## Invariants
+
+Conditions that MUST remain true throughout implementation and after deployment.
+These are hard constraints — violating any invariant is a blocker.
+
+- [e.g., "All API endpoints require authentication except /health and /login"]
+- [e.g., "Database migrations must be backward-compatible (no column drops)"]
+- [e.g., "Response time for any endpoint must stay under 500ms p95"]
+
+## Edge Cases
+
+Enumerate boundary conditions and unusual inputs that implementation must handle.
+
+| # | Edge Case | Expected Behavior | Priority |
+|---|-----------|-------------------|----------|
+| 1 | [e.g., Empty input array] | [Return empty result, not error] | must-handle |
+| 2 | [e.g., Concurrent updates to same resource] | [Last-write-wins with conflict detection] | must-handle |
+| 3 | [e.g., Unicode in usernames] | [Accept, normalize to NFC] | should-handle |
+
+Priority levels: `must-handle` (blocks release), `should-handle` (best effort), `won't-handle` (documented limitation).
+
+## Acceptance Criteria
+
+Formal, testable conditions that define "done". Each criterion must be verifiable by automated test or manual check.
+
+| ID | Criterion | Verification Method |
+|----|-----------|-------------------|
+| AC-1 | [e.g., User can log in with valid credentials] | `pytest tests/test_auth.py::test_login` |
+| AC-2 | [e.g., Invalid token returns 401] | `pytest tests/test_auth.py::test_invalid_token` |
+
+## Security Boundaries
+
+*(Include for security-critical tasks; omit for purely internal/cosmetic changes)*
+
+- **Trust boundary:** [e.g., "All user input is untrusted; validate at API layer"]
+- **Auth model:** [e.g., "RBAC with role checks at service layer, not just route level"]
+- **Data sensitivity:** [e.g., "PII fields encrypted at rest, never logged"]
+- **Attack surface:** [e.g., "Public API exposed to internet; internal services behind VPN"]
+
 ## Out of Scope
 
 - [Explicitly excluded items]
@@ -178,6 +217,54 @@ AskUserQuestion(questions=[
 - [Anything still unresolved]
 ```
 
+### Step 2a: Write Spec (when interview was skipped)
+
+If interview was skipped (task is well-defined), still write `spec_<branch>.md` using the same template as Step 2. Populate it from the user's requirements and discovery findings:
+
+- **Decisions Made**: extract from user's request (may be short or N/A)
+- **Invariants**: derive from existing code patterns found in discovery
+- **Edge Cases**: identify from the task description and affected code
+- **Acceptance Criteria**: REQUIRED — must be testable conditions that define "done"
+- **Security Boundaries**: include if task touches auth/validation/user input
+- **Out of Scope**: explicitly state what is NOT being changed
+
+This ensures every `/map-plan` run produces a spec, regardless of whether interview happened.
+
+### Step 2b: Devil's Advocate Review (SPEC_REVIEW)
+
+**Skip if:** complexity < 5 (simple, well-defined tasks).
+
+After writing the spec, invoke Monitor agent to adversarially review it. The goal is to surface gaps, contradictions, and missing edge cases BEFORE decomposition.
+
+```
+Task(
+  subagent_type="monitor",
+  description="Devil's Advocate spec review",
+  prompt=f"""You are reviewing a SPECIFICATION (not code). Act as Devil's Advocate.
+
+Read the spec file: .map/<branch>/spec_<branch>.md
+
+Check for:
+1. **Race conditions / concurrency gaps**: Are there shared resources without defined conflict resolution?
+2. **Ownership ambiguity**: Are responsibilities clearly assigned? Could two components both assume the other handles something?
+3. **Missing edge cases**: Compare the Edge Cases section against Invariants — are there invariant violations not covered by edge cases?
+4. **Contradictions**: Do any decisions contradict invariants or acceptance criteria?
+5. **Security gaps**: Are trust boundaries complete? Are there injection vectors not addressed?
+6. **Implicit assumptions**: What is assumed but not stated?
+
+Output format:
+- For each finding: severity (HIGH/MEDIUM/LOW), category, description, suggested fix
+- If NO high-severity issues found: output "SPEC APPROVED"
+- If HIGH-severity issues found: list them clearly for user resolution
+"""
+)
+```
+
+**After Devil's Advocate review:**
+- If **SPEC APPROVED** (no HIGH-severity findings): proceed to Step 3.
+- If **HIGH-severity findings**: present them to the user via AskUserQuestion. Update the spec with resolutions before proceeding. Do NOT silently proceed past HIGH findings.
+- MEDIUM/LOW findings: note them in the spec's Open Questions section but proceed.
+
 ### Step 3: Create Branch Directory
 
 ```bash
@@ -238,6 +325,32 @@ Output requirements:
 )
 ```
 
+### Step 5.5: Save Blueprint JSON
+
+Save the raw decomposer output as `.map/<branch>/blueprint.json` using the **Write** tool. This file is required by `/map-efficient` for wave computation (`set_waves`).
+
+The blueprint JSON must include at minimum:
+```json
+{
+  "summary": "<goal description>",
+  "subtasks": [
+    {
+      "id": "ST-001",
+      "title": "<title>",
+      "aag_contract": "Actor -> Action(params) -> Goal",
+      "dependencies": [],
+      "affected_files": ["path/to/file.py"],
+      "complexity_score": 5,
+      "risk_level": "medium",
+      "validation_criteria": ["VC1: ...", "VC2: ..."],
+      "test_strategy": {"unit": ["test description"]}
+    }
+  ]
+}
+```
+
+If the decomposer returned structured JSON, save it directly. If it returned markdown, construct the JSON from the decomposed subtasks. **This step is mandatory** — without `blueprint.json`, `/map-efficient` cannot compute parallel execution waves.
+
 ### Step 6: Create Human-Readable Plan
 
 Write the plan to `.map/<branch>/task_plan_<branch>.md` using the **Write** tool. Wrap content in `<MAP_Plan_v1_0>` semantic brackets for machine-parseable handoff to executors.
@@ -332,6 +445,7 @@ WORKFLOW CHECKPOINT: PLAN PHASE COMPLETE
 ✅ Deep interview completed (N decisions captured)
 ✅ Architecture graph written to spec_${BRANCH}.md
 ✅ Task decomposed into N subtasks with AAG contracts
+✅ Blueprint saved to .map/${BRANCH}/blueprint.json
 ✅ workflow_state.json initialized (with aag_contracts map)
 ✅ Plan written to .map/${BRANCH}/task_plan_${BRANCH}.md
 ✅ Context distilled (plan files ≤4000 tokens per subtask)

{mapify_cli-3.4.0 → mapify_cli-3.5.0}/src/mapify_cli/templates/commands/map-resume.md

@@ -21,10 +21,12 @@ description: Resume incomplete MAP workflow from checkpoint
 6. Continues from the last incomplete step via the state machine
 
 **State files used:**
-- **`step_state.json`** — Orchestrator canonical state. Source of truth for resumption. Tracks current step, retry counts, circuit breaker status.
+- **`step_state.json`** — Orchestrator canonical state. Source of truth for resumption. Tracks current step, retry counts, circuit breaker status. Includes `tdd_mode` field (persisted across sessions).
 - **`workflow_state.json`** — Enforcement gates. Tracks subtask completion for workflow-gate.py hook.
 - **`task_plan_<branch>.md`** — Full task decomposition with validation criteria and AAG contracts.
 
+**TDD mode note:** If the interrupted workflow was using `/map-tdd` or `--tdd` flag, `tdd_mode: true` is preserved in `step_state.json`. The TDD phases (TEST_WRITER, TEST_FAIL_GATE) will be correctly included in the resumed workflow. No manual re-enablement is needed when resuming from `step_state.json`.
+
 ---
 
 ## Step 1: Detect Checkpoint

mapify_cli-3.5.0/src/mapify_cli/templates/commands/map-task.md

@@ -0,0 +1,214 @@
+---
+description: Execute a single subtask from an existing plan
+---
+
+# /map-task — Single Subtask Execution
+
+**Purpose:** Execute one specific subtask from an existing plan, without running the full workflow.
+
+**When to use:**
+- After `/map-plan` has created a decomposition — pick and run one subtask
+- When you want fine-grained control over execution order
+- When resuming work on a specific subtask after context reset
+- When parallelizing subtasks across multiple sessions
+
+**Prerequisites:** A plan must exist (`.map/<branch>/task_plan_<branch>.md`). Run `/map-plan` first if needed.
+
+**Task:** $ARGUMENTS
+
+---
+
+## Step 0: Parse Arguments
+
+Extract the subtask ID from `$ARGUMENTS`:
+
+```bash
+SUBTASK_ID=$(echo "$ARGUMENTS" | grep -oE 'ST-[0-9]+' | head -1)
+if [ -z "$SUBTASK_ID" ]; then
+  echo "ERROR: No subtask ID found. Usage: /map-task ST-001"
+  exit 1
+fi
+```
+
+## Step 1: Initialize Single Subtask
+
+```bash
+BRANCH=$(git rev-parse --abbrev-ref HEAD | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||')
+
+# Set up state for single subtask execution
+RESULT=$(python3 .map/scripts/map_orchestrator.py resume_single_subtask "$SUBTASK_ID")
+STATUS=$(echo "$RESULT" | jq -r '.status')
+
+if [ "$STATUS" = "error" ]; then
+  echo "$RESULT" | jq -r '.message'
+  exit 1
+fi
+```
+
+**If error mentions "No plan found":** Run `/map-plan` first to create a decomposition.
+**If error mentions "not found in plan":** The output lists available subtask IDs — pick one.
+
+## Step 2: Load Subtask Context
+
+Read the plan to get the subtask's details:
+
+```bash
+BRANCH=$(git rev-parse --abbrev-ref HEAD | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|g; s|-{2,}|-|g; s|^-||; s|-$||')
+# Read: .map/${BRANCH}/task_plan_${BRANCH}.md — find the ### ${SUBTASK_ID} section
+# Read: .map/${BRANCH}/blueprint.json — get AAG contract, validation_criteria, dependencies
+```
+
+Display a brief summary:
+
+```text
+═══════════════════════════════════════════════════
+SINGLE SUBTASK EXECUTION
+═══════════════════════════════════════════════════
+Subtask: ${SUBTASK_ID}
+Title: <from plan>
+AAG Contract: <from blueprint>
+Risk: <from blueprint>
+Dependencies: <from blueprint>
+═══════════════════════════════════════════════════
+```
+
+## Step 3: State Machine Loop
+
+Follow the same state machine loop as `/map-efficient`. Call `get_next_step` and execute based on the returned phase.
+
+```bash
+NEXT_STEP=$(python3 .map/scripts/map_orchestrator.py get_next_step)
+PHASE=$(echo "$NEXT_STEP" | jq -r '.phase')
+```
+
+Route to the appropriate executor based on `$PHASE`. All phases from `/map-efficient` work identically:
+
+- **XML_PACKET (2.0)** — Build XML packet for this subtask
+- **CONTEXT_SEARCH (2.1)** — Search for relevant patterns
+- **RESEARCH (2.2)** — Call research-agent if needed
+- **ACTOR (2.3)** — Implement the subtask
+- **MONITOR (2.4)** — Validate implementation
+- **PREDICTOR (2.6)** — Impact analysis (conditional)
+- **UPDATE_STATE (2.7)** — Mark progress
+- **TESTS_GATE (2.8)** — Run tests
+- **LINTER_GATE (2.9)** — Run linter
+- **VERIFY_ADHERENCE (2.10)** — Self-audit
+
+For each step:
+1. Get next step from orchestrator
+2. Execute the phase (same handlers as map-efficient)
+3. Validate: `python3 .map/scripts/map_orchestrator.py validate_step "$STEP_ID"`
+4. Continue to next step until complete
+
+**If Monitor returns `valid: false`:**
+- Retry Actor with feedback (max 5 iterations)
+
+## Step 4: Completion and Progress Report
+
+When `get_next_step` returns `is_complete: true`:
+
+1. Update the plan status:
+```bash
+python3 .map/scripts/map_step_runner.py update_plan_status "${SUBTASK_ID}" "complete"
+```
+
+2. Get overall plan progress:
+```bash
+PROGRESS=$(python3 .map/scripts/map_orchestrator.py get_plan_progress)
+TOTAL=$(echo "$PROGRESS" | jq -r '.total')
+DONE=$(echo "$PROGRESS" | jq -r '.completed_count')
+REMAINING=$(echo "$PROGRESS" | jq -r '.pending_count')
+SUGGESTED=$(echo "$PROGRESS" | jq -r '.suggested_next')
+```
+
+3. Display completion report with remaining subtasks:
+
+```text
+═══════════════════════════════════════════════════
+SUBTASK COMPLETE
+═══════════════════════════════════════════════════
+Subtask: ${SUBTASK_ID}
+Title: <title>
+Status: COMPLETE
+
+Files Modified:
+  - <list of changed files>
+
+───────────────────────────────────────────────────
+PLAN PROGRESS: ${DONE}/${TOTAL} subtasks complete
+───────────────────────────────────────────────────
+
+Completed:
+  ✓ ST-001: <title>
+  ✓ ST-002: <title>  ← just completed
+
+Remaining:
+  ○ ST-003: <title> (pending)
+  ○ ST-004: <title> (pending)
+
+═══════════════════════════════════════════════════
+```
+
+4. **Suggest next subtask** using AskUserQuestion:
+
+```
+AskUserQuestion(questions=[
+  {
+    "question": "What would you like to do next?",
+    "header": "Next subtask",
+    "options": [
+      {"label": "/map-task ${SUGGESTED}", "description": "Execute next subtask: <title>"},
+      {"label": "/map-tdd ${SUGGESTED}", "description": "TDD for next subtask: <title>"},
+      {"label": "Done for now", "description": "Stop here, continue later with /map-task"}
+    ],
+    "multiSelect": false
+  }
+])
+```
+
+**If all subtasks are complete** (REMAINING == 0), skip the question and show:
+
+```text
+═══════════════════════════════════════════════════
+ALL SUBTASKS COMPLETE (${TOTAL}/${TOTAL})
+═══════════════════════════════════════════════════
+
+Run /map-check for final verification, or /map-learn to extract patterns.
+```
+
+---
+
+## Error Handling
+
+### No Plan Exists
+
+```text
+No plan found. Run /map-plan first to create a task decomposition,
+then use /map-task ST-001 to execute individual subtasks.
+```
+
+### Subtask Not in Plan
+
+```text
+Subtask ST-999 not found in plan.
+Available subtasks: ST-001, ST-002, ST-003
+```
+
+### Dependencies Not Met
+
+Check blueprint for dependencies. If the subtask depends on unfinished work, warn:
+
+```text
+WARNING: ${SUBTASK_ID} depends on ${DEP_ID} which may not be complete.
+Proceed anyway? (The Actor will work with whatever state exists.)
+```
+
+---
+
+## Related Commands
+
+- **/map-plan** — Create task decomposition (prerequisite)
+- **/map-efficient** — Run full workflow (all subtasks)
+- **/map-tdd ST-001** — Write tests for a specific subtask (TDD mode)
+- **/map-resume** — Resume interrupted workflow from checkpoint
+- **/map-check** — Verify all acceptance criteria