@open-agent-toolkit/cli 0.3.37 → 0.3.38

package/assets/bundle-metadata.json

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

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

@@ -205,8 +205,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 +214,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/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/skills/repo-improve.md

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

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

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

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

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

@@ -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.38",
+  "docs-config": "0.3.38",
+  "docs-theme": "0.3.38",
+  "docs-transforms": "0.3.38"
 }

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

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

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

@@ -7,7 +7,7 @@ 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.23
 ---
 
 # Implementation Phase

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

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 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.3.5
+  version: 1.3.6
 ---
 
 # Progress PR
@@ -399,9 +399,14 @@ entry is not registered yet and resumes at item 5.
    non-superseded registered delivery (item 3a), allocate the next unused
    `dNN` and write its entry with `status: registering`: `milestone`, the
    frozen `scope` (the ordered set), the agreed `endpoint` from the brief's
-   Delivery endpoint and authority, `kind: pr`, the persisted `lookup` keys
-   (`repository` from `gh repo view --json nameWithOwner`, `head_branch`,
-   `head_sha_at_registration` from `git rev-parse HEAD`), the
+   Delivery endpoint and authority, `kind: pr` for one pull request or
+   `kind: stack` when the milestone is delivered as an existing gh-stack, and
+   the persisted `lookup` keys (`repository` from
+   `gh repo view --json nameWithOwner`, `head_branch`,
+   `head_sha_at_registration` from `git rev-parse HEAD`). For a stack,
+   `lookup.head_branch` names the tip layer's branch and this same
+   `registering` write records every existing layer's `url` in base-to-tip
+   member order. Also record the
    `integrated_review` (`artifact`, `scope`, `bound_revisions`,
    `disposition: passed`) and the accepted `exit_gate` copied from the
    milestone's current exit carrier, so the gate result is captured with the
@@ -409,16 +414,22 @@ entry is not registered yet and resumes at item 5.
    and the predecessor's `superseded_by: <dNN>` in the same write; an additive
    correction writes `corrects_delivery_id` instead. Commit this registration
    record before creating anything.
-5. **Create or attach.** Generate the PR description (Steps 2–5), push the
-   branch, and create the pull request with the Step 6 commands. On resume
-   with a `registering` entry, first run
+5. **Create or attach.** For `kind: pr`, generate the PR description (Steps
+   2–5), push the branch, and create the pull request with the Step 6 commands.
+   On resume, first run
    `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`.
-6. **Record.** Write the member (`url`, `base`, `reviewed_head`),
-   `status: open`, `oat_milestone_status: delivered` for the active milestone,
-   `oat_pr_status: open`, `oat_pr_url`, and `oat_phase_status: pr_open`;
-   commit this registration bookkeeping.
+   create once. For `kind: stack`, attach the already-created pull requests;
+   never create a stack. On resume, re-check every recorded member URL with
+   `gh pr view`. 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.
+6. **Record.** For a stack, fill every member's `base` and `reviewed_head`;
+   for one pull request, write its member (`url`, `base`, `reviewed_head`).
+   Then write `status: open`, `oat_milestone_status: delivered` for the active
+   milestone, `oat_pr_status: open`, `oat_pr_url` (projected from the tip
+   member for a stack), and `oat_phase_status: pr_open`; commit this
+   registration bookkeeping.
 7. **Log.** After that registration commit, append exactly one structural
    entry and commit it in this same step:
    `oat project log append --project "$PROJECT_PATH" --structural --producer oat-project-pr-progress --ref <dNN> --idempotency-key "<goal-slug>-register-<dNN>" --body "Registered <dNN> for <mNN> (<ordered phase ids>) at <url>; <goal-slug>-register-<dNN>"`.