MAP Framework v3.10.0

Added

• Persisted review bundle: create_review_bundle() writes durable
  review-bundle.json and review-bundle.md under .map/<branch>/ so
  /map-review runs from a fresh chat context without relying on implementer
  session memory. Bundle JSON contract is captured in REVIEW_BUNDLE_SCHEMA
  (src/mapify_cli/schemas.py).
• /map-review --detached flag: prepare_detached_review() opens an
  isolated git worktree add --detach worktree at
  .map/<branch>/detached-review/ so reviewer agents read source from a clean
  copy. The source branch is never mutated; graceful degradation to in-place
  bundle on unavailable/error.
• Soft schema validation in create_review_bundle(): bundle JSON is
  validated against REVIEW_BUNDLE_SCHEMA after assembly. On failure the file
  is still written, gains a schema_validation_error array, and the manifest
  review stage is downgraded from ready to warn.
• Path-traversal guard on prepare_detached_review: explicit target_dir
  values that resolve outside .map/<branch>/ (or the .map/ root) are
  rejected with status="error" before any git mutation.
• code_state.diff_truncated flag: snapshot_code_state caps diff_stat
  at 64 KiB and files_changed at 500 entries, surfacing a diff_truncated
  marker so reviewers can see the snapshot was clipped on very large repos.
• hypothesis test dependency: added to [project.optional-dependencies]
test / dev extras for property-based coverage of _sanitize_for_json.
• Context compression policy: New compression_policy setting in .map/config.yaml
  with three modes — never (quality-leaning), auto (default, nudges at 120k tokens),
  and aggressive (nudges at 0.4 × threshold = 48k by default).
• mapify init --compression {never,auto,aggressive} --compression-threshold N:
  set the policy and absolute threshold at project init time. Persisted into
  .map/config.yaml.
• context-meter.py hook (UserPromptSubmit): counts tokens from the last
  assistant turn in transcript_path and injects a /compact <focus>
  recommendation into the assistant's context when the threshold is crossed.
  Honours a 5-minute cooldown via .map/<branch>/last-compact.marker so it
  does not double-fire after Claude Code's built-in 83.5% auto-compact.
• mapify_cli.token_budget: pure module exposing
  count_last_turn_tokens, effective_threshold, should_nudge,
  format_compact_instruction. 25 unit tests in tests/test_token_budget.py.
• Orchestrator --transcript-path flag: map_orchestrator.py accepts
  --transcript-path (or env MAPIFY_TRANSCRIPT_PATH) and emits the same
  /compact recommendation to stderr at every command. Provider-agnostic —
  works for both Claude Code and Codex sessions.
• Design doc: docs/context-compression-plan.md.
• /map-explain skill: new manual slash surface for deep code, PR, and
  project walkthroughs. Synced into shipped templates so generated projects
  get the same explainer workflow.
• /map-review order-bias hardening (Phase 1): review prompts now use
  randomized agent order, evidence-tagged findings, and explicit anti-bias
  checks so reviewer agents are less susceptible to ordering effects in
  multi-agent fan-out.
• Skill skillClass runtime taxonomy: .claude/skills/skill-rules.json
  and the shipped template copy declare task, reference, or hybrid for
  every shipped skill. Hybrid skills must enumerate runtimeEffects. The
  skills README and user docs distinguish runtime boundaries instead of
  treating every skill as passive documentation.
• Run health report artifact: write_run_health_report in
  .map/scripts/map_step_runner.py (and shipped template copy) emits
  .map/<branch>/run_health_report.json with terminal status, step
  progress, artifact presence, retry counters, Predictor/final-verifier
  signals, and hook-injection state. Backed by RUN_HEALTH_REPORT_SCHEMA
  and a new run_health stage in artifact_manifest.json.
• Run health closeout wiring: /map-efficient, /map-debug,
  /map-check, and /map-review write run_health_report.json after the
  terminal verdict is known. Closeout snippets set RUN_HEALTH_STATUS from
  the verdict instead of defaulting to complete, preserving pending,
  blocked, won't_do, and superseded paths.
• Expanded hook degradation status coverage: workflow-context-injector.py
  now records explicit skipped-hook reasons for malformed input, non-object
  payloads, non-injected tools, and insignificant Bash commands when an
  existing branch step_state.json can be safely parsed and updated.
• Run health validator: validate_run_health_report enforces required
  fields, terminal-status enum, artifact inventory entries, resiliency
  signal types, complete-without-pending-steps, complete-without-verification,
  retry overflow, and hook degradation reasons. Works in generated projects
  without mapify_cli.schemas.
• Contract-sized subtask guardrails: validate_blueprint_contract fails
  oversized, mixed-concern, untraceable, duplicate-ID, dangling-dependency,
  or non-logical subtasks before implementation starts. Blueprint schema
  gains expected_diff_size, concern_type, one_logical_step,
  aag_contract, validation_criteria, and coverage_map (with nested
  TaskDecomposer output support). Monitor and FinalVerifier prompts check
  for scope drift after planning.
• Evidence-first prompt outputs: .claude/references/map-output-examples.md
  provides a shared evidence-first JSON examples file. /map-review
  Monitor/Predictor/Evaluator, /map-debug investigation, and /map-plan
  spec-review/decomposition prompts now require evidence[] (with concrete
  quotes from logs, code, tests, or spec) before verdict, risk, or score
  fields. HIGH/CRITICAL issues, breaking changes, and sub-7 scores must be
  evidence-tied.
• JSON prompt-contract lint: .claude/references/map-json-output-contracts.md
  is the reusable backing reference for non-evidence JSON prompt sections.
  /map-fast, /map-debug, and /map-learn non-evidence outputs declare
  explicit contract references. tests/test_skills.py adds a generic
  scanner over both .claude/skills/ and the shipped templates that fails
  if future JSON prompt sections lack either evidence or a contract
  reference.
• Blueprint acceptance-criteria lineage: every coverage_map key in
  blueprint.json must now appear as a bracketed tag in the owning
  subtask's validation_criteria (e.g., VC1 [AC-1]: ...).
  validate_blueprint_contract fails untagged validation criteria before
  Actor starts and names the missing tag.
• Hard/soft constraint typing: blueprint schema adds hard_constraints
  and soft_constraints. Hard constraint ids must appear in coverage_map
  and the owning subtask's bracketed validation_criteria; soft
  constraints may be omitted only with tradeoff_rationale. Planner and
  decomposer prompts (Claude and Codex) ask for and validate the contract.
• Acceptance coverage reporting: write_verification_summary and
  create_review_bundle summarize every blueprint.json coverage_map
  tag, marking each covered only when bracketed evidence (e.g., [AC-1],
  [INV-1]) appears in downstream verification, QA, test contract,
  handoff, PR draft, or review artifacts. Otherwise outputs show
  missing_evidence. REVIEW_BUNDLE_SCHEMA, review-bundle Markdown, and
  manifest review-stage metadata surface both human and machine views.
• Prior-stage artifact consumption gates:
  build_prior_stage_consumption_report and
  validate_prior_stage_consumption <implementation|review> prove whether
  spec, task plan, blueprint, test contract, code diff, and review-time
  verification summary were consumed. write_verification_summary and
  create_review_bundle include prior_stage_consumption; review
  manifest status downgrades to warn when required prior-stage inputs
  are missing instead of hiding stage skipping.
• Workflow effort and parallelism policies: every shipped MAP task
  skill declares ## Effort and Parallelism Policy with explicit
  thinking_policy (low/medium/high) and parallel_tool_policy.
  Lightweight workflows (/map-fast, /map-check, /map-resume) use
  low/direct; implementation/learning workflows use medium/adaptive;
  planning, review, and release use high/adaptive. Top-level
  workflow-rules.json records execution policies for workflow-triggered
  /map-fast, /map-efficient, and /map-debug suggestions.

Changed

• Workflow gate COMPLETE phase is permissive: post-workflow polish and
  follow-up review fixes are no longer blocked. The atomic-completion invariant
  in map_orchestrator.mark_workflow_complete is the only writer of
  current_step_phase=COMPLETE, so the trust boundary is documented in-line
  on TERMINAL_PHASES.
• Workflow gate .claude/rules/learned/ exemption tightened to *.md:
  the exemption now requires a markdown filename so the directory cannot
  quietly widen into a general bypass for arbitrary file types.
• Stub detection in review bundle: _fixed_artifact_entry now flags
  verification-summary.md and pr-draft.md as present=False when their
  content matches the strict initial placeholder (from HUMAN_ARTIFACT_DEFAULTS)
  or the writer-emitted soft stub (all sections - [not recorded]).
• Skill rename map-planning → map-state: resolves a slash-command
  collision where /map-plan was fuzzy-matched to the longer map-planning
  name when map-plan was hidden via disable-model-invocation. The skill
  body, hooks, and scripts are unchanged — only the directory and the entry
  in skill-rules.json are renamed. Existing .map/<branch>/ artifacts
  remain compatible.
• map-plan becomes model-invocable: removed disable-model-invocation: true from `map-plan...

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