its-magic 0.1.2-29 → 0.1.2-32

package/template/.cursor/scratchpad.md

@@ -14,9 +14,9 @@
 # - AUTO_PAUSE_POLICY: after_task|after_phase (safe stop boundary)
 # - DONE: 0|1 (stop hook loops)
 MAGIC_CONTEXT_STRICT=1
-LOOP_UNTIL_GREEN=0
+LOOP_UNTIL_GREEN=1
 RUN_TESTS_ON_EDIT=0
-AUTO_IMPLEMENTATION_LOOP=0
+AUTO_IMPLEMENTATION_LOOP=1
 AUTO_LOOP_MAX_CYCLES=5
 AUTO_PAUSE_REQUEST=0
 AUTO_PAUSE_POLICY=after_phase
@@ -42,9 +42,9 @@ MAGIC_BENCH_SESSION=
 # - AUTO_EXECUTE_SELECTION: planned_then_priority
 # - AUTO_TEAM_SCOPE_ENFORCE: 0|1 (when TEAM_MODE=1, enforce TEAM_MEMBER + ACTIVE_TASK_IDS)
 AUTO_FLOW_MODE=auto_until_decision
-PHASE_MODE=interactive
-PERMISSION_MODE=interactive
-AUTO_INSTALL_DEPS=0
+PHASE_MODE=auto
+PERMISSION_MODE=auto
+AUTO_INSTALL_DEPS=1
 AUTO_RELEASE_NOTES=1
 AUTO_BACKLOG_DRAIN=0
 AUTO_BACKLOG_MAX_STORIES=1
@@ -56,6 +56,31 @@ AUTO_EXECUTE_ON_BLOCK=stop
 AUTO_EXECUTE_SELECTION=planned_then_priority
 AUTO_TEAM_SCOPE_ENFORCE=1
 #
+# `/auto` phase role policy (US-0069 / DEC-0051)
+# - AUTO_ROLE_RESEARCH: po|tech-lead (empty -> default tech-lead)
+# - AUTO_ROLE_PLAN_VERIFY: qa|tech-lead (empty -> default qa)
+# - AUTO_ROLE_REFRESH_CONTEXT: curator|po (empty -> default curator)
+# - AUTO_EXECUTE_ROLE_OVERRIDE: empty or allowed_non_dev_execute (execute default is dev)
+# - EXECUTE_OVERRIDE_GOVERNANCE_REF: parseable waiver pointer (DEC-xxxx / state anchor) when override set
+AUTO_ROLE_RESEARCH=
+AUTO_ROLE_PLAN_VERIFY=
+AUTO_ROLE_REFRESH_CONTEXT=
+AUTO_EXECUTE_ROLE_OVERRIDE=
+EXECUTE_OVERRIDE_GOVERNANCE_REF=
+#
+# `/auto` phase selection policy (US-0070 / DEC-0052)
+# Exactly one active mode after merge; conflict -> PHASE_POLICY_CONFLICT (no plan).
+# - AUTO_PHASE_PLAN: unset or full (default full canonical lifecycle)
+# - AUTO_PHASE_EXCLUDE: csv of canonical phase ids (exclude from full)
+# - AUTO_PHASE_INCLUDE: csv of canonical phase ids (re-sorted to canonical order)
+# - AUTO_PHASE_PROFILE: named profile (see /auto + DEC-0052; unknown -> fail closed)
+# - AUTO_PHASE_HIGH_RISK_ACK: required token when a high-risk profile demands it
+AUTO_PHASE_PLAN=
+AUTO_PHASE_EXCLUDE=
+AUTO_PHASE_INCLUDE=
+AUTO_PHASE_PROFILE=
+AUTO_PHASE_HIGH_RISK_ACK=
+#
 # Team mode
 # - TEAM_MODE: 0|1 (enable task/member scoped team workflow)
 # - TEAM_MEMBER: short id for current developer
@@ -94,7 +119,7 @@ SYNC_CUSTOM_PHASES=
 ALLOW_AUTO_PUSH=0
 AUTO_PUSH_BRANCH_ALLOWLIST=
 #
-# Knowledge curation / intake
+# Knowledge curation
 # - EARLY_RESEARCH: 0|1 (PO/TL search web during intake/architecture)
 # - INTAKE_GUIDED_MODE: 0|1 (guided intake follow-up/options/research behavior)
 # - INTAKE_SUBAGENT_FALLBACK: deny|allow (deny by default; when deny, missing
@@ -108,6 +133,10 @@ AUTO_PUSH_BRANCH_ALLOWLIST=
 #   archival rollover checks)
 # - STATE_HOT_MAX_CHECKPOINTS: integer >= 10 (max recent checkpoints to retain
 #   in `state.md` after rollover)
+# - PO_TO_TL_HOT_MAX_LINES: integer >= 200 (handoff hot-surface line cap)
+# - PO_TO_TL_HOT_MAX_SECTIONS: integer >= 10 (max top-level ## sections retained)
+# - ARCH_HOT_MAX_LINES: integer >= 500 (architecture hot-surface line cap)
+# - ARCH_HOT_MAX_STORY_SECTIONS: integer >= 20 (max # US-xxxx story sections retained)
 # - Manual-override precedence: explicit flag values in this file remain authoritative
 #   for that flag and override profile defaults.
 EARLY_RESEARCH=1
@@ -117,8 +146,12 @@ ID_NAMESPACE_BOOTSTRAP=0
 TOKEN_PROFILE=balanced
 STATE_HOT_MAX_LINES=1200
 STATE_HOT_MAX_CHECKPOINTS=80
+PO_TO_TL_HOT_MAX_LINES=800
+PO_TO_TL_HOT_MAX_SECTIONS=60
+ARCH_HOT_MAX_LINES=3500
+ARCH_HOT_MAX_STORY_SECTIONS=120
 
-# Publish targets
+# Publish targets (US-0054)
 # - RELEASE_PUBLISH_MODE: disabled|confirm|auto
 #   - disabled: skip post-release publish target execution
 #   - confirm: require explicit operator confirmation before publish (default)
@@ -138,7 +171,7 @@ RELEASE_TARGETS_DEFAULT=
 SECURITY_REVIEW=0
 COMPLIANCE_PROFILES=GDPR
 
-# Compatibility observability
+# Cross-repo compatibility observability
 # - CROSS_REPO_OBSERVABILITY: 0|1 (enable compatibility visibility and checks)
 # - COMPATIBILITY_GATE_ON_CRITICAL: 0|1 (when enabled, critical unresolved
 #   compatibility findings trigger decision gate before release)
@@ -148,15 +181,19 @@ CROSS_REPO_OBSERVABILITY=0
 COMPATIBILITY_GATE_ON_CRITICAL=1
 COMPATIBILITY_SOURCES=
 
-# Component scope
+# Component-scoped execution mode
 # - COMPONENT_SCOPE_MODE: 0|1 (enable scoped planning/execution guardrails)
 # - TARGET_COMPONENTS: comma-separated component IDs intended in scope
 COMPONENT_SCOPE_MODE=0
 TARGET_COMPONENTS=
 
-# Optional docs packs
+# Optional spec-pack documentation (US-0031)
 # - SPEC_PACK_MODE: 0|1 (enable Design Concept, CRS, Technical Spec generation/validation; default 0)
 #   When 0, intake/architecture/release add no required spec-pack steps.
 SPEC_PACK_MODE=0
+
+# Optional user-guide documentation (US-0032)
+# - USER_GUIDE_MODE: 0|1 (enable per-feature user guides at docs/user-guides/US-xxxx.md; default 0)
+#   When 0, intake/architecture/sprint-plan/execute/qa/release add no required user-guide steps or blocking checks.
 USER_GUIDE_MODE=0
 

package/template/README.md

@@ -16,6 +16,8 @@ with pause/resume, decision gates, and persistent artifacts.
 - Pause/resume with checkpoints (`handoffs/resume_brief.md`).
 - Automated execute/QA loop with safety caps (optional).
 - 3-layer quality chain: AI loop → local validate-and-push → CI auto-fix.
+- User-visible metadata guard for operator-facing scripts/CLI (`US-0071` / `DEC-0053`):
+  `python scripts/check-user-visible-metadata.py` (see `docs/engineering/runbook.md`).
 - CI/CD templates driven by `docs/engineering/runbook.md`.
 - Team-friendly local overrides (`scratchpad.local.md`).
 - Optional remote/docker execution and autonomous installs.
@@ -78,8 +80,13 @@ What upgrade does:
 - **Framework files** (commands, rules, agents, hooks, skills, CI, scripts) are
   updated to the latest version.
 - **User data** (docs, sprints, handoffs, decisions, runbook) is never touched.
-- **Mixed files** (`.cursor/scratchpad.md`, `README.md`) are preserved. If the
-  template version has new content, a review notice is printed.
+- **Mixed files** (`README.md`) are preserved. If the template version has new
+  content, a review notice is printed.
+- **Scratchpad baseline (DEC-0055 / US-0073, Model B):** `.cursor/scratchpad.md`
+  is not copied as a manifest file; the installer **materializes** it from the
+  packaged template when missing and validates required merged keys (Python
+  required). Legacy repos that already committed `.cursor/scratchpad.md` keep it on
+  upgrade (not overwritten).
 - A canonical version marker is stored at `its_magic/.its-magic-version` in your repo.
 - Installer bootstrap is OS-aware + stack-aware for runbook command defaults
   (`TEST_COMMAND`, optional `LINT_COMMAND`/`TYPECHECK_COMMAND`) and preserves
@@ -177,8 +184,8 @@ your-project/
   .cursor/agents/            Subagent definitions
   .cursor/skills/            Reusable skills
   .cursor/hooks/             Automation hooks
-  .cursor/scratchpad.md      Shared configuration flags
-  .cursor/scratchpad.local.example.md
+  .cursor/scratchpad.md      Materialized shared defaults (Model B; not manifest-copied)
+  .cursor/scratchpad.local.example.md   Framework default key catalog
   docs/                      Engineering & product docs, runbook
   sprints/                   Sprint tracking artifacts
   handoffs/                  Phase handoff artifacts
@@ -191,21 +198,38 @@ your-project/
 
 ### Team mode local overrides (recommended)
 
-Use two layers:
+Use three layers (merge precedence: **local > materialized baseline > example**,
+`DEC-0055`):
 
-- Shared defaults: `.cursor/scratchpad.md` (committed)
-- Personal overrides: `.cursor/scratchpad.local.md` (gitignored)
+- Framework catalog: `.cursor/scratchpad.local.example.md` (installed; refreshed on upgrade)
+- Shared team baseline: `.cursor/scratchpad.md` (materialized on install when missing; commit as you prefer)
+- Personal overrides: `.cursor/scratchpad.local.md` (gitignored; never overwritten by install/upgrade)
 
 Setup:
 
-1. Copy `.cursor/scratchpad.local.example.md` to `.cursor/scratchpad.local.md`
-2. Set personal values there (`TEAM_MEMBER`, `ACTIVE_TASK_IDS`, automation style)
-3. Hook merges shared + local (local wins)
+1. Run `its-magic` — baseline is materialized and merged validation runs (requires Python on PATH for `installer.ps1` / `installer.sh`).
+2. Optionally copy `.cursor/scratchpad.local.example.md` to `.cursor/scratchpad.local.md` for personal values (`TEAM_MEMBER`, `ACTIVE_TASK_IDS`, …).
 
-Upgrade behavior (US-0057):
-- `.cursor/scratchpad.local.example.md` is framework-owned and refreshed on `--mode upgrade`.
+Recovery if `.cursor/scratchpad.md` is missing or merge validation fails:
+
+```bash
+python installer.py --scratchpad-postinstall --target . --mode missing
+```
+
+Upgrade behavior (US-0057 / DEC-0057):
+- Aligns with **DEC-0039** (example vs local ownership), **DEC-0057** (example-first
+  ordering relative to baseline materialization), and Model B baseline rules below.
+
+- `.cursor/scratchpad.local.example.md` is framework-owned and always refreshed from
+  the shipped template during post-install **before** baseline handling (`DEC-0057` **AC-1..AC-3**).
 - `.cursor/scratchpad.local.md` is user-owned and preserved on `--mode upgrade`.
-- Installer output includes scratchpad example refresh status and local-preserved signal.
+- Existing `.cursor/scratchpad.md` is left untouched on upgrade unless missing (then
+  materialized) or `overwrite` / fresh materialize paths apply (Model B).
+- Installer output uses `[SCRATCHPAD_LAYER]` lines to distinguish example refresh,
+  baseline materialize/skip, and user-local preservation (`DEC-0057` **AC-5**).
+- Paired catalog parity (baseline vs `.cursor/scratchpad.local.example.md`, active and
+  `template/`): `python scripts/check-scratchpad-pair-parity.py --repo .` (wired into
+  `tests/run-tests.ps1` / `tests/run-tests.sh`; **AC-11**).
 
 Deterministic ordering behavior (US-0058):
 - Mutable artifacts follow `docs/engineering/artifact-ordering-policy.md`.
@@ -383,9 +407,15 @@ Compaction behavior:
 - Enforced rollover thresholds:
   - `STATE_HOT_MAX_LINES` (default `1200`)
   - `STATE_HOT_MAX_CHECKPOINTS` (default `80`)
-  `/refresh-context` must archive oldest checkpoints into deterministic
-  `state-pack-*` files when thresholds are exceeded, keeping only bounded recent
-  checkpoints in hot surface.
+  - `PO_TO_TL_HOT_MAX_LINES` (default `800`)
+  - `PO_TO_TL_HOT_MAX_SECTIONS` (default `60`)
+  - `ARCH_HOT_MAX_LINES` (default `3500`)
+  - `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.
+  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).
   Archive verification mismatch fails with
   `STATE_ARCHIVE_VERIFICATION_FAILED`.
 
@@ -545,12 +575,10 @@ Deterministic release semantics:
 - Unresolved sprint identity or queue/notes mismatch fails closed with reason
   codes and remediation guidance; no destructive reconciliation by default.
 
-### Release gate chain (US-0039)
-
-`/release` enforces mandatory gates in order: check-in test, QA completion, UAT completion, then finalization. Blank optional runbook keys do not block release. No bypass by default; override only via explicit decision gate.
-
 ### Post-QA release issue workflow (US-0042)
 
+Release gate chain (US-0039): `/release` enforces mandatory gates in order — check-in test, QA completion, UAT completion — then finalization. Blank optional runbook keys (`LINT_COMMAND`, `TYPECHECK_COMMAND`) do not block release; they are reported as skipped.
+
 If a problem appears **after QA** (during `/release`), record it separately from
 QA findings:
 
@@ -621,6 +649,32 @@ Fail-closed reason codes:
 `/auto`, `/verify-work`, and `/release` must validate these tuples before
 continuation/finalization.
 
+#### `/auto` phase→role enforcement (US-0069 / DEC-0051)
+
+`/auto` uses a deterministic **phase→role matrix** plus scratchpad alternates
+(`AUTO_ROLE_RESEARCH`, `AUTO_ROLE_PLAN_VERIFY`, `AUTO_ROLE_REFRESH_CONTEXT`).
+Before each phase spawn it runs a **preflight capability gate**; missing
+capability stops with `PHASE_ROLE_CAPABILITY_MISSING` (no unrelated-role
+substitution). After each phase, isolation `role` and strict-proof `role` must
+match the same expected role or the run stops with `PHASE_ROLE_MISMATCH`.
+`execute` defaults to `dev`; non-`dev` requires
+`AUTO_EXECUTE_ROLE_OVERRIDE=allowed_non_dev_execute` **and**
+`EXECUTE_OVERRIDE_GOVERNANCE_REF` pointing to a parseable approved waiver. See
+`docs/engineering/runbook.md` and `decisions/DEC-0051.md`.
+
+#### `/auto` phase selection policy (US-0070 / DEC-0052)
+
+`/auto` builds a **resolved phase plan** from scratchpad before spawning phases:
+exactly one of `AUTO_PHASE_PLAN` (default `full`), `AUTO_PHASE_EXCLUDE`,
+`AUTO_PHASE_INCLUDE`, or `AUTO_PHASE_PROFILE` applies; conflicting selectors
+stop with `PHASE_POLICY_CONFLICT`. Non-skippable safety gates (`qa`,
+`verify-work`, `release`) and evidence-chain closure reinstate omitted phases
+with breadcrumb reasons such as `non_skippable_gate`. `start-from` and resume
+anchors **intersect** with the plan (`START_FROM_PHASE_PLAN_EMPTY_INTERSECTION`
+when empty). Backlog-drain, bulk execute, and team-mode runs **recompute** the
+plan each boundary. See `/auto`, `docs/engineering/runbook.md`, and
+`decisions/DEC-0052.md`.
+
 ### Lightweight interaction
 
 Use `/ask` when you want to query the project without triggering the workflow:

package/template/docs/engineering/context/installer-owned-paths.manifest

@@ -1,5 +1,10 @@
 # its-magic installer ownership manifest
 # Sections are line-based path lists.
+#
+# Model B baseline: materialized scratchpad (under .cursor/) is not manifest-copied;
+# installers copy it from packaged template during post-install only. Framework-owned
+# scratchpad.local.example (under .cursor/) refreshes from template before baseline
+# handling in installer.py --scratchpad-postinstall (example-first ordering).
 
 [install_include_paths]
 .cursor/commands
@@ -8,7 +13,6 @@
 .cursor/agents
 .cursor/hooks
 .cursor/hooks.json
-.cursor/scratchpad.md
 .cursor/scratchpad.local.example.md
 docs
 sprints

package/template/docs/engineering/phase-context.md

@@ -0,0 +1,16 @@
+# Phase context pointers
+
+Use this file as the **first** narrow read for workflow orientation. Expand to
+linked hot or archive paths only when a question stays unresolved after the
+default set (see minimal-read table in `docs/engineering/runbook.md`).
+
+| Kind | Path | Notes |
+|------|------|-------|
+| Engineering state (hot) | `docs/engineering/state.md` | Recent checkpoints; archive under `docs/engineering/state-archive/` |
+| Decisions index | `docs/engineering/decisions.md` | Compact index; full records under `decisions/` |
+| PO → TL handoff (hot) | `handoffs/po_to_tl.md` | Narrative handoff; archive under `handoffs/archive/` |
+| Architecture (hot) | `docs/engineering/architecture.md` | Story-shaped sections; archive under `docs/engineering/architecture-archive/` |
+| Triad enforcement | `scripts/enforce-triad-hot-surface.py` | `--check` before phase completion when mutating triad surfaces |
+
+Escalation: open the **named archive pack** cited in the latest rollover
+verification tuple for the surface you need, not the entire archive tree.

package/template/docs/engineering/runbook.md

@@ -5,8 +5,8 @@
 TEST_COMMAND:
 LINT_COMMAND:
 TYPECHECK_COMMAND:
-DEPLOY_STAGING_COMMAND:
-DEPLOY_PROD_COMMAND:
+DEPLOY_STAGING_COMMAND: echo "No staging deploy target configured for this repository"
+DEPLOY_PROD_COMMAND: echo "No production deploy target configured for this repository"
 
 LINT_FIX_COMMAND:
 FORMAT_COMMAND:
@@ -26,9 +26,10 @@ TEST_TIMEOUT_SECONDS: 120
 
 ## Intentional empty commands (US-0015)
 
-For this template/installer repository, empty optional command keys are
-intentional defaults, not configuration errors:
+For this template/installer repository, the following command keys may be
+intentionally empty in the shipped template; they are not configuration errors:
 
+- `TEST_COMMAND` (blank until installer bootstrap per stack; **DEC-0056**)
 - `LINT_COMMAND`
 - `FORMAT_COMMAND`
 - `TYPECHECK_COMMAND`
@@ -59,6 +60,60 @@ Remediation:
 - define `TEST_COMMAND` explicitly in `docs/engineering/runbook.md`, or
 - add detectable stack markers/scripts then rerun installer upgrade.
 
+## User-visible internal metadata guard (US-0071 / DEC-0053)
+
+**Goal:** keep planning-shaped identifiers out of **operator-visible software
+channels** (CLI/installer/validate-and-push strings), while they remain valid in
+internal documentation trees and in source comments that are not emitted to
+users.
+
+### Forbidden tokens (user-visible channels only)
+
+Match planning-shaped tokens:
+
+- `US-[0-9]{4}`
+- `DEC-[0-9]{4}`
+- `R-[0-9]{4}`
+
+### Inclusive scan roots (deterministic)
+
+From repository root, the checker walks **only**:
+
+- `bin/**` (`*.js`)
+- `installer.py`, `installer.ps1`, `installer.sh`
+- `packaging/**` (`*.js`, `*.py`, `*.ps1`, `*.sh`)
+- `scripts/validate-and-push.ps1`, `scripts/validate-and-push.sh`
+
+Paths outside this set are **not** scanned by this tool (for example `docs/**`,
+`.cursor/**`, `sprints/**`, `handoffs/**`, `decisions/**` remain free to use
+story/decision/research IDs). If a new operator-visible deliverable is added
+outside these roots, extend the scan list or you risk
+`METADATA_SANITIZATION_SCOPE_AMBIGUOUS` classification during review.
+
+### Command
+
+```bash
+python scripts/check-user-visible-metadata.py
+python scripts/check-user-visible-metadata.py --json
+```
+
+### Reason codes (minimum)
+
+- `USER_VISIBLE_INTERNAL_METADATA_DETECTED` — forbidden token matched inside a
+  scanned user-visible string/literal.
+- `METADATA_SANITIZATION_POLICY_MISSING` — checker entrypoint missing or
+  unusable.
+- `METADATA_SANITIZATION_SCOPE_AMBIGUOUS` — cannot classify whether a path
+  belongs in inclusive scan roots; treat as fail-closed until the runbook table
+  is updated.
+
+### Findings / remediation (contract)
+
+On failure, diagnostics must cite **evidence_ref** (`path:line:column` when
+available), **token class** (`US` \| `DEC` \| `R`), and remediation: remove the
+token from operator-visible strings; keep traceability in allowlisted internal
+artifacts or non-emitting comments per `DEC-0053`.
+
 ## Guided intake mode (US-0033)
 
 Intake interaction behavior is controlled by one switch in
@@ -212,15 +267,71 @@ Context compaction policy:
 - Enforced rollover thresholds:
   - `STATE_HOT_MAX_LINES` (default `1200`)
   - `STATE_HOT_MAX_CHECKPOINTS` (default `80`)
-  When either threshold is exceeded during `/refresh-context`, older checkpoints
-  are archived into deterministic `state-pack-*` files and only bounded recent
-  checkpoints remain in hot surface.
+  - `PO_TO_TL_HOT_MAX_LINES` (default `800`)
+  - `PO_TO_TL_HOT_MAX_SECTIONS` (default `60`)
+  - `ARCH_HOT_MAX_LINES` (default `3500`)
+  - `ARCH_HOT_MAX_STORY_SECTIONS` (default `120`)
+  Thresholds resolve from merged `.cursor/scratchpad.md` +
+  `.cursor/scratchpad.local.md` (DEC-0054 triad contract).
+  When a cap is exceeded, the mutating phase must run rollover **before**
+  completion or fail closed (no successful completion with an oversize hot
+  surface).
+
+### Triad hot-surface enforcement (DEC-0054)
+
+Canonical hot/archive surfaces:
+
+- `docs/engineering/state.md` → `docs/engineering/state-archive/state-pack-*.md`
+- `handoffs/po_to_tl.md` → `handoffs/archive/po-to-tl-pack-*.md`
+- `docs/engineering/architecture.md` →
+  `docs/engineering/architecture-archive/architecture-pack-*.md`
+
+Operator commands:
+
+```bash
+python scripts/enforce-triad-hot-surface.py --check
+python scripts/enforce-triad-hot-surface.py --rollover
+```
+
+- `--check` verifies all three surfaces are within policy (CI-safe).
+- `--rollover` archives oldest contiguous units into the next deterministic pack
+  name; reruns are idempotent when already within caps.
+- Successful rollover records a verification tuple:
+  `boundary`, `moved`, `retained` (counts / lines), `pack_ref`.
 
 Rollover fail-safe reason codes:
 
 - `STATE_ARCHIVE_BOUNDARY_AMBIGUOUS`
 - `STATE_ARCHIVE_WRITE_FAILED`
 - `STATE_ARCHIVE_VERIFICATION_FAILED`
+- `STATE_ARCHIVE_REQUIRED`
+- `ARTIFACT_HOT_SURFACE_OVERSIZE`
+- `CONTEXT_BUDGET_EXCEEDED`
+
+### Minimal-read defaults by phase (bounded escalation)
+
+Read `docs/engineering/phase-context.md` first, then the **required** paths for
+your phase. If unresolved, expand once to the **single** archive pack named in
+the latest verification tuple for that surface. Do not load entire archive
+directories by default.
+
+| Phase | Required reads (default) | Combined line budget (guidance) |
+|-------|--------------------------|----------------------------------|
+| `/intake` | `phase-context.md`, target story in `docs/product/backlog.md`, `handoffs/po_to_tl.md` (tail) | ≤ 900 lines |
+| `/discovery` | `phase-context.md`, `docs/product/vision.md` (story notes), `handoffs/po_to_tl.md` (tail) | ≤ 900 lines |
+| `/research` | `phase-context.md`, `docs/engineering/research.md` (target entry), `docs/product/backlog.md` (target story) | ≤ 800 lines |
+| `/architecture` | `phase-context.md`, `docs/engineering/architecture.md` (target story section), `docs/engineering/research.md` | ≤ 1200 lines |
+| `/sprint-plan` | `phase-context.md`, `docs/engineering/architecture.md` (target story), `handoffs/tl_to_dev.md` | ≤ 1000 lines |
+| `/plan-verify` | `phase-context.md`, `sprints/Sxxxx/tasks.md`, `docs/product/backlog.md` (ACs) | ≤ 900 lines |
+| `/execute` | `phase-context.md`, `sprints/Sxxxx/tasks.md`, `handoffs/tl_to_dev.md` | ≤ 800 lines |
+| `/qa` | `phase-context.md`, `sprints/Sxxxx/`, `tests/report.md` | ≤ 900 lines |
+| `/verify-work` | `phase-context.md`, `sprints/Sxxxx/uat.json`, QA findings | ≤ 600 lines |
+| `/release` | `phase-context.md`, release queue + sprint release findings | ≤ 700 lines |
+| `/refresh-context` | `phase-context.md`, `docs/engineering/state.md` (tail), `docs/product/backlog.md` (status) | ≤ 900 lines |
+| `/auto` (resolver) | `phase-context.md`, `handoffs/resume_brief.md`, `docs/engineering/state.md` (tail) | ≤ 700 lines |
+
+If the default set is insufficient, escalate with an explicit note citing
+`pack_ref`. Unbounded broad reads fail closed with `CONTEXT_BUDGET_EXCEEDED`.
 
 `/ask` retrieval policy:
 
@@ -480,7 +591,7 @@ rewrite of unrelated backlog/acceptance/state/release artifacts.
 - `BACKLOG_DONE_TRACEABILITY_MISSING` — Backlog DONE but traceability/state lacks entry.
   Remediation: add traceability row in `docs/engineering/state.md` from backlog/release evidence or run backfill.
 - `BACKLOG_DONE_RELEASE_ARTIFACT_MISSING` — Backlog DONE but release artifacts lack representation.
-  Remediation: ensure release notes or queue row exists for the story's sprint or run backfill.
+  Remediation: ensure release notes or queue row exists for the story’s sprint or run backfill.
 
 **One-time backfill mode**: Explicit trigger (e.g. dedicated check or `/memory-audit`-related path).
 - Run detection once over all DONE stories; for each legacy-drift story, perform
@@ -781,6 +892,86 @@ Boundary behavior:
   isolation evidence checks.
 - Pause/resume provenance must reference latest valid strict-proof boundary.
 
+## Strict `/auto` phase→role enforcement (US-0069 / DEC-0051)
+
+`/auto` must treat phase roles as a **fail-closed admission and checkpoint
+contract** (see `decisions/DEC-0051.md` and `/auto` command text).
+
+### Canonical matrix and scratchpad alternates
+
+- Fixed phase→role defaults are documented in `/auto` (for example `execute` →
+  `dev`, `release` → `release`).
+- Alternate phases resolve **one** expected role via scratchpad:
+  - `AUTO_ROLE_RESEARCH`: `po` \| `tech-lead` (empty → default `tech-lead`)
+  - `AUTO_ROLE_PLAN_VERIFY`: `qa` \| `tech-lead` (empty → default `qa`)
+  - `AUTO_ROLE_REFRESH_CONTEXT`: `curator` \| `po` (empty → default `curator`)
+- Non-empty values outside the allowed set fail closed (no unrelated-role
+  substitution).
+
+### Preflight and checkpoints
+
+- **Preflight (before spawn)**: resolve expected role; verify the required
+  subagent capability exists. Missing capability → `PHASE_ROLE_CAPABILITY_MISSING`
+  with `phase_id`, expected role, observed result, remediation. Do not spawn a
+  substitute role.
+- **Post-completion**: isolation evidence `role` and strict-proof `role` must
+  both match the same preflight-resolved role; else `PHASE_ROLE_MISMATCH`.
+- **`proof_hash`**: SHA-256 over sorted-key JSON of the strict-proof tuple fields
+  (`orchestrator_run_id`, `runtime_proof_id`, `phase_id`, `role`,
+  `proof_issued_at`, `proof_ttl_seconds`).
+
+### Execute default deny and rare override
+
+- Default: `execute` requires `dev`.
+- Override allowed only when **both** hold:
+  `AUTO_EXECUTE_ROLE_OVERRIDE=allowed_non_dev_execute` and
+  `EXECUTE_OVERRIDE_GOVERNANCE_REF` references a parseable approved exception (for
+  example `DEC-xxxx` or a documented state anchor).
+
+### Continuation parity
+
+- Every `/auto` run recomputes role policy and preflight; `start-from`, fresh
+  `resume_brief`, and `state.md` fallback cannot bypass the gate with stale role
+  intent alone.
+
+## Configurable `/auto` phase plan (US-0070 / DEC-0052)
+
+`/auto` schedules a **resolved ordered phase plan** from merged scratchpad
+before any spawn. See `decisions/DEC-0052.md` and `/auto` command text.
+
+### Selectors (exactly one active mode)
+
+- `AUTO_PHASE_PLAN=full` (default when unset and no other selector is set)
+- `AUTO_PHASE_EXCLUDE=<csv>` — remove listed canonical phase ids from `full`
+- `AUTO_PHASE_INCLUDE=<csv>` — only listed ids, re-sorted into canonical lifecycle order
+- `AUTO_PHASE_PROFILE=<name>` — expand a named profile (unknown → fail closed)
+- `AUTO_PHASE_HIGH_RISK_ACK=<token>` — required when a documented high-risk profile demands acknowledgment
+
+Conflicting selectors → `PHASE_POLICY_CONFLICT` (no plan materialization).
+
+### Materialization and gates
+
+- Expand → apply **non-skippable reinstatement** (`qa`, `verify-work`, `release`,
+  plus evidence-chain closure per `/auto`) → intersect **`start-from` / resume
+  anchor** with the plan → **empty intersection** →
+  `START_FROM_PHASE_PLAN_EMPTY_INTERSECTION`.
+- Record `resolved_phase_plan`, `skipped_phases` (+ reasons such as
+  `policy_exclude`, `non_skippable_gate`), and **phase boundary status** entries
+  in continuation breadcrumbs (`docs/engineering/state.md`).
+- **Backlog-drain**, **bulk execute**, and **team scope** paths must **reload**
+  scratchpad phase-selection inputs and **recompute** the plan at each bounded
+  boundary (no silent revival of omitted phases).
+
+### Failure codes (deterministic)
+
+- `PHASE_POLICY_CONFLICT`
+- `PHASE_PLAN_UNKNOWN_PHASE`
+- `PHASE_PLAN_EMPTY_INCLUDE`
+- `PHASE_PLAN_UNKNOWN_PROFILE`
+- `PHASE_PLAN_INVALID_AUTO_PHASE_PLAN`
+- `PHASE_PLAN_HIGH_RISK_ACK_REQUIRED`
+- `START_FROM_PHASE_PLAN_EMPTY_INTERSECTION`
+
 ## Optional backlog-drain auto mode (US-0044)
 
 `/auto` can optionally continue across multiple planned stories when explicitly
@@ -927,9 +1118,17 @@ Deterministic mandatory gate order; no step may be skipped or reordered:
 
 Default: no bypass. Override only via explicit decision gate with rationale and evidence (DEC-0019).
 
-**Optional-command compatibility (US-0039 / AC-10)**: Blank optional runbook keys (`LINT_COMMAND`, `TYPECHECK_COMMAND`) must not cause release to fail. Mandatory gates are check-in test + QA + UAT + isolation only.
+**Optional-command compatibility (US-0039 / AC-10)**: Blank optional runbook keys (`LINT_COMMAND`, `TYPECHECK_COMMAND`) must not cause release to fail. Mandatory gates are check-in test + QA + UAT + isolation only; optional checks run only when configured and are reported as `skipped` when not configured. Release does not require lint/typecheck evidence when those keys are blank.
+
+**Per-gate audit verdict schema (US-0039)** — For TL/QA auditability, record per gate:
+
+- `gate` (check-in_test | qa | uat | isolation | finalization)
+- `verdict` (pass | fail | override)
+- `reason_code` (e.g. RELEASE_TEST_FAILED, RELEASE_QA_BLOCKERS_OPEN, RELEASE_UAT_INCOMPLETE, RELEASE_GATE_OVERRIDE_APPROVED)
+- `remediation` (short remediation steps when fail/override)
+- `evidence_refs` (paths to tests/report.md, qa-findings.md, uat.json, release-findings.md, DEC-xxxx as applicable)
 
-**Per-gate audit verdict schema (US-0039)**: Record per gate (check-in_test | qa | uat | isolation | finalization): verdict (pass|fail|override), reason_code, remediation, evidence_refs in release-findings and queue gate_snapshot.
+Record in `sprints/Sxxxx/release-findings.md` and/or `handoffs/release_queue.md` `gate_snapshot`; state checkpoint in `docs/engineering/state.md` may reference the same.
 
 ## Release queue and sprint notes contract (US-0040 / DEC-0020)
 
@@ -1036,16 +1235,37 @@ Use this matrix to validate end-to-end installer/CLI lifecycle behavior:
 | Negative path | invalid mode/args | `tests/run-tests.ps1`, `tests/run-tests.sh` | Deterministic non-zero fail-fast behavior |
 | Platform parity subset | npm/brew/choco CI jobs | `.github/workflows/ci.yml` | Lifecycle subset passes on all three runners |
 
-## Scratchpad example upgrade contract (US-0057 / DEC-0039)
+## Scratchpad example upgrade contract (US-0057 / DEC-0039 / DEC-0057)
 
 `its-magic --mode upgrade` treats `.cursor/scratchpad.local.example.md` as
 framework-owned and `.cursor/scratchpad.local.md` as user-owned.
 
 Expected deterministic outcome:
-- Framework-owned example is refreshed to latest release contract.
+- Framework-owned example is refreshed to latest release contract **before** baseline
+  materialization runs in `installer.py --scratchpad-postinstall` (**DEC-0057** ordering).
 - User local scratchpad remains preserved without overwrite.
-- Installer output reports scratchpad example refresh status
-  (`added|updated|unchanged`) and preservation signal for user local file.
+- Installer output reports manifest copy status for the example file where applicable
+  (`added|updated|unchanged`) **and** `[SCRATCHPAD_LAYER]` diagnostics from post-install
+  (`example_refresh`, `baseline_materialize` / `baseline_skip`, `user_local` preserved).
+- CI regression: `python scripts/check-scratchpad-pair-parity.py --repo <root>` exit `0`
+  when active and `template/` baseline/example pairs share the same automation `KEY=`
+  set and catalog `#` headers from `# Core behavior` (**US-0075** **AC-11**).
+
+## Scratchpad delivery Model B (US-0073 / DEC-0055)
+
+- Install manifest ships `.cursor/scratchpad.local.example.md` (framework catalog)
+  but **does not** list `.cursor/scratchpad.md` as a copied file. The installer
+  **materializes** `.cursor/scratchpad.md` from the packaged template when absent
+  (`missing`, `interactive`, `upgrade`) or refreshes it on `overwrite`.
+- Merge precedence for automation readers: **local > materialized baseline > example**
+  (same invariant as `DEC-0055`).
+- Post-install validation fails closed with `[SCRATCHPAD_MERGE_ERROR]` /
+  `[SCRATCHPAD_MATERIALIZE_ERROR]` when layers are missing or required keys are
+  empty after merge (`US-0073` `AC-4`).
+- `installer.ps1` / `installer.sh` delegate materialize+validate to
+  `python installer.py --scratchpad-postinstall` (Python 3 required on PATH).
+- Recovery: `python installer.py --scratchpad-postinstall --target <repo> --mode missing`
+  (or re-run a full install).
 
 ## Deterministic artifact ordering and write discipline (US-0058 / DEC-0040)