mapify-cli 3.20.0__tar.gz → 3.21.0__tar.gz

{mapify_cli-3.20.0 → mapify_cli-3.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.20.0
+Version: 3.21.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.20.0 → mapify_cli-3.21.0}/pyproject.toml

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

{mapify_cli-3.20.0 → mapify_cli-3.21.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.20.0"
+__version__ = "3.21.0"
 
 import os
 import subprocess
@@ -933,6 +933,18 @@ def init(
         total_claude = sum(claude_counts.values())
         tracker.complete("create-claude", f"{total_claude} files")
 
+        # Surface the non-destructive statusline decision so the user knows
+        # whether the context status row was wired or their own was preserved.
+        if claude_counts.get("statusline"):
+            console.print(
+                "[dim]· Context statusline → .claude/settings.local.json "
+                "(remove the statusLine key there to disable)[/dim]"
+            )
+        else:
+            console.print(
+                "[dim]· Existing statusLine detected — MAP statusline not wired[/dim]"
+            )
+
         # Create default .map/config.yaml (project-level settings)
         tracker.add("map-config", "Create .map/config.yaml")
         tracker.start("map-config")

{mapify_cli-3.20.0 → mapify_cli-3.21.0}/src/mapify_cli/config/project_config.py

@@ -17,6 +17,14 @@ logger = logging.getLogger(__name__)
 
 VALID_MINIMALITY = frozenset({"off", "lite", "full", "ultra"})
 VALID_PROMPT_LAYERING = frozenset({"docs_first", "stable_first"})
+VALID_WORKTREE_ISOLATION = frozenset({"off", "auto", "required"})
+VALID_WAVE_MODE = frozenset({"off", "auto", "on"})
+
+# Cross-AI peer review (#288): external AI CLI runtimes map-review can dispatch
+# to. Keep in sync with CROSS_AI_RUNTIMES in the rendered step runner
+# (map_step_runner.py) — the runner owns the per-runtime invocation adapters;
+# this set only gates the config value so a typo falls back to the default.
+VALID_CROSS_AI_RUNTIMES = frozenset({"claude", "codex", "gemini", "opencode"})
 
 
 @dataclass
@@ -128,6 +136,127 @@ class MapConfig:
     # and keep the IDs the framework wrote into comments/strings/test names.
     scrub_internal_ids: bool = True
 
+    # Cross-AI peer review (#288) — opt-in, OFF by default. When enabled AND the
+    # operator passes `map-review --cross-ai <runtime>`, the review is dispatched
+    # to an INDEPENDENT external AI CLI (codex/gemini/claude/opencode) for a
+    # second opinion. This is a DOUBLE-CONSENT gate: the per-run flag is the
+    # explicit egress consent (your diff/code is sent to an external vendor), and
+    # `review.cross_ai.enabled` is the org-level kill-switch — both must be true.
+    # Dotted YAML keys `review.cross_ai.{enabled,runtime,timeout_seconds}` alias
+    # to these snake_case fields (see load_map_config).
+    review_cross_ai_enabled: bool = False
+    # Default external runtime used when `--cross-ai` is passed without an
+    # explicit runtime name. Validated against VALID_CROSS_AI_RUNTIMES.
+    review_cross_ai_runtime: str = "codex"
+    # Per-dispatch timeout (seconds) for the external CLI subprocess. A real
+    # review can take minutes; default 180 balances latency against hangs.
+    review_cross_ai_timeout_seconds: int = 180
+
+    # Per-subtask git worktree isolation (#284) — opt-in, OFF by default. When
+    # enabled, `/map-efficient` runs each subtask's Actor inside a dedicated git
+    # worktree (stored OUT of the working tree, under the repo's common git dir),
+    # then atomically squash-merges the result into the working branch ONLY after
+    # the configured `verification_checks` pass IN the worktree (pre-merge gate).
+    # A rejected attempt (Monitor/Evaluator fail) discards the worktree, so the
+    # working branch is never touched by a bad attempt. This is a TOP-LEVEL
+    # filesystem concern, deliberately NOT nested under review/sofa. Dotted YAML
+    # key `worktree.isolation` aliases to this snake_case field (see
+    # load_map_config). The step runner owns the lifecycle + safety guards.
+    # Enum values:
+    #   "off"      — never create worktrees; sequential execution always.
+    #   "auto"     — create per-subtask worktrees when a parallel color-group
+    #                dispatches; degrade to sequential with a loud warning when git
+    #                worktrees are unavailable (non-git repo, shallow clone, etc.).
+    #                default ON (Slice 6); disable via MAP_EFFICIENT_SEQUENTIAL_ONLY=1
+    #                or set `worktree.isolation: off` in .map/config.yaml.
+    #   "required" — hard-fail before parallel dispatch if worktrees are unavailable.
+    # Backward compat: YAML boolean `false` migrates to `"off"`, `true` to
+    # `"required"` in load_map_config.
+    worktree_isolation: str = "auto"
+    # Bulk-deletion guard threshold: the per-subtask merge refuses when the
+    # worktree branch deletes MORE than this many files vs the base commit
+    # (catches `rm -rf` / hallucinated mass deletion before it reaches the
+    # working branch). 0 disables the guard. Dotted YAML key
+    # `worktree.max_deletions`.
+    worktree_max_deletions: int = 50
+
+    # Parallel wave execution mode (#303, Slice 0 scaffolding — no behavior change
+    # until Slice 3/5 promote the wave-loop to default). Controls whether
+    # `/map-efficient` routes multi-subtask waves through the parallel wave
+    # coordinator or the sequential single-subtask walker.
+    # Enum values:
+    #   "auto" — (default) engage the wave-loop when the color-group has >=2
+    #             independent subtasks AND worktree.isolation != "off"; degrade to
+    #             sequential otherwise. Slice 0: behaves as sequential everywhere
+    #             (the wave-loop promotion and concurrent dispatch land in Slice 3/5).
+    #   "off"  — always sequential; the legacy walker; instant rollback escape hatch.
+    #   "on"   — always attempt parallel dispatch (reserved for Slice 5/6; same as
+    #             "auto" until the concurrent-dispatch step lands).
+    # Dotted YAML key `execution.wave_mode` aliases to this field. YAML 1.1 parses
+    # bare `off`/`on` as booleans — load_map_config migrates them to strings.
+    execution_wave_mode: str = "auto"
+
+    # Maximum number of concurrent Actor workers in a parallel wave dispatch (#303
+    # Slice 5b). Range 1–8; out-of-range values are clamped by clamp_max_actors().
+    # Non-int / bool values fall back to the default 4 (see clamp_max_actors).
+    # Dotted YAML key: `execution.max_actors`.
+    # DORMANT in Slice 5a — parsed and validated but no execution path reads it yet.
+    max_actors: int = 4
+
+    # When True, a single worker that crashes with a transient error in a parallel
+    # wave will be retried once before the wave is aborted. Pairs with max_actors
+    # in Slice 5b concurrent dispatch. Dotted YAML key: `execution.retry_degraded_once`.
+    # DORMANT in Slice 5a — parsed and validated but no execution path reads it yet.
+    retry_degraded_once: bool = False
+
+    # Enable same-turn concurrent Actor dispatch in a parallel wave (#303 Slice 5b).
+    # default ON (Slice 6); disable via MAP_EFFICIENT_SEQUENTIAL_ONLY=1 (global
+    # kill-switch) or set `execution.concurrent_dispatch: false` in .map/config.yaml.
+    # Dotted YAML alias: `execution.concurrent_dispatch`.
+    # YAML 1.1 bare off/on arrive as Python bool, which matches this field type —
+    # no coercion needed (unlike the string enum fields).
+    concurrent_dispatch: bool = True
+
+    # Bounded retry cap for whole-wave rollback/restart in Slice 5b (#303).
+    # Range 1–10; values outside the range are clamped by clamp_max_wave_retries().
+    # Non-int / bool values fall back to the default 3.
+    # Dotted YAML alias: `execution.max_wave_retries`.
+    # DORMANT in 5b.0 — consumed by ST-006's rollback path; no execution path reads
+    # it yet.
+    max_wave_retries: int = 3
+
+
+def clamp_max_actors(n: object) -> int:
+    """Clamp max_actors to the valid range [1, 8], or return the default 4.
+
+    Non-int values (including bool, str, None) return the default 4.
+    int values are clamped: below 1 → 1, above 8 → 8.
+
+    Note: bool is explicitly excluded (isinstance(True, int) is True in Python)
+    because a YAML boolean arriving here is a misconfiguration, not an int.
+    The floor is 1, NOT the default 4 — a valid-but-low int (e.g. 0) is clamped
+    to 1 (minimum legal value), while a non-int/bool/None falls back to 4.
+    """
+    if isinstance(n, bool) or not isinstance(n, int):
+        return 4
+    return max(1, min(8, n))
+
+
+def clamp_max_wave_retries(n: object) -> int:
+    """Clamp max_wave_retries to the valid range [1, 10], or return the default 3.
+
+    Non-int values (including bool, str, None) return the default 3.
+    int values are clamped: below 1 → 1, above 10 → 10.
+
+    Note: bool is explicitly excluded (isinstance(True, int) is True in Python)
+    because a YAML boolean arriving here is a misconfiguration, not an int.
+    The floor is 1 — a valid-but-low int (e.g. 0) is clamped to 1 (minimum
+    legal value), while a non-int/bool/None falls back to the default 3.
+    """
+    if isinstance(n, bool) or not isinstance(n, int):
+        return 3
+    return max(1, min(10, n))
+
 
 def load_map_config(project_path: Path) -> MapConfig:
     """Load MAP config from .map/config.yaml with fallback to defaults.
@@ -187,6 +316,38 @@ def load_map_config(project_path: Path) -> MapConfig:
         if isinstance(data, dict) and "sofa.enabled" in data and "sofa_enabled" not in data:
             data["sofa_enabled"] = data.pop("sofa.enabled")
 
+        # Cross-AI peer review (#288): dotted hierarchical YAML keys
+        # `review.cross_ai.*` alias to flat snake_case dataclass fields. Without
+        # this the toggles are silent dead fields (load logs "unknown key" and
+        # the defaults stand even when the YAML sets them).
+        for dotted, field_name in (
+            ("review.cross_ai.enabled", "review_cross_ai_enabled"),
+            ("review.cross_ai.runtime", "review_cross_ai_runtime"),
+            ("review.cross_ai.timeout_seconds", "review_cross_ai_timeout_seconds"),
+            ("worktree.isolation", "worktree_isolation"),
+            ("worktree.max_deletions", "worktree_max_deletions"),
+            ("execution.wave_mode", "execution_wave_mode"),
+            ("execution.max_actors", "max_actors"),
+            ("execution.retry_degraded_once", "retry_degraded_once"),
+            ("execution.concurrent_dispatch", "concurrent_dispatch"),
+            ("execution.max_wave_retries", "max_wave_retries"),
+        ):
+            if dotted in data and field_name not in data:
+                data[field_name] = data.pop(dotted)
+
+        # Backward compat: worktree_isolation was a bool field; YAML `false`/`true`
+        # (and YAML 1.1 `off`/`on`) arrive as Python booleans. Migrate to the new
+        # enum string before the type-check loop (which expects str).
+        if isinstance(data.get("worktree_isolation"), bool):
+            data["worktree_isolation"] = (
+                "required" if data["worktree_isolation"] else "off"
+            )
+
+        # YAML 1.1 parses bare `off`/`on` as booleans for execution.wave_mode too.
+        # Coerce back to strings: False->"off", True->"on".
+        if isinstance(data.get("execution_wave_mode"), bool):
+            data["execution_wave_mode"] = "on" if data["execution_wave_mode"] else "off"
+
         # YAML 1.1 parses bare ``off``/``on`` as booleans, so ``minimality: off``
         # — the documented opt-out from the lite default (#183) — arrives as bool
         # ``False``. Coerce it back to the string level before the type-check loop;
@@ -262,6 +423,61 @@ def load_map_config(project_path: Path) -> MapConfig:
             )
             cfg.prompt_layering = "docs_first"
 
+        if cfg.review_cross_ai_runtime not in VALID_CROSS_AI_RUNTIMES:
+            logger.warning(
+                "Invalid review_cross_ai_runtime %r in %s (expected one of %s). "
+                "Using default 'codex'.",
+                cfg.review_cross_ai_runtime,
+                config_file,
+                ", ".join(sorted(VALID_CROSS_AI_RUNTIMES)),
+            )
+            cfg.review_cross_ai_runtime = "codex"
+
+        if cfg.review_cross_ai_timeout_seconds <= 0:
+            logger.warning(
+                "review_cross_ai_timeout_seconds must be > 0 in %s "
+                "(got %d). Using default 180.",
+                config_file,
+                cfg.review_cross_ai_timeout_seconds,
+            )
+            cfg.review_cross_ai_timeout_seconds = 180
+
+        if cfg.worktree_max_deletions < 0:
+            logger.warning(
+                "worktree_max_deletions must be >= 0 in %s "
+                "(got %d). Using default 50.",
+                config_file,
+                cfg.worktree_max_deletions,
+            )
+            cfg.worktree_max_deletions = 50
+
+        if cfg.worktree_isolation not in VALID_WORKTREE_ISOLATION:
+            logger.warning(
+                "Invalid worktree_isolation %r in %s (expected one of %s). "
+                "Using default 'off'.",
+                cfg.worktree_isolation,
+                config_file,
+                ", ".join(sorted(VALID_WORKTREE_ISOLATION)),
+            )
+            cfg.worktree_isolation = "off"
+
+        if cfg.execution_wave_mode not in VALID_WAVE_MODE:
+            logger.warning(
+                "Invalid execution_wave_mode %r in %s (expected one of %s). "
+                "Using default 'auto'.",
+                cfg.execution_wave_mode,
+                config_file,
+                ", ".join(sorted(VALID_WAVE_MODE)),
+            )
+            cfg.execution_wave_mode = "auto"
+
+        # Clamp max_actors to [1, 8]; non-int/bool → default 4.
+        # retry_degraded_once and concurrent_dispatch are plain bools handled by
+        # the generic type-check loop.
+        cfg.max_actors = clamp_max_actors(cfg.max_actors)
+        # Clamp max_wave_retries to [1, 10]; non-int/bool → default 3.
+        cfg.max_wave_retries = clamp_max_wave_retries(cfg.max_wave_retries)
+
         return cfg
 
     except yaml.YAMLError as e:
@@ -391,6 +607,67 @@ minimality: lite
 # Enable via `mapify init --sofa` or uncomment the line below.
 # sofa.enabled: false
 
+# Cross-AI peer review (#288) — opt-in, OFF by default. When enabled AND you run
+# `map-review --cross-ai <runtime>`, the review is dispatched to an INDEPENDENT
+# external AI CLI (codex/gemini/claude/opencode) for a second opinion. DOUBLE
+# CONSENT: your diff/code is sent to an external vendor, so BOTH the per-run flag
+# AND `review.cross_ai.enabled: true` are required. Returned findings always
+# enter context behind an EXTERNAL UNTRUSTED REFERENCE boundary (quote, never
+# execute, verify against source).
+# review.cross_ai.enabled: false
+# review.cross_ai.runtime: codex          # default target: claude|codex|gemini|opencode
+# review.cross_ai.timeout_seconds: 180
+
+# Per-subtask git worktree isolation (#284). Controls filesystem isolation for
+# each Actor run in `/map-efficient`. Enum values:
+#   off      — never create worktrees; sequential execution always.
+#   auto     — (DEFAULT, Slice 6) create per-subtask worktrees when a parallel
+#              color-group dispatches; degrade gracefully to sequential when git
+#              worktrees are unavailable (non-git repo, shallow clone, etc.).
+#   required — hard-fail before dispatch if worktrees are unavailable (first-party
+#              repos that must never degrade silently).
+# When on (auto/required), each Actor runs inside a dedicated git worktree stored
+# under the repo's .git common dir and is squash-merged back ONLY after
+# verification_checks pass. A rejected attempt is discarded — the working branch
+# is never touched by a bad Actor attempt.
+# OFF-RAMPS: set worktree.isolation: off (per-repo opt-out) OR set env
+# MAP_EFFICIENT_SEQUENTIAL_ONLY=1 (global kill-switch — forces full legacy path).
+# Backward compat: the old boolean `false`/`true` still works (migrates to off/required).
+# worktree.isolation: auto   # default ON (Slice 6); use off to revert
+# worktree.max_deletions: 50   # refuse a merge deleting more than N files (0 = off)
+
+# Parallel wave execution mode (#303). Controls whether `/map-efficient` routes
+# multi-subtask waves through the parallel coordinator or the sequential walker.
+#   auto — (default) engage the wave-loop when >=2 independent subtasks AND
+#           worktree.isolation != off; otherwise sequential.
+#   off  — always sequential; instant rollback escape hatch.
+#   on   — always attempt parallel (same as auto in Slice 6).
+# execution.wave_mode: auto
+
+# Concurrent Actor limit for parallel wave dispatch (#303 Slice 5b).
+# Valid range 1–8; values outside the range are clamped (0→1, 9→8).
+# Non-int / bool values fall back to the default 4.
+# execution.max_actors: 4
+
+# Retry a crashed worker once before aborting the wave (Slice 5b).
+# execution.retry_degraded_once: false
+
+# Enable same-turn concurrent Actor dispatch (#303 Slice 6). DEFAULT True.
+# YAML 1.1 bare off/on arrive as bool.
+# OFF-RAMPS: set false here (per-repo opt-out) OR MAP_EFFICIENT_SEQUENTIAL_ONLY=1 (global).
+# execution.concurrent_dispatch: true   # default ON (Slice 6); use false to revert
+
+# Bounded retry cap for whole-wave rollback/restart (#303 Slice 5b).
+# Valid range 1–10; values outside the range are clamped (0→1, 99→10).
+# Non-int / bool values fall back to the default 3.
+# execution.max_wave_retries: 3
+
+# Global kill-switch (Slice 6 off-ramp). Forces the FULL legacy sequential path
+# regardless of any config — no wave-loop, no worktrees, no concurrent dispatch.
+# Byte-identical to pre-5a legacy behavior. Set as an environment variable:
+#   export MAP_EFFICIENT_SEQUENTIAL_ONLY=1   # or true/yes/y/on
+# Unset (or empty / "0" / "false") to restore default parallel behavior.
+
 # Strip MAP-internal workflow IDs (ST-/AC-/VC-/INV-/HC-) from the code a run
 # changed, at workflow completion (Stop hook). On by default; uncomment and set
 # to false to keep the IDs the framework wrote into comments/strings/test names.

{mapify_cli-3.20.0 → mapify_cli-3.21.0}/src/mapify_cli/delivery/file_copier.py

@@ -6,6 +6,7 @@ import importlib.util
 import json
 import os
 import shutil
+from dataclasses import dataclass
 from pathlib import Path
 from typing import List
 
@@ -623,6 +624,102 @@ def create_config_files(
     return count
 
 
+@dataclass
+class StatuslineResult:
+    """Outcome of :func:`ensure_map_statusline`.
+
+    ``wired`` is True only when a fresh ``statusLine`` entry was written.
+    ``reason`` is ``"wired"`` on success, or ``"existing:<scope>"`` when an
+    existing status line in the ``user`` / ``project`` / ``local`` scope was
+    detected and left untouched.
+    """
+
+    wired: bool
+    reason: str
+    settings_path: Path | None = None
+
+
+def _read_json_object(path: Path) -> dict | None:
+    """Return a parsed JSON object, or None if missing/unreadable/not an object."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _has_status_line(path: Path) -> bool:
+    """True when *path* is a settings JSON that already defines a ``statusLine``."""
+    obj = _read_json_object(path)
+    return bool(obj and obj.get("statusLine"))
+
+
+def ensure_map_statusline(
+    project_path: Path,
+    *,
+    home: Path | None = None,
+) -> StatuslineResult:
+    """Non-destructively wire the MAP context status line.
+
+    Claude Code's ``statusLine`` setting fully owns the status row, so MAP must
+    never overwrite a status line the user already configured. This detects an
+    existing ``statusLine`` in every scope MAP must respect — highest precedence
+    first —
+
+      * ``<project>/.claude/settings.local.json`` (project-local overrides)
+      * ``<project>/.claude/settings.json``       (project, MAP-managed)
+      * ``~/.claude/settings.json``               (user global)
+
+    and, only when NONE is present, merges a ``statusLine`` entry pointing at the
+    installed ``map-statusline.py`` hook into ``.claude/settings.local.json``.
+
+    ``settings.local.json`` is deliberately chosen over the MAP-managed
+    ``settings.json``: it is user-owned and never re-rendered by the managed
+    copier, so the injection introduces no template drift and creates no ``.bak``
+    churn on upgrade. The merge preserves any pre-existing keys in that file, and
+    the operation is idempotent — a second ``mapify init`` detects MAP's own
+    entry and skips.
+
+    Args:
+        project_path: Root of the target project.
+        home: Override for the user home directory (test seam). Defaults to
+            ``Path.home()``.
+
+    Returns:
+        StatuslineResult describing whether a status line was wired or skipped.
+    """
+    home_dir = home if home is not None else Path.home()
+    claude_dir = project_path / ".claude"
+    scope_paths = {
+        "local": claude_dir / "settings.local.json",
+        "project": claude_dir / "settings.json",
+        "user": home_dir / ".claude" / "settings.json",
+    }
+
+    # Highest-precedence scope first so the reported scope is the one that would
+    # actually win at runtime.
+    for scope in ("local", "project", "user"):
+        if _has_status_line(scope_paths[scope]):
+            return StatuslineResult(wired=False, reason=f"existing:{scope}")
+
+    local_settings = scope_paths["local"]
+    hook_path = claude_dir / "hooks" / "map-statusline.py"
+    # Absolute, quoted path: settings.local.json is machine-local, and quoting
+    # keeps the shell-invoked command correct when the project path has spaces.
+    command = f'"{hook_path}"'
+
+    settings = _read_json_object(local_settings) or {}
+    settings["statusLine"] = {"type": "command", "command": command}
+
+    claude_dir.mkdir(parents=True, exist_ok=True)
+    local_settings.write_text(
+        json.dumps(settings, indent=2) + "\n", encoding="utf-8"
+    )
+    return StatuslineResult(
+        wired=True, reason="wired", settings_path=local_settings
+    )
+
+
 def create_rules_dir(
     project_path: Path,
     drift_report: DriftReport | None = None,

{mapify_cli-3.20.0 → mapify_cli-3.21.0}/src/mapify_cli/delivery/providers.py

@@ -14,6 +14,7 @@ from mapify_cli.delivery.file_copier import (
     create_config_files,
     create_map_tools,
     create_rules_dir,
+    ensure_map_statusline,
 )
 
 
@@ -53,6 +54,10 @@ class ClaudeProvider(BaseProvider):
     ) -> dict[str, int]:
         """Install Claude Code MAP files into target project."""
         servers = mcp_servers or []
+        # Statusline wiring is a Claude-only resource decision and stays inside
+        # this provider so it never leaks into the Codex install path. It is
+        # non-destructive: skips when the user already configured a statusLine.
+        statusline = ensure_map_statusline(project_path)
         return {
             "agents": create_agent_files(project_path, servers),
             "commands": create_command_files(project_path),
@@ -62,6 +67,7 @@ class ClaudeProvider(BaseProvider):
             "hooks": create_hook_files(project_path),
             "configs": create_config_files(project_path),
             "rules": create_rules_dir(project_path),
+            "statusline": 1 if statusline.wired else 0,
         }
 
 
@@ -83,6 +89,10 @@ class CodexProvider(BaseProvider):
         Returns:
             Mapping of category name to number of files created.
         """
+        # Codex configures agents via TOML, not MCP JSON: the interface
+        # parameter is accepted for BaseProvider conformance but intentionally
+        # unused. `del` documents that and satisfies reportUnusedParameter.
+        del mcp_servers
         # Deferred to avoid circular import (codex_copier imports from file_copier)
         from mapify_cli.delivery.codex_copier import create_codex_files