its-magic 0.1.2-37 → 0.1.2-39

package/scripts/intake_evidence_lib.py

@@ -1,5 +1,6 @@
 """
-Deterministic intake evidence validation (US-0078 / DEC-0060 / R-0055).
+Deterministic intake evidence validation
+(US-0078 / US-0083 / DEC-0060 / DEC-0067 / R-0055 / BUG-0007 / R-0066).
 
 Consumes a logical intake_evidence bundle (dict). PO workflows MUST run this
 gate before mutating backlog/acceptance; failures are fail-closed.
@@ -14,6 +15,7 @@ from dataclasses import dataclass, field
 from typing import Any
 
 IE_REF_RE = re.compile(r"^ie:([^:]+):(\d+):([0-9a-f]{16})$")
+PLAN_AREA_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{1,63}$")
 
 PACK_REQUIRED_KEYS: dict[str, tuple[str, ...]] = {
     "first-intake-pack": (
@@ -51,6 +53,8 @@ SAFE_ASSUMPTION_LITERALS = frozenset(
 )
 
 FALSE_CONFIRMATION_LITERALS = frozenset({"yes", "true", "confirmed"})
+ALLOWED_SATISFIED_BY = frozenset({"answer_ref", "assumption_confirmation_ref", "delegation_ref"})
+DELEGATION_CONFIDENCE_VALUES = frozenset({"low", "medium", "high"})
 
 
 def canonical_json_sha256_16(obj: dict[str, Any]) -> str:
@@ -187,6 +191,268 @@ def _row_turn(row: dict[str, Any]) -> int | None:
         return None
 
 
+def _row_uses_equivalent_evidence(row: dict[str, Any]) -> bool:
+    """
+    US-0083 AC-1: allow required-topic accounting without forcing repetitive asks
+    when equivalent evidence is already captured and explicitly referenced.
+    """
+    marker = str(row.get("evidence_source") or "").strip()
+    if marker != "equivalent_evidence_ref":
+        return False
+    return bool(str(row.get("equivalent_evidence_ref") or "").strip())
+
+
+def _norm_answer_ref_quoted_user_text(value: Any) -> str:
+    """Normalize quoted_user_text for BUG-0007 duplicate detection (DEC-0060 strip parity)."""
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _row_exempt_from_answer_ref_topic_distinctness(row: dict[str, Any]) -> bool:
+    """BUG-0007: alternate satisfaction paths do not participate in answer_ref blob reuse checks."""
+    return _row_uses_equivalent_evidence(row)
+
+
+def _validate_answer_ref_topic_distinctness(
+    bundle: dict[str, Any],
+    required: list[str],
+    by_key: dict[str, dict[str, Any]],
+    res: ValidationResult,
+) -> None:
+    """
+    BUG-0007 / R-0066: distinct required topic_key rows must not reuse the same
+    quoted_user_text under satisfied_by=answer_ref (normalized), except exempt rows.
+    """
+    norm_to_topics: dict[str, list[str]] = {}
+    for k in required:
+        row = by_key.get(k)
+        if not row:
+            continue
+        sat = (row.get("satisfied_by") or "").strip()
+        if sat != "answer_ref":
+            continue
+        if _row_exempt_from_answer_ref_topic_distinctness(row):
+            continue
+        irid = _row_run_id(bundle, row)
+        tit = _row_turn(row)
+        if irid is None or tit is None:
+            continue
+        qraw = row.get("quoted_user_text")
+        qtxt = "" if qraw is None else str(qraw)
+        ref = (row.get("ref") or "").strip()
+        if not ref or not verify_ie_ref(
+            ref,
+            intake_run_id=irid,
+            turn_index=int(tit),
+            topic_key=k,
+            satisfied_by=sat,
+            quoted_user_text=qtxt,
+        ):
+            continue
+        norm = _norm_answer_ref_quoted_user_text(qraw)
+        norm_to_topics.setdefault(norm, []).append(k)
+
+    dup_groups: list[str] = []
+    for norm, topics in norm_to_topics.items():
+        uniq = sorted(set(topics))
+        if len(uniq) < 2:
+            continue
+        dup_groups.append("text=" + repr(norm[:120]) + " topics=" + ",".join(uniq))
+
+    if dup_groups:
+        res.ok = False
+        res.add_code("INTAKE_ANSWER_REF_NOT_TOPIC_DISTINCT")
+        res.diagnostics.append(
+            "Remediation: distinct required topics must not reuse the same quoted_user_text "
+            "under satisfied_by=answer_ref (BUG-0007 / R-0066). Duplicates: "
+            + "; ".join(dup_groups)
+            + ". Use per-topic answers, or an allowed alternate path "
+            "(evidence_source=equivalent_evidence_ref + equivalent_evidence_ref, "
+            "delegation_ref per DEC-0067 / US-0083, or assumption_confirmation_ref on the row)."
+        )
+
+
+def _candidate_story_ids(bundle: dict[str, Any]) -> set[str]:
+    out: set[str] = set()
+
+    raw_ids = bundle.get("candidate_story_ids")
+    if isinstance(raw_ids, list):
+        for sid in raw_ids:
+            sv = str(sid).strip()
+            if sv:
+                out.add(sv)
+
+    raw_story_ids = bundle.get("story_ids")
+    if isinstance(raw_story_ids, list):
+        for sid in raw_story_ids:
+            sv = str(sid).strip()
+            if sv:
+                out.add(sv)
+
+    raw_story_map = bundle.get("story_map")
+    if isinstance(raw_story_map, list):
+        for row in raw_story_map:
+            if not isinstance(row, dict):
+                continue
+            sv = str(row.get("story_id") or "").strip()
+            if sv:
+                out.add(sv)
+
+    return out
+
+
+def _validate_plan_coverage_contract(bundle: dict[str, Any], res: ValidationResult) -> None:
+    inventory_raw = bundle.get("plan_area_inventory")
+    coverage_raw = bundle.get("plan_area_coverage")
+    coverage_complete_raw = bundle.get("coverage_complete")
+    candidate_story_ids = _candidate_story_ids(bundle)
+
+    inventory_rows = inventory_raw if isinstance(inventory_raw, list) else []
+    coverage_rows = coverage_raw if isinstance(coverage_raw, list) else []
+
+    inventory_ids: list[str] = []
+    coverage_by_id: dict[str, dict[str, Any]] = {}
+
+    coverage_missing = False
+    id_invalid = False
+    contract_invalid = False
+    deferred_ref_missing = False
+
+    if not inventory_rows:
+        coverage_missing = True
+        res.diagnostics.append(
+            "Remediation: plan_area_inventory must be a non-empty list for first/new/broad intake."
+        )
+    if not coverage_rows:
+        coverage_missing = True
+        res.diagnostics.append(
+            "Remediation: plan_area_coverage must be a non-empty list for first/new/broad intake."
+        )
+
+    seen_inventory_ids: set[str] = set()
+    for row in inventory_rows:
+        if not isinstance(row, dict):
+            id_invalid = True
+            continue
+        plan_area_id = str(row.get("plan_area_id") or "").strip()
+        if not PLAN_AREA_ID_RE.match(plan_area_id):
+            id_invalid = True
+            continue
+        if plan_area_id in seen_inventory_ids:
+            id_invalid = True
+            continue
+        seen_inventory_ids.add(plan_area_id)
+        inventory_ids.append(plan_area_id)
+
+    for row in coverage_rows:
+        if not isinstance(row, dict):
+            id_invalid = True
+            continue
+        plan_area_id = str(row.get("plan_area_id") or "").strip()
+        if not PLAN_AREA_ID_RE.match(plan_area_id):
+            id_invalid = True
+            continue
+        if plan_area_id in coverage_by_id:
+            id_invalid = True
+            continue
+        coverage_by_id[plan_area_id] = row
+
+    inventory_id_set = set(inventory_ids)
+    coverage_id_set = set(coverage_by_id.keys())
+
+    if inventory_id_set != coverage_id_set:
+        coverage_missing = True
+        missing_ids = sorted(inventory_id_set - coverage_id_set)
+        extra_ids = sorted(coverage_id_set - inventory_id_set)
+        if missing_ids:
+            res.diagnostics.append(
+                "Remediation: add plan_area_coverage rows for uncovered plan_area_id values: "
+                + ", ".join(missing_ids)
+            )
+        if extra_ids:
+            contract_invalid = True
+            res.diagnostics.append(
+                "Remediation: remove unknown plan_area_coverage plan_area_id values not in plan_area_inventory: "
+                + ", ".join(extra_ids)
+            )
+
+    for plan_area_id in sorted(inventory_id_set & coverage_id_set):
+        row = coverage_by_id[plan_area_id]
+        story_ids_raw = row.get("story_ids")
+        deferred_ref = str(row.get("deferred_ref") or "").strip()
+
+        story_ids: list[str] = []
+        if isinstance(story_ids_raw, list):
+            for sid in story_ids_raw:
+                sv = str(sid).strip()
+                if sv:
+                    story_ids.append(sv)
+        has_story_ids = bool(story_ids)
+        has_deferred_ref = bool(deferred_ref)
+
+        if has_story_ids == has_deferred_ref:
+            contract_invalid = True
+            res.diagnostics.append(
+                "Remediation: each plan_area_coverage row must set exactly one mapping path "
+                "(story_ids xor deferred_ref) for plan_area_id "
+                + repr(plan_area_id)
+                + "."
+            )
+            continue
+
+        if has_story_ids:
+            if candidate_story_ids:
+                unknown_story_ids = sorted({sid for sid in story_ids if sid not in candidate_story_ids})
+                if unknown_story_ids:
+                    contract_invalid = True
+                    res.diagnostics.append(
+                        "Remediation: plan_area_id "
+                        + repr(plan_area_id)
+                        + " references unknown story_ids not present in candidate story set: "
+                        + ", ".join(unknown_story_ids)
+                    )
+        else:
+            deferred_reason = str(row.get("deferred_reason") or "").strip()
+            if not deferred_reason:
+                deferred_ref_missing = True
+                res.diagnostics.append(
+                    "Remediation: deferred mapping for plan_area_id "
+                    + repr(plan_area_id)
+                    + " requires both deferred_ref and deferred_reason."
+                )
+
+    derived_coverage_complete = not (coverage_missing or id_invalid or contract_invalid or deferred_ref_missing)
+    if coverage_complete_raw is not True:
+        contract_invalid = True
+        res.diagnostics.append(
+            "Remediation: set coverage_complete=true only after plan_area_inventory and "
+            "plan_area_coverage pass deterministic validation."
+        )
+    if bool(coverage_complete_raw) != derived_coverage_complete:
+        contract_invalid = True
+        res.diagnostics.append(
+            "Remediation: coverage_complete must match derived contract result from "
+            "plan_area_inventory/plan_area_coverage validation."
+        )
+
+    if coverage_missing:
+        res.ok = False
+        res.add_code("INTAKE_PLAN_COVERAGE_MISSING")
+    if id_invalid:
+        res.ok = False
+        res.add_code("INTAKE_PLAN_AREA_ID_INVALID")
+        res.diagnostics.append(
+            "Remediation: plan_area_id must be unique and match ^[a-z0-9][a-z0-9_-]{1,63}$ in inventory and coverage."
+        )
+    if deferred_ref_missing:
+        res.ok = False
+        res.add_code("INTAKE_PLAN_DEFERRED_REF_MISSING")
+    if contract_invalid:
+        res.ok = False
+        res.add_code("INTAKE_PLAN_COVERAGE_CONTRACT_INVALID")
+
+
 def validate_intake_evidence(
     bundle: dict[str, Any],
     *,
@@ -232,15 +498,44 @@ def validate_intake_evidence(
             qtxt = ""
         qtxt = str(qtxt)
 
-        if sat not in ("answer_ref", "assumption_confirmation_ref"):
+        if sat not in ALLOWED_SATISFIED_BY:
             res.ok = False
             res.diagnostics.append(
                 f"Remediation: topic {k!r} must set satisfied_by to "
-                f"'answer_ref' or 'assumption_confirmation_ref' (got {sat!r})."
+                f"'answer_ref', 'assumption_confirmation_ref', or 'delegation_ref' (got {sat!r})."
             )
             missing_cov.append(k)
             continue
 
+        if sat == "delegation_ref":
+            scope = str(row.get("delegation_scope") or "").strip()
+            rationale = str(row.get("delegation_rationale") or "").strip()
+            confidence = str(row.get("delegation_confidence") or "").strip().lower()
+            if not scope or not rationale or not confidence:
+                res.ok = False
+                res.add_code("INTAKE_DELEGATION_EVIDENCE_MISSING")
+                missing_fields = []
+                if not scope:
+                    missing_fields.append("delegation_scope")
+                if not rationale:
+                    missing_fields.append("delegation_rationale")
+                if not confidence:
+                    missing_fields.append("delegation_confidence")
+                res.diagnostics.append(
+                    f"Remediation: delegated topic {k!r} requires non-empty fields: "
+                    + ", ".join(missing_fields)
+                    + "."
+                )
+                continue
+            if confidence not in DELEGATION_CONFIDENCE_VALUES:
+                res.ok = False
+                res.add_code("INTAKE_DELEGATION_EVIDENCE_INVALID")
+                res.diagnostics.append(
+                    f"Remediation: delegated topic {k!r} delegation_confidence must be one of "
+                    f"{sorted(DELEGATION_CONFIDENCE_VALUES)!r} (got {confidence!r})."
+                )
+                continue
+
         irid = _row_run_id(bundle, row)
         tit = _row_turn(row)
         if irid is None or tit is None:
@@ -261,11 +556,18 @@ def validate_intake_evidence(
             quoted_user_text=qtxt,
         ):
             res.ok = False
-            res.diagnostics.append(
-                f"Remediation: topic {k!r} ref is malformed or hash mismatch — rebuild ie: ref "
-                f"with DEC-0060 canonical JSON (sorted keys) and quoted_user_text."
-            )
-            missing_cov.append(k)
+            if sat == "delegation_ref":
+                res.add_code("INTAKE_DELEGATION_EVIDENCE_INVALID")
+                res.diagnostics.append(
+                    f"Remediation: delegated topic {k!r} ref is malformed or hash mismatch — rebuild ie: ref "
+                    f"with DEC-0060 canonical JSON (sorted keys) and quoted_user_text."
+                )
+            else:
+                res.diagnostics.append(
+                    f"Remediation: topic {k!r} ref is malformed or hash mismatch — rebuild ie: ref "
+                    f"with DEC-0060 canonical JSON (sorted keys) and quoted_user_text."
+                )
+                missing_cov.append(k)
 
     if missing_cov:
         res.ok = False
@@ -283,16 +585,25 @@ def validate_intake_evidence(
         if k not in by_key:
             continue
         if k not in asked:
+            row = by_key[k]
+            if _row_uses_equivalent_evidence(row):
+                continue
             res.ok = False
             res.add_code("INTAKE_REQUIRED_TOPIC_MISSING")
             res.diagnostics.append(
-                f"Remediation: add {k!r} to asked_topics — covered topics must have been "
-                f"prompted in-session (R-0055 asked-vs-covered; DEC-0060)."
+                f"Remediation: add {k!r} to asked_topics or mark evidence_source='equivalent_evidence_ref' "
+                f"with equivalent_evidence_ref when reusing previously captured equivalent evidence."
             )
             if k not in res.missing_topics:
                 res.missing_topics.append(k)
     res.missing_topics = sorted(set(res.missing_topics))
 
+    _validate_answer_ref_topic_distinctness(bundle, required, by_key, res)
+
+    # US-0081 / DEC-0064: first/new/broad intake requires complete-plan coverage contract.
+    if pack == "first-intake-pack":
+        _validate_plan_coverage_contract(bundle, res)
+
     ac = bundle.get("assumptions_confirmed")
     ac_str = ac if isinstance(ac, str) else ("(none)" if ac is None else str(ac))
 
@@ -397,3 +708,95 @@ def self_test() -> None:
     r1 = validate_intake_evidence(bundle, intake_guided_mode=1)
     assert r0.ok and r1.ok
     assert r0.primary_codes == r1.primary_codes
+
+    # US-0083 delegated-topic pass path
+    delegated_key = "done_definition"
+    rows2 = []
+    for i, key in enumerate(small):
+        sat = "delegation_ref" if key == delegated_key else "answer_ref"
+        txt = f"d{i}"
+        row = {
+            "topic_key": key,
+            "satisfied_by": sat,
+            "quoted_user_text": txt,
+            "intake_run_id": rid,
+            "turn_index": 200 + i,
+            "ref": build_ie_ref(rid, 200 + i, key, sat, txt),
+        }
+        if sat == "delegation_ref":
+            row["delegation_scope"] = "Implementation defaults for done criteria wording"
+            row["delegation_rationale"] = "User asked to proceed without additional specificity."
+            row["delegation_confidence"] = "medium"
+        rows2.append(row)
+    delegated_bundle = {
+        "selected_pack": "small-intake-pack",
+        "intake_run_id": rid,
+        "asked_topics": list(small),
+        "missing_topics": [],
+        "assumptions_confirmed": "(none)",
+        "topic_coverage": rows2,
+    }
+    d0 = validate_intake_evidence(delegated_bundle, intake_guided_mode=0)
+    d1 = validate_intake_evidence(delegated_bundle, intake_guided_mode=1)
+    assert d0.ok and d1.ok
+    assert d0.primary_codes == d1.primary_codes
+
+    # BUG-0007: same quoted_user_text across multiple answer_ref required topics fails
+    dup_txt = "synthetic blob echoed for every topic"
+    dup_rows = []
+    for i, key in enumerate(small):
+        dup_rows.append(
+            {
+                "topic_key": key,
+                "satisfied_by": "answer_ref",
+                "quoted_user_text": dup_txt,
+                "intake_run_id": rid,
+                "turn_index": 300 + i,
+                "ref": build_ie_ref(rid, 300 + i, key, "answer_ref", dup_txt),
+            }
+        )
+    dup_bundle = {
+        "selected_pack": "small-intake-pack",
+        "intake_run_id": rid,
+        "asked_topics": list(small),
+        "missing_topics": [],
+        "assumptions_confirmed": "(none)",
+        "topic_coverage": dup_rows,
+    }
+    dup_res = validate_intake_evidence(dup_bundle)
+    assert not dup_res.ok
+    assert "INTAKE_ANSWER_REF_NOT_TOPIC_DISTINCT" in dup_res.primary_codes
+
+    # First-intake full-plan coverage contract (US-0081 / DEC-0064)
+    first = PACK_REQUIRED_KEYS["first-intake-pack"]
+    first_rows = []
+    for i, key in enumerate(first):
+        first_rows.append(
+            {
+                "topic_key": key,
+                "satisfied_by": "answer_ref",
+                "quoted_user_text": f"b{i}",
+                "intake_run_id": rid,
+                "turn_index": i,
+                "ref": build_ie_ref(rid, i, key, "answer_ref", f"b{i}"),
+            }
+        )
+    full_bundle = {
+        "selected_pack": "first-intake-pack",
+        "intake_run_id": rid,
+        "asked_topics": list(first),
+        "missing_topics": [],
+        "assumptions_confirmed": "(none)",
+        "topic_coverage": first_rows,
+        "candidate_story_ids": ["US-9001", "US-9002"],
+        "plan_area_inventory": [
+            {"plan_area_id": "auth", "title": "Auth"},
+            {"plan_area_id": "billing", "title": "Billing"},
+        ],
+        "plan_area_coverage": [
+            {"plan_area_id": "auth", "story_ids": ["US-9001"]},
+            {"plan_area_id": "billing", "story_ids": ["US-9002"]},
+        ],
+        "coverage_complete": True,
+    }
+    assert validate_intake_evidence(full_bundle, intake_guided_mode=0).ok

package/scripts/intake_evidence_validate.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Validate intake_evidence JSON bundles (US-0078 / DEC-0060).
+Validate intake_evidence JSON bundles (US-0078 / US-0083 / DEC-0060 / DEC-0067).
 
 Used by PO workflow preflight and CI fixtures.
 """
@@ -21,7 +21,7 @@ import intake_evidence_lib  # noqa: E402
 
 
 def main() -> int:
-    p = argparse.ArgumentParser(description="Validate intake_evidence JSON (US-0078).")
+    p = argparse.ArgumentParser(description="Validate intake_evidence JSON (US-0078/US-0083).")
     p.add_argument("--file", help="Path to JSON file containing one intake_evidence object.")
     p.add_argument(
         "--stdin",

package/scripts/materialize_codebase_map.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""Idempotent codebase map bootstrap (US-0082 / DEC-0065).
+
+Writes only docs/engineering/codebase-map.md and docs/engineering/dependencies.json
+per /map-codebase contract. Does not append docs/engineering/state.md.
+
+Diagnostics on stdout use deterministic tokens: [CODEBASE_MAP_OK] ... and CODEBASE_MAP_BLOCKED:...
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+BOOTSTRAP_SENTINEL = "<!-- its-magic:codebase-map-bootstrap v1 -->"
+
+REMEDIATION = (
+    "Remediation: run `/map-codebase` for a full pass; see "
+    "`docs/engineering/runbook.md` (Codebase map bootstrap) and "
+    "`docs/engineering/architecture.md` (# US-0082)."
+)
+
+
+def _bootstrap_map_markdown() -> str:
+    lines = [
+        "# Codebase Map",
+        "",
+        BOOTSTRAP_SENTINEL,
+        "",
+        "This is a **bootstrap** codebase map created by the lifecycle materializer "
+        "(**US-0082** / **DEC-0065**). It satisfies the “map exists” contract for fresh repos.",
+        "",
+        "For a full repository analysis, run **`/map-codebase`** (explicit/manual).",
+        "",
+        "## Stack",
+        "",
+        "| Aspect | Detail |",
+        "|--------|--------|",
+        "| (pending) | Run `/map-codebase` or edit this table after local analysis |",
+        "",
+        "## Entry Points",
+        "",
+        "| Entry | File | Purpose |",
+        "|-------|------|---------|",
+        "| (pending) | — | Run `/map-codebase` to populate |",
+        "",
+        "## Next steps",
+        "",
+        "1. Run **`/map-codebase`** for a deep pass, **or**",
+        "2. Edit this file directly with project-specific structure.",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _bootstrap_dependencies_obj() -> dict:
+    return {"libraries": [], "runtime": [], "tooling": []}
+
+
+def _bootstrap_dependencies_text() -> str:
+    return json.dumps(_bootstrap_dependencies_obj(), sort_keys=True, indent=2) + "\n"
+
+
+def _normalize_newlines(text: str) -> str:
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def _json_stable(obj: object) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"))
+
+
+def sync_map(map_path: Path, desired: str) -> tuple[str, bool]:
+    """Returns (status_token, content_mutated)."""
+    if not map_path.is_file():
+        map_path.write_text(desired, encoding="utf-8", newline="\n")
+        return "created", True
+    existing = _normalize_newlines(map_path.read_text(encoding="utf-8"))
+    if BOOTSTRAP_SENTINEL in existing:
+        if existing == desired:
+            return "noop", False
+        map_path.write_text(desired, encoding="utf-8", newline="\n")
+        return "refreshed_bootstrap", True
+    return "preserved_existing", False
+
+
+def sync_dependencies(deps_path: Path, map_allows_bootstrap_deps: bool) -> tuple[str, bool]:
+    """When map_allows_bootstrap_deps, deps may be created/updated to bootstrap empty schema."""
+    desired_txt = _bootstrap_dependencies_text()
+    want_obj = _bootstrap_dependencies_obj()
+    want_stable = _json_stable(want_obj)
+
+    if not deps_path.is_file():
+        deps_path.write_text(desired_txt, encoding="utf-8", newline="\n")
+        return "deps_created", True
+
+    raw = deps_path.read_text(encoding="utf-8")
+    try:
+        cur = json.loads(raw)
+    except json.JSONDecodeError:
+        if map_allows_bootstrap_deps:
+            deps_path.write_text(desired_txt, encoding="utf-8", newline="\n")
+            return "deps_repaired", True
+        return "deps_preserved_existing", False
+
+    if _json_stable(cur) == want_stable:
+        return "deps_noop", False
+
+    if map_allows_bootstrap_deps:
+        deps_path.write_text(desired_txt, encoding="utf-8", newline="\n")
+        return "deps_refreshed", True
+    return "deps_preserved_existing", False
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Materialize idempotent codebase map bootstrap.")
+    p.add_argument("--repo", default=".", help="Repository root")
+    p.add_argument(
+        "--trigger",
+        choices=("architecture", "map-codebase", "refresh-context"),
+        default="architecture",
+        help="Lifecycle trigger label (stdout diagnostics only)",
+    )
+    p.add_argument("--dry-run", action="store_true", help="Print actions; do not write files")
+    p.add_argument(
+        "--simulate-block",
+        metavar="SUBREASON",
+        default=None,
+        help="Emit CODEBASE_MAP_BLOCKED:SUBREASON and exit 2 (tests)",
+    )
+    p.add_argument(
+        "--check-present",
+        action="store_true",
+        help="Read-only: exit 0 if codebase-map.md exists, else CODEBASE_MAP_MISSING + exit 2",
+    )
+    args = p.parse_args(argv)
+
+    if args.simulate_block:
+        print(f"[CODEBASE_MAP_BLOCKED:{args.simulate_block}] trigger={args.trigger}")
+        print(REMEDIATION)
+        return 2
+
+    if os.environ.get("CODEBASE_MAP_LIFECYCLE_SKIP", "").strip() in ("1", "true", "yes"):
+        print(f"[CODEBASE_MAP_BLOCKED:policy_skip] trigger={args.trigger}")
+        print(REMEDIATION)
+        return 2
+
+    root = Path(args.repo).resolve()
+    eng = root / "docs" / "engineering"
+    map_path = eng / "codebase-map.md"
+    deps_path = eng / "dependencies.json"
+
+    if args.check_present:
+        if map_path.is_file():
+            print(f"[CODEBASE_MAP_OK] check_present trigger={args.trigger} path={map_path}")
+            return 0
+        print("[CODEBASE_MAP_MISSING]")
+        print(REMEDIATION)
+        return 2
+
+    desired_map = _bootstrap_map_markdown()
+
+    if args.dry_run:
+        print(f"[CODEBASE_MAP_OK] dry_run trigger={args.trigger} map={map_path} deps={deps_path}")
+        return 0
+
+    eng.mkdir(parents=True, exist_ok=True)
+
+    map_status, _ = sync_map(map_path, desired_map)
+    print(f"[CODEBASE_MAP_OK] {map_status} trigger={args.trigger} path={map_path}")
+
+    map_text = _normalize_newlines(map_path.read_text(encoding="utf-8"))
+    map_allows_bootstrap_deps = BOOTSTRAP_SENTINEL in map_text
+
+    dep_status, _ = sync_dependencies(deps_path, map_allows_bootstrap_deps)
+    if dep_status not in ("deps_noop", "deps_preserved_existing"):
+        print(f"[CODEBASE_MAP_OK] {dep_status} trigger={args.trigger} path={deps_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())