its-magic 0.1.2-34 → 0.1.2-35

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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-34",
+  "version": "0.1.2-35",
   "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`.
 

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

@@ -48,9 +48,20 @@ as stale isolation evidence).
 
 Release gate semantics (US-0039): mandatory gates (check-in test, QA, UAT) and no-bypass/override contract are enforced at `/release`; see `.cursor/commands/release.md` and `.cursor/commands/qa.md`.
 
+## Intake evidence tooling reference (US-0078 / DEC-0060)
+
+Stories that harden intake persistence ship **`scripts/intake_evidence_lib.py`**,
+**`scripts/intake_evidence_validate.py`**, and **`tests/intake_evidence_fixtures_test.py`**
+(invoked from **`tests/run-tests.ps1`** / **`tests/run-tests.sh`** §26k). See
+**`docs/engineering/architecture.md`** **`# US-0078`** and **`decisions/DEC-0060.md`**.
+
+## Bug issue tooling reference (US-0079 / DEC-0061)
+
+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`**.
+
 ## Canonical status contract (US-0045)
 
-- Story status authority is `docs/product/backlog.md`.
+- Story status authority is `docs/product/backlog.md` (including **`BUG-####`** under **`## Bug issues (canonical)`** per **DEC-0061**).
 - `docs/product/acceptance.md` and `docs/engineering/state.md` are derived and
   must not be treated as canonical readiness sources when contradictory.
 - `/execute` must not start/continue implementation solely based on

package/template/.cursor/commands/intake.md

@@ -83,6 +83,43 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
   - `missing_topics`
   - `assumptions_confirmed`
 
+## Interactive intake evidence gate (US-0078 / DEC-0060 / R-0055)
+
+Machine-verifiable **`intake_evidence`** extends **DEC-0050** literals with
+**`topic_coverage`** (one row per required pack key), canonical **`ie:`** refs,
+and assumption binding. **Do not** mutate `docs/product/backlog.md` or
+`docs/product/acceptance.md` until validation **PASS**es.
+
+- Bundle minimum (logical shape — serialize inline in handoff/backlog notes or JSON sidecar):
+  - `selected_pack`, `asked_topics`, `missing_topics`, `assumptions_confirmed`
+  - `topic_coverage[]`: `topic_key`, `satisfied_by` (`answer_ref` \| `assumption_confirmation_ref`),
+    `ref` (**`ie:`** per **DEC-0060**), `quoted_user_text`, per-row `intake_run_id` / `turn_index`
+    (or bundle-level `intake_run_id` shared by rows)
+  - Affirmative / non-placeholder `assumptions_confirmed`: `assumption_confirmation_ref`,
+    `assumption_confirmation_intake_run_id`, `assumption_confirmation_turn_index`,
+    `assumption_confirmation_quoted`
+- Validator (fail-closed; preserves primary sub-codes under umbrella **`INTAKE_PERSISTENCE_BLOCKED`**):
+  - `python scripts/intake_evidence_validate.py --self-test`
+  - `python scripts/intake_evidence_validate.py --file <bundle.json>` or `--stdin`
+- Deterministic diagnostics (**AC-7**): on block, list `missing_topics`, cite reason codes, and emit
+  remediation prompts for unresolved required keys only.
+- **Guided vs low-touch parity**: **`INTAKE_GUIDED_MODE=1`** and **`INTAKE_GUIDED_MODE=0`** run the
+  **same pre-persistence validation pipeline**; low-touch may skip optional follow-ups but **must not**
+  bypass mandatory pack evidence (**AC-5**, **AC-6**).
+- **Grandfathering**: legacy intake rows remain valid for read/display; the **next** intake-driven
+  mutation must supply full **US-0078** evidence or the write is blocked (**DEC-0060** §5).
+
+## Bug issue routing (US-0079 / DEC-0061)
+
+- **Work item kind** (merged scratchpad per **DEC-0055**): **`INTAKE_WORK_ITEM_KIND=story`** (default) or **`INTAKE_WORK_ITEM_KIND=bug`**.
+- **Explicit argv**: when the operator invokes **`/intake bug`** (bug mode for this run), treat **`INTAKE_WORK_ITEM_KIND`** as **`bug`** for routing even if scratchpad defaults to story (command wins for the session).
+- **No silent US allocation for defects**: before creating a **`US-xxxx`** for **defect-shaped** input while in **story** kind, run **`python scripts/intake_bug_routing_guard.py --kind story --file <condensed-prose.txt>`** (or **`--stdin`**). Exit **3** → **`INTAKE_BUG_ROUTING_REQUIRED`** — **abort** backlog/acceptance mutation; remediation: set **`INTAKE_WORK_ITEM_KIND=bug`** and/or re-run as **`/intake bug`**, collect minimum bug fields, then allocate **`BUG-####`**.
+- **Bug persistence** (after **US-0078** evidence still passes for narrative packs when applicable):
+  - Next id: **`python scripts/bug_issue_validate.py --print-next-id`** (reads **`docs/product/backlog.md`**).
+  - Append **`### BUG-#### — Title`** under **`## Bug issues (canonical)`** with **Status**, **`environment`**, **`steps_to_reproduce`**, **`expected`**, **`actual`**, **`evidence_refs`**.
+  - Add matching **`- [ ]` / `- [x]`** row under **`## Bug acceptance (canonical)`**, sorted by id.
+  - Run **`python scripts/bug_issue_validate.py --backlog docs/product/backlog.md --check-acceptance`** before completing the handoff.
+
 ## Steps
 1. Determine intake mode from `.cursor/scratchpad.md`:
    - guided mode: `INTAKE_GUIDED_MODE=1` (default)
@@ -129,17 +166,23 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
      explicitly requests depth.
    - Keep single-story default (no forced decomposition), unless the user
      explicitly requests decomposition.
-5. Enforce mandatory question-pack coverage before persistence (US-0068):
+5. Enforce mandatory question-pack coverage before persistence (US-0068) **and**
+   interactive evidence (**US-0078 / DEC-0060**):
    - deterministically select one pack (`first-intake-pack` or
      `small-intake-pack`) and record `selected_pack`.
    - ask required questions for the selected pack; adaptive follow-ups remain
      allowed but bounded.
-   - before writing backlog/acceptance artifacts, compute required coverage:
-     - if complete, proceed to persistence;
-     - if incomplete and no explicit assumption confirmation, fail closed with
-       deterministic reason code and remediation guidance.
+   - accumulate **`topic_coverage`** rows with valid **`ie:`** refs; keep
+     `asked_topics` aligned with covered required keys (asked-vs-covered rule).
+   - before writing backlog/acceptance artifacts, run **`python scripts/intake_evidence_validate.py`**
+     on the captured bundle (or equivalent in-process validation):
+     - if validation **PASS**es, proceed to persistence;
+     - on **FAIL**, emit `INTAKE_REQUIRED_TOPIC_MISSING` /
+       `INTAKE_REQUIRED_PACK_INCOMPLETE` / `INTAKE_ASSUMPTION_CONFIRMATION_REQUIRED`
+       (and umbrella `INTAKE_PERSISTENCE_BLOCKED`) with remediation guidance — **no write**.
    - persist intake evidence fields (`asked_topics`, `missing_topics`,
-     `assumptions_confirmed`) in relevant intake artifacts.
+     `assumptions_confirmed`, `topic_coverage`, assumption ref fields per **DEC-0060**)
+     in relevant intake artifacts.
 6. Optional fresh-project ID namespace bootstrap (US-0052 / DEC-0034):
    - Read `ID_NAMESPACE_BOOTSTRAP` from `.cursor/scratchpad.md` (`0|1`,
      default `0`).

package/template/.cursor/commands/status-reconcile.md

@@ -36,9 +36,10 @@ description: "its-magic status-reconcile: deterministic status normalization and
 - Ambiguous next OPEN story / phase resolution
 
 ## Canonical precedence (US-0045 / DEC-0025)
-- Story status authority is `docs/product/backlog.md` only.
+- Story status authority is `docs/product/backlog.md` only (including **`BUG-####`** under **`## Bug issues (canonical)`** per **DEC-0061** / **US-0079**).
 - `docs/product/acceptance.md` and `docs/engineering/state.md` are derived views.
 - Reconciliation must not infer canonical story status from derived artifacts.
+- Bug portfolio drift vs **`## Bug acceptance (canonical)`** is machine-checkable: **`python scripts/bug_issue_validate.py --backlog docs/product/backlog.md --check-acceptance`** (**`BUG_RECONCILE_ACCEPTANCE_*`** codes).
 
 ## Deterministic detection matrix
 1. Backlog story `Status: DONE` with unchecked AC checkboxes.

package/template/.cursor/rules/core.mdc

@@ -3,6 +3,12 @@ description: "Core workflow and context pack rules"
 globs: ["**/*"]
 ---
 
+- Intake backlog/acceptance writes require **US-0078** evidence validation
+  (`scripts/intake_evidence_validate.py` / **DEC-0060**) before persistence; see
+  `.cursor/commands/intake.md`.
+- Defect intake uses **`INTAKE_WORK_ITEM_KIND=bug`** and/or **`/intake bug`**; validate bugs with
+  `scripts/bug_issue_validate.py` and run `scripts/intake_bug_routing_guard.py` before allocating
+  **`US-xxxx`** for defect-shaped prose (**US-0079** / **DEC-0061**).
 - Use the phase flow: intake -> discovery -> research -> architecture ->
   [security-review: design, if SECURITY_REVIEW=1] -> sprint plan -> plan verify
   -> execute -> [security-review: code, if SECURITY_REVIEW=1] -> QA ->

package/template/.cursor/scratchpad.local.example.md

@@ -124,6 +124,7 @@ AUTO_PUSH_BRANCH_ALLOWLIST=
 # - INTAKE_GUIDED_MODE: 0|1 (guided intake follow-up/options/research behavior)
 # - INTAKE_SUBAGENT_FALLBACK: deny|allow (deny by default; when deny, missing
 #   role-specific intake subagent capability fails fast)
+# - INTAKE_WORK_ITEM_KIND: story|bug (default story; bug selects BUG-#### path per DEC-0061 / US-0079)
 # - ID_NAMESPACE_BOOTSTRAP: 0|1 (optional fresh-project ID bootstrap mode; when 1, allow first IDs to start at 0001 only if deterministic freshness checks pass)
 # - TOKEN_PROFILE: lean|balanced|full (tiered token-cost profile defaults)
 #   - lean: lowest-token default profile; reduce non-critical automation/research intensity
@@ -142,6 +143,7 @@ AUTO_PUSH_BRANCH_ALLOWLIST=
 EARLY_RESEARCH=1
 INTAKE_GUIDED_MODE=1
 INTAKE_SUBAGENT_FALLBACK=deny
+INTAKE_WORK_ITEM_KIND=story
 ID_NAMESPACE_BOOTSTRAP=0
 TOKEN_PROFILE=balanced
 STATE_HOT_MAX_LINES=1200

package/template/.cursor/scratchpad.md

@@ -124,6 +124,7 @@ AUTO_PUSH_BRANCH_ALLOWLIST=
 # - INTAKE_GUIDED_MODE: 0|1 (guided intake follow-up/options/research behavior)
 # - INTAKE_SUBAGENT_FALLBACK: deny|allow (deny by default; when deny, missing
 #   role-specific intake subagent capability fails fast)
+# - INTAKE_WORK_ITEM_KIND: story|bug (default story; bug selects BUG-#### path per DEC-0061 / US-0079)
 # - ID_NAMESPACE_BOOTSTRAP: 0|1 (optional fresh-project ID bootstrap mode; when 1, allow first IDs to start at 0001 only if deterministic freshness checks pass)
 # - TOKEN_PROFILE: lean|balanced|full (tiered token-cost profile defaults)
 #   - lean: lowest-token default profile; reduce non-critical automation/research intensity
@@ -142,6 +143,7 @@ AUTO_PUSH_BRANCH_ALLOWLIST=
 EARLY_RESEARCH=1
 INTAKE_GUIDED_MODE=1
 INTAKE_SUBAGENT_FALLBACK=deny
+INTAKE_WORK_ITEM_KIND=story
 ID_NAMESPACE_BOOTSTRAP=0
 TOKEN_PROFILE=balanced
 STATE_HOT_MAX_LINES=1200

package/template/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:

package/template/docs/engineering/runbook.md

@@ -240,6 +240,35 @@ Required persisted intake evidence fields:
 - `missing_topics`
 - `assumptions_confirmed`
 
+## Interactive intake evidence validation (US-0078 / DEC-0060)
+
+**US-0078** adds machine-verifiable **`topic_coverage`** rows, canonical **`ie:`** refs
+(**DEC-0060**), asked-vs-covered enforcement, and **`assumption_confirmation_ref`**
+binding before backlog/acceptance writes.
+
+- Validator entrypoints: `python scripts/intake_evidence_validate.py --self-test`;
+  `python scripts/intake_evidence_validate.py --file <bundle.json>` or `--stdin`.
+- Library: `scripts/intake_evidence_lib.py` (shared rules for tests and tooling).
+- Regression: `tests/intake_evidence_fixtures_test.py` (R-0055 **AC-8** matrix tiers A/B),
+  invoked from `tests/run-tests.ps1` / `tests/run-tests.sh` §26k.
+- **Guided** and **low-touch** (`INTAKE_GUIDED_MODE=0`) share the **same** pre-persistence
+  validation pipeline; mandatory pack evidence is never skipped.
+- Legacy intake evidence without **`ie:`** refs remains **grandfathered** for display until the
+  next intake-driven mutation, which must supply full evidence (**DEC-0060** §5).
+
+## Bug issues (US-0079 / DEC-0061)
+
+- **Canonical ids**: **`BUG-####`** in **`docs/product/backlog.md`** **`## Bug issues (canonical)`**; status literals **`OPEN`** | **`DONE`** only — illegal values fail **`BUG_VALIDATION_STATUS_INVALID`**.
+- **Minimum fields** (non-empty): **`environment`**, **`steps_to_reproduce`**, **`expected`**, **`actual`**, **`evidence_refs`** — missing/empty → **`BUG_VALIDATION_FIELD_EMPTY`** (or **`BUG_VALIDATION_SECTION_MISSING`** when the region is absent).
+- **Ordering**: bug blocks sorted by id ascending — violation → **`BUG_VALIDATION_ORDER_INVERSION`**.
+- **Intake routing**: merged **`INTAKE_WORK_ITEM_KIND=story|bug`** and/or explicit **`/intake bug`**; defect-shaped prose with **`story`** kind → **`INTAKE_BUG_ROUTING_REQUIRED`** via **`python scripts/intake_bug_routing_guard.py`** (**DEC-0061** §5). Mismatch/conflict → **`INTAKE_WORK_ITEM_KIND_MISMATCH`** family (documented in command surfaces).
+- **Acceptance reconciliation**: **`docs/product/acceptance.md`** **`## Bug acceptance (canonical)`** checkbox rows must match backlog bug status — drift codes **`BUG_RECONCILE_ACCEPTANCE_*`**.
+- **Commands**:
+  - `python scripts/bug_issue_validate.py --self-test`
+  - `python scripts/bug_issue_validate.py --backlog docs/product/backlog.md [--check-acceptance] [--print-next-id]`
+  - `python scripts/intake_bug_routing_guard.py --kind story|bug --file <path>` (or **`--stdin`**)
+- **Regression**: `tests/bug_issue_fixtures_test.py` (R-0056 Tier A/B), invoked from **`tests/run-tests.ps1` / `tests/run-tests.sh`** §26L.
+
 ## Optional ID namespace bootstrap (US-0052)
 
 Fresh-project ID bootstrap is optional and default-off in

package/template/docs/product/backlog.md

@@ -1 +1,5 @@
 # Backlog
+
+## Bug issues (canonical)
+
+Stub — materialized installs use the full **`## Bug issues (canonical)`** contract in **`docs/product/backlog.md`** (**US-0079** / **DEC-0061**). Append **`### BUG-#### — Title`** blocks here when tracking defects; run **`python scripts/bug_issue_validate.py`** before handoff.