@open-agent-toolkit/cli 0.2.13 → 0.2.15

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.8
+version: 1.0.9
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -60,7 +60,10 @@ read and follow:
 
 1. `.agents/skills/oat-project-dispatch-subagents/SKILL.md`;
 2. `.agents/skills/oat-dispatch-subagents/SKILL.md`; and
-3. read exactly one active-provider reference from
+3. `.agents/skills/subagent-orchestration/references/model-selection-principles.md`;
+4. read exactly one active-provider selection reference from
+   `.agents/skills/subagent-orchestration/references/`; and
+5. read the matching mechanics reference from
    `.agents/skills/oat-dispatch-subagents/references/`.
 
 Every optional launch must have a bounded objective, explicit read/write

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.1.8
+version: 1.1.9
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -80,7 +80,7 @@ The primary reviewer must establish the authoritative scope before considering d
 When delegation is eligible:
 
 1. Use one bounded, read-only, non-recursive reconnaissance round with disjoint lane scopes. This is a one-level fan-out limit: lane workers must not spawn additional workers.
-2. Before launching any lane, read `.agents/skills/oat-dispatch-subagents/SKILL.md`, resolve the active provider, and read exactly one matching active-provider reference under `.agents/skills/oat-dispatch-subagents/references/`. Reviewer-local reconnaissance must not read or load `.agents/skills/oat-project-dispatch-subagents/SKILL.md`; that adapter is reserved for project lifecycle phase/task policy.
+2. Before launching any lane, read `.agents/skills/oat-dispatch-subagents/SKILL.md` and `.agents/skills/subagent-orchestration/references/model-selection-principles.md`. Resolve the active provider, then read exactly one matching selection reference under `.agents/skills/subagent-orchestration/references/` and one matching mechanics reference under `.agents/skills/oat-dispatch-subagents/references/`. Reviewer-local reconnaissance must not read or load `.agents/skills/oat-project-dispatch-subagents/SKILL.md`; that adapter is reserved for project lifecycle phase/task policy.
 3. Map every lane worker to the shared `recon` role class (`role.class: recon`); role authority stays read-only and advisory. Assign the independent `task_class`, `classification_source: caller`, and non-empty `classification_reason` fields after understanding the artifacts and diff. These task-class fields are required for reviewer-local reconnaissance even though the generic dispatch contract keeps them optional for other callers.
 4. Classify each lane as `mechanical-recon`, `intelligent-recon`, `default-implementation`, `hard-reasoning`, or `consequential`. Use the stronger floor when uncertain. Classification proceeds from deterministic verification to silent-miss risk, then dispersed context, ambiguity, and consequence; file count alone never justifies escalation.
    - `mechanical-recon`: deterministic inventories, parity checks, and test/lint/format/build execution whose misses are visible and cheaply checked.

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -166,6 +166,7 @@ Archive lifecycle settings live here as shared repo config:
 Tool-pack installation state also lives here as shared repo config:
 
 - `tools.core`
+- `tools.brainstorm`
 - `tools.docs`
 - `tools.ideas`
 - `tools.project-management`
@@ -173,7 +174,19 @@ Tool-pack installation state also lives here as shared repo config:
 - `tools.utility`
 - `tools.workflows`
 
-Use `oat config get tools.<pack>` when you need an explicit installed-capability signal for workflows or troubleshooting. PJM diagnostics use `tools.project-management`; disabled or unset repos report PJM as skipped instead of treating absent `.oat/repo/pjm/` files as drift.
+This complete eight-pack map is the shared project installation snapshot.
+Lifecycle reconciliation derives it only from project-scoped canonical assets;
+user-only packs do not set these keys. Use `oat config get tools.<pack>` to
+inspect repository installation state.
+
+For workflow routing or troubleshooting that needs current effective
+availability, run `oat tools has <pack>`. It checks project plus user scope by
+default; use `--scope project` or `--scope user` to isolate one scope. The
+global `--json` flag returns the matching scopes with the boolean result.
+
+PJM diagnostics intentionally use project configuration where repository setup
+is the question. Disabled or unset repos report PJM as skipped instead of
+treating absent `.oat/repo/pjm/` files as drift.
 
 Workflow automation preferences are also visible through `oat config` and can be set at local, shared, or user scope. Notable review-loop keys:
 

package/assets/docs/cli-utilities/configuration.md

@@ -87,7 +87,7 @@ Common keys in `.oat/config.json`:
 - `archive.wrapUpExportPath` — optional tracked destination for `oat-wrap-up` reports; when unset, the skill falls back to `.oat/repo/reference/wrap-ups`
 - `archive.awsProfile` — optional AWS named profile forwarded as `AWS_PROFILE` to every `aws` invocation in archive flows
 - `archive.awsRegion` — optional AWS region forwarded as `AWS_REGION` to every `aws` invocation in archive flows
-- `tools.<pack>` — whether a bundled tool pack is currently installed in the repo or user scopes after lifecycle reconciliation
+- `tools.<pack>` — project-scoped installation state for a bundled tool pack after lifecycle reconciliation
 - `workflow.gates.skills` / `workflow.gates.execTargets` — per-skill gates and cross-runtime exec targets; manage with `oat gate`
 - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — default review budgets in milliseconds
 
@@ -98,7 +98,28 @@ oat config get tools.project-management
 oat config set tools.project-management true
 ```
 
-The `tools.*` keys are primarily maintained by `oat tools install`, `oat tools update`, and `oat tools remove`, but they are intentionally visible through `oat config` so workflows and operators can inspect or override pack-state signals when needed.
+The `tools.*` group is a shared project installation snapshot, not an
+effective project-plus-user capability signal. `oat tools install`, `oat tools
+update`, and `oat tools remove` reconcile it from project-scoped canonical
+assets only. When project state is non-empty, reconciliation writes the complete
+eight-pack boolean map. When no project packs remain, it removes the group while
+preserving unrelated shared keys. User-only assets are ignored.
+
+Use `oat config get tools.<pack>` to inspect project installation state.
+`oat config set tools.<pack> ...` remains available as a shared override, but a
+later lifecycle reconciliation may replace the manual value with the canonical
+project snapshot.
+
+Use `oat tools has <pack>` for current effective availability. It checks project
+and user scopes by default; add `--scope project` or `--scope user` to isolate a
+scope, and use the global `--json` flag for the `{ pack, available, scopes }`
+result:
+
+```bash
+oat tools has project-management
+oat tools has project-management --scope user
+oat --json tools has project-management
+```
 
 ### Explainer configuration
 

package/assets/docs/cli-utilities/tool-packs.md

@@ -11,7 +11,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 
 - What it does: explains how bundled OAT packs are installed, updated, inspected, and removed.
 - When to use it: when you need to add capabilities to a repo, update installed skills, or understand which packs own which tools.
-- Primary commands: `oat tools list`, `oat tools install`, `oat tools update`, `oat tools remove`
+- Primary commands: `oat tools list`, `oat tools has`, `oat tools install`, `oat tools update`, `oat tools remove`
 
 ## Bundled packs at a glance
 
@@ -19,17 +19,35 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 - `docs` - docs and agent-instructions governance workflows
 - `workflows` - project lifecycle skills, wave-program orchestration (`oat-wave-program`, `oat-wave-execute`), the project subagent-dispatch adapter, wrap-up reporting, reviewer agents, and core project templates
 - `ideas` - lightweight ideation and promotion flows
-- `utility` - review and repo-maintenance helpers plus the provider-neutral subagent-dispatch engine
+- `utility` - review and repo-maintenance helpers plus portable subagent-selection guidance and the provider-neutral dispatch engine
 - `project-management` - file-backed backlog/reference skills plus backlog, roadmap, current-state, file-per-record decision, and AGENTS-guide templates
 - `research` - research, analysis, comparison, and synthesis skills
 - `brainstorm` - always-on brainstorming entry point with visual companion
 
-### Cross-pack dispatch dependency
+### Orchestration guidance and dispatch dependencies
 
-The reusable dispatch contracts intentionally span two packs:
+The utility pack ships the reusable orchestration pair:
+
+- `subagent-orchestration` owns durable task classes, model-selection
+  principles, dated provider selection matrices, and refresh evidence.
+- `oat-dispatch-subagents` owns capability checks, live catalog intersection,
+  authorized routes, launch acceptance, recovery, and dispatch records.
+
+Provider-aware callers load the generic principles plus exactly one provider
+selection reference, then the dispatch contract plus exactly one matching
+provider mechanics reference. The first reference answers which candidates
+satisfy the task-class floor; the second answers how the active provider can
+launch them. Root callers retain classification, selection judgment,
+cross-lane synthesis, and final authority.
+
+Custom utility selection has a directional dependency: choosing
+`oat-dispatch-subagents` automatically includes `subagent-orchestration`, while
+the self-contained guidance skill may be installed alone. Full utility-pack
+update and removal treat both as explicit members. Removing either skill by
+name does not implicitly remove the other.
+
+The OAT lifecycle adapter intentionally lives in a separate pack:
 
-- `utility` owns `oat-dispatch-subagents`, the provider-neutral engine for
-  capability checks, catalog-aware selection, launch evidence, and recovery.
 - `workflows` owns `oat-project-dispatch-subagents`, the adapter that adds OAT
   project lifecycle context without duplicating provider mechanics.
 
@@ -41,9 +59,9 @@ oat tools install workflows
 ```
 
 The packs remain independently installable. If the workflows adapter is
-present without the utility engine, it fails closed and reports the missing
+present without the utility contracts, it fails closed and reports the missing
 dependency instead of inventing a fallback route. Non-project analytical
-skills can use the utility engine directly.
+skills can use the utility guidance and dispatch layers directly.
 
 ### Cross-pack explainer dependency
 
@@ -169,6 +187,28 @@ Key behavior:
 - Reports whether the tool is invocable (for skills) and whether an update is available
 - Returns exit code 1 if the tool is not found in any scope
 
+### `oat tools has <pack>`
+
+Purpose:
+
+- Check current availability of one bundled pack without treating shared config as a runtime capability cache
+
+Key behavior:
+
+- Defaults to effective availability across project and user scopes
+- Accepts `--scope project`, `--scope user`, or `--scope all`
+- Prints `true` or `false` in plain mode
+- With the global `--json` flag, emits `{ "pack": "<pack>", "available": <boolean>, "scopes": ["project", "user"] }`; `scopes` contains only locations where the pack is currently found
+- Exits `0` for every valid query, including an unavailable pack, `1` for an invalid pack or other actionable input error, and `2` for an unexpected scan or runtime failure
+
+Examples:
+
+```bash
+oat tools has project-management
+oat tools has brainstorm --scope user
+oat --json tools has workflows
+```
+
 ### `oat tools install`
 
 Purpose:
@@ -187,7 +227,7 @@ Key behavior:
 - Removing a pack from a scope happens only when you explicitly choose a narrower end-state in the interactive flow (e.g. a pack at `both` set to `project` only). All staged removals are shown in a single change summary and applied only after one batch confirmation — declining makes no changes
 - Non-interactive installs (including `--scope project`, `--scope user`, and the default pack set) are strictly additive and never remove a pack from a scope. Removal is interactive-only
 - Tracks installed vs bundled skill versions and reports outdated skills
-- Records installed pack state in shared repo config as `tools.<pack>: true` so other OAT workflows can detect installed capabilities without relying on filesystem heuristics
+- Reconciles shared repo config from project-scoped canonical assets only; a user-only install does not set `tools.<pack>: true`
 - Refreshes the managed `OAT tools` section in the repository-root `AGENTS.md`.
 - Installing the `project-management` pack—through either the aggregate picker or `oat tools install project-management`—also upserts a managed `OAT project-management` section. It points agents to `.oat/repo/AGENTS.md` for active PJM and durable-reference routing, summarizes when to consult it, and gives decision-specific guidance for reviewing and creating durable records without hand-editing the generated index.
 - Interactive runs can prompt to update selected outdated skills
@@ -208,7 +248,7 @@ Key behavior:
 - Compares installed versions against bundled versions and copies updated assets
 - For `--pack <pack>` and `--all`, an already-installed pack is reconciled to include newly added bundled skills or agents in that same scope
 - Pack-targeted updates intentionally rewrite bundled template and script companions in place, even when the pack's installed skills are already current
-- For `--pack <pack>` and `--all`, shared repo config is also reconciled from an installed-pack scan so `tools.*` reflects what is actually available and stale `true` flags are cleared
+- For `--pack <pack>` and `--all`, shared repo config is also reconciled from a project-scoped installed-pack scan so `tools.*` reflects repository installation state and stale `true` flags are cleared
 - Dry-run mode with `--dry-run`; auto-sync after mutations by default
 - Use `--no-sync` to skip auto-sync
 - Reports tools that are already current, newer than bundled, or not bundled (custom)
@@ -223,19 +263,21 @@ Key behavior:
 
 - Accepts a tool name, `--pack <pack>`, or `--all` (mutually exclusive)
 - Removes skill directories and agent `.md` files from canonical locations
-- For `--pack <pack>` and `--all`, shared repo config is rewritten from a post-removal scan so `tools.<pack>` becomes `false` when a pack is no longer installed in any scope
+- For `--pack <pack>` and `--all`, shared repo config is reconciled from a post-removal project scan; removing the last project copy clears project state even when a user copy remains
 - Dry-run mode with `--dry-run`; auto-sync after mutations by default
 - Use `--no-sync` to skip auto-sync
 
 ## Shared config signal: `tools.*`
 
-Tool-pack lifecycle commands now persist pack availability in shared repo config under `.oat/config.json`.
+Tool-pack lifecycle commands maintain a project installation snapshot in shared repo config under `.oat/config.json`.
+
+- Install, update, and remove reconcile the snapshot from project-scoped canonical assets only. User-only operations never set a shared `true` flag.
+- When at least one project pack is installed, reconciliation writes the complete eight-pack boolean map: `core`, `ideas`, `docs`, `workflows`, `utility`, `project-management`, `research`, and `brainstorm`.
+- When no project packs remain, reconciliation removes the entire `tools` map. It preserves unrelated shared keys, avoids creating a default-only config file, and skips unchanged writes.
 
-- `oat tools install <pack>` writes `tools.<pack>: true`
-- `oat tools update --pack <pack>` and `oat tools update --all` rebuild the full `tools` map from installed-pack scans
-- `oat tools remove --pack <pack>` and `oat tools remove --all` rebuild the same map after removals
+Use `oat config get tools.<pack>` to inspect this project snapshot. A manual `oat config set tools.<pack> ...` value is a shared override that the next lifecycle reconciliation may replace.
 
-This matters because other workflows can now check `oat config get tools.<pack>` instead of inferring capabilities from directory existence alone. For example, `oat-project-document` checks `tools.project-management` before auto-running repo-reference refresh work.
+Use `oat tools has <pack>` when a workflow needs current effective availability from project or user scope. For example, `oat-project-document` checks `oat tools has project-management` before auto-running repo-reference refresh work.
 
 ## Workflows pack
 
@@ -360,20 +402,22 @@ Key behavior:
   and can surface it later if the conversation turns visual. Persistence paths
   use OAT-managed prefixes (`.oat/brainstorm/<session-id>/` repo-scope or
   `~/.oat/brainstorm/<session-id>/` user-scope).
-- **Terminal-state picker filtered by `tools.<pack>` config.** When the user
-  converges on a destination, the skill consults `oat config get tools.ideas`,
-  `tools.project-management`, and `tools.workflows` to filter the available
-  terminal states. Pack-gated outcomes (capture-as-idea, scoped backlog item,
-  project promotion, active-project fold-back) only appear when the
-  corresponding pack is installed.
+- **Terminal-state picker filtered by effective pack availability.** When the
+  user converges on a destination, the skill runs `oat tools has ideas`, `oat
+tools has project-management`, and `oat tools has workflows` to filter the
+  available terminal states. Pack-gated outcomes (capture-as-idea, scoped
+  backlog item, project promotion, active-project fold-back) appear when the
+  corresponding pack is available at project or user scope. The separate `oat
+config get activeProject` lookup resolves active project state.
 - **Destinations playbook.** The full set of terminal-state stanzas — trigger
   phrases, required template fields, confirmation patterns, handoff targets —
   lives at `.agents/skills/oat-brainstorm/references/destinations.md` and is
   consulted by the skill at destination-identification time.
 - **Pack lifecycle.** `oat tools install brainstorm`, `oat tools update --pack
 brainstorm`, and `oat tools remove --pack brainstorm` manage the skill plus
-  visual-companion bundle as a unit. Standard config-write semantics
-  (`tools.brainstorm: true` on install) apply.
+  visual-companion bundle as a unit. Project installs participate in the shared
+  project snapshot; user-only installs remain available through `oat tools has
+  brainstorm` without setting `tools.brainstorm` in shared config.
 
 ### Auto-sync behavior
 

package/assets/docs/contributing/skills.md

@@ -97,21 +97,28 @@ At minimum, the skill contract should:
 - Stop before side effects if delegation is required for correctness and authorization remains unresolved.
 - Document the fallback path and any quality or independence tradeoff.
 
-OAT-specific skills should compose with the internal
-`oat-dispatch-subagents` contract instead of copying provider selection and
-recovery rules. The caller still owns decomposition, user interaction,
-verification of load-bearing claims, cross-lane synthesis, and artifact
-writes. The dispatch contract owns capability and authorization checks, live
-catalog evidence, route/model/effort selection, launch acceptance, recovery,
-and the neutral dispatch record.
+Delegation-capable skills should load `subagent-orchestration` instead of
+copying task classes, model-selection principles, dated provider matrices, or
+refresh evidence. Load exactly one active-provider selection reference from
+that skill. The caller applies the guidance and still owns decomposition,
+classification judgment, user interaction, verification of load-bearing
+claims, cross-lane synthesis, and artifact writes.
+
+OAT-specific skills should separately compose with the internal
+`oat-dispatch-subagents` contract instead of copying launch or recovery rules.
+Load exactly one matching provider mechanics reference from that skill. The
+dispatch contract owns capability and authorization checks, live catalog
+evidence, authorized routes, launch acceptance, recovery, and the neutral
+dispatch record. Keep model/effort/reasoning/service-tier axes explicit and do
+not collapse the selection and mechanics references into one provider matrix.
 
 Keep project lifecycle policy out of that general layer. A lifecycle caller
 loads `oat-project-dispatch-subagents` to resolve project, phase/task, gate,
 write-boundary, commit, and worktree context, then passes a generic request to
 `oat-dispatch-subagents`. Analytical callers such as repository audits can use
-the general contract directly without requiring an active project. In either
-case, resolve the provider first and load exactly one provider-specific
-reference rather than merging provider mechanics into a universal catalog.
+the guidance and dispatch contracts without requiring an active project. In
+either case, resolve the provider first, then load one selection reference and
+the matching mechanics reference.
 
 Use `create-agnostic-skill` or `create-oat-skill` as the starting point; both include the current delegation guidance and optional capability-detection template.
 

package/assets/docs/provider-sync/providers.md

@@ -116,6 +116,32 @@ than falling back to the root target or a base role.
 - Rule adoption normalizes provider filenames back to canonical `.agents/rules/*.md` entries before cross-provider fanout.
 - Cross-provider fanout is explicit via `oat sync --scope all`.
 
+## Provider mutation safety
+
+The generic sync engine validates provider destinations for every operation that
+creates or updates a symlink, creates or updates a copy, or removes a managed
+provider path. The same guard applies across provider adapters; it is not
+Claude-specific.
+
+Validation runs at three boundaries:
+
+1. During planning, before a provider operation is classified.
+2. Across the complete mutating plan before apply starts, so an already-unsafe
+   later entry cannot allow earlier provider or manifest mutations.
+3. Immediately before each entry's first filesystem mutation, so ancestry that
+   changes after preflight fails closed.
+
+A mutation is refused when its destination escapes the sync scope, equals the
+scope root, or has any existing parent that is a symbolic link or not a
+directory. The final managed destination is excluded from the ancestry walk, so
+an existing managed symlink can still be updated or removed normally.
+
+Whole-plan preflight refusal leaves provider paths, canonical content, external
+symlink targets, and manifest state unchanged. If ancestry changes after
+preflight, the affected entry fails before its first removal or write and does
+not gain manifest ownership. OAT does not traverse, unlink, or rewrite the
+unsafe parent.
+
 ## Reference artifacts
 
 - `.oat/projects/<scope>/<project>/spec.md` (FR5)

package/assets/docs/reference/cli-reference.md

@@ -66,7 +66,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
-- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#plan-declared-parallelism).
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 - `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. For `targeting_correlation_failed`, do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).

package/assets/docs/reference/troubleshooting.md

@@ -61,6 +61,48 @@ Use [Instruction Sync](../provider-sync/instruction-sync.md) for the full strate
 - In TTY mode, select which outdated skills to update when prompted.
 - In non-interactive mode, rerun the relevant pack subcommand with `--force` if you want to overwrite outdated installed skills.
 
+## `sync` reports an unsafe provider parent
+
+Errors containing `Unsafe provider parent`, `symbolic links are not allowed in
+provider ancestry`, or `provider ancestry is not a directory` mean an existing
+parent of a managed provider destination is a symlink or a non-directory entry.
+OAT refuses to traverse, unlink, or rewrite that parent because it may be
+user-managed or externally owned. Canonical content and external symlink targets
+remain untouched.
+
+Recover explicitly:
+
+1. Inspect the reported parent and preserve or migrate any user-managed content.
+2. Replace that provider parent with a real directory under the intended project
+   or user sync scope.
+3. Rerun sync with the matching scope:
+
+   ```bash
+   oat sync --scope project
+   oat sync --scope user
+   oat sync --scope all
+   ```
+
+Do not replace the parent until you understand who owns its existing target.
+OAT intentionally does not automate this recovery.
+
+## A user-installed pack is missing from shared `tools.*`
+
+This is expected. `.oat/config.json#tools` records project installation state,
+so a user-only install does not set `tools.<pack>` in shared repo config.
+
+Check effective project-plus-user availability with:
+
+```bash
+oat tools has <pack>
+```
+
+To confirm specifically that the user copy is present, run:
+
+```bash
+oat tools has <pack> --scope user
+```
+
 ## Manifest not found or invalid
 
 - Missing manifest: run `sync` or `init`

package/assets/docs/workflows/projects/lifecycle.md

@@ -18,7 +18,7 @@ OAT lifecycle order:
 7. Summary (`oat-project-summary`) — generates `summary.md` as institutional memory; `oat-project-pr-final` and `oat-project-complete` auto-refresh it when missing or stale
 8. PR (`oat-project-pr-progress` / `oat-project-pr-final`) — sets `pr_open` status
 9. Revision loop (`oat-project-revise`) — optional; accepts post-PR feedback
-10. Documentation sync (`oat-project-document`) — optional; reads project artifacts and code evidence to identify docs needing updates, checks for missing coverage of newly shipped capability areas, checks `tools.project-management`, and auto-runs `oat-pjm-update-repo-reference` before scanning docs when the project-management pack is installed
+10. Documentation sync (`oat-project-document`) — optional; reads project artifacts and code evidence to identify docs needing updates, checks for missing coverage of newly shipped capability areas, checks effective project-management availability with `oat tools has project-management`, and auto-runs `oat-pjm-update-repo-reference` before scanning docs when the pack is available
 11. Complete (`oat-project-complete`)
 
 **Shortcut:** `oat-project-next` reads project state and invokes the correct next skill automatically — use it instead of remembering which skill comes next. Complements `oat-project-progress` (which is read-only diagnostic).
@@ -63,7 +63,7 @@ from missing state.
 After implementation closeout finishes:
 
 1. **Summary** (`oat-project-summary`) — generates `summary.md` as institutional memory from project artifacts; PR-final and completion will auto-refresh it if you have not already run it or if it is stale
-2. **Documentation** (`oat-project-document`) — optional sync of project docs; now uses the shared `tools.project-management` config signal to decide whether repo-reference refresh should run before docs analysis, and should recommend new docs pages/directories when the shipped work introduces a capability area that the docs app does not already cover
+2. **Documentation** (`oat-project-document`) — optional sync of project docs; checks effective project-management availability with `oat tools has project-management` to decide whether repo-reference refresh should run before docs analysis, and should recommend new docs pages/directories when the shipped work introduces a capability area that the docs app does not already cover
 3. **PR** (`oat-project-pr-final`) — creates PR description (auto-refreshes `summary.md` first when needed, then uses it as source), sets `oat_phase_status: pr_open`, and tracks actual PR existence with `oat_pr_status` / `oat_pr_url`
 4. **Revision loop** (`oat-project-revise`) — accepts post-PR feedback:
    - Inline feedback creates `p-revN` revision phases with `prevN-tNN` task IDs

package/assets/docs/workflows/projects/orchestration-model.md

@@ -53,16 +53,23 @@ does not launch a third tier.
 
 ## Dispatch Layers
 
-Every lifecycle launch flows through two contracts:
+Every lifecycle launch composes three responsibilities:
 
 1. `oat-project-dispatch-subagents` resolves project state, role policy,
    ceilings, scope, files, commits, worktrees, and checkpoints.
-2. `oat-dispatch-subagents` resolves capabilities, catalogs, exact routes,
-   launch acceptance, continuation, and generic evidence.
-
-The lifecycle workflow remains authoritative for synthesis and state mutation.
-The dispatch engine does not edit `plan.md`, `implementation.md`, or project
-state.
+2. `subagent-orchestration` supplies the durable task classes and
+   model-selection principles. The caller loads exactly one active-provider
+   selection reference for dated candidates and refresh evidence.
+3. `oat-dispatch-subagents` resolves capabilities, live catalogs, exact
+   routes, launch acceptance, continuation, recovery, and dispatch records. It
+   loads exactly one matching provider mechanics reference.
+
+The selection and mechanics references form a two-reference provider contract:
+the first owns model guidance, while the second owns provider control surfaces.
+They are loaded together for dispatch but never collapsed into one universal
+matrix. The lifecycle workflow remains authoritative for classification,
+selection judgment, synthesis, and state mutation. The dispatch engine does
+not edit `plan.md`, `implementation.md`, or project state.
 
 ```mermaid
 sequenceDiagram

package/assets/docs/workflows/projects/programmatic-execution.md

@@ -23,7 +23,7 @@ comes from configured dispatch policy or a configured cross-family gate
 (standing, scope-bound), or from explicit user approval for the current run.
 Availability of a provider CLI is capability evidence, not authorization. See
 the route tiers in
-[Orchestration Model](orchestration-model.md#route-tiers-and-terminality) for
+[Orchestration Model](orchestration-model.md#accepted-launch-terminality) for
 how native, policy-resolved, and improvised routes are ranked, and why an
 accepted launch is terminal for automatic replacement.
 

package/assets/docs/workflows/projects/reviews.md

@@ -276,8 +276,8 @@ task class sets its minimum model-capability floor:
 File count alone does not justify escalation. Interpretation and policy
 judgment either use an adequate stronger class or remain with the primary
 reviewer. Active user and repository instructions, the active-provider
-guidance, and the live nested catalog resolve current model examples; the
-canonical reviewer does not promise named models.
+selection guidance, and the live nested catalog resolve current model
+examples; the canonical reviewer does not promise named models.
 
 Reviewer-local fan-out is limited to one bounded, read-only, non-recursive
 round. Each worker receives a disjoint scope, cannot modify files or spawn more
@@ -288,15 +288,22 @@ workers, and returns a compact advisory report containing:
 - gaps in the assigned scope; and
 - explicit uncertainty, including uncertainty about absence claims.
 
-Before launching these lanes, the reviewer loads the generic
-`oat-dispatch-subagents` contract and exactly one active-provider reference.
-That shared contract owns nested capability checks, worker catalog resolution,
-model and effort selection, routing, authorization, launch evidence, and
-provider-specific mechanics. It records each lane's task class, model-class
-floor, classification rationale, and floor satisfaction without assuming that
-workers inherit the primary reviewer's target. Lanes may share one wave only
-when their task classes, model floors, and all other dispatch axes match;
-mixed-class reviews use separate waves and records.
+Before launching these lanes, the reviewer loads `subagent-orchestration` for
+durable task classes and model-selection principles, then exactly one
+active-provider selection reference. The reviewer applies that guidance and
+retains the classification, authority, reconciliation, and final finding
+judgment.
+
+The reviewer separately loads the internal `oat-dispatch-subagents` contract
+and exactly one matching provider mechanics reference. That layer owns nested
+capability checks, live worker-catalog resolution, authorized routing, launch
+acceptance, recovery, and dispatch records. Selection guidance owns dated
+provider matrices and refresh evidence; dispatch mechanics do not duplicate
+them. The dispatch record preserves each reviewer-supplied task class,
+model-class floor, classification rationale, selected axes, and floor
+satisfaction without assuming workers inherit the primary reviewer's target.
+Lanes may share one wave only when their task classes, model floors, and all
+other dispatch axes match; mixed-class reviews use separate waves and records.
 
 This generic reviewer-local use is distinct from
 `oat-project-dispatch-subagents`, which is reserved for OAT lifecycle phase and

package/assets/docs/workflows/skills/index.md

@@ -26,6 +26,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
 - Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
 - Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
+- Choose what to delegate and route bounded work by task class across Codex, Claude, or Cursor: `subagent-orchestration`. It is self-contained and usable without OAT; live catalogs and current instructions take precedence over its dated provider examples.
 - Build visual project explainers and final project recaps: `oat-explainer-kit`, backed by the destination-neutral `explainer-kit` core. See [Explainer Kit](explainer-kit.md).
 - Work on docs surfaces: `authoring-docs` (general documentation baseline), `oat-docs-authoring` (targeted OAT/Fumadocs authoring), `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
@@ -123,6 +124,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 === "Scaffolding and utility"
 
+    - `subagent-orchestration`
     - `explainer-kit`
     - `oat-worktree-bootstrap`
     - `oat-worktree-bootstrap-auto`

package/assets/docs/workflows/skills/repo-improve.md

@@ -56,4 +56,16 @@ Failure to publish a backlog item or issue does not invalidate a successfully wr
 
 ## Orchestration
 
-Full repository audits use `oat-dispatch-subagents` for bounded read-only reconnaissance while the root agent retains vetting, prioritization, and plan writing. Dispatch is native-first. Configured project/workflow policy may authorize required CLI or cross-runtime routes; an agent-improvised alternate route requires explicit current-run approval.
+Full repository audits use bounded read-only reconnaissance while the root
+agent retains classification, vetting, prioritization, cross-lane synthesis,
+and plan writing. Before launch, the caller loads the durable task classes and
+model-selection principles from `subagent-orchestration` plus exactly one
+active-provider selection reference.
+
+The internal `oat-dispatch-subagents` skill then owns capability checks, live
+catalog intersection, exact route selection, launch acceptance, recovery, and
+dispatch records. It loads exactly one matching provider mechanics reference;
+selection and mechanics references are not merged into one universal provider
+contract. Dispatch is native-first. Configured project/workflow policy may
+authorize required CLI or cross-runtime routes; an agent-improvised alternate
+route requires explicit current-run approval.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.13",
-  "docs-config": "0.2.13",
-  "docs-theme": "0.2.13",
-  "docs-transforms": "0.2.13"
+  "cli": "0.2.15",
+  "docs-config": "0.2.15",
+  "docs-theme": "0.2.15",
+  "docs-transforms": "0.2.15"
 }

package/assets/skills/oat-agent-instructions-analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-agent-instructions-analyze
-version: 1.11.1
+version: 1.11.2
 description: Run when you need to evaluate agent instruction file coverage, quality, and drift. Produces a severity-rated analysis artifact. Run before oat-agent-instructions-apply to identify what needs improvement.
 disable-model-invocation: true
 user-invocable: true
@@ -107,7 +107,7 @@ Delta mode scoping:
 git diff --name-only "$STORED_HASH"..HEAD
 ```
 
-Use the changed file list to limit coverage gap assessment (Step 5) and drift detection (Step 7) to affected directories. Quality evaluation (Step 4) always runs on ALL instruction files regardless of mode.
+Use the changed file list to limit coverage gap assessment (Step 4) and drift detection (Step 6) to affected directories. Quality evaluation (Step 3) always runs on ALL instruction files regardless of mode.
 
 ### Step 1: Discover Instruction Files