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

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

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

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

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.16.0"
+__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