@open-agent-toolkit/cli 0.3.8 → 0.3.10

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

@@ -134,6 +134,7 @@ Notable commands introduced in the current CLI surface:
   `refs/oat/completed/<project>` result counts as absence. Transport,
   authentication, and other lookup failures fail the command closed; they are
   never converted into a `recorded-absent` row or pull guidance.
+- `oat tools guidance` - print the managed `OAT tools` `AGENTS.md` block for the currently installed packs without installing, upgrading, or writing anything; `--json` returns `status`, `sectionKey`, `target`, `packs`, `otherProjectSkills`, and `managedBlock`. See [Tool Packs](../cli-utilities/tool-packs.md#oat-tools-guidance).
 - `oat tools migrate --pack <pack> --from <scope> --to <scope>` - move one installed pack between project and user scope. Always previews first, installs and re-inventories the destination before touching the source, and offers source removal only after the destination is verified complete. Declining or running non-interactively leaves the pack installed at both scopes rather than failing. `--dry-run` stops after the preview; there is no force flag. See [Tool Packs](../cli-utilities/tool-packs.md#oat-tools-migrate).
 - `oat pjm doctor --json` - read-only repository PJM diagnostics whose result carries an additive `adoption` object (`state` of `declared` | `inferred-legacy` | `partial-initialization` | `none`, `repoRoot`, and `recovery`). This, not `oat tools has project-management`, is the check that answers whether _this repository_ adopted PJM.
 - `oat pjm remote ... --json` - operate one explicit provider-neutral binding.
@@ -165,6 +166,7 @@ Notable commands introduced in the current CLI surface:
 - `oat gate target set <id> --timeout-ms <milliseconds>` - persist a validated per-target gate budget.
 - `oat gate target list --json` - inspect resolved gate targets without selecting or executing a reviewer. Each entry reports its config origin, whether it is explicitly configured and enabled, current availability, and normalized configured invocation values (`unknown` when omitted).
 - `oat gate cross-provider-exec <prompt...>` - choose an available exec target while avoiding the current runtime by default, then run the prompt with the chosen target's configured base command and exit with the child status.
+- `oat instructions sync [--dry-run] [--strategy none|pointer|symlink|copy]` - apply the effective `CLAUDE.md` strategy (`--strategy`, else `instructions.claude.shims`, else `none`). Under the default `none` it removes the `CLAUDE.md` shims OAT created — none at all while any `CLAUDE.md` has content of its own — keeps and reports every other `CLAUDE.md`, and warns about any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` that would make Claude Code ignore `AGENTS.md`. `oat instructions validate` checks the same strategy read-only. See [Instruction Sync](../provider-sync/instruction-sync.md).
 
 ## `oat config` surface flags
 

package/assets/docs/reference/oat-directory-structure.md

@@ -48,16 +48,16 @@ Project scope is used for project workflows and repo-local sync state. User scop
 
 ## Top-level entries
 
-| Path                     | Purpose                                             | Notes                                                                                                               |
-| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, `documentation.*`, and `pjm.remote.*` |
-| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                             |
-| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata                 |
-| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                                     |
-| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                                    |
-| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                                   |
-| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates.             |
-| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`                          |
+| Path                     | Purpose                                             | Notes                                                                                                                                 |
+| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, `documentation.*`, `instructions.*`, and `pjm.remote.*` |
+| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                                               |
+| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata                                   |
+| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                                                       |
+| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                                                      |
+| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                                                     |
+| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates.                               |
+| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`                                            |
 
 ## `.oat/sync/` details
 
@@ -125,9 +125,10 @@ Current schema keys:
 | `documentation.config`                                     | `string`                   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point: the generated app-root manifest `<root>/index.md` for Fumadocs, `mkdocs.yml` for MkDocs. Set by `oat docs init`. `oat docs generate-index` writes it only for the Fumadocs manifest transition and never for MkDocs.                                                                                                                                                                                                                                          |
 | `documentation.excludes`                                   | `string[]`                 | -                        | Globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. See [Excluding pages from the generated index](#excluding-pages-from-the-generated-index).                                                                                                                                                                                                                                                                                                 |
-| `documentation.instructionPointerExcludes`                 | `string[]`                 | -                        | Repo-relative directories `oat instructions sync`/`validate` must not treat as pointer sites, additive to the documentation content root they skip by default. Normalized and de-duplicated; a malformed value (non-array, or an empty or non-string entry) is rejected with exit code `2`. Set as one comma-separated value with `oat config set`; absolute paths and paths escaping the repository are refused. See [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees). |
 | `documentation.requireForProjectCompletion`                | `boolean`                  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                                                                                                                                                                                                                  |
+| `instructions.claude.shims`                                | `string`                   | `"none"`                 | CLAUDE.md shim strategy for `oat instructions sync`/`validate`: `none` (no shims; sync removes OAT-managed ones, all or nothing: none while any `CLAUDE.md` has content; see [All or nothing](../provider-sync/instruction-sync.md#all-or-nothing)), `pointer`, `symlink`, or `copy`. `--strategy` overrides it for one run; any other value is rejected with exit code `2`. See [Instruction Sync](../provider-sync/instruction-sync.md#choosing-a-strategy).                                      |
+| `instructions.claude.excludes`                             | `string[]`                 | -                        | Repo-relative directories `oat instructions sync`/`validate` must not treat as pointer sites, additive to the documentation content root they skip by default. Normalized and de-duplicated; a malformed value (non-array, or an empty or non-string entry) is rejected with exit code `2`. Set as one comma-separated value with `oat config set`; absolute paths and paths escaping the repository are refused. See [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees). |
 | `workflow.autoReviewAtHillCheckpoints`                     | `boolean`                  | unset                    | When `true`, completing a HiLL checkpoint automatically runs the extra lifecycle review. Does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in `plan.md` frontmatter. Legacy `autoReviewAtCheckpoints` remains a fallback.                                                                                                                                                                                             |
 | `workflow.dispatchPolicy.mode`                             | `string`                   | unset                    | Dispatch policy mode: `managed` lets OAT select model/effort controls; `inherit` leaves controls to the host/provider defaults.                                                                                                                                                                                                                                                                                                                                                                     |
 | `workflow.dispatchPolicy.policy`                           | `string`                   | unset                    | Managed dispatch policy: `economy`, `balanced`, `high`, `frontier`, or `uncapped`. Capped policies compile to provider targets; `uncapped` keeps OAT-managed preferred selection without provider caps. `inherit` mode is separate and leaves controls to the host/provider.                                                                                                                                                                                                                        |

package/assets/docs/reference/troubleshooting.md

@@ -56,12 +56,27 @@ when a same-name canonical skill exists; rename one package before retrying.
   - `oat providers set --scope project --enabled <providers> --disabled <providers>`
 - Re-run `oat sync --scope project` after updating config.
 
-## `instructions validate` reports `missing`, `content_mismatch`, or `stray`
+## `instructions validate` reports `missing`, `content_mismatch`, `stray`, or `managed_shim`
 
+- Check the effective strategy (`strategy:` in the output). The default is `none`, which expects no `CLAUDE.md`; `missing` is only reported under a configured shim strategy.
 - Run `oat instructions sync --dry-run` to preview changes.
-- Run `oat instructions sync --strategy pointer|symlink|copy` to apply the expected `CLAUDE.md` shape.
-- If mismatched `CLAUDE.md` files should be overwritten, run `oat instructions sync --force` (or combine it with `--strategy` if needed).
-- If `stray` is reported, `oat instructions sync` will adopt the Claude-only file into `AGENTS.md` and then regenerate `CLAUDE.md`.
+- Under `none`, `managed_shim` entries are `CLAUDE.md` files OAT created; `oat instructions sync` removes them, unless a `CLAUDE.md` with its own content blocks removal (see below).
+- To keep shims instead, run `oat config set instructions.claude.shims pointer` (or `symlink` / `copy`) and then `oat instructions sync`.
+- Under a shim strategy, if mismatched `CLAUDE.md` files should be overwritten, run `oat instructions sync --force`.
+- If `stray` is reported, `oat instructions sync` will adopt the Claude-only file into `AGENTS.md`, then regenerate `CLAUDE.md` under a shim strategy or remove it under `none`.
+
+## `instructions sync` removed no shims because a `CLAUDE.md` has content
+
+- Under `none`, removal is all or nothing: while any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` has content of its own, sync removes no `CLAUDE.md` at all, reports each held-back removal as skipped, and exits `1`. The finding (`claude_md_blocks_shim_removal` under `--json`) names the files with content (`paths`) and the `CLAUDE.md` files kept (`wouldRemove`); `linkedBy` names any `AGENTS.md` link to a file with content, which you replace with that file's content before removing it. `oat instructions validate` reports the same finding.
+- Either remove each named file or move its content into an `AGENTS.md`, then rerun `oat instructions sync`; or set `instructions.claude.shims` to `pointer`, `symlink`, or `copy` to keep `CLAUDE.md` files.
+- See [Instruction Sync](../provider-sync/instruction-sync.md#all-or-nothing).
+
+## `instructions sync` warns that a `CLAUDE.md` makes Claude Code ignore every `AGENTS.md`
+
+- Under the default `none` strategy, a remaining `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` makes Claude Code's `agents-md` plugin stand down: for every session when the file is at the repository root, and for sessions started in its directory or below when it is in a subdirectory.
+- Either remove the named file, or set `instructions.claude.shims` to a shim strategy and rerun `oat instructions sync` to add shims everywhere.
+- If the warning names an `AGENTS.md` that links to the file (`linkedBy` under `--json`), that file holds the only copy of those instructions: replace each linking `AGENTS.md` with the file's content first, then remove the file.
+- Sync never deletes a hand-written or modified `CLAUDE.md` itself; see [Instruction Sync](../provider-sync/instruction-sync.md#leftover-claudemd-warnings).
 - If a broken or unreadable instruction path is reported, fix the underlying file or symlink target first; sync will intentionally skip manual-repair cases instead of forcing recovery.
 - If a directory you expected to see is missing from the scan, confirm it is not under `.git`, `.oat`, `.worktrees`, or `node_modules`.
 - Re-run `oat instructions validate` and confirm status is `ok`.

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -85,13 +85,15 @@ Run the same command without `--dry-run` to replace bundled cells. Use
 `--shared` or `--local` instead when that scope owns the ladder. Add
 `--keep-existing` to fill only missing cells and preserve existing choices.
 
-Version `2026-09-25.1` is the current bundled recommendation. It prefers
-GPT-6 Luna and Sol in Codex, then Sol xhigh, Astra high, and Astra xhigh in
+Version `2026-10-01.1` is the current bundled recommendation. It prefers
+GPT-6 Luna and GPT-6.1 Sol in Codex, then Sol 6.1 xhigh, Astra high, and Astra xhigh in
 Codex Frontier. Astra's task advantage has not been measured locally; this is
 an explicit user-directed preference, not acceptance by the separately
-maintained model-selection policy. Opus 5.5 low/medium/high remains in Claude High.
+maintained model-selection policy. Sonnet 5.5 medium replaces Sonnet 5 medium
+in Claude Economy; the older generation stays supported for explicit cells.
+Opus 5.5 low/medium/high remains in Claude High.
 The Claude low option suits bounded intelligent recon in Balanced or High;
-medium remains the implementation starting point under High. GPT-5.6 targets remain
+medium remains the implementation starting point under High. GPT-6 Sol and GPT-5.6 targets remain
 supported for explicit Codex and Cursor configurations. Cursor's preferred
 ladder interleaves verified GPT-5.6 and Opus 5.5 mappings: Balanced adds
 Opus 5.5 low above Terra high, High orders Sol medium, Opus low, Sol high,
@@ -249,19 +251,23 @@ oat_dispatch_policy:
 The bundled ladder is a curated subset of the supported targets:
 
 - **Codex:** GPT-6 Luna at `low` through `max` across Economy and Balanced;
-  GPT-6 Sol at `low` through `high` in High and `xhigh` in Frontier; then
+  GPT-6.1 Sol at `low` through `high` in High and `xhigh` in Frontier; then
   GPT-6 Astra at `high` and `xhigh` in Frontier. Astra and Sol remain supported
-  at `low`, `medium`, `high`, `xhigh`, and `max`, while GPT-5.6 variants remain
+  at `low`, `medium`, `high`, `xhigh`, and `max`, while GPT-6 Sol and GPT-5.6 variants remain
   available outside this preferred ladder.
-- **Claude:** `haiku` and Sonnet 5 at Economy/Balanced, Opus 5.5 at High and
-  Frontier, and Fable 5.1 at Frontier.
+- **Claude:** `haiku` and Sonnet 5.5 medium at Economy; Opus 5.5 low at
+  Balanced, low/medium/high at High, and xhigh/max at Frontier; Fable 5.1
+  high ends Frontier. Sonnet 5 remains supported for explicit configurations.
 - **Cursor:** the preferred ladder uses approved Composer 2.5, GPT-5.6, Grok
   4.6, Opus 5.5, and Fable 5.1 targets. The catalogue maps each flat ladder ID
-  to its separately verified bracket-form frontmatter model. Grok 4.6 (`low`
+  to its separately verified frontmatter model. Sonnet 5.5 exact-ID pins
+  remain supported outside the ladder; existing families keep their bracket
+  selectors. Grok 4.6 (`low`
   through `xhigh`) and Fable 5.1 (`low` through `max`, thinking variants) were
   approved from a 2026-09-25 [native desktop probe](../../contributing/verifying-cursor-pins.md);
   targets outside the ladder remain available for explicit selection. Grok
-  4.7 has no approved mapping because it ignores bracket selectors.
+  4.7 stays outside the shipped catalogue pending its own approved mapping
+  and per-pin evidence; exact-ID support does not admit arbitrary CLI IDs.
 
 The final candidate in a named tier defines that tier's reviewer ceiling. Lower
 reviewer selection requires a separate reviewed contract; a normal reviewer
@@ -363,9 +369,9 @@ branch replaces, rather than supplements, preferred selection.
 
 An effort-pinned Claude candidate must establish the exact generation and that
 generation's supported effort. Current directly recognized generations include
-`claude-fable-5-1`, `claude-fable-5`, `claude-opus-5-5`, `claude-sonnet-5`,
+`claude-fable-5-1`, `claude-fable-5`, `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-sonnet-5`,
 `claude-opus-4-7`, `claude-opus-4-6`, and `claude-sonnet-4-6`.
-Opus 5.5 supports `low`, `medium`, `high`, `xhigh`, and `max`; consult the
+Opus 5.5 and Sonnet 5.5 support `low`, `medium`, `high`, `xhigh`, and `max`; consult the
 [updating guide](../../contributing/updating-model-guidance.md) before adding
 further generations or rungs. Retired Opus 5.0 and 4.8 are no longer directly
 recognized for effort-pinned dispatch.
@@ -413,8 +419,9 @@ Cursor selection, pin mapping, catalogue availability, and runtime identity are
 separate evidence layers:
 
 - The candidate ladder and resolver use an opaque flat ID.
-- The materialized definition uses the mapping's explicit bracket-form
-  frontmatter model.
+- The materialized definition uses the mapping's explicit frontmatter model,
+  either a verified bracket selector or a separately verified exact ID.
+  Sonnet 5.5 uses exact IDs; existing families keep their bracket mappings.
 - Mapping-specific native-launch evidence authorizes the shipped mapping data.
   An approved mapping may carry a probe record whose `submittedSelector` must
   equal the mapping's `frontmatterModel` and whose `resolvedModel` must equal

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

@@ -47,8 +47,9 @@ flowchart LR
 
   P --> Report["Phase report\nverification + commits"]
   Report --> Root
-  Root --> R["Independent phase reviewer"]
-  R -->|pass| Book["Bookkeeping + next phase"]
+  Root --> Ledger["Commit task ledger\npre-review bookkeeping"]
+  Ledger --> R["Independent phase reviewer"]
+  R -->|pass| Book["Review-outcome bookkeeping\n+ next phase"]
   R -->|blocking findings| Fix["Resume phase implementer\nbounded fix scope"]
   Fix --> R2["Fresh root-owned review round"]
 ```
@@ -241,7 +242,14 @@ already part of the next phase's base.
 
 The root sends the reviewer a fresh scope containing the authoritative phase
 commit range, task IDs and boundaries, project artifacts, and verification
-evidence. The review passes with zero Critical and zero High findings.
+evidence. The root commits the phase's task ledger — task rows, the resume
+pointer, and any settled recovery marker — before it dispatches the reviewer,
+so the reviewed head is never stale by construction. Review-outcome
+bookkeeping — the Reviews row and its disposition, the Orchestration Run, and
+the deferred project-log entries — is out of scope at the reviewed head: the
+root writes it after the review returns. In a parallel group the phase worktree
+does not carry the root ledger, so the reviewer brief names the task ledger out
+of scope as well. The review passes with zero Critical and zero High findings.
 Medium and Low findings are recorded without blocking the phase.
 
 ## Final Exit-Gate Boundary
@@ -278,14 +286,20 @@ contradictory, or ambiguous correlation fails closed. A valid accepted run or
 completed receive is never duplicated.
 
 Freshness is bound to the reviewed HEAD and a versioned implementation
-fingerprint. New generations use an `effective-delta-v1` fingerprint over
+fingerprint. New generations use an `effective-delta-v2` fingerprint over
 Git's canonical NUL-delimited raw tree delta. The generation persists the
 logical PR/default-branch base ref, requires one merge base, and hashes full
 base and final modes and object IDs with rename detection disabled. This makes
 same-file base changes visible while excluding commit history and human diff
 context. Every effective-delta path is included except the exact project
-`state.md` file that carries the digest and would otherwise be self-referential;
-that structured state is validated independently.
+`state.md` file that carries the digest and would otherwise be self-referential
+(that structured state is validated independently) and everything under
+`.oat/projects/` and `.oat/repo/`: project artifacts and repository records
+such as reviews, summaries, backlog items, and decisions never make the exit
+gate stale. `.oat/templates/`, `.oat/scripts/`, `.oat/config*.json`, and
+`.oat/sync/` stay fingerprinted. A stored `effective-delta-v1` value keeps its
+original meaning (only the `state.md` carrier excluded) and is never
+reinterpreted; the next generation after it goes stale uses v2.
 
 Recognized closeout-only descendants preserve a valid result: gate artifacts
 and receipts, project tracking and project-log appends,
@@ -301,8 +315,8 @@ A merge, rebase, or base update preserves the result only when its full
 effective delta matches that rolling checkpoint. Conflict resolution or
 branch-owned implementation, test, skill, template, or workflow changes that
 alter the delta make the result stale, require a current final lifecycle review,
-and start a new gate generation. No implementation or closeout output path is
-excluded from the comparison. Legacy unqualified fingerprints retain the older
+and start a new gate generation. Beyond the version's own exclusion set, no
+implementation or closeout output path is excluded from the comparison. Legacy unqualified fingerprints retain the older
 fail-closed descendant-path behavior and are not migrated in place.
 
 This narrow merge-only exemption relies on fresh repository CI, automated
@@ -375,8 +389,11 @@ Provider controls remain exact: Codex uses
 `providers.claude.dispatchArgs.variant` for an effort-pinned target and
 `providers.claude.dispatchArgs.model` only for a legacy model-only target; and
 Cursor uses `providers.cursor.dispatchArgs.variant`. Cursor launches that exact
-resolver-selected native agent type first; the flat ID and bracket-form pin
+resolver-selected native agent type first; the flat ID and frontmatter pin
 remain inside the explicit mapping and are never normalized by workflow prose.
+A mapping may retain a verified bracket-form selector or use a separately
+verified exact ID, as Sonnet 5.5 does. Exact IDs require an approved mapping
+and native probe evidence; catalog presence alone never enables pass-through.
 The launcher records this selection as `configured`, while runtime identity
 remains `not-reported` without independent observation. Only a pre-start native
 role-selection rejection permits another target-preserving route.

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

@@ -158,13 +158,11 @@ filesystem operation. Deleting or archiving the old scaffold does not make the
 roadmap stop promising its work, so completion checks the claim against the
 prose that still makes it.
 
-When a quick project consolidates earlier scaffolds, quick-start records
+When a quick or lite project consolidates earlier scaffolds, the workflow that
+scaffolds it (`oat-project-quick-start` or `oat-project-lite`) records
 `absorbed_projects` and `absorbed_backlog_ids` in that project's `state.md`
-frontmatter. Those two fields are the only inputs the sweep takes.
-
-Recording them is a quick-mode step today. A lite project that consolidates
-earlier scaffolds records nothing, so the sweep finds no inputs and degrades to
-its recorded note rather than checking that project's surfaces.
+frontmatter, with the same field shapes in both modes. Those two fields are the
+only inputs the sweep takes.
 
 Inside the project-log completion gate — after the log status probe and before
 the roll-up and seal — completion searches the active planning surfaces for each

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.8",
-  "docs-config": "0.3.8",
-  "docs-theme": "0.3.8",
-  "docs-transforms": "0.3.8"
+  "cli": "0.3.10",
+  "docs-config": "0.3.10",
+  "docs-theme": "0.3.10",
+  "docs-transforms": "0.3.10"
 }

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.12.3
+  version: 1.12.4
 ---
 
 # Agent Instructions Analysis
@@ -259,7 +259,7 @@ documentation inventory from Step 2 to:
 **Provider-specific validation:**
 
 - **AGENTS.md**: Check section structure, command accuracy, size budget.
-- **CLAUDE.md**: Verify `@AGENTS.md` import if present, check for content duplication with AGENTS.md.
+- **CLAUDE.md**: Read the shim strategy with `oat config get instructions.claude.shims`. Under a shim strategy (`pointer`, `symlink`, or `copy`), verify the `@AGENTS.md` import if present and check for content duplication with AGENTS.md. Under `none` (the default), Claude Code reads AGENTS.md itself through its built-in `agents-md` plugin, which stands down while a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists on the session's path: a root file affects the whole project, a nested file affects sessions started in its directory or below; record each such file as a High finding whose fix is to remove it or to configure a shim strategy and run `oat instructions sync`. Take the authoritative list from `oat instructions validate --json` `.warnings[]` (code `claude_md_hides_agents_md`), which covers the whole repository including `CLAUDE.local.md` (exact-case names only); the discovery script also lists `CLAUDE.local.md` under the claude provider. When a warning's `linkedBy` is non-empty, that file holds the only copy of the instructions behind those AGENTS.md links: the fix is to replace each linking AGENTS.md with the file's content first and only then remove the file; never recommend plain removal for it. When `.warnings[]` also holds a `claude_md_blocks_shim_removal` item, removal under `none` is all or nothing and is blocked: report its `paths` (the files with content of their own) as the High finding, whose fix is to move each file's content into an AGENTS.md or remove it (for a file its `linkedBy` maps to AGENTS.md links, replace each linking AGENTS.md with the file's content first) and then rerun `oat instructions sync`; list its `wouldRemove` as the CLAUDE.md files that sync then removes. Those files get no `claude_md_hides_agents_md` warning of their own while the block holds, so read them from the block item rather than reporting them as missing.
 - **Claude rules** (`.claude/rules/*.md`): Validate `paths` frontmatter if conditional.
 - **Cursor rules** (`.cursor/rules/*.mdc`): Validate frontmatter fields (`alwaysApply`, `globs`, `description`).
 - **Copilot instructions** (`.github/instructions/*.instructions.md`): Validate `applyTo` frontmatter.
@@ -306,7 +306,7 @@ These checks are mandatory even when the missing file does not appear in the dis
 
 Provider baseline examples:
 
-- **Claude**: if a directory has `AGENTS.md` and the claude provider is active but the matching `CLAUDE.md` shim is missing, record an explicit recommendation to create `CLAUDE.md` with the canonical `@AGENTS.md` import. This applies to **every** directory with an `AGENTS.md` — root and nested alike (e.g., `packages/cli/AGENTS.md` → `packages/cli/CLAUDE.md`).
+- **Claude**: only when a shim strategy is configured (`instructions.claude.shims` is `pointer`, `symlink`, or `copy`): if a directory has `AGENTS.md` and the claude provider is active but the matching `CLAUDE.md` shim is missing, record an explicit recommendation to create `CLAUDE.md` with the canonical `@AGENTS.md` import. This applies to **every** directory with an `AGENTS.md` — root and nested alike (e.g., `packages/cli/AGENTS.md` → `packages/cli/CLAUDE.md`). Under `none`, the default, recommend no `CLAUDE.md`: Claude Code loads AGENTS.md natively, and a shim in some directories but not others makes it ignore the AGENTS.md files that lack one.
 - **Copilot**: if the copilot provider is active but `.github/copilot-instructions.md` is missing, record an explicit recommendation to create the minimal Copilot shim.
 - **agents_md / codex**: no extra always-on shim beyond `AGENTS.md`.
 
@@ -314,7 +314,7 @@ Do not leave these as implied apply-time behavior. They must appear in the analy
 
 **Chained recommendations for new AGENTS.md files:**
 
-When a coverage-gap recommendation proposes creating a **new** `AGENTS.md` in a subdirectory, also emit the corresponding provider-baseline recommendations for that directory in the same artifact. For example, if the analysis recommends creating `packages/cli/AGENTS.md` and the claude provider is active, it must also recommend creating `packages/cli/CLAUDE.md` with `@AGENTS.md`. Do not defer these to a follow-up analysis — they belong in the same artifact so `oat-agent-instructions-apply` can generate both files in one pass.
+When a coverage-gap recommendation proposes creating a **new** `AGENTS.md` in a subdirectory, also emit the corresponding provider-baseline recommendations for that directory in the same artifact. For example, if the analysis recommends creating `packages/cli/AGENTS.md`, the claude provider is active, and a shim strategy is configured, it must also recommend creating `packages/cli/CLAUDE.md` with `@AGENTS.md`. Do not defer these to a follow-up analysis — they belong in the same artifact so `oat-agent-instructions-apply` can generate both files in one pass.
 
 **In delta mode:** Only assess directories that contain files changed since the last tracked commit. Skip unchanged directories.
 

package/assets/skills/oat-agent-instructions-analyze/references/analysis-artifact-template.md

@@ -119,11 +119,11 @@ None | {numbered list}
 
 Missing always-on provider compatibility files that should exist even when no corresponding file was discovered during inventory.
 
-| #   | Provider  | Required Path                     | Format             | Reason                                             | Evidence     | Severity      |
-| --- | --------- | --------------------------------- | ------------------ | -------------------------------------------------- | ------------ | ------------- |
-| 1   | `claude`  | `CLAUDE.md`                       | Claude import shim | {claude active + AGENTS.md present + shim missing} | {exact refs} | {High/Medium} |
-| 2   | `copilot` | `.github/copilot-instructions.md` | Copilot shim       | {copilot active + shim missing}                    | {exact refs} | {High/Medium} |
-| ... |           |                                   |                    |                                                    |              |               |
+| #   | Provider  | Required Path                     | Format             | Reason                                                                                                                    | Evidence     | Severity      |
+| --- | --------- | --------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- |
+| 1   | `claude`  | `CLAUDE.md`                       | Claude import shim | {claude active + shim strategy configured (`instructions.claude.shims` is not `none`) + AGENTS.md present + shim missing} | {exact refs} | {High/Medium} |
+| 2   | `copilot` | `.github/copilot-instructions.md` | Copilot shim       | {copilot active + shim missing}                                                                                           | {exact refs} | {High/Medium} |
+| ... |           |                                   |                    |                                                                                                                           |              |               |
 
 {Or: "No provider baseline gaps identified."}
 

package/assets/skills/oat-agent-instructions-analyze/references/docs/rules-files.md

@@ -125,13 +125,16 @@ User-level rules go in `~/.claude/rules/` and apply to all projects (lower prior
 
 ### 2.6 AGENTS.md Support
 
-**AGENTS.md is NOT natively supported by Claude Code** (GitHub issue #6235 has 2,700+ upvotes, still open). The recommended workaround is a one-line `CLAUDE.md`:
+Source: `anthropics/claude-code` `mods/agents-md` README, as of v2.1.278.
 
-```markdown
-@AGENTS.md
-```
+**Claude Code reads AGENTS.md natively** through its built-in `agents-md` plugin. Its `instructionFiles` option defaults to `claude-md-or-agents-md`; the other values are `claude-md`, `claude-md-and-agents-md`, and `managed-only`.
+
+- **Default mode stands down on any CLAUDE.md.** In `claude-md-or-agents-md`, the plugin loads no AGENTS.md for the session when any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or any directory above it up to the project root; the engine then loads only CLAUDE.md files. A root `CLAUDE.md` or a personal `CLAUDE.local.md` therefore hides every AGENTS.md, and shims in some directories but not others hide every AGENTS.md without one.
+- **`claude-md-and-agents-md`** loads both; an AGENTS.md that a CLAUDE.md already imports or links is not loaded twice.
+- **Only user or managed settings can set the option** (`~/.claude/settings.json`, `--settings`, or managed settings); a project's `.claude/settings.json` cannot.
+- **Nested gaps:** nested AGENTS.md files attach on a text `Read` only (not on `@`-mentions, IDE selections, or notebook, image, or PDF reads), and `--add-dir` directories contribute no AGENTS.md.
 
-This leverages @-import. Alternative: symlink `ln -s AGENTS.md CLAUDE.md`.
+The one-line `CLAUDE.md` shim (`@AGENTS.md`, or `ln -s AGENTS.md CLAUDE.md`) is now **opt-in**: use it for Claude Code releases before the plugin, for users who set `instructionFiles` to `claude-md`, or when the nested gaps above matter, and then keep a shim beside every AGENTS.md. In OAT this is `instructions.claude.shims` (`none` by default; `pointer`, `symlink`, or `copy` to opt in), applied by `oat instructions sync`; see the OAT docs page `provider-sync/instruction-sync.md` (§ Claude Code and AGENTS.md).
 
 ### 2.7 Skills vs CLAUDE.md vs Rules
 
@@ -411,12 +414,12 @@ All three providers support file-pattern-based activation — this is the unifyi
 
 ### 5.4 AGENTS.md Support
 
-| Provider    | Native support                   | Nested                 | Import mechanism     |
-| ----------- | -------------------------------- | ---------------------- | -------------------- |
-| Claude Code | **No** (use `@AGENTS.md` import) | N/A                    | `@path` in CLAUDE.md |
-| Cursor      | **Yes** (first-class)            | Yes (hierarchical)     | N/A — read directly  |
-| Copilot     | **Yes** (`**/AGENTS.md`)         | Yes (nearest wins)     | N/A — read directly  |
-| Codex       | **Yes** (primary format)         | Yes (override pattern) | N/A — native         |
+| Provider    | Native support                                                                                                                                            | Nested                          | Import mechanism                      |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- |
+| Claude Code | **Yes** (built-in `agents-md` plugin; stands down while any CLAUDE.md, `.claude/CLAUDE.md`, or `CLAUDE.local.md` is on the path to the working directory) | Yes (attached on a text `Read`) | Opt-in `@AGENTS.md` shim in CLAUDE.md |
+| Cursor      | **Yes** (first-class)                                                                                                                                     | Yes (hierarchical)              | N/A — read directly                   |
+| Copilot     | **Yes** (`**/AGENTS.md`)                                                                                                                                  | Yes (nearest wins)              | N/A — read directly                   |
+| Codex       | **Yes** (primary format)                                                                                                                                  | Yes (override pattern)          | N/A — native                          |
 
 ---
 

package/assets/skills/oat-agent-instructions-analyze/references/quality-checklist.md

@@ -27,7 +27,7 @@ Per-file evaluation criteria for agent instruction files. Use this checklist to
 
 ### 4. Size Within Budget
 
-- [ ] Root files (AGENTS.md, CLAUDE.md): <300 lines (hard max 500)
+- [ ] Root files (AGENTS.md, and CLAUDE.md when a shim strategy is configured): <300 lines (hard max 500)
 - [ ] Scoped/package files: 40–150 lines
 - [ ] Individual rules files: <80 lines
 - [ ] Always-on baseline load is estimated and kept comfortably below the task budget
@@ -44,7 +44,7 @@ Per-file evaluation criteria for agent instruction files. Use this checklist to
 
 ### 6. Precedence Clear
 
-- [ ] Override semantics are explicit (nearest-wins for AGENTS.md, import directives for CLAUDE.md)
+- [ ] Override semantics are explicit (nearest-wins for AGENTS.md, import directives for CLAUDE.md when a shim strategy is configured)
 - [ ] No ambiguous or conflicting instructions across scope levels
 - **Severity if failing:** Medium
 

package/assets/skills/oat-agent-instructions-analyze/scripts/resolve-instruction-files.sh

@@ -10,7 +10,7 @@
 #
 # File patterns per provider:
 #   agents_md → **/AGENTS.md
-#   claude    → **/CLAUDE.md, .claude/rules/*.md
+#   claude    → **/CLAUDE.md, **/CLAUDE.local.md, .claude/rules/*.md
 #   cursor    → .cursor/rules/*.mdc, .cursor/rules/*.md
 #   copilot   → .github/copilot-instructions.md, .github/instructions/*.instructions.md
 #   cline     → .cline/rules/*
@@ -58,8 +58,9 @@ discover_agents_md() {
 }
 
 discover_claude() {
-  # CLAUDE.md files
-  find_exclude -name 'CLAUDE.md' | while read -r f; do
+  # CLAUDE.md and personal CLAUDE.local.md files (either one makes Claude
+  # Code's default agents-md mode ignore AGENTS.md)
+  find_exclude -name 'CLAUDE.md' -o -name 'CLAUDE.local.md' | while read -r f; do
     local rel="${f#"$REPO_ROOT"/}"
     printf 'claude\t%s\n' "$rel"
   done

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.7.2
+  version: 1.7.3
 ---
 
 # Agent Instructions Apply
@@ -204,7 +204,7 @@ recommendation so plan review and generation stay aligned to the same pack file.
 **For provider baseline gaps (always-on provider files):**
 
 - Treat them as first-class recommendations from the artifact, not as implied apply-time behavior
-- Examples include missing Claude `CLAUDE.md` import shims and missing `.github/copilot-instructions.md` shims
+- Examples include missing Claude `CLAUDE.md` import shims (recommended only when `instructions.claude.shims` is a shim strategy: `pointer`, `symlink`, or `copy`) and missing `.github/copilot-instructions.md` shims
 - Carry forward the artifact's evidence refs, confidence, and disclosure mode into the plan
 - If the artifact marks a provider-baseline recommendation `omit`, do not include it in the apply plan
 - If the artifact marks a provider-baseline recommendation `ask_user`, include it with the evidence and require explicit user approval
@@ -240,7 +240,7 @@ recommendation so plan review and generation stay aligned to the same pack file.
 **Multi-format composition order:**
 
 1. **AGENTS.md first** — the canonical, provider-agnostic file
-2. **CLAUDE.md** — if claude provider is active, ensure `@AGENTS.md` import exists
+2. **CLAUDE.md** — only if the claude provider is active and a shim strategy is configured (`oat config get instructions.claude.shims` returns `pointer`, `symlink`, or `copy`), ensure the `@AGENTS.md` import exists. Under `none`, the default, create no `CLAUDE.md`: Claude Code reads AGENTS.md itself, and a CLAUDE.md makes it ignore AGENTS.md for sessions started in that file's directory or below (project-wide for a root file)
 3. **Glob-scoped rules** — author once in canonical format at `.agents/rules/{name}.md` with YAML frontmatter (`description`, `globs`, `activation`)
    - `activation` MUST be one of `always`, `glob`, `agent-requested`, `manual` — any other value (e.g. `auto`) is rejected by `oat sync`. Use `glob` (with `globs`) for file-targeted rules; see `frontmatter/canonical-rule.md` for the full activation matrix.
    - Provider-specific rule files are generated by `oat sync --scope project`

package/assets/skills/oat-agent-instructions-apply/references/docs/rules-files.md

@@ -125,13 +125,16 @@ User-level rules go in `~/.claude/rules/` and apply to all projects (lower prior
 
 ### 2.6 AGENTS.md Support
 
-**AGENTS.md is NOT natively supported by Claude Code** (GitHub issue #6235 has 2,700+ upvotes, still open). The recommended workaround is a one-line `CLAUDE.md`:
+Source: `anthropics/claude-code` `mods/agents-md` README, as of v2.1.278.
 
-```markdown
-@AGENTS.md
-```
+**Claude Code reads AGENTS.md natively** through its built-in `agents-md` plugin. Its `instructionFiles` option defaults to `claude-md-or-agents-md`; the other values are `claude-md`, `claude-md-and-agents-md`, and `managed-only`.
+
+- **Default mode stands down on any CLAUDE.md.** In `claude-md-or-agents-md`, the plugin loads no AGENTS.md for the session when any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or any directory above it up to the project root; the engine then loads only CLAUDE.md files. A root `CLAUDE.md` or a personal `CLAUDE.local.md` therefore hides every AGENTS.md, and shims in some directories but not others hide every AGENTS.md without one.
+- **`claude-md-and-agents-md`** loads both; an AGENTS.md that a CLAUDE.md already imports or links is not loaded twice.
+- **Only user or managed settings can set the option** (`~/.claude/settings.json`, `--settings`, or managed settings); a project's `.claude/settings.json` cannot.
+- **Nested gaps:** nested AGENTS.md files attach on a text `Read` only (not on `@`-mentions, IDE selections, or notebook, image, or PDF reads), and `--add-dir` directories contribute no AGENTS.md.
 
-This leverages @-import. Alternative: symlink `ln -s AGENTS.md CLAUDE.md`.
+The one-line `CLAUDE.md` shim (`@AGENTS.md`, or `ln -s AGENTS.md CLAUDE.md`) is now **opt-in**: use it for Claude Code releases before the plugin, for users who set `instructionFiles` to `claude-md`, or when the nested gaps above matter, and then keep a shim beside every AGENTS.md. In OAT this is `instructions.claude.shims` (`none` by default; `pointer`, `symlink`, or `copy` to opt in), applied by `oat instructions sync`; see the OAT docs page `provider-sync/instruction-sync.md` (§ Claude Code and AGENTS.md).
 
 ### 2.7 Skills vs CLAUDE.md vs Rules
 
@@ -411,12 +414,12 @@ All three providers support file-pattern-based activation — this is the unifyi
 
 ### 5.4 AGENTS.md Support
 
-| Provider    | Native support                   | Nested                 | Import mechanism     |
-| ----------- | -------------------------------- | ---------------------- | -------------------- |
-| Claude Code | **No** (use `@AGENTS.md` import) | N/A                    | `@path` in CLAUDE.md |
-| Cursor      | **Yes** (first-class)            | Yes (hierarchical)     | N/A — read directly  |
-| Copilot     | **Yes** (`**/AGENTS.md`)         | Yes (nearest wins)     | N/A — read directly  |
-| Codex       | **Yes** (primary format)         | Yes (override pattern) | N/A — native         |
+| Provider    | Native support                                                                                                                                            | Nested                          | Import mechanism                      |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- |
+| Claude Code | **Yes** (built-in `agents-md` plugin; stands down while any CLAUDE.md, `.claude/CLAUDE.md`, or `CLAUDE.local.md` is on the path to the working directory) | Yes (attached on a text `Read`) | Opt-in `@AGENTS.md` shim in CLAUDE.md |
+| Cursor      | **Yes** (first-class)                                                                                                                                     | Yes (hierarchical)              | N/A — read directly                   |
+| Copilot     | **Yes** (`**/AGENTS.md`)                                                                                                                                  | Yes (nearest wins)              | N/A — read directly                   |
+| Codex       | **Yes** (primary format)                                                                                                                                  | Yes (override pattern)          | N/A — native                          |
 
 ---
 

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read
 metadata:
-  version: 1.2.10
+  version: 1.2.11
 ---
 
 # Dispatching OAT Subagents

package/assets/skills/oat-dispatch-subagents/references/provider-cursor.md

@@ -46,8 +46,11 @@ prohibited.
 
 Outer lifecycle implementer and reviewer dispatch uses the exact
 `providers.cursor.dispatchArgs.variant` returned by the lifecycle resolver.
-The resolver maps an opaque flat model ID and owns the bracket-form model pin
-inside the materialized definition; skills never parse, normalize, or
+The resolver maps an opaque flat model ID to the mapping's explicit frontmatter
+pin inside the materialized definition. Existing families keep their verified
+bracket-form pins; Sonnet 5.5 uses verified exact-ID pins. Each exact ID needs
+its own native evidence and approved registry entry: this is not generic
+pass-through of any CLI catalog ID. Skills never parse, normalize, or
 reconstruct either model string.
 
 1. Require a non-empty resolver-returned variant for managed dispatch.