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

MAP Framework v3.0.0

[3.0.0] - 2026-01-16

Changed (BREAKING)

• Memory layer migration: Migrate from playbook.db/cipher to mem0 MCP for all pattern storage. This is a breaking change that requires mem0 MCP server configuration.

Added

• P0 foundation implementation: security hooks, permissions system, workflow recovery
• mem0 MCP integration for tiered pattern storage (branch → project → org scopes)
• Project settings allowlist extensions for worktree, sourcecraft, mem0 MCP tools

Fixed

• Address PR #70 review feedback for P0 foundation
• Align documentation with actual implementation
• Workflow enforcement to prevent Actor→Monitor cycle skip
• Documentation fixes: ARCHITECTURE.md workflow diagrams, deprecated /map-feature /map-refactor references
• Code quality: Black formatting, ruff linting, mypy type errors

Documentation

• Complete migration of playbook.db/cipher references to mem0 MCP across all docs and templates
• Comprehensive documentation update to v2.3.0 standards
• README optimization (418→93 lines) for improved conversion

MAP Framework v2.3.0

[2.3.0] - 2026-01-10

Added

• /map-planning skill: File-based planning for MAP Framework workflows with branch-scoped task tracking in .map/ directory
• Single-Writer Governance and 3-Strike Protocol for plan modification control
• Integration of map-planning skill with mapify templates and orchestrator

Fixed

• Critical bugs in map-planning skill session state management

Documentation

• Updated README and skills docs for map-planning skill

---

Installation:

pip install mapify-cli==2.3.0

Full Changelog: https://github.com/azalio/map-framework/blob/main/CHANGELOG.md

MAP Framework v2.2.0

[2.2.0] - 2026-01-08

Added

• /map-debate command: Debate-based MAP workflow with Opus arbiter for multi-variant synthesis. Generates 3 Actor variants in parallel (security/performance/simplicity focus), validates with parallel Monitors, then uses debate-arbiter (Opus model) to cross-evaluate and synthesize optimal solution

Changed

• Documentation cleanup: Remove deprecated /map-feature references, update learning workflow info

Fixed

• Address reviewer feedback on map-debate documentation

---

Installation:

pip install mapify-cli==2.2.0

Full Changelog: https://github.com/azalio/map-framework/blob/main/CHANGELOG.md

MAP Framework v2.1.0

Added

• External static analysis scripts for Monitor agent (analyze.sh, lint-go.sh, lint-python.sh)
• LLM Council recommended improvements to MAP workflow (context7 integration, parallel execution)

Changed

• Optimize task-decomposer template with references to mapify init
• Extract common functions to shared module with tests
• Update README and sync templates with map-efficient improvements

Fixed

• Security hardening per Copilot review
• Improve clarity per Copilot review comments (multiple rounds)
• Fix agent count documentation (8→10) and update template sync
• Fix black formatting issues

Documentation

• Document map-efficient command template
• Sync map-efficient.md documentation with source template

MAP Framework v2.0.0

[2.0.0] - 2025-12-15

Changed

• Parallelize Monitor, Predictor, Evaluator agents in /map-review workflow for improved performance
• Auto-create .mcp.json during mapify init for better MCP server integration

Fixed

• Remove hooks-related CI job and test after hooks system removal
• Restore JSON validation in stop.sh hook for malformed input handling
• Address Copilot and LLM Council security review findings
• Clarify enforcement points and framework-level secret handling in documentation
• Handle malformed JSON in stop.sh hook with updated INPUT FORMAT docs
• Address PR #56 review comments
• Fix black formatting issues

Added

• New research-agent for context isolation during research tasks

BREAKING CHANGES

Hooks System Removed

The Claude Code hooks system has been completely removed from MAP Framework.

Rationale:

• Hooks added complexity without proportional value
• Core MAP workflows (/map-efficient, /map-debug, /map-fast) operate independently of hooks
• Maintenance burden outweighed benefits

What was removed:

• .claude/hooks/ directory (13 hook scripts)
• src/mapify_cli/__init__.py functions: load_settings_with_merge(), merge_hooks_settings(), install_hooks()
• src/mapify_cli/templates/hooks/ directory
• CLI option: --with-hooks/--no-hooks from mapify init
• 59 test cases (test_hooks_*.py, test_init_merge.py, test_inject_playbook_bullets.py)

Migration guide:

For existing projects with hooks installed:

1. Hooks are now user-managed - The .claude/hooks/ directory (if present) will be ignored by MAP Framework
2. No action required - Your existing hooks will continue to work as Claude Code hooks
3. Optional cleanup - You can safely remove .claude/hooks/ if you don't use custom hooks

What continues to work:

• ✅ All MAP workflows (/map-efficient, /map-debug, /map-fast, /map-learn, /map-release, /map-review)
• ✅ Agent orchestration via Task tool
• ✅ Playbook management via mapify playbook commands
• ✅ MCP server integration (cipher, context7, deepwiki, etc.)

What no longer works:

• ❌ mapify init --with-hooks / --no-hooks options (removed from CLI)
• ❌ Automatic hooks installation via mapify init
• ❌ Hooks template synchronization

Upgrade path:

# Upgrade MAP Framework to v2.0.0
uv tool upgrade mapify-cli

# (Optional) Remove hooks directory if you don't use custom hooks
rm -rf .claude/hooks/

[1.7.0] - 2025-12-08

[2.0.0] - 2025-10-17

Added - Agent Templates Overhaul

See Agent Templates CHANGELOG for complete v2.0.0 changes.

Summary:

• Comprehensive MCP integration framework
• XML-style semantic structure for better LLM parsing
• Template size: 2,232 → 9,269 lines (+258% for comprehensive guidance)
• Removed orchestrator as subagent (moved to slash commands)

---

For older changes and agent template details, see:

• Agent Templates CHANGELOG
• Git commit history

Versioning

Version Format: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes (incompatible API/workflow changes)
• MINOR: New features (backward compatible additions like Phase 1)
• PATCH: Bug fixes and minor improvements

MAP Framework v1.7.0

[1.7.0] - 2025-12-08

Added

• Optional Learning Command: Added /map-learn command for optional post-workflow learning. Reflector and Curator agents are now invoked on-demand rather than automatically in workflows (cdc7e4e)
• Auto-Approval Permissions: mapify init now configures auto-approval rules for common readonly operations (cipher memory search, tracker queries, sequential-thinking) to reduce permission prompts (18f9532)

Changed

• Workflow Simplification: Removed unused workflow commands (/map-feature, /map-refactor) to reduce maintenance burden. Use /map-efficient for feature work (cdc7e4e)
• Permissions Merge: Settings permissions now use additive merge strategy to preserve user-defined rules (b585173, 1978af8)

Fixed

• Map-Review Command: Restored /map-review command that was accidentally removed and updated stale agent references (1394935)
• Stop Hook: Restored malformed JSON handling in stop.sh quality gates hook for robustness (41b96c9)
• README Accuracy: Updated README to reflect actual available commands, fixed playbook bullet ID generation for consistent identifiers (af2d5d3)
• Documentation Consistency: Fixed Next Steps sections across commands to show actual available commands (c0a257d)
• Map-Learn References: Removed stale references to deleted commands in /map-learn template (3fcf8fc)
• Agent Instructions: Removed misleading 'orchestrator directly' instruction from agent templates (ea75b21)
• Type Safety: Resolved 39 mypy type errors across 11 files, improving code quality (fe474dd)

Removed

• Recitation Functionality: Removed mapify recitation commands and related functionality. This feature was underutilized and added maintenance complexity (a1be4f8)
• MCP Server: codex-bridge: Removed codex-bridge MCP server from the framework (7a7e363)
  • Removed from INDIVIDUAL_MCP_SERVERS constant
  • Removed from agent template generators (actor, predictor)
  • Removed from agent_mcp_mappings configuration
  • Updated all agent templates to remove codex-bridge references
  • Updated documentation (README, ARCHITECTURE, presentations)
  • Updated .mcp.json.example and plugin configuration
  • Updated tests to expect 5 MCP servers instead of 6
  • Rationale: Simplify MCP server dependencies; codex-bridge functionality can be achieved through other tools

MAP Framework v1.6.2

[1.6.2] - 2025-11-29

Fixed

• MAP Efficient Workflow: Fixed incorrect subagent_type parameters in /map-efficient command template. Changed from deprecated type parameter to correct subagent_type for all Task tool invocations (reflector, curator, monitor, predictor, evaluator) (e05793a)

Installation

pip install mapify-cli==1.6.2

Full Changelog

https://github.com/azalio/map-framework/blob/main/CHANGELOG.md

MAP Framework v1.6.1

[1.6.1] - 2025-11-28

Fixed

• Playbook Migration: Fixed migration from playbook.json to playbook.db when using mapify init --force. The migration now properly detects and removes invalid/incomplete playbook.db files before attempting migration, and cleans up stale playbook.json files after successful migration (7cfa82e)
• Playbook References: Removed all playbook.json references from codebase (except CHANGELOG history). Updated CLAUDE.md, agent templates, skills, and documentation to reference playbook.db only. Added clarifying comments to migration code and tests (fbe6bd3)

Installation

pip install mapify-cli==1.6.1