@jaggerxtrm/specialists 3.10.0 → 3.13.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`');
+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/bead-id-verbatim.md

@@ -0,0 +1,14 @@
+# bead-id-verbatim
+
+## Rule
+Source bead-id arguments verbatim from injected context: `bead_id`, branch name, prior turn output, or `bd create` output. Do not retype bead ids from memory or regenerate them.
+
+## Command scope
+Applies only to bd commands that take a bead id, especially `bd close`, `bd update`, `bd dep add`, `bd dep list`, and `bd show`.
+
+## Legit cases
+- New bead creation: id may not exist yet; once `bd create` returns it, copy exact text forward.
+- Narrative prose: may mention bead ids freely. Only command arguments must be verbatim.
+
+## Failure example
+Today logs showed `unitAI-m8744.2` and `unitAI-m8744.3` retyped as `unitAI-m87442` and `unitAI-m87443`; `bd close` then failed with `issue id not found`.

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

@@ -11,6 +11,11 @@ Tools (prefer MCP; fall back to CLI if MCP unavailable):
 - Pre-commit scope check: `gitnexus_detect_changes()` (MCP only — fallback: `git diff --stat`).
 
 Rules:
-- Run impact for every symbol you modify; never edit without it.
+- 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/per-turn-handoff-schema.md

@@ -0,0 +1,16 @@
+---
+name: per-turn-handoff-schema
+kind: mandatory-rule
+---
+End every `run_complete` turn, resume turns included, with JSON last. Use `docs/specialists/handoff-schema.md` for required common fields and role-specific fields. Keep block small and valid. Minimal block:
+
+```json
+{
+  "status": "success",
+  "summary": "Done.",
+  "files_changed": [],
+  "follow_ups": [],
+  "risks": [],
+  "verification": []
+}
+```

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
 ---
 
@@ -13,6 +13,22 @@ synced_at: 236ca5e6
 
 > Source of truth: `src/specialist/schema.ts` | Runtime: `src/specialist/runner.ts`
 
+
+## Canonical References
+
+When a custom specialist needs a standard rule or skill, reference the canonical asset by name instead of copying its file into the repo. Runtime/package fallback resolves canonical mandatory rules and skills when no project-local override exists.
+
+Example:
+
+```json
+{
+  "mandatory_rules": { "template_sets": ["serena-cheatsheet"] },
+  "skills": { "paths": ["releasing"] }
+}
+```
+
+Only create project-local copies when intentionally changing canonical behavior. After setting references, run `sp config show <name> --resolved` to verify the resolved runtime surface.
+
 ---
 
 ## ACTION REQUIRED BEFORE ANYTHING ELSE
@@ -40,6 +56,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 +179,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 +222,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 +283,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 | 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 |
+| 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:
+
+```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>");