@jaggerxtrm/specialists 3.14.1 → 3.15.1

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/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.

package/config/skills/memory-audit-transaction/scripts/pre-bulk-export.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Pre-script for the memory-processor specialist.
+#
+# Phase 3 of the memory-audit-transaction skill: bulk-export every bd memory
+# to a single JSON artifact so the model can slice chunks without per-key
+# round-trips at runtime.
+#
+# `bd memories --json` returns one JSON object {key: content, ...} from a
+# single dolt query (~ms), independent of N. This is the bulk surface that
+# makes the Transactional File-Backed Audit Ledger pattern viable at any
+# scale.
+#
+# Output:
+#   .tmp/memory-audit/memories.json   — full {key: content} object
+#   .tmp/memory-audit/keys.txt        — one key per line
+#   .tmp/memory-audit/decisions.jsonl — initialized empty (model appends)
+#
+# stdout: one-line summary that the runner injects as $pre_script_output.
+
+set -euo pipefail
+
+ART_DIR=".tmp/memory-audit"
+mkdir -p "${ART_DIR}"
+
+# Refuse to clobber an in-flight ledger (resumable runs land here).
+if [ -s "${ART_DIR}/decisions.jsonl" ] && [ -s "${ART_DIR}/memories.json" ]; then
+  KEYS_PREV=$(jq -r 'keys[]' "${ART_DIR}/memories.json" 2>/dev/null | wc -l || echo 0)
+  ROWS_PREV=$(wc -l < "${ART_DIR}/decisions.jsonl" 2>/dev/null || echo 0)
+  echo "RESUMABLE: ${ROWS_PREV}/${KEYS_PREV} decisions already in ${ART_DIR}/decisions.jsonl"
+  echo "          Bulk export skipped (artifact still present)."
+  exit 0
+fi
+
+# Bulk export — single dolt query, no per-key recall.
+bd memories --json > "${ART_DIR}/memories.json"
+
+# Key list (one per line) for chunking.
+jq -r 'keys[]' "${ART_DIR}/memories.json" > "${ART_DIR}/keys.txt"
+
+# Initialize the ledger (empty; model appends per-chunk).
+: > "${ART_DIR}/decisions.jsonl"
+
+KEYS=$(wc -l < "${ART_DIR}/keys.txt" | tr -d ' ')
+BYTES=$(wc -c < "${ART_DIR}/memories.json" | tr -d ' ')
+
+cat <<EOF
+Bulk export complete:
+  artifact:  ${ART_DIR}/memories.json
+  keys:      ${ART_DIR}/keys.txt (${KEYS} keys)
+  size:      ${BYTES} bytes
+  ledger:    ${ART_DIR}/decisions.jsonl (initialized empty)
+
+Read each chunk's content from memories.json with jq, e.g.:
+  jq -r --arg k "<key>" '.[\$k]' ${ART_DIR}/memories.json
+
+Append per-entry decisions to ${ART_DIR}/decisions.jsonl with bash heredocs.
+Do NOT echo memories.json into chat history.
+EOF

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

@@ -119,13 +119,13 @@ specialists status --job <job-id>             # single-job detail view (legacy
 # Epic lifecycle (canonical publication path)
 specialists epic list [--unresolved]          # list epics with lifecycle state
 specialists epic status <epic-id>             # show chains, blockers, readiness
-specialists epic sync <epic-id> [--apply]     # reconcile DB vs live state (dry-run default)
-specialists epic resolve <epic-id>            # transition open -> resolving
+specialists epic sync <epic-id> [--apply]     # recompute derived readiness; repair drift
 specialists epic abandon <epic-id> --reason <text> [--force]  # terminal transition for stuck epics
-specialists epic merge <epic-id> [--pr]       # publish all epic-owned chains
+specialists epic merge <epic-id> [--pr]       # publish all epic-owned chains; auto-finalizes PASS chains
 
-# Merge (for standalone chains only)
-specialists merge <chain-root-bead> [--rebuild]  # publish ONE standalone chain
+# Merge (per-chain or standalone; PASS chains can merge inside an active epic)
+specialists merge <chain-root-bead> [--rebuild]
+specialists finalize <chain-root-bead>           # manual recovery if PASS auto-finalize did not fire
 
 # Session close (chain-aware, epic-aware)
 specialists end [--pr]                        # close session, publish via merge or PR
@@ -682,14 +682,15 @@ sp epic list --unresolved   # show non-terminal epics
 
 # Inspect one epic
 sp epic status unitAI-3f7b
-# Shows: persisted_state, readiness_state, chains[], blockers[], summary
+# Shows: derived readiness state, persisted state (audit only), chains[], blockers[], summary
 
-# Transition states (manual)
-sp epic resolve unitAI-3f7b   # open → resolving
-
-# Publish
-sp epic merge unitAI-3f7b     # merge_ready → merged
+# Publish (no manual state transition — readiness is derived live)
+sp epic merge unitAI-3f7b     # batch publish all chains; auto-finalizes PASS chains
 sp epic merge unitAI-3f7b --pr # PR mode
+
+# Or per-chain (PASS chain inside active epic is allowed)
+sp merge <chain-root-bead>
+sp finalize <chain-root-bead>  # manual recovery if PASS auto-finalize missed
 ```
 
 ### Conflict handling
@@ -1136,7 +1137,7 @@ sp stop <job-id> --force
 
 ### 5) `sp end` open-state loop fix
 
-If `sp end` detects open-state mismatch, tool now suggests `sp epic resolve <epic-id>` as next command (no redirect loop).
+If `sp end` detects open-state mismatch, tool surfaces the derived readiness summary (`sp epic status <epic-id>`) and the per-chain merge path. There is no `sp epic resolve` anymore — readiness is recomputed live from chain state.
 
 - **RPC timeout on worktree job start** (30s, `command id=1`) → pi runs `npm install` in fresh
   worktrees if `.pi/settings.json` lists local packages. Root cause: worktree gets a stale copy