@jaggerxtrm/specialists 3.18.0 → 3.18.2

package/docs/design/roadmap/specialists-roadmap.md

@@ -82,7 +82,7 @@ Discovered late via `bd help`: bd already implements primitives that several Opp
 | `bd gate` (create / check / resolve / list / add-waiter) | Async wait conditions with typed gates: `human` (manual close), `timer` (timeout), `gh:run` (GitHub workflow), `gh:pr` (PR merge), `bead` (cross-rig). Phase rollout 1-4. | **Opp 4** (composition gate), **Opp 8** (step_completed → gate satisfaction), `bd gate add-waiter` covers reviewer-↔-executor loop substrate-style. | `bd gate check` is already the "advance on satisfied" mechanism Opp 8 proposes for the bridge. |
 | `bd swarm` (create / list / status / validate) | "Structured body of work defined by epic + children with DAG"; epic-→-children with dependency graph. | **Opp 4** (chain composition), the molecule mental model in §0 | `bd swarm validate` checks DAG well-formedness — the composition pre-check Opp 4's `sp chain review` proposes. |
 | `bd create --skills <list>` (field) | Required skills declared on issue. | **substrate §10.4** skills-as-capability bridge | No roadmap Opp uses it; D26/D29 talk about skill discipline but never reach for this field. |
-| `bd state` / `bd set-state` | Multi-dimensional state (NOT just status open/closed); creates event + updates label. | **Opp 16** SCRUTINY, future state-dim work | SCRUTINY can be a state dimension instead of a contract field if substrate §6.6 chain-property model lands that way. |
+| `bd state` / `bd set-state` | Multi-dimensional state (NOT just status open/closed); creates event + updates label. | **Opp 16** SCRUTINY, future state-dim work; **[shipped 2026-07-03, doc-only bridge]** `contract:draft`/`contract:ready` bead-promotion gate (§5.3) | SCRUTINY can be a state dimension instead of a contract field if substrate §6.6 chain-property model lands that way. The `contract` dimension is the first state-dim actually in use — taught in skills/CLAUDE.md today; the `run.ts` hard-refuse check per §5.3 is still unbuilt. |
 | `bd wisp-type` (heartbeat/ping/patrol/gc_report/recovery/error/escalation) | TTL ephemeral patterns for short-lived issues subject to GC. | — | New paradigm; not yet referenced in roadmap. May be relevant for orchestrator-observability events. |
 | `bd create` fields not yet leveraged: `acceptance`, `design`, `context`, `due`, `estimate`, `metadata` (custom JSON), `spec-id`, `waits-for` + `waits-for-gate` (fanout) | First-class fields separate from description/notes | **Opp 12** XML contracts proposes embedding much of this in description XML; `waits-for`/`waits-for-gate` may be a cleaner bd-native alternative to Opp 8's event-based hand-off. | The XML-in-description approach (Opp 12) may be reinventing native bd fields. Worth re-evaluating. |
 | `bd federation` | Peer-to-peer federation between workspaces | — | Future cross-repo coordination (`unitAI-eoqxp.5`-shaped) may use this natively. |
@@ -215,6 +215,8 @@ Each opportunity (a) is implementable without the substrate daemon or `container
 
 **Opportunity 1 — Worktree lease shimmed onto chain-identity.** Add `worktree_lease_held_by` + `worktree_lease_state` to the chain-identity/status row (today jobs; later containers). Writer-step (executor, debugger) + lease `free` → acquire on dispatch, release on `agent_end` (supervisor.ts:1658). Writer-step + lease `held` → queue (`WAIT: lease held by <job>`). Read-only step → do not touch the lease; bind to the path (Opp 2). Closes Asymmetry 2 + much of 4/6; `--worktree`/`--job` mutual-exclusion becomes derivable from lease state. **Reads forward:** §6.9.6 *is* this column moved job→container; migration is rename + ownership transfer.
 
+> **[2026-06-28 ownership note — specialists-05q.5].** Lease arbitration itself is **not owned by specialists**. Container/worktree leasing belongs to **bd merge-slot / substrate lease** (substrate §6.9.6, exposed today via `bd merge-slot` semantics). Specialists does **not** introduce new `sp lease*` columns; the runtime row carries a foreign-key-style pointer to the lease owner (today: the chain-identity row references the bd-side slot; tomorrow: `containers.lease_*` per substrate). Specialists' role is to *observe* and *surface* lease state in `sp ps` / `sp doctor` / job feed, never to hold or arbitrate it. See §B for the full ownership split.
+
 **Opportunity 2 — READ_ONLY specialists bind by path, decoupled from owner keep-alive.** Today reviewer/code-sanity via `--job <owner>` requires the owner alive (waiting) — for the *workspace handle*, not LLM-state. Patch: when the dispatched specialist is `permission: READ_ONLY`, runner binds to the worktree **path** stored on `--job <owner>` (read once, cached) instead of requiring the owner live. Owner can be `done`/`closed`/killed; the read-only reviewer enters on its own pi session, reads the diff against the lease base, produces evidence. `--job` becomes a **workspace pointer**, not a **liveness pointer**, for read-only roles. Closes Asymmetry 6 + reduces the forgotten-`sp finalize` leak. **Reads forward:** §6.9.6 read-only steps don't acquire the lease and don't require a writer live — identical semantics; when containers land the lookup target moves job→container, surface identical. **This is the highest-leverage runtime patch. Land first.**
 
 **Opportunity 3 — Persist resolved chain shape as data.** Add a thin `chain_shapes` table (or `~/.specialists/chains/<chain-id>.json`). **[adjusted] The shape matches `resolved_chain_json` (§6.9.2): Layer-1 domain steps + Layer-2 overlaid gates, reached/pending per step** — so migration is a true rename, not a content transform:
@@ -270,6 +272,8 @@ The shape is persisted (Opp 3) on approve; dispatch follows it. Closes Asymmetry
 
 `--force-` taught "this is normal, override"; `--accept- --reason` makes it deliberate and audit-traceable. Closes B5. **Reads forward:** §6.4 precondition gate (precondition violation, not §5.10 recovery); the envelope matches channels.md §10.2; `--accept --reason` survives into `sb dispatch --allow-unready --reason`. **Stretch (non-blocking):** patch-id equivalence detection in `evaluateMergeWorthiness` — if the sibling's commits are patch-id-equal to commits already on master under a different SHA, the guard does not fire (addresses the over-fire root cause, §9.2).
 
+> **[2026-06-28 extension — specialists-05q.5, absorbs `specialists-05q.3`].** The stale-base gate also owns **fetch-and-pin base SHA** semantics — this is *not* a separate opportunity, it lives inside Opp 7. On dispatch the runtime runs `git fetch <remote> <base-branch>` once, resolves the tip to a SHA, and records that SHA on the chain-identity/observability row as `base_sha_pinned` + `base_sha_pinned_at_ms` (durable migration shape in §B). All subsequent staleness checks compare against the *pinned* SHA, not a re-read of `origin/master` HEAD — this eliminates the "base moved mid-chain → false stale" race that drove most over-firing. `--accept-stale-base --reason` continues to override; the refusal envelope gains `base_sha_pinned`, `base_sha_observed`, `commits_behind` fields. **Specialists owns the pinning** because it is a *job-observability* fact (which SHA this run measured against); the *fetch primitive* itself remains in xt (xtrm-tools epic `xtrm-lk4on`). No new bd column, no new substrate entity — pinning is an additive column on the existing job/observability row, mirrored later as `containers.base_sha_pinned` per the §B migration table.
+
 **Opportunity 8 — `step_completed` event with next-step recommendation.** On pi `agent_end`, extend the status row: look up Opp 3's resolved-shape row, find the just-completed step, compute the next from the template, emit `runner_event` kind `step_completed` with `{ completed, next, next_dispatch_command }`. `sp result` (§5.2) and `sp chain` (Opp 4) read it. **[recalibrated/principle]** This is also where **D2** lands: the `step_completed` for an executor carries the executor's *claimed* result, but the chain does not advance on it — it advances when the **independent gate** (code-sanity/local-validation) persists its verdict (§3.1). The executor's self-report is informational; the gate's evidence is authoritative. **[absorbed — bridge until channels v0]** Per `channels.md` §11, the channels-v0 `kind=verdict` discriminated-union message subsumes this event; when channels v0 ships, `step_completed` retires and the reviewer-↔-executor loop runs end-to-end via `verdict` + `finding` channel messages with no `sp resume`. Opp 8 supplies the same next-step recommendation in event form until then.
 
 **[discipline] Bridge-era restitch is manual-orchestrator-driven.** Substrate §3.1 has a daemon that auto-advances on member `agent_end` from persisted evidence — that's the target state. The bridge has **no daemon**. So when a gate produces a regression-finding verdict and the resolved-shape (Opp 3) says the next step is `debugger`, the `step_completed.next_dispatch_command` is a **recommendation**, not a trigger — the orchestrator (Claude/human/auto-mode harness) reads it via `sp chain <bead>` or the event stream and **executes the `sp run` manually**. Lease handoff is automatic (executor agent_end → lease free → debugger acquires per Opp 1), but the *invocation* is orchestrator-side until substrate's daemon takes over. This keeps the restitch loop honest in the bridge and avoids inventing a half-daemon that would later need to be unwound.
@@ -441,7 +445,7 @@ Both verbs surface counts (`stopped 7 waiting, skipped 3 terminal, refused 1 run
 
 **Opportunity 14 [shipped 2026-05-31] — Canonical-pipeline completion: `test-engineer` step + `test-runner` upgrade + chain_template wiring.** *(Beads: epic `unitAI-sfwe1`, design canon `docs/design/chain-templates.md` §2, formula integration `unitAI-f9kku`.)*
 
-**Problem today.** The current canonical pipeline (already in production via `using-specialists-v3`) runs `executor → code-sanity → obligations-scanner → reviewer` for production diffs. But there is a precise gap between the writer and `code-sanity`: nobody turns a production diff into the right behavioral tests, smoke/E2E checks, and telemetry assertions before the reviewer sees it. The executor is busy implementing; `test-runner` only executes. As a result, autonomous chains repeatedly ship code whose test/log/telemetry contract was never validated against the actual diff — the reviewer either gives a false PASS (no evidence to gate on) or a noisy PARTIAL (asking the operator to fill the gap manually).
+**Problem today.** The current canonical pipeline (already in production via `using-specialists`) runs `executor → code-sanity → obligations-scanner → reviewer` for production diffs. But there is a precise gap between the writer and `code-sanity`: nobody turns a production diff into the right behavioral tests, smoke/E2E checks, and telemetry assertions before the reviewer sees it. The executor is busy implementing; `test-runner` only executes. As a result, autonomous chains repeatedly ship code whose test/log/telemetry contract was never validated against the actual diff — the reviewer either gives a false PASS (no evidence to gate on) or a noisy PARTIAL (asking the operator to fill the gap manually).
 
 **Patch.** Two specialist additions/upgrades plus a chain_template formula pass that completes the canonical pipeline:
 
@@ -499,7 +503,7 @@ The fusion is architecturally clean: `reviewer.specialist.json` already declared
 **Companion enforcement.**
 
 - **Reviewer Release Checklist** (canon §2.6 already updated): three seconder lines (`scope_verdict`, `quality_verdict`, `overall_verdict`). Reviewer cannot PASS without an established `seconder.overall_verdict: PASS` at medium+.
-- **`using-specialists-v3` + `v4` SKILL docs**: teach the canonical pipeline including `seconder` step; document dual-verdict semantics + failure routing per dimension; cross-reference canon §2.3.
+- **`using-specialists` + `v4` SKILL docs**: teach the canonical pipeline including `seconder` step; document dual-verdict semantics + failure routing per dimension; cross-reference canon §2.3.
 - **Smoke/eval** (`unitAI-o7j1a` adapted): empirically prove that an off-scope writer dispatch produces `seconder.scope_verdict: FAIL` and blocks `test-engineer` from firing.
 
 **Cost: ~3 E-D-E (~half-day wall-clock auto-mode), parallelizable.** seconder spec authoring (inherit + extend code-sanity, 1 E-D-E) + reviewer prompt refactor (0.5 E-D-E) + formula integration (folds into f9kku, ~0 marginal since code-sanity → seconder is a string swap) + skill doc update (0.5 E-D-E) + eval (0.5 E-D-E) + optional mandatory rule (0.5 E-D-E).
@@ -712,9 +716,12 @@ PASS → `next: sp merge forge-eorh.48 — chain ready`. PARTIAL → `next: sp r
 | skip code-sanity on production diff | warn | `SKIP NOT PERMITTED on production diff — only test-only/new-file-only may skip.` |
 | `--force-stale-base` without `--reason` | warn (grace) | `STALE BASE: pass --reason "<why>" (Opp 7); old flag deprecated.` |
 | **cwd inside a worktree dispatching for a different bead (C1)** | **HARD-REFUSE** | `CWD MISMATCH: you're in <wt-path> for <bead-X>, dispatching for <bead-Y>. Refusing (data-loss risk, C1). cd out or pass explicit path.` |
+| **dispatch target bead is `contract:draft` (not yet promoted)** | **HARD-REFUSE** | `DRAFT BEAD: <id> is contract:draft. Promote first — explore + rewrite full 7-section contract + bd set-state <id> contract=ready.` |
 
 **[adjusted: R5 dedup]** The last check IS the reviewer-specific R5 — it lives here, once. §7's R5 references this row rather than restating it. This is the data-loss class, hence hard-refuse not warn.
 
+**[2026-07-03 addition — draft-bead promotion gate, shipped as a doc-only bridge.]** The `contract:draft`/`contract:ready` HARD-REFUSE row above is **not yet implemented as an `sp run` check** — it exists today only as orchestrator discipline, taught in `using-specialists` (rule #15 + "Draft Beads And The Promotion Gate"), `planning` ("Draft capture mode"), `using-xtrm` (two Trigger Patterns rows), and CLAUDE.md/AGENTS.md (new Dispatch gate row, marked explicitly "bridge — discipline only, not yet hook-enforced"). It reuses the existing `bd state`/`bd set-state` primitive (see the "Existing bd surface inventory" table above — the same row already flagged this primitive as under-used) rather than inventing a new schema field, per this document's own discipline. **What roadmap implementation must still build:** the real `run.ts` pre-dispatch check — `bd state <id> contract`, hard-refuse when `draft` or unset, same code path as the C1 cwd-mismatch check on the row above it. Until that lands, a session that skips the doc-taught discipline has no structural backstop; track this explicitly as unfinished work when Phase 3 (Naming, conventions, environment) or §5.3's implementation lands, not as something already closed by the doc changes.
+
 ### 5.4 `sp chain <bead>` CLI dashboard view
 
 Unifies Opp 3 + Opp 8 data into one display (root beads only, §0 #1):
@@ -886,7 +893,7 @@ Everything below this phase assumes Phase 0 has shipped. Without it, Phase 2 Pas
 | 0.b | Edit `config/specialists/planner.specialist.json` — extend `output_schema` with `recommended_template: enum(<15 formula names> \| 'on-the-run')`; validated at runtime against `bd formula list` (D26 a) | 0.3d | `jq` shows new enum; `sp validate planner` passes |
 | 0.c.1 | **Create canonical `config/skills/planning/SKILL.md` (does not exist today — only `.xtrm/skills/default/planning/SKILL.md` deployed mirror, 531 lines, Phases 1-6).** Add the **7 missing sections** identified by 2026-05-31 audit: (1) Pass-2 `recommended_template` annotation (D26 b core deliverable); (2) chain-template catalog enum with when-to-use briefs (15 templates, refs `chain-templates.md` §3.1-§3.15); (3) contract-creation discipline (D29 — CoT prefill in `<thinking>` tags, 2 worked + 1 anti-example per contract type, critique-before-commit premortem-style); (4) XML semantic structure (D30/Opp 12 — `<change-contract>` for root, `<step-contract>` for step; concrete shape with `<problem>`/`<scope>/<path>`/`<non-goals>`/`<validation>/<criterion>`/`<acceptance>`); (5) memory-recall integration (D27/Opp 11 — `bd memories <keyword>` BEFORE planning, `bd recall <key>` for payloads); (6) SCRUTINY-aware composition (Opp 16 — planner picks tier per scope/risk surface; canon §2.2 auto-escalation table; planner sets floor, reviewer can only escalate); (7) bd dep typed-edges navigation (D28 absorbed — full `--type` vocabulary: validates / informs / discovered-from / parent-child / related / supersedes; worked-template tables). | 1.0d | All 7 sections present + `sp validate planner` reads the new file via `skills.paths` |
 | 0.c.2 | **Cross-repo mirror to `~/dev/xtrm-tools`** — propagate canonical to xtrm-tools update pipeline so `xt update --apply` ships the new content to consumer projects. Requires `npm link` symlink + revendor + 2-pass `xt update --apply` per memory `xtrm-tools-skill-propagation-requires-npm-link-2026-05-23`. Verify identical SHA in ≥2 consumer repos. | 0.5d | `diff -q ~/projects/<repo>/.xtrm/skills/default/planning/SKILL.md ~/dev/specialists/config/skills/planning/SKILL.md` returns identical |
-| 0.d | Verify `/using-specialists-v3` still teaches the manual-chain-discipline + Iron pipeline + manual git per CLAUDE.md rule #9 that holds Phase 1 execution until Opp 4+10 land | 0.1d | Skim §"Orchestration Discipline" + §"Chain Management" sections |
+| 0.d | Verify `/using-specialists` still teaches the manual-chain-discipline + Iron pipeline + manual git per CLAUDE.md rule #9 that holds Phase 1 execution until Opp 4+10 land | 0.1d | Skim §"Orchestration Discipline" + §"Chain Management" sections |
 | 0.e | Smoke: dispatch planner on a vacuum bead (just a title) → confirm `recommended_template` field appears in output_schema-validated output | 0.2d | `sp run planner --bead <test> --json` shows the field; resolved chain pour respects template-declared scrutiny floor |
 
 **Why Phase 0 is bootstrap, not Phase 3:** D26 was originally Phase 3 row 11b because the operator could in principle hand-edit it any time. But Phase 2 Pass-2 (planner annotation of `recommended_template`) **cannot run without D26 shipped**. Putting D26 inside Phase 3 created a circular dependency: planning Phase 2 produces the bd board that includes Phase 3 work that planning Phase 2 needs. The fix is sequencing, not redesign.
@@ -936,18 +943,18 @@ After Phase 0: the operator has the chain templates installed, the planner knows
 |---|---|---|---|
 | 17 | bd auto-stage + hooksPath cases + dep/migration verify | §6 / §0 #6 | **`xtrm-h9hqg`** ✓ done (CLOSED 2026-05-27 per D25) |
 | 18 | Orphan worktree cleanup (B-A4), test excludes (B-A5), osv wrapper (B-A6) | §6 | friction-audit-side (~1d) |
-| 19 | `sp merge` / `sp epic merge` / `sp finalize` rework | §5.5 | **NEW epic `unitAI-lyh1b` filed 2026-05-31 as kj651 child** — supersedes the original "dirty-index diagnostic" scope (D18 runway recalibration) with a fuller rework: structured failure envelopes, conflict-recovery paths, auto-rebase suggestion, soak across 3 repos to remove the `using-specialists-v3` rule #9 prohibition. Decomposition into child beads by planner Pass-1. |
+| 19 | `sp merge` / `sp epic merge` / `sp finalize` rework | §5.5 | **NEW epic `unitAI-lyh1b` filed 2026-05-31 as kj651 child** — supersedes the original "dirty-index diagnostic" scope (D18 runway recalibration) with a fuller rework: structured failure envelopes, conflict-recovery paths, auto-rebase suggestion, soak across 3 repos to remove the `using-specialists` rule #9 prohibition. Decomposition into child beads by planner Pass-1. |
 | 20 | `xt init` auto-runs the bootstrap skill on new repos (per D19) | §6 | xtrm-tools (~0.5d) |
 
 ### Phase 6 — Skills revamp: `using-specialists-v4` as new canonical (~2 days)
 
-The operator-facing skills (`using-specialists-v3`, `using-specialists-auto`) currently teach the pre-roadmap discipline: `--bead` + `--worktree` / `--job` dispatch, manual chain stitching, Iron pipeline as convention, manual git per rule #9. After Phases 1–5 ship, the discipline has fundamentally changed — `--chain <molecule-id>` is the single dispatch verb, `sp chain review/approve/insert` is the composition gate, step-bead conventions are atomic with `kind:step` as truth, R-checks fire at dispatch, the new mandatory rule replaces auto-injection, the chain-template catalog is live. **This is a revamp, not a patch.** v3 was built for the pre-roadmap world; trying to patch it in-place produces contradictory text where every section disagrees with the next. v4 is the clean canonical successor.
+The operator-facing skills (`using-specialists`, `using-specialists-auto`) currently teach the pre-roadmap discipline: `--bead` + `--worktree` / `--job` dispatch, manual chain stitching, Iron pipeline as convention, manual git per rule #9. After Phases 1–5 ship, the discipline has fundamentally changed — `--chain <molecule-id>` is the single dispatch verb, `sp chain review/approve/insert` is the composition gate, step-bead conventions are atomic with `kind:step` as truth, R-checks fire at dispatch, the new mandatory rule replaces auto-injection, the chain-template catalog is live. **This is a revamp, not a patch.** v3 was built for the pre-roadmap world; trying to patch it in-place produces contradictory text where every section disagrees with the next. v4 is the clean canonical successor.
 
 | # | Item | Source | Cost |
 |---|---|---|---|
 | 21 | **Create `config/skills/using-specialists-v4/SKILL.md`** as the new canonical operator-facing skill, taught from scratch around the shipped surfaces: `--chain <molecule-id>` as the only dispatch verb (Opp 10); `sp chain review/approve/insert` as composition gate (Opp 4); `bd mol pour` + 13 chain templates as the resolved-shape source (§13); `kind:step` label-as-truth for step beads (Opp 5/D20); atomic role→edge wiring via `sp chain wire-edges` post-pour helper; R-check behavior per §7 (R3/R6/R7 hard-refuse; R1/R2/R5 retired with `--job`); pull-not-push memory recall via the new mandatory rule (Opp 11/D27) — no more bd-prime / .xtrm/memory.md auto-dump; `sp epic` as decorated reader-only surface (§12); manual git per CLAUDE.md rule #9 remains canonical (sp merge / sp epic merge dropped). Mark frontmatter `status: canonical (post-roadmap)`. | §11.1 D28 | 1d |
 | 22 | **Refresh `config/skills/using-specialists-auto/SKILL.md`** to mirror v4 in the auto-orchestration mode; explicitly call out the new smoke-checkpoint cadence (each phase's checkpoint set is the auto-mode validation gate); teach the "eat-your-own-dogfood as it ships" discipline. | §11.1 D28 | 0.5d |
-| 23 | **Freeze `config/skills/using-specialists-v3/SKILL.md`** as legacy reference. Prepend a frontmatter banner: `status: legacy — superseded by using-specialists-v4 as of <commit>; preserved for historical reference and for any cold-start sessions that haven't migrated`. Do NOT rewrite v3 in place — patching v3 produces contradictory text where new and old surfaces collide. v3 stays as the pre-roadmap snapshot. Inside-v4 forward-looking section ("Future surfaces") notes channels v0 + substrate concepts as *coming, not active* — so operators know what to expect when those land, without v4 itself being gated on them. | §11.1 D28 | 0.5d |
+| 23 | **Freeze `config/skills/using-specialists/SKILL.md`** as legacy reference. Prepend a frontmatter banner: `status: legacy — superseded by using-specialists-v4 as of <commit>; preserved for historical reference and for any cold-start sessions that haven't migrated`. Do NOT rewrite v3 in place — patching v3 produces contradictory text where new and old surfaces collide. v3 stays as the pre-roadmap snapshot. Inside-v4 forward-looking section ("Future surfaces") notes channels v0 + substrate concepts as *coming, not active* — so operators know what to expect when those land, without v4 itself being gated on them. | §11.1 D28 | 0.5d |
 
 **Why v4 is canonical-now, not channels-gated:** the 11 opportunities ship in ~16 days (Phases 0–5); channels v0 and substrate landing are months out and outside this roadmap. Gating v4 on channels would leave the operator with a stale v3 teaching dead surfaces (`--worktree`/`--job`/raw `--bead`) for months. v4 = canonical for what shipped. Channels/substrate-aware surfaces live as a clearly-marked "Future surfaces" section inside v4 (or as a future `using-specialists-v5` when channels v0 ships) — they do not block v4's release.
 
@@ -1191,3 +1198,64 @@ If an operator objects during the announcement window, the objection itself beco
 | R3 follow-on: "each gap blocks cutover instead of becoming one bridged edge" | §A.4 makes objections substrate issues, so blocked-by-gap becomes tracked work, not a stall |
 | Synthesis cross-cutting A: "deferral compound" | §A.3 carrying-cost ledger surfaces the cost of each deferred retirement so the compound cost is visible per-release, not hidden |
 | Synthesis cross-cutting D: "stage acceptance ≠ operator adoption" | §A.3 forensic instrumentation makes adoption measurable — a Stage isn't done when its code ships, it's done when bridges retire because operators stopped using them |
+
+## §B. Durable runtime track and PR/base drift ownership split (added 2026-06-28, specialists-05q)
+
+> Companion epic: **specialists-05q** (this repo). Children: `.1` durable PR/base drift fields, `.2` attention surface, `.3` fetch-and-pin (absorbed into Opp 7 per §3.2), `.4` dead-job audit, `.5` (this roadmap edit), `.6` validation suite. Paired upstream: **`xtrm-lk4on`** (xtrm-tools — git/worktree/PR primitives) and **`xtrm-2zd`** (xtrm/Mercury collaborator doc — container composition: webhooks, cron, bot identity, fork topology, see `~/dev/xtrm/docs/devops/mercury-devops-collaborator.md` §4–7).
+
+### §B.1 Why this section exists
+
+PR/base drift work straddles four owners. Without an explicit split it gravitates to specialists (because that's where operators feel the pain) and the durable home is missed — repeating the §A "permanent bridge" failure mode. This section pins ownership *before* any of the §3.2 work above lands new columns, refusal envelopes, or restart audits, so each child of `specialists-05q` knows whose surface it extends.
+
+### §B.2 Ownership split
+
+| Owner | Surface | What it owns | What it does NOT own |
+|---|---|---|---|
+| **xt (`xtrm-tools`, epic `xtrm-lk4on`)** | git, worktree, PR | git/worktree primitives, `xt end`, branch/PR creation, fetch-base, sibling-branch detection, patch-id equivalence | job-state observability, attention scoring, dead-job declaration |
+| **sp (specialists, epic `specialists-05q`)** | job runtime + observability | job-row PR/base drift fields, `sp ps` / `sp doctor` attention surface, base SHA pin recording, dead-job audit + restart, `--accept-stale-base --reason` UX | the lease itself, the merge slot, the fetch primitive, container composition |
+| **bd / substrate** | leases + slots | `bd merge-slot` lease, container lease (substrate §6.9.6), slot arbitration | telemetry, attention scoring, dispatch ergonomics |
+| **xtrm / Mercury collaborator doc (`~/dev/xtrm/docs/devops/mercury-devops-collaborator.md` §4–7, epic `xtrm-2zd`)** | container composition | webhook topology, cron triggers, bot identity, fork topology, what *constitutes* a container in the collaborator model | per-job lease state, per-job observability, per-job dispatch |
+
+**Reading rule.** When a child of `specialists-05q` (or any future drift bead) needs a primitive that is **not** in the sp column, it does NOT add the primitive to specialists. It (a) opens / extends a bead in the owning epic above, (b) cross-links via `bd dep add … --type tracks`, and (c) consumes the upstream surface read-only. This prevents the "specialists absorbs every adjacent concern" failure mode flagged in §A.1.
+
+### §B.3 Durable migration table
+
+Every row below states **bridge home** (where the data/behavior lives pre-substrate), **substrate target** (where it ends up per the §6.9 substrate model), and **migration shape** (`rename` / `attach` / `retire`) consistent with §11 and §A.2. No row introduces a new `sp lease*` column.
+
+| Concern | Bridge home (today) | Substrate target | Migration shape | Evidence surfaces | Owning epic |
+|---|---|---|---|---|---|
+| **PR drift fields** (PR #, head SHA, base ref, drift status, last-refresh ms) | additive columns on the job-observability row (specialists-side) | `containers.pr_*` (substrate §6.9.6 / §6.9.7) | **rename** (column-for-column; ownership transfers job→container) | `sp ps --json` (jobs with `pr_*` populated), `sp doctor` "PR drift" check, job feed `pr_drift_observed` event | `specialists-05q.1` |
+| **base_sha pin** (pinned SHA + pinned-at ms; refusal envelope fields `base_sha_pinned` / `base_sha_observed` / `commits_behind`) | additive columns on the job-observability row + refusal envelope fields per Opp 7 extension above | `containers.base_sha_pinned` + `containers.base_sha_pinned_at_ms`; refusal envelope unchanged | **rename** (column move job→container; refusal envelope shape stable) | `sp ps --json` (`base_sha_pinned`), `sp doctor` "stale base" check, `--accept-stale-base --reason` audit trail, `xtrm.forensic.v1` `precondition.stale_base.*` | `specialists-05q.3` (absorbed into Opp 7); fetch primitive in `xtrm-lk4on` |
+| **needs-attention view** (per-job attention score: stale base, drifted PR, dead-job suspect, missing lease holder) | derived view in `sp ps` / `sp doctor` reading existing job-observability columns; specialists computes; surfaces JSON + human | derived view in substrate console reading `containers.*`; the *score* is bridge-only — substrate may project a different attention model in §6.9.x | **retire** (specialists-side derived view retires when substrate console ships its own attention surface; specialists keeps the JSON contract while bridges exist per §A.3) | `sp ps --json` (`attention_reasons[]`), `sp doctor --attention`, job feed `attention_raised` / `attention_cleared` events, Prometheus low-cardinality projection (Opp 18) | `specialists-05q.2`; container-side composition in `xtrm-2zd` |
+| **dead-job audit** (restart-time scan: jobs marked running with no pi process, no recent heartbeat, no lease activity → declare `dead` and emit audit event) | restart-time hook in specialists runtime + audit table column on the job-observability row | substrate daemon's container-state reconciler (§6.9.x) absorbs the audit; the column moves job→container as `containers.lifecycle_audit_*` | **attach** then **retire** (today: specialists owns the audit because no daemon; once substrate daemon ships, the audit logic is retired — the column is renamed, the *logic* is dropped) | `sp ps --json` (`lifecycle_state=dead`, `lifecycle_audit_reason`), `sp doctor` "dead jobs" check, audit JSONL artifact, `xtrm.forensic.v1` `lifecycle.dead_declared` | `specialists-05q.4`; substrate daemon in `kj651` follow-up |
+
+**Cross-row invariant.** None of the four rows above introduces a new lease column on the specialists side. The lease holder, when needed, is **read** from the bd / substrate side (today: `bd merge-slot` query; tomorrow: `containers.lease_*`) and **mirrored read-only** onto the attention surface — not stored as authoritative state on the job row. This is the §B.2 ownership rule in schema form.
+
+### §B.4 Evidence surfaces (per §3 CONSTRAINTS)
+
+All child work under `specialists-05q` must name evidence in these surfaces before it can close:
+
+- **`sp ps`** — both human (terminal-aesthetic) and `--json` (machine-consumable) outputs surface the new fields under the existing tokens/cost/state line pattern (per §3.2 Opp 8 / Surface Coverage §v2.0).
+- **`sp doctor`** — gains the four checks named in §B.3 (PR drift, stale base, attention, dead jobs); each check is independently runnable and JSON-emitable.
+- **Job/specialist feed** — gains the additive forensic-event families in §B.3 right column; emitted under `xtrm.forensic.v1` envelopes per Opp 18 contract; persisted to `specialist_forensic_events`.
+- **Prometheus projection** — low-cardinality only per `docs/telemetry/prometheus-projection-contract.md`; never `job_id`/`bead_id` as labels; PR/base/attention/dead-job counters are by `event_family` + `outcome` only.
+
+### §B.5 Bridge cost per §A
+
+Each row in §B.3 carries a §A.3 carrying cost. Owners-of-cutover:
+
+| Bridge | Class (§A.2) | Owner-of-cutover | Retirement gate |
+|---|---|---|---|
+| Specialists-side PR drift columns | Migration bridge | specialists-runtime maintainer | `containers.pr_*` projection passes drift-check in CI; `xtrm.forensic.v1` `pr_drift_observed` event count from specialists-side projection drops below threshold for 7d |
+| Specialists-side base_sha pin columns | Migration bridge | specialists-runtime maintainer | `containers.base_sha_pinned` projection passes; refusal envelope unchanged across the cut |
+| Specialists-side attention view | Throwaway diagnostic | specialists-CLI maintainer | substrate console ships its own attention surface; operator adoption confirmed via `attention_*` event source-family shift |
+| Specialists-side dead-job audit logic | Throwaway diagnostic | specialists-runtime maintainer | substrate daemon ships container-state reconciler; `lifecycle.dead_declared` source-family shifts from specialists to substrate |
+
+Per §A.4 each retirement runs the 7-day announcement window; the column renames are atomic with the substrate landing commit so no row persists with both old and new column names live.
+
+### §B.6 What this section does NOT do
+
+- Does not modify the §3.2 Opp 1 / Opp 7 wording beyond the inline 2026-06-28 ownership / extension notes above.
+- Does not introduce a new opportunity number — fetch-and-pin is absorbed into Opp 7, lease ownership clarifies Opp 1, attention/audit ride existing Opp 8 / `sp doctor` surfaces.
+- Does not commit specialists to any new substrate-side schema; substrate targets are *informational* per §11 migration shape.
+- Does not transfer ownership of git/worktree/PR primitives to specialists; those stay in `xtrm-lk4on` (xt) and `xtrm-2zd` (collaborator doc).

package/docs/design/xt-pi-role-pi-flag-passthrough.md

@@ -0,0 +1,174 @@
+# `xt pi --role` ↔ `pi` runtime flag passthrough
+
+**Context:** `xt pi --role <name>` (xtrm-tools/core PR #362, branch
+`feature/xtrm-yd1p1-pi-role-launcher`) launches a `pi` interactive session in
+a worktree. The current implementation forwards **zero flags** to the pi
+subprocess (`cli/src/utils/worktree-session.ts:373`):
+
+```ts
+const runtimeCmd = runtime === 'claude' ? 'claude' : 'pi';
+const runtimeArgs = runtime === 'claude' ? ['--dangerously-skip-permissions'] : [];
+const launchResult = spawnSync(runtimeCmd, runtimeArgs, { cwd: worktreePath, stdio: 'inherit' });
+```
+
+xt pi's own flags today: `[name]`, `--role <name>`, `--bead <id>`, `--no-attach`.
+Everything `pi` accepts (`pi --help`) is currently unreachable through xt.
+
+This doc rules pi's ~30 CLI flags **passthrough / xt-owned / skip** for `xt pi --role`.
+
+Coordinated with xt-design.3, epic `xtmux-2i5`.
+
+## Recommended shape
+
+**Adopt the `--` passthrough convention.** Anything after `--` on the `xt pi`
+command line is forwarded verbatim as pi argv:
+
+```bash
+xt pi --role chain-coordinator --bead unitAI-2i5 -- --thinking high --no-extensions -e ./local-ext.js
+```
+
+Rationale: pi's flag surface is large, changes independently, and includes
+extension-registered flags xt can't enumerate ahead of time (`--gitnexus-cmd`,
+`--mcp-config`, `--plan`, …). Enumerating each is a maintenance treadmill.
+The `--` convention gives full parity with one code change, zero drift.
+
+Individual xt flags (below) are reserved for pi flags xt itself needs to
+*read or override* — e.g. session naming, which xt derives from the branch.
+
+## Passthrough table
+
+Legend:
+- **passthrough** — forward as-is after `--` (no xt interpretation)
+- **xt-owned** — xt sets or overrides these; user cannot pass them
+- **surface** — worth a first-class xt flag (short-form convenience or
+  interpretation needed before pi launches)
+- **skip** — not meaningful under `xt pi --role`
+
+### Runtime shape
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--provider <name>` | passthrough | Runtime shape. `pi --model provider/id` also handles this, but explicit form works. |
+| `--model <pattern>` | **surface** as `--model` | High-value parity flag. Also match `sp run --model`. Support `:thinking` shorthand pi already parses. |
+| `--api-key <key>` | passthrough | Rare; env vars usually suffice. Don't surface (secret on cmdline). |
+| `--thinking <level>` | **surface** as `--thinking` | Runtime shape and highest-frequency override. Match pi's levels: off/minimal/low/medium/high/xhigh. |
+| `--models <patterns>` | passthrough | Ctrl+P cycling config. Not critical to surface. |
+
+### Session lifecycle
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--continue, -c` | passthrough | Meaningful when re-entering an existing xt worktree; user knows the intent. |
+| `--resume, -r` | passthrough | Same. |
+| `--session <path\|id>` | passthrough | Advanced use. Passthrough sufficient. |
+| `--session-id <id>` | passthrough | Same. |
+| `--fork <path\|id>` | passthrough | Same. |
+| `--session-dir <dir>` | **xt-owned** | xt sets `PI_CODING_AGENT_SESSION_DIR` (or equivalent) to a worktree-scoped path if desired. Don't let users override — breaks session locality. |
+| `--no-session` | passthrough | Ephemeral run inside a persistent worktree is a valid user choice. |
+| `--name, -n <name>` | **xt-owned** | xt derives the display name from `[name]` positional / branch slug. Overriding here fragments observability. |
+
+### Tools / extensions / skills
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--no-tools, -nt` | passthrough | Read-only mode; user choice. |
+| `--no-builtin-tools, -nbt` | passthrough | Same. |
+| `--tools, -t <list>` | passthrough | Allowlist. Same. |
+| `--exclude-tools, -xt <list>` | passthrough | Denylist. Same. |
+| `--extension, -e <path>` | passthrough | Load explicit extension file. Multi-use. Passthrough. |
+| `--no-extensions, -ne` | passthrough | Disable discovery. Passthrough. |
+| `--skill <path>` | passthrough | Same as `-e` for skills. |
+| `--no-skills, -ns` | passthrough | Same. |
+| `--prompt-template <path>` | passthrough | Same. |
+| `--no-prompt-templates, -np` | passthrough | Same. |
+| `--theme <path>` | passthrough | Cosmetic. |
+| `--no-themes` | passthrough | Same. |
+| `--no-context-files, -nc` | passthrough | Disable AGENTS.md/CLAUDE.md load. Legitimate override. |
+
+### System prompt
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--system-prompt <text>` | **xt-owned when `--role` set** | The role's `specialist.prompt.system` is already the system prompt (see `resolveRole` in worktree-session.ts). Passing this again would clobber the role. Reject with an error when `--role` is present; passthrough when it isn't. |
+| `--append-system-prompt <text>` | passthrough | Additive, not clobbering. Safe alongside `--role`. Multi-use. |
+
+### Startup / mode
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--mode <mode>` | passthrough | text/json/rpc — user knows intent. |
+| `--print, -p` | **skip / warn** | Non-interactive mode contradicts `xt pi`'s interactive-tmux design. Warn and refuse (use `sp run` for one-shot). |
+| `--approve, -a` | passthrough | Trust project files this run. |
+| `--no-approve, -na` | passthrough | Same. |
+| `--offline` | passthrough | `PI_OFFLINE=1` alternative. |
+| `--verbose` | passthrough | Debug aid. |
+
+### Introspection / one-shot commands
+
+| pi flag | Verdict | Rationale |
+|---|---|---|
+| `--list-models [search]` | **skip** | Not a session — no worktree needed. User runs `pi --list-models` directly. |
+| `--export <file>` | **skip** | One-shot session-to-HTML. Not an xt workflow. |
+| `--help, -h` | **skip** | xt owns its own `--help`. |
+| `--version, -v` | **skip** | Use `xt pi status` (already exists per pi.ts). |
+
+### Subcommands (`pi install`, `pi update`, `pi list`, `pi config`)
+
+| Subcommand | Verdict | Rationale |
+|---|---|---|
+| `pi install / remove / uninstall / update / list / config` | **skip** | Not launch flows. User runs `pi <cmd>` directly outside a worktree. |
+
+### Extension-registered flags
+
+| Flag | Verdict | Rationale |
+|---|---|---|
+| `--gitnexus-cmd <value>` | passthrough | Registered by extension. Cannot enumerate ahead of time. |
+| `--mcp-config <value>` | passthrough | Same. |
+| Any future extension flag | passthrough | Same. Justifies the `--` convention as primary path. |
+
+## Summary
+
+**Primary path — do this first:**
+Implement `--` passthrough in `launchWorktreeSession`. Every flag pi supports
+(current or future, first-party or extension-registered) becomes reachable
+with zero per-flag maintenance.
+
+**Surface as first-class xt flags** (short-form convenience for the two most
+common overrides):
+- `--model <pattern>` — passes to pi as `--model`
+- `--thinking <level>` — passes to pi as `--thinking`
+
+**xt-owned (reject or override user attempts):**
+- `--session-dir` — xt controls session locality
+- `--name` — xt derives from branch slug
+- `--system-prompt` — clobbers `--role`'s specialist prompt when both set (error)
+
+**Skip / warn:**
+- `--print, -p` — non-interactive contradicts xt pi's design
+- `--list-models`, `--export`, `--help`, `--version`, subcommands — not launch flows
+
+**Everything else** — passthrough via `--`.
+
+## Implementation sketch (~10 lines)
+
+```ts
+// worktree-session.ts, near line 373
+const passthroughIdx = process.argv.indexOf('--');
+const passthroughArgs = passthroughIdx >= 0 ? process.argv.slice(passthroughIdx + 1) : [];
+
+// commander already strips xt-owned flags; combine with surfaced overrides
+const piArgs: string[] = [];
+if (opts.model) piArgs.push('--model', opts.model);
+if (opts.thinking) piArgs.push('--thinking', opts.thinking);
+piArgs.push(...passthroughArgs);
+
+// Guard: reject conflicts before spawn
+if (roleName && passthroughArgs.includes('--system-prompt')) {
+    console.error(kleur.red('\n  ✗ --system-prompt conflicts with --role (role owns the system prompt). Use --append-system-prompt instead.\n'));
+    process.exit(1);
+}
+
+const runtimeArgs = runtime === 'claude' ? ['--dangerously-skip-permissions'] : piArgs;
+```
+
+Decision doc only — no implementation in this PR.

package/docs/skills.md

@@ -36,26 +36,17 @@ User-authored skills belong in the user/active layer used by the local agent set
 
 The package ships the source copies under `config/skills/`. The active `.xtrm/skills/...` files in a project may be refreshed by xtrm-tools.
 
-### `using-specialists-v3`
+### `using-specialists`
 
-Location: `config/skills/using-specialists-v3/SKILL.md`
+Location: `config/skills/using-specialists/SKILL.md`
 
-Canonical orchestration doctrine for substantial tracked work. It covers bead contracts, dependency graph shape, conflict-cluster mapping, advisory passes, reviewer rebuttal, debugger-restitch, E2E smoke phases, monitoring cadence, `sp merge` / `sp epic merge`, and session-end handoff. Use this for multi-step implementation, debugging, reviews, docs sync planning, and specialist orchestration.
+Canonical orchestration doctrine for substantial tracked work. It covers bead contracts, dependency graph shape, conflict-cluster mapping, advisory passes, reviewer rebuttal, debugger-restitch, E2E smoke phases, monitoring cadence, manual publication, and session-end handoff. Use this for multi-step implementation, debugging, reviews, docs sync planning, and specialist orchestration.
 
 ### `using-specialists-auto`
 
 Location: `config/skills/using-specialists-auto/SKILL.md`
 
-Autonomous/offline orchestration overlay. It delegates shared mechanics to `using-specialists-v3` and adds auto-mode pacing, per-item loop shape, escalation triggers, and unattended-run discipline.
-
-### `using-specialists-v2` / `using-specialists`
-
-Locations:
-
-- `config/skills/using-specialists-v2/SKILL.md`
-- `config/skills/using-specialists/SKILL.md`
-
-Older orchestration references retained for compatibility and migration context. Prefer `using-specialists-v3` for current guidance.
+Autonomous/offline orchestration overlay. It delegates shared mechanics to `using-specialists` and adds auto-mode pacing, per-item loop shape, escalation triggers, and unattended-run discipline.
 
 ### `sync-docs`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.18.0",
+  "version": "3.18.2",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "types": "dist/types/lib.d.ts",
@@ -45,7 +45,7 @@
     "lint": "tsc --noEmit",
     "test": "bun --bun vitest run",
     "test:node": "node node_modules/.bin/vitest run",
-    "test:bun": "bun test tests/unit/specialist/observability-sqlite.test.ts tests/unit/specialist/observability-db.test.ts tests/unit/cli/db.test.ts",
+    "test:bun": "bun test tests/unit/specialist/observability-sqlite.test.ts tests/unit/specialist/observability-sqlite-pr-refresh.test.ts tests/unit/specialist/observability-db.test.ts tests/unit/cli/db.test.ts",
     "test:watch": "bun --bun vitest",
     "test:coverage": "bun --bun vitest run --coverage",
     "test:supervisor": "bun --bun vitest run tests/unit/specialist/supervisor.test.ts --no-file-parallelism",