@jaggerxtrm/specialists 3.16.0 → 3.18.0

package/docs/archive/discoveries.md

@@ -0,0 +1,148 @@
+---
+title: Agent Forge — Discovery Notes
+scope: discoveries
+category: reference
+version: 1.0.0
+updated: 2026-03-19
+domain: []
+---
+
+<!-- INDEX: auto-generated by validate_doc.py — do not edit manually -->
+| Section | Summary |
+|---|---|
+| [Architettura — Chiarimenti post-PRD](#architettura-chiarimenti-post-prd) | **Posizione nel sistema:** Agent Forge è layer 2-3 |
+| [Orchestratore — Worktrees e Branch Model](#orchestratore-worktrees-e-branch-model) | **Il modello corretto** (nuovo punto di questo pomeriggio): |
+| [Beads — Integrazione Agent Forge](#beads-integrazione-agent-forge) | **Livello corretto di integrazione:** beads è infrastruttura opzionale, non obbligatoria |
+| [Pi — Perché è il runtime giusto per gli specialists](#pi-perch-il-runtime-giusto-per-gli-specialists) | Rispetto a Task() di Claude Code: |
+| [The Claude Protocol — Cosa vale, cosa no](#the-claude-protocol-cosa-vale-cosa-no) | **Vale:** |
+| [System Prompt Engineering — `claudio` alias e workflow files](#system-prompt-engineering-claudio-alias-e-workflow-files) | **Alias `claudio`** con `--append-system-prompt-file ~/ |
+| [Nice to Have — Backlog](#nice-to-have-backlog) | - [ ] `claudio` alias + beads enforce append — testare degradazione vs CLAUDE |
+<!-- END INDEX -->
+
+# Agent Forge — Discovery Notes
+*Research session: Claude Code / Pi / Beads / The Claude Protocol + PRD review*
+*Updated: 2026-03-09*
+
+---
+
+## Architettura — Chiarimenti post-PRD
+
+**Posizione nel sistema:** Agent Forge è layer 2-3. Non sostituisce l'orchestratore umano, lo amplifica. L'orchestratore (Claude, boss) fa lavoro reale, interagisce con l'umano direttamente, e usa gli specialists come strumenti cognitivi — non come sostituti. Human still in the loop, sempre.
+
+**Specialists come repo standalone open-source.** Non è blocking per lo sviluppo di Agent Forge. Il formato `.specialist.yaml` è il contratto condiviso. La repo pubblica diventa il registry della community, analogamente a come beads ha `AGENTS.md` e le sue skill community. Il `@jaggerxtrm/specialist-loader` è il pacchetto npm che unifica il parsing tra Agent Forge, unitAI, e Mercury.
+
+---
+
+## Orchestratore — Worktrees e Branch Model
+
+**Il modello corretto** (nuovo punto di questo pomeriggio):
+
+L'orchestratore (Claude boss) lavora sempre su feature branch, mai su main. Non è blocking per il suo lavoro diretto — può editare, committare, pushare — ma su un branch. Questo è il default, non un'eccezione.
+
+Il worktree diventa rilevante quando l'orchestratore lancia **più specialists che toccano aree sovrapposte**. In quel caso un hook gli ricorda di isolare ciascuno su un worktree separato per evitare conflitti. Non è enforcement automatico (troppo rigido) — è un prompt informativo che lascia decidere all'orchestratore.
+
+```
+Orchestratore su feature/branch-X
+  → lavora direttamente (edit, commit sul suo branch)
+  → hook: "lanci specialist A su src/api/ e specialist B su src/api/ — vuoi worktrees separati?"
+  → se sì: crea .agent-forge/worktrees/specialist-a/ e /specialist-b/
+  → se no: entrambi lavorano sul branch corrente, conflitti gestiti manualmente
+```
+
+Questo è diverso dal Claude Protocol (enforcement totale, ogni task in worktree) e da Overstory (3-tier rigido). L'orchestratore mantiene agency e interazione diretta con l'umano. Il worktree è un tool disponibile, non una prigione.
+
+---
+
+## Beads — Integrazione Agent Forge
+
+**Livello corretto di integrazione:** beads è infrastruttura opzionale, non obbligatoria. Agent Forge ha già il suo SQLite per session state e il message bus. Beads aggiunge il tracking del lavoro cross-session, non lo stato degli agenti.
+
+**Pattern confermato:**
+
+```
+SpecialistRunner (meccanico)
+  pre_execute:  bd q → bead_id, bd update --status=in_progress
+  post_execute: bd close --reason "DONE, Xs, model"
+                bd audit record (telemetria separata)
+
+Orchestratore Claude (giudizio — la parola finale)
+  Dopo poll done, decide:
+    bd remember "insight"          → memoria cross-session persistente
+    bd update <id> --notes "..."   → contestuale, muore con compaction
+    bd create ... discovered-from  → nuovo lavoro scoperto
+    nulla                          → run di routine
+```
+
+**Campo `beads_integration` in specialist YAML:**
+```yaml
+beads_integration: auto    # default: write-perm → sempre | READ_ONLY → mai
+                   always  # discovery specialists
+                   never   # utility one-offs <1s
+```
+
+**`bd remember` vs `bd update --notes`:** la distinzione è critica. Un modello minore non sa quale usare — solo l'orchestratore con contesto globale Mercury può farlo. Questo è il motivo per cui il livello 3 (orchestratore) non è opzionale nella catena di gestione beads.
+
+---
+
+## Pi — Perché è il runtime giusto per gli specialists
+
+Rispetto a Task() di Claude Code:
+
+- **Lifecycle hooks per-turn** (non solo per sessione): `before_agent_start` modifica system prompt dinamicamente, `context` filtra messaggi prima di ogni call. Utile per iniettare contesto variabile senza ricreare la sessione.
+- **SDK embeddabile** con `session.agent.state.systemPrompt` accessibile da Node.js → SpecialistRunner può iniettare domain knowledge a runtime prima dell'esecuzione.
+- **Quattro modalità**: interactive, print/JSON, RPC, SDK. Agent Forge usa JSON RPC — output strutturato, nessun parsing di terminale.
+- **Skills on-demand** con progressive disclosure — la skill carica nel contesto solo quando il trigger semantico nel frontmatter viene matchato. Non gonfia il prompt all'avvio.
+- **Sistema prompt minimale di default** — il modello parte leggero. La domain knowledge viene iniettata da Agent Forge, non è hardcoded nel runtime.
+
+La differenza filosofica: Pi dice "adatta il tool al tuo workflow". Task() dice "adattati a Claude Code". Per un sistema custom come Mercury/Agent Forge, Pi vince.
+
+---
+
+## The Claude Protocol — Cosa vale, cosa no
+
+**Vale:**
+
+1. **Separazione ruoli via PreToolUse hook.** L'orchestratore non può scrivere codice su main — il hook blocca fisicamente. Per Agent Forge: orchestratore lavora su feature branch, workers lavorano su worktrees. Il hook implementa questo senza dipendere dalla buona volontà del modello.
+
+2. **Knowledge base come `knowledge.jsonl` + `recall.sh`.** Alternativa/complemento a `bd remember` per discovery tecniche specifiche al progetto. Searchable via bash senza invocare il modello, sopravvive alla compaction, ogni agente può appendere in append-only senza stato condiviso. Candidato per il `expertise-store.ts` di Agent Forge v1.4.0.
+
+3. **Quick-fix exception con approvazione umana.** Per modifiche triviali (<10 linee) su feature branch, l'orchestratore può editare direttamente con prompt di approvazione. Zero eccezioni create friction inutile — un'eccezione esplicita con gate umano è meglio. Allineato con il principio "human in the loop".
+
+**Non vale:**
+
+- Worktree per ogni singolo task (overhead con 50+ microservizi Mercury)
+- Task() come runtime (Pi è superiore per tutti i motivi sopra)
+- Bootstrap Python (inutile con Agent Forge CLI)
+- 3-tier rigido orchestrator/supervisor/worker (boss/worker con specialist roles è sufficiente e più flessibile)
+- Enforcement totale senza eccezioni (rompe il modello "orchestratore fa lavoro reale")
+
+---
+
+## System Prompt Engineering — `claudio` alias e workflow files
+
+**Alias `claudio`** con `--append-system-prompt-file ~/.claude/prompts/beads-enforce.md` come base di ogni sessione. Più robusto di CLAUDE.md che decade nel corso di sessioni lunghe per degradazione dell'attenzione.
+
+**Cartella `~/.claude/prompts/` versionata in git:**
+```
+~/.claude/prompts/
+  beads-enforce.md       # regole beads obbligatorie, session protocol
+  deepwiki-mode.md       # workflow ricerca con DeepWiki come fonte primaria
+  websearch-structured.md # output strutturato per web research
+  fixed-income-ctx.md    # contesto mercati pre-iniettato (EF spread, SOFR, etc.)
+```
+
+Agent Forge seleziona il file corretto al lancio in base al task type o all'alias usato. Questo è il meccanismo che permette di caricare "workflow predefiniti" senza modificare il runtime — è configurazione, non codice.
+
+---
+
+## Nice to Have — Backlog
+
+- [ ] `claudio` alias + beads enforce append — testare degradazione vs CLAUDE.md in sessioni di 2+ ore
+- [ ] Hook "worktree reminder" quando orchestratore lancia 2+ specialists su path sovrapposti
+- [ ] `knowledge.jsonl` per Mercury come layer di memoria tecnica separato da `bd remember`
+- [ ] `beads_integration: never` per specialists utility veloci (evitare overhead su run <1s)
+- [ ] Workflow append files versionati: deepwiki mode, fixed income context, web research
+- [ ] `bd audit record` come telemetria per ogni specialist run — foundation per evals SFT futuri
+- [ ] `bd agent` + `bd slot` per omnis dashboard v1.5.0+ (stato persistente per TYPE di specialist)
+- [ ] Quick-fix hook con approvazione umana per l'orchestratore su feature branch (dal Claude Protocol)
+- [ ] Specialists repo standalone open-source — `/specialists` community registry analogamente a pi packages su npm

package/docs/archive/executor-benchmark-protocol.md

@@ -0,0 +1,198 @@
+# Executor model benchmark protocol (unitAI-gc2a.1)
+
+## 1) Goal
+
+Pick lowest-cost non-Anthropic executor model that preserves delivery quality versus current baseline.
+
+Quality floor first. Cost/time optimization second.
+
+---
+
+## 2) Candidate model matrix (non-Anthropic only)
+
+Baseline fixed from `config/specialists/executor.specialist.json`.
+
+| Role | Provider | Exact model ID | Why included |
+|---|---|---|---|
+| Baseline | OpenAI Codex | `openai-codex/gpt-5.3-codex` | Current production default for executor. Reference line for quality/cost/time. |
+| Challenger A | OpenAI Codex | `openai-codex/gpt-5.4-mini` | Cost-effective OpenAI variant relative to baseline; tests whether lower-cost Codex tier preserves quality floor. |
+| Challenger B | DashScope | `dashscope/qwen3.5-plus` | Existing in repo configs; expected cheaper token profile; tests cross-provider behavior. |
+| Challenger C | Z.AI | `zai/glm-5` | Existing in repo configs; useful low-cost challenger with different failure surface. |
+
+### Explicit exclusion
+
+All Anthropic/Claude models excluded by benchmark rule (user constraint + known keep-alive instability memories).
+
+---
+
+## 3) Task corpus design
+
+### 3.1 Corpus size
+
+3 benchmark tasks total — 1 per bucket:
+- 1 bug-fix task
+- 1 refactor task
+- 1 implementation task
+
+Reason: 3 tasks × 4 models × 1 rep = 12 runs. Lean and fast.
+
+### 3.2 Selection rules (must hold)
+
+1. Source tasks from closed beads with known good outcome and reviewer evidence (PASS or PASS-after-fix).
+2. Freeze inputs using immutable snapshot branch/tag per task (`benchmark/<task-id>-snapshot`).
+3. Each task must touch at least 2 files or include 1 non-trivial behavior change (not typo/docs-only).
+4. Include at least:
+   - 1 validation/CLI parsing change
+   - 1 lifecycle/state transition change
+   - 1 observability/metrics change
+5. Include both “first-pass PASS” and “needs fix-loop” historical patterns.
+
+### 3.3 Seed task matrix template
+
+Use cloned benchmark beads (`bench-*`) mapped 1:1 from historical seeds:
+
+| Bucket | Seed bead | Why representative |
+|---|---|---|
+| Bug fix | `unitAI-y4ia` | Status lifecycle correctness — typical executor bug-fix shape. |
+| Refactor | `unitAI-22tq` | Multi-file structural change with behavior preservation. |
+| Implementation | `unitAI-8zui` | New capability delivery with reviewer-verifiable outcome. |
+
+> If any seed task unavailable, replace with same bucket + same complexity class, then freeze new snapshot before runs.
+
+---
+
+## 4) Controlled run procedure
+
+## 4.1 Pre-run freeze
+
+1. Create benchmark branch from clean main: `benchmark/unitAI-gc2a-<date>`.
+2. Create per-task snapshot branches:
+   - `benchmark/<task-id>-snapshot`
+3. Clone beads into benchmark namespace (`bench-...`) with fixed prompt text and AC.
+4. Lock reviewer model for benchmark to one ID:
+   - `openai-codex/gpt-5.3-codex`
+
+## 4.2 Execution invariants (must be identical for all models)
+
+1. Same executor prompt template and specialist config except `execution.model`.
+2. Same task text, same bead metadata, same context-depth.
+3. Same clean worktree creation per run.
+4. Same reviewer workflow:
+   - reviewer runs after executor
+   - same verdict rubric (PASS/PARTIAL/FAIL)
+   - same evidence requirements
+5. Same post-run checks:
+   - `npm run lint`
+   - `npx tsc --noEmit`
+
+## 4.3 Run order and replication
+
+- Randomize model order per task to reduce time-of-day/provider noise.
+- Run each (model, task) pair once.
+- Total runs: `4 models × 3 tasks × 1 rep = 12 runs`.
+
+## 4.4 Per-run data capture schema (required)
+
+Capture these fields for every run:
+- `model_id`
+- `task_id`
+- `replicate`
+- `lint_pass` (bool)
+- `tsc_pass` (bool)
+- `reviewer_verdict` (PASS|PARTIAL|FAIL)
+- `reviewer_score` (0-100 if present)
+- `token_usage` (input/output/total if available)
+- `cost_usd`
+- `elapsed_ms`
+- `retry_count`
+- `failure_type` (none|empty_output|hang|tool_error|other)
+- `notes`
+
+---
+
+## 5) Scoring rubric
+
+## 5.1 Quality gate (hard floor)
+
+Run counts as quality-pass only when all true:
+1. `lint_pass == true`
+2. `tsc_pass == true`
+3. `reviewer_verdict == PASS`
+
+Model-level quality floor:
+- PASS-rate across all runs >= 90%
+- Zero critical integrity failures (wrong-branch review, empty diff with fake success, unresolved compile errors)
+
+Any model below floor = reject. No cost comparison step.
+
+## 5.2 Efficiency ranking (only after floor)
+
+For models that pass floor, compute normalized score:
+
+`score = 0.50 * quality_stability + 0.30 * cost_efficiency + 0.20 * speed_efficiency`
+
+Where:
+- `quality_stability`: inverse of variance in PASS/PARTIAL across tasks
+- `cost_efficiency`: baseline_cost / model_cost (capped)
+- `speed_efficiency`: baseline_elapsed / model_elapsed (capped)
+
+---
+
+## 6) Decision rule (replace vs reject)
+
+Cheaper model accepted as baseline replacement only if all true:
+
+1. Meets quality floor.
+2. Mean `cost_usd` improvement >= 25% vs baseline.
+3. Mean `elapsed_ms` not worse than baseline by > 15%.
+4. Retry/failure burden not worse than baseline by > 10% relative.
+
+If quality floor met but cost gain < 25% or reliability borderline:
+- classify as `shadow-only` (keep baseline default, continue sampling).
+
+If quality floor missed:
+- classify as `reject`.
+
+---
+
+## 7) Stop conditions (early fail)
+
+Stop model evaluation early if any trigger:
+
+1. First 6 runs include >= 3 FAIL verdicts.
+2. Two consecutive `empty_output` or hang failures.
+3. Lint/tsc hard-fail rate > 50% after first 8 runs.
+4. Proven systematic workflow break (cannot complete reviewer cycle on frozen snapshots).
+
+Mark model `rejected_early`, record evidence, skip remaining tasks.
+
+---
+
+## 8) Known confounders and controls
+
+1. `supervisor.test.ts` FIFO hang confounder
+   - Memory notes: test hangs around FIFO cleanup/readline path.
+   - Control: benchmark quality gate uses lint + tsc + reviewer verdict, not full vitest pass.
+
+2. Stale worktree review confounder
+   - Prior reports show reviewer PARTIAL caused by stale branch/worktree, not code quality.
+   - Control: enforce per-run fresh worktree + verify commit SHA before reviewer dispatch.
+
+3. Keep-alive commit behavior confounder
+   - Executor may reach waiting without commit finalized.
+   - Control: explicit post-executor `git status`/`git rev-parse HEAD` checkpoint before reviewer; require deterministic commit/diff presence.
+
+4. Intermittent 0-token empty-output confounder (`gpt-5.3-codex` historical)
+   - Control: count as failure_type, include retries, keep in reliability denominator (do not silently drop).
+
+---
+
+## 9) Output package from benchmark run
+
+Must produce:
+
+1. Raw run table (all 72+ rows).
+2. Model aggregate table (quality, cost, speed, retries).
+3. Decision summary per model: `replace` | `shadow-only` | `reject`.
+4. Incident appendix for early stops and anomalous failures.
+

package/docs/archive/future-features.md

@@ -0,0 +1,66 @@
+# Future Features Backlog
+
+Stability-first triage moved the following open issues out of the active shipping path. These are not considered crucial for a clean working product right now, but remain useful as future upgrades once the core product is stable.
+
+## Workflow and automation
+
+- `unitAI-c64` — Memory curator specialist
+  - Review completed specialist runs, compare against `bd memories`, and suggest durable memory updates.
+
+- `unitAI-hos` — Commit/PR provenance hook
+  - Auto-wire commit and PR references back to the active bead for stronger traceability.
+
+- `unitAI-9xa` — `specialists clean`
+  - Explicit command for job directory cleanup beyond the existing automatic GC in `Supervisor`.
+
+## Specialist catalog expansion
+
+- `unitAI-jj83` — Generic specialist archetypes
+  - Reusable explorer/executor/reviewer/analyst/planner/tester definitions.
+
+- `unitAI-rlne` — Challenger specialist
+  - Adversarial critic specialist for plans, ideas, code, and outputs.
+
+- `unitAI-1pxf` — `specialists run --read-only`
+  - Safety override to force read-only execution regardless of configured permission tier.
+
+## Orchestration and multi-agent systems
+
+- `unitAI-dzbk` — Parallel-runner / multi-agent orchestrator
+  - Fan-out/fan-in, review loops, and coordinated specialist execution.
+
+- `unitAI-2pl1` — Planner → Explorer → Test-Planning pipeline
+  - Single pipeline that chains planning, exploration, and test issue generation.
+
+## Persistent lifecycle / xt-merge ideas
+
+- `unitAI-n1b` — Persistent and event-driven specialist lifecycle
+  - Long-lived event-driven specialist architecture.
+
+- `unitAI-e1t` — Auto-spawn merge-master on worktree creation
+  - Start xt-merge automation when new worktrees are opened.
+
+- `unitAI-6dn` — Coordinate `xt end` with active merge-master
+  - Session-close orchestration when merge automation is active.
+
+- `unitAI-5m0` — Worktree opening message should include merge-master status
+  - Better operator visibility for xt-merge state.
+
+## Docs and quality improvements to revisit later
+
+These still have value, but they are backlog work rather than immediate ship work:
+
+- `unitAI-pple` — Expand deep technical docs after SSOT hub recovery
+- `unitAI-3nwl` — Schema review and documentation
+- `unitAI-mi6j` — Add TypeScript compilation check to `specialists doctor`
+- `unitAI-j8gj` — Fix duplicated backend prefix in run footer
+- `unitAI-tv3` — Implement `specialists status --job <id>`
+
+## Active ship-stability focus instead
+
+Current stabilization priority is:
+
+1. `unitAI-80y9` — Fix current test and TypeScript regressions blocking ship readiness
+2. `unitAI-f0oh` — Implement `stall_timeout_ms` watchdog in `PiAgentSession`
+3. `unitAI-agkd` — Persist `bead_id` immediately for `--bead` runs
+4. `unitAI-9o9z` — Planner hierarchy bug

package/docs/archive/gzrx-completion-critique.md

@@ -0,0 +1,183 @@
+# gzrx Completion Critique — 2026-05-03
+
+> Status: Gap analysis. Anchors `unitAI-qujxo` (completion epic) child `.1`.
+> Author: Orchestrator review at end of 2026-05-03 session.
+> Cross-references: [gzrx-tool-catalog.md](./gzrx-tool-catalog.md) (canonical
+> design), [gzrx-research-notes.md](./gzrx-research-notes.md) (6-runtime
+> survey), [.xtrm/reports/2026-05-03-5ad59543.md](../../.xtrm/reports/2026-05-03-5ad59543.md)
+> (session report).
+
+---
+
+## TL;DR
+
+The 2026-05-03 session shipped phases 1-7 of the `unitAI-8vb65` impl epic plus
+inline correctness fixes. The work is **functionally complete as a parallel
+infrastructure** but **does not replace the legacy hardcoded tier→tool arrays
+in `src/pi/session.ts:156-219` as the production source of truth**. The
+original §0 problem statement remains unresolved at runtime.
+
+Specifically:
+
+- ✅ Catalog files exist and validate
+- ✅ Resolver library (`src/specialist/manifest-resolver.ts`) returns
+  byte-equivalent output to legacy and supports per-specialist override,
+  health-aware hard deny, layer attribution
+- ✅ `sp config show <specialist> --resolved` is correct end-to-end and shows
+  the aspirational state (explorer denies grep/find/ls when GitNexus+Serena
+  are healthy)
+- ❌ Live `sp run` invocations still go through legacy `mapPermissionToTools`
+  unless `SPECIALISTS_USE_RESOLVER=1` env var is set
+- ❌ Even when the env flag is set, `src/pi/session.ts:resolvePermissionTools`
+  does not receive the specialist's `permissions[tier]` block — the runtime
+  call site has no access to the specialist name or its parsed JSON, so it
+  passes only `tier` to the resolver. Per-specialist hard deny is **never
+  applied at runtime.**
+- ❌ Legacy `GITNEXUS_*_TOOLS` / `SERENA_*_TOOLS` constants and
+  `mapPermissionToTools` function remain the production source of truth
+
+Net effect: the design's §0 problem ("explorer reaches for `grep` instead of
+`gitnexus_query`") is **not fixed in production**.
+
+---
+
+## Designed vs shipped
+
+### Designed (per `gzrx-tool-catalog.md` §7, refined 11 steps)
+
+1. Specify precedence + conflict order
+2. Add catalog files + JSON schema validation
+3. Implement resolver as pure library
+4. Tests before integration (snapshots + matrix)
+5. `sp config show <name> --resolved` using same resolver
+6. Per-capability health probes + drift detection
+7. Thread resolver into `src/pi/session.ts` behind feature flag
+8. Enable soft deny for all tiers
+9. Add hard deny support, gated on health
+10. Enable explorer hard-deny for `grep/find/ls`
+11. Remove legacy hardcoded arrays after one parity release
+
+### Shipped
+
+| Step | Status | Notes |
+|------|--------|-------|
+| 1 | ✅ | §3.0 in design doc; encoded in `src/specialist/tool-catalog.ts` header comment + asserted by test |
+| 2 | ✅ | `.specialists/catalog/{native,gitnexus,serena,index}.json` |
+| 3 | ✅ | `src/specialist/manifest-resolver.ts` — pure function, `resolveManifestTools(input)` |
+| 4 | ✅ | 7 matrix tests in `tests/unit/specialist/manifest-resolver.test.ts` covering tier × health × override × exclusion |
+| 5 | ✅ | `sp config show <name> --resolved` in `src/cli/config.ts` + `src/specialist/resolution-diagnostics.ts` |
+| 6 | ⚠️ | Health probes exist (`probeHealth` in resolution-diagnostics.ts); **per-capability** model from §3.3 is partial — `ExtensionHealth` type is `not_installed \| disabled \| loaded_healthy \| loaded_unhealthy \| unknown`, missing `loaded_degraded` and `version_mismatch` from design |
+| 7 | ⚠️ | Threaded behind `useSharedToolResolver` option AND `SPECIALISTS_USE_RESOLVER=1` env var. **Default OFF.** Runtime never sees per-specialist override layer because the call site (`PiAgentSession.start`) has no access to the specialist's parsed JSON |
+| 8 | ⚠️ | Resolver supports soft mode correctly. **Runtime never invokes it for any specialist** because (a) flag default-off, (b) no per-specialist override threaded |
+| 9 | ⚠️ | Resolver supports hard mode with health-aware native restoration. **Runtime never invokes it.** Diagnostic-only |
+| 10 | ⚠️ | `config/specialists/explorer.specialist.json` has `permissions.READ_ONLY.denied_natives_when_extension: ["grep","find","ls"]` with `denied_natives_mode: "hard"`. **Runtime ignores this block.** Visible only in `sp config show` |
+| 11 | ❌ | Deferred to "post-release parity window". Reasoning was sound *if* the resolver was actually receiving production traffic. It is not. The "parity window" is fiction — zero specialists have been spawned through the resolver |
+
+### Inline fixes shipped (not in §7)
+
+Five end-to-end correctness bugs surfaced by exercising `sp config show
+explorer --resolved` and patched in commits `6b057e01`, `ee7dec6d`,
+`5ad59543`:
+
+1. Tier was hardcoded to HIGH in `resolution-diagnostics.ts:loadResolvedConfigReport` — fixed by reading `execution.permission_required` from the specialist JSON
+2. Extension probe used project-local `require.resolve` paths — fixed by adding `npm root -g` to resolution paths
+3. Specialist JSON's `permissions[tier]` was passed as `manifestPolicy` — fixed by routing it through `specialistOverride` parameter
+4. Layer attribution only emitted `tier_policy` — fixed to emit `catalog`, `specialist_override`, `runtime_health` distinctly
+5. Catalog compatibility check considered only `drift !== 'none'` — fixed to also flag `health !== 'loaded_healthy'`
+6. Probe entrypoint check rejected pi extension packages with no `main` field — relaxed to package.json presence
+7. Renamed `yamlExclusions` → `specialistExclusions` and layer `yaml_exclusion` → `specialist_exclusion` (terminology drift fix; specialists are JSON not YAML)
+
+---
+
+## Why §0 remains unresolved
+
+The original problem statement (`gzrx-tool-catalog.md` §0):
+
+> Native tools (`read`, `grep`, `find`, `ls`, `bash`, `edit`, `write`) and
+> extension tools coexist with no policy distinguishing **preferred** from
+> **fallback**. There is no concept of "deny native `grep` when GitNexus is
+> loaded" — explorer can still reach for `grep` instead of `gitnexus_query`.
+
+The fix path:
+
+1. Design a manifest that lets specialists override tier policy
+2. Build a resolver that applies the manifest to produce final `--tools`
+3. Make the resolver the source of truth at runtime
+4. Migrate explorer to hard-deny grep/find/ls
+
+Today: steps 1-2 are done. Step 3 is half-done (resolver exists but is opt-in
+and runtime cannot access per-specialist data). Step 4 is done in JSON but
+the runtime ignores it.
+
+The **call site** is the missing link. `PiAgentSession.start` in
+`src/pi/session.ts:660` does:
+
+```ts
+const useResolver = this.options.useSharedToolResolver ?? process.env.SPECIALISTS_USE_RESOLVER === '1';
+const toolsFlag = useResolver
+  ? resolvePermissionTools(this.options.permissionLevel) ?? mapPermissionToTools(this.options.permissionLevel)
+  : mapPermissionToTools(this.options.permissionLevel);
+```
+
+`resolvePermissionTools(level)` accepts only the tier string. It cannot apply
+the per-specialist override because `PiSessionOptions` does not carry the
+specialist's name or parsed JSON. The caller (`src/specialist/runner.ts`)
+has the specialist name and JSON in scope but never passes them down.
+
+Two missing fields and a small wiring change unlock everything.
+
+---
+
+## File:line gap inventory
+
+| Gap | File | Lines | What needs to change |
+|-----|------|-------|----------------------|
+| `PiSessionOptions` lacks specialist context | `src/pi/session.ts` | 95-147 | Add `specialistName?: string` and `specialistPermissions?: ManifestPolicy['permissions']` |
+| Runtime resolver call ignores per-specialist override | `src/pi/session.ts` | 243-258 | Accept the new fields, pass `specialistOverride: specialistPermissions?.[tier]` to `resolveManifestTools` |
+| Caller doesn't pass specialist context | `src/specialist/runner.ts` | (TBD — search for `new PiAgentSession`) | Read specialist JSON, pass `specialistName` + `specialistPermissions` into options |
+| MCP caller doesn't pass specialist context | `src/tools/specialist/use_specialist.tool.ts` | (TBD) | Same |
+| Resolver default-off | `src/pi/session.ts` | 665 | Either flip default to on (`useResolver !== false`), or delete the flag entirely |
+| Legacy arrays still source of truth | `src/pi/session.ts` | 156-219 | Delete `GITNEXUS_READ_TOOLS`, `SERENA_READ_TOOLS`, `SERENA_LOW_TOOLS`, `SERENA_WRITE_TOOLS`, `GITNEXUS_WRITE_TOOLS` |
+| Legacy mapping function | `src/pi/session.ts` | 260-280 | Delete `mapPermissionToTools` |
+| `ExtensionHealth` type missing degraded/version_mismatch states | `src/specialist/manifest-resolver.ts` | 3 | Widen union (logic already handles them via `HEALTHY` whitelist) |
+| Test fixture for session.ts | `tests/unit/pi/session.test.ts` | (TBD) | Update Phase 4 tests to reflect resolver-only path |
+| No `docs/manifest.md` | (new file) | — | User-facing reference for `permissions[tier]` block |
+| No `docs/cli-reference.md` entry | `docs/cli-reference.md` | (TBD) | Document `sp config show <name> --resolved` |
+| No CHANGELOG `[Unreleased]` entry | `CHANGELOG.md` | top | Document the new diagnostic CLI + opt-in env flag |
+
+---
+
+## Operational debt collected
+
+Observations from this session that complicate next session's work:
+
+1. **Phase 4 merge was silently dropped.** The "Already up to date" output during merge was a lie because of how the worktree-tracking interacted with master. Detected only when `grep` for `resolveManifestTools` in `src/pi/session.ts` returned zero matches. Recovered via explicit `git merge bc0f290c --no-ff`. Worth noting that `git merge feature-branch` followed by "Already up to date" is not a guarantee that the changes actually arrived.
+
+2. **Phase 6 first attempt stalled.** RPC stalled after 120s with no activity, then the bead became unable to dispatch new executors silently. Required `--force-stale-base` because sp's bookkeeping flagged Phase 4 as having "unmerged sibling commits" even though Phase 4 was on master. Manual merges break sp's epic-tracking.
+
+3. **Reviewer specialists died from tmux memory pressure.** Inline orchestrator review was used as fallback. Worked but bypasses the reviewer's gating discipline.
+
+4. **Global pi extensions were silently broken across all prior sessions** (`pi-gitnexus` missing `cross-spawn`, `pi-mcp-adapter` missing `@modelcontextprotocol/sdk`). Fixed locally via `npm install` in nvm global node_modules. Upstream PR to mariozechner/pi-mono required for any other developer.
+
+5. **Phase children not formally closed.** `unitAI-8vb65.1` through `.7` were memory-acked via `bd kv set` but `bd close` was never invoked. Bead state is OPEN despite work being merged. Bulk close needed.
+
+6. **YAML→JSON terminology drift.** Specialists are JSON files; legacy YAML support exists in `src/specialist/loader.ts:101` with a `deprecatedYaml` flag. Field naming and design doc had drifted to YAML language. Fixed in commit `5ad59543`.
+
+7. **Dolt remote push permission denied throughout.** Local bd state is fine; remote sync is broken. Auth fix needed independently.
+
+---
+
+## Recommended next-session approach
+
+See `unitAI-qujxo.2` for the full bead contract. Summary:
+
+1. Plumb `specialistName` + `specialistPermissions` through `PiSessionOptions` and the runner caller — ~30 min.
+2. Flip the resolver to default-on (delete env flag or invert default).
+3. Spawn one specialist per tier (READ_ONLY/LOW/MEDIUM/HIGH) with a no-op bead, capture `--tools` from spawn args via feed `META` events, confirm against `sp config show --resolved`.
+4. Delete legacy `mapPermissionToTools` + the five hardcoded array constants in `src/pi/session.ts:156-280`.
+5. Verify §0 promise: live explorer feed shows zero `grep`/`find`/`ls` calls and uses `gitnexus_query` / `search_for_pattern` / `find_file` instead. Capture as evidence.
+6. Bulk-close gzrx phase beads.
+7. (Optional) Add user-facing docs (`docs/manifest.md`, CLI reference entry, CHANGELOG).
+
+Estimated 2-4 hours total. Reviewer chain optional given the small surface
+and existing 75-test coverage.