MAP Framework v3.24.1

See CHANGELOG.md for details.

MAP Framework v3.24.0

See CHANGELOG.md for details.

MAP Framework v3.23.0

See CHANGELOG.md for details.

MAP Framework v3.22.0

See CHANGELOG.md for details.

MAP Framework v3.21.0

See CHANGELOG.md for details.

MAP Framework v3.20.0

[3.20.0] - 2026-06-26

Added

• Automatic cleanup of MAP-internal workflow IDs from shipped code. At workflow completion (WORKFLOW_COMPLETE), the new scrub-internal-ids.py Stop hook strips leaked internal identifiers — subtask ST-001, acceptance criteria AC-3, verification criteria VC1, invariants INV-7, hard constraints HC-1 — that an Actor wrote into the code a run changed — as comments (// The rule (INV-7) is:) or test names (test_vc1_* → test_*). The deterministic engine (.map/scripts/scrub_internal_ids.py) is hard-scoped to the run's git diff (only files the run changed, only the lines it added; pre-existing IDs on untouched lines are never modified) and to recognized source files using each language's comment syntax (#, // + /* */, <!-- -->, …). It strips ID tokens inside comments (deleting pure-marker comment lines) and renames vc<n> test identifiers with a collision guard. IDs in code, string literals, docstrings, and data files (.json, …) are deliberately left intact and only reported — stripping a string substring would corrupt legitimate values (e.g. "INV-7-special-sku") and # is a heading, not a comment, in markdown. It re-scans for residual. It then commits the cleanup as a dedicated chore(map): strip internal workflow IDs commit, runs exactly once per completed run, no-ops outside a completed run, honors MAP_INVOKED_BY, and can be disabled with scrub_internal_ids: false in .map/config.yaml. The Actor prompt now also forbids writing these IDs into comments/strings (the transient test_vc<n> grep aid stays during the run and is renamed at close). Claude provider only — the Codex hook model has no Stop event; the shared engine ships to .map/scripts/ regardless.

MAP Framework v3.19.0

Fixed

• Blueprint affected-files refresh no longer shrinks approved subtask scope after resume (closes #273). refresh_blueprint_affected_files now merges the computed actual delta into existing affected_files by default, preserving files that were already approved but excluded from the per-subtask baseline. The old destructive rewrite behavior remains available only via explicit --replace, and reports now expose both actual and mode.
• Plan resume requires an overlap floor, not containment alone (closes #274). check_plan_resume() no longer returns a false resume verdict (with the dangerous "existing step_state ⇒ plan complete, print checkpoint and STOP" recommendation) when the new goal merely overlaps a contained-but-near-zero existing plan. The verdict now requires a minimum goal overlap in addition to containment, so a genuinely different goal starts fresh instead of silently resuming a stale plan.
• Codex hooks.json no longer carries an unsupported _map_managed top-level key (closes #270). The codex hooks-JSON generator merged MAP metadata as a top-level _map_managed object, which the Codex runtime rejects. The generator now writes only the supported hooks structure and keeps MAP's managed-merge bookkeeping out of the emitted file.
• /map-efficient resume prefers blueprint.json for ordered subtask IDs (closes #264). resume_from_plan, resume_single_subtask, resume_from_test_contract, and get_plan_progress now read ordered ST-XXX IDs from blueprint.json first, falling back to markdown task_plan parsing (including the /map-plan table layout with IDs in the first column). set_subtasks normalizes whitespace-joined arguments and rejects malformed subtask IDs, so resume no longer fails to parse a well-formed plan and force a manual set_subtasks.

Added

• Opt-in --autonomy posture for mapify init (claude provider). mapify init --autonomy writes a "YOLO-minus-git" permission set — broad auto-approve (Bash(*), Read/Edit/Write/MultiEdit/Glob/Grep/LS(*)) plus a Bash(git commit:*) / Bash(git push:*) deny — into the per-user, gitignored .claude/settings.local.json, leaving the committed team .claude/settings.json as the secure curated baseline. Because the permission-level git deny is bypassable under a broad Bash(*) allow (bash -c 'git commit' matches as bash, not git commit), enforcement is the safety-guardrails.py PreToolUse hook: it now hard-blocks git commit/git push (including shell-wrapped and chained forms) gated on a mapify.autonomy sentinel the installer writes beside the permissions, so posture and permissions can't drift apart and the standard commit workflow is never broken for non-autonomy users. --no-autonomy cleanly removes the block; omitting the flag leaves any existing local posture untouched on re-init. mapify init --autonomy also gitignores .claude/settings.local.json so the personal posture can't leak to the team. The codex provider ignores the flag (it installs neither file). Design was llm-council-reviewed (per-user opt-in over team/global default; hook enforcement over permission-deny-alone; sentinel embedded in settings.local.json).
• Merge-conflict resolution guardrail (closes #256). The workflow-context injector now surfaces MAP conflict-resolution guidance during a git merge/rebase preflight and whenever the index holds active unmerged paths. It detects conflicted paths read-only via git diff --name-only --diff-filter=U -z -- (the existing step_state.json gate is preserved) and documents the per-file, intent-preserving, test-after-each-batch protocol so conflicts are resolved one file at a time rather than with bulk overwrites.
• defer_flaky_subtask orchestrator command for validated flaky Monitor outcomes (closes #252). When a Monitor verdict is an explicit deferred_nondeterministic outcome, the orchestrator can now persist the non-green flaky evidence metadata in step_state.json and advance without requeueing Actor, preserving run-health completion parity instead of grinding the retry loop on a known-flaky check.
• run_flaky_test_triage repeat runner for /map-efficient (part of #252). New step-runner subcommand repeats an exact argv command with shell=False and records flaky-test evidence automatically into flaky_test_triage.json, preserving bounded stdout/stderr tails, timeout, and duration evidence. No shell interpretation by default (shell behavior requires explicit argv such as bash -lc); output tails are tempfile-backed to avoid unbounded in-memory capture. Design was llm-council-reviewed (argv-based runner; core Monitor/orchestrator state-machine integration deferred).
• Qualitative convergence sidecar for high-risk Monitor/self-review gates (issue #257). New step-runner subcommands record_qualitative_convergence <gate-id> <pass-json> [--scope monitor|self_review] [--required-clean-passes N] [--max-passes N] and validate_qualitative_convergence [path] persist append-only qualitative review passes in .map/<branch>/qualitative_convergence.json and register the qualitative_convergence manifest stage. Validation re-derives the tail clean streak from the pass log (clean, dirty, clean with K=2 is not converged), rejects clean=true with critical findings, requires evidence even for clean passes, and treats max_passes_exceeded as a hard stop/escalation rather than a pass. Scope is deliberately limited to qualitative monitor / self_review; deterministic build/test/lint gates remain single-pass. Part of #251.
• Flaky-test triage artifact for /map-efficient (issue #252). New step-runner subcommands record_flaky_test_triage <check-id> <outcomes-json> [--command ...] [--reason ...] [--branch ...] and validate_flaky_test_triage [path] persist repeated check outcomes in .map/<branch>/flaky_test_triage.json and register the flaky_test_triage manifest stage. Mixed pass/fail repetitions classify as disposition:"deferred_nondeterministic" with monitor_verdict_policy:"not_valid_without_explicit_triage" and operator requirements that forbid weakening, skipping, deleting, or treating the artifact as a passing gate. All-failing repetitions classify as deterministic_failure; all-passing repetitions classify as not_reproduced. Package schemas and run-health artifact inventory now understand the new artifact, while keeping the core Monitor/orchestrator binary verdict path unchanged. Part of #251.
• Intra-run failure memory for the Actor→Monitor retry loop (issue #253). When Monitor rejects the same subtask the same way twice, /map-efficient now injects a binding anti-stagnation constraint into the next Actor attempt so the loop stops re-walking a dead end (token burn / identical rejected diffs). Four deterministic step-runner subcommands implement it: record_failure_signature "<feedback>" <subtask_id> [--source monitor_rejection|test_failure|gate_failure] conservatively normalizes the failure (strips line numbers, absolute-path prefixes, hex/uuid/addresses, timestamps, ANSI; preserves exception types, file basenames, symbol/test names, assertion text), hashes it, and arms on the 2nd identical signature; build_anti_repeat_constraint <subtask_id> [--quarantine-active] renders the <intra_run_failure_memory>-delimited block (shows the human-readable sample, never the hash) and returns empty when nothing is armed or a CLEAN_RETRY quarantine is active that iteration; set_anti_repeat_subtask_status <subtask_id> succeeded|failed|escalated records the terminal disposition; collect_anti_repeat_learn_candidates feeds write_learning_handoff so armed signs from non-succeeded subtasks become /map-learn candidates (a subtask that eventually passed is excluded — it found a way through). The constraint is anti-stagnation, not anti-approach: it binds the next delta to resolve the repeated failure, never bans a whole approach. Generic rejections with no concrete anchor ("tests still fail") are recorded low_specificity and never arm. At the 3rd identical failure the record sets escalation_recommended=true as a SIGNAL only — bounded-effort escalation (#255) owns the stop decision; this slice never skips the Actor call. Durable store: .map/<branch>/anti_repeat.json + anti_repeat manifest stage; thresholds are env-tunable (MAP_ANTI_REPEAT_ARM_THRESHOLD, MAP_ANTI_REPEAT_ESCALATE_THRESHOLD). Complements — never duplicates — log_agent_failure (FORMAT failures only) and retry_quarantine (one-shot CLEAN_RETRY). Design was llm-council-reviewed (hard anti-stagnation + generic-failure guard + per-subtask scoping + CLEAN_RETRY suppression). Part of #251.
• Bounded-effort escalation: "act once, then escalate" (issue #255). Turns the #253 escalation_recommended SIGNAL (previously written but never consumed) and the orchestrator's max_retries hard cap into ONE deterministic terminal outcome instead of grinding the Actor→Monitor loop to the ceiling on a dead end. New step-runner subcommand build_escalation_outcome <subtask_id> <reason> [--retry-count N --max-retries M] [--quarantine-active] (reason ∈ repeated_failure | max_retries) emits a structured {status:"escalated", outcome, reason_code, attempts, blocker_summary, repeated_failures, recommended_action}, sets the subtask's anti-repeat status to escalated, writes a durable human-readable .map/<branch>/escalation_<subtask>.md blocker report, and registers a new escalation manifest stage. The outcome splits on cause: a 3rd identical failure short-circuits to outcome:"BLOCKED" (the constraint armed at the 2nd identical failure was the single bounded recovery act, so the legacy retry-3 Stuck-Recovery is bypassed for identical-failure loops, kept for non-identical stuckness), while budget exhaustion across differing failures is outcome:"CLARIFICATION_NEEDED". The stop is re-derived from the anti_repeat store IN...

MAP Framework v3.18.0

Fixed

• PyYAML promoted to a hard runtime dependency (closes #245). pyyaml was
  declared only in the test/dev optional groups, so a normal install
  (uv tool install / pipx / pip install mapify-cli without extras) shipped
  without PyYAML. project_config.load_map_config then hit ImportError, warned
  once, and silently fell back to default config — the user's entire
  .map/config.yaml (minimality, profile, compression_policy, thresholds,
  language, prompt_layering, …) was ignored by every config-dependent CLI path
  (minimality-report, mapify init compression/sofa overrides). CI never caught
  it because the dev/test groups do include pyyaml. Fix adds pyyaml>=6.0.0 to
  [project].dependencies in pyproject.toml. (The .map/scripts/map_step_runner.py
  runner was unaffected — it reads config via a stdlib-only scalar parser — which is
  why the defect hid.) Regression tests assert pyyaml is in the runtime dependency
  table and that a non-default .map/config.yaml value actually loads.

Changed

• Prompt layering resolved as cache-neutral; docs_first stays the default (closes #231).
  The remaining field-gated step of #231 — measure docs_first vs stable_first
  on a real multi-subtask run, then maybe flip the global default — is resolved
  on mechanism, not a fabricated measurement. Anthropic prompt caching writes
  a cache entry only at an explicit cache_control breakpoint on a content-block
  boundary and hits require a byte-identical prefix up to that block; Claude Code's
  Task tool owns the API call and all breakpoint placement, and MAP joins its
  sections into one user-message string so the stable/variable seam lives mid-block
  and can never become a cache boundary. The only byte-identical cross-dispatch
  prefix (tools + role system prompt) is independent of prompt_layering, so both
  modes benefit equally. Therefore stable_first yields no incremental prefix-cache
  hit under the current Claude Code Task architecture. No behavior change: the
  global default stays docs_first; stable_first remains opt-in and is not a
  behavior no-op (it still changes token order/attention) and is never silently
  remapped. docs/ARCHITECTURE.md, docs/USAGE.md, the MapConfig.prompt_layering
  comment, the generated .map/config.yaml comment, the map_step_runner.py layering
  comments, and tests/test_prompt_layering.py were de-overclaimed accordingly, and
  re-open triggers were recorded. No token_accounting.json figures were fabricated —
  per-subagent cache usage is harness-owned and not observable to MAP for Task
  dispatches, which is exactly why an end-to-end run is a poor test of this hypothesis.
• Global minimality default flipped off → lite (Phase 3, closes #183).
  The promotion gate (mapify minimality-report) reached candidate and the
  manual review gate passed against field telemetry, so the keyless default now
  resolves to lite instead of off at BOTH layers: MapConfig.minimality
  (src/mapify_cli/config/project_config.py) and the runner's
  _load_minimality_level (map_step_runner.py). Projects that omit the key now
  get the advisory complexity-lens / minimality doctrine (advisory-only — never a
  verdict gate). Opt out with minimality: off. Opt-out hardening: YAML 1.1
  parses bare off as boolean False, which the str field previously rejected and
  silently dropped to the default — now the loader coerces a boolean minimality
  back to the off level before type-checking, so minimality: off (quoted or
  bare) reliably opts out. generate_default_config already wrote minimality: lite for new projects, so generated configs are unchanged; only keyless/invalid
  fallbacks move from off to lite. Regression tests pin the new default, the
  bare-off opt-out, the invalid→lite fallback, run-health stamping, and the
  doctrine/lens activation at the lite default.

Added

• /map-plan Step 0.6: Verify Live/Runtime State gate (#243). A new
  depends_on_runtime_state workflow-fit signal (6th signal on
  record_workflow_fit, default false; CLI flag --depends-on-runtime-state,
  legacy positional path unchanged) arms a gated Step 0.6 between the
  Already-Implemented gate (Step 0.5) and decomposition. It is the runtime
  analogue of Step 0.5: where 0.5 stops you re-planning code that already
  exists, 0.6 stops you planning against runtime facts that have drifted
  (prod row counts, enum labels actually present in a live DB, a column that
  already exists, the applied migration head, a live feature-flag value).
  Each assumption is either verified read-only through an approved source
  (replica/dashboard/metadata query — cite the derived fact, never persist
  prod rows/PII/secrets into .map/<branch>/ artifacts) or recorded as an
  Unverified Runtime Assumption in the spec's Open Questions / Risks with the
  exact check to run, with dependent subtasks marked provisional. The skill is
  a planning-time gate, not a runtime tool — it suggests the read-only checks and
  defers execution to the operator or an authorized sub-agent; it never
  hard-stops merely because prod is unreachable. Mirrored into the Codex
  $map-plan surface; detail + examples + safety guardrails live in the bundled
  plan-reference.md (the active SKILL body stays under its line budget).
  WORKFLOW_FIT_DECISION_SCHEMA gains the optional depends_on_runtime_state
  boolean (not required, so pre-existing workflow-fit.json files still
  validate). Design pressure-tested via llm-council (deep mode). New regression
  tests pin the signal round-trip, the keyword CLI flag, the legacy-positional
  default, schema backward-compat, and the gate prose across all rendered
  Claude + Codex trees.
• Opt-in cache-friendly prompt layering for reviewer fan-out (Part of #231).
  .map/config.yaml now accepts prompt_layering: docs_first | stable_first
  (default docs_first, behavior unchanged). docs_first keeps the historical
  attention-optimized envelope (variable <documents> first, stable contract
  last). stable_first reorders the stable <task>/<workflow_policy>/
  <instructions>/<expected_output> contract ahead of the variable documents
  so it forms a byte-identical prefix across repeated same-role Monitor/
  Predictor/Evaluator (and complexity-lens) dispatches — the precondition for an
  automatic prefix-cache hit. _render_review_prompt and
  _render_complexity_lens_prompt route through a shared _layer_prompt_sections
  helper; build_review_prompts reads _load_prompt_layering() and echoes the
  active mode as prompt_layering in its result. Registered + validated on
  MapConfig and documented (commented) in the generated config. The
  attention-vs-cache tradeoff is unproven, so the default does not flip: it
  is gated on a measured docs_first vs stable_first comparison (incremental
  cache_read + no quality regression) — the measurement recipe and the
  harness-owned-dispatch constraint are documented under "Prompt Layering &
  Prefix Caching" in docs/ARCHITECTURE.md. The token-accounting cache_read
  double-count the issue cited as a measurement caveat was already fixed and is
  regression-tested, so the comparison numbers are trustworthy. New
  tests/test_prompt_layering.py pins docs_first byte-identity and the
  stable_first prefix invariant.
• Agent-Boundary Doctrine: written down + every live hand-off audited
  independent | relay (#230). docs/ARCHITECTURE.md now carries the explicit
  criterion — keep a separate sub-agent only when it adds an independent /
  adversarial perspective; collapse any pure-relay hop (a context that only
  paraphrases a prior agent's output, emitting no new verdict) into its caller.
  It is a substance rule, not a wiring rule. The doctrine includes a ground-truth
  audit (classified from actual subagent_type="…" dispatch sites, not docs): all
  8 pipeline-dispatched agents emit independent verdicts and none is a relay; the
  only relay hops the doctrine condemns — the Self-MoA synthesizer/debate-arbiter
  — were already collapsed in #240. The audit also resolves the orphaned
  documentation-reviewer (zero skill dispatch sites) as a deliberate keep: it
  emits a unique, non-relay verdict, so it is retained as an optional,
  user-dispatchable agent (invoke via Task(subagent_type="documentation-reviewer"))
  and now self-declares a Dispatch status: annotation. A new
  tests/test_agent_dispatch_audit.py enforces the invariant going forward: any
  agent shipped with no dispatch site and not marked optional fails the gate,
  preventing a silent orphan from recurring.
• Hand-authored RESEARCH artifacts now self-correct on the first reject, and
  the exact contract is documented (#228, follow-up to #197). The documented
  save_research path ("save direct current-session findings") used to cost 2-3
  validate_research rejects because the strict schema enforced by the validator
  (status enum, confidence float, search_stats field names, lines: [start, end] with a ≤200-line span) lived only in code — the SKILL prose implied free
  text ("complete", "high", files_examined). Now: (1) validate_research
  echoes a copy-pasteable, structurally-valid artifact in a skeleton field on
  ANY failure (bad JSON, wrong types, or a missing artifact), so the first reject
  is self-correcting — copy it, swap your values, re-save; (2) the exact field
  table + the same skeleton are documented under "RESEARCH artifact schema" in
  the map-efficient efficient-reference.md (Claude and Codex), with the SKILL
  RESEARCH section naming the exact status enum and pointing at it. Validator
  behavior is unchanged for valid artifacts (no skeleton field is added).
• **Compaction now offloads large tool outputs for on-demand retrieval in...

MAP Framework v3.17.1

[3.17.1] - 2026-06-18

Fixed

• Broken and misleading prose in lower-tier MAP skill prompts (prompt-quality
  audit). Repaired shipped SKILL.md defects surfaced by a PQS audit: the
  /map-tdd ACTOR example carried an unterminated f""" string (would break on
  copy-paste) plus a duplicated <TDD_Tests> placeholder; /map-state declared
  three conflicting versions (frontmatter 1.0.0, metadata 3.1.0, footer
  1.0.0) — now all 3.1.0; the auto-generated Troubleshooting footer in
  /map-fast, /map-debug, /map-tdd, and /map-release referenced a
  non-existent "What this command CANNOT do" section and shipped a
  <typical args> placeholder Examples block; the /map-release validation-gate
  matrix listed a "Black format" gate that make check never runs (black is
  make format only); and /map-skill-eval Troubleshooting required a
  non-existent id field on eval-set entries (cell_ids are derived).

Changed

• Strengthened inhibition (NEVER rules) and output contracts in read/write MAP
  skills. /map-state, /map-tokenreport, /map-memory-now, and
  /map-skill-eval gained explicit Constraints (NEVER) blocks (single-writer
  enforcement, no direct step_state.json/run-log edits, read-only guarantees,
  no auto-persisting secrets or flipping user config) plus fixed output-report
  templates and a skill-eval self-check — raising prompt quality without changing
  runtime behavior. The /map-debug, /map-fast, /map-tdd, and /map-release
  Examples/Troubleshooting sections now reference real sections and real example
  invocations.

MAP Framework v3.17.0

Added

• /map-understand interactive learning mode (#221). MAP now ships an
  opt-in deep-understanding slash surface for Claude and Codex. It keeps a
  transient Markdown checklist in the conversation, teaches code/diffs/workflow
  artifacts incrementally, asks restatement or quiz checks without revealing
  multiple-choice answers early, and stays separate from normal workflow
  verbosity and /map-learn persistence.
• Minimality rollout telemetry can now be inspected before the Phase 3 default
  flip (#180/#183). run_health_report.json records the workflow's historical
  minimality level, and mapify minimality-report compares complete off and
  opt-in cohorts for retry pressure, guard rework, and deferred-YAGNI reversal
  rate before marking the local rollout as candidate, hold, or
  insufficient_data. The report summary now includes sample_gaps,
  cohort_branches, next_actions, and a candidate-only manual_review_gate
  with opt-in branches plus a clarity/underscope checklist, so maintainers can
  see the exact telemetry, stale historical-minimality branches, and human review
  still needed before promotion.
• Decomposer pruning is now contract-gated and user-visible (#184).
  Blueprints can carry requiredness/pruneable metadata per active subtask
  and a deferred_yagni parking lot for speculative omissions. The validator
  rejects non-empty deferred_yagni under minimality: off/lite, requires
  explicit REVIEW_PLAN approval warnings under full/ultra, and Actor context
  now preserves approved omissions so they are not silently implemented or lost.
• Deferred YAGNI items can be restored before approval (#184).
  map_orchestrator.py restore_deferred_yagni YG-NNN moves one parking-lot
  item into active subtasks, appends it to the task plan, and clears prior plan
  approval so REVIEW_PLAN cannot proceed on stale scope.
• Research-agent localization quality can now be scored deterministically
  (#200). Maintainers can parse ResearchEvidence JSON or path:line[-end]
  text citations, validate them against a fixture repo, and compute file-level
  plus line-overlap precision/recall/F1 without live provider credentials.
  The scorer is exposed as mapify research-eval score and covered by the
  no-provider E2E artifact-contract suite.

Changed

• /map-explain now respects the user's language and scales depth to target
  size (#224). The skill writes prose in the user's established language
  (code, identifiers, commands, and file:line refs stay English) instead of
  always defaulting to English. The rigid always-emit-all-10-sections /
  explain-every-line structure is replaced by a signal-first output spec:
  size tiers with word-budget ceilings and load-bearing-line caps, a front-loaded
  "Mental model in 60 seconds" block, read-tier section tags
  ([MUST READ]/[READ IF MODIFYING]/[SKIM]), a single load-bearing-lines
  table (merging the old "what every line does" + "why each line" sections,
  repeated shapes explained once), before→after-first ordering for diffs,
  adaptive sections with an Omitted: footer, and natural-language follow-up
  offers. Applies to both the Claude and Codex surfaces.
• Research artifacts are now unified and consumed before broad search
  (#209/#210). Planning and per-subtask research now share a single artifact
  shape across /map-plan, /map-efficient, and the research-agent, and Actor
  is required to consume the persisted research artifact before launching its
  own broad codebase search — enforced by map_step_runner.py so research spend
  is not duplicated or ignored.