xtrm-tools 0.7.17 → 0.7.18

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.

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

@@ -633,36 +633,29 @@ Release helper contract:
 
 ## Epic Lifecycle
 
-Epics are merge-gated identities with a persisted state machine:
+Epics are merge-gated identities with a **derived** readiness model. State is computed live from chain readiness; only `merged` and `abandoned` are persisted as terminal markers.
 
-```text
-open -> resolving -> merge_ready -> merged
-                  -> failed
-                  -> abandoned
-```
+| Derived state | Meaning | Per-chain merge | Batch merge |
+| --- | --- | :---: | :---: |
+| `blocked` | Some chain pending or has no reviewer verdict. | — | No |
+| `failed` | At least one chain has a failed reviewer verdict. | per-chain on PASS chains | No |
+| `merge_ready` | All chains pass and no active jobs. | Yes | Yes via `sp epic merge` |
+| `merged` | (persisted) Publication complete. | — | — |
+| `abandoned` | (persisted) Cancelled without merge. | — | — |
 
-| State | Meaning | Chains mergeable? |
-| --- | --- | --- |
-| `open` | Epic created, chains not yet running. | No |
-| `resolving` | Chains actively running. | No |
-| `merge_ready` | All chains terminal, reviewer PASS, tsc gate passes. | Yes via `sp epic merge` |
-| `merged` | Publication complete. | — |
-| `failed` | One or more chains failed. | Resolve or abandon. |
-| `abandoned` | Cancelled without merge. | — |
-
-Operator transitions:
+Operator commands:
 
 ```bash
-sp epic resolve <epic-id>              # open -> resolving (marks epic as merge-ready target)
-sp epic merge <epic-id>                # merge_ready -> merged (canonical publication)
+sp epic merge <epic-id>                # publish all chains; auto-runs finalize preflight
 sp epic merge <epic-id> --pr           # PR mode (publish via pull request)
-sp epic sync <epic-id> --apply         # reconcile DB vs live job state when stuck
+sp epic sync <epic-id> --apply         # recompute derived readiness; repair drift
 sp epic abandon <epic-id> --reason <t> # terminal close for unrecoverable epic
 sp epic abandon <epic-id> --reason <t> --force  # force when active pointers still exist
 ```
 
-`sp merge <chain>` refuses if the chain belongs to an unresolved epic. Use
-`sp epic merge` for epic-owned chains.
+`sp merge <chain>` is allowed for any PASS chain regardless of sibling-epic state. Use `sp epic merge` only when batching all epic chains together. `sp finalize <chain>` is a manual recovery for keep-alive executors that reached PASS but did not auto-finalize.
+
+`sp epic resolve` was removed — there is no operator-driven open→resolving transition anymore; readiness is recomputed every read.
 
 ## Concurrency And Force Flags