its-magic 0.1.2-35 → 0.1.2-37

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.
 
@@ -430,6 +431,20 @@ Compaction behavior:
   - `ARCH_HOT_MAX_STORY_SECTIONS` (default `120`)
   Triad hot surfaces (`state.md`, `handoffs/po_to_tl.md`,
   `docs/engineering/architecture.md`) must stay within merged scratchpad caps.
+
+### Token-cost measurement and low-cache patterns (US-0080 / DEC-0062)
+
+- Prefer **fresh subagent/chat boundaries** per `/auto` phase spawn (see `.cursor/commands/auto.md`).
+- Use explicit **`/auto start-from=<phase>`** when resuming so **`resolved_phase_plan`**
+  intersection stays deterministic (**`DEC-0052`**).
+- Select **`TOKEN_PROFILE=lean`** when compatible with your work to reduce scratchpad-driven
+  breadth; mandatory gates (**`US-0048`**, **`US-0056`**, **`US-0069`**, **`US-0039`**) stay on.
+- **Comparable** cache-read baselines require identical **`run_class_hash`**; otherwise
+  **`TOKEN_COST_RUN_CLASS_MISMATCH`** (no cross-plan gaming).
+- Committed metrics: **`handoffs/token_cost_runs/<orchestrator_run_id>.md`**; link from
+  **`docs/engineering/state.md`** via **`token_cost_evidence_ref`**.
+- Tooling: **`scripts/token_cost_lib.py`**, **`scripts/token_cost_compare.py`**,
+  **`python scripts/check_token_cost_parity.py --repo .`**.
   Use `python scripts/enforce-triad-hot-surface.py --check` before completing a
   phase that mutates them; use `--rollover` to archive oldest material into
   deterministic packs when over cap (DEC-0054).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-35",
+  "version": "0.1.2-37",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {
@@ -12,6 +12,10 @@
     "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",
     "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())

package/scripts/intake_evidence_lib.py

@@ -0,0 +1,399 @@
+"""
+Deterministic intake evidence validation (US-0078 / DEC-0060 / R-0055).
+
+Consumes a logical intake_evidence bundle (dict). PO workflows MUST run this
+gate before mutating backlog/acceptance; failures are fail-closed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+IE_REF_RE = re.compile(r"^ie:([^:]+):(\d+):([0-9a-f]{16})$")
+
+PACK_REQUIRED_KEYS: dict[str, tuple[str, ...]] = {
+    "first-intake-pack": (
+        "users_problem",
+        "runtime_target_environment",
+        "language_framework_runtime",
+        "architecture_preference",
+        "ui_design_expectations",
+        "security_compliance",
+        "non_functional_priorities",
+        "scope_timeline",
+    ),
+    "small-intake-pack": (
+        "outcome_success_criteria",
+        "impacted_components",
+        "constraints_compatibility_risks",
+        "required_tests_acceptance_checks",
+        "done_definition",
+    ),
+}
+
+ASSUMPTIONS_TOPIC_KEY = "assumptions_bundle"
+
+SAFE_ASSUMPTION_LITERALS = frozenset(
+    {
+        "",
+        "(none)",
+        "none",
+        "no",
+        "false",
+        "n/a",
+        "na",
+        "n",
+    }
+)
+
+FALSE_CONFIRMATION_LITERALS = frozenset({"yes", "true", "confirmed"})
+
+
+def canonical_json_sha256_16(obj: dict[str, Any]) -> str:
+    """Sorted-key compact JSON UTF-8 → first 16 hex chars of SHA-256 (DEC-0060)."""
+    blob = json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    return hashlib.sha256(blob).hexdigest()[:16]
+
+
+def build_ie_ref(
+    intake_run_id: str,
+    turn_index: int,
+    topic_key: str,
+    satisfied_by: str,
+    quoted_user_text: str,
+) -> str:
+    """Construct ie: ref per DEC-0060 §4."""
+    payload = {
+        "intake_run_id": intake_run_id,
+        "turn_index": int(turn_index),
+        "topic_key": topic_key,
+        "satisfied_by": satisfied_by,
+        "quoted_user_text": (quoted_user_text or "").strip(),
+    }
+    digest = canonical_json_sha256_16(payload)
+    return f"ie:{intake_run_id}:{int(turn_index)}:{digest}"
+
+
+def parse_ie_ref(ref: str) -> tuple[str, int, str] | None:
+    if not ref or not isinstance(ref, str):
+        return None
+    m = IE_REF_RE.match(ref.strip())
+    if not m:
+        return None
+    return m.group(1), int(m.group(2)), m.group(3)
+
+
+def verify_ie_ref(
+    ref: str,
+    *,
+    intake_run_id: str,
+    turn_index: int,
+    topic_key: str,
+    satisfied_by: str,
+    quoted_user_text: str,
+) -> bool:
+    parsed = parse_ie_ref(ref)
+    if not parsed:
+        return False
+    prun, pturn, phash = parsed
+    if prun != intake_run_id or pturn != int(turn_index):
+        return False
+    payload = {
+        "intake_run_id": intake_run_id,
+        "turn_index": int(turn_index),
+        "topic_key": topic_key,
+        "satisfied_by": satisfied_by,
+        "quoted_user_text": (quoted_user_text or "").strip(),
+    }
+    return canonical_json_sha256_16(payload) == phash
+
+
+def _norm_assumption(s: str) -> str:
+    return (s or "").strip()
+
+
+def assumption_literal_requires_confirmation_ref(value: str) -> bool:
+    """R-0055 rules 4–5 + DEC-0060: non-placeholder confirmations need evidence."""
+    v = _norm_assumption(value)
+    if not v:
+        return False
+    low = v.lower()
+    if low in SAFE_ASSUMPTION_LITERALS:
+        return False
+    if low in FALSE_CONFIRMATION_LITERALS:
+        return True
+    # Any other non-empty narrative still implies confirmation was recorded → needs ref
+    return True
+
+
+@dataclass
+class ValidationResult:
+    ok: bool
+    primary_codes: list[str] = field(default_factory=list)
+    missing_topics: list[str] = field(default_factory=list)
+    diagnostics: list[str] = field(default_factory=list)
+
+    def add_code(self, code: str) -> None:
+        if code not in self.primary_codes:
+            self.primary_codes.append(code)
+
+
+def _topic_rows(bundle: dict[str, Any]) -> list[dict[str, Any]]:
+    raw = bundle.get("topic_coverage")
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        return []
+    out: list[dict[str, Any]] = []
+    for row in raw:
+        if isinstance(row, dict):
+            out.append(row)
+    return out
+
+
+def _asked_set(bundle: dict[str, Any]) -> set[str]:
+    at = bundle.get("asked_topics")
+    if at is None:
+        return set()
+    if isinstance(at, str):
+        parts = [p.strip() for p in at.replace("\n", ",").split(",")]
+        return {p for p in parts if p}
+    if isinstance(at, list):
+        return {str(x).strip() for x in at if str(x).strip()}
+    return set()
+
+
+def _row_run_id(bundle: dict[str, Any], row: dict[str, Any]) -> str | None:
+    v = row.get("intake_run_id")
+    if v is not None and str(v).strip():
+        return str(v).strip()
+    v2 = bundle.get("intake_run_id")
+    if v2 is not None and str(v2).strip():
+        return str(v2).strip()
+    return None
+
+
+def _row_turn(row: dict[str, Any]) -> int | None:
+    t = row.get("turn_index")
+    if t is None:
+        return None
+    try:
+        return int(t)
+    except (TypeError, ValueError):
+        return None
+
+
+def validate_intake_evidence(
+    bundle: dict[str, Any],
+    *,
+    intake_guided_mode: int | None = None,
+) -> ValidationResult:
+    """
+    Validate logical intake_evidence. intake_guided_mode is accepted for API parity
+    (AC-5/AC-6): validation rules do not branch on mode — same pipeline for {0,1}.
+    """
+    _ = intake_guided_mode  # explicit no-op for parity contract
+    res = ValidationResult(ok=True)
+
+    pack = (bundle.get("selected_pack") or "").strip()
+    if pack not in PACK_REQUIRED_KEYS:
+        res.ok = False
+        res.add_code("INTAKE_REQUIRED_PACK_INCOMPLETE")
+        res.diagnostics.append(
+            f"Remediation: set selected_pack to one of {sorted(PACK_REQUIRED_KEYS.keys())!r}; "
+            f"unknown or empty pack is not allowed before persistence."
+        )
+        res.add_code("INTAKE_PERSISTENCE_BLOCKED")
+        return res
+
+    required = list(PACK_REQUIRED_KEYS[pack])
+    rows = _topic_rows(bundle)
+    by_key: dict[str, dict[str, Any]] = {}
+    for row in rows:
+        k = (row.get("topic_key") or "").strip()
+        if k:
+            by_key[k] = row
+
+    missing_cov: list[str] = []
+    for k in required:
+        row = by_key.get(k)
+        if not row:
+            missing_cov.append(k)
+            continue
+
+        ref = (row.get("ref") or "").strip()
+        sat = (row.get("satisfied_by") or "").strip()
+        qtxt = row.get("quoted_user_text")
+        if qtxt is None:
+            qtxt = ""
+        qtxt = str(qtxt)
+
+        if sat not in ("answer_ref", "assumption_confirmation_ref"):
+            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})."
+            )
+            missing_cov.append(k)
+            continue
+
+        irid = _row_run_id(bundle, row)
+        tit = _row_turn(row)
+        if irid is None or tit is None:
+            res.ok = False
+            res.diagnostics.append(
+                f"Remediation: topic {k!r} needs intake_run_id and turn_index (row or bundle) "
+                f"for ie: ref verification."
+            )
+            missing_cov.append(k)
+            continue
+
+        if not ref or not verify_ie_ref(
+            ref,
+            intake_run_id=irid,
+            turn_index=tit,
+            topic_key=k,
+            satisfied_by=sat,
+            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 missing_cov:
+        res.ok = False
+        res.missing_topics = sorted(set(missing_cov))
+        res.add_code("INTAKE_REQUIRED_TOPIC_MISSING")
+        if len(res.missing_topics) > 1:
+            res.add_code("INTAKE_REQUIRED_PACK_INCOMPLETE")
+        res.diagnostics.append(
+            "Remediation: supply complete topic_coverage with valid ie: refs for: "
+            + ", ".join(res.missing_topics)
+        )
+
+    asked = _asked_set(bundle)
+    for k in required:
+        if k not in by_key:
+            continue
+        if k not in asked:
+            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)."
+            )
+            if k not in res.missing_topics:
+                res.missing_topics.append(k)
+    res.missing_topics = sorted(set(res.missing_topics))
+
+    ac = bundle.get("assumptions_confirmed")
+    ac_str = ac if isinstance(ac, str) else ("(none)" if ac is None else str(ac))
+
+    low = _norm_assumption(ac_str).lower()
+    if low in FALSE_CONFIRMATION_LITERALS and not (bundle.get("assumption_confirmation_ref") or "").strip():
+        res.ok = False
+        res.add_code("INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED")
+        res.diagnostics.append(
+            "Remediation: literal yes/true/confirmed is rejected without "
+            "assumption_confirmation_ref (R-0055 rule 5)."
+        )
+
+    if assumption_literal_requires_confirmation_ref(ac_str):
+        aref = (bundle.get("assumption_confirmation_ref") or "").strip()
+        aquote = str(bundle.get("assumption_confirmation_quoted") or "")
+        irid = bundle.get("assumption_confirmation_intake_run_id")
+        tit = bundle.get("assumption_confirmation_turn_index")
+        if not aref or irid is None or tit is None:
+            res.ok = False
+            res.add_code("INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED")
+            res.diagnostics.append(
+                "Remediation: affirmative assumptions_confirmed requires assumption_confirmation_ref "
+                "plus assumption_confirmation_intake_run_id, assumption_confirmation_turn_index, "
+                "and assumption_confirmation_quoted for ie: binding."
+            )
+        elif not verify_ie_ref(
+            aref,
+            intake_run_id=str(irid),
+            turn_index=int(tit),
+            topic_key=ASSUMPTIONS_TOPIC_KEY,
+            satisfied_by="assumption_confirmation_ref",
+            quoted_user_text=aquote,
+        ):
+            res.ok = False
+            res.add_code("INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED")
+            res.diagnostics.append(
+                "Remediation: assumption_confirmation_ref is invalid or does not match "
+                "quoted affirmative user text / run metadata."
+            )
+
+    if not res.ok and "INTAKE_PERSISTENCE_BLOCKED" not in res.primary_codes:
+        res.add_code("INTAKE_PERSISTENCE_BLOCKED")
+
+    return res
+
+
+def format_blocked_message(result: ValidationResult) -> str:
+    lines = [
+        "INTAKE_PERSISTENCE_BLOCKED",
+        "primary_codes=" + ",".join(result.primary_codes),
+    ]
+    if result.missing_topics:
+        lines.append("missing_topics=" + ",".join(result.missing_topics))
+    lines.extend(result.diagnostics)
+    return "\n".join(lines)
+
+
+def self_test() -> None:
+    """Minimal sanity checks for --self-test / installer wiring."""
+    rid = "selftest-run"
+    ref = build_ie_ref(rid, 0, "outcome_success_criteria", "answer_ref", "ok")
+    assert parse_ie_ref(ref) is not None
+    assert verify_ie_ref(
+        ref,
+        intake_run_id=rid,
+        turn_index=0,
+        topic_key="outcome_success_criteria",
+        satisfied_by="answer_ref",
+        quoted_user_text="ok",
+    )
+    assert not verify_ie_ref(
+        ref,
+        intake_run_id=rid,
+        turn_index=0,
+        topic_key="outcome_success_criteria",
+        satisfied_by="answer_ref",
+        quoted_user_text="tampered",
+    )
+    # Mode argument must not change outcome (AC-6 / AC-5 parity)
+    small = PACK_REQUIRED_KEYS["small-intake-pack"]
+    rows = []
+    for i, key in enumerate(small):
+        rows.append(
+            {
+                "topic_key": key,
+                "satisfied_by": "answer_ref",
+                "quoted_user_text": f"a{i}",
+                "intake_run_id": rid,
+                "turn_index": i,
+                "ref": build_ie_ref(rid, i, key, "answer_ref", f"a{i}"),
+            }
+        )
+    bundle = {
+        "selected_pack": "small-intake-pack",
+        "intake_run_id": rid,
+        "asked_topics": list(small),
+        "missing_topics": [],
+        "assumptions_confirmed": "(none)",
+        "topic_coverage": rows,
+    }
+    r0 = validate_intake_evidence(bundle, intake_guided_mode=0)
+    r1 = validate_intake_evidence(bundle, intake_guided_mode=1)
+    assert r0.ok and r1.ok
+    assert r0.primary_codes == r1.primary_codes

package/scripts/intake_evidence_validate.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""
+Validate intake_evidence JSON bundles (US-0078 / DEC-0060).
+
+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).")
+    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())