its-magic 0.1.2-31 → 0.1.2-33

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`.
@@ -273,7 +280,7 @@ Generated test scaffolding + auto-run behavior (US-0066):
 - Static baseline test pass does not bypass runtime autopilot; runtime verdict
   remains mandatory for QA PASS.
 
-## Workflow
+## Commands and workflow
 
 ### Core commands
 
@@ -1007,25 +1014,32 @@ the safety cap (`AUTO_LOOP_MAX_CYCLES`) is reached.
 
 #### Layer 2: Local validate-and-push
 
-Run before pushing to catch anything the AI loop missed:
+Run before pushing to catch anything the AI loop missed. **Merged scratchpad** (see
+`docs/engineering/runbook.md`, **Executable validate-and-push wiring (DEC-0058)**) gates
+**`git push`**: default **`SYNC_POLICY_MODE=manual`** and **`ALLOW_AUTO_PUSH=0`** exit early
+with a **reason code** (no push). Opt-in push requires an eligible mode, **`ALLOW_AUTO_PUSH=1`**,
+a non-empty **branch allowlist** match, passing **runbook** checks, and bounded **QA** rules.
 
 ```bash
-# Bash (Linux / macOS)
-sh scripts/validate-and-push.sh
+# Bash (Linux / macOS; bash required for this script)
+bash scripts/validate-and-push.sh
 
 # PowerShell (Windows)
 powershell scripts/validate-and-push.ps1
 powershell scripts/validate-and-push.ps1 -MaxAttempts 3
+powershell scripts/validate-and-push.ps1 -DryRun
 ```
 
 The script:
-1. Runs `FORMAT_COMMAND` and `LINT_FIX_COMMAND` to auto-fix what it can
-2. Runs `LINT_COMMAND` and `TEST_COMMAND` to verify
-3. If checks fail, pauses and waits for you to fix
-4. Re-runs (up to 5 attempts, configurable)
-5. When green, commits and pushes automatically
+1. Evaluates merged scratchpad policy via **`python scripts/sync_push_gates.py`** (Python 3 on PATH)
+2. Runs `FORMAT_COMMAND` and `LINT_FIX_COMMAND` to auto-fix what it can
+3. Runs `LINT_COMMAND`, optional `TYPECHECK_COMMAND`, and `TEST_COMMAND` to verify (with `TEST_TIMEOUT_SECONDS` when `timeout`/`gtimeout` is available on Unix)
+4. If checks fail, pauses and waits for you to fix
+5. Re-runs (up to 5 attempts, configurable)
+6. When green, re-checks allowlist + QA scan, then commits and pushes automatically (unless dry-run / no-commit)
 
-Use `-NoCommit` (PowerShell) or `false` as third arg (Bash) to skip auto-push.
+Use `-NoCommit` (PowerShell), **`--dry-run`** first arg (Bash), or `false` as third arg (Bash) to skip **push**.
+**Policy-only** interpretation of scratchpad sync flags is **deprecated** for these scripts; see **`decisions/DEC-0058.md`** (policy semantics remain **`DEC-0018`** / **`US-0038`**).
 
 #### Layer 3: CI auto-fix (GitHub Actions)
 
@@ -1055,7 +1069,7 @@ push / PR  ──>  checks  ──>  PASS  ──>  done
 Auto-fix commits appear as `ci: auto-fix attempt N/3`. After 3 retries the
 workflow stops and points you to `scripts/validate-and-push` for local fixing.
 
-## Examples
+## Walkthrough examples
 
 ### Example 1: New feature from idea
 
@@ -1347,3 +1361,44 @@ flowchart TD
 - `sprints/Sxxxx/*`: sprint scope, tasks, progress, QA findings, summary.
 - `decisions/*`: decision records.
 - `handoffs/*`: role-to-role transfer notes.
+
+## Purpose
+
+This repository publishes the **its-magic** workflow kit: commands, rules, skills, and
+documentation templates that teams install into their own repositories. The goal is a
+repeatable, file-backed lifecycle from intake through release.
+
+## Quickstart
+
+Use [Setup](#setup) for install commands. First-time install:
+
+```bash
+npx its-magic --target . --mode missing --create
+```
+
+## Examples
+
+- Upgrade an existing repo: `its-magic --target . --mode upgrade`
+- Run check-in tests: use `TEST_COMMAND` from `docs/engineering/runbook.md` (often `sh tests/run-tests.sh`).
+
+## Related documentation
+
+- Operator commands and gates: `docs/engineering/runbook.md`
+- Architecture and story contracts: `docs/engineering/architecture.md`
+- Product backlog and acceptance: `docs/product/backlog.md`, `docs/product/acceptance.md`
+- Optional spec-pack mode (`SPEC_PACK_MODE=1`): engineering design artifacts under `docs/engineering/` when your team enables it
+- Optional user guides (`USER_GUIDE_MODE=1`): `docs/user-guides/` when enabled
+
+## Limitations
+
+- its-magic is a **process and documentation** framework; it does not replace your
+  application runtime, hosting, or product-specific compliance work.
+- Mixed files such as `README.md` are preserved on upgrade; review notices may appear when
+  the template adds new sections.
+- Documentation profile validation (`scripts/validate_doc_profile.py`) enforces audience and
+  depth choices from the merged scratchpad (`DOC_AUDIENCE_PROFILE`, `DOC_DETAIL_LEVEL`).
+
+## Contributing
+
+Contributor-focused workflow and guardrails live in
+[`docs/developer/README.md`](docs/developer/README.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

@@ -122,6 +122,7 @@ function Classify-File($RelPath) {
     '.cursor/hooks/',
     '.github/workflows/',
     'scripts/validate-and-push',
+    'scripts/sync_push_gates',
     'docs/engineering/context/',
     'its_magic/'
   )
@@ -664,6 +665,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,72 @@ 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 _doc_profile_sync(target_root, merged, print_ok=True):
+    """Append missing normative README/developer doc sections from merged profile (non-destructive)."""
+    scripts_dir = os.path.join(normalize(os.path.dirname(__file__)), "scripts")
+    if scripts_dir not in sys.path:
+        sys.path.insert(0, scripts_dir)
+    import doc_profile_lib
+
+    notes = doc_profile_lib.ensure_doc_surfaces_merged(merged, target_root, print_ok=print_ok)
+    bad = [ln for ln in notes if ln.startswith("[DOC_PROFILE_INVALID]")]
+    return (not bad), notes
+
+
 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:
+        merged, _paths = merge_scratchpad_layers(target_root)
+        dp_ok, dp_notes = _doc_profile_sync(target_root, merged, print_ok=print_ok)
+        for line in dp_notes:
+            print(line)
+        if not dp_ok:
+            ok = False
     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 +812,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

@@ -157,7 +157,7 @@ classify_file() {
     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" ;;
+    .github/workflows/*|scripts/validate-and-push*|scripts/sync_push_gates.py|docs/engineering/context/*|its_magic/*) echo "framework" ;;
     .its-magic-version|its_magic/.its-magic-version|its_magic/README.md) echo "framework" ;;
     docs/product/*|docs/engineering/*|docs/user-guides/*) echo "user-data" ;;
     sprints/*|handoffs/*|decisions/*) echo "user-data" ;;
@@ -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-33",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {

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

@@ -193,7 +193,14 @@ Release gate semantics (US-0039): mandatory gates (check-in test, QA, UAT) and n
      scan roots in `scripts/check-user-visible-metadata.py` **and** this runbook
      section together or fail closed with `METADATA_SANITIZATION_SCOPE_AMBIGUOUS`
      semantics at QA/release.
-21. Triad hot-surface enforcement (DEC-0054):
+21. Documentation profile validation (US-0077 / DEC-0059):
+   - When you change `README.md`, `docs/developer/README.md`, scratchpad profile keys
+     (`DOC_AUDIENCE_PROFILE`, `DOC_DETAIL_LEVEL`), or `scripts/doc_profile_lib.py` /
+     `scripts/validate_doc_profile.py`, run `python scripts/validate_doc_profile.py --repo <root>`.
+   - Fail closed on `DOC_PROFILE_INVALID`, `DOC_PROFILE_MERGE_ERROR`,
+     `DOC_SECTION_MISSING:*`, `DOC_SECTION_BUDGET_EXCEEDED`, or `DOC_TEMPLATE_PARITY_FAIL`
+     (see `docs/engineering/runbook.md`).
+22. Triad hot-surface enforcement (DEC-0054):
    - Before completing `/execute`, run
      `python scripts/enforce-triad-hot-surface.py --check` from repository root
      (or `--repo <root>`).

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

@@ -24,7 +24,7 @@ globs: ["**/*"]
   (local pre-push) → CI auto-fix (GitHub Actions). Each layer catches issues
   the previous layer missed.
 - Before pushing, recommend running `scripts/validate-and-push.ps1` (Windows)
-  or `scripts/validate-and-push.sh` (Linux/Mac) to catch failures locally.
+  or `bash scripts/validate-and-push.sh` (Linux/Mac) to catch failures locally.
 - `LINT_FIX_COMMAND` and `FORMAT_COMMAND` in the runbook enable automatic
   formatting/lint fixes both locally and in CI.
 - Remote config validation errors (when `REMOTE_EXECUTION=1`) must be fail-fast

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,25 @@ 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
+
+# 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

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)
@@ -189,3 +197,9 @@ SPEC_PACK_MODE=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
+

package/template/.github/workflows/ci.yml

@@ -186,7 +186,7 @@ jobs:
           echo ""
           echo "What to do next:"
           echo "  1. Pull the latest changes"
-          echo "  2. Run:  sh scripts/validate-and-push.sh"
+          echo "  2. Run:  bash scripts/validate-and-push.sh"
           echo "     (or:  powershell scripts/validate-and-push.ps1)"
           echo "  3. Fix failures, the script loops until green, then pushes."
 

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`.
@@ -273,7 +280,7 @@ Generated test scaffolding + auto-run behavior (US-0066):
 - Static baseline test pass does not bypass runtime autopilot; runtime verdict
   remains mandatory for QA PASS.
 
-## Workflow
+## Commands and workflow
 
 ### Core commands
 
@@ -1007,25 +1014,32 @@ the safety cap (`AUTO_LOOP_MAX_CYCLES`) is reached.
 
 #### Layer 2: Local validate-and-push
 
-Run before pushing to catch anything the AI loop missed:
+Run before pushing to catch anything the AI loop missed. **Merged scratchpad** (see
+`docs/engineering/runbook.md`, **Executable validate-and-push wiring (DEC-0058)**) gates
+**`git push`**: default **`SYNC_POLICY_MODE=manual`** and **`ALLOW_AUTO_PUSH=0`** exit early
+with a **reason code** (no push). Opt-in push requires an eligible mode, **`ALLOW_AUTO_PUSH=1`**,
+a non-empty **branch allowlist** match, passing **runbook** checks, and bounded **QA** rules.
 
 ```bash
-# Bash (Linux / macOS)
-sh scripts/validate-and-push.sh
+# Bash (Linux / macOS; bash required for this script)
+bash scripts/validate-and-push.sh
 
 # PowerShell (Windows)
 powershell scripts/validate-and-push.ps1
 powershell scripts/validate-and-push.ps1 -MaxAttempts 3
+powershell scripts/validate-and-push.ps1 -DryRun
 ```
 
 The script:
-1. Runs `FORMAT_COMMAND` and `LINT_FIX_COMMAND` to auto-fix what it can
-2. Runs `LINT_COMMAND` and `TEST_COMMAND` to verify
-3. If checks fail, pauses and waits for you to fix
-4. Re-runs (up to 5 attempts, configurable)
-5. When green, commits and pushes automatically
+1. Evaluates merged scratchpad policy via **`python scripts/sync_push_gates.py`** (Python 3 on PATH)
+2. Runs `FORMAT_COMMAND` and `LINT_FIX_COMMAND` to auto-fix what it can
+3. Runs `LINT_COMMAND`, optional `TYPECHECK_COMMAND`, and `TEST_COMMAND` to verify (with `TEST_TIMEOUT_SECONDS` when `timeout`/`gtimeout` is available on Unix)
+4. If checks fail, pauses and waits for you to fix
+5. Re-runs (up to 5 attempts, configurable)
+6. When green, re-checks allowlist + QA scan, then commits and pushes automatically (unless dry-run / no-commit)
 
-Use `-NoCommit` (PowerShell) or `false` as third arg (Bash) to skip auto-push.
+Use `-NoCommit` (PowerShell), **`--dry-run`** first arg (Bash), or `false` as third arg (Bash) to skip **push**.
+**Policy-only** interpretation of scratchpad sync flags is **deprecated** for these scripts; see **`decisions/DEC-0058.md`** (policy semantics remain **`DEC-0018`** / **`US-0038`**).
 
 #### Layer 3: CI auto-fix (GitHub Actions)
 
@@ -1055,7 +1069,7 @@ push / PR  ──>  checks  ──>  PASS  ──>  done
 Auto-fix commits appear as `ci: auto-fix attempt N/3`. After 3 retries the
 workflow stops and points you to `scripts/validate-and-push` for local fixing.
 
-## Examples
+## Walkthrough examples
 
 ### Example 1: New feature from idea
 
@@ -1347,3 +1361,44 @@ flowchart TD
 - `sprints/Sxxxx/*`: sprint scope, tasks, progress, QA findings, summary.
 - `decisions/*`: decision records.
 - `handoffs/*`: role-to-role transfer notes.
+
+## Purpose
+
+This repository publishes the **its-magic** workflow kit: commands, rules, skills, and
+documentation templates that teams install into their own repositories. The goal is a
+repeatable, file-backed lifecycle from intake through release.
+
+## Quickstart
+
+Use [Setup](#setup) for install commands. First-time install:
+
+```bash
+npx its-magic --target . --mode missing --create
+```
+
+## Examples
+
+- Upgrade an existing repo: `its-magic --target . --mode upgrade`
+- Run check-in tests: use `TEST_COMMAND` from `docs/engineering/runbook.md` (often `sh tests/run-tests.sh`).
+
+## Related documentation
+
+- Operator commands and gates: `docs/engineering/runbook.md`
+- Architecture and story contracts: `docs/engineering/architecture.md`
+- Product backlog and acceptance: `docs/product/backlog.md`, `docs/product/acceptance.md`
+- Optional spec-pack mode (`SPEC_PACK_MODE=1`): engineering design artifacts under `docs/engineering/` when your team enables it
+- Optional user guides (`USER_GUIDE_MODE=1`): `docs/user-guides/` when enabled
+
+## Limitations
+
+- its-magic is a **process and documentation** framework; it does not replace your
+  application runtime, hosting, or product-specific compliance work.
+- Mixed files such as `README.md` are preserved on upgrade; review notices may appear when
+  the template adds new sections.
+- Documentation profile validation (`scripts/validate_doc_profile.py`) enforces audience and
+  depth choices from the merged scratchpad (`DOC_AUDIENCE_PROFILE`, `DOC_DETAIL_LEVEL`).
+
+## Contributing
+
+Contributor-focused workflow and guardrails live in
+[`docs/developer/README.md`](docs/developer/README.md).