xtrm-tools 0.7.15 → 0.7.17

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.

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

@@ -143,6 +143,92 @@ sp db stats --with-payload --format json \
         end'
 ```
 
+## Recipe 7 — payload component breakdown per specialist
+
+**Truth source first.** The actual prompt size billed by the API is the first turn's `input_tokens` from `token_trajectory_json[0]`. Use it as the ground truth — `payload_breakdown` events undercount (tool definitions and harness framing are not captured) and historical rows before the rule N× fix overcount mandatory_rule by attached-rule count.
+
+```bash
+DB=.specialists/db/observability.db
+sqlite3 "$DB" "SELECT specialist, model, 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, model ORDER BY avg_first_in DESC"
+```
+
+Use this number for cost decisions. Use `payload_breakdown` only for *relative* component analysis (which knob to tune), not absolute sizing.
+
+`sp db stats --with-payload` only surfaces total `payload_kb` / `payload_tokens`. To audit *what* fills the prompt (system_prompt vs mandatory rules vs skills vs bead_context vs memory), query `payload_breakdown` events directly. Use this for eager-load bloat investigations, prompt/rule consolidation planning, or duplication hunts — but cross-check against the truth source above.
+
+```bash
+DB=.specialists/db/observability.db
+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
+rows = []
+for line in sys.stdin:
+    if "|" not in line: continue
+    spec, js = line.split("|", 1)
+    d = json.loads(js)
+    agg = {}
+    for c in d["payload_breakdown"]["components"]:
+        a = agg.setdefault(c["kind"], {"tokens":0,"n":0})
+        a["tokens"] += c["tokens"]; a["n"] += 1
+    rows.append((spec, d["payload_breakdown"]["totals"]["tokens"], agg))
+rows.sort(key=lambda r: -r[1])
+print(f"{\"specialist\":<22}{\"total\":>8}{\"rules\":>8}{\"rules_n\":>8}{\"sys\":>8}{\"skills\":>8}{\"bead\":>8}{\"mem\":>8}")
+for s, t, a in rows:
+    g = lambda k: a.get(k, {"tokens":0,"n":0})
+    print(f"{s:<22}{t:>8}{g(\"mandatory_rule\")[\"tokens\"]:>8}{g(\"mandatory_rule\")[\"n\"]:>8}{g(\"system_prompt\")[\"tokens\"]:>8}{g(\"skill\")[\"tokens\"]:>8}{g(\"bead_context\")[\"tokens\"]:>8}{g(\"memory\")[\"tokens\"]:>8}")
+'
+```
+
+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`.
+
+**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-specialists-v2/SKILL.md

@@ -272,7 +272,7 @@ sp epic abandon <epic-id> --reason "..."
 sp end
 ```
 
-`sp result <job-id>` returns the most recent completed turn for `waiting` jobs with a `Session is waiting for your input` footer — use it to inspect a keep-alive job before deciding whether to resume. For `running` jobs, `sp feed <job-id>` is the right tool; `sp poll` is deprecated. Avoid `specialists status --job` for normal monitoring; prefer `sp ps <job-id>`.
+`sp result <job-id>` returns the most recent completed turn for `waiting` jobs with a `Session is waiting for your input` footer — use it to inspect a keep-alive job before deciding whether to resume. For `running` jobs, `sp feed <job-id>` is the right tool. Avoid `specialists status --job` for normal monitoring; prefer `sp ps <job-id>`.
 
 ## Flag Semantics