@open-agent-toolkit/cli 0.3.8 → 0.3.9

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-doctor/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 2.0.1
+  version: 2.0.2
 ---
 
 # OAT Doctor
@@ -81,15 +81,15 @@ Run the seven commands below and the four file checks. Every command call is pro
 
 A command has **failed** only when its stdout does not parse as JSON, or the process is killed or times out. A non-zero exit with parseable JSON is a findings result: `oat doctor` and `oat pjm doctor` both exit 1 whenever any check warns, which is the normal state of a healthy repository. A failed command becomes one `warning` finding for its area whose summary names the command and quotes the first line of stderr; the sweep continues.
 
-| #   | Command                                 | Projection                                                                               | Feeds                                        |
-| --- | --------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------- |
-| 1   | `oat doctor --json --scope all`         | `.checks[] \| {name, status, message}` — drop `packEvidence` and `providerRefreshAdvice` | config, tools, docs (by the check map below) |
-| 2   | `oat pjm doctor --json`                 | `.adoption` and `.checks[] \| {name, status, message}`                                   | PJM                                          |
-| 3   | `oat config dump --json`                | `.shared`, `.local`, `.user` (the three surface objects)                                 | config, docs                                 |
-| 4   | `oat config describe --json`            | `.entries[] \| {key, group, file, scope, defaultValue, owningCommand, deprecated}`       | config                                       |
-| 5   | `oat instructions validate --json`      | `.summary` and `.entries[] \| select(.status != "ok") \| {agentsPath, status, detail}`   | agent instructions                           |
-| 6   | `oat tools list --json --scope all`     | `.tools[] \| {name, pack, scope, status}`                                                | tools                                        |
-| 7   | `oat tools outdated --json --scope all` | `.tools[] \| {name, version, bundledVersion, scope}`                                     | tools                                        |
+| #   | Command                                 | Projection                                                                                                                                                                                               | Feeds                                        |
+| --- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| 1   | `oat doctor --json --scope all`         | `.checks[] \| {name, status, message}` — drop `packEvidence` and `providerRefreshAdvice`                                                                                                                 | config, tools, docs (by the check map below) |
+| 2   | `oat pjm doctor --json`                 | `.adoption` and `.checks[] \| {name, status, message}`                                                                                                                                                   | PJM                                          |
+| 3   | `oat config dump --json`                | `.shared`, `.local`, `.user` (the three surface objects)                                                                                                                                                 | config, docs                                 |
+| 4   | `oat config describe --json`            | `.entries[] \| {key, group, file, scope, defaultValue, owningCommand, deprecated}`                                                                                                                       | config                                       |
+| 5   | `oat instructions validate --json`      | `.strategy`, `.summary`, `.entries[] \| select(.status != "ok") \| {agentsPath, status, detail}`, and `.warnings[] \| {code, path, paths, wouldRemove, linkedBy, message}` (omitted when there are none) | agent instructions                           |
+| 6   | `oat tools list --json --scope all`     | `.tools[] \| {name, pack, scope, status}`                                                                                                                                                                | tools                                        |
+| 7   | `oat tools outdated --json --scope all` | `.tools[] \| {name, version, bundledVersion, scope}`                                                                                                                                                     | tools                                        |
 
 File checks (read-only):
 
@@ -123,9 +123,13 @@ Each finding is one line with an **area**, a **severity**, a one-line **summary*
 
 **Agent instructions**
 
-- An entry with status `missing` or `content_mismatch` (the entry literal; the summary counter is spelled `contentMismatch`) → `error`; fix `oat instructions sync` (`--force` for a content mismatch the person confirms is stale).
+- An entry with status `content_mismatch` (the entry literal; the summary counter is spelled `contentMismatch`) → `error`; fix `oat instructions sync` (`--force` for a content mismatch the person confirms is stale).
+- An entry with status `missing` → `error` only when a shim strategy is configured (`.strategy` is `pointer`, `symlink`, or `copy`); fix `oat instructions sync`. Under `none`, the default, an AGENTS.md without a CLAUDE.md is correct and the CLI never reports it as `missing`.
+- An entry with status `managed_shim` (strategy `none` only: a CLAUDE.md in the exact shape OAT writes) → `warning`; fix `oat instructions sync`, which removes it, unless `.warnings[]` holds a `claude_md_blocks_shim_removal` item: then sync removes nothing, so report that item instead of sending the person to sync. An entry with status `unmanaged` (a hand-written or modified CLAUDE.md that sync keeps, or one an AGENTS.md links to) is not a finding of its own; the leftover warning below covers it, including the link caveat through `linkedBy`.
+- Each `.warnings[]` item with code `claude_md_hides_agents_md` → `warning`; the summary names its `path`: while that `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists, Claude Code's default `agents-md` mode ignores every AGENTS.md in the project (for a file below the root: in sessions started in its directory or below). Offer exactly the two fixes the CLI names: the person removes the file (the doctor never deletes it), or `oat config set instructions.claude.shims pointer` (or `symlink` / `copy`) followed by `oat instructions sync` to add shims back. When the item's `linkedBy` is non-empty, the file holds the only copy of the instructions for those AGENTS.md links: the first fix becomes "the person replaces each linking AGENTS.md with the file's content first, then removes the file", naming the `linkedBy` paths, and never offer plain removal for it. Skip an item whose `path` is in a `claude_md_blocks_shim_removal` item's `wouldRemove`: that item already names the file, and removing one kept file by hand recreates the mix the block exists to prevent.
+- A `.warnings[]` item with code `claude_md_blocks_shim_removal` → `warning`: removal under `none` is all or nothing, so while any file in its `paths` (a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` with content that is not an OAT shim) exists, `oat instructions sync` removes none of the shims in its `wouldRemove`. The summary names both lists. Offer the fixes the CLI names: the person removes each file in `paths` or moves its content into an AGENTS.md, then reruns `oat instructions sync`; or `oat config set instructions.claude.shims` to `pointer`, `symlink`, or `copy` to keep CLAUDE.md files. Its `linkedBy` maps each file in `paths` to the AGENTS.md links that reach it: for a file with a non-empty list, the first fix becomes "the person replaces each linking AGENTS.md with the file's content first, then removes the file", naming those links, and never offer plain removal for it. While this item exists, offer no removal for any path in its `wouldRemove`. The doctor never deletes or edits the files.
 - An entry with status `stray` → `warning`; fix `oat instructions sync` after the person decides whether the stray file should exist.
-- A CLI-written heading absent while its capability is present → `warning`: no `## Tool Packs` while any pack is installed at project scope (fix `oat tools install <pack> --project-guidance`); no `### Project Management` or `### Decision Records` while PJM adoption is `declared` (fix `oat pjm init`, which rewrites the guidance); no `## Documentation` while a docs surface exists (fix: `oat-docs-bootstrap`).
+- A CLI-written heading absent while its capability is present → `warning`: no `## Tool Packs` while any pack is installed at project scope (fix `oat tools guidance`, which prints the managed `OAT tools` block for the installed packs without installing, upgrading, or writing anything, for the person to add to `AGENTS.md`); no `### Project Management` or `### Decision Records` while PJM adoption is `declared` (fix `oat pjm init`, which appends the absent guidance blocks; a block that exists but differs gets a printed manual patch); no `## Documentation` while a docs surface exists (fix: `oat-docs-bootstrap`).
 - Content quality beyond presence is not judged here; route to `oat-agent-instructions-analyze`.
 
 **Docs**
@@ -221,7 +225,7 @@ State the adoption state (`declared`, `inferred-legacy`, `partial-initialization
 
 #### Agent instructions dive
 
-Explain the sync strategy in use (`oat instructions validate --json` `.summary`) and each non-`ok` entry with its path. Explain each missing heading: what the CLI writes there and why an agent needs it (`cli-utilities/bootstrap.md` for `## Tool Packs`; `cli-utilities/backlog-lifecycle.md` § Adoption comes first for the PJM sections). Offer `oat instructions sync`, `oat tools install <pack> --project-guidance`, or `oat pjm init` as the finding names; for wording and coverage beyond presence, hand off to `oat-agent-instructions-analyze` then `oat-agent-instructions-apply`.
+Explain the sync strategy in use (`oat instructions validate --json` `.strategy`: `none`, the default, keeps no CLAUDE.md because Claude Code reads AGENTS.md itself; `pointer`, `symlink`, and `copy` keep a shim beside each AGENTS.md) and each non-`ok` entry and leftover-CLAUDE.md warning with its path. Explain each missing heading: what the CLI writes there and why an agent needs it (`cli-utilities/bootstrap.md` for `## Tool Packs`; `cli-utilities/backlog-lifecycle.md` § Adoption comes first for the PJM sections). Offer `oat instructions sync`, `oat tools guidance` (read-only: prints the `OAT tools` block to add), or `oat pjm init` (appends absent PJM blocks) as the finding names; for wording and coverage beyond presence, hand off to `oat-agent-instructions-analyze` then `oat-agent-instructions-apply`.
 
 #### Docs dive
 

package/assets/skills/oat-project-implement/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(oat project log:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 2.3.13
+  version: 2.3.14
 ---
 
 # Implementation Phase
@@ -102,7 +102,7 @@ record only the gate decision and its review/dispatch provenance.
 After every code commit and after every phase/review-fix completion, you MUST commit the OAT tracking files (project: `implementation.md`, `state.md`, `plan.md`) as a separate bookkeeping commit. Refresh the repo dashboard with `oat state refresh` before staging when available, but do not stage `.oat/state.md`; it is generated dashboard state and is normally gitignored. Do not defer, batch, or skip these commits under the reasoning that they "aren't related to the implementation." Skipping a bookkeeping commit is the primary cause of cross-session state drift and will cause the next implementation run to fail bookkeeping cross-checks. If bookkeeping commits feel frequent, that is the intended design — they are cheap and they prevent drift.
 
 **CRITICAL — Review boundaries require a committed artifact baseline.**
-Do not enter checkpoint review, final review, revise, or PR-final handoff with dirty core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`). If one of those boundaries is next and artifact bookkeeping is still uncommitted, stop and create the bookkeeping commit first.
+Do not enter checkpoint review, final review, revise, or PR-final handoff with dirty core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`). If one of those boundaries is next and artifact bookkeeping is still uncommitted, stop and create the bookkeeping commit first. The per-phase review is such a boundary: commit the phase's task ledger (`references/phase-execution.md` Step 7a) before dispatching the per-phase reviewer, and write review-outcome bookkeeping after the review returns (Step 7b).
 
 **CRITICAL — Intentional artifact divergence must be recorded.**
 If implementation intentionally diverges from `spec.md`, `design.md`, or `plan.md`, record the delta in `implementation.md` before the next phase/review boundary. Include what diverged, why it diverged, whether the implementation or original artifact is now source of truth, and any follow-up artifact updates or explicit deferral. Do not leave accepted design drift only in chat, a review artifact, or code comments; final summary generation depends on `implementation.md` preserving the delta.

package/assets/skills/oat-project-implement/references/completion-and-closeout.md

@@ -384,13 +384,13 @@ and can never be reused as a fresh `allowed` result once the gate is
 re-enabled; the re-enabled gate requires a new configured generation.
 
 New generations persist `implementation_fingerprint` as
-`sha256:effective-delta-v1:<digest>`. Resolve the logical integration base from
+`sha256:effective-delta-v2:<digest>`. Resolve the logical integration base from
 the tracked PR's exact base ref, then the repository's configured remote default
 branch; missing or ambiguous resolution fails closed. Persist the logical base
 ref as `implementation_base_ref`; require exactly one merge base between that
 ref and each compared HEAD.
 
-Prefix the fingerprint input with the bytes `effective-delta-v1\0`. Hash the
+Prefix the fingerprint input with the bytes `effective-delta-v2\0`. Hash the
 exact NUL-delimited byte stream from Git
 `--raw -z --no-renames --no-abbrev` output, which includes both base and final
 modes and full object IDs for blobs, symlinks, deletions, and gitlinks. Run with
@@ -398,13 +398,29 @@ modes and full object IDs for blobs, symlinks, deletions, and gitlinks. Run with
 format owns path framing and byte ordering; do not parse and reserialize it,
 abbreviate object IDs, enable rename detection, or hash human patch output.
 
-Exclude only the exact `$PROJECT_PATH/state.md` checkpoint carrier to avoid a
-self-referential digest. Use Git's literal exclusion pathspec, not a glob.
-Validate that file independently as the structured transition above. Every
-other path remains fingerprinted. Set `freshness_head` to `reviewed_head` and
-`freshness_fingerprint` to `implementation_fingerprint` when the generation
-starts. These rolling fields preserve the accepted tree outcome after later
-authorized closeout transitions without changing the immutable reviewed basis.
+Exclude the exact `$PROJECT_PATH/state.md` checkpoint carrier, which would make
+the digest self-referential, and every path under `.oat/projects/` and
+`.oat/repo/`, whose project artifacts and repository records never make the
+gate stale. Use Git's literal exclusion pathspecs
+`:(exclude,literal)$PROJECT_PATH/state.md`, `:(exclude,literal).oat/projects`,
+and `:(exclude,literal).oat/repo`, not globs. A literal directory pathspec
+excludes that directory and everything beneath it, never a sibling whose name
+merely starts the same way. `.oat/templates/`, `.oat/scripts/`,
+`.oat/config*.json`, and `.oat/sync/` stay fingerprinted, as does every other
+path. The `.oat/projects` exclusion names the default location literally; a
+project whose configured `projects.root` lies outside `.oat/projects/` keeps
+its other artifacts fingerprinted (more staleness, never less). Validate the
+state carrier independently as the structured transition above.
+
+Stored `sha256:effective-delta-v1:<digest>` values keep v1 semantics and are
+never reinterpreted: recompute them with the `effective-delta-v1\0` prefix and
+only the exact `$PROJECT_PATH/state.md` exclusion. A v1 generation stays v1
+until it goes stale; its replacement generation uses v2.
+
+Set `freshness_head` to `reviewed_head` and `freshness_fingerprint` to
+`implementation_fingerprint` when the generation starts. These rolling fields
+preserve the accepted tree outcome after later authorized closeout transitions
+without changing the immutable reviewed basis.
 
 An in-flight `pending` or `blocked` generation reuses its persisted resolved
 configuration and never re-resolves it. Recompute the fingerprint from those
@@ -561,9 +577,14 @@ disposition.
   closeout-only. A path category alone is insufficient: the corresponding
   persisted gate or sequence transition must own that descendant boundary;
   unknown or mixed work is substantive.
-- For a qualified `sha256:effective-delta-v1:<digest>` value, require the
+- For a qualified `sha256:effective-delta-v2:<digest>` or
+  `sha256:effective-delta-v1:<digest>` value, require the
   persisted `implementation_base_ref`, `freshness_head`, one current merge base,
   and 64-character lowercase hexadecimal implementation and freshness digests.
+  Recompute with the stored value's own version prefix and exclusion set.
+  Under v2, a descendant commit whose changes all fall inside the v2 exclusion
+  set leaves the effective delta unchanged; it is neither substantive nor
+  unknown and needs no owning transition.
   Missing or malformed inputs fail closed. Walk descendants after
   `freshness_head` in commit order. Ignore a checkpoint-persistence commit only
   after verifying its diff changes the exact state carrier and nothing else.
@@ -587,7 +608,8 @@ disposition.
   or workflow configuration changes make the prior result `stale`.
 - Every stale transition preserves prior provenance for audit, requires a
   current final lifecycle review for the changed basis, and starts a new
-  generation using the qualified fingerprint format.
+  generation using the current qualified fingerprint format,
+  `effective-delta-v2`.
 
 Before approval-aware sequencing, final HiLL approval, implementation
 completion, or success output, run the configured gate:

package/assets/skills/oat-project-implement/references/phase-execution.md

@@ -684,8 +684,11 @@ degradation is forbidden for the invalid run.
 ### Per-Phase Review
 
 The root workflow owns implementation review. After validating the phase
-report, resolve and dispatch exactly one fresh `oat-reviewer` round at the
-configured review ceiling:
+report (sequential phases; see the parallel-group note below), commit Step 7a
+pre-review bookkeeping before resolving or dispatching the reviewer, so the
+reviewed head carries the phase's current task ledger. Then resolve and
+dispatch exactly one fresh `oat-reviewer` round at the configured review
+ceiling:
 
 ```bash
 oat project dispatch-ceiling resolve \
@@ -703,6 +706,17 @@ commit range, task IDs and boundaries, artifacts, verification evidence,
 configured axes, selection reason, and candidates. Require a timestamped review
 artifact under the project's `reviews/` directory.
 
+The Review Scope names review-outcome bookkeeping as out of scope: this
+review's `## Reviews` row and its disposition, the Orchestration Run entry for
+this review's outcome, the deferred phase-outcome and review-orchestration
+project-log entries, and the ledger's record of any review-fix commit. Step 7b
+writes all of them after the review returns, so their absence at the reviewed
+head is not a finding. The task ledger itself stays in scope and must be
+current at the reviewed head, because Step 7a committed it before dispatch.
+In a parallel group the phase worktree under review does not carry the root
+ledger (step 10 of Parallel Group Execution commits it once after fan-in), so
+that phase's Review Scope also names the task ledger as out of scope.
+
 For a managed capped review, bind the exact provider argument to the actual
 invocation: `providers.codex.dispatchArgs.variant`,
 `providers.claude.dispatchArgs.variant` for an effort-pinned target,
@@ -755,7 +769,9 @@ and workers never write `project-log.md` or append this entry.
 
 No project-log write happens anywhere between a reviewer returning and a fix
 child being dispatched. The deferred orchestration entry is appended with the
-phase-outcome entry at Step 7 and committed by that step's bookkeeping.
+phase-outcome entry at Step 7b and committed by that half's bookkeeping. Step
+7a's commit lands before the reviewer is dispatched, so it cannot dirty that
+window either.
 
 After successful signal and orchestration validation, validate the review
 artifact scope and commit range.
@@ -796,8 +812,10 @@ worktree in Outstanding Items.
 
 ### Optional External Phase Review Gate
 
-After the root-owned per-phase reviewer passes and phase bookkeeping is clean,
-run `oat_phase_review_gate` for selected phases:
+After the root-owned per-phase reviewer passes and both halves of Step 7
+bookkeeping are committed, run `oat_phase_review_gate` for selected phases. The
+gate reviews the committed ledger after both Step 7 halves — which, after a fix
+loop or in a parallel group, is newer than the head the per-phase reviewer saw:
 
 ```bash
 oat --json gate review \
@@ -817,6 +835,11 @@ and `handoff` is non-null.
   implementer under the bounded loop, then re-run root review and the gate.
 - target execution, artifact validation, or missing-artifact failure: stop.
 
+The phase row stays `in_progress` until this gate passes and every review
+disposition is settled; the bookkeeping that records the passing gate sets it
+`complete`, and gate retry exhaustion sets it `blocked` (see Step 7b's phase
+row transitions).
+
 Gate retry rounds use the same orchestration retry limit. Gate independence,
 configured provenance, liveness telemetry, and fail-closed behavior are
 unchanged.
@@ -879,7 +902,65 @@ target-preserving execution and must be recorded.
 
 ### Step 7: Artifact Updates After Each Phase (or Group)
 
-After each phase or parallel group:
+After each phase or parallel group, Step 7 runs in two halves around the
+per-phase review, each with its own commit.
+The split exists so the reviewer never evaluates a head whose task ledger is
+stale by construction, while the tree stays clean for a bounded fix child.
+
+#### Step 7a: Pre-Review Bookkeeping
+
+Run after the phase report validates and before Per-Phase Review dispatches the
+reviewer. Write the phase's task ledger:
+
+- the `implementation.md` task and phase completion rows: each planned task's
+  status and commit; keep the phase row `in_progress` (tasks complete, review
+  pending), because the phase's terminal status depends on its review;
+- the `state.md` resume pointer (`oat_current_task`, last commit, and
+  timestamp), advanced consistently with `implementation.md` so the two
+  resume pointers never disagree;
+- when the phase report carried a recovery attempt, after the matching
+  handoff-matrix row validates, clear the terminal `pending_attempt` marker,
+  preserve `used_attempts`, and append the validated canonical recovery event
+  to `implementation.md`;
+- remove legacy `oat_execution_mode: subagent-driven`; and
+- preserve any configured retry override.
+
+The task rows, resume pointer, and recovery settlement do not depend on the
+review outcome, which is why they can move ahead of the review; the recovery
+settlement is validated from the phase report, not from the review. A
+terminal-stop branch that ends without a review (`failed-attempt`,
+`direction-required`, or `BLOCKED`) records its event and marker disposition
+through the Step 7a commit block and then stops; it has no Step 7b. Commit it
+through the same scope-resolving branch as Step 7b, including the synced-scope
+`oat project push` path. Why this keeps the fix-child
+preflight clean: the pre-review writes are committed before the reviewer is
+dispatched, so the tree is clean when a bounded fix child is dispatched after
+the review. The Optional External Phase Review Gate later sees this committed
+ledger plus Step 7b's writes.
+
+Pre-review bookkeeping is mandatory:
+
+```bash
+oat state refresh
+PROJECT_SCOPE=$(oat project scope "{PROJECT_PATH}" --format value) || { echo "oat: cannot resolve project scope for {PROJECT_PATH}; refusing to commit artifacts" >&2; exit 1; }
+# fail closed: never fall back to branch bookkeeping when scope resolution fails
+if [ "$PROJECT_SCOPE" = "synced" ]; then
+  oat project push "{PROJECT_PATH}" --message "chore(oat): record {pNN} task ledger before review" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+else
+  git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/plan.md
+  [ -f {PROJECT_PATH}/project-log.md ] && git add {PROJECT_PATH}/project-log.md
+  git commit -m "chore(oat): record {pNN} task ledger before review"
+fi
+```
+
+A parallel group makes this commit once after fan-in, together with Step 7b
+(step 10 of Parallel Group Execution), because its phase worktrees do not carry
+the root ledger.
+
+#### Step 7b: Post-Review Bookkeeping
+
+Run after the phase's terminal review outcome (pass, or retry exhaustion).
+Write the review-outcome bookkeeping that Step 7a leaves out:
 
 - append an Orchestration Run with phase outcomes, task commits, phase/root
   review result, fix iterations, dispatch stamps, selection reasons,
@@ -891,10 +972,30 @@ After each phase or parallel group:
   move an event status backward;
 - apply the Reviews Ledger Mutation Contract above before every disposition or
   archive re-point;
-- update `state.md` current task, last commit, and timestamp;
-- remove legacy `oat_execution_mode: subagent-driven`; and
+- set the phase's `implementation.md` row from the review outcome: `blocked`
+  on retry exhaustion; on a passing review, keep the row nonterminal
+  (`in_progress`) while any review-fix task added by review-receive is open or
+  a selected Optional External Phase Review Gate has not yet passed, and set
+  `complete` only under the rule below; update the phase summary for any
+  review-fix commits;
+- append the deferred phase-outcome and review-orchestration entries through
+  `oat project log append`;
+- update `state.md` last commit and timestamp for any review-fix commit, and
+  its current task when the phase outcome changes it; and
 - preserve any configured retry override.
 
+Phase row transitions: a passing root review (zero Critical and zero High) can
+still queue Medium or Low fix tasks through review-receive, and the selected
+phase gate runs after this step, so neither makes the phase complete by itself.
+An added review-fix task keeps the row `in_progress` and names the queued task;
+the bookkeeping that completes that task re-evaluates the row. A `blocked` gate
+keeps the row `in_progress` through the bounded fix loop; gate retry exhaustion
+sets it `blocked`. Set the row `complete` only when every review disposition is
+settled and every selected phase gate has passed, in whichever bookkeeping
+commit observes that last condition: this Step 7b commit when nothing is
+queued and no gate is selected, otherwise the commit that records the final
+review-fix task or the passing gate.
+
 Bookkeeping is mandatory:
 
 ```bash

package/assets/skills/oat-project-lite/SKILL.md

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.1.5
+  version: 1.1.6
 ---
 
 # Lite Project
@@ -159,6 +159,28 @@ PROJECT_PATH=$(oat config get activeProject)
 Confirm `state.md` reports `oat_workflow_mode: lite`, `oat_phase: plan`, and
 `oat_phase_status: in_progress`. Do not create discovery or design artifacts.
 
+**Consolidating earlier scaffolds.** When this new Lite project absorbs work
+that earlier project scaffolds already started — those directories are being
+retired into this one rather than continued — record what was absorbed in
+`"$PROJECT_PATH/state.md"` frontmatter as one frontmatter write immediately
+after the scaffold above, before Step 1. `PROJECT_PATH` here is the value
+re-resolved after `oat project new`, never the pre-scaffold value, which still
+names the previously active project. The fields have the same shapes that
+`oat-project-quick-start` records:
+
+- `absorbed_projects: [<slug>]` — the project slug of every retired scaffold,
+  which also names the scaffold directory under the projects root that this
+  project supersedes.
+- `absorbed_backlog_ids: [<BL-id>]` — every backlog ID those scaffolds carried
+  into this project.
+
+Record both fields only when a consolidation actually happened; an absent field
+and an empty list are equivalent. A resumed Lite project keeps whatever it
+already recorded. These two fields are the only inputs the absorbed-project
+retirement sweep reads at completion, where retiring a scaffold is treated as a
+semantic claim about the planning surfaces rather than the physical removal of
+a directory. The write travels with this project's next `state.md` commit.
+
 ### Step 1: Read Repository Knowledge
 
 Read repository instructions and the minimum durable context needed for the

package/assets/skills/oat-project-next/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash(git:*), Bash(oat:*), Skill
 metadata:
-  version: 1.1.2
+  version: 1.1.3
 ---
 
 # Project Next
@@ -253,8 +253,8 @@ Otherwise, look up the target skill from the routing table for the current `oat_
 | Current Phase | Phase Status | Boundary Tier | Quick Plan Readiness | Target Skill               |
 | ------------- | ------------ | ------------- | -------------------- | -------------------------- |
 | discovery     | in_progress  | tier 3        | —                    | `oat-project-discover`     |
-| discovery     | in_progress  | tier 2        | —                    | `oat-project-plan`         |
-| discovery     | complete     | tier 1        | —                    | `oat-project-plan`         |
+| discovery     | in_progress  | tier 2        | —                    | `oat-project-quick-start`  |
+| discovery     | complete     | tier 1        | —                    | `oat-project-quick-start`  |
 | plan          | in_progress  | tier 3        | not ready            | `oat-project-quick-start`  |
 | plan          | in_progress  | tier 2        | not ready            | `oat-project-quick-start`  |
 | plan          | in_progress  | tier 1        | not ready            | `oat-project-quick-start`  |