its-magic 0.1.2-34 → 0.1.2-36

package/README.md

@@ -360,6 +360,23 @@ Intake artifacts must persist coverage evidence fields:
 - `missing_topics`
 - `assumptions_confirmed`
 
+### Interactive intake evidence + validator (US-0078 / DEC-0060)
+
+**US-0078** closes silent persistence: every intake that mutates backlog/acceptance must pass the
+deterministic **`intake_evidence`** gate — **`topic_coverage`** with valid **`ie:`** refs,
+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).
+- 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.
+
+### Bug issues + intake routing (US-0079 / DEC-0061)
+
+Defects use **`BUG-####`** under **`docs/product/backlog.md`** **`## Bug issues (canonical)`** with **`OPEN`/`DONE`** only and minimum reproducibility fields. Intake must not silently file defect prose as **`US-xxxx`**: set merged scratchpad **`INTAKE_WORK_ITEM_KIND=bug`** and/or use **`/intake bug`**, then run **`python scripts/intake_bug_routing_guard.py --kind story --file <prose.txt>`** before story allocation when in doubt.
+
+- Validators: `python scripts/bug_issue_validate.py --self-test`; `python scripts/bug_issue_validate.py --backlog docs/product/backlog.md --check-acceptance`.
+- Operator docs: **`decisions/DEC-0061.md`**, **`docs/engineering/architecture.md`** **`# US-0079`**, runbook **Bug issues (US-0079 / DEC-0061)**.
+
 ### Optional ID namespace bootstrap (US-0052)
 
 Fresh-project ID bootstrap behavior is explicit and default-off:
@@ -413,6 +430,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-34",
+  "version": "0.1.2-36",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

package/template/.cursor/agents/po.mdc

@@ -107,4 +107,16 @@ Mandatory intake question packs (`US-0068` / `DEC-0050`):
   - `asked_topics`
   - `missing_topics`
   - `assumptions_confirmed`
+- **US-0078 / DEC-0060**: also persist **`topic_coverage`** (with valid **`ie:`** refs per row),
+  keep **`asked_topics`** aligned with covered required keys, and supply
+  **`assumption_confirmation_ref`** (+ quoted text + run/turn metadata) whenever
+  `assumptions_confirmed` is affirmative or non-placeholder. Run
+  `python scripts/intake_evidence_validate.py` on the bundle **before** backlog/acceptance writes;
+  on failure emit deterministic codes (`INTAKE_REQUIRED_TOPIC_MISSING`,
+  `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`, umbrella `INTAKE_PERSISTENCE_BLOCKED`) and **abort** writes.
+  **`INTAKE_GUIDED_MODE=0`** uses the **same** validation pipeline as guided mode.
+- **US-0079 / DEC-0061**: for **defect** work use **`INTAKE_WORK_ITEM_KIND=bug`** and/or **`/intake bug`**;
+  run **`python scripts/intake_bug_routing_guard.py`** when allocating **`US-xxxx`** for ambiguous prose;
+  persist **`BUG-####`** under **`## Bug issues (canonical)`** with required fields and validate with
+  **`python scripts/bug_issue_validate.py --check-acceptance`**.
 

package/template/.cursor/commands/ask.md

@@ -16,8 +16,8 @@ Apply narrow-read retrieval policy (US-0053):
 Preferred read order:
 1. `docs/engineering/state.md` (latest relevant checkpoint/section)
 2. `handoffs/resume_brief.md` (current continuation intent)
-3. `docs/product/backlog.md` (specific story block by `US-xxxx`)
-4. `docs/product/acceptance.md` (specific checklist rows)
+3. `docs/product/backlog.md` (specific story block by `US-xxxx` or bug block by `BUG-####` under **`## Bug issues (canonical)`**)
+4. `docs/product/acceptance.md` (specific checklist rows, including **`## Bug acceptance (canonical)`** when answering defect status)
 5. `docs/engineering/decisions.md` and `decisions/DEC-xxxx.md` (when decision detail is required)
 6. `docs/engineering/architecture.md` and `docs/engineering/runbook.md` (only if implementation/policy depth is required)
 7. `sprints/S*/progress.md` (only latest relevant sprint)
@@ -32,7 +32,7 @@ Preferred read order:
 ## Behavior rules
 - Do NOT create, modify, or delete any files.
 - Do NOT update state.md or any sprint artifacts.
-- Reference stories (US-xxxx), decisions (DEC-xxxx), and tasks (T-xxx) by ID.
+- Reference stories (**`US-xxxx`**), bug issues (**`BUG-####`**), decisions (**`DEC-xxxx`**), and tasks (**`T-xxx`**) by ID.
 - Suggest next actions but do not execute them.
 - If the question reveals a bug or feature idea, suggest running `/intake`.