@jaggerxtrm/specialists 3.14.0 → 3.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dawid (Jaggerxtrm)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,12 +16,33 @@ A specialist is a reusable execution spec: model, allowed tools, skills, system
 
 ---
 
+## Vision
+
+Specialists turns one overloaded agent chat into a coordinated agent mind: a central orchestrator keeps task identity and evidence, while fresh specialist sessions act as scoped capabilities with their own prompts, rules, memory, and contracts. See [specialists.scheme.md](specialists.scheme.md) for diagrams comparing the single-chat model with specialist pipelines, herd memory, adaptive chains, and service specialists.
+
 ## Quick start
 
+1. Install Bun.
+
+```bash
+bun --version
+curl -fsSL https://bun.sh/install | bash
+```
+
+2. Install xtrm-tools.
+
+```bash
+npm install -g xtrm-tools
+xt install
+xt init
+```
+
+3. Install Specialists.
+
 ```bash
 npm install -g @jaggerxtrm/specialists
-specialists init
-specialists list
+sp init
+sp list
 ```
 
 `sp` is a shorter alias for `specialists` — both commands are identical:
@@ -62,7 +83,7 @@ specialists run codebase-explorer --prompt "Map the CLI architecture"
 - creates `specialists/`
 - creates `.specialists/` runtime dirs (`jobs/`, `ready/`)
 - adds `.specialists/` to `.gitignore`
-- injects the canonical Specialists Workflow block into `AGENTS.md` and `CLAUDE.md`
+- injects the canonical Specialists Workflow block into `AGENTS.md`
 - registers the Specialists MCP server at project scope
 
 Verify bootstrap state:

package/config/catalog/gitnexus.json

@@ -0,0 +1,12 @@
+{
+  "catalog": "gitnexus",
+  "package": "pi-gitnexus",
+  "version": "0.6.1",
+  "precedence": 1,
+  "source_tiers": {
+    "READ_ONLY": ["gitnexus_list_repos", "gitnexus_query", "gitnexus_context", "gitnexus_impact", "gitnexus_detect_changes"],
+    "LOW": ["gitnexus_list_repos", "gitnexus_query", "gitnexus_context", "gitnexus_impact", "gitnexus_detect_changes"],
+    "MEDIUM": ["gitnexus_list_repos", "gitnexus_query", "gitnexus_context", "gitnexus_impact", "gitnexus_detect_changes", "gitnexus_rename", "gitnexus_cypher"],
+    "HIGH": ["gitnexus_list_repos", "gitnexus_query", "gitnexus_context", "gitnexus_impact", "gitnexus_detect_changes", "gitnexus_rename", "gitnexus_cypher"]
+  }
+}

package/config/catalog/index.json

@@ -0,0 +1,59 @@
+{
+  "precedence_order": ["native", "gitnexus", "serena"],
+  "default_overrides": {
+    "READ_ONLY": {
+      "denied_natives_when_extension": ["read", "grep", "find", "ls"],
+      "denied_natives_mode": "hard"
+    },
+    "LOW": {
+      "denied_natives_when_extension": ["read", "grep", "find", "ls"],
+      "denied_natives_mode": "hard"
+    },
+    "MEDIUM": {
+      "denied_natives_when_extension": ["read", "grep", "find", "ls"],
+      "denied_natives_mode": "hard"
+    },
+    "HIGH": {
+      "denied_natives_when_extension": ["read", "grep", "find", "ls"],
+      "denied_natives_mode": "hard"
+    }
+  },
+  "catalogs": [
+    {
+      "catalog": "native",
+      "package": "specialists",
+      "version": "3.11.0",
+      "precedence": 0,
+      "source_tiers": {
+        "READ_ONLY": ["read", "grep", "find", "ls"],
+        "LOW": ["read", "grep", "find", "ls", "bash"],
+        "MEDIUM": ["read", "grep", "find", "ls", "bash", "edit"],
+        "HIGH": ["read", "grep", "find", "ls", "bash", "edit", "write"]
+      }
+    },
+    {
+      "catalog": "gitnexus",
+      "package": "pi-gitnexus",
+      "version": "0.6.1",
+      "precedence": 1,
+      "source_tiers": {
+        "READ_ONLY": ["gitnexus_list_repos", "gitnexus_query", "gitnexus_context", "gitnexus_impact", "gitnexus_detect_changes"],
+        "LOW": ["gitnexus_list_repos", "gitnexus_query", "gitnexus_context", "gitnexus_impact", "gitnexus_detect_changes"],
+        "MEDIUM": ["gitnexus_list_repos", "gitnexus_query", "gitnexus_context", "gitnexus_impact", "gitnexus_detect_changes", "gitnexus_rename", "gitnexus_cypher"],
+        "HIGH": ["gitnexus_list_repos", "gitnexus_query", "gitnexus_context", "gitnexus_impact", "gitnexus_detect_changes", "gitnexus_rename", "gitnexus_cypher"]
+      }
+    },
+    {
+      "catalog": "serena",
+      "package": "pi-serena-tools",
+      "version": "0.1.0",
+      "precedence": 2,
+      "source_tiers": {
+        "READ_ONLY": ["serena_list_tools", "find_symbol", "find_referencing_symbols", "read_file", "get_symbols_overview", "jet_brains_get_symbols_overview", "jet_brains_find_symbol", "jet_brains_find_referencing_symbols", "jet_brains_type_hierarchy", "search_for_pattern", "list_dir", "find_file", "get_current_config", "activate_project", "check_onboarding_performed", "initial_instructions", "think_about_collected_information", "think_about_task_adherence", "think_about_whether_you_are_done", "list_memories", "read_memory"],
+        "LOW": ["serena_list_tools", "find_symbol", "find_referencing_symbols", "read_file", "get_symbols_overview", "jet_brains_get_symbols_overview", "jet_brains_find_symbol", "jet_brains_find_referencing_symbols", "jet_brains_type_hierarchy", "search_for_pattern", "list_dir", "find_file", "get_current_config", "activate_project", "check_onboarding_performed", "initial_instructions", "think_about_collected_information", "think_about_task_adherence", "think_about_whether_you_are_done", "list_memories", "read_memory", "execute_shell_command"],
+        "MEDIUM": ["serena_list_tools", "find_symbol", "find_referencing_symbols", "read_file", "get_symbols_overview", "jet_brains_get_symbols_overview", "jet_brains_find_symbol", "jet_brains_find_referencing_symbols", "jet_brains_type_hierarchy", "search_for_pattern", "list_dir", "find_file", "get_current_config", "activate_project", "check_onboarding_performed", "initial_instructions", "think_about_collected_information", "think_about_task_adherence", "think_about_whether_you_are_done", "list_memories", "read_memory", "execute_shell_command", "insert_after_symbol", "replace_symbol_body", "insert_before_symbol", "rename_symbol", "restart_language_server", "create_text_file", "replace_content", "delete_lines", "replace_lines", "insert_at_line", "remove_project", "switch_modes", "open_dashboard", "onboarding", "prepare_for_new_conversation", "summarize_changes", "write_memory", "delete_memory", "rename_memory", "edit_memory", "serena_mcp_reset"],
+        "HIGH": ["serena_list_tools", "find_symbol", "find_referencing_symbols", "read_file", "get_symbols_overview", "jet_brains_get_symbols_overview", "jet_brains_find_symbol", "jet_brains_find_referencing_symbols", "jet_brains_type_hierarchy", "search_for_pattern", "list_dir", "find_file", "get_current_config", "activate_project", "check_onboarding_performed", "initial_instructions", "think_about_collected_information", "think_about_task_adherence", "think_about_whether_you_are_done", "list_memories", "read_memory", "execute_shell_command", "insert_after_symbol", "replace_symbol_body", "insert_before_symbol", "rename_symbol", "restart_language_server", "create_text_file", "replace_content", "delete_lines", "replace_lines", "insert_at_line", "remove_project", "switch_modes", "open_dashboard", "onboarding", "prepare_for_new_conversation", "summarize_changes", "write_memory", "delete_memory", "rename_memory", "edit_memory", "serena_mcp_reset"]
+      }
+    }
+  ]
+}

package/config/catalog/native.json

@@ -0,0 +1,12 @@
+{
+  "catalog": "native",
+  "package": "specialists",
+  "version": "3.11.0",
+  "precedence": 0,
+  "source_tiers": {
+    "READ_ONLY": ["read", "grep", "find", "ls"],
+    "LOW": ["read", "grep", "find", "ls", "bash"],
+    "MEDIUM": ["read", "grep", "find", "ls", "bash", "edit"],
+    "HIGH": ["read", "grep", "find", "ls", "bash", "edit", "write"]
+  }
+}

package/config/catalog/serena.json

@@ -0,0 +1,12 @@
+{
+  "catalog": "serena",
+  "package": "pi-serena-tools",
+  "version": "0.1.0",
+  "precedence": 2,
+  "source_tiers": {
+    "READ_ONLY": ["serena_list_tools", "find_symbol", "find_referencing_symbols", "read_file", "get_symbols_overview", "jet_brains_get_symbols_overview", "jet_brains_find_symbol", "jet_brains_find_referencing_symbols", "jet_brains_type_hierarchy", "search_for_pattern", "list_dir", "find_file", "get_current_config", "activate_project", "check_onboarding_performed", "initial_instructions", "think_about_collected_information", "think_about_task_adherence", "think_about_whether_you_are_done", "list_memories", "read_memory"],
+    "LOW": ["serena_list_tools", "find_symbol", "find_referencing_symbols", "read_file", "get_symbols_overview", "jet_brains_get_symbols_overview", "jet_brains_find_symbol", "jet_brains_find_referencing_symbols", "jet_brains_type_hierarchy", "search_for_pattern", "list_dir", "find_file", "get_current_config", "activate_project", "check_onboarding_performed", "initial_instructions", "think_about_collected_information", "think_about_task_adherence", "think_about_whether_you_are_done", "list_memories", "read_memory", "execute_shell_command"],
+    "MEDIUM": ["serena_list_tools", "find_symbol", "find_referencing_symbols", "read_file", "get_symbols_overview", "jet_brains_get_symbols_overview", "jet_brains_find_symbol", "jet_brains_find_referencing_symbols", "jet_brains_type_hierarchy", "search_for_pattern", "list_dir", "find_file", "get_current_config", "activate_project", "check_onboarding_performed", "initial_instructions", "think_about_collected_information", "think_about_task_adherence", "think_about_whether_you_are_done", "list_memories", "read_memory", "execute_shell_command", "insert_after_symbol", "replace_symbol_body", "insert_before_symbol", "rename_symbol", "restart_language_server", "create_text_file", "replace_content", "delete_lines", "replace_lines", "insert_at_line", "remove_project", "switch_modes", "open_dashboard", "onboarding", "prepare_for_new_conversation", "summarize_changes", "write_memory", "delete_memory", "rename_memory", "edit_memory", "serena_mcp_reset"],
+    "HIGH": ["serena_list_tools", "find_symbol", "find_referencing_symbols", "read_file", "get_symbols_overview", "jet_brains_get_symbols_overview", "jet_brains_find_symbol", "jet_brains_find_referencing_symbols", "jet_brains_type_hierarchy", "search_for_pattern", "list_dir", "find_file", "get_current_config", "activate_project", "check_onboarding_performed", "initial_instructions", "think_about_collected_information", "think_about_task_adherence", "think_about_whether_you_are_done", "list_memories", "read_memory", "execute_shell_command", "insert_after_symbol", "replace_symbol_body", "insert_before_symbol", "rename_symbol", "restart_language_server", "create_text_file", "replace_content", "delete_lines", "replace_lines", "insert_at_line", "remove_project", "switch_modes", "open_dashboard", "onboarding", "prepare_for_new_conversation", "summarize_changes", "write_memory", "delete_memory", "rename_memory", "edit_memory", "serena_mcp_reset"]
+  }
+}

package/config/mandatory-rules/README.md

@@ -7,17 +7,18 @@ behaviors the model must follow regardless of the specific task.
 > Filter with `sp list-rules --rule <id>` or `sp list-rules --specialist <name>`,
 > machine output via `--json`.
 
-## Layout (three tiers)
+## Layout (four tiers)
 
-The loader reads and unions indexes from three paths, in this precedence:
+The loader reads and unions indexes from four paths, in this precedence:
 
 | Tier | Path | Writer | Role |
 |------|------|--------|------|
-| 1. Source | `config/mandatory-rules/` | specialists repo commits | Canonical source of truth. Ships with the tool. |
-| 2. Canonical copy | `.specialists/default/mandatory-rules/` | `sp init --sync-defaults` | Mirror of canonical, placed in every downstream project. |
-| 3. Overlay | `.specialists/mandatory-rules/` | you (per-repo) | Repo-specific additions and overrides. Wins on set-id conflict. |
+| 1. User overlay | `.specialists/user/mandatory-rules/` | you (per-repo) | Highest-priority repo-specific additions and overrides. Wins on set-id conflict. |
+| 2. Source | `config/mandatory-rules/` | specialists repo commits | Canonical source of truth. Ships with the tool. |
+| 3. Canonical copy | `.specialists/default/mandatory-rules/` | `sp init --sync-defaults` | Mirror of canonical, placed in every downstream project. |
+| 4. Overlay | `.specialists/mandatory-rules/` | you (per-repo) | Repo-specific additions and overrides. Wins on set-id conflict. |
 
-A rule set defined in tier 3 overrides a same-id rule set from tier 2 or 1,
+A rule set defined in tier 4 overrides a same-id rule set from tier 3, 2, or 1,
 letting a repo tailor or replace canonical rules without editing the source.
 
 ## What gets injected

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

@@ -2,49 +2,37 @@
 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.
+SINGLE PURPOSE. You exist to fill or top-up the `[Unreleased]` block of `CHANGELOG.md` from xt session reports + commit subjects. Nothing else. The `/releasing` skill (not you) bumps the version, runs the build, commits, tags, pushes, and publishes.
 
-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 WHITELIST. You may write to ONLY:
+- `CHANGELOG.md`
 
 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)
+- `package.json`, `package-lock.json`, `bun.lock`, `pnpm-lock.yaml`
+- `dist/**` (regenerated by `npm run build` — out of your scope)
+- `src/**`, `tests/**`, `docs/**`, `config/**`
+- `.specialists/**`, `.xtrm/**`, `.wolf/**`, `.beads/**`
+- `README.md`, `CLAUDE.md`, `AGENTS.md`, `XTRM-GUIDE.md`
 - 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.
+If a file outside the whitelist seems necessary, 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.
+INPUT DISCIPLINE. Your synthesis input is xtrm session reports under `.xtrm/reports/`. The bead's SCOPE/RANGE names the relevant tag range. Read reports with `Read` and decide which apply. Supplement with `git log --oneline <prev-tag>..HEAD` for commit verification. Do not crawl `src/`, `docs/`, or other source. Reports are pre-filtered, curated 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).
+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`.
+EDIT TARGET. The `[Unreleased]` block at the top of `CHANGELOG.md`. Preserve its heading shape and any existing bullets. Merge missing entries into the correct subsections. Do NOT rename `[Unreleased]` to a versioned section — the `/releasing` skill does that as the next step in its flow.
 
-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.
+NO INVENTION. Every bullet you add must trace to either a session report under `.xtrm/reports/` or a commit subject in the named range. If a commit lacks a covering report and is plausibly user-facing, add a one-line bullet referenced to the commit; flag the synthesis in your output.
 
-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 RELEASE OPS. NEVER run any of: `npm run build`, `npm publish`, `git add` (other than `CHANGELOG.md`), `git commit`, `git tag`, `git push`, `gh release`. NEVER edit `package.json` or `package-lock.json`. NEVER `git reset --hard`, `git push --force`, delete tags, or rewrite history. The `/releasing` skill performs all of these after you return.
 
-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.
+NO DESTRUCTIVE OPS. If a prior `[Unreleased]` block contains entries that look wrong, do NOT delete them. Add what is missing and report the suspected drift in your output. The operator decides whether to prune.
 
-SELF-VERIFY. Before finishing, run `git diff --stat HEAD~1 HEAD` and confirm the result matches:
+SELF-VERIFY. Before finishing, run `git status --short` 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.
+If anything else appears, 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.
+OUTPUT SHAPE. Final report must include: `VERDICT: <FILLED|NO_GAPS|BLOCKED>`, `RANGE: <prev-tag>..<ref>`, `ADDED_BULLETS: <count>`, `SYNTHESIZED_FROM_COMMITS: <count or 0>`, `FILES_CHANGED: CHANGELOG.md`, `NOTES: <one line about anything notable, e.g. dropped older reports, commits without reports>`. On BLOCKED, name the precondition violated.

package/config/mandatory-rules/code-quality-defaults.md

@@ -0,0 +1,5 @@
+---
+name: code-quality-defaults
+kind: mandatory-rule
+---
+SRP, DRY, KISS, YAGNI. No premature abstraction. No speculative features. Don't add comments to explain what well-named code already says. Match existing project conventions; never invent a new style mid-file.

package/config/mandatory-rules/diagnose-loop.md

@@ -0,0 +1,13 @@
+---
+name: diagnose-loop
+kind: mandatory-rule
+---
+Trace symptom to root cause before editing. Pinpoint suspects via stack trace and call graph, apply the minimal fix on the fault line, then verify. Do not refactor surrounding code, change style, or expand scope. Cite evidence as `file:line` for every claim.
+
+Discipline:
+
+- Build a fast deterministic feedback loop before any code change. If you cannot reproduce the symptom, report it as a blocker — do not patch in the dark.
+- After reproducing, write 3–5 falsifiable hypotheses before touching code. Test one variable at a time.
+- Tag any temporary instrumentation with `[DEBUG-<short-id>]` so it is greppable. Remove every tagged line before completing the fix.
+- When a correct test seam exists, convert the minimized repro into a regression test. When it does not, name the missing seam as an architecture/testability finding and route it to overthinker or planner instead of forcing a brittle test.
+- Verify with targeted lint/typecheck and the focused repro. Full suites belong to test-runner — do not run them yourself.

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

@@ -8,6 +8,7 @@ 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>"`.
+- Execution flow trace: `gitnexus_query({query: "<flow-keyword>"})` (process-grouped results) or read the MCP resource `gitnexus://repo/<name>/process/<flow-name>` for the step-by-step trace.
 - Pre-commit scope check: `gitnexus_detect_changes()` (MCP only — fallback: `git diff --stat`).
 
 Rules:

package/config/mandatory-rules/research-tool-routing.md

@@ -0,0 +1,12 @@
+---
+name: research-tool-routing
+kind: mandatory-rule
+---
+Pick the right source before invoking research. Default to the project knowledge graph and repo evidence first; reach for external tools only when the answer cannot come from local sources.
+
+- `find-docs` / context7 — library, framework, SDK, CLI, or cloud-service docs (API syntax, config, migration).
+- `deepwiki` — public GitHub repo internals (architecture, conventions, code paths).
+- `github-search` (ghgrep) — real-world code patterns and API usage examples.
+- `last30days` — recent web/social signals (Reddit, X, HN, YouTube). Early-warning only, never authoritative.
+
+Invoke skills on demand, not by default. Cite the source for every external claim.

package/config/mandatory-rules/security-review-defaults.md

@@ -0,0 +1,9 @@
+---
+name: security-review-defaults
+kind: mandatory-rule
+---
+Scan-only stance. Do not edit files, modify dependencies, run destructive tools, exfiltrate secrets, or run exploits against live targets. Recommend fixes; let executor apply them in a separate bead.
+
+Threat-model surfaces: auth, session, input validation, injection sinks, file upload, SSRF, deserialization, secrets and crypto, dependency CVEs, agent/MCP/hook config, prompt-injection vectors.
+
+Evidence required for any finding: a local path with line/symbol, an audit-tool output line, or an authoritative advisory (OSV, GHSA, NVD/CVE, vendor). Community chatter cannot be the sole proof. Keep findings to plausible user-controlled paths to a meaningful sink; drop low-signal noise.

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

@@ -5,6 +5,9 @@ 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."
+
+  # --- Read tier (always applicable) ---
+
   - 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."
@@ -23,18 +26,27 @@ rules:
   - 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."
+
+  # --- Edit tier (apply only if your specialist permission_required is MEDIUM or HIGH; READ_ONLY skip) ---
+
+  - id: edit-tier-applicability
+    level: info
+    text: "The rules below are edit-only. If your specialist's permission_required is READ_ONLY, ignore them — you cannot call these tools and they do not apply to your work."
   - 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)."
+    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)."
+    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)."
+    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)."
+    text: "replace_content <path> <pattern> <replacement> — line-range or regex edits when no symbol target fits. (MEDIUM+ permission)"
+
+  # --- Cost guidance ---
+
   - 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/presets.json

@@ -2,7 +2,7 @@
   "cheap": {
     "description": "Low-cost, fast responses — best for exploration and simple tasks",
     "fields": {
-      "specialist.execution.model": "dashscope/qwen3.5-plus",
+      "specialist.execution.model": "nano-gpt/moonshotai/kimi-k2.5",
       "specialist.execution.thinking_level": "off",
       "specialist.execution.stall_timeout_ms": 60000
     }

package/config/skills/memory-audit-transaction/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: memory-audit-transaction
+kind: skill
+---
+
+# Memory Audit Transaction
+
+Pattern for auditing the project's persistent bd memories at any scale (N=500, N=2000+) without exhausting the agent's context window.
+
+The naive workflow — `bd memories` → per-key `bd recall` → per-entry classification text in chat → per-key `bd forget` — collapses past ~150-200 memories because every classification row cumulates in conversation history. This skill replaces it with a **transactional file-backed audit ledger**: per-entry decisions persist to a JSONL artifact on disk, chunked work bounds the per-turn token cost, and pruning happens through one hash-guarded batch step rather than N inline `bd forget` calls.
+
+## When This Activates
+
+- The memory-processor specialist's input bead targets `.xtrm/memory.md` consolidation
+- Project has more than ~50 bd memories (`bd memories | wc -l`)
+- A previous memory-processor run hit context CRITICAL or produced "all current" without per-entry evidence
+
+## Workflow
+
+### Phase 1 — Read existing synthesized memory
+
+Read `.xtrm/memory.md` if present. Single Read call. Tells you what was synthesized last time and prevents regressions.
+
+### Phase 2 — Read last 3 session reports (targeted sections)
+
+For each of the latest 3 `.xtrm/reports/*.md`, extract only:
+- `## Summary`
+- `## Problems Encountered`
+- `## Memories Saved`
+- `## Suggested Next Priority`
+
+Ignore everything else. These are the highest-signal sections.
+
+### Phase 3 — Bulk-export memories (already done by pre-script)
+
+The specialist's pre-script (`config/skills/memory-audit-transaction/scripts/pre-bulk-export.sh`, registered in `skills.scripts` phase=pre) has **already executed before your first turn** and produced three artifacts:
+
+- `.tmp/memory-audit/memories.json` — full `{key: content}` JSON object from one `bd memories --json` call (single dolt query, no per-key round-trips)
+- `.tmp/memory-audit/keys.txt` — one key per line, for chunking
+- `.tmp/memory-audit/decisions.jsonl` — initialized empty, you append to it
+
+Verify the pre-script summary in `$pre_script_output` (injected at the top of the task). Confirm `keys.txt` count matches expectation. Do NOT re-export — running `bd recall` 500+ times in your bash window WILL time out (~150-300ms per call × 500 = 75-150s vs 120s bash stall window). The pre-script bypasses that entirely.
+
+Read a chunk's content by slicing the JSON object:
+
+```bash
+# extract the next 20-30 keys for this chunk
+sed -n '1,30p' .tmp/memory-audit/keys.txt > .tmp/memory-audit/chunk-1-keys.txt
+# fetch their content from the bulk JSON
+jq --slurpfile keys <(jq -R . .tmp/memory-audit/chunk-1-keys.txt | jq -s .) \
+   'with_entries(select(.key as $k | $keys[0] | index($k)))' \
+   .tmp/memory-audit/memories.json > .tmp/memory-audit/chunk-1.json
+```
+
+Simpler if jq feels heavy — just read keys.txt for the chunk's slice and look up each key with `jq -r --arg k "<key>" '.[$k]' memories.json` one at a time in a bash heredoc. Either way, the dump is on disk; do NOT echo memories.json into chat.
+
+### Phase 4 — Fill gaps from project state (single pass)
+
+One Bash call combining several quick reads:
+
+```bash
+git log --oneline -30
+cat CLAUDE.md 2>/dev/null | head -100
+cat README.md 2>/dev/null | head -50
+```
+
+Use this as the cross-reference baseline for Phase 5 classification.
+
+### Phase 5 — Chunked classification with on-disk ledger
+
+Read `.tmp/memory-audit/keys.txt` to know how many memories there are. Process them in **chunks of 20-30 keys**. For each chunk:
+
+1. Read only the slice of `memories.txt` for the chunk's keys (use `awk`/`sed` to extract `=== key ===` … blocks for the N keys in this chunk).
+2. For each memory in the chunk, decide its classification using the cross-reference baseline from Phase 4 plus targeted file spot-checks where needed.
+3. **Append decisions to `.tmp/memory-audit/decisions.jsonl`** — one JSON line per memory:
+
+   ```json
+   {"key":"<memory-key>","content_hash":"sha256:<hex>","status":"Current|Stale|Contradicted|Redundant|Skipped","confidence":"high|medium|low","evidence":["file:line or memory-key or report-ref"],"reason":"one sentence","duplicate_of":"optional-key"}
+   ```
+
+4. **Do NOT print the decisions to chat**. Use a single Bash heredoc to append the chunk's rows to the JSONL file. The chat-side summary for each chunk is just one line: `chunk N: X classified (Current=a, Stale=b, Contradicted=c, Redundant=d, Skipped=e)`.
+
+5. After each chunk, optionally write a checkpoint marker file `.tmp/memory-audit/chunk-N.done` so a re-dispatch can resume.
+
+Compute `content_hash` with `sha256sum` against the exact `bd recall` output captured in Phase 3. The hash will be re-verified at Phase 7 apply time.
+
+### Phase 6 — Ledger completeness validation (HARD GATE)
+
+Before writing `.xtrm/memory.md`:
+
+```bash
+KEYS=$(wc -l < .tmp/memory-audit/keys.txt)
+ROWS=$(wc -l < .tmp/memory-audit/decisions.jsonl)
+echo "keys=${KEYS} rows=${ROWS}"
+test "${KEYS}" = "${ROWS}" || { echo "INCOMPLETE — missing $((KEYS - ROWS)) decisions"; exit 1; }
+```
+
+If the count does not match, the audit is incomplete. **Do not proceed to Phase 7 or Phase 8**. Report the gap and stop. Never default missing rows to `Current` to "make it work" — that is the c791ef failure mode (`bead unitAI-aofbp` empirical evidence).
+
+### Phase 7 — Atomic prune with hash guard
+
+When bd CLI gains `bd forget --batch --apply --if-hash-matches --transaction --backup` (tracked in Phase B of the parent epic, `unitAI-pwojn.2`), use it directly. Until then, the Phase A fallback is a single bash loop that re-verifies the hash before each delete and writes a backup:
+
+```bash
+mkdir -p .tmp/memory-audit/backup
+PRUNED=0; SKIPPED_HASH=0
+jq -c 'select(.status=="Stale" or .status=="Contradicted" or .status=="Redundant")' \
+  .tmp/memory-audit/decisions.jsonl > .tmp/memory-audit/prune-set.jsonl
+
+while read -r row; do
+  key=$(echo "${row}" | jq -r .key)
+  want_hash=$(echo "${row}" | jq -r .content_hash | sed 's/^sha256://')
+  have_hash=$(bd recall "${key}" 2>/dev/null | sha256sum | awk '{print $1}')
+  if [ "${want_hash}" = "${have_hash}" ]; then
+    bd recall "${key}" > ".tmp/memory-audit/backup/${key}.txt"
+    bd forget "${key}" && PRUNED=$((PRUNED + 1))
+  else
+    SKIPPED_HASH=$((SKIPPED_HASH + 1))
+    echo "${key}: hash mismatch — skipping" >> .tmp/memory-audit/apply-log.txt
+  fi
+done < .tmp/memory-audit/prune-set.jsonl
+
+echo "pruned=${PRUNED} skipped_hash=${SKIPPED_HASH}"
+```
+
+The chat output stays the count line only. The list of pruned keys lives in the apply-log file on disk; the report links to it.
+
+### Phase 8 — Write .xtrm/memory.md from Current rows
+
+Use `jq` to filter `decisions.jsonl` to only `Current` entries, then synthesize the 3-section `.xtrm/memory.md`:
+
+```markdown
+# Project Memory — <project-name>
+_Updated: <YYYY-MM-DD> | <N-current> memories synthesized, <N-pruned> pruned, <N-skipped> skipped | last session: <YYYY-MM-DD>_
+
+## Do Not Repeat
+- ❌ <wrong action> → ✅ <correct action>
+
+## How This Project Works
+- <directive bullet>
+
+## Active Context
+- <situational brief from last 2-3 session reports>
+```
+
+Target 100-200 lines. Imperative voice. No descriptive prose. Each bullet ends in "do Y" or "never Z".
+
+### Phase 9 — Final report (counts only, NOT per-entry text)
+
+```
+## Memory Processor Report
+
+### Synthesized → .xtrm/memory.md
+<N> memories synthesized into 3 sections (~<line count> lines)
+
+### Pruned (<N> applied, <M> hash-mismatch-skipped)
+See `.tmp/memory-audit/apply-log.txt` for the full list and `.tmp/memory-audit/backup/` for restore data.
+
+### Kept in bd (<N> entries)
+Raw detail store intact. Use `bd recall <key>` to dig deeper.
+
+### Ledger artifact
+`.tmp/memory-audit/decisions.jsonl` (one row per memory, every status decision evidence-backed).
+```
+
+## Conservative-Pruning Rule (Inviolable)
+
+When in doubt, **status=Skipped** — never default to Current. A false negative (slightly stale memory survives) is less harmful than a false positive (delete still-relevant entry). The completeness validator (Phase 6) ensures missing rows do not slip through as "all current."
+
+## Decision-Row Evidence Requirements
+
+Every row in `decisions.jsonl` must have non-empty `evidence`. Acceptable evidence forms:
+
+- `"src/foo.ts:42"` — file:line reference verified against current repo
+- `"memory:other-key"` — duplicate-of reference to another existing memory
+- `"reports/2026-05-10:Summary"` — section reference in a recent session report
+- `"commit:abc1234"` — git commit hash that fixed/changed the memorialized behavior
+- `"unverifiable: <reason>"` — explicit acknowledgment when nothing concrete supports the classification → forces `status=Skipped`
+
+A row with status not in {Current, Skipped} and evidence `["unverifiable: …"]` is a contract violation and is treated as Skipped during Phase 7.
+
+## Failure-Mode Mapping
+
+| Past failure | Symptom | Guarded by |
+|---|---|---|
+| c791ef (deepseek pre-DSML-fix) | 82% context, false "all 507 current" without per-entry evidence | Phase 6 completeness validator + evidence requirement; missing/uncertain → Skipped |
+| fad36f (qwen with bulk-export) | 105% context, STALE for 80s, then flailing into gitnexus_* + destructive git | Phase 5 chunked decisions written to disk not chat; Phase 7 single batch not N inline forget; prompt forbids git sync commands |
+
+## Anti-Patterns (Do Not)
+
+- **Do not** echo `bd recall` output into chat. Read from `.tmp/memory-audit/memories.txt` slice instead.
+- **Do not** classify multiple chunks worth of memories in one turn. Cap N at 20-30 per chunk.
+- **Do not** emit per-entry decision text to chat. Append to the JSONL ledger; chat gets the count summary.
+- **Do not** run `bd forget` inline per decision. Always go through Phase 7 batch path.
+- **Do not** run `git pull --rebase`, `git push`, `git reset --hard`, or any destructive git command. The memory audit is a project-local read+forget+single-file-write operation. No remote sync, no history rewrite.
+- **Do not** proceed to Phase 8 if Phase 6 completeness check fails. Stop and report the gap.