pipeline discipline: main is promote-only, sync owns pin realignment

Development happens on the dev pipeline (dev branch or feature branches);
the stable branch (main) only moves via 'lpb-devstack release promote'.

- pre-commit guard (validate check 0): committing on main fails the
  hook unless the promote exemption is set. 'release promote' sets
  LPB_ALLOW_MAIN_COMMIT=1 around its devstack VERSION-strip commit (the
  one legitimate git commit on main — its merges don't trigger hooks).
  Outside a hook, validate on main stays green and only warns.
- workspace sync re-aligns settings.json pins to the synced pipeline:
  one command (sync --tag dev / --tag main) leaves repos, symlinks AND
  pins consistent; realign_pins() shared with release promote (pins
  follow the stable version right after promote — no leftover -lpb-dev).
- pin rewrites dedupe: a managed repo always ends up with exactly ONE
  entry (pi maps every git:<owner>/<repo> entry to one storage dir;
  duplicates raced during 'pi update --extensions').
- render --force guard: a stale pin of a repo the template owns is not
  a user addition — dropped/re-pinned, never appended as an 'extra'
  (this is what originally produced the duplicate 0.0.83-lpb-dev pins).

Tests: 6 new commit-guard tests + render/sync/dedupe cases; 16/16
localpibox suites and test_lpb (93) green.

Author: localpibox

.githooks/pre-commit

@@ -12,6 +12,11 @@
 # Escape hatches:
 #   SKIP_TESTS=1 git commit ...   — skip unit tests (~4s)
 #   git commit --no-verify ...    — skip everything
+#   LPB_ALLOW_MAIN_COMMIT=1 git commit ... — commit on the stable branch
+#       (main) without release promote. The validate commit guard (section 0)
+#       blocks development commits to main; use this only for deliberate
+#       stable-branch work. `release promote` sets it automatically for its
+#       devstack VERSION-strip commit.
 
 # In a linked worktree GIT_DIR is an ABSOLUTE path into the main repo's
 # .git/worktrees/<name> — it would leak into every `git -C` subprocess the

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

@@ -111,7 +111,31 @@ Extension clones (pi loads these per settings.json pins):
   clean merges from `lpb-dev` via the release procedure. Divergence from
   `lpb-dev` is normal during active development.
 
-**Rule:** always work on the default branch (`dev` or `lpb-dev`).
+**Rule:** always work on the dev pipeline (`dev` / `lpb-dev`, or a feature
+branch off dev). **`main` is promoted, not developed on** — the devstack
+pre-commit hook enforces this (the *commit guard*, validate section 0):
+committing on `main` fails validation unless `release promote` sets the
+exemption (`LPB_ALLOW_MAIN_COMMIT=1`, automatic for its devstack
+VERSION-strip commit) or the commit is deliberately made with
+`--no-verify` / `LPB_ALLOW_MAIN_COMMIT=1 git commit ...`. Outside a hook,
+`lpb-devstack validate` on main only warns — validating the stable tree
+stays possible.
+
+**Pipeline moves are one command each:**
+- Start development: `lpb-devstack workspace sync --tag dev` → devstack,
+  config + both extension repos onto their dev branches **and**
+  `settings.json` pins re-aligned to the dev version (leftover stable
+  pins dropped).
+- Return to stable: `lpb-devstack workspace sync --tag main` → same, to
+  stable branches + stable pins.
+- After `release promote`: pins are re-aligned to the stable version
+  automatically (no leftover `-lpb-dev` pins), then `pi update --extensions`.
+
+`render --force` also refuses to reintroduce stale managed pins: an existing
+`git:github.com/lpb-stack/<repo>@<old>` whose repo the template already owns
+is a stale pin, not a user addition — it is dropped (or re-pinned), never
+appended alongside the template's entry (duplicate entries map to one pi
+checkout dir and race during `pi update --extensions`).
 
 ## Commit Author Convention
 
@@ -170,9 +194,9 @@ on `main` is the trigger:
 1. Builds `:{v}-cli/web`, `:main-cli/web`, `:latest-cli/web`, `:{sha}-cli/web`
 2. Tags the 4 repos on their stable branches (`lpb`/`main`)
 
-Then align the runtime to the stable pipeline:
+Then align the runtime to the stable pipeline (promote already re-aligned
+the `settings.json` pins to the stable version — verify, don't redo):
 ```bash
-lpb-config --tag main sync-pins   # pins → stable version
 pi update --extensions
 lpb-devstack --tag main validate
 ```
@@ -247,6 +271,11 @@ lpb-devstack validate-hooks     # full pre-commit checks (tests included)
 lpb-devstack --tag main validate
 ```
 
+`workspace sync` is the single write path for a pipeline move: clones /
+symlinks / branches **and** re-aligns `settings.json` extension pins to
+that pipeline's stack version (stale cross-pipeline pins are re-pinned and
+extra duplicates dropped — one entry per managed repo).
+
 Both tools are thin CLIs over the shared `scripts/localpibox/stack/` library
 (`gitutil` / `repos` / `version` / `workspace` / `validate` / `release`).
 
@@ -288,16 +317,18 @@ Same pattern — template in config repo, user config on host volume:
 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, 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.
+   check. **Check 0 (commit guard)**: committing on `main` fails unless
+   the promote exemption is set (see Branch Strategy) — development
+   belongs on `dev` or feature branches. 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. Remaining checks: VERSION, `LPB_PI_VERSION`,
+   extension pins, branch alignment, pipeline consistency, config
+   worktree clean + extension-repo WIP report.
 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
-the same checks on demand.
+Escape hatches: `SKIP_TESTS=1` (tests only), `LPB_ALLOW_MAIN_COMMIT=1`
+(commit on main without promote), `--no-verify` (everything).
 
 **commit-msg** — **no-op.** Version bumping is manual (`lpb-devstack bump`).
 Git hooks never write VERSION or cross-repo state.

scripts/localpibox/stack/release.py

@@ -18,7 +18,9 @@
 from ..run import run_cmd
 from .gitutil import git, git_auth
 from .repos import TAG_REPOS, repo_path, stack_repos
+from .repos import DEFAULT_AGENT_DIR
 from .version import get_version
+from .workspace import realign_pins
 
 
 # ─── Dev release gate ────────────────────────────────────────────────────────
@@ -554,6 +556,10 @@ def cmd_release_promote(*, assume_yes: bool, dry_run: bool, rebase: bool,
             cons.info(f"  {label}: merged origin/{dev_b} → {main_b} ({action})")
 
     # ── devstack VERSION: strip -dev on main ──
+    # devstack commits on main under the hook's promote exemption: the
+    # commit guard (validate section 0) refuses commits on the stable
+    # branch — this strip commit is THE legitimate one.
+    os.environ["LPB_ALLOW_MAIN_COMMIT"] = "1"
     for label, path, dev_b, main_b, gh, st in entries:
         if label != "devstack" or label in failures or label in skipped:
             continue
@@ -584,6 +590,7 @@ def cmd_release_promote(*, assume_yes: bool, dry_run: bool, rebase: bool,
                 failures.append("devstack")
             else:
                 cons.info(f"  devstack: VERSION {current} → {stable} (on {main_b})")
+    del os.environ["LPB_ALLOW_MAIN_COMMIT"]
 
     # ── Push ──
     cons.info("")
@@ -645,6 +652,11 @@ def cmd_release_promote(*, assume_yes: bool, dry_run: bool, rebase: bool,
         return 1
     stable_version = (version[:-len("-dev")] if version.endswith("-dev") else version)
     cons.done(f"Promoted all 6 repos. main's VERSION is now {stable_version}.")
+    # Realign the runtime pins to the stable version: without this, the
+    # dev pins outlive the release in settings.json (and the next
+    # render --force would re-append them as 'extras').
+    if realign_pins(DEFAULT_AGENT_DIR, "main", cons):
+        cons.info("  Run 'pi update --extensions' to apply the stable pins.")
     cons.info(f"CI (main pipeline) now builds :{stable_version}-* / :main-* / :latest-*")
     cons.info("and tags the 5 repos at the stable branches.")
     cons.info("After CI passes:")

scripts/localpibox/stack/validate.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import os
 import re
 from pathlib import Path
 
@@ -35,6 +36,36 @@
 )
 
 
+def _branch_is_main() -> str:
+    """Current branch name of the devstack checkout being validated ('' if none)."""
+    out, _, code = git(".", "branch", "--show-current")
+    return out.strip() if code == 0 else ""
+
+
+def _allow_main_commit() -> bool:
+    """True when the caller opted into committing on the stable branch.
+
+    `release promote` sets LPB_ALLOW_MAIN_COMMIT=1 for its devstack
+    VERSION-strip commit (the only legitimate `git commit` on main —
+    promote's merges don't trigger hooks, the strip commit does).
+    """
+    return bool(os.environ.get("LPB_ALLOW_MAIN_COMMIT"))
+
+
+def _commit_guard_failed() -> bool:
+    """True when committing on the stable branch without the promote exemption.
+
+    Development belongs on the dev pipeline (dev branch or feature
+    branches); `main` only moves via `lpb-devstack release promote`.
+    """
+    return _branch_is_main() == "main" and not _allow_main_commit()
+
+
+def _inside_git_hook() -> bool:
+    """True when running under a git hook (git sets GIT_INDEX_FILE)."""
+    return bool(os.environ.get("GIT_INDEX_FILE"))
+
+
 def cmd_validate(pipeline: str, cons: Console) -> int:
     """Validate the entire stack alignment to the current pipeline."""
     version = get_version()
@@ -68,7 +99,32 @@ def check(label: str, condition: bool, detail: str = "", fix: str = "") -> None:
             if fix:
                 cons.info(f"     Fix: {fix}")
 
-    # ── 1. VERSION file ────────────────────────────────────────────────
+    # ── 0. Commit guard — main is promote-only ────────────────────────
+    # Commit-time check: under a git hook (GIT_INDEX_FILE set) a commit on
+    # the stable branch is a hard failure unless promote exempted it.
+    # Outside hooks (plain `lpb-devstack validate`) it's informational
+    # only — validating the stable environment on main must stay green.
+    # The guard is branch-based, NOT pipeline-based: the pipeline is
+    # detected from the VERSION file, which on main carries the stable
+    # suffix even right after a promote.
+    if _commit_guard_failed():
+        detail = ("on stable branch without the promote exemption "
+                  "(LPB_ALLOW_MAIN_COMMIT, set by 'release promote')")
+        if _inside_git_hook():
+            check(
+                "Commit target is not the stable branch (main is promote-only)",
+                False,
+                detail,
+                "Switch to the dev pipeline first (lpb-devstack workspace sync "
+                "--tag dev), or commit a feature branch off dev. Escape "
+                "hatches (deliberate stable commits only): "
+                "LPB_ALLOW_MAIN_COMMIT=1 git commit ...  or  --no-verify",
+            )
+            return 1
+        cons.warn("  (on the stable branch: commits to main need the promote "
+                  "exemption — LPB_ALLOW_MAIN_COMMIT=1 or --no-verify)")
+
+    # ── 1. VERSION file ─────────────────────────────────────────────────
     vf = _find_version_file()
     if vf is not None:
         version_on_disk = vf.read_text().strip()

scripts/localpibox/stack/workspace.py

@@ -421,6 +421,15 @@ def cmd_workspace_sync(pipeline: str, cons: Console) -> int:
     if not _sync_config(pipeline, cons):
         prepared = False
 
+    # Realign settings.json pins to the pipeline we just synced to: the
+    # single write path leaves repos, symlinks, AND pins consistent
+    # (fixes stale cross-pipeline pins that otherwise survive until the
+    # next manual sync-pins / render --force).
+    changed = realign_pins(DEFAULT_AGENT_DIR, pipeline, cons)
+    if changed:
+        cons.info(f"  {changed} extension pin(s) realigned to the "
+                  f"{pipeline} pipeline")
+
     cons.info("")
     if prepared:
         cons.done("Workspace prepared.")
@@ -466,23 +475,52 @@ def _get_pinned_versions(settings: dict) -> dict[str, str]:
     return pins
 
 
+def _dedupe_managed_pins(packages: list) -> list[str]:
+    """Collapse duplicate managed-pin entries: one entry per LPB extension repo.
+
+    A polluted settings.json can carry several `git:.../<name>@<old>` lines
+    per repo (e.g. a stale `-lpb-dev` pin surviving a pipeline move next to
+    the fresh one). pi maps every `git:<owner>/<repo>` entry to ONE storage
+    dir, so duplicates make `pi update --extensions` race on the same
+    checkout — deduping is mandatory, not cosmetic. Non-managed packages
+    (npm/bare) pass through untouched, in order.
+    """
+    seen: set[str] = set()
+    out: list[str] = []
+    for pkg in packages:
+        if not isinstance(pkg, str):
+            out.append(pkg)
+            continue
+        name = git_extension_pin(pkg)
+        if name is None:
+            out.append(pkg)
+        elif name not in seen:
+            seen.add(name)
+            out.append(pkg)
+    return out
+
+
 def _update_pinned_versions(settings: dict, target_version: str) -> list[tuple[str, str, str]]:
     """Update git-managed LPB extension pins to target_version. Returns changes.
 
+    Also DEDUPES: if a repo appears multiple times (stale pins from an
+    earlier pipeline move), only the FIRST entry is re-pinned — the rest
+    are dropped — so the result has exactly one entry per managed repo.
     npm/bare packages are left untouched — not managed by the stack VERSION.
     """
     packages = settings.get("packages", [])
     changes: list[tuple[str, str, str]] = []
+    deduped = _dedupe_managed_pins(packages)
     for name in LPB_EXTENSION_REPOS:
         marker = f"git:github.com/lpb-stack/{name}@"
-        for i, pkg in enumerate(packages):
+        for i, pkg in enumerate(deduped):
             if isinstance(pkg, str) and pkg.startswith(marker):
                 old_tag = pkg.split("@")[-1]
                 if old_tag != target_version:
-                    new_pkg = f"{marker}{target_version}"
-                    packages[i] = new_pkg
+                    deduped[i] = f"{marker}{target_version}"
                     changes.append((name, old_tag, target_version))
-    settings["packages"] = packages
+                break
+    settings["packages"] = deduped
     return changes
 
 
@@ -491,22 +529,55 @@ def _update_pinned_versions(settings: dict, target_version: str) -> list[tuple[s
 def sync_pins_quiet(agent_dir: str | Path, target_version: str,
                     cons: Console) -> int:
     """Non-interactive pin update: write pins != *target_version* in
-    settings.json. Returns the number of changed extension(s); 0 if nothing
-    to do or no settings.json (a missing file is not an error here —
-    callers treat it as 'nothing to sync'). Used by `lpb-devstack bump`
-    so a VERSION commit never lands with stale pins (the pre-commit
-    validate would fail, and a post-hook sync would target the OLD
-    version)."""
+    settings.json (also dedupes duplicate managed-pin entries). Returns the
+    number of changed extension(s); 0 if nothing to do or no settings.json
+    (a missing file is not an error here — callers treat it as 'nothing to
+    sync'). Used by `lpb-devstack bump` so a VERSION commit never lands
+    with stale pins (the pre-commit validate would fail, and a post-hook
+    sync would target the OLD version)."""
     settings = _read_settings(agent_dir)
     if settings is None:
         return 0
+    before = settings.get("packages", [])
     changed = _update_pinned_versions(settings, target_version)
-    if not changed:
+    if settings.get("packages") == before:
         return 0
     _write_settings(agent_dir, settings)
     for name, old, new in changed:
         cons.info(f"  pin {name}: {old} → {new}")
-    return len(changed)
+    return max(len(changed), 1)
+
+
+def realign_pins(agent_dir: str | Path, pipeline: str, cons: Console) -> int:
+    """Realign settings.json extension pins to *pipeline*'s stack version.
+
+    Shared write path for the two moments when the pipeline moves out from
+    under the runtime config:
+      - `workspace sync`  — every sync now leaves pins matching the branch
+        it just aligned the repos to (start dev / return to stable);
+      - `release promote` — after dev is merged to the stable branches, the
+        runtime must track the stable version, not leftover dev pins.
+
+    Re-pins stale pins AND drops duplicate managed-pin entries (a polluted
+    file can survive re-pinning with the first entry already at target).
+    Returns the number of pin operations performed (0 = already aligned or
+    no settings.json — a missing file is not an error here, mirroring
+    sync_pins_quiet).
+    """
+    target_version = expected_pin_version(pipeline)
+    settings = _read_settings(agent_dir)
+    if settings is None:
+        return 0
+    before = settings.get("packages", [])
+    changed = _update_pinned_versions(settings, target_version)
+    if settings.get("packages") == before:
+        return 0
+    _write_settings(agent_dir, settings)
+    for name, old, new in changed:
+        cons.info(f"  pin {name}: {old} → {new}")
+    if not changed:
+        cons.info("  dropped duplicate managed-pin entrie(s)")
+    return max(len(changed), 1)
 
 
 def cmd_workspace_sync_pins(pipeline: str, cons: Console) -> int:

scripts/lpb-config

@@ -97,11 +97,13 @@ from localpibox.stack.repos import (  # noqa: E402
     DEFAULT_AGENT_DIR,
     DEFAULT_REMOTE,
     DEFAULT_REF,
+    GIT_EXTENSION_PREFIX,
     LPB_EXTENSION_REPOS,
     migrate_legacy_layout,
 )
 from localpibox.stack.version import detect_pipeline, get_version  # noqa: E402
 from localpibox.stack.workspace import (  # noqa: E402
+    _dedupe_managed_pins,
     _write_settings,
     cmd_workspace_sync_pins,
 )
@@ -244,8 +246,24 @@ def _render_file(
         and isinstance(existing.get("packages"), list)
     ):
         tpl_pkgs = new["packages"]
-        extras = [p for p in existing["packages"] if p not in tpl_pkgs]
-        new = {**new, "packages": tpl_pkgs + extras}
+        # A stale pin of a repo the TEMPLATE already owns (e.g. a leftover
+        # `-lpb-dev` pin after a promote to `-lpb`) is not a user addition:
+        # the template re-pins that repo. Keeping it would leave two
+        # entries for the same repo, which pi maps to one checkout dir
+        # (duplicate updates race there). Drop stale template-owned pins;
+        # keep genuine extras (npm/bare/other repos) — deduped for safety.
+        tpl_owned = {
+            p[len(GIT_EXTENSION_PREFIX):].split("@", 1)[0]
+            for p in tpl_pkgs
+            if isinstance(p, str) and p.startswith(GIT_EXTENSION_PREFIX)
+        }
+        extras = [
+            p for p in existing["packages"]
+            if p not in tpl_pkgs
+            and (not isinstance(p, str) or not p.startswith(GIT_EXTENSION_PREFIX)
+                 or p[len(GIT_EXTENSION_PREFIX):].split("@", 1)[0] not in tpl_owned)
+        ]
+        new = {**new, "packages": _dedupe_managed_pins(tpl_pkgs + extras)}
     merged = {**new, **existing} if local_wins else {**existing, **new}
     out.write_text(json.dumps(merged, indent=2) + "\n")
     cons.info(f"Re-rendered {out.name} from {template_name} (merged, user keys preserved)")