its-magic 0.1.2-9 → 0.1.2

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

@@ -0,0 +1,280 @@
+# -------------------------------------------------------------------
+# validate-and-push.ps1 — local test-fix-push loop
+#
+# Part of the its-magic quality chain:
+#   Cursor AI loop  →  validate-and-push  →  CI auto-fix (GitHub)
+#
+# 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]$DryRun
+)
+
+$ErrorActionPreference = "Stop"
+$root = Resolve-Path (Join-Path $PSScriptRoot "..")
+
+function Log-Info  { param($Msg) Write-Host "[info]  $Msg" -ForegroundColor Cyan }
+function Log-Pass  { param($Msg) Write-Host "[pass]  $Msg" -ForegroundColor Green }
+function Log-Fail  { param($Msg) Write-Host "[fail]  $Msg" -ForegroundColor Red }
+function Log-Warn  { param($Msg) Write-Host "[warn]  $Msg" -ForegroundColor Yellow }
+
+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)
+  $runbook = Join-Path $root "docs\engineering\runbook.md"
+  if (-not (Test-Path $runbook -PathType Leaf)) { return "" }
+  $content = Get-Content -Path $runbook -Raw
+  $m = [regex]::Match($content, "(?m)^${Key}:[ \t]*(.+)$")
+  if (-not $m.Success) { return "" }
+  $val = $m.Groups[1].Value.Trim()
+  if ($val -in @("", "...", "<...>", "TODO")) { return "" }
+  return $val
+}
+
+$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
+}
+
+$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
+}
+
+if (-not $Branch) {
+  $Branch = (git -C $root rev-parse --abbrev-ref HEAD 2>$null)
+  if (-not $Branch) { $Branch = "main" }
+}
+
+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, [int]$TimeoutSec = 0)
+  $prev = $ErrorActionPreference
+  $ErrorActionPreference = "Continue"
+  try {
+    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
+  }
+}
+
+$passed = $false
+for ($attempt = 1; $attempt -le $MaxAttempts; $attempt++) {
+  Log-Info "--- Attempt $attempt / $MaxAttempts ---"
+
+  Push-Location $root
+  $allOk = $true
+
+  if ($FormatCmd) {
+    Log-Info "Running formatter..."
+    $r = Run-Cmd -Cmd $FormatCmd -TimeoutSec 0
+    if ($r.Ok) { Log-Pass "Format OK" } else { Log-Warn "Formatter reported issues (non-blocking)" }
+  }
+
+  if ($LintFixCmd) {
+    Log-Info "Running lint auto-fix..."
+    Run-Cmd -Cmd $LintFixCmd -TimeoutSec 0 | Out-Null
+  }
+
+  if ($LintCmd) {
+    Log-Info "Running lint check..."
+    $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
+    }
+  }
+
+  if ($TypecheckCmd) {
+    Log-Info "Running typecheck..."
+    $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
+    }
+  }
+
+  if ($TestCmd) {
+    Log-Info "Running tests..."
+    $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
+    }
+  }
+
+  Pop-Location
+
+  if ($allOk) {
+    Log-Pass "All checks passed on attempt $attempt."
+    $passed = $true
+    break
+  }
+
+  if ($attempt -ge $MaxAttempts) {
+    Log-Fail "Reached max attempts ($MaxAttempts). Aborting push."
+    Write-Host ""
+    Log-Warn "Fix the issues above, then re-run:"
+    Log-Warn "  powershell scripts\validate-and-push.ps1"
+    exit 1
+  }
+
+  Write-Host ""
+  Log-Warn "Fix the failing checks, then press Enter to retry (or Ctrl+C to abort)..."
+  Read-Host | Out-Null
+}
+
+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 ($DryRun -or $NoCommit) {
+  if ($DryRun) {
+    Log-Pass "reason_code=SYNC_PUSHED (dry-run; no git push)"
+  } else {
+    Log-Info "Auto-commit disabled (--NoCommit). Push manually when ready."
+    Log-Pass "reason_code=SYNC_PUSHED (checks only; push skipped by flag)"
+  }
+  exit 0
+}
+
+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 "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

@@ -0,0 +1,243 @@
+#!/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)
+#
+# 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 -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}"
+
+pass_color="\033[1;32m"
+fail_color="\033[1;31m"
+info_color="\033[1;36m"
+warn_color="\033[1;33m"
+reset="\033[0m"
+
+log_info()  { printf "${info_color}[info]${reset}  %s\n" "$*"; }
+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" "$*"; }
+
+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() {
+  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 ;;
+  esac
+  printf "%s" "$value"
+}
+
+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
+}
+
+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
+
+if [ -z "$BRANCH" ]; then
+  BRANCH=$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+fi
+
+log_info "validate-and-push loop"
+log_info "Branch: $BRANCH  |  Max attempts: $MAX_ATTEMPTS"
+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"
+log_info "TEST_TIMEOUT_SECONDS: $TEST_TIMEOUT_SEC"
+printf "\n"
+
+attempt=0
+while [ "$attempt" -lt "$MAX_ATTEMPTS" ]; do
+  attempt=$((attempt + 1))
+  log_info "--- Attempt $attempt / $MAX_ATTEMPTS ---"
+
+  cd "$ROOT"
+  all_ok=true
+
+  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
+  fi
+
+  if [ -n "$LINT_FIX_CMD" ]; then
+    log_info "Running lint auto-fix..."
+    eval "$LINT_FIX_CMD" || true
+  fi
+
+  if [ -n "$LINT_CMD" ]; then
+    log_info "Running lint check..."
+    if run_runbook_cmd "$LINT_CMD" "optional" "$TEST_TIMEOUT_SEC"; then log_pass "Lint OK"; else all_ok=false; fi
+  fi
+
+  if [ -n "$TYPECHECK_CMD" ]; then
+    log_info "Running typecheck..."
+    if run_runbook_cmd "$TYPECHECK_CMD" "optional" "$TEST_TIMEOUT_SEC"; then log_pass "Typecheck OK"; else all_ok=false; fi
+  fi
+
+  if [ -n "$TEST_CMD" ]; then
+    log_info "Running tests..."
+    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
+    log_pass "All checks passed on attempt $attempt."
+    break
+  fi
+
+  if [ "$attempt" -ge "$MAX_ATTEMPTS" ]; then
+    log_fail "Reached max attempts ($MAX_ATTEMPTS). Aborting push."
+    printf "\n"
+    log_warn "Fix the issues above, then re-run:"
+    log_warn "  bash scripts/validate-and-push.sh"
+    exit 1
+  fi
+
+  printf "\n"
+  log_warn "Fix the failing checks, then press Enter to retry (or Ctrl+C to abort)..."
+  read -r _unused
+done
+
+if ! run_sync_gate post; then exit 1; fi
+
+printf "\n"
+
+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 "Auto-commit disabled. Push manually when ready."
+    log_pass "reason_code=SYNC_PUSHED (checks only; push skipped by flag)"
+  fi
+  exit 0
+fi
+
+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 "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())