feat(validate): worktree-state checks + hook unstaged guard

- validate: new 'Worktree state' section — config worktree must be
  clean (hard check; runtime state is gitignored there, so drift is
  always an anomaly); extension-repo WIP is reported, not blocking
  (it previously sat invisible until a workspace sync skipped the repo)
- workspace: _dirty_files() helper (porcelain minus lockfile
  tool-noise that sync auto-discards)
- pre-commit: fail fast when tracked devstack changes are unstaged
  (they would silently be missing from the commit being made)
- skill doc updated

Author: lpb-docs

.githooks/pre-commit

@@ -13,6 +13,19 @@
 #   SKIP_TESTS=1 git commit ...   — skip unit tests (~4s)
 #   git commit --no-verify ...    — skip everything
 
+# Devstack's own tree: tracked changes must be STAGED — unstaged edits
+# would silently be missing from the commit being made right now.
+# (Untracked files are fine: new work-in-progress.)
+echo "=== devstack staged ==="
+unstaged=$(git diff --name-only)
+if [ -n "$unstaged" ]; then
+    echo "❌ Unstaged changes in devstack (NOT included in this commit):"
+    echo "$unstaged" | sed 's/^/   /'
+    echo "   git add the files above (or commit them separately), or --no-verify"
+    exit 1
+fi
+echo ""
+
 echo "=== lpb-devstack validate (workspace copy) ==="
 if ! python3 scripts/lpb-devstack validate; then
     echo ""

.pi/skills/localpibox-repo-workflow/SKILL.md

@@ -277,12 +277,15 @@ Same pattern — template in config repo, user config on host volume:
 ## Hooks (devstack only, `core.hooksPath=.githooks`)
 
 **pre-commit** — validates BEFORE commit (exit non-zero aborts):
-1. `python3 scripts/lpb-devstack validate` — the full stack alignment
+1. devstack's tracked changes are fully staged (unstaged edits would
+   silently miss the commit)
+2. `python3 scripts/lpb-devstack validate` — the full stack alignment
    check (VERSION, `LPB_PI_VERSION`, extension pins, branch alignment,
-   pipeline consistency). Runs the WORKSPACE copy on purpose: the PATH
-   `lpb-devstack` is the image-baked one and stays stale until the next
-   rebuild, so the hook always validates with the current logic.
-2. `scripts/test_lpb.py` passes (skip with `SKIP_TESTS=1`)
+   pipeline consistency, config worktree clean + extension-repo WIP
+   report). Runs the WORKSPACE copy on purpose: the PATH `lpb-devstack`
+   is the image-baked one and stays stale until the next rebuild, so the
+   hook always validates with the current logic.
+3. `scripts/test_lpb.py` passes (skip with `SKIP_TESTS=1`)
 
 The full test suite in pre-commit is intentional — it guards against
 low-quality changes reaching the repo. `lpb-devstack validate-hooks` runs

scripts/localpibox/stack/validate.py

@@ -2,7 +2,8 @@
 
 Covers: VERSION file, config repo branch, workspace repo branches/symlinks,
 pipeline consistency (no mixed dev/main state), extension alignment,
-stack env refs, and settings.json pins.
+worktree state (config clean, extension-repo WIP report), stack env refs,
+and settings.json pins.
 """
 
 from __future__ import annotations
@@ -23,6 +24,7 @@
 from .version import _find_version_file, expected_branch, expected_pin_version, get_stack_env, get_stack_env_base, get_version
 from .workspace import (
     _detached_ref,
+    _dirty_files,
     _get_pinned_versions,
     _read_settings,
     _repo_branch,
@@ -146,6 +148,44 @@ def check(label: str, condition: bool, detail: str = "", fix: str = "") -> None:
         f"lpb-devstack --tag {pipeline} workspace sync",
     )
 
+    # ── 3b. Worktree state — leftover uncommitted changes ─────────────
+    cons.info("")
+    cons.info("  Worktree state:")
+
+    # config repo: everything runtime is gitignored there, so a dirty
+    # worktree means uncommitted template/skill/doc content — always an
+    # anomaly, and a hard check.
+    if (config_path / ".git").exists():
+        cfg_dirty = _dirty_files(config_path)
+        check(
+            "  config worktree clean",
+            not cfg_dirty,
+            "uncommitted changes:" if cfg_dirty else "clean",
+            "git -C ~/.pi/agent status — commit or discard first",
+        )
+        if cfg_dirty:
+            for line in cfg_dirty[:5]:
+                cons.warn(f"     {line.strip()}")
+
+    # Extension code repos: uncommitted WIP is normal during dev — report
+    # it (it previously sat invisible until a sync skipped the repo), but
+    # don't block on it. devstack's own tree is judged by the pre-commit
+    # hook (unstaged check), not here.
+    dirty_ext: list[str] = []
+    for name, is_sym, is_ext, dev_branch, main_branch in WORKSPACE_REPOS:
+        if name == "devstack":
+            continue
+        path = _resolve_repo_path(name)
+        if path is None:
+            continue
+        files = _dirty_files(path)
+        if files:
+            dirty_ext.append(f"{name} ({len(files)} file(s))")
+    if dirty_ext:
+        cons.warn(f"  WIP in extension repos (not blocking): {', '.join(dirty_ext)}")
+    else:
+        cons.info("  extension repos: no uncommitted changes")
+
     # ── 4. Extension repos match workspace ─────────────────────────────
     cons.info("")
     cons.info("  Extension alignment:")

scripts/localpibox/stack/workspace.py

@@ -106,6 +106,17 @@ def _is_dirty(path: Path) -> bool:
     return bool(out.strip())
 
 
+def _dirty_files(path: Path) -> list[str]:
+    """Uncommitted change lines (porcelain), minus lockfile tool-noise.
+
+    Lockfile rewrites are discarded automatically by workspace sync, so
+    they are not reported as drift.
+    """
+    st, _, _ = git(path, "status", "--porcelain")
+    return [line for line in st.splitlines()
+            if line.strip() and line[3:] not in LOCKFILE_NAMES]
+
+
 # Dependency lockfiles a package manager rewrites during `npm install`.
 # pi's extension manager runs npm install inside the extension clones, and a
 # newer npm than the one that generated the committed lockfile rewrites it