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

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

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

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

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

{mapify_cli-3.14.0 → mapify_cli-3.15.0}/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.0}/src/mapify_cli/templates/codex/hooks/workflow-gate.py

@@ -390,8 +390,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.0}/src/mapify_cli/templates/codex/skills/map-efficient/SKILL.md

@@ -160,12 +160,14 @@ fi
 ### RESEARCH
 
 Use `researcher` when independent exploration is useful; otherwise research in
-the current session. Persist concise findings before Actor work:
+the current session. Persist concise strict-JSON findings, 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.0}/src/mapify_cli/templates/hooks/workflow-gate.py

@@ -390,8 +390,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.0}/src/mapify_cli/templates/map/scripts/map_orchestrator.py

@@ -1333,22 +1333,34 @@ 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.
+    # 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.
     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}. "
                     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."
+                    "then validate_research before validate_step 2.2."
                 ),
+                "research_report": research_report,
             }
         # Auto-snapshot per-subtask baseline at RESEARCH-complete so the
         # MONITOR-side validate_mutation_boundary check only flags files

{mapify_cli-3.14.0 → mapify_cli-3.15.0}/src/mapify_cli/templates/map/scripts/map_step_runner.py

@@ -38,7 +38,7 @@ import subprocess
 import sys
 import time
 from datetime import datetime, timezone
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Callable, Iterable, Mapping, Optional, TypedDict, cast
 
 # Keep in sync with workflow-context-injector.py GOAL_HEADING_RE
@@ -6046,6 +6046,13 @@ def _sanitize_branch(branch: str) -> str:
 
 _RESEARCH_KIND_RE = re.compile(r"^[a-z][a-z0-9_]*$")
 _RESEARCH_SUBTASK_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+_RESEARCH_STATUS_VALUES = frozenset(
+    {"OK", "PARTIAL_RESULTS", "NO_RESULTS", "SEARCH_FAILED"}
+)
+_RESEARCH_MAX_ARTIFACT_BYTES = 64 * 1024
+_RESEARCH_MAX_LOCATIONS = 5
+_RESEARCH_MAX_LINE_SPAN = 200
+_RESEARCH_ABSENT_LOCATION_STATUSES = frozenset({"absent", "missing", "new", "not_found"})
 
 
 def _research_path(branch: str, subtask_id: str, kind: str) -> Path:
@@ -6070,6 +6077,304 @@ def _research_path(branch: str, subtask_id: str, kind: str) -> Path:
     )
 
 
+def _is_int_not_bool(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _location_marks_absent(location: Mapping[str, object]) -> bool:
+    if location.get("exists") is False or location.get("absent") is True:
+        return True
+    status = location.get("status")
+    return (
+        isinstance(status, str)
+        and status.strip().lower() in _RESEARCH_ABSENT_LOCATION_STATUSES
+    )
+
+
+def _validate_research_location(
+    location: object,
+    index: int,
+    *,
+    project_dir: Path,
+) -> tuple[list[str], list[str]]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    prefix = f"relevant_locations[{index}]"
+    if not isinstance(location, dict):
+        return [f"{prefix} must be an object"], warnings
+
+    path_value = location.get("path")
+    if not isinstance(path_value, str) or not path_value.strip():
+        errors.append(f"{prefix}.path must be a non-empty relative path")
+    else:
+        path_text = path_value.strip()
+        pure_path = PurePosixPath(path_text)
+        if (
+            pure_path.is_absolute()
+            or path_text.startswith("~")
+            or "\\" in path_text
+            or any(part == ".." for part in pure_path.parts)
+        ):
+            errors.append(f"{prefix}.path must be a safe relative repo path")
+        else:
+            target = project_dir / Path(*pure_path.parts)
+            if target.exists() and not target.is_file():
+                errors.append(f"{prefix}.path points to a directory, not a file")
+            elif not target.exists() and not _location_marks_absent(location):
+                errors.append(
+                    f"{prefix}.path does not exist; mark the location absent/new if intentional"
+                )
+
+    raw_lines = location.get("lines", location.get("line_range"))
+    if not isinstance(raw_lines, list) or len(raw_lines) != 2:
+        errors.append(f"{prefix}.lines must be [start, end]")
+    elif not all(_is_int_not_bool(part) for part in raw_lines):
+        errors.append(f"{prefix}.lines values must be positive integers")
+    else:
+        start = int(raw_lines[0])
+        end = int(raw_lines[1])
+        if start < 1 or end < 1 or start > end:
+            errors.append(f"{prefix}.lines must be a positive inclusive range")
+        elif end - start + 1 > _RESEARCH_MAX_LINE_SPAN:
+            errors.append(
+                f"{prefix}.lines spans more than {_RESEARCH_MAX_LINE_SPAN} lines"
+            )
+        elif isinstance(path_value, str) and path_value.strip():
+            pure_path = PurePosixPath(path_value.strip())
+            if (
+                not pure_path.is_absolute()
+                and "\\" not in path_value
+                and not any(part == ".." for part in pure_path.parts)
+            ):
+                target = project_dir / Path(*pure_path.parts)
+                if target.is_file():
+                    try:
+                        line_count = len(target.read_text(encoding="utf-8").splitlines())
+                    except (OSError, UnicodeDecodeError):
+                        line_count = 0
+                    if line_count and end > line_count:
+                        errors.append(
+                            f"{prefix}.lines end exceeds file length ({line_count})"
+                        )
+
+    relevance = location.get("relevance")
+    if not isinstance(relevance, str) or not relevance.strip():
+        errors.append(f"{prefix}.relevance must explain why the location matters")
+
+    for raw_key in ("content", "file_contents", "raw_code"):
+        if raw_key in location:
+            errors.append(f"{prefix}.{raw_key} is not allowed; cite paths and ranges only")
+
+    return errors, warnings
+
+
+def validate_research_content(
+    content: str,
+    *,
+    project_dir: Optional[Path] = None,
+    artifact_path: Optional[str] = None,
+    max_locations: int = _RESEARCH_MAX_LOCATIONS,
+) -> dict[str, object]:
+    """Validate the machine-checkable research-agent output contract."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    project = project_dir or Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+    encoded_size = len(content.encode("utf-8"))
+    if encoded_size > _RESEARCH_MAX_ARTIFACT_BYTES:
+        errors.append(
+            f"artifact exceeds {_RESEARCH_MAX_ARTIFACT_BYTES} bytes ({encoded_size})"
+        )
+
+    stripped = content.strip()
+    if not stripped:
+        errors.append("artifact is empty")
+        return {
+            "valid": False,
+            "status": "invalid",
+            "artifact_path": artifact_path,
+            "errors": errors,
+            "warnings": warnings,
+        }
+    if "```" in stripped:
+        errors.append("artifact must not contain markdown/code fences or raw code blocks")
+
+    parsed: object
+    try:
+        parsed = json.loads(stripped)
+    except json.JSONDecodeError as exc:
+        errors.append(f"artifact must be strict JSON: {exc.msg}")
+        return {
+            "valid": False,
+            "status": "invalid",
+            "artifact_path": artifact_path,
+            "errors": errors,
+            "warnings": warnings,
+        }
+
+    if not isinstance(parsed, dict):
+        errors.append("artifact JSON must be an object")
+        return {
+            "valid": False,
+            "status": "invalid",
+            "artifact_path": artifact_path,
+            "errors": errors,
+            "warnings": warnings,
+        }
+
+    research_status = parsed.get("status")
+    if research_status not in _RESEARCH_STATUS_VALUES:
+        errors.append(
+            "status must be one of " + ", ".join(sorted(_RESEARCH_STATUS_VALUES))
+        )
+
+    confidence = parsed.get("confidence")
+    if (
+        isinstance(confidence, bool)
+        or not isinstance(confidence, (int, float))
+        or not 0 <= float(confidence) <= 1
+    ):
+        errors.append("confidence must be a number between 0 and 1")
+
+    search_stats = parsed.get("search_stats")
+    if not isinstance(search_stats, dict):
+        errors.append("search_stats must be an object")
+    else:
+        for key in ("files_scanned", "total_matches_found"):
+            value = search_stats.get(key)
+            if not _is_int_not_bool(value):
+                errors.append(f"search_stats.{key} must be a non-negative integer")
+            elif cast(int, value) < 0:
+                errors.append(f"search_stats.{key} must be a non-negative integer")
+        if not isinstance(search_stats.get("results_truncated"), bool):
+            errors.append("search_stats.results_truncated must be boolean")
+
+    locations = parsed.get("relevant_locations")
+    location_count = 0
+    if not isinstance(locations, list):
+        errors.append("relevant_locations must be a list")
+    else:
+        location_count = len(locations)
+        if len(locations) > max_locations:
+            errors.append(
+                f"relevant_locations must contain at most {max_locations} entries"
+            )
+        for index, location in enumerate(locations):
+            loc_errors, loc_warnings = _validate_research_location(
+                location,
+                index,
+                project_dir=project,
+            )
+            errors.extend(loc_errors)
+            warnings.extend(loc_warnings)
+
+    return {
+        "valid": not errors,
+        "status": "valid" if not errors else "invalid",
+        "artifact_path": artifact_path,
+        "errors": errors,
+        "warnings": warnings,
+        "research_status": research_status if isinstance(research_status, str) else None,
+        "confidence": float(confidence) if isinstance(confidence, (int, float)) and not isinstance(confidence, bool) else None,
+        "location_count": location_count,
+    }
+
+
+def validate_research_artifact(path: Path, *, project_dir: Optional[Path] = None) -> dict[str, object]:
+    """Validate one persisted research artifact file."""
+    if not path.is_file():
+        return {
+            "valid": False,
+            "status": "missing",
+            "artifact_path": str(path),
+            "errors": [f"research artifact not found: {path}"],
+            "warnings": [],
+        }
+    try:
+        content = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return {
+            "valid": False,
+            "status": "invalid",
+            "artifact_path": str(path),
+            "errors": [f"could not read research artifact: {exc}"],
+            "warnings": [],
+        }
+    return validate_research_content(
+        content,
+        project_dir=project_dir,
+        artifact_path=str(path),
+    )
+
+
+def validate_research(
+    branch: str,
+    subtask_id: str,
+    *,
+    kind: Optional[str] = None,
+) -> dict[str, object]:
+    """Validate persisted research for a subtask before Actor consumes it."""
+    project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+    artifacts: list[dict[str, object]] = []
+    errors: list[str] = []
+
+    if kind is not None:
+        paths = [_research_path(branch, subtask_id, kind)]
+    else:
+        seed_path = _research_path(branch, subtask_id, "actor")
+        research_dir = seed_path.parent
+        paths = []
+        if research_dir.is_dir():
+            for candidate in sorted(research_dir.glob(f"{subtask_id}__*.md")):
+                if ".attempt-" in candidate.name:
+                    continue
+                stem = candidate.stem
+                marker = "__"
+                if marker not in stem:
+                    continue
+                kind_name = stem.rsplit(marker, 1)[-1]
+                if not _RESEARCH_KIND_RE.match(kind_name):
+                    errors.append(f"invalid research artifact kind in filename: {candidate.name}")
+                    continue
+                paths.append(candidate)
+
+    if not paths:
+        seed = _research_path(branch, subtask_id, kind or "actor")
+        return {
+            "valid": False,
+            "status": "missing",
+            "subtask_id": subtask_id,
+            "kind": kind,
+            "artifacts": [],
+            "errors": [f"no research artifact found for {subtask_id} under {seed.parent}"],
+            "warnings": [],
+        }
+
+    warnings: list[str] = []
+    for path in paths:
+        report = validate_research_artifact(path, project_dir=project_dir)
+        artifacts.append(report)
+        report_errors = report.get("errors")
+        if isinstance(report_errors, list):
+            for error in report_errors:
+                if isinstance(error, str):
+                    errors.append(f"{path.name}: {error}")
+        report_warnings = report.get("warnings")
+        if isinstance(report_warnings, list):
+            for warning in report_warnings:
+                if isinstance(warning, str):
+                    warnings.append(f"{path.name}: {warning}")
+
+    return {
+        "valid": not errors,
+        "status": "valid" if not errors else "invalid",
+        "subtask_id": subtask_id,
+        "kind": kind,
+        "artifacts": artifacts,
+        "errors": errors,
+        "warnings": warnings,
+    }
+
+
 def save_research(
     branch: str,
     subtask_id: str,
@@ -9777,6 +10082,20 @@ if __name__ == "__main__":
             print(json.dumps({"status": "error", "message": str(exc)}))
             sys.exit(1)
 
+    elif func_name == "validate_research" and len(sys.argv) >= 4:
+        # CLI: validate_research <branch> <subtask_id> [kind]
+        branch_arg = sys.argv[2]
+        subtask_arg = sys.argv[3]
+        kind_arg = sys.argv[4] if len(sys.argv) >= 5 else None
+        try:
+            report = validate_research(branch_arg, subtask_arg, kind=kind_arg)
+            print(json.dumps(report, indent=2))
+            if not report.get("valid"):
+                sys.exit(1)
+        except ValueError as exc:
+            print(json.dumps({"status": "error", "message": str(exc)}))
+            sys.exit(1)
+
     elif func_name == "load_research" and len(sys.argv) >= 4:
         # CLI: load_research <branch> <subtask_id> [kind] [--all]
         # Content to stdout. On error: write the diagnostic to STDERR

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

@@ -238,7 +238,7 @@ This records a synthetic subtask_result with status="no-op", marks the phase COM
 
 ### Phase: RESEARCH (2.2) - Required
 
-Call `research-agent` for the current subtask, then persist its concise findings via the canonical `save_research` API so Actor and Monitor consume them from the same path. Validate the phase with the orchestrator.
+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.
 
 ```bash
 SUBTASK_ID=$(jq -r '.current_subtask_id' ".map/${BRANCH}/step_state.json")
@@ -247,15 +247,16 @@ 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"
 # (defaults kind=actor; pass a 4th arg like 'monitor' or 'decomposer' to partition)
+python3 .map/scripts/map_step_runner.py validate_research "$BRANCH" "$SUBTASK_ID"
+python3 .map/scripts/map_orchestrator.py validate_step 2.2
 ```
 
 Later phases read with:
-
 ```bash
 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`. 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-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.
 
 ### Phase: TEST_WRITER (2.25) - TDD Mode Only
 

{mapify_cli-3.14.0 → mapify_cli-3.15.0}/src/mapify_cli/templates/skills/map-plan/SKILL.md

@@ -308,6 +308,7 @@ Runner functions you'll commonly need from `/map-plan`:
 | `list_plans` | List per-branch plan artifacts under `.map/` to pick scope from a multi-roadmap workspace. |
 | `check_plan_resume "<request>" [--branch <b>]` | Resume preflight: reports existing artifacts + a `verdict` (`no_plan`/`resume`/`goal_mismatch`) comparing the prior plan's goal against the incoming request, so a branch hosting a *completed* plan for a different goal isn't falsely treated as "complete". |
 | `save_research <branch> <subtask_id>` | Persist research-agent findings for a subtask (stdin-fed). |
+| `validate_research <branch> <subtask_id>` | Validate strict JSON research evidence before `validate_step 2.2`. |
 
 ### Step 8: Output Checkpoint
 

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

@@ -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.