@jaggerxtrm/specialists 3.6.11 → 3.6.13

package/config/benchmarks/executor-benchmark-matrix.json

@@ -0,0 +1,25 @@
+{
+  "id": "unitAI-gc2a",
+  "replicate": 1,
+  "reviewerModel": "openai-codex/gpt-5.4-mini",
+  "models": [
+    "openai-codex/gpt-5.3-codex",
+    "openai-codex/gpt-5.4-mini",
+    "dashscope/qwen3.5-plus",
+    "zai/glm-5"
+  ],
+  "tasks": [
+    {
+      "id": "bug-fix",
+      "seedBead": "unitAI-y4ia"
+    },
+    {
+      "id": "refactor",
+      "seedBead": "unitAI-22tq"
+    },
+    {
+      "id": "implementation",
+      "seedBead": "unitAI-8zui"
+    }
+  ]
+}

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

@@ -0,0 +1,339 @@
+---
+name: update-specialists
+description: >
+  Reconcile a project with current canonical specialists install state.
+  Use this skill when a user says "update specialists", "specialists is broken",
+  "sp is out of date", "hooks not firing", "skills not loading after update",
+  or when drift is detected in installed specialists config, hooks, jobs, DB,
+  extensions, or worktree cleanup.
+version: 1.1
+synced_at: 00000000
+---
+
+# update-specialists
+
+Bring specialists install back to canonical state. Detect drift, apply targeted
+fixes, then verify with `sp doctor`. Treat canonical state as both:
+1. healthy repo wiring and runtime behavior, and
+2. parity with the currently installed `@jaggerxtrm/specialists` package version
+   when package-level comparison is available.
+
+## Canonical State
+
+Check each item explicitly. This is what a healthy specialists-initialized project
+looks like.
+
+### Package + runtime parity
+
+| Check | Expected value |
+|-------|----------------|
+| Installed `@jaggerxtrm/specialists` package version | Matches intended runtime version for repo install |
+| `sp --version` / `specialists --version` | Matches installed package version or same release line |
+| Installed package root | Resolvable from Node / npm environment |
+| Canonical package defaults | Available from installed package for direct diffing |
+| Repo install vs package install | No unexpected drift in canonical files unless intentionally customized |
+
+### Specialists configs
+
+| Check | Expected value |
+|-------|----------------|
+| `.specialists/default/*.specialist.json` | JSON-first specialist configs present |
+| `metadata.name` | Matches filename stem |
+| `metadata.version` | Valid semver string and consistent with canonical shipped copy when comparing like-for-like |
+| `metadata.description` | Present |
+| `metadata.category` | Present |
+| `execution.model` | Present and pingable |
+| `execution.fallback_model` | Present, different provider from primary |
+| `execution.permission_required` | Valid enum |
+| `skills.paths` | Referenced skill paths resolve correctly |
+| `execution.interactive` | Matches intended keep-alive behavior |
+| Installed default specialist copy | Matches canonical package copy unless intentionally customized |
+
+### Hooks wiring
+
+| Check | Expected value |
+|-------|----------------|
+| `.claude/settings.json` | Has hook entries for active events |
+| Hook events | At minimum: `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop` |
+| Hook paths | Point at specialists runtime hook scripts, not stale xtrm-only paths |
+| Hook format | Matches project's installed settings format and loads cleanly |
+| Installed hook scripts | Match canonical package hook files unless intentionally customized |
+
+### CLI reachability
+
+| Check | Expected value |
+|-------|----------------|
+| `sp` command | On PATH and runs |
+| `specialists` command | On PATH and runs |
+| Version compatibility | `sp doctor` reports matching runtime / install state |
+| Command surface | `sp doctor`, `sp init`, `sp clean`, `sp status` available |
+
+### Jobs and runtime dirs
+
+| Check | Expected value |
+|-------|----------------|
+| `.specialists/jobs/` | Exists |
+| `.specialists/ready/` | Exists if used by runtime |
+| `.specialists/default/` | Canonical install copy present |
+| Orphaned worktrees | None under `.worktrees/` |
+| Worktree ownership | No stale entries for deleted jobs |
+
+### SQLite / observability
+
+| Check | Expected value |
+|-------|----------------|
+| specialists DB | Opens cleanly |
+| Schema version | Matches runtime expectation |
+| WAL / busy timeout settings | Present when runtime uses SQLite |
+| Corruption / lock errors | None in `sp doctor` |
+
+### Skills + extensions parity
+
+| Check | Expected value |
+|-------|----------------|
+| `.xtrm/skills/default/` | Matches canonical package skill set for installed version |
+| Active skill links / copies | Resolve to expected default or active targets |
+| Skill frontmatter `version` / `synced_at` | Present and reasonable for shipped skills |
+| `quality-gates` | Registered if project uses quality gates |
+| `pi-gitnexus` | Registered when GitNexus integration is expected |
+| `pi-serena-tools` | Registered when Serena integration is expected |
+| Extension paths | Resolve from installed project, not stale workspace copies |
+
+## Detection
+
+Run these in order. Report which checks pass and which drift.
+
+```bash
+# 1. Primary health check
+sp doctor
+
+# 2. Runtime status
+sp status
+
+# 3. Installed package + CLI version parity
+npm ls @jaggerxtrm/specialists --depth=0 2>/dev/null || true
+node -e "try { const pkg=require(require.resolve('@jaggerxtrm/specialists/package.json')); console.log(JSON.stringify({installed_package_version: pkg.version}, null, 2)); } catch (err) { console.log('PACKAGE_NOT_RESOLVABLE'); }"
+sp --version 2>/dev/null || true
+specialists --version 2>/dev/null || true
+
+# 4. Resolve canonical package root for direct drift diff
+node -e "try { const path=require('path'); const pkgPath=require.resolve('@jaggerxtrm/specialists/package.json'); console.log(path.dirname(pkgPath)); } catch (err) { console.log('PACKAGE_ROOT_UNAVAILABLE'); }"
+
+# 5. Config shape
+find .specialists/default -maxdepth 1 -name '*.specialist.json' -print
+
+# 6. Validate specialist JSON files
+node -e "const fs=require('fs'); const path=require('path'); const dir='.specialists/default'; for (const file of fs.readdirSync(dir)) { if (!file.endsWith('.specialist.json')) continue; const s=JSON.parse(fs.readFileSync(path.join(dir,file),'utf8')); const m=s.metadata||{}; const e=s.execution||{}; const missing=[]; for (const key of ['name','version','description','category']) if (!m[key]) missing.push('metadata.'+key); for (const key of ['model','fallback_model','permission_required']) if (!e[key]) missing.push('execution.'+key); if (missing.length) console.log(file+': MISSING '+missing.join(', ')); if (m.name && m.name !== file.replace(/\.specialist\.json$/, '')) console.log(file+': NAME MISMATCH '+m.name); }"
+
+# 7. Validate referenced skill paths
+node -e "const fs=require('fs'); const path=require('path'); const dir='.specialists/default'; for (const file of fs.readdirSync(dir)) { if (!file.endsWith('.specialist.json')) continue; const s=JSON.parse(fs.readFileSync(path.join(dir,file),'utf8')); for (const p of (s.skills?.paths ?? [])) { if (!fs.existsSync(p)) console.log(file+': MISSING SKILL PATH '+p); } }"
+
+# 8. Compare repo defaults against installed package defaults (if package root resolvable)
+PKG_ROOT="$(node -e "try { const path=require('path'); process.stdout.write(path.dirname(require.resolve('@jaggerxtrm/specialists/package.json'))); } catch (err) {}")"
+if [ -n "$PKG_ROOT" ]; then
+  diff -rq .specialists/default "$PKG_ROOT/config/specialists" || true
+  diff -rq .xtrm/skills/default "$PKG_ROOT/config/skills" || true
+  diff -rq .claude/hooks "$PKG_ROOT/config/hooks" || true
+else
+  echo PACKAGE_COMPARE_UNAVAILABLE
+fi
+
+# 9. Hooks wiring
+node -e "const fs=require('fs'); const p='.claude/settings.json'; if (fs.existsSync(p)) { const s=JSON.parse(fs.readFileSync(p,'utf8')); console.log(JSON.stringify(s.hooks ?? s, null, 2)); } else { console.log('MISSING .claude/settings.json'); }"
+
+# 10. Command availability
+command -v sp
+command -v specialists
+specialists init --help | sed -n '1,120p'
+sp doctor --json 2>/dev/null || true
+
+# 11. Jobs and worktrees
+ls -1 .specialists/jobs 2>/dev/null || true
+find .worktrees -maxdepth 2 -mindepth 1 -type d 2>/dev/null || true
+
+# 12. Extension registration
+node -e "const fs=require('fs'); const p='.pi/settings.json'; if (fs.existsSync(p)) console.log(JSON.stringify(JSON.parse(fs.readFileSync(p,'utf8')).skills ?? JSON.parse(fs.readFileSync(p,'utf8')).extensions ?? {}, null, 2)); else console.log('MISSING .pi/settings.json')"
+
+# 13. Shipped skill frontmatter parity
+node -e "const fs=require('fs'); const path=require('path'); const dir='.xtrm/skills/default'; if (!fs.existsSync(dir)) process.exit(0); for (const name of fs.readdirSync(dir)) { const p=path.join(dir,name,'SKILL.md'); if (!fs.existsSync(p)) continue; const head=fs.readFileSync(p,'utf8').split('---')[1] || ''; const version=(head.match(/version:\s*([^\n]+)/)||[])[1]; const synced=(head.match(/synced_at:\s*([^\n]+)/)||[])[1]; console.log(name+': version='+(version||'missing')+' synced_at='+(synced||'missing')); }"
+```
+
+## Drift -> Fix Mapping
+
+Use targeted fixes first. Escalate to full sync only if needed.
+
+| Drift | Fix |
+|-------|-----|
+| Installed package version mismatch | reinstall / upgrade `@jaggerxtrm/specialists`, then re-run checks |
+| CLI version mismatch vs package | reinstall runtime so `sp` / `specialists` align with installed package |
+| Specialist JSON missing required fields | `sp edit <name> ...` or regenerate via `specialists init --sync-defaults` |
+| Specialist JSON schema mismatch | `specialists init --sync-defaults` |
+| Installed specialist default differs from canonical package copy | `specialists init --sync-defaults` unless local customization is intentional |
+| Hooks missing or stale | `specialists init` |
+| Installed hook file differs from canonical package copy | `specialists init` unless local customization is intentional |
+| `sp` / `specialists` missing from PATH | Reinstall / re-bootstrap specialists runtime |
+| Job dir missing | `specialists init` |
+| Orphaned `.worktrees/` entries | `specialists clean` |
+| SQLite schema/version mismatch | `sp doctor` first, then `specialists init --sync-defaults` or runtime migration command |
+| Pi extensions missing | `specialists init --sync-skills` or reinstall extension registration |
+| Hook config format stale | `specialists init` |
+| Skill symlink / active-skill drift | `specialists init --sync-skills` |
+| Installed default skill differs from canonical package copy | `specialists init --sync-skills` unless local customization is intentional |
+| Skill frontmatter version / synced_at drift | `specialists init --sync-skills` or refresh packaged skills |
+| Unknown manual drift | Stop, inspect, then apply user-approved fix |
+
+## Remediation
+
+### Fix: Package/runtime version drift
+
+If installed npm package version, CLI version, or package root parity checks disagree:
+
+```bash
+npm ls @jaggerxtrm/specialists --depth=0
+specialists --version
+sp --version
+```
+
+If versions do not align, reinstall or upgrade the package first. After runtime
+version is correct, re-run `specialists init` / sync commands to repair repo drift.
+
+### Fix: Specialist configs drifted
+
+If `sp doctor`, JSON validation, or direct diff against package canonical defaults
+shows missing fields, wrong names, or schema mismatch:
+
+```bash
+specialists init --sync-defaults
+```
+
+If one specialist needs a small repair and `sp edit` supports it, prefer that over
+full sync.
+
+### Fix: Hooks not firing
+
+If hooks are missing, wrong events, stale script paths, or hook files differ from
+installed package canonical copies:
+
+```bash
+specialists init
+```
+
+If runtime exposes a narrower hook sync command, prefer it. Use full init only
+when hook-only sync is not enough.
+
+### Fix: CLI not reachable
+
+If `sp` or `specialists` is missing or incompatible:
+
+```bash
+sp doctor
+```
+
+If doctor confirms install drift, reinstall or re-bootstrap specialists runtime.
+Do not guess at file edits when command surface itself is broken.
+
+### Fix: Job dirs or worktree GC drift
+
+If jobs exist without owners, worktrees are orphaned, or cleanup state is stale:
+
+```bash
+specialists clean
+```
+
+Then re-run `sp doctor`.
+
+### Fix: SQLite schema drift
+
+If doctor reports DB version mismatch or recovery issue:
+
+1. Run `sp doctor` and capture exact schema error.
+2. Apply runtime migration command if available.
+3. If no automated migration exists, flag manual intervention.
+
+### Fix: Skills/defaults differ from shipped package copy
+
+If diff against the installed package shows `.specialists/default/`,
+`.xtrm/skills/default/`, or `.claude/hooks/` drift from shipped canonical files:
+
+- If drift is intentional project customization, report it and do not overwrite silently.
+- If drift is unintentional, use the narrowest sync that fixes the affected area:
+
+```bash
+specialists init --sync-defaults
+specialists init --sync-skills
+specialists init
+```
+
+### Fix: Pi extensions not registered
+
+If `quality-gates`, `pi-gitnexus`, or `pi-serena-tools` are missing:
+
+```bash
+specialists init --sync-skills
+```
+
+If project uses different extension packaging, re-run install step that writes
+`.pi/settings.json`.
+
+## Verification
+
+After fixes, confirm canonical state restored.
+
+```bash
+sp doctor
+sp status
+npm ls @jaggerxtrm/specialists --depth=0 2>/dev/null || true
+specialists --version 2>/dev/null || true
+sp --version 2>/dev/null || true
+
+node -e "const fs=require('fs'); const p='.claude/settings.json'; const s=JSON.parse(fs.readFileSync(p,'utf8')); console.log(Boolean(s.hooks || Object.keys(s).length))"
+```
+
+Expected outcome:
+- `sp doctor` clean
+- `sp status` no drift / no repair hints
+- `sp` and `specialists` reachable (`sp` is shorthand; `specialists` is canonical)
+- installed package / CLI versions aligned
+- specialist JSON files valid
+- repo defaults match installed package defaults (or intentional custom drift acknowledged)
+- hooks present on required events and canonical hook files match installed package copy
+- no orphaned worktrees
+- SQLite state healthy
+
+## Manual Intervention
+
+Flag these when automatic fix is unsafe or impossible:
+
+- `sp doctor` reports corrupt DB / unreadable SQLite file
+- command surface missing because install itself is broken
+- hook scripts absent from repo and cannot be regenerated
+- schema mismatch with no available migration path
+- worktree cleanup would remove user changes
+- extensions required by project are not installed at package level
+- package root is unavailable, so package-vs-installed diff cannot be computed
+- repo intentionally diverges from canonical package copies and user must preserve customizations
+
+When manual intervention needed, report:
+1. exact drift
+2. exact command tried
+3. why auto-fix stopped
+4. next safe operator action
+
+## User Summary Format
+
+After detection + remediation, answer with compact status:
+
+```text
+## specialists update complete
+
+✓ sp doctor clean
+✓ package / CLI versions aligned
+✓ specialist configs valid
+✓ hooks wired
+✓ canonical package parity checked
+✓ jobs/worktrees clean
+✓ SQLite healthy
+✓ extensions registered
+
+[manual items, if any]
+```

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

@@ -29,6 +29,27 @@ Specialists are autonomous AI agents that run independently — fresh context, d
 
 ---
 
+## Response Style Policy
+
+- Be direct, concise, and professional.
+- Answer the user's actual question first, in the first sentence when possible.
+- Do not append conversational filler like:
+  - "If you want, I can..."
+  - "I can also..."
+  - "Let me know if you want..."
+  unless the user explicitly asked for options.
+- Do not restate context the user already provided unless needed to resolve ambiguity.
+- Prefer short conclusions over long explanatory structures.
+- Use bullets only when they improve clarity; otherwise respond in plain prose.
+- Do not hedge unnecessarily. If the answer is clear, state it plainly.
+- Do not give a recommendation section unless the user asked for recommendations or a decision.
+- Do not propose next steps automatically after every answer.
+- When reporting status, give:
+  1. current state
+  2. blocker or result
+  3. only the next action if action is already implied or necessary
+- Default to terse operational language, not coaching language.
+
 ## Hard Rules
 
 1. **Zero implementation by orchestrator.** When this skill is active for substantial work, you do not implement the solution yourself.

package/config/specialists/debugger.specialist.json

@@ -33,7 +33,7 @@
       "max_retries": 0
     },
     "prompt": {
-      "system": "Autonomous debugger specialist. Given symptom, error, or stack trace \u2014 conduct disciplined, tool-driven investigation. Find root cause, apply targeted fix, verify.\n\nNOT executor. Fix bugs only \u2014 no refactor, no features, no improvements beyond resolving specific issue.\n\n## Investigation Workflow\n\nWork through phases in order.\n\n### Phase 0 \u2014 GitNexus Triage (preferred, skip if unavailable)\n\nUse knowledge graph to orient before touching source files.\n\n1. `gitnexus_query({query: \"<error text or symptom>\"})`\n2. `gitnexus_context({name: \"<suspect symbol>\"})`\n3. Read `gitnexus://repo/{name}/process/{processName}` for execution trace details\n4. Optional: `gitnexus_cypher({query: \"MATCH path = ...\"})` for custom traversal\n\nThen read source files only for pinpointed suspects \u2014 never whole codebase.\n\n### Phase 1 \u2014 File Discovery (fallback if GitNexus unavailable)\n\nParse symptom for candidate locations:\n- stack trace file paths + line numbers\n- module/import names in errors\n- error codes or exception types tied to subsystems\n\nUse `grep` and `find` to locate code quickly; read only relevant sections.\n\n### Phase 2 \u2014 Root Cause Analysis\n\nDetermine:\n- exact line/expression causing failure\n- causal explanation of observed symptom\n- whether root cause or downstream effect\n- likely side effects on related components\n\n### Phase 3 \u2014 Apply Fix\n\nOnce root cause confirmed:\n- Edit minimum code needed to fix bug\n- Do NOT refactor surrounding code, add comments, or improve style\n- Run lint and tsc to verify fix compiles\n- Do NOT run tests (test-runner specialist handles that)\n\n### Phase 4 \u2014 Verify\n\nRun specific failing command, test, or reproduction step that triggered bug.\nPass \u2192 report success. Still fails \u2192 return Phase 2 with new evidence.\n\n## Keep-Alive Behavior\n\nAfter delivering initial fix + verification:\n- Enter waiting state\n- Orchestrator may resume with \"still failing\" or \"new error after fix\"\n- Each resume cycle: re-diagnose \u2192 fix \u2192 verify\n- Issue fully resolved \u2192 report final status, exit\n\n## Output Format\n\nAlways output complete **Bug Investigation Report**:\n- Symptoms\n- Investigation path (GitNexus traces or files analyzed)\n- Root cause (with file:line references)\n- Fix applied (files changed, what changed)\n- Verification result (pass/fail + command output)\n- Concise summary\n\nEFFICIENCY RULE: Stop investigation, move to fix after at most 15 tool calls.\nNo over-investigate \u2014 form hypothesis, fix, verify.",
+      "system": "Autonomous debugger specialist. Given symptom, error, or stack trace \u2014 conduct disciplined, tool-driven investigation. Find root cause, apply targeted fix, verify.\n\nNOT executor. Fix bugs only \u2014 no refactor, no features, no improvements beyond resolving specific issue.\n\n## Investigation Workflow\n\nWork through phases in order.\n\n### Phase 0 \u2014 GitNexus Triage (preferred, skip if unavailable)\n\nUse knowledge graph to orient before touching source files.\n\n1. `gitnexus_query({query: \"<error text or symptom>\"})`\n2. `gitnexus_context({name: \"<suspect symbol>\"})`\n3. Read `gitnexus://repo/{name}/process/{processName}` for execution trace details\n4. Optional: `gitnexus_cypher({query: \"MATCH path = ...\"})` for custom traversal\n\nThen read source files only for pinpointed suspects \u2014 never whole codebase.\n\n### Phase 1 \u2014 File Discovery (fallback if GitNexus unavailable)\n\nParse symptom for candidate locations:\n- stack trace file paths + line numbers\n- module/import names in errors\n- error codes or exception types tied to subsystems\n\nUse `grep` and `find` to locate code quickly; read only relevant sections.\n\n### Phase 2 \u2014 Root Cause Analysis\n\nDetermine:\n- exact line/expression causing failure\n- causal explanation of observed symptom\n- whether root cause or downstream effect\n- likely side effects on related components\n\n### Phase 3 \u2014 Apply Fix\n\nOnce root cause confirmed:\n- Edit minimum code needed to fix bug\n- Do NOT refactor surrounding code, add comments, or improve style\n- Run lint and tsc to verify fix compiles\n- Stage ALL changes including new files: `git add -A` — do this before the turn ends\n- Do NOT run tests (test-runner specialist handles that)\n\n### Phase 4 \u2014 Verify\n\nRun specific failing command, test, or reproduction step that triggered bug.\nPass \u2192 report success. Still fails \u2192 return Phase 2 with new evidence.\n\n## Keep-Alive Behavior\n\nAfter delivering initial fix + verification:\n- Enter waiting state\n- Orchestrator may resume with \"still failing\" or \"new error after fix\"\n- Each resume cycle: re-diagnose \u2192 fix \u2192 verify\n- Issue fully resolved \u2192 report final status, exit\n\n## Output Format\n\nAlways output complete **Bug Investigation Report**:\n- Symptoms\n- Investigation path (GitNexus traces or files analyzed)\n- Root cause (with file:line references)\n- Fix applied (files changed, what changed)\n- Verification result (pass/fail + command output)\n- Concise summary\n\nEFFICIENCY RULE: Stop investigation, move to fix after at most 15 tool calls.\nNo over-investigate \u2014 form hypothesis, fix, verify.",
       "task_template": "Debug the following issue:\n\n$prompt\n\n$reused_worktree_awareness\n\nWorking directory: $cwd\n\n## Required investigation steps:\n1. `gitnexus_query({query: \"<error text or symptom>\"})` \u2014 find related execution flows\n2. `gitnexus_context({name: \"<suspect symbol>\"})` \u2014 trace callers and callees\n3. Read source files ONLY for pinpointed suspects from steps 1-2\n4. `gitnexus_impact` on any symbol before modifying it\n5. Apply fix, then `gitnexus_detect_changes()` to verify scope\n\nDo NOT skip steps 1-2 by going straight to grep/find.\n"
     },
     "skills": {

package/config/specialists/executor.specialist.json

@@ -29,7 +29,7 @@
       "mode": "auto"
     },
     "prompt": {
-      "system": "# Expert Code Executor — Production Standards\n\nSenior implementation specialist. Receive task specs, deliver production-quality code. Write code directly — no tutorials, no explanations unless logic genuinely non-obvious.\n\n---\n\n## Core Principles\n\n**SRP** — Single Responsibility. Every function does ONE thing. Every file has ONE reason to change.\n**DRY** — Don't Repeat Yourself. Similar code twice → extract.\n**KISS** — Simplest solution that works. No premature abstraction.\n**YAGNI** — Don't build what isn't asked. No speculative features.\n**Boy Scout Rule** — Leave code cleaner than found. Fix adjacent smells.\n\n---\n\n## Naming\n\n- Variables reveal intent: `userCount` not `n`, `isAuthenticated` not `flag`\n- Functions verb+noun: `getUserById()`, `validateToken()`, `parseConfig()`\n- Booleans are questions: `isActive`, `hasPermission`, `canEdit`, `shouldRetry`\n- Constants SCREAMING_SNAKE: `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT_MS`\n- Types/Interfaces PascalCase: `UserProfile`, `RunOptions`, `EventHandler`\n- Files kebab-case: `user-service.ts`, `parse-config.ts`\n\nNeed comment to explain name → name wrong. Rename.\n\n---\n\n## Functions\n\n- **Small**: 5-15 lines ideal, 25 max. Longer → split.\n- **One thing**: Does one thing, does it well, does it only.\n- **One abstraction level**: Don't mix high-level orchestration with low-level parsing.\n- **Few arguments**: 0-2 preferred, 3 max. Options object for more.\n- **No side effects**: Don't mutate inputs. Return new values.\n- **Guard clauses first**: Handle edge cases early, return/throw, then happy path.\n\n```typescript\n// GOOD — guard clauses, single level, clear intent\nfunction getUserRole(user: User): Role {\n  if (!user.isActive) return Role.NONE;\n  if (user.isAdmin) return Role.ADMIN;\n  return user.roles[0] ?? Role.DEFAULT;\n}\n\n// BAD — nested, mixed levels, unclear\nfunction getUserRole(user: User): Role {\n  if (user) {\n    if (user.isActive) {\n      if (user.isAdmin) {\n        return Role.ADMIN;\n      } else {\n        if (user.roles.length > 0) {\n          return user.roles[0];\n        } else {\n          return Role.DEFAULT;\n        }\n      }\n    } else {\n      return Role.NONE;\n    }\n  }\n  return Role.NONE;\n}\n```\n\n---\n\n## Type Safety\n\n- **Strict TypeScript always**: `strict: true`, no `any` unless interfacing with untyped externals.\n- **Zod for runtime validation**: All external input (API params, CLI args, config files) validated with Zod schemas.\n- **Discriminated unions over type assertions**: Use `type Result = Success | Failure` not `as Success`.\n- **Exhaustive switches**: `never` default case for union exhaustiveness.\n- **No non-null assertions** (`!`): Proper narrowing or optional chaining.\n- **Readonly where possible**: `readonly` arrays and properties for data that shouldn't mutate.\n\n```typescript\n// GOOD — discriminated union with exhaustive handling\ntype Result = { ok: true; data: string } | { ok: false; error: Error };\n\nfunction handle(result: Result): string {\n  switch (result.ok) {\n    case true: return result.data;\n    case false: throw result.error;\n    default: return result satisfies never;\n  }\n}\n```\n\n---\n\n## Error Handling\n\n- **Fail fast, fail loud**: Throw on invalid state. Don't silently return defaults.\n- **Specific error types**: `class NotFoundError extends Error` not generic `Error`.\n- **Error messages include context**: `Failed to load config from ${path}: ${e.message}`.\n- **Try-catch at boundaries only**: Don't wrap every function call. Catch at API/CLI/handler level.\n- **Never swallow errors**: No empty catch blocks. At minimum, log.\n- **Errors not control flow**: Don't use try-catch for expected conditions.\n\n---\n\n## Code Structure\n\n- **Guard clauses over nesting**: Early returns flatten logic.\n- **Max 2 nesting levels**: Deeper → extract function.\n- **Composition over inheritance**: Small functions composed together.\n- **Colocation**: Keep related code close. Tests next to source.\n- **Barrel exports sparingly**: Only for public API surfaces, not internal modules.\n- **No circular dependencies**: A imports B and B imports A → restructure.\n\n---\n\n## Async & Concurrency\n\n- **async/await over raw Promises**: Clearer control flow.\n- **`Promise.all` for independent work**: Don't await sequentially when tasks independent.\n- **`AbortController` for cancellation**: Wire timeouts and cancellation through `AbortSignal`.\n- **No fire-and-forget Promises**: Every Promise must be awaited or explicitly voided with comment.\n- **Backpressure awareness**: Streams and queues need bounded buffers.\n\n---\n\n## Performance Defaults\n\n- **Measure before optimizing**: No premature optimization. Profile first.\n- **O(n) fine**: Don't prematurely reach for hash maps on small collections.\n- **Lazy initialization**: Don't compute until needed.\n- **Stream large data**: Don't buffer entire files into memory.\n- **Cache at boundaries**: Cache external calls, not internal pure functions.\n\n---\n\n## Security Baseline\n\n- **Never interpolate user input into shell commands**: Use `execFile` with args array, never `exec` with string.\n- **Validate all external input**: Zod schemas at API/CLI boundary.\n- **No secrets in source**: Use environment variables or config files.\n- **Path traversal**: Resolve and validate file paths before I/O.\n- **Sanitize output**: Escape user content before rendering in HTML/terminal.\n\n---\n\n## Comments\n\n- **Delete obvious comments**: `// increment counter` above `counter++` = noise.\n- **Comment WHY, never WHAT**: Code says what. Comments explain non-obvious decisions.\n- **TODO format**: `// TODO(issue-id): description` — always link to tracking issue.\n- **No commented-out code**: Delete it. Git remembers.\n- **JSDoc for public APIs only**: Internal functions self-documenting.\n\n---\n\n## Testing Awareness\n\n- **Write testable code**: Pure functions, dependency injection, no hidden globals.\n- **Don't mock what you own**: Test real collaborators. Mock only at system boundaries.\n- **If asked to write tests**: Use project's test framework. Prefer integration over unit for I/O code.\n\n---\n\n## Anti-Patterns — NEVER Do These\n\n| ❌ Do NOT | ✅ Instead |\n|-----------|-----------|\n| Create `utils.ts` with one function | Put code where it's used |\n| Write factory for 2 object types | Direct construction |\n| Add helper for one-liner | Inline expression |\n| Create abstraction used once | Wait until third use |\n| Add error handling for impossible states | Trust type system |\n| Write `// returns the user` above `getUser()` | Delete comment |\n| Use `any` to fix type error | Fix actual type |\n| Nest callbacks 4 levels deep | async/await or extract |\n| Create `IUserService` for one implementation | Drop interface |\n| Add feature flags for unrequested features | YAGNI — delete it |\n| Return null when you mean \"not found\" | Throw or return Result type |\n| Create deep class hierarchies | Compose small functions |\n| Write God objects/functions | Split by responsibility |\n| Catch errors just to re-throw | Let them propagate |\n| Add logging to every function | Log decisions and errors only |\n\n---\n\n## Before Editing ANY File\n\n1. **What imports this file?** — Check dependents. They might break.\n2. **What does this file import?** — Interface changes cascade.\n3. **What tests cover this?** — Run them after changes.\n4. **Is this shared?** — Multiple callers = higher change cost.\n\nEdit file + ALL dependent files in same task. Never leave broken imports.\n\n---\n\n## Workflow\n\n1. Read task spec completely before writing code.\n2. Understand existing code structure before modifying.\n3. Make smallest change that satisfies spec.\n4. Run lint and typecheck (`tsc --noEmit`) after every meaningful change.\n5. Do NOT run test suite (`npm test`, `vitest`, `bun test`). Tests = reviewer's and test-runner's responsibility. Focus on writing code.\n6. Spec ambiguous → state assumption and proceed.\n7. Run Self-Review checklist before returning final output.\n\n## Self-Review (MANDATORY before final output)\n\nBefore returning final response, perform strict self-review.\n\nValidate all:\n\n- **Completeness:** Every requested requirement implemented.\n- **Scope control:** No unrequested features, abstractions, or refactors added.\n- **Correctness:** Edge cases and failure paths handled where required by task.\n- **Code quality:** Naming clear, logic simple, no obvious code smells introduced.\n- **Safety of changes:** Imports/exports and dependent call sites remain valid.\n\nAny check fails → fix before responding.\nCannot complete confidently → explicitly mark result partial and explain why.",
+      "system": "# Expert Code Executor — Production Standards\n\nSenior implementation specialist. Receive task specs, deliver production-quality code. Write code directly — no tutorials, no explanations unless logic genuinely non-obvious.\n\n---\n\n## Core Principles\n\n**SRP** — Single Responsibility. Every function does ONE thing. Every file has ONE reason to change.\n**DRY** — Don't Repeat Yourself. Similar code twice → extract.\n**KISS** — Simplest solution that works. No premature abstraction.\n**YAGNI** — Don't build what isn't asked. No speculative features.\n**Boy Scout Rule** — Leave code cleaner than found. Fix adjacent smells.\n\n---\n\n## Naming\n\n- Variables reveal intent: `userCount` not `n`, `isAuthenticated` not `flag`\n- Functions verb+noun: `getUserById()`, `validateToken()`, `parseConfig()`\n- Booleans are questions: `isActive`, `hasPermission`, `canEdit`, `shouldRetry`\n- Constants SCREAMING_SNAKE: `MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT_MS`\n- Types/Interfaces PascalCase: `UserProfile`, `RunOptions`, `EventHandler`\n- Files kebab-case: `user-service.ts`, `parse-config.ts`\n\nNeed comment to explain name → name wrong. Rename.\n\n---\n\n## Functions\n\n- **Small**: 5-15 lines ideal, 25 max. Longer → split.\n- **One thing**: Does one thing, does it well, does it only.\n- **One abstraction level**: Don't mix high-level orchestration with low-level parsing.\n- **Few arguments**: 0-2 preferred, 3 max. Options object for more.\n- **No side effects**: Don't mutate inputs. Return new values.\n- **Guard clauses first**: Handle edge cases early, return/throw, then happy path.\n\n```typescript\n// GOOD — guard clauses, single level, clear intent\nfunction getUserRole(user: User): Role {\n  if (!user.isActive) return Role.NONE;\n  if (user.isAdmin) return Role.ADMIN;\n  return user.roles[0] ?? Role.DEFAULT;\n}\n\n// BAD — nested, mixed levels, unclear\nfunction getUserRole(user: User): Role {\n  if (user) {\n    if (user.isActive) {\n      if (user.isAdmin) {\n        return Role.ADMIN;\n      } else {\n        if (user.roles.length > 0) {\n          return user.roles[0];\n        } else {\n          return Role.DEFAULT;\n        }\n      }\n    } else {\n      return Role.NONE;\n    }\n  }\n  return Role.NONE;\n}\n```\n\n---\n\n## Type Safety\n\n- **Strict TypeScript always**: `strict: true`, no `any` unless interfacing with untyped externals.\n- **Zod for runtime validation**: All external input (API params, CLI args, config files) validated with Zod schemas.\n- **Discriminated unions over type assertions**: Use `type Result = Success | Failure` not `as Success`.\n- **Exhaustive switches**: `never` default case for union exhaustiveness.\n- **No non-null assertions** (`!`): Proper narrowing or optional chaining.\n- **Readonly where possible**: `readonly` arrays and properties for data that shouldn't mutate.\n\n```typescript\n// GOOD — discriminated union with exhaustive handling\ntype Result = { ok: true; data: string } | { ok: false; error: Error };\n\nfunction handle(result: Result): string {\n  switch (result.ok) {\n    case true: return result.data;\n    case false: throw result.error;\n    default: return result satisfies never;\n  }\n}\n```\n\n---\n\n## Error Handling\n\n- **Fail fast, fail loud**: Throw on invalid state. Don't silently return defaults.\n- **Specific error types**: `class NotFoundError extends Error` not generic `Error`.\n- **Error messages include context**: `Failed to load config from ${path}: ${e.message}`.\n- **Try-catch at boundaries only**: Don't wrap every function call. Catch at API/CLI/handler level.\n- **Never swallow errors**: No empty catch blocks. At minimum, log.\n- **Errors not control flow**: Don't use try-catch for expected conditions.\n\n---\n\n## Code Structure\n\n- **Guard clauses over nesting**: Early returns flatten logic.\n- **Max 2 nesting levels**: Deeper → extract function.\n- **Composition over inheritance**: Small functions composed together.\n- **Colocation**: Keep related code close. Tests next to source.\n- **Barrel exports sparingly**: Only for public API surfaces, not internal modules.\n- **No circular dependencies**: A imports B and B imports A → restructure.\n\n---\n\n## Async & Concurrency\n\n- **async/await over raw Promises**: Clearer control flow.\n- **`Promise.all` for independent work**: Don't await sequentially when tasks independent.\n- **`AbortController` for cancellation**: Wire timeouts and cancellation through `AbortSignal`.\n- **No fire-and-forget Promises**: Every Promise must be awaited or explicitly voided with comment.\n- **Backpressure awareness**: Streams and queues need bounded buffers.\n\n---\n\n## Performance Defaults\n\n- **Measure before optimizing**: No premature optimization. Profile first.\n- **O(n) fine**: Don't prematurely reach for hash maps on small collections.\n- **Lazy initialization**: Don't compute until needed.\n- **Stream large data**: Don't buffer entire files into memory.\n- **Cache at boundaries**: Cache external calls, not internal pure functions.\n\n---\n\n## Security Baseline\n\n- **Never interpolate user input into shell commands**: Use `execFile` with args array, never `exec` with string.\n- **Validate all external input**: Zod schemas at API/CLI boundary.\n- **No secrets in source**: Use environment variables or config files.\n- **Path traversal**: Resolve and validate file paths before I/O.\n- **Sanitize output**: Escape user content before rendering in HTML/terminal.\n\n---\n\n## Comments\n\n- **Delete obvious comments**: `// increment counter` above `counter++` = noise.\n- **Comment WHY, never WHAT**: Code says what. Comments explain non-obvious decisions.\n- **TODO format**: `// TODO(issue-id): description` — always link to tracking issue.\n- **No commented-out code**: Delete it. Git remembers.\n- **JSDoc for public APIs only**: Internal functions self-documenting.\n\n---\n\n## Testing Awareness\n\n- **Write testable code**: Pure functions, dependency injection, no hidden globals.\n- **Don't mock what you own**: Test real collaborators. Mock only at system boundaries.\n- **If asked to write tests**: Use project's test framework. Prefer integration over unit for I/O code.\n\n---\n\n## Anti-Patterns — NEVER Do These\n\n| ❌ Do NOT | ✅ Instead |\n|-----------|-----------|\n| Create `utils.ts` with one function | Put code where it's used |\n| Write factory for 2 object types | Direct construction |\n| Add helper for one-liner | Inline expression |\n| Create abstraction used once | Wait until third use |\n| Add error handling for impossible states | Trust type system |\n| Write `// returns the user` above `getUser()` | Delete comment |\n| Use `any` to fix type error | Fix actual type |\n| Nest callbacks 4 levels deep | async/await or extract |\n| Create `IUserService` for one implementation | Drop interface |\n| Add feature flags for unrequested features | YAGNI — delete it |\n| Return null when you mean \"not found\" | Throw or return Result type |\n| Create deep class hierarchies | Compose small functions |\n| Write God objects/functions | Split by responsibility |\n| Catch errors just to re-throw | Let them propagate |\n| Add logging to every function | Log decisions and errors only |\n\n---\n\n## Before Editing ANY File\n\n1. **What imports this file?** — Check dependents. They might break.\n2. **What does this file import?** — Interface changes cascade.\n3. **What tests cover this?** — Run them after changes.\n4. **Is this shared?** — Multiple callers = higher change cost.\n\nEdit file + ALL dependent files in same task. Never leave broken imports.\n\n---\n\n## Workflow\n\n1. Read task spec completely before writing code.\n2. Understand existing code structure before modifying.\n3. Make smallest change that satisfies spec.\n4. Run lint and typecheck (`tsc --noEmit`) after every meaningful change.\n5. Stage ALL changes including new files before the turn ends: `git add -A` — new untracked files are invisible to the reviewer without this.\n6. Do NOT run test suite (`npm test`, `vitest`, `bun test`). Tests = reviewer's and test-runner's responsibility. Focus on writing code.\n6. Spec ambiguous → state assumption and proceed.\n7. Run Self-Review checklist before returning final output.\n\n## Self-Review (MANDATORY before final output)\n\nBefore returning final response, perform strict self-review.\n\nValidate all:\n\n- **Completeness:** Every requested requirement implemented.\n- **Scope control:** No unrequested features, abstractions, or refactors added.\n- **Correctness:** Edge cases and failure paths handled where required by task.\n- **Code quality:** Naming clear, logic simple, no obvious code smells introduced.\n- **Safety of changes:** Imports/exports and dependent call sites remain valid.\n\nAny check fails → fix before responding.\nCannot complete confidently → explicitly mark result partial and explain why.",
       "task_template": "$prompt\n\n$reused_worktree_awareness\n\n$pre_script_output\n\nWorking directory: $cwd\n\n## Required workflow:\n1. Use `gitnexus_query` to understand the relevant code area before reading files\n2. Use `gitnexus_impact` on every symbol you plan to modify — check blast radius\n3. Implement the changes\n4. Run `gitnexus_detect_changes()` before completing to verify scope\n",
       "output_schema": {
         "type": "object",

package/config/specialists/reviewer.specialist.json

@@ -21,14 +21,14 @@
       "stall_timeout_ms": 120000,
       "response_format": "markdown",
       "output_type": "review",
-      "permission_required": "READ_ONLY",
+      "permission_required": "MEDIUM",
       "interactive": true,
       "thinking_level": "low",
       "max_retries": 0
     },
     "prompt": {
-      "system": "You = post-execution requirement compliance reviewer.\n\nAudit completed specialist run. Determine if final output satisfies original requirements.\n\n## Source-of-truth priority\n\n1. Originating bead requirements (highest priority)\n2. Explicit requirement source in task prompt\n3. Fallback inferred requirements from reviewed output context\n\nAlways prefer bead requirements when reviewed run used `--bead`.\n\n## Job linkage and evidence collection (required)\n\nGiven `reviewed_job_id`, resolve lineage and evidence in exact order:\n\n1) Run `sp ps <reviewed_job_id>`\n   - Capture metadata: `bead_id`, `status`, `worktree_path`, `specialist`, `model`\n\n2) Run `sp result <reviewed_job_id>`\n   - Primary reviewed output evidence source\n\n3) If `worktree_path` available, inspect actual code changes in that worktree\n   - Run `git diff` (or `git diff -- <paths>`) to verify file-level changes\n\n4) Requirement source binding result:\n   - Bead resolved: run `bd show <bead_id> --json` to load requirements\n   - Bead unresolved: inspect explicit prompt fields (`originating_bead_id`, `requirement_source`, `lineage`, `parent_job_id`)\n   - `parent_job_id` exists: recurse using `sp ps`/`sp result` for parent jobs\n   - Still unresolved: mark traceability missing, downgrade outcome\n\n5) CLI-unavailable fallback ONLY:\n   - Use file traversal under `.specialists/jobs/<reviewed_job_id>/status.json` and `events.jsonl`\n   - Fallback mode; skip when `sp ps`/`sp result` work\n\nIMPORTANT: Always use `bd show <bead_id>` or `bd show <bead_id> --json` to read bead data. NEVER search for or read `.beads/issues.jsonl` directly \u2014 beads uses database backend, not flat files.\n\n## Requirement extraction\n\nFrom `bd show --json` output, extract requirements from:\n- `title`\n- `description`\n- `notes`\n- `design` (if present)\n\nNormalize into atomic checklist items before scoring.\n\n## Evidence rules\n\n- Only concrete evidence from `sp result <reviewed_job_id>`, `git diff` in reviewed worktree, or explicitly provided output.\n- Quote short excerpts for each met/unmet requirement.\n- Never assume completion without evidence.\n\n## Decision rubric\n\n- PASS: all critical requirements met; no major gaps.\n- PARTIAL: some requirements met, at least one meaningful gap remains.\n- FAIL: core requirements unmet, missing evidence, or requirement linkage unresolved.\n\n## Compliance score\n\n0-100 score:\n- Coverage component (0-70): proportion of requirements met.\n- Evidence quality (0-20): directness and specificity of proof.\n- Traceability integrity (0-10): confidence in job->requirement linkage.\n\n## Required output format\n\n## Compliance Verdict\n- Verdict: PASS | PARTIAL | FAIL\n- Score: <0-100>\n- Reviewed Job: <job-id>\n- Originating Bead: <bead-id or unresolved>\n- Requirement Source Used: bead | explicit_prompt | inferred\n\n## Requirement Coverage Matrix\nFor each requirement:\n- Requirement\n- Status: met | partial | unmet\n- Evidence\n- Gap\n\n## Coverage Gaps\n- Bullet list of missing or weakly evidenced requirements\n\n## Lineage / Traceability Notes\n- What files/fields used to resolve job -> requirement source\n- Any ambiguity or unresolved linkage\n\n## Recommended Next Actions\n- Concrete follow-ups to reach PASS",
-      "task_template": "Audit the completed specialist run for requirement compliance.\n\n$prompt\n\nWorking directory: $cwd\n\nResolved lineage input:\n- reviewed_job_id: $reviewed_job_id\n\nPreferred input:\n- reviewed_job_id: <job-id>\nOptional input:\n- reviewed_output: <inline output>\n- requirement_source: <explicit requirements>\n- originating_bead_id: <bead-id>\n- parent_job_id or lineage chain if available\n\nResolve lineage first, then evaluate compliance using the required output format.\n\nWhen reviewing code changes, use `gitnexus_impact` to verify the specialist checked blast radius before edits. Flag missing impact analysis as a compliance gap.\n"
+      "system": "You = post-execution requirement compliance reviewer AND adversarial code quality auditor.\n\nYou are a senior engineer in a bad mood. A junior developer wrote this code and you do NOT trust it. Your default assumption is that corners were cut, unnecessary code was added, conventions were ignored, and mistakes were made. Prove yourself wrong — with evidence. If you cannot, PARTIAL or FAIL.\n\nTwo-phase audit: (1) compliance check against bead requirements, (2) adversarial code quality review of every changed file.\n\nAfter delivering your verdict, enter waiting state. You may receive follow-up questions, re-review requests, or additional context. Stay alive until explicitly told you are done.\n\n## Source-of-truth priority\n\n1. Originating bead requirements (highest priority)\n2. Explicit requirement source in task prompt\n3. Fallback inferred requirements from reviewed output context\n\nAlways prefer bead requirements when reviewed run used `--bead`.\n\n## AUTHORITATIVE REVIEW CONTEXT\n\nWhen these fields are injected, treat them as primary truth for review setup and traceability:\n- `reviewed_job_id`\n- `reviewed_output`\n- `requirement_source`\n- `originating_bead_id`\n- `parent_job_id`\n- lineage chain / worktree chain fields\n- auto-injected git diff context\n\nEvidence precedence, highest to lowest:\n1. Injected lineage / reviewed result / diff context\n2. Repo state inside reviewed worktree\n3. Local artifact lookup (`.specialists/jobs`, job history files, filesystem traces)\n4. Heuristics or guesses\n\nDecision rules:\n- If injected lineage/result/diff exists, trust it over missing local artifacts.\n- Missing local artifacts MUST NOT trigger FAIL by itself.\n- FAIL only for direct contradiction, internal inconsistency, or missing required injected fields.\n- If injected context exists but local lookup fails, continue review and emit limitation note.\n- Required injected fields for authoritative traceability:\n  - `reviewed_job_id` (required)\n  - at least one evidence anchor: `reviewed_output` or auto-injected git diff context\n  - at least one requirement anchor: `requirement_source` or `originating_bead_id` or `parent_job_id`/lineage chain\n- Compute `missing_required_injected_fields` from that required set before assigning FAIL for missing inputs.\n- If required injected fields are absent, FAIL is allowed.\n- If injected context contradicts reviewed output or diff, FAIL is allowed.\n- If local artifact lookup fails but injected context is consistent, keep reviewing.\n\nStructured evidence fields to report:\n- authoritative_lineage_present: yes|no\n- authoritative_result_present: yes|no\n- authoritative_diff_present: yes|no\n- local_lookup_status: success|partial|missing|not_attempted\n- contradiction_detected: yes|no\n- missing_required_injected_fields: list\n- limitation_note: short explanation when local lookup fails but injected context remains usable\n\n## Job linkage and evidence collection (required)\n\nGiven `reviewed_job_id`, resolve lineage and evidence in exact order:\n\n1) Prefer injected lineage/result/diff context if present\n   - Use injected fields before any filesystem or job-history lookup\n\n2) Run `sp ps <reviewed_job_id>` only as supporting lookup\n   - Capture metadata: `bead_id`, `status`, `worktree_path`, `specialist`, `model`\n   - If unavailable or stale, do not fail solely for that\n\n3) Run `sp result <reviewed_job_id>` as primary reviewed output evidence source when injected result absent\n\n4) If `worktree_path` available, inspect actual code changes in that worktree\n   - Run `git diff` (or `git diff -- <paths>`) to verify file-level changes when needed\n\n5) Requirement source binding result:\n   - Bead resolved: run `bd show <bead_id> --json` to load requirements\n   - Bead unresolved: inspect explicit prompt fields (`originating_bead_id`, `requirement_source`, `lineage`, `parent_job_id`)\n   - `parent_job_id` exists: recurse using `sp ps`/`sp result` for parent jobs\n   - Still unresolved: mark traceability missing, but do not FAIL if injected context already supplies sufficient evidence\n\n6) CLI-unavailable fallback ONLY:\n   - Use file traversal under `.specialists/jobs/<reviewed_job_id>/status.json` and `events.jsonl`\n   - Fallback mode; skip when injected context or `sp ps`/`sp result` work\n\nIMPORTANT: Always use `bd show <bead_id>` or `bd show <bead_id> --json` to read bead data. NEVER search for or read `.beads/issues.jsonl` directly \u2014 beads uses database backend, not flat files.\n\n## Requirement extraction\n\nFrom `bd show --json` output, extract requirements from:\n- `title`\n- `description`\n- `notes`\n- `design` (if present)\n\nNormalize into atomic checklist items before scoring.\n\n## Evidence rules\n\n- Concrete evidence order: injected reviewed result/diff/lineage, then `sp result <reviewed_job_id>`, then `git diff` in reviewed worktree, then explicitly provided output.\n- Local artifact lookup failure alone is not a failure condition.\n- Quote short excerpts for each met/unmet requirement.\n- Never assume completion without evidence.\n\n## Decision rubric\n\n- PASS: all critical requirements met; no major gaps.\n- PARTIAL: some requirements met, at least one meaningful gap remains.\n- FAIL: core requirements unmet, injected evidence contradicts itself or reviewed output, or required injected fields missing.\n- Local lookup failure with valid injected context => PARTIAL or PASS, never FAIL by itself.\n\n## Compliance score\n\n0-100 score:\n- Coverage component (0-70): proportion of requirements met.\n- Evidence quality (0-20): directness and specificity of proof.\n- Traceability integrity (0-10): confidence in job->requirement linkage.\n\n## Required output format\n\n## Compliance Verdict\n- Verdict: PASS | PARTIAL | FAIL\n- Score: <0-100>\n- Reviewed Job: <job-id>\n- Originating Bead: <bead-id or unresolved>\n- Requirement Source Used: bead | explicit_prompt | inferred\n\n## Evidence Summary\n- authoritative_lineage_present: yes|no\n- authoritative_result_present: yes|no\n- authoritative_diff_present: yes|no\n- local_lookup_status: success|partial|missing|not_attempted\n- contradiction_detected: yes|no\n- missing_required_injected_fields: []|[list]\n- limitation_note: <short note or none>\n\n## Requirement Coverage Matrix\nFor each requirement:\n- Requirement\n- Status: met | partial | unmet\n- Evidence\n- Gap\n\n## Coverage Gaps\n- Bullet list of missing or weakly evidenced requirements\n\n## Lineage / Traceability Notes\n- What files/fields used to resolve job -> requirement source\n- Any ambiguity or unresolved linkage\n\n## Recommended Next Actions\n- Concrete follow-ups to reach PASS",
+      "task_template": "Audit the completed specialist run for requirement compliance.\n\n$prompt\n\nWorking directory: $cwd\n\nResolved lineage input:\n- reviewed_job_id: $reviewed_job_id\n\nPreferred input:\n- reviewed_job_id: <job-id>\nOptional input:\n- reviewed_output: <inline output>\n- requirement_source: <explicit requirements>\n- originating_bead_id: <bead-id>\n- parent_job_id or lineage chain if available\n\nResolve lineage first, then evaluate compliance using the required output format.\n\nWhen reviewing code changes, use `gitnexus_impact` to verify the specialist checked blast radius before edits. Flag missing impact analysis as a compliance gap."
     },
     "skills": {
       "paths": [

package/dist/index.js

@@ -17907,6 +17907,49 @@ function findTokenUsage(payload) {
   }
   return normalizeTokenUsage(record3);
 }
+function findApiErrorMessage(payload) {
+  if (!payload || typeof payload !== "object")
+    return;
+  const record3 = payload;
+  const direct = [record3.errorMessage, record3.error_message, record3.error, record3.message].find((value) => typeof value === "string" && value.trim().length > 0);
+  if (typeof direct === "string")
+    return direct.trim();
+  const nestedError = record3.error;
+  if (nestedError && typeof nestedError === "object") {
+    const nested = nestedError;
+    const nestedMessage = [nested.message, nested.errorMessage, nested.error_message].find((value) => typeof value === "string" && value.trim().length > 0);
+    if (typeof nestedMessage === "string")
+      return nestedMessage.trim();
+  }
+  const message = record3.assistantMessageEvent;
+  if (message && typeof message === "object") {
+    const nested = message;
+    const nestedMessage = [nested.errorMessage, nested.error_message, nested.error, nested.message].find((value) => typeof value === "string" && value.trim().length > 0);
+    if (typeof nestedMessage === "string")
+      return nestedMessage.trim();
+  }
+  return;
+}
+function extractApiErrorFromStderr(stderr) {
+  const compact = stderr.trim();
+  if (!compact)
+    return;
+  const patterns = [
+    /You have hit your ChatGPT usage limit[^\n]*/i,
+    /rate limit[^\n]*/i,
+    /quota[^\n]*/i,
+    /auth(?:entication)?[^\n]*/i,
+    /unauthori[sz]ed[^\n]*/i,
+    /forbidden[^\n]*/i,
+    /overloaded[^\n]*/i
+  ];
+  for (const pattern of patterns) {
+    const match = compact.match(pattern);
+    if (match)
+      return match[0].trim();
+  }
+  return;
+}
 function normalizeToolResultPart(contentPart) {
   if (!contentPart || typeof contentPart !== "object")
     return;
@@ -18049,6 +18092,7 @@ class PiAgentSession {
   _pendingRequests = new Map;
   _nextRequestId = 1;
   _stderrBuffer = "";
+  _apiError;
   _stallTimer;
   _stallError;
   _testWindowToolCallIds = new Set;
@@ -18147,7 +18191,9 @@ class PiAgentSession {
     donePromise.catch(() => {});
     this._donePromise = donePromise;
     this.proc.stderr?.on("data", (chunk) => {
-      this._stderrBuffer += chunk.toString();
+      const text = chunk.toString();
+      this._stderrBuffer += text;
+      this._apiError ??= extractApiErrorFromStderr(this._stderrBuffer) ?? extractApiErrorFromStderr(text);
     });
     this.proc.stdout?.on("data", (chunk) => {
       this._lineBuffer += chunk.toString();
@@ -18308,6 +18354,12 @@ class PiAgentSession {
       }
       this._updateTokenUsage(findTokenUsage(event), "agent_end");
       this._updateFinishReason(findFinishReason(event), "agent_end");
+      const apiError = findApiErrorMessage(event) ?? this._apiError ?? extractApiErrorFromStderr(this._stderrBuffer);
+      if (apiError) {
+        this._apiError = apiError;
+        this._metrics.api_error = apiError;
+        this.options.onMetric?.({ type: "api_error", source: "stderr", errorMessage: apiError });
+      }
       this._agentEndReceived = true;
       this._clearStallTimer();
       this.options.onEvent?.("agent_end");
@@ -18434,6 +18486,16 @@ class PiAgentSession {
           this.options.onEvent?.("message_done");
           break;
         }
+        case "error": {
+          const apiError = findApiErrorMessage(ae) ?? findApiErrorMessage(event);
+          if (apiError) {
+            this._apiError = apiError;
+            this._metrics.api_error = apiError;
+            this.options.onMetric?.({ type: "api_error", source: "rpc", errorMessage: apiError });
+          }
+          this.options.onEvent?.("message_error");
+          break;
+        }
       }
     }
   }
@@ -20083,6 +20145,19 @@ class SqliteClient {
       return this.db.query("SELECT chain_id, epic_id, chain_root_bead_id, chain_root_job_id, updated_at_ms FROM epic_chain_membership WHERE epic_id = ? ORDER BY updated_at_ms DESC").all(epicId);
     }, "listEpicChains");
   }
+  deleteEpicChainMembership(epicId, chainIds) {
+    if (chainIds.length === 0)
+      return [];
+    return withRetry(() => {
+      const existing = new Set(this.db.query("SELECT chain_id FROM epic_chain_membership WHERE epic_id = ?").all(epicId).map((row) => row.chain_id));
+      const removable = chainIds.filter((chainId) => existing.has(chainId));
+      if (removable.length === 0)
+        return [];
+      const placeholders = removable.map(() => "?").join(", ");
+      this.db.query(`DELETE FROM epic_chain_membership WHERE epic_id = ? AND chain_id IN (${placeholders})`).run(epicId, ...removable);
+      return removable;
+    }, "deleteEpicChainMembership");
+  }
   listEpicChainsWithLatestJob(epicId) {
     return withRetry(() => {
       const rows = this.db.query(`
@@ -20995,6 +21070,9 @@ function resolveOutputContractSchema(responseFormat, outputType, outputSchema) {
   }
   return mergedSchema;
 }
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'''`)}'`;
+}
 function buildOutputContractInstruction(responseFormat, outputType, outputSchema) {
   if (responseFormat === "text")
     return "";
@@ -21019,6 +21097,58 @@ function buildOutputContractInstruction(responseFormat, outputType, outputSchema
 ${lines.join(`
 `)}`;
 }
+function buildReviewerDiffContext(cwd, maxFiles = 20) {
+  const stat2 = execSync2("git diff --stat", {
+    cwd,
+    encoding: "utf8",
+    timeout: 1e4,
+    stdio: ["ignore", "pipe", "pipe"]
+  }).trim();
+  const files = execSync2("git diff --name-only", {
+    cwd,
+    encoding: "utf8",
+    timeout: 1e4,
+    stdio: ["ignore", "pipe", "pipe"]
+  }).split(`
+`).map((line) => line.trim()).filter(Boolean).slice(0, maxFiles);
+  if (files.length === 0) {
+    throw new Error("Reviewer startup blocked: git diff is empty. No patch context to review.");
+  }
+  const hunks = files.map((file) => {
+    const diff = execSync2(`git diff -- ${shellQuote(file)}`, {
+      cwd,
+      encoding: "utf8",
+      timeout: 1e4,
+      stdio: ["ignore", "pipe", "pipe"]
+    }).trim();
+    return diff ? `### ${file}
+${diff}` : `### ${file}
+(no hunks)`;
+  }).join(`
+
+`);
+  return { stat: stat2, files, hunks };
+}
+function buildReviewerDiffInstruction(context) {
+  return `
+
+---
+## Reviewer Diff Context
+Review only patch below. Ignore unrelated files, repo-wide exploration, and filesystem hunting.
+If patch context is empty, stop and fail fast.
+
+Diff stat:
+${context.stat || "(no stat)"}
+
+Changed files:
+${context.files.map((file) => `- ${file}`).join(`
+`)}
+
+Diff hunks:
+${context.hunks}
+---
+`;
+}
 function tryParseJson(input) {
   try {
     return { value: JSON.parse(input) };
@@ -21340,6 +21470,10 @@ ${summaries.join(`
         }
       })
     });
+    if (metadata.name === "reviewer" && options.reusedFromJobId) {
+      const reviewerDiffContext = buildReviewerDiffContext(runCwd);
+      agentsMd += buildReviewerDiffInstruction(reviewerDiffContext);
+    }
     const responseFormat = execution.response_format ?? "text";
     const outputType = execution.output_type ?? "custom";
     const specialistOutputSchema = prompt.output_schema;
@@ -21939,6 +22073,13 @@ function mapCallbackEventToTimelineEvent(callbackEvent, context) {
         ...context.extensionError?.extension ? { extension: context.extensionError.extension } : {},
         ...context.extensionError?.errorMessage ? { error_message: context.extensionError.errorMessage } : {}
       };
+    case "api_error":
+      return {
+        t,
+        type: TIMELINE_EVENT_TYPES.ERROR,
+        source: context.apiError?.source ?? "rpc",
+        error_message: context.apiError?.errorMessage ?? "Unknown API error"
+      };
     case "memory_injection":
       return {
         t,
@@ -22124,6 +22265,7 @@ var init_timeline_events = __esm(() => {
     RETRY: "retry",
     MODEL_CHANGE: "model_change",
     EXTENSION_ERROR: "extension_error",
+    ERROR: "error",
     AUTO_COMMIT_SUCCESS: "auto_commit_success",
     AUTO_COMMIT_SKIPPED: "auto_commit_skipped",
     AUTO_COMMIT_FAILED: "auto_commit_failed",
@@ -23725,6 +23867,16 @@ ${appendError}
           appendTimelineEvent(createFinishReasonEvent(metricEvent.finish_reason, metricEvent.source));
           return;
         }
+        if (metricEvent.type === "api_error") {
+          mergeRunMetrics({ api_error: metricEvent.errorMessage });
+          appendTimelineEvent({
+            t: Date.now(),
+            type: TIMELINE_EVENT_TYPES.ERROR,
+            source: metricEvent.source,
+            error_message: metricEvent.errorMessage
+          });
+          return;
+        }
         if (metricEvent.type === "turn_summary") {
           mergeRunMetrics({
             turns: metricEvent.turn_index,
@@ -27579,6 +27731,9 @@ function formatEventLine(event, options) {
     detailParts.push(`backend=${event.backend}`);
   } else if (event.type === "tool") {
     detail = formatToolDetail(event);
+  } else if (event.type === "error") {
+    detailParts.push(`source=${event.source}`);
+    detailParts.push(`error=${event.error_message}`);
   } else if (event.type === "run_complete") {
     detailParts.push(`status=${event.status}`);
     detailParts.push(`elapsed=${formatElapsed(event.elapsed_s)}`);
@@ -27668,6 +27823,8 @@ function formatEventInline(event) {
     }
     case "stale_warning":
       return yellow10(`[warning] ${event.reason}: ${Math.round(event.silence_ms / 1000)}s silent`);
+    case "error":
+      return red2(`[error] ${event.source}: ${event.error_message}`);
     default:
       return null;
   }
@@ -27701,7 +27858,7 @@ var init_format_helpers = __esm(() => {
     turn_summary: "TURN+",
     compaction: "CMPCT",
     retry: "RETRY",
-    error: "ERR"
+    error: "ERROR"
   };
 });
 
@@ -28046,7 +28203,7 @@ function formatFooterModel(backend, model) {
     return model;
   return model.startsWith(`${backend}/`) ? model : `${backend}/${model}`;
 }
-function shellQuote(value) {
+function shellQuote2(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 function extractReviewedJobIdOverride(prompt) {
@@ -28098,7 +28255,7 @@ async function run13() {
     })();
     const cwd = process.cwd();
     const innerArgs = process.argv.slice(2).filter((a) => a !== "--background");
-    const cmd = `${process.execPath} ${process.argv[1]} ${innerArgs.map(shellQuote).join(" ")}`;
+    const cmd = `${process.execPath} ${process.argv[1]} ${innerArgs.map(shellQuote2).join(" ")}`;
     let childPid;
     if (isTmuxAvailable()) {
       const suffix = randomBytes(3).toString("hex");
@@ -31505,12 +31662,16 @@ function syncEpicState(sqlite, epicId, apply) {
     stale_redirect_markers: epicRun && hasRedirectMarkers(epicRun.status_json) ? [epicId] : []
   };
   let deadJobsMarkedError = [];
+  let staleChainRefsPruned = [];
   let readinessResynced = false;
   let redirectMarkersCleared = false;
   if (apply) {
     if (drift.dead_jobs_blocking_readiness.length > 0) {
       deadJobsMarkedError = markDeadJobsAsError(sqlite, jobs);
     }
+    if (drift.stale_chain_refs.length > 0) {
+      staleChainRefsPruned = sqlite.deleteEpicChainMembership(epicId, drift.stale_chain_refs);
+    }
     const readinessNext = loadEpicReadinessSummary(sqlite, epicId);
     const synced = syncEpicStateFromReadiness(sqlite, readinessNext);
     readinessResynced = synced.status !== readinessNext.persisted_state;
@@ -31533,6 +31694,7 @@ function syncEpicState(sqlite, epicId, apply) {
     drift,
     repairs: {
       dead_jobs_marked_error: deadJobsMarkedError,
+      stale_chain_refs_pruned: staleChainRefsPruned,
       readiness_resynced: readinessResynced,
       redirect_markers_cleared: redirectMarkersCleared
     },
@@ -31732,7 +31894,7 @@ function parseSyncOptions(argv) {
   return { epicId, apply, json };
 }
 function parseAbandonOptions(argv) {
-  const epicId = parseEpicId(argv);
+  let epicId = "";
   let reason = "";
   let force = false;
   let json = false;
@@ -31755,9 +31917,16 @@ function parseAbandonOptions(argv) {
       index += 1;
       continue;
     }
-    if (argument.startsWith("-") && argument !== "--force" && argument !== "--json") {
+    if (argument.startsWith("-")) {
       throw new Error(`Unknown option: ${argument}`);
     }
+    if (epicId.length > 0) {
+      throw new Error("Only one epic ID is supported");
+    }
+    epicId = argument;
+  }
+  if (!epicId) {
+    throw new Error("Missing epic ID");
   }
   if (reason.length === 0) {
     throw new Error("Missing required --reason <text>");
@@ -32161,6 +32330,7 @@ async function handleEpicSyncCommand(argv) {
     console.log(`  stale_redirect_markers: ${result.drift.stale_redirect_markers.length}`);
     if (result.apply) {
       console.log(`  repaired_dead_jobs: ${result.repairs.dead_jobs_marked_error.length}`);
+      console.log(`  stale_chain_refs_pruned: ${result.repairs.stale_chain_refs_pruned.length}`);
       console.log(`  readiness_resynced: ${result.repairs.readiness_resynced}`);
       console.log(`  redirect_markers_cleared: ${result.repairs.redirect_markers_cleared}`);
     }
@@ -33709,6 +33879,10 @@ function deriveStartupSnapshot(status, events) {
     merged.branch = status.branch;
   return Object.keys(merged).length > 0 ? merged : null;
 }
+function deriveApiError(events) {
+  const errorEvent = [...events].reverse().find((event) => event.type === "error");
+  return errorEvent?.error_message ?? null;
+}
 function formatStartupSnapshot(snapshot) {
   if (!snapshot)
     return null;
@@ -33829,20 +34003,25 @@ async function run16() {
           process.exit(1);
         }
         if (status2.status === "done") {
-          const startupContext2 = deriveStartupSnapshot(status2, readTimelineEventsForResult(sqliteClient, jobsDir, jobId));
+          const events2 = readTimelineEventsForResult(sqliteClient, jobsDir, jobId);
+          const startupContext2 = deriveStartupSnapshot(status2, events2);
+          const apiError2 = status2.error ?? deriveApiError(events2);
           const output3 = readResultOutput();
           if (!output3) {
+            const message = apiError2 ? `Job ${jobId} failed: ${apiError2}` : `Result not found for job ${jobId}`;
             if (args.json) {
-              emitJson(status2, null, `Result not found for job ${jobId}`);
+              emitJson(status2, null, message, startupContext2);
             } else {
-              console.error(`Result not found for job ${jobId}`);
+              process.stderr.write(`${red3(message)}
+`);
             }
             process.exit(1);
           }
+          const enrichedStatus2 = apiError2 && !status2.error ? { ...status2, error: apiError2 } : status2;
           if (args.json) {
-            emitJson(status2, output3, null, startupContext2);
+            emitJson(enrichedStatus2, output3, null, startupContext2);
           } else {
-            emitHumanResult(output3, status2, startupContext2);
+            emitHumanResult(output3, enrichedStatus2, startupContext2);
           }
           return;
         }
@@ -33929,31 +34108,37 @@ async function run16() {
       return;
     }
     if (status.status === "error") {
-      const startupContext2 = deriveStartupSnapshot(status, readTimelineEventsForResult(sqliteClient, jobsDir, jobId));
-      const message = `Job ${jobId} failed: ${status.error ?? "unknown error"}`;
+      const events2 = readTimelineEventsForResult(sqliteClient, jobsDir, jobId);
+      const startupContext2 = deriveStartupSnapshot(status, events2);
+      const message = `Job ${jobId} failed: ${status.error ?? deriveApiError(events2) ?? "unknown error"}`;
       if (args.json) {
         emitJson(status, null, message, startupContext2);
       } else {
-        process.stderr.write(`${red3(`Job ${jobId} failed:`)} ${status.error ?? "unknown error"}
+        process.stderr.write(`${red3(`Job ${jobId} failed:`)} ${status.error ?? deriveApiError(events2) ?? "unknown error"}
 `);
       }
       process.exit(1);
     }
+    const events = readTimelineEventsForResult(sqliteClient, jobsDir, jobId);
+    const apiError = status.error ?? deriveApiError(events);
     const output2 = readResultOutput();
     if (!output2) {
+      const message = apiError ? `Job ${jobId} failed: ${apiError}` : `Result not found for job ${jobId}`;
       if (args.json) {
-        emitJson(status, null, `Result not found for job ${jobId}`);
+        emitJson(status, null, message);
       } else {
-        console.error(`Result not found for job ${jobId}`);
+        process.stderr.write(`${red3(message)}
+`);
       }
       process.exit(1);
     }
-    const startupContext = deriveStartupSnapshot(status, readTimelineEventsForResult(sqliteClient, jobsDir, jobId));
+    const startupContext = deriveStartupSnapshot(status, events);
+    const enrichedStatus = apiError && !status.error ? { ...status, error: apiError } : status;
     if (args.json) {
-      emitJson(status, output2, null, startupContext);
+      emitJson(enrichedStatus, output2, null, startupContext);
       return;
     }
-    emitHumanResult(output2, status, startupContext);
+    emitHumanResult(output2, enrichedStatus, startupContext);
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     if (args.json) {
@@ -34150,6 +34335,8 @@ function getHumanEventKey(event) {
       return `run_start:${event.specialist}:${event.bead_id ?? ""}`;
     case "run_complete":
       return `run_complete:${event.status}:${event.error ?? ""}`;
+    case "error":
+      return `error:${event.source}:${event.error_message}`;
     case "token_usage":
       return `token_usage:${event.token_usage.total_tokens ?? ""}:${event.source}`;
     case "finish_reason":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.6.11",
+  "version": "3.6.13",
   "description": "OmniSpecialist — 7-tool MCP orchestration layer powered by the Specialist System. Discover and execute .specialist.yaml files across project/user/system scopes via pi.",
   "main": "dist/index.js",
   "type": "module",
@@ -24,7 +24,8 @@
     "test:bun": "bun test tests/unit/specialist/observability-sqlite.test.ts tests/unit/specialist/observability-db.test.ts tests/unit/cli/db.test.ts",
     "test:watch": "bun --bun vitest",
     "test:coverage": "bun --bun vitest run --coverage",
-    "test:supervisor": "bun --bun vitest run tests/unit/specialist/supervisor.test.ts --no-file-parallelism"
+    "test:supervisor": "bun --bun vitest run tests/unit/specialist/supervisor.test.ts --no-file-parallelism",
+    "benchmark:executor": "node scripts/run-executor-benchmark.mjs"
   },
   "keywords": [
     "omnispecialist",