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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.15.2
+Version: 3.17.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
@@ -70,6 +70,7 @@ You drive the whole loop with two core commands plus three gates:
 /map-check                                          # 3. CHECK — quality gates against the plan
 /map-review                                         # 4. REVIEW — semantic review vs spec, tests, and diff
 /map-learn                                          # 5. LEARN — save the gotchas for next session
+/map-understand                                     # optional - teach and quiz until the workflow makes sense
 ```
 
 - **Start with `/map-plan`** for anything non-trivial — it clarifies behavior and splits the work into contract-sized subtasks.
@@ -117,6 +118,7 @@ Then enable the Codex hook manually: run `/hooks`, select `PreToolUse`, press `t
 /map-check
 /map-review
 /map-learn
+/map-understand   # optional learning/quiz mode
 ```
 
 That's the whole golden path. Everything below explains *why* it works and *when* to reach for it.
@@ -180,6 +182,7 @@ The DevOpsConf 2026 case study applies this process to a production Kubernetes P
 | `/map-check` | Quality gates, verification, and artifact checks |
 | `/map-review` | Pre-commit semantic review against the plan, tests, and diff |
 | `/map-learn` | Capture project memory and reusable lessons |
+| `/map-understand` | Interactive teaching and quiz mode for code, diffs, and workflow results |
 | `/map-debug` | Bug fixes and debugging |
 | `/map-task` | Execute a single subtask from an existing plan |
 | `/map-tdd` | Test-first implementation workflow |
@@ -211,9 +214,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.
 
@@ -249,7 +252,7 @@ MAP is inspired by the [MAP cognitive architecture](https://github.com/Shanka123
 minimality: lite   # new installs default to lite; existing repos without the key stay off
 ```
 
-Allowed values: `off`, `lite`, `full`, `ultra`. Phase 1 ships conservative `lite` defaults: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate.
+Allowed values: `off`, `lite`, `full`, `ultra`. Phase 1 ships conservative `lite` defaults: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate. In `full`/`ultra`, the decomposer may place speculative omissions in `blueprint.deferred_yagni`; those items must be shown during plan approval and can be restored before execution with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can inspect local rollout readiness with `mapify minimality-report --json`, which compares complete `off` and opt-in run-health samples before considering the Phase 3 default flip, reports missing sample gaps and cohort branch names, lists the next telemetry actions, and emits a candidate-only `manual_review_gate` with opt-in branches plus a clarity/underscope checklist before promotion.
 
 **Context-compression policy** (controls the `/compact` nudge; default `never` — opt-in):
 

{mapify_cli-3.15.2 → mapify_cli-3.17.0}/README.md

@@ -26,6 +26,7 @@ You drive the whole loop with two core commands plus three gates:
 /map-check                                          # 3. CHECK — quality gates against the plan
 /map-review                                         # 4. REVIEW — semantic review vs spec, tests, and diff
 /map-learn                                          # 5. LEARN — save the gotchas for next session
+/map-understand                                     # optional - teach and quiz until the workflow makes sense
 ```
 
 - **Start with `/map-plan`** for anything non-trivial — it clarifies behavior and splits the work into contract-sized subtasks.
@@ -73,6 +74,7 @@ Then enable the Codex hook manually: run `/hooks`, select `PreToolUse`, press `t
 /map-check
 /map-review
 /map-learn
+/map-understand   # optional learning/quiz mode
 ```
 
 That's the whole golden path. Everything below explains *why* it works and *when* to reach for it.
@@ -136,6 +138,7 @@ The DevOpsConf 2026 case study applies this process to a production Kubernetes P
 | `/map-check` | Quality gates, verification, and artifact checks |
 | `/map-review` | Pre-commit semantic review against the plan, tests, and diff |
 | `/map-learn` | Capture project memory and reusable lessons |
+| `/map-understand` | Interactive teaching and quiz mode for code, diffs, and workflow results |
 | `/map-debug` | Bug fixes and debugging |
 | `/map-task` | Execute a single subtask from an existing plan |
 | `/map-tdd` | Test-first implementation workflow |
@@ -167,9 +170,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.
 
@@ -205,7 +208,7 @@ MAP is inspired by the [MAP cognitive architecture](https://github.com/Shanka123
 minimality: lite   # new installs default to lite; existing repos without the key stay off
 ```
 
-Allowed values: `off`, `lite`, `full`, `ultra`. Phase 1 ships conservative `lite` defaults: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate.
+Allowed values: `off`, `lite`, `full`, `ultra`. Phase 1 ships conservative `lite` defaults: Actor prefers the fewest moving parts, Monitor blocks scope drift only when it affects required behavior, and Evaluator scores simplicity without letting it hide missing required work. `/map-review` also adds an advisory what-to-delete lens when minimality is not `off`; its `net: -N` estimate is informational, not a gate. In `full`/`ultra`, the decomposer may place speculative omissions in `blueprint.deferred_yagni`; those items must be shown during plan approval and can be restored before execution with `python3 .map/scripts/map_orchestrator.py restore_deferred_yagni YG-NNN`. Maintainers can inspect local rollout readiness with `mapify minimality-report --json`, which compares complete `off` and opt-in run-health samples before considering the Phase 3 default flip, reports missing sample gaps and cohort branch names, lists the next telemetry actions, and emits a candidate-only `manual_review_gate` with opt-in branches plus a clarity/underscope checklist before promotion.
 
 **Context-compression policy** (controls the `/compact` nudge; default `never` — opt-in):
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "mapify-cli"
-version = "3.15.2"
+version = "3.17.0"
 description = "MAP Framework installer - Modular Agentic Planner for Claude Code"
 authors = [{ name = "MAP Framework Contributors" }]
 readme = "README.md"
@@ -114,6 +114,9 @@ exclude = [
 [tool.ruff]
 extend-exclude = ["tests/skills_eval/fixtures/whole_skill"]
 
+[tool.black]
+target-version = ["py311"]
+
 [[tool.mypy.overrides]]
 module = "yaml"
 ignore_missing_imports = true

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

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.15.2"
+__version__ = "3.17.0"
 
 import os
 import subprocess
@@ -32,7 +32,7 @@ import shutil
 import ssl
 from datetime import datetime
 from pathlib import Path
-from typing import Optional, List, Dict, Any
+from typing import Optional, List, Dict, Any, Mapping
 
 import typer
 import httpx
@@ -145,6 +145,13 @@ skill_eval_app = typer.Typer(
 
 app.add_typer(skill_eval_app, name="skill-eval")
 
+research_eval_app = typer.Typer(
+    name="research-eval",
+    help="Evaluate research-agent localization quality without provider calls",
+)
+
+app.add_typer(research_eval_app, name="research-eval")
+
 
 def version_callback(value: bool):
     """Callback to show version and exit."""
@@ -1265,6 +1272,150 @@ def doctor(debug: bool = typer.Option(False, "--debug", help="Enable debug loggi
             console.print(f"  • {path_name}")
 
 
+def _format_percent(value: Any) -> str:
+    if value is None:
+        return "n/a"
+    try:
+        return f"{float(value):.1%}"
+    except (TypeError, ValueError):
+        return "n/a"
+
+
+def _render_minimality_report(report: Mapping[str, Any]) -> None:
+    summary = report.get("summary")
+    if not isinstance(summary, Mapping):
+        summary = {}
+    branches = report.get("branches")
+    branch_rows = branches if isinstance(branches, list) else []
+
+    console.print("[bold]Minimality rollout report[/bold]")
+    console.print(
+        f"Current config minimality: [cyan]{report.get('current_config_minimality', 'off')}[/cyan]"
+    )
+    console.print(
+        f"Decision: [bold]{summary.get('decision', 'insufficient_data')}[/bold] "
+        f"(ready_for_phase3={summary.get('ready_for_phase3', False)})"
+    )
+    console.print(
+        "Runs: "
+        f"{summary.get('complete_opt_in_runs', 0)} opt-in complete, "
+        f"{summary.get('complete_off_runs', 0)} off-baseline complete, "
+        f"{summary.get('complete_runs_missing_historical_minimality', 0)} inferred"
+    )
+    console.print(
+        "Averages: "
+        f"retry {float(summary.get('avg_retry_events_opt_in', 0.0)):.2f} opt-in vs "
+        f"{float(summary.get('avg_retry_events_off', 0.0)):.2f} off; "
+        f"guard rework {float(summary.get('avg_guard_rework_opt_in', 0.0)):.2f} opt-in vs "
+        f"{float(summary.get('avg_guard_rework_off', 0.0)):.2f} off; "
+        f"YAGNI reversal {_format_percent(summary.get('user_reversal_rate'))}"
+    )
+
+    reasons = summary.get("reasons")
+    if isinstance(reasons, list) and reasons:
+        console.print()
+        console.print("[bold]Reasons[/bold]")
+        for reason in reasons:
+            console.print(f"  - {reason}")
+
+    next_actions = summary.get("next_actions")
+    if isinstance(next_actions, list) and next_actions:
+        console.print()
+        console.print("[bold]Next actions[/bold]")
+        for action in next_actions:
+            console.print(f"  - {action}")
+
+    cohort_branches = summary.get("cohort_branches")
+    if isinstance(cohort_branches, Mapping):
+        cohort_rows = (
+            ("Off baseline", cohort_branches.get("off_baseline")),
+            ("Opt-in", cohort_branches.get("opt_in")),
+            (
+                "Missing historical minimality",
+                cohort_branches.get("missing_historical_minimality"),
+            ),
+        )
+        if any(isinstance(branches, list) and branches for _, branches in cohort_rows):
+            console.print()
+            console.print("[bold]Cohort branches[/bold]")
+            for label, branches in cohort_rows:
+                if isinstance(branches, list) and branches:
+                    console.print(f"  {label}: " + ", ".join(map(str, branches)))
+
+    manual_review_gate = summary.get("manual_review_gate")
+    if (
+        isinstance(manual_review_gate, Mapping)
+        and manual_review_gate.get("required") is True
+    ):
+        console.print()
+        console.print("[bold]Manual review gate[/bold]")
+        candidate_branches = manual_review_gate.get("candidate_branches")
+        if isinstance(candidate_branches, list) and candidate_branches:
+            console.print(
+                "  Candidate opt-in branches: "
+                + ", ".join(map(str, candidate_branches))
+            )
+        checklist = manual_review_gate.get("checklist")
+        if isinstance(checklist, list) and checklist:
+            console.print("  Checklist:")
+            for item in checklist:
+                console.print(f"  - {item}")
+
+    if branch_rows:
+        table = Table(title="Branch Samples", show_header=True, header_style="bold cyan")
+        table.add_column("Branch")
+        table.add_column("Status")
+        table.add_column("Minimality")
+        table.add_column("Source")
+        table.add_column("Retries", justify="right")
+        table.add_column("Guard", justify="right")
+        table.add_column("YAGNI", justify="right")
+        for row in branch_rows:
+            if not isinstance(row, Mapping):
+                continue
+            table.add_row(
+                str(row.get("branch", "")),
+                str(row.get("terminal_status", "")),
+                str(row.get("minimality", "")),
+                str(row.get("minimality_source", "")),
+                str(row.get("retry_events", 0)),
+                str(row.get("guard_rework_events", 0)),
+                f"{row.get('restored_yagni_count', 0)}/{row.get('total_yagni_recommendations', 0)}",
+            )
+        console.print()
+        console.print(table)
+
+
+@app.command("minimality-report")
+def minimality_report(
+    project_path: Path = typer.Option(
+        Path("."),
+        "--path",
+        "-p",
+        help="Project root containing .map/ artifacts",
+    ),
+    min_complete_runs: int = typer.Option(
+        3,
+        "--min-runs",
+        min=1,
+        help="Minimum complete runs required per off/opt-in cohort",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Print the machine-readable report as JSON",
+    ),
+) -> None:
+    """Summarize local minimality telemetry for the Phase 3 default-flip gate."""
+    from mapify_cli.minimality_report import build_minimality_rollout_report
+
+    report = build_minimality_rollout_report(project_path, min_complete_runs)
+    if json_output:
+        console.print_json(data=report)
+        return
+    _render_minimality_report(report)
+
+
 def _mapify_install_kind() -> str:
     """Classify how this mapify CLI is installed.
 
@@ -1388,6 +1539,113 @@ def upgrade():
     )
 
 
+# Research localization eval commands
+
+
+@research_eval_app.command("score")
+def research_eval_score(
+    output_file: Path = typer.Argument(
+        ...,
+        help="ResearchEvidence JSON/text output file to score",
+    ),
+    expected_file: Path = typer.Argument(
+        ...,
+        help="JSON list, or object with expected_locations, of target file ranges",
+    ),
+    repo_root: Optional[Path] = typer.Option(
+        None,
+        "--repo-root",
+        help="Fixture repository root for path and line-range validation",
+    ),
+    fail_under_file_f1: float = typer.Option(
+        0.0,
+        "--fail-under-file-f1",
+        min=0.0,
+        max=1.0,
+        help="Exit 1 when file-level F1 is below this threshold",
+    ),
+    fail_under_line_f1: float = typer.Option(
+        0.0,
+        "--fail-under-line-f1",
+        min=0.0,
+        max=1.0,
+        help="Exit 1 when line-overlap F1 is below this threshold",
+    ),
+    overbroad_line_threshold: int = typer.Option(
+        50,
+        "--overbroad-line-threshold",
+        min=1,
+        help="Count predicted locations above this line span as over-broad",
+    ),
+    fail_on_malformed: bool = typer.Option(
+        True,
+        "--fail-on-malformed/--allow-malformed",
+        help="Exit 1 when parsed output contains malformed locations",
+    ),
+) -> None:
+    """Score research-agent localization against known fixture targets.
+
+    Exit codes:
+      0 - Score meets thresholds
+      1 - Score below threshold or malformed output found
+      2 - Input files are missing or malformed
+    """
+    import json
+
+    from mapify_cli.research_eval import (
+        load_expected_locations,
+        score_research_output,
+        score_to_dict,
+    )
+
+    try:
+        output = output_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        console.print(f"[bold red]Error:[/bold red] cannot read output file: {exc}")
+        raise typer.Exit(2)
+
+    try:
+        expected = load_expected_locations(expected_file)
+    except (OSError, ValueError) as exc:
+        console.print(f"[bold red]Error:[/bold red] cannot load expected targets: {exc}")
+        raise typer.Exit(2)
+
+    root = repo_root.resolve() if repo_root else Path.cwd()
+    score = score_research_output(
+        output,
+        expected,
+        repo_root=root,
+        overbroad_line_threshold=overbroad_line_threshold,
+    )
+
+    failed_reasons: list[str] = []
+    if score.file_level.f1 < fail_under_file_f1:
+        failed_reasons.append(
+            f"file_level.f1 {score.file_level.f1:.3f} < {fail_under_file_f1:.3f}"
+        )
+    if score.line_level.f1 < fail_under_line_f1:
+        failed_reasons.append(
+            f"line_level.f1 {score.line_level.f1:.3f} < {fail_under_line_f1:.3f}"
+        )
+    if fail_on_malformed and score.malformed_count > 0:
+        failed_reasons.append(f"malformed_count {score.malformed_count} > 0")
+
+    payload = {
+        "passed": not failed_reasons,
+        "failed_reasons": failed_reasons,
+        "thresholds": {
+            "fail_under_file_f1": fail_under_file_f1,
+            "fail_under_line_f1": fail_under_line_f1,
+            "fail_on_malformed": fail_on_malformed,
+            "overbroad_line_threshold": overbroad_line_threshold,
+        },
+        "score": score_to_dict(score),
+    }
+    print(json.dumps(payload, indent=2, sort_keys=True))
+    if failed_reasons:
+        raise typer.Exit(1)
+
+
 # Skill-eval commands