its-magic 0.1.2-32 → 0.1.2-34

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

@@ -1,5 +1,6 @@
 import argparse
 import filecmp
+import importlib.util
 import json
 import os
 import re
@@ -280,6 +281,47 @@ def materialize_scratchpad_baseline(target_root, source_root, mode, print_ok=Tru
     return True
 
 
+def _load_doc_profile_lib():
+    """
+    Load doc_profile_lib from scripts/ adjacent to this installer (repo checkout or npm package root).
+    Path is derived from __file__ only (no cwd / PYTHONPATH dependency).
+    """
+    here = os.path.dirname(os.path.abspath(__file__))
+    path = os.path.join(here, "scripts", "doc_profile_lib.py")
+    if not os.path.isfile(path):
+        raise RuntimeError(
+            "[DOC_PROFILE_LIB_MISSING] Expected documentation profile library at "
+            f"{path} (same directory as installer.py). "
+            "Global installs require this file in the published its-magic package; "
+            f"reinstall or upgrade its-magic ({REPO_URL})."
+        )
+    spec = importlib.util.spec_from_file_location("doc_profile_lib", path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(
+            "[DOC_PROFILE_LIB_LOAD_ERROR] Could not create import spec for "
+            f"{path}. Reinstall its-magic ({REPO_URL})."
+        )
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["doc_profile_lib"] = mod
+    try:
+        spec.loader.exec_module(mod)
+    except Exception as e:
+        sys.modules.pop("doc_profile_lib", None)
+        raise RuntimeError(
+            "[DOC_PROFILE_LIB_LOAD_ERROR] doc_profile_lib failed to load "
+            f"({e!r}). Reinstall its-magic ({REPO_URL})."
+        ) from e
+    return mod
+
+
+def _doc_profile_sync(target_root, merged, print_ok=True):
+    """Append missing normative README/developer doc sections from merged profile (non-destructive)."""
+    doc_profile_lib = _load_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 +330,18 @@ 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)
+        try:
+            dp_ok, dp_notes = _doc_profile_sync(target_root, merged, print_ok=print_ok)
+        except RuntimeError as e:
+            print(str(e))
+            ok = False
+        else:
+            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-34",
   "description": "its-magic - AI dev team workflow for Cursor.",
   "license": "MIT",
   "bin": {
@@ -11,6 +11,7 @@
     "installer.ps1",
     "installer.sh",
     "installer.py",
+    "scripts/doc_profile_lib.py",
     "bin/its-magic.js",
     "bin/postinstall.js"
   ],

package/scripts/doc_profile_lib.py

@@ -0,0 +1,415 @@
+"""
+Documentation profile resolution and surface helpers (DEC-0059).
+
+Shared by installer (optional surface sync) and scripts/validate_doc_profile.py.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, List, Optional, Set, Tuple
+
+DOC_AUDIENCE_ALLOWED = frozenset({"user", "developer", "both"})
+DOC_DETAIL_ALLOWED = frozenset({"concise", "balanced", "technical-deep"})
+
+USER_KEY_TO_H2: Dict[str, str] = {
+    "USER_PURPOSE": "Purpose",
+    "USER_QUICKSTART": "Quickstart",
+    "USER_EXAMPLES": "Examples",
+    "USER_TROUBLESHOOTING": "Troubleshooting",
+    "USER_LIMITATIONS": "Limitations",
+    "USER_RELATED_DOCS": "Related documentation",
+}
+
+DEV_KEY_TO_H2: Dict[str, str] = {
+    "DEV_PREREQS": "Prerequisites",
+    "DEV_WORKFLOW": "Workflow",
+    "DEV_QUALITY_GATES": "Quality gates",
+    "DEV_ARCHITECTURE": "Architecture notes",
+    "DEV_CONTRACTS": "Contracts and interfaces",
+    "DEV_DECISIONS": "Engineering decisions",
+}
+
+DEV_H2_TITLES = frozenset(DEV_KEY_TO_H2.values())
+USER_H2_TITLES = frozenset(USER_KEY_TO_H2.values())
+
+POINTER_H2 = "Contributing"
+
+# Root README H2 budget (user-channel headings + optional Contributing pointer only).
+ROOT_BUDGET: Dict[Tuple[str, str], int] = {}
+for aud in ("user", "developer", "both"):
+    for det in ("concise", "balanced", "technical-deep"):
+        if aud == "user":
+            ROOT_BUDGET[(aud, det)] = {"concise": 5, "balanced": 7, "technical-deep": 9}[det]
+        elif aud == "developer":
+            ROOT_BUDGET[(aud, det)] = {"concise": 4, "balanced": 6, "technical-deep": 8}[det]
+        else:
+            ROOT_BUDGET[(aud, det)] = {"concise": 6, "balanced": 8, "technical-deep": 6}[det]
+
+
+def resolve_doc_profile(merged: Dict[str, str]) -> Tuple[Optional[str], Optional[str], List[str]]:
+    """Return (audience, detail, errors). Empty profile keys default per DEC-0059 §6."""
+    raw_a = (merged.get("DOC_AUDIENCE_PROFILE") or "").strip().lower()
+    raw_d = (merged.get("DOC_DETAIL_LEVEL") or "").strip().lower()
+    errors: List[str] = []
+    if raw_a and raw_a not in DOC_AUDIENCE_ALLOWED:
+        errors.append(
+            "[DOC_PROFILE_INVALID] DOC_AUDIENCE_PROFILE must be one of: "
+            f"user, developer, both (got={raw_a!r})."
+        )
+    if raw_d and raw_d not in DOC_DETAIL_ALLOWED:
+        errors.append(
+            "[DOC_PROFILE_INVALID] DOC_DETAIL_LEVEL must be one of: "
+            f"concise, balanced, technical-deep (got={raw_d!r})."
+        )
+    if errors:
+        return None, None, errors
+    audience = raw_a or "both"
+    detail = raw_d or "balanced"
+    return audience, detail, []
+
+
+def required_user_keys(audience: str, detail: str) -> Set[str]:
+    if audience not in ("user", "both"):
+        return set()
+    if detail == "concise":
+        return {"USER_PURPOSE", "USER_QUICKSTART", "USER_LIMITATIONS"}
+    if detail == "balanced":
+        return {
+            "USER_PURPOSE",
+            "USER_QUICKSTART",
+            "USER_LIMITATIONS",
+            "USER_EXAMPLES",
+            "USER_RELATED_DOCS",
+        }
+    return {
+        "USER_PURPOSE",
+        "USER_QUICKSTART",
+        "USER_LIMITATIONS",
+        "USER_EXAMPLES",
+        "USER_RELATED_DOCS",
+        "USER_TROUBLESHOOTING",
+    }
+
+
+def required_dev_keys(audience: str, detail: str) -> Set[str]:
+    if audience not in ("developer", "both"):
+        return set()
+    if detail == "concise":
+        return {"DEV_PREREQS", "DEV_WORKFLOW"}
+    if detail == "balanced":
+        return {"DEV_PREREQS", "DEV_WORKFLOW", "DEV_QUALITY_GATES", "DEV_ARCHITECTURE"}
+    return {
+        "DEV_PREREQS",
+        "DEV_WORKFLOW",
+        "DEV_QUALITY_GATES",
+        "DEV_ARCHITECTURE",
+        "DEV_CONTRACTS",
+        "DEV_DECISIONS",
+    }
+
+
+def extract_h2_titles(markdown: str) -> List[str]:
+    titles: List[str] = []
+    for line in markdown.splitlines():
+        if line.startswith("## ") and not line.startswith("###"):
+            titles.append(line[3:].strip())
+    return titles
+
+
+def has_exact_h2(markdown: str, title: str) -> bool:
+    for line in markdown.splitlines():
+        if line.startswith("## ") and not line.startswith("###"):
+            if line[3:].strip() == title:
+                return True
+    return False
+
+
+def count_profile_root_h2s(
+    markdown: str,
+    audience: str,
+    detail: str,
+    required_user_keys_set: Set[str],
+) -> int:
+    """
+    Count H2 lines in budget scope: required USER_* titles only for user/both;
+    Contributing pointer alone for developer-only (DEC-0059 / R-0054 user H2 budgets).
+    """
+    titles = extract_h2_titles(markdown)
+    want: Set[str] = set()
+    for key in required_user_keys_set:
+        want.add(USER_KEY_TO_H2[key])
+    if audience == "developer":
+        return sum(1 for t in titles if t == POINTER_H2)
+    n = 0
+    for t in titles:
+        if t in want:
+            n += 1
+    return n
+
+
+def dev_h2_forbidden_in_root(markdown: str) -> List[str]:
+    """Return DEV_* H2 titles present in root (split layout forbids these in README)."""
+    found: List[str] = []
+    for t in extract_h2_titles(markdown):
+        if t in DEV_H2_TITLES:
+            found.append(t)
+    return found
+
+
+def validate_optional_modes(merged: Dict[str, str], readme_text: str) -> List[str]:
+    """
+    US-0031 / US-0032 compatibility: never require optional artifacts when modes are off.
+    When on, ensure profile surfaces mention cross-links (additive, lightweight).
+    """
+    out: List[str] = []
+    sp = (merged.get("SPEC_PACK_MODE") or "0").strip()
+    ug = (merged.get("USER_GUIDE_MODE") or "0").strip()
+    if sp != "1" and ug != "1":
+        return out
+    if sp == "1":
+        if "docs/engineering" not in readme_text and "spec" not in readme_text.lower():
+            out.append(
+                "[DOC_OPTIONAL_CROSSLINK_WEAK] SPEC_PACK_MODE=1: root README should mention "
+                "engineering docs or spec-pack paths in a user channel section (see Related documentation)."
+            )
+    if ug == "1":
+        if "user-guides" not in readme_text and "user guide" not in readme_text.lower():
+            out.append(
+                "[DOC_OPTIONAL_CROSSLINK_WEAK] USER_GUIDE_MODE=1: root README should mention "
+                "docs/user-guides in a user channel section."
+            )
+    return out
+
+
+def ensure_section(path: str, h2_title: str, body: str) -> Tuple[bool, str]:
+    """
+    Append ## h2_title + body if missing. Non-destructive.
+    Returns (changed, message).
+    """
+    ensure_parent_dir(path)
+    if os.path.isfile(path):
+        text = _read_utf8(path)
+    else:
+        text = ""
+
+    if has_exact_h2(text, h2_title):
+        return False, f"[DOC_PROFILE_SYNC] skip existing: ## {h2_title} ({path})"
+
+    block = f"\n\n## {h2_title}\n\n{body.strip()}\n"
+    if not text:
+        base = os.path.basename(path)
+        if base.lower() == "readme.md":
+            text = f"# Documentation\n"
+        else:
+            text = f"# {base.replace('.md', '').replace('_', ' ')}\n"
+    new_text = text.rstrip() + block
+    _write_utf8(path, new_text)
+    return True, f"[DOC_PROFILE_SYNC] appended: ## {h2_title} ({path})"
+
+
+def ensure_doc_surfaces_merged(
+    merged: Dict[str, str],
+    target_root: str,
+    print_ok: bool = True,
+) -> List[str]:
+    audience, detail, errors = resolve_doc_profile(merged)
+    if errors:
+        return list(errors)
+    assert audience is not None and detail is not None
+    messages: List[str] = []
+    uk = required_user_keys(audience, detail)
+    dk = required_dev_keys(audience, detail)
+    readme = os.path.join(target_root, "README.md")
+    dev_readme = os.path.join(target_root, "docs", "developer", "README.md")
+
+    stubs_user = {
+        "USER_PURPOSE": (
+            "Describe what this repository is for in plain language. "
+            "Replace this placeholder with your product outcome."
+        ),
+        "USER_QUICKSTART": (
+            "Link to your fastest path to success. For its-magic, see [Setup](#setup) above."
+        ),
+        "USER_EXAMPLES": "Add short, copy-paste friendly examples for common tasks.",
+        "USER_TROUBLESHOOTING": (
+            "List frequent issues, what to check, and where logs or docs live."
+        ),
+        "USER_LIMITATIONS": "Call out known limits, unsupported environments, or sharp edges.",
+        "USER_RELATED_DOCS": (
+            "Link runbooks, architecture notes, and deeper guides. "
+            "Operator commands live in `docs/engineering/runbook.md`."
+        ),
+    }
+    stubs_dev = {
+        "DEV_PREREQS": "Toolchain, repo layout, and local prerequisites for contributors.",
+        "DEV_WORKFLOW": "Branching, phases, and day-to-day contributor workflow.",
+        "DEV_QUALITY_GATES": "Tests, lint, typecheck, and review expectations before merge.",
+        "DEV_ARCHITECTURE": "High-level modules, boundaries, and extension points.",
+        "DEV_CONTRACTS": "Public interfaces, file formats, and compatibility promises.",
+        "DEV_DECISIONS": "Pointers to `decisions/` and architecture sections that matter.",
+    }
+
+    for key in sorted(uk):
+        h2 = USER_KEY_TO_H2[key]
+        changed, msg = ensure_section(readme, h2, stubs_user[key])
+        if print_ok or changed:
+            messages.append(msg)
+
+    if dk:
+        for key in sorted(dk):
+            h2 = DEV_KEY_TO_H2[key]
+            changed, msg = ensure_section(dev_readme, h2, stubs_dev[key])
+            if print_ok or changed:
+                messages.append(msg)
+
+    if audience in ("developer", "both"):
+        contrib_body = (
+            "Contributor-focused workflow and guardrails live in "
+            "[`docs/developer/README.md`](docs/developer/README.md)."
+        )
+        changed, msg = ensure_section(readme, POINTER_H2, contrib_body)
+        if print_ok or changed:
+            messages.append(msg)
+
+    return messages
+
+
+def optional_mode_warnings(merged: Dict[str, str], readme_text: str) -> List[str]:
+    """Non-blocking hints when optional doc modes are enabled (US-0031 / US-0032)."""
+    return validate_optional_modes(merged, readme_text)
+
+
+def ensure_parent_dir(path: str) -> None:
+    parent = os.path.dirname(path)
+    if parent and not os.path.isdir(parent):
+        os.makedirs(parent, exist_ok=True)
+
+
+def _read_utf8(path: str) -> str:
+    with open(path, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def _write_utf8(path: str, text: str) -> None:
+    ensure_parent_dir(path)
+    with open(path, "w", encoding="utf-8", newline="\n") as f:
+        f.write(text)
+
+
+def validate_repo_doc_profile(
+    target_root: str,
+    merged: Dict[str, str],
+    template_root: Optional[str],
+) -> List[str]:
+    """
+    Full validation for active target_root; optional template_root for parity.
+    Returns error strings (empty => pass).
+    """
+    errors: List[str] = []
+    audience, detail, err = resolve_doc_profile(merged)
+    errors.extend(err)
+    if errors:
+        return errors
+    assert audience is not None and detail is not None
+
+    uk = required_user_keys(audience, detail)
+    dk = required_dev_keys(audience, detail)
+
+    readme_path = os.path.join(target_root, "README.md")
+    dev_path = os.path.join(target_root, "docs", "developer", "README.md")
+
+    if not os.path.isfile(readme_path):
+        errors.append("[DOC_PROFILE_MERGE_ERROR] README.md missing (required for user channel checks).")
+        return errors
+
+    readme_text = _read_utf8(readme_path)
+
+    if audience in ("developer", "both") and dk:
+        if not os.path.isfile(dev_path):
+            errors.append(
+                "[DOC_SECTION_MISSING:shard] docs/developer/README.md missing but profile requires developer sections."
+            )
+
+    if audience in ("developer", "both"):
+        if not has_exact_h2(readme_text, POINTER_H2):
+            errors.append(
+                f"[DOC_SECTION_MISSING:DEV_SHARD_POINTER] Missing H2 ## {POINTER_H2} in README.md "
+                "(required pointer to docs/developer/README.md per DEC-0059)."
+            )
+        bad = dev_h2_forbidden_in_root(readme_text)
+        if bad:
+            errors.append(
+                "[DOC_PROFILE_INVALID] DEV sections must not use root README for split layout; "
+                f"found H2 titles {bad!r}. Move them to docs/developer/README.md."
+            )
+
+    for key in sorted(uk):
+        h2 = USER_KEY_TO_H2[key]
+        if not has_exact_h2(readme_text, h2):
+            errors.append(f"[DOC_SECTION_MISSING:{key}] Missing H2 ## {h2} in README.md.")
+
+    dev_text = ""
+    if os.path.isfile(dev_path):
+        dev_text = _read_utf8(dev_path)
+
+    for key in sorted(dk):
+        h2 = DEV_KEY_TO_H2[key]
+        if not has_exact_h2(dev_text, h2):
+            errors.append(f"[DOC_SECTION_MISSING:{key}] Missing H2 ## {h2} in docs/developer/README.md.")
+
+    budget = ROOT_BUDGET.get((audience, detail), 8)
+    counted = count_profile_root_h2s(readme_text, audience, detail, uk)
+    if counted > budget:
+        errors.append(
+            f"[DOC_SECTION_BUDGET_EXCEEDED] Root README profile-scoped H2 count={counted} "
+            f"exceeds budget={budget} for audience={audience!r} detail={detail!r}."
+        )
+
+    if template_root:
+        tr = os.path.join(template_root, "README.md")
+        td = os.path.join(template_root, "docs", "developer", "README.md")
+        if not os.path.isfile(tr):
+            errors.append("[DOC_TEMPLATE_PARITY_FAIL] template/README.md missing.")
+        else:
+            tt = _read_utf8(tr)
+            for key in sorted(uk):
+                h2 = USER_KEY_TO_H2[key]
+                if has_exact_h2(readme_text, h2) != has_exact_h2(tt, h2):
+                    errors.append(
+                        f"[DOC_TEMPLATE_PARITY_FAIL] USER H2 ## {h2} presence differs active vs template README."
+                    )
+            if audience in ("developer", "both"):
+                if has_exact_h2(readme_text, POINTER_H2) != has_exact_h2(tt, POINTER_H2):
+                    errors.append(
+                        "[DOC_TEMPLATE_PARITY_FAIL] ## Contributing pointer presence differs active vs template README."
+                    )
+        if dk:
+            if not os.path.isfile(td) or not os.path.isfile(dev_path):
+                errors.append(
+                    "[DOC_TEMPLATE_PARITY_FAIL] developer README missing in active or template."
+                )
+            else:
+                tdev = _read_utf8(td)
+                for key in sorted(dk):
+                    h2 = DEV_KEY_TO_H2[key]
+                    if has_exact_h2(dev_text, h2) != has_exact_h2(tdev, h2):
+                        errors.append(
+                            f"[DOC_TEMPLATE_PARITY_FAIL] DEV H2 ## {h2} presence differs active vs template."
+                        )
+
+    return errors
+
+
+def self_test_resolver() -> None:
+    """Tier B: assert matrix key sets."""
+    assert required_user_keys("user", "concise") == {
+        "USER_PURPOSE",
+        "USER_QUICKSTART",
+        "USER_LIMITATIONS",
+    }
+    assert required_dev_keys("developer", "technical-deep") == set(DEV_KEY_TO_H2.keys())
+    a, d, e = resolve_doc_profile({"DOC_AUDIENCE_PROFILE": "", "DOC_DETAIL_LEVEL": ""})
+    assert not e and a == "both" and d == "balanced"
+    _, _, e2 = resolve_doc_profile({"DOC_AUDIENCE_PROFILE": "nope"})
+    assert e2 and "DOC_PROFILE_INVALID" in e2[0]

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
+