its-magic 0.1.3-2 → 0.1.3-3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.3-2",
+  "version": "0.1.3-3",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

package/scripts/check_intake_template_parity.py

@@ -13,6 +13,9 @@ Scoped modes (DEC-0073 §10 / US-0090):
   --scope=us-0096               DEC-0082 delivery modes surfaces (US-0096).
   --scope=project-readme        DEC-0083 project README bootstrap surfaces (US-0097).
   --scope=dev-environment       DEC-0084 dev auto-launch profile surfaces (US-0098).
+  --scope=sovereign-parallel-dev DEC-0108 parallel instance arbitrage surfaces (US-0108).
+  --scope=sovereign-self-healing-deploy DEC-0109 self-healing deploy loop surfaces (US-0109).
+  --scope=release-trigger-adapter DEC-0111 release trigger adapter surfaces (US-0111).
   --scope=all              union of all tables.
 """
 
@@ -297,6 +300,115 @@ DOWNSTREAM_CI_GUARD_PAIRS: tuple[tuple[str, str], ...] = (
     ),
 )
 
+SOVEREIGN_ROLE_MANIFEST_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        ".cursor/sovereign-role-manifest.yaml",
+        "template/.cursor/sovereign-role-manifest.yaml.example",
+    ),
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        "scripts/sovereign_role_manifest_validate.py",
+        "template/scripts/sovereign_role_manifest_validate.py",
+    ),
+    (
+        "scripts/sovereign_role_manifest_lib.py",
+        "template/scripts/sovereign_role_manifest_lib.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+    (
+        "docs/engineering/reason_codes.md",
+        "template/docs/engineering/reason_codes.md",
+    ),
+    (
+        "handoffs/sovereign_role_reviews.jsonl",
+        "template/handoffs/sovereign_role_reviews.jsonl",
+    ),
+)
+
+SOVEREIGN_PARALLEL_DEV_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        "scripts/parallel_dev_arbiter.py",
+        "template/scripts/parallel_dev_arbiter.py",
+    ),
+    (
+        "tests/us0108_contract_test.py",
+        "template/tests/us0108_contract_test.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+    (
+        "docs/engineering/reason_codes.md",
+        "template/docs/engineering/reason_codes.md",
+    ),
+    (
+        "scripts/check_intake_template_parity.py",
+        "template/scripts/check_intake_template_parity.py",
+    ),
+)
+
+SOVEREIGN_SELF_HEALING_DEPLOY_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        ".cursor/scratchpad.md",
+        "template/.cursor/scratchpad.md",
+    ),
+    (
+        "scripts/self_healing_deploy_lib.py",
+        "template/scripts/self_healing_deploy_lib.py",
+    ),
+    (
+        "scripts/self_healing_deploy_validate.py",
+        "template/scripts/self_healing_deploy_validate.py",
+    ),
+    (
+        "tests/us0109_contract_test.py",
+        "template/tests/us0109_contract_test.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+    (
+        "docs/engineering/reason_codes.md",
+        "template/docs/engineering/reason_codes.md",
+    ),
+)
+
+# US-0111 release trigger adapter parity pairs
+RELEASE_TRIGGER_ADAPTER_PAIRS: tuple[tuple[str, str], ...] = (
+    (
+        "scripts/release_trigger_adapters.py",
+        "template/scripts/release_trigger_adapters.py",
+    ),
+    (
+        "tests/us0111_contract_test.py",
+        "template/tests/us0111_contract_test.py",
+    ),
+    (
+        "docs/engineering/runbook.md",
+        "template/docs/engineering/runbook.md",
+    ),
+    (
+        "docs/engineering/reason_codes.md",
+        "template/docs/engineering/reason_codes.md",
+    ),
+    (
+        "scripts/check_intake_template_parity.py",
+        "template/scripts/check_intake_template_parity.py",
+    ),
+)
+
 SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
     "intake": INTAKE_TEMPLATE_PAIRS,
     "caveman-compress": CAVEMAN_COMPRESS_PAIRS,
@@ -312,6 +424,10 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
     "release-changelog": RELEASE_CHANGELOG_PAIRS,
     "model-tier": MODEL_TIER_PAIRS,
     "model-tier-overrides": MODEL_TIER_OVERRIDES_PAIRS,
+    "sovereign-role-manifest": SOVEREIGN_ROLE_MANIFEST_PAIRS,
+    "sovereign-parallel-dev": SOVEREIGN_PARALLEL_DEV_PAIRS,
+    "sovereign-self-healing-deploy": SOVEREIGN_SELF_HEALING_DEPLOY_PAIRS,
+    "release-trigger-adapter": RELEASE_TRIGGER_ADAPTER_PAIRS,
     "all": (
         INTAKE_TEMPLATE_PAIRS
         + CAVEMAN_COMPRESS_PAIRS
@@ -327,6 +443,9 @@ SCOPES: dict[str, tuple[tuple[str, str], ...]] = {
         + RELEASE_CHANGELOG_PAIRS
         + MODEL_TIER_PAIRS
         + MODEL_TIER_OVERRIDES_PAIRS
+        + SOVEREIGN_ROLE_MANIFEST_PAIRS
+        + SOVEREIGN_SELF_HEALING_DEPLOY_PAIRS
+        + RELEASE_TRIGGER_ADAPTER_PAIRS
     ),
 }
 

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

@@ -1,378 +1,539 @@
-# its-magic scratchpad (framework default catalog — Model B / DEC-0055)
-#
-# 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)
-# - LOOP_UNTIL_GREEN: 0|1 (optional test loop)
-# - RUN_TESTS_ON_EDIT: 0|1 (run tests after edits)
-# - AUTO_IMPLEMENTATION_LOOP: 0|1 (auto cycle execute->qa->execute)
-# - AUTO_LOOP_MAX_CYCLES: integer >= 1 (safety guard)
-# - AUTO_PAUSE_REQUEST: 0|1 (request graceful stop at next safe boundary)
-# - AUTO_PAUSE_POLICY: after_task|after_phase (safe stop boundary)
-# - DONE: 0|1 (stop hook loops)
-MAGIC_CONTEXT_STRICT=1
-LOOP_UNTIL_GREEN=0
-RUN_TESTS_ON_EDIT=0
-AUTO_IMPLEMENTATION_LOOP=0
-AUTO_LOOP_MAX_CYCLES=5
-AUTO_PAUSE_REQUEST=0
-AUTO_PAUSE_POLICY=after_phase
-DONE=0
-#
-# Benchmarking
-# - MAGIC_BENCH_SESSION: free-form id for live benchmark logging
-MAGIC_BENCH_SESSION=
-#
-# Automation
-# - AUTO_FLOW_MODE: manual|auto_until_decision|full_autonomy
-#   - manual: operator invokes phases explicitly (default when unset)
-#   - auto_until_decision: continuous until decision_gate
-#   - full_autonomy: outer-driver loop + relaxable transient stops + drain-without-pause (default-off; US-0092 / DEC-0078)
-#   - opt-in enablement: AUTO_FLOW_MODE=full_autonomy
-# - AUTO_BLOCK_RETRY_MAX: integer >= 1 (default 3; per (story_id, stop_reason) recoverable retries before BLOCK_RETRY_CAP_EXHAUSTED)
-# - AUTO_OUTER_DRIVER_TIMEOUT_SECONDS: optional integer; unset = no hook timeout (timeout -> exit 124)
-# Interaction (full_autonomy): PHASE_MODE/PERMISSION_MODE orthogonal; AUTO_BACKLOG_DRAIN/AUTO_BUG_QUEUE per US-0044/US-0087;
-#   AUTO_LOOP_MAX_CYCLES/AUTO_BACKLOG_MAX_STORIES hard caps; TOKEN_PROFILE = context breadth / token cost only (DEC-0062 / US-0092).
-# - PHASE_MODE: interactive|auto
-# - PERMISSION_MODE: interactive|auto
-# - AUTO_INSTALL_DEPS: 0|1
-# - AUTO_RELEASE_NOTES: 0|1
-# - AUTO_BACKLOG_DRAIN: 0|1 (continue across multiple stories when enabled)
-# - AUTO_BACKLOG_MAX_STORIES: integer >= 1 (max stories per auto run when drain enabled)
-# - AUTO_BACKLOG_ON_BLOCK: stop|skip (behavior when a story blocks)
-# - AUTO_STORY_SELECTION: priority_then_backlog_order
-# - AUTO_EXECUTE_BULK: 0|1 (explicit bulk execute orchestration mode)
-# - AUTO_EXECUTE_MAX_ITEMS: integer >= 1 (max planned items per bulk execute run)
-# - AUTO_EXECUTE_ON_BLOCK: stop|skip (behavior when a planned item blocks)
-# - AUTO_EXECUTE_SELECTION: planned_then_priority
-# - AUTO_TEAM_SCOPE_ENFORCE: 0|1 (when TEAM_MODE=1, enforce TEAM_MEMBER + ACTIVE_TASK_IDS)
-# Optional bug-queue mode (US-0087) — default-off when absent/unset after merge
-# - AUTO_BUG_QUEUE: 0|1 (1 = enable bug-targeted /auto; mutex vs AUTO_BACKLOG_DRAIN without bug-target argv)
-# - AUTO_BUG_TARGET: all-open|BUG-#### (required when AUTO_BUG_QUEUE=1 unless bug-target= argv supplies target)
-# - AUTO_BUG_MAX_ITEMS: non-negative integer (0 or unset = no cap for all-open queue per run)
-# - AUTO_BUG_ON_BLOCK: stop|skip (bug segment pause/stop boundary)
-# Quiet mode (US-0088) — suppress routine per-phase success chatter only
-# - AUTO_QUIET: 0|1 (default 0; 1 = quiet routine notifications)
-#   Non-suppressible: decision_gate, errors, pause, loop_max, blocked, missing inputs.
-#   Orthogonal to TOKEN_PROFILE (DEC-0035 / US-0080) — TOKEN_PROFILE controls
-#   context breadth / token cost, not notification policy.
-AUTO_QUIET=0
-AUTO_FLOW_MODE=auto_until_decision
-PHASE_MODE=interactive
-PERMISSION_MODE=interactive
-AUTO_INSTALL_DEPS=0
-AUTO_RELEASE_NOTES=1
-AUTO_BACKLOG_DRAIN=0
-AUTO_BACKLOG_MAX_STORIES=1
-AUTO_BACKLOG_ON_BLOCK=stop
-AUTO_STORY_SELECTION=priority_then_backlog_order
-AUTO_EXECUTE_BULK=0
-AUTO_EXECUTE_MAX_ITEMS=1
-AUTO_EXECUTE_ON_BLOCK=stop
-AUTO_EXECUTE_SELECTION=planned_then_priority
-AUTO_TEAM_SCOPE_ENFORCE=1
-AUTO_BUG_QUEUE=0
-AUTO_BUG_TARGET=
-AUTO_BUG_MAX_ITEMS=0
-AUTO_BUG_ON_BLOCK=stop
-AUTO_BLOCK_RETRY_MAX=3
-#
-# `/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
-# - ACTIVE_TASK_IDS: comma-separated task ids (for example T-12,T-13)
-TEAM_MODE=0
-TEAM_MEMBER=
-ACTIVE_TASK_IDS=
-#
-# Sprint planning
-# - SPRINT_MAX_TASKS: integer >= 1 (max atomic tasks per sprint, default 12)
-# - SPRINT_AUTO_SPLIT: 0|1 (propose splitting when over threshold)
-# - SPRINT_BULK_MAX_STORIES: integer >= 1 (candidate stories when /sprint-plan --bulk)
-# - SPRINT_BULK_MAX_SPRINTS: integer >= 1 (generated sprints per /sprint-plan --bulk run)
-# - SPRINT_BULK_SELECTION: priority_then_backlog_order
-SPRINT_MAX_TASKS=12
-SPRINT_AUTO_SPLIT=1
-SPRINT_BULK_MAX_STORIES=5
-SPRINT_BULK_MAX_SPRINTS=3
-SPRINT_BULK_SELECTION=priority_then_backlog_order
-#
-# Remote execution (US-0086 / US-0084 / US-0064)
-# - REMOTE_EXECUTION: 0|1
-# - REMOTE_CONFIG: path to remote config
-# - AUTO_REMOTE_AUTOMATION_PROFILE: off|deterministic_v1 (default off/manual-safe)
-# - AUTO_REMOTE_ENVIRONMENT_LABEL: local|docker|ssh (names-only evidence label)
-REMOTE_EXECUTION=0
-REMOTE_CONFIG=.cursor/remote.json
-AUTO_REMOTE_AUTOMATION_PROFILE=off
-AUTO_REMOTE_ENVIRONMENT_LABEL=local
-#
-# Sync policy
-# - SYNC_POLICY_MODE: disabled|manual|by_phase|by_milestone|custom_phase_list
-# - SYNC_CUSTOM_PHASES: comma-separated canonical phase IDs; only used when
-#   SYNC_POLICY_MODE=custom_phase_list
-# - ALLOW_AUTO_PUSH: 0|1 (default off; explicit opt-in required)
-# - AUTO_PUSH_BRANCH_ALLOWLIST: comma-separated branches/patterns eligible for
-#   auto-push. Protected/default branches are denied unless allowlisted.
-SYNC_POLICY_MODE=manual
-SYNC_CUSTOM_PHASES=
-ALLOW_AUTO_PUSH=0
-AUTO_PUSH_BRANCH_ALLOWLIST=
-#
-# 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
-#   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)
-#   TOKEN_PROFILE controls context breadth / token cost only (DEC-0062 / US-0092).
-#   - lean: lowest context breadth / token cost defaults
-#   - balanced: default profile; moderate context breadth
-#   - full: highest context breadth / token cost for complex work
-# - STATE_HOT_MAX_LINES: integer >= 200 (hot-surface soft cap trigger for
-#   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.
-#
-# Delivery mode (US-0096 / DEC-0082)
-# - DELIVERY_MODE: standard|ultra_lean|mega_quick (default standard; unset = standard)
-# - LEAN_MEMORY_READ: 0|1 (default 1 when pack/active-context paths exist)
-# - LEAN_MEMORY_WRITE: 0|1 (default 1 when pack/active-context paths exist)
-# - LEAN_COLD_READ_MAX_SECTIONS: int >= 1 (default 4)
-# - LEAN_STATE_INDEX_ROWS: int >= 30 (default 80)
-# - AUTO_DELIVERY_ROUTING: scratchpad_only|backlog_then_scratchpad (default scratchpad_only)
-# Tranche A default hot caps (US-0096): 1000/650/3000 — explicit values override.
-DELIVERY_MODE=standard
-LEAN_MEMORY_READ=1
-LEAN_MEMORY_WRITE=1
-LEAN_COLD_READ_MAX_SECTIONS=4
-LEAN_STATE_INDEX_ROWS=80
-AUTO_DELIVERY_ROUTING=scratchpad_only
-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=1000
-STATE_HOT_MAX_CHECKPOINTS=80
-PO_TO_TL_HOT_MAX_LINES=650
-PO_TO_TL_HOT_MAX_SECTIONS=60
-ARCH_HOT_MAX_LINES=3000
-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)
-#   - auto: allow publish without confirmation (explicit opt-in)
-# - RELEASE_TARGETS_FILE: canonical target config path
-# - RELEASE_TARGETS_DEFAULT: comma-separated default target IDs (optional)
-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)
-# - COMPLIANCE_PROFILES: comma-separated values (GDPR,SOC2,HIPAA,PCI-DSS,ISO27001)
-#   Empty value means general security best practices only.
-#   When SECURITY_REVIEW=0, the workflow adds zero security-review overhead.
-SECURITY_REVIEW=0
-COMPLIANCE_PROFILES=GDPR
-
-# 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)
-# - COMPATIBILITY_SOURCES: semicolon-separated sources
-#   (repo=<path|url>,module=<id>,contract=<path|url>,docs=<path|url>)
-CROSS_REPO_OBSERVABILITY=0
-COMPATIBILITY_GATE_ON_CRITICAL=1
-COMPATIBILITY_SOURCES=
-
-# 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 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
-
-# Documentation audience profile (DEC-0059)
-# - DOC_AUDIENCE_PROFILE: user|developer|both (empty -> both during transition)
-# - DOC_DETAIL_LEVEL: concise|balanced|technical-deep (empty -> balanced during transition)
-DOC_AUDIENCE_PROFILE=both
-DOC_DETAIL_LEVEL=balanced
-
-# README feature coverage gate (US-0091 / DEC-0074)
-# - README_FEATURE_COVERAGE_ENFORCE: 0|1 (default 0 until backfill + --report green)
-README_FEATURE_COVERAGE_ENFORCE=1
-
-#
-# ## Project README coverage (US-0097 / DEC-0083)
-# Project-owned root README bootstrap + per-story catalog growth.
-# - PROJECT_README_ENFORCE: 0|1 (default 1 post-bootstrap)
-#   When 0, /release step 3g skips (migration/grandfathering only). When 1, blocking.
-#   Flip 0→1 only after validate_project_readme_coverage.py --report shows coverage_missing: [].
-# - FRAMEWORK_KIT_REPO: 0|1 (default 0)
-#   When 1 (its-magic dev kit repo only), skip execute 23a/23b and project validator root check.
-#   Consumer repos never set FRAMEWORK_KIT_REPO=1.
-PROJECT_README_ENFORCE=1
-FRAMEWORK_KIT_REPO=0
-
-#
-# ## Browser UAT self-test (US-0093 / DEC-0079)
-# Two-tier browser probe: stdlib lib classifies + agent owns Cursor browser MCP (BUG-0006).
-# - UAT_BROWSER_PROBE_MODE: cursor|http_fallback|playwright_fallback (default cursor)
-#   - cursor: agent executes MCP sequence; lib emits plan + UAT_PROBE_UNRESOLVED until evidence
-#   - http_fallback: stdlib HTTP GET (CI recipe — set this in CI)
-#   - playwright_fallback: subprocess Playwright primary; HTTP fallback when missing
-# - UAT_BROWSER_FALLBACK_CHAIN: 0|1 (default 1; enable HTTP → Playwright after MCP unavailable)
-# - UAT_PROCESS_HEALTH_POLL_SECONDS: positive int (default 60; process_health readiness cap)
-# - UAT_PROCESS_HEALTH_POLL_INTERVAL_SECONDS: positive int (default 2; poll interval)
-# - DEV_SERVER_PORT: int (optional; URL/port inference override)
-# - DEV_SERVER_COMMAND: shell command (optional; process_health startup override)
-# Interaction: orthogonal to PERMISSION_MODE and Cursor browser approval modes (manual / allow-list /
-#   auto-run per vendor docs). Health URLs from docs/engineering/runtime-connectivity.md first.
-UAT_BROWSER_PROBE_MODE=cursor
-UAT_BROWSER_FALLBACK_CHAIN=1
-UAT_PROCESS_HEALTH_POLL_SECONDS=60
-UAT_PROCESS_HEALTH_POLL_INTERVAL_SECONDS=2
-DEV_SERVER_PORT=
-DEV_SERVER_COMMAND=
-
-#
-# ## Dev environment auto-launch (US-0098 / DEC-0084)
-# Execute-phase bounded rebuild/relaunch + Connect surfacing — distinct from US-0065 phase QA,
-# US-0086 test routing, and US-0067 release hints. Orthogonal to AUTO_REMOTE_AUTOMATION_PROFILE.
-# When off, execute step 24 skipped with zero overhead.
-# - DEV_AUTO_LAUNCH_PROFILE: off|deterministic_v1 (default off)
-# - DEV_ENVIRONMENT_CONFIG: repo-relative path (default .cursor/dev-environment.json)
-DEV_AUTO_LAUNCH_PROFILE=off
-DEV_ENVIRONMENT_CONFIG=.cursor/dev-environment.json
-
-#
-# ## Caveman mode (US-0089)
-# Response-side voice toggle. Default off. Composition is orthogonal to
-# TOKEN_PROFILE (DEC-0035 / US-0080) and AUTO_QUIET (US-0088) --
-# TOKEN_PROFILE controls context breadth, CAVEMAN_MODE controls reply voice;
-# neither substitutes for the other.
-# - CAVEMAN_MODE: 0|1 (default 0; absence = 0)
-# - CAVEMAN_LEVEL: lite|full|ultra (empty; with MODE=1 empty -> treat as full;
-#   unknown value -> CAVEMAN_LEVEL_UNKNOWN and fall back to pre-US-0089 voice)
-#
-# ## Caveman input compression (US-0090 / DEC-0073)
-# Input-side prose minification via scripts/caveman_compress_input.py. Default off.
-# Orthogonal to CAVEMAN_MODE (reply voice) and TOKEN_PROFILE (context breadth).
-# - CAVEMAN_COMPRESS_INPUT: 0|1 (default 0) -- activation gate; must be 1 for --write
-# - CAVEMAN_FILE_SCOPE: string (empty default) -- allow-list of files eligible for compression:
-#     * empty: no files in scope (fail-closed on --write with CAVEMAN_COMPRESS_SCOPE_EMPTY)
-#     * named profile: e.g. docs-prose-only (user-guides, runbook, state-archive, handoffs/archive)
-#     * raw globs: e.g. docs/user-guides/**/*.md,handoffs/archive/*.md (forward slashes only)
-#     * hybrid: profile:docs-prose-only;globs:handoffs/archive/*.md
-#   Mutation requires COMPRESS_INPUT=1 + non-empty scope + CLI --write; use --dry-run first.
-#   Originals land in docs/.caveman-originals/<path>; deny-list always wins over allow.
-CAVEMAN_MODE=0
-CAVEMAN_LEVEL=
-CAVEMAN_COMPRESS_INPUT=0
-CAVEMAN_FILE_SCOPE=
-
-#
-# ## Per-phase model tier selection (US-0101 / DEC-0086)
-# MODEL_TIER selects LLM model strength (which model runs).
-# MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — these are independent axes;
-#   none substitutes for the other (DEC-0062 / US-0080 / US-0096).
-# - MODEL_TIER_DEFAULT: cheap|balanced|strong (default balanced)
-# - MODEL_TIER_<PHASE>: cheap|balanced|strong (per-phase override; PHASE = canonical phase id)
-#   Default matrix (architecture-locked):
-#     cheap    — ask, refresh-context, memory-audit, status-reconcile, pause
-#     balanced — intake, discovery, research, release, plan-verify
-#     strong   — architecture, execute, quick, qa, verify-work, security-review
-#     (inherit parent) — auto (orchestrator always inherits parent model)
-# - MODEL_CATALOG: path to local slug catalog (default .cursor/model-catalog.local.json)
-# - MODEL_RESOLVE: alias_only|local_catalog|role_catalog (default alias_only)
-# - MODEL_FALLBACK: fallback when catalog lookup fails (default inherit)
-# - MODEL_PROVIDER_MODE: cursor|api (default cursor)
-#   cursor = all subagents route through Cursor-managed infrastructure
-#   api = operator uses BYOK via Cursor Settings → Models → API Key
-#   Known limitation: subagents do NOT inherit custom API keys/base URLs.
-#
-# ## Direct per-phase model slug override (US-0102 / DEC-0087) — set in this local file only
-# Precedence: MODEL_<PHASE> > MODEL_TIER_<PHASE> > MODEL_TIER_DEFAULT > Cursor alias
-# - MODEL_<PHASE>: direct vendor slug (e.g. MODEL_EXECUTE=<your-vendor-slug>, MODEL_ASK=<your-vendor-slug>)
-# - MODEL_RESOLVE=role_catalog enables phase→role→catalog slug lookup (requires v2 catalog with roles section)
-MODEL_TIER_DEFAULT=balanced
-MODEL_CATALOG=.cursor/model-catalog.local.json
-MODEL_RESOLVE=alias_only
-MODEL_FALLBACK=inherit
-MODEL_PROVIDER_MODE=cursor
-
-# Per-phase tier overrides for this project (uncomment and adjust as needed):
-#MODEL_TIER_INTAKE=balanced
-#MODEL_TIER_DISCOVERY=cheap
-#MODEL_TIER_RESEARCH=balanced
-#MODEL_TIER_ARCHITECTURE=strong
-#MODEL_TIER_SPRINT-PLAN=strong
-#MODEL_TIER_PLAN-VERIFY=balanced
-#MODEL_TIER_EXECUTE=cheap
-#MODEL_TIER_QA=strong
-#MODEL_TIER_VERIFY-WORK=strong
-#MODEL_TIER_RELEASE=balanced
-#MODEL_TIER_REFRESH-CONTEXT=cheap
-
-# Direct per-phase slug overrides (US-0102 — uncomment and set vendor slugs):
-#MODEL_ASK=<your-vendor-slug>
-#MODEL_EXECUTE=<your-vendor-slug>
-#MODEL_QA=<your-vendor-slug>
-
-# Use a vendor catalog instead of Cursor aliases:
-#   cp .cursor/model-catalog.local.example.level-2-complex.json .cursor/model-catalog.local.json
-#MODEL_RESOLVE=local_catalog
-# Role-based catalog preset (US-0102):
-#   cp .cursor/model-catalog.local.example.role-based-balanced.json .cursor/model-catalog.local.json
-#MODEL_RESOLVE=role_catalog
+# its-magic scratchpad (framework default catalog — Model B / DEC-0055)
+#
+# 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)
+# - LOOP_UNTIL_GREEN: 0|1 (optional test loop)
+# - RUN_TESTS_ON_EDIT: 0|1 (run tests after edits)
+# - AUTO_IMPLEMENTATION_LOOP: 0|1 (auto cycle execute->qa->execute)
+# - AUTO_LOOP_MAX_CYCLES: integer >= 1 (safety guard)
+# - AUTO_PAUSE_REQUEST: 0|1 (request graceful stop at next safe boundary)
+# - AUTO_PAUSE_POLICY: after_task|after_phase (safe stop boundary)
+# - DONE: 0|1 (stop hook loops)
+MAGIC_CONTEXT_STRICT=1
+LOOP_UNTIL_GREEN=1
+RUN_TESTS_ON_EDIT=1
+AUTO_IMPLEMENTATION_LOOP=1
+AUTO_LOOP_MAX_CYCLES=5
+AUTO_PAUSE_REQUEST=0
+AUTO_PAUSE_POLICY=after_phase
+DONE=0
+#
+# Benchmarking
+# - MAGIC_BENCH_SESSION: free-form id for live benchmark logging
+MAGIC_BENCH_SESSION=
+#
+# Automation
+# - AUTO_FLOW_MODE: manual|auto_until_decision|full_autonomy
+#   - manual: operator invokes phases explicitly (default when unset)
+#   - auto_until_decision: continuous until decision_gate
+#   - full_autonomy: outer-driver loop + relaxable transient stops + drain-without-pause (default-off; US-0092 / DEC-0078)
+#   - opt-in enablement: AUTO_FLOW_MODE=full_autonomy
+# - AUTO_BLOCK_RETRY_MAX: integer >= 1 (default 3; per (story_id, stop_reason) recoverable retries before BLOCK_RETRY_CAP_EXHAUSTED)
+# - AUTO_OUTER_DRIVER_TIMEOUT_SECONDS: optional integer; unset = no hook timeout (timeout -> exit 124)
+# Interaction (full_autonomy): PHASE_MODE/PERMISSION_MODE orthogonal; AUTO_BACKLOG_DRAIN/AUTO_BUG_QUEUE per US-0044/US-0087;
+#   AUTO_LOOP_MAX_CYCLES/AUTO_BACKLOG_MAX_STORIES hard caps; TOKEN_PROFILE = context breadth / token cost only (DEC-0062 / US-0092).
+# - PHASE_MODE: interactive|auto
+# - PERMISSION_MODE: interactive|auto
+# - AUTO_INSTALL_DEPS: 0|1
+# - AUTO_RELEASE_NOTES: 0|1
+# - AUTO_BACKLOG_DRAIN: 0|1 (continue across multiple stories when enabled)
+# - AUTO_BACKLOG_MAX_STORIES: integer >= 1 (max stories per auto run when drain enabled)
+# - AUTO_BACKLOG_ON_BLOCK: stop|skip (behavior when a story blocks)
+# - AUTO_STORY_SELECTION: priority_then_backlog_order
+# - AUTO_EXECUTE_BULK: 0|1 (explicit bulk execute orchestration mode)
+# - AUTO_EXECUTE_MAX_ITEMS: integer >= 1 (max planned items per bulk execute run)
+# - AUTO_EXECUTE_ON_BLOCK: stop|skip (behavior when a planned item blocks)
+# - AUTO_EXECUTE_SELECTION: planned_then_priority
+# - AUTO_TEAM_SCOPE_ENFORCE: 0|1 (when TEAM_MODE=1, enforce TEAM_MEMBER + ACTIVE_TASK_IDS)
+# Optional bug-queue mode (US-0087) — default-off when absent/unset after merge
+# - AUTO_BUG_QUEUE: 0|1 (1 = enable bug-targeted /auto; mutex vs AUTO_BACKLOG_DRAIN without bug-target argv)
+# - AUTO_BUG_TARGET: all-open|BUG-#### (required when AUTO_BUG_QUEUE=1 unless bug-target= argv supplies target)
+# - AUTO_BUG_MAX_ITEMS: non-negative integer (0 or unset = no cap for all-open queue per run)
+# - AUTO_BUG_ON_BLOCK: stop|skip (bug segment pause/stop boundary)
+# Quiet mode (US-0088) — suppress routine per-phase success chatter only
+# - AUTO_QUIET: 0|1 (default 0; 1 = quiet routine notifications)
+#   Non-suppressible: decision_gate, errors, pause, loop_max, blocked, missing inputs.
+#   Orthogonal to TOKEN_PROFILE (DEC-0035 / US-0080) — TOKEN_PROFILE controls
+#   context breadth / token cost, not notification policy.
+AUTO_QUIET=1
+AUTO_FLOW_MODE=full_autonomy
+PHASE_MODE=auto
+PERMISSION_MODE=auto
+AUTO_INSTALL_DEPS=1
+AUTO_RELEASE_NOTES=1
+AUTO_BACKLOG_DRAIN=1
+AUTO_BACKLOG_MAX_STORIES=10
+AUTO_BACKLOG_ON_BLOCK=skip
+AUTO_STORY_SELECTION=priority_then_backlog_order
+AUTO_EXECUTE_BULK=0
+AUTO_EXECUTE_MAX_ITEMS=1
+AUTO_EXECUTE_ON_BLOCK=skip
+AUTO_EXECUTE_SELECTION=planned_then_priority
+AUTO_TEAM_SCOPE_ENFORCE=1
+AUTO_BUG_QUEUE=0
+AUTO_BUG_TARGET=
+AUTO_BUG_MAX_ITEMS=0
+AUTO_BUG_ON_BLOCK=skip
+AUTO_BLOCK_RETRY_MAX=5
+#
+# `/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
+# - ACTIVE_TASK_IDS: comma-separated task ids (for example T-12,T-13)
+TEAM_MODE=0
+TEAM_MEMBER=
+ACTIVE_TASK_IDS=
+#
+# Sprint planning
+# - SPRINT_MAX_TASKS: integer >= 1 (max atomic tasks per sprint, default 12)
+# - SPRINT_AUTO_SPLIT: 0|1 (propose splitting when over threshold)
+# - SPRINT_BULK_MAX_STORIES: integer >= 1 (candidate stories when /sprint-plan --bulk)
+# - SPRINT_BULK_MAX_SPRINTS: integer >= 1 (generated sprints per /sprint-plan --bulk run)
+# - SPRINT_BULK_SELECTION: priority_then_backlog_order
+SPRINT_MAX_TASKS=12
+SPRINT_AUTO_SPLIT=1
+SPRINT_BULK_MAX_STORIES=5
+SPRINT_BULK_MAX_SPRINTS=3
+SPRINT_BULK_SELECTION=priority_then_backlog_order
+#
+# Remote execution (US-0086 / US-0084 / US-0064)
+# - REMOTE_EXECUTION: 0|1
+# - REMOTE_CONFIG: path to remote config
+# - AUTO_REMOTE_AUTOMATION_PROFILE: off|deterministic_v1 (default off/manual-safe)
+# - AUTO_REMOTE_ENVIRONMENT_LABEL: local|docker|ssh (names-only evidence label)
+REMOTE_EXECUTION=0
+REMOTE_CONFIG=.cursor/remote.json
+AUTO_REMOTE_AUTOMATION_PROFILE=off
+AUTO_REMOTE_ENVIRONMENT_LABEL=local
+#
+# Sync policy
+# - SYNC_POLICY_MODE: disabled|manual|by_phase|by_milestone|custom_phase_list
+# - SYNC_CUSTOM_PHASES: comma-separated canonical phase IDs; only used when
+#   SYNC_POLICY_MODE=custom_phase_list
+# - ALLOW_AUTO_PUSH: 0|1 (default off; explicit opt-in required)
+# - AUTO_PUSH_BRANCH_ALLOWLIST: comma-separated branches/patterns eligible for
+#   auto-push. Protected/default branches are denied unless allowlisted.
+SYNC_POLICY_MODE=disabled
+SYNC_CUSTOM_PHASES=
+ALLOW_AUTO_PUSH=1
+AUTO_PUSH_BRANCH_ALLOWLIST=main
+#
+# 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
+#   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)
+#   TOKEN_PROFILE controls context breadth / token cost only (DEC-0062 / US-0092).
+#   - lean: lowest context breadth / token cost defaults
+#   - balanced: default profile; moderate context breadth
+#   - full: highest context breadth / token cost for complex work
+# - STATE_HOT_MAX_LINES: integer >= 200 (hot-surface soft cap trigger for
+#   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.
+#
+# Delivery mode (US-0096 / DEC-0082)
+# - DELIVERY_MODE: standard|ultra_lean|mega_quick (default standard; unset = standard)
+# - LEAN_MEMORY_READ: 0|1 (default 1 when pack/active-context paths exist)
+# - LEAN_MEMORY_WRITE: 0|1 (default 1 when pack/active-context paths exist)
+# - LEAN_COLD_READ_MAX_SECTIONS: int >= 1 (default 4)
+# - LEAN_STATE_INDEX_ROWS: int >= 30 (default 80)
+# - AUTO_DELIVERY_ROUTING: scratchpad_only|backlog_then_scratchpad (default scratchpad_only)
+# Tranche A default hot caps (US-0096): example uses 1000/650/3000; explicit values here override.
+DELIVERY_MODE=standard
+LEAN_MEMORY_READ=1
+LEAN_MEMORY_WRITE=1
+LEAN_COLD_READ_MAX_SECTIONS=4
+LEAN_STATE_INDEX_ROWS=80
+AUTO_DELIVERY_ROUTING=scratchpad_only
+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=1000
+STATE_HOT_MAX_CHECKPOINTS=80
+PO_TO_TL_HOT_MAX_LINES=650
+PO_TO_TL_HOT_MAX_SECTIONS=60
+ARCH_HOT_MAX_LINES=3000
+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)
+#   - auto: allow publish without confirmation (explicit opt-in)
+# - RELEASE_TARGETS_FILE: canonical target config path
+# - RELEASE_TARGETS_DEFAULT: comma-separated default target IDs (optional)
+RELEASE_PUBLISH_MODE=disabled
+RELEASE_TARGETS_FILE=docs/engineering/release-targets.json
+RELEASE_TARGETS_DEFAULT=
+
+#
+# Security review
+# - SECURITY_REVIEW: 0|1 (enable optional security/compliance review; default off)
+# - COMPLIANCE_PROFILES: comma-separated values (GDPR,SOC2,HIPAA,PCI-DSS,ISO27001)
+#   Empty value means general security best practices only.
+#   When SECURITY_REVIEW=0, the workflow adds zero security-review overhead.
+SECURITY_REVIEW=0
+COMPLIANCE_PROFILES=GDPR
+
+# 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)
+# - COMPATIBILITY_SOURCES: semicolon-separated sources
+#   (repo=<path|url>,module=<id>,contract=<path|url>,docs=<path|url>)
+CROSS_REPO_OBSERVABILITY=0
+COMPATIBILITY_GATE_ON_CRITICAL=1
+COMPATIBILITY_SOURCES=
+
+# 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 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
+
+# Documentation audience profile (DEC-0059)
+# - DOC_AUDIENCE_PROFILE: user|developer|both (empty -> both during transition)
+# - DOC_DETAIL_LEVEL: concise|balanced|technical-deep (empty -> balanced during transition)
+DOC_AUDIENCE_PROFILE=both
+DOC_DETAIL_LEVEL=balanced
+
+# README feature coverage gate (US-0091 / DEC-0074)
+# - README_FEATURE_COVERAGE_ENFORCE: 0|1 (default 0 until backfill + --report green)
+#   When 0, /release step 3f skips (grandfathering). When 1, static coverage is blocking.
+README_FEATURE_COVERAGE_ENFORCE=1
+
+#
+# ## Project README coverage (US-0097 / DEC-0083)
+# Project-owned root README bootstrap + per-story catalog growth.
+# - PROJECT_README_ENFORCE: 0|1 (default 1 post-bootstrap)
+#   When 0, /release step 3g skips (migration/grandfathering only). When 1, blocking.
+#   Flip 0→1 only after validate_project_readme_coverage.py --report shows coverage_missing: [].
+# - FRAMEWORK_KIT_REPO: 0|1 (default 0)
+#   When 1 (its-magic dev kit repo only), skip execute 23a/23b and project validator root check.
+#   Consumer repos never set FRAMEWORK_KIT_REPO=1.
+PROJECT_README_ENFORCE=1
+FRAMEWORK_KIT_REPO=0
+
+#
+# ## Browser UAT self-test (US-0093 / DEC-0079)
+# Two-tier browser probe: stdlib lib classifies + agent owns Cursor browser MCP (BUG-0006).
+# - UAT_BROWSER_PROBE_MODE: cursor|http_fallback|playwright_fallback (default cursor)
+#   - cursor: agent executes MCP sequence; lib emits plan + UAT_PROBE_UNRESOLVED until evidence
+#   - http_fallback: stdlib HTTP GET (CI recipe — set this in CI)
+#   - playwright_fallback: subprocess Playwright primary; HTTP fallback when missing
+# - UAT_BROWSER_FALLBACK_CHAIN: 0|1 (default 1; enable HTTP → Playwright after MCP unavailable)
+# - UAT_PROCESS_HEALTH_POLL_SECONDS: positive int (default 60; process_health readiness cap)
+# - UAT_PROCESS_HEALTH_POLL_INTERVAL_SECONDS: positive int (default 2; poll interval)
+# - DEV_SERVER_PORT: int (optional; URL/port inference override)
+# - DEV_SERVER_COMMAND: shell command (optional; process_health startup override)
+# Interaction: orthogonal to PERMISSION_MODE and Cursor browser approval modes (manual / allow-list /
+#   auto-run per vendor docs). Health URLs from docs/engineering/runtime-connectivity.md first.
+UAT_BROWSER_PROBE_MODE=cursor
+UAT_BROWSER_FALLBACK_CHAIN=1
+UAT_PROCESS_HEALTH_POLL_SECONDS=60
+UAT_PROCESS_HEALTH_POLL_INTERVAL_SECONDS=2
+DEV_SERVER_PORT=
+DEV_SERVER_COMMAND=
+
+#
+# ## Dev environment auto-launch (US-0098 / DEC-0084)
+# Execute-phase bounded rebuild/relaunch + Connect surfacing — distinct from US-0065 phase QA,
+# US-0086 test routing, and US-0067 release hints. Orthogonal to AUTO_REMOTE_AUTOMATION_PROFILE.
+# When off, execute step 24 skipped with zero overhead.
+# - DEV_AUTO_LAUNCH_PROFILE: off|deterministic_v1 (default off)
+# - DEV_ENVIRONMENT_CONFIG: repo-relative path (default .cursor/dev-environment.json)
+DEV_AUTO_LAUNCH_PROFILE=off
+DEV_ENVIRONMENT_CONFIG=.cursor/dev-environment.json
+
+#
+# ## Caveman mode (US-0089)
+# Response-side voice toggle. Default off. Composition is orthogonal to
+# TOKEN_PROFILE (DEC-0035 / US-0080) and AUTO_QUIET (US-0088) --
+# TOKEN_PROFILE controls context breadth, CAVEMAN_MODE controls reply voice;
+# neither substitutes for the other.
+# - CAVEMAN_MODE: 0|1 (default 0; absence = 0)
+# - CAVEMAN_LEVEL: lite|full|ultra (empty; with MODE=1 empty -> treat as full;
+#   unknown value -> CAVEMAN_LEVEL_UNKNOWN and fall back to pre-US-0089 voice)
+#
+# ## Caveman input compression (US-0090 / DEC-0073)
+# Input-side prose minification via scripts/caveman_compress_input.py. Default off.
+# Orthogonal to CAVEMAN_MODE (reply voice) and TOKEN_PROFILE (context breadth).
+# - CAVEMAN_COMPRESS_INPUT: 0|1 (default 0) -- activation gate; must be 1 for --write
+# - CAVEMAN_FILE_SCOPE: string (empty default) -- allow-list of files eligible for compression:
+#     * empty: no files in scope (fail-closed on --write with CAVEMAN_COMPRESS_SCOPE_EMPTY)
+#     * named profile: e.g. docs-prose-only (user-guides, runbook, state-archive, handoffs/archive)
+#     * raw globs: e.g. docs/user-guides/**/*.md,handoffs/archive/*.md (forward slashes only)
+#     * hybrid: profile:docs-prose-only;globs:handoffs/archive/*.md
+#   Mutation requires COMPRESS_INPUT=1 + non-empty scope + CLI --write; use --dry-run first.
+#   Originals land in docs/.caveman-originals/<path>; deny-list always wins over allow.
+CAVEMAN_MODE=0
+CAVEMAN_LEVEL=
+CAVEMAN_COMPRESS_INPUT=0
+CAVEMAN_FILE_SCOPE=
+
+#
+# ## Per-phase model tier selection (US-0101 / DEC-0086)
+# MODEL_TIER selects LLM model strength (which model runs).
+# MODEL_TIER ≠ TOKEN_PROFILE ≠ DELIVERY_MODE — these are independent axes;
+#   none substitutes for the other (DEC-0062 / US-0080 / US-0096).
+# - MODEL_TIER_DEFAULT: cheap|balanced|strong (default balanced)
+# - MODEL_TIER_<PHASE>: cheap|balanced|strong (per-phase override; PHASE = canonical phase id)
+#   Examples: MODEL_TIER_EXECUTE=cheap, MODEL_TIER_QA=strong, MODEL_TIER_RESEARCH=balanced
+#   Set in .cursor/scratchpad.local.md to override per phase without touching committed defaults.
+#   Default matrix (architecture-locked):
+#     cheap    — ask, refresh-context, memory-audit, status-reconcile, pause
+#     balanced — intake, discovery, research, release, plan-verify
+#     strong   — architecture, execute, quick, qa, verify-work, security-review
+#     (inherit parent) — auto (orchestrator always inherits parent model)
+# - MODEL_CATALOG: path to local slug catalog (default .cursor/model-catalog.local.json)
+# - MODEL_RESOLVE: alias_only|local_catalog|role_catalog (default alias_only)
+#   alias_only    = use Cursor-stable aliases (cheap->fast, balanced->inherit, strong->omit model:)
+#   local_catalog = look up vendor model slugs from MODEL_CATALOG; requires valid JSON catalog
+#   role_catalog  = opt-in phase→role→catalog slug lookup (US-0102 / DEC-0087); falls through on miss
+# - MODEL_FALLBACK: fallback when catalog lookup fails (default inherit)
+# - MODEL_PROVIDER_MODE: cursor|api (default cursor)
+#   cursor = all subagents route through Cursor-managed infrastructure
+#   api = operator uses BYOK via Cursor Settings → Models → API Key
+#   Known limitation: subagents do NOT inherit custom API keys/base URLs.
+#
+# Example catalogs for 4 software-complexity levels + a Cursor-only variant:
+#   .cursor/model-catalog.local.example.json                           — minimal placeholder template
+#   .cursor/model-catalog.local.example.cursor-only.json             — only Cursor-integrated Composer models
+#   .cursor/model-catalog.local.example.level-1-easy.json            — small/simple apps
+#   .cursor/model-catalog.local.example.level-2-complex.json         — complex multi-service apps
+#   .cursor/model-catalog.local.example.level-3-mega.json            — mega-complex / modular monoliths
+#   .cursor/model-catalog.local.example.level-4-super.json            — super-high-sophisticated / mission-critical
+#   .cursor/model-catalog.local.example.role-based-balanced.json     — v2 role preset (balanced)
+#   .cursor/model-catalog.local.example.role-based-highend.json      — v2 role preset (high-end)
+# Copy one to .cursor/model-catalog.local.json and set MODEL_RESOLVE=local_catalog or role_catalog to activate.
+MODEL_TIER_DEFAULT=balanced
+MODEL_CATALOG=.cursor/model-catalog.local.json
+MODEL_RESOLVE=alias_only
+MODEL_FALLBACK=inherit
+MODEL_PROVIDER_MODE=cursor
+#
+# ## Direct per-phase model slug override + role catalog (US-0102 / DEC-0087)
+# Composes on US-0101 / DEC-0086 — tier baseline unchanged; overlays are optional.
+# Precedence chain (deterministic, per canonical phase_id):
+#   1. MODEL_<PHASE>           — direct vendor slug override (highest priority)
+#   2. MODEL_TIER_<PHASE>      — DEC-0086 tier→alias / local_catalog chain
+#   3. role_catalog lookup     — only when MODEL_RESOLVE=role_catalog; miss falls through
+#   4. MODEL_TIER_DEFAULT      — DEC-0086 tier chain
+#   5. Cursor stable alias     — DEC-0086 built-in mapping (fast / inherit / omit)
+# Scratchpad merge precedence for all MODEL_* keys: MODEL_<PHASE> > MODEL_TIER_<PHASE> > MODEL_TIER_DEFAULT
+# - MODEL_<PHASE>: direct vendor slug; <PHASE> = canonical phase id (same list as MODEL_TIER_<PHASE>)
+#   Set in .cursor/scratchpad.local.md only — use <your-vendor-slug> placeholders in committed files.
+#   Canonical phase ids: ask, refresh-context, memory-audit, status-reconcile, pause,
+#     intake, discovery, research, release, plan-verify, architecture, execute, quick,
+#     qa, verify-work, security-review, auto
+#   Examples (placeholders — replace in scratchpad.local.md):
+#     MODEL_ASK=<your-vendor-slug>
+#     MODEL_EXECUTE=<your-vendor-slug>
+#     MODEL_QA=<your-vendor-slug>
+#     MODEL_REFRESH-CONTEXT=<your-vendor-slug>
+#   MODEL_ASK participates in step 1 like any other phase (no special-case bypass).
+#
+# AI Decision Ledger + Plan Fidelity (US-0103 / DEC-0103)
+# Sovereign-loop foundation. Default-off — zero overhead when AI_DECISION_LEDGER=0.
+# - AI_DECISION_LEDGER: 0|1 (default 0) — when 0: no ledger reads/writes/schema checks.
+# - AUTO_PLAN_FIDELITY: strict|relaxed|extended (default strict) — active only when ledger enabled.
+#   strict   = any unapproved drop/reorder/scope-add → PLAN_FIDELITY_VIOLATION hard stop
+#   relaxed  = drop/reorder allowed (ledger entry); scope-add still hard stop
+#   extended = scope-add allowed (extension report); drop/reorder allowed
+AI_DECISION_LEDGER=0
+AUTO_PLAN_FIDELITY=strict
+#
+# Goal-Based Convergence (US-0110 / DEC-0110)
+# Default-off sovereign-loop terminal predicate. When SOVEREIGN_GOAL_MODE=phase_driven,
+# zero overhead — no evaluation, no goal_progress block, no partial-delivery write.
+# Compose do NOT amend US-0088 / US-0092 / US-0095 / US-0044 / US-0103 (read-only surfaces).
+# - SOVEREIGN_GOAL_MODE: phase_driven|goal_convergence (default phase_driven)
+# - SOVEREIGN_GOAL: explicit goal text (wins over vision auto-derive; default empty)
+# - SOVEREIGN_GOAL_TOP_N: int >= 1 vision paragraph count for auto-derive (default 3)
+# - SOVEREIGN_GOAL_MAX_CHARS: int >= 64 truncation cap (default 512)
+# - SOVEREIGN_GOAL_TIMEOUT_MAX: int >= 0 iteration-count cap (0 = disabled; not wall-clock)
+SOVEREIGN_GOAL_MODE=phase_driven
+SOVEREIGN_GOAL=
+SOVEREIGN_GOAL_TOP_N=3
+SOVEREIGN_GOAL_MAX_CHARS=512
+SOVEREIGN_GOAL_TIMEOUT_MAX=0
+#
+# Cross-Model Adversarial Critic (US-0104 / DEC-0104)
+# Default-off cross-model review. When CROSS_MODEL_REVIEW=0, zero overhead — no critic
+# spawn, no findings writes, no anti-slop gate. Compose do NOT amend US-0048 / US-0069 /
+# US-0023 / US-0110 / US-0103 (additive surfaces only).
+# - CROSS_MODEL_REVIEW: 0|1 (default 0)
+# - CROSS_MODEL_ANTISLOP_THRESHOLD: int 0-10 aggregate floor (default 6)
+# - CROSS_MODEL_REWORK_MAX: int >= 0 producer re-spawns per (run, phase) (default 2)
+CROSS_MODEL_REVIEW=0
+CROSS_MODEL_ANTISLOP_THRESHOLD=6
+CROSS_MODEL_REWORK_MAX=2
+#
+# Sovereign Memory (US-0105 / DEC-0105)
+# Default-off institutional memory. When SOVEREIGN_MEMORY=0, zero overhead —
+# no JSONL writes, no injection reads, no spawn digest assembly.
+# Compose do NOT amend US-0029 / US-0080 / US-0103 / US-0072 / US-0096.
+# - SOVEREIGN_MEMORY: 0|1 (default 0)
+# - SOVEREIGN_MEMORY_TOP_N: int >= 0 (default 5) — global recent pool (all four JSONL families)
+# - SOVEREIGN_MEMORY_TOP_K: int >= 0 (default 3) — high-impact pool (patterns + mistakes only)
+# - SOVEREIGN_MEMORY_MAX_CHARS: int >= 0 (default 2048) — hard cap on assembled digest_text
+# - SOVEREIGN_MEMORY_JSONL_MAX_LINES: int >= 1 (default 500) — active JSONL line cap before archive rollover
+SOVEREIGN_MEMORY=0
+SOVEREIGN_MEMORY_TOP_N=5
+SOVEREIGN_MEMORY_TOP_K=3
+SOVEREIGN_MEMORY_MAX_CHARS=2048
+SOVEREIGN_MEMORY_JSONL_MAX_LINES=500
+#
+# Sovereign Loop Mode (US-0107 / DEC-0107)
+# Default-off project orchestration. When AUTO_SOVEREIGN=0, zero overhead — no deferral
+# reads/writes, no advance, no notifications. Requires SOVEREIGN_GOAL_MODE=goal_convergence
+# when enabled (fail-closed SOVEREIGN_LOOP_GOAL_MODE_REQUIRED). Compose do NOT amend
+# US-0088 / US-0092 / US-0095 / US-0044 / US-0103 / US-0105 / US-0110 (additive hooks only).
+# - AUTO_SOVEREIGN: 0|1 (default 0)
+# - AUTO_SOVEREIGN_DEFERRAL_MAX: int >= 1 (default 50) — max open deferral rows
+# - AUTO_SOVEREIGN_DRAIN_GENERATE_MAX: int >= 0 (default 3) — drain-generate iterations per run
+# - AUTO_SOVEREIGN_DEFERRAL_POLICY: stop|skip|resolve_first (default resolve_first)
+# - SOVEREIGN_NOTIFY_TARGET: off|ntfy|email|hook (default off)
+# - SOVEREIGN_NOTIFY_NTFY_TOPIC: string (default empty — local-only)
+# - SOVEREIGN_NOTIFY_NTFY_BASE: URL (default empty — local-only ntfy base override)
+# - SOVEREIGN_NOTIFY_HOOK_URL: URL (default empty — local-only webhook)
+# - SOVEREIGN_NOTIFY_EMAIL_TO: email (default empty — email v1 deferred)
+AUTO_SOVEREIGN=0
+AUTO_SOVEREIGN_DEFERRAL_MAX=50
+AUTO_SOVEREIGN_DRAIN_GENERATE_MAX=3
+AUTO_SOVEREIGN_DEFERRAL_POLICY=resolve_first
+SOVEREIGN_NOTIFY_TARGET=off
+SOVEREIGN_NOTIFY_NTFY_TOPIC=
+SOVEREIGN_NOTIFY_NTFY_BASE=
+SOVEREIGN_NOTIFY_HOOK_URL=
+SOVEREIGN_NOTIFY_EMAIL_TO=
+#
+# Sovereign Role-Behavior Manifest (US-0106 / DEC-0106)
+# Default-off per-role objective + inter-role review obligations. When SOVEREIGN_ROLE_MANIFEST=0,
+# zero overhead — no manifest reads, no objective injection, no review dispatch.
+# Compose do NOT amend US-0069 (phase→role matrix unchanged; review spawns supplementary),
+# US-0104 (critic lenses + findings schema unchanged; role reviews additive),
+# US-0003 / US-0023 / US-0103 / US-0105 / US-0107 (unchanged surfaces).
+# - SOVEREIGN_ROLE_MANIFEST: 0|1 (default 0)
+# - SOVEREIGN_ROLE_OBJECTIVE_MAX_CHARS: int >= 1 (default 512) — hard truncate for injection
+# - SOVEREIGN_ROLE_REVIEW_MAX_PER_PHASE: int >= 0 (default 2) — per-phase review cap
+# - SOVEREIGN_ROLE_REVIEW_REWORK_MAX: int >= 0 (default 1) — bounded rework before decision gate
+SOVEREIGN_ROLE_MANIFEST=0
+SOVEREIGN_ROLE_OBJECTIVE_MAX_CHARS=512
+SOVEREIGN_ROLE_REVIEW_MAX_PER_PHASE=2
+SOVEREIGN_ROLE_REVIEW_REWORK_MAX=1
+#
+# Parallel Instance Arbitrage (US-0108 / DEC-0108)
+# Default-off parallel execute-phase instance orchestration. When SOVEREIGN_PARALLEL_DEV=0,
+# zero overhead — no worktrees, no parallel QA, no pick JSON, no resource guard.
+# Compose do NOT amend US-0047 (bulk execute unchanged), US-0092 (full autonomy unchanged),
+# US-0103 (ledger schema unchanged; read-only consumer), US-0104 (critic schema unchanged;
+# read-only anti_slop_score consumer), US-0107 (sovereign loop unchanged; consumer only).
+# - SOVEREIGN_PARALLEL_DEV: 0|1 (default 0) — global enable gate
+# - AUTO_SOVEREIGN_PARALLEL_N: int >= 1 (default 3) — instances per execute cycle
+# - AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL: int >= 1 (default 6) — system-wide instance cap
+# - AUTO_SOVEREIGN_MERGE_RESOLVE: first_pass_wins|last_pass_wins|winner_takes_all|manual (default first_pass_wins)
+# - AUTO_SOVEREIGN_WORKTREE_KEEP: 0|1 (default 0) — retain loser worktrees for debugging
+# - AUTO_SOVEREIGN_PARALLEL_QA: 0|1 (default 0) — enable parallel QA cross-review (v2)
+# - AUTO_SOVEREIGN_PARALLEL_QA_ARBITER: critic_first_pass|majority_vote (default critic_first_pass)
+# - AUTO_SOVEREIGN_PARALLEL_ANTI_SLOP_THRESHOLD: int 0-10 (default 6) — anti-slop floor
+# - AUTO_SOVEREIGN_PARALLEL_REWORK_MAX: int >= 0 (default 2) — per-instance rework cap
+# - AUTO_SOVEREIGN_PARALLEL_MERGE_TIMEOUT_SEC: int >= 10 (default 60) — merge timeout
+# - AUTO_SOVEREIGN_PARALLEL_MODEL_<idx>: model slug per instance (optional)
+# - AUTO_SOVEREIGN_PARALLEL_LENS_<idx>: lens config per instance (optional)
+SOVEREIGN_PARALLEL_DEV=0
+AUTO_SOVEREIGN_PARALLEL_N=3
+AUTO_SOVEREIGN_PARALLEL_MAX_TOTAL=6
+AUTO_SOVEREIGN_MERGE_RESOLVE=first_pass_wins
+AUTO_SOVEREIGN_WORKTREE_KEEP=0
+AUTO_SOVEREIGN_PARALLEL_QA=0
+AUTO_SOVEREIGN_PARALLEL_QA_ARBITER=critic_first_pass
+AUTO_SOVEREIGN_PARALLEL_ANTI_SLOP_THRESHOLD=6
+AUTO_SOVEREIGN_PARALLEL_REWORK_MAX=2
+AUTO_SOVEREIGN_PARALLEL_MERGE_TIMEOUT_SEC=60
+#
+# Self-Healing Deploy Loop (US-0109 / DEC-0109)
+# Default-off auto-heal post-publish probe + bounded retry + DEPLOY_DEFERRED.
+# When AUTO_SOVEREIGN_SELF_HEALING_DEPLOY=0 zero overhead, byte-identical US-0054 publish path —
+# no probe, no retry, no deferral, no execute steps 29-31. Compose do NOT amend US-0054 / US-0100 /
+# US-0103 / US-0107 / US-0110 (US-0109 consumer-only hook after US-0054 publish PASS).
+# - AUTO_SOVEREIGN_SELF_HEALING_DEPLOY: 0|1 (default 0) — global gate
+# - AUTO_SOVEREIGN_DEPLOY_RETRY_MAX: int >= 1 (default 3) — max retry attempts after probe FAIL
+# - AUTO_SOVEREIGN_DEPLOY_SMOKE_TIMEOUT_SEC: int >= 1 (default 30) — per-stage probe HTTP timeout
+# - AUTO_SOVEREIGN_DEPLOY_PROBE_KIND: health_endpoint|acceptance_smoke|both (default both)
+# - SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH: repo-relative path (default tests/deploy_smoke/)
+# - AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT: names-only env ref (US-0085 compose); empty = unresolvable
+# Reason codes (DEC-0109 §7): DEPLOY_HEALING_DISABLED (info), DEPLOY_HEALING_SMOKE_HEALTH_FAIL,
+#   DEPLOY_HEALING_SMOKE_ACCEPTANCE_FAIL, DEPLOY_HEALING_RETRY_ATTEMPT,
+#   DEPLOY_HEALING_RETRY_CAP_EXHAUSTED, DEPLOY_HEALING_DEFERRED,
+#   DEPLOY_HEALING_PROBE_TARGET_MISSING, DEPLOY_HEALING_TIMEOUT.
+AUTO_SOVEREIGN_SELF_HEALING_DEPLOY=0
+AUTO_SOVEREIGN_DEPLOY_RETRY_MAX=3
+AUTO_SOVEREIGN_DEPLOY_SMOKE_TIMEOUT_SEC=30
+AUTO_SOVEREIGN_DEPLOY_PROBE_KIND=both
+SOVEREIGN_DEPLOY_ACCEPTANCE_SMOKE_PATH=tests/deploy_smoke/
+AUTO_SOVEREIGN_DEPLOY_HEALTH_ENDPOINT=
+#
+# Release Trigger Adapters (US-0111 / DEC-0111)
+# Dispatch release flow by trigger source (GitHub webhook, npm publish, Git tag
+# push, manual /release). Default source is manual (zero behavior change vs
+# pre-US-0111 /release path — byte-identical). Compose with US-0100; reuses
+# release_changelog_lib APIs without modification.
+# - RELEASE_TRIGGER_SOURCE: manual|github|npm|git_tag|auto (default manual)
+# - RELEASE_TRIGGER_TIMEOUT_SEC: int >= 1 (default 10; adapter subprocess timeout)
+# - RELEASE_TRIGGER_FALLBACK_TO_LOCAL: 0|1 (default 0; npm adapter offline fallback)
+RELEASE_TRIGGER_SOURCE=manual
+RELEASE_TRIGGER_TIMEOUT_SEC=10
+RELEASE_TRIGGER_FALLBACK_TO_LOCAL=0

package/template/docs/engineering/runbook.md

@@ -1946,6 +1946,15 @@ Multi-segment operator E2E recipe — validates native-chain orchestrator compli
 Normative detail: **`.cursor/commands/auto.md`** § **Orchestrator post-subagent continuation
 mandate (BUG-0012)** and architecture **`# BUG-0012`**.
 
+### Scratchpad example parity
+
+Verifies `template/.cursor/scratchpad.local.example.md` stays byte-identical with canonical `.cursor/scratchpad.md`:
+
+- **Single-source-of-truth**: canonical is `.cursor/scratchpad.md`; template example is the consumer-shipped packaged copy.
+- **Sync procedure**: copy canonical `.cursor/scratchpad.md` to `template/.cursor/scratchpad.local.example.md`, preserving the example-only header (first 5 lines) and excluding project-local override section (consumer-specific `#MODEL_TIER_*`, `# Per-phase tier overrides for this project`, etc.).
+- **Verification**: `pytest tests/scratchpad_example_parity_test.py -v`
+- **Installer contract**: `installer.py materialize_scratchpad_example()` reads from `template/.cursor/scratchpad.local.example.md` on every install/upgrade, ensuring consumers get the latest framework defaults without overwriting their personal overrides in `.cursor/scratchpad.local.md`.
+
 ### Full-autonomy outer driver (US-0092) — fallback
 
 Opt-in **`AUTO_FLOW_MODE=full_autonomy`** (exact literal, default-off) also enables
@@ -3501,6 +3510,63 @@ US-0109 does not participate in convergence evaluation.
 
 ---
 
+## Scratchpad Example Parity (BUG-0013)
+
+**Goal**: `template/.cursor/scratchpad.local.example.md` must stay in structural parity with the canonical `.cursor/scratchpad.md` (current source of truth), while preserving the example-only header (L1–L5) and excluding project-local flag overrides (which belong in consumer `.cursor/scratchpad.local.md`).
+
+### Single source of truth
+
+- Canonical scratchpad: `.cursor/scratchpad.md` (read-only for installers).
+- Template example: `template/.cursor/scratchpad.local.example.md` (mirror — must stay in sync structurally; project-local value overrides must be reset to safe defaults).
+- Active example: `.cursor/scratchpad.local.example.md` (body must be byte-identical to template mirror from L6 onwards).
+
+### When to re-sync
+
+Whenever `.cursor/scratchpad.md` gains a new `## Section` / key block, the template example must be refreshed (copy canonical, then reset project-local values):
+
+- Copy canonical to template.
+- Preserve the example-only header comment (first 5 lines).
+- Reset framework/project-local keys to their safe example defaults:
+
+| Key | Example default | Canonical (framework) value |
+|---|---|---|
+| `FRAMEWORK_KIT_REPO` | `0` | `1` |
+| `CAVEMAN_LEVEL` | *(empty)* | `full` |
+| `TOKEN_PROFILE` | `balanced` | `lean` |
+| `CAVEMAN_MODE` | `0` | `1` |
+
+### Verification command
+
+```bash
+python -m pytest tests/scratchpad_example_parity_test.py -v
+```
+
+Three regression test markers cover this contract:
+
+- `test_bug0013_parity_check`: all canonical keys present in template (canonical keys ⊆ template example keys).
+- `test_bug0013_header_preserved`: example-only header comment (L1–L5) intact.
+- `test_bug0013_local_overrides_preserved`: no project-local override values leak into the template example.
+
+### Reason codes
+
+| Reason | Meaning |
+|---|---|
+| `SCRATCHPAD_EXAMPLE_OUT_OF_SYNC` | Template example is missing one or more canonical sections/keys. |
+| `SCRATCHPAD_HEADER_DRIFT` | Example-only header (L1–L5) was overwritten or drifted. |
+| `SCRATCHPAD_LOCAL_VALUES_LEAKED` | Project-local override values (e.g. `FRAMEWORK_KIT_REPO=1`, `CAVEMAN_LEVEL=full`) are present in the template example. |
+
+### Normative architecture
+
+- **Backlog**: `docs/product/backlog.md` § `BUG-0013` (scratchpad-example-stale).
+- **Sprint**: `sprints/S-BUG0013/`.
+- **Test**: `tests/scratchpad_example_parity_test.py`.
+
+### Compose guards (unchanged)
+
+US-0008, US-0040, US-0054, US-0100, US-0101, US-0102, US-0103, US-0107, US-0110 (as per sprint constraints — all UNCHANGED during BUG-0013).
+
+---
+
 ## Project run steps
 
 ### Prerequisites

package/template/tests/scratchpad_example_parity_test.py

@@ -0,0 +1,124 @@
+"""
+BUG-0013: Scratchpad example parity tests.
+
+Verifies template/.cursor/scratchpad.local.example.md stays in sync
+with canonical .cursor/scratchpad.md, excluding project-local overrides.
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+
+CANONICAL = Path(__file__).parent.parent / ".cursor" / "scratchpad.md"
+TEMPLATE = (
+    Path(__file__).parent.parent
+    / "template"
+    / ".cursor"
+    / "scratchpad.local.example.md"
+)
+
+
+def extract_keys(text):
+    """Extract KEY=value keys from scratchpad text."""
+    pattern = re.compile(r"^([A-Z_][A-Z0-9_]*)=", re.MULTILINE)
+    return set(pattern.findall(text))
+
+
+def extract_sections(text):
+    """Extract # Section headers from scratchpad text."""
+    pattern = re.compile(r"^(#+\s+.+)$", re.MULTILINE)
+    return [m.strip() for m in pattern.findall(text)]
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture
+def canonical_text():
+    return CANONICAL.read_text(encoding="utf-8")
+
+
+@pytest.fixture
+def template_text():
+    return TEMPLATE.read_text(encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Test markers
+# ---------------------------------------------------------------------------
+
+def test_bug0013_parity_check(canonical_text, template_text):
+    """AC-1: All canonical sections keys present in template example."""
+    # 1) Section headers should be present
+    canonical_sections = extract_sections(canonical_text)
+    template_sections = extract_sections(template_text)
+    missing_sections = set(canonical_sections) - set(template_sections)
+
+    # 2) Keys (canonical keys ⊆ template example keys)
+    canonical_keys = extract_keys(canonical_text)
+    template_keys = extract_keys(template_text)
+    missing_keys = canonical_keys - template_keys
+
+    msg = []
+    if missing_sections:
+        msg.append(
+            f"Template missing {len(missing_sections)} canonical section(s):\n"
+            + "\n".join(f"  - {s}" for s in sorted(missing_sections))
+        )
+    if missing_keys:
+        msg.append(
+            f"Template missing {len(missing_keys)} canonical key(s):\n"
+            + "\n".join(f"  - {k}" for k in sorted(missing_keys))
+        )
+
+    assert not msg, "\n".join(msg)
+
+
+def test_bug0013_header_preserved(template_text):
+    """AC-1: Example-only header comment (L1-L5) preserved intact."""
+    lines = template_text.splitlines()[:5]
+
+    expected_patterns = [
+        r"^#",            # L1: comment line
+        r"its-magic",     # L2: contains "its-magic"
+        r"DEC-",          # L3: contains DEC reference
+        r"Copy this file",# L4: contains copy instruction
+        r"local>",        # L5: contains "local>" reference
+    ]
+    assert len(lines) >= 5, (
+        f"Template header must have at least 5 lines; only {len(lines)} found"
+    )
+
+    for idx, pattern in enumerate(expected_patterns, start=1):
+        assert pattern in lines[idx - 1] or re.match(pattern, lines[idx - 1]), (
+            f"Header line {idx} missing expected pattern '{pattern}'.\n"
+            f"Found: {lines[idx - 1]}"
+        )
+
+
+def test_bug0013_local_overrides_preserved(template_text):
+    """AC-1: Project-local overrides NOT leaked into template example."""
+    # Patterns indicating project-local overrides that should NOT be in template
+    forbidden = [
+        r"^MODEL_[A-Z]+=",   # Direct per-phase model overrides (e.g., MODEL_EXECUTE=...)
+        r"^#MODEL_",          # Commented per-phase slug overrides
+        r"^#MODEL_RESOLVE=local_catalog",  # Local catalog override (commented)
+        r"^#MODEL_RESOLVE=role_catalog",   # Role catalog override (commented)
+    ]
+
+    violations = []
+    for pattern in forbidden:
+        matches = re.findall(pattern, template_text, re.MULTILINE)
+        if matches:
+            violations.append((pattern, matches[:3]))  # up to 3 examples
+
+    assert not violations, (
+        f"Template contains {len(violations)} project-local override pattern(s) "
+        "that should NOT be present:\n"
+        + "\n".join(
+            f"  - {pat} (examples: {ex})" for pat, ex in violations
+        )
+        + "\nProject-local overrides belong in consumer's .cursor/scratchpad.local.md"
+    )