@jaggerxtrm/specialists 3.17.0 → 3.18.1

package/config/skills/specialists-creator/SKILL.md

@@ -5,8 +5,8 @@ description: >
   agent through writing a valid `.specialist.json`, choosing supported models,
   validating against the schema, and avoiding common specialist authoring
   mistakes.
-version: 1.3
-synced_at: 78a7883e
+version: 1.4
+synced_at: fc9168e2
 ---
 
 # Specialist Author Guide
@@ -266,7 +266,7 @@ Avoid vague descriptions like "general purpose assistant" or "helps with code".
 | `mode` | enum | `auto` | `tool` \| `skill` \| `auto` |
 | `timeout_ms` | number | `120000` | ms |
 | `stall_timeout_ms` | number | — | kill if no event for N ms |
-| `interactive` | boolean | `false` | enable multi-turn keep-alive by default |
+| `interactive` | boolean | `false` | enable multi-turn keep-alive by default (also overridable globally via `~/.config/specialists/user.json`) |
 | `response_format` | enum | `text` | `text` \| `json` \| `markdown` |
 | `output_type` | enum | `custom` | `codegen` \| `analysis` \| `review` \| `synthesis` \| `orchestration` \| `workflow` \| `research` \| `custom` |
 | `permission_required` | enum | `READ_ONLY` | see tier table below |
@@ -281,7 +281,8 @@ Avoid vague descriptions like "general purpose assistant" or "helps with code".
 - Run-level overrides still apply:
   - CLI: `--keep-alive` enables, `--no-keep-alive` disables.
   - MCP `start_specialist`: `keep_alive` enables, `no_keep_alive` disables.
-- Effective precedence: explicit disable (`--no-keep-alive` / `no_keep_alive`) → explicit enable (`--keep-alive` / `keep_alive`) → `execution.interactive` → one-shot default.
+- Effective precedence: explicit disable (`--no-keep-alive` / `no_keep_alive`) → explicit enable (`--keep-alive` / `keep_alive`) → merged `execution.interactive` (package / global user.json / repo) → one-shot default.
+- When the operator wants a cross-repo default, prefer `sp edit --global --set <name>.execution.interactive true|false` over forking per-repo specs.
 
 **Permission tiers** — controls the *native* pi tools the specialist gets. The full resolved tool set also includes catalog-defined GitNexus and Serena tools per tier; see [docs/manifest.md](../../../docs/manifest.md) for the complete picture.
 
@@ -651,6 +652,131 @@ This specialist goes STALE the moment `schema.ts` or `runner.ts` is modified aft
 
 ---
 
+## Global User Override Layer (KAN-90/91)
+
+The same per-spec field schema documented above is also exposed at a **global,
+cross-repo layer** since 2026-06-13. Operators do not need to fork a
+`.specialists/user/<name>.specialist.json` per repo just to swap their model or
+opt out of an extension — those changes live once in
+`~/.config/specialists/user.json` and apply everywhere.
+
+### 3-layer field merge
+
+`SpecialistLoader.get()` resolves fields top-down:
+
+1. **Package canonical** — `config/specialists/<name>.specialist.json` shipped
+   in `@jaggerxtrm/specialists`. Most fields are concrete defaults; `model` and
+   `fallback_model` ship as `null` since KAN-90 part 2.
+2. **`~/.config/specialists/user.json`** — operator's global override. Wins
+   over package canonical for the allowlisted user-environment fields.
+3. **`.specialists/user/<name>.specialist.json`** — per-repo override. Wins
+   over global. Can change any field, including ones blocked at the global
+   layer.
+
+The pre-KAN-90 `.specialists/default/<name>.specialist.json` mirror is no
+longer walked (commit `31a6421c`).
+
+### CLI surface
+
+| Command | Effect |
+|---|---|
+| `sp init --global` | Bootstraps `~/.config/specialists/user.json` with null placeholders for every spec; writes `_doc` sentinel + `overrides-guide.md`. Idempotent — preserves existing values, only adds entries for newly-discovered specialists on re-run. |
+| `sp edit --global --set <name>.<dot.path> <value>` | Writes one field in `user.json` (schema-validated). |
+| `sp edit --global --get <name>.<dot.path>` | Reads the current merged value. |
+| `sp doctor --specialists` | Reports `N/M specialists have a model configured`, lists missing models, and surfaces blocked-field overrides applied with warning. |
+| `sp config show <name> --resolved` | Shows the merged spec for one specialist with per-layer attribution. |
+
+The bare positional form (`sp edit --global <name>.field value` without
+`--set`) currently falls through to `$EDITOR` in some environments — prefer
+`--set` in scripts.
+
+### Allowlist mapping (which fields can be set globally)
+
+The constants in `src/specialist/schema.ts` define what the global layer may
+write:
+
+```ts
+OVERRIDE_ALLOWED_EXECUTION_FIELDS = [
+  'model', 'fallback_model', 'fallback_models',
+  'timeout_ms', 'stall_timeout_ms', 'interactive', 'thinking_level',
+  'max_retries', 'prompt_limit_bytes', 'stdout_limit_bytes',
+]
+OVERRIDE_ALLOWED_NESTED_EXECUTION_PATHS = [
+  'extensions.serena', 'extensions.gitnexus',
+]
+OVERRIDE_ALLOWED_STALL_DETECTION_PATHS = ['waiting_auto_close_ms']
+OVERRIDE_ALLOWED_PROMPT_FIELDS = ['system_prompt_mode']
+OVERRIDE_ALLOWED_TOP_FIELDS = ['beads_write_notes', 'notes_mode', 'output_file']
+```
+
+So `sp edit --global --set executor.notes_mode final-only` is allowed; the
+same effect for `permission_required`, `prompt.system`, `mandatory_rules`,
+`capabilities`, `output_schema`, `auto_commit`, `skills.scripts`, or
+`prompt.task_template` is **blocked at the global layer** and must be done
+per-repo in `.specialists/user/<name>.specialist.json`. A blocked field that
+sneaks into `user.json` is applied with a `BlockedFieldWarning` and reported
+by `sp doctor --specialists`.
+
+### Same fields as the per-spec reference
+
+Every field documented above in `## Schema Reference` applies at the global
+layer with the same semantics — only the **scope** changes (one machine vs one
+repo). Examples:
+
+```bash
+# Set notes_mode + output_file globally for a chained pipeline reader
+sp edit --global --set sync-docs.notes_mode final-only
+sp edit --global --set sync-docs.output_file ".specialists/sync-docs-result.md"
+
+# Opt out of Serena MCP injection on a read-only specialist (RAM saver)
+sp edit --global --set overthinker.execution.extensions.serena false
+
+# Set the default keep-alive behavior globally for one specialist
+sp edit --global --set reviewer.execution.interactive false
+
+# Auto-close forgotten waiting sessions after 1h (graceful close first)
+sp edit --global --set reviewer.stall_detection.waiting_auto_close_ms 3600000
+
+# Set system_prompt_mode to replace globally for a bare specialist
+sp edit --global --set my-bare-spec.prompt.system_prompt_mode replace
+
+# Plural fallback chain (KAN-91 Phase 2; walked on transient failures only)
+sp edit --global --set executor.execution.fallback_models \
+  '["openai-codex/gpt-5.5","anthropic/claude-sonnet-4-6"]'
+```
+
+### Preset references (KAN-91 Phase 3)
+
+Both `model` and `fallback_model`/`fallback_models` entries may be a
+`@preset/<name>` reference:
+
+```bash
+sp edit --global --set executor.execution.model @preset/medium
+sp edit --global --set executor.execution.fallback_models '["@preset/cheap"]'
+sp edit --list-presets    # show available preset names in the installed package
+```
+
+Built-in presets typically include `cheap`, `medium`, `power`. Depth cap = 5;
+cycles surface a structured error at dispatch.
+
+### `_doc` sentinel and `overrides-guide.md`
+
+`sp init --global` writes a `_doc` key at the top of `user.json` pointing at
+`./overrides-guide.md`, and (re)generates that guide with the live field
+reference. Any other `_`-prefixed keys are tolerated as comments. Authors of a
+new specialist should run `sp init --global` after release so existing operators
+get a fresh null-placeholder entry on next bootstrap.
+
+### Pitfall — `thinking_level: "off"`
+
+`thinking_level: null` inherits pi's `defaultThinkingLevel` (typically `high`
+on most installs). Forcing `off` on certain thinking-class models (verified:
+Kimi-via-nano-gpt) silently produces an empty assistant text turn after
+multi-tool runs because the model's tool-result-summary phase needs thinking
+budget. Leave it `null` unless you have a documented reason to force a level.
+
+---
+
 ## Built-in Template Variables
 
 These are **always available** in `task_template` — no configuration needed:
@@ -794,6 +920,7 @@ Quality degrades as the context grows — compressed early context causes incons
 
 **Rules when authoring a specialist:**
 - Set `stall_timeout_ms` explicitly for any specialist that may idle between turns (keep-alive/interactive). Without it, a stuck session holds resources indefinitely.
+- If the operator wants forgotten waiting sessions to retire automatically, set `stall_detection.waiting_auto_close_ms` explicitly; keep it unset/0 when human follow-up should remain indefinitely resumable.
 - Use `thinking_level: low` for orchestration/coordinator specialists that emit structured JSON output — thinking tokens cost context budget without improving structured output quality.
 - For research/explorer specialists: bounded scope per session + `handoff_summary` in `output_schema` > one unbounded session.
 - `interactive: true` specialists must define what "done" looks like in their system prompt — otherwise they drift.
@@ -827,6 +954,7 @@ Before finalising a specialist that uses `interactive: true` or is expected to r
 
 ```
 [ ] stall_timeout_ms set (not relying on timeout_ms alone)
+[ ] waiting_auto_close_ms decision made (unset/0 for indefinite waiting, explicit ms for auto-retire)
 [ ] thinking_level set appropriately for the output type
 [ ] output_schema includes handoff_summary or equivalent for rotation
 [ ] system prompt has explicit termination condition ("you are done when...")

package/config/skills/specialists-creator/scripts/audit-spec-uniformity.mjs

@@ -27,7 +27,7 @@ const KNOWN = {
   capabilities: new Set(['required_tools','external_commands','diagnostic_scripts']),
   communication: new Set(['next_specialists','publishes']),
   validation: new Set(['files_to_watch','stale_threshold_days']),
-  stall_detection: new Set(['running_idle_warn_ms','running_idle_kill_ms','waiting_stale_ms','tool_duration_warn_ms']),
+  stall_detection: new Set(['running_idle_warn_ms','running_idle_kill_ms','waiting_stale_ms','waiting_auto_close_ms','tool_duration_warn_ms']),
 };
 
 function unknownKeys(obj, knownSet, path) {

package/config/skills/using-specialists-v3/SKILL.md

@@ -7,7 +7,7 @@ description: >
   security checks, multi-step chains, integration-phase reconciliation,
   debugger-restitch on conflicting chains, pre-dispatch conflict-cluster
   mapping, test-failure-map epics, and questions about specialist workflow.
-version: 3.5
+version: 3.7
 ---
 
 # Using Specialists v3
@@ -215,6 +215,7 @@ Do small deterministic edits directly when scope is already obvious and delegati
 12. Drive routine stages autonomously once task is clear. Escalate only for human judgment, destructive actions, repeated crashes, or reviewer `FAIL`.
 13. The orchestrator NEVER edits code directly. Conflict resolution, even mechanical, goes through a debugger or executor specialist. Manual conflict resolution always escalates to the operator. (Exception: epics that explicitly restructure the specialists themselves — bootstrapping via the specialists they restructure is circular. Such epics are operator-authorized manual-orchestrator-direct work and must say so up-front.)
 14. Before dispatching any chain whose work depends on prior chain output, verify git state per the Git State Precondition section: `git status` clean, HEAD contains prior chain commits, no orphaned worktrees. Stale-base dispatch produces guaranteed debugger-restitch loops downstream.
+15. Never dispatch a specialist against a bead tagged `contract:draft` (`bd state <id> contract` returns `draft` or nothing). Promote it first — see Draft Beads And The Promotion Gate. A draft is a sanctioned capture format, not a shortcut around bead quality.
 
 ## Escalation Matrix
 
@@ -238,6 +239,7 @@ Do small deterministic edits directly when scope is already obvious and delegati
 | `npm publish` | Never | Always |
 | Dependency bump | Auto for security-patch bumps | Major/minor bumps escalate |
 | Config file schema-changing edit | Never | Always |
+| Dispatch against `contract:draft` bead | Never (rule #15) | Always — promote first: explore + rewrite full 7-section contract + `bd set-state <id> contract=ready --reason "..."` |
 
 ## Live Registry And Help
 
@@ -300,6 +302,58 @@ Fix three bad smells fast:
 
 What differs: orchestrator writes contract before dispatch, so specialist does less guessing and more useful work.
 
+## Draft Beads And The Promotion Gate
+
+Full 7-section contracts are expensive to write for an idea you won't touch for weeks. Demanding that rigor for every captured thought is exactly what produces the other failure mode: skipping the bead entirely, or writing a one-liner. There is a third, sanctioned option — but it is a capture format, not an escape hatch.
+
+**Draft state.** Tag a bead `contract:draft` at creation:
+
+```bash
+bd create --title "..." --labels contract:draft --type task --priority 3 \
+  --description "PROBLEM: <2+ real sentences — why this matters, not a title restated>
+SCOPE: <rough guess — 'somewhere in src/auth/, needs investigation' is fine>
+SUCCESS: TBD — needs exploration
+NON_GOALS: TBD — needs exploration
+CONSTRAINTS: TBD — needs exploration
+VALIDATION: TBD — needs exploration
+OUTPUT: TBD — needs exploration"
+```
+
+**No one-liners, ever — draft or not.** A draft still requires a real PROBLEM (why this exists, in prose) and a rough SCOPE. Every other section must be present and say `TBD — needs exploration` explicitly. A bare title, or a description that just restates the title, is never a valid bead — draft state lowers the bar on *completeness*, not on *honesty about what's missing*.
+
+**The promotion gate (rule #15).** No specialist may be dispatched against a `contract:draft` bead. Before dispatch, the orchestrator must:
+
+1. Re-read the bead (`bd show <id>`).
+2. Actually explore — the same Phase 2 evidence-gathering the `planning` skill requires before writing a real contract (`gitnexus_query`/`gitnexus_context`/`gitnexus_impact`, or Serena symbol reads).
+3. Rewrite the bead in place to the full 7-section contract (`bd update <id> --description "..."`), replacing every `TBD` with real content grounded in what was just found.
+4. Flip the state: `bd set-state <id> contract=ready --reason "Explored via <what>; rewrote to full contract"`.
+
+Check before any dispatch: `bd state <id> contract` — if it returns `draft` or nothing, stop and promote. This is a hard refuse (Escalation Matrix), not a warning — a stale draft wastes a full specialist turn on a contract the executor will have to guess at, which is the exact failure this rule exists to prevent.
+
+**Current enforcement is a bridge.** This is orchestrator-discipline-enforced today, not yet a hard `sp run` pre-dispatch check — see `specialists-roadmap.md` §5.3 for the planned real enforcement (same class as the existing C1 cwd-mismatch hard-refuse). Follow the rule anyway; do not treat the absence of a hook as license to dispatch against a draft.
+
+What differs: orchestrator has a sanctioned way to capture backlog ideas cheaply without either over-scoping them immediately or letting them decay into unusable one-liners.
+
+## Bead Title Convention (canonical)
+
+Every bead dispatched to a specialist gets a title in the form:
+
+```text
+<specialist-role>: <concise task description>
+```
+
+Examples: `explorer: map auth refresh path`, `executor: implement token refresh retry`, `reviewer: verify token refresh retry`, `seconder: sanity check token retry diff`, `security-auditor: scan token retry diff`, `test-runner: refresh <epic> failure map`.
+
+Why: `bd list`, `bd ready`, `bd query`, and `sp ps` all show titles inline — a role-prefixed title makes the board scannable at a glance (which role owns which open work) without opening each bead. It also disambiguates same-named chains dispatched to different roles against the same parent (e.g. a `seconder:` and a `security-auditor:` bead both `validates`-linked to the same `executor:` bead).
+
+Rules:
+
+- Prefix with the exact specialist name from `specialists list --full` (`explorer`, `debugger`, `executor`, `reviewer`, `seconder`, `security-auditor`, `test-runner`, `test-engineer`, `obligations-scanner`, `planner`, `overthinker`, `researcher`, `sync-docs`, `changelog-keeper`, `specialists-creator`), not a role synonym.
+- Root task/epic beads that are not themselves dispatched to a single specialist (the umbrella bead a chain is built under) are exempt — keep those descriptive without a role prefix, e.g. `Epic: auth refresh hardening`, `Fix token refresh retry`.
+- Combine with the nesting default above: a role-prefixed title on a `--parent`-nested bead gives both a scannable title and a scannable ID (`bd-x.2` = `seconder: ...`).
+
+What differs: orchestrator can `bd list`/`sp ps` and immediately tell which role owns which open work, instead of opening each bead to find out.
+
 ## SCRUTINY taxonomy (Iron-style)
 
 `SCRUTINY` is a chain-property from canon §2.2, not reviewer input and not a quality tier. Every substantive bead must declare it at creation. It modulates chain structure only; quality stays invariant. New beads without it are invalid unless read-only / none-chain work.
@@ -363,13 +417,15 @@ Core commands:
 - `bd dep <blocker> --blocks <blocked>`: reverse phrasing of the same hard sequencing edge. [source: bd dep --help]
 - `bd dep add <issue> <other> --type <type>`: store a typed relationship. Supported types: `blocks`, `tracks`, `related`, `parent-child`, `discovered-from`, `until`, `caused-by`, `validates`, `relates-to`, `supersedes`. [source: bd dep add --help]
 - `bd dep relate <a> <b>` / `bd dep unrelate <a> <b>`: bidirectional non-blocking `relates_to` link. Use for context, not order. [source: bd dep --help]
-- `bd create --parent <epic-id>`: epic-child edge; auto-names child `.1`, `.2`, … and adds parent ownership. Use for chain members that must live under an epic. [source: bd create --help]
+- `bd create --parent <bead-id>`: hierarchical child edge; auto-names child `<parent>.1`, `<parent>.2`, … and nests recursively — a child's own child becomes `<parent>.1.1`. `<bead-id>` can be an epic, a plain task, or an already-nested child; bd does not restrict `--parent` by issue type (`bd create --help` describes it generically as "Parent issue ID for hierarchical child"). [source: bd create --help]
 - `bd create --deps discovered-from:<id>` or `bd dep add <new> <source> --type discovered-from`: follow-up work discovered from a source bead.
 - `bd duplicate <new> --of <canonical>`: close duplicate issue and point at canonical. Use when two beads describe the same required work.
 - `bd duplicates` / `bd find-duplicates --status open --method ai --json`: find exact or semantic duplicates before dispatching parallel chains.
 - `bd supersede <old> --with <new>` or `bd dep add <new> <old> --type supersedes`: mark a replacement when a better-scoped fix bead replaces an obsolete/abandoned one.
 - `bd dep cycles`, `bd dep tree <id>`, and `bd graph <id>`: sanity-check the execution graph before merge/publication.
 
+**Default to nesting, not loose beads.** When a chain is dispatched to service an existing bead — a top-level task, an epic, or an already-nested child like `bd-x.1` — create the new bead with `bd create --parent <that-bead>` so it inherits the next sequential child ID (`bd-x.1`, or `bd-x.1.1` if the parent is itself a child). This applies uniformly, not only under epics — the common failure mode is orchestrators treating `--parent` as epic-only and defaulting every explorer/executor/reviewer/seconder/security bead spawned mid-chain to a loose top-level bead linked solely by a typed dep. `--parent` (hierarchy/ID) and a typed `bd dep add ... --type <blocks|validates|discovered-from>` edge (semantic relationship) are independent flags — combine both when the relationship needs naming beyond parentage. Only skip `--parent` when the new bead is a genuine standalone sibling concern, not work done on behalf of the bead it services.
+
 Relationship vocabulary for specialist chains:
 
 | Relationship | Reach for it when | Example command |
@@ -377,7 +433,7 @@ Relationship vocabulary for specialist chains:
 | `blocks` | Hard must-happen-before sequencing: planner before executor, implementation before reviewer, restitch before publish. | `bd dep add <impl> <plan> --type blocks` |
 | `tracks` | A local bead mirrors upstream or cross-project work whose status matters but is not owned here. | `bd dep add <local> external:xtrm-tools:<capability> --type tracks` |
 | `related` | Loose topical association when no direction or scheduling effect is intended. Prefer `bd dep relate` for bidirectional relation. | `bd dep add <a> <b> --type related` |
-| `parent-child` | Epic owns child chains. Prefer `bd create --parent <epic>` so IDs and parentage stay canonical. | `bd create --parent <epic> --title "Impl auth retry" ...` |
+| `parent-child` | Any bead spawns tracked child work — epic owning chains, a task spawning its explorer/executor/reviewer, or an already-nested child spawning its own sub-chain. Prefer `bd create --parent <bead>` (not only `<epic>`) so IDs nest and parentage stays canonical instead of drifting into loose top-level beads. | `bd create --parent <bead-id> --title "executor: Impl auth retry" ...` |
 | `discovered-from` | Reviewer, debugger, explorer, or test-runner surfaces new follow-up work from a run. | `bd dep add <follow-up> <reviewer-bead> --type discovered-from` |
 | `until` | Time-bounded or event-bounded precondition that blocks only until a stated condition lands. | `bd dep add <chain> <precondition> --type until` |
 | `caused-by` | Failure bead points to the root-cause bead/cluster that explains it. Makes test-failure-map epics navigable. | `bd dep add <failing-test> <root-cause> --type caused-by` |
@@ -416,7 +472,7 @@ Use each form for a different reason:
 - `discovered-from` for spawned follow-up beads.
 - `caused-by` for failure-to-root-cause attribution.
 - `relates-to` / `bd dep relate` for soft linkage with no schedule effect.
-- `parent-child` / `--parent` for epic ownership and child naming.
+- `parent-child` / `--parent` for hierarchy and child naming — use for any bead spawned to do work on behalf of another bead, not only epic ownership. Nests recursively: a chain dispatched from an already-nested child (e.g. `bd-x.1`) becomes `bd-x.1.1`, not a new loose top-level bead.
 - `supersedes` / `bd supersede` for replacement work; `duplicate` for same-work issues.
 
 Cross-repo consistency: keep this vocabulary aligned with the xtrm-tools triaging skill and sibling triage bead `xtrm-drkk`; both should use the same relationship names when rewiring issue graphs.
@@ -698,7 +754,7 @@ Use when:
 ### Step-by-step
 
 1. **Run the suite once**, save the full log. Do not interpret yet.
-2. **File one mapping bead** (e.g., `test-runner: refresh <epic> failure map`) with contract:
+2. **File one mapping bead** titled per the Bead Title Convention (e.g., `test-runner: refresh <epic> failure map`) with contract:
    - `PROBLEM:` exact command + exit status + raw failure count.
    - `SUCCESS:` cluster table grouping every failure by **likely shared root cause and file scope**, plus recommended fix-chain order.
    - `SCOPE:` the log file path + bounded test files involved.
@@ -736,29 +792,29 @@ Use for one implementation branch.
 bd create --title "Fix token refresh retry" --type task --priority 2 --description "PROBLEM: login and refresh flow have a retry bug when transient token refresh fails before backoff clears stale state. SUCCESS: token refresh retries once, login survives transient failure, and terminal failure stays clear. SCOPE: src/auth/refresh.ts, src/cli/login.ts, tests/unit/auth/refresh.test.ts. NON_GOALS: no auth provider redesign, no storage migration, no UI changes. CONSTRAINTS: preserve token format, keep error text backward-compatible, avoid broad retry changes outside auth flow. VALIDATION: add regression test for fail-then-succeed path and run targeted auth tests. OUTPUT: changed files, test proof, residual risks."
 bd update <task> --claim
 
-# 2. Optional discovery when path is unknown
-bd create --title "Explore auth refresh path" --type task --priority 2 --description "PROBLEM: token refresh retry path is undocumented and likely drifts on failure handling. SUCCESS: evidence-backed plan names exact files, symbols, and risk. SCOPE: src/auth/refresh.ts, src/cli/login.ts, tests/unit/auth/*.test.ts. NON_GOALS: no implementation, no broad audit. CONSTRAINTS: READ_ONLY, cite files/symbols/flows, stay within live repo evidence. VALIDATION: findings cite code path and recommended sequence. OUTPUT: tracked discovery plan with stop condition."
+# 2. Optional discovery when path is unknown — nested under task (bd-x.1) + typed edge for relationship semantics
+bd create --parent <task> --title "explorer: map auth refresh path" --type task --priority 2 --description "PROBLEM: token refresh retry path is undocumented and likely drifts on failure handling. SUCCESS: evidence-backed plan names exact files, symbols, and risk. SCOPE: src/auth/refresh.ts, src/cli/login.ts, tests/unit/auth/*.test.ts. NON_GOALS: no implementation, no broad audit. CONSTRAINTS: READ_ONLY, cite files/symbols/flows, stay within live repo evidence. VALIDATION: findings cite code path and recommended sequence. OUTPUT: tracked discovery plan with stop condition."
 bd dep add <explore> <task> --type discovered-from
 specialists run explorer --bead <explore> --context-depth 3
 specialists result <explore-job>
 
-# 3. Implementation
-bd create --title "Implement token refresh retry" --type task --priority 2 --description "PROBLEM: login fails after transient token refresh error because retry path returns before backoff and clear error state. SUCCESS: retry waits once, preserves session on success, and surfaces final failure clearly. SCOPE: src/auth/refresh.ts, src/cli/login.ts, tests/unit/auth/refresh.test.ts. NON_GOALS: no auth redesign, no storage migration, no UI refresh. CONSTRAINTS: preserve existing token format, keep backward-compatible error text, avoid broad retry changes elsewhere. VALIDATION: add regression test for transient failure then success; run targeted auth tests. OUTPUT: changed files, test evidence, residual risks."
+# 3. Implementation — nested under task (bd-x.2)
+bd create --parent <task> --title "executor: implement token refresh retry" --type task --priority 2 --description "PROBLEM: login fails after transient token refresh error because retry path returns before backoff and clear error state. SUCCESS: retry waits once, preserves session on success, and surfaces final failure clearly. SCOPE: src/auth/refresh.ts, src/cli/login.ts, tests/unit/auth/refresh.test.ts. NON_GOALS: no auth redesign, no storage migration, no UI refresh. CONSTRAINTS: preserve existing token format, keep backward-compatible error text, avoid broad retry changes elsewhere. VALIDATION: add regression test for transient failure then success; run targeted auth tests. OUTPUT: changed files, test evidence, residual risks."
 bd dep add <impl> <explore-or-task> --type blocks
 specialists run executor --bead <impl> --context-depth 3
 specialists result <exec-job>
 
-# 4. Advisory passes when diff smells risky
-bd create --title "Sanity check token retry diff" --type task --priority 2 --description "PROBLEM: auth retry diff has control-flow and state-handling smell that could hide bug. SUCCESS: findings identify concrete simplification or confirm clean shape. SCOPE: executor diff in auth refresh and login flow. NON_GOALS: no edits, no merge gate decision. CONSTRAINTS: READ_ONLY, keep feedback cheap, cite exact lines or symbols. VALIDATION: findings name concrete improvement or say OK. OUTPUT: FINDINGS with severity or OK with caveats."
+# 4. Advisory passes when diff smells risky — nested under impl (bd-x.2.1, bd-x.2.2), since they service impl's diff specifically
+bd create --parent <impl> --title "seconder: sanity check token retry diff" --type task --priority 2 --description "PROBLEM: auth retry diff has control-flow and state-handling smell that could hide bug. SUCCESS: findings identify concrete simplification or confirm clean shape. SCOPE: executor diff in auth refresh and login flow. NON_GOALS: no edits, no merge gate decision. CONSTRAINTS: READ_ONLY, keep feedback cheap, cite exact lines or symbols. VALIDATION: findings name concrete improvement or say OK. OUTPUT: FINDINGS with severity or OK with caveats."
 bd dep add <sanity-bead> <impl> --type validates
 specialists run seconder --bead <sanity-bead> --job <exec-job> --context-depth 3
 
-bd create --title "Security scan token retry diff" --type task --priority 2 --description "PROBLEM: auth refresh code touches secrets and session handling, so security regression is possible. SUCCESS: findings isolate real risk surface or confirm no obvious issue. SCOPE: executor diff in auth, token storage, and login path. NON_GOALS: no edits, no package updates, no destructive scans, no live exploit tests. CONSTRAINTS: LOW permissions, scan-only, recommendations only. VALIDATION: findings cite auth/secrets/input surface and why it matters. OUTPUT: recommendations for executor to apply in separate bead."
+bd create --parent <impl> --title "security-auditor: scan token retry diff" --type task --priority 2 --description "PROBLEM: auth refresh code touches secrets and session handling, so security regression is possible. SUCCESS: findings isolate real risk surface or confirm no obvious issue. SCOPE: executor diff in auth, token storage, and login path. NON_GOALS: no edits, no package updates, no destructive scans, no live exploit tests. CONSTRAINTS: LOW permissions, scan-only, recommendations only. VALIDATION: findings cite auth/secrets/input surface and why it matters. OUTPUT: recommendations for executor to apply in separate bead."
 bd dep add <security-bead> <impl> --type validates
 specialists run security-auditor --bead <security-bead> --job <exec-job> --context-depth 3
 
-# 5. Final review
-bd create --title "Review token refresh retry" --type task --priority 2 --description "PROBLEM: verify executor output against auth retry requirements. SUCCESS: PASS only if retry behavior, error handling, and tests satisfy contract. SCOPE: executor job, diff, acceptance criteria, and target auth files. NON_GOALS: do not rewrite unless explicitly asked. CONSTRAINTS: code-review mindset; findings first; verify security and sanity findings were handled. VALIDATION: inspect targeted checks and regression coverage. OUTPUT: PASS/PARTIAL/FAIL with file/line findings."
+# 5. Final review — nested under impl (bd-x.2.3)
+bd create --parent <impl> --title "reviewer: verify token refresh retry" --type task --priority 2 --description "PROBLEM: verify executor output against auth retry requirements. SUCCESS: PASS only if retry behavior, error handling, and tests satisfy contract. SCOPE: executor job, diff, acceptance criteria, and target auth files. NON_GOALS: do not rewrite unless explicitly asked. CONSTRAINTS: code-review mindset; findings first; verify security and sanity findings were handled. VALIDATION: inspect targeted checks and regression coverage. OUTPUT: PASS/PARTIAL/FAIL with file/line findings."
 bd dep add <review> <impl> --type validates
 specialists run reviewer --bead <review> --job <exec-job> --context-depth 3
 specialists result <review-job>
@@ -789,18 +845,20 @@ Use epic when multiple implementation chains publish together.
 # Epic bead
 bd create --title "Epic: auth refresh hardening" --type epic --priority 2 --description "PROBLEM: login and refresh flow have retry drift, weak error surfacing, and unclear follow-up ownership. SUCCESS: epic closes with stable retry behavior, tests, docs, and clean publish. SCOPE: src/auth/*, src/cli/login.ts, tests/unit/auth/*, docs/auth-refresh.md. NON_GOALS: no auth provider swap, no storage migration, no unrelated session revamp. CONSTRAINTS: preserve token format, keep login compatible, sequence risky fixes before merge, use child beads for parallelizable slices. VALIDATION: targeted tests, seconder or security pass if risk appears, final reviewer PASS. OUTPUT: merged chain set with notes on remaining gaps."
 
-# Planner bead
-bd create --parent <epic> --title "Plan auth refresh split" --type task --priority 2 --description "PROBLEM: epic needs disjoint chains before executor starts. SUCCESS: child beads, dependency edges, and file ownership split are explicit. SCOPE: auth refresh epic area. NON_GOALS: no code changes. CONSTRAINTS: keep chains disjoint, identify security-sensitive slice, name review order. VALIDATION: plan names beads and edges. OUTPUT: parallel-ready plan with risk notes."
+# Planner bead — bd-epic.1
+bd create --parent <epic> --title "planner: plan auth refresh split" --type task --priority 2 --description "PROBLEM: epic needs disjoint chains before executor starts. SUCCESS: child beads, dependency edges, and file ownership split are explicit. SCOPE: auth refresh epic area. NON_GOALS: no code changes. CONSTRAINTS: keep chains disjoint, identify security-sensitive slice, name review order. VALIDATION: plan names beads and edges. OUTPUT: parallel-ready plan with risk notes."
 specialists run planner --bead <plan> --context-depth 3
 
-# Parallel impl beads
-bd create --parent <epic> --title "Impl auth retry" --type task --priority 2 --description "PROBLEM: transient refresh failure breaks login flow. SUCCESS: retry path succeeds after one transient failure and preserves session state. SCOPE: src/auth/refresh.ts, tests/unit/auth/refresh.test.ts. NON_GOALS: no UI changes, no storage migration, no unrelated retry framework edits. CONSTRAINTS: preserve error text, keep backoff bounded, avoid side effects outside auth flow. VALIDATION: regression test for fail-then-succeed path. OUTPUT: code diff, test proof, residual risk list."
-bd create --parent <epic> --title "Impl login handoff" --type task --priority 2 --description "PROBLEM: login CLI does not surface refresh outcome clearly enough for operators. SUCCESS: login shows clear success/failure handoff and no stale token state. SCOPE: src/cli/login.ts, tests/unit/cli/login.test.ts. NON_GOALS: no auth protocol redesign. CONSTRAINTS: preserve CLI flags and error codes, keep output terse. VALIDATION: CLI regression test. OUTPUT: login diff and test evidence."
+# Parallel impl beads — bd-epic.2, bd-epic.3
+bd create --parent <epic> --title "executor: impl auth retry" --type task --priority 2 --description "PROBLEM: transient refresh failure breaks login flow. SUCCESS: retry path succeeds after one transient failure and preserves session state. SCOPE: src/auth/refresh.ts, tests/unit/auth/refresh.test.ts. NON_GOALS: no UI changes, no storage migration, no unrelated retry framework edits. CONSTRAINTS: preserve error text, keep backoff bounded, avoid side effects outside auth flow. VALIDATION: regression test for fail-then-succeed path. OUTPUT: code diff, test proof, residual risk list."
+bd create --parent <epic> --title "executor: impl login handoff" --type task --priority 2 --description "PROBLEM: login CLI does not surface refresh outcome clearly enough for operators. SUCCESS: login shows clear success/failure handoff and no stale token state. SCOPE: src/cli/login.ts, tests/unit/cli/login.test.ts. NON_GOALS: no auth protocol redesign. CONSTRAINTS: preserve CLI flags and error codes, keep output terse. VALIDATION: CLI regression test. OUTPUT: login diff and test evidence."
 
 specialists run executor --bead <impl-a> --context-depth 3
 specialists run executor --bead <impl-b> --context-depth 3
 
-# Per-chain review
+# Per-chain review — nested under each impl (bd-epic.2.1, bd-epic.3.1)
+bd create --parent <impl-a> --title "reviewer: verify auth retry" --type task --priority 2 --description "..."
+bd create --parent <impl-b> --title "reviewer: verify login handoff" --type task --priority 2 --description "..."
 bd dep add <review-a> <impl-a> --type validates
 bd dep add <review-b> <impl-b> --type validates
 specialists run reviewer --bead <review-a> --job <exec-a-job> --context-depth 3
@@ -1250,6 +1308,8 @@ Then choose one action:
 ## What Orchestrator Does Differently Because Of This Skill
 
 - Writes bead contract before dispatch.
+- Nests specialist-dispatch beads under the bead they service via `--parent`, regardless of whether that bead is an epic, a task, or already a nested child — never defaults to loose top-level beads.
+- Titles every specialist-dispatch bead `<specialist-role>: <task>` so `bd list`/`sp ps` are scannable by role at a glance.
 - Chooses edge type before creating chain.
 - Uses specialist role by job shape, not by habit.
 - Keeps fix loops alive with resume, not re-spawn.

package/config/specialists/bare.specialist.json

@@ -3,7 +3,7 @@
     "metadata": {
       "name": "bare",
       "version": "1.0.0",
-      "description": "TEMPLATE — do not dispatch. Copy from the installed @jaggerxtrm/specialists package to .specialists/user/<your-name>.specialist.json and customize for your own task. Fresh-canvas specialist template for non-coding transforms that need zero runtime prompt injection.",
+      "description": "TEMPLATE \u2014 do not dispatch. Copy from the installed @jaggerxtrm/specialists package to .specialists/user/<your-name>.specialist.json and customize for your own task. Fresh-canvas specialist template for non-coding transforms that need zero runtime prompt injection.",
       "category": "template",
       "tags": [
         "template",
@@ -14,8 +14,8 @@
     "execution": {
       "bare": true,
       "mode": "tool",
-      "model": "openai/codex-5",
-      "fallback_model": "google-gemini-cli/gemini-3.1-pro-preview",
+      "model": null,
+      "fallback_model": null,
       "timeout_ms": 120000,
       "max_retries": 0,
       "interactive": false,

package/config/specialists/changelog-drafter.specialist.json

@@ -14,8 +14,8 @@
       ]
     },
     "execution": {
-      "model": "openai-codex/gpt-5.4-mini",
-      "fallback_model": "google-gemini-cli/gemini-3-flash-preview",
+      "model": null,
+      "fallback_model": null,
       "timeout_ms": 120000,
       "stall_timeout_ms": 120000,
       "response_format": "markdown",
@@ -40,7 +40,7 @@
       ]
     },
     "prompt": {
-      "system": "# changelog-drafter — Read-Only Release Drafting\n\nYou synthesize changelog and release-note text only. You do NOT publish releases, bump versions, edit files, create commits, create tags, push, or require a worktree.\n\n## Hard scope\n\nDraft only:\n- changelog section text\n- release metadata summary\n- version-range summary\n\nForbidden:\n- file edits\n- git commit/tag/push\n- build/release side effects\n- worktree assumptions\n\n## Synthesis input\n\nxt reports under `.xtrm/reports/` are curated intent and post-mortem context. Use them to write WHY-grounded entries instead of pure WHAT diffs.\n\nDo NOT crawl `src/`, `docs/`, or run `git log -p`. Use report bundle as primary input.\n\n## Output shape\n\nReturn release-ready markdown plus optional structured metadata in a JSON block if asked by caller. Keep bullets one line each. Default bucket is Changed.\n\n## Section format\n\n```\n## [vX.Y.Z] — YYYY-MM-DD\n\n### Added\n- ...\n\n### Changed\n- ...\n\n### Fixed\n- ...\n```\n\n## Version policy\n\n- Default: patch bump unless caller supplies explicit version or bump type.\n- If neither is specified, STOP and report `BLOCKED: version-not-specified`.\n\n## Forbidden\n\n- editing files\n- publishing steps\n- worktree setup\n- release automation beyond drafting\n- inventing bullets not supported by reports\n",
+      "system": "# changelog-drafter \u2014 Read-Only Release Drafting\n\nYou synthesize changelog and release-note text only. You do NOT publish releases, bump versions, edit files, create commits, create tags, push, or require a worktree.\n\n## Hard scope\n\nDraft only:\n- changelog section text\n- release metadata summary\n- version-range summary\n\nForbidden:\n- file edits\n- git commit/tag/push\n- build/release side effects\n- worktree assumptions\n\n## Synthesis input\n\nxt reports under `.xtrm/reports/` are curated intent and post-mortem context. Use them to write WHY-grounded entries instead of pure WHAT diffs.\n\nDo NOT crawl `src/`, `docs/`, or run `git log -p`. Use report bundle as primary input.\n\n## Output shape\n\nReturn release-ready markdown plus optional structured metadata in a JSON block if asked by caller. Keep bullets one line each. Default bucket is Changed.\n\n## Section format\n\n```\n## [vX.Y.Z] \u2014 YYYY-MM-DD\n\n### Added\n- ...\n\n### Changed\n- ...\n\n### Fixed\n- ...\n```\n\n## Version policy\n\n- Default: patch bump unless caller supplies explicit version or bump type.\n- If neither is specified, STOP and report `BLOCKED: version-not-specified`.\n\n## Forbidden\n\n- editing files\n- publishing steps\n- worktree setup\n- release automation beyond drafting\n- inventing bullets not supported by reports\n",
       "task_template": "$prompt\n\n$reused_worktree_awareness\n\nWorking directory: $cwd\n\n$bead_context\n\nInject xt report bundle first, then draft. Draft only; do not publish or mutate files. Return release-ready text and any metadata needed by xt release prepare. Proceed step-by-step.\n",
       "system_prompt_mode": "append"
     },
@@ -63,6 +63,7 @@
       "stale_threshold_days": 30
     },
     "beads_integration": "auto",
-    "beads_write_notes": false
+    "beads_write_notes": false,
+    "stall_detection": {}
   }
 }

package/config/specialists/changelog-keeper.specialist.json

@@ -3,7 +3,7 @@
     "metadata": {
       "name": "changelog-keeper",
       "version": "3.0.0",
-      "description": "CHANGELOG.md gap-filler. Reconciles [Unreleased] from xt reports + commit subjects in a tag range. Edits CHANGELOG.md only — does not bump version, build, commit, tag, push, or publish. Invoked from /releasing skill when [Unreleased] is empty or sparse.",
+      "description": "CHANGELOG.md gap-filler. Reconciles [Unreleased] from xt reports + commit subjects in a tag range. Edits CHANGELOG.md only \u2014 does not bump version, build, commit, tag, push, or publish. Invoked from /releasing skill when [Unreleased] is empty or sparse.",
       "category": "release",
       "updated": "2026-05-07",
       "tags": [
@@ -13,8 +13,8 @@
       ]
     },
     "execution": {
-      "model": "openai-codex/gpt-5.4-mini",
-      "fallback_model": "google-gemini-cli/gemini-3.1-pro-preview",
+      "model": null,
+      "fallback_model": null,
       "timeout_ms": 0,
       "stall_timeout_ms": 120000,
       "response_format": "markdown",
@@ -37,8 +37,8 @@
       ]
     },
     "prompt": {
-      "system": "# changelog-keeper — [Unreleased] gap-filler\n\nYou edit ONLY `CHANGELOG.md`. You do not bump versions, run builds, commit, tag, push, or publish. The `/releasing` skill owns those steps and invokes you only when its `[Unreleased]` block is empty or sparse and user-facing changes shipped in the target tag range.\n\n## Hard scope (enforced by `changelog-keeper-scope` mandatory rule)\n\nYou edit ONLY:\n- `CHANGELOG.md`\n\nAny other path → STOP and report `BLOCKED: scope-violation`. No exceptions.\n\nForbidden:\n- Editing `package.json`, `package-lock.json`, `dist/**`, source, docs, config.\n- Running `npm run build`, `git add` (other than CHANGELOG.md), `git commit`, `git tag`, `git push`, `npm publish`, `gh release`.\n- `git reset --hard`, `git push --force`, history rewrites.\n\n## Synthesis input\n\nThe bead names the tag range and the missing or sparse session set. xt reports under `.xtrm/reports/` are the curated input — they document intent and post-mortem context for sessions that contributed to the range. Read the relevant report bundle first.\n\nSecondary input: `git log <prev-tag>..HEAD --oneline` to verify reports cover the commits and to spot any user-facing change that has no report.\n\nDo NOT crawl `src/`, `docs/`, or run `git log -p`. Reports are the input — that is why they exist.\n\n## What counts as user-facing\n\nGoes into `[Unreleased]`:\n- new or removed CLI flags, commands, env vars, config keys\n- new or removed services / containers / jobs an operator deploys\n- schema migrations downstream consumers see\n- new or removed API/MCP/REST endpoints, tools, or response fields\n- bug fixes that change observable behavior\n- security-relevant changes\n\nDoes NOT go into `[Unreleased]`:\n- session reports themselves\n- skill/memory edits that only affect agents\n- refactors with byte-identical observable behavior\n- per-issue notes already living in beads\n\n## Section format (Keep-a-Changelog v1.0.0)\n\n```\n## [Unreleased]\n\n### Added\n- one-line user-facing addition (bead-ref)\n\n### Changed\n- one-line user-facing change (bead-ref)\n\n### Fixed\n- one-line user-facing fix (bead-ref)\n```\n\nRules:\n- One line per bullet.\n- Bead refs in parens when helpful: `(unitAI-xxxxx)`.\n- Sections in order Added / Changed / Fixed / Removed / Deprecated / Security. Omit empty sections.\n- Default bucket is **Changed**. `Deprecated` is ONLY for explicit sunset/removal notices.\n- No meta-commentary, no \"Conventional commit mapping\", no reasoning summary in bullets.\n- Wording derives from xt report content, not commit subjects directly. Reports already filter noise.\n\n## Reconciliation rules\n\n- If `[Unreleased]` already has bullets, KEEP them. Add only what is missing from the report set.\n- Do not invent entries that have no grounding in reports or commits.\n- If a commit has no covering report and is plausibly user-facing, add a one-line bullet referencing the commit subject; flag in the output that this entry was synthesized from commit subject (not a report).\n- If a report describes work that is purely internal, do not add a bullet.\n- Preserve the existing `[Unreleased]` heading and any subsections; merge into them.\n\n## Workflow\n\n1. Read the bead. Extract: tag range (prev-tag..HEAD or prev-tag..ref), optional list of sessions known to have skipped session-close-report Step 6.\n2. Run the report helper for the range — see `skills.scripts` (pre-injected). The bundle is bounded; if older reports drop, trust the bundle and continue.\n3. Run `git log <prev-tag>..HEAD --oneline` to enumerate commits.\n4. Read the existing `[Unreleased]` block in `CHANGELOG.md`.\n5. Diff: which user-facing changes from reports + commits are NOT in the existing block?\n6. Edit `CHANGELOG.md` to merge missing entries into the existing `[Unreleased]` sections. Preserve heading shape and prior bullets.\n7. Verify scope: `git status --short` must show ONLY `CHANGELOG.md`. If anything else is dirty, STOP and report `BLOCKED: scope-leak`.\n8. Do NOT commit. Do NOT stage. The `/releasing` skill commits as part of the release commit.\n\n## Output\n\n```\nVERDICT: FILLED | NO_GAPS | BLOCKED\nRANGE: <prev-tag>..<ref>\nADDED_BULLETS: <count>\nSYNTHESIZED_FROM_COMMITS: <count or 0>\nFILES_CHANGED: CHANGELOG.md\nNOTES: <one line about anything notable, e.g. dropped older reports, commits without reports>\n```\n\nOn BLOCKED, name the precondition violated. Operator (or skill) handles repair.",
-      "task_template": "$prompt\n\n$reused_worktree_awareness\n\nWorking directory: $cwd\n\n$bead_context\n\nReport bundle injected first; treat it as the curated input. Read the bead, list the range, read the bundle, read existing [Unreleased], identify gaps, merge missing user-facing bullets into [Unreleased] under the correct Keep-a-Changelog sections. Do NOT bump version, build, commit, tag, push, or publish — the /releasing skill owns those. Edit CHANGELOG.md only.\n",
+      "system": "# changelog-keeper \u2014 [Unreleased] gap-filler\n\nYou edit ONLY `CHANGELOG.md`. You do not bump versions, run builds, commit, tag, push, or publish. The `/releasing` skill owns those steps and invokes you only when its `[Unreleased]` block is empty or sparse and user-facing changes shipped in the target tag range.\n\n## Hard scope (enforced by `changelog-keeper-scope` mandatory rule)\n\nYou edit ONLY:\n- `CHANGELOG.md`\n\nAny other path \u2192 STOP and report `BLOCKED: scope-violation`. No exceptions.\n\nForbidden:\n- Editing `package.json`, `package-lock.json`, `dist/**`, source, docs, config.\n- Running `npm run build`, `git add` (other than CHANGELOG.md), `git commit`, `git tag`, `git push`, `npm publish`, `gh release`.\n- `git reset --hard`, `git push --force`, history rewrites.\n\n## Synthesis input\n\nThe bead names the tag range and the missing or sparse session set. xt reports under `.xtrm/reports/` are the curated input \u2014 they document intent and post-mortem context for sessions that contributed to the range. Read the relevant report bundle first.\n\nSecondary input: `git log <prev-tag>..HEAD --oneline` to verify reports cover the commits and to spot any user-facing change that has no report.\n\nDo NOT crawl `src/`, `docs/`, or run `git log -p`. Reports are the input \u2014 that is why they exist.\n\n## What counts as user-facing\n\nGoes into `[Unreleased]`:\n- new or removed CLI flags, commands, env vars, config keys\n- new or removed services / containers / jobs an operator deploys\n- schema migrations downstream consumers see\n- new or removed API/MCP/REST endpoints, tools, or response fields\n- bug fixes that change observable behavior\n- security-relevant changes\n\nDoes NOT go into `[Unreleased]`:\n- session reports themselves\n- skill/memory edits that only affect agents\n- refactors with byte-identical observable behavior\n- per-issue notes already living in beads\n\n## Section format (Keep-a-Changelog v1.0.0)\n\n```\n## [Unreleased]\n\n### Added\n- one-line user-facing addition (bead-ref)\n\n### Changed\n- one-line user-facing change (bead-ref)\n\n### Fixed\n- one-line user-facing fix (bead-ref)\n```\n\nRules:\n- One line per bullet.\n- Bead refs in parens when helpful: `(unitAI-xxxxx)`.\n- Sections in order Added / Changed / Fixed / Removed / Deprecated / Security. Omit empty sections.\n- Default bucket is **Changed**. `Deprecated` is ONLY for explicit sunset/removal notices.\n- No meta-commentary, no \"Conventional commit mapping\", no reasoning summary in bullets.\n- Wording derives from xt report content, not commit subjects directly. Reports already filter noise.\n\n## Reconciliation rules\n\n- If `[Unreleased]` already has bullets, KEEP them. Add only what is missing from the report set.\n- Do not invent entries that have no grounding in reports or commits.\n- If a commit has no covering report and is plausibly user-facing, add a one-line bullet referencing the commit subject; flag in the output that this entry was synthesized from commit subject (not a report).\n- If a report describes work that is purely internal, do not add a bullet.\n- Preserve the existing `[Unreleased]` heading and any subsections; merge into them.\n\n## Workflow\n\n1. Read the bead. Extract: tag range (prev-tag..HEAD or prev-tag..ref), optional list of sessions known to have skipped session-close-report Step 6.\n2. Run the report helper for the range \u2014 see `skills.scripts` (pre-injected). The bundle is bounded; if older reports drop, trust the bundle and continue.\n3. Run `git log <prev-tag>..HEAD --oneline` to enumerate commits.\n4. Read the existing `[Unreleased]` block in `CHANGELOG.md`.\n5. Diff: which user-facing changes from reports + commits are NOT in the existing block?\n6. Edit `CHANGELOG.md` to merge missing entries into the existing `[Unreleased]` sections. Preserve heading shape and prior bullets.\n7. Verify scope: `git status --short` must show ONLY `CHANGELOG.md`. If anything else is dirty, STOP and report `BLOCKED: scope-leak`.\n8. Do NOT commit. Do NOT stage. The `/releasing` skill commits as part of the release commit.\n\n## Output\n\n```\nVERDICT: FILLED | NO_GAPS | BLOCKED\nRANGE: <prev-tag>..<ref>\nADDED_BULLETS: <count>\nSYNTHESIZED_FROM_COMMITS: <count or 0>\nFILES_CHANGED: CHANGELOG.md\nNOTES: <one line about anything notable, e.g. dropped older reports, commits without reports>\n```\n\nOn BLOCKED, name the precondition violated. Operator (or skill) handles repair.",
+      "task_template": "$prompt\n\n$reused_worktree_awareness\n\nWorking directory: $cwd\n\n$bead_context\n\nReport bundle injected first; treat it as the curated input. Read the bead, list the range, read the bundle, read existing [Unreleased], identify gaps, merge missing user-facing bullets into [Unreleased] under the correct Keep-a-Changelog sections. Do NOT bump version, build, commit, tag, push, or publish \u2014 the /releasing skill owns those. Edit CHANGELOG.md only.\n",
       "system_prompt_mode": "append"
     },
     "skills": {
@@ -72,6 +72,7 @@
       "stale_threshold_days": 30
     },
     "beads_integration": "auto",
-    "beads_write_notes": true
+    "beads_write_notes": true,
+    "stall_detection": {}
   }
 }

package/config/specialists/debugger.specialist.json

@@ -20,8 +20,8 @@
     },
     "execution": {
       "mode": "tool",
-      "model": "openai-codex/gpt-5.3-codex",
-      "fallback_model": "openai-codex/gpt-5.4",
+      "model": null,
+      "fallback_model": null,
       "timeout_ms": 0,
       "stall_timeout_ms": 120000,
       "interactive": true,

package/config/specialists/executor.specialist.json

@@ -14,8 +14,8 @@
       ]
     },
     "execution": {
-      "model": "openai-codex/gpt-5.4-mini",
-      "fallback_model": "google-gemini-cli/gemini-3.1-pro-preview",
+      "model": null,
+      "fallback_model": null,
       "timeout_ms": 0,
       "stall_timeout_ms": 120000,
       "response_format": "markdown",

package/config/specialists/explorer.specialist.json

@@ -15,8 +15,8 @@
     },
     "execution": {
       "mode": "tool",
-      "model": "nano-gpt/zai-org/glm-5",
-      "fallback_model": "google-gemini-cli/gemini-3-flash-preview",
+      "model": null,
+      "fallback_model": null,
       "timeout_ms": 0,
       "stall_timeout_ms": 120000,
       "response_format": "markdown",
@@ -48,8 +48,8 @@
       }
     },
     "prompt": {
-      "system": "You are codebase explorer specialist with GitNexus knowledge graph access.\nJob: analyze codebases deep, give clear structured answers about\narchitecture, patterns, code organization.\n\n## Primary Approach — GitNexus (use when indexed)\n\nStart here for any codebase. GitNexus gives call chains, execution flows,\nsymbol relationships that grep/find cannot. Prefer MCP tools; if not loaded\nin the harness, fall back to the `npx gitnexus` CLI (equivalent evidence —\nreviewer accepts either form):\n\n- MCP `gitnexus_query({query})` ↔ CLI `npx gitnexus query \"<text>\"`\n- MCP `gitnexus_context({name})` ↔ CLI `npx gitnexus context <name>`\n- MCP `gitnexus_impact({target})` ↔ CLI `npx gitnexus impact <target>`\n- MCP resources (`gitnexus://repo/{name}/clusters`, `/process/{name}`) have no CLI equivalent — skip if MCP unavailable.\n\n1. Read `gitnexus://repo/{name}/context`\n   → Stats, staleness check. If stale, fall back to bash.\n2. `gitnexus_query({query: \"<what you want to understand>\"})`\n   → Find execution flows and related symbols grouped by process.\n3. `gitnexus_context({name: \"<symbol>\"})`\n   → 360-degree view: callers, callees, processes symbol participates in.\n4. Read `gitnexus://repo/{name}/clusters`\n   → Functional areas with cohesion scores (architectural map).\n5. Read `gitnexus://repo/{name}/process/{name}`\n   → Step-by-step execution trace for specific flow.\n\n## Fallback Approach — Bash/Grep\n\nUse when GitNexus unavailable or index stale:\n- `find`, `tree`, `grep -r` for structure discovery\n- Read key files: package.json, tsconfig.json, README.md, src/index.ts\n- Trace imports manually for layer dependencies\n\n## Output Format\n\nAlways provide:\n1. **Summary** (2-3 sentences)\n2. **Architecture overview** — layers, modules, key patterns\n3. **Execution flows** (GitNexus) or **Directory map** (fallback)\n4. **Key symbols** — entry points, central hubs, important interfaces\n5. **Answer** — direct response to specific question\n\nSTRICT CONSTRAINTS:\n- MUST NOT edit, write, or modify any files.\n- Read-only: bash (read-only commands), grep, find, ls, GitNexus tools only.\n- If find something worth fixing, REPORT it — do not fix.\nEFFICIENCY RULE: Stop using tools and write final answer after at most 12 tool calls.",
-      "task_template": "Explore the codebase and answer the following question:\n\n$prompt\n\nWorking directory: $cwd\n\n## Required exploration steps (MCP form shown; if MCP tools not loaded, use `npx gitnexus query|context` CLI — same evidence):\n1. `gitnexus_query({query: \"<your question>\"})` or `npx gitnexus query \"<question>\"` — find execution flows and symbols\n2. `gitnexus_context({name: \"<key symbol>\"})` or `npx gitnexus context <symbol>` — callers, callees, process participation\n3. Read `gitnexus://repo/{name}/clusters` — architectural map\n4. Read `gitnexus://repo/{name}/process/{name}` — step-by-step execution traces\n5. Read source files ONLY for details that GitNexus didn't cover\n\nDo NOT skip to grep/find — GitNexus is your primary navigation tool.\n",
+      "system": "You are codebase explorer specialist with GitNexus knowledge graph access.\nJob: analyze codebases deep, give clear structured answers about\narchitecture, patterns, code organization.\n\n## Primary Approach \u2014 GitNexus (use when indexed)\n\nStart here for any codebase. GitNexus gives call chains, execution flows,\nsymbol relationships that grep/find cannot. Prefer MCP tools; if not loaded\nin the harness, fall back to the `npx gitnexus` CLI (equivalent evidence \u2014\nreviewer accepts either form):\n\n- MCP `gitnexus_query({query})` \u2194 CLI `npx gitnexus query \"<text>\"`\n- MCP `gitnexus_context({name})` \u2194 CLI `npx gitnexus context <name>`\n- MCP `gitnexus_impact({target})` \u2194 CLI `npx gitnexus impact <target>`\n- MCP resources (`gitnexus://repo/{name}/clusters`, `/process/{name}`) have no CLI equivalent \u2014 skip if MCP unavailable.\n\n1. Read `gitnexus://repo/{name}/context`\n   \u2192 Stats, staleness check. If stale, fall back to bash.\n2. `gitnexus_query({query: \"<what you want to understand>\"})`\n   \u2192 Find execution flows and related symbols grouped by process.\n3. `gitnexus_context({name: \"<symbol>\"})`\n   \u2192 360-degree view: callers, callees, processes symbol participates in.\n4. Read `gitnexus://repo/{name}/clusters`\n   \u2192 Functional areas with cohesion scores (architectural map).\n5. Read `gitnexus://repo/{name}/process/{name}`\n   \u2192 Step-by-step execution trace for specific flow.\n\n## Fallback Approach \u2014 Bash/Grep\n\nUse when GitNexus unavailable or index stale:\n- `find`, `tree`, `grep -r` for structure discovery\n- Read key files: package.json, tsconfig.json, README.md, src/index.ts\n- Trace imports manually for layer dependencies\n\n## Output Format\n\nAlways provide:\n1. **Summary** (2-3 sentences)\n2. **Architecture overview** \u2014 layers, modules, key patterns\n3. **Execution flows** (GitNexus) or **Directory map** (fallback)\n4. **Key symbols** \u2014 entry points, central hubs, important interfaces\n5. **Answer** \u2014 direct response to specific question\n\nSTRICT CONSTRAINTS:\n- MUST NOT edit, write, or modify any files.\n- Read-only: bash (read-only commands), grep, find, ls, GitNexus tools only.\n- If find something worth fixing, REPORT it \u2014 do not fix.\nEFFICIENCY RULE: Stop using tools and write final answer after at most 12 tool calls.",
+      "task_template": "Explore the codebase and answer the following question:\n\n$prompt\n\nWorking directory: $cwd\n\n## Required exploration steps (MCP form shown; if MCP tools not loaded, use `npx gitnexus query|context` CLI \u2014 same evidence):\n1. `gitnexus_query({query: \"<your question>\"})` or `npx gitnexus query \"<question>\"` \u2014 find execution flows and symbols\n2. `gitnexus_context({name: \"<key symbol>\"})` or `npx gitnexus context <symbol>` \u2014 callers, callees, process participation\n3. Read `gitnexus://repo/{name}/clusters` \u2014 architectural map\n4. Read `gitnexus://repo/{name}/process/{name}` \u2014 step-by-step execution traces\n5. Read source files ONLY for details that GitNexus didn't cover\n\nDo NOT skip to grep/find \u2014 GitNexus is your primary navigation tool.\n",
       "output_schema": {
         "type": "object",
         "properties": {

package/config/specialists/memory-processor.specialist.json

@@ -17,8 +17,8 @@
     },
     "execution": {
       "mode": "tool",
-      "model": "openai-codex/gpt-5.3-codex",
-      "fallback_model": "google-gemini-cli/gemini-3.1-pro-preview",
+      "model": null,
+      "fallback_model": null,
       "timeout_ms": 0,
       "stall_timeout_ms": 120000,
       "response_format": "markdown",
@@ -30,7 +30,7 @@
       "bare": false
     },
     "prompt": {
-      "system": "You are a memory curator for a software project. You synthesize the project's accumulated bd memories and current code state into a clean, dense context document at .xtrm/memory.md — written for a fresh agent who has never seen this codebase.\n\nFollow the `memory-audit-transaction` skill exactly. It defines the chunked file-backed ledger workflow that scales to any N memories without exhausting context.\n\n## Hard rules (non-negotiable)\n\n- **Per-entry decisions never go in chat.** Append every classification to `.tmp/memory-audit/decisions.jsonl` as a JSON line. Chat output per chunk is one line: `chunk N: X classified (Current=a, Stale=b, Contradicted=c, Redundant=d, Skipped=e)`.\n- **Chunk size is 20-30 memories per turn.** Never classify more than 30 entries in one model turn. Checkpoint to disk between chunks.\n- **Completeness gate before .xtrm/memory.md write.** Before Phase 8, `wc -l .tmp/memory-audit/keys.txt` must equal `wc -l .tmp/memory-audit/decisions.jsonl`. If not, STOP and report the gap. Never default missing rows to Current.\n- **Conservative pruning.** When in doubt about a memory's status, write `status=Skipped` with `evidence=[\"unverifiable: <reason>\"]`. Never default to Current without evidence; never delete without evidence.\n- **No destructive git ever.** Forbidden: `git pull`, `git push`, `git reset --hard`, `git rebase`, `git checkout HEAD --`, force-push, any history rewrite. Memory audit is local read + bd forget + single-file write only.\n- **Hash-guarded prune.** Each `bd forget` re-verifies sha256(bd recall) against the hash captured at classification time. Mismatches are skipped and logged, not silently dropped.\n\n## Workflow summary\n\nPhases 1-9 are defined in `config/skills/memory-audit-transaction/SKILL.md` (injected). Adhere to it line-by-line:\n\n1. Read `.xtrm/memory.md` (existing)\n2. Read targeted sections of latest 3 session reports\n3. Bulk-export all memories to `.tmp/memory-audit/memories.txt` via ONE shell call\n4. Single-pass project state read (git log -30, CLAUDE.md head, README.md head)\n5. Chunked classification, decisions appended to `.tmp/memory-audit/decisions.jsonl`\n6. Completeness validator (HARD GATE)\n7. Atomic prune with hash guard (single batch loop, output goes to `.tmp/memory-audit/apply-log.txt`)\n8. Write `.xtrm/memory.md` filtered from Current rows\n9. Final report: counts + artifact paths, NOT per-entry text\n\n## Output format\n\nFinal chat output is the Memory Processor Report defined in the skill Phase 9. Counts only. Per-entry data lives in artifacts:\n\n- `.tmp/memory-audit/decisions.jsonl` — every classification with evidence\n- `.tmp/memory-audit/apply-log.txt` — every applied/skipped prune\n- `.tmp/memory-audit/backup/<key>.txt` — per-key backup before delete\n",
+      "system": "You are a memory curator for a software project. You synthesize the project's accumulated bd memories and current code state into a clean, dense context document at .xtrm/memory.md \u2014 written for a fresh agent who has never seen this codebase.\n\nFollow the `memory-audit-transaction` skill exactly. It defines the chunked file-backed ledger workflow that scales to any N memories without exhausting context.\n\n## Hard rules (non-negotiable)\n\n- **Per-entry decisions never go in chat.** Append every classification to `.tmp/memory-audit/decisions.jsonl` as a JSON line. Chat output per chunk is one line: `chunk N: X classified (Current=a, Stale=b, Contradicted=c, Redundant=d, Skipped=e)`.\n- **Chunk size is 20-30 memories per turn.** Never classify more than 30 entries in one model turn. Checkpoint to disk between chunks.\n- **Completeness gate before .xtrm/memory.md write.** Before Phase 8, `wc -l .tmp/memory-audit/keys.txt` must equal `wc -l .tmp/memory-audit/decisions.jsonl`. If not, STOP and report the gap. Never default missing rows to Current.\n- **Conservative pruning.** When in doubt about a memory's status, write `status=Skipped` with `evidence=[\"unverifiable: <reason>\"]`. Never default to Current without evidence; never delete without evidence.\n- **No destructive git ever.** Forbidden: `git pull`, `git push`, `git reset --hard`, `git rebase`, `git checkout HEAD --`, force-push, any history rewrite. Memory audit is local read + bd forget + single-file write only.\n- **Hash-guarded prune.** Each `bd forget` re-verifies sha256(bd recall) against the hash captured at classification time. Mismatches are skipped and logged, not silently dropped.\n\n## Workflow summary\n\nPhases 1-9 are defined in `config/skills/memory-audit-transaction/SKILL.md` (injected). Adhere to it line-by-line:\n\n1. Read `.xtrm/memory.md` (existing)\n2. Read targeted sections of latest 3 session reports\n3. Bulk-export all memories to `.tmp/memory-audit/memories.txt` via ONE shell call\n4. Single-pass project state read (git log -30, CLAUDE.md head, README.md head)\n5. Chunked classification, decisions appended to `.tmp/memory-audit/decisions.jsonl`\n6. Completeness validator (HARD GATE)\n7. Atomic prune with hash guard (single batch loop, output goes to `.tmp/memory-audit/apply-log.txt`)\n8. Write `.xtrm/memory.md` filtered from Current rows\n9. Final report: counts + artifact paths, NOT per-entry text\n\n## Output format\n\nFinal chat output is the Memory Processor Report defined in the skill Phase 9. Counts only. Per-entry data lives in artifacts:\n\n- `.tmp/memory-audit/decisions.jsonl` \u2014 every classification with evidence\n- `.tmp/memory-audit/apply-log.txt` \u2014 every applied/skipped prune\n- `.tmp/memory-audit/backup/<key>.txt` \u2014 per-key backup before delete\n",
       "task_template": "Run the memory processor for this project.\n\nWorking directory: $cwd\n$prompt\n\n$bead_context\n\nFollow the `memory-audit-transaction` skill (injected) exactly. The skill replaces the legacy linear workflow with chunked file-backed ledger that scales past 500+ memories.\n\nHard constraints reminder:\n- Chunks of 20-30 per turn, decisions to `.tmp/memory-audit/decisions.jsonl` not chat\n- Phase 6 completeness gate is non-negotiable; do NOT default missing rows to Current\n- Phase 7 prune is one batch loop with hash-guard, not inline `bd forget` per decision\n- No destructive git commands\n\nProceed step-by-step.\n",
       "system_prompt_mode": "append"
     },