its-magic 0.1.2-9 → 0.1.3-0

package/template/docs/engineering/runtime-connectivity.md

@@ -0,0 +1,81 @@
+# Runtime Connectivity
+
+Canonical operator-facing connectivity summary for release and QA/runtime debug
+contexts.
+
+## Purpose
+
+- Show where current targets are hosted (local vs remote).
+- Provide connection instructions (domain/ip/port/protocol).
+- Provide ingress/proxy metadata (for example Traefik) when configured.
+- Preserve secret safety: never store secret values, only env-reference names.
+
+## Source of truth
+
+- `docs/engineering/release-targets.json`
+
+## Operator summary template
+
+For each enabled target include:
+
+- `target_id`
+- `target_type`
+- `execution_mode` (`local|remote`)
+- `connect_endpoint` (`protocol://domain:port` or `ip:port`)
+- `ingress` (`traefik enabled/disabled`, router, entrypoint, tls)
+- `docker_over_ssh` (enabled + context hints when configured)
+- `release_context` (latest sprint/release note ref)
+- `qa_context` (latest remote/local verification path)
+
+## Security rules
+
+- Do not write inline credentials/tokens/private keys.
+- Only env reference names are permitted in connectivity artifacts.
+- Redact auth details in handoffs and release outputs.
+
+## `*Env` variable sourcing (US-0085 / DEC-0071)
+
+Operators may populate `release-targets.json`-referenced `*Env` variables
+(such as `SSH_HOST`, `DOCKER_TOKEN`, `AWS_PROFILE`, etc.) from a sourced
+`.env` file at repository root. Values are never stored in JSON configs —
+only env-reference **names** appear in committed artifacts. See
+`docs/engineering/runbook.md` for the copy/source recipe and
+`.env.example` for the full 20-name inventory.
+
+## Dev/QA remote profiles vs `release-targets.json` (US-0084)
+
+Use this table to map **where you run tests** to the **US-0064** release/QA
+connectivity model (**no parallel schema**). Cursor/dev **`REMOTE_CONFIG`** is
+documented in the runbook; it complements, not replaces, **`release-targets.json`**.
+
+| Operator path | Maps in `release-targets.json` | Scratchpad / dev config |
+|---------------|----------------------------------|-------------------------|
+| **WSL** | Local Linux on the same machine — not a separate target row by default. | Usually **`REMOTE_EXECUTION=0`**. Cite **environment label** **`WSL`** in QA evidence. |
+| **Bare SSH Linux** | **`ssh-server`**: `hostEnv`, `userEnv`, `authEnv`, `remoteCommand`, `runtime`, ingress. | **`REMOTE_EXECUTION=1`**, **`REMOTE_CONFIG=.cursor/remote.json`** (see **`.cursor/scratchpad.md`**). |
+| **Docker-over-SSH** | **`ssh-server.dockerOverSsh`**: `dockerHostEnv`, `dockerContextEnv`, `composeFile`, `service`. | Same scratchpad keys; operator sets **`DOCKER_HOST`** / context using **env names** only in docs. |
+
+### `docker_over_ssh` (operator summary)
+
+When **`dockerOverSsh.enabled`** is true on **`ssh-server`**, connectivity flows
+through SSH to a host where Docker commands run; **`dockerHostEnv`** and
+**`dockerContextEnv`** name the operator env vars (values never pasted into
+artifacts). **`composeFile`** and **`service`** identify the stack slice. Full
+fields remain in **`docs/engineering/release-targets.json`** and **DEC-0044**.
+
+## Optional deterministic CI routing recipe (US-0086)
+
+This recipe is optional and applies only when automation routing is explicitly
+enabled.
+
+- Keep `AUTO_REMOTE_AUTOMATION_PROFILE=off` as the default in CI unless the
+  workflow intentionally opts into automation routing.
+- Use deterministic path filters to set an execution label:
+  - `docker` label for container surfaces (`Dockerfile*`, `docker-compose*.yml`,
+    container runtime scripts)
+  - `ssh` label for ssh/deploy/runtime host scripts
+  - `local` label for all other changes
+- If explicit NL intent `start container <target_id>` is provided by automation,
+  target-id resolution takes precedence over path filters.
+- Emit names-only routing evidence:
+  `target_id`, `environment_label`, `automation_profile`, `routing_source`,
+  `secret_surface=names_only`.

package/template/docs/engineering/security-review.md

@@ -0,0 +1,33 @@
+# Security Review
+
+## Review metadata
+- Timestamp:
+- Mode: design | code
+- Sprint:
+- Compliance profiles:
+
+## Findings
+
+### [Severity: critical|high|medium|low] - [Title]
+- Component:
+- Description:
+- Risk:
+- Remediation:
+- Status: open | blocking | resolved | accepted | deferred
+- Decision reference:
+
+## Blockers
+- None.
+
+## Recommended actions
+- Add prioritized remediation actions here.
+
+## Summary
+- Critical: 0
+- High: 0
+- Medium: 0
+- Low: 0
+- Overall: pass | fail
+
+> Findings are AI-guided review support and are not a compliance certification.
+> Human expert validation is recommended for production compliance decisions.

package/template/docs/engineering/spec-pack/README.md

@@ -0,0 +1,20 @@
+# Spec-pack (US-0031)
+
+When `SPEC_PACK_MODE=1` in `.cursor/scratchpad.md`, the workflow creates/updates
+three artifacts per story at these canonical paths:
+
+- `docs/engineering/spec-pack/<story_id>-design-concept.md`
+- `docs/engineering/spec-pack/<story_id>-crs.md`
+- `docs/engineering/spec-pack/<story_id>-technical-specification.md`
+
+Traceability: backlog story ID → the three paths above.
+
+Minimum required sections (see `docs/engineering/runbook.md` for validation and
+ownership):
+
+- Design Concept: Summary, Goals, Non-goals, Key decisions
+- CRS: Purpose, Scope, Acceptance criteria ref
+- Technical Specification: Overview, Components, Interfaces, Non-functional
+
+Validation blocks release only when `SPEC_PACK_MODE=1` and a required section
+is missing or empty (`SPEC_PACK_INCOMPLETE`).

package/template/docs/engineering/state-archive/README.md

@@ -0,0 +1,15 @@
+# State Archive Packs
+
+This folder stores append-only historical state packs for context compaction
+(US-0053 / DEC-0035).
+
+Policy:
+
+- Keep `docs/engineering/state.md` focused on active/hot context and recent
+  checkpoints.
+- Move older, low-frequency checkpoints into timestamped archive packs here.
+- Do not rewrite historical evidence; archive moves are non-destructive and
+  traceable.
+- Use stable pack naming:
+  - `state-pack-YYYY-QN.md` for periodic compaction
+  - or `state-pack-YYYYMMDD.md` for ad-hoc snapshots

package/template/docs/engineering/state.md

@@ -0,0 +1,20 @@
+# Engineering State
+
+## Active context surface (US-0053 / DEC-0035)
+
+- This file is the hot context surface for current phase checkpoints and
+  short-horizon traceability.
+- Archive policy: move low-frequency historical checkpoints into
+  `docs/engineering/state-archive/` packs without rewriting evidence.
+- Retrieval policy for `/ask`: prefer latest targeted sections first and expand
+  only when unresolved.
+
+## Session status
+
+## Progress snapshot
+
+## Known issues (carry-forward)
+
+## Key risks
+
+## Next actions

package/template/docs/engineering/status-normalization-report.md

@@ -0,0 +1,19 @@
+# Status Normalization Report
+
+- Baseline run date: not yet run
+- Scope: append-only status normalization evidence for stories with completed
+  release/state evidence but stale product status artifacts.
+- Canonical owner: `docs/product/backlog.md`
+- Derived views reconciled: `docs/product/acceptance.md`,
+  `docs/engineering/state.md`
+
+| Story | Prior backlog status | Prior acceptance | Resolved backlog status | Resolved acceptance | Evidence refs | Timestamp |
+|---|---|---|---|---|---|---|
+| (none yet) | - | - | - | - | - | - |
+
+## Procedure notes
+
+- This baseline is append-only; later reconciliations add delta rows only.
+- Guardrail scope is target stories only. Unrelated stories are never rewritten.
+- Contradictory reconciliation outcomes must fail safe with reason code
+  `CANONICAL_STATUS_CONFLICT` and remediation guidance.

package/template/docs/engineering/token-cost-parity-manifest.md

@@ -0,0 +1,16 @@
+# Token-cost parity manifest (DEC-0062 §5 / US-0080)
+
+- **version**: `1`
+- **purpose**: Paths below MUST be **byte-identical** between repository root and
+  `template/` after edits (installer parity). CI: `python scripts/check_token_cost_parity.py --repo .`
+
+## Mirrored path pairs (`active` → `template`)
+
+- `.cursor/commands/auto.md` → `template/.cursor/commands/auto.md`
+- `.cursor/commands/execute.md` → `template/.cursor/commands/execute.md`
+- `docs/engineering/auto-orchestration-reference.md` → `template/docs/engineering/auto-orchestration-reference.md`
+- `docs/engineering/token-cost-parity-manifest.md` → `template/docs/engineering/token-cost-parity-manifest.md`
+- `scripts/token_cost_lib.py` → `template/scripts/token_cost_lib.py`
+- `scripts/token_cost_compare.py` → `template/scripts/token_cost_compare.py`
+- `scripts/check_token_cost_parity.py` → `template/scripts/check_token_cost_parity.py`
+- `handoffs/token_cost_runs/README.md` → `template/handoffs/token_cost_runs/README.md`

package/template/docs/engineering/us-0084-remote-e2e.md

@@ -0,0 +1,44 @@
+# US-0084 — Minimal remote sanity path (Windows → WSL or SSH Linux)
+
+Sprint **S0069** / story **US-0084**. This is a short operator walkthrough; normative
+contracts live in **`docs/engineering/architecture.md`** **`# US-0084`**,
+**`docs/engineering/release-targets.json`**, and **`docs/engineering/runtime-connectivity.md`**
+(**US-0064**).
+
+## Path A — WSL (local Linux on the Windows machine)
+
+1. Install/launch **WSL** and open a Linux shell in the repo (or clone the repo inside WSL).
+2. Ensure **Node.js** and **Python 3** are available on **PATH** (same as host runbook).
+3. Run **`npm pack`** / local **`its-magic`** or **`sh installer.sh --target <repo> --mode missing --create`** from the package root.
+4. Run **`python tests/installer_shell_bug0004_test.py`** and your stack’s **`TEST_COMMAND`** (from merged runbook / scratchpad).
+5. Evidence: set **environment label** **`WSL`** in QA handoffs; **`REMOTE_EXECUTION=0`** is typical (no **`.cursor/remote.json`** validation required).
+
+## Path B — SSH to a Linux host
+
+1. SSH into the Linux machine; clone or sync the repo there.
+2. Copy **`.env.example`** to **`.env`** and fill in values for `SSH_HOST`,
+   `SSH_USER`, `SSH_PRIVATE_KEY`, and any other relevant `REMOTE_*` vars.
+   Source the file (`source .env` or equivalent) before running remote ops.
+   See **`docs/engineering/runbook.md`** § Operator `.env` setup.
+3. Run the same **`sh`/`dash`** installer and **`python`** tests as on native Linux.
+4. For **release/QA connectivity** semantics, align with **`ssh-server`** in
+   **`docs/engineering/release-targets.json`** (`hostEnv`, `userEnv`, `authEnv`, …).
+5. For **Cursor/dev remote** validation, set **`REMOTE_EXECUTION=1`** and
+   **`REMOTE_CONFIG=.cursor/remote.json`** on the merged scratchpad; run
+   **`python scripts/remote_config_summary.py`** — stdout must list **names only**
+   (no keys/passwords).
+6. Evidence: cite **`ssh:<hostEnv>`** (the **env var name**, not the host value) plus
+   **environment label**; never paste private key material.
+
+## Path C — Docker-over-SSH
+
+1. Follow **Path B** on the SSH host (including **`.env`** setup from
+   **`.env.example`**); enable **`dockerOverSsh`** patterns per
+   **`runtime-connectivity.md`** (**`dockerHostEnv`**, **`dockerContextEnv`**, **`composeFile`**, **`service`**).
+2. Ensure **`DOCKER_HOST`** and **`DOCKER_CONTEXT`** are set in your **`.env`**;
+   source before running Docker commands. Document **env names** only in handoffs.
+
+## Related
+
+- **`tests/run-tests.sh`** / **`tests/run-tests.ps1`** — **H1–H5** (**US-0084** / AC-10).
+- **`python scripts/guard_installer_publish.py`** — publish-time LF + POSIX guard.

package/template/docs/product/acceptance.md

@@ -0,0 +1 @@
+# Acceptance

package/template/docs/product/backlog.md

@@ -0,0 +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.

package/template/docs/product/vision.md

@@ -0,0 +1,11 @@
+# Vision
+
+## Problem
+
+## Audience
+
+## Value
+
+## Look and Feel
+
+## UX References

package/template/docs/user-guides/README.md

@@ -0,0 +1,40 @@
+# User guides (US-0032)
+
+When `USER_GUIDE_MODE=1` in `.cursor/scratchpad.md`, the workflow expects one
+end-user how-to guide per feature story at a canonical path.
+
+## Canonical location and naming
+
+- **Path**: `docs/user-guides/US-xxxx.md`
+- **Naming**: Use the backlog story ID (e.g. `US-0032`) as the filename.
+- One guide per feature story; create or update when the story is in scope.
+
+## Minimum required schema
+
+Each guide must include the following sections (structural validation; content
+quality is not enforced by the gate):
+
+| Section | Description |
+|--------|-------------|
+| Purpose | What the feature is for and who it is for |
+| Prerequisites | What the user needs before following the guide |
+| Usage steps | Step-by-step how-to |
+| Example | Concrete example(s) |
+| Limitations | Known limits or caveats |
+| Troubleshooting | Common issues and fixes |
+
+Validation runs only when `USER_GUIDE_MODE=1`. Missing file or missing/empty
+required section blocks release with reason code `USER_GUIDE_INCOMPLETE`.
+
+## Boundary with spec-pack (US-0031)
+
+- **User guides**: End-user facing; how-to and usage only.
+- **Spec-pack**: Design Concept, CRS, Technical Specification (engineering/design).
+- Do not duplicate spec-pack content in user guides; guides may reference
+  technical docs but remain end-user focused.
+
+## Traceability
+
+Story ID → user guide artifact is 1:1. Handoffs and release context should
+reference `docs/user-guides/US-xxxx.md` for the target story when user-guide
+mode is enabled.

package/{handoffs → template/handoffs}/dev_to_qa.md

@@ -1,8 +1,5 @@
 # Dev -> QA Handoff
 
 ## Summary
-- ...
 
 ## Test focus
-- ...
-

package/{handoffs → template/handoffs}/po_to_tl.md

@@ -1,8 +1,5 @@
 # PO -> TL Handoff
 
 ## Summary
-- ...
 
 ## Open questions
-- ...
-

package/{handoffs → template/handoffs}/qa_to_dev.md

@@ -1,6 +1,5 @@
 # QA -> Dev Handoff
+
 ## Findings
-- ...
 
 ## Required fixes
-- ...

package/template/handoffs/release_notes.md

@@ -0,0 +1,51 @@
+# Release Notes (Legacy Compatibility Pointer)
+
+This file remains backward-compatible for workflows that read
+`handoffs/release_notes.md` as the latest release summary.
+
+Canonical sprint history now lives under:
+- `handoffs/releases/Sxxxx-release-notes.md`
+
+Canonical queue state now lives under:
+- `handoffs/release_queue.md`
+
+---
+
+## Latest finalized release pointer
+
+- **Latest released sprint:** `Sxxxx`
+- **Latest canonical notes:** `handoffs/releases/Sxxxx-release-notes.md`
+- **Latest release date:** YYYY-MM-DD
+- **Latest release story:** US-xxxx
+
+## Unreleased queue visibility
+
+Check `handoffs/release_queue.md` for all pending entries where `status=unreleased`
+or `status=blocked` before finalization.
+
+## Latest operator summary (Run/Connect/Verify)
+
+- **Start command:** Refer to `## Run` in
+  `handoffs/releases/Sxxxx-release-notes.md`.
+- **Endpoint + port:** Refer to `## Connect` in
+  `handoffs/releases/Sxxxx-release-notes.md`.
+- **Verification steps + health signal:** Refer to `## Verify` in
+  `handoffs/releases/Sxxxx-release-notes.md`.
+- **Credentials source refs (sanitized):** Refer to `## Credentials` in
+  `handoffs/releases/Sxxxx-release-notes.md` (env-ref only).
+- **Known issues:** Refer to `## Known Issues` in
+  `handoffs/releases/Sxxxx-release-notes.md`.
+
+## Historical references
+
+- `Sxxxx`: `handoffs/releases/Sxxxx-release-notes.md`
+
+---
+
+## Compatibility behavior contract
+
+- Keep this file as a pointer/summary; do not treat it as canonical historical
+  storage.
+- `/release` must update sprint-scoped notes first, then refresh this pointer.
+- Never delete or destructively rewrite historical sprint-scoped note files
+  through this legacy path.

package/template/handoffs/release_queue.md

@@ -0,0 +1,47 @@
+# Release Queue Tracker
+
+Canonical release queue for sprint-level release state.
+
+## Queue rows
+
+| sprint_id | story_refs | status | last_updated | release_notes_ref | gate_snapshot | release_version | remediation |
+|-----------|------------|--------|--------------|-------------------|---------------|-----------------|-------------|
+
+## Status model
+
+- `planned`: sprint exists, release flow not entered
+- `ready`: verify-work completed and release is eligible to start
+- `unreleased`: release flow entered; notes written; finalization not completed
+- `released`: release finalization completed for the sprint
+- `blocked`: deterministic fail-safe condition requiring remediation
+
+## Deterministic transition contract
+
+- Allowed lifecycle: `planned -> ready -> unreleased -> released`.
+- `blocked` can be set on deterministic failure conditions.
+- Only the target sprint row may change during one `/release` run.
+- No destructive auto-reconciliation is allowed by default.
+
+## Fail-safe reason codes
+
+- `RELEASE_SPRINT_UNRESOLVED`
+- `LEGACY_NOTES_SPRINT_UNRESOLVED`
+- `QUEUE_ENTRY_MISSING`
+- `NOTES_REF_MISSING`
+- `STATUS_TRANSITION_INVALID`
+- `BACKLOG_STATUS_DRIFT`
+- `CANONICAL_STATUS_CONFLICT`
+- `COMPATIBILITY_CRITICAL_OPEN`
+- `COMPONENT_SCOPE_VIOLATION_UNAPPROVED`
+
+## Remediation guidance
+
+- `RELEASE_SPRINT_UNRESOLVED`: set explicit sprint context (`Sxxxx`) and rerun `/release`.
+- `LEGACY_NOTES_SPRINT_UNRESOLVED`: preserve legacy notes, identify sprint manually, then create target sprint notes file.
+- `QUEUE_ENTRY_MISSING`: create the target sprint queue row with required fields, then rerun `/release`.
+- `NOTES_REF_MISSING`: add canonical `release_notes_ref` for target sprint row and rerun `/release`.
+- `STATUS_TRANSITION_INVALID`: correct row status to a valid predecessor state and rerun `/release`.
+- `BACKLOG_STATUS_DRIFT`: reconcile target story status/ACs in `docs/product/backlog.md` using release evidence, then rerun `/release`.
+- `CANONICAL_STATUS_CONFLICT`: resolve canonical backlog status mismatch versus derived artifacts and rerun `/release`.
+- `COMPATIBILITY_CRITICAL_OPEN`: resolve or explicitly decide on open critical compatibility findings before rerun.
+- `COMPONENT_SCOPE_VIOLATION_UNAPPROVED`: resolve or explicitly approve out-of-scope component impact before rerun.

package/template/handoffs/release_to_dev.md

@@ -0,0 +1,31 @@
+# Release -> Dev Handoff
+
+## Status
+
+- Result: BLOCKED
+- Sprint: `Sxxxx`
+- Story: `US-xxxx`
+
+## Blocking reason
+
+- Primary reason code: `RELEASE_TEST_FAILED|RELEASE_QA_BLOCKERS_OPEN|RELEASE_UAT_INCOMPLETE|RELEASE_SPRINT_UNRESOLVED|QUEUE_ENTRY_MISSING|NOTES_REF_MISSING|STATUS_TRANSITION_INVALID|LEGACY_NOTES_SPRINT_UNRESOLVED`
+- Summary:
+
+## Evidence refs
+
+- `sprints/Sxxxx/release-findings.md`
+- `handoffs/release_queue.md`
+- `tests/report.md`
+- `sprints/Sxxxx/qa-findings.md`
+- `sprints/Sxxxx/uat.json`
+
+## Required remediation
+
+1. 
+2. 
+
+## Re-run criteria
+
+- Update `sprints/Sxxxx/release-findings.md` with remediation status.
+- Confirm blocking reason code is resolved.
+- Re-run `/release` for sprint `Sxxxx`.

package/template/handoffs/releases/Sxxxx-release-notes.md

@@ -0,0 +1,62 @@
+# Sprint Release Notes Template
+
+**Sprint:** Sxxxx  
+**Date:** YYYY-MM-DD  
+**Stories:** US-xxxx  
+**Queue status:** unreleased|released|blocked
+
+---
+
+## Gate results
+
+1. **Check-in test gate:** PASS|FAIL
+2. **QA completion gate:** PASS|FAIL
+3. **UAT completeness gate:** PASS|FAIL
+4. **Release finalization gate:** PASS|FAIL
+
+---
+
+## Run
+
+- `start_command`: `<required>`
+- `runtime_mode`: `local|remote` (required)
+- `runtime_context_ref`: `docs/engineering/runtime-connectivity.md` (required
+  when present)
+
+## Connect
+
+- `service_url`: `<required>`
+- `service_port`: `<required>`
+- `health_endpoint`: `<required>`
+
+## Verify
+
+- `verification_steps`:
+  1. `<required step 1>`
+  2. `<required step 2>`
+  3. `<required step 3>`
+- `expected_health_signal`: `<required>`
+
+## Credentials
+
+- `credential_source_refs` (env names only):
+  - `<ENV_VAR_NAME>`
+- `expected_value_source`:
+  - `<CI secret store | operator shell profile | deployment platform variable set>`
+- Never place inline secrets/tokens/passwords in this file.
+
+## Known Issues
+
+- `None` or deterministic concise issue list.
+
+## Notes
+
+- Sprint-scoped notes are canonical history artifacts.
+- Do not overwrite notes for non-target sprints.
+- Required section order is deterministic:
+  `Run -> Connect -> Verify -> Credentials -> Known Issues`.
+
+## Queue linkage
+
+- `release_queue.md` row must reference this file via `release_notes_ref`.
+- Status transitions must affect only the target sprint row.

package/template/handoffs/releases/vX.Y.Z-release-notes.md.example

@@ -0,0 +1,21 @@
+# Per-version release notes — pattern example (US-0100 / DEC-0085)
+
+> **Rename at use**: copy this file to `handoffs/releases/{semver}-release-notes.md`
+> where `{semver}` is the normalized semver stem **without** a leading `v`
+> (e.g. `0.1.2-41-release-notes.md`, not `v0.1.2-41-release-notes.md`).
+>
+> **Do not overwrite** unrelated version files — target only the semver you are publishing.
+> Sprint-scoped workflow evidence stays in `handoffs/releases/Sxxxx-release-notes.md`
+> (**US-0040**); never pass `Sxxxx` notes to `gh -F`.
+
+## Work items
+
+- **US-xxxx** — One-line summary derived from sprint notes / backlog / queue precedence.
+- **BUG-xxxx** — One-line fix summary (category **Fixed** in cumulative `CHANGELOG.md`).
+
+## Sprint evidence
+
+- [`S0070`](handoffs/releases/S0070-release-notes.md)
+- [`S0071`](handoffs/releases/S0071-release-notes.md)
+
+<!-- Example coalesce: S0070 + S0071 → semver 0.1.2-41 -->

package/template/handoffs/resume_brief.md

@@ -0,0 +1,14 @@
+# Resume Brief
+
+## Current status
+
+## Next actions
+
+## Intended resume phase
+
+`intake`
+
+## Isolation provenance (US-0048 / DEC-0029)
+
+- isolation_provenance_ref=
+- resume_requires_fresh_context=1

package/{handoffs → template/handoffs}/tl_to_dev.md

@@ -1,7 +1,5 @@
 # TL -> Dev Handoff
 
 ## Summary
-- ...
 
 ## Tasks
-- ...

package/template/handoffs/token_cost_runs/README.md

@@ -0,0 +1,26 @@
+# Token-cost run evidence (`handoffs/token_cost_runs/`)
+
+Append-only artifacts per **`orchestrator_run_id`** (**`DEC-0062`** §3, **`US-0080`**).
+
+## Schema (markdown table)
+
+Each run file SHOULD include:
+
+- `orchestrator_run_id` — stable id for the orchestrated run
+- `run_class_hash` — SHA-256 hex over canonical **`DEC-0062`** §2 JSON object
+- `metric_source` — how numbers were produced (for example `cursor_usage_export`,
+  `fixture`, `unmapped_host`)
+- `recorded_at_utc` — RFC3339 UTC
+- **Run totals** row: `cache_read_tokens`, `input_tokens`, `output_tokens`, and
+  optional `cache_creation_tokens`, `orchestrator_call_estimate`
+- **Per-phase** rows: same metrics plus `phase_id`, `phase_call_count`
+
+`docs/engineering/state.md` checkpoints SHOULD set **`token_cost_evidence_ref`**
+to the primary file path when metrics exist.
+
+## Tooling
+
+- `scripts/token_cost_lib.py` — `run_class_hash`, strict-proof hash helper, AC-2 compare
+- `scripts/token_cost_compare.py <baseline.json> <target.json>` — exit **0** if
+  same `run_class_hash` and ≥ **50%** `cache_read_tokens` reduction vs baseline
+- `python scripts/check_token_cost_parity.py --repo .` — active/`template/` parity

package/template/its_magic/.its-magic-version

@@ -0,0 +1 @@
+0.1.2-26

package/template/its_magic/README.md

@@ -0,0 +1,9 @@
+# its-magic metadata home
+
+This directory is installer-owned and stores framework metadata surfaces that are
+not part of product/project artifacts.
+
+Current metadata:
+
+- `.its-magic-version` (installed framework version marker)
+- this operator-oriented README surface