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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.15.1
+Version: 3.16.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
@@ -211,9 +211,9 @@ These flows maintain branch-scoped artifacts under `.map/<branch>/` — `bluepri
 - **Mutation boundary constraints** — write-capable Claude and Codex surfaces tell agents not to edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the current subtask requires it. Broader scope is reported as a blocker or tradeoff instead of silently expanding the diff.
 - **Context-first prompt envelopes** — high-context `/map-plan`, `/map-efficient`, `/map-debug`, and `/map-review` prompts wrap branch artifacts in XML-style `<documents>`, then state the `<task>` and `<expected_output>`, so specs, diffs, logs, and schemas stay separated for the model.
 - **Contract-sized subtasks** — blueprints require `expected_diff_size`, `concern_type`, `one_logical_step`, `hard_constraints`, `soft_constraints`, and `coverage_map`. Hard constraints must be owned in `coverage_map` and cited in the owning subtask; soft constraints can be traded off only with explicit `tradeoff_rationale`.
-- **Token budget report** — Actor and review prompt builders append active-path budget decisions to `.map/<branch>/token_budget.json` (before/after estimated tokens, clipped sections, source artifacts). The operator breadcrumb for diagnosing missing context.
+- **Token budget and research ROI reports** — Actor and review prompt builders append active-path budget decisions to `.map/<branch>/token_budget.json`, while `token_accounting.json` and `/map-tokenreport` separate research-agent/researcher cost from Actor/Monitor cost so operators can see whether delegated research paid for itself.
 - **Clean retry quarantine** — after repeated Monitor rejection, write-capable workflows switch the next attempt into clean-retry mode using `.map/<branch>/retry_quarantine.json` (constraints, required evidence, do-not-repeat feedback) instead of raw failed-session context.
-- **Run health report** — workflows write `.map/<branch>/run_health_report.json` during closeout: terminal status, step progress, retry counters, artifact presence, hook-injection status. CI can fail inconsistent closeouts with `python3 .map/scripts/map_step_runner.py validate_run_health_report`.
+- **Run health report** — workflows write `.map/<branch>/run_health_report.json` during closeout: terminal status, step progress, retry counters, artifact presence, hook-injection status, and advisory research artifact/ROI signals. CI can fail inconsistent closeouts with `python3 .map/scripts/map_step_runner.py validate_run_health_report`.
 - **Compact recovery surface** — `/map-resume` keeps the active recovery flow short and moves low-frequency notes to `resume-reference.md`, so recovery after `/clear` or context exhaustion gives the next checkpoint action without loading the whole appendix.
 - **Skill IR audit** — release checks lower shipped Claude and Codex `SKILL.md` files into a typed `SkillIR`, verify content hashes, catch unsupported frontmatter, reject missing supporting-file links, and block injection-like instructions before `mapify init` copies surfaces into user repos.
 

{mapify_cli-3.15.1 → mapify_cli-3.16.0}/README.md

@@ -167,9 +167,9 @@ These flows maintain branch-scoped artifacts under `.map/<branch>/` — `bluepri
 - **Mutation boundary constraints** — write-capable Claude and Codex surfaces tell agents not to edit unrelated files, add or upgrade dependencies, or refactor neighboring code unless the current subtask requires it. Broader scope is reported as a blocker or tradeoff instead of silently expanding the diff.
 - **Context-first prompt envelopes** — high-context `/map-plan`, `/map-efficient`, `/map-debug`, and `/map-review` prompts wrap branch artifacts in XML-style `<documents>`, then state the `<task>` and `<expected_output>`, so specs, diffs, logs, and schemas stay separated for the model.
 - **Contract-sized subtasks** — blueprints require `expected_diff_size`, `concern_type`, `one_logical_step`, `hard_constraints`, `soft_constraints`, and `coverage_map`. Hard constraints must be owned in `coverage_map` and cited in the owning subtask; soft constraints can be traded off only with explicit `tradeoff_rationale`.
-- **Token budget report** — Actor and review prompt builders append active-path budget decisions to `.map/<branch>/token_budget.json` (before/after estimated tokens, clipped sections, source artifacts). The operator breadcrumb for diagnosing missing context.
+- **Token budget and research ROI reports** — Actor and review prompt builders append active-path budget decisions to `.map/<branch>/token_budget.json`, while `token_accounting.json` and `/map-tokenreport` separate research-agent/researcher cost from Actor/Monitor cost so operators can see whether delegated research paid for itself.
 - **Clean retry quarantine** — after repeated Monitor rejection, write-capable workflows switch the next attempt into clean-retry mode using `.map/<branch>/retry_quarantine.json` (constraints, required evidence, do-not-repeat feedback) instead of raw failed-session context.
-- **Run health report** — workflows write `.map/<branch>/run_health_report.json` during closeout: terminal status, step progress, retry counters, artifact presence, hook-injection status. CI can fail inconsistent closeouts with `python3 .map/scripts/map_step_runner.py validate_run_health_report`.
+- **Run health report** — workflows write `.map/<branch>/run_health_report.json` during closeout: terminal status, step progress, retry counters, artifact presence, hook-injection status, and advisory research artifact/ROI signals. CI can fail inconsistent closeouts with `python3 .map/scripts/map_step_runner.py validate_run_health_report`.
 - **Compact recovery surface** — `/map-resume` keeps the active recovery flow short and moves low-frequency notes to `resume-reference.md`, so recovery after `/clear` or context exhaustion gives the next checkpoint action without loading the whole appendix.
 - **Skill IR audit** — release checks lower shipped Claude and Codex `SKILL.md` files into a typed `SkillIR`, verify content hashes, catch unsupported frontmatter, reject missing supporting-file links, and block injection-like instructions before `mapify init` copies surfaces into user repos.
 

{mapify_cli-3.15.1 → mapify_cli-3.16.0}/pyproject.toml

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

{mapify_cli-3.15.1 → mapify_cli-3.16.0}/src/mapify_cli/__init__.py

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

{mapify_cli-3.15.1 → mapify_cli-3.16.0}/src/mapify_cli/schemas.py

@@ -963,6 +963,42 @@ _RUN_HEALTH_ARTIFACT_KEYS = [
 ]
 
 
+_RUN_HEALTH_RESEARCH_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "schema_version": {"type": "string"},
+        "artifact_count": {"type": "integer", "minimum": 0},
+        "valid_artifact_count": {"type": "integer", "minimum": 0},
+        "invalid_artifact_count": {"type": "integer", "minimum": 0},
+        "low_confidence_artifact_count": {"type": "integer", "minimum": 0},
+        "location_count": {"type": "integer", "minimum": 0},
+        "research_tokens": {"type": "integer", "minimum": 0},
+        "research_est_cost_usd": {"type": "number", "minimum": 0},
+        "actor_monitor_tokens": {"type": "integer", "minimum": 0},
+        "actor_monitor_est_cost_usd": {"type": "number", "minimum": 0},
+        "research_token_share": {"type": "number", "minimum": 0},
+        "by_subtask": {"type": "object"},
+        "warnings": {"type": "array", "items": {"type": "string"}},
+    },
+    "required": [
+        "schema_version",
+        "artifact_count",
+        "valid_artifact_count",
+        "invalid_artifact_count",
+        "low_confidence_artifact_count",
+        "location_count",
+        "research_tokens",
+        "research_est_cost_usd",
+        "actor_monitor_tokens",
+        "actor_monitor_est_cost_usd",
+        "research_token_share",
+        "by_subtask",
+        "warnings",
+    ],
+    "additionalProperties": False,
+}
+
+
 RUN_HEALTH_REPORT_SCHEMA = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://mapframework.dev/schemas/run-health-report.json",
@@ -992,6 +1028,7 @@ RUN_HEALTH_REPORT_SCHEMA = {
             "required": _RUN_HEALTH_ARTIFACT_KEYS,
             "additionalProperties": _RUN_HEALTH_ARTIFACT_ENTRY_SCHEMA,
         },
+        "research": _RUN_HEALTH_RESEARCH_SCHEMA,
         "resiliency_signals": {
             "type": "object",
             "properties": {

{mapify_cli-3.15.1 → mapify_cli-3.16.0}/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.1 → mapify_cli-3.16.0}/src/mapify_cli/templates/map/scripts/map_step_runner.py

@@ -711,6 +711,20 @@ def _coerce_token_int(value: object) -> int:
     return 0
 
 
+def _coerce_token_float(value: object) -> float:
+    """Best-effort float from a cost/share field that may come from JSON."""
+    if isinstance(value, bool):
+        return 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except ValueError:
+            return 0.0
+    return 0.0
+
+
 def _usage_token_total(usage: Mapping[str, object]) -> int:
     """Sum of the four token fields for one usage record.
 
@@ -926,6 +940,104 @@ def _empty_token_bucket() -> dict[str, float]:
     return {field: 0 for field in _TOKEN_FIELDS}
 
 
+_RESEARCH_AGENT_NAMES = frozenset({"research-agent", "researcher"})
+_ACTOR_MONITOR_AGENT_NAMES = frozenset({"actor", "monitor"})
+_RESEARCH_LOW_CONFIDENCE_THRESHOLD = 0.5
+
+
+def _empty_token_counter_bucket() -> dict[str, float]:
+    return {**_empty_token_bucket(), "est_cost_usd": 0.0, "event_count": 0}
+
+
+def _accumulate_token_bucket(
+    bucket: dict[str, float], usage: Mapping[str, object], row_cost: float
+) -> None:
+    for field in _TOKEN_FIELDS:
+        bucket[field] += _coerce_token_int(usage.get(field, 0))
+    bucket["est_cost_usd"] = round(bucket.get("est_cost_usd", 0.0) + row_cost, 6)
+    bucket["event_count"] = bucket.get("event_count", 0) + 1
+
+
+def _token_bucket_total(bucket: Mapping[str, object]) -> int:
+    return sum(_coerce_token_int(bucket.get(field, 0)) for field in _TOKEN_FIELDS)
+
+
+def _is_research_token_source(agent: str, phase: str) -> bool:
+    return agent in _RESEARCH_AGENT_NAMES or phase.upper() == "RESEARCH"
+
+
+def _is_actor_monitor_token_source(agent: str, phase: str) -> bool:
+    return agent in _ACTOR_MONITOR_AGENT_NAMES or phase.upper() in {"ACTOR", "MONITOR"}
+
+
+def _build_research_roi_summary(
+    research_by_subtask: Mapping[str, Mapping[str, object]],
+    actor_monitor_by_subtask: Mapping[str, Mapping[str, object]],
+    aggregate: Mapping[str, object],
+) -> dict[str, object]:
+    """Return advisory research cost vs downstream Actor/Monitor cost."""
+    aggregate_tokens = _token_bucket_total(aggregate)
+    total_research_tokens = sum(
+        _token_bucket_total(bucket) for bucket in research_by_subtask.values()
+    )
+    total_actor_monitor_tokens = sum(
+        _token_bucket_total(bucket) for bucket in actor_monitor_by_subtask.values()
+    )
+    total_research_cost = round(
+        sum(
+            _coerce_token_float(bucket.get("est_cost_usd", 0.0))
+            for bucket in research_by_subtask.values()
+        ),
+        6,
+    )
+    total_actor_monitor_cost = round(
+        sum(
+            _coerce_token_float(bucket.get("est_cost_usd", 0.0))
+            for bucket in actor_monitor_by_subtask.values()
+        ),
+        6,
+    )
+
+    by_subtask: dict[str, dict[str, object]] = {}
+    for sid in sorted(set(research_by_subtask) | set(actor_monitor_by_subtask)):
+        research_bucket = research_by_subtask.get(sid, {})
+        downstream_bucket = actor_monitor_by_subtask.get(sid, {})
+        research_tokens = _token_bucket_total(research_bucket)
+        downstream_tokens = _token_bucket_total(downstream_bucket)
+        comparable_tokens = research_tokens + downstream_tokens
+        by_subtask[sid] = {
+            "research_tokens": research_tokens,
+            "research_est_cost_usd": round(
+                _coerce_token_float(research_bucket.get("est_cost_usd", 0.0)), 6
+            ),
+            "research_event_count": _coerce_token_int(
+                research_bucket.get("event_count", 0)
+            ),
+            "actor_monitor_tokens": downstream_tokens,
+            "actor_monitor_est_cost_usd": round(
+                _coerce_token_float(downstream_bucket.get("est_cost_usd", 0.0)), 6
+            ),
+            "actor_monitor_event_count": _coerce_token_int(
+                downstream_bucket.get("event_count", 0)
+            ),
+            "research_token_share": round(research_tokens / comparable_tokens, 4)
+            if comparable_tokens
+            else 0.0,
+        }
+
+    return {
+        "schema_version": "1.0",
+        "research_tokens": total_research_tokens,
+        "research_est_cost_usd": total_research_cost,
+        "actor_monitor_tokens": total_actor_monitor_tokens,
+        "actor_monitor_est_cost_usd": total_actor_monitor_cost,
+        "research_token_share": round(total_research_tokens / aggregate_tokens, 4)
+        if aggregate_tokens
+        else 0.0,
+        "by_subtask": by_subtask,
+    }
+
+
 def _rebuild_token_accounting(branch: Optional[str] = None) -> dict[str, object]:
     """Roll token_log.jsonl up into token_accounting.json.
 
@@ -942,6 +1054,8 @@ def _rebuild_token_accounting(branch: Optional[str] = None) -> dict[str, object]
     by_subtask: dict[str, dict[str, float]] = {}
     by_agent: dict[str, dict[str, float]] = {}
     by_phase: dict[str, dict[str, float]] = {}
+    research_by_subtask: dict[str, dict[str, float]] = {}
+    actor_monitor_by_subtask: dict[str, dict[str, float]] = {}
     aggregate: dict[str, float] = _empty_token_bucket()
     total_cost = 0.0
     event_count = 0
@@ -991,10 +1105,13 @@ def _rebuild_token_accounting(branch: Optional[str] = None) -> dict[str, object]
             }
             row_cost = _token_cost(usage, model)
             total_cost += row_cost
+            subtask_id = str(row.get("subtask_id") or "unattributed")
+            agent = str(row.get("agent") or "unknown")
+            phase = str(row.get("phase") or "unknown")
             for dim_key, dim in (
-                (str(row.get("subtask_id") or "unattributed"), by_subtask),
-                (str(row.get("agent") or "unknown"), by_agent),
-                (str(row.get("phase") or "unknown"), by_phase),
+                (subtask_id, by_subtask),
+                (agent, by_agent),
+                (phase, by_phase),
             ):
                 bucket = dim.setdefault(
                     dim_key, {**_empty_token_bucket(), "est_cost_usd": 0.0}
@@ -1007,6 +1124,23 @@ def _rebuild_token_accounting(branch: Optional[str] = None) -> dict[str, object]
             for field in _TOKEN_FIELDS:
                 aggregate[field] += usage[field]
 
+            if _is_research_token_source(agent, phase):
+                _accumulate_token_bucket(
+                    research_by_subtask.setdefault(
+                        subtask_id, _empty_token_counter_bucket()
+                    ),
+                    usage,
+                    row_cost,
+                )
+            elif _is_actor_monitor_token_source(agent, phase):
+                _accumulate_token_bucket(
+                    actor_monitor_by_subtask.setdefault(
+                        subtask_id, _empty_token_counter_bucket()
+                    ),
+                    usage,
+                    row_cost,
+                )
+
     cache_read = aggregate["cache_read"]
     cacheable = aggregate["input"] + cache_read
     aggregate["cache_hit_ratio"] = (
@@ -1023,6 +1157,9 @@ def _rebuild_token_accounting(branch: Optional[str] = None) -> dict[str, object]
         "by_subtask": by_subtask,
         "by_agent": by_agent,
         "by_phase": by_phase,
+        "research_roi": _build_research_roi_summary(
+            research_by_subtask, actor_monitor_by_subtask, aggregate
+        ),
     }
     _write_json_file(get_branch_dir(branch_name) / TOKEN_ACCOUNTING_NAME, payload)
     return payload
@@ -1034,6 +1171,8 @@ def token_report(branch: Optional[str] = None) -> str:
     payload = _rebuild_token_accounting(branch_name)
     aggregate = cast(dict[str, float], payload["aggregate"])
     by_subtask = cast(dict[str, dict[str, float]], payload["by_subtask"])
+    by_agent = cast(dict[str, dict[str, float]], payload["by_agent"])
+    research_roi = cast(dict[str, object], payload.get("research_roi", {}))
 
     header = (
         f"{'subtask':<18}{'input':>13}{'output':>12}"
@@ -1061,6 +1200,24 @@ def token_report(branch: Optional[str] = None) -> str:
         rows.append(_fmt(sid, by_subtask[sid]))
     rows.append("-" * len(header))
     rows.append(_fmt("TOTAL", aggregate))
+
+    if by_agent:
+        rows.extend(["", "By agent", header, "-" * len(header)])
+        for agent in sorted(by_agent):
+            rows.append(_fmt(agent, by_agent[agent]))
+
+    rows.append("")
+    research_tokens = _coerce_token_int(research_roi.get("research_tokens", 0))
+    actor_monitor_tokens = _coerce_token_int(
+        research_roi.get("actor_monitor_tokens", 0)
+    )
+    research_share = _coerce_token_float(research_roi.get("research_token_share", 0.0)) * 100
+    rows.append(
+        "research ROI: "
+        f"research {research_tokens:,} tokens / "
+        f"actor+monitor {actor_monitor_tokens:,} tokens "
+        f"({research_share:.1f}% of run tokens)"
+    )
     rows.append("")
     ratio = float(aggregate.get("cache_hit_ratio", 0.0)) * 100
     rows.append(
@@ -3213,6 +3370,158 @@ def _run_health_artifact_inventory(
     }
 
 
+def _default_research_roi_summary() -> dict[str, object]:
+    return {
+        "schema_version": "1.0",
+        "research_tokens": 0,
+        "research_est_cost_usd": 0.0,
+        "actor_monitor_tokens": 0,
+        "actor_monitor_est_cost_usd": 0.0,
+        "research_token_share": 0.0,
+        "by_subtask": {},
+    }
+
+
+def _research_filename_parts(path: Path) -> tuple[str, str]:
+    if "__" not in path.stem:
+        return (path.stem, "unknown")
+    subtask_id, kind = path.stem.split("__", 1)
+    return (subtask_id or "unknown", kind or "unknown")
+
+
+def _research_health_subtask_entry(
+    by_subtask: dict[str, dict[str, object]], subtask_id: str
+) -> dict[str, object]:
+    return by_subtask.setdefault(
+        subtask_id,
+        {
+            "artifact_count": 0,
+            "valid_artifact_count": 0,
+            "invalid_artifact_count": 0,
+            "low_confidence_artifact_count": 0,
+            "location_count": 0,
+            "statuses": [],
+            "kinds": [],
+            "research_tokens": 0,
+            "research_est_cost_usd": 0.0,
+            "actor_monitor_tokens": 0,
+            "actor_monitor_est_cost_usd": 0.0,
+            "research_token_share": 0.0,
+        },
+    )
+
+
+def _append_unique_string(values: object, value: str) -> None:
+    if isinstance(values, list) and value not in values:
+        values.append(value)
+
+
+def _load_research_roi_for_health(branch_dir: Path, branch: str) -> dict[str, object]:
+    token_log_path = branch_dir / TOKEN_LOG_NAME
+    accounting_path = branch_dir / TOKEN_ACCOUNTING_NAME
+    if token_log_path.is_file():
+        accounting = _rebuild_token_accounting(branch)
+    else:
+        accounting = _read_json_file(accounting_path) or {}
+    if not isinstance(accounting, Mapping):
+        return _default_research_roi_summary()
+    roi = accounting.get("research_roi")
+    return dict(roi) if isinstance(roi, Mapping) else _default_research_roi_summary()
+
+
+def _research_health_summary(branch_dir: Path, branch: str) -> dict[str, object]:
+    """Summarize research artifacts and advisory token ROI for run health."""
+    research_dir = branch_dir / "research"
+    project_dir = branch_dir.parents[1] if len(branch_dir.parents) > 1 else Path.cwd()
+    paths = sorted(research_dir.glob("*.md")) if research_dir.is_dir() else []
+    roi = _load_research_roi_for_health(branch_dir, branch)
+    by_subtask: dict[str, dict[str, object]] = {}
+
+    roi_by_subtask = roi.get("by_subtask")
+    if isinstance(roi_by_subtask, Mapping):
+        for subtask_id, raw_entry in roi_by_subtask.items():
+            if not isinstance(raw_entry, Mapping):
+                continue
+            entry = _research_health_subtask_entry(by_subtask, str(subtask_id))
+            for key in (
+                "research_tokens",
+                "research_est_cost_usd",
+                "actor_monitor_tokens",
+                "actor_monitor_est_cost_usd",
+                "research_token_share",
+            ):
+                if key in raw_entry:
+                    entry[key] = raw_entry[key]
+
+    artifact_count = 0
+    valid_count = 0
+    invalid_count = 0
+    low_confidence_count = 0
+    location_count = 0
+    warnings: list[str] = []
+
+    for path in paths:
+        artifact_count += 1
+        subtask_id, kind = _research_filename_parts(path)
+        entry = _research_health_subtask_entry(by_subtask, subtask_id)
+        entry["artifact_count"] = _coerce_token_int(entry.get("artifact_count", 0)) + 1
+        _append_unique_string(entry.get("kinds"), kind)
+
+        report = validate_research_artifact(path, project_dir=project_dir)
+        if report.get("valid"):
+            valid_count += 1
+            entry["valid_artifact_count"] = (
+                _coerce_token_int(entry.get("valid_artifact_count", 0)) + 1
+            )
+        else:
+            invalid_count += 1
+            entry["invalid_artifact_count"] = (
+                _coerce_token_int(entry.get("invalid_artifact_count", 0)) + 1
+            )
+            errors = report.get("errors")
+            if isinstance(errors, list) and errors:
+                warnings.append(f"{path.name}: {errors[0]}")
+
+        status = report.get("research_status")
+        if isinstance(status, str):
+            _append_unique_string(entry.get("statuses"), status)
+            if status in {"SEARCH_FAILED", "NO_RESULTS", "PARTIAL_RESULTS"}:
+                warnings.append(f"{path.name}: research status {status}")
+
+        confidence = report.get("confidence")
+        if isinstance(confidence, (int, float)) and not isinstance(confidence, bool):
+            if float(confidence) < _RESEARCH_LOW_CONFIDENCE_THRESHOLD:
+                low_confidence_count += 1
+                entry["low_confidence_artifact_count"] = (
+                    _coerce_token_int(entry.get("low_confidence_artifact_count", 0)) + 1
+                )
+                warnings.append(f"{path.name}: low confidence {float(confidence):.2f}")
+
+        locations = _coerce_token_int(report.get("location_count", 0))
+        location_count += locations
+        entry["location_count"] = _coerce_token_int(entry.get("location_count", 0)) + locations
+
+    return {
+        "schema_version": "1.0",
+        "artifact_count": artifact_count,
+        "valid_artifact_count": valid_count,
+        "invalid_artifact_count": invalid_count,
+        "low_confidence_artifact_count": low_confidence_count,
+        "location_count": location_count,
+        "research_tokens": _coerce_token_int(roi.get("research_tokens", 0)),
+        "research_est_cost_usd": _coerce_token_float(
+            roi.get("research_est_cost_usd", 0.0)
+        ),
+        "actor_monitor_tokens": _coerce_token_int(roi.get("actor_monitor_tokens", 0)),
+        "actor_monitor_est_cost_usd": _coerce_token_float(
+            roi.get("actor_monitor_est_cost_usd", 0.0)
+        ),
+        "research_token_share": _coerce_token_float(roi.get("research_token_share", 0.0)),
+        "by_subtask": by_subtask,
+        "warnings": warnings[:10],
+    }
+
+
 def write_run_health_report(
     workflow: str = "map-efficient",
     terminal_status: str = "",
@@ -3245,6 +3554,7 @@ def write_run_health_report(
     retry_isolation_status = _as_dict(state.get("retry_isolation_status"))
     hook_injection = _as_dict(state.get("hook_injection"))
     artifact_inventory = _run_health_artifact_inventory(branch_dir, branch_name)
+    research_summary = _research_health_summary(branch_dir, branch_name)
 
     payload: dict[str, object] = {
         "schema_version": "1.0",
@@ -3258,6 +3568,7 @@ def write_run_health_report(
         "completed_step_count": _count_step_entries(completed_steps),
         "pending_step_count": _count_step_entries(pending_steps),
         "artifacts": artifact_inventory,
+        "research": research_summary,
         "resiliency_signals": {
             "hook_injection": hook_injection
             or {"status": "unknown", "reason": "not recorded"},
@@ -3342,6 +3653,7 @@ def _validate_run_health_report_shape(report: Mapping[str, object]) -> list[str]
         "current_step_id",
         "current_step_phase",
         "current_subtask_id",
+        "research",
     }
     for key in sorted(RUN_HEALTH_REQUIRED_KEYS - set(report)):
         errors.append(f"missing required field: {key}")
@@ -3379,6 +3691,36 @@ def _validate_run_health_report_shape(report: Mapping[str, object]) -> list[str]
             if not _is_non_negative_int(size_bytes):
                 errors.append(f"artifacts.{key}.size_bytes must be a non-negative integer")
 
+    research = report.get("research")
+    if "research" in report:
+        if not isinstance(research, Mapping):
+            errors.append("research must be an object")
+        else:
+            for key in (
+                "artifact_count",
+                "valid_artifact_count",
+                "invalid_artifact_count",
+                "low_confidence_artifact_count",
+                "location_count",
+                "research_tokens",
+                "actor_monitor_tokens",
+            ):
+                if key in research and not _is_non_negative_int(research.get(key)):
+                    errors.append(f"research.{key} must be a non-negative integer")
+            for key in (
+                "research_est_cost_usd",
+                "actor_monitor_est_cost_usd",
+                "research_token_share",
+            ):
+                if key in research and not isinstance(research.get(key), (int, float)):
+                    errors.append(f"research.{key} must be a number")
+            if "by_subtask" in research and not isinstance(
+                research.get("by_subtask"), Mapping
+            ):
+                errors.append("research.by_subtask must be an object")
+            if "warnings" in research and not isinstance(research.get("warnings"), list):
+                errors.append("research.warnings must be an array")
+
     signals = report.get("resiliency_signals")
     if not isinstance(signals, Mapping):
         errors.append("resiliency_signals must be an object")

{mapify_cli-3.15.1 → mapify_cli-3.16.0}/src/mapify_cli/templates/skills/map-tokenreport/SKILL.md

@@ -29,6 +29,9 @@ appends attributed rows to `.map/<branch>/token_log.jsonl`, rolled up into
   caching is paying off.
 - Breakdowns by subtask, by agent (actor / monitor / research-agent /
   orchestrator / ...), and by phase.
+- **research_roi** — research-agent / Codex researcher tokens and cost compared
+  with downstream Actor/Monitor tokens, so users can see whether delegated
+  exploration paid for itself.
 
 ## Steps
 
@@ -48,24 +51,25 @@ python3 .map/scripts/map_step_runner.py token_report "$BRANCH"
 ```
 
 `token_report` re-reads `token_log.jsonl`, rebuilds `token_accounting.json`,
-and prints a per-subtask table plus a TOTAL line with the cache-hit ratio and
-estimated cost. It is idempotent and read-only against your code.
+and prints a per-subtask table, a per-agent table, research ROI, and a TOTAL
+line with the cache-hit ratio and estimated cost. It is idempotent and read-only
+against your code.
 
 ### Step 3: Optional — inspect the raw rollup
 
-For the per-agent / per-phase split (the table only shows per-subtask), read
-the JSON directly:
+For the per-phase split or per-subtask research ROI details, read the JSON
+directly:
 
 ```bash
-jq '{aggregate, by_agent, by_phase}' ".map/${BRANCH}/token_accounting.json"
+jq '{aggregate, by_agent, by_phase, research_roi}' ".map/${BRANCH}/token_accounting.json"
 ```
 
 ### Step 4: Summarize
 
-Report the totals (input / output / cache), the cache-hit ratio, and the
-estimated cost. Call out the most expensive subtask or agent, and a low
-cache-hit ratio if present (it usually means prompt-cache churn worth
-investigating). Then STOP — do not change code from this skill.
+Report the totals (input / output / cache), the cache-hit ratio, the research
+token share, and the estimated cost. Call out the most expensive subtask or
+agent, a low cache-hit ratio, or research cost that looks high relative to
+Actor/Monitor. Then STOP — do not change code from this skill.
 
 ## Examples