@open-agent-toolkit/cli 0.3.37 → 0.3.39

package/README.md

@@ -20,8 +20,8 @@ npx @open-agent-toolkit/cli --help
 
 ```bash
 oat init --scope project
-oat status --scope all
-oat sync --scope all
+oat status --scope project
+oat sync --scope project
 oat config describe
 ```
 

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.37"
+  "oatVersion": "0.3.39"
 }

package/assets/docs/getting-started/bootstrap.md

@@ -73,9 +73,8 @@ on your `PATH`. OAT adds its lines between `# >>> oat pre-commit hook >>>` and
 
 To remove the hook, run `oat init --scope project --no-hook` in the
 repository. (Without `--scope project`, `oat init` uses scope `all` and also
-writes under your home directory.) Although its
-help text reads "Skip optional pre-commit hook install", the flag also removes
-an OAT hook that is already installed. It deletes only the marked OAT block
+writes under your home directory.) As its help text says, `--no-hook` removes
+an installed optional pre-commit hook and skips installing one. It deletes only the marked OAT block
 and keeps any other hook content; if the file contained nothing but the OAT
 block, the file is deleted (or emptied, when it is a symlink). You can also
 delete the lines between the two markers by hand. To install the hook later
@@ -99,8 +98,7 @@ oat init --scope project
 
 ### Where tool packs install
 
-Guided setup uses the same per-pack defaults as `oat tools install`, with one
-difference described at the end of this section. The `--scope` option of `oat tools install` and `oat tools remove` lists `all` as
+Guided setup uses the same per-pack defaults as `oat tools install`. The `--scope` option of `oat tools install` and `oat tools remove` lists `all` as
 its default in `--help`. For `oat tools install`, that default does not mean
 both scopes:
 
@@ -114,21 +112,22 @@ both scopes:
 The `core` pack can only live under your home directory:
 
 - `oat tools install --scope project`, with no pack name, installs the other
-  seven packs in this repository and still installs `core` under your home
-  directory.
-- `oat tools install core --scope project` exits successfully and prints
-  `Installed core tool pack.`, but it writes nothing, neither in the
-  repository nor in your home directory.
+  seven packs in this repository, skips `core`, and reports that core is
+  user-scope only.
+- `oat tools install core --scope project` exits 1 with a message that core is
+  user-scope only and writes nothing.
 - `oat tools remove --all --scope project` fails with
   `Pack core does not allow project scope`, and so does
   `oat tools remove --all` with no `--scope`.
 
-The difference: guided setup does not take its pack scope from `--scope`.
-`oat init --scope project --setup`, run without an interactive terminal,
-installed all eight packs under the home directory. In an interactive
-terminal, answer **Yes** to the per-pack scope question to choose project
-scope, or install packs afterwards with `oat tools install <pack> --scope project`. See [Where packs install](tool-packs.md#where-packs-install) for
-the full rules and how to remove packs.
+Guided setup takes its pack scope from an explicit `--scope`:
+`oat init --scope project --setup` installs the selected packs in this
+repository, skips `core`, and writes nothing under your home directory, and
+`--scope user --setup` installs them at user scope only. Without an
+explicit scope, guided setup keeps the per-pack defaults above. Guided setup
+detects the default branch from `origin/HEAD`, then `main`, and does not run
+`gh`. See [Where packs install](tool-packs.md#where-packs-install) for the full
+rules and how to remove packs.
 
 Related commands:
 

package/assets/docs/getting-started/tool-packs.md

@@ -12,7 +12,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 > - A tool pack is a bundle of OAT skills (instructions your coding agent follows), agents, templates and scripts that installs as one unit.
 > - There are eight packs: `core` (setup diagnostics and a local copy of these docs), `workflows` (tracked projects), `docs` (documentation upkeep), `utility` (reviews and maintenance helpers), `research` (evidence gathering and comparison), `ideas` and `brainstorm` (exploring ideas), and `project-management` (backlog and decisions kept in the repository).
 > - Install one pack with an explicit scope: `oat tools install research --scope project` puts it in this repository, and `oat tools install research --scope user` puts it in your home directory. Leave out the pack name, as in `oat tools install --scope project`, to install every pack; in an interactive terminal it first asks which packs to include.
-> - The `core` pack only ever installs under your home directory, whatever `--scope` you pass. [Where packs install](#where-packs-install) shows what that means for each command.
+> - The `core` pack only ever installs under your home directory; `--scope project` refuses or skips it. [Where packs install](#where-packs-install) shows what that means for each command.
 > - Installing the `project-management` pack is not the same as adopting project management: the repository's planning files are created only when someone runs `oat pjm init`.
 > - Read next: [Choosing packs and their ownership](#choosing-packs-and-their-ownership), [Install vs. initialize](#install-vs-initialize), [Upgrading from an earlier CLI](#upgrading-from-an-earlier-cli), and [What OAT Writes](../reference/what-oat-writes.md) for every file each command creates.
 
@@ -54,18 +54,19 @@ mean both scopes:
   packs asks where each one should go and suggests the same answer.
 - With `--scope project`, the pack is installed in this repository
   (`.agents/` and `.oat/`). With `--scope user`, it is installed under your
-  home directory.
+  home directory. An explicit `--scope project` or `--scope user` writes only
+  that scope, with or without a pack name: a copy the pack already has at the
+  other scope is left as it is, and the summary names only the scope written.
 - With `--scope all` given explicitly for one pack, as in
   `oat tools install docs --scope all`, that pack is installed at both scopes.
 
 The `core` pack can only live under your home directory:
 
 - `oat tools install --scope project`, with no pack name, installs the other
-  seven packs in this repository and still installs `core` under your home
-  directory.
-- `oat tools install core --scope project` exits successfully and prints
-  `Installed core tool pack.`, but it writes nothing, neither in the
-  repository nor in your home directory. Run `oat tools install core` (or add
+  seven packs in this repository, skips `core`, and reports that core is
+  user-scope only; nothing is written under your home directory.
+- `oat tools install core --scope project` exits 1 with a message that core is
+  user-scope only and writes nothing. Run `oat tools install core` (or add
   `--scope user`) to install it.
 - `oat tools remove --all --scope project` fails with
   `Pack core does not allow project scope`, and so does
@@ -773,7 +774,8 @@ Key behavior:
 - Installing is **additive**: choosing a scope for a pack never removes it from another scope. A pack installed at user scope plus a project install ends up at `project + user`, not moved
 - For every pack that allows both scopes (`ideas`, `docs`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`), the interactive flow offers a per-pack end-state selector (`project`, `user`, or `both`) defaulting to the pack's current placement; leaving the default makes no changes for that pack
 - Fresh installs default to **user scope** for every pack; existing installs keep their current placement. The `--scope` default shown in `--help` is `all`, but with no `--scope` a pack that is not installed yet goes under your home directory; see [Where packs install](#where-packs-install)
-- `oat init --setup` uses this same additive scope resolver. In guided setup, choosing to customize scope reaches the per-pack selector; choosing the recommended defaults, or running non-interactively, applies additive per-pack defaults without removals
+- `oat init --setup` uses this same additive scope resolver. In guided setup, choosing to customize scope reaches the per-pack selector; choosing the recommended defaults, or running non-interactively, applies additive per-pack defaults without removals. An explicit `oat init --scope project --setup` or `--scope user --setup` installs the selected packs at that scope only (core is skipped under `--scope project`), and guided setup never runs `gh`: it detects the default branch from `origin/HEAD`, then `main`
+- An explicit `--scope project` or `--scope user` writes only that scope, for one pack or all of them; existing placements at the other scope are neither reconciled nor removed. With no `--scope` or with `--scope all`, the rules above apply
 - Every pack's fresh-install default is user scope (`defaultScope` in the release manifest); existing installs keep their current placement on re-install, so a re-install never moves a pack between scopes or creates a second copy at the other one. This applies to the per-pack subcommands too: a bare `oat tools install docs` in a repository where `docs` is already at project scope stays at project scope, and only an explicit `--scope` overrides that
 - Removing a pack from a scope happens only when you explicitly choose a narrower end-state in the interactive flow (e.g. a pack at `both` set to `project` only). All staged removals are shown in a single change summary and applied only after one batch confirmation — declining makes no changes
 - Non-interactive installs (including `--scope project`, `--scope user`, and the default pack set) are strictly additive and never remove a pack from a scope. Removal is interactive-only
@@ -963,7 +965,7 @@ The `core` pack contains foundational diagnostic and documentation skills:
 
 Key behavior:
 
-- Core pack always installs at **user scope** (`~/.agents/skills/`). It is the only pack whose sole allowed scope is `user`. A conflicting explicit `--scope project` is not rejected: `oat tools install core --scope project` (and the legacy `oat init tools core --scope project`) exits successfully and prints `Installed core tool pack.` but writes nothing, while `oat tools install --scope project` with no pack name still installs core under your home directory. To install core, omit `--scope` or pass `--scope user`. Keeping core in your home directory makes its skills available in any directory. See [Where packs install](#where-packs-install).
+- Core pack always installs at **user scope** (`~/.agents/skills/`). It is the only pack whose sole allowed scope is `user`. A conflicting explicit `--scope project` is refused: `oat tools install core --scope project` (and the legacy `oat init tools core --scope project`) exits 1 with a message that core is user-scope only and writes nothing, and `oat tools install --scope project` with no pack name skips core and says so. To install core, omit `--scope` or pass `--scope user`. Keeping core in your home directory makes its skills available in any directory. See [Where packs install](#where-packs-install).
 - `~/.oat/docs/` is a managed directory asset: its completeness and drift are compared as a whole tree, so a partially deleted docs tree is reported as a partial `core` install rather than passing silently.
 - Core is checked by default in the `oat init tools` guided setup.
 - Installation also bundles OAT documentation to `~/.oat/docs/` for the oat-docs skill.
@@ -1277,11 +1279,10 @@ created until someone runs `oat pjm init` (see [Install vs. initialize](#install
 A fresh install goes to user scope, which lets you reuse packs across
 repositories without update churn in each one; a pack that is already installed
 keeps its scope. **`core` is user-only**: `oat tools install --scope project`
-with no pack name still installs it in your home directory, and
-`oat tools install core --scope project` reports success but installs nothing
-(see [Where packs install](#where-packs-install)). `oat init --scope project --setup` does not choose
-project scope for packs; customize each pack's scope at the prompt, or install
-packs explicitly. Installing a pack at a second scope adds a second copy rather
+with no pack name skips it, and `oat tools install core --scope project` exits
+1 without installing anything (see [Where packs install](#where-packs-install)).
+`oat init --scope project --setup` installs the packs you select at project
+scope. Installing a pack at a second scope adds a second copy rather
 than moving it, so use `oat tools migrate` to move a pack between scopes.
 Templates that a project-scope install writes belong to the repository after
 that: later pack updates and `oat tools remove` leave them alone.

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

@@ -206,11 +206,12 @@ Key behavior:
   project role file; `--scope user` writes only under `~/.codex`
 - `--agent-path` selects a specific canonical agent and `--role-name` overrides
   the generated role name
-- Managed role registration enables multi-agent support and merges an
-  `agents.max_depth` floor of `2`
-- Project writes preserve a higher existing project depth or inherited user
-  depth without mutating user configuration; user writes do not inspect or
-  mutate project configuration
+- Managed role registration adds `[features] multi_agent = true` and
+  `agents.max_depth = 2` only when those keys are absent; an explicit value is
+  kept, and each `Config:` line names a key added or a conflict
+- A project write that adds `max_depth` uses a higher inherited user depth
+  when there is one, without mutating user configuration; user writes do not
+  inspect or mutate project configuration
 - Existing unrelated Codex configuration and custom roles are preserved
 
 ## Notes

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -54,32 +54,39 @@ Diagram: canonical assets produce provider views and a manifest; status reports
 - **What re-running `oat sync` does.** It writes unless you pass `--dry-run`.
   It recreates missing views and rewrites drifted ones from canonical, so an
   edit made in a provider copy is lost, not merged. A file you placed at a
-  view's path without OAT is replaced too. When a skill or rule is deleted
-  from `.agents/`, sync removes its views. When an agent is deleted or
-  renamed, it does not; see the warning below.
+  view's path without OAT is replaced too. When a skill, rule or agent is
+  deleted from `.agents/`, sync removes its views; see the note below for
+  agents.
 - **What to do with a stray.** In an interactive `oat status` or `oat init` you
   can adopt it, which moves or converts it into `.agents/`. For a Cursor or
   Copilot skill you can keep it in place; OAT records the path under
   `knownStrays` in `.oat/sync/config.json` and leaves it out of later reports.
   You can also list a path there by hand.
 
-> [!WARNING]
-> Sync does not clean up after a deleted or renamed agent. With Cursor enabled,
-> once `.agents/agents/<name>.md` is gone, `oat sync`, `oat sync --dry-run` and
-> `oat status` exit 1 with
-> `Cursor agent definition is a symbolic link at .cursor/agents/<name>.md whose target escapes the sync scope.`
-> With Codex enabled, the agent's generated files stay behind. After deleting
-> or renaming an agent, clean up by hand:
+> [!NOTE]
+> From 0.3.39, sync cleans up after a deleted or renamed agent. Once
+> `.agents/agents/<name>.md` is gone, `oat status` reports the pending change,
+> `oat sync --dry-run` lists the removals and writes nothing, and
+> `oat sync --scope project` removes the agent's `.claude/agents/`,
+> `.cursor/agents/` and `.github/agents/` views, its
+> `.codex/agents/<name>.toml` with any generated model variants, and its
+> `[agents.<name>]` tables in `.codex/config.toml`. A rename also creates the
+> new name's views. User-authored `[agents.*]` tables stay. A dangling link
+> left in `.cursor/agents/`, `.claude/agents/` or `.codex/agents/` no longer
+> stops sync with an `escapes the sync scope` error. At an agent view path,
+> such as `.cursor/agents/<name>.md`, sync restores the managed link. Sync
+> cannot write a generated file through a dangling link: at the path of a
+> generated Cursor model variant, such as
+> `.cursor/agents/oat-reviewer-<model>-<effort>.md`, it reports a failed
+> materialization, and at a Codex role path, such as
+> `.codex/agents/<name>.toml` or one of its model variants, it reports the
+> role as `missing`. Either way sync exits 1; delete the link and rerun sync.
+> A link whose existing target lies outside the sync scope is still refused.
 >
-> 1. Delete the link `.cursor/agents/<name>.md`.
-> 2. Delete the link `.claude/agents/<name>.md`; until it is gone, the same
->    error names that path instead.
-> 3. Delete `.codex/agents/<name>.toml`.
-> 4. In `.codex/config.toml`, delete the `[agents.<name>]` table.
-> 5. Run `oat sync --scope project`; it should now succeed.
->
-> Skills and rules are not affected: sync removes their views when the
-> canonical file is deleted.
+> Codex roles written by versions before 0.3.39 carry no owner header until
+> the next sync rewrites them. If such an agent was deleted before you first
+> synced with 0.3.39, delete its `.codex/agents/<name>.toml` and its
+> `[agents.<name>]` table by hand once.
 
 ## Manifest locations
 

package/assets/docs/provider-sync/pilot-with-a-team.md

@@ -144,23 +144,23 @@ checkouts handle committed links was not tested.
 
 Run `oat sync --scope project`, and commit its output in the same change, when
 you add, rename, or delete a skill, agent, or rule, or change an agent or rule.
-Deleting or renaming an agent also needs the manual cleanup described below.
 Rules, Codex agent files and Cursor's per-model agent variants are generated
 copies, so they only change when sync runs. An edit inside an existing linked
 skill reaches Claude Code at once, because the view is a link.
 
 Make every change in `.agents/`, never in the provider folders. Re-running sync
 overwrites edits made to generated copies, replaces an untracked file sitting
-at a view path, and removes the view of a deleted skill or rule. Editing
-through a link changes the canonical file itself, which is easy to miss in
-review.
-
-Agents are the exception. After you delete or rename an agent, delete its old
-links in `.cursor/agents/` and `.claude/agents/` yourself: with Cursor enabled,
-`oat sync` and `oat status` stop with an error saying the link's target
-`escapes the sync scope` until both links are gone. Also delete its
-`.codex/agents/<name>.toml` file and the `[agents.<name>]` table in
-`.codex/config.toml`, which sync leaves behind.
+at a view path, and removes the views of a deleted skill, rule, or agent.
+Editing through a link changes the canonical file itself, which is easy to miss
+in review.
+
+From 0.3.39, deleting or renaming an agent needs no manual cleanup: sync
+removes its old links in `.cursor/agents/`, `.claude/agents/` and
+`.github/agents/`, its `.codex/agents/<name>.toml` file and its
+`[agents.<name>]` table in `.codex/config.toml`. A Codex role that a version
+before 0.3.39 generated for an agent deleted before the upgrade has no owner
+header, so delete that file and its table by hand once (see
+[Manifest and Drift](manifest-and-drift.md#quick-look)).
 
 Before committing, run `oat status --scope project`. It exits 1 when any view
 is missing or drifted, or when a stray file sits in a provider folder. For a
@@ -177,12 +177,12 @@ inside the working tree. Remove it with `oat init --scope project --no-hook`.
 
 ## Mixed tools
 
-| Provider    | What OAT generates in the repository                                                                                             | What the team should know                                                                                                                                                        |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude Code | A relative link per skill in `.claude/skills/` and per agent in `.claude/agents/`; rules as generated copies in `.claude/rules/` | The only provider with skill views, so a new skill reaches Claude Code only after sync                                                                                           |
-| Cursor      | No skill files: it reads `.agents/skills`. A link per agent in `.cursor/agents/`; rules as `.cursor/rules/*.mdc` files           | Its `.cursor/skills/` folder is not managed; skills found there are reported as strays                                                                                           |
-| Codex       | No skill files: it reads `.agents/skills`. A generated `.codex/agents/<name>.toml` per agent, registered in `.codex/config.toml` | Sync merges into an existing `.codex/config.toml`: it adds OAT's tables, turns on `multi_agent` and raises `max_depth` to at least 2, and keeps your other settings and comments |
-| Gemini      | Nothing; it reads skills and agents from `.agents/` directly                                                                     | Nothing to commit                                                                                                                                                                |
+| Provider    | What OAT generates in the repository                                                                                             | What the team should know                                                                                                                                                                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code | A relative link per skill in `.claude/skills/` and per agent in `.claude/agents/`; rules as generated copies in `.claude/rules/` | The only provider with skill views, so a new skill reaches Claude Code only after sync                                                                                                                                                                     |
+| Cursor      | No skill files: it reads `.agents/skills`. A link per agent in `.cursor/agents/`; rules as `.cursor/rules/*.mdc` files           | Its `.cursor/skills/` folder is not managed; skills found there are reported as strays                                                                                                                                                                     |
+| Codex       | No skill files: it reads `.agents/skills`. A generated `.codex/agents/<name>.toml` per agent, registered in `.codex/config.toml` | Sync merges into an existing `.codex/config.toml`: it adds OAT's tables, adds `multi_agent` and `max_depth` only when they are missing, keeps the values you set (reporting a conflict when OAT needs another), and keeps your other settings and comments |
+| Gemini      | Nothing; it reads skills and agents from `.agents/` directly                                                                     | Nothing to commit                                                                                                                                                                                                                                          |
 
 If OAT's own implementer and reviewer agents are installed in the repository,
 sync also generates one file per supported model for each of them, in

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

@@ -57,13 +57,13 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Agents are native-read from `.agents/agents` for canonical source-of-truth workflows
     - Canonical markdown agents in `.agents/agents/*.md` are exported to Codex runtime roles:
       - `.codex/agents/<role>.toml`
-      - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
-    - Sync and direct materialization edit `config.toml` in place. They change only `features.multi_agent`, `agents.max_depth`, and the `description` and `config_file` keys of managed `[agents.<role>]` tables, and remove stale managed role tables. Comments (including other tools' ownership markers), blank lines, table order, and other keys stay byte for byte, and the file is not rewritten when nothing managed changed. Removing a stale role deletes its whole table, including comments inside it; comments above or after the table stay. Dotted keys and inline tables are edited where they are defined. New keys and tables are never added between another tool's `# BEGIN <label>` and `# END <label>` comments: a key goes before the block, and a table that cannot sit next to its related tables outside the block goes at the end of the file. If `features`, `agents`, or a managed role is not a table, or a key can only be added inside such a block, sync stops with an error instead of rewriting the file.
+      - `.codex/config.toml` (`[features] multi_agent = true` when absent, `[agents.<role>]` upserts)
+    - Sync and direct materialization edit `config.toml` in place. They change only the `description` and `config_file` keys of managed `[agents.<role>]` tables, add `features.multi_agent` and `agents.max_depth` only when those keys are absent, and remove stale managed role tables. An explicit `multi_agent` or `max_depth` value is never rewritten. The output (human and `--json`, including when nothing else changes) names each key added, reports a conflict for `multi_agent` other than `true` or a `max_depth` below `1`, and notes that `max_depth = 1` disables only optional nested work. Comments (including other tools' ownership markers), blank lines, table order, and other keys stay byte for byte, and the file is not rewritten when nothing managed changed. Removing a stale role deletes its whole table, including comments inside it; comments above or after the table stay. Dotted keys and inline tables are edited where they are defined. New keys and tables are never added between another tool's `# BEGIN <label>` and `# END <label>` comments: a key goes before the block, and a table that cannot sit next to its related tables outside the block goes at the end of the file. If `features`, `agents`, or a managed role is not a table, or a key can only be added inside such a block, sync stops with an error instead of rewriting the file.
     - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project|user|all`
     - Project sync writes and maintains the version-controlled supported catalogue: GPT-6.1 Sol and GPT-6 Luna, Sol, and Astra at `low`, `medium`, `high`, `xhigh`, and `max`; GPT-5.6 Luna and Terra through `xhigh`; and GPT-5.6 Sol through `max`. Both `oat-phase-implementer` and `oat-reviewer` receive each supported pair (66 pinned variants). Sync writes files; it does not create a Git commit.
     - Custom targets follow configuration provenance: user-config targets write only under `~/.codex`; shared, repo-local, and active-project targets write under the project's tracked `.codex` view.
     - User sync loads only the bundled canonical `oat-phase-implementer` and `oat-reviewer` definitions needed to expand user-config targets. It does not enable general user-agent mirroring, and it refuses stale user-role cleanup if either managed definition is unavailable.
-    - Generated variants carry `supported-catalogue`, `user-config`, or `project-config` ownership. Cleanup removes stale entries only for the owner being reconciled and preserves other scopes plus unrelated Codex entries.
+    - Generated variants carry `supported-catalogue`, `user-config`, or `project-config` ownership, and from 0.3.39 each canonical agent's base role carries the scope's owner (`project-config` or `user-config`). Cleanup removes stale entries only for the owner being reconciled (`supported-catalogue` and `project-config` at project scope, `user-config` at user scope) and preserves other scopes plus unrelated Codex entries. A deleted or renamed agent's role files, variants, and tables are removed by full sync and by pack removal. Roles an older CLI wrote without an owner header are left in place. A stale `[agents.<role>]` table is removed only while its `config_file` still names the stale OAT-owned role file; a table you re-pointed at another file stays, and only the leftover OAT file is removed. Cleanup never deletes a role file whose real path, after resolving symlinks (including a symlinked `.codex/agents` directory), is outside the sync scope.
     - All project-generated Codex variants and config registrations are repository-owned, version-controlled output and are never auto-ignored by OAT. User-config output remains under `~/.codex`.
     - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a user-config-owned role.
     - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
@@ -71,7 +71,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Codex `max` is a first-class dispatch effort. It is supported for GPT-6.1 Sol, GPT-6 Luna, Sol, and Astra, plus GPT-5.6 Sol, for both implementer and reviewer roles.
     - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
     - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
-    - Default managed Codex execution requires root (depth 0) → phase implementer (depth 1). `agents.max_depth >= 2` enables optional nested phase-agent work; sync and direct materialization still merge that capability floor without lowering a higher target value.
+    - Default managed Codex execution requires root (depth 0) → phase implementer (depth 1). `agents.max_depth >= 2` enables optional nested phase-agent work; when the key is absent, sync and direct materialization add `2` (or a higher inherited value), and they never change an explicit value.
     - Project sync or materialization writes only the project's `.codex/config.toml`; explicit user-scope materialization writes only `~/.codex/config.toml`. Project scope may read the lower-precedence user depth, but never mutates user configuration.
     - Missing depth and explicit depth `1` are sufficient for default phase execution. Invalid values or values below `1` block managed implementation preflight. `oat doctor` explains when depth `2` optional nesting is available.
     - The phase implementer directly executes its planned tasks from one Phase Scope, preserves one bounded commit per task, and returns phase-wide verification. It does not dispatch the phase reviewer.

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

@@ -25,7 +25,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 
 - Mutate by default; `--dry-run` to preview
 - Explicit `--dry-run` for safe preview of mutations
-- Deletions are limited to manifest-tracked entries: sync removes a skill or rule view only when the manifest records it and its canonical source is gone. Deleted agents are not cleaned up this way: with Cursor enabled, sync and status stop with an `escapes the sync scope` error until you delete the agent's dangling links in `.cursor/agents/` and `.claude/agents/`, and Codex's `.codex/agents/<name>.toml` and `[agents.<name>]` table are never removed (see [Manifest and Drift](manifest-and-drift.md#quick-look)). A provider file with no canonical source and no manifest entry is reported as a stray by `oat status`, not deleted. Writing a view is not limited this way: sync replaces whatever sits at a view's expected path, including an untracked file (see the warning under [Choosing sync scope](#choosing-sync-scope))
+- Deletions are limited to managed entries: sync removes a skill, rule or agent view only when the manifest records it and its canonical source is gone. A deleted or renamed agent's generated Codex role and `[agents.<name>]` table are removed through their owner header instead (0.3.39 and later; see [Manifest and Drift](manifest-and-drift.md#quick-look)). A provider file with no canonical source and no manifest entry is reported as a stray by `oat status`, not deleted. Writing a view is not limited this way: sync replaces whatever sits at a view's expected path, including an untracked file (see the warning under [Choosing sync scope](#choosing-sync-scope))
 - Cross-provider compatibility via adapters
 - Native-read assets stay canonical while provider-local adoption sources remain discoverable independently
 - Obsolete managed mappings are deleted only when their provider paths are verified clean; changed or unverified paths are preserved and detached from manifest ownership
@@ -64,7 +64,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Cursor provider enablement still controls agents, rules, migration discovery, and legacy cleanup even though Cursor reads canonical skills without a generated skill view.
 - Copilot provider enablement still controls agents, project rules, migration discovery, and legacy cleanup even though Copilot reads canonical skills without a generated skill view.
 - Codex project-scope subagent sync writes `.codex/config.toml` and `.codex/agents/*.toml` at command layer after path-mapping sync. Every generated project Codex variant and registration is repository-owned, version-controlled provider output. OAT provides no automatic ignore mechanism for this project output; collaborators review and commit it like other project configuration.
-- Default Codex execution requires `root (0) → phase implementer (1)`. Sync and direct materialization continue to apply an `agents.max_depth` floor of `2` as optional nested-work capability without lowering a higher target value. A project write may read a higher lower-precedence user value and preserves it in project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
+- Default Codex execution requires `root (0) → phase implementer (1)`. When `agents.max_depth` is absent, sync and direct materialization add `2` (or a higher inherited value) as optional nested-work capability; they keep an explicit value and report it as a conflict when it is below `1`. A project write may read a higher lower-precedence user value and preserves it in project configuration; it writes only project `.codex/config.toml`. User scope writes only `~/.codex/config.toml` and does not read or change project configuration.
 - Missing depth or depth `1` does not block default phase execution. Invalid values or explicit values below `1` fail managed implementation preflight. `oat doctor` reports whether optional depth-two nesting is available and gives a scope-specific repair when the configured value is unusable.
 - Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
 - Codex user-config materialization writes user-owned implementer and reviewer roles under the user provider directory, `~/.codex`; it does not write those roles into the repository.
@@ -154,9 +154,9 @@ the provider views, because sync overwrites changes made in the views.
 > A bare `oat sync` uses scope `all`, so it also writes under your home
 > directory. Every sync also overwrites edits made directly in provider folders,
 > replaces an untracked file sitting at a view path, and removes the view of a
-> deleted skill or rule. It does not clean up after a deleted or renamed agent;
-> see [Manifest and Drift](manifest-and-drift.md#quick-look) for the manual
-> steps. Pass `--scope` explicitly, and preview with `--dry-run` when you are
+> deleted skill or rule. From 0.3.39 it also removes a deleted or renamed
+> agent's views, Codex role and `[agents.<name>]` table; see
+> [Manifest and Drift](manifest-and-drift.md#quick-look). Pass `--scope` explicitly, and preview with `--dry-run` when you are
 > unsure.
 
 - If the run is in CI or a script, always pass `--scope project`, and preview

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

@@ -41,8 +41,11 @@ The first practical expansion path is to keep improving the existing owners: [Do
 
 `oat internal commit-paths --identity <operation> --message <message> -- <files...>`
 commits an explicit list of owned files with enabled Git hooks. Include tracked
-removals and both names of a rename. Directories, untracked missing paths,
-unmerged entries and paths outside the repository are rejected; the command
+removals and both names of a rename. A file `HEAD` already tracks is
+committed even when an ignore rule matches it or its directory (for example
+`packages/cli/assets/templates/` under `packages/cli/assets/*`); an untracked
+path that an ignore rule matches is rejected. Directories, untracked missing
+paths, unmerged entries and paths outside the repository are rejected; the command
 does not discover ownership or expand directory/glob pathspecs. Unrelated staged
 entries and worktree bytes remain preserved, including partially staged files.
 On success, owned index/worktree bytes match the hook-final commit.
@@ -205,8 +208,8 @@ Notable commands introduced in the current CLI surface:
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project closeout-check <project-path> [--autonomous] [--json]` - read-only check of the closeout invariant: a closeout that must snapshot its post-implementation sequence cannot reach terminal completion until its `oat_post_implement_sequence` snapshot exists, every stored step is recorded complete, approval is recorded, and the snapshot reached `status: complete`. A snapshot is required when the effective layered `workflow.postImplementSequence` is configured, when the closeout is autonomous (`--autonomous`, or `OAT_AUTONOMOUS=1` in the environment even without the flag), or when `oat_workflow_mode` is `lite`. Once a snapshot exists its recorded state is authoritative and current configuration is not consulted. JSON output reports `status` (`complete`, `not_required`, or `incomplete`), the missing `invariant` (`snapshot_missing`, `snapshot_malformed`, `sequence_failed`, `pre_approval_step_pending`, `approval_pending`, `post_approval_step_pending`, or `sequence_not_complete`), `route` (`oat-project-implement` when incomplete), `nextOwner` (the next stored step and its skill, or the approval), and the evaluated `inputs`. An incomplete or malformed result exits 1. For a goal project (`oat_workflow_mode: goal`) the goal boundary is checked first and read-only: it requires `oat_goal_status: declared_met`, a valid exhaustive `oat_goal_outcome_audit`, resolved extractions, a successful `gh pr view` observation of every terminal delivery member, and delivery coverage of every accepted phase (each in a terminal delivery's effective scope with a passed, fresh integrated review and its persisted `exit_gate`); refusals report `goal_inputs_unreadable`, `goal_not_declared`, `goal_audit_invalid`, `goal_extraction_unresolved`, `goal_observation_failed`, or `goal_coverage_incomplete`, and `nextOwner` is `{ kind: "goal", skill, reasons }`, where each reason is `{ code, message, subject? }` and `skill` is the owner of the first reason: for example `not-declared` and `audit-invalid` route to `oat-project-goal`, `review-not-fresh` to `oat-project-review-provide`, `exit-carrier-not-fresh` to `oat-project-implement`, delivery and endpoint reasons such as `endpoint-unmet` to `oat-project-pr-progress`, and `phase-uncovered` to `oat-project-pr-final`. A goal snapshot may record its `pr` step as satisfied by delivery coverage (`satisfied_by: { pr: delivery-coverage }`) only once `pr` is in the completed prefix.
-- `oat project delivery refresh --project <path> [--json]` - goal only. Observes every registered delivery member with `gh pr view <url> --json state,headRefOid,baseRefOid` and persists, in `state.md`, only the observations (`observed_head`, `observed_base`, member `status`), the delivery `status` (`open` or `at_endpoint`), the first observed `endpoint_attainment`, and derived staleness (`integrated_review.disposition: stale`, the milestone exit carrier's `freshness: stale` with `freshness_reason`). It never rewrites a reviewed revision, a member base, or the first endpoint attainment, never writes `oat_milestone_status` or `oat_goal_recovery`, and never manufactures a passed review or a fresh carrier. `oat-project-pr-progress` and `oat-project-goal` run it before registration and re-alignment.
-- `oat project delivery check --project <path> --subject <mNN|dNN> [--json]` - goal only, read-only. Reports whether a milestone (before registration, against the branch head) or a registered delivery (against its observed member revisions) is deliverable: a passed integrated review that is still fresh under the bookkeeping-successor rule and an allowed, fresh milestone exit carrier (reported as `exit.source: milestone-carrier`; the closeout boundary judges each delivery's persisted `exit_gate` instead). Evidence reviewed at R covers a later head only when every intervening commit changes permitted bookkeeping in this project's tracking files (`state.md`, `plan.md`, `implementation.md`, `project-log.md`, `summary.md`) and review artifacts (including those of deliveries sharing the same member pull request); any change to `summary.md` is bookkeeping because it is derived memory, never the authority for the brief's content; code changes, edits to approved brief content, and a substantive change followed by its revert fail. JSON output carries `status` (`ok` or `undeliverable`), the subject, its ordered `scope`, `publishedHeads`, `review`, `exit`, and `deliverable`; an undeliverable subject exits 1 with the full report. A stale `review` or `exit` result carries a `reason` that starts with a code, such as `review-missing`, `review-scope-narrow`, `member-unobserved`, `base-changed`, `bound-revision-mismatch` (a bound revision differs from its member's set-once `reviewed_head`), `subject-changed`, `configuration-changed`, or a bookkeeping-successor failure: `missing-revision`, `missing-object`, `not-ancestor`, `inspection-failed`, `disallowed-path`, or `substantive-change`.
+- `oat project delivery refresh --project <path> [--json]` - goal only. Observes every registered delivery member with `gh pr view <url> --json state,headRefOid,baseRefOid` and persists, in `state.md`, only the observations (`observed_head`, `observed_base`, member `status`), the delivery `status` (`open` or `at_endpoint`), the first observed `endpoint_attainment`, and derived staleness (`integrated_review.disposition: stale`, the milestone exit carrier's `freshness: stale` with `freshness_reason`). It never rewrites a reviewed revision, a member base, or the first endpoint attainment, never writes `oat_milestone_status` or `oat_goal_recovery`, and never manufactures a passed review or a fresh carrier. For `kind: stack`, members are ordered base to tip. A configured code carrier bound to a reviewed head is judged at the tip, and each lower observed head must be an ancestor of the tip; null carriers are skipped, and unreviewed-resolution carriers (`no_gate`, `project_disabled`) are evaluated exactly as for `kind: pr`. `oat-project-pr-progress` and `oat-project-goal` run it before registration and re-alignment.
+- `oat project delivery check --project <path> --subject <mNN|dNN> [--json]` - goal only, read-only. Reports whether a milestone (before registration, against the branch head) or a registered delivery (against its observed member revisions) is deliverable: a passed integrated review that is still fresh under the bookkeeping-successor rule and an allowed, fresh milestone exit carrier (reported as `exit.source: milestone-carrier`; the closeout boundary judges each delivery's persisted `exit_gate` instead). For `kind: stack`, `publishedHeads` still reports every member head. For a registered delivery subject (`--subject dNN`), a configured code carrier bound to a reviewed head is judged against the tip after verifying each lower head is its ancestor (`stack-order` otherwise); null carriers and unreviewed-resolution carriers (`no_gate`, `project_disabled`) are evaluated exactly as for `kind: pr`. A milestone subject (`--subject mNN`) keeps branch-head carrier evaluation. Evidence reviewed at R covers a later head only when every intervening commit changes permitted bookkeeping in this project's tracking files (`state.md`, `plan.md`, `implementation.md`, `project-log.md`, `summary.md`) and review artifacts (including those of deliveries sharing the same member pull request). A gate-produced code-review artifact under `reviews/` also counts as permitted bookkeeping when its Reviews row has Invocation `gate` and Reviewed Head equal to the carrier's `reviewed_head`; it remains shared evidence, never integrated-review evidence or a delivery's own evidence. Any change to `summary.md` is bookkeeping because it is derived memory, never the authority for the brief's content; code changes, edits to approved brief content, and a substantive change followed by its revert fail. JSON output carries `status` (`ok` or `undeliverable`), the subject, its ordered `scope`, `publishedHeads`, `review`, `exit`, and `deliverable`; an undeliverable subject exits 1 with the full report. A stale `review` or `exit` result carries a `reason` that starts with a code, such as `review-missing`, `review-scope-narrow`, `member-unobserved`, `base-changed`, `bound-revision-mismatch` (a bound revision differs from its member's set-once `reviewed_head`), `subject-changed`, `configuration-changed`, `stack-order`, or a bookkeeping-successor failure: `missing-revision`, `missing-object`, `not-ancestor`, `inspection-failed`, `disallowed-path`, or `substantive-change`.
 - `oat project complete-state <project-path> [--archived] [--autonomous]` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout. It first evaluates the same closeout invariant as `oat project closeout-check` and refuses, with the same message and without writing, a configured, autonomous, or lite closeout whose snapshot is absent, malformed, or incomplete. A project whose implementation finished before closeout snapshots existed recovers by running `oat-project-implement`, which persists the snapshot (`completion-and-closeout.md` Step 15) and completes its stored steps; there is no override flag. An unconfigured, interactive, non-lite closeout without a snapshot completes as before. A goal project is also refused, without writing, by the goal boundary that `closeout-check` describes. When the project has an `implementation.md`, `complete-state` then runs the final journal evaluator (`oat project journal check --at completion`) on the same bytes immediately before its write, and refuses with the evaluator's reasons, writing nothing, when the journal does not hold its terminal shape; an override line covers only its eligible gap and never the closeout invariant. A project with a `plan.md` but no `implementation.md` is refused with `journal-missing`; only a plan-less project completes on the closeout invariant alone.
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit] [--new-generation <reason>]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive verifies the complete selected package and every immutable file byte, then atomically exports one self-contained `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>.html` page before deleting the active project. The full original package remains in the archived project. JSON `projectRecapExport` identifies `runId`, `page.sourceRelativePath`, `page.originalSha256`, `page.exportedSha256`, `verifiedArtifactCount`, and the flat `exportRoot`. No tracked sidecar is created. Matching dated pages are adopted on retry; conflicting destinations, incomplete inventory coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. Summary and PR links point to the tracked page. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt. Retry identity: one read-only evaluator, shared by apply and `--dry-run`, resolves the archive before any write. An identical retry (the project's retained-artifact manifest matches exactly one same-scope archive) reuses that snapshot's local path, dated export identity (summary export file and S3 key) and receipt on any later date, and a source-absent retry resumes the single same-scope archive; changed content, several matching archives, or an unverifiable non-empty directory at the archive path refuse before export, copy, overwrite or S3 upload, with follow-up-project guidance. The dry-run reports the identity the apply would use. `.oat-archive-source.json` records `manifestHash` and `generation` beside the project name, scope, snapshot and synced source SHA. The exported summary rewrites `oat-project:<project>#<entry-id>` locators to `oat-archive:<snapshot>#<entry-id>` and turns relative `project-log.md` or `oat-execution-learnings.md` links into plain text; see [Archive identity](project-artifacts.md#archive-identity). `--new-generation <reason>` archives reopened work of a shared or local project as the next generation instead of refusing it: it requires a non-empty single-line reason and exactly one latest generation of the same project and scope as predecessor (otherwise it refuses), never overwrites that predecessor, and persists the new generation (`<project>-gN` locally, `<YYYYMMDD>-<project>-gN` as export identity; when the same project's archive from another scope already holds that path or identity, both carry the scope: `<project>-gN-<scope>` and `<YYYYMMDD>-<project>-gN-<scope>`) with its predecessor, reason and `generationRequest` id before any export, copy or S3 side effect, so a retry reuses it. Replaying the same predecessor and content resolves to the same generation; synced projects refuse the option. JSON adds `generation` and `predecessorSnapshot`, and `--dry-run` reports the proposed generation without writing it.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. A name resolves as an exact snapshot, then a full generation name such as `demo-g2`, then the project (or `<project>-<scope>` family), restoring its latest generation and then its latest date; see [Project Artifacts](project-artifacts.md) for the `<project>[-gN][-<scope>]` naming contract. The old `oat project archive sync` path remains as a deprecated shim.
@@ -214,7 +217,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project dispatch record --event-file <json-file-or-dash> --format line [--dispatch-stamp <line>]` - print the one-line journal run record for the same validated, redacted record and event (projection `run/v1`), and write nothing; standard input still works. The line is `run/v1` followed by named fields in a fixed order, joined by a space-padded `·`: `request`, `scope`, `action`, `role`, configured `target`, `model` and `effort`, `stamp` (the formal `Dispatch:` stamp passed verbatim through `--dispatch-stamp`; a stamp without the canonical prefix is refused), `launch` (`planned`, `accepted`, or `blocked-before-start`), the raw child `outcome`, `terminal` (`yes` or `no`) and its `class` (`completed`, `terminal-stop`, `blocked-before-start`, `live`, or `unrecognized`), `continuation` references, and the optional `observed` identity with its `match`, which never replaces the configured fields. Inside a value, `\\` is a literal backslash and `\·`, `\~`, `\n`, and `\r` escape the delimiter, a tilde, a newline, and a carriage return; a bare `~` is null. Terminality comes from one producer-to-outcome mapping: a successful completion (`completed`, `DONE`, `DONE_WITH_CONCERNS`), a terminal stop (`BLOCKED`, `failed`, `cancelled`, `INVALID_RUN_ABORT`) and `blocked-before-start` are terminal; `planned`, `running`, `pending`, and `NEEDS_CONTEXT` with its handle still open are not, and an outcome outside the mapping is `unrecognized`, never success. The owning skill writes one line per request id under `## Orchestration Runs` and updates it in place. `--json` keeps `status: validated-only`, the record and `runtimeIdentity`, and adds `runLine` (`version`, `line`, `fields`, `classification`, `terminal`).
 - `oat project dispatch canonical-role --role <name> --request-id <id> --skill-dir <dir> [--json]` - resolve a canonical role through the loaded, user (`$HOME/.agents`), and project (`<repo>/.agents`) tiers and print the `canonical-role-resolution` event that `oat project dispatch record` accepts unchanged: redacted `canonicalPath` and `selectedPath` in the form `<loaded|user|project>/agents/<name>.md`, the role's `contentDigest`, and `candidateMisses`. `--skill-dir` is required because the loaded tier is derived from the loaded skill's directory; a missing or invalid directory exits 1 with a redacted error. An unknown role prints `missing` evidence with its recovery commands. Read-only; the dependency is the `workflows` pack.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. Brief plans (`oat_workflow_mode: brief`) are validated with the brief profile: phases need non-empty `**Intent:**` and `**Exit evidence:**`, a `**Provisional:**` value of `yes` or `no`, unique IDs, and a concrete first phase; `### Task` headings in a brief are reported as a warning, and taskless parallel groups are valid. Goal plans add the goal profile: `oat_plan_source: goal`, a valid `## Milestones` table (`goal-milestones-missing`, `goal-milestones-malformed`, `goal-duplicate-milestone`, `goal-milestone-empty`, `goal-milestone-unknown-phase`, `goal-phase-in-multiple-milestones`, `goal-phase-without-milestone`), no parallel group spanning milestones (`goal-group-crosses-milestone`), canonical persisted phase IDs (`goal-noncanonical-phase-id`), and no change to a shipped milestone or a registered delivery's frozen scope (`goal-shipped-milestone-changed`, `goal-delivered-scope-changed`); phases the journal marks `extracted` need no milestone. See [Implementation Execution](../workflows/projects/execution/implementation-execution.md#parallel-phase-groups).
-- `oat project journal check --at <implement-preflight|review|completion> [--project <path>] [--scope pNN[,pNN]] [--json]` - read-only journal evaluator: it reads `plan.md`, `implementation.md`, and `state.md` and writes nothing. `implement-preflight` is implement's call before its Step 16: it validates the accepted task and phase evidence while the terminal headers and pointers Step 16 owns may still be unwritten. `review` requires an explicit `--scope` of phases the plan declares and ignores future phases; a live run line warns there instead of refusing. `completion` (oat-project-complete, before roll-up, seal, or any lifecycle write) also requires the terminal journal shape: journal `oat_status: complete` and a cleared `oat_current_task_id`, `state.md` `oat_phase_status` `complete` or `pr_open` and a cleared `oat_current_task`. Task modes read journal records through the shared heading-only reader (fenced and indented code excluded, a block ends at the next heading of equal or higher level): every plan task heading is unique and sits under its own phase (`plan-task-duplicate`, `plan-task-misplaced`, routed to the plan owner and never override-eligible), and every plan task has exactly one journal block in its phase with exactly one owned `**Status:** completed` and one owned `**Commit:**` SHA; tables and checklists are never completion evidence, and overview totals must match. Brief and goal read phase units: an accepted phase carries its `**Head:**`, execution records close as `completed` with a commit or as `failed`, `cancelled`, or `no-change` without one, an extracted goal phase and a phase the goal outcome audit defers or retires stay valid and incomplete. Everywhere: `## References` is last, review receipts sit in their phase or `## Reviews and Gates`, deferrals in `## Deferred Findings`, dispatch payloads are refused unless marked `quoted-evidence`, every run line parses as `run/v1` under `## Orchestration Runs`, carries a valid `request` identifier, and is terminal at implement-preflight and completion, and no template placeholder survives, including one left in an inline-code slot such as ``- `{path}` - …`` unless the line is marked `quoted-evidence`. An override is one line under `## Deviations from Plan / Design`: `**Override:** <scope-disposition-approved|evidence-lost|operator-accepted-gap> · **Authorized by:** <decision id> · **Scope:** <pNN-tNN|pNN> · <reason>`; it covers only a missing task block, an incomplete task, missing commit evidence, or (for `scope-disposition-approved`) an unaccepted phase within its scope, and a malformed or misplaced override is refused. Output is `{ status: ok | refused, reasons: [{ code, path, line, owner, message }], warnings, overrides }`; a refusal exits 1. Delivery coverage and the post-implementation sequence stay with `closeout-check`.
+- `oat project journal check --at <implement-preflight|review|completion> [--project <path>] [--scope pNN[,pNN]] [--json]` - read-only journal evaluator: it reads `plan.md`, `implementation.md`, and `state.md` and writes nothing. `implement-preflight` is implement's call before its Step 16: it validates the accepted task and phase evidence while the terminal headers and pointers Step 16 owns may still be unwritten. `review` requires an explicit `--scope` of phases the plan declares and ignores future phases; a live run line warns there instead of refusing. In goal projects, those two boundaries also compare working `implementation.md` with its committed `HEAD` version and refuse each removed or rewritten recorded line as `journal-line-rewritten`; append-only additions, mutable progress fields, and new extraction markers do not trigger that reason. The comparison base is `HEAD`, so a rewrite that is already committed is left to `delivery check`. Unparseable committed journal frontmatter refuses as `journal-frontmatter-malformed` and must be repaired and committed before re-running. An untracked journal or unborn `HEAD` has no committed version to compare, while other Git inspection failures are command errors. `completion` does not run this comparison and instead requires the terminal journal shape: journal `oat_status: complete` and a cleared `oat_current_task_id`, `state.md` `oat_phase_status` `complete` or `pr_open` and a cleared `oat_current_task`. Task modes read journal records through the shared heading-only reader (fenced and indented code excluded, a block ends at the next heading of equal or higher level): every plan task heading is unique and sits under its own phase (`plan-task-duplicate`, `plan-task-misplaced`, routed to the plan owner and never override-eligible), and every plan task has exactly one journal block in its phase with exactly one owned `**Status:** completed` and one owned `**Commit:**` SHA; tables and checklists are never completion evidence, and overview totals must match. Brief and goal read phase units: an accepted phase carries its `**Head:**`, execution records close as `completed` with a commit or as `failed`, `cancelled`, or `no-change` without one, an extracted goal phase and a phase the goal outcome audit defers or retires stay valid and incomplete. Everywhere: `## References` is last, review receipts sit in their phase or `## Reviews and Gates`, deferrals in `## Deferred Findings`, dispatch payloads are refused unless marked `quoted-evidence`, every run line parses as `run/v1` under `## Orchestration Runs`, carries a valid `request` identifier, and is terminal at implement-preflight and completion, and no template placeholder survives, including one left in an inline-code slot such as ``- `{path}` - …`` unless the line is marked `quoted-evidence`. An override is one line under `## Deviations from Plan / Design`: `**Override:** <scope-disposition-approved|evidence-lost|operator-accepted-gap> · **Authorized by:** <decision id> · **Scope:** <pNN-tNN|pNN> · <reason>`; it covers only a missing task block, an incomplete task, missing commit evidence, or (for `scope-disposition-approved`) an unaccepted phase within its scope, and a malformed or misplaced override is refused. Output is `{ status: ok | refused, reasons: [{ code, path, line, owner, message }], warnings, overrides }`; a refusal exits 1. Delivery coverage and the post-implementation sequence stay with `closeout-check`.
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../workflows/projects/execution/project-log.md).
 - `oat project log append --category <category> --source <id> [--origin <producer>]` - record a learning on a judgment entry. The category is one of `gotcha`, `efficiency`, `documentation-gap`, `candidate-skill-content`, `decision`, or `environment-limited`; any other value, `--category` without `--source`, a `--source` containing whitespace, and these flags on a `--structural` entry are refused. The flags write a `**Category:**`, `**Source:**`, `**Origin:**`, `**Recorded:**` body head above the body; the heading grammar is unchanged and an entry without them is stored as before. Passing the source id as `--idempotency-key` makes a retry report `already-appended` and write nothing.
 - `oat project log check` - JSON adds `learnings`: `legacy` when the project still has `oat-execution-learnings.md`, which summary and retro read after the log, and `none` otherwise, in every status.

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

@@ -127,7 +127,7 @@ Current schema keys:
 | `documentation.nonReaderPaths`                             | `string[]`                 | -                        | Shared-only content-root-relative bounded globs omitted from nav inventory/Contents/check/manifest and, with OAT source config, Fumadocs rendering. MkDocs 1.4.2 still renders routes. See [Non-reader paths](#non-reader-paths).                                                                                                                                                                                                                                                                   |
 | `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.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`.                                                                                                                                                                                                                                                                                                                                  |
+| `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init --setup` from `origin/HEAD`, falling back to `main`. Used by `oat-project-pr-final`, `oat-project-pr-progress`, and `oat-project-complete`.                                                                                                                                                                                                                                                                                          |
 | `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.                                                                                                                                                                                             |

package/assets/docs/reference/project-artifacts.md

@@ -112,19 +112,28 @@ goal fields:
   its milestone, frozen phase scope, agreed endpoint, status, member pull
   requests and their observed revisions, the integrated review it was
   delivered on, its exit-gate binding and the first observed endpoint
-  attainment. A delivery's `status` is `registering`, `open`, `at_endpoint`,
+  attainment. A delivery's `kind` is `pr` for one pull request or `stack` for
+  an existing gh-stack, whose members are recorded base to tip; a stack's
+  configured code exit carrier is judged at the tip member, and every lower
+  member's observed head must be an ancestor of the tip (`stack-order`
+  otherwise). A delivery's `status` is `registering`, `open`, `at_endpoint`,
   or `superseded`, and its agreed `endpoint` is `open` or `merged`. A
   replacement delivery names its one direct predecessor in `covers_scope_of`,
   and the predecessor's `superseded_by` points back; only a delivery that never
   reached its agreed endpoint may be replaced. A correction of a delivery that
   did reach it is additive (`corrects_delivery_id`, new phase IDs, no inherited
   coverage). `oat_pr_status` and `oat_pr_url` project the latest member pull
-  request.
+  request, which is the tip member for a stack.
 
 Delivery evidence stays fresh across later commits that change only bookkeeping:
 `state.md`, `plan.md` (outside its approved content), `implementation.md`,
 `project-log.md` appends, `summary.md`, and the review artifacts of the
-delivery and of any delivery sharing its pull request.
+delivery and of any delivery sharing its pull request. In evidence scopes built
+for an exit carrier, the gate's own artifact also counts as bookkeeping if its
+`## Reviews` row has Type `code`, Invocation `gate` and a non-placeholder
+Reviewed Head equal to the carrier's `reviewed_head`, and the artifact is under `reviews/`
+(including `reviews/archived/`). That artifact is never integrated-review
+evidence and never one of a delivery's own review artifacts.
 
 A delivery's evidence identity is set once: its `exit_gate`, its
 `integrated_review` identity (`artifact`, `scope`, `bound_revisions`), and each

package/assets/docs/reference/troubleshooting.md

@@ -95,9 +95,8 @@ link or copy that OAT creates in the tool's own folder, such as
 - If you are working in the OAT source repository: run
   `pnpm run worktree:init`. This command copies local-only files from the main
   worktree, installs dependencies, configures Git hooks, builds the workspace,
-  and runs `oat sync` with no scope flag. A bare `oat sync` uses
-  `--scope all`, so it refreshes user-scope provider views in your home
-  directory as well as the project's.
+  and runs `oat sync --scope project`, which refreshes only the project's
+  provider views and leaves user-scope views in your home directory alone.
 
 ## Codex appears detected but no skill sync actions are listed
 
@@ -328,8 +327,8 @@ npm install --global @open-agent-toolkit/cli
 oat status # or: oat doctor
 ```
 
-The diagnostic's own recovery line says to run `pnpm build`. That applies only
-when you run the CLI from a checkout of the OAT source repository.
+The diagnostic's own recovery line names the same two remedies and mentions
+`pnpm build` only for a checkout of the OAT source repository.
 
 If you are working in the OAT source repository: rebuild the CLI workspace,
 then rerun the command named in the diagnostic: