its-magic 0.1.2-36 → 0.1.2-38

package/README.md

@@ -367,6 +367,7 @@ deterministic **`intake_evidence`** gate — **`topic_coverage`** with valid **`
 asked-vs-covered alignment, and **`assumption_confirmation_ref`** when assumptions are affirmative.
 
 - Run `python scripts/intake_evidence_validate.py --self-test` (also exercised via `tests/run-tests.*` §26k).
+- **Packaged installs (BUG-0001 / DEC-0063)**: the intake gate modules (`intake_evidence_validate.py`, `intake_evidence_lib.py`, `intake_bug_routing_guard.py`) ship under **`template/scripts/`** and hydrate consumer repos at **`scripts/`** (npm **`files`**, Chocolatey/Homebrew **`template/`** tree, **`installer.ps1` / `installer.sh`** + **`installer-owned-paths.manifest`**). **`--mode upgrade`** treats them as framework files (added/updated like other shipped scripts). CI parity: **`python scripts/check_intake_template_parity.py --repo .`** (`tests/run-tests.*` §26N).
 - Operator docs: **`decisions/DEC-0060.md`**, **`docs/engineering/architecture.md`** **`# US-0078`**, runbook section **Interactive intake evidence validation (US-0078 / DEC-0060)**.
 - **Guided** and **low-touch** share the **same pre-persistence validation pipeline**; low-touch does not bypass mandatory pack coverage.
 

package/installer.ps1

@@ -405,6 +405,24 @@ function Invoke-ScratchpadPostinstall {
   if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 }
 
+function Invoke-InstallCompletenessValidation {
+  param(
+    [string]$TargetRoot
+  )
+  $installerPy = Join-Path $scriptDir "installer.py"
+  if (-not (Test-Path $installerPy -PathType Leaf)) {
+    Write-Host "[INSTALL_COMPLETENESS_FAILED] installer.py missing next to installer.ps1."
+    exit 1
+  }
+  $py = Get-Command python -ErrorAction SilentlyContinue
+  if (-not $py) {
+    Write-Host "[INSTALL_COMPLETENESS_FAILED] PYTHON_NOT_FOUND: Python is required for deterministic installer completeness validation."
+    exit 1
+  }
+  & python $installerPy --validate-install-completeness --target $TargetRoot
+  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
 function Show-ItsMagicBanner([switch]$IncludeInstallMessage) {
   $prev = [Console]::OutputEncoding
   [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
@@ -643,6 +661,7 @@ if ($mode -eq "upgrade") {
   }
 
   Invoke-ScratchpadPostinstall -TargetRoot $targetRoot -Mode "upgrade"
+  Invoke-InstallCompletenessValidation -TargetRoot $targetRoot
 
   Write-InstalledVersion $targetRoot $appVersion
   Sync-RootReadmeToItsMagic $targetRoot | Out-Null
@@ -724,6 +743,7 @@ foreach ($rel in $files) {
 }
 
 Invoke-ScratchpadPostinstall -TargetRoot $targetRoot -Mode $mode
+Invoke-InstallCompletenessValidation -TargetRoot $targetRoot
 
 Write-InstalledVersion $targetRoot $appVersion
 Sync-RootReadmeToItsMagic $targetRoot | Out-Null

package/installer.py

@@ -11,6 +11,7 @@ from datetime import datetime
 
 REPO_URL = "https://github.com/fl0wm0ti0n/its-magic"
 MANIFEST_RELATIVE_PATH = os.path.join("docs", "engineering", "context", "installer-owned-paths.manifest")
+MANIFEST_REQUIRED_SCRIPTS_SECTION = "required_install_script_paths"
 
 
 def normalize(path):
@@ -67,12 +68,42 @@ def load_ownership_manifest(source_root, script_dir):
             continue
         install_paths = read_manifest_paths(path, "install_include_paths")
         clean_paths = read_manifest_paths(path, "clean_paths")
+        required_script_paths = read_manifest_paths(path, MANIFEST_REQUIRED_SCRIPTS_SECTION)
         if not install_paths or not clean_paths:
             raise RuntimeError(f"[INSTALL_MANIFEST_ERROR] {path} is missing required sections or entries.")
-        return install_paths, clean_paths
+        if not required_script_paths:
+            raise RuntimeError(
+                f"[INSTALL_MANIFEST_ERROR] {path} is missing [{MANIFEST_REQUIRED_SCRIPTS_SECTION}] entries."
+            )
+        return install_paths, clean_paths, required_script_paths, path
     raise RuntimeError("[INSTALL_SOURCE_ERROR] installer-owned-paths.manifest not found. Reinstall its-magic package.")
 
 
+def validate_install_completeness(target_root, source_root, required_script_paths, manifest_path):
+    missing_paths = []
+    for rel in sorted(set(required_script_paths)):
+        src = os.path.join(source_root, rel)
+        dst = os.path.join(target_root, rel)
+        if not os.path.isfile(src) or not os.path.isfile(dst):
+            missing_paths.append(rel.replace("\\", "/"))
+    if not missing_paths:
+        return True
+    print(
+        "[INSTALL_COMPLETENESS_FAILED] Required installer scripts are missing after "
+        "copy/classification invariant check."
+    )
+    for rel in missing_paths:
+        print(f"[INSTALL_REQUIRED_SCRIPT_MISSING:{rel}]")
+    print(
+        "Fix: update manifest parity and required-script inventory at "
+        f"{MANIFEST_RELATIVE_PATH} (section [{MANIFEST_REQUIRED_SCRIPTS_SECTION}]), "
+        "ensure each listed script exists in template/scripts and clean-path ownership, "
+        "then rerun installer missing/upgrade."
+    )
+    print(f"Manifest source: {manifest_path}")
+    return False
+
+
 def ensure_parent(path):
     parent = os.path.dirname(path)
     if parent and not os.path.isdir(parent):
@@ -684,6 +715,12 @@ def main():
         action="store_true",
         help=argparse.SUPPRESS,
     )
+    parser.add_argument("--source-root", help=argparse.SUPPRESS)
+    parser.add_argument(
+        "--validate-install-completeness",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
     args = parser.parse_args()
 
     if len(sys.argv) == 1 or args.help:
@@ -694,6 +731,9 @@ def main():
         print(f"its-magic v{version}")
         return 0
 
+    if args.source_root:
+        source_root = normalize(args.source_root)
+
     if args.scratchpad_postinstall:
         target_root = normalize(args.target) if args.target else normalize(".")
         mode = args.mode or "missing"
@@ -712,11 +752,31 @@ def main():
         ok = run_scratchpad_postinstall(target_root, source_root, mode, print_ok=True)
         return 0 if ok else 1
 
+    if args.validate_install_completeness:
+        target_root = normalize(args.target) if args.target else normalize(".")
+        if not os.path.isdir(target_root):
+            print(f"[INSTALL_COMPLETENESS_FAILED] target directory missing: {target_root}")
+            return 1
+        if not os.path.isdir(source_root):
+            print("[INSTALL_SOURCE_ERROR] template directory is missing. Reinstall its-magic package.")
+            return 1
+        try:
+            _install_paths, _clean_paths, required_script_paths, manifest_path = load_ownership_manifest(
+                source_root, script_dir
+            )
+        except RuntimeError as exc:
+            print(str(exc))
+            return 1
+        ok = validate_install_completeness(target_root, source_root, required_script_paths, manifest_path)
+        return 0 if ok else 1
+
     if not os.path.isdir(source_root):
         print("[INSTALL_SOURCE_ERROR] template directory is missing. Reinstall its-magic package.")
         return 1
     try:
-        include_paths, clean_paths = load_ownership_manifest(source_root, script_dir)
+        include_paths, clean_paths, required_script_paths, manifest_path = load_ownership_manifest(
+            source_root, script_dir
+        )
     except RuntimeError as exc:
         print(str(exc))
         return 1
@@ -818,6 +878,8 @@ def main():
 
         if not run_scratchpad_postinstall(target_root, source_root, "upgrade", print_ok=True):
             return 1
+        if not validate_install_completeness(target_root, source_root, required_script_paths, manifest_path):
+            return 1
 
         write_installed_version(target_root, version)
         sync_root_readme_to_its_magic(target_root)
@@ -896,6 +958,8 @@ def main():
 
     if not run_scratchpad_postinstall(target_root, source_root, mode, print_ok=True):
         return 1
+    if not validate_install_completeness(target_root, source_root, required_script_paths, manifest_path):
+        return 1
 
     write_installed_version(target_root, version)
     sync_root_readme_to_its_magic(target_root)

package/installer.sh

@@ -151,6 +151,23 @@ scratchpad_postinstall() {
   fi
 }
 
+validate_install_completeness() {
+  target_root="$1"
+  installer_py="$SCRIPT_DIR/installer.py"
+  if [ ! -f "$installer_py" ]; then
+    printf "%s\n" "[INSTALL_COMPLETENESS_FAILED] installer.py missing next to installer.sh."
+    exit 1
+  fi
+  if command -v python3 >/dev/null 2>&1; then
+    python3 "$installer_py" --validate-install-completeness --target "$target_root" || exit $?
+  elif command -v python >/dev/null 2>&1; then
+    python "$installer_py" --validate-install-completeness --target "$target_root" || exit $?
+  else
+    printf "%s\n" "[INSTALL_COMPLETENESS_FAILED] PYTHON_NOT_FOUND: Python is required for deterministic installer completeness validation."
+    exit 1
+  fi
+}
+
 classify_file() {
   rel="$1"
   case "$rel" in
@@ -535,6 +552,7 @@ if [ "$MODE" = "upgrade" ]; then
   done
 
   scratchpad_postinstall "$TARGET_ROOT" "upgrade"
+  validate_install_completeness "$TARGET_ROOT"
 
   write_installed_version "$TARGET_ROOT" "$APP_VERSION"
   sync_root_readme_to_its_magic "$TARGET_ROOT" || true
@@ -606,6 +624,7 @@ for rel in $FILES; do
 done
 
 scratchpad_postinstall "$TARGET_ROOT" "$MODE"
+validate_install_completeness "$TARGET_ROOT"
 
 write_installed_version "$TARGET_ROOT" "$APP_VERSION"
 sync_root_readme_to_its_magic "$TARGET_ROOT" || true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-36",
+  "version": "0.1.2-38",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {
@@ -12,6 +12,11 @@
     "installer.sh",
     "installer.py",
     "scripts/doc_profile_lib.py",
+    "scripts/intake_evidence_validate.py",
+    "scripts/intake_evidence_lib.py",
+    "scripts/intake_bug_routing_guard.py",
+    "scripts/check_intake_template_parity.py",
+    "scripts/materialize_codebase_map.py",
     "bin/its-magic.js",
     "bin/postinstall.js"
   ],

package/scripts/check_intake_template_parity.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Verify active vs template/scripts/ bytes match for DEC-0063 intake gate modules (BUG-0001)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Normative pairs: repo scripts/ (canonical dev) → template/scripts/ (packaged ship path).
+INTAKE_TEMPLATE_PAIRS: tuple[tuple[str, str], ...] = (
+    ("scripts/intake_evidence_validate.py", "template/scripts/intake_evidence_validate.py"),
+    ("scripts/intake_evidence_lib.py", "template/scripts/intake_evidence_lib.py"),
+    ("scripts/intake_bug_routing_guard.py", "template/scripts/intake_bug_routing_guard.py"),
+    ("scripts/check_intake_template_parity.py", "template/scripts/check_intake_template_parity.py"),
+)
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument(
+        "--repo",
+        type=Path,
+        default=Path(__file__).resolve().parent.parent,
+        help="Repository root",
+    )
+    args = p.parse_args()
+    root: Path = args.repo
+    failed = False
+    for rel_active, rel_tpl in INTAKE_TEMPLATE_PAIRS:
+        a = root / rel_active
+        t = root / rel_tpl
+        if not a.is_file() or not t.is_file():
+            print(f"[INTAKE_TEMPLATE_PARITY_ERROR] missing file: {rel_active} or {rel_tpl}")
+            failed = True
+            continue
+        ba = a.read_bytes()
+        bt = t.read_bytes()
+        if ba != bt:
+            print(
+                f"[INTAKE_TEMPLATE_PARITY_ERROR] mismatch: {rel_active} ({len(ba)}b) "
+                f"!= {rel_tpl} ({len(bt)}b)"
+            )
+            failed = True
+    if failed:
+        return 2
+    print("[INTAKE_TEMPLATE_PARITY_OK]")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/intake_bug_routing_guard.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+Fail-closed guard: defect-shaped prose must not persist as US-xxxx without bug routing (DEC-0061 §5).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+
+# Strong defect signals (deterministic heuristic — PO still must set INTAKE_WORK_ITEM_KIND or /intake bug)
+_REPRO = re.compile(
+    r"\b(steps\s+to\s+reproduce|steps_to_reproduce|repro\s+steps|reproduction\s+steps)\b",
+    re.IGNORECASE,
+)
+_DEFECT = re.compile(
+    r"\b(bug|regression|defect|crash|stack\s+trace|broken|throws\s+exception)\b",
+    re.IGNORECASE,
+)
+
+
+def prose_looks_like_defect(text: str) -> bool:
+    low = text.lower()
+    if not _DEFECT.search(low):
+        return False
+    if _REPRO.search(low):
+        return True
+    if "expected" in low and "actual" in low:
+        return True
+    return False
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(
+        description="If work item kind is story but prose looks like a defect report, fail with INTAKE_BUG_ROUTING_REQUIRED."
+    )
+    ap.add_argument("--kind", choices=("story", "bug"), required=True)
+    ap.add_argument("--file", help="Path to prose file (title+summary)")
+    ap.add_argument("--stdin", action="store_true", help="Read prose from stdin")
+    args = ap.parse_args()
+
+    if args.kind == "bug":
+        print("[INTAKE_BUG_ROUTING_OK] kind=bug")
+        return 0
+
+    if args.stdin:
+        text = sys.stdin.read()
+    elif args.file:
+        text = open(args.file, encoding="utf-8").read()
+    else:
+        print("INTAKE_BUG_ROUTING_GUARD_ERROR: provide --file or --stdin", file=sys.stderr)
+        return 2
+
+    if prose_looks_like_defect(text):
+        print(
+            "INTAKE_BUG_ROUTING_REQUIRED: defect-shaped prose with INTAKE_WORK_ITEM_KIND=story "
+            "(set INTAKE_WORK_ITEM_KIND=bug and/or use `/intake bug` per DEC-0061 §5)",
+            file=sys.stderr,
+        )
+        return 3
+    print("[INTAKE_BUG_ROUTING_OK] kind=story")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())