mapify-cli 3.15.0__tar.gz → 3.15.2__tar.gz

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.15.0
+Version: 3.15.2
 Summary: MAP Framework installer - Modular Agentic Planner for Claude Code
 Project-URL: Homepage, https://github.com/azalio/map-framework
 Project-URL: Repository, https://github.com/azalio/map-framework.git

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "3.15.0"
+version = "3.15.2"
 description = "MAP Framework installer - Modular Agentic Planner for Claude Code"
 authors = [{ name = "MAP Framework Contributors" }]
 readme = "README.md"

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.15.0"
+__version__ = "3.15.2"
 
 import os
 import subprocess

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/codex/agents/researcher.toml

@@ -8,13 +8,18 @@ You are a research agent. Your job is to explore the codebase and gather actiona
 findings for downstream agents (decomposer, actor). You do NOT implement anything.
 You observe, summarize, and report.
 
-## OUTPUT FORMAT (STRICT JSON)
+## OUTPUT FORMAT (STRICT RESEARCH EVIDENCE JSON)
 
-Write ONLY one JSON object to the findings file specified in your task. Do not
+For `/map-efficient` subtask RESEARCH and any task that names `save_research`,
+write ONLY one JSON object to the findings file specified in your task. Do not
 wrap it in markdown or prose. The downstream `validate_research` gate rejects
 malformed JSON, missing confidence, missing line ranges, unsafe paths, and more
 than 5 locations.
 
+This is the same ResearchEvidence contract used by Claude `research-agent`.
+Codex may use provider-specific commands to inspect files, but the saved
+artifact has the same downstream semantics.
+
 ```
 {
   "confidence": 0.85,
@@ -42,6 +47,13 @@ than 5 locations.
 
 Status values: `OK`, `PARTIAL_RESULTS`, `NO_RESULTS`, `SEARCH_FAILED`.
 
+Search method values: `glob_grep` or `grep_read`.
+
+`search_stats` fields:
+- `files_scanned`: total files examined during search.
+- `total_matches_found`: all matches before truncating to the top locations.
+- `results_truncated`: true if more results exist than returned.
+
 ## RULES
 
 1. Target: under 1500 tokens in the findings file.
@@ -52,21 +64,23 @@ Status values: `OK`, `PARTIAL_RESULTS`, `NO_RESULTS`, `SEARCH_FAILED`.
 6. Focus on WHAT EXISTS, not what should be built.
 7. If the task mentions external libraries, note their current usage patterns in the codebase.
 8. Write the findings file once at the end — do not stream partial results.
+9. Add `has_intent: true|false` for every location after checking the cited line range for `# Intent:` comments.
+10. If a planning task explicitly asks for a non-JSON discovery artifact, follow that task's requested format; do not reuse that markdown as a `save_research` artifact.
 
 ## SEARCH STRATEGY
 
-1. Start broad: find relevant directories and entry points.
-   - `find . -type f -name '*.py'` in likely directories
-   - `rg -l 'keyword'` to locate mentions
-2. Then narrow: read specific files that are most relevant.
-   - Focus on function signatures, class definitions, imports
-   - Note line numbers for everything you report
-3. Look for:
-   - Existing tests (to understand testing patterns)
-   - Config files (pyproject.toml, setup.cfg, Makefile)
-   - Similar implementations already in the codebase
-4. Check git history for recent changes to relevant files:
-   - `git log --oneline -n 5 -- path/to/file.py`
+Use the provider-neutral Glob/Grep/Read search protocol even when Codex exposes
+those operations through shell-backed commands:
+
+1. Glob-equivalent file discovery: find likely directories and file patterns.
+2. Grep-equivalent content search: locate exact symbols, imports, and keywords.
+3. Read-equivalent narrow inspection: open only the most relevant files and cite
+   function signatures, class definitions, imports, and inclusive line ranges.
+4. AAG-filter results against the requested Actor/Action/Goal when provided.
+5. Intent-inspect each returned range for `# Intent:` comments and set
+   `has_intent` accordingly.
+6. Use git history only when the task explicitly asks for recent-change or
+   regression context; never substitute history for file-line evidence.
 
 ## DO NOT
 

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/codex/hooks/workflow-gate.py

@@ -43,11 +43,12 @@ EDITING_PHASES = {"ACTOR", "APPLY", "TEST_WRITER"}
 
 # Docs-only file suffixes / path prefixes that are permitted during
 # RESEARCH (2.2). A docs-only subtask (runbook update, README tweak,
-# CHANGELOG line) doesn't benefit from research-agent investigation,
-# but the unconditional RESEARCH gate forced operators to save an
-# empty research stub before they could edit a .md file. Allowing
-# obvious docs surfaces during RESEARCH preserves the intent (block
-# code edits before research) without the friction.
+# CHANGELOG line) usually doesn't need delegated research-agent
+# investigation, but the unconditional RESEARCH edit gate forced
+# operators to save an empty research stub before they could edit a .md
+# file. Allowing obvious docs surfaces during RESEARCH preserves the
+# intent (block code edits before research) without the friction; the
+# state machine still requires a persisted artifact before Actor closes.
 DOCS_ONLY_EXTENSIONS = {".md", ".mdx", ".rst", ".txt", ".adoc"}
 DOCS_ONLY_PATH_PREFIXES = ("docs/", "doc/", "documentation/", "CHANGELOG", "RELEASING", "README")
 
@@ -120,12 +121,12 @@ def extract_target_file_paths(tool_call: dict) -> list[str]:
 def is_docs_only_path(file_path: str) -> bool:
     """Return True if path is documentation that may be edited during RESEARCH.
 
-    RESEARCH (2.2) blocks Edit by default — research-agent must run
-    before code mutation. Docs surfaces (README, runbook, CHANGELOG)
-    don't benefit from research-agent, so the unconditional block
-    forced operators to save an empty research stub. Allowing docs
-    files during RESEARCH preserves the intent (no code edits before
-    research) without the friction.
+    RESEARCH (2.2) blocks Edit by default — a persisted research
+    artifact must exist before code mutation. Docs surfaces (README,
+    runbook, CHANGELOG) usually don't need delegated research-agent, so
+    the unconditional edit block forced operators to save an empty
+    research stub. Allowing docs files during RESEARCH preserves the
+    intent (no code edits before research) without the friction.
     """
     if not isinstance(file_path, str) or not file_path.strip():
         return False

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/codex/skills/map-efficient/SKILL.md

@@ -159,9 +159,13 @@ fi
 
 ### RESEARCH
 
-Use `researcher` when independent exploration is useful; otherwise research in
-the current session. Persist concise strict-JSON findings, validate the research
-contract, then close RESEARCH before Actor work:
+Persist a RESEARCH artifact for every non-no-op subtask before Actor. Use
+`researcher` when independent exploration is useful: cold-start repository
+exploration, 3+ existing files, high risk, unclear locations, or failed direct
+search. Otherwise research in the current session and save concise strict-JSON
+findings. If the subtask truly needs no Actor/Monitor, use
+`mark_subtask_complete --reason` instead of closing RESEARCH. Validate the
+research contract, then close RESEARCH before Actor work:
 
 ```bash
 SUBTASK_ID=$(jq -r '.current_subtask_id' ".map/${BRANCH}/step_state.json")

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/hooks/post-compact-context.py

@@ -24,7 +24,7 @@ REPRIME_LIMIT = 1200
 STEP_REQUIRED_ACTIONS = {
     "1.55": "Approve plan before execution state is initialized.",
     "1.56": "Choose execution mode before implementation.",
-    "2.2": "Run research-agent before Actor if context gathering is required.",
+    "2.2": "Persist a RESEARCH artifact before Actor; delegate only when broad discovery is required.",
     "2.3": "Implement only the current subtask, then run Monitor.",
     "2.4": "Run Monitor and treat valid=false as a hard stop.",
 }

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/hooks/workflow-context-injector.py

@@ -344,7 +344,7 @@ def required_action_for_step(step_id: str, step_phase: str) -> str | None:
     if step_id == "1.56":
         return "Choose mode (set_execution_mode step_by_step|batch)"
     if step_id == "2.2":
-        return "Run research-agent (conditional: 3+ existing files or high risk)"
+        return "Persist RESEARCH artifact (research-agent only for broad/high-risk discovery)"
     if step_id == "2.3":
         return "Run Actor"
     if step_id == "2.4":

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/hooks/workflow-gate.py

@@ -43,11 +43,12 @@ EDITING_PHASES = {"ACTOR", "APPLY", "TEST_WRITER"}
 
 # Docs-only file suffixes / path prefixes that are permitted during
 # RESEARCH (2.2). A docs-only subtask (runbook update, README tweak,
-# CHANGELOG line) doesn't benefit from research-agent investigation,
-# but the unconditional RESEARCH gate forced operators to save an
-# empty research stub before they could edit a .md file. Allowing
-# obvious docs surfaces during RESEARCH preserves the intent (block
-# code edits before research) without the friction.
+# CHANGELOG line) usually doesn't need delegated research-agent
+# investigation, but the unconditional RESEARCH edit gate forced
+# operators to save an empty research stub before they could edit a .md
+# file. Allowing obvious docs surfaces during RESEARCH preserves the
+# intent (block code edits before research) without the friction; the
+# state machine still requires a persisted artifact before Actor closes.
 DOCS_ONLY_EXTENSIONS = {".md", ".mdx", ".rst", ".txt", ".adoc"}
 DOCS_ONLY_PATH_PREFIXES = ("docs/", "doc/", "documentation/", "CHANGELOG", "RELEASING", "README")
 
@@ -120,12 +121,12 @@ def extract_target_file_paths(tool_call: dict) -> list[str]:
 def is_docs_only_path(file_path: str) -> bool:
     """Return True if path is documentation that may be edited during RESEARCH.
 
-    RESEARCH (2.2) blocks Edit by default — research-agent must run
-    before code mutation. Docs surfaces (README, runbook, CHANGELOG)
-    don't benefit from research-agent, so the unconditional block
-    forced operators to save an empty research stub. Allowing docs
-    files during RESEARCH preserves the intent (no code edits before
-    research) without the friction.
+    RESEARCH (2.2) blocks Edit by default — a persisted research
+    artifact must exist before code mutation. Docs surfaces (README,
+    runbook, CHANGELOG) usually don't need delegated research-agent, so
+    the unconditional edit block forced operators to save an empty
+    research stub. Allowing docs files during RESEARCH preserves the
+    intent (no code edits before research) without the friction.
     """
     if not isinstance(file_path, str) or not file_path.strip():
         return False

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/map/scripts/map_orchestrator.py

@@ -41,7 +41,7 @@ STEP PHASES (10 total, 8 standard + 2 TDD):
   1.55 REVIEW_PLAN        - User review + explicit approval checkpoint
   1.56 CHOOSE_MODE        - Auto-skipped (always batch mode)
   1.6  INIT_STATE         - Create step_state.json (single source of truth)
-  2.2  RESEARCH           - research-agent (mandatory for all subtasks)
+  2.2  RESEARCH           - persisted research artifact (mandatory; research-agent conditional)
   2.25 TEST_WRITER        - TDD: write tests from spec (TDD mode only)
   2.26 TEST_FAIL_GATE     - TDD: verify tests fail without impl (TDD mode only)
   2.3  ACTOR              - Actor agent implementation
@@ -771,11 +771,13 @@ def get_step_instruction(step_id: str, state: StepState) -> str:
             "Single source of truth for workflow enforcement."
         ),
         "2.2": (
-            "Call Task(subagent_type='research-agent') to research the subtask, "
-            "then persist findings via "
+            "Persist RESEARCH findings for the subtask via "
             "`python3 .map/scripts/map_step_runner.py save_research <branch> "
-            "<subtask_id>`. MANDATORY for all subtasks (validate_step 2.2 "
-            "rejects when no research artifact exists). "
+            "<subtask_id>`. The artifact is MANDATORY for every non-no-op "
+            "subtask (validate_step 2.2 rejects when none exists); "
+            "Task(subagent_type='research-agent') is conditional for broad, "
+            "high-risk, or unclear discovery. If the target file/symbol is "
+            "already known, save direct current-session findings instead. "
             "Short-circuit hint: if this subtask is already done in a prior "
             "PR or is a pure no-op, skip the cycle with "
             "`python3 .map/scripts/map_orchestrator.py mark_subtask_complete "
@@ -1332,10 +1334,11 @@ def validate_step(
                 ),
                 "recommendation": normalized_rec,
             }
-    # RESEARCH (2.2) is documented MANDATORY for every subtask — enforce that
-    # save_research wrote a machine-checkable artifact before letting Actor
-    # proceed. Without this check, "MANDATORY" was prompt-text only and
-    # malformed markdown could be silently passed downstream.
+    # RESEARCH (2.2) requires a persisted artifact for every non-no-op subtask.
+    # The artifact can come from research-agent or direct current-session
+    # findings; enforce the machine-checkable contract before Actor proceeds.
+    # Without this check, "MANDATORY" was prompt-text only and malformed
+    # markdown could be silently passed downstream.
     if step_id == "2.2" and state.current_subtask_id:
         try:
             from map_step_runner import validate_research  # pyright: ignore[reportMissingImports]
@@ -1356,9 +1359,13 @@ def validate_step(
                 "message": (
                     f"RESEARCH artifact invalid for {state.current_subtask_id}: "
                     f"{detail}. "
+                    "Use research-agent for broad/high-risk/unclear discovery, "
+                    "or save direct current-session findings when the target is known. "
                     f"Run: python3 .map/scripts/map_step_runner.py save_research "
-                    f"<branch> {state.current_subtask_id} (defaults kind=actor) "
-                    "then validate_research before validate_step 2.2."
+                    f"<branch> {state.current_subtask_id} (defaults kind=actor), "
+                    "then validate_research before validate_step 2.2. If this "
+                    "subtask needs no Actor/Monitor, use mark_subtask_complete "
+                    "--reason instead."
                 ),
                 "research_report": research_report,
             }

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/references/step-state-schema.md

@@ -53,14 +53,13 @@ Branch name is sanitized (e.g., `feature/foo` → `feature-foo`).
 
 ## Step IDs (map-efficient)
 
-Current step set (linear order; some are conditional):
+Current step set (linear order; some phases use conditional subagents):
 
 1. `1.0` DECOMPOSE
 2. `1.5` INIT_PLAN
 3. `1.55` REVIEW_PLAN
 4. `1.56` CHOOSE_MODE
 5. `1.6` INIT_STATE
-7. `2.2` RESEARCH (conditional)
+7. `2.2` RESEARCH (artifact required; research-agent conditional)
 9. `2.3` ACTOR
 10. `2.4` MONITOR
-

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/skills/map-efficient/SKILL.md

@@ -226,7 +226,7 @@ have ≥2 subtasks AND (b) the subtasks in that wave touch disjoint files
 
 ### No-op subtask short-circuit (before RESEARCH)
 
-Some subtasks are already-done historically (rename/refactor landed in a prior PR), or are docs-only and don't need the full research→actor→monitor cycle. Skip them up-front to save tokens:
+Some subtasks are already-done historically (rename/refactor landed in a prior PR), or truly do not need Actor/Monitor because the requested work is already satisfied by repo state. Skip them up-front to save tokens:
 
 ```bash
 SUBTASK_ID=$(jq -r '.current_subtask_id' ".map/${BRANCH}/step_state.json")
@@ -236,14 +236,14 @@ python3 .map/scripts/map_orchestrator.py mark_subtask_complete "$SUBTASK_ID" \
 
 This records a synthetic subtask_result with status="no-op", marks the phase COMPLETE, and advances the cursor (or closes the workflow if it was the last). Always pass `--reason` so audits know why the work was skipped. If unsure, run RESEARCH first and decide based on its findings.
 
-### Phase: RESEARCH (2.2) - Required
+### Phase: RESEARCH (2.2) - Required artifact; delegated agent conditional
 
-Call `research-agent` for the current subtask, then persist its concise strict-JSON findings via the canonical `save_research` API so Actor and Monitor consume them from the same path. Validate the machine-checkable research contract before closing the phase with the orchestrator.
+Persist a RESEARCH artifact for every non-no-op subtask before Actor. `research-agent` is conditional: use it for cold-start repository exploration, 3+ existing files, high risk, unclear locations, or failed direct search. If the relevant file/symbol is already known, or the subtask is greenfield/new-file work, do narrow current-session research and save those concise strict-JSON findings via the canonical `save_research` API. Validate the machine-checkable research contract before closing the phase with the orchestrator.
 
 ```bash
 SUBTASK_ID=$(jq -r '.current_subtask_id' ".map/${BRANCH}/step_state.json")
 # RECOMMENDED: proactive refresh_blueprint_affected_files <branch>
-# <sid> [--dry-run] BEFORE research-agent (efficient-reference.md).
+# <sid> [--dry-run] BEFORE delegated research (efficient-reference.md).
 printf '%s' "$RESEARCH_FINDINGS" | \
   python3 .map/scripts/map_step_runner.py save_research "$BRANCH" "$SUBTASK_ID"
 # (defaults kind=actor; pass a 4th arg like 'monitor' or 'decomposer' to partition)
@@ -256,7 +256,7 @@ Later phases read with:
 RESEARCH_FINDINGS=$(python3 .map/scripts/map_step_runner.py load_research "$BRANCH" "$SUBTASK_ID")
 ```
 
-The artifact lands under `.map/<branch>/research/<subtask_id>__<kind>.md` and must satisfy the research-agent JSON contract (`status`, `confidence`, `search_stats`, and at most 5 `relevant_locations` with safe relative paths and line ranges). Use `load_research` to fill the `{research_findings}` placeholder in Actor and Monitor prompts below.
+The artifact lands under `.map/<branch>/research/<subtask_id>__<kind>.md` and must satisfy the research evidence JSON contract (`status`, `confidence`, `search_stats`, and at most 5 `relevant_locations` with safe relative paths and line ranges). Use `load_research` to fill the `{research_findings}` placeholder in Actor and Monitor prompts below.
 
 ### Phase: TEST_WRITER (2.25) - TDD Mode Only
 

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates/skills/map-task/SKILL.md

@@ -122,7 +122,7 @@ PHASE=$(echo "$NEXT_STEP" | jq -r '.phase')
 
 Route to the appropriate executor based on `$PHASE`. All phases from `/map-efficient` work identically:
 
-- **RESEARCH (2.2)** — Required context gathering via research-agent.
+- **RESEARCH (2.2)** — Required persisted research artifact; research-agent is conditional for broad/high-risk discovery.
 - **ACTOR (2.3)** — Implement the subtask
 - **MONITOR (2.4)** — Required validation before the subtask can complete.
 

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates_src/codex/agents/researcher.toml.jinja

@@ -8,13 +8,18 @@ You are a research agent. Your job is to explore the codebase and gather actiona
 findings for downstream agents (decomposer, actor). You do NOT implement anything.
 You observe, summarize, and report.
 
-## OUTPUT FORMAT (STRICT JSON)
+## OUTPUT FORMAT (STRICT RESEARCH EVIDENCE JSON)
 
-Write ONLY one JSON object to the findings file specified in your task. Do not
+For `/map-efficient` subtask RESEARCH and any task that names `save_research`,
+write ONLY one JSON object to the findings file specified in your task. Do not
 wrap it in markdown or prose. The downstream `validate_research` gate rejects
 malformed JSON, missing confidence, missing line ranges, unsafe paths, and more
 than 5 locations.
 
+This is the same ResearchEvidence contract used by Claude `research-agent`.
+Codex may use provider-specific commands to inspect files, but the saved
+artifact has the same downstream semantics.
+
 ```
 {
   "confidence": 0.85,
@@ -42,6 +47,13 @@ than 5 locations.
 
 Status values: `OK`, `PARTIAL_RESULTS`, `NO_RESULTS`, `SEARCH_FAILED`.
 
+Search method values: `glob_grep` or `grep_read`.
+
+`search_stats` fields:
+- `files_scanned`: total files examined during search.
+- `total_matches_found`: all matches before truncating to the top locations.
+- `results_truncated`: true if more results exist than returned.
+
 ## RULES
 
 1. Target: under 1500 tokens in the findings file.
@@ -52,21 +64,23 @@ Status values: `OK`, `PARTIAL_RESULTS`, `NO_RESULTS`, `SEARCH_FAILED`.
 6. Focus on WHAT EXISTS, not what should be built.
 7. If the task mentions external libraries, note their current usage patterns in the codebase.
 8. Write the findings file once at the end — do not stream partial results.
+9. Add `has_intent: true|false` for every location after checking the cited line range for `# Intent:` comments.
+10. If a planning task explicitly asks for a non-JSON discovery artifact, follow that task's requested format; do not reuse that markdown as a `save_research` artifact.
 
 ## SEARCH STRATEGY
 
-1. Start broad: find relevant directories and entry points.
-   - `find . -type f -name '*.py'` in likely directories
-   - `rg -l 'keyword'` to locate mentions
-2. Then narrow: read specific files that are most relevant.
-   - Focus on function signatures, class definitions, imports
-   - Note line numbers for everything you report
-3. Look for:
-   - Existing tests (to understand testing patterns)
-   - Config files (pyproject.toml, setup.cfg, Makefile)
-   - Similar implementations already in the codebase
-4. Check git history for recent changes to relevant files:
-   - `git log --oneline -n 5 -- path/to/file.py`
+Use the provider-neutral Glob/Grep/Read search protocol even when Codex exposes
+those operations through shell-backed commands:
+
+1. Glob-equivalent file discovery: find likely directories and file patterns.
+2. Grep-equivalent content search: locate exact symbols, imports, and keywords.
+3. Read-equivalent narrow inspection: open only the most relevant files and cite
+   function signatures, class definitions, imports, and inclusive line ranges.
+4. AAG-filter results against the requested Actor/Action/Goal when provided.
+5. Intent-inspect each returned range for `# Intent:` comments and set
+   `has_intent` accordingly.
+6. Use git history only when the task explicitly asks for recent-change or
+   regression context; never substitute history for file-line evidence.
 
 ## DO NOT
 

{mapify_cli-3.15.0/src/mapify_cli/templates_src → mapify_cli-3.15.2/src/mapify_cli/templates_src/codex}/hooks/workflow-gate.py.jinja

@@ -43,11 +43,12 @@ EDITING_PHASES = {"ACTOR", "APPLY", "TEST_WRITER"}
 
 # Docs-only file suffixes / path prefixes that are permitted during
 # RESEARCH (2.2). A docs-only subtask (runbook update, README tweak,
-# CHANGELOG line) doesn't benefit from research-agent investigation,
-# but the unconditional RESEARCH gate forced operators to save an
-# empty research stub before they could edit a .md file. Allowing
-# obvious docs surfaces during RESEARCH preserves the intent (block
-# code edits before research) without the friction.
+# CHANGELOG line) usually doesn't need delegated research-agent
+# investigation, but the unconditional RESEARCH edit gate forced
+# operators to save an empty research stub before they could edit a .md
+# file. Allowing obvious docs surfaces during RESEARCH preserves the
+# intent (block code edits before research) without the friction; the
+# state machine still requires a persisted artifact before Actor closes.
 DOCS_ONLY_EXTENSIONS = {".md", ".mdx", ".rst", ".txt", ".adoc"}
 DOCS_ONLY_PATH_PREFIXES = ("docs/", "doc/", "documentation/", "CHANGELOG", "RELEASING", "README")
 
@@ -120,12 +121,12 @@ def extract_target_file_paths(tool_call: dict) -> list[str]:
 def is_docs_only_path(file_path: str) -> bool:
     """Return True if path is documentation that may be edited during RESEARCH.
 
-    RESEARCH (2.2) blocks Edit by default — research-agent must run
-    before code mutation. Docs surfaces (README, runbook, CHANGELOG)
-    don't benefit from research-agent, so the unconditional block
-    forced operators to save an empty research stub. Allowing docs
-    files during RESEARCH preserves the intent (no code edits before
-    research) without the friction.
+    RESEARCH (2.2) blocks Edit by default — a persisted research
+    artifact must exist before code mutation. Docs surfaces (README,
+    runbook, CHANGELOG) usually don't need delegated research-agent, so
+    the unconditional edit block forced operators to save an empty
+    research stub. Allowing docs files during RESEARCH preserves the
+    intent (no code edits before research) without the friction.
     """
     if not isinstance(file_path, str) or not file_path.strip():
         return False

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates_src/codex/skills/map-efficient/SKILL.md.jinja

@@ -159,9 +159,13 @@ fi
 
 ### RESEARCH
 
-Use `researcher` when independent exploration is useful; otherwise research in
-the current session. Persist concise strict-JSON findings, validate the research
-contract, then close RESEARCH before Actor work:
+Persist a RESEARCH artifact for every non-no-op subtask before Actor. Use
+`researcher` when independent exploration is useful: cold-start repository
+exploration, 3+ existing files, high risk, unclear locations, or failed direct
+search. Otherwise research in the current session and save concise strict-JSON
+findings. If the subtask truly needs no Actor/Monitor, use
+`mark_subtask_complete --reason` instead of closing RESEARCH. Validate the
+research contract, then close RESEARCH before Actor work:
 
 ```bash
 SUBTASK_ID=$(jq -r '.current_subtask_id' ".map/${BRANCH}/step_state.json")

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates_src/hooks/post-compact-context.py.jinja

@@ -24,7 +24,7 @@ REPRIME_LIMIT = 1200
 STEP_REQUIRED_ACTIONS = {
     "1.55": "Approve plan before execution state is initialized.",
     "1.56": "Choose execution mode before implementation.",
-    "2.2": "Run research-agent before Actor if context gathering is required.",
+    "2.2": "Persist a RESEARCH artifact before Actor; delegate only when broad discovery is required.",
     "2.3": "Implement only the current subtask, then run Monitor.",
     "2.4": "Run Monitor and treat valid=false as a hard stop.",
 }

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates_src/hooks/workflow-context-injector.py.jinja

@@ -344,7 +344,7 @@ def required_action_for_step(step_id: str, step_phase: str) -> str | None:
     if step_id == "1.56":
         return "Choose mode (set_execution_mode step_by_step|batch)"
     if step_id == "2.2":
-        return "Run research-agent (conditional: 3+ existing files or high risk)"
+        return "Persist RESEARCH artifact (research-agent only for broad/high-risk discovery)"
     if step_id == "2.3":
         return "Run Actor"
     if step_id == "2.4":

{mapify_cli-3.15.0/src/mapify_cli/templates_src/codex → mapify_cli-3.15.2/src/mapify_cli/templates_src}/hooks/workflow-gate.py.jinja

@@ -43,11 +43,12 @@ EDITING_PHASES = {"ACTOR", "APPLY", "TEST_WRITER"}
 
 # Docs-only file suffixes / path prefixes that are permitted during
 # RESEARCH (2.2). A docs-only subtask (runbook update, README tweak,
-# CHANGELOG line) doesn't benefit from research-agent investigation,
-# but the unconditional RESEARCH gate forced operators to save an
-# empty research stub before they could edit a .md file. Allowing
-# obvious docs surfaces during RESEARCH preserves the intent (block
-# code edits before research) without the friction.
+# CHANGELOG line) usually doesn't need delegated research-agent
+# investigation, but the unconditional RESEARCH edit gate forced
+# operators to save an empty research stub before they could edit a .md
+# file. Allowing obvious docs surfaces during RESEARCH preserves the
+# intent (block code edits before research) without the friction; the
+# state machine still requires a persisted artifact before Actor closes.
 DOCS_ONLY_EXTENSIONS = {".md", ".mdx", ".rst", ".txt", ".adoc"}
 DOCS_ONLY_PATH_PREFIXES = ("docs/", "doc/", "documentation/", "CHANGELOG", "RELEASING", "README")
 
@@ -120,12 +121,12 @@ def extract_target_file_paths(tool_call: dict) -> list[str]:
 def is_docs_only_path(file_path: str) -> bool:
     """Return True if path is documentation that may be edited during RESEARCH.
 
-    RESEARCH (2.2) blocks Edit by default — research-agent must run
-    before code mutation. Docs surfaces (README, runbook, CHANGELOG)
-    don't benefit from research-agent, so the unconditional block
-    forced operators to save an empty research stub. Allowing docs
-    files during RESEARCH preserves the intent (no code edits before
-    research) without the friction.
+    RESEARCH (2.2) blocks Edit by default — a persisted research
+    artifact must exist before code mutation. Docs surfaces (README,
+    runbook, CHANGELOG) usually don't need delegated research-agent, so
+    the unconditional edit block forced operators to save an empty
+    research stub. Allowing docs files during RESEARCH preserves the
+    intent (no code edits before research) without the friction.
     """
     if not isinstance(file_path, str) or not file_path.strip():
         return False

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates_src/map/scripts/map_orchestrator.py.jinja

@@ -41,7 +41,7 @@ STEP PHASES (10 total, 8 standard + 2 TDD):
   1.55 REVIEW_PLAN        - User review + explicit approval checkpoint
   1.56 CHOOSE_MODE        - Auto-skipped (always batch mode)
   1.6  INIT_STATE         - Create step_state.json (single source of truth)
-  2.2  RESEARCH           - research-agent (mandatory for all subtasks)
+  2.2  RESEARCH           - persisted research artifact (mandatory; research-agent conditional)
   2.25 TEST_WRITER        - TDD: write tests from spec (TDD mode only)
   2.26 TEST_FAIL_GATE     - TDD: verify tests fail without impl (TDD mode only)
   2.3  ACTOR              - Actor agent implementation
@@ -771,11 +771,13 @@ def get_step_instruction(step_id: str, state: StepState) -> str:
             "Single source of truth for workflow enforcement."
         ),
         "2.2": (
-            "Call Task(subagent_type='research-agent') to research the subtask, "
-            "then persist findings via "
+            "Persist RESEARCH findings for the subtask via "
             "`python3 .map/scripts/map_step_runner.py save_research <branch> "
-            "<subtask_id>`. MANDATORY for all subtasks (validate_step 2.2 "
-            "rejects when no research artifact exists). "
+            "<subtask_id>`. The artifact is MANDATORY for every non-no-op "
+            "subtask (validate_step 2.2 rejects when none exists); "
+            "Task(subagent_type='research-agent') is conditional for broad, "
+            "high-risk, or unclear discovery. If the target file/symbol is "
+            "already known, save direct current-session findings instead. "
             "Short-circuit hint: if this subtask is already done in a prior "
             "PR or is a pure no-op, skip the cycle with "
             "`python3 .map/scripts/map_orchestrator.py mark_subtask_complete "
@@ -1332,10 +1334,11 @@ def validate_step(
                 ),
                 "recommendation": normalized_rec,
             }
-    # RESEARCH (2.2) is documented MANDATORY for every subtask — enforce that
-    # save_research wrote a machine-checkable artifact before letting Actor
-    # proceed. Without this check, "MANDATORY" was prompt-text only and
-    # malformed markdown could be silently passed downstream.
+    # RESEARCH (2.2) requires a persisted artifact for every non-no-op subtask.
+    # The artifact can come from research-agent or direct current-session
+    # findings; enforce the machine-checkable contract before Actor proceeds.
+    # Without this check, "MANDATORY" was prompt-text only and malformed
+    # markdown could be silently passed downstream.
     if step_id == "2.2" and state.current_subtask_id:
         try:
             from map_step_runner import validate_research  # pyright: ignore[reportMissingImports]
@@ -1356,9 +1359,13 @@ def validate_step(
                 "message": (
                     f"RESEARCH artifact invalid for {state.current_subtask_id}: "
                     f"{detail}. "
+                    "Use research-agent for broad/high-risk/unclear discovery, "
+                    "or save direct current-session findings when the target is known. "
                     f"Run: python3 .map/scripts/map_step_runner.py save_research "
-                    f"<branch> {state.current_subtask_id} (defaults kind=actor) "
-                    "then validate_research before validate_step 2.2."
+                    f"<branch> {state.current_subtask_id} (defaults kind=actor), "
+                    "then validate_research before validate_step 2.2. If this "
+                    "subtask needs no Actor/Monitor, use mark_subtask_complete "
+                    "--reason instead."
                 ),
                 "research_report": research_report,
             }

{mapify_cli-3.15.0 → mapify_cli-3.15.2}/src/mapify_cli/templates_src/references/step-state-schema.md.jinja

@@ -53,14 +53,13 @@ Branch name is sanitized (e.g., `feature/foo` → `feature-foo`).
 
 ## Step IDs (map-efficient)
 
-Current step set (linear order; some are conditional):
+Current step set (linear order; some phases use conditional subagents):
 
 1. `1.0` DECOMPOSE
 2. `1.5` INIT_PLAN
 3. `1.55` REVIEW_PLAN
 4. `1.56` CHOOSE_MODE
 5. `1.6` INIT_STATE
-7. `2.2` RESEARCH (conditional)
+7. `2.2` RESEARCH (artifact required; research-agent conditional)
 9. `2.3` ACTOR
 10. `2.4` MONITOR
-