npm - @jaggerxtrm/specialists - Versions diffs - 3.15.1 → 3.15.3 - Mend

@jaggerxtrm/specialists 3.15.1 → 3.15.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +175 -97
package/config/skills/using-specialists-v3/SKILL.md +113 -35
package/dist/asset-contract.json +2 -2
package/dist/index.js +175 -68
package/dist/lib.js +45 -25
package/dist/types/cli/run.d.ts.map +1 -1
package/dist/types/cli/serve.d.ts +1 -1
package/package.json +7 -5

package/README.md CHANGED Viewed

@@ -1,162 +1,241 @@
 # Specialists
-**One MCP server. Many specialists. Bead-first orchestration.**
+**One MCP server. Many specialist agents. Bead-first orchestration.**
 [![npm version](https://img.shields.io/npm/v/@jaggerxtrm/specialists.svg)](https://www.npmjs.com/package/@jaggerxtrm/specialists)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
-**Specialists is a universal framework for defining and running specialist agents.** You can invoke the same specialist from the terminal, through MCP inside coding agents, inside autonomous multi-agent runtimes, or from scripts and CI/CD pipelines. Each run can explicitly define the model, tool access, system prompt, task input, permission level, timeout, output format, tracking behavior, memory sources, and dependency context.
+Specialists is a project-scoped runtime for running focused AI agents from the CLI, MCP, scripts, CI, or HTTP sidecars. A specialist definition declares its model, tools, permission tier, prompt, skills, output contract, timeout/stall policy, worktree behavior, and tracking behavior. The orchestrator keeps task identity in a **bead**; specialists run as fresh scoped sessions that report evidence, changes, and results back to that bead.
-Specialists is built on top of the **[pi coding agent](https://github.com/Jaggerxtrm/pi-coding-agent)** as its base execution technology. That gives Specialists access to a broad provider surface across many OAuth and API-backed models, a richer lifecycle event stream for tracking session progress and tool execution, and a usable RPC protocol for orchestrating specialist runs as a stable subprocess boundary.
+Specialists sits in the xt/xtrm stack:
-Specialists is intended to run inside the **xt/xtrm architecture** provided by **[xtrm-tools](https://github.com/Jaggerxtrm/xtrm-tools)**. xtrm-tools provides the worktree isolation, execution boundaries, session model, and surrounding workflow environment that Specialists expects. Specialists handles specialist execution; xtrm-tools owns the broader operator workflow and beads enforcement hooks. For tracking and coordination Specialists uses **beads** by **Steven Yegge** as the issue, dependency, and communication layer. I built a similar issue system for Mercury AACS and Terminal back in November, but Beads is already widely used and actively maintained, so xt/Specialists is built around Beads instead of carrying a separate workflow stack. When a specialist run originates from a bead, its output is written back to that same bead, so the task spec, dependency context, coordination state, and result stay inside one tight, controlled loop.
+- **[pi coding agent](https://github.com/Jaggerxtrm/pi-coding-agent)** supplies the model/provider execution layer, JSONL/RPC subprocess boundary, tool events, and extension hooks.
+- **[xtrm-tools](https://github.com/Jaggerxtrm/xtrm-tools)** supplies the surrounding operator workflow: worktree sessions, `.xtrm/` skills/hooks, session reports, update tooling, and workflow enforcement.
+- **[beads](https://github.com/steveyegge/beads)** supplies issue IDs, dependency edges, claims, and durable task/result notes.
-A specialist is a reusable execution spec: model, allowed tools, skills, system prompt, task prompt, timeout, permission level, output format, and background-job behavior. It can run from a plain prompt, from a system+task prompt pair, or directly from an **issue/bead ID as the task source**. Dependency chains can be injected as context, centralized memory can be reused across runs, and jobs can execute in the foreground or as background processes with status, events, and results exposed through the CLI and MCP surfaces.
+When a run starts from `--bead <id>`, the bead is the task prompt. Dependency context and relevant memory can be injected, the specialist output is appended back to the same bead, and edit-capable specialists work in isolated branches/worktrees that can be reviewed and merged through `sp merge` or `sp epic merge`.
 ---
 ## Vision
-Specialists turns one overloaded agent chat into a coordinated agent mind: a central orchestrator keeps task identity and evidence, while fresh specialist sessions act as scoped capabilities with their own prompts, rules, memory, and contracts. See [specialists.scheme.md](specialists.scheme.md) for diagrams comparing the single-chat model with specialist pipelines, herd memory, adaptive chains, and service specialists.
+Specialists turns one overloaded agent chat into a coordinated agent mind: a central orchestrator keeps task identity, evidence, and publication control, while fresh specialist sessions act as scoped capabilities with their own prompts, rules, tools, memory, and output contracts.
+The problem it solves is not just token count. Long single-agent sessions accumulate old hypotheses, partial plans, tool residue, self-review bias, and forgotten constraints. Specialists uses **contract-bound cognition** instead: write the task contract once, dispatch the right expert role with only the relevant context, require a structured handoff, and let the orchestrator decide the next step.
+See [specialists.scheme.md](specialists.scheme.md) for the full diagrams and rationale. The core shape is:
+```mermaid
+flowchart TD
+  U[User / project need] --> O[Orchestrator]
+  O --> B[Bead issue contract]
+  B --> C{Contract ready?}
+  C -->|no| R[Repair scope, success, constraints]
+  R --> B
+  C -->|yes| D[Dispatch specialist]
+  D --> E[Explorer\nfresh read-only context]
+  D --> G[Debugger\nfresh root-cause context]
+  D --> X[Executor\nfresh implementation context]
+  D --> T[Test-runner\nfresh validation context]
+  D --> S[Code-sanity / Security\nadvisory context]
+  D --> V[Reviewer\ncontract compliance context]
+  B --> E
+  B --> G
+  B --> X
+  B --> T
+  B --> S
+  B --> V
+  E --> H[Structured handoff / evidence]
+  G --> H
+  X --> H
+  T --> H
+  S --> H
+  V --> H
+  H --> O
+  O --> P[Merge, resume, re-review, or close]
+```
-## Quick start
+## What you can run
-1. Install Bun.
+| Need | Specialist / surface |
+|---|---|
+| Map unfamiliar local code | `explorer` |
+| Diagnose a bug with unknown cause | `debugger` |
+| Implement a scoped change | `executor` |
+| Review an executor/debugger result | `reviewer --job <exec-job>` |
+| Run/classify tests | `test-runner` |
+| Current library/API/GitHub research | `researcher` |
+| Plan a multi-file feature into beads | `planner` |
+| Check code shape before review | `code-sanity` |
+| Audit security-sensitive diffs | `security-auditor` |
+| Sync exactly one doc | `sync-docs` |
+| Draft changelog gaps | `changelog-keeper` |
+| One-shot script/HTTP generation | `sp script` / `sp serve` |
+The live registry is authoritative:
 ```bash
-bun --version
-curl -fsSL https://bun.sh/install | bash
+sp list
+sp list --compact
+sp list-rules
+sp help
 ```
-2. Install xtrm-tools.
+## Install and bootstrap
+Specialists is **Bun-only** and expects xtrm-tools to be installed explicitly. xtrm-tools is a runtime prerequisite, not an npm dependency of this package.
 ```bash
+# 1. Bun
+curl -fsSL https://bun.sh/install | bash
+bun --version
+# 2. xtrm-tools
 npm install -g xtrm-tools
 xt install
 xt init
-```
-3. Install Specialists.
-```bash
+# 3. Specialists
 npm install -g @jaggerxtrm/specialists
 sp init
+sp doctor
 sp list
 ```
-`sp` is a shorter alias for `specialists` — both commands are identical:
+`sp` is an alias for `specialists`.
-```bash
-sp list
-sp run bug-hunt --bead <id>
-```
+`sp init` is an interactive, human-run bootstrap. It checks for `xt` and `.xtrm/`, wires project MCP registration, hooks, skill symlinks, `.specialists/` runtime directories, and the Specialists block in `AGENTS.md`. It does **not** require copying package-owned defaults into every repo.
-Tracked work:
+## Update and drift repair
+Specialists uses two distribution tracks:
+| Track | Owned by | What it covers | Check / update |
+|---|---|---|---|
+| **Category A** runtime assets | `@jaggerxtrm/specialists` package | specialist JSON, mandatory rules, catalog, nodes, hooks shipped with the package | `sp doctor --check-drift`, `sp prune-stale-defaults --dry-run`, `sp prune-stale-defaults` |
+| **Category B** filesystem assets | xtrm-tools | `.xtrm/skills`, `.claude/skills`, `.pi/skills`, hook snapshots read directly from disk | `xt doctor --cwd <repo> --json`, `xt update --repo <repo> --apply` |
+`.specialists/user/` is your customization layer. `.specialists/default/` is now only for intentional pins or compatibility snapshots; stale default files are drift debt and `sp prune-stale-defaults` removes them by default. `sp init --sync-defaults` remains as a compatibility path, but it is deprecated because it creates repo-local snapshots that can drift from the package-canonical source.
+## Core tracked workflow
 ```bash
 bd create "Investigate auth bug" -t bug -p 1 --json
-specialists run bug-hunt --bead <id>
-specialists feed -f
-bd close <id> --reason "Done"
+bd update <id> --claim --json
+sp run debugger --bead <id> --context-depth 3
+sp ps
+sp feed <job-id> --follow
+sp result <job-id>
+# After implementation and reviewer PASS
+sp merge <chain-root-bead>          # standalone chain
+sp epic status <epic-id>            # multi-chain publication check
+sp epic merge <epic-id>             # canonical epic publication
+bd close <id> --reason "Done" --json
 ```
-Merge worktree branches:
+Ad-hoc work is still available, but tracked work should use beads:
 ```bash
-specialists merge <bead-id>           # single chain or epic (topological)
-specialists merge <bead-id> --rebuild # rebuild after merge
+sp run explorer --prompt "Map the CLI architecture"
 ```
-`specialists run` prints `[job started: <id>]` early. Normal runtime is DB-backed; `.specialists/jobs/latest` is legacy/operator-only.
+## Background jobs and monitoring
-Runtime state lives in `observability.db`; `.specialists/jobs/latest` is legacy convenience pointer only.
+Normal runtime is DB-first: `.specialists/db/observability.db` stores jobs, events, and results. File mirrors under `.specialists/jobs/` are legacy/operator recovery surfaces.
-Ad-hoc work:
+Useful commands:
 ```bash
-specialists run codebase-explorer --prompt "Map the CLI architecture"
+sp ps                         # actionable dashboard
+sp ps -f                      # TTY dashboard follow; pipes emit ANSI-free snapshots
+sp feed <job-id>              # full DB-backed event replay
+sp feed -f                    # follow all active jobs
+sp result <job-id> --wait
+sp steer <job-id> "focus only on X"
+sp resume <job-id> "continue with these findings"
+sp finalize <any-chain-job>   # cascade-close waiting keep-alive chain after PASS if needed
+sp clean --reap-orphans --dry-run
+sp clean --ps                 # hide terminal dashboard history without deleting DB audit rows
 ```
-## What `specialists init` does
+## Script and service specialists
-- creates `specialists/`
-- creates `.specialists/` runtime dirs (`jobs/`, `ready/`)
-- adds `.specialists/` to `.gitignore`
-- injects the canonical Specialists Workflow block into `AGENTS.md`
-- registers the Specialists MCP server at project scope
-Verify bootstrap state:
+Use `sp run` for interactive agent orchestration. Use the script/service surfaces when you need a synchronous, READ_ONLY, one-shot generation path:
 ```bash
-specialists status
-specialists doctor
+sp script <name> --vars key=value --json
+sp serve --port 8000 --readiness-canary warn
+curl -sS http://localhost:8000/v1/generate \
+  -H 'content-type: application/json' \
+  -d '{"specialist":"hello","variables":{"name":"world"}}'
 ```
-## Documentation map
+`sp serve` is intended as a sidecar for script-class specialists. For container deployments, mount the whole `.specialists/` directory read-write, set `HOME=/pi-home`, and align container UID/GID with the host user. See [docs/specialists-service.md](docs/specialists-service.md), [docs/specialists-service-install.md](docs/specialists-service-install.md), and [docs/deploying-alongside.md](docs/deploying-alongside.md).
-`docs/` is the source of truth for detailed documentation. Start with the page that matches your task:
+## Documentation map
 | Need | Doc |
 |---|---|
-| Install and bootstrap a project | [docs/bootstrap.md](docs/bootstrap.md) |
-| Release notes and version history | [CHANGELOG.md](CHANGELOG.md) |
-| Changelog drafting specialist | [config/specialists/changelog-keeper.specialist.json](config/specialists/changelog-keeper.specialist.json) |
-| Run a script-class specialist over HTTP (`sp serve`) — overview & contract | [docs/specialists-service.md](docs/specialists-service.md) |
-| Install `sp serve` in another project (sidecar Docker / Podman) | [docs/specialists-service-install.md](docs/specialists-service-install.md) |
-| Build & publish the specialists-service image | [docs/release-image.md](docs/release-image.md) |
-| Release flow (skill + specialist) | [config/skills/releasing/SKILL.md](config/skills/releasing/SKILL.md) |
-| Bead-first workflow and semantics | [docs/workflow.md](docs/workflow.md) |
+| Install, update, and distribution model | [docs/installation.md](docs/installation.md) |
+| Project bootstrap and `sp init` | [docs/bootstrap.md](docs/bootstrap.md) |
+| Bead-first workflow | [docs/workflow.md](docs/workflow.md) |
 | CLI commands and flags | [docs/cli-reference.md](docs/cli-reference.md) |
-| Background jobs, feed, result, stop | [docs/background-jobs.md](docs/background-jobs.md) |
-| Write or edit a `.specialist.yaml` | [docs/authoring.md](docs/authoring.md) |
-| Current built-in specialists | [docs/specialists-catalog.md](docs/specialists-catalog.md) |
-| MCP registration details | [docs/mcp-servers.md](docs/mcp-servers.md) |
-| Hook behavior | [docs/hooks.md](docs/hooks.md) |
-| Skills shipped in this repo | [docs/skills.md](docs/skills.md) |
-| xtrm / worktree integration | [docs/worktree.md](docs/worktree.md) |
-| RPC mode notes | [docs/pi-rpc.md](docs/pi-rpc.md) |
-| Pi subprocess isolation and extensions | [docs/pi-session.md](docs/pi-session.md) |
-| NodeSupervisor architecture, node lifecycle, and `sp node` CLI | [docs/nodes.md](docs/nodes.md) |
-## Ownership model
-Specialists uses layered ownership with deterministic loader precedence: user layer overrides default layer, and default layer falls back to package source (`.specialists/user/*` > `.specialists/default/*` > `config/*`). Operationally: `config/*` is upstream source shipped by package, `.specialists/default/*` is managed mirror refreshed by `specialists init --sync-defaults` (scope: specialists + mandatory-rules + nodes), `.specialists/user/*` is repo customization layer, and `.specialists/{jobs,ready,db}` is runtime/generated state; `.specialists/jobs/` is legacy mirror/debug surface, not normal-runtime source of truth. Use `sp edit --fork-from <base>` to promote non-user specialist into user layer before editing.
+| Background jobs / `ps` / `feed` / `result` | [docs/background-jobs.md](docs/background-jobs.md) |
+| Specialist JSON authoring | [docs/authoring.md](docs/authoring.md) |
+| Built-in specialists | [docs/specialists-catalog.md](docs/specialists-catalog.md) |
+| Tool catalog and permission resolver | [docs/manifest.md](docs/manifest.md) |
+| MCP registration and tool surface | [docs/mcp-servers.md](docs/mcp-servers.md), [docs/mcp-tools.md](docs/mcp-tools.md) |
+| Hooks | [docs/hooks.md](docs/hooks.md) |
+| Skills | [docs/skills.md](docs/skills.md) |
+| Worktrees and session close | [docs/worktrees.md](docs/worktrees.md), [docs/worktree.md](docs/worktree.md) |
+| Runtime architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
+| Pi subprocess isolation / RPC boundary | [docs/pi-session.md](docs/pi-session.md), [docs/pi-rpc-boundary.md](docs/pi-rpc-boundary.md) |
+| NodeSupervisor | [docs/nodes.md](docs/nodes.md) |
+| Service sidecar / HTTP contract | [docs/specialists-service.md](docs/specialists-service.md) |
+| Compose deployment recipe | [docs/deploying-alongside.md](docs/deploying-alongside.md) |
+| Release notes | [CHANGELOG.md](CHANGELOG.md) |
 ## Project structure
 ```text
 config/
-├── specialists/       canonical specialist definitions (.specialist.json)
-├── mandatory-rules/   canonical rule sets injected into specialist prompts (+ README)
-├── nodes/             canonical node configs
+├── specialists/       package-canonical specialist definitions (.specialist.json)
+├── mandatory-rules/   package-canonical rule sets injected into specialist prompts
+├── catalog/           package-canonical tool catalog
+├── nodes/             package-canonical node configs
 ├── hooks/             bundled hook scripts
-├── skills/            repo-local skills used by specialists
-└── extensions/        pi extensions (future)
+└── skills/            repo-local skills shipped by this package
 .specialists/
-├── default/           managed mirror of canonical (from sp init --sync-defaults)
-│   ├── specialists/
-│   ├── mandatory-rules/
-│   ├── nodes/
-│   ├── hooks/
-│   └── skills/
-├── user/              repo-owned customizations (overrides default + canonical)
-│   ├── specialists/
-│   ├── hooks/
-│   └── skills/
-├── mandatory-rules/   repo-specific rule overlay (wins on set-id conflict)
-├── jobs/              runtime — gitignored
-└── ready/             runtime — gitignored
-src/                CLI, server, loader, runner, tools
+├── user/              repo-owned specialists and overrides (highest precedence)
+├── default/           optional pins / compatibility snapshots; prune stale files
+├── mandatory-rules/   legacy/repo rule overlay compatibility
+├── db/                runtime SQLite state (gitignored)
+├── jobs/              legacy runtime mirror (gitignored)
+└── ready/             legacy ready markers (gitignored)
+.xtrm/
+├── skills/            xtrm-managed skill snapshots and active links
+└── hooks/             xtrm-managed hook snapshots
+src/                   CLI, server, loader, runner, supervisor, MCP tool
 ```
-## Core workflow rules
+## Core rules
-- **Use `--bead` for tracked work.** The bead is the prompt source.
-- **Use `--prompt` for ad-hoc work only.**
-- `--context-depth` controls how many completed blocker levels are injected.
-- `--no-beads` does **not** disable bead reading.
-- specialists are **project-only**. User-scope specialist discovery is deprecated.
+- Use `--bead` for tracked work; use `--prompt` only for quick untracked work.
+- `--context-depth` controls completed dependency context injection; default is 3 for bead runs.
+- `--no-beads` disables tracking bead creation/updates, but it does not disable reading the input bead when `--bead` is provided.
+- Edit-capable specialists run in isolated worktrees. Review/fix passes should use `--job <exec-job>` to reuse the same workspace.
+- Reviewer PASS is the publish gate. Code-sanity/security/test-runner outputs are advisory evidence, not merge approval.
+- Specialists are project-scoped. User-scope specialist discovery is deprecated.
 ## Deprecated commands
@@ -164,8 +243,9 @@ These commands are still recognized for migration guidance but are no longer onb
 - `specialists setup`
 - `specialists install`
+- `sp release prepare` / `sp release publish` (deprecated aliases; release flow is skill-driven)
-Use `specialists init` instead.
+Use `sp init`, `xt update`, and the release skill flow instead.
 ## Development
@@ -173,12 +253,10 @@ Use `specialists init` instead.
 bun run build
 bun test           # bun vitest run (default)
 bun run test:node  # node vitest run (subprocess-safe alternative)
-specialists help
-specialists quickstart
+sp help
+sp quickstart
 ```
-`test:node` uses plain `node vitest run` as an alternative to `bun --bun vitest`. Useful for executor/codex subprocess chains that may trigger stall detection during vitest's tinypool worker initialization silence.
 ## License
-MIT
+MIT — see [LICENSE](LICENSE).

package/config/skills/using-specialists-v3/SKILL.md CHANGED Viewed

@@ -7,7 +7,7 @@ description: >
   security checks, multi-step chains, integration-phase reconciliation,
   debugger-restitch on conflicting chains, pre-dispatch conflict-cluster
   mapping, test-failure-map epics, and questions about specialist workflow.
-version: 3.3
+version: 3.4
 ---
 # Using Specialists v3
@@ -279,24 +279,75 @@ Fix three bad smells fast:
 What differs: orchestrator writes contract before dispatch, so specialist does less guessing and more useful work.
-## Dependency Linking
+## Dependency Linking And Relationship Vocabulary
-Link beads with correct edge shape. The edge tells orchestrator what blocks what, what is only related, and what should auto-nest.
+Link beads with correct edge shape. The edge tells orchestrator what blocks execution, what only preserves context, which bead verifies another, and which issue has been replaced. Do not overload `blocks` for follow-ups, root-cause links, verification pairs, duplicates, or restitch replacements.
-- `bd dep add <issue> <depends-on>`: issue depends on depends-on; depends-on blocks issue. Use this for hard sequencing. [source: bd dep --help]
-- `bd dep <blocker> --blocks <blocked>`: reverse phrasing of same edge; blocker-first reads better when thinking in blockers. [source: bd dep --help; CLAUDE.md lines 62-64]
-- `bd dep relate <a> <b>`: non-blocking `relates_to` link. Use for context, not order. [source: bd dep --help; CLAUDE.md lines 64, 200-204]
-- `bd create --parent <epic-id>`: epic-child edge; auto-names child `.1`, `.2`, … and adds parent edge. Use for chain members that must live under epic. [source: CLAUDE.md lines 49-50, 154-156; bd create --help]
-- `bd create --deps discovered-from:<id>`: follow-up work discovered from source bead. Use when one bead reveals new tracked work. [source: CLAUDE.md lines 50, 62-65; bd create --help]
+Core commands:
+- `bd dep add <issue> <depends-on>`: issue depends on depends-on; depends-on blocks issue. Default type is `blocks`. Use only for hard sequencing. [source: bd dep add --help]
+- `bd dep <blocker> --blocks <blocked>`: reverse phrasing of the same hard sequencing edge. [source: bd dep --help]
+- `bd dep add <issue> <other> --type <type>`: store a typed relationship. Supported types: `blocks`, `tracks`, `related`, `parent-child`, `discovered-from`, `until`, `caused-by`, `validates`, `relates-to`, `supersedes`. [source: bd dep add --help]
+- `bd dep relate <a> <b>` / `bd dep unrelate <a> <b>`: bidirectional non-blocking `relates_to` link. Use for context, not order. [source: bd dep --help]
+- `bd create --parent <epic-id>`: epic-child edge; auto-names child `.1`, `.2`, … and adds parent ownership. Use for chain members that must live under an epic. [source: bd create --help]
+- `bd create --deps discovered-from:<id>` or `bd dep add <new> <source> --type discovered-from`: follow-up work discovered from a source bead.
+- `bd duplicate <new> --of <canonical>`: close duplicate issue and point at canonical. Use when two beads describe the same required work.
+- `bd duplicates` / `bd find-duplicates --status open --method ai --json`: find exact or semantic duplicates before dispatching parallel chains.
+- `bd supersede <old> --with <new>` or `bd dep add <new> <old> --type supersedes`: mark a replacement when a better-scoped fix bead replaces an obsolete/abandoned one.
+- `bd dep cycles`, `bd dep tree <id>`, and `bd graph <id>`: sanity-check the execution graph before merge/publication.
+Relationship vocabulary for specialist chains:
+| Relationship | Reach for it when | Example command |
+| --- | --- | --- |
+| `blocks` | Hard must-happen-before sequencing: planner before executor, implementation before reviewer, restitch before publish. | `bd dep add <impl> <plan> --type blocks` |
+| `tracks` | A local bead mirrors upstream or cross-project work whose status matters but is not owned here. | `bd dep add <local> external:xtrm-tools:<capability> --type tracks` |
+| `related` | Loose topical association when no direction or scheduling effect is intended. Prefer `bd dep relate` for bidirectional relation. | `bd dep add <a> <b> --type related` |
+| `parent-child` | Epic owns child chains. Prefer `bd create --parent <epic>` so IDs and parentage stay canonical. | `bd create --parent <epic> --title "Impl auth retry" ...` |
+| `discovered-from` | Reviewer, debugger, explorer, or test-runner surfaces new follow-up work from a run. | `bd dep add <follow-up> <reviewer-bead> --type discovered-from` |
+| `until` | Time-bounded or event-bounded precondition that blocks only until a stated condition lands. | `bd dep add <chain> <precondition> --type until` |
+| `caused-by` | Failure bead points to the root-cause bead/cluster that explains it. Makes test-failure-map epics navigable. | `bd dep add <failing-test> <root-cause> --type caused-by` |
+| `validates` | Reviewer, test-runner, code-sanity, or security-auditor bead verifies an implementation/debugger bead. | `bd dep add <review> <impl> --type validates` |
+| `relates-to` | Bidirectional context edge for conflict clusters, sibling designs, or rebuttal patterns. Prefer dedicated relate command. | `bd dep relate <chain-a> <chain-b>` |
+| `supersedes` | New fix/design/restitch bead replaces an older bead that should no longer be executed or merged. Prefer `bd supersede`. | `bd supersede <old> --with <new>` |
+Worked high-value patterns:
+```bash
+# Reviewer discovers a separate follow-up during review. Do not block the impl.
+bd create --title "Follow up: tighten retry metrics" --type task --priority 3 --description "..."
+bd dep add <follow-up> <review> --type discovered-from
+# Test-failure-map root cause: many failures point at one underlying issue.
+bd create --title "Root cause: stale fixture factory" --type bug --priority 2 --description "..."
+bd dep add <failing-test-bead> <root-cause> --type caused-by
+# Verification bead validates implementation. This is not a hard prerequisite edge.
+bd dep add <test-runner-bead> <impl> --type validates
+bd dep add <reviewer-bead> <impl> --type validates
+# Replacement bead supersedes an abandoned or wrongly scoped implementation.
+bd create --title "Restitch auth retry onto integration state" --type task --priority 2 --description "..."
+bd supersede <old-impl> --with <restitch>
+# Before merging an epic or integration branch, prove the graph is sane.
+bd dep cycles
+bd graph <epic> --compact
+```
 Use each form for a different reason:
-- `add` / `--blocks` for must-happen-before dependency.
-- `relate` for soft linkage with no schedule effect.
-- `--parent` for epic ownership and child naming.
-- `discovered-from:` for spawned follow-up beads.
+- `blocks` / `--blocks` for must-happen-before dependency only.
+- `validates` for review, test, sanity, and security evidence.
+- `discovered-from` for spawned follow-up beads.
+- `caused-by` for failure-to-root-cause attribution.
+- `relates-to` / `bd dep relate` for soft linkage with no schedule effect.
+- `parent-child` / `--parent` for epic ownership and child naming.
+- `supersedes` / `bd supersede` for replacement work; `duplicate` for same-work issues.
+Cross-repo consistency: keep this vocabulary aligned with the xtrm-tools triaging skill and sibling triage bead `xtrm-drkk`; both should use the same relationship names when rewiring issue graphs.
-What differs: orchestrator chooses edge type deliberately, so graph stays correct for chain execution, epic publish, and follow-up traceability.
+What differs: orchestrator chooses edge type deliberately, so graph stays correct for chain execution, epic publish, duplicate cleanup, root-cause navigation, verification evidence, and follow-up traceability.
 ## Bead Contract By Bead Type
@@ -537,11 +588,25 @@ Before dispatching N parallel chains, build the file-overlap matrix:
 For each cluster of overlapping chains, choose **one** of:
-1. **Serial dispatch** — execute chains in dependency order, each waits for previous to land. Slowest but cleanest.
-2. **Unified bead** — collapse all chains into one bead/executor pass. Larger reviewer scope but no merge conflicts.
-3. **Parallel dispatch + debugger restitch at integration** — dispatch in parallel, plan for ~40% conflict rate (empirical), budget debugger-restitch passes during integration.
+1. **Serial dispatch** — execute chains in dependency order, each waits for previous to land. Slowest but cleanest. Encode the order with `blocks`, not notes.
+2. **Unified bead** — collapse all chains into one bead/executor pass. Larger reviewer scope but no merge conflicts. Mark obsolete split beads with `bd supersede <old> --with <unified>`.
+3. **Parallel dispatch + debugger restitch at integration** — dispatch in parallel, plan for ~40% conflict rate (empirical), budget debugger-restitch passes during integration. Link overlapping siblings with `bd dep relate <chain-a> <chain-b>` so the future restitch has visible context without creating fake blockers.
+Example graph rewiring:
+```bash
+# soft conflict-cluster context; does not change schedule
+bd dep relate <chain-a> <chain-b>
+# serializing because both chains edit src/cli/update.ts
+bd dep add <chain-b> <chain-a> --type blocks
+# replacing scattered duplicate/split beads with one unified implementation
+bd supersede <old-chain-a> --with <unified-chain>
+bd supersede <old-chain-b> --with <unified-chain>
+```
-Default heuristic: if 3+ chains touch the same file, **serial-dispatch them**. Conflict-resolution time at integration usually exceeds the time saved by parallel dispatch.
+Default heuristic: if 3+ chains touch the same file, **serial-dispatch them**. Conflict-resolution time at integration usually exceeds the time saved by parallel dispatch. Run `bd find-duplicates --status open --method ai --json` before launching a large wave; merge or supersede duplicate work before specialists spend tokens on it.
 ## Pre-Epic: Test-Failure-Map Pattern
@@ -560,11 +625,17 @@ Use when:
    - `CONSTRAINTS:` READ_ONLY, no source/test edits, no fix attempts.
 3. **Dispatch test-runner / explorer / debugger** for this bead READ_ONLY (or fill inline by reading the log).
 4. **Build the cluster table**: cluster name | files (counts) | representative error | root-cause hypothesis | likely-owner area | targeted validation command. Save in bead notes.
-5. **Plan fix chains** off the cluster table:
+5. **Wire root-cause relationships** so the graph is navigable:
+   ```bash
+   bd dep add <failure-cluster-bead> <root-cause-bead> --type caused-by
+   bd dep add <test-runner-bead> <fix-bead> --type validates
+   ```
+   Use `caused-by` for attribution, not `blocks`; use `validates` for the evidence-producing test bead.
+6. **Plan fix chains** off the cluster table:
    - One chain per cluster, file scopes disjoint where possible.
    - Order by leverage (largest cluster first), then by simplicity.
    - Debugger when root cause unclear; executor when bead constraint is concrete.
-6. **Save the topology insight as `bd remember`** — patterns about where a codebase's test fragility concentrates are reusable.
+7. **Save the topology insight as `bd remember`** — patterns about where a codebase's test fragility concentrates are reusable.
 ### Why this beats dispatch-blind
@@ -587,26 +658,28 @@ bd update <task> --claim
 # 2. Optional discovery when path is unknown
 bd create --title "Explore auth refresh path" --type task --priority 2 --description "PROBLEM: token refresh retry path is undocumented and likely drifts on failure handling. SUCCESS: evidence-backed plan names exact files, symbols, and risk. SCOPE: src/auth/refresh.ts, src/cli/login.ts, tests/unit/auth/*.test.ts. NON_GOALS: no implementation, no broad audit. CONSTRAINTS: READ_ONLY, cite files/symbols/flows, stay within live repo evidence. VALIDATION: findings cite code path and recommended sequence. OUTPUT: tracked discovery plan with stop condition."
-bd dep add <explore> <task>
+bd dep add <explore> <task> --type discovered-from
 specialists run explorer --bead <explore> --context-depth 3
 specialists result <explore-job>
 # 3. Implementation
 bd create --title "Implement token refresh retry" --type task --priority 2 --description "PROBLEM: login fails after transient token refresh error because retry path returns before backoff and clear error state. SUCCESS: retry waits once, preserves session on success, and surfaces final failure clearly. SCOPE: src/auth/refresh.ts, src/cli/login.ts, tests/unit/auth/refresh.test.ts. NON_GOALS: no auth redesign, no storage migration, no UI refresh. CONSTRAINTS: preserve existing token format, keep backward-compatible error text, avoid broad retry changes elsewhere. VALIDATION: add regression test for transient failure then success; run targeted auth tests. OUTPUT: changed files, test evidence, residual risks."
-bd dep add <impl> <explore-or-task>
+bd dep add <impl> <explore-or-task> --type blocks
 specialists run executor --bead <impl> --context-depth 3
 specialists result <exec-job>
 # 4. Advisory passes when diff smells risky
 bd create --title "Sanity check token retry diff" --type task --priority 2 --description "PROBLEM: auth retry diff has control-flow and state-handling smell that could hide bug. SUCCESS: findings identify concrete simplification or confirm clean shape. SCOPE: executor diff in auth refresh and login flow. NON_GOALS: no edits, no merge gate decision. CONSTRAINTS: READ_ONLY, keep feedback cheap, cite exact lines or symbols. VALIDATION: findings name concrete improvement or say OK. OUTPUT: FINDINGS with severity or OK with caveats."
+bd dep add <sanity-bead> <impl> --type validates
 specialists run code-sanity --bead <sanity-bead> --job <exec-job> --context-depth 3
 bd create --title "Security scan token retry diff" --type task --priority 2 --description "PROBLEM: auth refresh code touches secrets and session handling, so security regression is possible. SUCCESS: findings isolate real risk surface or confirm no obvious issue. SCOPE: executor diff in auth, token storage, and login path. NON_GOALS: no edits, no package updates, no destructive scans, no live exploit tests. CONSTRAINTS: LOW permissions, scan-only, recommendations only. VALIDATION: findings cite auth/secrets/input surface and why it matters. OUTPUT: recommendations for executor to apply in separate bead."
+bd dep add <security-bead> <impl> --type validates
 specialists run security-auditor --bead <security-bead> --job <exec-job> --context-depth 3
 # 5. Final review
 bd create --title "Review token refresh retry" --type task --priority 2 --description "PROBLEM: verify executor output against auth retry requirements. SUCCESS: PASS only if retry behavior, error handling, and tests satisfy contract. SCOPE: executor job, diff, acceptance criteria, and target auth files. NON_GOALS: do not rewrite unless explicitly asked. CONSTRAINTS: code-review mindset; findings first; verify security and sanity findings were handled. VALIDATION: inspect targeted checks and regression coverage. OUTPUT: PASS/PARTIAL/FAIL with file/line findings."
-bd dep add <review> <impl>
+bd dep add <review> <impl> --type validates
 specialists run reviewer --bead <review> --job <exec-job> --context-depth 3
 specialists result <review-job>
@@ -621,7 +694,7 @@ sp merge <impl>
 bd close <task> --reason "Reviewer PASS; merged."
 ```
-Edit-capable specialists with `--bead` auto-provision a worktree. `--worktree` is accepted for clarity but usually unnecessary. Use `--job <exec-job>` for reviewer/fix passes that must enter existing executor workspace.
+Edit-capable specialists with `--bead` auto-provision a clean git worktree. This does **not** provision ignored project dependency artifacts (`node_modules/`, `.venv/`, build caches). If validation tools are missing inside that worktree, have the specialist run the repo's standard bootstrap command (`make bootstrap`, `just setup`, `npm ci`, `uv sync`, etc.) or report that bootstrap is required; do not solve it by tracking dependency directories. `--worktree` is accepted for clarity but usually unnecessary. Use `--job <exec-job>` for reviewer/fix passes that must enter existing executor workspace.
 What differs: orchestrator carries full bead contract inline, so downstream specialists inherit the actual job shape, not a title.
@@ -634,8 +707,7 @@ Use epic when multiple implementation chains publish together.
 bd create --title "Epic: auth refresh hardening" --type epic --priority 2 --description "PROBLEM: login and refresh flow have retry drift, weak error surfacing, and unclear follow-up ownership. SUCCESS: epic closes with stable retry behavior, tests, docs, and clean publish. SCOPE: src/auth/*, src/cli/login.ts, tests/unit/auth/*, docs/auth-refresh.md. NON_GOALS: no auth provider swap, no storage migration, no unrelated session revamp. CONSTRAINTS: preserve token format, keep login compatible, sequence risky fixes before merge, use child beads for parallelizable slices. VALIDATION: targeted tests, code-sanity or security pass if risk appears, final reviewer PASS. OUTPUT: merged chain set with notes on remaining gaps."
 # Planner bead
-bd create --title "Plan auth refresh split" --type task --priority 2 --description "PROBLEM: epic needs disjoint chains before executor starts. SUCCESS: child beads, dependency edges, and file ownership split are explicit. SCOPE: auth refresh epic area. NON_GOALS: no code changes. CONSTRAINTS: keep chains disjoint, identify security-sensitive slice, name review order. VALIDATION: plan names beads and edges. OUTPUT: parallel-ready plan with risk notes."
-bd dep add <plan> <epic>
+bd create --parent <epic> --title "Plan auth refresh split" --type task --priority 2 --description "PROBLEM: epic needs disjoint chains before executor starts. SUCCESS: child beads, dependency edges, and file ownership split are explicit. SCOPE: auth refresh epic area. NON_GOALS: no code changes. CONSTRAINTS: keep chains disjoint, identify security-sensitive slice, name review order. VALIDATION: plan names beads and edges. OUTPUT: parallel-ready plan with risk notes."
 specialists run planner --bead <plan> --context-depth 3
 # Parallel impl beads
@@ -646,6 +718,8 @@ specialists run executor --bead <impl-a> --context-depth 3
 specialists run executor --bead <impl-b> --context-depth 3
 # Per-chain review
+bd dep add <review-a> <impl-a> --type validates
+bd dep add <review-b> <impl-b> --type validates
 specialists run reviewer --bead <review-a> --job <exec-a-job> --context-depth 3
 specialists run reviewer --bead <review-b> --job <exec-b-job> --context-depth 3
@@ -655,6 +729,7 @@ sp finalize <review-a-job>
 sp finalize <review-b-job>
 # Publish
+bd dep cycles                 # stop if relationship rewiring introduced a cycle
 sp epic status <epic>          # verify derived state shows merge_ready
 sp epic merge <epic>           # batch publish all chains in dependency order with tsc gate per merge
 ```
@@ -675,7 +750,7 @@ reviewer -> PASS | PARTIAL | FAIL
 - `PASS`: verify expected commit/diff. If reviewer's PASS appeared in its streaming output, auto-finalize already closed the chain — go straight to `sp merge` / `sp epic merge`. If PASS arrived via `sp resume`, run `sp finalize <any-chain-job-id>` first to cascade-close any waiting keep-alive members, then publish.
 - `PARTIAL`: resume same executor/debugger with exact findings, then re-review (`sp resume <reviewer-job>`).
-- `FAIL`: stop and decide whether to replace chain, re-scope bead, or ask operator if judgment is required.
+- `FAIL`: stop and decide whether to replace chain, re-scope bead, or ask operator if judgment is required. If replacing a bad chain with a narrower one, use `bd supersede <failed-impl> --with <replacement>`; if reviewer discovered separate follow-up work, use `bd dep add <follow-up> <reviewer-bead> --type discovered-from`.
 Prefer resume over new fix executor when original job is waiting and context is healthy:
@@ -764,8 +839,8 @@ Several specialists default to over-cautious verdicts when an evidence gate look
 ### Overthinker
 - "Hold for operator decision" without specifying what decision is needed → push: "Cite file/line evidence for why this is a product decision rather than a mechanical resolution."
-- "Close as superseded by X" without verification → push: "Read the current state of `<file>` and check whether feature Y from this bead is actually present."
-- "Run separate small beads" or "run one big bead" without rationale → push: "Pick one and explain operationally — cost difference, conflict expectations, reviewer scope."
+- "Close as superseded by X" without verification → push: "Read the current state of `<file>` and check whether feature Y from this bead is actually present." If verified, record it structurally with `bd supersede <old> --with <new>` instead of burying the replacement in notes.
+- "Run separate small beads" or "run one big bead" without rationale → push: "Pick one and explain operationally — cost difference, conflict expectations, reviewer scope." If one big bead wins, mark replaced split beads with `bd supersede`; if the small beads remain parallel siblings, link overlap with `bd dep relate`, not `blocks`.
 ### Reviewer
@@ -891,6 +966,7 @@ sp merge <chain-root-bead>
 Batch publish all chains in an epic in dependency order with tsc gate between each:
 ```bash
+bd dep cycles
 sp epic status <epic-id>
 sp epic merge <epic-id>
 ```
@@ -922,11 +998,12 @@ Use when `sp merge` / `sp epic merge` is not the right path: chains forked from
 3. For each non-overlapping chain (security/critical first, then test-baseline, then features):
    - `git merge --squash <chain-branch>`
    - Restore noise files (see "Chain noise filter checklist" below)
-   - **Advisory passes** before commit: if the staged diff smells overcomplicated/duplicative/type-risky, dispatch `code-sanity --job <last-exec-job-of-chain>`; if it touches auth/secrets/input/agent-config, dispatch `security-auditor --job <last-exec-job-of-chain>`. Apply findings or document why skipped.
+   - **Advisory passes** before commit: if the staged diff smells overcomplicated/duplicative/type-risky, dispatch `code-sanity --job <last-exec-job-of-chain>`; if it touches auth/secrets/input/agent-config, dispatch `security-auditor --job <last-exec-job-of-chain>`. Link those beads with `bd dep add <advisory-bead> <chain-bead> --type validates`. Apply findings or document why skipped.
    - `git commit -m "<type>(<scope>): <summary> (<bead-id>)"` — one squash commit per chain.
-4. For each overlapping chain, switch to the **debugger-restitch** pattern (next section).
-5. After all chains land, run E2E smoke phase (below) before declaring done.
-6. Operator FF-merges integration → main when satisfied.
+4. For each overlapping chain, add `bd dep relate <overlap-a> <overlap-b>` if not already linked, then switch to the **debugger-restitch** pattern (next section).
+5. Before publication, run `bd dep cycles`; fix any accidental cycle before `sp epic merge` or operator FF-merge.
+6. After all chains land, run E2E smoke phase (below) before declaring done.
+7. Operator FF-merges integration → main when satisfied.
 ### Chain noise filter checklist
@@ -950,7 +1027,7 @@ If a chain commits its own `.beads` symlink (older bd-in-worktree behavior), `rm
 When chain X conflicts with already-landed chain Y on shared files, raw `git cherry-pick` will revert Y's work. The debugger-restitch pattern preserves both, but only when the debugger gets an explicit "preserve already-landed work" contract.
-1. **Reopen X**: `bd reopen <X> --reason="integration stitch onto post-Y state"`.
+1. **Reopen X**: `bd reopen <X> --reason="integration stitch onto post-Y state"`. If the old X chain is no longer publishable, create a restitch bead and mark replacement explicitly: `bd supersede <X> --with <X-restitch>`. Link X and Y with `bd dep relate <X-restitch> <Y>` for conflict context; use `caused-by` only when a concrete failure bead is attributable to Y's already-landed change.
 2. **Strengthen the bead contract** with these fields:
    - `## CRITICAL CONSTRAINTS:` heading at the top.
    - "Fork off `integration/<date>-orchestrator`. Verify with `git log integration/...$..HEAD` empty before any commits."
@@ -969,13 +1046,13 @@ When chain X conflicts with already-landed chain Y on shared files, raw `git che
    git diff integration/<date>...feature/<X>-debugger -- <key-files>
    ```
    Confirm the debugger's diff is **additive** — no reverts of Y's lines.
-5. **Advisory passes**: before landing the restitch, dispatch `code-sanity --job <debugger-job>` if the restitch added control-flow complexity, and `security-auditor --job <debugger-job>` if it touched a sensitive surface. Restitched diffs are higher-risk than fresh executor diffs because the debugger had to thread around already-landed work.
+5. **Advisory passes**: before landing the restitch, dispatch `code-sanity --job <debugger-job>` if the restitch added control-flow complexity, and `security-auditor --job <debugger-job>` if it touched a sensitive surface. Link each advisory bead back with `bd dep add <advisory> <X-restitch-or-X> --type validates`. Restitched diffs are higher-risk than fresh executor diffs because the debugger had to thread around already-landed work.
 6. **Land via FF or cherry-pick the named commit** (NOT the checkpoint commit). Look for the commit with the proper `<type>(<scope>):` message; ignore `checkpoint(debugger):` commits above it.
 7. **Verify tests** before marking done.
 ### Failure mode to watch for
-If the debugger forks off the OLD baseline (pre-Y) instead of integration, its commit will revert Y. Symptom: `git diff integration..feature/<X>-debugger -- <Y's-file>` shows DELETIONS of Y's symbols. Fix: resume the debugger with explicit "cd to a fresh worktree forked from `integration/<date>-orchestrator`" instruction. Re-verify with `git log integration..HEAD` empty.
+If the debugger forks off the OLD baseline (pre-Y) instead of integration, its commit will revert Y. Symptom: `git diff integration..feature/<X>-debugger -- <Y's-file>` shows DELETIONS of Y's symbols. Fix: resume the debugger with explicit "cd to a fresh worktree forked from `integration/<date>-orchestrator`" instruction. Re-verify with `git log integration..HEAD` empty. If the bad restitch became a tracked bead, supersede it with the corrected restitch bead so nobody merges the obsolete chain.
 ## E2E Smoke Phase
@@ -1049,6 +1126,7 @@ Then choose one action:
 | `sp merge` refuses with "non-terminal chain jobs" after reviewer PASS | Auto-finalize did not fire (PASS arrived via `sp resume`, not streaming) | `sp finalize <any-chain-job-id>` — cascades to close every waiting keep-alive member |
 | `sp epic merge` says epic is "in terminal state 'failed'" | Prior `sp epic merge` hit a transient error (rebase conflict, dirty worktree) and persisted a soft `failed` marker | Clear the original conflict source, then re-run `sp epic merge` — it retries fresh, only `merged`/`abandoned` truly block |
 | `sp epic merge` says "rebase failed: unstaged changes" in a worktree | bd auto-export or other tooling left uncommitted changes inside the worktree | `cd .worktrees/<bead>/<bead>-executor && git stash push -u -m epic-merge-prep`, then re-run from main repo |
+| Validation fails with `command not found`, `vitest: not found`, missing Python tools, or `ERR_MODULE_NOT_FOUND` in a fresh worktree | Normal git worktree behavior: ignored dependency dirs (`node_modules/`, `.venv/`) are not copied into new worktrees | Run the repo's standard bootstrap inside that worktree (`make bootstrap`, `just setup`, `npm ci`, `uv sync`, etc.) or report bootstrap-required. Do not track dependency artifacts. |
 | `sp ps` shows old terminal jobs after a session | Default dashboard keeps unresolved terminal problems visible until acknowledged | `sp clean --ps --dry-run`, then `sp clean --ps` to soft-hide from default ps; use `sp ps --include-cleaned`/`--all` for audit history |
 | Reviewer keeps returning PARTIAL on functional contracts already met | Reviewer demanding tool-event evidence — typically obsoleted after the gate relaxation, but if it persists check the executor's `gitnexus_detect_changes` ran and use the rebuttal pattern (see Specialist Rebuttal As Routine) | Rebut with cited evidence; second FAIL = escalate |
 | Multiple `sp run` background launches drop silently under shell parallelism | Known launch-ceremony race | Re-check `sp ps` after each dispatch and retry the missing one; serialize when reliability matters |

package/dist/asset-contract.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0.0",
-  "package_version": "3.15.1",
+  "package_version": "3.15.3",
   "shipped_skills": [
     {
       "path": "config/skills/memory-audit-transaction/SKILL.md",
@@ -40,7 +40,7 @@
     },
     {
       "path": "config/skills/using-specialists-v3/SKILL.md",
-      "sha256": "c8aa5dccd55fe6a461e66202a6829a3f1b9f9b4dc8c54f5c4f2847eb585b30f1"
+      "sha256": "643264862dfa758f85cff41a150be13d6a0c2c8ed42ded6186a3b9b16a87852b"
     },
     {
       "path": "config/skills/using-specialists/SKILL.md",

package/dist/index.js CHANGED Viewed

@@ -7013,6 +7013,9 @@ var require_data = __commonJS((exports, module) => {
 var require_utils = __commonJS((exports, module) => {
   var isUUID = RegExp.prototype.test.bind(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu);
   var isIPv4 = RegExp.prototype.test.bind(/^(?:(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)$/u);
+  var isHexPair = RegExp.prototype.test.bind(/^[\da-f]{2}$/iu);
+  var isUnreserved = RegExp.prototype.test.bind(/^[\da-z\-._~]$/iu);
+  var isPathCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/]$/iu);
   function stringArrayToHexStripped(input) {
     let acc = "";
     let code = 0;
@@ -7206,27 +7209,77 @@ var require_utils = __commonJS((exports, module) => {
     }
     return output.join("");
   }
-  function normalizeComponentEncoding(component, esc2) {
-    const func = esc2 !== true ? escape : unescape;
-    if (component.scheme !== undefined) {
-      component.scheme = func(component.scheme);
-    }
-    if (component.userinfo !== undefined) {
-      component.userinfo = func(component.userinfo);
-    }
-    if (component.host !== undefined) {
-      component.host = func(component.host);
+  var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
+  var HOST_DELIM_RE = /[@/?#:]/g;
+  var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
+  function reescapeHostDelimiters(host, isIP) {
+    const re = isIP ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
+    re.lastIndex = 0;
+    return host.replace(re, (ch) => HOST_DELIMS[ch]);
+  }
+  function normalizePercentEncoding(input, decodeUnreserved = false) {
+    if (input.indexOf("%") === -1) {
+      return input;
     }
-    if (component.path !== undefined) {
-      component.path = func(component.path);
+    let output = "";
+    for (let i = 0;i < input.length; i++) {
+      if (input[i] === "%" && i + 2 < input.length) {
+        const hex = input.slice(i + 1, i + 3);
+        if (isHexPair(hex)) {
+          const normalizedHex = hex.toUpperCase();
+          const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+          if (decodeUnreserved && isUnreserved(decoded)) {
+            output += decoded;
+          } else {
+            output += "%" + normalizedHex;
+          }
+          i += 2;
+          continue;
+        }
+      }
+      output += input[i];
     }
-    if (component.query !== undefined) {
-      component.query = func(component.query);
+    return output;
+  }
+  function normalizePathEncoding(input) {
+    let output = "";
+    for (let i = 0;i < input.length; i++) {
+      if (input[i] === "%" && i + 2 < input.length) {
+        const hex = input.slice(i + 1, i + 3);
+        if (isHexPair(hex)) {
+          const normalizedHex = hex.toUpperCase();
+          const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+          if (decoded !== "." && isUnreserved(decoded)) {
+            output += decoded;
+          } else {
+            output += "%" + normalizedHex;
+          }
+          i += 2;
+          continue;
+        }
+      }
+      if (isPathCharacter(input[i])) {
+        output += input[i];
+      } else {
+        output += escape(input[i]);
+      }
     }
-    if (component.fragment !== undefined) {
-      component.fragment = func(component.fragment);
+    return output;
+  }
+  function escapePreservingEscapes(input) {
+    let output = "";
+    for (let i = 0;i < input.length; i++) {
+      if (input[i] === "%" && i + 2 < input.length) {
+        const hex = input.slice(i + 1, i + 3);
+        if (isHexPair(hex)) {
+          output += "%" + hex.toUpperCase();
+          i += 2;
+          continue;
+        }
+      }
+      output += escape(input[i]);
     }
-    return component;
+    return output;
   }
   function recomposeAuthority(component) {
     const uriTokens = [];
@@ -7241,7 +7294,7 @@ var require_utils = __commonJS((exports, module) => {
         if (ipV6res.isIPV6 === true) {
           host = `[${ipV6res.escapedHost}]`;
         } else {
-          host = component.host;
+          host = reescapeHostDelimiters(host, false);
         }
       }
       uriTokens.push(host);
@@ -7255,7 +7308,10 @@ var require_utils = __commonJS((exports, module) => {
   module.exports = {
     nonSimpleDomain,
     recomposeAuthority,
-    normalizeComponentEncoding,
+    reescapeHostDelimiters,
+    normalizePercentEncoding,
+    normalizePathEncoding,
+    escapePreservingEscapes,
     removeDotSegments,
     isIPv4,
     isUUID,
@@ -7440,11 +7496,11 @@ var require_schemes = __commonJS((exports, module) => {
 // node_modules/fast-uri/index.js
 var require_fast_uri = __commonJS((exports, module) => {
-  var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizeComponentEncoding, isIPv4, nonSimpleDomain } = require_utils();
+  var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
   var { SCHEMES, getSchemeHandler } = require_schemes();
   function normalize(uri, options) {
     if (typeof uri === "string") {
-      uri = serialize(parse5(uri, options), options);
+      uri = normalizeString(uri, options);
     } else if (typeof uri === "object") {
       uri = parse5(serialize(uri, options), options);
     }
@@ -7510,19 +7566,9 @@ var require_fast_uri = __commonJS((exports, module) => {
     return target;
   }
   function equal(uriA, uriB, options) {
-    if (typeof uriA === "string") {
-      uriA = unescape(uriA);
-      uriA = serialize(normalizeComponentEncoding(parse5(uriA, options), true), { ...options, skipEscape: true });
-    } else if (typeof uriA === "object") {
-      uriA = serialize(normalizeComponentEncoding(uriA, true), { ...options, skipEscape: true });
-    }
-    if (typeof uriB === "string") {
-      uriB = unescape(uriB);
-      uriB = serialize(normalizeComponentEncoding(parse5(uriB, options), true), { ...options, skipEscape: true });
-    } else if (typeof uriB === "object") {
-      uriB = serialize(normalizeComponentEncoding(uriB, true), { ...options, skipEscape: true });
-    }
-    return uriA.toLowerCase() === uriB.toLowerCase();
+    const normalizedA = normalizeComparableURI(uriA, options);
+    const normalizedB = normalizeComparableURI(uriB, options);
+    return normalizedA !== undefined && normalizedB !== undefined && normalizedA.toLowerCase() === normalizedB.toLowerCase();
   }
   function serialize(cmpts, opts) {
     const component = {
@@ -7548,12 +7594,12 @@ var require_fast_uri = __commonJS((exports, module) => {
       schemeHandler.serialize(component, options);
     if (component.path !== undefined) {
       if (!options.skipEscape) {
-        component.path = escape(component.path);
+        component.path = escapePreservingEscapes(component.path);
         if (component.scheme !== undefined) {
           component.path = component.path.split("%3A").join(":");
         }
       } else {
-        component.path = unescape(component.path);
+        component.path = normalizePercentEncoding(component.path);
       }
     }
     if (options.reference !== "suffix" && component.scheme) {
@@ -7588,7 +7634,16 @@ var require_fast_uri = __commonJS((exports, module) => {
     return uriTokens.join("");
   }
   var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
-  function parse5(uri, opts) {
+  function getParseError(parsed, matches) {
+    if (matches[2] !== undefined && parsed.path && parsed.path[0] !== "/") {
+      return 'URI path must start with "/" when authority is present.';
+    }
+    if (typeof parsed.port === "number" && (parsed.port < 0 || parsed.port > 65535)) {
+      return "URI port is malformed.";
+    }
+    return;
+  }
+  function parseWithStatus(uri, opts) {
     const options = Object.assign({}, opts);
     const parsed = {
       scheme: undefined,
@@ -7599,6 +7654,7 @@ var require_fast_uri = __commonJS((exports, module) => {
       query: undefined,
       fragment: undefined
     };
+    let malformedAuthorityOrPort = false;
     let isIP = false;
     if (options.reference === "suffix") {
       if (options.scheme) {
@@ -7619,6 +7675,11 @@ var require_fast_uri = __commonJS((exports, module) => {
       if (isNaN(parsed.port)) {
         parsed.port = matches[5];
       }
+      const parseError = getParseError(parsed, matches);
+      if (parseError !== undefined) {
+        parsed.error = parsed.error || parseError;
+        malformedAuthorityOrPort = true;
+      }
       if (parsed.host) {
         const ipv4result = isIPv4(parsed.host);
         if (ipv4result === false) {
@@ -7657,14 +7718,18 @@ var require_fast_uri = __commonJS((exports, module) => {
             parsed.scheme = unescape(parsed.scheme);
           }
           if (parsed.host !== undefined) {
-            parsed.host = unescape(parsed.host);
+            parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP);
           }
         }
         if (parsed.path) {
-          parsed.path = escape(unescape(parsed.path));
+          parsed.path = normalizePathEncoding(parsed.path);
         }
         if (parsed.fragment) {
-          parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+          try {
+            parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+          } catch {
+            parsed.error = parsed.error || "URI malformed";
+          }
         }
       }
       if (schemeHandler && schemeHandler.parse) {
@@ -7673,7 +7738,29 @@ var require_fast_uri = __commonJS((exports, module) => {
     } else {
       parsed.error = parsed.error || "URI can not be parsed.";
     }
-    return parsed;
+    return { parsed, malformedAuthorityOrPort };
+  }
+  function parse5(uri, opts) {
+    return parseWithStatus(uri, opts).parsed;
+  }
+  function normalizeString(uri, opts) {
+    return normalizeStringWithStatus(uri, opts).normalized;
+  }
+  function normalizeStringWithStatus(uri, opts) {
+    const { parsed, malformedAuthorityOrPort } = parseWithStatus(uri, opts);
+    return {
+      normalized: malformedAuthorityOrPort ? uri : serialize(parsed, opts),
+      malformedAuthorityOrPort
+    };
+  }
+  function normalizeComparableURI(uri, opts) {
+    if (typeof uri === "string") {
+      const { normalized, malformedAuthorityOrPort } = normalizeStringWithStatus(uri, opts);
+      return malformedAuthorityOrPort ? undefined : normalized;
+    }
+    if (typeof uri === "object") {
+      return serialize(uri, opts);
+    }
   }
   var fastUri = {
     SCHEMES,
@@ -7808,7 +7895,7 @@ var require_core = __commonJS((exports) => {
     constructor(opts = {}) {
       this.schemas = {};
       this.refs = {};
-      this.formats = {};
+      this.formats = Object.create(null);
       this._compilations = new Set;
       this._loading = {};
       this._cache = new Map;
@@ -15332,8 +15419,10 @@ ${cb}` : comment;
         }
       }
       if (afterDoc) {
-        Array.prototype.push.apply(doc2.errors, this.errors);
-        Array.prototype.push.apply(doc2.warnings, this.warnings);
+        for (let i = 0;i < this.errors.length; ++i)
+          doc2.errors.push(this.errors[i]);
+        for (let i = 0;i < this.warnings.length; ++i)
+          doc2.warnings.push(this.warnings[i]);
       } else {
         doc2.errors = this.errors;
         doc2.warnings = this.warnings;
@@ -16045,7 +16134,7 @@ var require_lexer = __commonJS((exports) => {
         const n = (yield* this.pushCount(1)) + (yield* this.pushSpaces(true));
         this.indentNext = this.indentValue + 1;
         this.indentValue += n;
-        return yield* this.parseBlockStart();
+        return "block-start";
       }
       return "doc";
     }
@@ -16352,26 +16441,37 @@ var require_lexer = __commonJS((exports) => {
       return 0;
     }
     *pushIndicators() {
-      switch (this.charAt(0)) {
-        case "!":
-          return (yield* this.pushTag()) + (yield* this.pushSpaces(true)) + (yield* this.pushIndicators());
-        case "&":
-          return (yield* this.pushUntil(isNotAnchorChar)) + (yield* this.pushSpaces(true)) + (yield* this.pushIndicators());
-        case "-":
-        case "?":
-        case ":": {
-          const inFlow = this.flowLevel > 0;
-          const ch1 = this.charAt(1);
-          if (isEmpty(ch1) || inFlow && flowIndicatorChars.has(ch1)) {
-            if (!inFlow)
-              this.indentNext = this.indentValue + 1;
-            else if (this.flowKey)
-              this.flowKey = false;
-            return (yield* this.pushCount(1)) + (yield* this.pushSpaces(true)) + (yield* this.pushIndicators());
+      let n = 0;
+      loop:
+        while (true) {
+          switch (this.charAt(0)) {
+            case "!":
+              n += yield* this.pushTag();
+              n += yield* this.pushSpaces(true);
+              continue loop;
+            case "&":
+              n += yield* this.pushUntil(isNotAnchorChar);
+              n += yield* this.pushSpaces(true);
+              continue loop;
+            case "-":
+            case "?":
+            case ":": {
+              const inFlow = this.flowLevel > 0;
+              const ch1 = this.charAt(1);
+              if (isEmpty(ch1) || inFlow && flowIndicatorChars.has(ch1)) {
+                if (!inFlow)
+                  this.indentNext = this.indentValue + 1;
+                else if (this.flowKey)
+                  this.flowKey = false;
+                n += yield* this.pushCount(1);
+                n += yield* this.pushSpaces(true);
+                continue loop;
+              }
+            }
           }
+          break loop;
         }
-      }
-      return 0;
+      return n;
     }
     *pushTag() {
       if (this.charAt(1) === "<") {
@@ -16525,6 +16625,13 @@ var require_parser = __commonJS((exports) => {
     while (prev[++i]?.type === "space") {}
     return prev.splice(i, prev.length);
   }
+  function arrayPushArray(target, source) {
+    if (source.length < 1e5)
+      Array.prototype.push.apply(target, source);
+    else
+      for (let i = 0;i < source.length; ++i)
+        target.push(source[i]);
+  }
   function fixFlowSeqItems(fc) {
     if (fc.start.type === "flow-seq-start") {
       for (const it of fc.items) {
@@ -16534,11 +16641,11 @@ var require_parser = __commonJS((exports) => {
           delete it.key;
           if (isFlowToken(it.value)) {
             if (it.value.end)
-              Array.prototype.push.apply(it.value.end, it.sep);
+              arrayPushArray(it.value.end, it.sep);
             else
               it.value.end = it.sep;
           } else
-            Array.prototype.push.apply(it.start, it.sep);
+            arrayPushArray(it.start, it.sep);
           delete it.sep;
         }
       }
@@ -16878,7 +16985,7 @@ var require_parser = __commonJS((exports) => {
               const prev = map2.items[map2.items.length - 2];
               const end = prev?.value?.end;
               if (Array.isArray(end)) {
-                Array.prototype.push.apply(end, it.start);
+                arrayPushArray(end, it.start);
                 end.push(this.sourceToken);
                 map2.items.pop();
                 return;
@@ -17066,7 +17173,7 @@ var require_parser = __commonJS((exports) => {
               const prev = seq.items[seq.items.length - 2];
               const end = prev?.value?.end;
               if (Array.isArray(end)) {
-                Array.prototype.push.apply(end, it.start);
+                arrayPushArray(end, it.start);
                 end.push(this.sourceToken);
                 seq.items.pop();
                 return;
@@ -31951,7 +32058,7 @@ async function run14() {
     const launchStartedAt = Date.now();
     const innerArgs = process.argv.slice(2).filter((a) => a !== "--background");
     const cmd = `${process.execPath} ${process.argv[1]} ${innerArgs.map(shellQuote2).join(" ")}`;
-    const tmuxCmd = `/bin/bash -lc ${shellQuote2(`cd ${shellQuote2(cwd)} && exec ${cmd}`)}`;
+    const tmuxCmd = `/bin/bash -c ${shellQuote2(`cd ${shellQuote2(cwd)} && exec ${cmd}`)}`;
     let childPid;
     let childExitCode;
     let childExitPromise;

package/dist/lib.js CHANGED Viewed

@@ -4855,8 +4855,10 @@ ${cb}` : comment;
         }
       }
       if (afterDoc) {
-        Array.prototype.push.apply(doc.errors, this.errors);
-        Array.prototype.push.apply(doc.warnings, this.warnings);
+        for (let i = 0;i < this.errors.length; ++i)
+          doc.errors.push(this.errors[i]);
+        for (let i = 0;i < this.warnings.length; ++i)
+          doc.warnings.push(this.warnings[i]);
       } else {
         doc.errors = this.errors;
         doc.warnings = this.warnings;
@@ -5568,7 +5570,7 @@ var require_lexer = __commonJS((exports) => {
         const n = (yield* this.pushCount(1)) + (yield* this.pushSpaces(true));
         this.indentNext = this.indentValue + 1;
         this.indentValue += n;
-        return yield* this.parseBlockStart();
+        return "block-start";
       }
       return "doc";
     }
@@ -5875,26 +5877,37 @@ var require_lexer = __commonJS((exports) => {
       return 0;
     }
     *pushIndicators() {
-      switch (this.charAt(0)) {
-        case "!":
-          return (yield* this.pushTag()) + (yield* this.pushSpaces(true)) + (yield* this.pushIndicators());
-        case "&":
-          return (yield* this.pushUntil(isNotAnchorChar)) + (yield* this.pushSpaces(true)) + (yield* this.pushIndicators());
-        case "-":
-        case "?":
-        case ":": {
-          const inFlow = this.flowLevel > 0;
-          const ch1 = this.charAt(1);
-          if (isEmpty(ch1) || inFlow && flowIndicatorChars.has(ch1)) {
-            if (!inFlow)
-              this.indentNext = this.indentValue + 1;
-            else if (this.flowKey)
-              this.flowKey = false;
-            return (yield* this.pushCount(1)) + (yield* this.pushSpaces(true)) + (yield* this.pushIndicators());
+      let n = 0;
+      loop:
+        while (true) {
+          switch (this.charAt(0)) {
+            case "!":
+              n += yield* this.pushTag();
+              n += yield* this.pushSpaces(true);
+              continue loop;
+            case "&":
+              n += yield* this.pushUntil(isNotAnchorChar);
+              n += yield* this.pushSpaces(true);
+              continue loop;
+            case "-":
+            case "?":
+            case ":": {
+              const inFlow = this.flowLevel > 0;
+              const ch1 = this.charAt(1);
+              if (isEmpty(ch1) || inFlow && flowIndicatorChars.has(ch1)) {
+                if (!inFlow)
+                  this.indentNext = this.indentValue + 1;
+                else if (this.flowKey)
+                  this.flowKey = false;
+                n += yield* this.pushCount(1);
+                n += yield* this.pushSpaces(true);
+                continue loop;
+              }
+            }
           }
+          break loop;
         }
-      }
-      return 0;
+      return n;
     }
     *pushTag() {
       if (this.charAt(1) === "<") {
@@ -6048,6 +6061,13 @@ var require_parser = __commonJS((exports) => {
     while (prev[++i]?.type === "space") {}
     return prev.splice(i, prev.length);
   }
+  function arrayPushArray(target, source) {
+    if (source.length < 1e5)
+      Array.prototype.push.apply(target, source);
+    else
+      for (let i = 0;i < source.length; ++i)
+        target.push(source[i]);
+  }
   function fixFlowSeqItems(fc) {
     if (fc.start.type === "flow-seq-start") {
       for (const it of fc.items) {
@@ -6057,11 +6077,11 @@ var require_parser = __commonJS((exports) => {
           delete it.key;
           if (isFlowToken(it.value)) {
             if (it.value.end)
-              Array.prototype.push.apply(it.value.end, it.sep);
+              arrayPushArray(it.value.end, it.sep);
             else
               it.value.end = it.sep;
           } else
-            Array.prototype.push.apply(it.start, it.sep);
+            arrayPushArray(it.start, it.sep);
           delete it.sep;
         }
       }
@@ -6401,7 +6421,7 @@ var require_parser = __commonJS((exports) => {
               const prev = map.items[map.items.length - 2];
               const end = prev?.value?.end;
               if (Array.isArray(end)) {
-                Array.prototype.push.apply(end, it.start);
+                arrayPushArray(end, it.start);
                 end.push(this.sourceToken);
                 map.items.pop();
                 return;
@@ -6589,7 +6609,7 @@ var require_parser = __commonJS((exports) => {
               const prev = seq.items[seq.items.length - 2];
               const end = prev?.value?.end;
               if (Array.isArray(end)) {
-                Array.prototype.push.apply(end, it.start);
+                arrayPushArray(end, it.start);
                 end.push(this.sourceToken);
                 seq.items.pop();
                 return;

package/dist/types/cli/run.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/run.ts"],"names":[],"mappings":"AA6gBA,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA+FrG;AAGD,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,~~CAmXzC~~"}
1	+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/run.ts"],"names":[],"mappings":"AA6gBA,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA+FrG;AAGD,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAsXzC"}

package/dist/types/cli/serve.d.ts CHANGED Viewed

@@ -44,7 +44,7 @@ export declare function evaluateReadiness(opts: ReadinessCheckOptions): Promise<
 }>;
 export declare function checkPiHelpForFlags(flags?: string[]): ReadinessReason | undefined;
 export declare function startServe(argv?: string[]): Promise<{
-    server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+    server: import("node:http").Server<typeof IncomingMessage, typeof ServerResponse>;
     args: ServeArgs;
     db: import("../specialist/observability-sqlite.js").ObservabilitySqliteClient | null;
     readinessState: ReadinessState;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/specialists",
-  "version": "3.15.1",
+  "version": "3.15.3",
   "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",
   "types": "dist/types/lib.d.ts",
@@ -74,13 +74,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "yaml": "2.8.4",
+    "yaml": "2.9.0",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6"
   },
   "devDependencies": {
-    "@types/bun": "1.3.10",
-    "@types/node": "^24.0.0",
+    "@types/bun": "1.3.14",
+    "@types/node": "^25.8.0",
     "@vitest/coverage-v8": "^4.1.6",
     "tsx": "^4.20.6",
     "typescript": "^5.0.0",
@@ -90,8 +90,10 @@
     "bun": ">=1.0.0"
   },
   "overrides": {
+    "@hono/node-server": "^1.19.13",
     "fast-uri": "^3.1.2",
+    "hono": "^4.12.18",
     "ip-address": "^10.2.0",
-    "hono": "^4.12.18"
+    "path-to-regexp": "^8.4.0"
   }
 }