@open-agent-toolkit/cli 0.3.8 → 0.3.9

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

@@ -1,19 +1,22 @@
 ---
 title: Instruction Sync
-description: Project-scoped AGENTS.md and CLAUDE.md validation, repair strategies, and Claude-only adoption.
+description: Project-scoped AGENTS.md and CLAUDE.md validation, the no-shim default, opt-in shim strategies, and Claude-only adoption.
 ---
 
 # Instruction Sync
 
-`oat instructions ...` is the project-scoped lane for keeping canonical `AGENTS.md` files aligned with sibling `CLAUDE.md` files throughout a repository tree.
+`oat instructions ...` is the project-scoped lane for keeping canonical `AGENTS.md` files and any sibling `CLAUDE.md` files consistent throughout a repository tree.
+
+By default OAT keeps **no** `CLAUDE.md` shims: Claude Code reads `AGENTS.md` itself (see [Claude Code and AGENTS.md](#claude-code-and-agentsmd)). A repository opts back into shims with `instructions.claude.shims`.
 
 Use it when you want OAT to:
 
-- validate nested `AGENTS.md` / `CLAUDE.md` pairs
-- repair missing or drifted `CLAUDE.md` files with a chosen strategy
+- validate nested `AGENTS.md` files, and their `CLAUDE.md` shims when a shim strategy is configured
+- remove the `CLAUDE.md` shims OAT created, under the default, once no `CLAUDE.md` with its own content remains, and warn about any `CLAUDE.md` that would hide `AGENTS.md` from Claude Code
+- create or repair `CLAUDE.md` shims with a chosen strategy, when you opt in
 - adopt Claude-only directories back into canonical `AGENTS.md`
 
-This command group is intentionally separate from manifest-backed provider sync. It operates on repo-local instruction files, not provider view manifests.
+This command group is intentionally separate from manifest-backed provider sync. It operates on repo-local instruction files, not provider view manifests. The shim setting affects only `oat instructions`: `oat sync` writes the same rules (including `.claude/rules`), skills, and agents under every strategy and never creates or removes a `CLAUDE.md`, and `oat instructions sync` leaves synced `.claude/rules` files alone.
 
 ## Scope
 
@@ -22,8 +25,9 @@ Instruction sync is currently project-only.
 - It scans the current repository recursively.
 - It supports nested directories all the way down the tree.
 - It skips provider-irrelevant or local-only roots such as `.git`, `.oat`, `.worktrees`, and `node_modules`.
-- Exception: `.oat/repo/**` is scanned even though the rest of `.oat/` is skipped, so the curated `AGENTS.md` files there (repo root guidance, `pjm/`, `reference/`) get their sibling `CLAUDE.md` shims managed and validated like any other directory. The rest of `.oat/` (`templates/`, `projects/`, `sync/`) stays excluded.
-- It skips the documentation content tree by default, and any path you add to `documentation.instructionPointerExcludes`. See [Documentation trees](#documentation-trees) below.
+- It stops at nested git checkouts: any directory below the root that holds its own `.git` (a directory, or the gitdir file of a submodule or linked worktree such as `.claude/worktrees/<name>`) is a separate repository that its own `oat instructions` run owns. Nothing inside it is scanned, removed, or warned about.
+- Exception: `.oat/repo/**` is scanned even though the rest of `.oat/` is skipped, so the curated `AGENTS.md` files there (repo root guidance, `pjm/`, `reference/`) are managed and validated like any other directory. The rest of `.oat/` (`templates/`, `projects/`, `sync/`) stays excluded.
+- It skips the documentation content tree by default, and any path you add to `instructions.claude.excludes`. See [Documentation trees](#documentation-trees) below.
 - It does not scan user-level provider roots such as `~/.claude` in this release.
 
 ## Documentation Trees
@@ -49,20 +53,25 @@ only; it does not change what instruction sync excludes.)
 canonically names the docs _app_ root, and a file like
 `apps/oat-docs/AGENTS.md` is instructions for working on the docs app rather
 than a documentation page. When the app root has a `docs` child, only that
-child is skipped, and the app root keeps receiving its `CLAUDE.md` pointer. Opt
-the app root out explicitly if you do not want it synced.
+child is skipped, and the app root is still synced (under a shim strategy it
+keeps receiving its `CLAUDE.md` pointer). Opt the app root out explicitly if
+you do not want it synced.
 
-Add further paths with `documentation.instructionPointerExcludes`, a list of
+Add further paths with `instructions.claude.excludes`, a list of
 repository-relative directories. Set it with
-`oat config set documentation.instructionPointerExcludes "vendor,third_party/docs"`
+`oat config set instructions.claude.excludes "vendor,third_party/docs"`
 (an empty value clears it, and `oat config unset` removes it), or write it
 directly:
 
 ```json
 {
   "documentation": {
-    "root": "apps/oat-docs",
-    "instructionPointerExcludes": ["vendor", "third_party/docs"]
+    "root": "apps/oat-docs"
+  },
+  "instructions": {
+    "claude": {
+      "excludes": ["vendor", "third_party/docs"]
+    }
   }
 }
 ```
@@ -115,8 +124,11 @@ leaves the content root underived, and no default exclusion applies).
 
 Exclusion only stops a directory from being scanned. Nothing is deleted: a
 `CLAUDE.md` that already exists inside an excluded tree is left exactly as it
-is. When any exclusion is configured, `--json` output carries three additional
-fields.
+is, even under the default `none` strategy, which removes managed shims
+everywhere else. Exclusion does not silence the
+[leftover `CLAUDE.md` warning](#leftover-claudemd-warnings), because Claude
+Code does not honor OAT's exclusions. When any exclusion is configured,
+`--json` output carries three additional fields.
 
 - `excludedPaths` lists the configured exclusions — a statement of intent, not
   a per-directory skip log, so `.oat` appearing there does not contradict
@@ -135,8 +147,8 @@ dropped before `excludedPaths` is built, so it appears only here.
 ## Canonical Model
 
 - `AGENTS.md` is canonical.
-- `CLAUDE.md` is derived from the sibling `AGENTS.md`.
-- If a directory contains only `CLAUDE.md`, OAT can adopt that file by writing canonical `AGENTS.md` content first and then regenerating `CLAUDE.md`.
+- A `CLAUDE.md` beside it is either absent (the default, strategy `none`) or a shim derived from the sibling `AGENTS.md` (strategies `pointer`, `symlink`, and `copy`).
+- If a directory contains only `CLAUDE.md`, OAT can adopt that file by writing canonical `AGENTS.md` content first. Under a shim strategy it then regenerates `CLAUDE.md`; under `none` it removes it.
 
 ## Commands
 
@@ -146,40 +158,177 @@ Read-only validation for instruction integrity.
 
 - Resolves the project root automatically.
 - Scans nested directories for instruction pairs and Claude-only strays.
-- Returns exit code `0` when everything is valid and `1` when drift is detected.
-- Suggests the matching repair command, including `--strategy` when you validated with a non-default mode.
+- Returns exit code `0` when everything is valid and `1` when drift is detected. Leftover-`CLAUDE.md` warnings never change the exit code.
+- Suggests the matching repair command, including `--strategy` when you validated with an explicit `--strategy`.
 
 ### `oat instructions sync`
 
 Repair and adoption command for instruction drift.
 
 - Mutates by default.
-- Use `--dry-run` to preview planned actions.
-- Use `--force` to overwrite mismatched `CLAUDE.md` files.
-- Reuses the selected strategy when creating or repairing `CLAUDE.md`.
+- Use `--dry-run` to preview planned actions, including every planned removal.
+- Under a shim strategy, use `--force` to overwrite mismatched `CLAUDE.md` files. Under `none`, `--force` has no effect: sync never deletes anything that is not an exact managed shim.
+- Applies the effective strategy when creating, repairing, or removing `CLAUDE.md`.
 
-## Supported Strategies
+Both commands report the effective strategy as `strategy:` in human output and as the `strategy` field under `--json`.
 
-`CLAUDE.md` can be generated or validated in one of three modes:
+## Supported Strategies
 
-| Strategy  | Expected `CLAUDE.md` shape       | Notes                                   |
-| --------- | -------------------------------- | --------------------------------------- |
-| `pointer` | file content `@AGENTS.md`        | Default mode. Lightweight and explicit. |
-| `symlink` | file symlink to `AGENTS.md`      | Uses a same-directory relative symlink. |
-| `copy`    | hard copy of `AGENTS.md` content | Useful when symlinks are undesirable.   |
+| Strategy  | Expected `CLAUDE.md` shape       | Notes                                                                                               |
+| --------- | -------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `none`    | no `CLAUDE.md`                   | Default. Sync removes the shims OAT created (all or nothing) and warns about any other `CLAUDE.md`. |
+| `pointer` | file content `@AGENTS.md`        | Lightweight and explicit. The default before shims became opt-in.                                   |
+| `symlink` | file symlink to `AGENTS.md`      | Uses a same-directory relative symlink.                                                             |
+| `copy`    | hard copy of `AGENTS.md` content | Useful when symlinks are undesirable.                                                               |
 
 Validation treats the selected file shape as part of correctness. For example, `copy` mode rejects a symlink even if the symlink resolves to identical content.
 
+### Choosing a strategy
+
+The effective strategy for a run is resolved in this order:
+
+1. the `--strategy` flag, which overrides for that one run and never changes config;
+2. `instructions.claude.shims` in `.oat/config.json`;
+3. the built-in default, `none`.
+
+Persist a shim strategy for the repository with:
+
+```bash
+oat config set instructions.claude.shims pointer
+oat instructions sync
+```
+
+`oat config unset instructions.claude.shims` returns to the default. A value outside `none`, `pointer`, `symlink`, and `copy` is rejected with exit code `2` instead of silently falling back to the default, and `oat config set` can still repair it.
+
 ## Reported States
 
 `oat instructions validate` and `oat instructions sync --dry-run` work from the same scan model.
 
-| State              | Meaning                                                                                          |
-| ------------------ | ------------------------------------------------------------------------------------------------ |
-| `ok`               | The discovered instruction pair matches the selected strategy.                                   |
-| `missing`          | `AGENTS.md` exists but sibling `CLAUDE.md` is missing.                                           |
-| `content_mismatch` | `CLAUDE.md` exists but has the wrong shape/content, or an instruction file is unreadable/broken. |
-| `stray`            | `CLAUDE.md` exists without sibling `AGENTS.md` and the Claude file is readable enough to adopt.  |
+| State              | Meaning                                                                                                                                                          |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ok`               | The directory matches the effective strategy (under `none`: no `CLAUDE.md` beside `AGENTS.md`).                                                                  |
+| `missing`          | Shim strategies only: `AGENTS.md` exists but sibling `CLAUDE.md` is missing. Under `none` a missing `CLAUDE.md` is correct, never drift.                         |
+| `content_mismatch` | `CLAUDE.md` exists but has the wrong shape/content, or an instruction file is unreadable/broken.                                                                 |
+| `stray`            | `CLAUDE.md` exists without sibling `AGENTS.md` and the Claude file is readable enough to adopt.                                                                  |
+| `managed_shim`     | `none` only: a `CLAUDE.md` in an exact shape OAT writes. Drift; sync removes it unless [a `CLAUDE.md` with content blocks removal](#all-or-nothing).             |
+| `unmanaged`        | `none` only: a `CLAUDE.md` that is not an exact managed shape (hand-written, modified, or a symlink elsewhere). Reported and kept, never deleted, and not drift. |
+
+## Removing OAT-Managed Shims
+
+Under `none`, a non-dry-run sync removes the `CLAUDE.md` files OAT created, so
+the repository never sits with shims in some directories and not others (see
+[Claude Code and AGENTS.md](#claude-code-and-agentsmd) for why that state is
+worse than either extreme). `--dry-run` lists each planned `remove` action and
+changes nothing.
+
+Removal is deliberately narrow. It only ever targets a file named `CLAUDE.md`
+whose sibling is `AGENTS.md`, inside the tree the scan walks, in one of these
+exact shapes:
+
+- the pointer `@AGENTS.md` followed by a newline (LF or CRLF), and nothing else;
+- a symlink whose target names the sibling `AGENTS.md`;
+- a byte-identical copy of the sibling `AGENTS.md`.
+
+Everything else is kept and reported as `unmanaged`: a hand-written or edited
+`CLAUDE.md`, a pointer with extra lines or trailing spaces, a symlink to any
+other file, `.claude/CLAUDE.md`, and any `CLAUDE.md` that a scanned instruction
+file in another directory links to (`pkg/AGENTS.md -> ../CLAUDE.md`), which
+is neither removed nor adopted because that would leave the link dangling; the
+entry names the links. A `CLAUDE.md` that the sibling
+`AGENTS.md` resolves to (the Claude-first `ln -s CLAUDE.md AGENTS.md` layout,
+or a hard link) holds the only copy of the instructions, so it is never
+treated as a shim of any shape; and a copy is only ever recognized against a
+distinct regular `AGENTS.md`. `CLAUDE.local.md` is never touched and never
+scanned as a shim; it is reported only through the
+[leftover warning](#leftover-claudemd-warnings). A `CLAUDE.md` inside the
+documentation content tree, an excluded directory, or a nested git checkout is
+never touched.
+
+### All or nothing
+
+A file with content never leaves a mix behind. If any `CLAUDE.md`,
+`.claude/CLAUDE.md`, or `CLAUDE.local.md` in the repository is not one of the
+exact shapes above — it has content of its own — sync removes **nothing**, not
+even the managed shims.
+A partial removal would strand directories: while that file exists, Claude
+Code ignores `AGENTS.md` for the sessions it covers, and the removed shims were
+what carried those directories' instructions. The check covers the whole
+repository, including excluded and documentation trees, because Claude Code's
+walk does not honor OAT's exclusions. A lone `CLAUDE.md` that sync will adopt
+(no sibling `AGENTS.md`) is not counted: its content moves into a new
+`AGENTS.md`. While another file blocks removal, that stray is still adopted
+into `AGENTS.md`, but its `CLAUDE.md` is kept.
+
+Exact shims do not block. An exact shim inside an `instructions.claude.excludes`
+directory or the documentation content tree is never touched, so sync removes
+the other shims and reports that one as a
+[leftover](#leftover-claudemd-warnings); sessions started in its directory
+still ignore `AGENTS.md` until you remove it.
+
+When removal is blocked, sync reports every removal it held back as a skipped
+action and exits `1`, and sync, `oat instructions validate`, and `oat-doctor`
+report one finding (`code: "claude_md_blocks_shim_removal"` under `--json`,
+with `paths` naming the files with content, `wouldRemove` naming the
+`CLAUDE.md` files kept, and `linkedBy` mapping each file in `paths` to the
+`AGENTS.md` links that reach it). The finding names the `CLAUDE.md` files the
+configuration would remove, says none were removed and why, links to
+[Claude Code and AGENTS.md](#claude-code-and-agentsmd), and names what to do
+next:
+
+- remove each named file, or move its content into an `AGENTS.md`, and rerun
+  `oat instructions sync`; for a file an `AGENTS.md` links to (the Claude-first
+  layout), replace each link with the file's content first, then remove the
+  file, because it holds the only copy of those instructions; or
+- set `instructions.claude.shims` to a shim strategy (`pointer`, `symlink`, or
+  `copy`) to keep `CLAUDE.md` files.
+
+While removal is blocked, the files in `wouldRemove` get no
+[leftover warning](#leftover-claudemd-warnings) of their own: the finding
+already names them, and removing one by hand would recreate the mix.
+
+Removal also fails closed at apply time. Immediately before deleting, sync
+re-checks the file: it must still be the same file the scan saw (same device
+and inode, and the same symlink target), still an exact managed shape, and not
+the target of a link from any scanned instruction file. If it was edited or
+replaced, or a link to it appeared, in between, it is kept, byte for byte, and reported
+as `CLAUDE.md changed since planning (...); kept`, and the command exits `1`
+so you can rerun it.
+
+## Leftover `CLAUDE.md` Warnings
+
+Under `none`, after sync (and on every `validate`) OAT reports each remaining
+`CLAUDE.md`, `.claude/CLAUDE.md`, and `CLAUDE.local.md` anywhere in the
+repository with a warning: while that file exists, Claude Code's default
+`agents-md` mode ignores every `AGENTS.md` in the project. For a file at the
+root (including `.claude/CLAUDE.md` and `CLAUDE.local.md` there) that holds for
+every session; for a file in a subdirectory it holds for sessions started in
+that directory or below, and the warning says so. The warning names exactly
+two ways out:
+
+- remove the file — or, when an `AGENTS.md` links to it (the warning's
+  `linkedBy`), first replace each linking `AGENTS.md` with the file's content,
+  because the file holds the only copy of those instructions; or
+- set `instructions.claude.shims` in `.oat/config.json` to a shim
+  strategy (`pointer`, `symlink`, or `copy`) and rerun `oat instructions sync`
+  to add shims back everywhere.
+
+This check is a separate, read-only walk of the whole repository. It
+deliberately ignores `documentation.root` and
+`instructions.claude.excludes`, which only limit what OAT may
+change, because Claude Code's own walk does not honor them. Only `.git`,
+`node_modules`, the root `.worktrees`, and nested git checkouts are skipped.
+
+Warnings go to stderr in human mode and to the `warnings` array under `--json`
+(each item has `code: "claude_md_hides_agents_md"`, a repository-relative
+`path`, `linkedBy` — the repository-relative `AGENTS.md` paths whose symlink
+chain reaches the file, empty when there are none — and the `message`).
+Names are matched exactly: a case variant such as `claude.md` is neither
+reported nor ever removed, because such names are common for ordinary
+documents (a provider page named `claude.md`, for example). On a
+case-insensitive filesystem, rename a case-variant file yourself if Claude Code
+treats it as `CLAUDE.md`. They never change the exit code, a dry run leaves
+out files it is about to remove, a repository with no remaining `CLAUDE.md`
+prints nothing, and no warning is emitted under a shim strategy.
 
 ## Claude-Only Adoption
 
@@ -187,15 +336,59 @@ When a directory contains `CLAUDE.md` but no `AGENTS.md`, sync can adopt it:
 
 1. Read the existing `CLAUDE.md`
 2. Write canonical `AGENTS.md` with that content
-3. Regenerate `CLAUDE.md` using the selected strategy
+3. Under a shim strategy, regenerate `CLAUDE.md` using that strategy. Under
+   `none`, remove the `CLAUDE.md`, so adoption never leaves a file that makes
+   Claude Code ignore `AGENTS.md` — unless another `CLAUDE.md` with content
+   [blocks removal](#all-or-nothing), in which case the adopted `CLAUDE.md` is
+   kept.
+
+This means the original Claude instructions become canonical before the derived file is rewritten or removed.
 
-This means the original Claude instructions become canonical before the derived file is rewritten.
+Under `none` the removal is re-verified like any other: the `CLAUDE.md` must
+still be the same file and now byte-identical to the new `AGENTS.md`. If it
+changed during adoption, it is kept and reported as
+`CLAUDE.md kept after adoption into AGENTS.md (...)`, and it is also named in a
+leftover warning.
 
 Readable Claude-only files are adoptable. Unreadable Claude-only files are not.
+`.claude/CLAUDE.md` is Claude Code's own alternate project file, not a stray,
+so under `none` it is never adopted.
+
+## Claude Code and AGENTS.md
+
+Claude Code reads `AGENTS.md` natively through its built-in `agents-md` plugin
+(`anthropics/claude-code`, `mods/agents-md`, as of v2.1.278). Its
+`instructionFiles` option defaults to `claude-md-or-agents-md`:
+
+- In that default mode the plugin stands down for the **whole project** when
+  any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in any
+  directory from the project root down to the working directory; Claude Code
+  then loads only `CLAUDE.md` files. A single root `CLAUDE.md` or a personal
+  `CLAUDE.local.md` is enough to make it ignore every `AGENTS.md`, and a
+  repository with shims in some directories but not others loses every
+  `AGENTS.md` that has no shim. This is why the default removes managed shims
+  and warns about the rest.
+- In `claude-md-and-agents-md` mode, an `AGENTS.md` that a `CLAUDE.md` already
+  imports or links is not loaded twice, so shims are harmless there.
+- The option can be set only in user settings (`~/.claude/settings.json`),
+  with `--settings`, or in managed settings. A project's
+  `.claude/settings.json` cannot set it, so a repository cannot choose the mode
+  for its contributors.
+
+Opt into a shim strategy when your contributors need `CLAUDE.md`:
+
+- they run Claude Code releases from before the built-in `agents-md` plugin;
+- they set `instructionFiles` to `claude-md`, which loads no `AGENTS.md`;
+- the plugin's documented gaps matter to you: nested `AGENTS.md` files attach
+  only on a text file `Read` (not on `@`-mentions, IDE selections, or
+  notebook, image, or PDF reads), and `--add-dir` directories contribute no
+  `AGENTS.md`, where Claude Code's own `CLAUDE.md` loading covers those cases
+  (for `--add-dir`, only when `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`
+  is set).
 
 ## When `--force` Is Required
 
-`oat instructions sync` does not overwrite a mismatched `CLAUDE.md` unless you pass `--force`.
+Under a shim strategy, `oat instructions sync` does not overwrite a mismatched `CLAUDE.md` unless you pass `--force`.
 
 Typical pattern:
 
@@ -223,9 +416,18 @@ In these cases, sync reports a manual-repair skip instead of guessing at destruc
 
 ## Example Workflow
 
-Preview and adopt nested Claude-only strays as pointer files:
+Preview and apply the default: remove OAT-managed shims and adopt Claude-only
+strays into `AGENTS.md`:
+
+```bash
+oat instructions sync --dry-run
+oat instructions sync
+```
+
+Opt the repository into pointer shims:
 
 ```bash
+oat config set instructions.claude.shims pointer
 oat instructions sync --dry-run
 oat instructions sync
 ```

package/assets/docs/provider-sync/scope-and-surface.md

@@ -123,7 +123,7 @@ runtime mismatch, malformed output, and missing telemetry never authorize it.
 ## Non-interop namespaces in the same CLI
 
 - `oat project new <name>` (workflow/project scaffolding)
-- `oat instructions validate` / `oat instructions sync` (AGENTS.md/CLAUDE.md pointer, symlink, or copy integrity plus Claude-only adoption)
+- `oat instructions validate` / `oat instructions sync` (AGENTS.md integrity with no CLAUDE.md shims by default, opt-in pointer, symlink, or copy shims, plus Claude-only adoption)
 - `oat internal validate-oat-skills` (internal maintenance)
 
 ## Reference artifacts

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/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

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.9",
+  "docs-config": "0.3.9",
+  "docs-theme": "0.3.9",
+  "docs-transforms": "0.3.9"
 }