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.

MAP Framework v3.16.0

Added

• Research ROI is now visible in token and run-health diagnostics (#202).
  token_accounting.json records advisory research_roi, /map-tokenreport prints per-agent cost plus research-vs-Actor/Monitor token share, and run_health_report.json summarizes persisted research artifacts, parsed status/confidence/location counts, low-confidence warnings, and token share.

MAP Framework v3.15.2

[3.15.2] - 2026-06-15

Changed

• Codex researcher now shares the Claude research-agent ResearchEvidence
  contract (#198). Codex may use provider-specific search commands internally,
  but /map-efficient research artifacts now explicitly preserve the same strict
  JSON fields, bounded file-line evidence, and downstream Actor/Monitor
  semantics across providers.

MAP Framework v3.15.1

[3.15.1] - 2026-06-15

Fixed

• /map-efficient now distinguishes mandatory RESEARCH artifacts from conditional research-agent delegation (#201). Hook hints, Claude/Codex workflow skills, orchestrator validation errors, and docs now tell operators to persist a research artifact before Actor while using research-agent / researcher only for broad, high-risk, or unclear discovery.

MAP Framework v3.15.0

Added

• MAP RESEARCH artifacts are now validated before Actor work (#197).
  validate_research checks strict JSON, confidence/status/search stats,
  bounded file-line evidence, safe relative paths, and over-broad location lists;
  validate_step 2.2 now blocks malformed or missing research before Actor can
  consume it.