mapify-cli 3.19.0__py3-none-any.whl → 3.20.0__py3-none-any.whl

mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.19.0"
+__version__ = "3.20.0"
 
 import os
 import subprocess

mapify_cli/config/project_config.py

@@ -122,6 +122,12 @@ class MapConfig:
     # .map/config.yaml. When enabled, the map-so-search skill is available.
     sofa_enabled: bool = False
 
+    # 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
+    # and keep the IDs the framework wrote into comments/strings/test names.
+    scrub_internal_ids: bool = True
+
 
 def load_map_config(project_path: Path) -> MapConfig:
     """Load MAP config from .map/config.yaml with fallback to defaults.
@@ -384,6 +390,11 @@ minimality: lite
 # Stack Overflow for Agents (SOFA) integration — opt-in, off by default.
 # Enable via `mapify init --sofa` or uncomment the line below.
 # sofa.enabled: false
+
+# 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.
+# scrub_internal_ids: true
 """
 
 

mapify_cli/templates/agents/actor.md

@@ -776,6 +776,7 @@ Follow this protocol exactly — do not infer "how seniors write" or add stylist
 4. **Intent comments**: Add a one-line `# Intent: <why>` comment above any non-obvious logic block. Do NOT comment obvious code.
 5. **Performance**: Clarity first, optimize only if proven necessary.
 6. **Imports**: Group by stdlib → third-party → local. One blank line between groups.
+7. **No internal workflow IDs in comments or strings**: NEVER write MAP-internal workflow identifiers — subtask `ST-001`, acceptance criteria `AC-3`, verification criteria `VC1`, invariants `INV-7`, hard constraints `HC-1` — into shipped code comments or string literals. They are workflow scaffolding, not user-facing documentation. State the *reason* without the ID (`# enforce single-writer invariant`, not `# INV-7 single writer`). The one exception is the transient `test_vc<n>_*` test-naming aid described above: keep it during the run — the framework strips the `vc<n>` segment from shipped tests automatically at completion.
 
 ## Error Handling Patterns
 

mapify_cli/templates/hooks/README.md

@@ -86,7 +86,7 @@ documented per event in the official Claude Code docs.
 
 ## Hook inventory
 
-All 15 hooks (14 `.py` + `end-of-turn.sh`) are classified against the
+All 16 hooks (15 `.py` + `end-of-turn.sh`) are classified against the
 `MAP_INVOKED_BY` recursion-guard contract. **REQUIRE_GUARD** hooks early-exit
 when MAP spawns a nested subprocess; **FORBID_GUARD** hooks must always fire
 and may not carry the guard. Full contract and per-hook rationale:
@@ -107,6 +107,7 @@ classification is enforced by `scripts/lint-hooks.py` (in `make lint` /
 | `pre-compact-save-transcript.py` | `PreCompact` | No | REQUIRE_GUARD | Save full conversation transcript |
 | `detect-clarification-triggers.py` | `UserPromptSubmit` | No | REQUIRE_GUARD | Detect "ask if unclear" + async/durability language |
 | `end-of-turn.sh` | `Stop` | No | REQUIRE_GUARD | Auto-fix lint/format silently |
+| `scrub-internal-ids.py` | `Stop` | No | REQUIRE_GUARD | On `WORKFLOW_COMPLETE`, strip leaked `ST-`/`AC-`/`VC-`/`INV-`/`HC-` IDs from run-changed code and commit the cleanup (gated, runs once) |
 | `map-memory-capture.py` | `Stop` | No | REQUIRE_GUARD | Append per-turn scratch WAL record (cross-session memory) |
 | `map-memory-endmark.py` | `SessionEnd` | No | REQUIRE_GUARD | Best-effort 'ended' marker for the session WAL |
 | `map-memory-finalize.py` | `SessionStart` | No | REQUIRE_GUARD | Finalize prior dirty session scratches into digests (claude -p) |

mapify_cli/templates/hooks/scrub-internal-ids.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""Strip MAP-internal workflow IDs from shipped code — Stop hook.
+
+Runs when the main agent finishes a turn (Stop event). It is a thin, strictly
+gated wrapper: the deterministic work lives in ``.map/scripts/scrub_internal_ids
+.py`` (stdlib-only, importable-free, identical in this repo and installed
+projects — same split as ``map-token-meter`` / ``map_step_runner``).
+
+Why a Stop hook and not a skill step: the executor must not depend on the agent
+remembering to call a command at close. The harness fires Stop deterministically;
+the hook decides for itself whether the run is done.
+
+Gating (no-op in ~all turns):
+    1. ``MAP_INVOKED_BY`` set            -> exit (don't run inside a sub-agent).
+    2. no ``.map/<branch>/step_state.json`` OR ``workflow_status`` is not
+       ``WORKFLOW_COMPLETE``            -> exit (run not finished).
+    3. marker ``.map/<branch>/.scrub_done`` present -> exit (already ran once).
+    4. ``scrub_internal_ids: false`` in ``.map/config.yaml`` -> exit (opt-out).
+
+When it does run: calls the engine in ``clean`` mode, commits the resulting
+working-tree changes as a dedicated ``chore(map): strip internal workflow IDs``
+commit (never amends), and writes the marker so it fires exactly once.
+
+Synchronous by design (justified exception to the async-hook rule): the scrub
+must finish and commit before the run is considered done; a detached run would
+race the close/PR and could land after it. The work is fast — scoped to the
+run's git diff, like ``end-of-turn.sh``.
+
+Exit codes: always 0. The scrub is advisory and must never block a turn.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+PROJECT_DIR = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+ENGINE = PROJECT_DIR / ".map" / "scripts" / "scrub_internal_ids.py"
+
+
+def _silent() -> NoReturn:
+    sys.stdout.write("{}")
+    sys.exit(0)
+
+
+def _sanitize_branch(branch: str) -> str:
+    sanitized = branch.replace("/", "-")
+    sanitized = re.sub(r"[^a-zA-Z0-9_.-]", "-", sanitized)
+    sanitized = re.sub(r"-+", "-", sanitized).strip("-")
+    if ".." in sanitized or sanitized.startswith("."):
+        return "default"
+    return sanitized or "default"
+
+
+def _get_branch() -> str:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            capture_output=True, text=True, cwd=PROJECT_DIR, timeout=2,
+        )
+        if result.returncode == 0:
+            return _sanitize_branch(result.stdout.strip())
+    except Exception:
+        pass
+    return "default"
+
+
+def _scrub_enabled(branch_dir: Path) -> bool:
+    """Honor the ``scrub_internal_ids`` opt-out in .map/config.yaml (default on).
+
+    Minimal stdlib parse — PyYAML is not guaranteed in installed projects.
+    """
+    config = PROJECT_DIR / ".map" / "config.yaml"
+    if not config.exists():
+        return True
+    try:
+        text = config.read_text(encoding="utf-8")
+    except OSError:
+        return True
+    m = re.search(r"^\s*scrub[._]internal_ids\s*:\s*(\S+)", text, re.MULTILINE)
+    if m and m.group(1).strip().lower() in ("false", "no", "off", "0"):
+        return False
+    return True
+
+
+def main() -> None:
+    if os.environ.get("MAP_INVOKED_BY"):
+        sys.exit(0)
+    # Stop payload is read defensively but not required.
+    try:
+        json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        pass
+
+    branch = _get_branch()
+    branch_dir = PROJECT_DIR / ".map" / branch
+    state_file = branch_dir / "step_state.json"
+    if not state_file.exists():
+        _silent()
+    try:
+        state = json.loads(state_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        _silent()
+
+    status = str(state.get("workflow_status") or "").strip().upper()
+    if status != "WORKFLOW_COMPLETE":
+        _silent()
+
+    marker = branch_dir / ".scrub_done"
+    if marker.exists():
+        _silent()
+    if not _scrub_enabled(branch_dir):
+        marker.write_text("disabled\n", encoding="utf-8")
+        _silent()
+    if not ENGINE.exists():
+        _silent()
+
+    # Run the engine. MAP_INVOKED_BY guards any nested hook from re-entering.
+    env = {**os.environ, "MAP_INVOKED_BY": "scrub-internal-ids"}
+    try:
+        proc = subprocess.run(
+            [sys.executable, str(ENGINE), "clean", "--branch", branch],
+            capture_output=True, text=True, cwd=PROJECT_DIR, env=env, timeout=120,
+        )
+    except (OSError, subprocess.SubprocessError):
+        _silent()
+
+    report = {}
+    try:
+        report = json.loads(proc.stdout)
+    except (json.JSONDecodeError, ValueError):
+        report = {}
+
+    modified = report.get("files_modified") or []
+    if modified:
+        try:
+            subprocess.run(["git", "add", "--", *modified], cwd=PROJECT_DIR,
+                           env=env, capture_output=True, text=True, timeout=15)
+            subprocess.run(
+                ["git", "commit", "-m", "chore(map): strip internal workflow IDs"],
+                cwd=PROJECT_DIR, env=env, capture_output=True, text=True, timeout=30,
+            )
+        except (OSError, subprocess.SubprocessError):
+            pass  # leave the cleaned working tree in place; never block
+
+    # Mark done so the scrub fires exactly once for this completed run.
+    try:
+        marker.write_text(
+            json.dumps({
+                "files_modified": modified,
+                "tokens_removed": report.get("tokens_removed", 0),
+                "tests_renamed": report.get("tests_renamed", []),
+                "residual": report.get("residual", []),
+            }) + "\n",
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+
+    if report.get("residual"):
+        sys.stderr.write(
+            "[scrub-internal-ids] could not auto-remove some internal IDs; "
+            f"see {marker} (residual list).\n"
+        )
+    _silent()
+
+
+if __name__ == "__main__":
+    main()