its-magic 0.1.2-32 → 0.1.2-33

package/template/scripts/validate-and-push.ps1

@@ -4,16 +4,16 @@
 # Part of the its-magic quality chain:
 #   Cursor AI loop  →  validate-and-push  →  CI auto-fix (GitHub)
 #
-# Reads TEST_COMMAND (and optionally LINT_COMMAND / TYPECHECK_COMMAND /
-# LINT_FIX_COMMAND / FORMAT_COMMAND)
-# from docs/engineering/runbook.md, runs them in a loop, and pushes
-# only when everything passes.
+# Reads merged scratchpad (installer merge / DEC-0055) for sync policy and
+# runbook keys for commands. Opt-in push only when policy allows; reason codes
+# on stdout/stderr. See docs/engineering/runbook.md (executable wiring: DEC-0058).
 # -------------------------------------------------------------------
 
 Param(
   [int]$MaxAttempts = 5,
   [string]$Branch,
-  [switch]$NoCommit
+  [switch]$NoCommit,
+  [switch]$DryRun
 )
 
 $ErrorActionPreference = "Stop"
@@ -24,7 +24,38 @@ function Log-Pass  { param($Msg) Write-Host "[pass]  $Msg" -ForegroundColor Gree
 function Log-Fail  { param($Msg) Write-Host "[fail]  $Msg" -ForegroundColor Red }
 function Log-Warn  { param($Msg) Write-Host "[warn]  $Msg" -ForegroundColor Yellow }
 
-# --- Read commands from runbook ------------------------------------------
+function Resolve-PythonExe {
+  foreach ($name in @("python", "python3")) {
+    $cmd = Get-Command $name -ErrorAction SilentlyContinue
+    if ($cmd) { return $cmd.Source }
+  }
+  return $null
+}
+
+function Invoke-GateJson {
+  param(
+    [string]$PythonExe,
+    [string]$GateScript,
+    [string]$SubCommand,
+    [string]$RepoRoot,
+    [string]$BranchName
+  )
+  $outFile = [System.IO.Path]::GetTempFileName()
+  $errFile = [System.IO.Path]::GetTempFileName()
+  try {
+    $p = Start-Process -FilePath $PythonExe `
+      -ArgumentList @($GateScript, $SubCommand, "--root", $RepoRoot, "--branch", $BranchName) `
+      -Wait -PassThru -NoNewWindow `
+      -RedirectStandardOutput $outFile -RedirectStandardError $errFile
+    $stderr = if (Test-Path $errFile) { Get-Content -Raw -Path $errFile } else { "" }
+    $stdout = if (Test-Path $outFile) { Get-Content -Raw -Path $outFile } else { "" }
+    if ($stderr.Trim().Length -gt 0) { Write-Host $stderr.TrimEnd() }
+    return @{ ExitCode = $p.ExitCode; StdOut = $stdout.Trim() }
+  }
+  finally {
+    Remove-Item -Path $outFile, $errFile -ErrorAction SilentlyContinue
+  }
+}
 
 function Read-RunbookKey {
   param([string]$Key)
@@ -38,16 +69,16 @@ function Read-RunbookKey {
   return $val
 }
 
-$TestCmd    = Read-RunbookKey "TEST_COMMAND"
-$LintCmd    = Read-RunbookKey "LINT_COMMAND"
-$TypecheckCmd = Read-RunbookKey "TYPECHECK_COMMAND"
-$LintFixCmd = Read-RunbookKey "LINT_FIX_COMMAND"
-$FormatCmd  = Read-RunbookKey "FORMAT_COMMAND"
+$py = Resolve-PythonExe
+if (-not $py) {
+  Log-Fail "reason_code=PYTHON_NOT_ON_PATH"
+  Log-Warn "Install Python 3 and ensure it is on PATH for merged scratchpad policy gates."
+  exit 1
+}
 
-if (-not $TestCmd -and -not $LintCmd) {
-  Log-Warn "No TEST_COMMAND or LINT_COMMAND found in docs/engineering/runbook.md"
-  Log-Warn "TEST_COMMAND is required by sync policy for push-eligible paths."
-  Log-Warn "Fill in the runbook first, then re-run."
+$gateScript = Join-Path $root "scripts\sync_push_gates.py"
+if (-not (Test-Path $gateScript -PathType Leaf)) {
+  Log-Fail "reason_code=SYNC_GATE_SCRIPT_MISSING"
   exit 1
 }
 
@@ -58,22 +89,75 @@ if (-not $Branch) {
 
 Log-Info "validate-and-push loop"
 Log-Info "Branch: $Branch  |  Max attempts: $MaxAttempts"
+if ($DryRun) { Log-Info "Dry-run: no git push will run." }
+Write-Host ""
+
+$pol = Invoke-GateJson -PythonExe $py -GateScript $gateScript -SubCommand "policy" -RepoRoot $root -BranchName $Branch
+try {
+  $polObj = $pol.StdOut | ConvertFrom-Json
+} catch {
+  Log-Fail "reason_code=SYNC_POLICY_PARSE_FAILED"
+  exit 1
+}
+if (-not $polObj.ok) {
+  Log-Fail ("reason_code=" + $polObj.reason_code)
+  exit 1
+}
+
+$TestCmd      = Read-RunbookKey "TEST_COMMAND"
+$LintCmd      = Read-RunbookKey "LINT_COMMAND"
+$TypecheckCmd = Read-RunbookKey "TYPECHECK_COMMAND"
+$LintFixCmd   = Read-RunbookKey "LINT_FIX_COMMAND"
+$FormatCmd    = Read-RunbookKey "FORMAT_COMMAND"
+$timeoutRaw   = Read-RunbookKey "TEST_TIMEOUT_SECONDS"
+$TestTimeoutSec = 120
+if ($timeoutRaw -match '^\d+$') { $TestTimeoutSec = [int]$timeoutRaw }
+
+if (-not $TestCmd) {
+  Log-Fail "reason_code=TEST_COMMAND_MISSING"
+  Log-Warn "TEST_COMMAND is required by sync policy for push-eligible paths."
+  exit 1
+}
+
 if ($TestCmd)    { Log-Info "TEST_COMMAND:     $TestCmd" }
 if ($LintCmd)    { Log-Info "LINT_COMMAND:     $LintCmd" }
 if ($TypecheckCmd) { Log-Info "TYPECHECK_COMMAND: $TypecheckCmd" }
 if ($LintFixCmd) { Log-Info "LINT_FIX_COMMAND: $LintFixCmd" }
 if ($FormatCmd)  { Log-Info "FORMAT_COMMAND:   $FormatCmd" }
+Log-Info "TEST_TIMEOUT_SECONDS: $TestTimeoutSec"
 Write-Host ""
 
 function Run-Cmd {
-  param([string]$Cmd)
+  param([string]$Cmd, [int]$TimeoutSec = 0)
   $prev = $ErrorActionPreference
   $ErrorActionPreference = "Continue"
   try {
-    Invoke-Expression $Cmd
-    return $LASTEXITCODE -eq 0
-  } catch {
-    return $false
+    if ($TimeoutSec -le 0) {
+      Invoke-Expression $Cmd
+      return @{ Ok = ($LASTEXITCODE -eq 0); TimedOut = $false }
+    }
+    $job = Start-Job -ScriptBlock {
+      param($c, $r)
+      Set-Location $r
+      try {
+        Invoke-Expression $c | Out-Null
+      } catch {
+        return 1
+      }
+      if ($null -eq $LASTEXITCODE) { return 0 }
+      return $LASTEXITCODE
+    } -ArgumentList $Cmd, $root
+    $finished = Wait-Job -Job $job -Timeout $TimeoutSec
+    if (-not $finished -or $job.State -eq "Running") {
+      Stop-Job -Job $job -ErrorAction SilentlyContinue
+      Remove-Job -Job $job -Force -ErrorAction SilentlyContinue
+      return @{ Ok = $false; TimedOut = $true }
+    }
+    $code = Receive-Job -Job $job
+    Remove-Job -Job $job -Force -ErrorAction SilentlyContinue
+    $exitNum = 1
+    if ($null -ne $code) { $exitNum = [int]$code[-1] }
+    return @{ Ok = ($exitNum -eq 0); TimedOut = $false }
   } finally {
     $ErrorActionPreference = $prev
   }
@@ -86,51 +170,49 @@ for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
   Push-Location $root
   $allOk = $true
 
-  # 1. Run formatter if available
   if ($FormatCmd) {
     Log-Info "Running formatter..."
-    if (Run-Cmd $FormatCmd) {
-      Log-Pass "Format OK"
-    } else {
-      Log-Warn "Formatter reported issues (non-blocking)"
-    }
+    $r = Run-Cmd -Cmd $FormatCmd -TimeoutSec 0
+    if ($r.Ok) { Log-Pass "Format OK" } else { Log-Warn "Formatter reported issues (non-blocking)" }
   }
 
-  # 2. Try lint fix if available
   if ($LintFixCmd) {
     Log-Info "Running lint auto-fix..."
-    Run-Cmd $LintFixCmd | Out-Null
+    Run-Cmd -Cmd $LintFixCmd -TimeoutSec 0 | Out-Null
   }
 
-  # 3. Run lint check
   if ($LintCmd) {
     Log-Info "Running lint check..."
-    if (Run-Cmd $LintCmd) {
-      Log-Pass "Lint OK"
-    } else {
-      Log-Fail "Lint failed"
+    $r = Run-Cmd -Cmd $LintCmd -TimeoutSec $TestTimeoutSec
+    if ($r.TimedOut) {
+      Log-Fail "reason_code=OPTIONAL_CHECK_FAILED"
+      $allOk = $false
+    } elseif ($r.Ok) { Log-Pass "Lint OK" } else {
+      Log-Fail "reason_code=OPTIONAL_CHECK_FAILED"
       $allOk = $false
     }
   }
 
-  # 4. Run typecheck (optional)
   if ($TypecheckCmd) {
     Log-Info "Running typecheck..."
-    if (Run-Cmd $TypecheckCmd) {
-      Log-Pass "Typecheck OK"
-    } else {
-      Log-Fail "Typecheck failed"
+    $r = Run-Cmd -Cmd $TypecheckCmd -TimeoutSec $TestTimeoutSec
+    if ($r.TimedOut) {
+      Log-Fail "reason_code=OPTIONAL_CHECK_FAILED"
+      $allOk = $false
+    } elseif ($r.Ok) { Log-Pass "Typecheck OK" } else {
+      Log-Fail "reason_code=OPTIONAL_CHECK_FAILED"
       $allOk = $false
     }
   }
 
-  # 5. Run tests
   if ($TestCmd) {
     Log-Info "Running tests..."
-    if (Run-Cmd $TestCmd) {
-      Log-Pass "Tests OK"
-    } else {
-      Log-Fail "Tests failed"
+    $r = Run-Cmd -Cmd $TestCmd -TimeoutSec $TestTimeoutSec
+    if ($r.TimedOut) {
+      Log-Fail "reason_code=TEST_TIMEOUT"
+      $allOk = $false
+    } elseif ($r.Ok) { Log-Pass "Tests OK" } else {
+      Log-Fail "reason_code=TEST_FAILED"
       $allOk = $false
     }
   }
@@ -158,23 +240,41 @@ for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
 
 if (-not $passed) { exit 1 }
 
+$post = Invoke-GateJson -PythonExe $py -GateScript $gateScript -SubCommand "post" -RepoRoot $root -BranchName $Branch
+try {
+  $postObj = $post.StdOut | ConvertFrom-Json
+} catch {
+  Log-Fail "reason_code=SYNC_POST_PARSE_FAILED"
+  exit 1
+}
+if (-not $postObj.ok) {
+  Log-Fail ("reason_code=" + $postObj.reason_code)
+  exit 1
+}
+
 Write-Host ""
 
-if (-not $NoCommit) {
-  Push-Location $root
-  $status = git status --porcelain
-  if ($status) {
-    Log-Info "Staging and committing changes..."
-    git add -A
-    git commit -m "fix: address check failures (validate-and-push)"
+if ($DryRun -or $NoCommit) {
+  if ($DryRun) {
+    Log-Pass "reason_code=SYNC_PUSHED (dry-run; no git push)"
   } else {
-    Log-Info "Working tree clean, nothing to commit."
+    Log-Info "Auto-commit disabled (--NoCommit). Push manually when ready."
+    Log-Pass "reason_code=SYNC_PUSHED (checks only; push skipped by flag)"
   }
+  exit 0
+}
 
-  Log-Info "Pushing to origin/$Branch..."
-  git push origin $Branch
-  Log-Pass "Push successful."
-  Pop-Location
+Push-Location $root
+$status = git status --porcelain
+if ($status) {
+  Log-Info "Staging and committing changes..."
+  git add -A
+  git commit -m "fix: address check failures (validate-and-push)"
 } else {
-  Log-Info "Auto-commit disabled (--NoCommit). Push manually when ready."
+  Log-Info "Working tree clean, nothing to commit."
 }
+
+Log-Info "Pushing to origin/$Branch..."
+git push origin $Branch
+Log-Pass "reason_code=SYNC_PUSHED"
+Pop-Location

package/template/scripts/validate-and-push.sh

@@ -1,18 +1,25 @@
-#!/usr/bin/env sh
+#!/usr/bin/env bash
 # -------------------------------------------------------------------
 # validate-and-push.sh — local test-fix-push loop
 #
 # Part of the its-magic quality chain:
 #   Cursor AI loop  →  validate-and-push  →  CI auto-fix (GitHub)
 #
-# Reads TEST_COMMAND (and optionally LINT_COMMAND / TYPECHECK_COMMAND /
-# LINT_FIX_COMMAND / FORMAT_COMMAND)
-# from docs/engineering/runbook.md, runs them in a loop, and pushes
-# only when everything passes.
+# Bash is required for safe eval + optional timeout wrapping (DEC-0058 / parity
+# with validate-and-push.ps1).
+#
+# Reads merged scratchpad (installer merge) for sync policy and runbook keys
+# for commands. Opt-in push only when policy allows. See runbook (DEC-0058).
 # -------------------------------------------------------------------
-set -e
+set -euo pipefail
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+DRY_RUN=0
+if [ "${1:-}" = "--dry-run" ]; then
+  DRY_RUN=1
+  shift
+fi
+
 MAX_ATTEMPTS="${1:-5}"
 BRANCH="${2:-}"
 AUTO_COMMIT="${3:-true}"
@@ -28,13 +35,54 @@ log_pass()  { printf "${pass_color}[pass]${reset}  %s\n" "$*"; }
 log_fail()  { printf "${fail_color}[fail]${reset}  %s\n" "$*"; }
 log_warn()  { printf "${warn_color}[warn]${reset}  %s\n" "$*"; }
 
-# --- Read commands from runbook ------------------------------------------
+resolve_python() {
+  if command -v python >/dev/null 2>&1; then printf "%s" "python"; return; fi
+  if command -v python3 >/dev/null 2>&1; then printf "%s" "python3"; return; fi
+  printf "%s" ""
+}
+
+run_with_timeout() {
+  local sec="$1"
+  shift
+  if command -v timeout >/dev/null 2>&1; then
+    timeout "$sec" "$@"
+  elif command -v gtimeout >/dev/null 2>&1; then
+    gtimeout "$sec" "$@"
+  else
+    "$@"
+  fi
+}
+
+# Run runbook command string from repo root; optional wall-clock cap.
+run_runbook_cmd() {
+  local cmd="$1"
+  local kind="$2"
+  local sec="$3"
+  if command -v timeout >/dev/null 2>&1 || command -v gtimeout >/dev/null 2>&1; then
+    if ! run_with_timeout "$sec" bash -c 'cd "$1" && eval "$2"' _ "$ROOT" "$cmd"; then
+      local ec=$?
+      if [ "$kind" = "test" ]; then
+        if [ "$ec" = "124" ] || [ "$ec" = "143" ]; then log_fail "reason_code=TEST_TIMEOUT"; else log_fail "reason_code=TEST_FAILED"; fi
+      else
+        log_fail "reason_code=OPTIONAL_CHECK_FAILED"
+      fi
+      return 1
+    fi
+  else
+    if ! ( cd "$ROOT" && eval "$cmd" ); then
+      if [ "$kind" = "test" ]; then log_fail "reason_code=TEST_FAILED"; else log_fail "reason_code=OPTIONAL_CHECK_FAILED"; fi
+      return 1
+    fi
+  fi
+  return 0
+}
 
 RUNBOOK="$ROOT/docs/engineering/runbook.md"
 
 read_runbook_key() {
-  key="$1"
+  local key="$1"
   if [ ! -f "$RUNBOOK" ]; then return; fi
+  local value
   value=$(sed -n "s/^${key}:[[:space:]]*\(.\{1,\}\)$/\1/p" "$RUNBOOK" | head -n 1)
   case "$value" in
     ""|"..."|"<...>"|"TODO") return ;;
@@ -42,16 +90,40 @@ read_runbook_key() {
   printf "%s" "$value"
 }
 
-TEST_CMD=$(read_runbook_key "TEST_COMMAND")
-LINT_CMD=$(read_runbook_key "LINT_COMMAND")
-TYPECHECK_CMD=$(read_runbook_key "TYPECHECK_COMMAND")
-LINT_FIX_CMD=$(read_runbook_key "LINT_FIX_COMMAND")
-FORMAT_CMD=$(read_runbook_key "FORMAT_COMMAND")
+run_sync_gate() {
+  local sub="$1"
+  local out err line gate_ok gate_rc
+  out="$(mktemp)"
+  err="$(mktemp)"
+  set +e
+  "$PY" "$GATE_SCRIPT" "$sub" --root "$ROOT" --branch "$BRANCH" >"$out" 2>"$err"
+  set -e
+  if [ -s "$err" ]; then cat "$err" >&2; fi
+  line="$(grep '^{' "$out" | tail -n 1)"
+  rm -f "$out" "$err"
+  if [ -z "$line" ]; then
+    log_fail "reason_code=SYNC_GATE_EMPTY_RESPONSE"
+    return 1
+  fi
+  gate_ok="$("$PY" -c "import json,sys; print(1 if json.loads(sys.argv[1]).get('ok') else 0)" "$line" 2>/dev/null || echo 0)"
+  gate_rc="$("$PY" -c "import json,sys; print(json.loads(sys.argv[1]).get('reason_code') or '')" "$line" 2>/dev/null || true)"
+  if [ "$gate_ok" != "1" ]; then
+    log_fail "reason_code=${gate_rc:-SYNC_GATE_BLOCK}"
+    return 1
+  fi
+  return 0
+}
 
-if [ -z "$TEST_CMD" ] && [ -z "$LINT_CMD" ]; then
-  log_warn "No TEST_COMMAND or LINT_COMMAND found in docs/engineering/runbook.md"
-  log_warn "TEST_COMMAND is required by sync policy for push-eligible paths."
-  log_warn "Fill in the runbook first, then re-run."
+PY="$(resolve_python)"
+if [ -z "$PY" ]; then
+  log_fail "reason_code=PYTHON_NOT_ON_PATH"
+  log_warn "Install Python 3 and ensure it is on PATH for merged scratchpad policy gates."
+  exit 1
+fi
+
+GATE_SCRIPT="$ROOT/scripts/sync_push_gates.py"
+if [ ! -f "$GATE_SCRIPT" ]; then
+  log_fail "reason_code=SYNC_GATE_SCRIPT_MISSING"
   exit 1
 fi
 
@@ -61,11 +133,35 @@ fi
 
 log_info "validate-and-push loop"
 log_info "Branch: $BRANCH  |  Max attempts: $MAX_ATTEMPTS"
-[ -n "$TEST_CMD" ]     && log_info "TEST_COMMAND:     $TEST_CMD"
-[ -n "$LINT_CMD" ]     && log_info "LINT_COMMAND:     $LINT_CMD"
+if [ "$DRY_RUN" = "1" ]; then log_info "Dry-run: no git push will run."; fi
+printf "\n"
+
+if ! run_sync_gate policy; then exit 1; fi
+
+TEST_CMD=$(read_runbook_key "TEST_COMMAND")
+LINT_CMD=$(read_runbook_key "LINT_COMMAND")
+TYPECHECK_CMD=$(read_runbook_key "TYPECHECK_COMMAND")
+LINT_FIX_CMD=$(read_runbook_key "LINT_FIX_COMMAND")
+FORMAT_CMD=$(read_runbook_key "FORMAT_COMMAND")
+TIMEOUT_RAW=$(read_runbook_key "TEST_TIMEOUT_SECONDS")
+TEST_TIMEOUT_SEC=120
+case "$TIMEOUT_RAW" in
+  ''|*[!0-9]*) ;;
+  *) TEST_TIMEOUT_SEC="$TIMEOUT_RAW" ;;
+esac
+
+if [ -z "$TEST_CMD" ]; then
+  log_fail "reason_code=TEST_COMMAND_MISSING"
+  log_warn "TEST_COMMAND is required by sync policy for push-eligible paths."
+  exit 1
+fi
+
+[ -n "$TEST_CMD" ] && log_info "TEST_COMMAND:     $TEST_CMD"
+[ -n "$LINT_CMD" ] && log_info "LINT_COMMAND:     $LINT_CMD"
 [ -n "$TYPECHECK_CMD" ] && log_info "TYPECHECK_COMMAND: $TYPECHECK_CMD"
 [ -n "$LINT_FIX_CMD" ] && log_info "LINT_FIX_COMMAND: $LINT_FIX_CMD"
-[ -n "$FORMAT_CMD" ]   && log_info "FORMAT_COMMAND:   $FORMAT_CMD"
+[ -n "$FORMAT_CMD" ] && log_info "FORMAT_COMMAND:   $FORMAT_CMD"
+log_info "TEST_TIMEOUT_SECONDS: $TEST_TIMEOUT_SEC"
 printf "\n"
 
 attempt=0
@@ -76,53 +172,29 @@ while [ "$attempt" -lt "$MAX_ATTEMPTS" ]; do
   cd "$ROOT"
   all_ok=true
 
-  # 1. Run formatter if available
   if [ -n "$FORMAT_CMD" ]; then
     log_info "Running formatter..."
-    if eval "$FORMAT_CMD"; then
-      log_pass "Format OK"
-    else
-      log_warn "Formatter reported issues (non-blocking)"
-    fi
+    if eval "$FORMAT_CMD"; then log_pass "Format OK"; else log_warn "Formatter reported issues (non-blocking)"; fi
   fi
 
-  # 2. Try lint fix if available
   if [ -n "$LINT_FIX_CMD" ]; then
     log_info "Running lint auto-fix..."
     eval "$LINT_FIX_CMD" || true
   fi
 
-  # 3. Run lint check
   if [ -n "$LINT_CMD" ]; then
     log_info "Running lint check..."
-    if eval "$LINT_CMD"; then
-      log_pass "Lint OK"
-    else
-      log_fail "Lint failed"
-      all_ok=false
-    fi
+    if run_runbook_cmd "$LINT_CMD" "optional" "$TEST_TIMEOUT_SEC"; then log_pass "Lint OK"; else all_ok=false; fi
   fi
 
-  # 4. Run typecheck (optional)
   if [ -n "$TYPECHECK_CMD" ]; then
     log_info "Running typecheck..."
-    if eval "$TYPECHECK_CMD"; then
-      log_pass "Typecheck OK"
-    else
-      log_fail "Typecheck failed"
-      all_ok=false
-    fi
+    if run_runbook_cmd "$TYPECHECK_CMD" "optional" "$TEST_TIMEOUT_SEC"; then log_pass "Typecheck OK"; else all_ok=false; fi
   fi
 
-  # 5. Run tests
   if [ -n "$TEST_CMD" ]; then
     log_info "Running tests..."
-    if eval "$TEST_CMD"; then
-      log_pass "Tests OK"
-    else
-      log_fail "Tests failed"
-      all_ok=false
-    fi
+    if run_runbook_cmd "$TEST_CMD" "test" "$TEST_TIMEOUT_SEC"; then log_pass "Tests OK"; else all_ok=false; fi
   fi
 
   if [ "$all_ok" = "true" ]; then
@@ -134,7 +206,7 @@ while [ "$attempt" -lt "$MAX_ATTEMPTS" ]; do
     log_fail "Reached max attempts ($MAX_ATTEMPTS). Aborting push."
     printf "\n"
     log_warn "Fix the issues above, then re-run:"
-    log_warn "  sh scripts/validate-and-push.sh"
+    log_warn "  bash scripts/validate-and-push.sh"
     exit 1
   fi
 
@@ -143,21 +215,29 @@ while [ "$attempt" -lt "$MAX_ATTEMPTS" ]; do
   read -r _unused
 done
 
+if ! run_sync_gate post; then exit 1; fi
+
 printf "\n"
 
-if [ "$AUTO_COMMIT" = "true" ]; then
-  cd "$ROOT"
-  if [ -n "$(git status --porcelain)" ]; then
-    log_info "Staging and committing changes..."
-    git add -A
-    git commit -m "fix: address check failures (validate-and-push)"
+if [ "$DRY_RUN" = "1" ] || [ "$AUTO_COMMIT" != "true" ]; then
+  if [ "$DRY_RUN" = "1" ]; then
+    log_pass "reason_code=SYNC_PUSHED (dry-run; no git push)"
   else
-    log_info "Working tree clean, nothing to commit."
+    log_info "Auto-commit disabled. Push manually when ready."
+    log_pass "reason_code=SYNC_PUSHED (checks only; push skipped by flag)"
   fi
+  exit 0
+fi
 
-  log_info "Pushing to origin/$BRANCH..."
-  git push origin "$BRANCH"
-  log_pass "Push successful."
+cd "$ROOT"
+if [ -n "$(git status --porcelain)" ]; then
+  log_info "Staging and committing changes..."
+  git add -A
+  git commit -m "fix: address check failures (validate-and-push)"
 else
-  log_info "Auto-commit disabled. Push manually when ready."
+  log_info "Working tree clean, nothing to commit."
 fi
+
+log_info "Pushing to origin/$BRANCH..."
+git push origin "$BRANCH"
+log_pass "reason_code=SYNC_PUSHED"

package/template/scripts/validate_doc_profile.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Validate documentation profile surfaces (DEC-0059).
+
+Reads merged scratchpad via installer.merge_scratchpad_layers (DEC-0058 pattern).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+# Repo root (parent of scripts/)
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.normpath(os.path.join(_SCRIPT_DIR, ".."))
+
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import installer  # noqa: E402
+import doc_profile_lib  # noqa: E402
+
+
+def _fail(messages: list[str]) -> int:
+    for m in messages:
+        print(m, file=sys.stderr)
+    return 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Validate README/doc profile vs merged scratchpad.")
+    parser.add_argument(
+        "--repo",
+        default=_REPO_ROOT,
+        help="Target repository root (default: parent of scripts/).",
+    )
+    parser.add_argument(
+        "--no-template-parity",
+        action="store_true",
+        help="Skip active vs template/ parity (for fixture-only trees).",
+    )
+    parser.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Run resolver matrix self-test and exit.",
+    )
+    args = parser.parse_args()
+
+    if args.self_test:
+        doc_profile_lib.self_test_resolver()
+        print("[DOC_PROFILE_SELF_TEST_OK]")
+        return 0
+
+    target = os.path.abspath(args.repo)
+    template_root = None if args.no_template_parity else os.path.join(target, "template")
+
+    merged, paths = installer.merge_scratchpad_layers(target)
+    merge_errors: list[str] = []
+    if not os.path.isfile(paths["example"]):
+        merge_errors.append(
+            "[DOC_PROFILE_MERGE_ERROR] EXAMPLE_LAYER_MISSING: "
+            f".cursor/scratchpad.local.example.md not found under {target}."
+        )
+    if not os.path.isfile(paths["baseline"]):
+        merge_errors.append(
+            "[DOC_PROFILE_MERGE_ERROR] MATERIALIZED_BASELINE_MISSING: "
+            f".cursor/scratchpad.md not found under {target}."
+        )
+    if merge_errors:
+        return _fail(merge_errors)
+
+    ok, scratch_diagnostics = installer.validate_merged_scratchpad(target)
+    if not ok:
+        out = [ln for ln in scratch_diagnostics if "SCRATCHPAD_MERGE_ERROR" in ln or "REQUIRED_KEY" in ln]
+        mapped = [
+            ln.replace("[SCRATCHPAD_MERGE_ERROR]", "[DOC_PROFILE_MERGE_ERROR]", 1)
+            if ln.startswith("[SCRATCHPAD_MERGE_ERROR]")
+            else f"[DOC_PROFILE_MERGE_ERROR] {ln}"
+            for ln in (out or scratch_diagnostics)
+        ]
+        return _fail(mapped)
+
+    readme_path = os.path.join(target, "README.md")
+    readme_txt = ""
+    if os.path.isfile(readme_path):
+        with open(readme_path, "r", encoding="utf-8") as f:
+            readme_txt = f.read()
+    for w in doc_profile_lib.optional_mode_warnings(merged, readme_txt):
+        print(w, file=sys.stderr)
+
+    errs = doc_profile_lib.validate_repo_doc_profile(target, merged, template_root)
+    if errs:
+        return _fail(errs)
+
+    print("[DOC_PROFILE_VALIDATE_OK]")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())