mapify-cli 3.7.0__tar.gz → 3.8.0__tar.gz

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.7.0
+Version: 3.8.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
@@ -87,17 +87,21 @@ claude
 | `/map-tdd` | Test-first implementation workflow |
 | `/map-release` | Package release workflow |
 | `/map-resume` | Resume interrupted workflows |
-| `/map-learn` | Extract lessons after workflow completion |
+| `/map-learn` | Extract lessons after workflow completion; optional `[workflow-summary]` |
 
 [Detailed usage and options →](docs/USAGE.md)
 
 Canonical MAP flows:
 
-- Standard: `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review`
-- Full TDD: `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review`
-- Targeted subtask TDD: `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review`
+- Standard: `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review` -> `/map-learn` (when you want to pay the learning cost)
+- Full TDD: `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review` -> `/map-learn`
+- Targeted subtask TDD: `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review` -> `/map-learn`
 
-These workflows maintain branch-scoped artifacts like `code-review-001.md`, `qa-001.md`, `verification-summary.md`, `pr-draft.md`, and run dossiers under `.map/<branch>/`.
+`/map-plan` now records a workflow-fit decision first, so trivial work can exit early with a direct edit or `/map-fast` recommendation instead of forcing full MAP planning.
+
+These workflows maintain branch-scoped artifacts like `code-review-001.md`, `qa-001.md`, `verification-summary.md`, `pr-draft.md`, `artifact_manifest.json`, and run dossiers under `.map/<branch>/`. Targeted TDD flows also persist `test_contract_ST-00N.md` and `test_handoff_ST-00N.json` so `/map-task` can resume implementation from a clean red-phase handoff.
+
+`LEARN` is still the philosophical end of the MAP cycle, but runtime keeps it soft: `/map-efficient`, `/map-debug`, `/map-check`, and `/map-review` now write `learning-handoff.md` / `.json` under `.map/<branch>/`, so `/map-learn [workflow-summary]` can run immediately with an explicit summary or later with no argument by auto-loading the generated handoff.
 
 ## How It Works
 

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/README.md

@@ -55,17 +55,21 @@ claude
 | `/map-tdd` | Test-first implementation workflow |
 | `/map-release` | Package release workflow |
 | `/map-resume` | Resume interrupted workflows |
-| `/map-learn` | Extract lessons after workflow completion |
+| `/map-learn` | Extract lessons after workflow completion; optional `[workflow-summary]` |
 
 [Detailed usage and options →](docs/USAGE.md)
 
 Canonical MAP flows:
 
-- Standard: `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review`
-- Full TDD: `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review`
-- Targeted subtask TDD: `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review`
+- Standard: `/map-plan` -> `/map-efficient` -> `/map-check` -> `/map-review` -> `/map-learn` (when you want to pay the learning cost)
+- Full TDD: `/map-plan` -> `/map-tdd` -> `/map-check` -> `/map-review` -> `/map-learn`
+- Targeted subtask TDD: `/map-plan` -> `/map-tdd ST-001` -> `/map-task ST-001` -> ... -> `/map-check` -> `/map-review` -> `/map-learn`
 
-These workflows maintain branch-scoped artifacts like `code-review-001.md`, `qa-001.md`, `verification-summary.md`, `pr-draft.md`, and run dossiers under `.map/<branch>/`.
+`/map-plan` now records a workflow-fit decision first, so trivial work can exit early with a direct edit or `/map-fast` recommendation instead of forcing full MAP planning.
+
+These workflows maintain branch-scoped artifacts like `code-review-001.md`, `qa-001.md`, `verification-summary.md`, `pr-draft.md`, `artifact_manifest.json`, and run dossiers under `.map/<branch>/`. Targeted TDD flows also persist `test_contract_ST-00N.md` and `test_handoff_ST-00N.json` so `/map-task` can resume implementation from a clean red-phase handoff.
+
+`LEARN` is still the philosophical end of the MAP cycle, but runtime keeps it soft: `/map-efficient`, `/map-debug`, `/map-check`, and `/map-review` now write `learning-handoff.md` / `.json` under `.map/<branch>/`, so `/map-learn [workflow-summary]` can run immediately with an explicit summary or later with no argument by auto-loading the generated handoff.
 
 ## How It Works
 

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/pyproject.toml

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

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.7.0"
+__version__ = "3.8.0"
 
 import os
 import subprocess

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/delivery/file_copier.py

@@ -184,16 +184,6 @@ $ARGUMENTS
 
 Implement quickly with basic monitor validation only. No learning, no predictor.
     Use for small, low-risk changes where speed matters.
-""",
-            "map-learn": """---
-description: Extract lessons from completed workflows
----
-
-Extract and preserve lessons from recent workflow:
-
-$ARGUMENTS
-
-Call Reflector to extract patterns from recent workflow.
 """,
         }
 
@@ -315,10 +305,13 @@ This directory contains custom slash commands for Claude Code.
 - `/map-review` - Run a structured review workflow
 - `/map-check` - Run workflow quality gates and verification
 - `/map-fast` - Quick implementation with minimal validation
-- `/map-learn` - Extract lessons from completed workflows
 - `/map-release` - Execute MAP Framework package release workflow
 - `/map-resume` - Resume an interrupted workflow from `.map/`
 
+## Skill-Backed Slash Surfaces
+
+- `/map-learn` - Extract lessons from completed workflows (implemented via `.claude/skills/map-learn/SKILL.md`)
+
 ## Creating Custom Commands
 
 Create a new `.md` file in this directory with the following format:

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/schemas.py

@@ -464,3 +464,159 @@ REPO_INSIGHT_SCHEMA = {
     "required": ["language", "suggested_checks", "key_dirs"],
     "additionalProperties": True,
 }
+
+
+WORKFLOW_FIT_DECISION_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/workflow-fit-decision.json",
+    "title": "MAP Workflow Fit Decision",
+    "description": "Preflight workflow-fit decision stored in .map/<branch>/workflow-fit.json",
+    "type": "object",
+    "properties": {
+        "version": {"type": "string"},
+        "recommended_workflow": {
+            "type": "string",
+            "enum": [
+                "direct-edit",
+                "map-fast",
+                "map-efficient",
+                "map-tdd",
+                "map-plan",
+            ],
+        },
+        "needs_map": {"type": "boolean"},
+        "decision_summary": {"type": "string"},
+        "signals": {
+            "type": "object",
+            "properties": {
+                "expected_diff_size": {
+                    "type": "string",
+                    "enum": ["tiny", "small", "medium", "large"],
+                },
+                "has_new_invariants": {"type": "boolean"},
+                "needs_independent_review": {"type": "boolean"},
+                "has_clear_acceptance_criteria": {"type": "boolean"},
+                "test_first_required": {"type": "boolean"},
+            },
+            "required": [
+                "expected_diff_size",
+                "has_new_invariants",
+                "needs_independent_review",
+                "has_clear_acceptance_criteria",
+                "test_first_required",
+            ],
+            "additionalProperties": False,
+        },
+        "updated_at": {"type": "string", "format": "date-time"},
+    },
+    "required": [
+        "version",
+        "recommended_workflow",
+        "needs_map",
+        "decision_summary",
+        "signals",
+        "updated_at",
+    ],
+    "additionalProperties": False,
+}
+
+
+ARTIFACT_STAGE_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/artifact-stage.json",
+    "title": "MAP Artifact Stage",
+    "description": "One stage entry inside artifact_manifest.json",
+    "type": "object",
+    "properties": {
+        "status": {"type": "string"},
+        "updated_at": {"type": "string", "format": "date-time"},
+        "artifacts": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "kind": {"type": "string"},
+                },
+                "required": ["path", "kind"],
+                "additionalProperties": False,
+            },
+        },
+        "metadata": {"type": "object"},
+    },
+    "required": ["status", "updated_at", "artifacts", "metadata"],
+    "additionalProperties": False,
+}
+
+
+ARTIFACT_MANIFEST_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/artifact-manifest.json",
+    "title": "MAP Artifact Manifest",
+    "description": "Branch-scoped artifact manifest stored in .map/<branch>/artifact_manifest.json",
+    "type": "object",
+    "properties": {
+        "schema_version": {"type": "string"},
+        "branch": {"type": "string"},
+        "updated_at": {"type": "string", "format": "date-time"},
+        "stages": {
+            "type": "object",
+            "properties": {
+                "workflow_fit": ARTIFACT_STAGE_SCHEMA,
+                "spec": ARTIFACT_STAGE_SCHEMA,
+                "plan": ARTIFACT_STAGE_SCHEMA,
+                "test_contract": ARTIFACT_STAGE_SCHEMA,
+                "implementation": ARTIFACT_STAGE_SCHEMA,
+                "review": ARTIFACT_STAGE_SCHEMA,
+                "verification": ARTIFACT_STAGE_SCHEMA,
+                "learn_handoff": ARTIFACT_STAGE_SCHEMA,
+            },
+            "required": [
+                "workflow_fit",
+                "spec",
+                "plan",
+                "test_contract",
+                "implementation",
+                "review",
+                "verification",
+                "learn_handoff",
+            ],
+            "additionalProperties": False,
+        },
+    },
+    "required": ["schema_version", "branch", "updated_at", "stages"],
+    "additionalProperties": False,
+}
+
+
+TEST_HANDOFF_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/test-handoff.json",
+    "title": "MAP Test Handoff",
+    "description": "Persisted TDD handoff stored in .map/<branch>/test_handoff_<subtask>.json",
+    "type": "object",
+    "properties": {
+        "subtask_id": {"type": "string"},
+        "status": {"type": "string", "enum": ["contract_ready"]},
+        "contract_path": {"type": "string"},
+        "failing_test_command": {"type": ["string", "null"]},
+        "test_files": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+        "contract_summary": {"type": "string"},
+        "notes": {"type": "string"},
+        "updated_at": {"type": "string", "format": "date-time"},
+    },
+    "required": [
+        "subtask_id",
+        "status",
+        "contract_path",
+        "failing_test_command",
+        "test_files",
+        "contract_summary",
+        "notes",
+        "updated_at",
+    ],
+    "additionalProperties": False,
+}

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/templates/commands/map-check.md

@@ -338,6 +338,19 @@ python3 .map/scripts/map_step_runner.py write_pr_draft "$SUMMARY" "$VALIDATION"
 This ensures `pr-draft.md` is built from actual workflow artifacts instead of freeform memory.
 It also means `/map-review` can consume a single consolidated verification handoff instead of re-deriving the branch state from scratch.
 
+Then write the deferred learning handoff so the philosophical `LEARN` stage stays cheap at runtime:
+
+```bash
+python3 .map/scripts/map_step_runner.py write_learning_handoff \
+  map-check \
+  "<task title>" \
+  "READY FOR REVIEW|NEEDS WORK" \
+  "<run /map-review next, or rework and rerun /map-check>" \
+  "<optional verification note>"
+```
+
+This writes `.map/<branch>/learning-handoff.md` and `.json`, updates `artifact_manifest.json`, and lets `/map-learn` auto-load the workflow context later with no manual reconstruction.
+
 Recommended format:
 
 ```markdown

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/templates/commands/map-debug.md

@@ -208,6 +208,18 @@ If evaluator recommends proceeding:
 - Apply code changes using Write/Edit tools
 - Run tests to verify fix
 - Check that original issue is resolved
+- Write a deferred learning handoff so `/map-learn` can reuse the debug context later:
+
+```bash
+python3 .map/scripts/map_step_runner.py write_learning_handoff \
+  map-debug \
+  "$ARGUMENTS" \
+  "Debugging workflow complete" \
+  "Ship the fix, or run /map-review if you want independent scrutiny" \
+  "<root cause + fix summary>"
+```
+
+This writes `.map/<branch>/learning-handoff.md` and `.json`, updates `artifact_manifest.json`, and keeps post-debug learning cheap.
 
 ## Step 4: Verification
 
@@ -225,9 +237,7 @@ After all fixes applied:
 **If you want to save debugging patterns for future use:**
 
 ```
-/map-learn Debugged [issue description]. Root cause: [cause].
-Fix: [summary]. Prevention strategies: [list].
-Files changed: [files]. Iterations: [count].
+/map-learn
 ```
 
 This is **completely optional**. Run it when debugging patterns are valuable for future reference.

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/templates/commands/map-efficient.md

@@ -77,6 +77,7 @@ Branch-scoped markdown artifacts in `.map/<branch>/`:
 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.
+- If you need a persisted clean-session handoff between tests and implementation, prefer `/map-tdd ST-001` and then resume with `/map-task ST-001`.
 
 ```bash
 # Extract flags and clean task description
@@ -419,6 +420,8 @@ pytest --tb=short 2>&1 || true
 # If tests FAIL with assertion errors → proceed to ACTOR (expected TDD state)
 ```
 
+If you want to stop after the red phase and resume implementation in a clean session, persist `test_contract_<subtask>.md` + `test_handoff_<subtask>.json` via `/map-tdd ST-001`, then continue later with `/map-task ST-001`.
+
 ### 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.
@@ -786,6 +789,19 @@ Also update `.map/<branch>/pr-draft.md` with:
 
 Update `.map/<branch>/pr-draft.md` with final summary and verification results.
 
+Then write the deferred learning handoff so `LEARN` remains part of the philosophy without paying Reflector cost inline:
+
+```bash
+python3 .map/scripts/map_step_runner.py write_learning_handoff \
+  map-efficient \
+  "<task title>" \
+  "READY FOR REVIEW" \
+  "Run /map-review next, or defer /map-learn until you want to preserve patterns" \
+  "<optional implementation note>"
+```
+
+This writes `.map/<branch>/learning-handoff.md` and `.json`, updates `artifact_manifest.json`, and lets `/map-learn` auto-load the workflow context later.
+
 ### 3.3 Evaluate Results
 
 ```python
@@ -817,6 +833,7 @@ else:
 
 - Update Terminal State in task_plan: **Status:** complete
 - Report features implemented, files changed, verification confidence
-- **Optional:** Run `/map-learn [summary]` to preserve patterns
+- `learning-handoff.md` / `.json` should already be written for deferred learning
+- **Optional:** Run `/map-learn` now, or batch it later when the workflow is worth preserving
 
 Begin execution now.

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/templates/commands/map-plan.md

@@ -8,10 +8,12 @@
 - Want to establish clear task boundaries before execution
 
 **What this command does:**
+- Records a workflow-fit decision before planning so trivial work can exit early
 - Optionally runs a short discovery pass (research-agent) to identify key files/patterns
 - Calls task-decomposer agent to break down the user's request into subtasks
 - Creates `.map/<branch>/task_plan_<branch>.md` with subtask list
 - Initializes `.map/<branch>/step_state.json` with subtask sequence
+- Updates `.map/<branch>/artifact_manifest.json` with the planning artifacts
 - **STOPS** after planning (forces context flush)
 
 **What this command CANNOT do:**
@@ -43,6 +45,35 @@ echo "state:       $(test -f .map/${BRANCH}/step_state.json && echo EXISTS || ec
 
 This prevents redundant work when the user restarts Claude mid-plan.
 
+### Pre-flight: Workflow-Fit Gate
+
+Before discovery or interview, decide whether MAP planning is actually warranted for this task.
+
+Assess these signals explicitly:
+- `expected_diff_size`: `tiny` / `small` / `medium` / `large`
+- `has_new_invariants`: does the task introduce or change domain model / contracts / schema rules?
+- `needs_independent_review`: would this change be risky enough that independent review should be required?
+- `has_clear_acceptance_criteria`: can the task already be executed without a planning pass?
+- `test_first_required`: should later implementation use TDD because the behavior contract matters more than code speed?
+
+For `/map-plan`, pick one of these outcomes:
+- `direct-edit` — tiny, isolated work with clear acceptance criteria and no new invariants
+- `map-fast` — small bounded change where MAP planning overhead is not justified
+- `map-plan` — non-trivial work that should go through `SPEC + PLAN` before execution
+
+Persist the decision:
+
+```bash
+python3 .map/scripts/map_step_runner.py record_workflow_fit "<direct-edit|map-fast|map-plan>" "<tiny|small|medium|large>" "<true|false>" "<true|false>" "<true|false>" "<true|false>" "<one-sentence decision summary>"
+```
+
+**Decision rules:**
+- If the outcome is `direct-edit`: print a short off-ramp message explaining MAP is not needed and STOP.
+- If the outcome is `map-fast`: recommend `/map-fast` and STOP.
+- If the outcome is `map-plan`: continue with the steps below.
+
+This is not a black box. The decision summary must state which signal(s) forced planning or justified the off-ramp.
+
 ### Step 0: Quick Discovery (Optional but Recommended)
 
 **IMPORTANT — Check for existing discovery first:**
@@ -566,6 +597,12 @@ Use the **Write** tool to create `.map/<branch>/step_state.json` with this struc
 - Populate `aag_contracts` map with each subtask's AAG contract from the decomposer output — executors read this to set context for each subtask
 - Populate `constraints` from the spec's Constraints section. null = unlimited (hook skips enforcement)
 
+After writing `spec_<branch>.md`, `task_plan_<branch>.md`, `blueprint.json`, and `step_state.json`, record them in the artifact manifest:
+
+```bash
+python3 .map/scripts/map_step_runner.py record_plan_artifacts
+```
+
 ### Step 8: Output Checkpoint
 
 Print a clear checkpoint showing the plan is complete:
@@ -582,6 +619,7 @@ WORKFLOW CHECKPOINT: PLAN PHASE COMPLETE
 ✅ Blueprint saved to .map/${BRANCH}/blueprint.json
 ✅ step_state.json initialized (with aag_contracts map)
 ✅ Plan written to .map/${BRANCH}/task_plan_${BRANCH}.md
+✅ artifact_manifest.json updated for spec + plan artifacts
 ✅ Context distilled (plan files ≤4000 tokens per subtask)
 
 Next Steps:
@@ -606,6 +644,7 @@ DISTILLATION CHECKLIST:
   [x] step_state.json   — has aag_contracts map + subtask_sequence
   [x] blueprint.json     — raw decomposer output for wave computation (with coverage_map)
   [x] spec_<branch>.md      — has architecture graph + decisions + COMPLETE acceptance criteria (if interview was done)
+  [x] artifact_manifest.json — records workflow_fit + spec + plan stage artifacts
   [x] findings_<branch>.md  — has research pointers (if discovery was done)
 
 TARGET: Executor reads ≤4000 tokens of distilled state to start any subtask.

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/templates/commands/map-review.md

@@ -353,6 +353,19 @@ This keeps `pr-draft.md` aligned with the latest review verdict and follow-up wo
 
 `active-issues.json` is the current unresolved set. Historical issues remain in `plan-review-00N.md`, `code-review-00N.md`, `qa-001.md`, and run dossiers under `.map/<branch>/runs/`.
 
+3. Write the deferred learning handoff so review lessons can be preserved later without hand-writing a summary:
+
+```bash
+python3 .map/scripts/map_step_runner.py write_learning_handoff \
+  map-review \
+  "$ARGUMENTS" \
+  "<PROCEED|REVISE|BLOCK>" \
+  "<next action based on the verdict>" \
+  "<brief note about the most reusable review lesson>"
+```
+
+This writes `.map/<branch>/learning-handoff.md` and `.json`, updates `artifact_manifest.json`, and allows `/map-learn` to auto-load the review context later with no extra reconstruction.
+
 ## CI/Auto Mode Behavior
 
 When `CI_MODE = true` (triggered by `--ci` or `--auto` in $ARGUMENTS):
@@ -367,7 +380,7 @@ When `CI_MODE = true` (triggered by `--ci` or `--auto` in $ARGUMENTS):
 If the review revealed valuable patterns or common issues worth preserving:
 
 ```
-/map-learn [review summary with key findings, resolution patterns, and verdict rationale]
+/map-learn
 ```
 
 ## MCP Tools Used

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/templates/commands/map-task.md

@@ -35,8 +35,13 @@ fi
 ```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")
+# If a persisted TDD contract exists, resume implementation from ACTOR.
+# Otherwise start normal single-subtask execution from RESEARCH.
+if [ -f ".map/${BRANCH}/test_handoff_${SUBTASK_ID}.json" ] && [ -f ".map/${BRANCH}/test_contract_${SUBTASK_ID}.md" ]; then
+  RESULT=$(python3 .map/scripts/map_orchestrator.py resume_from_test_contract "$SUBTASK_ID")
+else
+  RESULT=$(python3 .map/scripts/map_orchestrator.py resume_single_subtask "$SUBTASK_ID")
+fi
 STATUS=$(echo "$RESULT" | jq -r '.status')
 
 if [ "$STATUS" = "error" ]; then
@@ -47,6 +52,7 @@ 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.
+**If persisted TDD artifacts exist:** `/map-task` resumes at `ACTOR` using `test_contract_<subtask>.md` + `test_handoff_<subtask>.json` instead of restarting research.
 
 ## Step 2: Load Subtask Context
 
@@ -56,6 +62,9 @@ Read the plan to get the subtask's details:
 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
+# If present, also read:
+# - .map/${BRANCH}/test_contract_${SUBTASK_ID}.md
+# - .map/${BRANCH}/test_handoff_${SUBTASK_ID}.json
 ```
 
 Display a brief summary:

{mapify_cli-3.7.0 → mapify_cli-3.8.0}/src/mapify_cli/templates/commands/map-tdd.md

@@ -22,8 +22,10 @@ description: TDD workflow — test-first development with spec-driven tests writ
 ## Execution Flow
 
 ```
-Standard:  DECOMPOSE → ACTOR (code+tests) → MONITOR
-TDD:       DECOMPOSE → TEST_WRITER → TEST_FAIL_GATE → ACTOR (code only) → MONITOR
+Standard:          DECOMPOSE → ACTOR (code+tests) → MONITOR
+Targeted TDD:      DECOMPOSE → TEST_WRITER → TEST_FAIL_GATE → CONTRACT_HANDOFF → STOP
+Targeted Resume:   /map-task ST-001 → ACTOR (code only) → MONITOR
+Full-workflow TDD: DECOMPOSE → TEST_WRITER → TEST_FAIL_GATE → ACTOR (code only) → MONITOR
 ```
 
 **Task:** $ARGUMENTS
@@ -39,7 +41,7 @@ BRANCH=$(git rev-parse --abbrev-ref HEAD | sed -E 's|/|-|g; s|[^a-zA-Z0-9_.-]|-|
 ```
 
 **Two modes:**
-- **Single-subtask mode** (`/map-tdd ST-001`): Write tests + implement for ONE subtask only
+- **Single-subtask mode** (`/map-tdd ST-001`): Write tests, persist a red-phase contract, then resume implementation separately
 - **Full workflow mode** (`/map-tdd "task description"`): TDD for all subtasks
 
 ### Single-Subtask Mode (when `$SUBTASK_ID` is detected)
@@ -56,7 +58,7 @@ if [ "$STATUS" = "error" ]; then
 fi
 ```
 
-Then proceed directly to **Step 1: State Machine Loop** below.
+Then proceed directly to **Step 1: State Machine Loop** below. In single-subtask mode, the workflow should pause after `TEST_FAIL_GATE` once the persisted contract artifacts are written.
 
 ### Full Workflow Mode (no subtask ID)
 
@@ -225,11 +227,38 @@ a real bug, not just confirm one obvious branch."
 python3 .map/scripts/map_orchestrator.py validate_step "2.26"
 ```
 
+**Single-subtask mode only: persist the red-phase contract before any implementation starts.**
+
+When `$SUBTASK_ID` is non-empty, write `.map/${BRANCH}/test_contract_${SUBTASK_ID}.md` with:
+- the subtask ID and title
+- the AAG contract
+- the test files created by TEST_WRITER
+- the failing test command
+- the behavior locked by the tests
+- any constraints ACTOR must preserve
+
+Then record the machine-readable handoff and stop this session:
+
+```bash
+python3 .map/scripts/map_step_runner.py record_test_contract_handoff "$SUBTASK_ID" "<failing test command>" "<comma-separated test files>" "<one-sentence contract summary>" "<optional notes>"
+python3 .map/scripts/map_orchestrator.py mark_contract_ready "$SUBTASK_ID"
+```
+
+After that, STOP and tell the user to resume implementation with:
+
+```text
+/map-task ST-001
+```
+
+That follow-up command will detect `test_handoff_${SUBTASK_ID}.json` and resume at `ACTOR` with the persisted contract, instead of re-running research or test writing.
+
+When `$SUBTASK_ID` is empty (full-workflow mode), do **not** write `test_contract_.md`, do **not** call `mark_contract_ready ""`, and do **not** stop the workflow here. In full-workflow mode, `TEST_FAIL_GATE` continues directly into `ACTOR` for the current subtask.
+
 ---
 
 ## Phase: ACTOR in TDD Mode (2.3)
 
-When TDD mode is active, Actor receives a modified prompt:
+When implementation resumes from the persisted TDD contract, Actor receives a modified prompt:
 
 ```python
 Task(
@@ -303,12 +332,13 @@ Monitor verifies both implementation correctness AND that all tests pass.
 
 `/map-tdd` uses the same branch-scoped execution artifacts as `/map-efficient` because it runs through the same orchestrated state machine with extra TDD phases:
 
-
 - `code-review-00N.md`
 - `qa-001.md`
 - `pr-draft.md`
+- `test_contract_ST-00N.md`
+- `test_handoff_ST-00N.json`
 
-In TDD mode, `TEST_WRITER` and `TEST_FAIL_GATE` should append to the same branch workspace instead of creating a separate artifact universe.
+In TDD mode, `TEST_WRITER` and `TEST_FAIL_GATE` still write into the same branch workspace, but they must now leave behind a persisted contract that `/map-task` can resume from in a clean implementation session.
 
 ---
 
@@ -324,7 +354,7 @@ In TDD mode, `TEST_WRITER` and `TEST_FAIL_GATE` should append to the same branch
 ## Related Commands
 
 - **/map-plan** — Create spec with invariants and acceptance criteria (recommended before /map-tdd)
-- **/map-task ST-001** — Execute a single subtask without TDD (implementation only)
+- **/map-task ST-001** — Resume implementation from a persisted TDD contract or execute a normal single subtask
 - **/map-efficient** — Standard workflow without test-first constraint
 - **/map-check** — Final verification after all subtasks complete
 - **/map-learn** — Extract lessons from completed TDD workflow