its-magic 0.1.2-9 → 0.1.3-0

package/template/scripts/intake_evidence_validate.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""
+Validate intake_evidence JSON bundles (US-0078 / US-0083 / DEC-0060 / DEC-0067).
+
+Used by PO workflow preflight and CI fixtures.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.normpath(os.path.join(_SCRIPT_DIR, ".."))
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import intake_evidence_lib  # noqa: E402
+
+
+def main() -> int:
+    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",
+        action="store_true",
+        help="Read JSON object from stdin.",
+    )
+    p.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Run library sanity checks and exit.",
+    )
+    args = p.parse_args()
+
+    if args.self_test:
+        intake_evidence_lib.self_test()
+        print("[INTAKE_EVIDENCE_SELF_TEST_OK]")
+        return 0
+
+    raw = ""
+    if args.file:
+        with open(os.path.abspath(args.file), encoding="utf-8") as f:
+            raw = f.read()
+    elif args.stdin:
+        raw = sys.stdin.read()
+    else:
+        print("error: specify --file, --stdin, or --self-test", file=sys.stderr)
+        return 2
+
+    try:
+        bundle = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"error: invalid JSON: {e}", file=sys.stderr)
+        return 2
+
+    if not isinstance(bundle, dict):
+        print("error: root must be a JSON object", file=sys.stderr)
+        return 2
+
+    r = intake_evidence_lib.validate_intake_evidence(bundle)
+    if r.ok:
+        print("[INTAKE_EVIDENCE_VALIDATION_OK]")
+        return 0
+
+    print(intake_evidence_lib.format_blocked_message(r), file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/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())

package/template/scripts/pack_json_validate.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Validate work/<story_id>/pack.json schema v1 (US-0096 / DEC-0082)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+REQUIRED_FIELDS = (
+    "schema_version",
+    "story_id",
+    "delivery_mode",
+    "status",
+    "ac",
+    "tasks",
+    "refs",
+    "deltas",
+    "memory_layer",
+)
+
+VALID_DELIVERY_MODES = frozenset({"standard", "ultra_lean", "mega_quick"})
+VALID_MEMORY_LAYER = "pack"
+
+
+def validate_pack(data: Any, *, expected_story_id: str | None = None) -> list[str]:
+    """Return PACK_* reason codes; empty list means valid."""
+    codes: list[str] = []
+    if not isinstance(data, dict):
+        return ["PACK_INVALID_ROOT"]
+
+    for field in REQUIRED_FIELDS:
+        if field not in data:
+            codes.append(f"PACK_MISSING_REQUIRED_FIELD:{field}")
+
+    if codes:
+        return codes
+
+    if data.get("schema_version") != "1":
+        codes.append("PACK_SCHEMA_VERSION_INVALID")
+
+    story_id = data.get("story_id")
+    if not isinstance(story_id, str) or not story_id.strip():
+        codes.append("PACK_STORY_ID_INVALID")
+    elif expected_story_id and story_id != expected_story_id:
+        codes.append("PACK_STORY_ID_MISMATCH")
+
+    delivery_mode = data.get("delivery_mode")
+    if delivery_mode not in VALID_DELIVERY_MODES:
+        codes.append("PACK_DELIVERY_MODE_INVALID")
+
+    if not isinstance(data.get("status"), str) or not str(data["status"]).strip():
+        codes.append("PACK_STATUS_INVALID")
+
+    for list_field in ("ac", "tasks", "refs", "deltas"):
+        if not isinstance(data.get(list_field), list):
+            codes.append(f"PACK_INVALID_FIELD_TYPE:{list_field}")
+
+    if data.get("memory_layer") != VALID_MEMORY_LAYER:
+        codes.append("PACK_MEMORY_LAYER_INVALID")
+
+    return codes
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Validate pack.json schema v1 (US-0096).")
+    p.add_argument("--file", type=Path, help="Path to pack.json")
+    p.add_argument(
+        "--story-id",
+        help="Expected story_id (e.g. US-0096); mismatch → PACK_STORY_ID_MISMATCH",
+    )
+    p.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Run built-in fixture checks and exit.",
+    )
+    args = p.parse_args()
+
+    if args.self_test:
+        valid = {
+            "schema_version": "1",
+            "story_id": "US-0096",
+            "delivery_mode": "ultra_lean",
+            "status": "OPEN",
+            "ac": ["AC-1"],
+            "tasks": [{"id": "T-001", "status": "pending"}],
+            "refs": ["decisions/DEC-0082.md"],
+            "deltas": [],
+            "memory_layer": "pack",
+        }
+        if validate_pack(valid):
+            print("PACK_SELF_TEST_FAIL: valid fixture rejected", file=sys.stderr)
+            return 1
+        invalid = dict(valid)
+        del invalid["story_id"]
+        if "PACK_MISSING_REQUIRED_FIELD:story_id" not in validate_pack(invalid):
+            print("PACK_SELF_TEST_FAIL: missing field not detected", file=sys.stderr)
+            return 1
+        print("[PACK_JSON_SELF_TEST_OK]")
+        return 0
+
+    if not args.file:
+        print("error: specify --file or --self-test", file=sys.stderr)
+        return 2
+
+    path = args.file.resolve()
+    if not path.is_file():
+        print(f"PACK_FILE_NOT_FOUND: {path}", file=sys.stderr)
+        return 2
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"PACK_INVALID_JSON: {exc}", file=sys.stderr)
+        return 1
+
+    codes = validate_pack(data, expected_story_id=args.story_id)
+    if codes:
+        for code in codes:
+            print(code, file=sys.stderr)
+        return 1
+
+    print("[PACK_JSON_VALIDATION_OK]")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())