its-magic 0.1.2-29 → 0.1.2-32

package/template/.cursor/commands/auto.md

@@ -61,13 +61,231 @@ Strict-proof reason codes:
 - `RUNTIME_PROOF_STALE`
 - `RUNTIME_PROOF_AMBIGUOUS_LINK`
 
+## Strict phase role enforcement (US-0069 / DEC-0051)
+
+`/auto` must enforce a deterministic **phase→role contract** with **preflight
+admission** before each phase spawn, **fail-closed checkpoint validation** after
+each phase completes, and **aligned strict-proof `role`** values. Post-hoc
+isolation markers alone are insufficient.
+
+### Canonical phase→role matrix (fixed defaults)
+
+| phase_id | Allowed roles | Default when no valid alternate policy |
+|----------|-----------------|----------------------------------------|
+| `intake` | `po` | `po` |
+| `discovery` | `po` | `po` |
+| `research` | `po`, `tech-lead` | `tech-lead` |
+| `architecture` | `tech-lead` | `tech-lead` |
+| `sprint-plan` | `tech-lead` | `tech-lead` |
+| `plan-verify` | `qa`, `tech-lead` | `qa` |
+| `execute` | `dev` (override path only) | `dev` |
+| `qa` | `qa` | `qa` |
+| `verify-work` | `qa` | `qa` |
+| `release` | `release` | `release` |
+| `refresh-context` | `curator`, `po` | `curator` |
+
+### Alternate-role scratchpad policy (single-valued resolution)
+
+Resolve **exactly one** expected role for phases with alternates using merged
+scratchpad (active + `.cursor/scratchpad.local.md`; template parity on install):
+
+- `AUTO_ROLE_RESEARCH`: `po` \| `tech-lead` — when **unset or empty**, default
+  `tech-lead`; when set to any other value, fail closed with diagnostics (no
+  unrelated-role fallback).
+- `AUTO_ROLE_PLAN_VERIFY`: `qa` \| `tech-lead` — when **unset or empty**,
+  default `qa`; otherwise only `qa` or `tech-lead` allowed (else fail closed).
+- `AUTO_ROLE_REFRESH_CONTEXT`: `curator` \| `po` — when **unset or empty**,
+  default `curator`; otherwise only `curator` or `po` allowed (else fail closed).
+
+### Preflight capability gate (before spawn)
+
+Before spawning phase work, `/auto` must:
+
+1. Resolve `phase_id` → expected canonical `role` (matrix + policy keys above).
+2. For `execute`, apply **default deny**: expected role is `dev` unless **both**
+   `AUTO_EXECUTE_ROLE_OVERRIDE=allowed_non_dev_execute` **and**
+   `EXECUTE_OVERRIDE_GOVERNANCE_REF` point to a **parseable** approved exception
+   record (for example `DEC-xxxx` or a documented anchor in
+   `docs/engineering/state.md`).
+3. Evaluate **role capability availability** for that boundary (subagent/tooling
+   can satisfy the resolved role).
+4. On missing capability: stop with `PHASE_ROLE_CAPABILITY_MISSING` including
+   `phase_id`, expected role, observed capability result, and remediation. **Do
+   not** spawn under a substitute unrelated role.
+
+### Post-completion boundary validation
+
+When a phase completes, before advancing:
+
+- Isolation evidence `role` must equal the **same** preflight-resolved expected
+  role for that `phase_id`. Else stop with `PHASE_ROLE_MISMATCH`.
+- Strict-proof tuple `role` must equal isolation `role` and the expected role.
+- `proof_hash` must be SHA-256 over canonical sorted-key JSON of
+  `orchestrator_run_id`, `runtime_proof_id`, `phase_id`, `role`,
+  `proof_issued_at`, `proof_ttl_seconds` (`DEC-0038` / architecture US-0069).
+
+### Resume / `start-from` parity
+
+Every `/auto` invocation (explicit `start-from`, `resume_brief`, or conservative
+`state.md` fallback) must **recompute** policy resolution and preflight from
+scratch; stale continuation artifacts must not bypass the gate.
+
+### Role-enforcement reason codes (deterministic)
+
+- `PHASE_ROLE_CAPABILITY_MISSING`
+- `PHASE_ROLE_MISMATCH`
+
+## Configurable phase selection policy (US-0070 / DEC-0052)
+
+`/auto` must treat the **resolved phase plan** as a first-class, fail-closed
+schedule: a single ordered subset of canonical phases computed from merged
+scratchpad (active + `.cursor/scratchpad.local.md`; template parity on install),
+**before** resume/`start-from` intersection and **before** any phase spawn.
+
+### Canonical lifecycle order (baseline `full` plan)
+
+Unless narrowed by policy, the canonical ordered phase list is:
+
+`intake` → `discovery` → `research` → `architecture` → `sprint-plan` →
+`plan-verify` → `execute` → `qa` → `verify-work` → `release` →
+`refresh-context`
+
+When `SECURITY_REVIEW=1`, insert `/security-review` in **design** mode
+immediately after `architecture` and before `sprint-plan`, and in **code** mode
+immediately after `execute` and before `qa`, as documented in **Steps** below.
+Record these inserts in `resolved_phase_plan` breadcrumbs using the same
+deterministic labels the orchestrator already uses for security boundaries.
+
+### Scratchpad selectors (exactly one active policy mode)
+
+At most one of the following may be materially active after merge. If two or
+more non-default selectors conflict, fail closed with `PHASE_POLICY_CONFLICT`
+and **do not** materialize a plan:
+
+- `AUTO_PHASE_PLAN=full` — full canonical lifecycle (including security-review
+  inserts when enabled). Default when unset and no other selector is set.
+- `AUTO_PHASE_EXCLUDE=<csv>` — start from `full`, remove listed phase IDs
+  (validate each token; unknown id → `PHASE_PLAN_UNKNOWN_PHASE`).
+- `AUTO_PHASE_INCLUDE=<csv>` — schedule **only** listed ids, then **re-sort**
+  into canonical lifecycle order. Unknown id → `PHASE_PLAN_UNKNOWN_PHASE`.
+  Empty result after parsing → `PHASE_PLAN_EMPTY_INCLUDE`.
+- `AUTO_PHASE_PROFILE=<name>` — expand a **named profile** from the registry
+  below. Unknown profile → `PHASE_PLAN_UNKNOWN_PROFILE`.
+
+**Conflict rule**: `AUTO_PHASE_PLAN` is default-only when it is unset, empty, or
+exactly `full`. Any explicit non-`full` `AUTO_PHASE_PLAN` value is invalid
+(fail closed with `PHASE_PLAN_INVALID_AUTO_PHASE_PLAN`) — use `INCLUDE` /
+`EXCLUDE` / `PROFILE` instead.
+
+### Profile registry (baseline)
+
+- `default` — equivalent to `full` (optional explicit alias; same behavior as
+  unset policy).
+
+**High-risk profile sketch** (illustrative; `R-0049`): `profile_high_risk_dev_fast`
+may only be selected when **both** hold: `AUTO_PHASE_PROFILE=profile_high_risk_dev_fast`
+and `AUTO_PHASE_HIGH_RISK_ACK=<operator_token>` matches the profile spec
+version documented in `decisions/DEC-0052.md` / research `R-0049`. Missing ack →
+`PHASE_PLAN_HIGH_RISK_ACK_REQUIRED`. High-risk profiles may define **narrower**
+reinstatement rules **only** as documented for that profile; default profile
+behavior applies otherwise.
+
+### Plan materialization pipeline (evaluation order)
+
+On every `/auto` entry (including resume, backlog-drain, bulk execute, and
+team-mode runs), **recompute** from merged scratchpad:
+
+1. Parse merged scratchpad policy inputs for phase selection + `SECURITY_REVIEW`.
+2. Detect active policy mode; on conflict → `PHASE_POLICY_CONFLICT` (no plan).
+3. Expand mode to a **candidate** ordered phase list in canonical order.
+4. Apply **non-skippable reinstatement** for the **default profile** (and for
+   any profile that does not explicitly document a narrower exception with ack):
+   - **Safety gates**: always reinstate if removed: `qa`, `verify-work`,
+     `release`.
+   - **Evidence-chain closure**: if the candidate retains any phase from
+     `execute` onward (`execute`, optional `security-review-code`, `qa`,
+     `verify-work`, `release`, `refresh-context`), reinstate (if removed) the
+     contiguous canonical prefix from `intake` through `plan-verify` so later
+     gates retain valid upstream isolation + strict-proof chain semantics.
+   - When `SECURITY_REVIEW=1`, reinstate the corresponding `security-review-*`
+     insert when the adjacent retained phases would otherwise violate the
+     documented security boundary contract.
+   Record each reinstatement in breadcrumbs with reason `non_skippable_gate`
+   (or a more specific documented code).
+5. Record **operator-visible plan breadcrumbs** to `docs/engineering/state.md`
+   **before** first spawn (append-bottom per `DEC-0040`):
+   - `phase_policy_mode` (`full|exclude|include|profile`)
+   - `resolved_phase_plan` (ordered `phase_id` list)
+   - `skipped_phases` (id + reason: `policy_exclude`, `non_skippable_gate`,
+     `default_full_plan`, etc.)
+   - `orchestrator_run_id` (when known for this run)
+6. **Do not** silently revive phases omitted by policy on continuation: every
+   entry re-reads scratchpad bytes and recomputes the plan class.
+
+### `start-from` and resume intersection with the resolved plan
+
+After computing the **resolved phase plan**, resolve the **nominal** start
+phase using **Deterministic resume-source precedence** (explicit `start-from`
+→ `resume_brief` → `state` fallback → fail-fast).
+
+Then **intersect**:
+
+- Keep phases that appear in the resolved plan **in plan order**, starting at
+  the first plan phase whose canonical position is **at or after** the nominal
+  anchor phase (canonical order matches the baseline list above, including
+  security inserts when enabled).
+- If the intersection is empty, fail closed with
+  `START_FROM_PHASE_PLAN_EMPTY_INTERSECTION` and diagnostics listing
+  `resolved_phase_plan` vs `requested_start_phase` / resume inference.
+
+### Compatibility with `US-0069` / `DEC-0051`
+
+- Role resolution and preflight apply **only** to phases present in the
+  intersected schedule. Skipping `research` does **not** change the expected
+  role for `architecture` or any other retained phase.
+- Skipped phases produce **no** spawn and **no** alternate-role substitution
+  for a different phase.
+
+### Phase-plan reason codes (deterministic)
+
+Add to operator diagnostics and breadcrumb records:
+
+- `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`
+
+### Phase boundary operator visibility (AC-10)
+
+At each phase boundary (after completing a scheduled phase), record a compact
+**phase boundary status** entry (for example in `docs/engineering/state.md`
+continuation breadcrumbs) including:
+
+- `resolved_phase_plan` snapshot (or stable hash pointer to the run’s plan record)
+- `skipped_phases` summary (id + reason code)
+- `phase_boundary` (completed `phase_id`)
+- `next_scheduled_phase` (or `none` when complete/stopped)
+
 ## Inputs
-- `AUTO_FLOW_MODE` and `PHASE_MODE` from `.cursor/scratchpad.md`
-- `AUTO_IMPLEMENTATION_LOOP`, `AUTO_LOOP_MAX_CYCLES` from `.cursor/scratchpad.md`
-- `AUTO_PAUSE_REQUEST`, `AUTO_PAUSE_POLICY` from `.cursor/scratchpad.md`
-- `SECURITY_REVIEW`, `COMPLIANCE_PROFILES` from `.cursor/scratchpad.md`
+- Merged scratchpad policy (`US-0073` / `DEC-0055`): resolve flags from **local >
+  materialized `.cursor/scratchpad.md` > `.cursor/scratchpad.local.example.md`**
+  (installers materialize baseline when missing; missing required keys after merge
+  must fail closed with `[SCRATCHPAD_MERGE_ERROR]` diagnostics, not silent defaults).
+- `AUTO_FLOW_MODE` and `PHASE_MODE` from merged scratchpad
+- `AUTO_IMPLEMENTATION_LOOP`, `AUTO_LOOP_MAX_CYCLES` from merged scratchpad
+- `AUTO_PAUSE_REQUEST`, `AUTO_PAUSE_POLICY` from merged scratchpad
+- `SECURITY_REVIEW`, `COMPLIANCE_PROFILES` from merged scratchpad
 - `AUTO_EXECUTE_BULK`, `AUTO_EXECUTE_MAX_ITEMS`, `AUTO_EXECUTE_ON_BLOCK`,
-  `AUTO_EXECUTE_SELECTION`, `AUTO_TEAM_SCOPE_ENFORCE` from `.cursor/scratchpad.md`
+  `AUTO_EXECUTE_SELECTION`, `AUTO_TEAM_SCOPE_ENFORCE` from merged scratchpad
+- `AUTO_ROLE_RESEARCH`, `AUTO_ROLE_PLAN_VERIFY`, `AUTO_ROLE_REFRESH_CONTEXT`,
+  `AUTO_EXECUTE_ROLE_OVERRIDE`, `EXECUTE_OVERRIDE_GOVERNANCE_REF` from merged
+  scratchpad (US-0069 / DEC-0051)
+- `AUTO_PHASE_PLAN`, `AUTO_PHASE_EXCLUDE`, `AUTO_PHASE_INCLUDE`,
+  `AUTO_PHASE_PROFILE`, `AUTO_PHASE_HIGH_RISK_ACK` from merged scratchpad
+  (US-0070 / DEC-0052)
 - `TEAM_MODE`, `TEAM_MEMBER`, `ACTIVE_TASK_IDS` from merged scratchpad context
 - Current product and engineering docs
 - Optional explicit argument: `start-from=<phase>`
@@ -225,6 +443,15 @@ Reason-code baseline:
 - `RUNTIME_PROOF_REUSED`
 - `RUNTIME_PROOF_STALE`
 - `RUNTIME_PROOF_AMBIGUOUS_LINK`
+- `PHASE_ROLE_CAPABILITY_MISSING`
+- `PHASE_ROLE_MISMATCH`
+- `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`
 
 ## Canonical `start-from` contract
 
@@ -284,21 +511,35 @@ Required codes:
 - `STATE_PHASE_UNRECOVERABLE`
 
 ## Steps
-1. Read automation flags from scratchpad.
+1. Read automation flags from merged scratchpad and **materialize the resolved
+   phase plan** per **Configurable phase selection policy (US-0070 / DEC-0052)**:
+   detect exactly-one policy mode, expand, apply non-skippable reinstatement,
+   validate tokens/profile/ack requirements, and append plan breadcrumbs
+   (`phase_policy_mode`, `resolved_phase_plan`, `skipped_phases` + reasons) to
+   `docs/engineering/state.md` **before** any phase spawn. On failure, emit
+   deterministic phase-plan reason codes and stop (no partial schedule).
 2. Parse optional `start-from=<phase>` and validate canonical phase ID rules.
    Parse optional `--execute-bulk` and treat it as explicit one-run override.
-3. Resolve start phase using deterministic precedence:
+3. Resolve **nominal** start phase using deterministic precedence:
    - explicit argument -> resume brief -> state fallback -> fail-fast.
    - Emit `[AUTO_RESUME_ERROR] ...` message on resolver failure.
+3a. **Intersect** the nominal start anchor with the resolved phase plan (plan
+   order preserved; drop scheduled phases strictly before the anchor in canonical
+   order). **Empty intersection** → fail fast with
+   `START_FROM_PHASE_PLAN_EMPTY_INTERSECTION` and diagnostics listing
+   `resolved_phase_plan` vs `requested_start_phase` / inferred resume anchor.
+   Set the executable schedule to this intersection.
 4. Record continuation breadcrumb metadata in `docs/engineering/state.md`:
    - `invocation_mode=auto`
    - `requested_start_from`
-   - `resolved_start_phase`
+   - `resolved_start_phase` (first phase of the intersected schedule)
    - `resolution_source` (`argument|resume_brief|state_fallback`)
    - `resolution_status` (`resolved|fail-fast`)
    - `timestamp`
-5. Spawn a fresh subagent for each remaining phase in canonical order, starting
-   at the resolved phase:
+5. Spawn a fresh subagent for each remaining phase in **the intersected
+   resolved schedule order** (not the full canonical list when phases are
+   omitted), starting at `resolved_start_phase`:
+   default full path:
    intake -> discovery -> research -> architecture -> sprint plan ->
    plan verify -> execute -> QA -> verify work -> release -> refresh context.
    If `SECURITY_REVIEW=1`, run `/security-review` in a fresh security subagent:
@@ -307,13 +548,25 @@ Required codes:
    If `SECURITY_REVIEW=0` (default), skip both checks with zero overhead.
    - If `AUTO_BACKLOG_DRAIN=1`, repeat story lifecycle for next eligible OPEN
      story using deterministic selection policy until bounded stop criteria.
+     **Reload merged scratchpad phase-selection inputs and recompute the phase
+     plan at each story boundary** (same policy class as single-segment runs).
    - If bulk execute mode is active (`--execute-bulk` or
      `AUTO_EXECUTE_BULK=1`), iterate eligible planned items using
      `AUTO_EXECUTE_SELECTION` with bounded item count
      (`AUTO_EXECUTE_MAX_ITEMS`) and deterministic block/skip semantics.
+     **Reload merged scratchpad phase-selection inputs and recompute the phase
+     plan at each item boundary** (no silent revival of omitted phases).
    - In team mode with enforcement enabled, run pre-mutation scope checks against
      `TEAM_MEMBER` and `ACTIVE_TASK_IDS`; out-of-scope tasks produce deterministic
      reason codes and no writes.
+   - **US-0069 / DEC-0051**: Before each phase spawn, resolve the single-valued
+     expected role (matrix + `AUTO_ROLE_RESEARCH`, `AUTO_ROLE_PLAN_VERIFY`,
+     `AUTO_ROLE_REFRESH_CONTEXT`), enforce execute default deny / override
+     contract, and run the preflight capability gate; on failure stop with
+     `PHASE_ROLE_CAPABILITY_MISSING` (no unrelated-role spawn).
+   - **US-0069 / DEC-0051**: After each phase completes, validate isolation
+     `role` and strict-proof `role` against the preflight-resolved expected
+     role; on conflict stop with `PHASE_ROLE_MISMATCH`.
 6. Pass only the phase input files and current objective to each spawned
    subagent. Do not pass prior conversational reasoning as phase context.
 7. If `AUTO_IMPLEMENTATION_LOOP=1`, alternate fresh subagents for execute and QA
@@ -338,7 +591,9 @@ Required codes:
     phase in `docs/engineering/state.md` and includes all required fields. If
     missing/invalid/stale, stop with the appropriate reason code and remediation
     guidance (run the phase again in a fresh subagent context and write new
-    evidence).
+    evidence). Append **phase boundary status** per **Configurable phase
+    selection policy (US-0070 / DEC-0052)** (selected/skipped summary + next
+    scheduled phase).
 11b. At each phase boundary, verify strict runtime attestation tuple exists and
     is valid for the completed phase (`orchestrator_run_id`,
     `runtime_proof_id`, `phase_id`, `role`, `proof_issued_at`,

package/template/.cursor/commands/discovery.md

@@ -29,4 +29,15 @@ description: "its-magic discovery: collect design/UX inspiration and scope updat
 1. Capture references and UX notes in vision.
 2. Add new stories or updates to backlog.
 3. Refresh the PO -> TL handoff.
+4. Triad hot-surface gate (DEC-0054) when `handoffs/po_to_tl.md` is mutated:
+   - run `python scripts/enforce-triad-hot-surface.py --rollover` then `--check`
+     from repository root,
+   - on failure stop with `STATE_ARCHIVE_REQUIRED` or
+     `ARTIFACT_HOT_SURFACE_OVERSIZE`,
+   - record verification tuple fields when rollover occurred (see runbook).
+
+5. Default minimal-read posture: start at `docs/engineering/phase-context.md`,
+   then vision/backlog/tail of `handoffs/po_to_tl.md` per runbook table; escalate
+   only to a named archive `pack_ref` when unresolved (`CONTEXT_BUDGET_EXCEEDED`
+   on unbounded reads).
 

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

@@ -182,4 +182,27 @@ Release gate semantics (US-0039): mandatory gates (check-in test, QA, UAT) and n
    - Runtime boundary:
      - static generated-test PASS is necessary but not sufficient for QA PASS;
        runtime startup/connectivity/log verdict remains governed by `US-0065`.
+20. User-visible internal metadata guard (US-0071 / DEC-0053):
+   - Before completing `/execute`, run `python scripts/check-user-visible-metadata.py`
+     from the repository root (or `python scripts/check-user-visible-metadata.py --repo <root>`).
+   - On failure, stop with `USER_VISIBLE_INTERNAL_METADATA_DETECTED` and use the
+     remediation contract in `docs/engineering/runbook.md` (evidence ref, token
+     class, neutral operator copy). Do not ship planning tokens in scanned
+     operator-visible strings.
+   - If you add a new operator-facing script or binary path, update inclusive
+     scan roots in `scripts/check-user-visible-metadata.py` **and** this runbook
+     section together or fail closed with `METADATA_SANITIZATION_SCOPE_AMBIGUOUS`
+     semantics at QA/release.
+21. Triad hot-surface enforcement (DEC-0054):
+   - Before completing `/execute`, run
+     `python scripts/enforce-triad-hot-surface.py --check` from repository root
+     (or `--repo <root>`).
+   - If the check fails, run `python scripts/enforce-triad-hot-surface.py --rollover`
+     then `--check` again; if still failing, stop with `STATE_ARCHIVE_REQUIRED` or
+     `ARTIFACT_HOT_SURFACE_OVERSIZE` (no successful execute completion on oversize
+     triad hot files).
+   - When your edits touched any triad path (`docs/engineering/state.md`,
+     `handoffs/po_to_tl.md`, `docs/engineering/architecture.md`), ensure rollover
+     evidence (`boundary`, `moved`, `retained`, `pack_ref`) is recorded in the
+     execute checkpoint when packs were written.
 

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

@@ -183,6 +183,14 @@ description: "its-magic intake: clarify idea and capture story + acceptance."
    - If `USER_GUIDE_MODE=0`, add no required user-guide steps or blocking checks (zero overhead).
    - If `USER_GUIDE_MODE=1`, ensure handoff references canonical user-guide path
      `docs/user-guides/US-xxxx.md` for the new story when applicable; see runbook.
+14. Triad hot-surface gate (DEC-0054) when `handoffs/po_to_tl.md` is mutated:
+   - run `python scripts/enforce-triad-hot-surface.py --rollover` then `--check`
+     from repository root,
+   - on failure stop with `STATE_ARCHIVE_REQUIRED` or
+     `ARTIFACT_HOT_SURFACE_OVERSIZE` (no successful intake completion with an
+     oversize handoff hot file),
+   - record the verification tuple (`boundary`, `moved`, `retained`,
+     `pack_ref`) in intake outputs when rollover occurred.
 
 ## Deterministic artifact ordering contract (US-0058 / DEC-0040)
 

package/template/.cursor/commands/qa.md

@@ -57,6 +57,12 @@ verify no unresolved blockers.
    - `TEST_COMMAND` is mandatory baseline evidence for push eligibility.
    - Optional checks run only when configured and should be reported as
      `pass|fail|skipped` deterministically.
+   - **User-visible metadata guard (US-0071 / DEC-0053):** run
+     `python scripts/check-user-visible-metadata.py` (see runbook). On failure,
+     record blocking findings with reason `USER_VISIBLE_INTERNAL_METADATA_DETECTED`,
+     cite `path:line:column` evidence, token class, and remediation per runbook.
+     If the checker entrypoint is missing, fail closed with
+     `METADATA_SANITIZATION_POLICY_MISSING`.
 2. Record findings and severity.
    - Explicitly classify blockers that must prevent auto-push:
      unresolved blocking QA findings and unresolved critical issues.

package/template/.cursor/commands/refresh-context.md

@@ -27,14 +27,24 @@ description: "its-magic refresh context: compact state and decisions."
 1. Compact state and decisions into a short context pack.
 2. Update sprint summary with current status.
 3. Ensure handoffs and state are consistent.
-4. Enforce state hot-surface rollover when configured thresholds are exceeded:
-   - evaluate `STATE_HOT_MAX_LINES` and `STATE_HOT_MAX_CHECKPOINTS` from
-     `.cursor/scratchpad.md`,
-   - archive oldest low-frequency checkpoints into deterministic pack files under
-     `docs/engineering/state-archive/`,
-   - preserve only bounded recent checkpoints in `docs/engineering/state.md`,
-   - write deterministic verification evidence (archive boundary, moved entries,
-     retained hot-surface markers); fail closed on verification mismatch.
+4. Enforce **triad** hot-surface rollover when merged scratchpad thresholds are
+   exceeded (DEC-0054):
+   - read caps from `.cursor/scratchpad.md` + `.cursor/scratchpad.local.md`,
+     including `STATE_HOT_MAX_LINES`, `STATE_HOT_MAX_CHECKPOINTS`,
+     `PO_TO_TL_HOT_MAX_LINES`, `PO_TO_TL_HOT_MAX_SECTIONS`, `ARCH_HOT_MAX_LINES`,
+     and `ARCH_HOT_MAX_STORY_SECTIONS` (see runbook defaults),
+   - run `python scripts/enforce-triad-hot-surface.py --rollover` from repo root
+     (or `--repo <root>`) so `state.md`, `handoffs/po_to_tl.md`, and
+     `docs/engineering/architecture.md` archive oldest contiguous units into
+     deterministic packs under `docs/engineering/state-archive/`,
+     `handoffs/archive/`, and `docs/engineering/architecture-archive/`,
+   - immediately rerun `python scripts/enforce-triad-hot-surface.py --check`;
+     on failure stop with `STATE_ARCHIVE_REQUIRED` or
+     `ARTIFACT_HOT_SURFACE_OVERSIZE` (no successful phase completion on oversize
+     hot files),
+   - record verification tuple fields (`boundary`, `moved`, `retained`,
+     `pack_ref`) in the new `state.md` checkpoint when any rollover occurred;
+     idempotent reruns must not duplicate archived content.
 
 ## Deterministic artifact ordering contract (US-0058 / DEC-0040)
 

package/template/.cursor/commands/release.md

@@ -85,7 +85,7 @@ Strict mutation semantics:
 
 Mandatory gate order (strict, deterministic). No step may be skipped or reordered:
 
-1. **Check-in test gate** — Verify latest `TEST_COMMAND` result is passing; block on missing, stale, or failing evidence.
+1. **Check-in test gate** — Verify latest `TEST_COMMAND` result is passing; block on missing, stale, or failing evidence. When `TEST_COMMAND` runs the consolidated repo runner (`tests/run-tests.*`), passing results must include **US-0071** user-visible metadata guard coverage (positive, leak detection, idempotence); otherwise treat as incomplete release evidence for this repository (`METADATA_SANITIZATION_POLICY_MISSING` / missing regression row).
 2. **QA completion gate** — Require no unresolved blocking findings in current sprint context before proceeding.
 3. **UAT completion gate** — Require UAT artifacts populated and verified; block on placeholder, incomplete, or unresolved-fail state.
 4. **Isolation compliance gate** — Require valid per-phase isolation evidence (US-0048 / DEC-0029); block on missing/invalid/stale evidence or violation.
@@ -255,6 +255,9 @@ Guardrails:
     - Stale/reused evidence: block with `ISOLATION_EVIDENCE_STALE`
     - Orchestrator/phase executed without fresh subagent: block with
       `PHASE_CONTEXT_ISOLATION_VIOLATION`
+    - **Phase role alignment (US-0069 / DEC-0051)**: each entry's `role` must
+      match the canonical expected role for its `phase_id` (matrix + scratchpad
+      alternates as documented in `/auto`). Mismatch → `PHASE_ROLE_MISMATCH`.
     - Remediation: re-run the affected phase(s) in fresh subagent contexts,
       write new isolation evidence, then rerun `/release`.
 4b. Strict runtime proof gate (US-0056 / DEC-0038): verify strict runtime-proof
@@ -266,6 +269,11 @@ Guardrails:
     - Expired/stale proof: block with `RUNTIME_PROOF_STALE`
     - Ambiguous proof-to-checkpoint linkage: block with
       `RUNTIME_PROOF_AMBIGUOUS_LINK`
+    - **Strict-proof role alignment (US-0069 / DEC-0051)**: tuple `role` must
+      equal the sibling isolation evidence `role` and the expected phase contract
+      role; `proof_hash` must be consistent with sorted-key JSON of the tuple
+      fields per `DEC-0038`. Violation → `RUNTIME_PROOF_INVALID` or
+      `PHASE_ROLE_MISMATCH` as applicable.
     - Remediation: rerun affected phase(s), write fresh runtime proof tuples,
       then rerun `/release`.
 5. Ensure target queue row exists; set status to `unreleased` before finalization.

package/template/.cursor/rules/quality.mdc

@@ -39,4 +39,11 @@ globs: ["**/*"]
   `RUNTIME_STACK_PROFILE_UNRESOLVED`.
   Include startup command/profile, runtime mode, health result, retry ledger,
   and log summary in QA artifacts.
+- User-visible internal metadata (US-0071 / DEC-0053): do not introduce
+  planning-shaped tokens (`US-[0-9]{4}`, `DEC-[0-9]{4}`, `R-[0-9]{4}`) into
+  operator-visible strings under inclusive scan roots (`bin/`, root installers,
+  `packaging/**`, `scripts/validate-and-push.*`). Use
+  `python scripts/check-user-visible-metadata.py` before handoff; on leakage use
+  `USER_VISIBLE_INTERNAL_METADATA_DETECTED` with path evidence and remediation
+  per `docs/engineering/runbook.md`.
 

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

@@ -1,7 +1,8 @@
-# its-magic scratchpad (local overrides example)
+# its-magic scratchpad (framework default catalog — Model B / DEC-0055)
 #
-# Copy this file to `.cursor/scratchpad.local.md` and set personal overrides.
-# Local values override `.cursor/scratchpad.md` and should stay gitignored.
+# Copy this file to `.cursor/scratchpad.local.md` for personal overrides (gitignored).
+# Merge precedence: local > materialized `.cursor/scratchpad.md` > this example
+# (installers materialize the baseline from template when missing).
 #
 # Core behavior
 # - MAGIC_CONTEXT_STRICT: 0|1 (require context refresh after code changes)
@@ -55,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
@@ -93,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
@@ -107,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
@@ -116,8 +146,12 @@ ID_NAMESPACE_BOOTSTRAP=0
 TOKEN_PROFILE=balanced
 STATE_HOT_MAX_LINES=1200
 STATE_HOT_MAX_CHECKPOINTS=80
-#
-# Publish targets
+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 (US-0054)
 # - RELEASE_PUBLISH_MODE: disabled|confirm|auto
 #   - disabled: skip post-release publish target execution
 #   - confirm: require explicit operator confirmation before publish (default)
@@ -127,6 +161,7 @@ STATE_HOT_MAX_CHECKPOINTS=80
 RELEASE_PUBLISH_MODE=confirm
 RELEASE_TARGETS_FILE=docs/engineering/release-targets.json
 RELEASE_TARGETS_DEFAULT=
+
 #
 # Security review
 # - SECURITY_REVIEW: 0|1 (enable optional security/compliance review; default off)
@@ -135,8 +170,8 @@ RELEASE_TARGETS_DEFAULT=
 #   When SECURITY_REVIEW=0, the workflow adds zero security-review overhead.
 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)
@@ -145,17 +180,19 @@ COMPLIANCE_PROFILES=GDPR
 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.
-SPEC_PACK_MODE=0
 USER_GUIDE_MODE=0