xtrm-tools 0.7.16 → 0.7.18

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-kpi/SKILL.md

@@ -179,14 +179,56 @@ for s, t, a in rows:
 '
 ```
 
-Component kinds: `system_prompt`, `mandatory_rule` (one event entry per attached rule), `skill` (path reference, ~10 tokens — bodies are loaded on demand, not eagerly), `task_template`, `bead_context`, `memory`.
+Component kinds: `system_prompt`, `mandatory_rule` (one event entry per attached rule), `skill` (path/description label only — full bodies are eagerly injected at runtime but NOT counted here), `task_template`, `bead_context`, `memory`.
 
-Optimization signals:
-- `mandatory_rule` total dominates: audit wrapper inflation by comparing `bytes` per rule in the event vs `wc -c config/mandatory-rules/<id>.md`. Mismatch >5x means a wrapper or richer source is adding hidden cost — investigate `formatMandatoryRulesBlock` and `parseMandatoryRulesFrontmatter`.
-- `skill` total small (always): skills are reference-only at startup; inlining skill bodies into rules saves nothing.
-- `bead_context` huge: the bead description is bloated — orchestrator should write more concise contracts.
+**Important:** `skill` entries in `payload_breakdown` show only the path/description label (~10-40 tokens). The full skill body is forcefully injected via `skills.paths` on every run and IS billed as input tokens. To measure the real eager-skill cost, see Recipe 8.
+
+Optimization signals (from breakdown alone):
+- `mandatory_rule` total dominates: audit wrapper inflation by comparing `bytes` per rule in the event vs `wc -c config/mandatory-rules/<id>.md`. Mismatch >5x means a wrapper or richer source is adding hidden cost.
+- `bead_context` huge: bead description is bloated — orchestrator should write more concise contracts.
 - `memory` huge: stale or noisy memories — run `bd memories` cleanup or consolidation.
 
+## Recipe 8 — eager skill-body cost per specialist
+
+`skills.paths` are eagerly injected on every run; the bodies appear in the API-billed prompt but the `payload_breakdown` event records only the path label. To derive the real eager-skill cost:
+
+```
+eager_skill_cost ≈ first_turn_input_tokens − sum(payload_breakdown non-skill components)
+                   − constant per-specialist framing/tool-defs overhead
+```
+
+Two-step audit:
+
+```bash
+# Step 1: real first-turn input tokens per specialist (truth)
+DB=.specialists/db/observability.db
+sqlite3 "$DB" "
+  SELECT specialist, AVG(json_extract(token_trajectory_json, '\$[0].token_usage.input_tokens')) AS avg_first_in, COUNT(*) AS n
+  FROM specialist_job_metrics
+  WHERE token_trajectory_json IS NOT NULL AND status='done'
+  GROUP BY specialist ORDER BY avg_first_in DESC"
+
+# Step 2: per-specialist measured non-skill components (post-kdl4n)
+sqlite3 "$DB" "SELECT specialist, event_json FROM specialist_events WHERE type='payload_breakdown' GROUP BY specialist ORDER BY t DESC" \
+  | python3 -c '
+import json, sys
+for line in sys.stdin:
+    if "|" not in line: continue
+    spec, js = line.split("|", 1)
+    d = json.loads(js)
+    non_skill = sum(c["tokens"] for c in d["payload_breakdown"]["components"] if c["kind"] != "skill")
+    print(f"{spec:<22}{non_skill:>10}")
+'
+```
+
+Then `delta = first_in − non_skill_total`. The framing/tool-defs constant is roughly the same across specialists with the same model — you can estimate it by running a specialist with NO `skills.paths` attached as a baseline.
+
+Per-skill body weight: `wc -c <skill-path>/SKILL.md` divided by 4 (cl100k_base approximation). High-frequency, large-body skills are the inlining candidates; low-frequency or small ones stay attached.
+
+Optimization signals (skills):
+- `delta` >> sum of attached skill body bytes/4: framing/tool defs are the bulk — leave skills alone.
+- `delta` ≈ sum of skill body weights: skills dominate eager cost — inline frequently-used hot guidance into `system_prompt`, keep rare deep references as skills, consider splitting big mixed skills.
+
 ## References
 
 - `docs/observability-metrics.md`

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`).

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

@@ -119,13 +119,13 @@ specialists status --job <job-id>             # single-job detail view (legacy
 # Epic lifecycle (canonical publication path)
 specialists epic list [--unresolved]          # list epics with lifecycle state
 specialists epic status <epic-id>             # show chains, blockers, readiness
-specialists epic sync <epic-id> [--apply]     # reconcile DB vs live state (dry-run default)
-specialists epic resolve <epic-id>            # transition open -> resolving
+specialists epic sync <epic-id> [--apply]     # recompute derived readiness; repair drift
 specialists epic abandon <epic-id> --reason <text> [--force]  # terminal transition for stuck epics
-specialists epic merge <epic-id> [--pr]       # publish all epic-owned chains
+specialists epic merge <epic-id> [--pr]       # publish all epic-owned chains; auto-finalizes PASS chains
 
-# Merge (for standalone chains only)
-specialists merge <chain-root-bead> [--rebuild]  # publish ONE standalone chain
+# Merge (per-chain or standalone; PASS chains can merge inside an active epic)
+specialists merge <chain-root-bead> [--rebuild]
+specialists finalize <chain-root-bead>           # manual recovery if PASS auto-finalize did not fire
 
 # Session close (chain-aware, epic-aware)
 specialists end [--pr]                        # close session, publish via merge or PR
@@ -682,14 +682,15 @@ sp epic list --unresolved   # show non-terminal epics
 
 # Inspect one epic
 sp epic status unitAI-3f7b
-# Shows: persisted_state, readiness_state, chains[], blockers[], summary
+# Shows: derived readiness state, persisted state (audit only), chains[], blockers[], summary
 
-# Transition states (manual)
-sp epic resolve unitAI-3f7b   # open → resolving
-
-# Publish
-sp epic merge unitAI-3f7b     # merge_ready → merged
+# Publish (no manual state transition — readiness is derived live)
+sp epic merge unitAI-3f7b     # batch publish all chains; auto-finalizes PASS chains
 sp epic merge unitAI-3f7b --pr # PR mode
+
+# Or per-chain (PASS chain inside active epic is allowed)
+sp merge <chain-root-bead>
+sp finalize <chain-root-bead>  # manual recovery if PASS auto-finalize missed
 ```
 
 ### Conflict handling
@@ -1136,7 +1137,7 @@ sp stop <job-id> --force
 
 ### 5) `sp end` open-state loop fix
 
-If `sp end` detects open-state mismatch, tool now suggests `sp epic resolve <epic-id>` as next command (no redirect loop).
+If `sp end` detects open-state mismatch, tool surfaces the derived readiness summary (`sp epic status <epic-id>`) and the per-chain merge path. There is no `sp epic resolve` anymore — readiness is recomputed live from chain state.
 
 - **RPC timeout on worktree job start** (30s, `command id=1`) → pi runs `npm install` in fresh
   worktrees if `.pi/settings.json` lists local packages. Root cause: worktree gets a stale copy

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

@@ -0,0 +1,137 @@
+---
+name: using-specialists-auto
+description: >
+  Operator-offline autonomous orchestration overlay. Activate when the user says
+  "auto mode", "full auto", "run autonomously", "I'll leave you alone", or
+  similar — and hands over a multi-item priority list. Layers on top of
+  `using-specialists-v3`: paranoid pacing, dispatch loop shape, dist-rebuild
+  discipline, escalation triggers specific to unsupervised runs. Does NOT
+  duplicate v3's bead contracts, sleep table, rebuttal patterns, escalation
+  matrix, or session-end handoff — refers to v3 for those.
+version: 2.0
+---
+
+# Using Specialists — Auto Mode (overlay)
+
+You are running unsupervised. Every shortcut you skip costs the operator on return. Move slowly enough to be correct.
+
+`using-specialists-v3` is the canonical specialist orchestration skill — bead contracts, role selection, advisory passes, sleep cadence, rebuttal patterns, escalation matrix, session-end handoff all live there. This skill adds **only** the discipline overlay that changes when no operator is present to catch drift.
+
+## When this skill activates
+
+User explicitly hands over autonomy: "auto mode", "go", "I'll leave you alone", "run the list", "do them all". Skill stays active until session end or the operator returns. Do NOT activate on a single ad-hoc task.
+
+## Auto-mode-specific rules (in addition to v3 hard rules)
+
+These EXTEND v3's Non-Negotiable Rules + Escalation Matrix — they do not replace them.
+
+1. **Default to serial chains.** Auto-mode rarely benefits from parallel chains; the project-wide commit gate (v3 → Bead Lifecycle) forces serial-tail anyway. Only parallelize when file scopes are provably disjoint AND the time savings outweigh the conflict-resolution cost (rare).
+2. **Re-read each bead and defend each field in your head before launching.** If you can't, the bead isn't ready. Title-only beads waste a turn.
+3. **Rebuild + smoke after each P0 (and after every chain touching `src/`).** Skipping breaks the next chain's baseline silently.
+4. **One rebuttal per reviewer, then escalate.** v3 documents the rebuttal pattern — auto-mode just caps the loop count.
+5. **Session-close report is non-optional.** Operator returning to a clean tree but no report = blind cold-start next session. Follow `/session-close-report` skill at session end.
+
+## Per-item loop shape
+
+```
+read bead → write 7-section contract (child impl bead) → bd dep add parent→child
+  → sp run executor --bead <impl> --keep-alive --context-depth 3 --background
+  → sleep 10 && sp ps                              # confirm started, not stuck queued
+  → sleep <role-typical from v3> & sp ps          # check (see v3 Monitoring section)
+  → sp result <exec-job>                           # consume immediately on transition to waiting
+  → optional advisory passes per v3 (code-sanity if smelly, security-auditor if risk surface)
+  → write reviewer bead contract → sp run reviewer --bead <review> --job <exec-job> --background
+  → sleep 90 & sp ps
+  → sp result <reviewer-job>
+  → PASS?    → sp finalize <exec> → sp merge → rebuild dist → smoke → close chain (memory ack first)
+  → PARTIAL? → resume executor with exact findings → resume reviewer
+  → FAIL with valid evidence?       → stop and report (file follow-up bead)
+  → FAIL with overcautious gate?    → rebut once with cited evidence (v3 → Specialist Rebuttal As Routine)
+```
+
+## Dist rebuild + commit after every P0 or src/-touching chain
+
+```bash
+bun build src/index.ts --target=bun --outfile=dist/index.js
+sed -i '1s|#!/usr/bin/env node|#!/usr/bin/env bun|' dist/index.js
+chmod +x dist/index.js
+git add dist/index.js dist/types/<changed-paths> 2>/dev/null
+git commit -m "build: rebuild dist after <bead-id> <one-line summary>"
+```
+
+Without this, the next chain's tests/smokes run against stale dist and the globally-installed `sp` binary (symlinked to local `dist/index.js`) silently uses pre-fix behavior.
+
+## Smoke per chain
+
+Tighter than v3's E2E Smoke Phase (which is integration-end). Per-chain smoke is:
+
+- `bunx tsc --noEmit` clean
+- The targeted test(s) the chain added — green
+- After P0 also: `sp --version`, the specific CLI surface that changed, and (if runtime resolution touched) the same command from a non-repo cwd (`cd /tmp/smoke && sp <cmd>`)
+
+If any chain in the session touched auth/secrets/input/dep-lock surface, do v3's cross-cutting security-auditor pass once at end before session close.
+
+## Pre-merge state hygiene (transitional, until v3.14.2 ships globally)
+
+`sp merge` now ignores `.beads/` and `.xtrm/skills/active/**` (per `unitAI-pqe96` shipped this session). The globally-installed `sp` symlinks to local `dist/index.js`, so after `npm install -g .` the fix is live locally. If you still see `sp merge` refuse on dirty state, the leftover is usually a STAGED `.beads/issues.jsonl` (`M ` not ` M`):
+
+```bash
+git restore --staged .beads/issues.jsonl 2>/dev/null
+git checkout -- .beads/issues.jsonl 2>/dev/null
+sp merge <chain-root-bead>
+```
+
+In the worktree, drop noise stash before merging if `.xtrm/skills/active/...` files are dirty:
+
+```bash
+git stash push -u -m "noise" -- .xtrm/
+```
+
+After merge cleanup: `git worktree remove <path> --force`, `git branch -D feature/<bead>-<role>`, `git worktree prune`, `rm -rf .worktrees/<bead>`.
+
+## Auto-mode-specific escalation triggers
+
+These supplement v3's Escalation Matrix — stop and report when:
+
+- Reviewer FAIL twice after one rebuttal attempt (v3 rebuttal limit hit).
+- Any chain looped twice with no progress.
+- Repeated specialist crashes (>2 same role).
+- Cross-project state pollution (specialists from another repo holding locks/processes).
+- Anything that would otherwise require a v3 hard-rule break.
+
+When you stop: file an issue bead with concrete evidence (PIDs, job IDs, exact error), save a memory if the failure mode is durable, write a partial session-close report, do NOT abandon mid-merge.
+
+## Session start (auto-specific)
+
+In addition to v3's session-start patterns (`bd prime`, `bv --robot-triage`):
+
+```bash
+specialists list --full     # confirm current roles + models (registry may have drifted)
+sp ps                        # 0 active expected
+git worktree list           # main only expected (specialist worktrees from prior sessions should be cleaned)
+git status -s               # clean expected
+bd ready                     # work to pick up
+```
+
+If any of these are dirty (active jobs, lingering worktrees, dirty tree from prior session), reconcile before claiming new work.
+
+## Session close (mandatory)
+
+Per v3 → At Session End — Mandatory Handoff. Auto-mode addenda:
+
+1. Confirm `sp ps` empty (0 running, 0 waiting) and `git worktree list` shows only main.
+2. Drop accumulated stashes if they contain only known noise.
+3. Memory gate at session level: `bd kv set "memory-gate-done:<session-id>" "saved: <durable-insights>"` (or `"nothing novel: <reason>"`).
+4. Run `/session-close-report` skill — fills the canonical report template, drives CHANGELOG sync, commit, push.
+
+## Telltale signs you're drifting from auto-mode discipline
+
+- Skipping bead contracts because "the change is small" → write it anyway, costs nothing, downstream specialist needs it.
+- Polling `sp ps` more often than v3's sleep table → wastes context.
+- Letting executors run >2× expected without `sp feed` → blocking future work.
+- Accepting reviewer FAIL without cited evidence in the rebuttal → produces longer loops.
+- Manually editing a config file because "the executor would just do the same thing" → breaks v3 hard rule 13 (orchestrator never edits code), no audit trail.
+- Skipping `bun run build` after src/ change → next chain's smoke fails for unrelated reason.
+- Closing the parent bead before chain memory saved → loses durable insight forever.
+
+Read once at session start. Re-read if you catch yourself drifting.