@jaggerxtrm/specialists 3.17.0 → 3.18.1

package/docs/upgrade-notes/kan-91-expanded-overrides.md

@@ -0,0 +1,261 @@
+# KAN-91 / unitAI-gp7nq — Expanded global overrides
+
+For the current canonical reference, see [`docs/overrides-guide.md`](../overrides-guide.md). This page documents the KAN-91 delta only.
+
+KAN-91 expands the KAN-90 global `user.json` layer from model-only tuning into a per-user environment override surface. The new surface adds user-owned knobs for prompt composition, extension injection, notes/output behavior, prompt/stdout limits, fallback model chains, and `@preset/<name>` references. Specialist identity and safety fields remain blocked.
+
+## Overview
+
+This expansion adds:
+
+- Six allowlisted user-environment fields: `prompt.system_prompt_mode`, `execution.extensions.serena`, `execution.extensions.gitnexus`, `notes_mode`, `output_file`, `execution.prompt_limit_bytes`, and `execution.stdout_limit_bytes`.
+- Follow-up fields now also exposed in the live global layer: `execution.interactive` and `stall_detection.waiting_auto_close_ms`.
+- Fallback chains via `execution.fallback_models` while keeping legacy `execution.fallback_model`.
+- Preset references like `@preset/cheap` for model and fallback entries.
+- A top-level `_doc` sentinel in generated `user.json` pointing back to this guide. Keys starting with `_` are metadata, not specialist names.
+
+The examples below are delta snippets to add inside an existing specialist entry from `sp init --global`; they are not complete standalone `user.json` files. Keep the surrounding generated entry shape, including its `execution`, `prompt`, `stall_detection`, `beads_write_notes`, and `skills` keys, and change only the highlighted field.
+
+## Per-field reference
+
+### `prompt.system_prompt_mode`
+
+- Type: `"append" | "replace" | null`
+- Default semantics: `null` inherits the shipped specialist value, normally `append`.
+- Example:
+
+```json
+{
+  "executor": {
+    "prompt": { "system_prompt_mode": "replace" }
+  }
+}
+```
+
+Pitfall: this controls composition mode only. It does not let `user.json` replace `prompt.system`; prompt content remains blocked.
+
+### `execution.extensions.serena`
+
+- Type: `boolean | null`
+- Default semantics: `null` inherits the shipped extension setting.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "extensions": { "serena": false } }
+  }
+}
+```
+
+Pitfall: extension overrides are per-key overlays. Setting `serena: false` does not change `gitnexus`.
+
+### `execution.extensions.gitnexus`
+
+- Type: `boolean | null`
+- Default semantics: `null` inherits the shipped extension setting.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "extensions": { "gitnexus": false } }
+  }
+}
+```
+
+Pitfall: disabling GitNexus removes graph tooling from that specialist run. Use only when project indexing is unavailable or too expensive.
+
+### `notes_mode`
+
+- Type: `"full-trail" | "final-only" | null`
+- Default semantics: `null` inherits the specialist default. `full-trail` appends turn handoffs; `final-only` keeps final handoff only.
+- Example:
+
+```json
+{
+  "researcher": {
+    "notes_mode": "final-only"
+  }
+}
+```
+
+Pitfall: `final-only` is quieter but removes intermediate turn notes from bead history.
+
+### `output_file`
+
+- Type: `string | null`
+- Default semantics: `null` inherits the specialist default or no file mirror.
+- Example:
+
+```json
+{
+  "researcher": {
+    "output_file": "./.specialists/researcher-result.md"
+  }
+}
+```
+
+Pitfall: paths are not expanded by the loader. `~/result.md` stays literal and is not converted to your home directory.
+
+### `execution.prompt_limit_bytes`
+
+- Type: `number | null`
+- Default semantics: `null` inherits the shipped prompt input limit.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "prompt_limit_bytes": 8388608 }
+  }
+}
+```
+
+Pitfall: raising this limit can increase token spend or provider rejection risk.
+
+### `execution.stdout_limit_bytes`
+
+- Type: `number | null`
+- Default semantics: `null` inherits the shipped stdout capture limit.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "stdout_limit_bytes": 67108864 }
+  }
+}
+```
+
+Pitfall: raising this limit can produce very large logs and result files.
+
+### `execution.fallback_model`
+
+- Type: `string | null`
+- Default semantics: legacy single fallback. `null` means no singular fallback from this layer.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": { "fallback_model": "openai-codex/gpt-5.4-mini" }
+  }
+}
+```
+
+Pitfall: if `fallback_models` is also set, plural wins.
+
+### `execution.fallback_models`
+
+- Type: `string[] | null`
+- Default semantics: `null` inherits lower layers. Array values replace the singular fallback chain for that layer.
+- Example:
+
+```json
+{
+  "executor": {
+    "execution": {
+      "fallback_models": [
+        "openai-codex/gpt-5.4-mini",
+        "nano-gpt/moonshotai/kimi-k2.5"
+      ]
+    }
+  }
+}
+```
+
+Pitfall: fallback walk is transient-failure-only. Auth failures, prompt rejections, and other logical failures do not advance to the next provider.
+
+## Preset reference syntax
+
+Write a preset reference as an exact string inside the existing generated specialist entry:
+
+```json
+{
+  "executor": {
+    "execution": {
+      "model": "@preset/cheap",
+      "fallback_models": ["@preset/medium", "openai-codex/gpt-5.4-mini"]
+    }
+  }
+}
+```
+
+Package presets live in `config/presets.json`. Current shipped names are `cheap`, `medium`, and `power`. User-defined preset files and repo-level preset shadowing are not part of KAN-91.
+
+Preset references resolve transitively with depth cap 4. Cycles raise `SpecialistPresetCycleError` with the visited preset list. Unknown names raise `SpecialistPresetNotFoundError` and list known presets. Malformed preset payloads raise `SpecialistPresetTypeError` before the loader writes the resolved value into the merged specialist spec.
+
+Only allowlisted override fields accept preset references. A blocked field such as `prompt.system` cannot smuggle a preset reference through `user.json`.
+
+## Fallback chain semantics
+
+Runtime model order is:
+
+1. Primary `execution.model`.
+2. `execution.fallback_models` entries when plural is present.
+3. Legacy `execution.fallback_model` only when plural is absent.
+
+Plural wins over singular in the same layer. A plural override in a higher layer replaces the lower layer's singular fallback chain because mixing singular and plural fallbacks across layers is ambiguous.
+
+Each fallback step emits `fallback_step` telemetry with specialist, attempt number, tried model, error class, and whether the step was terminal. Chain walk only happens for transient failures such as rate limits, network errors, timeouts, and 5xx-class provider failures.
+
+## Migration
+
+Existing `~/.config/specialists/user.json` files auto-extend on the next `sp init --global` run. Existing values are preserved. Missing fields are filled with `null` defaults, and `_doc` is added if absent.
+
+Generated files stay strict JSON. `sp init --global` does not write comments; it writes `_doc` as a top-level metadata key instead.
+
+## Complete example (validates against `GlobalUserConfigSchema`)
+
+This is a complete `user.json` shape, not a delta snippet. It keeps every required key from `sp init --global` and exercises `system_prompt_mode`, fallback chains, extension opt-out, and `@preset/<name>` references.
+
+```json
+{
+  "_doc": "See docs/upgrade-notes/kan-91-expanded-overrides.md for expanded override fields.",
+  "executor": {
+    "execution": {
+      "model": "@preset/cheap",
+      "fallback_model": null,
+      "fallback_models": [
+        "@preset/medium",
+        "openai-codex/gpt-5.4-mini"
+      ],
+      "timeout_ms": null,
+      "stall_timeout_ms": null,
+      "interactive": true,
+      "thinking_level": null,
+      "max_retries": null,
+      "prompt_limit_bytes": 8388608,
+      "stdout_limit_bytes": null,
+      "extensions": {
+        "serena": false,
+        "gitnexus": null
+      }
+    },
+    "prompt": {
+      "system_prompt_mode": "replace"
+    },
+    "stall_detection": {
+      "waiting_auto_close_ms": 3600000
+    },
+    "beads_write_notes": null,
+    "notes_mode": "final-only",
+    "output_file": null,
+    "skills": {
+      "paths": []
+    }
+  }
+}
+```
+
+## Cross-references
+
+- Origin doc: `docs/upgrade-notes/kan-90-global-user-config.md`
+- KAN-91 epic: `unitAI-gp7nq`
+- Phase 0 override machinery: `unitAI-gp7nq.1`
+- Phase 1 user-environment fields: `unitAI-gp7nq.2`
+- Phase 2 fallback chains: `unitAI-gp7nq.3`
+- Phase 3 preset references: `unitAI-gp7nq.4`
+- Follow-up reference-doc update: `unitAI-aav4w`
+- Follow-up stale 4-layer wording fix: `unitAI-v4i0j`

package/docs/workflow.md

@@ -0,0 +1,114 @@
+---
+title: Bead-First Workflow
+scope: workflow
+category: guide
+version: 1.4.2
+updated: 2026-06-24
+synced_at: bf6baf7a
+description: Canonical tracked and ad-hoc workflow for Specialists.
+source_of_truth_for:
+  - "src/cli/run.ts"
+  - "src/cli/chat.ts"
+  - "src/specialist/runner.ts"
+  - "src/specialist/supervisor.ts"
+  - "src/cli/resume.ts"
+  - "src/cli/steer.ts"
+domain:
+  - workflow
+  - beads
+---
+
+# Bead-First Workflow
+
+> `sp` is an alias for `specialists`.
+
+The canonical flow is bead-first. `specialists run` is always Supervisor-backed and emits a job id.
+
+## Tracked work (primary)
+
+```bash
+bd create "Investigate X" -t task -p 1 --json
+bd update <id> --claim --json
+specialists run <name> --bead <id> [--context-depth N]
+specialists feed -f
+bd close <id> --reason "Done" --json
+```
+
+Key behavior for `--bead` runs:
+- Bead content is the prompt source.
+- Runner injects bead context variables (`$bead_context`, `$bead_id`).
+- Runner applies a bead-aware system override to prevent sub-bead creation.
+- Supervisor appends specialist output back to the input bead. Terminal bead closure still follows the current workflow gates and memory-ack rules; if `waiting_auto_close_ms` is configured, waiting keep-alive jobs can also close automatically after silence. Verify bead state before committing or publishing.
+
+## Ad-hoc work
+
+```bash
+specialists run <name> --prompt "..."
+```
+
+Use this for quick untracked tasks.
+
+## Async observation model
+
+For headless or multi-job work, run specialists normally and inspect them with `feed`, `ps`, and `result`:
+
+```bash
+specialists run explorer --bead unitAI-abc
+sp feed -f
+sp result <job-id>
+```
+
+For a human-in-the-loop launch, use `sp chat`:
+
+```bash
+sp chat explorer --bead unitAI-abc
+```
+
+`sp chat` opens a TUI that combines a `sp feed -f`-style feed, pinned status row, final result display, and input prompt. Freeform input maps to `steer` while the job is running and `resume` while it is waiting. `/quit` and `Ctrl+C` detach without killing the job; use `/stop` when you intend to stop it.
+
+`--background` may also create a legacy tmux session when tmux is available. `sp attach <job>` reconnects to that tmux session only; it is not yet the chat TUI attach flow. Existing-job TUI attach is tracked separately in bead `unitAI-hx4ln`.
+
+Use:
+- CLI: run/chat, then inspect with `feed`, `ps`, `result`
+- MCP: `use_specialist` (only exposed tool)
+- Shell backgrounding (`&`) when needed
+
+## `--context-depth`
+
+`--context-depth` controls blocker context injection when using `--bead`.
+
+| Value | Meaning |
+|---|---|
+| `0` | Disable dependency context injection |
+| `3` | Walk 3 levels up completed blockers (default) |
+| `N` | Walk N levels up completed blockers |
+
+## `--no-beads`
+
+`--no-beads` disables tracking bead creation/updates for the run.
+
+Important:
+- It does not disable bead reading when `--bead <id>` is used.
+- Prompt source is still the bead when `--bead` is provided.
+
+## Steering vs resume
+
+- `steer`: for jobs currently `running` (mid-turn redirection)
+- `resume`: for keep-alive jobs in `waiting` (next turn)
+
+Inside `sp chat`, freeform input chooses between those two actions automatically based on the current status. Use explicit `sp steer` / `sp resume` commands when operating outside the chat TUI or from scripts.
+
+Keep-alive may be enabled explicitly (`--keep-alive`) or by specialist YAML (`execution.interactive: true`).
+Use `--no-keep-alive` when you want one-shot behavior for an otherwise interactive specialist.
+
+`resume` is not valid for non-waiting jobs.
+
+## Auto-append bead notes (all specialists)
+
+For **all specialists** invoked with `--bead`, Supervisor appends output notes back to the input bead automatically. This includes READ_ONLY, LOW, MEDIUM, and HIGH specialists.
+
+## See also
+
+- [background-jobs.md](background-jobs.md)
+- [mcp-tools.md](mcp-tools.md)
+- [authoring.md](authoring.md)

package/docs/worktree.md

@@ -0,0 +1,71 @@
+---
+title: Worktree Integration
+scope: worktree
+category: guide
+version: 1.2.1
+updated: 2026-06-24
+synced_at: bf6baf7a
+description: xtrm worktree usage alongside Specialists.
+source_of_truth_for:
+  - "src/cli/help.ts"
+  - "config/specialists/xt-merge.specialist.json"
+domain:
+  - worktrees
+  - xtrm
+---
+
+<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+| [Common commands](#common-commands) | xt pi, xt claude, xt attach, xt worktree list, xt end, xt report |
+| [Recommended pattern](#recommended-pattern) | create/claim bead → worktree → specialists --bead → feed → close |
+| [PR queue help](#pr-queue-help) | Use `xt-merge` when you need a specialist to drain the PR queue in FIFO order |
+| [See also](#see-also) | workflow.md, specialists-catalog.md |
+<!-- END INDEX -->
+
+# Worktree Integration
+
+Specialists can be used alongside xtrm worktree workflows.
+
+## Common commands
+
+| Command | Purpose |
+|---|---|
+| `xt pi [name]` | Start a Pi session in a sandboxed xt worktree |
+| `xt claude [name]` | Start a Claude session in a sandboxed xt worktree |
+| `xt attach [slug]` | Resume an existing xt worktree session |
+| `xt worktree list` | List worktrees with runtime and activity |
+| `xt end [--epic <id>] [--pr]` | Close session: push, PR/merge, cleanup. Use `--epic` for wave-bound chain publication. |
+| `xt report show\|list\|diff` | Session report surfaces (same .xtrm/reports files) |
+
+## Recommended pattern
+
+1. create/claim a bead
+2. work in a dedicated worktree
+3. use specialists with `--bead`
+4. monitor with `specialists feed -f`
+5. close the bead and end the worktree session
+
+### Epic-aware session close
+
+For wave-bound chains, use `xt end --epic <id>` or let auto-detection redirect:
+
+```bash
+# Explicit epic publication
+xt end --epic unitAI-3f7b --pr
+
+# Auto-detect epic from chain membership
+xt end
+# → redirects to sp epic merge if chain belongs to unresolved epic
+```
+
+See `docs/worktrees.md` for full `sp end` behavior.
+
+## PR queue help
+
+Use `xt-merge` when you need a specialist to drain the PR queue in FIFO order.
+
+## See also
+
+- [workflow.md](workflow.md)
+- [specialists-catalog.md](specialists-catalog.md)