xtrm-tools 0.7.16 → 0.7.18

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

@@ -1,35 +1,121 @@
 ---
 name: update-specialists
 description: >
-  Reconcile all xtrm-managed asset drift across repos.
-  Use this skill when user says "update specialists", "xtrm drift", "assets out of date",
-  or when operator needs guided refresh across one repo or many.
-version: 2.0
+  Reconcile specialists runtime drift and xtrm-managed asset drift across one repo or many.
+  Use this skill when user says "update specialists", "specialists is out of date",
+  "xtrm drift", "skills not updating", "assets out of date", or when operator needs
+  guided refresh of specialists/xtrm state.
+version: 2.1
 synced_at: 2026-05-05
 ---
 
 # update-specialists
 
-Interactive wrapper over `xt update` for xtrm-managed asset drift.
+Interactive operator workflow for the two distribution tracks:
 
-Canonical-live model:
-- **Category A**: specialist runtime / loader-live surfaces. No refresh needed; verify only.
-- **Category B**: xtrm-managed snapshots under repos (`.xtrm/skills/default/`, `.xtrm/hooks/default/`, and related managed assets). These can drift and need operator-confirmed refresh.
+- **Category A — specialists runtime / npm-live assets**
+  - specialist definitions
+  - mandatory rules
+  - tool catalogs
+  - node configs
+  - resolved by `sp` from the installed `@jaggerxtrm/specialists` package unless a repo intentionally overrides them
+- **Category B — xtrm-managed filesystem assets**
+  - skills under `.xtrm/skills/default/`
+  - hooks under `.xtrm/hooks/default/`
+  - active `.claude/skills`, `.pi/skills`, hook settings, and related registry-managed files
+  - refreshed by `xt update`
 
-Skill goal:
-1. find projects root,
-2. inspect drift,
-3. summarize per-repo state,
-4. ask operator which repos to refresh,
-5. run `xt update --apply`,
-6. re-check,
-7. report final state.
+Do not collapse these flows. Category A is specialists-owned and uses `sp` commands. Category B is xtrm-owned and uses `xt` commands.
 
-No automatic execution. Always operator-confirmed.
+No automatic destructive execution. Always summarize first and ask before applying refresh/prune actions.
 
-## Operator Flow
+## Quick Decision Tree
 
-### 1) Discover projects root
+1. User says **specialist configs/rules/catalog/node behavior is stale** → run Category A flow.
+2. User says **skills/hooks/Claude/Pi active files are stale** → run Category B flow.
+3. User says **update specialists** with no detail → run both diagnostics, then present a combined plan.
+4. User is in many repos → use root discovery and group results by repo.
+5. `xt` missing → Category A can still run; Category B falls back to install/update guidance.
+6. `sp` missing → tell user to install/upgrade `@jaggerxtrm/specialists`; do not claim runtime drift is fixed.
+
+## Category A — Specialists Runtime / npm-live Flow
+
+### A1) Verify package and command surface
+
+Run in the target repo:
+
+```bash
+sp --version
+sp doctor
+sp doctor --check-drift
+```
+
+Use `specialists` instead of `sp` if the alias is unavailable.
+
+Category A canonical source is the installed `@jaggerxtrm/specialists` npm package. To update it, upgrade/pin the package version:
+
+```bash
+npm install -g @jaggerxtrm/specialists@latest
+# or project-local/package-managed pin, depending on repo policy
+npm install -D @jaggerxtrm/specialists@<version>
+```
+
+Report the installed version and whether the repo is intentionally pinned.
+
+### A2) Interpret `sp doctor --check-drift`
+
+This checks stale `.specialists/default/` snapshots against package-canonical assets.
+
+Typical statuses:
+
+| Finding | Meaning | Action |
+|---|---|---|
+| redundant / byte-identical default | Local default snapshot duplicates package canonical | Safe to prune after review |
+| diverged default | Local default differs from package canonical | Treat as intentional until operator confirms migration |
+| missing package canonical | Installed package or registry is incomplete/stale | Upgrade/reinstall specialists package |
+| user overlay | `.specialists/user/` custom asset | Preserve; never overwrite automatically |
+
+### A3) Prune redundant Category A snapshots
+
+Dry-run first:
+
+```bash
+sp prune-stale-defaults --dry-run
+sp prune-stale-defaults --root <repo>
+```
+
+Only after operator confirmation, prune redundant defaults:
+
+```bash
+sp prune-stale-defaults --root <repo>
+```
+
+Rules:
+- Never prune `.specialists/user/`.
+- Never overwrite or delete diverged defaults without explicit operator approval.
+- If a diverged default should become a customization, move/keep it as user-owned policy and document why.
+- If the repo deliberately pins old behavior, leave `.specialists/default/` in place and record the pinned specialists version.
+
+### A4) Validate runtime resolution
+
+For specialist definitions and tool policy:
+
+```bash
+sp list --full
+sp config show <specialist> --resolved
+```
+
+For mandatory rules/skills references in custom specialists, verify resolution from package canonical or project override:
+
+```bash
+sp config show <specialist> --resolved --from-source
+```
+
+Use `--from-source` only in a specialists source/worktree context where installed dist may lag local source.
+
+## Category B — xtrm-managed Filesystem Asset Flow
+
+### B1) Discover projects root
 
 Ask for root if user did not name one.
 
@@ -41,7 +127,7 @@ Default order:
 
 If multiple candidate roots exist, ask which one to use.
 
-### 2) Run doctor
+### B2) Run xtrm doctor
 
 Use:
 
@@ -49,106 +135,147 @@ Use:
 xt doctor --cwd <root> --json
 ```
 
-If `xt` is unavailable, stop and switch to fallback guidance below.
+If `xt` is unavailable, stop Category B and use fallback guidance below. Do not invent xtrm bulk commands.
+
+### B3) Summarize Category B drift
 
-### 3) Summarize drift
+Render a clean table grouped by repo:
 
-Render clean table grouped by repo:
-- repo path
-- status
-- drift count
-- missing / extra / mismatched assets
-- suggested action
+| repo | status | drift | missing | mismatched | suggested action |
+|---|---|---:|---:|---:|---|
 
 Keep focus on operator action, not internal diagnostics.
 
-### 4) Ask for confirm
+### B4) Ask for confirmation
 
 Offer three paths:
-- refresh all repos,
+- dry-run only,
 - refresh specific repos,
-- dry-run only.
+- refresh all repos.
 
 If user names one repo, keep flow narrow and confirm only that repo.
 
-### 5) Apply refresh
+### B5) Apply xtrm refresh
 
-Use:
+Dry-run:
 
 ```bash
-xt update --apply --root <root>
+xt update --root <root>
+xt update --repo <repo>
 ```
 
-Or for one repo:
+Apply:
 
 ```bash
+xt update --apply --root <root>
 xt update --apply --repo <repo>
 ```
 
-For dry-run, omit `--apply`.
+### B6) Re-run doctor
+
+Run the same doctor command again after update:
+
+```bash
+xt doctor --cwd <root> --json
+```
+
+Confirm clean state or reduced-to-intentional drift.
+
+## Combined Multi-repo Flow
+
+When the operator asks broadly to "update specialists" across repos:
+
+1. Choose projects root.
+2. For each repo with specialists state:
+   - run/record Category A status: `sp --version`, `sp doctor --check-drift` if available.
+3. For each repo with `.xtrm/registry.json`:
+   - run/record Category B status: `xt doctor --cwd <repo> --json`.
+4. Present one combined table:
+
+| repo | specialists pkg | Category A status | Category B status | recommended action |
+|---|---|---|---|---|
+
+Recommended action examples:
+- upgrade `@jaggerxtrm/specialists`, then re-run `sp doctor --check-drift`,
+- prune redundant `.specialists/default/` snapshots,
+- preserve `.specialists/user/` customization,
+- run `xt update --repo <repo> --apply`,
+- no action.
+
+## Fallbacks
+
+### `sp` missing
+
+Say Category A cannot be verified until specialists is installed:
+
+```bash
+npm install -g @jaggerxtrm/specialists@latest
+```
+
+If project policy uses local dev dependency, recommend the project-local package manager command instead.
+
+### `xt` missing
 
-### 6) Re-run doctor
+Category A can still be checked with `sp`. For Category B, tell user:
 
-Run same doctor command again after update and confirm clean state.
+```bash
+npm install -g xtrm-tools@latest
+xt install
+xt doctor --cwd <repo> --json
+```
 
-### 7) Final report
+Do not claim skills/hooks are synced without `xt` or a valid `.xtrm/registry.json`.
 
-State:
-- what drift existed,
-- what refreshed,
-- what stayed untouched,
-- any residual manual fixes.
+### `.xtrm/registry.json` missing
 
-## Fallback When xt Missing
+Report that xtrm-managed assets cannot be drift-checked in that repo until registry scaffold exists. Suggested action:
 
-If `xt` / `xtrm` not installed or doctor/update help unavailable:
-- do not block user,
-- switch to per-repo guidance,
-- tell user to run repo-local checks manually,
-- do not invent bulk repair commands.
+```bash
+xt install
+```
 
-Fallback response shape:
-- identify likely drifted repos,
-- point user at repo-local `sp doctor` / package-specific checks already available in that repo,
-- say bulk refresh needs `xt` installed.
+or pull a repo revision that tracks `.xtrm/registry.json`.
 
-## Drift Review Rules
+## Safety Rules
 
-- Treat repo-custom overlays as intentional unless doctor marks them mismatched against managed snapshot.
-- Do not overwrite user-owned layers.
-- Prefer dry-run first when drift touches multiple repos.
-- If only one repo needs refresh, keep output narrow and use single-repo update path.
-- If doctor shows mixed drift across 3 repos, summarize each repo separately and ask which to refresh.
+- Preserve `.specialists/user/` and any user-authored skill/hook layer.
+- Treat `.specialists/default/` as compatibility/pinning surface, not normal fresh-repo state.
+- Treat `.xtrm/skills/default/` and `.xtrm/hooks/default/` as managed output; do not hand-edit as the repair path.
+- Prefer dry-run first when more than one repo will change.
+- Keep Category A and Category B results separate in the final report.
 
 ## Output Shape
 
 Use this order:
-1. root chosen
-2. doctor summary
-3. drift table
-4. confirm prompt
-5. update action
-6. post-update doctor result
-7. final status
+1. root/repo chosen,
+2. specialists package version and Category A summary,
+3. xtrm Category B summary,
+4. combined drift table,
+5. proposed actions,
+6. explicit confirmation request,
+7. commands run,
+8. post-action verification,
+9. residual manual work.
 
 ## Example Operator Loop
 
 ```text
 Root: ~/dev
-Doctor: 3 repos checked
 
-repo                      status      drift
-repo-a                    drifted     4 assets
-repo-b                    in-sync     0 assets
-repo-c                    drifted     1 asset
+repo       sp version  Category A                  Category B              action
+repo-a     3.13.0      redundant defaults: 4        skills drift: 2         prune A + xt update
+repo-b     3.12.0      package behind latest        in-sync                 upgrade sp only
+repo-c     3.13.0      user overlay only            hooks drift: 1          preserve user + xt update
 
-Refresh all / specific repos / dry-run?
+Apply which actions? dry-run / selected repos / all
 ```
 
-## Verification
+## Verification Checklist
 
-After refresh:
+After work:
+- `sp doctor --check-drift` clean or reduced to intentional pins/overrides,
+- `sp prune-stale-defaults --dry-run` shows no redundant defaults unless intentionally retained,
+- `sp list --full` and selected `sp config show <name> --resolved` reflect package-live runtime,
 - `xt doctor --cwd <root> --json` clean or reduced to intentional custom drift,
-- repo-specific follow-up actions called out only when needed,
 - single-repo case stays single-repo,
-- missing `xt` path falls back cleanly.
+- missing-tool paths fall back cleanly.