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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.15.0
+Version: 3.15.1
 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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "3.15.0"
+version = "3.15.1"
 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.1}/src/mapify_cli/__init__.py

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

{mapify_cli-3.15.0 → mapify_cli-3.15.1}/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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/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/src/mapify_cli/templates_src → mapify_cli-3.15.1/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.1}/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.1}/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.1}/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.1/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.1}/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.1}/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
-

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

@@ -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.1}/src/mapify_cli/templates_src/skills/map-task/SKILL.md.jinja

@@ -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.1}/tests/test_skills.py

@@ -2190,6 +2190,48 @@ class TestMapEfficientSaveResearchWiring:
             "validate_step 2.2 so malformed research cannot reach Actor."
         )
 
+    def test_research_policy_distinguishes_artifact_from_subagent(
+        self, skill_path: Path
+    ) -> None:
+        content = skill_path.read_text(encoding="utf-8")
+        assert "Persist a RESEARCH artifact" in content
+        assert "`research-agent` is conditional" in content
+        assert "Call `research-agent` for the current subtask" not in content
+
+    def test_codex_research_policy_matches_claude_contract(self) -> None:
+        project_root = Path(__file__).parent.parent
+        for relative_path in [
+            Path(".agents/skills/map-efficient/SKILL.md"),
+            Path("src/mapify_cli/templates/codex/skills/map-efficient/SKILL.md"),
+        ]:
+            content = (project_root / relative_path).read_text(encoding="utf-8")
+            assert "Persist a RESEARCH artifact" in content
+            assert "Use" in content
+            assert "`researcher`" in content
+            assert "when independent exploration is useful" in content
+            assert "If the subtask truly needs no Actor/Monitor" in content
+
+    def test_hook_hint_mentions_required_artifact_not_required_subagent(self) -> None:
+        project_root = Path(__file__).parent.parent
+        for relative_path in [
+            Path(".claude/hooks/workflow-context-injector.py"),
+            Path("src/mapify_cli/templates/hooks/workflow-context-injector.py"),
+        ]:
+            content = (project_root / relative_path).read_text(encoding="utf-8")
+            assert "Persist RESEARCH artifact" in content
+            assert "Run research-agent (conditional" not in content
+
+    def test_orchestrator_error_offers_delegated_and_direct_research_paths(self) -> None:
+        project_root = Path(__file__).parent.parent
+        for relative_path in [
+            Path(".map/scripts/map_orchestrator.py"),
+            Path("src/mapify_cli/templates/map/scripts/map_orchestrator.py"),
+        ]:
+            content = (project_root / relative_path).read_text(encoding="utf-8")
+            assert "research-agent conditional" in content
+            assert "Use research-agent for broad/high-risk/unclear discovery" in content
+            assert "save direct current-session findings" in content
+
 
 class TestMapEfficientBuildContextBlockCli:
     """Regression: map-efficient must show the build_context_block CLI form.