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

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

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

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

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

{mapify_cli-3.14.0 → mapify_cli-3.15.1}/src/mapify_cli/templates/codex/agents/researcher.toml

@@ -8,40 +8,46 @@ 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
+## OUTPUT FORMAT (STRICT JSON)
 
-Write ONLY to the findings file specified in your task.
-Structure findings exactly as follows:
+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.
 
 ```
-## Findings: <topic>
-
-### Relevant Files
-- path/to/file.py:L10-L50 — description of what's there
-- path/to/other.py:L3-L20 — description
-
-### Key Patterns
-- Pattern name: how it works, where it's used
-- Pattern name: how it works, where it's used
-
-### Dependencies
-- External: list of external deps relevant to the task
-- Internal: list of internal modules that interact
-
-### Constraints Discovered
-- Constraint 1: description
-- Constraint 2: description
-
-### Recommendations
-- Recommendation for implementation approach
+{
+  "confidence": 0.85,
+  "status": "OK",
+  "search_method": "glob_grep",
+  "search_stats": {
+    "files_scanned": 50,
+    "total_matches_found": 23,
+    "results_truncated": true
+  },
+  "executive_summary": "One paragraph summary, max 100 words",
+  "relevant_locations": [
+    {
+      "path": "src/auth/service.py",
+      "lines": [45, 67],
+      "signature": "def validate_token(token: str) -> User",
+      "relevance": "Core JWT validation with expiry check",
+      "relevance_score": 0.95,
+      "has_intent": true
+    }
+  ],
+  "patterns_discovered": ["JWT with HS256", "decorator-based auth"]
+}
 ```
 
+Status values: `OK`, `PARTIAL_RESULTS`, `NO_RESULTS`, `SEARCH_FAILED`.
+
 ## RULES
 
 1. Target: under 1500 tokens in the findings file.
-2. Include: file paths, line ranges, function signatures, import patterns.
-3. Exclude: raw search output, full file contents, speculation.
-4. Use shell commands (find, rg/grep, cat) to search the codebase.
+2. Include: safe relative file paths, inclusive line ranges, function signatures, import patterns.
+3. Exclude: raw search output, full file contents, markdown fences, speculation.
+4. Return at most 5 `relevant_locations`, prioritized by relevance.
 5. Read files to understand patterns — do not guess.
 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.

{mapify_cli-3.14.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
@@ -390,8 +391,10 @@ def is_editing_phase(branch: str) -> tuple[bool, Optional[str]]:
             "Required:\n"
             f"  1. echo '<findings>' | python3 .map/scripts/map_step_runner.py \\\n"
             f"       save_research <branch> {subtask}  # default kind=actor\n"
-            f"  2. python3 .map/scripts/map_orchestrator.py validate_step 2.2\n"
-            "  3. Then Edit/Write opens (ACTOR phase).\n"
+            f"  2. python3 .map/scripts/map_step_runner.py validate_research \\\n"
+            f"       <branch> {subtask}\n"
+            f"  3. python3 .map/scripts/map_orchestrator.py validate_step 2.2\n"
+            "  4. Then Edit/Write opens (ACTOR phase).\n"
             "\n"
             f"Note: this block is scoped to {subtask}'s affected_files. Edits to\n"
             "files OUTSIDE that surface (orthogonal hotfixes, repo-root config,\n"

{mapify_cli-3.14.0 → mapify_cli-3.15.1}/src/mapify_cli/templates/codex/skills/map-efficient/SKILL.md

@@ -159,13 +159,19 @@ fi
 
 ### RESEARCH
 
-Use `researcher` when independent exploration is useful; otherwise research in
-the current session. Persist concise findings 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")
 printf '%s' "$RESEARCH_FINDINGS" | \
   python3 .map/scripts/map_step_runner.py save_research "$BRANCH" "$SUBTASK_ID"
+python3 .map/scripts/map_step_runner.py validate_research "$BRANCH" "$SUBTASK_ID"
 python3 .map/scripts/map_orchestrator.py validate_step "$STEP_ID"
 ```
 

{mapify_cli-3.14.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.14.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.14.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
@@ -390,8 +391,10 @@ def is_editing_phase(branch: str) -> tuple[bool, Optional[str]]:
             "Required:\n"
             f"  1. echo '<findings>' | python3 .map/scripts/map_step_runner.py \\\n"
             f"       save_research <branch> {subtask}  # default kind=actor\n"
-            f"  2. python3 .map/scripts/map_orchestrator.py validate_step 2.2\n"
-            "  3. Then Edit/Write opens (ACTOR phase).\n"
+            f"  2. python3 .map/scripts/map_step_runner.py validate_research \\\n"
+            f"       <branch> {subtask}\n"
+            f"  3. python3 .map/scripts/map_orchestrator.py validate_step 2.2\n"
+            "  4. Then Edit/Write opens (ACTOR phase).\n"
             "\n"
             f"Note: this block is scoped to {subtask}'s affected_files. Edits to\n"
             "files OUTSIDE that surface (orthogonal hotfixes, repo-root config,\n"

{mapify_cli-3.14.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,23 +1334,40 @@ def validate_step(
                 ),
                 "recommendation": normalized_rec,
             }
-    # RESEARCH (2.2) is documented MANDATORY for every subtask — enforce that
-    # save_research wrote something before letting Actor proceed. Without this
-    # check, "MANDATORY" was prompt-text only and could be silently skipped.
+    # 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:
-        research_dir = Path(f".map/{branch}/research")
-        # Accept any kind of research artifact for this subtask.
-        if not research_dir.is_dir() or not any(
-            research_dir.glob(f"{state.current_subtask_id}__*.md")
-        ):
+        try:
+            from map_step_runner import validate_research  # pyright: ignore[reportMissingImports]
+            research_report = validate_research(branch, state.current_subtask_id)
+        except ImportError:
+            research_report = {
+                "valid": False,
+                "errors": ["map_step_runner.validate_research could not be imported"],
+            }
+        if not research_report.get("valid"):
+            research_errors = research_report.get("errors")
+            if isinstance(research_errors, list) and research_errors:
+                detail = "; ".join(str(err) for err in research_errors[:3])
+            else:
+                detail = "research artifact is missing or invalid"
             return {
                 "valid": False,
                 "message": (
-                    f"RESEARCH not persisted for {state.current_subtask_id}. "
+                    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) "
-                    "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,
             }
         # Auto-snapshot per-subtask baseline at RESEARCH-complete so the
         # MONITOR-side validate_mutation_boundary check only flags files