npm - @open-agent-toolkit/cli - Versions diffs - 0.3.37 → 0.3.39 - Mend

@open-agent-toolkit/cli 0.3.37 → 0.3.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (84) hide show

package/assets/docs/reference/what-oat-writes.md CHANGED Viewed

@@ -8,7 +8,8 @@ description: 'Every file, link and Git ref that OAT commands create in your repo
 This page lists what each OAT command writes in your repository, under your
 home directory and on your shared `origin` remote, which of those files belong
 in Git, and how to back out of OAT completely. Everything here was observed by
-running OAT CLI version 0.3.14 on macOS. The removal procedure in
+running OAT CLI version 0.3.14 on macOS, except statements marked with a later
+version, which describe what changed in that version. The removal procedure in
 [Remove everything](#remove-everything) was run end to end twice, once
 originally and once in an independent re-run, and both times it returned the
 repository and the home directory to their pre-OAT state.
@@ -23,11 +24,11 @@ agents, templates and scripts that `oat tools install` adds.
 ## The short version
-- With `--scope project`, `oat init`, `oat sync` and `oat tools install <pack>`
-  write only inside the repository. Two forms are exceptions:
-  `oat tools install --scope project` without a pack name also installs the
-  `core` pack under your home directory, and `oat init --scope project --setup`
-  installs every pack there.
+- With `--scope project`, `oat init`, `oat sync` and `oat tools install`
+  write only inside the repository. `oat tools install --scope project`
+  without a pack name and `oat init --scope project --setup` skip the
+  user-only `core` pack and say so, and `oat tools install core --scope project`
+  exits 1 (0.3.39 and later).
 - Without `--scope`, `oat init` and `oat sync` use scope `all`, so they can
   also write under your home directory, and `oat tools install <pack>` installs
   a pack that is not yet installed under your home directory (user scope).
@@ -47,11 +48,12 @@ agents, templates and scripts that `oat tools install` adds.
 Where a file already existed, OAT appended its own marked block instead of
 replacing it. This held for `.gitignore`, `.gitattributes` and an existing
 `pre-commit` hook. From version 0.3.37, an existing `.codex/config.toml` is
-edited in place: OAT changes only `multi_agent`, `max_depth` and its own
-`[agents.<name>]` tables, and comments, blank lines, table order and your other
-settings stay as they were (see the
+edited in place: OAT changes only its own `[agents.<name>]` tables and adds
+`multi_agent` and `max_depth` when they are missing, and comments, blank lines,
+table order and your other settings stay as they were (see the
 [provider table](#syncing-provider-views)). Earlier versions rewrote the whole
-file and dropped its comments. A pre-existing
+file and dropped its comments, and versions before 0.3.39 also changed a
+`multi_agent` or `max_depth` value you had set. A pre-existing
 `~/.claude/settings.json` was left untouched.
 ### Setting up
@@ -85,13 +87,13 @@ views OAT manages. A provider does not have to be enabled: an existing
 `.claude/` directory in the repository, or `~/.claude/` in your home directory,
 is enough for `oat sync` to create Claude views.
-| Provider | Repository views created by `oat sync --scope project`                                                                                                                                                                                                                                                                                              |
-| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude   | `.claude/skills/<name>` and `.claude/agents/<name>.md`, relative symlinks into `.agents/`                                                                                                                                                                                                                                                           |
-| Cursor   | `.cursor/agents/`: relative symlinks for agents, plus generated model-variant files marked `# oat-managed: true`                                                                                                                                                                                                                                    |
-| Copilot  | `.github/agents/`, relative symlinks                                                                                                                                                                                                                                                                                                                |
-| Codex    | `.codex/agents/*.toml` and `.codex/config.toml`, generated files. In an existing `config.toml`, OAT adds its `[agents.<name>]` tables and sets `[features] multi_agent = true` and `[agents] max_depth` to at least 2, changing those two values if you had set them lower; your other settings and comments stay byte for byte (0.3.37 and later). |
-| Gemini   | Nothing                                                                                                                                                                                                                                                                                                                                             |
+| Provider | Repository views created by `oat sync --scope project`                                                                                                                                                                                                                                                                                                                                                                                          |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude   | `.claude/skills/<name>` and `.claude/agents/<name>.md`, relative symlinks into `.agents/`                                                                                                                                                                                                                                                                                                                                                       |
+| Cursor   | `.cursor/agents/`: relative symlinks for agents, plus generated model-variant files marked `# oat-managed: true`                                                                                                                                                                                                                                                                                                                                |
+| Copilot  | `.github/agents/`, relative symlinks                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Codex    | `.codex/agents/*.toml` and `.codex/config.toml`, generated files. In an existing `config.toml`, OAT adds its `[agents.<name>]` tables; your other settings and comments stay byte for byte (0.3.37 and later). It adds `[features] multi_agent = true` and `[agents] max_depth` only when they are missing and names each key it added; a value you set is kept, and sync reports a conflict when OAT needs a different one (0.3.39 and later). |
+| Gemini   | Nothing                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 OAT creates skill views only for Claude. It reports the other providers' skill
 support as `native-read` and creates no skill views for them. No generated
@@ -107,7 +109,7 @@ file contained an absolute path.
 | Command                                    | In the repository                                                                                                                                                                                                                                           | Under your home directory                                                                                                                                                               |
 | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `oat tools install <pack> --scope project` | The pack's skills in `.agents/skills/`, plus any agents in `.agents/agents/`, templates in `.oat/templates/` and scripts in `.oat/scripts/` it ships; `tools.<pack>: true` in `.oat/config.json`. Views for enabled providers, unless you pass `--no-sync`. | Nothing                                                                                                                                                                                 |
-| `oat tools install --scope user`           | Nothing, unless the workflows pack is already installed at project scope (see [surprises](#known-surprises-in-0314))                                                                                                                                        | `~/.agents/skills/`, `~/.agents/agents/`, `~/.oat/config.json`, `~/.oat/docs/`, `~/.oat/ideas/`, `~/.oat/scripts/`, `~/.oat/templates/`. Provider links only if a provider is detected. |
+| `oat tools install --scope user`           | Nothing, even when a pack is already installed at project scope (0.3.39 and later)                                                                                                                                                                          | `~/.agents/skills/`, `~/.agents/agents/`, `~/.oat/config.json`, `~/.oat/docs/`, `~/.oat/ideas/`, `~/.oat/scripts/`, `~/.oat/templates/`. Provider links only if a provider is detected. |
 | `oat tools install core`                   | Nothing                                                                                                                                                                                                                                                     | `~/.oat/config.json`, `~/.agents/skills/oat-docs`, `~/.agents/skills/oat-doctor`, and `~/.oat/docs/` (a bundled copy of these docs)                                                     |
 Some packs write more at project scope. The ideas pack adds
@@ -116,9 +118,10 @@ Some packs write more at project scope. The ideas pack adds
 `.oat/projects/archived/.gitkeep` and a `projects.root` setting. Passing
 `--project-guidance` adds a marked `<!-- OAT tools -->` block to `AGENTS.md`,
 creating the file if needed. Installing every pack at once with
-`oat tools install --scope project` puts core in your home directory and the
-other seven packs in the repository, and also adds a `localPaths` setting and a
-`# OAT local paths` block to `.gitignore`.
+`oat tools install --scope project` puts the other seven packs in the
+repository, skips core with a message that it is user-scope only (0.3.39 and
+later; earlier versions installed core in your home directory), and also adds a
+`localPaths` setting and a `# OAT local paths` block to `.gitignore`.
 No tool pack command wrote to `origin`.
@@ -198,14 +201,16 @@ is anything that differs between machines.
 - **Generated provider files** (Cursor model variants, Codex agents and
   `config.toml` tables). Committed, they arrive with every clone. Not
   committed, each teammate runs `oat sync --scope project` to generate them.
-  Either way, `oat tools remove` does not delete them; see
-  [Backing out](#backing-out).
+  Either way, `oat tools remove` deletes the removed agents' Codex roles and
+  tables (0.3.39 and later) but leaves Cursor model variants until the next
+  `oat sync --scope project`; see [Backing out](#backing-out).
 - **Pack files in `.oat/`** (templates, scripts, ideas, `projects-root`).
   Committed, every clone has them. Not committed, each teammate needs the same
   `oat tools install` to get them.
-- **`AGENTS.md` guidance block.** It tells agents how to refresh views, but the
-  command it recommends, `oat sync --scope all`, also writes under each
-  reader's home directory.
+- **`AGENTS.md` guidance block.** It tells agents how to refresh views with
+  `oat sync --scope project`, which writes only inside the repository (0.3.39
+  and later; earlier blocks recommend `oat sync --scope all`, which also writes
+  under each reader's home directory).
 - **A hook inside the working tree.** Committed, everyone using that hooks path
   gets the drift warning. A hook in `.git/hooks` is never committed.
 - **`pr/` and `reviews/archived/` folders.** Whether PR material and archived
@@ -231,9 +236,8 @@ is anything that differs between machines.
 4. **Install personal packs separately.** User-scope packs live under each
    person's `~/.agents` and `~/.oat`, so nobody receives them from the
    repository. A teammate who wants them runs `oat tools install --scope user`,
-   which installs all eight packs. Run inside a repository where the workflows
-   pack is installed at project scope, it also edits that repository; see
-   [surprises](#known-surprises-in-0314).
+   which installs all eight packs and writes nothing into the repository
+   (0.3.39 and later).
 5. **Fetch synced projects explicitly.** A fresh clone does not receive
    `refs/oat/*`, so synced projects are not in it. See
    [Picking Up Projects](../workflows/projects/execution/picking-up-projects.md)
@@ -256,14 +260,14 @@ The hook does nothing when no `oat` binary is on `PATH`, and
 ### Supported removal commands
-| Command                                                               | Removes                                                                                                                                                | Leaves behind                                                                                                                                                                                                                                   |
-| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `oat tools remove --pack <pack> --scope project` (one pack at a time) | The pack's skills and agents in `.agents/`, their symlink views (Claude, Copilot, Cursor symlinks), and its `.oat/scripts/*.sh`                        | `.oat/templates/`, `.oat/ideas/`, `.oat/projects-root`, `.oat/config.json` (with a stale `tools.requiredBy` entry), `.oat/sync/`, both `.gitignore` blocks, `.gitattributes`, projects, empty folders, and all generated Cursor and Codex files |
-| `oat tools remove --all`                                              | Nothing: exits 2 with `Pack core does not allow project scope`, with or without `--scope project`                                                      | Everything                                                                                                                                                                                                                                      |
-| `oat tools remove --all --scope user`                                 | With only core installed at user scope: `~/.agents/skills/oat-docs`, `~/.agents/skills/oat-doctor`, `~/.oat/docs/` and their `~/.claude/skills/` links | `~/.oat/config.json` (now `{"version": 1}`), `~/.oat/sync/manifest.json`, an empty `~/.agents/skills/` and an empty `~/.claude/skills/`                                                                                                         |
-| `oat remove skill <name> --scope project`                             | The canonical skill, its Claude view and its manifest entry                                                                                            | Nothing for that skill                                                                                                                                                                                                                          |
-| `oat project prune <name>` (synced projects only)                     | The worktree, the pointer file, the local ref and the ref on `origin`; commits `chore(oat): prune synced project <name>` on the current branch         | An empty `.oat/projects/synced/`                                                                                                                                                                                                                |
-| `oat init --scope project --no-hook`                                  | OAT's hook block. If the file holds only OAT's block, the whole `pre-commit` file is deleted.                                                          | Your own hook lines, byte for byte                                                                                                                                                                                                              |
+| Command                                                               | Removes                                                                                                                                                                                                | Leaves behind                                                                                                                                                                                                                                                                        |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `oat tools remove --pack <pack> --scope project` (one pack at a time) | The pack's skills and agents in `.agents/`, their symlink views (Claude, Copilot, Cursor symlinks), its `.oat/scripts/*.sh`, and from 0.3.39 its agents' generated Codex roles and `[agents.*]` tables | `.oat/templates/`, `.oat/ideas/`, `.oat/projects-root`, `.oat/config.json` (with a stale `tools.requiredBy` entry), `.oat/sync/`, both `.gitignore` blocks, `.gitattributes`, projects, empty folders, and generated Cursor model variants until the next `oat sync --scope project` |
+| `oat tools remove --all`                                              | Nothing: exits 2 with `Pack core does not allow project scope`, with or without `--scope project`                                                                                                      | Everything                                                                                                                                                                                                                                                                           |
+| `oat tools remove --all --scope user`                                 | With only core installed at user scope: `~/.agents/skills/oat-docs`, `~/.agents/skills/oat-doctor`, `~/.oat/docs/` and their `~/.claude/skills/` links                                                 | `~/.oat/config.json` (now `{"version": 1}`), `~/.oat/sync/manifest.json`, an empty `~/.agents/skills/` and an empty `~/.claude/skills/`                                                                                                                                              |
+| `oat remove skill <name> --scope project`                             | The canonical skill, its Claude view and its manifest entry                                                                                                                                            | Nothing for that skill                                                                                                                                                                                                                                                               |
+| `oat project prune <name>` (synced projects only)                     | The worktree, the pointer file, the local ref and the ref on `origin`; commits `chore(oat): prune synced project <name>` on the current branch                                                         | An empty `.oat/projects/synced/`                                                                                                                                                                                                                                                     |
+| `oat init --scope project --no-hook`                                  | OAT's hook block. If the file holds only OAT's block, the whole `pre-commit` file is deleted.                                                                                                          | Your own hook lines, byte for byte                                                                                                                                                                                                                                                   |
 No command deletes a shared or local project. `oat project prune` refuses a
 shared project, and `oat project archive` moves a project to
@@ -340,36 +344,28 @@ prune to erase sensitive content. Rewriting history is not covered here.
 ## Known surprises in 0.3.14
-These are current behaviors as of version 0.3.14.
-- `oat tools install core --scope project` prints `Installed core tool pack.`
-  but writes nothing.
-- `oat init --scope project --setup` installs all eight packs under your home
-  directory, and runs `gh repo view`, which makes the `gh` CLI write
-  `~/.local/state/gh/device-id`.
-- `oat tools install --scope user` writes into the current repository when the
-  workflows pack is already installed there at project scope: it adds
-  `localPaths` to `.oat/config.json` and a `# OAT local paths` block to
-  `.gitignore`.
-- `oat tools install workflows --scope project` does not add that block, but
+These behaviors were observed in version 0.3.14. Entries that later versions
+fixed have been removed: from 0.3.39, `core` under `--scope project` is refused
+or skipped, an explicit `--scope` writes only that scope, `init --setup` honors
+`--scope` and does not run `gh`, the guidance block recommends
+`oat sync --scope project`, local-scope `oat project new` reports why it made no
+commit, and piping output into `head` exits quietly.
+- `oat tools install workflows --scope project` does not add the
+  `# OAT local paths` block to `.gitignore`, but
   `oat tools install --scope project` does, so `pr/` and `reviews/archived/`
   folders are committable in one setup and ignored in the other.
 - `oat tools remove --all` fails unless you add `--scope user`.
 - After removing packs, a stale `tools.requiredBy` entry stays in
   `.oat/config.json`, and `oat status` reports the utility pack as missing and
   suggests `oat tools update`.
-- Removing a pack leaves its generated Cursor and Codex files, and a later
-  `oat sync` reports no changes.
+- Removing a pack leaves its generated Cursor model variants until the next
+  `oat sync --scope project` removes them. Its agents' generated Codex roles
+  and `config.toml` tables are removed with the pack (0.3.39 and later).
 - An existing `.claude/` folder, in the repository or your home directory, is
   enough for `oat sync` to create Claude views without enabling Claude.
 - After `oat tools install <pack> --no-sync`, running the same install again
   reports `unchanged` and creates no views; run `oat sync --scope project`.
-- The `AGENTS.md` block from `--project-guidance` recommends
-  `oat sync --scope all`, which also writes under your home directory.
-- `oat project new --scope local` prints `Scaffold commit: skipped (--no-commit)`
-  even when you did not pass that flag.
-- Piping `oat tools list` or `oat status` into `head` crashes with an
-  `Error: write EPIPE` stack trace.
 ## Not covered here
@@ -399,8 +395,7 @@ These are current behaviors as of version 0.3.14.
   [Config and Local State](config-and-local-state.md).
 - **Files you place at a view path yourself.** See
   [Manifest and Drift](../provider-sync/manifest-and-drift.md).
-- **`gh repo view` against a real GitHub remote**, and Git versions older than
-  2.31.
+- **Git versions older than 2.31.**
 ## Related

package/assets/docs/skills/repo-improve.md CHANGED Viewed

@@ -209,15 +209,22 @@ explicitly save a report before asking another workflow to consume its path.
 so use the slash or `$` form rather than relying on the agent to pick it. It
 does not require a project name or an active-project pointer.
-**Prerequisites:** A Git repository, the OAT CLI, and the ability to dispatch
-the `oat-codebase-mapper` subagent. A preflight checks whether background
-agents can write files and switches to a read-only fallback if they cannot.
-Needs an active OAT project: no. If a knowledge directory already exists,
-choose whether to refresh it or skip the run. Refresh removes only regular
-Markdown files marked `oat_generated: true` and regenerates the eight named
-outputs. Hand-written notes survive; an unmarked expected-output collision
-stops the run before deletion so you can decide how to preserve it. Symlinked
-knowledge directories and output collisions are refused.
+**Prerequisites:** A Git repository, the OAT CLI, the utility-pack dispatch
+skills, and an installed `oat-codebase-mapper` provider projection. Before
+changing knowledge on either a first generation or a refresh, the skill
+resolves `oat-dispatch-subagents` and `subagent-orchestration`, then checks that
+the active Claude, Codex, or Cursor provider can launch its mapper projection.
+A missing dispatch skill reports the utility-pack install/update commands; a
+missing mapper projection reports the workflows-pack commands or `oat sync`.
+An unsupported host or declined authorization reports that limitation without
+irrelevant install advice. Every failure stops before cleanup, thin-index
+creation, or a write probe. Needs an active OAT project: no. If a knowledge
+directory already exists, choose whether to refresh it or skip the run.
+Refresh removes only regular Markdown files marked `oat_generated: true` and
+regenerates the eight named outputs. Hand-written notes survive; an unmarked
+expected-output collision stops the run before deletion so you can decide how
+to preserve it. Symlinked knowledge directories and output collisions are
+refused.
 **Example scenario:** A new teammate needs to understand which packages own
 the CLI, how shared configuration reaches applications, and which test
@@ -232,16 +239,13 @@ index is an onboarding and retrieval aid, not a declaration that all
 architecture concerns have been fixed or that every future question is
 answered.
-**What it does without asking:** The only question is refresh-or-skip when
-knowledge files already exist. Otherwise it creates `.oat/repo/knowledge/`,
-starts a test subagent and then four `oat-codebase-mapper` subagents in the
-background, and writes the knowledge files. It then runs
-`oat internal commit-paths` on your current branch with the exact generated
-output/deletion paths and enabled hooks. Unrelated staged and unstaged work
-remains intact.
-Afterwards it records the run in `.oat/tracking.json` and regenerates the
-`.oat/state.md` dashboard with `oat state refresh`; those two files are not
-part of the commit. It does not push.
+**What it does without asking:** The run resolves a usable mapper route before
+changing knowledge and may ask once for authorization covering the write probe
+and four mapper lanes. It offers read-only fallback only after a launched probe
+verifies that writes are blocked. It preserves manual notes while preparing and
+generating the eight owned outputs. It commits only the exact owned paths with
+hooks enabled, leaving unrelated staged and unstaged work intact, then updates
+the tracking dashboard without pushing.
 **Expected output:** Eight files under `.oat/repo/knowledge/`:
 `project-index.md`, `stack.md`, `architecture.md`, `structure.md`,

package/assets/docs/workflows/advanced/workflow-gates.md CHANGED Viewed

@@ -299,7 +299,13 @@ milestone's `plan` carrier, `oat_milestone_gates[mNN].plan`, written with
 for a re-alignment amendment it is the only approval evidence. The implement
 exit gate at milestone closeout writes `oat_milestone_gates[mNN].exit` (never
 `oat_implement_exit_gate`, which goal uses only at terminal closeout). It runs
-before the milestone's integrated review and runs again after queued fixes.
+the configured command verbatim with `--review-scope final`, before the
+milestone's integrated review, and runs again after queued fixes. Its own
+Type `code`, Invocation `gate` Reviews row and artifact count as bookkeeping
+only when the row's non-placeholder Reviewed Head equals the carrier's
+`reviewed_head` and the artifact's project-relative path is under `reviews/`
+(including `reviews/archived/`). That row never serves as the integrated review
+or unlocks delivery fields, and no placeholder row is required before the gate runs.
 `oat project delivery check` reports the exit carrier's freshness, and
 `oat project delivery refresh` marks it stale when delivery evidence no longer
 holds.

package/assets/docs/workflows/projects/closeout/closeout-skills.md CHANGED Viewed

@@ -143,7 +143,9 @@ deliveries exist and registers only when
 `oat project delivery check --subject <mNN|dNN>` reports `status: ok`. It
 commits a `registering` registry entry before creating anything, then creates
 the PR, or on resume attaches the single PR that `gh pr list` finds for the
-head branch (more than one match stops at `oat-project-reconcile`). It then
+head branch (more than one match stops at `oat-project-reconcile`). For a
+stacked milestone, registration instead records `kind: stack` and attaches its
+existing layer pull requests base to tip; it never creates a stack. It then
 records the member, `status: open`, and `oat_milestone_status: delivered`, and
 appends one structural project-log entry. Stale review or exit-gate evidence
 stops before registration: for the active milestone the skill writes
@@ -190,10 +192,10 @@ generates or refreshes a missing or stale `summary.md` through
 decision-record promotion also happen. It then writes the PR description,
 pushes the current branch with `git push -u origin`, and runs
 `gh pr create`. For a synced project, it also publishes the project artifacts
-with `oat project push` before and after creating the PR. Besides the PR title
-and base branch when you did not pass them, the only question it asks is
-whether to continue when the latest final review has not passed. It never
-merges the PR.
+with `oat project push` before and after creating the PR. When you do not pass
+a PR title or base branch, it fills them from the defaults without asking. The
+only question it asks is whether to continue when the latest final review has
+not passed. It never merges the PR.
 **Goal projects:** in a goal project this skill is the terminal delivery
 registration owner, not a second project PR. It runs its own registration step
@@ -582,7 +584,8 @@ writes a PR description file, clears the active
 project (or keeps it until an archive succeeds), commits the completion
 bookkeeping, and pushes it. A yes to the PR question, or
 `workflow.createPrOnComplete: true` when no PR is tracked, creates a new PR
-against `main`. If a PR is already open, the skill updates its description
+against the base branch resolved from `git.defaultBranch` (default `main`), the
+same way `oat-project-pr-final` resolves it. If a PR is already open, the skill updates its description
 with `gh pr edit` when archiving or for a synced project. Archives keep no
 `pr/` directory, so when archiving the skill carries the regenerated PR body in
 a temporary file until the PR is created or updated; a run that resumes an

package/assets/docs/workflows/projects/execution/execution-skills.md CHANGED Viewed

@@ -76,8 +76,7 @@ is ready.
 The number of fix attempts after a failed review comes from
 `oat_orchestration_retry_limit` in the project's `state.md` (default 2, range
-0–5). The skill's argument hint also lists `--retry-limit`, but no step reads
-that flag, so passing it changes nothing.
+0–5).
 **Prerequisites:** Select an existing project with an approved, complete
 `plan.md` whose readiness points to `oat-project-implement`. The lifecycle

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

@@ -569,8 +569,9 @@ worktree registrations before materializing or updating the current checkout.
 Default execution needs the root-to-phase-agent depth. `agents.max_depth >= 2`
 is useful capability for optional phase-agent nesting, but it is not a default
-topology preflight requirement. OAT may still materialize a higher depth floor
-so recon or specialist fanout is available when justified.
+topology preflight requirement. When `agents.max_depth` is absent, sync adds
+`2` so recon or specialist fanout is available when justified; an explicit
+value is kept.
 ## Accepted Launches

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

@@ -612,7 +612,9 @@ from a first–last range. `oat-project-pr-progress` registers a delivery only
 when `oat project delivery check --subject <mNN|dNN>` reports `status: ok`,
 writing the `oat_deliveries` entry (`registering`) before it creates the pull
 request so an interrupted run resumes by `gh pr list` instead of opening a
-duplicate.
+duplicate. For a stacked milestone, registration instead records `kind: stack`
+and attaches its existing layer pull requests base to tip; it never creates a
+stack.
 **Freshness.** Evidence keeps the revision actually reviewed. Commits after it
 count as bookkeeping only when they touch the project's tracking files in

package/assets/public-package-versions.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.37",
-  "docs-config": "0.3.37",
-  "docs-theme": "0.3.37",
-  "docs-transforms": "0.3.37"
+  "cli": "0.3.39",
+  "docs-config": "0.3.39",
+  "docs-theme": "0.3.39",
+  "docs-transforms": "0.3.39"
 }

package/assets/skills/oat-project-brief/SKILL.md CHANGED Viewed

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.0.3
+  version: 1.0.4
 ---
 # Brief Project

package/assets/skills/oat-project-brief/references/brief-contract.md CHANGED Viewed

@@ -531,7 +531,8 @@ root commits shared routing, registry, gate and acceptance records.
 `oat_deliveries` entries carry `delivery_id` (`dNN`, unique), `milestone`, a
 `scope` frozen on registration, the agreed `endpoint` (`open | merged`),
-`kind: pr`, `status` (`registering | open | at_endpoint | superseded`), the
+`kind: pr | stack`, `status`
+(`registering | open | at_endpoint | superseded`), the
 supersession links `superseded_by` and `covers_scope_of`, an additive
 `corrects_delivery_id`, persisted `lookup` keys (`repository`, `head_branch`,
 `head_sha_at_registration`), `members` (`url`, `base`, `reviewed_head`,
@@ -540,12 +541,26 @@ supersession links `superseded_by` and `covers_scope_of`, an additive
 binding `exit_gate`, and the first observed `endpoint_attainment`.
 - **Idempotent registration.** The registration owner writes the entry with
-  `status: registering` and its `lookup` keys and commits before creating the
-  pull request, then records the URL and `status: open`. A `registering` entry
-  on resume runs `gh pr list --repo <repository> --head <head_branch> --state
-all --json url,headRefOid`: exactly one match is attached without creating a
-  duplicate; zero matches create once; more than one stops and routes to
-  `oat-project-reconcile`.
+  `status: registering` and its `lookup` keys. For `kind: pr`, it commits
+  before creating the pull request, then records the URL and `status: open`; on
+  resume, `gh pr list --repo <repository> --head <head_branch> --state all
+--json url,headRefOid` attaches exactly one match, creates once for zero
+  matches, and stops for more than one. For `kind: stack`, registration is
+  attach-only: the `registering` write records every existing member URL in
+  base-to-tip order, and resume re-checks each URL rather than creating a
+  stack. For a PR lookup, more than one stops and routes to
+  `oat-project-reconcile`; a missing, closed-unmerged or re-targeted stack
+  layer follows the same stop-and-route.
+- **Stacked deliveries.** A stack records members base to tip. For a configured
+  code carrier bound to a reviewed head, the exit carrier is judged against
+  the tip member's observed head, and every lower member's observed head must
+  be an ancestor of the tip (`stack-order` otherwise). Null carriers and
+  unreviewed-resolution carriers (`no_gate`, `project_disabled`) are evaluated
+  exactly as for `kind: pr`; the integrated review remains per member.
+  Post-review bookkeeping lands on the tip member's branch, because a commit
+  on a lower layer changes upper members' bases and stales their review. A stack
+  that fails the configured-carrier order check is never repaired in place:
+  replace it through supersession with `covers_scope_of`.
 - **Prerequisites.** Before registration the owner runs
   `oat project delivery refresh --project <path>` and
   `oat project delivery check --project <path> --subject <mNN|dNN> --json`; it
@@ -562,7 +577,8 @@ all --json url,headRefOid`: exactly one match is attached without creating a
   share their member pull request (`gh` allows one open pull request per head
   and base), so one member URL may appear in several deliveries. Coverage
   judges each delivery's own frozen scope and bound evidence, never the shared
-  member alone; `oat_pr_url` and `oat_pr_status` project the latest member.
+  member alone; `oat_pr_url` and `oat_pr_status` project the latest member,
+  which is the tip member for a stack.
 - **Evidence capture.** The exit-gate result accepted for the delivery is
   persisted as its `exit_gate` with the delivery evidence; overwriting the
   milestone's working carrier for a correction never relabels another
@@ -600,7 +616,14 @@ changes only permitted bookkeeping:
   the evidence being recorded or archived, and, for a delivery whose member
   pull request is shared (12.7, Shared members), the review artifacts recorded
   for the deliveries that share it; each delivery is still judged on its own
-  frozen scope, reviewed revisions and `exit_gate`. `summary.md` is derived
+  frozen scope, reviewed revisions and `exit_gate`. The artifact of a Reviews
+  row with Type `code`, Invocation `gate`, and a non-placeholder Reviewed Head
+  equal to the judged carrier's `reviewed_head` is also admitted in evidence
+  scopes built for that carrier (its review and exit evaluations), provided
+  its project-relative artifact path is under `reviews/` (including
+  `reviews/archived/`). The gate row is never integrated-review evidence and
+  its artifact never joins a delivery's own review-artifact set, so it cannot
+  unlock set-once fields. `summary.md` is derived
   institutional memory, never the authority for outcomes, approach,
   constraints, decisions or endpoint, which live in the brief; any change to
   it is bookkeeping. Path membership alone is insufficient for the other

package/assets/skills/oat-project-complete/SKILL.md CHANGED Viewed

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, AskUserQuestion
 metadata:
-  version: 1.7.18
+  version: 1.7.19
 ---
 # Complete Project
@@ -1139,11 +1139,17 @@ carries the same Steps 0.5 through 4 contract:
 1. **Archive residual review artifacts** — already handled in Step 4.
 2. **Validate required artifacts** — read available project artifacts (`plan.md`, `implementation.md`, `spec.md`, `design.md`, `discovery.md`) based on workflow mode from `state.md`.
 3. **Check final review status** — already checked in Step 3.1. Use the result, don't re-check.
-4. **Collect project summary** — if `summary.md` exists (from Step 3.5), use it as the primary source for the PR description's Summary section (per `oat-project-pr-final` Step 3.0). Read remaining artifacts and collect git context:
+4. **Collect project summary** — if `summary.md` exists (from Step 3.5), use it as the primary source for the PR description's Summary section (per `oat-project-pr-final` Step 3.0). Read remaining artifacts and collect git context. Resolve `BASE_BRANCH` here with the same chain the final PR skill uses (this skill takes no base argument); Step 11 reuses it:
 ```bash
 BRANCH=$(git rev-parse --abbrev-ref HEAD)
-MERGE_BASE=$(git merge-base origin/main HEAD 2>/dev/null || git merge-base main HEAD 2>/dev/null || echo "")
+# Resolution chain: OAT config > git remote > fallback
+BASE_BRANCH=$(oat config get git.defaultBranch 2>/dev/null || true)
+if [ -z "$BASE_BRANCH" ]; then
+  BASE_BRANCH=$(git rev-parse --abbrev-ref origin/HEAD 2>/dev/null | sed 's|origin/||' || true)
+fi
+BASE_BRANCH="${BASE_BRANCH:-main}"
+MERGE_BASE=$(git merge-base "origin/$BASE_BRANCH" HEAD 2>/dev/null || git merge-base "$BASE_BRANCH" HEAD 2>/dev/null || echo "")
 if [[ -n "$MERGE_BASE" ]]; then
   git log --oneline "${MERGE_BASE}..HEAD"
@@ -1628,17 +1634,21 @@ Steps:
    description artifact at `PR_DESCRIPTION_PATH`.
 2. For the non-archive artifact, write the stripped body to a temporary file (remove all lines from the opening `---` through the closing `---`, inclusive).
 3. Verify the temp file does not start with YAML frontmatter keys.
-4. Create the PR from the branch already pushed in Step 10:
+4. Reuse the `BASE_BRANCH` resolved in Step 7 item 4. A Step 3.65 resume
+   route that skipped Step 7 has not set it: run that step's resolution block
+   first. Never create the PR with an empty base.
+5. Create the PR from the branch already pushed in Step 10:
 ```bash
-gh pr create --base main --title "{title}" --body-file "$TMP_BODY"
+: "${BASE_BRANCH:?BASE_BRANCH is unset; run the Step 7 base-branch resolution first}"
+gh pr create --base "$BASE_BRANCH" --title "{title}" --body-file "$TMP_BODY"
 ```
-5. Clean up the temp file, including `PR_BODY_FILE`, once the PR is created.
+6. Clean up the temp file, including `PR_BODY_FILE`, once the PR is created.
    When `gh` is missing or `gh pr create` fails, keep it and report its path
    in Step 12.
-Do not assume `gh` is installed; if missing, instruct manual PR creation using the file contents.
+Do not assume `gh` is installed; if missing, instruct manual PR creation using the file contents and note the resolved base branch (`BASE_BRANCH`).
 ### Step 11.5: Sync Open-PR Description on GitHub (Conditional)

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

@@ -2,12 +2,12 @@
 name: oat-project-implement
 description: Use when the user explicitly asks to implement an approved OAT plan — e.g. "implement the plan", "start implementation", or accepts a previously offered implementation step. Do NOT auto-invoke just because plan.md is ready. Dispatches one phase implementer per phase, owns independent phase review and bounded fix routing, and supports plan-declared worktree-isolated parallel phases.
 oat_gateable: true
-argument-hint: '[--retry-limit <N>] [--dry-run]'
+argument-hint: '[--dry-run]'
 disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat:*), Bash(oat project log:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 2.3.22
+  version: 2.3.24
 ---
 # Implementation Phase

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

@@ -59,10 +59,20 @@ recovery owner for that carrier:
 1. **Exit gate before the integrated review.** Resolve and run the configured
    implement exit gate exactly as Step 14 does (`oat gate resolve
 oat-project-implement --project "$PROJECT_PATH" --json`, canonical
-   `oat --json gate review`, receive eligibility, `onFailure`, `maxAttempts`),
-   scoped to the milestone's ordered phase set. The goal ladder exception
-   applies: this gate precedes the integrated delivery review, and queued
-   fixes require it to run again.
+   `oat --json gate review`, receive eligibility, `onFailure`, `maxAttempts`).
+   Run the configured command verbatim, including its
+   `--review-scope final`; do not rewrite that argument to the milestone's
+   phase IDs. The carrier subject still records the milestone's ordered phase
+   set. The goal ladder exception applies: this gate precedes the integrated
+   delivery review, and queued fixes require it to run again. The gate's own
+   Reviews row is admitted as carrier bookkeeping only when it has Type
+   `code`, Invocation `gate`, and a non-placeholder Reviewed Head equal to the
+   carrier's `reviewed_head`; its non-placeholder artifact is admitted with
+   that row only when its project-relative path is under `reviews/` (including
+   `reviews/archived/`). This row never serves as the milestone or delivery
+   integrated review and never joins a delivery's own evidence artifacts, so
+   it cannot unlock set-once delivery fields. Do not create a placeholder
+   Reviews row before the gate runs.
 2. **Write the milestone carrier.** Record `oat_milestone_gates[mNN].exit`
    with the gate approval record core, `resolution` (`configured`, `no_gate`,
    or `project_disabled`), `subject: { kind: code, scope: [ordered phase

package/assets/skills/oat-project-pr-final/SKILL.md CHANGED Viewed

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(awk:*), Bash(gh:*), Bash(git:*), Bash(mktemp:*), Bash(oat:*), Bash(rm:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.6.12
+  version: 1.6.13
 ---
 # Project PR (Final)
@@ -90,7 +90,7 @@ oat-project-pr-final title="feat: add review loop"
 ### Without arguments
-Run the `oat-project-pr-final` skill and it will ask for:
+Run the `oat-project-pr-final` skill and it fills these from the defaults below without asking, then pushes the branch and creates the PR:
 - PR title
   - default when a known ticket is associated: `[{TICKET-NUM}] {Descriptive Project Title}`