mapify-cli 3.24.0__tar.gz → 3.25.0__tar.gz

{mapify_cli-3.24.0 → mapify_cli-3.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mapify-cli
-Version: 3.24.0
+Version: 3.25.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.24.0 → mapify_cli-3.25.0}/pyproject.toml

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

{mapify_cli-3.24.0 → mapify_cli-3.25.0}/src/mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.24.0"
+__version__ = "3.25.0"
 
 import json
 import os
@@ -770,6 +770,18 @@ def init(
             "See docs/USAGE.md."
         ),
     ),
+    agent_memory: str = typer.Option(
+        "off",
+        "--agent-memory",
+        help=(
+            "Role-local persistent memory for the reflector learning agent "
+            "(opt-in, off by default). Adds a `memory:` frontmatter field to "
+            ".claude/agents/reflector.md and writes "
+            "claude_agents.persistent_memory=<level> to .map/config.yaml. "
+            "Allowed: off, local (user-local, NOT committed), "
+            "project (project-scoped, committed). See docs/USAGE.md."
+        ),
+    ),
     autonomy: bool | None = typer.Option(
         None,
         "--autonomy/--no-autonomy",
@@ -856,6 +868,14 @@ def init(
         )
         raise typer.Exit(1)
 
+    from mapify_cli.config.project_config import VALID_AGENT_MEMORY_LEVELS
+    if agent_memory not in VALID_AGENT_MEMORY_LEVELS:
+        console.print(
+            f"[red]Error:[/red] Invalid --agent-memory '{agent_memory}'. "
+            f"Valid: {', '.join(sorted(VALID_AGENT_MEMORY_LEVELS))}"
+        )
+        raise typer.Exit(1)
+
     # Handle '.' as shorthand for current directory
     use_current_dir = project_name == "."
 
@@ -975,6 +995,7 @@ def init(
         tracker.start("map-config")
         try:
             from mapify_cli.config.project_config import (
+                apply_agent_memory_overrides,
                 apply_compression_overrides,
                 apply_sofa_overrides,
                 write_default_config,
@@ -994,6 +1015,8 @@ def init(
                 from mapify_cli.delivery.file_copier import merge_sofa_gitignore
 
                 merge_sofa_gitignore(project_path)
+            if agent_memory != "off":
+                apply_agent_memory_overrides(config_path, agent_memory)
             tracker.complete(
                 "map-config", str(config_path.relative_to(project_path))
             )
@@ -1029,6 +1052,7 @@ def init(
         tracker.start("map-config")
         try:
             from mapify_cli.config.project_config import (
+                apply_agent_memory_overrides,
                 apply_compression_overrides,
                 apply_sofa_overrides,
                 write_default_config,
@@ -1048,6 +1072,16 @@ def init(
                 from mapify_cli.delivery.file_copier import merge_sofa_gitignore
 
                 merge_sofa_gitignore(project_path)
+            if agent_memory != "off":
+                apply_agent_memory_overrides(config_path, agent_memory)
+                from mapify_cli.delivery.file_copier import (
+                    apply_reflector_memory_field,
+                    merge_agent_memory_gitignore,
+                )
+
+                apply_reflector_memory_field(project_path, agent_memory)
+                if agent_memory == "local":
+                    merge_agent_memory_gitignore(project_path)
             tracker.complete("map-config", str(config_path.relative_to(project_path)))
         except Exception as e:  # noqa: BLE001 -- deliberate fallback/resilience boundary, must not propagate
             tracker.error("map-config", f"skipped: {e}")

{mapify_cli-3.24.0 → mapify_cli-3.25.0}/src/mapify_cli/config/project_config.py

@@ -19,6 +19,7 @@ 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"})
+VALID_AGENT_MEMORY_LEVELS = frozenset({"off", "local", "project"})
 
 # 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
@@ -130,6 +131,17 @@ class MapConfig:
     # .map/config.yaml. When enabled, the map-so-search skill is available.
     sofa_enabled: bool = False
 
+    # Role-local persistent memory for learning agents (#379). Enables the
+    # Claude Code `memory:` frontmatter on the reflector agent so it can retain
+    # lessons across sessions. Enum values:
+    #   "off"     — no memory field added (default; behaviour unchanged)
+    #   "local"   — user-local memory: .claude/agent-memory-local/ (not committed)
+    #   "project" — project-scoped memory: .claude/agent-memory/ (committed)
+    # Enable via `mapify init --agent-memory local|project` or set
+    # `claude_agents.persistent_memory: local|project` in .map/config.yaml.
+    # Dotted YAML key: `claude_agents.persistent_memory` (aliased in load_map_config).
+    claude_agents_persistent_memory: str = "off"
+
     # Strip MAP-internal workflow IDs (ST-/AC-/VC-/INV-/HC-) from run-changed
     # code at workflow completion (Stop hook `scrub-internal-ids.py`). On by
     # default; set `scrub_internal_ids: false` in .map/config.yaml to opt out
@@ -373,6 +385,7 @@ def load_map_config(project_path: Path) -> MapConfig:
             ("scale.thresholds.small.max_lines", "scale_small_max_lines"),
             ("scale.thresholds.medium.max_files", "scale_medium_max_files"),
             ("scale.thresholds.medium.max_lines", "scale_medium_max_lines"),
+            ("claude_agents.persistent_memory", "claude_agents_persistent_memory"),
         ):
             if dotted in data and field_name not in data:
                 data[field_name] = data.pop(dotted)
@@ -513,6 +526,16 @@ def load_map_config(project_path: Path) -> MapConfig:
             )
             cfg.execution_wave_mode = "auto"
 
+        if cfg.claude_agents_persistent_memory not in VALID_AGENT_MEMORY_LEVELS:
+            logger.warning(
+                "Invalid claude_agents_persistent_memory %r in %s (expected one of %s). "
+                "Using default 'off'.",
+                cfg.claude_agents_persistent_memory,
+                config_file,
+                ", ".join(sorted(VALID_AGENT_MEMORY_LEVELS)),
+            )
+            cfg.claude_agents_persistent_memory = "off"
+
         # 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.
@@ -520,6 +543,28 @@ def load_map_config(project_path: Path) -> MapConfig:
         # Clamp max_wave_retries to [1, 10]; non-int/bool → default 3.
         cfg.max_wave_retries = clamp_max_wave_retries(cfg.max_wave_retries)
 
+        # Scale threshold fields must be >= 1; a value <= 0 makes one or more
+        # scope brackets unreachable (e.g. estimated_files <= -1 is always False).
+        _scale_defaults: dict[str, int] = {
+            "scale_trivial_max_files": 3,
+            "scale_trivial_max_lines": 50,
+            "scale_small_max_files": 10,
+            "scale_small_max_lines": 200,
+            "scale_medium_max_files": 30,
+            "scale_medium_max_lines": 1000,
+        }
+        for _sf, _default in _scale_defaults.items():
+            _val = getattr(cfg, _sf)
+            if _val < 1:
+                logger.warning(
+                    "%s must be >= 1 in %s (got %d). Using default %d.",
+                    _sf,
+                    config_file,
+                    _val,
+                    _default,
+                )
+                setattr(cfg, _sf, _default)
+
         return cfg
 
     except yaml.YAMLError as e:
@@ -649,6 +694,15 @@ minimality: lite
 # Enable via `mapify init --sofa` or uncomment the line below.
 # sofa.enabled: false
 
+# Role-local persistent memory for learning agents (#379) — opt-in, off by default.
+# Adds the Claude Code `memory:` frontmatter to the reflector agent so it retains
+# lessons across sessions. Enable via `mapify init --agent-memory local|project`
+# or uncomment and set one of the values below.
+#   off     — no memory (default; behaviour unchanged)
+#   local   — user-local memory: .claude/agent-memory-local/ (NOT committed)
+#   project — project-scoped memory: .claude/agent-memory/ (committed, shared)
+# claude_agents.persistent_memory: off
+
 # 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
@@ -834,6 +888,39 @@ def apply_sofa_overrides(config_path: Path) -> None:
     config_path.write_text(text, encoding="utf-8")
 
 
+def apply_agent_memory_overrides(config_path: Path, level: str) -> None:
+    """Write claude_agents.persistent_memory=<level> into an existing .map/config.yaml.
+
+    Called by ``mapify init`` when the user passes ``--agent-memory``. Replaces
+    the commented placeholder line so the value becomes active without duplicating
+    keys. Callers should skip this function when ``level`` is ``"off"``.
+
+    Args:
+        config_path: path to the .map/config.yaml produced by ``write_default_config``.
+        level: one of "off", "local", "project" (caller is responsible for validation).
+    """
+    if not config_path.is_file():
+        return
+
+    text = config_path.read_text(encoding="utf-8")
+
+    def _set(key: str, value: str, body: str) -> str:
+        import re
+
+        active_re = re.compile(rf"(?m)^{re.escape(key)}\s*:.*$")
+        commented_re = re.compile(rf"(?m)^#\s*{re.escape(key)}\s*:.*$")
+        new_line = f"{key}: {value}"
+        if active_re.search(body):
+            return active_re.sub(new_line, body, count=1)
+        if commented_re.search(body):
+            return commented_re.sub(new_line, body, count=1)
+        sep = "" if body.endswith("\n") else "\n"
+        return f"{body}{sep}{new_line}\n"
+
+    text = _set("claude_agents.persistent_memory", level, text)
+    config_path.write_text(text, encoding="utf-8")
+
+
 def write_default_config(project_path: Path) -> Path:
     """Write default config.yaml to .map/config.yaml.
 

{mapify_cli-3.24.0 → mapify_cli-3.25.0}/src/mapify_cli/delivery/file_copier.py

@@ -498,6 +498,98 @@ def merge_sofa_gitignore(project_path: Path) -> int:
     return 1
 
 
+_AGENT_MEMORY_LOCAL_GITIGNORE_MARKER = "# map:agent-memory-local"
+_AGENT_MEMORY_LOCAL_GITIGNORE_BLOCK = (
+    "# map:agent-memory-local — user-local agent memory (opt-in); never commit.\n"
+    ".claude/agent-memory-local/\n"
+)
+
+
+def merge_agent_memory_gitignore(project_path: Path) -> int:
+    """Idempotently add .claude/agent-memory-local/ to the repo-root .gitignore.
+
+    Only called when ``--agent-memory local`` is used. The project-scoped level
+    (``--agent-memory project``) writes to ``.claude/agent-memory/`` which IS
+    intended to be committed, so no gitignore entry is needed for it.
+
+    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(_AGENT_MEMORY_LOCAL_GITIGNORE_BLOCK)
+        return 1
+
+    existing = gitignore.read_text()
+
+    # OR-not-AND idempotency guard: skip if our marker OR the exact path is
+    # already present (prevents duplicates when user already has the line).
+    ignored_lines = {line.strip() for line in existing.splitlines()}
+    if (
+        _AGENT_MEMORY_LOCAL_GITIGNORE_MARKER in existing
+        or ".claude/agent-memory-local/" in ignored_lines
+    ):
+        return 0
+
+    separator = "" if existing.endswith("\n") else "\n"
+    gitignore.write_text(existing + separator + _AGENT_MEMORY_LOCAL_GITIGNORE_BLOCK)
+    return 1
+
+
+def apply_reflector_memory_field(project_path: Path, level: str) -> int:
+    """Add or update the ``memory:`` frontmatter field in the installed reflector.md.
+
+    Called post-install when ``--agent-memory`` is ``"local"`` or ``"project"``.
+    Idempotent: if the field already exists with the correct value it is left
+    unchanged; if it exists with a different value it is replaced.
+
+    Args:
+        project_path: root of the target project (installed ``.claude/`` lives here).
+        level: ``"local"`` or ``"project"`` (caller is responsible for validation;
+               ``"off"`` callers must not invoke this function).
+
+    Returns:
+        1 if the file was modified, 0 if already up-to-date or not found.
+    """
+    import re
+
+    reflector_path = project_path / ".claude" / "agents" / "reflector.md"
+    if not reflector_path.exists():
+        return 0
+
+    text = reflector_path.read_text(encoding="utf-8")
+
+    # Determine the correct memory field value based on level.
+    # "local"   → memory: user_local   (maps to .claude/agent-memory-local/)
+    # "project" → memory: project      (maps to .claude/agent-memory/)
+    memory_value = "user_local" if level == "local" else "project"
+    new_field_line = f"memory: {memory_value}"
+
+    # If a `memory:` line already exists in the frontmatter, replace it.
+    existing_memory_re = re.compile(r"(?m)^memory\s*:.*$")
+    if existing_memory_re.search(text):
+        updated = existing_memory_re.sub(new_field_line, text, count=1)
+        if updated == text:
+            return 0  # already up-to-date
+        reflector_path.write_text(updated, encoding="utf-8")
+        return 1
+
+    # Inject the `memory:` line into the YAML frontmatter, just before the
+    # closing `---` delimiter. This preserves the existing frontmatter structure.
+    # Match the opening `---\n ... \n---` block.
+    frontmatter_re = re.compile(r"^(---\n.*?\n)(---)", re.DOTALL)
+    m = frontmatter_re.match(text)
+    if not m:
+        # No frontmatter — prepend a minimal one.
+        updated = f"---\n{new_field_line}\n---\n{text}"
+    else:
+        # Insert before the closing `---`.
+        updated = text[: m.start(2)] + new_field_line + "\n" + text[m.start(2) :]
+
+    reflector_path.write_text(updated, encoding="utf-8")
+    return 1
+
+
 def create_commands_dir(project_path: Path) -> None:
     """Create commands directory with README pointing at skill-backed surfaces."""
     commands_dir = project_path / ".claude" / "commands"

{mapify_cli-3.24.0 → mapify_cli-3.25.0}/src/mapify_cli/delivery/governance_report.py

@@ -189,6 +189,14 @@ _SKILL_META: dict[str, tuple[str, str]] = {
         "context",
         "Opt-in read-only prior-art search against Stack Overflow for Agents (SOFA)",
     ),
+    "map-wayfind": (
+        "oversight",
+        "Decision-frontier wayfinding: resolve open design decisions on a durable map before /map-plan",
+    ),
+    "map-architecture": (
+        "context",
+        "Opt-in proactive architecture-deepening report: rank codebase hotspots by design friction",
+    ),
 }
 
 #: Default categories for known references (enforcement = "prompt-only")

{mapify_cli-3.24.0 → mapify_cli-3.25.0}/src/mapify_cli/delivery/template_renderer.py

@@ -62,7 +62,6 @@ _STRAY_TOKENS = ("[%", "<%", "[#")
 _CLAUDE_SHIPPED_ONLY: frozenset[str] = frozenset(
     {
         "CLAUDE.md",
-        "settings.json",
         "workflow-rules.json",
         "ralph-loop-config.json",
         "hooks/README.md",
@@ -262,9 +261,13 @@ def _build_claude_resolver(
         (``map/`` prefix remaps to ``.map/`` in the dev tree)
 
     * hooks/README.md, rules/learned/README.md, CLAUDE.md,
-      settings.json, workflow-rules.json, ralph-loop-config.json
+      workflow-rules.json, ralph-loop-config.json
       → ``src/mapify_cli/templates/<rel>`` ONLY (shipped-only — no dev dest)
 
+    * settings.json
+      → BOTH ``src/mapify_cli/templates/settings.json`` AND ``.claude/settings.json``
+        (dual-dest so ``check-render`` gates both and drift is caught; issue #390)
+
     A rendered file mapping to 0 destinations is simply not written live
     (future use; not used for CLAUDE provider currently).
 

{mapify_cli-3.24.0 → mapify_cli-3.25.0}/src/mapify_cli/schemas.py

@@ -1882,3 +1882,176 @@ CONTEXT_USEFULNESS_SCHEMA: dict[str, Any] = {
     "required": ["schema_version", "branch", "workflow", "items", "summary"],
     "additionalProperties": True,
 }
+
+
+REVIEW_VERDICT_LEDGER_SCHEMA: dict[str, Any] = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://mapframework.dev/schemas/review-verdict-ledger.json",
+    "title": "MAP Review Verdict Ledger",
+    "description": (
+        "Durable normalized finding registry and computed verdict for a /map-review run. "
+        "Written before write_stage_gate so the reasoning surface is reproducible from "
+        "a closed decision table, not assigned ad hoc. See issue #406."
+    ),
+    "type": "object",
+    "properties": {
+        "schema_version": {"type": "string"},
+        "generated_at": {"type": "string"},
+        "branch": {"type": "string"},
+        "criteria_version": {"type": "string"},
+        "input_classification": {
+            "type": "object",
+            "properties": {
+                "review_mode": {
+                    "type": "string",
+                    "enum": ["normal", "adversarial", "cross_ai", "compare_orderings", "unknown"],
+                },
+                "destination": {
+                    "type": "string",
+                    "enum": ["pre_commit", "pr_review", "ci", "unknown"],
+                },
+                "evidence_mode": {
+                    "type": "string",
+                    "enum": ["structural", "self_executed", "independent_run", "mixed", "unknown"],
+                },
+                "executor_class": {"type": "string"},
+            },
+            "required": ["review_mode"],
+            "additionalProperties": True,
+        },
+        "findings_registry": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "source_agent": {
+                        "type": "string",
+                        "enum": [
+                            "monitor", "predictor", "evaluator",
+                            "adversarial", "ordering", "operator",
+                        ],
+                    },
+                    "category": {
+                        "type": "string",
+                        "enum": [
+                            "correctness", "security", "tests", "performance",
+                            "maintainability", "workflow", "unknown",
+                        ],
+                    },
+                    "severity": {
+                        "type": "string",
+                        "enum": ["critical", "important", "minor", "needs_investigation"],
+                    },
+                    "claim": {"type": "string"},
+                    "evidence": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "file_path": {"type": "string"},
+                                "line_range": {"type": "string"},
+                                "quote": {"type": "string"},
+                            },
+                            "additionalProperties": True,
+                        },
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": ["active", "tombstoned", "downgraded"],
+                    },
+                    "transition_reason": {
+                        "type": ["string", "null"],
+                        "enum": [
+                            "new_evidence", "quote_absent", "wrong_category",
+                            "different_version", "pre_existing_backlog",
+                            "human_escalation", "pressure_without_new_fact",
+                            "input_integrity", "not_applicable", None,
+                        ],
+                    },
+                    "transition_evidence": {"type": ["string", "null"]},
+                    "was_present_before_pr": {"type": ["boolean", "null"]},
+                    "downgraded_from": {
+                        "type": "string",
+                        "enum": ["critical", "important", "minor", "needs_investigation"],
+                        "description": (
+                            "Severity the finding carried before it was downgraded. "
+                            "Present only on downgraded rows."
+                        ),
+                    },
+                },
+                "required": ["id", "source_agent", "severity", "claim", "status"],
+                "additionalProperties": True,
+            },
+        },
+        "not_verified": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Concerns that could not be verified against source evidence.",
+        },
+        "evaluator_scores": {
+            "type": ["object", "null"],
+            "description": "Raw Evaluator scores — advisory signal, cannot override active findings.",
+            "additionalProperties": True,
+        },
+        "verdict_table": {"type": "string"},
+        "computed_verdict": {
+            "type": "string",
+            "enum": ["PROCEED", "REVISE", "BLOCK"],
+        },
+        "verdict_basis": {
+            "type": "string",
+            "description": "Human-readable explanation of why the decision table chose this verdict.",
+        },
+        "journal": {
+            "type": "object",
+            "properties": {
+                "previous_verdict": {
+                    "type": ["string", "null"],
+                    "enum": ["PROCEED", "REVISE", "BLOCK", None],
+                },
+                "current_verdict": {
+                    "type": "string",
+                    "enum": ["PROCEED", "REVISE", "BLOCK"],
+                },
+                "matches_previous": {"type": ["boolean", "null"]},
+                "repeated_verbatim": {
+                    "type": "boolean",
+                    "description": (
+                        "True when an objection carried no new fact, so the prior "
+                        "verdict stands rather than being re-argued."
+                    ),
+                },
+                "basis": {"type": "string"},
+            },
+            "required": ["current_verdict"],
+            "additionalProperties": True,
+        },
+        "escalation_required": {
+            "type": "boolean",
+            "description": (
+                "True when a human must decide. PROCEED is unavailable while this is set."
+            ),
+        },
+        "escalation_reasons": {
+            "type": "array",
+            "items": {"type": "string"},
+        },
+        # active_count counts what the decision table consumed: active AND
+        # downgraded rows. tombstoned_count counts only rows that left the table.
+        "active_count": {"type": "integer", "minimum": 0},
+        "downgraded_count": {"type": "integer", "minimum": 0},
+        "tombstoned_count": {"type": "integer", "minimum": 0},
+    },
+    "required": [
+        "schema_version",
+        "branch",
+        "generated_at",
+        "findings_registry",
+        "not_verified",
+        "computed_verdict",
+        "verdict_table",
+        "journal",
+    ],
+    "additionalProperties": True,
+}

{mapify_cli-3.24.0/src/mapify_cli/templates → mapify_cli-3.25.0/src/mapify_cli/templates/codex}/hooks/workflow-gate.py

@@ -190,7 +190,18 @@ def is_exempt_path(file_path: str) -> bool:
     # rules written by ``/map-learn``. The exemption is restricted to ``*.md`` files to
     # prevent the directory from quietly broadening into a general bypass for arbitrary
     # file types (executables, configs, secrets-bearing JSON, etc.).
-    return bool(len(parts) >= 4 and parts[:3] == (".claude", "rules", "learned") and parts[-1].endswith(".md"))
+    if len(parts) >= 4 and parts[:3] == (".claude", "rules", "learned") and parts[-1].endswith(".md"):
+        return True
+    # POLICY: ``.claude/agent-memory/`` and ``.claude/agent-memory-local/`` are the
+    # destinations for role-local persistent memory written by learning agents (e.g.
+    # reflector). Exemption is restricted to ``*.md`` files only — the same narrow
+    # scope as the ``rules/learned/`` exemption above.
+    return (
+        len(parts) >= 3
+        and parts[0] == ".claude"
+        and parts[1] in ("agent-memory", "agent-memory-local")
+        and parts[-1].endswith(".md")
+    )
 
 
 def sanitize_branch_name(branch: str) -> str:

{mapify_cli-3.24.0 → mapify_cli-3.25.0}/src/mapify_cli/templates/codex/skills/map-review/review-reference.md

@@ -300,10 +300,17 @@ python3 .map/scripts/map_step_runner.py write_learning_handoff \
 This preserves `active-issues`, `pr-draft`, and `learning-handoff` flows.
 
 If edits are needed (REVISE/BLOCK), write the stage gate so the owning
-workflow can continue:
+workflow can continue. Positional arguments are
+`<stage> <verdict> <source_artifact> <notes>` — the summary is the FOURTH
+argument, not the third. The runner normalizes `PROCEED` -> `ready`,
+`REVISE` -> `needs-revision`, `BLOCK` -> `blocked`:
 
 ```bash
-python3 .map/scripts/map_step_runner.py write_stage_gate review "$FINAL_VERDICT" "$REVIEW_SUMMARY"
+python3 .map/scripts/map_step_runner.py write_stage_gate \
+  review \
+  "$FINAL_VERDICT" \
+  code-review-001.md \
+  "$REVIEW_SUMMARY"
 ```
 
 Set `RUN_HEALTH_STATUS` from verdict:

{mapify_cli-3.24.0/src/mapify_cli/templates/codex → mapify_cli-3.25.0/src/mapify_cli/templates}/hooks/workflow-gate.py

@@ -190,7 +190,18 @@ def is_exempt_path(file_path: str) -> bool:
     # rules written by ``/map-learn``. The exemption is restricted to ``*.md`` files to
     # prevent the directory from quietly broadening into a general bypass for arbitrary
     # file types (executables, configs, secrets-bearing JSON, etc.).
-    return bool(len(parts) >= 4 and parts[:3] == (".claude", "rules", "learned") and parts[-1].endswith(".md"))
+    if len(parts) >= 4 and parts[:3] == (".claude", "rules", "learned") and parts[-1].endswith(".md"):
+        return True
+    # POLICY: ``.claude/agent-memory/`` and ``.claude/agent-memory-local/`` are the
+    # destinations for role-local persistent memory written by learning agents (e.g.
+    # reflector). Exemption is restricted to ``*.md`` files only — the same narrow
+    # scope as the ``rules/learned/`` exemption above.
+    return (
+        len(parts) >= 3
+        and parts[0] == ".claude"
+        and parts[1] in ("agent-memory", "agent-memory-local")
+        and parts[-1].endswith(".md")
+    )
 
 
 def sanitize_branch_name(branch: str) -> str: