its-magic 0.1.2-32 → 0.1.2-33

package/README.md

@@ -280,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
 
@@ -1014,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)
 
@@ -1062,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
 
@@ -1354,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/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/'
   )

package/installer.py

@@ -280,6 +280,18 @@ def materialize_scratchpad_baseline(target_root, source_root, mode, print_ok=Tru
     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_example(target_root, source_root, print_ok=print_ok):
         return False
@@ -288,6 +300,13 @@ def run_scratchpad_postinstall(target_root, source_root, mode, print_ok=True):
     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):

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" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "its-magic",
-  "version": "0.1.2-32",
+  "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

@@ -196,3 +196,9 @@ SPEC_PACK_MODE=0
 # - 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.
 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

@@ -197,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

@@ -280,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
 
@@ -1014,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)
 
@@ -1062,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
 
@@ -1354,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/template/docs/developer/README.md

@@ -0,0 +1,44 @@
+# Developer documentation
+
+This shard holds contributor-facing material for the **its-magic** framework. End-user
+setup stays in the root `README.md` (user channel).
+
+## Prerequisites
+
+- **Cursor** (or compatible editor) with the workflow files installed.
+- **Python 3** on PATH for scratchpad merge validation and several repo scripts.
+- **Node.js** if you use npm-packaged `its-magic` or npm-driven `TEST_COMMAND` defaults.
+
+## Workflow
+
+- Follow phased commands under `.cursor/commands/` (`intake`, `discovery`, `architecture`,
+  `sprint-plan`, `execute`, `qa`, `release`, etc.).
+- Keep handoffs and `docs/engineering/state.md` updated at phase boundaries.
+- Use `.cursor/scratchpad.local.md` for personal overrides; never commit secrets.
+
+## Quality gates
+
+- Run `TEST_COMMAND` from `docs/engineering/runbook.md` before push; CI should mirror the same.
+- Run `python scripts/validate_doc_profile.py` when changing documentation profile flags or
+  README surfaces.
+- Observe `US-0071` hygiene for user-visible script output (see runbook).
+
+## Architecture notes
+
+- High-level contracts live in `docs/engineering/architecture.md` (search for story ids).
+- Installer ownership is driven by `docs/engineering/context/installer-owned-paths.manifest`.
+- Template parity: changes in repo root often require the same edit under `template/`.
+
+## Contracts and interfaces
+
+- Scratchpad merge precedence: local → materialized `.cursor/scratchpad.md` →
+  `.cursor/scratchpad.local.example.md` (Model B / **DEC-0055**).
+- Documentation profile keys: `DOC_AUDIENCE_PROFILE`, `DOC_DETAIL_LEVEL` (**DEC-0059**).
+- Optional modes: `SPEC_PACK_MODE`, `USER_GUIDE_MODE` remain orthogonal; when `0`, validators
+  must not require those artifacts.
+
+## Engineering decisions
+
+- Decision records: `decisions/DEC-xxxx.md` and the compact index in
+  `docs/engineering/decisions.md`.
+- Profile semantics for this shard: **DEC-0059** and `# US-0077` in `architecture.md`.

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

@@ -20,6 +20,9 @@ handoffs
 decisions
 scripts/validate-and-push.ps1
 scripts/validate-and-push.sh
+scripts/sync_push_gates.py
+scripts/doc_profile_lib.py
+scripts/validate_doc_profile.py
 .github/workflows
 README.md
 its_magic
@@ -28,12 +31,16 @@ its_magic
 .cursor
 docs/product
 docs/engineering
+docs/developer
 docs/user-guides
 sprints
 handoffs
 decisions
 scripts/validate-and-push.ps1
 scripts/validate-and-push.sh
+scripts/sync_push_gates.py
+scripts/doc_profile_lib.py
+scripts/validate_doc_profile.py
 .github/workflows/ci.yml
 .github/workflows/deploy.yml
 its_magic

package/template/docs/engineering/runbook.md

@@ -60,6 +60,36 @@ Remediation:
 - define `TEST_COMMAND` explicitly in `docs/engineering/runbook.md`, or
 - add detectable stack markers/scripts then rerun installer upgrade.
 
+## Documentation profile validation (US-0077 / DEC-0059)
+
+**Goal:** keep root `README.md` (user channel) and `docs/developer/README.md`
+(developer shard) aligned with merged scratchpad keys `DOC_AUDIENCE_PROFILE` and
+`DOC_DETAIL_LEVEL`, with deterministic reason codes and active/`template/` parity.
+
+### Scratchpad keys
+
+- `DOC_AUDIENCE_PROFILE`: `user` \| `developer` \| `both` (empty defaults to `both` during transition).
+- `DOC_DETAIL_LEVEL`: `concise` \| `balanced` \| `technical-deep` (empty defaults to `balanced`).
+- Invalid values → `DOC_PROFILE_INVALID`. Merge/read failures → `DOC_PROFILE_MERGE_ERROR`.
+- Optional modes `SPEC_PACK_MODE` / `USER_GUIDE_MODE` stay additive only: when `0`, this
+  validator does not require spec-pack or user-guide files.
+
+### Command
+
+```bash
+python scripts/validate_doc_profile.py --repo .
+python scripts/validate_doc_profile.py --repo . --no-template-parity   # fixture trees without template/
+```
+
+### Installer hook
+
+`installer.py` scratchpad post-install refreshes missing normative `##` sections
+(non-destructive append) from the resolved profile, then operators should keep
+content accurate. Re-run `python installer.py --scratchpad-postinstall --target <repo> --mode missing`
+after template upgrades if needed.
+
+Normative H2 titles and matrix: `docs/engineering/architecture.md` (`# US-0077`).
+
 ## User-visible internal metadata guard (US-0071 / DEC-0053)
 
 **Goal:** keep planning-shaped identifiers out of **operator-visible software
@@ -1095,6 +1125,39 @@ Deterministic reason-code baseline:
 - `OPTIONAL_CHECK_FAILED`
 - `SYNC_PUSHED`
 
+## Executable validate-and-push wiring (DEC-0058)
+
+Scratchpad **`SYNC_*` / `ALLOW_AUTO_PUSH` / `AUTO_PUSH_BRANCH_ALLOWLIST`** are read from the
+**merged** scratchpad only (installer merge: local → materialized baseline → example; same
+precedence as installer post-install validation). **`scripts/validate-and-push.ps1`** and
+**`scripts/validate-and-push.sh`** call **`python scripts/sync_push_gates.py`** for policy;
+**`docs/engineering/runbook.md`** remains the sole source for **`TEST_COMMAND`** and optional
+lint/typecheck commands.
+
+**Operator rule:** changing scratchpad alone does **not** run **`git push`**. Run
+**`validate-and-push`** (or CI) after an eligible boundary. For **`by_phase`**, **`by_milestone`**,
+and **`custom_phase_list`**, scheduling is **operator or CI** responsibility.
+
+**`SYNC_PHASE_BOUNDARY`:** optional environment variable (canonical phase id, case-insensitive).
+When **`SYNC_POLICY_MODE=custom_phase_list`**, the variable must be set and must appear in
+**`SYNC_CUSTOM_PHASES`** (comma-separated) or the script exits **`SYNC_TRIGGER_NOT_ELIGIBLE`**.
+
+**Dry-run:** **`powershell .../validate-and-push.ps1 -DryRun`** or
+**`bash scripts/validate-and-push.sh --dry-run ...`** — runs merge/policy and the runbook check
+chain, then prints **`SYNC_PUSHED`** without **`git push`**.
+
+**Branch allowlist matching (`AUTO_PUSH_BRANCH_ALLOWLIST`):** comma-separated entries; each entry
+is either an exact branch name or a **`fnmatch`** pattern (for example `release/*`). An empty
+allowlist denies every branch (**`BRANCH_NOT_ALLOWLISTED`**).
+
+**QA scan (bounded):** files under **`sprints/S####/qa-findings.md`** (four digits). Blocking
+rules match **`DEC-0058`** §6. **`PRE_QA_AUTOPUSH_FORBIDDEN`** applies on branches other than
+**`main`** / **`master`** when **no** such **`qa-findings.md`** file exists yet (feature-line
+signal; see architecture **US-0076**).
+
+**Python:** merged policy evaluation requires **Python 3** on **`PATH`** (**`PYTHON_NOT_ON_PATH`**
+if missing).
+
 Required sync evidence fields:
 - `phase_boundary`
 - `policy_mode`