xtrm-tools 0.7.17 → 0.7.19

package/.xtrm/skills/default/security-pipeline/templates/scripts/semgrep-diff.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Run semgrep against the diff between HEAD and origin/main.
+# Used by pre-push hook so pre-existing debt doesn't block unrelated pushes.
+# CI's full scan remains the source of truth for absolute findings.
+
+set -euo pipefail
+
+if ! command -v semgrep >/dev/null; then
+    echo "semgrep not installed — skipping (CI covers it)"
+    exit 0
+fi
+
+# Derive base ref dynamically. Order:
+#   1. branch's tracked upstream ('@{u}') — most reliable
+#   2. common default branches if their *remote* version exists (origin/*)
+#   3. local default branches IF different from current branch
+# We refuse to use the current branch as its own baseline because then
+# merge-base resolves to HEAD and --baseline-commit=HEAD silently scans
+# nothing on every push.
+HEAD_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+HEAD_SHA=$(git rev-parse HEAD)
+
+upstream=$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || true)
+BASE_REF=""
+if [ -n "$upstream" ]; then
+    BASE_REF="$upstream"
+else
+    for cand in origin/main origin/master main master; do
+        git rev-parse --verify "$cand" >/dev/null 2>&1 || continue
+        # Skip a local-branch candidate that IS the current branch
+        [ "$cand" = "$HEAD_BRANCH" ] && continue
+        BASE_REF="$cand"
+        break
+    done
+fi
+
+[ -n "$BASE_REF" ] && git fetch "${BASE_REF%%/*}" "${BASE_REF#*/}" --quiet 2>/dev/null || true
+
+SEMGREP_BASELINE_ARGS=()
+if [ -n "$BASE_REF" ]; then
+    BASE=$(git merge-base HEAD "$BASE_REF" 2>/dev/null || true)
+    # merge-base==HEAD here means branch is at upstream tip — legitimate empty
+    # diff. Pass --baseline-commit so semgrep produces an empty result rather
+    # than falling back to a full scan.
+    [ -n "$BASE" ] && SEMGREP_BASELINE_ARGS=(--baseline-commit="$BASE")
+fi
+# Last-resort: no upstream resolved at all. rev-list can equal HEAD on single
+# -commit histories; reject and full-scan in that case.
+if [ ${#SEMGREP_BASELINE_ARGS[@]} -eq 0 ]; then
+    BASE=$(git rev-list HEAD --max-count=50 | tail -1)
+    if [ -n "$BASE" ] && [ "$BASE" != "$HEAD_SHA" ]; then
+        SEMGREP_BASELINE_ARGS=(--baseline-commit="$BASE")
+    else
+        echo "[semgrep-diff] no usable baseline (no upstream, single-commit branch, or pushing default branch directly) — running full scan"
+    fi
+fi
+
+exec semgrep scan \
+    --config=p/default \
+    --config=p/security-audit \
+    --config=p/secrets \
+    --config=p/python \
+    --config=p/dockerfile \
+    --config=p/github-actions \
+    "${SEMGREP_BASELINE_ARGS[@]}" \
+    --error \
+    --quiet \
+    --skip-unknown-extensions

package/.xtrm/skills/default/session-close-report/SKILL.md

@@ -41,6 +41,52 @@ are factually superseded.
 
 ## Workflow
 
+### 0. Cleanup before reporting (MANDATORY)
+
+A report on a dirty session is misleading. Before selecting or generating any
+report, verify and clean up everything this session opened. The report must
+reflect a clean terminal state.
+
+```bash
+# 0a. Worktrees opened during the session
+git worktree list                  # any feature/fix/chore worktrees still here?
+# Remove every worktree this session created (or that a stopped specialist left):
+git worktree remove <path>         # for each stale entry
+git branch -D <branch>             # only after confirming merged or abandoned
+git worktree prune                 # drop stale metadata
+
+# 0b. Specialist jobs still running or waiting
+sp ps                              # MUST be empty (or only intentionally kept-alive jobs)
+sp stop <job-id>                   # for any leftover running/waiting job
+# After every sp stop, re-check sp ps and git worktree list — sp stop should
+# clean its worktree, but verify.
+
+# 0c. Stale background processes from the session
+ps -ef | grep -E '(serena|gitnexus|specialists|sp-serve|sp-script|pi[ -]|claude)' | grep -v grep
+# Kill anything you launched that is still running and no longer needed.
+# Be especially careful with:
+#   - serena MCP servers (often leak when an MCP host crashes)
+#   - gitnexus index processes (`npx gitnexus analyze` can outlive its terminal)
+#   - sp-serve / sp-script tmux sessions
+#   - orphaned `pi` or `claude` processes from interactive sessions
+
+tmux ls 2>/dev/null                # any sp-* or xt-* tmux sessions left?
+tmux kill-session -t <name>        # for each stale session
+
+# 0d. Tmp dirs the session created (only if large or sensitive)
+ls -la /tmp/sp-serve-* /tmp/sp-script-* 2>/dev/null
+```
+
+Do not skip any sub-step. If a process refuses to stop cleanly, document it in
+the **Problems Encountered** section of the report so the next agent knows.
+
+A clean session ends with:
+- `git worktree list` showing only the main worktree (plus any intentional ones)
+- `sp ps` showing 0 jobs (or only intentional keep-alive)
+- no leaked `serena` / `gitnexus` / `specialists` / `sp-serve` / `sp-script`
+  processes from this session
+- no orphaned tmux sessions matching `sp-*` or `xt-*`
+
 ### 1. Select report: update existing or generate new
 
 For same-day update:
@@ -115,8 +161,8 @@ delete this section. If prior dispatches exist, keep and extend them.
 #### Problems Encountered
 Every problem hit during the session. Root Cause and Resolution columns are
 mandatory. Include: bugs discovered, wrong approaches tried, blockers hit,
-tooling failures. If no problems exist anywhere in the same-day report, delete
-this section entirely.
+tooling failures, and any cleanup-step failures from Step 0 above. If no
+problems exist anywhere in the same-day report, delete this section entirely.
 
 #### Code Changes
 The skeleton lists files. Add narrative:
@@ -127,7 +173,8 @@ The skeleton lists files. Add narrative:
   to the final pushed stack
 
 #### Documentation Updates
-List doc changes, skill updates, memory saves, CHANGELOG entries.
+List doc changes, skill updates, memory saves, CHANGELOG entries
+(see Step 5 — due-diligence sweep — and Step 6 — CHANGELOG sync).
 Delete if no doc work happened.
 
 #### Open Issues with Context
@@ -162,12 +209,108 @@ Ensure all frontmatter counts are accurate after filling/updating:
 - `issues_closed` — actual closed issue count represented in the report
 - `commits` — commit count represented in the report, if known
 
-### 5. Commit the report
+### 5. Due-diligence sweep (paranoid mode — assume you forgot something)
+
+Step 0 cleaned the *process* state. This step audits the *content* state.
+Cleanup work the orchestrator usually forgets at session close, ranked by
+how often it gets missed:
+
+- **Service skills**: did this session touch any code under a service
+  registered in `.claude/skills/service-registry.json` (or equivalent
+  registry)? If yes, the service skill's SKILL.md or diagnostic scripts
+  are likely drifted. Run `/updating-service-skills` (or
+  `service-skills-sync` specialist) and let it scan. If no registry exists,
+  skip — but check whether the project keeps service skills under
+  `.xtrm/skills/user/packs/<service>/` and treat them the same.
+- **Docs SSOT**: did the session change architecture, migrations, public
+  APIs, or service ownership? If yes, run `/sync-docs` (or the
+  `sync-docs` specialist) for any drifted doc. Skip if changes are
+  pure-internal (refactors with no observable surface change).
+- **Memories**: every `bd close` should have triggered a memory-gate ack.
+  Run `bd memories <topic>` to confirm anything genuinely novel landed.
+  If you saw a real surprise but acked "nothing novel" out of haste,
+  go back and `bd remember` it now.
+- **CLAUDE.md / project guide**: did this session add or remove a
+  service, change a key port, change a top-level workflow command, or
+  change how tools are wired? If yes, append/correct in CLAUDE.md before
+  commit — the file is loaded automatically by every future session.
+- **Evidence artifacts**: did the session generate reports, dashboards,
+  CSVs, or figures intended to be persisted (`scripts/outputs/`,
+  `docs/review/`, etc.)? Confirm they are committed; otherwise either
+  commit them or document in the report why they were not kept.
+- **Decisions**: did the session make a non-obvious architectural call
+  (deprecating a service, schema choice, dependency swap)? Record via
+  `bd decision` if the project uses it, otherwise note in the report.
+- **Tests**: did new behavior land without tests? If yes, file a test
+  follow-up bead (`discovered-from:<impl-id>`) before closing — do not
+  let untested behavior leave the session silent.
+- **Skill packs (`.xtrm/skills/`)**: did you edit a skill in this
+  project? If the canonical version lives in xtrm-tools, mirror the edit
+  there too (or note that `xt update` will overwrite the local mirror on
+  next sync, which makes the local edit ephemeral).
+- **Open beads created mid-session**: every bead filed this session
+  should be either closed, scheduled with a parent, or marked with clear
+  context. Run `bd list --status=open --created-by=me` (or equivalent)
+  and confirm none are floating without a parent or follow-up note.
+
+If any item above turns up real work, do it now or file a follow-up bead
+linked `discovered-from:<this-session-root>` so the next agent picks it up.
+A clean session means none of these were forgotten — the report should be
+able to honestly claim "due-diligence sweep clean."
+
+### 6. Sync CHANGELOG.md (MANDATORY when user-facing changes shipped)
+
+The session report is for the next *agent*; CHANGELOG.md is for downstream
+*consumers*. Both must stay in sync — the report alone is not enough.
+
+```bash
+ls CHANGELOG.md 2>/dev/null   # confirm the project keeps one
+git tag --sort=-v:refname | head -3   # last release tag
+git log <last-tag>..HEAD --oneline    # what is missing
+```
 
-Reports are versioned handoff artifacts and should be tracked.
+Decision tree:
+
+- **A release was cut this session** (new tag, e.g. via `/releasing` or
+  `changelog-keeper`): the new version section already exists. Verify it
+  contains every user-facing change from the session and that
+  `[Unreleased]` is empty. Stop — release flow owns CHANGELOG.
+- **No release was cut**: append every user-facing change from the session
+  to the existing `[Unreleased]` block at the top of CHANGELOG.md. Use
+  Keep a Changelog categories: `### Added` / `### Changed` / `### Deprecated`
+  / `### Removed` / `### Fixed` / `### Security`. One bullet per change,
+  lead with the affected subsystem or symbol, include the bead ID(s) when
+  available — same prose density as prior `[Unreleased]` entries.
+- **No user-facing change shipped** (pure orchestration, doc-only edits to
+  internal-handoff files like reports/skills, refactors with no observable
+  effect): skip — do not pollute `[Unreleased]` with internal noise. Note
+  the skip in the Documentation Updates section so it is auditable.
+
+What counts as user-facing for `[Unreleased]`:
+- new or removed CLI flags, commands, env vars, config keys
+- new or removed services / containers / jobs an operator deploys
+- schema migrations that downstream consumers see
+- new or removed API/MCP/REST endpoints, tools, or response fields
+- bug fixes that change observable behavior
+- security-relevant changes
+
+What does NOT belong in `[Unreleased]`:
+- session reports themselves
+- skill or memory edits that only affect agents
+- refactors with byte-identical observable behavior
+- per-issue notes that already live in beads
+
+If the project has no CHANGELOG.md, skip silently — do not create one
+without operator direction.
+
+### 7. Commit the report (and CHANGELOG if updated)
+
+Reports are versioned handoff artifacts and should be tracked. If Step 5
+modified `CHANGELOG.md`, fold it into the same commit so the report and
+changelog ship together.
 
 ```bash
-git add .xtrm/reports/
+git add .xtrm/reports/ CHANGELOG.md   # CHANGELOG.md only if changed
 git commit -m "session report: <date>"
 ```
 
@@ -175,11 +318,29 @@ If you updated an existing same-day report after an earlier report commit, commi
 that update with the same message style or fold it into the current final commit
 before push.
 
+### 8. Final cleanup verification (MANDATORY)
+
+After committing, re-run the Step 0 checks one more time:
+
+```bash
+git worktree list
+sp ps
+ps -ef | grep -E '(serena|gitnexus|specialists|sp-serve|sp-script)' | grep -v grep
+tmux ls 2>/dev/null
+```
+
+If any of these show session-leaked artifacts, stop them now or document them
+in the report. Do not consider the session "closed" until this verification is
+clean.
+
 ## Quality bar
 
 The reference is `~/projects/specialists/.xtrm/reports/2026-03-30-orchestration-session.md`.
 Every report must match that level of detail. Specifically:
 
+- Step 0 cleanup performed before report generation; Step 8 verification clean.
+- Step 5 due-diligence sweep performed; service skills, docs, memories, CLAUDE.md, evidence, decisions, tests, and skill mirrors checked (or skipped with reason).
+- Step 6 CHANGELOG sync performed when user-facing changes shipped (or skip noted).
 - No empty `<!-- FILL -->` markers left in the final output
 - No duplicate same-day reports unless explicitly requested by the operator
 - Every closed issue has context, not just an ID

package/.xtrm/skills/default/sync-docs/SKILL.md

@@ -78,7 +78,7 @@ and stop.
 
 ```bash
 python3 .xtrm/skills/default/sync-docs/scripts/drift_detector.py scan --json \
-  | jq '[.[] | select(.path == "<YOUR_DOC>")]'
+  | jq '[.stale[]? | select(.doc == "<YOUR_DOC>")]'
 ```
 
 If your doc reports stale, capture the list of commits since `synced_at` — those are your candidate commits for Phase 3.

package/.xtrm/skills/default/update-xt/SKILL.md

@@ -28,7 +28,8 @@ This is what a correctly installed project looks like. Check each item.
 | `.xtrm/skills/active/` | Flat directory of symlinks to `../default/<skill>` |
 | `active/pi/` subdirectory | Must NOT exist (stale — old runtime split) |
 | `active/claude/` subdirectory | Must NOT exist (stale — old runtime split) |
-| `.pi/settings.json` `.skills` array | Must include `"../.xtrm/skills/active"` |
+| `.pi/settings.json` `.skills` array | Must include `"../.xtrm/skills/active"` (project-local, wins) |
+| `.pi/settings.json` `.skills` array | Must include `"~/.xtrm/skills/default"` (user-level fallback — xtrm-4h6u) |
 | `.pi/settings.json` `.skills` array | Must NOT include `"../.xtrm/skills/active/pi"` (old path) |
 
 ### Hooks wiring
@@ -65,10 +66,10 @@ readlink .claude/skills
 ls .xtrm/skills/active/pi 2>/dev/null && echo "STALE: active/pi exists"
 ls .xtrm/skills/active/claude 2>/dev/null && echo "STALE: active/claude exists"
 
-# 5. Pi settings skills entry
+# 5. Pi settings skills entries (both must be present since xtrm-4h6u)
 node -e "const s=require('./.pi/settings.json'); console.log(s.skills)" 2>/dev/null
-# Expected to include: ../.xtrm/skills/active
-# Stale if includes: ../.xtrm/skills/active/pi
+# Expected to include BOTH: ../.xtrm/skills/active  AND  ~/.xtrm/skills/default
+# Stale if only first entry present, or if includes: ../.xtrm/skills/active/pi
 
 # 6. Active view integrity (all entries must be valid symlinks)
 for f in .xtrm/skills/active/*; do [ -L "$f" ] || echo "NOT A SYMLINK: $f"; done
@@ -167,6 +168,16 @@ cd cli && npm run build
 xt init -y   # now runs with updated code
 ```
 
+**Worktree caveat**: `npm run build` from inside `.xtrm/worktrees/<name>/cli/` is blocked by a guard script — building from a worktree contaminates dist with worktree-specific absolute paths. If you're working in a worktree, build from a detached worktree outside `.xtrm/`:
+
+```bash
+git worktree add --detach /tmp/xt-build HEAD
+cd /tmp/xt-build/cli && npm ci && npm run build
+cp dist/index.cjs <worktree-root>/cli/dist/index.cjs
+cp dist/index.cjs.map <worktree-root>/cli/dist/index.cjs.map
+git worktree remove /tmp/xt-build --force
+```
+
 ## Verification
 
 After all fixes, confirm canonical state is restored:
@@ -198,6 +209,261 @@ If `xt status` still shows drift after targeted fixes, run the full sync:
 xt init
 ```
 
+## Multi-Repo Sweep (Fleet Update)
+
+For updating **many repos at once** after an xtrm-tools upgrade — much lighter than
+running `xt init -y` per repo. The right pattern when you've just rebuilt xtrm-tools
+locally or pulled a new tag.
+
+### Dry-run discovery first
+
+```bash
+xt update --root ~/dev               # walk the tree
+xt update --root ~/projects/mercury  # walk another tree
+```
+
+Output classifies each discovered repo by `.xtrm/` state:
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| `refreshed` | `.xtrm/registry.json` present; drift vs current package detected | `--apply` will reinstall managed assets |
+| `already-current` | `.xtrm/registry.json` present; no drift | no action |
+| `incomplete` | `.xtrm/` directory exists but `.xtrm/registry.json` is missing | `xt init -y` now seeds registry.json automatically (xtrm-ya2i, xtrm-tools ≥ 0.7.18). Older `.xtrm/` dirs created before that fix still need the recipe below. |
+| `failed` | Hard error during drift check or install | inspect reason — common: PACK metadata drift, missing source files, fs-extra refusing to copy onto a symlink |
+
+Transient worktree paths under `.worktrees/` (specialists) or `.xtrm/worktrees/`
+(`xt claude` / `xt pi`) are **skipped** automatically — they're not real repos to
+refresh.
+
+### Apply
+
+```bash
+xt update --apply --root ~/dev
+xt update --apply --root ~/projects/mercury
+```
+
+What `--apply` does for each managed repo:
+- Runs the install flow with `force=true` — refreshes `.xtrm/config`, `.xtrm/hooks`, `.xtrm/skills/default` (mirror), `.pi/settings.json`, `.mcp.json`.
+- Writes `dolt.shared-server: true` into `.beads/config.yaml` if not already set (so the worktree's bd routes to the shared dolt server instead of spawning per-worktree subprocesses).
+- Globally installs any missing xt-managed Pi packages.
+- Does NOT touch `incomplete` repos (deliberate — auto-fix would be destructive).
+
+### Bootstrapping `incomplete` repos
+
+Two scenarios:
+
+**A. The repo legitimately needs full xtrm management:**
+
+```bash
+cd <repo>
+xt init -y                       # scaffolds .xtrm/{config,hooks,skills} AND seeds registry.json
+xt update --apply --repo .       # bring everything in sync (registry-driven)
+```
+
+`xt init -y` now snapshots `.xtrm/registry.json` from the installed xtrm-tools package automatically (xtrm-ya2i). The previous manual `cp /path/to/xtrm-tools/.xtrm/registry.json .xtrm/` step is no longer needed on xtrm-tools ≥ 0.7.18. If you're on an older version (or the registry is missing for some other reason), fall back to:
+
+```bash
+cp "$(npm root -g)/xtrm-tools/.xtrm/registry.json" .xtrm/
+```
+
+**B. The repo is intentionally not xtrm-managed.** Leave the `.xtrm/` partial dir
+alone; `incomplete` is just a status row, not an error. If you want it to stop
+appearing, remove the orphaned `.xtrm/` directory.
+
+### When a repo fails
+
+Common failure modes and fixes:
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Source and destination must not be the same` | `npm link`'d xtrm-tools + repo has symlinked `.xtrm/skills/default → xtrm-tools` (link chain collapses to same canonical path) | Functionally fine — repo is already in sync via the live symlinks, not a real failure. If you want to **fully decouple** the project from the dev tree, follow the migration recipe below. |
+| `PACK_METADATA_MISMATCH: metadata-only: X, filesystem-only: Y` | A user-skill-pack (`.xtrm/skills/user/packs/<name>/PACK.json`) lists a skill that has been renamed on disk | Edit `PACK.json` so the listed skill names match the directory names; re-run. |
+| `Cannot read properties of null (reading 'dolt')` | Repo's `.beads/config.yaml` is comments-only (fresh `bd init` default); pre-`xtrm-16ec` xtrm crashes parsing it | Upgrade xtrm-tools to ≥ 0.7.18; the parse result is coerced to `{}` defensively now. |
+
+## Migrating a dev-linked project to a real consumer install
+
+A project ends up with `.xtrm/skills/default` (or another `.xtrm/` asset) as a **symlink** back to the dev tree when:
+- xtrm-tools was `npm link`-ed globally (`/home/<user>/.nvm/.../node_modules/xtrm-tools` → `/home/<user>/dev/xtrm-tools/`), AND
+- the project's `.xtrm/skills/default` was manually replaced with a symlink to the npm-global path (common dev-loop shortcut so skill edits propagate instantly).
+
+`installFromRegistry`'s `scaffoldSkillsDefaultFromPackage` has an intentional branch (`registry-scaffold.ts:104`): *"if target is a symlink whose realpath equals the package realpath → noop"*. This **preserves the dev symlink** on every `xt update`. The arrangement is functional but the project is invisibly coupled to whatever lives in the dev tree (or whatever the global npm path points to).
+
+### When to migrate
+
+- Before publishing a consumer-facing release of the dependent project.
+- Before handing the project to another developer / machine.
+- When you want `xt update --apply` to actually *write files into the project* rather than no-op.
+
+### Detection
+
+```bash
+# Is .xtrm/skills/default a symlink, and where does it point?
+readlink <repo>/.xtrm/skills/default
+# If empty / not-a-symlink: nothing to migrate.
+# If points anywhere outside <repo>/: needs migration.
+```
+
+### Recipe
+
+```bash
+cd <repo>
+
+# 1. Remove the symlink (does NOT touch the real files in the dev tree).
+rm .xtrm/skills/default
+
+# 2. Re-run init — copies real files from the installed xtrm-tools package
+#    into .xtrm/skills/default/ AND seeds .xtrm/registry.json (xtrm-ya2i).
+xt init -y
+
+# 3. If the symlink was committed (git ls-files showed it as mode 120000),
+#    flip the tracked entry to a real directory:
+git rm --cached .xtrm/skills/default 2>/dev/null   # ok if it was untracked
+git add .xtrm/skills/default
+git commit -m "chore: replace dev symlink with real xtrm skills payload"
+
+# 4. Optional sanity: confirm no more symlinks point outside the repo.
+find .xtrm -type l -lname '/*' -o -type l ! -lname '../*' -a ! -lname './*'
+# Empty output means clean.
+```
+
+### What `npm install -g xtrm-tools` alone does
+
+Replacing the `npm link` with a real npm install (`npm install -g xtrm-tools`) breaks the dev-tree coupling — the global path becomes real files at the published version — **but it does not remove the project's symlink.** The symlink still points at the global npm path, which now resolves to immutable published files. The project keeps working but stays pinned to the npm-installed version forever, and `.xtrm/skills/default` remains a symlink on disk.
+
+To get true isolation (real files inside `<repo>/.xtrm/skills/default/`), the recipe above is still required.
+
+## Worktree hygiene: `.beads/` and `core.hooksPath`
+
+Modern bd 1.0.3 stores `core.hooksPath` as an **absolute parent path** at `bd init`
+time (e.g. `$HOME/repo/.beads/hooks`), so worktrees inherit parent hooks via
+shared git config — no on-disk `.beads/` is needed inside a worktree. Since
+`xtrm-cbjo` (xtrm-tools commit `937b151`) and `unitAI-yvqmf` (specialists commit
+`986bc8e4`), `xt claude` / `xt pi` / `sp run` worktrees do **not** create a
+`.beads/` symlink; they `rm -rf <worktree>/.beads` and `git update-index
+--skip-worktree --` on tracked `.beads/*` paths. This eliminates the
+squash-merge `.beads`-wipe hazard documented in projects/infra PR #39.
+
+### Audit your `core.hooksPath` once (xtrm-2s44)
+
+If your bd was installed before 1.0.3, `core.hooksPath` may be the relative
+string `.beads/hooks`, which would resolve against a worktree's cwd — i.e.,
+the (now-missing) worktree-local `.beads/hooks/`. To survey:
+
+```bash
+for r in ~/dev/*/ ~/projects/*/*/; do
+  [ -d "$r/.git" ] && [ -d "$r/.beads" ] || continue
+  hp=$(git -C "$r" config core.hooksPath 2>/dev/null || echo "<unset>")
+  case "$hp" in
+    /*)              cat="ABSOLUTE" ;;
+    "<unset>")       cat="UNSET" ;;
+    .beads/hooks)    cat="RELATIVE-BD  <- needs fix" ;;
+    *)               cat="OTHER       (project .githooks chain — leave alone)" ;;
+  esac
+  printf "%-50s %s\n" "${r#$HOME/}  $cat" "$hp"
+done
+```
+
+Classification:
+- `ABSOLUTE` — correct, no action.
+- `RELATIVE-BD` (literal `.beads/hooks` or `./.beads/hooks`) — rewrite once:
+  ```bash
+  git -C <repo> config core.hooksPath "$(realpath <repo>/.beads/hooks)"
+  ```
+- `OTHER` like `.githooks` — project-specific hook chain, leave alone. bd in
+  these repos works via direct invocation (not git hooks), so worktree hygiene
+  is unaffected.
+- `UNSET` — no hooks wired anywhere; same outcome as `OTHER`.
+
+Survey across `~/dev` + `~/projects/mercury` on 2026-05-12 returned **0 repos
+needing the fix**. The safety net in `launchWorktreeSession` /
+`provisionWorktree` (`normalizeParentHooksPath`) auto-rewrites on next worktree
+creation if a relative `.beads/hooks` ever does appear, so the survey is mostly
+defensive.
+
+### Worktree-internal artifact inventory (xtrm-x80f)
+
+A worktree is a partial clone with extras: bd metadata, npm caches, runtime
+state, per-worktree settings. None of these belong on a chain branch — but
+the moment any of them get staged via `git add -A` or a checkpoint commit,
+they can ride a PR into `main`. The matrix below documents what is protected
+by which mechanism. Audit it whenever you add a new per-worktree artifact.
+
+| Artifact | Source | Mechanism in a worktree | Status |
+|----------|--------|-------------------------|--------|
+| `.beads/*` | bd tracked dir | rm + `skip-worktree` (xtrm-cbjo) | ✅ |
+| `.beads-credential-key`, `.beads/dolt-monitor.pid`, `.beads/dolt-server.activity` | bd runtime | gitignored at parent | ✅ |
+| `.pi/npm/` | npm cache | gitignored + symlink to parent | ✅ |
+| `.pi/extensions/` | pi runtime | gitignored under `.xtrm/extensions/**/.pi/` | ✅ |
+| `.specialists/default` | (xtrm-tools: untracked) | symlink to parent in worktree | ✅ |
+| `.specialists/user` | tracked (.json overrides) | symlink to parent in worktree | ⚠️ merge-hazard candidate, tracked at follow-up bead |
+| `.specialists/{jobs,ready,trace.jsonl,db/*}` | runtime state | gitignored at parent | ✅ |
+| `.claude/skills` | install symlink | gitignored | ✅ |
+| `.claude/settings.local.json` | per-worktree write (`launchWorktreeSession`) | gitignored (user-global + project) | ✅ |
+| `.claude/worktrees/`, `.claude/tdd-guard/data/` | runtime | gitignored | ✅ |
+| `.xtrm/worktrees/`, `.xtrm/skills/active/`, `.xtrm/session-meta.json`, `.xtrm/statusline-claim`, `.xtrm/debug.db` | runtime | gitignored | ✅ |
+| `AGENTS.md`, `CLAUDE.md` | tracked | gitnexus stat-counter scrubbed (xtrm-c6sf), build-gate prevents reintroduction | ✅ |
+| `pnpm-workspace.yaml`, `cli/pnpm-workspace.yaml` | generated by pnpm in an npm-workspaces repo when specialist tooling shells out to pnpm | gitignored (xtrm-ombq) | ✅ |
+| `.gitnexus/` | runtime | gitignored | ✅ |
+| `.dolt/`, `*.db` | runtime | gitignored | ✅ |
+
+The remaining ⚠️ is `.specialists/user/*.json`: the symlink swap in
+`ensureWorktreeSpecialists` has the same shape as the pre-fix `.beads`
+problem — a chain-branch checkpoint could capture the dir→symlink delta and
+squash-merge would wipe the parent's `.specialists/user/`. Lower urgency
+than `.beads` (smaller blast radius, files are intentional overrides) but
+worth resolving with the same skip-worktree pattern when convenient.
+
+The defense-in-depth pre-push guard in `xt end`
+(`findBeadsSymlinkIntroductions`) currently only checks `.beads/*`. Extend
+to `.specialists/*` if/when the symlink swap there becomes the next chain
+of work.
+
+## Pre-Release Validation Methodology
+
+Before publishing a new xtrm-tools version, validate the operator-facing CLI locally
+against every consumer repo. This is the procedure that surfaced two release-blockers
+in 2026-05-12 alone (`xtrm-16ec` yaml-null crash, `xtrm-ny61` worktree over-discovery).
+
+### Procedure
+
+```bash
+# 1. Build dist from the local checkout
+cd /path/to/xtrm-tools && npm run build --workspace cli
+
+# 2. Link globally so `xt` runs local source
+npm link
+
+# 3. Sweep across all consumer trees (dry-run first)
+xt update --root ~/dev
+xt update --root ~/projects/mercury
+
+# 4. Identify failed/incomplete rows. Fix any real bugs in xtrm-tools FIRST,
+#    then re-build + re-link + re-sweep.
+
+# 5. Once dry-run is clean, apply across the fleet:
+xt update --apply --root ~/dev
+xt update --apply --root ~/projects/mercury
+
+# 6. Cut the public release only after the local apply succeeds end-to-end.
+```
+
+### Why this beats publishing first and patching later
+
+- A published `0.7.X` that crashes on a default-config consumer repo wastes a
+  version number — users see "upgrade and immediately break" and lose trust.
+- Bugs that only manifest on real consumer state (comments-only YAML, transient
+  worktrees, drifted PACK metadata) are invisible from xtrm-tools' own test
+  suite — only a real sweep catches them.
+- `npm link` flips between local-source-globally and published-version-globally
+  in seconds (`npm unlink` reverts), so the validation cost is minimal.
+
+### Watch-fors during the sweep
+
+- **Pi packages shown as `missing` when `npm ls -g` confirms them installed** —
+  detection bug, filed at `xtrm-ntf8`. Not a real problem; packages work.
+- **xtrm-tools itself appearing as `failed` with "Source and destination..."** —
+  expected when xtrm-tools is npm-linked into itself; not a release blocker.
+
 ## Reporting to the user
 
 After completing detection + remediation + verification, give the user a concise

package/.xtrm/skills/default/updating-service-skills/scripts/drift_detector.py

@@ -28,6 +28,7 @@ from bootstrap import (  # noqa: E402
     RootResolutionError,
     find_service_for_path,
     get_project_root,
+    get_registry_path,
     get_service,
     load_registry,
     save_registry,
@@ -110,6 +111,22 @@ def check_drift_from_hook_stdin() -> None:
     sys.exit(0)
 
 
+def _print_missing_registry_hint(project_root: str | None = None) -> None:
+    if project_root is None:
+        try:
+            project_root = get_project_root()
+        except RootResolutionError:
+            project_root = "."
+
+    root = Path(project_root)
+    expected = (
+        f"Registry not found. Expected one of: {root / 'service-registry.json'}, "
+        f"{root / '.claude/skills/service-registry.json'}, "
+        f"{root / '.xtrm/skills/user/packs/*/service-registry.json'}"
+    )
+    print(expected, file=sys.stderr)
+
+
 def update_sync_time(service_id: str, project_root: str | None = None) -> bool:
     """Update last_sync timestamp for a service in the registry."""
     try:
@@ -140,6 +157,11 @@ def scan_drift(project_root: str | None = None) -> list[dict]:
             return []
 
     root = Path(project_root)
+    registry_path = get_registry_path(project_root)
+    if not registry_path.exists():
+        _print_missing_registry_hint(project_root)
+        return []
+
     registry = load_registry(project_root)
     drifted: list[dict] = []
 

package/.xtrm/skills/default/using-script-specialists/SKILL.md

@@ -9,7 +9,9 @@ description: >
   output immediately, or when the work is a single LLM call with structured
   input/output. Do NOT use for tracked agent work — that belongs to
   `using-specialists-v2`.
-version: 1.0
+version: 1.1.0
+updated: 2026-05-06
+synced_at: a0e54d0c
 ---
 
 # Script-Class Specialists
@@ -54,7 +56,7 @@ A spec is rejected at request time (`specialist_load_error`) if any of:
 - `execution.interactive` is `true`
 - `execution.requires_worktree` is `true`
 - `execution.permission_required` is anything other than `READ_ONLY`
-- `skills.scripts` is non-empty
+- `skills.scripts` is non-empty (always rejected; no `--allow-local-scripts` bypass)
 - `prompt.task_template` is missing
 - a referenced `$var` in the chosen template is not supplied (`template_variable_missing`)
 
@@ -101,9 +103,9 @@ sp script <specialist-name> \
 Behaviour:
 
 - Loads the spec via `SpecialistLoader` (same loader as `sp run`).
-- Renders `prompt.task_template` (or named template) with `--vars`.
-- Spawns `pi --mode json --no-session --no-extensions --no-tools` with the
-  resolved model.
+- Renders `prompt.task_template` (or named template) with `--vars`, then feeds the rendered prompt via stdin.
+- `--db-path /path/to/observability.db` is an exact SQLite file path; omit it to use the project default `.specialists/db/observability.db`.
+- Spawns `pi` in JSON mode with no session, no extensions, no tools, and offline; forwards the resolved model, optional `--thinking`, and `--system-prompt` when `prompt.system` is set (full override, not append).
 - Returns the final assistant text on stdout. With `--json`, returns the full
   `ScriptGenerateResult` envelope.
 - Writes one row to `.specialists/db/observability.db` (same writer as `sp run`).