mapify-cli 3.18.0__tar.gz → 3.19.0__tar.gz

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapify-cli
-Version: 3.18.0
+Version: 3.19.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
@@ -274,6 +274,15 @@ mapify init . --sofa            # opt-in: enable the map-so-search skill
 
 This writes `sofa.enabled: true` to `.map/config.yaml` and adds `.sofa/` to your `.gitignore`. Without the flag, no SOFA code path runs. See the [SOFA usage guide](docs/USAGE.md#stack-overflow-for-agents-sofa).
 
+**Autonomy posture** (`--autonomy`, claude provider) — **off by default**, opt-in "YOLO-minus-git":
+
+```bash
+mapify init . --autonomy        # auto-approve most tools; keep git commit/push for the human
+mapify init . --no-autonomy     # remove the autonomy posture
+```
+
+`--autonomy` writes a broad auto-approve allowlist plus a `git commit`/`push` deny into the **per-user, gitignored** `.claude/settings.local.json` (the committed team `.claude/settings.json` stays the secure baseline) and gitignores that file. The git block is enforced by the `safety-guardrails.py` PreToolUse hook (the permission deny alone is bypassable under a broad `Bash(*)` allow). Omit the flag to leave existing local settings untouched on re-init. See the [autonomy usage guide](docs/USAGE.md#autonomy-posture-yolo-minus-git).
+
 </details>
 
 ## Documentation

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/README.md

@@ -229,6 +229,15 @@ mapify init . --sofa            # opt-in: enable the map-so-search skill
 
 This writes `sofa.enabled: true` to `.map/config.yaml` and adds `.sofa/` to your `.gitignore`. Without the flag, no SOFA code path runs. See the [SOFA usage guide](docs/USAGE.md#stack-overflow-for-agents-sofa).
 
+**Autonomy posture** (`--autonomy`, claude provider) — **off by default**, opt-in "YOLO-minus-git":
+
+```bash
+mapify init . --autonomy        # auto-approve most tools; keep git commit/push for the human
+mapify init . --no-autonomy     # remove the autonomy posture
+```
+
+`--autonomy` writes a broad auto-approve allowlist plus a `git commit`/`push` deny into the **per-user, gitignored** `.claude/settings.local.json` (the committed team `.claude/settings.json` stays the secure baseline) and gitignores that file. The git block is enforced by the `safety-guardrails.py` PreToolUse hook (the permission deny alone is bypassable under a broad `Bash(*)` allow). Omit the flag to leave existing local settings untouched on re-init. See the [autonomy usage guide](docs/USAGE.md#autonomy-posture-yolo-minus-git).
+
 </details>
 
 ## Documentation

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/pyproject.toml

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

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.18.0"
+__version__ = "3.19.0"
 
 import os
 import subprocess
@@ -38,7 +38,7 @@ import typer
 import httpx
 
 try:
-    import truststore
+    import truststore  # pyright: ignore[reportMissingImports]
 
     HAS_TRUSTSTORE = True
 except ImportError:
@@ -691,6 +691,18 @@ def init(
             "See docs/USAGE.md."
         ),
     ),
+    autonomy: Optional[bool] = typer.Option(
+        None,
+        "--autonomy/--no-autonomy",
+        help=(
+            "Opt-in 'YOLO-minus-git' posture (claude provider only): auto-approve "
+            "most tools in the per-user, gitignored .claude/settings.local.json "
+            "while a PreToolUse hook keeps git commit/push blocked (you run them). "
+            "--no-autonomy removes it. Omit to leave existing local settings "
+            "untouched. The committed team settings.json stays the secure baseline. "
+            "See docs/USAGE.md."
+        ),
+    ),
 ):
     """
     Initialize a new MAP Framework project.
@@ -739,6 +751,14 @@ def init(
         )
         raise typer.Exit(1)
 
+    # Autonomy posture is delivered via .claude/settings.local.json + the Claude
+    # safety-guardrails hook, neither of which the codex provider installs.
+    if provider == "codex" and autonomy is not None:
+        console.print(
+            "[yellow]Note:[/yellow] --autonomy/--no-autonomy applies to the claude "
+            "provider only; ignored for --provider codex."
+        )
+
     # Validate compression policy & threshold only when the user actually
     # passed the flag — None means "leave existing config alone", which is
     # the correct behaviour on re-run in an existing project. The canonical
@@ -956,7 +976,7 @@ def init(
 
         tracker.add("project-permissions", "Configure project approvals")
         tracker.start("project-permissions")
-        create_or_merge_project_settings_local(project_path)
+        create_or_merge_project_settings_local(project_path, autonomy=autonomy)
         tracker.complete("project-permissions", ".claude/settings.local.json")
 
     # Initialize git (shared, provider-agnostic)

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/src/mapify_cli/config/settings.py

@@ -2,11 +2,76 @@
 
 import json
 from pathlib import Path
-from typing import Dict, Any
+from typing import Dict, Any, Optional
 
 from mapify_cli.cli_ui import console
 
 
+# ---------------------------------------------------------------------------
+# Autonomy posture (opt-in via `mapify init --autonomy`)
+# ---------------------------------------------------------------------------
+#
+# "YOLO-minus-git": auto-approve most tools locally while keeping the human in
+# control of commit/push. This is a *personal* risk preference, so it is written
+# ONLY to the per-user, gitignored .claude/settings.local.json — never to the
+# committed, team-shared .claude/settings.json baseline.
+#
+# The permission-level git deny below is documentation / defense-in-depth: under
+# a broad ``Bash(*)`` allow it is bypassable (``bash -c 'git commit'`` matches as
+# ``bash``). The actual hard block is the ``safety-guardrails.py`` PreToolUse
+# hook, which is gated on the ``mapify.autonomy`` sentinel this module writes.
+_AUTONOMY_ALLOW = [
+    "Bash(*)",
+    "Read(*)",
+    "Edit(*)",
+    "Write(*)",
+    "MultiEdit(*)",
+    "Glob(*)",
+    "Grep(*)",
+    "LS(*)",
+]
+_AUTONOMY_DENY = [
+    "Bash(git commit:*)",
+    "Bash(git push:*)",
+]
+
+_SETTINGS_LOCAL_GITIGNORE_MARKER = "# map:settings-local"
+_SETTINGS_LOCAL_GITIGNORE_BLOCK = (
+    "# map:settings-local — per-user Claude Code approvals / autonomy posture; "
+    "never commit\n"
+    ".claude/settings.local.json\n"
+)
+
+
+def ensure_settings_local_gitignored(project_path: Path) -> int:
+    """Idempotently add ``.claude/settings.local.json`` to the repo-root .gitignore.
+
+    A personal autonomy posture must not leak into the team via a committed
+    settings.local.json. Mirrors ``merge_sofa_gitignore``: the OR-guard skips the
+    append whenever our marker OR an active ignore line is already present, so the
+    entry is never duplicated regardless of how the user got it there.
+
+    Returns 1 when the file was created or modified, 0 when already up-to-date.
+    """
+    gitignore = project_path / ".gitignore"
+
+    if not gitignore.exists():
+        gitignore.write_text(_SETTINGS_LOCAL_GITIGNORE_BLOCK)
+        return 1
+
+    existing = gitignore.read_text()
+    ignored_lines = {line.strip() for line in existing.splitlines()}
+    if (
+        _SETTINGS_LOCAL_GITIGNORE_MARKER in existing
+        or ".claude/settings.local.json" in ignored_lines
+    ):
+        return 0
+
+    separator = "" if existing.endswith("\n") else "\n"
+    gitignore.write_text(existing + separator + _SETTINGS_LOCAL_GITIGNORE_BLOCK)
+    return 1
+
+
 def configure_global_permissions() -> None:
     """Configure global Claude Code permissions for read-only commands"""
     claude_dir = Path.home() / ".claude"
@@ -91,7 +156,9 @@ def configure_global_permissions() -> None:
     )
 
 
-def create_or_merge_project_settings_local(project_path: Path) -> None:
+def create_or_merge_project_settings_local(
+    project_path: Path, *, autonomy: Optional[bool] = None
+) -> None:
     """Create/merge .claude/settings.local.json with safe project allowlist.
 
     Claude Code supports per-project approvals via `.claude/settings.local.json`.
@@ -105,6 +172,16 @@ def create_or_merge_project_settings_local(project_path: Path) -> None:
 
     We keep this allowlist intentionally narrow and focused on common safe actions
     for local development workflows.
+
+    Args:
+        project_path: Target project root.
+        autonomy: Opt-in "YOLO-minus-git" posture.
+            - ``True``  → merge a broad tool allowlist + git commit/push deny and
+              write the ``mapify.autonomy`` sentinel (also gitignores the file).
+            - ``False`` → remove the autonomy allow/deny entries and the sentinel
+              (teardown for ``--no-autonomy``).
+            - ``None``  → leave any existing autonomy posture untouched (default on
+              re-run, so re-init never silently flips a user's choice).
     """
 
     settings_file = project_path / ".claude" / "settings.local.json"
@@ -167,4 +244,60 @@ def create_or_merge_project_settings_local(project_path: Path) -> None:
     permissions.setdefault("deny", [])
     permissions.setdefault("ask", [])
 
+    # Autonomy posture (opt-in). None = leave as-is.
+    if autonomy is True:
+        _apply_autonomy(existing_settings, permissions)
+    elif autonomy is False:
+        _remove_autonomy(existing_settings, permissions)
+
     settings_file.write_text(json.dumps(existing_settings, indent=2) + "\n")
+
+    if autonomy is True:
+        ensure_settings_local_gitignored(project_path)
+        console.print(
+            "[yellow]Autonomy mode:[/yellow] auto-allowing most tools in "
+            ".claude/settings.local.json (per-user, gitignored). git commit/push "
+            "stay blocked — you run them. The local deny overrides the team baseline."
+        )
+    elif autonomy is False:
+        console.print(
+            "[dim]Autonomy mode disabled: removed local broad-allow + git block "
+            "from .claude/settings.local.json.[/dim]"
+        )
+
+
+def _apply_autonomy(settings: Dict[str, Any], permissions: Dict[str, Any]) -> None:
+    """Add the broad allow + git deny entries and the autonomy sentinel."""
+    allow = permissions.setdefault("allow", [])
+    for entry in _AUTONOMY_ALLOW:
+        if entry not in allow:
+            allow.append(entry)
+
+    deny = permissions.setdefault("deny", [])
+    for entry in _AUTONOMY_DENY:
+        if entry not in deny:
+            deny.append(entry)
+
+    # Sentinel beside the permissions it governs so posture and permissions
+    # cannot drift apart; read by the safety-guardrails.py PreToolUse hook.
+    mapify_meta = settings.setdefault("mapify", {})
+    if isinstance(mapify_meta, dict):
+        mapify_meta["autonomy"] = True
+
+
+def _remove_autonomy(settings: Dict[str, Any], permissions: Dict[str, Any]) -> None:
+    """Remove the autonomy allow/deny entries and the sentinel (teardown)."""
+    if isinstance(permissions.get("allow"), list):
+        permissions["allow"] = [
+            e for e in permissions["allow"] if e not in _AUTONOMY_ALLOW
+        ]
+    if isinstance(permissions.get("deny"), list):
+        permissions["deny"] = [
+            e for e in permissions["deny"] if e not in _AUTONOMY_DENY
+        ]
+
+    mapify_meta = settings.get("mapify")
+    if isinstance(mapify_meta, dict):
+        mapify_meta.pop("autonomy", None)
+        if not mapify_meta:
+            settings.pop("mapify", None)

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/src/mapify_cli/delivery/codex_copier.py

@@ -8,8 +8,11 @@ Never touches .claude/.
 
 from __future__ import annotations
 
+import json
 import shutil
+from copy import deepcopy
 from pathlib import Path
+from typing import Any
 
 from mapify_cli.delivery.file_copier import (
     _extract_requires_block,
@@ -20,7 +23,11 @@ from mapify_cli.delivery.file_copier import (
     _warn_requires_skills,
     get_templates_dir,
 )
-from mapify_cli.delivery.managed_file_copier import copy_managed_file
+from mapify_cli.delivery.managed_file_copier import (
+    _assert_safe_dest,
+    _atomic_write,
+    copy_managed_file,
+)
 
 
 def _install_managed_file(
@@ -81,6 +88,129 @@ def _copy_tree(
 
 
 _EXEC_SUFFIXES = frozenset((".py", ".sh"))
+_CODEX_WORKFLOW_GATE_PATH = ".codex/hooks/workflow-gate.py"
+
+
+def _is_codex_workflow_gate_hook(hook: Any) -> bool:
+    """Return True for MAP's managed Codex workflow-gate command hook."""
+    if not isinstance(hook, dict):
+        return False
+    command = hook.get("command")
+    return isinstance(command, str) and _CODEX_WORKFLOW_GATE_PATH in command
+
+
+def _merge_codex_hook_entries(
+    existing_entries: Any,
+    template_entries: Any,
+) -> list[Any]:
+    """Merge MAP hook entries into existing Codex hook entries.
+
+    Existing project hooks are preserved. MAP-owned workflow-gate command hooks
+    are refreshed from the template and de-duplicated.
+    """
+    merged_entries: list[Any] = []
+    if isinstance(existing_entries, list):
+        for raw_entry in deepcopy(existing_entries):
+            if not isinstance(raw_entry, dict):
+                merged_entries.append(raw_entry)
+                continue
+
+            raw_hooks = raw_entry.get("hooks")
+            if not isinstance(raw_hooks, list):
+                merged_entries.append(raw_entry)
+                continue
+
+            cleaned_hooks = [
+                hook for hook in raw_hooks if not _is_codex_workflow_gate_hook(hook)
+            ]
+            if not cleaned_hooks and len(cleaned_hooks) != len(raw_hooks):
+                continue
+
+            raw_entry["hooks"] = cleaned_hooks
+            merged_entries.append(raw_entry)
+
+    if not isinstance(template_entries, list):
+        return merged_entries
+
+    for template_entry in template_entries:
+        if not isinstance(template_entry, dict):
+            if template_entry not in merged_entries:
+                merged_entries.append(deepcopy(template_entry))
+            continue
+
+        matcher = template_entry.get("matcher")
+        template_hooks = template_entry.get("hooks")
+        target = None
+        if isinstance(matcher, str) and isinstance(template_hooks, list):
+            for entry in merged_entries:
+                if (
+                    isinstance(entry, dict)
+                    and entry.get("matcher") == matcher
+                    and isinstance(entry.get("hooks"), list)
+                ):
+                    target = entry
+                    break
+
+        if target is None:
+            if template_entry not in merged_entries:
+                merged_entries.append(deepcopy(template_entry))
+            continue
+
+        assert isinstance(template_hooks, list)
+        target_hooks = target["hooks"]
+        assert isinstance(target_hooks, list)
+        for hook in template_hooks:
+            if hook not in target_hooks:
+                target_hooks.append(deepcopy(hook))
+
+    return merged_entries
+
+
+def _merge_codex_hooks_json(
+    existing_data: dict[str, Any] | None,
+    template_data: dict[str, Any],
+) -> dict[str, Any]:
+    """Return Codex-valid hooks.json containing only the top-level hooks key."""
+    existing_hooks = existing_data.get("hooks") if existing_data else None
+    template_hooks = template_data.get("hooks")
+
+    merged_hooks: dict[str, Any] = (
+        deepcopy(existing_hooks) if isinstance(existing_hooks, dict) else {}
+    )
+
+    if isinstance(template_hooks, dict):
+        for event_name, template_entries in template_hooks.items():
+            merged_hooks[event_name] = _merge_codex_hook_entries(
+                merged_hooks.get(event_name),
+                template_entries,
+            )
+
+    return {"hooks": merged_hooks}
+
+
+def _load_json_object(path: Path) -> dict[str, Any] | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _install_codex_hooks_json(src: Path, dst: Path) -> None:
+    """Install .codex/hooks.json without MAP metadata and merge project hooks."""
+    template_data = _load_json_object(src)
+    if template_data is None:
+        raise ValueError(f"Invalid Codex hooks template JSON: {src}")
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+
+    existing_data: dict[str, Any] | None = None
+    if dst.exists():
+        _assert_safe_dest(dst)
+        existing_data = _load_json_object(dst)
+
+    merged = _merge_codex_hooks_json(existing_data, template_data)
+    _atomic_write(dst, json.dumps(merged, indent=2, ensure_ascii=False) + "\n")
 
 
 def create_codex_files(project_path: Path) -> dict[str, int]:
@@ -96,8 +226,8 @@ def create_codex_files(project_path: Path) -> dict[str, int]:
 
     Watched files (skills, agents, config, AGENTS.md, hooks) are installed
     fence-aware so a re-install preserves any user content below the fence;
-    hooks.json is JSON (fully-managed via _map_managed); .map/scripts is
-    MAP-owned (fenced=False, skip-if-exists).
+    hooks.json is merged without MAP metadata because Codex validates top-level
+    keys strictly; .map/scripts is MAP-owned (fenced=False, skip-if-exists).
 
     Skips .map/scripts/ if the directory already exists.
     Never creates or modifies any .claude/ path.
@@ -186,12 +316,13 @@ def create_codex_files(project_path: Path) -> dict[str, int]:
 
     # ------------------------------------------------------------------
     # 4. Hooks (hooks.json + hooks/*.py)
-    #    hooks.json is JSON (fully-managed via _map_managed, no fence);
+    #    hooks.json must remain Codex-schema-valid, so install it with a
+    #    Codex-specific merge instead of the generic _map_managed JSON copier.
     #    hooks/*.py are watched (fence-aware) with exec bits preserved.
     # ------------------------------------------------------------------
     hooks_json_src = codex_templates / "hooks.json"
     if hooks_json_src.exists():
-        _install_managed_file(hooks_json_src, codex_dir / "hooks.json", version)
+        _install_codex_hooks_json(hooks_json_src, codex_dir / "hooks.json")
         counts["hooks"] += 1
 
     hooks_dir_src = codex_templates / "hooks"

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/src/mapify_cli/schemas.py

@@ -501,6 +501,13 @@ BLUEPRINT_SCHEMA = {
                 "additionalProperties": True,
             },
         },
+        # Forward-coverage source-of-truth: the authoritative list of requirement
+        # IDs lives in the spec's Requirements Index (the mapify:requirements-index:v1
+        # block, parsed by parse_requirements_index in map_step_runner). The
+        # decomposition-completeness gate diffs that index against these coverage_map
+        # keys. Acceptance criteria are deliberately NOT stored as a blueprint field
+        # (the decomposer cannot be trusted to declare the set it is checked against);
+        # coverage_map remains a mapping of those spec IDs to owning subtasks only.
         "coverage_map": {
             "type": "object",
             "description": (
@@ -802,10 +809,15 @@ ARTIFACT_MANIFEST_SCHEMA = {
                 "spec": ARTIFACT_STAGE_SCHEMA,
                 "plan": ARTIFACT_STAGE_SCHEMA,
                 "test_contract": ARTIFACT_STAGE_SCHEMA,
+                "repro_probe": ARTIFACT_STAGE_SCHEMA,
                 "implementation": ARTIFACT_STAGE_SCHEMA,
                 "review": ARTIFACT_STAGE_SCHEMA,
                 "verification": ARTIFACT_STAGE_SCHEMA,
                 "retry_quarantine": ARTIFACT_STAGE_SCHEMA,
+                "flaky_test_triage": ARTIFACT_STAGE_SCHEMA,
+                "qualitative_convergence": ARTIFACT_STAGE_SCHEMA,
+                "anti_repeat": ARTIFACT_STAGE_SCHEMA,
+                "escalation": ARTIFACT_STAGE_SCHEMA,
                 "token_budget": ARTIFACT_STAGE_SCHEMA,
                 "run_health": ARTIFACT_STAGE_SCHEMA,
                 "learn_handoff": ARTIFACT_STAGE_SCHEMA,
@@ -957,6 +969,101 @@ RETRY_QUARANTINE_SCHEMA = {
 }
 
 
+FLAKY_TEST_TRIAGE_EVIDENCE_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "run": {"type": "integer", "minimum": 1},
+        "status": {"type": "string", "enum": ["passed", "failed"]},
+        "exit_code": {"type": "integer"},
+        "summary": {"type": "string"},
+        "timed_out": {"type": "boolean"},
+        "duration_seconds": {"type": "number", "minimum": 0},
+        "stdout_tail": {"type": "string"},
+        "stderr_tail": {"type": "string"},
+    },
+    "required": ["run", "status", "exit_code", "summary"],
+    "additionalProperties": False,
+}
+
+
+FLAKY_TEST_TRIAGE_ENTRY_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "check_id": {"type": "string"},
+        "command": {"type": "string"},
+        "reason": {"type": "string"},
+        "run_count": {"type": "integer", "minimum": 1},
+        "pass_count": {"type": "integer", "minimum": 0},
+        "fail_count": {"type": "integer", "minimum": 0},
+        "outcome_sequence": {
+            "type": "array",
+            "items": {"type": "string", "enum": ["passed", "failed"]},
+            "minItems": 1,
+        },
+        "disposition": {
+            "type": "string",
+            "enum": [
+                "deferred_nondeterministic",
+                "deterministic_failure",
+                "not_reproduced",
+                "insufficient_evidence",
+            ],
+        },
+        "recommended_next_action": {"type": "string"},
+        "monitor_verdict_policy": {
+            "type": "string",
+            "enum": ["not_valid_without_explicit_triage"],
+        },
+        "operator_requirements": {
+            "type": "array",
+            "items": {"type": "string"},
+            "minItems": 1,
+        },
+        "evidence": {
+            "type": "array",
+            "items": FLAKY_TEST_TRIAGE_EVIDENCE_SCHEMA,
+            "minItems": 1,
+        },
+    },
+    "required": [
+        "check_id",
+        "command",
+        "reason",
+        "run_count",
+        "pass_count",
+        "fail_count",
+        "outcome_sequence",
+        "disposition",
+        "recommended_next_action",
+        "monitor_verdict_policy",
+        "operator_requirements",
+        "evidence",
+    ],
+    "additionalProperties": False,
+}
+
+
+FLAKY_TEST_TRIAGE_SCHEMA = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/flaky-test-triage.json",
+    "title": "MAP Flaky Test Triage",
+    "description": "Repeated check evidence stored in .map/<branch>/flaky_test_triage.json",
+    "type": "object",
+    "properties": {
+        "schema_version": {"type": "string"},
+        "branch": {"type": "string"},
+        "updated_at": {"type": "string", "format": "date-time"},
+        "triages": {
+            "type": "array",
+            "items": FLAKY_TEST_TRIAGE_ENTRY_SCHEMA,
+            "minItems": 1,
+        },
+    },
+    "required": ["schema_version", "branch", "updated_at", "triages"],
+    "additionalProperties": False,
+}
+
+
 TEST_HANDOFF_SCHEMA = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://mapframework.dev/schemas/test-handoff.json",

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/src/mapify_cli/templates/agents/actor.md

@@ -489,6 +489,16 @@ exhaustive test matrices by default.
 - [ ] When using training data for unfamiliar patterns, tag with `[training-data]` in Approach section
 - [ ] Tag verified sources: `[code: path/to/file.py:line]`, `[training-data]`
 
+### Qualitative Self-Review Convergence (Opt-In Only)
+- [ ] If the caller explicitly requests self-review convergence, treat this
+  checklist run as one bounded pass and return concrete evidence for every
+  `clean=true` claim.
+- [ ] `clean` means no critical findings in this pass, not proof of correctness.
+  If you find a blocker, report it as a critical finding; do not soften it to
+  help the convergence loop finish.
+- [ ] On pass N>1, verify prior critical findings are resolved before looking
+  for new regressions.
+
 ### SFT Comfort Zone (Token Discipline)
 - [ ] Each function/method body stays within ~100 lines (~4000 tokens)
 - [ ] If a function exceeds this: split into sub-functions with their own inline contracts

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/src/mapify_cli/templates/agents/monitor.md

@@ -467,6 +467,22 @@ IF {{feedback}} contains previous review findings:
 }
 ```
 
+### Qualitative Convergence Passes (Opt-In Only)
+
+When the caller explicitly marks this subtask/gate for qualitative convergence,
+your current review is one pass in a bounded sequence. The caller records each
+pass with `record_qualitative_convergence`; you must make the pass auditable:
+
+- `clean` means **no critical findings for this gate**, not globally defect-free.
+- A clean pass must still cite evidence (`path:line`, test command, or artifact)
+  for the contract slices you checked.
+- A non-clean pass must list concrete critical findings; do not emit
+  `clean=true` with findings or `clean=false` with no blocker.
+- On pass N>1, first verify the prior pass's critical findings are resolved and
+  that the fix did not introduce regressions; then perform the normal review.
+- Do not soften critical findings to help the run converge. If the max-pass cap
+  is reached, the caller escalates instead of treating the gate as passed.
+
 ### Disputed Findings Protocol
 
 ```

{mapify_cli-3.18.0 → mapify_cli-3.19.0}/src/mapify_cli/templates/codex/skills/map-efficient/SKILL.md

@@ -44,7 +44,9 @@ These constraints apply before any write-capable step:
   sidecar artifacts: `record_test_baseline`, `save_research`, `load_research`,
   `build_context_block`, `detect_truncated_agent_output`,
   `detect_actor_files_changed_mismatch`, `detect_symbol_blast_radius`,
-  `detect_cross_subtask_regression_risk`, `write_run_health_report`.
+  `detect_cross_subtask_regression_risk`, `run_flaky_test_triage`,
+  `record_flaky_test_triage`,
+  `validate_flaky_test_triage`, `write_run_health_report`.
 
 ## Argument Handling
 
@@ -239,6 +241,15 @@ python3 .map/scripts/map_orchestrator.py monitor_failed --feedback "$MONITOR_FEE
 Write a durable `.map/<branch>/code-review-N.md` with exact issues and then fix
 the current subtask. Do not advance until Monitor passes.
 
+If the failure is inconsistent across repeated identical check runs, record the
+run evidence with `run_flaky_test_triage` (or `record_flaky_test_triage` if the
+repeated runs were already collected) and validate
+`flaky_test_triage.json` before reporting `deferred_nondeterministic`. This is
+not a passing gate: do not weaken, skip, or delete the check, and do not return
+a silent green. After validation, close with
+`python3 .map/scripts/map_orchestrator.py defer_flaky_subtask "$SUBTASK_ID" --check-id "<check-id>"`,
+not `validate_step 2.4 --recommendation proceed`.
+
 On a clean pass, run the regression gate and record the subtask:
 
 ```bash