MAP Framework v3.9.0

What's New in v3.9.0

Added

• Codex CLI provider: mapify init . --provider codex installs .codex/ layout (skills, TOML agents, hooks) for OpenAI Codex CLI
• Provider abstraction: BaseProvider ABC and ClaudeProvider/CodexProvider in mapify_cli.delivery.providers
• Provider-aware commands: mapify check, mapify doctor, mapify upgrade now detect and adapt to the active provider

Fixed

• Workflow gate step-ID translation: subtask_phases values (step IDs like "2.3") are now properly translated to phase names via STEP_ID_TO_PHASE dict before comparison against EDITING_PHASES
• get_project_health provider awareness: No longer reports .claude/* as missing paths for Codex-initialized projects

Changed

• Tagline: Changed from "MAP Kit - for Claude Code" to "MAP Kit - Modular Agentic Planner Framework"
• init() uses ClaudeProvider: The claude path in init() now delegates to ClaudeProvider.install() instead of calling individual file creation functions directly

---

Install: pip install mapify-cli==3.9.0

MAP Framework v3.8.0

[3.8.0] - 2026-04-17

Added

• Skill frontmatter hygiene: Automated validation and cleanup of skill frontmatter across all MAP skills (#100)
• Skill-first map-learn: /map-learn now operates as a skill-first workflow for better integration (#99)
• Repeated learned-rule violation tracking: System now detects and tracks when learned rules are violated repeatedly (#98)
• Learning handoff artifacts: New artifacts for preserving learning context across workflow handoffs (#97)

Changed

• MAP runtime alignment: Aligned runtime with workflow-fit handoffs for smoother transitions
• Handoff flow improvements: Addressed review feedback on handoff flow

Fixed

• Artifact timestamps and manifest branch loading: Fixed timestamp handling in artifacts and branch loading in manifest

MAP Framework v3.7.0

[3.7.0] - 2026-04-11

Added

• Context-aware step injection: Two-layer "active window" context system that replaces full plan injection with focused current-subtask context
  • Hook layer: workflow-context-injector.py now includes goal + subtask title in ≤500 char reminders
  • Actor prompt layer: structured <map_context> block with goal, current subtask details, sibling summaries, upstream results, and repo delta
  • New helpers in map_step_runner.py: load_blueprint(), get_subtask_from_blueprint(), get_upstream_ids(), build_context_block()
  • New StepState fields: subtask_results (per-subtask outcome tracking), last_subtask_commit_sha (differential insight baseline)
  • New function compute_differential_insight() in repo_insight.py for git-diff-based file change tracking between subtasks
• Automatic ACTOR retry on Monitor failure: Monitor valid=false now triggers automatic Actor retry instead of requiring manual intervention
• Integration awareness in agent templates: MAP agent templates now include integration test and reference accuracy checks (Step 5.7 in /map-plan)
• Coverage verification in /map-plan: Anti-compression guards ensure decomposer output preserves all subtasks and acceptance criteria
• Integration tests and e2e Make targets: New make e2e targets for end-to-end testing of plan-to-execution pipeline
• Learned rules: Added architecture patterns and error patterns from parallel wave and frontmatter bugfixes

Changed

• Mandatory research and sequential execution: /map-efficient enforces mandatory research phase and build gate; sequential execution when parallel waves unavailable
• Decomposer granularity rules: Removed artificial max_subtasks constraint; added granularity rules to prevent over-splitting or under-splitting

Fixed

• Parallel wave execution: Orchestrator now correctly supports parallel wave execution without state corruption
• YAML frontmatter preservation: Managed .md files no longer corrupt YAML frontmatter during metadata injection
• Monitor phase enforcement: Monitor phase marked as MANDATORY — never skipped even if tests pass
• CLI dispatch and sanitization: Fixed path consistency, injection safety, DRY violations, deleted file handling, and word truncation
• Template sync: map-plan.md template synced with dev copy
• Code quality: Resolved black formatting issues in 12 files and ruff lint errors (E402 import order, F841 unused variables)

---

Install: pip install mapify-cli==3.7.0

MAP Framework v3.6.0

[3.6.0] - 2026-03-26

Changed

• Pipeline simplification: /map-efficient reduced from 11 phases to 2-3 per subtask ([RESEARCH] → ACTOR → MONITOR). Removed XML_PACKET, CONTEXT_SEARCH, PREDICTOR, UPDATE_STATE, TESTS_GATE, LINTER_GATE, VERIFY_ADHERENCE, SUBTASK_APPROVAL phases
• Per-wave gates: Tests and linter now run once per wave (after all Monitor passes) instead of per subtask
• Single state file: workflow_state.json merged into step_state.json as single source of truth
• Workflow gate rewrite: Phase-based enforcement (ACTOR/APPLY/TEST_WRITER phases allow Edit) instead of completed_steps checking
• Predictor: No longer a pipeline phase; runs only during stuck recovery at retry 3

Removed

• Evidence files and evidence directory (write-only artifacts nobody read)
• session-log.md and devlog-XXX.md (boilerplate, replaced by code-review-XXX.md)
• workflow_state.json (replaced by step_state.json)
• 8 pipeline phases (see Changed above)

Added

• Persist /map-learn lessons to .claude/rules/: Extracted lessons are saved as rule files so future sessions apply them automatically
• Platform refactor: Extracted spec, decomposition, config, and managed file copier into standalone modules for cleaner architecture
• Guard pattern: Decision table for regression detection (monitor pass + guard fail → retry Actor max 2)
• Stuck recovery protocol: At monitor retry 3, invoke research-agent → predictor before retries 4-5
• Scenario dimensions: test_strategy.scenario_dimensions (happy_path, error, edge_case, security) in TaskDecomposer
• Constraint enforcement: scope_glob, time_budget in workflow-gate.py hook
• Flaky-aware verification: FinalVerifier re-runs failed tests 3x with 2/3 majority rule
• Iteration summary: iteration_summary.json derived from ralph-iteration-logger
• Git-as-memory: Conditional {{git_history}} context in Actor for debug/retry/resume

Fixed

• Lint cleanup: Removed unused imports, added re-export aliases, fixed E402 module ordering in __init__.py
• Mypy config: Added [tool.mypy] section to pyproject.toml excluding template scripts and ignoring missing yaml stubs

MAP Framework v3.5.0

[3.5.0] - 2026-03-18

Added

• TDD workflow (/map-tdd): Test-first development mode where tests are written from specification before implementation. Includes TEST_WRITER (2.25) and TEST_FAIL_GATE (2.26) phases
• --tdd flag for /map-efficient: Enables TDD mode within the standard efficient workflow
• TDD support in Actor agent: Two new modes — test_writer (write only tests from spec) and code_only (implement to make tests green, no test modifications)
• set_tdd_mode orchestrator command: Enable/disable TDD phases in the state machine
• Single subtask execution (/map-task ST-001): Execute one specific subtask from an existing plan without running the full workflow. Requires /map-plan first
• Single subtask TDD (/map-tdd ST-001): Write TDD tests and implement a specific subtask. Combines single-subtask execution with test-first development
• resume_single_subtask orchestrator command: Sets up state for executing a single subtask with optional --tdd flag
• Enhanced SPEC phase in /map-plan: Structured spec template with Invariants, Edge Cases, Acceptance Criteria, and Security Boundaries sections
• Devil's Advocate review step: After spec creation, Monitor agent adversarially reviews the spec for race conditions, ownership ambiguity, missing edge cases, contradictions, and security gaps (skipped for complexity < 5)
• Spec invariant linkage in task-decomposer: Contracts must trace back to spec invariants when spec exists; checklist enforces coverage
• skipped_steps tracking: TDD steps skipped when TDD is disabled are tracked separately from completed steps, making TDD toggle reversible
• Plan progress tracking (get_plan_progress): Shows completed/pending subtask counts and suggests next subtask

Fixed

• --tdd flag leak: Flag was leaking into agent prompts via $ARGUMENTS; now stripped into $TASK_ARGS
• Wave-mode TDD support: Waves now start subtasks at TEST_WRITER (2.25) instead of ACTOR (2.3) when TDD is enabled
• set_tdd_mode restart bug: Toggling TDD after first subtask no longer re-introduces completed global steps (1.x)
• TDD toggle reversibility: Re-enabling TDD correctly re-introduces TEST_WRITER/TEST_FAIL_GATE phases even when they come before the current position
• ARCHITECTURE.md phase list: Added missing 2.1 CONTEXT_SEARCH, fixed CHOOSE_MODE description
• SKIPPABLE_STEPS docstring: Added 2.25/2.26 to documented skippable steps
• get_plan_progress docstring: Removed incorrect claim about dependency-aware ordering
• Workflow gate ~/.claude/ scope: Narrowed exemption from entire ~/.claude/ to only ~/.claude/projects/*/memory/
• Missing blueprint.json in /map-plan: Added Step 5.5 to save decomposer output as blueprint.json for wave computation; /map-efficient gracefully falls back to sequential execution when missing

MAP Framework v3.4.1

Release 3.4.1

Release version 3.4.1

MAP Framework v3.4.0

[3.4.0] - 2026-03-09

Added

• Pre-compact transcript saver hook to preserve conversation context before compaction
• SessionStart(compact) hook to inject transcript path after compaction for context continuity

Fixed

• Hook test coverage: replaced deleted hook tests with safety-guardrails tests
• Copilot review comments: addressed feedback from automated code review
• Black formatting in hook template files (safety-guardrails, workflow-gate, ralph-context-pruner)

---

Install: pip install mapify-cli==3.4.0

MAP Framework v3.3.0

[3.3.0] - 2026-03-05

Added

• Wave-based parallel subtask execution in /map-efficient with dependency-graph-driven wave ordering
• Resume detection in /map-plan for continuing interrupted planning sessions
• Interactive 4-section map-review rewrite with structured review flow

Changed

• Monitor forwarding: Actor now forwards directly to Monitor instead of debugging after Actor phase
• Parallel wave enforcement: Enforced parallel wave execution in map-efficient workflow
• Auto batch mode: Automatically set batch mode in map-efficient, skip CHOOSE_MODE step
• Monitor hard stop: valid=false from Monitor is now a hard stop requiring fixes before proceeding
• Integrated AAG contracts with validation criteria enforcement (VC→tests)

Removed

• SQLite Knowledge Graph modules removed entirely
• Cipher and playbook references removed, migrated to mem0 patterns terminology
• mem0/ACE/Curator agents removed, simplified architecture
• context7 and claude-reviewer MCP server configurations removed
• Curator agent template files removed

Fixed

• Claude Code hook configuration and outputs for correct schema compliance
• Workflow gate now allows map artifact updates
• Evidence writes replaced heredoc pattern with Write tool, added predictor skip logic
• PR review findings across agents, CLI reference, and templates
• Hook robustness improvements and documentation
• Black formatting, ruff lint, and mypy type errors across 11 files

---

Install: pip install mapify-cli==3.3.0

MAP Framework v3.2.0

[3.2.0] - 2026-02-14

Added

• Artifact-gated validation in MAP orchestrator for stricter workflow enforcement
• Enhanced skills with examples, troubleshooting sections, trigger rules, and validation scripts
• skip_step command for MAP orchestrator to allow controlled step skipping

Fixed

• Documentation accuracy audit (48 fixes): Comprehensive alignment of all docs, presentations, and templates with actual implementation
  • Corrected agent count references across all docs (8/9/11 → 12 agents)
  • Corrected command count references (updated to 10 MAP commands)
  • Added missing agents (Synthesizer, DebateArbiter, ResearchAgent, FinalVerifier) to ARCHITECTURE.md and presentations
  • Replaced phantom /map-feature and /map-refactor references with implemented workflows
  • Removed stale haiku model references from presentations
  • Fixed Evaluator workflow assignments and map-fast agent pipeline docs
• Template variable consistency: Resolved 8 template variable inconsistencies ({{standards_url}} → {{standards_doc}}, etc.)
• Branch sanitization: Unified branch name sanitization across all hooks, commands, and agents
• Path conventions: Corrected flat .map/ path references to nested <branch>/ directory convention
• API parameter naming: Fixed top_k → limit in documentation-reviewer and other agents
• MAP workflow inconsistencies: Resolved 35 audit issues across orchestrator, commands, and agent templates
• Plan path bug and evidence indentation in orchestrator
• Removed stale references: Cleaned up RETRY_LOOP/APPLY_CHANGES step references
• Test fixtures: Updated to cover all 12 agents and 10 commands
• Black formatting: Fixed formatting in 4 template/test files

MAP Framework v3.1.0

Changed (BREAKING)

• Hook-Based Context Injection: Optimize /map-efficient workflow with state-machine orchestration
  • Problem: 995-line command file (5.4K tokens) caused attention dilution → 20% step compliance
  • Solution: State-machine + PreToolUse hook injection → 85% predicted compliance
  • Command file reduced: 995 → 394 lines (5.4K → 1.75K tokens, 68% reduction)
  • New hook: workflow-context-injector.py - Injects step reminders before every tool call
  • New state machine: .map/scripts/map_orchestrator.py - Enforces 14-phase workflow sequencing
  • New utilities: .map/scripts/map_step_runner.py - Deterministic step executors
  • State file: .map/<branch>/step_state.json - Tracks current step phase for hook injection
  • Token efficiency: 54K → 9.25K per workflow (83% reduction despite hook overhead)
  • Migration: Run mapify init to update project structure with new hooks and scripts
• Simplified Workflow: Removed workflow-gate.py enforcement hook
  • Actor now applies code directly with Edit/Write tools (no gate blocking)
  • Monitor validates WRITTEN code by running tests, not proposals
  • Simpler flow: Actor writes → Monitor tests → If issues, Actor fixes → Repeat
  • Phase 2.7 renamed: APPLY_CHANGES → UPDATE_STATE (code already applied by Actor)

Added

• Ralph Wiggum Loop Integration: Continuous iteration pattern to prevent premature completion and hallucinated success
  • State machine with 10 phases (INIT → DECOMPOSITION → EXECUTION → FINAL_VERIFICATION → COMPLETE/RE_DECOMPOSITION/ESCALATE/HARD_STOP/RECOVERY/WONT_DO)
  • Circuit breaker with configurable limits (max 50 tool calls, 5 same-file edits, 60 min wall time)
  • Final verification step in map-efficient.md (Step 3.5) with re-decomposition on failure
  • Thrashing detection (oscillation detection via net_progress and confidence_variance)
  • Recovery path via RESET_LIMITS marker file
• New Agent: final-verifier.md - Adversarial verifier with Root Cause Analysis for Ralph Loop
• New Hooks:
  • ralph-circuit-breaker.py (PreToolUse): Enforces iteration limits, blocks at thresholds
  • ralph-iteration-logger.py (PostToolUse): Logs metrics, detects thrashing patterns
  • ralph-context-pruner.py (PreCompact): Archives old logs, truncates large files
• New Python Modules:
  • src/mapify_cli/ralph_state.py: State machine, circuit breaker config, verification types, thrashing detection
  • src/mapify_cli/dependency_graph.py: Cascade invalidation for subtask dependencies
• New Configuration: .claude/ralph-loop-config.json - Single source of truth for Ralph Loop limits
• New Reference: .claude/references/escalation-matrix.md - Escalation decision rules

Changed

• task-decomposer.md: Enhanced with Acceptance Criteria table format, re-decomposition mode, dependency enforcement
• map-efficient.md: Added Step 3.5 Final Verification with circuit breaker check, final-verifier invocation, re-decomposition logic
• settings.hooks.json: Added PreToolUse, PostToolUse, and PreCompact hook entries for Ralph Loop

Documentation

• Branch-scoped artifacts stored in .map/<sanitized-branch>/ directory
• Branch name sanitization (e.g., feature/foo → feature-foo) for safe filesystem paths