its-magic 0.1.2-31 → 0.1.2-32

package/README.md

@@ -216,13 +216,20 @@ Recovery if `.cursor/scratchpad.md` is missing or merge validation fails:
 python installer.py --scratchpad-postinstall --target . --mode missing
 ```
 
-Upgrade behavior (US-0057):
-- Aligns with **DEC-0039** (example vs local ownership) and Model B baseline rules below.
+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 refreshed on `--mode upgrade`.
+- `.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`.
-- Existing `.cursor/scratchpad.md` is left untouched on upgrade (legacy parity).
-- 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`.

package/bin/its-magic.js

@@ -118,9 +118,10 @@ 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; PowerShell/bash installers require Python 3
-        on PATH for merged scratchpad validation. Recovery:
+  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:

package/installer.ps1

@@ -664,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)"
   }

package/installer.py

@@ -215,7 +215,30 @@ def validate_merged_scratchpad(target_root):
     return ok, diagnostics
 
 
-def materialize_scratchpad_baseline(target_root, source_root, mode):
+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.
@@ -228,32 +251,53 @@ def materialize_scratchpad_baseline(target_root, source_root, mode):
             f"expected template file at {src}. Reinstall its-magic package."
         )
         return False
+    wrote = False
     if mode == "overwrite":
         ensure_parent(dst)
         shutil.copy2(src, dst)
-        return True
-    if mode == "upgrade":
+        wrote = True
+    elif mode == "upgrade":
         if not os.path.isfile(dst):
             ensure_parent(dst)
             shutil.copy2(src, dst)
-        return True
-    # missing, interactive
-    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_baseline(target_root, source_root, mode):
+    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: materialized baseline (if required) "
-            "and merged scratchpad validation passed."
+            "[SCRATCHPAD_POSTINSTALL_OK] Model B: example refreshed, baseline handled, "
+            "merged scratchpad validation passed."
         )
     return ok
 
@@ -749,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:

package/installer.sh

@@ -556,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"

package/package.json

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

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

@@ -60,8 +60,8 @@ AUTO_TEAM_SCOPE_ENFORCE=1
 # - 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_OVERRIDE_GOVERNANCE_REF: parseable waiver pointer when override set
+# - 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=
@@ -70,6 +70,11 @@ 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=
@@ -114,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
@@ -128,8 +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 / PO_TO_TL_HOT_MAX_SECTIONS (handoff hot caps)
-# - ARCH_HOT_MAX_LINES / ARCH_HOT_MAX_STORY_SECTIONS (architecture hot caps)
+# - 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
@@ -143,8 +150,8 @@ PO_TO_TL_HOT_MAX_LINES=800
 PO_TO_TL_HOT_MAX_SECTIONS=60
 ARCH_HOT_MAX_LINES=3500
 ARCH_HOT_MAX_STORY_SECTIONS=120
-#
-# Publish targets
+
+# Publish targets (US-0054)
 # - RELEASE_PUBLISH_MODE: disabled|confirm|auto
 #   - disabled: skip post-release publish target execution
 #   - confirm: require explicit operator confirmation before publish (default)
@@ -154,6 +161,7 @@ ARCH_HOT_MAX_STORY_SECTIONS=120
 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)
@@ -162,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)
@@ -172,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

package/template/.cursor/scratchpad.md

@@ -81,6 +81,14 @@ 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)

package/template/README.md

@@ -216,13 +216,20 @@ Recovery if `.cursor/scratchpad.md` is missing or merge validation fails:
 python installer.py --scratchpad-postinstall --target . --mode missing
 ```
 
-Upgrade behavior (US-0057):
-- Aligns with **DEC-0039** (example vs local ownership) and Model B baseline rules below.
+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 refreshed on `--mode upgrade`.
+- `.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`.
-- Existing `.cursor/scratchpad.md` is left untouched on upgrade (legacy parity).
-- 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`.

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

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

package/template/docs/engineering/runbook.md

@@ -1235,16 +1235,21 @@ Use this matrix to validate end-to-end installer/CLI lifecycle behavior:
 | Negative path | invalid mode/args | `tests/run-tests.ps1`, `tests/run-tests.sh` | Deterministic non-zero fail-fast behavior |
 | Platform parity subset | npm/brew/choco CI jobs | `.github/workflows/ci.yml` | Lifecycle subset passes on all three runners |
 
-## Scratchpad example upgrade contract (US-0057 / DEC-0039)
+## Scratchpad example upgrade contract (US-0057 / DEC-0039 / DEC-0057)
 
 `its-magic --mode upgrade` treats `.cursor/scratchpad.local.example.md` as
 framework-owned and `.cursor/scratchpad.local.md` as user-owned.
 
 Expected deterministic outcome:
-- Framework-owned example is refreshed to latest release contract.
+- Framework-owned example is refreshed to latest release contract **before** baseline
+  materialization runs in `installer.py --scratchpad-postinstall` (**DEC-0057** ordering).
 - User local scratchpad remains preserved without overwrite.
-- Installer output reports scratchpad example refresh status
-  (`added|updated|unchanged`) and preservation signal for user local file.
+- Installer output reports manifest copy status for the example file where applicable
+  (`added|updated|unchanged`) **and** `[SCRATCHPAD_LAYER]` diagnostics from post-install
+  (`example_refresh`, `baseline_materialize` / `baseline_skip`, `user_local` preserved).
+- CI regression: `python scripts/check-scratchpad-pair-parity.py --repo <root>` exit `0`
+  when active and `template/` baseline/example pairs share the same automation `KEY=`
+  set and catalog `#` headers from `# Core behavior` (**US-0075** **AC-11**).
 
 ## Scratchpad delivery Model B (US-0073 / DEC-0055)