@jaggerxtrm/specialists 3.9.0 → 3.12.0

package/README.md

@@ -79,9 +79,12 @@ specialists doctor
 | Need | Doc |
 |---|---|
 | Install and bootstrap a project | [docs/bootstrap.md](docs/bootstrap.md) |
+| Release notes and version history | [CHANGELOG.md](CHANGELOG.md) |
+| Changelog drafting specialist | [config/specialists/changelog-keeper.specialist.json](config/specialists/changelog-keeper.specialist.json) |
 | Run a script-class specialist over HTTP (`sp serve`) — overview & contract | [docs/specialists-service.md](docs/specialists-service.md) |
 | Install `sp serve` in another project (sidecar Docker / Podman) | [docs/specialists-service-install.md](docs/specialists-service-install.md) |
 | Build & publish the specialists-service image | [docs/release-image.md](docs/release-image.md) |
+| Release flow (skill + specialist) | [config/skills/releasing/SKILL.md](config/skills/releasing/SKILL.md) |
 | Bead-first workflow and semantics | [docs/workflow.md](docs/workflow.md) |
 | CLI commands and flags | [docs/cli-reference.md](docs/cli-reference.md) |
 | Background jobs, feed, result, stop | [docs/background-jobs.md](docs/background-jobs.md) |

package/config/hooks/specialists-session-start.mjs

@@ -9,7 +9,8 @@
 // Hook type: SessionStart
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
 const cwd     = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
@@ -17,6 +18,25 @@ const HOME    = homedir();
 const jobsDir = join(cwd, '.specialists', 'jobs');
 const lines   = [];
 
+// Resolve specialists package version for hot-tips header.
+function readSpecialistsVersion() {
+  // Walk up from this hook's location looking for package.json with name=@jaggerxtrm/specialists or name=specialists.
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    const pkg = join(dir, 'package.json');
+    if (existsSync(pkg)) {
+      try {
+        const j = JSON.parse(readFileSync(pkg, 'utf-8'));
+        if (j?.name && j.name.includes('specialists')) return j.version ?? 'unknown';
+      } catch { /* skip */ }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return 'unknown';
+}
+
 // ── 1. Active background jobs ──────────────────────────────────────────────
 if (existsSync(jobsDir)) {
   let entries = [];
@@ -95,6 +115,18 @@ lines.push('specialists doctor                                 # troubleshoot is
 lines.push('```');
 lines.push('');
 lines.push('MCP tools: use_specialist (foreground only)');
+lines.push('');
+
+// ── 4. Hot tips (version-pinned, current sp release) ───────────────────────
+const spVersion = readSpecialistsVersion();
+lines.push(`## Specialists — Hot Tips (sp v${spVersion})`);
+lines.push('');
+lines.push('- `--bead` on edit-capable specialists auto-provisions worktree');
+lines.push('- Reviewer enters with `--job <exec-job>`; `--worktree`/`--job` exclusive');
+lines.push('- `sp epic merge <epic>` for epic chains; `sp merge <chain>` for standalone');
+lines.push('- `sp ps`/`sp feed`/`sp result` (sp poll deprecated)');
+lines.push('- `--keep-alive` required so reviewer/overthinker can be `sp resume`d');
+lines.push('- `sp merge` fails after `sp stop` cleans status.json — see unitAI-ofjvj');
 
 // ── Output ─────────────────────────────────────────────────────────────────
 if (lines.length === 0) process.exit(0);

package/config/mandatory-rules/README.md

@@ -3,6 +3,10 @@
 Rule sets injected at the end of every specialist prompt at spawn time. Enforces
 behaviors the model must follow regardless of the specific task.
 
+> **Quick introspection:** `sp list-rules` prints the rule × specialist matrix.
+> Filter with `sp list-rules --rule <id>` or `sp list-rules --specialist <name>`,
+> machine output via `--json`.
+
 ## Layout (three tiers)
 
 The loader reads and unions indexes from three paths, in this precedence:

package/config/mandatory-rules/changelog-conventions.md

@@ -0,0 +1,21 @@
+---
+name: changelog-conventions
+kind: mandatory-rule
+rules:
+  - id: keep-a-changelog
+    level: required
+    text: "Use Keep-a-Changelog format with YAML frontmatter, version headers, and top-level sections Added, Changed, Fixed, Removed, Deprecated, Security."
+  - id: one-line-entries
+    level: required
+    text: "Keep each changelog entry to one line."
+  - id: bead-references
+    level: required
+    text: "Include bead-id references in parentheses when helpful, like (unitAI-123)."
+  - id: conventional-commit-mapping
+    level: required
+    text: "Map conventional commits to sections: feat -> Added, fix -> Fixed, refactor/perf -> Changed, docs -> Changed, chore -> Changed unless user-facing, revert -> Removed, sec/security -> Security."
+  - id: section-completeness
+    level: required
+    text: "Draft all applicable sections in this order: Added, Changed, Fixed, Removed, Deprecated, Security. Omit only empty sections."
+---
+Changelog drafting rules for release automation.

package/config/mandatory-rules/changelog-keeper-scope.md

@@ -0,0 +1,50 @@
+---
+name: changelog-keeper-scope
+kind: mandatory-rule
+---
+SINGLE PURPOSE. You exist to produce one release: draft the next CHANGELOG.md section, bump package.json, rebuild dist, commit, tag, and push. Nothing else.
+
+EDIT WHITELIST. You may write to ONLY these paths:
+- `CHANGELOG.md` (insert the new release section above the previous one)
+- `package.json` (version field only — no other field)
+- `dist/index.js`, `dist/lib.js`, `dist/types/**` (regenerated by `npm run build` — never hand-edit)
+
+EDIT BLACKLIST. NEVER write to ANY of:
+- `src/**` (source code — out of scope, ever)
+- `tests/**` (test code — out of scope)
+- `docs/**` (any markdown except CHANGELOG.md is out of scope)
+- `config/**` (specialist configs, mandatory rules, skills — out of scope)
+- `.specialists/**` (runtime state — out of scope)
+- `.xtrm/**`, `.wolf/**`, `.beads/**` (session bookkeeping — out of scope)
+- `README.md`, `CLAUDE.md`, `AGENTS.md`, `XTRM-GUIDE.md` (top-level docs — out of scope)
+- Any other file not in the EDIT WHITELIST above.
+
+If you believe a file outside the whitelist must be edited, STOP and emit `BLOCKED: scope-violation` naming the file and the reason. Do not attempt the edit.
+
+INPUT DISCIPLINE. Your synthesis input is xtrm session reports under `.xtrm/reports/`. The bead's SCOPE field names the relevant tag range. Read reports with `Read` and decide which apply. Supplement with `git log --oneline <prev-tag>..HEAD` for tag verification. Do not crawl `src/`, `docs/`, or other source. The reports are pre-filtered, curated synthesis input — that is why they exist.
+
+SECTION FORMAT. Apply changelog-conventions (Keep-a-Changelog v1.0.0, one-line bullets, bead-id refs in parens, sections in order Added/Changed/Fixed/Removed/Deprecated/Security, omit empty). Default bucket is Changed. Deprecated is ONLY for explicit sunset/removal notices. No meta-commentary in bullets ("Conventional commit mapping applied", "Bead IDs included parenthetically", etc. — banned).
+
+VERSION POLICY. Default is patch bump (`v3.10.0` → `v3.10.1`). Use minor for new features (`v3.11.0`), major only on explicit operator instruction. The bead names the target version explicitly OR specifies the bump type; if neither is present, STOP and emit `BLOCKED: version-not-specified`.
+
+INSERT POSITION. The new section goes immediately above the most recent existing release section, below the `[Unreleased]` placeholder. Re-emit an empty `[Unreleased]` placeholder above the new section.
+
+GIT DISCIPLINE. After file edits + rebuild succeed:
+- `git add CHANGELOG.md package.json dist/` (no other paths)
+- `git diff --cached --stat` and confirm only whitelisted paths are staged. If anything else is staged, STOP and report.
+- `git commit -m "release: vX.Y.Z"` (exactly this format, no other prefix or suffix)
+- `git tag -a vX.Y.Z -m "<one-line summary derived from changelog section>"`
+- `git push --follow-tags origin <branch>`
+- Optional: `gh release create vX.Y.Z --notes "<the changelog section body>"` (only if `gh` is available and the bead requests it)
+
+NO DESTRUCTIVE OPS. Never `git reset --hard`, never `git push --force`, never delete tags, never rewrite history. If a prior release commit/tag is wrong, STOP and report — operator handles repair.
+
+SELF-VERIFY. Before finishing, run `git diff --stat HEAD~1 HEAD` and confirm the result matches:
+- `CHANGELOG.md` modified
+- `package.json` modified
+- `dist/**` modified
+- nothing else
+
+If anything else appears, the operator's manual edits leaked in. STOP and emit `BLOCKED: scope-leak` naming the offending paths.
+
+OUTPUT SHAPE. Final report must include: `VERSION: vX.Y.Z`, `VERDICT: <RELEASED|BLOCKED>`, `SECTION_DRAFTED: <one-line summary>`, `FILES_CHANGED: <list>`, `COMMIT: <sha>`, `TAG: <vX.Y.Z>`, `PUSHED: <true|false>`, `GH_RELEASE: <url|none>`. On BLOCKED, name the precondition violated.

package/config/mandatory-rules/gitnexus-required.md

@@ -2,4 +2,20 @@
 name: gitnexus-required
 kind: mandatory-rule
 ---
-Use GitNexus for symbol changes. Run impact before edit and detect_changes before finish.
+Use GitNexus before editing any function/class/method.
+
+Tools (prefer MCP; fall back to CLI if MCP unavailable):
+- Blast radius before edit: `gitnexus_impact({target, direction:"upstream"})` or `npx gitnexus impact <target>`. STOP and warn if HIGH/CRITICAL.
+- Symbol callers/callees: `gitnexus_context({name})` or `npx gitnexus context <name>`.
+- Concept search: `gitnexus_query({query})` or `npx gitnexus query "<text>"`.
+- Pre-commit scope check: `gitnexus_detect_changes()` (MCP only — fallback: `git diff --stat`).
+
+Rules:
+- Run impact for every existing symbol you modify; never edit without it.
+- Never rename via find-replace — use `gitnexus_rename({symbol_name, new_name, dry_run:true})` first.
+- If index is stale, ask the user to run `npx gitnexus analyze`.
+
+New-file scope (escape hatch):
+- When the diff adds only new files (new specialist JSON, new mandatory-rule, new test, new doc) and modifies no existing functions/classes/methods, blast-radius analysis is moot. State this explicitly in your output ("new-file scope; no existing-symbol modifications") and skip the impact call.
+- This applies to dispatch entries that merely add a routing case to an existing function (e.g. `src/index.ts` subcommand wiring): the touched symbol is the dispatcher, but the change is purely additive and equivalent to a registration. Note the dispatch addition and skip impact — list the new files instead.
+- Reviewer compliance: when authoritative_diff shows only new files (or additive dispatch entries), the "verify blast radius" requirement is satisfied by the executor's new-file-scope statement; do not flag as unmet.

package/config/mandatory-rules/serena-cheatsheet.md

@@ -0,0 +1,41 @@
+---
+name: serena-cheatsheet
+kind: mandatory-rule
+rules:
+  - id: prefer-serena
+    level: required
+    text: "Prefer Serena tools over read/grep/find/ls for source code (.ts .py .go .rs .js etc.). Native tools fine for .md .json .yaml configs."
+  - id: get_symbols_overview
+    level: required
+    text: "get_symbols_overview <path> — symbol skeleton of a file or dir (~300 tokens vs reading the whole file). Use first to pick what you actually need."
+  - id: find_symbol
+    level: required
+    text: "find_symbol <name_path> — fetch one symbol's body (or just signature). Drop-in replacement for read-then-scan-for-function workflows."
+  - id: find_referencing_symbols
+    level: required
+    text: "find_referencing_symbols <name_path> — who calls or uses this symbol across the codebase."
+  - id: search_for_pattern
+    level: required
+    text: "search_for_pattern <regex> — replaces grep. Returns matches with file:line context."
+  - id: find_file
+    level: required
+    text: "find_file <glob> and list_dir <path> — replace native find and ls."
+  - id: read_file
+    level: required
+    text: "read_file <path> — full or sliced read. Use only when navigation tools are not enough; check get_symbols_overview first."
+  - id: replace_symbol_body
+    level: required
+    text: "replace_symbol_body <name_path> — swap a function or class body in place. Use instead of Edit string-match for symbol-scoped changes (MEDIUM+ permission)."
+  - id: insert_around_symbol
+    level: required
+    text: "insert_before_symbol / insert_after_symbol <name_path> — add adjacent code such as imports or helpers (MEDIUM+ permission)."
+  - id: rename_symbol
+    level: required
+    text: "rename_symbol <name_path> <new_name> — refactor-safe across all references. Use instead of find-and-replace (MEDIUM+ permission)."
+  - id: replace_content
+    level: required
+    text: "replace_content <path> <pattern> <replacement> — line-range or regex edits when no symbol target fits (MEDIUM+ permission)."
+  - id: cost-rule
+    level: info
+    text: "Rule of thumb: read of a 500-line source file ~5000 tokens; find_symbol on one function ~200 tokens (~25x cheaper). Use get_symbols_overview before deciding."
+---

package/config/mandatory-rules/sync-docs-scope-discipline.md

@@ -0,0 +1,40 @@
+---
+name: sync-docs-scope-discipline
+kind: mandatory-rule
+---
+ONE DOC PER INVOCATION. The bead's `SCOPE` field MUST name exactly one doc path. If `SCOPE` names zero docs, more than one doc, or anything other than a single `docs/<name>.md` (or `CHANGELOG.md` / `README.md` if that IS the SCOPE doc), STOP immediately and emit a `BLOCKED: scope-violation` report. Do not proceed.
+
+INPUTS ARE FIXED. Your only sources of truth for what changed in the project:
+- The pre-script output above (latest xt report excerpt + recent master commits).
+- Your one doc's content (read with `Read`).
+- `python3 .xtrm/skills/default/sync-docs/scripts/drift_detector.py scan --json` — output MUST be filtered to your one SCOPE doc (jq or python filter). Discard all other entries.
+- `python3 .xtrm/skills/default/sync-docs/scripts/context_gatherer.py --doc <YOUR_SCOPE_DOC>` — exactly that doc, no broader flags.
+
+DIFF ESCAPE VALVE — STRICT. When a commit subject is insufficient to judge a claim in your doc, run `git show <hash> -- <path1> [<path2>...]` for ONE commit, naming only paths the doc actually claims about. Maximum 3 such commits per run. FORBIDDEN: `git diff <a>..<b>` (range diffs), `git show <hash>` without `--`, `git log -p`, `git log --stat` over more than 5 commits.
+
+DO NOT INSPECT SOURCE FILES BY ANY TOOL. The following are forbidden on `src/`, `tests/`, `pi/`, `packages/`, `config/specialists/`, `.specialists/default/`, or any non-doc path:
+- `Read` / `cat` / `head` / `tail` / `sed -n` / `awk` / `less` / `more`
+- `Grep` / `grep` / `rg` / `git grep`
+- `Glob` / `find` / `ls -R`
+- `python -c "open(...)"`, `python -c "Path(...).read_text()"`, or any scripted file slurp
+- `Bash` invocations that pipe source files anywhere (`< srcfile`, `cat srcfile | ...`)
+
+The pre-script context plus per-commit `git show -- <paths>` is exhaustive. Reading source by any other route is the failure mode this specialist exists to prevent.
+
+EXCEPTION (sole allowed source-inspection path): the `git show <hash> -- <paths>` form described above. No other tool, command, or pattern is permitted to read source files. The "DO NOT INSPECT SOURCE FILES" ban applies to every tool *except* this one bounded form.
+
+EDIT BOUNDARY. Edit ONLY your one SCOPE doc. NEVER touch CHANGELOG (unless it IS your SCOPE doc), README, `.xtrm/skills/`, other docs, or any source file. Cross-cutting updates are separate beads with their own SCOPE.
+
+NO RE-READING. If you have already gathered context this turn, refer to your prior output. Do NOT re-fetch after compaction. If prior gathered context is unreachable after compaction, STOP and emit `BLOCKED: context-lost-after-compaction` — do not re-run tools to recover.
+
+OBEY STEER AND STOP. When the orchestrator or user issues a steer or stop, comply on the very next tool call. Do not finish "one more thing".
+
+BUDGET. Per run: ONE drift scan (filtered), ONE context_gatherer call (only if pre-script context is insufficient), max THREE `git show <hash> -- <paths>` calls, ONE doc edit pass, ONE final drift validation. No exploratory loops.
+
+STOP CONDITIONS. Stop and emit your final report when ANY is true:
+- The one doc has been edited and stamped (`VERDICT: UPDATED`).
+- You determine no edit is needed (`VERDICT: NO_CHANGE_NEEDED`, cite commit evidence).
+- A precondition above is violated (`VERDICT: BLOCKED`, name the violation).
+- Steer or stop received.
+
+OUTPUT SHAPE. Final report must include: `DOC: <path>`, `VERDICT: <UPDATED|NO_CHANGE_NEEDED|BLOCKED>`, `COMMITS_REVIEWED: <hashes>`, `EDITS: <summary or "none">`, `DRIFT_BEFORE`, `DRIFT_AFTER`, optional `SUGGESTED_FOLLOWUPS: <other doc names — never edited>`.

package/config/skills/releasing/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: releasing
+description: >-
+  Cut a release end-to-end via xt release. Use when the operator wants to
+  publish a new tag (vX.Y.Z) — drafts CHANGELOG section from xt reports,
+  bumps package.json, rebuilds dist, commits, tags, pushes, optional GH
+  release. Strict scope: only CHANGELOG.md + package.json + dist/.
+version: 1.2.0
+---
+
+# releasing
+
+One-step release publication via specialist delegation.
+
+## When to use
+
+The operator wants to cut a release. They say "release it", "ship vX.Y.Z", "cut a tag", or just "release".
+
+## How
+
+1. Determine target version. Default is patch bump from most recent semver tag. Operator may specify `--minor`, `--major`, or explicit version.
+
+2. Determine tag range. Default is `<latest-tag>..HEAD`. For backfills, operator names `--from` / `--to` explicitly.
+
+3. Create release bead. Template:
+
+   ```
+   PROBLEM: Cut release vX.Y.Z covering <prev-tag>..HEAD.
+   SUCCESS: CHANGELOG.md updated with new section above prior release; package.json bumped; dist rebuilt; commit `release: vX.Y.Z` pushed with tag.
+   SCOPE: CHANGELOG.md, package.json, dist/. Synthesis input: xt reports under .xtrm/reports/ dated within <prev-tag-date>..HEAD.
+   NON_GOALS: No source/docs/config edits. No retroactive changes to prior release sections.
+   CONSTRAINTS: Keep-a-Changelog v1.0.0 format. One-line bullets. Default bucket Changed. Deprecated only for explicit sunsets.
+   VALIDATION: git diff --stat HEAD~1 HEAD shows only CHANGELOG.md, package.json, dist/.
+   OUTPUT: Final report with VERSION, COMMIT, TAG, PUSHED status.
+   GH_RELEASE: <true|false>   # whether to also `gh release create`
+   ```
+
+4. Dispatch specialist:
+
+   ```bash
+   xt release prepare --from <prev-tag> --to HEAD --patch
+   ```
+
+   or `xt release publish` once draft is approved. `xt release` invokes
+   `sp script changelog-keeper` synchronously, READ_ONLY, template-driven.
+   No HTTP. No bead. No worktree.
+
+5. Verify diff after specialist completes.
+
+   ```bash
+   git diff --stat HEAD~1 HEAD
+   ```
+
+   Output MUST show only:
+   - `CHANGELOG.md`
+   - `package.json`
+   - `dist/index.js`, `dist/lib.js`, `dist/types/**`
+
+6. If diff check passes, release shipped. Confirm:
+
+   ```bash
+   git tag --list 'v*' | tail -3
+   git log --oneline -1
+   ```
+
+## Why this design
+
+- Specialist does work itself. No CLI plumbing, no template substitution, no JSON output schema, no two-phase prepare/publish gate.
+- Mandatory rule `changelog-keeper-scope` enforces edit whitelist.
+- Operator gate is single `git diff --stat HEAD~1 HEAD` check after specialist finishes.
+- xt reports are synthesis input, not git log + bd query. Reports are pre-curated, signal-rich, written in user-facing language.
+- New pre-script injects a bounded xt report bundle first so changelog bullets can reflect intent and post-mortem context, not just file diffs.
+
+## Parallel sessions
+
+Each orchestrator runs this skill in its own session. Specialist commits + tags + pushes atomically. If two sessions try same version, first push wins; second sees remote tag conflict and aborts cleanly. Operator picks next version and retries.
+
+## Don't
+
+- Don't manually `sp release prepare`/`publish` — deprecated aliases only. Use `xt release prepare`/`publish`.
+- Don't edit CHANGELOG.md outside release flow — manual edits leak into next release diff and break scope verification.
+- Don't pre-stage files. Specialist stages exactly what it commits.

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

@@ -5,7 +5,7 @@ description: >
   agent through writing a valid `.specialist.json`, choosing supported models,
   validating against the schema, and avoiding common specialist authoring
   mistakes.
-version: 1.1
+version: 1.2
 synced_at: 236ca5e6
 ---
 
@@ -40,6 +40,7 @@ Model tiers:
 Rules:
 - Always pick the **highest version** in a family (`claude-sonnet-4-6` not `4-5`, `gemini-3.1-pro-preview` not `gemini-2.5-pro`)
 - `model` and `fallback_model` must be **different providers**
+- If a specialist needs a longer fallback chain, keep first fallback in `fallback_model` and let runtime supply any extra retry tier.
 - Never write a model string you have not pinged in this session
 
 ---
@@ -162,6 +163,10 @@ specialists models  # confirm assignments look balanced
 
 ---
 
+## Canonical references
+
+Reference any canonical skill or rule by name; runtime finds it.
+
 ## Quick Start: Scaffold + `sp edit`
 
 ```bash
@@ -201,19 +206,47 @@ bun config/skills/specialists-creator/scripts/validate-specialist.ts config/spec
 |-------|------|----------|-------|
 | `name` | string | yes | kebab-case: `[a-z][a-z0-9-]*` |
 | `version` | string | yes | semver: `1.0.0` |
-| `description` | string | yes | One sentence |
+| `description` | string | yes | Routing summary surfaced by `specialists list`; see Description writing below |
 | `category` | string | yes | Free text (e.g. `workflow`, `analysis`, `codegen`) |
 | `author` | string | no | Optional |
 | `created` | string | no | Optional date |
 | `updated` | string | no | Optional date, quote it: `"2026-03-22"` |
 | `tags` | string[] | no | Optional list |
 
+
+### Description writing for `specialists list`
+
+`specialist.metadata.description` is the routing surface that orchestrators see in `specialists list`. Write it as an operational role definition, not marketing copy. Keep the first clause distinctive because list output may truncate.
+
+A good description answers, in this order:
+
+1. **Choose when** — the task shape that should route here.
+2. **Do not choose when** — adjacent roles that should win instead.
+3. **Distinctive capability** — what this specialist does that others do not.
+4. **Permission/risk note** — READ_ONLY/LOW/MEDIUM/HIGH implication when it affects orchestration.
+
+Pattern:
+
+```text
+<role noun>. Use for <specific task shape>. Not for <near misses>; use <better roles>. <permission/workflow distinction>.
+```
+
+Examples:
+
+```text
+Scoped implementation only. Use when requirements, files/symbols, constraints, and validation are clear. Not diagnosis, planning, review, tests, release, or research. HIGH worktree.
+
+Debug symptoms/errors/regressions first. Use when cause is unknown or tests fail unexpectedly; traces, fixes targeted code, and verifies. HIGH keep-alive.
+```
+
+Avoid vague descriptions like "general purpose assistant" or "helps with code". Those cause orchestrators to overuse familiar specialists instead of routing to debugger, test-runner, researcher, sync-docs, or other sharper roles.
+
 ### `specialist.execution` (required)
 
 | Field | Type | Default | Notes |
 |-------|------|---------|-------|
 | `model` | string | — | required — ping before using |
-| `fallback_model` | string | — | must be a different provider |
+| `fallback_model` | string | — | first fallback only; runtime may append more tiers |
 | `mode` | enum | `auto` | `tool` \| `skill` \| `auto` |
 | `timeout_ms` | number | `120000` | ms |
 | `stall_timeout_ms` | number | — | kill if no event for N ms |
@@ -234,17 +267,58 @@ bun config/skills/specialists-creator/scripts/validate-specialist.ts config/spec
   - 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.
 
-**Permission tiers** — controls which pi tools are available:
+**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.
+
+| Level | Native tools (cumulative) | Use when |
+|-------|---------------------------|----------|
+| `READ_ONLY` | `read, grep, find, ls` | Read-only analysis, no bash |
+| `LOW` | `+ bash` | Inspect/run commands, no file edits |
+| `MEDIUM` | `+ edit` | Can edit existing files |
+| `HIGH` | `+ write` | Full access — can create new files |
+
+After choosing a tier, verify the resolved tool list before dispatching:
 
-| Level | pi --tools | Use when |
-|-------|-----------|----------|
-| `READ_ONLY` | `read,grep,find,ls` | Read-only analysis, no bash |
-| `LOW` | `+bash` | Inspect/run commands, no file edits |
-| `MEDIUM` | `+edit` | Can edit existing files |
-| `HIGH` | `+write` | Full access — can create new files |
+```bash
+sp config show <name> --resolved
+```
 
 **Common pitfall:** `READ_WRITE` is **not** a valid value — use `LOW` or higher.
 
+### Per-specialist `permissions[<TIER>]` override (rarely needed)
+
+Most specialists use the catalog default deny baseline. **Do not declare an override unless this specialist's policy genuinely diverges from its tier.** When you do override, remember the specialist block replaces catalog defaults for that tier.
+
+If divergence is real, add a top-level `permissions` block (sibling to `execution`):
+
+```jsonc
+{
+  "specialist": {
+    "execution": { "permission_required": "READ_ONLY" },
+    "permissions": {
+      "READ_ONLY": {
+        "denied_natives_when_extension": ["grep", "find", "ls"],
+        "denied_natives_mode": "hard"
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Default | Effect |
+|-------|------|---------|--------|
+| `denied_natives_when_extension` | `string[]` | `[]` | Native tools to deny only when a replacement extension is healthy. Catalog defaults apply first; specialist override replaces them for that tier. |
+| `denied_natives_mode` | `"soft"` \| `"hard"` | `"soft"` | `soft` keeps the tool with a preference hint; `hard` removes it (with auto-restore if the extension degrades) |
+
+The override block can only *deny* natives — it cannot add new tools beyond the catalog tier. To add tools, change the tier or update the catalog file.
+
+**Decision rule when authoring:**
+1. Pick the lowest tier that satisfies the specialist's actual capability needs.
+2. Run `sp config show <name> --resolved` and inspect the `--tools` line.
+3. If the tools are right, you're done — no override needed.
+4. If a native tool is genuinely worse than an extension equivalent for this specialist's task, declare a soft-deny first to observe behavior, then promote to hard-deny once you trust it.
+
+See [docs/manifest.md](../../../docs/manifest.md) for full deny-mode semantics, extension health gating, and the canonical explorer example.
+
 **Per-specialist extension opt-out**
 
 Use `execution.extensions` only when this specialist must suppress default extension injection.

package/config/skills/specialists-creator/scripts/validate-specialist.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { parseSpecialist } from "../../../src/specialist/schema.ts";
+import { parseSpecialist } from "../../../../src/specialist/schema.ts";
 
 function printUsage(): void {
   console.error("Usage: bun skills/specialist-author/scripts/validate-specialist.ts <path-to.specialist.yaml>");

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

@@ -6,8 +6,8 @@ description: >
   "sp is out of date", "hooks not firing", "skills not loading after update",
   or when drift is detected in installed specialists config, hooks, jobs, DB,
   extensions, or worktree cleanup.
-version: 1.3
-synced_at: 2026-04-25
+version: 1.4
+synced_at: 2026-04-29
 ---
 
 # update-specialists
@@ -91,13 +91,18 @@ looks like.
 | Check | Expected value |
 |-------|----------------|
 | specialists DB | Opens cleanly (`.specialists/db/observability.db`) |
-| Schema version | Matches runtime expectation (current: v11) |
+| Schema version | Matches runtime expectation (current: v11; auto-migrates on next runtime startup) |
 | `specialist_job_metrics` table | Present at v11+ — holds aggregated per-job metrics |
+| `specialist_job_metrics` columns | Includes `active_runtime_ms` + `waiting_ms` (drs41.1 — auto-added by idempotent `migrateToV11` ALTER TABLE on first start of upgraded runtime; pre-existing rows get NULL until next aggregate) |
+| Auto-aggregation hook | Supervisor + `sp stop` invoke `aggregateJobMetricsBestEffort` after terminal-status persistence (drs41.1) — table populates without manual `sp db extract` under normal operation |
+| Merge target lookup | DB-first (post-ofjvj): `readAllJobStatuses()` reads `specialist_jobs` via `listStatuses()`. `sp merge` no longer reads `.specialists/jobs/<id>/status.json`. Older versions silently failed after `sp stop` cleaned status.json. |
 | WAL / busy timeout settings | Present when runtime uses SQLite |
 | Corruption / lock errors | None in `sp doctor` |
 | Pre-prune extract | `sp db prune --apply` extracts metrics to `specialist_job_metrics` before deleting events |
-| Extract backfill | `sp db extract --all-missing` populates metrics for jobs whose events still exist |
-| Historical stats query | `sp db stats [--spec <name>] [--model <glob>] [--since <dur>]` reads the aggregated table |
+| Extract backfill | `sp db extract --all-missing` populates metrics for jobs whose events still exist (still useful for backfilling historical jobs that ran before the auto-aggregate hook landed) |
+| Historical stats query | `sp db stats [--spec <name>] [--model <glob>] [--since <dur>]` reads the aggregated table; output includes `active_s`, `waiting_s`, `total_s` (drs41.1) |
+
+**Safety: `sp init` and `sp init --sync-defaults` do NOT touch `.specialists/db/observability.db`.** Init checks file existence and skips with "observability database already exists (not touched)" when present. Schema migrations run on next runtime startup (any `sp` invocation that opens the DB), additively via `ALTER TABLE ADD COLUMN`. No data loss path during a normal package upgrade.
 
 ### Skills + extensions parity
 
@@ -126,6 +131,28 @@ Loader unions indexes from three paths and probes set files in reverse precedenc
 | Index files (`index.json`) | Any of the three tiers may define `required_template_sets` / `default_template_sets`; loader unions + dedups |
 | Prompt injection behavior | Runner appends resolved `MANDATORY_RULES` block at end of prompt; supervisor emits `mandatory_rules_injection` meta event |
 
+## Discover Latest Release
+
+Before reconciling, determine whether a newer release is published. Compare local `package.json` version to the most recent `vX.Y.Z` tag on `origin`:
+
+```bash
+LOCAL=$(node -p "require('./package.json').version")
+LATEST=$(git ls-remote --tags --refs origin | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1 | sed 's/^v//')
+echo "local: $LOCAL  latest: $LATEST"
+```
+
+If `LATEST > LOCAL`, read the corresponding `CHANGELOG.md` section to summarize what shipped:
+
+```bash
+awk -v ver="$LATEST" '/^## \[v?'"$LATEST"'\]/,/^## \[/{print}' CHANGELOG.md | head -60
+```
+
+Surface a one-line summary to the user (Added/Changed/Fixed counts plus the headline) and **ask before pulling**. The reconcile flow below applies regardless of whether the user pulls a new release first or stays on the current version — drift detection is independent of release version.
+
+Skip this discovery step entirely when `SPECIALISTS_OFFLINE=1` is set, when offline, or when the user already specified the version. The `using-specialists-v2` skill performs the same lightweight check on session-load and may have already surfaced the notice; do not repeat it.
+
+After the user confirms a pull (e.g. `git fetch && git pull origin master`), proceed with detection below to catch any drift introduced by the new release.
+
 ## Detection
 
 Run these in order. Report which checks pass and which drift.
@@ -182,8 +209,8 @@ find .worktrees -maxdepth 2 -mindepth 1 -type d 2>/dev/null || true
 # 12. Extension registration
 node -e "const fs=require('fs'); const p='.pi/settings.json'; if (fs.existsSync(p)) console.log(JSON.stringify(JSON.parse(fs.readFileSync(p,'utf8')).skills ?? JSON.parse(fs.readFileSync(p,'utf8')).extensions ?? {}, null, 2)); else console.log('MISSING .pi/settings.json')"
 
-# 13a. Observability schema + metrics coverage
-node -e "const {Database} = require('bun:sqlite'); const p='.specialists/db/observability.db'; const fs=require('fs'); if (!fs.existsSync(p)) { console.log('NO_DB'); process.exit(0); } const db=new Database(p,{readonly:true}); const v=db.query(\"SELECT value FROM schema_meta WHERE key='version'\").get(); const has=db.query(\"SELECT name FROM sqlite_master WHERE type='table' AND name='specialist_job_metrics'\").get(); const jobs=db.query('SELECT COUNT(*) c FROM specialist_jobs').get(); const metrics=has ? db.query('SELECT COUNT(*) c FROM specialist_job_metrics').get() : null; console.log(JSON.stringify({schema_version: v?.value, has_metrics_table: !!has, jobs: jobs.c, metrics_rows: metrics?.c ?? 0, metrics_coverage: metrics ? (metrics.c/jobs.c).toFixed(2) : null}, null, 2));" 2>/dev/null || echo "REQUIRES_BUN_RUNTIME"
+# 13a. Observability schema + metrics coverage + drs41.1 column presence
+node -e "const {Database} = require('bun:sqlite'); const p='.specialists/db/observability.db'; const fs=require('fs'); if (!fs.existsSync(p)) { console.log('NO_DB'); process.exit(0); } const db=new Database(p,{readonly:true}); const v=db.query(\"SELECT value FROM schema_meta WHERE key='version'\").get(); const has=db.query(\"SELECT name FROM sqlite_master WHERE type='table' AND name='specialist_job_metrics'\").get(); const jobs=db.query('SELECT COUNT(*) c FROM specialist_jobs').get(); const metrics=has ? db.query('SELECT COUNT(*) c FROM specialist_job_metrics').get() : null; const cols=has ? new Set(db.query('PRAGMA table_info(specialist_job_metrics)').all().map(r=>r.name)) : new Set(); const drs41Cols={active_runtime_ms: cols.has('active_runtime_ms'), waiting_ms: cols.has('waiting_ms')}; console.log(JSON.stringify({schema_version: v?.value, has_metrics_table: !!has, drs41_columns_present: drs41Cols, jobs: jobs.c, metrics_rows: metrics?.c ?? 0, metrics_coverage: metrics ? (metrics.c/jobs.c).toFixed(2) : null}, null, 2));" 2>/dev/null || echo "REQUIRES_BUN_RUNTIME"
 
 # 13. Mandatory-rules template tiers + reference checks (three-tier resolution)
 find .specialists/default/mandatory-rules -maxdepth 1 -type f 2>/dev/null || true
@@ -213,6 +240,9 @@ Use targeted fixes first. Escalate to full sync only if needed.
 | Orphaned `.worktrees/` entries | `specialists clean` |
 | SQLite schema/version mismatch | `sp doctor` first, then `specialists init --sync-defaults` or runtime migration command |
 | Schema below v11 (no `specialist_job_metrics`) | Reinstall / upgrade runtime; table is created by initSchema / migrateToV11. No data loss — raw events untouched. |
+| `specialist_job_metrics` missing `active_runtime_ms` / `waiting_ms` columns (post-drs41.1) | Open any `sp` command — `migrateToV11` is idempotent and ALTERs the table to add the columns. No reinstall needed. Pre-existing rows show NULL until next aggregate or `sp db extract --all-missing`. |
+| Auto-aggregate hook absent (older runtime) — empty `specialist_job_metrics` despite job activity | Upgrade `@jaggerxtrm/specialists` package. Post-drs41.1, supervisor + `sp stop` invoke `aggregateJobMetricsBestEffort` on every terminal status, so the table fills under normal operation. Backfill historical with `sp db extract --all-missing`. |
+| `sp merge` fails after `sp stop` (older runtime) — "No chain-root job with worktree metadata found" | Upgrade `@jaggerxtrm/specialists` past ofjvj fix. Merge lookup is now DB-first via `readAllJobStatuses()` / `listStatuses()`. Pre-fix workaround was manual `git merge --no-ff feature/<branch>` (skips tsc + conflict gates). |
 | Events about to be pruned but never aggregated | `sp db extract --all-missing` BEFORE `sp db prune --apply`. Prune refuses when extract fails (safe by design). |
 | Emergency: need to prune but extract is wedged | `sp db prune --apply --skip-extract` — raw events deleted without aggregation. Use only when data loss is acceptable. |
 | Historical per-job stats needed | `sp db stats` reads `specialist_job_metrics`. Replaces ad-hoc `status.json` scans. Supports `--format json\|table`. |
@@ -300,6 +330,10 @@ If doctor reports DB version mismatch or recovery issue:
 2. Apply runtime migration command if available.
 3. If no automated migration exists, flag manual intervention.
 
+For additive schema bumps (e.g. drs41.1 added `active_runtime_ms` / `waiting_ms` columns within v11): just open any `sp` command in the repo. `initSchema()` runs every migrate-up function on every startup; `migrateToV11` is idempotent — it detects existing v11 schema and `ALTER TABLE ADD COLUMN`s the missing fields. Existing rows are preserved (new fields = NULL until next aggregate). No data loss, no manual SQL.
+
+`sp init` and `sp init --sync-defaults` skip the DB entirely when it exists — the only way to wipe `.specialists/db/observability.db` is to delete the file manually.
+
 ### Fix: metrics aggregation missing or stale
 
 Schema v11 introduced `specialist_job_metrics` (aggregated per-job stats). If you see low `metrics_coverage` in the detection output, or want historical stats before running `sp db prune`: