its-magic 0.1.2-29 → 0.1.2-32

package/README.md

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

package/bin/its-magic.js

@@ -118,6 +118,11 @@ Install options:
   Note: installer bootstraps runbook TEST/LINT/TYPECHECK commands from
         OS+stack detection; unresolved TEST_COMMAND fails fast with
         [RUNBOOK_BOOTSTRAP_ERROR] diagnostics.
+  Note: scratchpad Model B: .cursor/scratchpad.md is materialized when missing;
+        post-install always refreshes .cursor/scratchpad.local.example.md from the
+        template before baseline handling. PowerShell/bash installers require
+        Python 3 on PATH for merged scratchpad validation. Recovery:
+        python installer.py --scratchpad-postinstall --target <repo> --mode missing
 
 Clean options:
   --clean-repo      Remove all its-magic workflow artifacts from the target repo

package/installer.ps1

@@ -111,7 +111,7 @@ function Choose-Mode {
 function Classify-File($RelPath) {
   $normalized = $RelPath -replace '\\','/'
 
-  $mixedFiles = @('.cursor/scratchpad.md', 'README.md')
+  $mixedFiles = @('README.md')
   if ($mixedFiles -contains $normalized) { return 'mixed' }
 
   $frameworkPrefixes = @(
@@ -232,7 +232,6 @@ function Get-DetectedRunbookDefaults($TargetRoot) {
     TYPECHECK_COMMAND = ""
   }
 
-  $testsPs1 = Join-Path $TargetRoot "tests\run-tests.ps1"
   $testsSh = Join-Path $TargetRoot "tests\run-tests.sh"
   $pkgPath = Join-Path $TargetRoot "package.json"
   $goMod = Join-Path $TargetRoot "go.mod"
@@ -261,11 +260,6 @@ function Get-DetectedRunbookDefaults($TargetRoot) {
     return $defaults
   }
 
-  if (Test-Path $testsPs1 -PathType Leaf) {
-    $defaults.TEST_COMMAND = "powershell -ExecutionPolicy Bypass -File `"tests/run-tests.ps1`""
-    return $defaults
-  }
-
   if (Test-Path $testsSh -PathType Leaf) {
     $defaults.TEST_COMMAND = "sh tests/run-tests.sh"
     return $defaults
@@ -391,6 +385,25 @@ function Get-AppVersion($SourceRoot) {
   return "unknown"
 }
 
+function Invoke-ScratchpadPostinstall {
+  param(
+    [string]$TargetRoot,
+    [string]$Mode
+  )
+  $installerPy = Join-Path $scriptDir "installer.py"
+  if (-not (Test-Path $installerPy -PathType Leaf)) {
+    Write-Host "[SCRATCHPAD_POSTINSTALL_ERROR] installer.py missing next to installer.ps1."
+    exit 1
+  }
+  $py = Get-Command python -ErrorAction SilentlyContinue
+  if (-not $py) {
+    Write-Host "[SCRATCHPAD_POSTINSTALL_ERROR] PYTHON_NOT_FOUND: Python is required for scratchpad materialization/validation (Model B). Fix: install Python 3 and re-run."
+    exit 1
+  }
+  & python $installerPy --scratchpad-postinstall --target $TargetRoot --mode $Mode
+  if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+}
+
 function Show-ItsMagicBanner([switch]$IncludeInstallMessage) {
   $prev = [Console]::OutputEncoding
   [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
@@ -440,6 +453,9 @@ function Show-ItsMagicHelp($VersionString, $RepoUrl) {
   Write-Host "  Note: installer bootstraps runbook TEST/LINT/TYPECHECK commands from"
   Write-Host "        OS+stack detection; unresolved TEST_COMMAND fails fast with"
   Write-Host "        [RUNBOOK_BOOTSTRAP_ERROR] diagnostics."
+  Write-Host "  Note: scratchpad Model B: .cursor/scratchpad.md is"
+  Write-Host "        materialized when missing; Python 3 on PATH is required for validation."
+  Write-Host "        Recovery: python installer.py --scratchpad-postinstall --target <repo> --mode missing"
   Write-Host ""
   Write-Host "Clean options:"
   Write-Host "  --clean-repo      Remove all its-magic workflow artifacts from the target repo"
@@ -625,6 +641,8 @@ if ($mode -eq "upgrade") {
     }
   }
 
+  Invoke-ScratchpadPostinstall -TargetRoot $targetRoot -Mode "upgrade"
+
   Write-InstalledVersion $targetRoot $appVersion
   Sync-RootReadmeToItsMagic $targetRoot | Out-Null
   $runbookBootstrap = Invoke-RunbookBootstrap -TargetRoot $targetRoot
@@ -646,6 +664,7 @@ if ($mode -eq "upgrade") {
   Write-Host "  Preserved (user):    $preserved files"
   if ($scratchpadExampleStatus -eq 'not-seen') { $scratchpadExampleStatus = 'not-in-manifest' }
   Write-Host "  Scratchpad example:  $scratchpadExampleStatus (.cursor/scratchpad.local.example.md)"
+  Write-Host "  Scratchpad layers:   post-install refreshed example-first, then baseline (see [SCRATCHPAD_LAYER] lines)."
   if (Test-Path (Join-Path $targetRoot '.cursor/scratchpad.local.md') -PathType Leaf) {
     Write-Host "  User local file:     preserved (.cursor/scratchpad.local.md)"
   }
@@ -703,6 +722,8 @@ foreach ($rel in $files) {
   }
 }
 
+Invoke-ScratchpadPostinstall -TargetRoot $targetRoot -Mode $mode
+
 Write-InstalledVersion $targetRoot $appVersion
 Sync-RootReadmeToItsMagic $targetRoot | Out-Null
 $runbookBootstrap = Invoke-RunbookBootstrap -TargetRoot $targetRoot

package/installer.py

@@ -119,7 +119,187 @@ USER_DATA_PREFIXES = (
     "docs/product/", "docs/engineering/", "docs/user-guides/",
     "sprints/", "handoffs/", "decisions/",
 )
-MIXED_FILES = {".cursor/scratchpad.md", "README.md"}
+MIXED_FILES = {"README.md"}
+
+# Model B (DEC-0055 / US-0073): baseline bytes live in template only; installs materialize `.cursor/scratchpad.md`.
+SCRATCHPAD_BASELINE_REL = os.path.join(".cursor", "scratchpad.md")
+SCRATCHPAD_EXAMPLE_REL = os.path.join(".cursor", "scratchpad.local.example.md")
+SCRATCHPAD_LOCAL_REL = os.path.join(".cursor", "scratchpad.local.md")
+
+# After merge (local > baseline > example), these must be non-empty (fail closed).
+REQUIRED_SCRATCHPAD_KEYS = (
+    "MAGIC_CONTEXT_STRICT",
+    "AUTO_FLOW_MODE",
+    "PHASE_MODE",
+    "PERMISSION_MODE",
+    "AUTO_LOOP_MAX_CYCLES",
+    "SYNC_POLICY_MODE",
+    "DONE",
+    "TEAM_MODE",
+)
+
+
+def parse_scratchpad_file(path):
+    """Parse KEY=value lines; empty values are retained (explicit override to empty)."""
+    if not os.path.isfile(path):
+        return {}
+    out = {}
+    with open(path, "r", encoding="utf-8") as f:
+        for raw in f:
+            line = raw.strip()
+            if not line or line.startswith("#") or line.startswith("- "):
+                continue
+            if "=" not in line:
+                continue
+            key, _, val = line.partition("=")
+            key = key.strip()
+            if not key:
+                continue
+            out[key] = val.strip()
+    return out
+
+
+def merge_scratchpad_layers(target_root):
+    """
+    Model B merge precedence: local > materialized baseline > example (later wins only when key absent).
+    """
+    ex_path = os.path.join(target_root, SCRATCHPAD_EXAMPLE_REL)
+    base_path = os.path.join(target_root, SCRATCHPAD_BASELINE_REL)
+    loc_path = os.path.join(target_root, SCRATCHPAD_LOCAL_REL)
+    example = parse_scratchpad_file(ex_path)
+    baseline = parse_scratchpad_file(base_path)
+    local = parse_scratchpad_file(loc_path)
+    merged = {}
+    all_keys = set(example) | set(baseline) | set(local)
+    for key in all_keys:
+        if key in local:
+            merged[key] = local[key]
+        elif key in baseline:
+            merged[key] = baseline[key]
+        elif key in example:
+            merged[key] = example[key]
+    paths = {"example": ex_path, "baseline": base_path, "local": loc_path}
+    return merged, paths
+
+
+def validate_merged_scratchpad(target_root):
+    """Return (ok, list of diagnostic lines)."""
+    merged, paths = merge_scratchpad_layers(target_root)
+    diagnostics = []
+    if not os.path.isfile(paths["example"]):
+        diagnostics.append(
+            "[SCRATCHPAD_MERGE_ERROR] EXAMPLE_LAYER_MISSING: "
+            f".cursor/scratchpad.local.example.md not found under {target_root}. "
+            "Fix: re-run its-magic install/upgrade."
+        )
+    if not os.path.isfile(paths["baseline"]):
+        diagnostics.append(
+            "[SCRATCHPAD_MERGE_ERROR] MATERIALIZED_BASELINE_MISSING: "
+            f".cursor/scratchpad.md not found under {target_root}. "
+            "Fix: run `python installer.py --scratchpad-postinstall --target <repo> --mode missing` "
+            "or re-run its-magic install (Model B materialization; see docs)."
+        )
+    missing = []
+    for key in REQUIRED_SCRATCHPAD_KEYS:
+        val = merged.get(key)
+        if val is None or str(val).strip() == "":
+            missing.append(key)
+    if missing:
+        diagnostics.append(
+            "[SCRATCHPAD_MERGE_ERROR] REQUIRED_KEY_MISSING_AFTER_MERGE: "
+            f"keys={','.join(missing)}. Layers consulted: local, baseline|materialized, example "
+            f"({paths['local']}, {paths['baseline']}, {paths['example']}). "
+            "Fix: set non-empty values in .cursor/scratchpad.local.md or restore materialized baseline from template."
+        )
+    ok = not diagnostics
+    return ok, diagnostics
+
+
+def materialize_scratchpad_example(target_root, source_root, print_ok=True):
+    """
+    Always refresh framework-owned scratchpad.local.example from template first
+    (example-first ordering before baseline; never touches scratchpad.local.md).
+    """
+    src = os.path.join(source_root, SCRATCHPAD_EXAMPLE_REL)
+    dst = os.path.join(target_root, SCRATCHPAD_EXAMPLE_REL)
+    if not os.path.isfile(src):
+        print(
+            "[SCRATCHPAD_EXAMPLE_ERROR] TEMPLATE_EXAMPLE_MISSING: "
+            f"expected template file at {src}. Reinstall its-magic package."
+        )
+        return False
+    ensure_parent(dst)
+    shutil.copy2(src, dst)
+    if print_ok:
+        print(
+            "[SCRATCHPAD_LAYER] example_refresh: copied template "
+            f"{SCRATCHPAD_EXAMPLE_REL} -> target (ordering: example before baseline)."
+        )
+    return True
+
+
+def materialize_scratchpad_baseline(target_root, source_root, mode, print_ok=True):
+    """
+    Write stable baseline bytes from template when Model B requires it.
+    Never touches .cursor/scratchpad.local.md.
+    """
+    src = os.path.join(source_root, SCRATCHPAD_BASELINE_REL)
+    dst = os.path.join(target_root, SCRATCHPAD_BASELINE_REL)
+    if not os.path.isfile(src):
+        print(
+            "[SCRATCHPAD_MATERIALIZE_ERROR] TEMPLATE_BASELINE_MISSING: "
+            f"expected template file at {src}. Reinstall its-magic package."
+        )
+        return False
+    wrote = False
+    if mode == "overwrite":
+        ensure_parent(dst)
+        shutil.copy2(src, dst)
+        wrote = True
+    elif mode == "upgrade":
+        if not os.path.isfile(dst):
+            ensure_parent(dst)
+            shutil.copy2(src, dst)
+            wrote = True
+    else:
+        # missing, interactive
+        if not os.path.isfile(dst):
+            ensure_parent(dst)
+            shutil.copy2(src, dst)
+            wrote = True
+    if wrote and print_ok:
+        print(
+            "[SCRATCHPAD_LAYER] baseline_materialize: wrote materialized "
+            f"{SCRATCHPAD_BASELINE_REL} from template (Model B)."
+        )
+    elif print_ok and os.path.isfile(dst):
+        print(
+            "[SCRATCHPAD_LAYER] baseline_skip: materialized baseline already present "
+            f"({SCRATCHPAD_BASELINE_REL}); not overwritten in this mode."
+        )
+    return True
+
+
+def run_scratchpad_postinstall(target_root, source_root, mode, print_ok=True):
+    if not materialize_scratchpad_example(target_root, source_root, print_ok=print_ok):
+        return False
+    if not materialize_scratchpad_baseline(target_root, source_root, mode, print_ok=print_ok):
+        return False
+    ok, diagnostics = validate_merged_scratchpad(target_root)
+    for line in diagnostics:
+        print(line)
+    if ok and print_ok:
+        loc = os.path.join(target_root, SCRATCHPAD_LOCAL_REL)
+        if os.path.isfile(loc):
+            print(
+                "[SCRATCHPAD_LAYER] user_local: preserved "
+                f"{SCRATCHPAD_LOCAL_REL} (merge precedence unchanged)."
+            )
+        print(
+            "[SCRATCHPAD_POSTINSTALL_OK] Model B: example refreshed, baseline handled, "
+            "merged scratchpad validation passed."
+        )
+    return ok
 
 
 def classify_file(rel_path):
@@ -213,8 +393,6 @@ def package_has_script(target_root, script_name):
 
 
 def detect_runbook_defaults(target_root):
-    is_windows = os.name == "nt"
-    tests_ps1 = os.path.join(target_root, "tests", "run-tests.ps1")
     tests_sh = os.path.join(target_root, "tests", "run-tests.sh")
     has_pkg = os.path.isfile(os.path.join(target_root, "package.json"))
     has_py = any(
@@ -235,8 +413,6 @@ def detect_runbook_defaults(target_root):
         result["TEST_COMMAND"] = "go test ./..."
     elif has_py:
         result["TEST_COMMAND"] = "python -m pytest"
-    elif is_windows and os.path.isfile(tests_ps1):
-        result["TEST_COMMAND"] = "powershell -ExecutionPolicy Bypass -File \"tests/run-tests.ps1\""
     elif os.path.isfile(tests_sh):
         result["TEST_COMMAND"] = "sh tests/run-tests.sh"
 
@@ -392,6 +568,10 @@ def show_help(version):
     print("  Note: installer bootstraps runbook TEST/LINT/TYPECHECK commands")
     print("        from OS+stack detection; unresolved TEST_COMMAND fails fast with")
     print("        [RUNBOOK_BOOTSTRAP_ERROR] diagnostics.")
+    print("  Note: scratchpad Model B: `.cursor/scratchpad.md` is")
+    print("        materialized from the packaged template when missing; merged validation")
+    print("        requires Python 3 on PATH for installer.ps1 / installer.sh. Recovery:")
+    print("        python installer.py --scratchpad-postinstall --target <repo> --mode missing")
     print()
     print("Clean options:")
     print("  --clean-repo      Remove all its-magic workflow artifacts from the target repo")
@@ -445,6 +625,11 @@ def main():
     parser.add_argument("--yes", action="store_true", help="Skip clean confirmation prompt")
     parser.add_argument("--help", "-h", action="store_true", help="Show help")
     parser.add_argument("--version", "-v", action="store_true", help="Show version")
+    parser.add_argument(
+        "--scratchpad-postinstall",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
     args = parser.parse_args()
 
     if len(sys.argv) == 1 or args.help:
@@ -455,6 +640,24 @@ def main():
         print(f"its-magic v{version}")
         return 0
 
+    if args.scratchpad_postinstall:
+        target_root = normalize(args.target) if args.target else normalize(".")
+        mode = args.mode or "missing"
+        if mode not in ("missing", "overwrite", "interactive", "upgrade"):
+            print(
+                "[SCRATCHPAD_POSTINSTALL_ERROR] INVALID_MODE: use --mode "
+                "missing|overwrite|interactive|upgrade with --scratchpad-postinstall."
+            )
+            return 1
+        if not os.path.isdir(source_root):
+            print("[INSTALL_SOURCE_ERROR] template directory is missing. Reinstall its-magic package.")
+            return 1
+        if not os.path.isdir(target_root):
+            print(f"[SCRATCHPAD_POSTINSTALL_ERROR] TARGET_MISSING: {target_root}")
+            return 1
+        ok = run_scratchpad_postinstall(target_root, source_root, mode, print_ok=True)
+        return 0 if ok else 1
+
     if not os.path.isdir(source_root):
         print("[INSTALL_SOURCE_ERROR] template directory is missing. Reinstall its-magic package.")
         return 1
@@ -559,6 +762,9 @@ def main():
                     review.append(rel)
                 continue
 
+        if not run_scratchpad_postinstall(target_root, source_root, "upgrade", print_ok=True):
+            return 1
+
         write_installed_version(target_root, version)
         sync_root_readme_to_its_magic(target_root)
         runbook_ok, runbook_notes = bootstrap_runbook_commands(target_root)
@@ -587,6 +793,10 @@ def main():
         if scratchpad_example_status == "not-seen":
             scratchpad_example_status = "not-in-manifest"
         print(f"  Scratchpad example:  {scratchpad_example_status} (.cursor/scratchpad.local.example.md)")
+        print(
+            "  Scratchpad layers:   post-install refreshed example-first, then baseline "
+            "(see [SCRATCHPAD_LAYER] lines)."
+        )
         if os.path.isfile(os.path.join(target_root, ".cursor", "scratchpad.local.md")):
             print("  User local file:     preserved (.cursor/scratchpad.local.md)")
         if review:
@@ -630,6 +840,9 @@ def main():
                 ensure_parent(dst)
                 shutil.copy2(src, dst)
 
+    if not run_scratchpad_postinstall(target_root, source_root, mode, print_ok=True):
+        return 1
+
     write_installed_version(target_root, version)
     sync_root_readme_to_its_magic(target_root)
     runbook_ok, runbook_notes = bootstrap_runbook_commands(target_root)

package/installer.sh

@@ -46,7 +46,10 @@ show_help() {
   printf "  --create          Create the target directory if it does not exist.\n\n"
   printf "  Note: installer bootstraps runbook TEST/LINT/TYPECHECK commands from\n"
   printf "        OS+stack detection; unresolved TEST_COMMAND fails fast with\n"
-  printf "        [RUNBOOK_BOOTSTRAP_ERROR] diagnostics.\n\n"
+  printf "        [RUNBOOK_BOOTSTRAP_ERROR] diagnostics.\n"
+  printf "  Note: scratchpad Model B: .cursor/scratchpad.md is\n"
+  printf "        materialized when missing; Python 3 on PATH is required for validation.\n"
+  printf "        Recovery: python installer.py --scratchpad-postinstall --target <repo> --mode missing\n\n"
   printf "Clean options:\n"
   printf "  --clean-repo      Remove all its-magic workflow artifacts from the target repo\n"
   printf "                    (owned paths from installer manifest, including .cursor,\n"
@@ -130,10 +133,28 @@ choose_mode() {
   esac
 }
 
+scratchpad_postinstall() {
+  target_root="$1"
+  mode="$2"
+  installer_py="$SCRIPT_DIR/installer.py"
+  if [ ! -f "$installer_py" ]; then
+    printf "%s\n" "[SCRATCHPAD_POSTINSTALL_ERROR] installer.py missing next to installer.sh."
+    exit 1
+  fi
+  if command -v python3 >/dev/null 2>&1; then
+    python3 "$installer_py" --scratchpad-postinstall --target "$target_root" --mode "$mode" || exit $?
+  elif command -v python >/dev/null 2>&1; then
+    python "$installer_py" --scratchpad-postinstall --target "$target_root" --mode "$mode" || exit $?
+  else
+    printf "%s\n" "[SCRATCHPAD_POSTINSTALL_ERROR] PYTHON_NOT_FOUND: Python 3 is required for scratchpad materialization/validation (Model B)."
+    exit 1
+  fi
+}
+
 classify_file() {
   rel="$1"
   case "$rel" in
-    .cursor/scratchpad.md|README.md) echo "mixed" ;;
+    README.md) echo "mixed" ;;
     .cursor/commands/*|.cursor/rules/*|.cursor/agents/*|.cursor/skills/*) echo "framework" ;;
     .cursor/hooks/*|.cursor/hooks.json|.cursor/scratchpad.local.example.md) echo "framework" ;;
     .github/workflows/*|scripts/validate-and-push*|docs/engineering/context/*|its_magic/*) echo "framework" ;;
@@ -513,6 +534,8 @@ if [ "$MODE" = "upgrade" ]; then
     fi
   done
 
+  scratchpad_postinstall "$TARGET_ROOT" "upgrade"
+
   write_installed_version "$TARGET_ROOT" "$APP_VERSION"
   sync_root_readme_to_its_magic "$TARGET_ROOT" || true
   bootstrap_runbook_commands "$TARGET_ROOT"
@@ -533,6 +556,7 @@ if [ "$MODE" = "upgrade" ]; then
   printf "  Preserved (user):    %s files\n" "$count_preserved"
   [ "$scratchpad_example_status" = "not-seen" ] && scratchpad_example_status="not-in-manifest"
   printf "  Scratchpad example:  %s (.cursor/scratchpad.local.example.md)\n" "$scratchpad_example_status"
+  printf "  Scratchpad layers:   post-install refreshed example-first, then baseline (see [SCRATCHPAD_LAYER] lines).\n"
   [ -f "$TARGET_ROOT/.cursor/scratchpad.local.md" ] && printf "  User local file:     preserved (.cursor/scratchpad.local.md)\n"
   if [ "$count_review" -gt 0 ]; then
     printf "\n  \033[1;35mReview recommended:  %s files\033[0m\n" "$count_review"
@@ -581,6 +605,8 @@ for rel in $FILES; do
   fi
 done
 
+scratchpad_postinstall "$TARGET_ROOT" "$MODE"
+
 write_installed_version "$TARGET_ROOT" "$APP_VERSION"
 sync_root_readme_to_its_magic "$TARGET_ROOT" || true
 bootstrap_runbook_commands "$TARGET_ROOT"

package/package.json

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

package/template/.cursor/commands/architecture.md

@@ -78,6 +78,14 @@ description: "its-magic architecture: define approach, risks, and decisions."
    - If `USER_GUIDE_MODE=0`, add no required user-guide steps or blocking checks (zero overhead).
    - If `USER_GUIDE_MODE=1`, reference canonical user-guide path and schema in
      architecture/state for in-scope feature stories; see runbook user-guide section.
+9. Triad hot-surface gate (DEC-0054) when `docs/engineering/architecture.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`,
+   - preserve non-target history in archive packs only (never delete unrelated
+     story sections without archival evidence).
 
 ## Cross-phase ownership guard (US-0061 / DEC-0043)