its-magic 0.1.2-35 → 0.1.2-37

package/template/.cursor/commands/execute.md

@@ -59,6 +59,16 @@ Stories that harden intake persistence ship **`scripts/intake_evidence_lib.py`**
 
 Ship **`scripts/bug_issue_lib.py`**, **`scripts/bug_issue_validate.py`**, **`scripts/intake_bug_routing_guard.py`**, and **`tests/bug_issue_fixtures_test.py`** (§26L in **`tests/run-tests.ps1`** / **`tests/run-tests.sh`**). See **`docs/engineering/architecture.md`** **`# US-0079`** and **`decisions/DEC-0061.md`**.
 
+## Token-cost evidence (US-0080 / DEC-0062)
+
+When persisting token metrics for an orchestrated run: use append-only
+**`handoffs/token_cost_runs/<orchestrator_run_id>.md`** (or **`.jsonl`**) per
+**`DEC-0062`** §3; set **`token_cost_evidence_ref`** on **`docs/engineering/state.md`**
+checkpoints when rows exist. **`run_class_hash`** comparability for **AC-2** uses
+**`scripts/token_cost_lib.py`** / **`scripts/token_cost_compare.py`**; active/`template/`
+parity for listed paths: **`python scripts/check_token_cost_parity.py --repo .`**
+(§26M in **`tests/run-tests.ps1`** / **`tests/run-tests.sh`**).
+
 ## Canonical status contract (US-0045)
 
 - Story status authority is `docs/product/backlog.md` (including **`BUG-####`** under **`## Bug issues (canonical)`** per **DEC-0061**).

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