@jaggerxtrm/specialists 3.16.0 → 3.18.0

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.
 
@@ -575,7 +576,34 @@ Informational declarations used by pre-run validation and future tooling (e.g. `
 }
 ```
 
-Writes the final session output to this file path after the session completes. Relative to the working directory.
+When set, the specialist writes its **handoff block** to this file on every substantive turn — foreground and `--background`. The content is identical to what is appended to the input bead notes and shown by `sp result`: a markdown heading, the verbatim specialist output, and an italic metadata footer.
+
+- **No env flag required.** `output_file` is honored whenever it is set (since unitAI-f58ma). It does NOT require `SPECIALISTS_JOB_FILE_OUTPUT` — that flag now only gates the debug file-mirrors (events.jsonl / status.json / result.txt).
+- **Single writer.** In a supervised run (`sp run`) the supervisor owns the file and the runner's own write is suppressed, so the file is never double-written. (In script/serve runs there is no supervisor; the runner writes the raw output instead of the enveloped block.)
+- **Format is the rendered handoff block, not bare output.** A downstream specialist that consumes this file as input will see the header/footer envelope around the body.
+- **Append vs overwrite is controlled by `notes_mode`** (see below): `full-trail` appends each turn; `final-only` overwrites with just the final `[FINAL · DONE]` block.
+- **Gitignore the path** if you don't want it committed — specs with `output_file` always write, so add the path (e.g. `.specialists/*-result.md`) to `.gitignore`.
+
+Relative paths resolve from the working directory.
+
+### `specialist.notes_mode`
+
+Controls how per-turn handoff output is persisted to BOTH the input bead notes and `output_file`.
+
+| Value | Behavior |
+|---|---|
+| `"full-trail"` (default) | Append every substantive turn. Bead notes / `output_file` accumulate `### … [turn N · WAITING]` blocks, ending with a final `## … [FINAL · DONE]` block. Best for keep-alive specialists where the operator wants the full trail. |
+| `"final-only"` | Persist only the single canonical `## … [FINAL · DONE]` block; intermediate turns are skipped and `output_file` is OVERWRITTEN (not appended). Best for non-coding / chained pipelines where the next specialist reads the previous specialist's bead note or `output_file` as its input and only wants the final result. |
+
+Empty turns are never persisted. The handoff block is markdown-native (heading + verbatim body + one italic metadata footer); the model string is normalized (provider prefix stripped, e.g. `nano-gpt/moonshotai/kimi-k2.5` renders as `kimi-k2.5`).
+
+```json
+{ "notes_mode": "final-only" }
+```
+
+### Handoff / pipeline output recipe
+
+For a non-coding pipeline where each specialist reads the previous one's result, set `output_file` to a known path AND `notes_mode: "final-only"` so the file (and the bead note) holds exactly the final result, overwritten each run — clean for the next specialist to consume. For a human-monitored keep-alive specialist, leave `notes_mode: "full-trail"` (default) so the operator sees every turn accumulate. `output_file` needs no env flag; just gitignore its path.
 
 ### `specialist.validation` (optional)
 
@@ -624,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:
@@ -767,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.
@@ -800,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-auto/SKILL.md

@@ -39,7 +39,7 @@ read bead → write 7-section contract (child impl bead) → bd dep add parent
   → sleep 10 && sp ps                              # confirm started, not stuck queued
   → sleep <role-typical from v3> & sp ps          # check (see v3 Monitoring section)
   → sp result <exec-job>                           # consume immediately on transition to waiting
-  → optional advisory passes per v3 (code-sanity if smelly, security-auditor if risk surface)
+  → optional advisory passes per v3 (seconder if smelly, security-auditor if risk surface)
   → write reviewer bead contract → sp run reviewer --bead <review> --job <exec-job> --background
   → sleep 90 & sp ps
   → sp result <reviewer-job>

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

@@ -215,7 +215,7 @@ Run `specialists list` if you need the live registry. Choose by task, not by hab
 | Design/tradeoffs | `overthinker` | The approach is risky, ambiguous, or needs critique. |
 | Implementation | `executor` | The contract is clear enough to write code or docs. |
 | Compliance/code review | `reviewer` | An executor/debugger produced changes that need the final PASS/PARTIAL/FAIL verdict. |
-| Implementation sanity | `code-sanity` | You want a cheap READ_ONLY smell pass for simplicity, type safety, dead code, brittle async/error handling, or maintainability before reviewer. |
+| Implementation sanity | `seconder` | You want a cheap READ_ONLY smell pass for simplicity, type safety, dead code, brittle async/error handling, or maintainability before reviewer. |
 | Security/dependency audit | `security-auditor` | You need threat modeling, secure-code review, package advisory triage, or agent/config security scanning. LOW: scan/read/recommend only. |
 | Multiple review perspectives | `parallel-review` | A critical diff needs independent review passes. |
 | Test execution | `test-runner` | You need suites run and failures interpreted. |
@@ -247,7 +247,7 @@ specialists doctor --check-drift                 # inspect stale .specialists/de
 sp prune-stale-defaults --dry-run                # preview redundant default snapshots
 specialists run <name> --bead <id> --background
 specialists run executor --bead <impl-bead> --background       # worktree auto-provisioned
-specialists run code-sanity --bead <sanity-bead> --job <exec-job> --keep-alive --background
+specialists run seconder --bead <sanity-bead> --job <exec-job> --keep-alive --background
 specialists run security-auditor --bead <security-bead> --job <exec-job> --keep-alive --background
 specialists run reviewer --bead <review-bead> --job <exec-job> --keep-alive --background
 specialists ps
@@ -343,7 +343,7 @@ specialists run executor --worktree --bead <impl> --context-depth 3 --background
 specialists result <exec-job>
 ```
 
-Optional code-sanity pass for implementation smell checks (use when the diff is non-trivial or likely to accumulate agent-code complexity):
+Optional seconder pass for implementation smell checks (use when the diff is non-trivial or likely to accumulate agent-code complexity):
 
 ```bash
 bd create --title "Code sanity check token refresh retry" --type task --priority 3 \
@@ -355,11 +355,11 @@ CONSTRAINTS: At most 5 concrete findings; cite files/symbols/lines where possibl
 VALIDATION: Findings are suitable to paste into specialists resume <exec-job>.
 OUTPUT: OK/FINDINGS/BLOCKED with handoff."
 bd dep add <sanity> <impl>
-specialists run code-sanity --bead <sanity> --job <exec-job> --context-depth 3 --keep-alive --background
+specialists run seconder --bead <sanity> --job <exec-job> --context-depth 3 --keep-alive --background
 specialists result <sanity-job>
 ```
 
-If code-sanity returns `FINDINGS`, resume executor with those concrete instructions, then rerun code-sanity only if the fixes were substantive. Do not treat code-sanity `OK` as reviewer PASS.
+If seconder returns `FINDINGS`, resume executor with those concrete instructions, then rerun seconder only if the fixes were substantive. Do not treat seconder `OK` as reviewer PASS.
 
 Optional security pass when the task touches auth, secrets, input handling, dependency updates, package advisories, agent config, hooks, or exposed endpoints:
 
@@ -492,7 +492,7 @@ Standard loop:
 ```text
 executor --worktree --bead impl
   -> waiting after turn
-optional code-sanity --bead sanity --job exec-job
+optional seconder --bead sanity --job exec-job
   -> OK: continue
   -> FINDINGS: resume executor with exact sanity findings
 optional security-auditor --bead security --job exec-job
@@ -506,7 +506,7 @@ reviewer --bead review --job exec-job
 
 Prefer `sp resume <exec-job>` over a new fix executor when the original job is waiting and context is healthy. Use a new fix bead with `--job <exec-job>` only when the original executor is dead, context exhausted, or a separate audit trail is required.
 
-Code-sanity and security-auditor outputs are advisory inputs to the chain; reviewer output must still be consumed before publishing. Do not treat job completion, code-sanity OK, or security no-findings as equivalent to reviewer acceptance.
+Seconder and security-auditor outputs are advisory inputs to the chain; reviewer output must still be consumed before publishing. Do not treat job completion, seconder OK, or security no-findings as equivalent to reviewer acceptance.
 
 ## Dependency Mapping