mapify-cli 3.34.2__py3-none-any.whl → 3.35.0__py3-none-any.whl

mapify_cli/__init__.py

@@ -23,7 +23,7 @@ Or install globally:
     mapify check
 """
 
-__version__ = "3.34.2"
+__version__ = "3.35.0"
 
 # MUST stay the first import: it turns "this interpreter is older than 3.11" into
 # a message that says so, instead of the ImportError raised by `from datetime
@@ -144,6 +144,7 @@ from mapify_cli.provider_registry import (
     SUPPORTED_PROVIDERS,
     skill_dir,
 )
+from mapify_cli.ralph_state import sanitize_branch_name
 
 if TYPE_CHECKING:
     from mapify_cli.install_manifest import InstallManifest
@@ -434,7 +435,7 @@ def _detect_provider(project_path: Path) -> str:
 def get_project_health(project_path: Path) -> dict[str, Any]:
     """Collect project health diagnostics for check/doctor commands."""
     agent_exclude = {"README.md", "CHANGELOG.md", "MCP-PATTERNS.md"}
-    current_branch = sanitize_identifier(get_current_branch_name())
+    current_branch = sanitize_branch_name(get_current_branch_name())
     branch_dir = project_path / ".map" / current_branch
     detected = _detect_provider(project_path)
 
@@ -548,7 +549,7 @@ def get_current_branch_name() -> str:
 
 def get_branch_workspace_dir(project_path: Path, branch: str | None = None) -> Path:
     """Return the branch-scoped MAP workspace directory."""
-    branch_name = sanitize_identifier(branch or get_current_branch_name())
+    branch_name = sanitize_branch_name(branch or get_current_branch_name())
     return project_path / ".map" / branch_name
 
 
@@ -563,7 +564,7 @@ def get_branch_artifact_templates() -> dict[str, str]:
 
 def initialize_branch_workspace(project_path: Path, branch: str | None = None) -> Path:
     """Create branch-scoped planning artifacts inside `.map/<branch>/`."""
-    branch_name = sanitize_identifier(branch or get_current_branch_name())
+    branch_name = sanitize_branch_name(branch or get_current_branch_name())
     workspace_dir = get_branch_workspace_dir(project_path, branch_name)
     workspace_dir.mkdir(parents=True, exist_ok=True)
 
@@ -579,7 +580,7 @@ def get_branch_workspace_status(
     project_path: Path, branch: str | None = None
 ) -> dict[str, Any]:
     """Collect status information for branch-scoped planning artifacts."""
-    branch_name = sanitize_identifier(branch or get_current_branch_name())
+    branch_name = sanitize_branch_name(branch or get_current_branch_name())
     workspace_dir = get_branch_workspace_dir(project_path, branch_name)
     expected_files = list(get_branch_artifact_templates().keys())
     existing_files = (

mapify_cli/delivery/file_copier.py

@@ -511,6 +511,8 @@ _UPDATE_RUNTIME_GITIGNORE_PATHS = (
     ".map/provider-refresh.lock",
     ".map/installer.lock",
     ".map/gitignore.lock",
+    ".map/**/sessions/",
+    "**/__pycache__/",
     ".claude/worktrees/",
 )
 _WINDOWS_GITIGNORE_MUTEX_TIMEOUT_MS = 30_000
@@ -1135,6 +1137,48 @@ def _gitignore_pattern_matches(pattern: bytes, path: bytes) -> bool:
     return match(0, 0)
 
 
+def _gitignore_patterns_may_overlap(left: bytes, right: bytes) -> bool:
+    """Conservatively intersect patterns, including recursive directory rules.
+
+    Unlike matching a concrete path, either side can contain wildcards. Two
+    wildcard-bearing segments may overlap; literal segments still constrain the
+    result so unrelated negations do not cause repeated ignore-file growth.
+    """
+    def parts(pattern: bytes) -> list[bytes]:
+        stripped = pattern.rstrip(b"/")
+        segments = stripped.lstrip(b"/").split(b"/")
+        return [b"**", *segments] if b"/" not in stripped else segments
+
+    a, b = parts(left), parts(right)
+    pending = [(0, 0)]
+    seen: set[tuple[int, int]] = set()
+    while pending:
+        i, j = pending.pop()
+        if (i, j) in seen:
+            continue
+        seen.add((i, j))
+        if i == len(a) and j == len(b):
+            return True
+        if i < len(a) and a[i] == b"**":
+            pending.append((i + 1, j))
+            if j < len(b):
+                pending.append((i, j + 1))
+        elif j < len(b) and b[j] == b"**":
+            pending.append((i, j + 1))
+            if i < len(a):
+                pending.append((i + 1, j))
+        elif i < len(a) and j < len(b):
+            a_glob = any(char in a[i] for char in (b"*", b"?", b"["))
+            b_glob = any(char in b[j] for char in (b"*", b"?", b"["))
+            if (
+                (a_glob and b_glob)
+                or fnmatchcase(a[i], b[j])
+                or fnmatchcase(b[j], a[i])
+            ):
+                pending.append((i + 1, j + 1))
+    return False
+
+
 def _negation_targets_path(negation: bytes, required: bytes) -> bool:
     """Return whether a later ``!`` rule can plausibly re-include *required*.
 
@@ -1148,6 +1192,10 @@ def _negation_targets_path(negation: bytes, required: bytes) -> bool:
     if not pattern:
         return False
     base = required.rstrip(b"/")
+    if b"*" in base and _gitignore_patterns_may_overlap(
+        pattern, required
+    ):
+        return True
     if _gitignore_pattern_matches(pattern, base):
         return True
     pattern_base = pattern.rstrip(b"/")

mapify_cli/memory/capture.py

@@ -55,7 +55,8 @@ def _sanitize_branch(name: str) -> str:
     rest of MAP (a path-traversal hardening applied there is inherited here).
     Behaviour: replaces every character not in [a-zA-Z0-9_.-] with '-',
     collapses consecutive '-', strips leading/trailing '-', and falls back to
-    "default" on empty result or path-traversal indicators.
+    "default" on empty input or path-traversal indicators. Non-empty names
+    stripped entirely by normalization use a deterministic SHA-256 scope.
     """
     return sanitize_branch_name(name)
 

mapify_cli/ralph_state.py

@@ -10,6 +10,7 @@ State persisted to .map/<branch>/ralph_state.json
 Circuit breaker config source: .claude/ralph-loop-config.json
 """
 
+import hashlib
 import json
 import re
 from dataclasses import dataclass, field
@@ -299,7 +300,7 @@ def sanitize_branch_name(branch: str) -> str:
     # Prevent path traversal attempts
     if ".." in sanitized or sanitized.startswith("."):
         return "default"
-    return sanitized or "default"
+    return sanitized or ("branch-" + hashlib.sha256(branch.encode("utf-8")).hexdigest() if branch else "default")
 
 
 @dataclass

mapify_cli/templates/agents/actor.md

@@ -289,6 +289,7 @@ Rules:
 8. Do NOT add temporal comments about test failure status (e.g., "currently FAILS",
    "expected to FAIL", "will PASS once fix is applied"). Write tests as permanent,
    clean code — the Red/Green state is transient and must not leak into comments.
+9. Every test must pass the vacuous-test check in section 5 (Testing Considerations).
 
 Output:
 - Test files created via Write tool
@@ -395,6 +396,31 @@ Document key decisions using this structure:
 - For each `VCn:` item in `validation_criteria`, implement or update at least one automated test that would fail without your change and pass with it.
 - Prefer naming tests with `vc<n>` (e.g., `test_vc1_*`, `TestVC1*`) so Monitor can deterministically confirm coverage.
 
+**Vacuous-test check (do-nothing implementation).** For every new or changed
+test, name the assertion that would FAIL if the code under test were replaced by
+a do-nothing implementation: each function returns the empty value of its return
+type (`None`, `[]`, `{}`, `""`, `0`, `False`) and performs no side effect (no
+write, no call, no state change). No such assertion means the test is
+**vacuous**: it stays green when the code does nothing, so it verifies no behavior.
+
+Typical vacuous shapes:
+- no assertion at all: `process(data)`
+- only a type/shape check an empty value satisfies: `assert isinstance(parse("a,b"), list)`
+- only `is not None` / truthiness of a value an empty implementation also returns: `assert load({"x": 1}) is not None`
+- only checks values the test set up itself, never calling the code under test: `repo.get.return_value = item; assert repo.get(1) == item`
+- expects an exception the test itself raises, not the code under test: `with pytest.raises(KeyError): load({"x": 1})["missing"]`
+
+Not vacuous: `assert parse("a,b") == ["a", "b"]`; expected-exception tests
+(`pytest.raises`, `assertRaises`, `toThrow`) whose exception is raised by the code
+under test, because a do-nothing implementation does not raise it; and, for code
+whose job is a side effect, assertions on that
+effect (written content, persisted row, a call with the expected arguments).
+This check catches tests that verify nothing; it does not prove a test checks the
+right thing (that needs mutation testing).
+
+Self-check before handoff: rewrite or drop any vacuous test. Monitor counts it as
+no coverage.
+
 **Format**:
 ```text
 1. test_[function]_[scenario]_[expected]
@@ -484,6 +510,7 @@ exhaustive test matrices by default.
 - [ ] Trade-offs documented with alternatives
 - [ ] Test cases cover happy + edge + error paths
 - [ ] Each `validation_criteria` item has at least one automated test (or explicit N/A with reason)
+- [ ] No vacuous tests: each new or changed test fails against a do-nothing implementation
 - [ ] Template variables `{{...}}` preserved in generated code
 
 ### Hallucination Guard

mapify_cli/templates/agents/evaluator.md

@@ -624,6 +624,32 @@ Untested code is broken code waiting to happen. Testability indicates design qua
 - [ ] Happy path + error cases tested?
 - [ ] Edge cases covered?
 - [ ] Tests are deterministic (not flaky)?
+- [ ] Every new or changed test fails against a do-nothing implementation?
+
+**Vacuous-test check (do-nothing implementation).** For every new or changed
+test, name the assertion that would FAIL if the code under test were replaced by
+a do-nothing implementation: each function returns the empty value of its return
+type (`None`, `[]`, `{}`, `""`, `0`, `False`) and performs no side effect (no
+write, no call, no state change). No such assertion means the test is
+**vacuous**: it stays green when the code does nothing, so it verifies no behavior.
+
+Typical vacuous shapes:
+- no assertion at all: `process(data)`
+- only a type/shape check an empty value satisfies: `assert isinstance(parse("a,b"), list)`
+- only `is not None` / truthiness of a value an empty implementation also returns: `assert load({"x": 1}) is not None`
+- only checks values the test set up itself, never calling the code under test: `repo.get.return_value = item; assert repo.get(1) == item`
+- expects an exception the test itself raises, not the code under test: `with pytest.raises(KeyError): load({"x": 1})["missing"]`
+
+Not vacuous: `assert parse("a,b") == ["a", "b"]`; expected-exception tests
+(`pytest.raises`, `assertRaises`, `toThrow`) whose exception is raised by the code
+under test, because a do-nothing implementation does not raise it; and, for code
+whose job is a side effect, assertions on that
+effect (written content, persisted row, a call with the expected arguments).
+This check catches tests that verify nothing; it does not prove a test checks the
+right thing (that needs mutation testing).
+
+Score vacuous tests as absent: they add nothing to test coverage or test
+quality, and code covered only by vacuous tests is scored as untested.
 
 <example type="score_9">
 **Code**: Dependency injection, 95% coverage, tests for happy path + 5 error cases + 3 edge cases, mocked external APIs, isolated tests.

mapify_cli/templates/agents/monitor.md

@@ -62,6 +62,26 @@ subtask metadata) apply only to Actor subtask validation, not standalone review.
 
 ### Actor runtime preflight in linked worktrees
 
+**Managed Actor worktree:** use the `monitor_instruction` returned by
+`create_subtask_worktree` (also included by `build_context_block` after creation).
+It names the parent metadata root, candidate checkout, and two absolute runner
+commands with **both** `--metadata-root <parent>` and `--worktree <candidate>`.
+Run those commands instead of the checkout-local commands below. The runner
+verifies the registered subtask/path and shared Git repository, reads the
+blueprint and prior results from the parent, and computes the candidate diff
+against its registered creation SHA. Parent dirty baselines never filter this
+diff. Read AAG/research/state from the supplied parent branch directory; run
+source inspection, builds, and tests in the candidate. Do not copy or symlink
+mutable `.map/` artifacts into managed candidates, and do not globally redirect
+`CLAUDE_PROJECT_DIR` to the parent. Explicit roots apply only to these gates.
+Missing/mismatched registration, metadata, or runner is a blocking setup error:
+report `valid: false`, `recommendation: "block"`; never fall back to the parent
+diff or silently use the checkout-local gates. Unset inherited Git directory
+and index variables for independent source/test commands as well.
+
+**Unmanaged checkout without explicit managed context:** use the existing
+checkout-local preflight below. A standalone `/map-review` skips both variants.
+
 Before invoking either Actor-specific `.map/scripts/map_step_runner.py` gate,
 clear inherited `GIT_DIR`, `GIT_WORK_TREE`, `GIT_COMMON_DIR`, and
 `GIT_INDEX_FILE` in a subshell before resolving the checkout being reviewed
@@ -1263,18 +1283,49 @@ for user in users:
 2. Check if external calls can be mocked
 3. Review included tests for coverage
 4. Validate test assertions are specific
+5. Apply the vacuous-test check below to every new or changed test
+
+**Vacuous-test check (do-nothing implementation).** For every new or changed
+test, name the assertion that would FAIL if the code under test were replaced by
+a do-nothing implementation: each function returns the empty value of its return
+type (`None`, `[]`, `{}`, `""`, `0`, `False`) and performs no side effect (no
+write, no call, no state change). No such assertion means the test is
+**vacuous**: it stays green when the code does nothing, so it verifies no behavior.
+
+Typical vacuous shapes:
+- no assertion at all: `process(data)`
+- only a type/shape check an empty value satisfies: `assert isinstance(parse("a,b"), list)`
+- only `is not None` / truthiness of a value an empty implementation also returns: `assert load({"x": 1}) is not None`
+- only checks values the test set up itself, never calling the code under test: `repo.get.return_value = item; assert repo.get(1) == item`
+- expects an exception the test itself raises, not the code under test: `with pytest.raises(KeyError): load({"x": 1})["missing"]`
+
+Not vacuous: `assert parse("a,b") == ["a", "b"]`; expected-exception tests
+(`pytest.raises`, `assertRaises`, `toThrow`) whose exception is raised by the code
+under test, because a do-nothing implementation does not raise it; and, for code
+whose job is a side effect, assertions on that
+effect (written content, persisted row, a call with the expected arguments).
+This check catches tests that verify nothing; it does not prove a test checks the
+right thing (that needs mutation testing).
+
+A vacuous test does not count as coverage: a `VCn` or requirement covered only
+by vacuous tests has `test_coverage != PASS` and falls under the contract
+Decision Rule. Report each one as a `testability` issue titled
+`Vacuous test: <test id>` that names the missing assertion; severity HIGH when it
+is the only test for a requirement, otherwise MEDIUM.
 
 #### Pass Criteria
 - Dependencies injected, not hardcoded
 - Tests cover happy path and errors
 - Tests are deterministic and isolated
 - Assertions validate specific behaviors
+- Every new or changed test fails against a do-nothing implementation
 
 #### Common Failures
 - Hardcoded external dependencies
 - Missing tests for error cases
 - Flaky tests (time-dependent, order-dependent)
 - Generic assertions (assertTrue without specifics)
+- Vacuous tests that stay green against a do-nothing implementation
 
 #### Severity Mapping
 - **Critical**: Untestable design blocking all testing

mapify_cli/templates/agents/review-reader.md

@@ -28,7 +28,16 @@ changed-hunk attribution instead of shell commands. A line existing at base does
 not prove a behavioral defect is pre-existing; require supporting context or mark
 attribution unknown. Request missing bundle content from the parent, never shell.
 
-Return the role's envelope with an additional receipt object:
+When the prompt provides parent-served context, return its exact context_request
+JSON and consume context_chunk continuations in this same session. Follow
+next_offset through eof and check offsets, total size and hash metadata against the manifest before using it. Request
+permitted resources from the parent, never read context object paths directly.
+These intermediate responses are not findings or final review envelopes.
+Wait for the parent's post-delivery finalization request before returning a final
+review. In structured final envelopes, echo its session_id and finalization_token
+in a context_receipt object.
+Delivery is parent_acknowledged; it does not prove inspection or capability.
+After receiving needed evidence, return the role's envelope with an additional receipt object:
 `receipt={covered_files:[],skipped_files:[],denied_access:[],check_evidence:[check_id]}`.
 List only paths actually inspected in covered_files; report skipped scope and denied
 required access honestly. Reading claims are self_reported, not tool_witnessed.

mapify_cli/templates/codex/agents/actor.toml

@@ -22,6 +22,32 @@ changes, never revert unrelated work, and adapt to concurrent edits.
 6. Never edit generated MAP trees directly when repository instructions designate a
    template source; edit the source and run the documented renderer.
 7. Do not commit, publish, delete broad paths, or expand scope without explicit authority.
+8. Before reporting, apply the vacuous-test check below to every test you wrote or
+   changed; rewrite or drop any vacuous test. Monitor counts it as no coverage.
+
+# Vacuous tests
+
+**Vacuous-test check (do-nothing implementation).** For every new or changed
+test, name the assertion that would FAIL if the code under test were replaced by
+a do-nothing implementation: each function returns the empty value of its return
+type (`None`, `[]`, `{}`, `""`, `0`, `False`) and performs no side effect (no
+write, no call, no state change). No such assertion means the test is
+**vacuous**: it stays green when the code does nothing, so it verifies no behavior.
+
+Typical vacuous shapes:
+- no assertion at all: `process(data)`
+- only a type/shape check an empty value satisfies: `assert isinstance(parse("a,b"), list)`
+- only `is not None` / truthiness of a value an empty implementation also returns: `assert load({"x": 1}) is not None`
+- only checks values the test set up itself, never calling the code under test: `repo.get.return_value = item; assert repo.get(1) == item`
+- expects an exception the test itself raises, not the code under test: `with pytest.raises(KeyError): load({"x": 1})["missing"]`
+
+Not vacuous: `assert parse("a,b") == ["a", "b"]`; expected-exception tests
+(`pytest.raises`, `assertRaises`, `toThrow`) whose exception is raised by the code
+under test, because a do-nothing implementation does not raise it; and, for code
+whose job is a side effect, assertions on that
+effect (written content, persisted row, a call with the expected arguments).
+This check catches tests that verify nothing; it does not prove a test checks the
+right thing (that needs mutation testing).
 
 # Output
 

mapify_cli/templates/codex/agents/evaluator.toml

@@ -88,6 +88,31 @@ Weighting: readability 40%, maintainability 30%, idioms 30%.
 0-1: hardcoded dependencies, no test consideration.
 Weighting: test coverage 40%, test quality 30%, design for testability 30%.
 
+**Vacuous-test check (do-nothing implementation).** For every new or changed
+test, name the assertion that would FAIL if the code under test were replaced by
+a do-nothing implementation: each function returns the empty value of its return
+type (`None`, `[]`, `{}`, `""`, `0`, `False`) and performs no side effect (no
+write, no call, no state change). No such assertion means the test is
+**vacuous**: it stays green when the code does nothing, so it verifies no behavior.
+
+Typical vacuous shapes:
+- no assertion at all: `process(data)`
+- only a type/shape check an empty value satisfies: `assert isinstance(parse("a,b"), list)`
+- only `is not None` / truthiness of a value an empty implementation also returns: `assert load({"x": 1}) is not None`
+- only checks values the test set up itself, never calling the code under test: `repo.get.return_value = item; assert repo.get(1) == item`
+- expects an exception the test itself raises, not the code under test: `with pytest.raises(KeyError): load({"x": 1})["missing"]`
+
+Not vacuous: `assert parse("a,b") == ["a", "b"]`; expected-exception tests
+(`pytest.raises`, `assertRaises`, `toThrow`) whose exception is raised by the code
+under test, because a do-nothing implementation does not raise it; and, for code
+whose job is a side effect, assertions on that
+effect (written content, persisted row, a call with the expected arguments).
+This check catches tests that verify nothing; it does not prove a test checks the
+right thing (that needs mutation testing).
+
+Score vacuous tests as absent: they add nothing to test coverage or test
+quality, and code covered only by vacuous tests is scored as untested.
+
 ## 6. Performance (0-10)
 10: efficient algorithms, appropriate data structures, handles scale.
 8-9: reasonable complexity, minor optimizations possible.

mapify_cli/templates/codex/agents/monitor.toml

@@ -53,6 +53,26 @@ subtask metadata) apply only to Actor subtask validation, not standalone review.
 
 ### Actor runtime preflight in linked worktrees
 
+**Managed Actor worktree:** use the `monitor_instruction` returned by
+`create_subtask_worktree` (also included by `build_context_block` after creation).
+It names the parent metadata root, candidate checkout, and two absolute runner
+commands with **both** `--metadata-root <parent>` and `--worktree <candidate>`.
+Run those commands instead of the checkout-local commands below. The runner
+verifies the registered subtask/path and shared Git repository, reads the
+blueprint and prior results from the parent, and computes the candidate diff
+against its registered creation SHA. Parent dirty baselines never filter this
+diff. Read AAG/research/state from the supplied parent branch directory; run
+source inspection, builds, and tests in the candidate. Do not copy or symlink
+mutable `.map/` artifacts into managed candidates, and do not globally redirect
+`CLAUDE_PROJECT_DIR` to the parent. Explicit roots apply only to these gates.
+Missing/mismatched registration, metadata, or runner is a blocking setup error:
+report `valid: false`, `recommendation: "block"`; never fall back to the parent
+diff or silently use the checkout-local gates. Unset inherited Git directory
+and index variables for independent source/test commands as well.
+
+**Unmanaged checkout without explicit managed context:** use the existing
+checkout-local preflight below. A standalone `/map-review` skips both variants.
+
 Before invoking either Actor-specific `.map/scripts/map_step_runner.py` gate,
 clear inherited `GIT_DIR`, `GIT_WORK_TREE`, `GIT_COMMON_DIR`, and
 `GIT_INDEX_FILE` in a subshell before resolving the checkout being reviewed
@@ -458,11 +478,40 @@ What to Check:
 - Tests included (happy path, errors, edge cases)
 - Test quality (deterministic, isolated, specific assertions)
 
+**Vacuous-test check (do-nothing implementation).** For every new or changed
+test, name the assertion that would FAIL if the code under test were replaced by
+a do-nothing implementation: each function returns the empty value of its return
+type (`None`, `[]`, `{}`, `""`, `0`, `False`) and performs no side effect (no
+write, no call, no state change). No such assertion means the test is
+**vacuous**: it stays green when the code does nothing, so it verifies no behavior.
+
+Typical vacuous shapes:
+- no assertion at all: `process(data)`
+- only a type/shape check an empty value satisfies: `assert isinstance(parse("a,b"), list)`
+- only `is not None` / truthiness of a value an empty implementation also returns: `assert load({"x": 1}) is not None`
+- only checks values the test set up itself, never calling the code under test: `repo.get.return_value = item; assert repo.get(1) == item`
+- expects an exception the test itself raises, not the code under test: `with pytest.raises(KeyError): load({"x": 1})["missing"]`
+
+Not vacuous: `assert parse("a,b") == ["a", "b"]`; expected-exception tests
+(`pytest.raises`, `assertRaises`, `toThrow`) whose exception is raised by the code
+under test, because a do-nothing implementation does not raise it; and, for code
+whose job is a side effect, assertions on that
+effect (written content, persisted row, a call with the expected arguments).
+This check catches tests that verify nothing; it does not prove a test checks the
+right thing (that needs mutation testing).
+
+A vacuous test does not count as coverage: a `VCn` or requirement covered only
+by vacuous tests has `test_coverage != PASS` and falls under the contract
+Decision Rule. Report each one as a `testability` issue titled
+`Vacuous test: <test id>` that names the missing assertion; severity HIGH when it
+is the only test for a requirement, otherwise MEDIUM.
+
 Pass Criteria:
 - Dependencies injected, not hardcoded
 - Tests cover happy path and errors
 - Tests are deterministic and isolated
 - Assertions validate specific behaviors
+- Every new or changed test fails against a do-nothing implementation
 
 Severity Mapping:
 - Critical: Untestable design blocking all testing

mapify_cli/templates/codex/agents/review-reader.toml

@@ -16,7 +16,16 @@ changed-hunk attribution. Native shell-free read/search has not been established
 Request missing content from the parent; never restore shell or guess attribution.
 Existing base lines alone do not prove that a behavioral defect is pre-existing.
 
-Return the role envelope plus
+When a generated prompt provides parent-served context, first return its exact
+context_request JSON and consume context_chunk continuations in this same session.
+Follow next_offset through eof; check offsets, total size and hash metadata against the manifest before using it. Request
+missing permitted resources from the parent, never object paths or extra tools.
+These are intermediate responses, not findings or final review envelopes.
+Wait for the parent's post-delivery finalization request before returning a final
+review. In structured final envelopes, echo its session_id and finalization_token
+in a context_receipt object.
+Delivery is parent_acknowledged; it does not prove inspection or capability.
+After receiving needed evidence, return the role envelope plus
 receipt={covered_files:[],skipped_files:[],denied_access:[],check_evidence:[check_id]}.
 covered_files lists only paths actually inspected, including supplied source text.
 Report missing scope and denied access honestly. Reading claims are self_reported,

mapify_cli/templates/codex/hooks/context-meter.py

@@ -53,6 +53,7 @@ if tuple(sys.version_info) < (3, 11):
     sys.stderr.write(_MAP_PYTHON_PROBLEM)
     sys.exit(1)
 
+import hashlib
 import json
 import os
 import re
@@ -76,23 +77,33 @@ def _sanitize_branch(branch: str) -> str:
     sanitized = re.sub(r"-+", "-", sanitized).strip("-")
     if ".." in sanitized or sanitized.startswith("."):
         return "default"
-    return sanitized or "default"
+    return sanitized or ("branch-" + hashlib.sha256(branch.encode("utf-8")).hexdigest() if branch else "default")
 
 
 def _get_branch() -> str:
+    """Resolve branch scope before the first commit; warn on unavailable Git."""
     try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-            capture_output=True,
-            text=True,
-            cwd=PROJECT_DIR,
-            timeout=2,
-            check=False,
-        )
+        # Symbolic HEAD exists even before the branch has its first commit.
+        # rev-parse retains the historical detached-HEAD fallback.
+        for command in (
+            ["symbolic-ref", "--quiet", "--short", "HEAD"],
+            ["rev-parse", "--abbrev-ref", "HEAD"],
+        ):
+            result = subprocess.run(
+                ["git", *command],
+                capture_output=True,
+                text=True,
+                cwd=PROJECT_DIR,
+                timeout=2,
+                check=False,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                break
         if result.returncode == 0:
             return _sanitize_branch(result.stdout.strip())
     except Exception:  # noqa: BLE001, S110 -- deliberate fallback/resilience boundary, must not propagate
         pass
+    print("MAP warning: could not determine Git branch; using .map/default/ for workflow artifacts.", file=sys.stderr)
     return "default"
 
 

mapify_cli/templates/codex/hooks/map-token-meter.py

@@ -58,6 +58,7 @@ if tuple(sys.version_info) < (3, 11):
     sys.stderr.write(_MAP_PYTHON_PROBLEM)
     sys.exit(1)
 
+import hashlib
 import json
 import os
 import re
@@ -75,23 +76,33 @@ def _sanitize_branch(branch: str) -> str:
     sanitized = re.sub(r"-+", "-", sanitized).strip("-")
     if ".." in sanitized or sanitized.startswith("."):
         return "default"
-    return sanitized or "default"
+    return sanitized or ("branch-" + hashlib.sha256(branch.encode("utf-8")).hexdigest() if branch else "default")
 
 
 def _get_branch() -> str:
+    """Resolve branch scope before the first commit; warn on unavailable Git."""
     try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-            capture_output=True,
-            text=True,
-            cwd=PROJECT_DIR,
-            timeout=2,
-            check=False,
-        )
+        # Symbolic HEAD exists even before the branch has its first commit.
+        # rev-parse retains the historical detached-HEAD fallback.
+        for command in (
+            ["symbolic-ref", "--quiet", "--short", "HEAD"],
+            ["rev-parse", "--abbrev-ref", "HEAD"],
+        ):
+            result = subprocess.run(
+                ["git", *command],
+                capture_output=True,
+                text=True,
+                cwd=PROJECT_DIR,
+                timeout=2,
+                check=False,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                break
         if result.returncode == 0:
             return _sanitize_branch(result.stdout.strip())
     except Exception:  # noqa: BLE001, S110 -- deliberate fallback/resilience boundary, must not propagate
         pass
+    print("MAP warning: could not determine Git branch; using .map/default/ for workflow artifacts.", file=sys.stderr)
     return "default"
 
 

mapify_cli/templates/codex/hooks/post-compact-context.py

@@ -37,6 +37,7 @@ if tuple(sys.version_info) < (3, 11):
     sys.stderr.write(_MAP_PYTHON_PROBLEM)
     sys.exit(1)
 
+import hashlib
 import json
 import os
 import re
@@ -64,24 +65,33 @@ def sanitize_branch_name(branch: str) -> str:
     sanitized = re.sub(r"-+", "-", sanitized).strip("-")
     if ".." in sanitized or sanitized.startswith("."):
         return "default"
-    return sanitized or "default"
+    return sanitized or ("branch-" + hashlib.sha256(branch.encode("utf-8")).hexdigest() if branch else "default")
 
 
 def get_branch_name() -> str:
     """Get current git branch name."""
     try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
-            capture_output=True,
-            text=True,
-            cwd=PROJECT_DIR,
-            timeout=2,
-            check=False,
-        )
+        # Symbolic HEAD exists even before the branch has its first commit.
+        # rev-parse retains the historical detached-HEAD fallback.
+        for command in (
+            ["symbolic-ref", "--quiet", "--short", "HEAD"],
+            ["rev-parse", "--abbrev-ref", "HEAD"],
+        ):
+            result = subprocess.run(
+                ["git", *command],
+                capture_output=True,
+                text=True,
+                cwd=PROJECT_DIR,
+                timeout=2,
+                check=False,
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                break
         if result.returncode == 0:
             return sanitize_branch_name(result.stdout.strip())
     except Exception:  # noqa: BLE001, S110 -- deliberate fallback/resilience boundary, must not propagate
         pass
+    print("MAP warning: could not determine Git branch; using .map/default/ for workflow artifacts.", file=sys.stderr)
     return "default"