@open-agent-toolkit/cli 0.1.40 → 0.1.42

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.0.2
+version: 1.0.3
 description: Implements a single plan phase end-to-end — reads artifacts once, executes tasks sequentially, commits per task, self-reviews, and returns a structured summary. Dispatched by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: cyan
@@ -46,7 +46,7 @@ For Codex, `provider-default` means the base/unpinned role follows Codex configu
 
 If `mode: fix`, the block also includes:
 
-- **review_artifact**: Path to the review artifact from the reviewer (e.g., `reviews/p02-review-YYYY-MM-DD.md`)
+- **review_artifact**: Path to the review artifact from the reviewer (e.g., `reviews/p02-review-2026-01-28T140322Z.md`)
 - **findings**: Critical and Important findings list
 - **prior_summary**: Your own prior `implement` run summary (what was previously built)
 

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.1.3
+version: 1.1.4
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write
 color: yellow
@@ -287,19 +287,21 @@ Write the review artifact to the specified path.
 
 **File path format:**
 
-- Phase review: `{project}/reviews/pNN-review-YYYY-MM-DD.md`
-- Final review: `{project}/reviews/final-review-YYYY-MM-DD.md`
-- Task review: `{project}/reviews/pNN-tNN-review-YYYY-MM-DD.md`
-- Range review: `{project}/reviews/range-review-YYYY-MM-DD.md`
+Use a seconds-precision **UTC** timestamp token (`YYYY-MM-DDTHHMMSSZ`, from `date -u +%Y-%m-%dT%H%M%SZ` — the `-u` and the trailing `Z` are mandatory) so same-scope, same-day re-reviews never collide and always sort by recency. Never emit a local-time or `Z`-less timestamp: a timezone-less datetime mis-orders artifacts written by agents in different timezones.
 
-**If file already exists for today:** add `-v2`, `-v3`, etc.
+- Phase review: `{project}/reviews/pNN-review-YYYY-MM-DDTHHMMSSZ.md`
+- Final review: `{project}/reviews/final-review-YYYY-MM-DDTHHMMSSZ.md`
+- Task review: `{project}/reviews/pNN-tNN-review-YYYY-MM-DDTHHMMSSZ.md`
+- Range review: `{project}/reviews/range-review-YYYY-MM-DDTHHMMSSZ.md`
+
+The timestamp token must match the `oat_generated_at` frontmatter for the same run. In the unlikely event a file with that exact second already exists, append `-v2`, `-v3`, etc.
 
 **Review artifact template:**
 
 ````markdown
 ---
 oat_generated: true
-oat_generated_at: YYYY-MM-DD
+oat_generated_at: YYYY-MM-DDTHH:MM:SSZ
 oat_review_scope: { scope }
 oat_review_type: { code|artifact|analysis }
 oat_review_invocation: { manual|auto|gate }
@@ -308,7 +310,7 @@ oat_project: { project-path }
 
 # {Code|Artifact|Analysis} Review: {scope}
 
-**Reviewed:** YYYY-MM-DD
+**Reviewed:** YYYY-MM-DDTHH:MM:SSZ
 **Scope:** {scope description}
 **Files reviewed:** {N}
 **Commits:** {range or count}

package/assets/docs/cli-utilities/backlog-lifecycle.md

@@ -0,0 +1,61 @@
+---
+title: Backlog Lifecycle
+description: The states a file-backed backlog item moves through, how oat backlog archive closes it out atomically, and how oat pjm doctor catches lifecycle drift.
+---
+
+# Backlog Lifecycle
+
+The file-backed backlog under `.oat/repo/pjm/backlog/` tracks work as one Markdown file per item. This page describes the lifecycle those items move through, the atomic close-out command that keeps the pieces in sync, and the diagnostics that flag drift when a close-out is done by hand and something is missed.
+
+For the flag-by-flag command reference, see [`oat backlog archive`](config-and-local-state.md#oat-backlog-archive). For the two-layer PJM surface that hosts the backlog, see [Tool Packs](tool-packs.md#install-vs-initialize).
+
+## Where a backlog item lives
+
+- **`items/<id>.md`** - active, file-backed records. Each carries frontmatter with a `status` and an `updated` timestamp.
+- **`archived/<id>.md`** - the resting place for closed-out items, preserving the full item file as history.
+- **`completed.md`** - a newest-first summary log of completed work, one line per entry (`YYYY-MM-DD — BL-YYMMDD-slug — Title — one-line outcome`).
+- **`index.md`** - the human-facing curated overview plus a managed, generated index table rebuilt from item frontmatter.
+
+## Item statuses
+
+An item's `status` frontmatter field is one of exactly four values:
+
+- `open` - captured, not yet started.
+- `in_progress` - actively being worked.
+- `closed` - completed.
+- `wont_do` - abandoned or intentionally declined.
+
+`closed` and `wont_do` are the two **terminal** statuses. These are the only valid values — never invent variants like `done`. A terminal item belongs in `archived/`, not `items/`.
+
+## Closing out an item
+
+When an item reaches a terminal state, close it out with the atomic command rather than editing files by hand:
+
+```bash
+# completed work
+oat backlog archive BL-260705-example --summary "shipped the thing"
+
+# abandoned work
+oat backlog archive BL-260705-example --wont-do --summary "superseded by BL-260706-other"
+```
+
+A single `oat backlog archive` run performs the whole close-out so its parts cannot drift apart:
+
+1. Sets the terminal `status` (`closed` by default, `wont_do` with `--wont-do`) and stamps `updated`.
+2. Appends a canonical newest-first entry to `completed.md`. `closed` items always get an entry (with a visible `TODO: summarize outcome` placeholder when `--summary` is omitted, so the gap stays visible); `wont_do` items get one only when you pass `--summary`.
+3. Moves `items/<id>.md` into `archived/` — with `git mv` inside a work tree, or a plain rename outside git.
+4. Regenerates the managed backlog index.
+
+The command is safe to re-run: an item already in `archived/` produces a no-op warning with no writes. An out-of-enum current status (for example a hand-set `done`) is a hard error that names the file, lists the valid statuses, and tells you how to recover. See the [command reference](config-and-local-state.md#oat-backlog-archive) for exit codes and the `--json` payload.
+
+## Catching lifecycle drift
+
+The manual close-out this command replaces is exactly where the two motivating repos drifted — an item was marked closed in frontmatter and summarized in `completed.md` but never moved to `archived/`, and one shipped with the invalid status `done`. `oat pjm doctor` (and therefore `oat doctor`, which aggregates the `pjm:*` checks) now surfaces that drift:
+
+- **`pjm:backlog_terminal_in_items`** (fail) - a `closed` or `wont_do` item is still sitting in `items/`. Fix: run `oat backlog archive <id>` to finish the move.
+- **`pjm:backlog_invalid_status`** (fail) - an item carries an out-of-enum or missing `status`. The message lists the offending file paths and the valid statuses.
+- **`pjm:backlog_archived_open`** (warn) - an `open` or `in_progress` item is in `archived/`, which usually means it was archived prematurely.
+- **`pjm:backlog_completed_unarchived`** (warn) - `completed.md` references an item whose file still lives in `items/`.
+- **`pjm:backlog_duplicate_id`** (fail) - the same `<id>.md` exists in both `items/` and `archived/`. `oat backlog archive` refuses to auto-resolve this (it would clobber the archived record), so the duplicate must be reconciled by hand.
+
+Doctor reports drift; it never auto-fixes. A human or agent runs `oat backlog archive` (or corrects the status) and re-runs doctor to confirm the backlog is clean again.

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -16,12 +16,59 @@ Use the `oat backlog` group when you want direct CLI support for the file-backed
 - `oat backlog init` - scaffold `.oat/repo/pjm/backlog/` with starter files and directories for a fresh repo
 - `oat backlog generate-id <title>` - generate a deterministic `BL-YYMMDD-slug` backlog ID from a title
 - `oat backlog generate-id <title> --created-at <timestamp>` - generate a reproducible ID for a known creation timestamp
+- `oat backlog archive <id>` - atomic close-out: set a terminal status, record the completion in `completed.md`, move the item into `archived/`, and regenerate the index in one step
 - `oat backlog regenerate-index` - rebuild the managed backlog index table from item frontmatter
 
 Backlog IDs are deterministic date+slug identifiers (`BL-YYMMDD-slug`) derived from the creation date and title, so two machines or worktrees produce the same ID for the same record without scanning the local checkout. The slug is capped at 30 characters at the last whole-word boundary (with trailing stop-words trimmed), so prefer concise, meaningful titles. Index regeneration is deterministic and safe to re-run when resolving an index merge conflict.
 
 Run `oat backlog init` first when the local backlog scaffold does not exist yet in a fresh repo. This command group is primarily used by the `oat-pjm-*` project-management skills, but it is also available directly when you need to inspect or repair backlog metadata by hand.
 
+For the end-to-end states an item moves through — and how `oat backlog archive` and `oat pjm doctor` keep the backlog honest — see [Backlog Lifecycle](backlog-lifecycle.md).
+
+### `oat backlog archive`
+
+`oat backlog archive <id> [--wont-do] [--summary <text>] [--json] [--backlog-root <path>]` performs the full close-out for a backlog item so status flip, completed-log entry, file move, and index regeneration never drift apart.
+
+**Arguments and flags:**
+
+- `<id>` (required) - the backlog item id (`BL-YYMMDD-slug`); the item file must live under `items/`.
+- `--wont-do` - close the item as `wont_do` instead of the default terminal status `closed`.
+- `--summary <text>` - one-line outcome summary recorded in `completed.md`.
+- `--backlog-root <path>` - override the backlog root (defaults to `.oat/repo/pjm/backlog`).
+- `--json` - emit the machine-readable result payload instead of human log lines.
+
+**Behavior:**
+
+- Validates the item's current `status` against the enum (`open | in_progress | closed | wont_do`); an out-of-enum value such as `done` is a hard error with a fix hint. Archiving is legal from any valid status — a `closed` item still in `items/` just gets its move finished.
+- Rewrites only the `status:` and `updated:` frontmatter lines (preserving any inline enum comment), then moves the item from `items/` to `archived/` with `git mv` inside a work tree, falling back to a plain rename (with a warning) outside git or if `git mv` fails.
+- `closed` archives always append a canonical newest-first `completed.md` entry (`YYYY-MM-DD — <id> — Title — summary`); when `--summary` is omitted the entry carries a visible `TODO: summarize outcome` placeholder. `wont_do` archives append an entry only when `--summary` is provided. A missing `completed.md` is scaffolded from the starter template; a missing `## Completed Items` heading is scaffolded with a warning.
+- Regenerates the managed backlog index after the move.
+- Idempotent: re-running on an item already in `archived/` is a no-op warning with no writes.
+
+**Exit codes:**
+
+- `0` - item archived, or already-archived no-op.
+- `1` - actionable error: unknown id (no file under `items/`) or an out-of-enum current status. The message names the file path, the valid statuses, and the fix.
+- `2` - reserved for unexpected system/runtime failures.
+
+**JSON payload (`--json`):**
+
+On success the payload is the archive result object:
+
+```json
+{
+  "id": "BL-260705-example",
+  "result": "archived",
+  "status": "closed",
+  "completedEntry": "written",
+  "movedTo": ".oat/repo/pjm/backlog/archived/BL-260705-example.md",
+  "indexRegenerated": true,
+  "warnings": []
+}
+```
+
+`result` is `archived` or `noop` (already archived); `completedEntry` is `written`, `scaffolded`, or `skipped` (e.g. a `wont_do` archive without `--summary`); `movedTo` is the destination path or `null`. On an actionable failure the payload is `{ "result": "error", "id": "<id>", "message": "<why + fix>" }`.
+
 For full project-management repo-reference setup, use [`oat pjm init`](tool-packs.md#install-vs-initialize). It scaffolds the two-layer PJM surface (`pjm/current-state.md`, `pjm/roadmap.md`, `reference/decisions/`, and AGENTS guides) and delegates the backlog sub-surface to `oat backlog init`.
 
 ## `oat decision ...`

package/assets/docs/cli-utilities/index.md

@@ -15,6 +15,7 @@ Use this section when you want bootstrap guidance, tool-pack lifecycle details,
 - [Tool Packs and Installed Assets](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
+- [Backlog Lifecycle](backlog-lifecycle.md) - Backlog item states, atomic close-out with `oat backlog archive`, and lifecycle drift detection in `oat pjm doctor`.
 - [Workflow Gates](workflow-gates.md) - Per-skill final commands and cross-runtime review dispatch with `oat gate`.
 
 ## What Lives Here

package/assets/docs/cli-utilities/workflow-gates.md

@@ -71,6 +71,61 @@ status when the configured threshold is met. `cross-provider-exec` does not do
 that interpretation; for generic prompts it still returns only the child process
 status.
 
+`oat-project-implement` uses `oat gate review` per phase when a project opts in
+via the `oat_phase_review_gate` plan frontmatter — a non-pausing gate that runs
+after each selected phase's standard reviewer passes. See
+[Reviews → Phase review gate](../workflows/projects/reviews.md#phase-review-gate)
+for the frontmatter contract and how passing versus blocking gates are
+dispositioned.
+
+### Gate completion signal
+
+The canonical "how do I know the gate finished" signal is the structured result
+`oat --json gate review` writes to stdout on exit, together with the process
+exit code. Orchestrators should run the gate synchronously and read that
+envelope — do **not** poll the `reviews/` directory for a file to appear or
+watch the provider process's log for liveness. Filesystem and log-liveness
+heuristics are unreliable: a re-gate can momentarily surface a prior round's
+artifact, and a lingering provider side-process says nothing about whether the
+review committed.
+
+Every terminal envelope carries a `runId` (unique per gate invocation) and,
+once an artifact exists, its `generatedAt` (the artifact's seconds-precision
+`oat_generated_at`), so a caller can correlate the result to the exact artifact
+and disambiguate re-gate rounds:
+
+| `status`                     | Exit | Meaning                                                   |
+| ---------------------------- | ---- | --------------------------------------------------------- |
+| `ok`                         | 0    | Review completed; gate passed at the threshold.           |
+| `blocked`                    | 1    | Review completed; findings at/above the threshold.        |
+| `review_failed`              | ≠0   | The provider target exited non-zero; no verdict.          |
+| `artifact_validation_failed` | 1    | Provider ran but the review artifact could not be parsed. |
+
+`ok` and `blocked` also include `outcome`, `artifactPath`, `counts`, `scope`,
+and `handoff`. Treat any status other than `ok`/`blocked` as an operational
+failure, not a passing gate.
+
+**Drive gates through `oat gate review`, not raw provider invocation.** An
+orchestrator that hand-rolls the review (for example, calling
+`codex exec … oat-project-review-provide <scope>` directly) and then watches
+`reviews/` for a file is reimplementing — less reliably — what the CLI already
+does: `oat gate review` snapshots the reviews directory, dispatches the
+provider, and attributes the produced artifact by content hash, so it is immune
+to a stale file lingering from a prior round. It works standalone, not only
+inside the `oat-project-implement` auto-loop — a one-off final review is just:
+
+```bash
+oat --json gate review \
+  --project "$PROJECT_PATH" \
+  --review-type code \
+  --review-scope final \
+  --exit-nonzero-on important \
+  'Use oat-project-review-provide code final to review the current project'
+```
+
+Read the resulting envelope and exit code; that is the whole completion
+contract.
+
 ## Exec targets
 
 `oat gate cross-provider-exec` chooses from `workflow.gates.execTargets`.

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

@@ -22,6 +22,7 @@ Instruction sync is currently project-only.
 - It scans the current repository recursively.
 - It supports nested directories all the way down the tree.
 - It skips provider-irrelevant or local-only roots such as `.git`, `.oat`, `.worktrees`, and `node_modules`.
+- Exception: `.oat/repo/**` is scanned even though the rest of `.oat/` is skipped, so the curated `AGENTS.md` files there (repo root guidance, `pjm/`, `reference/`) get their sibling `CLAUDE.md` shims managed and validated like any other directory. The rest of `.oat/` (`templates/`, `projects/`, `sync/`) stays excluded.
 - It does not scan user-level provider roots such as `~/.claude` in this release.
 
 ## Canonical Model

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

@@ -68,7 +68,7 @@ Notable commands introduced in the current CLI surface:
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#validating-plan-metadata).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
-- `oat gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings; produced gate reviews use `oat_review_invocation: gate` and still require `oat-project-review-receive` handoff before they are dispositioned.
+- `oat gate review <prompt...>` - run a stateful OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings; produced gate reviews use `oat_review_invocation: gate` and still require `oat-project-review-receive` handoff before they are dispositioned. With `--json`, the result envelope on exit is the canonical completion signal — `status` (`ok` | `blocked` | `review_failed` | `artifact_validation_failed`), `runId`, `generatedAt`, `artifactPath` — so orchestrators should read it rather than poll the filesystem. Runs standalone (e.g. `--review-scope final`), not only inside `oat-project-implement`. See [Workflow Gates → Gate completion signal](../cli-utilities/workflow-gates.md#gate-completion-signal).
 - `oat gate cross-provider-exec <prompt...>` - choose an available exec target while avoiding the current runtime by default, then run the prompt with the chosen target's configured base command and exit with the child status.
 
 ## `oat config` surface flags

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

@@ -57,6 +57,7 @@ See [Project Splitting](splitting.md) for the full parent/child model.
 
 - `oat_plan_hill_phases` — list of phase IDs to pause at for HiLL checkpoints.
 - `oat_plan_parallel_groups` — declares which phases may execute concurrently in worktrees. See below.
+- `oat_phase_review_gate` — opt-in non-pausing external review gate that runs after a phase's standard reviewer passes. See below.
 
 #### oat_plan_parallel_groups
 
@@ -85,6 +86,27 @@ Each inner array is a group of phases that execute concurrently in their own wor
 
 Before dispatching, `oat-project-implement` invokes `oat project validate-plan --project-path "${PROJECT_PATH}"`. Non-zero exit blocks the run. See [CLI Reference](../../reference/cli-reference.md) and [Implementation Execution](implementation-execution.md) for details.
 
+#### oat_phase_review_gate
+
+Enable an optional, non-pausing external review gate that runs after each selected phase's standard reviewer passes and its bookkeeping is committed:
+
+```yaml
+oat_phase_review_gate:
+  enabled: true
+  phases: [] # empty or omitted = every implementation phase
+  review_type: code
+  exit_nonzero_on: important
+```
+
+**Semantics:**
+
+- Missing, `null`, or `enabled: false` → disabled (default). `enabled: true` activates the gate.
+- `phases` → optional. Empty or missing runs the gate after every implementation phase; a populated list restricts it to those phase IDs, each of which must exist in the plan body.
+- `review_type` → optional, defaults to `code`. Only `code` is supported for phase gates.
+- `exit_nonzero_on` → optional, defaults to `important`. One of `critical`, `important`, `medium`, `minor`. This is the blocking threshold: findings at or above it stop the phase; sub-threshold findings are dispositioned by the judgment sweep rather than ignored.
+
+A malformed gate stops the run before task execution rather than being silently disabled. The gate is independent of HiLL checkpoints and reuses the existing `oat gate review` target config — it does not hardcode a `--target`. See [Reviews → Phase review gate](reviews.md#phase-review-gate) for the runtime behavior and disposition rules.
+
 ## Reference artifacts
 
 - `.oat/templates/*.md`

package/assets/docs/workflows/projects/hill-checkpoints.md

@@ -10,6 +10,8 @@ OAT supports two checkpoint classes:
 - Workflow phase checkpoints
 - Plan phase checkpoints
 
+The [phase review gate](reviews.md#phase-review-gate) (`oat_phase_review_gate`) is a separate, non-pausing mechanism — it does not pause on a passing gate and never modifies the HiLL keys below (`oat_hill_completed`, `oat_plan_hill_phases`).
+
 ## Workflow checkpoints (`state.md`)
 
 Frontmatter keys:

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

@@ -187,7 +187,8 @@ For each phase in the plan (whether sequential or inside a parallel group):
 5. **Parse the verdict:** zero Critical + zero Important findings → `pass`; otherwise `fail`.
 6. **On fail, run the bounded fix loop** (see below).
 7. **Update artifacts** (`implementation.md`, `plan.md` review row, `state.md`) and make the mandatory bookkeeping commit.
-8. **HiLL checkpoint** if the phase id is listed in `oat_plan_hill_phases`.
+8. **Phase review gate** — when `oat_phase_review_gate` selects the phase, run the optional non-pausing external gate (`oat gate review`) after the step 7 bookkeeping commit and before the HiLL check. A passing gate continues automatically; a blocking gate is received and fixed, reusing the bounded fix loop's `oat_orchestration_retry_limit`. See [Reviews → Phase review gate](reviews.md#phase-review-gate).
+9. **HiLL checkpoint** if the phase id is listed in `oat_plan_hill_phases`.
 
 ### Bounded fix loop
 

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

@@ -107,6 +107,23 @@ Auto-triggered reviews use `oat_review_invocation: auto` in the review artifact
 
 This feature is opt-in and disabled by default. When disabled, the manual `oat-project-review-provide` workflow applies.
 
+## Phase review gate
+
+The phase review gate is an optional, **non-pausing** external review gate that runs after a phase's standard per-phase reviewer passes and the phase bookkeeping is committed. Where the Tier 1 reviewer is an in-session self-review, the gate calls `oat gate review` against the configured cross-provider target, adding an independent perspective before implementation moves to the next phase. It is enabled per-project through `plan.md` frontmatter (`oat_phase_review_gate`; see [Project Artifacts](artifacts.md#oat_phase_review_gate) for the field shape and validation).
+
+It is independent of [HiLL checkpoints](hill-checkpoints.md): a passing gate does not pause, and the gate never touches `oat_hill_completed`, `oat_plan_hill_phases`, or `oat_auto_review_at_hill_checkpoints`.
+
+Gate-produced review artifacts use `oat_review_invocation: gate` in frontmatter (the third invocation marker alongside `manual` and `auto`). The gate verdict — controlled by `exit_nonzero_on` (default `important`) — decides whether the **phase stops**; it does not decide whether sub-threshold findings are ignored. Either way the produced artifact is consumed by `oat-project-review-receive`, autonomously and without user prompts, so findings never evaporate:
+
+- **Passing gate** (no findings at or above the threshold): receive runs a non-pausing **judgment sweep**. It makes a per-finding decision for each Medium/Minor — defer to final review (the default, recorded so [final review](#phase-and-final-review) resurfaces it), address now (only for small, contained, low-risk fixes, which do **not** re-trigger the standard reviewer or re-gate the phase), or reject with rationale — then archives the artifact. Address-now is an exception, not the norm; if such a fix reveals a Critical/Important concern it escalates to the blocking path.
+- **Blocking gate** (one or more findings at or above the threshold): receive converts findings to fix tasks and implementation re-runs the standard reviewer and the gate for the phase. These block → fix → re-gate rounds are bounded by `oat_orchestration_retry_limit` (default `2`); exhausting the bound stops a sequential run or excludes the phase in a parallel group, matching the standard fix loop's terminal handling.
+
+Gate-originated artifacts (`oat_review_invocation: gate`) are excluded from the same-scope review-cycle cap in `oat-project-review-receive`. The cap measures failed fix cycles of the standard review loop, so counting gate artifacts would trip it on artifact volume rather than real fix rounds.
+
+When a phase is re-gated multiple times, each round produces a distinct review artifact — filenames and `oat_generated_at` are seconds-precision, so rounds never collide and `oat review latest` resolves the newest. An orchestrator should know a gate finished from the `oat --json gate review` result envelope on process exit (`status`, `runId`, `generatedAt`), not by watching the `reviews/` directory or the provider's log; see [Gate completion signal](../../cli-utilities/workflow-gates.md#gate-completion-signal).
+
+This feature is opt-in and disabled by default (missing or `enabled: false`). For a parallel phase group, selected gates run after fan-in and bookkeeping, one per merged phase in plan order.
+
 ## Auto artifact-review loops
 
 Generated planning and analysis artifacts have a separate review loop from code/phase reviews.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.40",
-  "docs-config": "0.1.40",
-  "docs-theme": "0.1.40",
-  "docs-transforms": "0.1.40"
+  "cli": "0.1.42",
+  "docs-config": "0.1.42",
+  "docs-theme": "0.1.42",
+  "docs-transforms": "0.1.42"
 }

package/assets/skills/oat-pjm-review-backlog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-review-backlog
-version: 1.3.0
+version: 1.4.0
 description: Use when prioritizing the file-backed repo backlog or evaluating roadmap alignment. Produces value-effort ratings, dependency mapping, and execution recommendations.
 argument-hint: '[backlog-root] [--roadmap=<path>] [--output=<path>]'
 disable-model-invocation: true
@@ -48,12 +48,13 @@ When executing this skill, provide lightweight progress feedback so the user can
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before multi-step work, print short step indicators, e.g.:
-  - `[1/6] Resolving backlog inputs…`
-  - `[2/6] Cataloging backlog items…`
-  - `[3/6] Reading codebase context…`
-  - `[4/6] Writing review document…`
-  - `[5/6] Summarizing recommendations…`
-  - `[6/6] (Optional) Priority-alignment walkthrough…` — only print after the operator accepts the offer in Step 9
+  - `[1/7] Resolving backlog inputs…`
+  - `[2/7] Cataloging backlog items…`
+  - `[3/7] Reading codebase context…`
+  - `[4/7] Writing review document…`
+  - `[5/7] Summarizing recommendations…`
+  - `[6/7] (Optional) Priority-alignment walkthrough…` — only print after the operator accepts the offer in Step 9
+  - `[7/7] (Optional) Refreshing project kickoff handoffs…` — only print after the operator agrees a kickoff stack in Step 10
 
 ## Arguments
 
@@ -225,6 +226,26 @@ If the operator declines, stop after the summary. Do not silently write or modif
 
 When referencing backlog items inside the priority-alignment doc, the **Reference Format Convention** still applies — link to the item file and pair the ID with a human-readable title.
 
+### Step 10: Refresh Project Kickoff Handoffs (Optional)
+
+When a priority-alignment pass concludes (Step 9), generate or refresh one **kickoff handoff** per item in the agreed kickoff stack. A handoff is a one-shot kickoff prompt — consumable context for turning a backlog item into a project, not durable documentation. The item file and `reference/` remain the source of truth. Handoffs live under `.oat/repo/pjm/handoffs/`; see that directory's `README.md` for the convention (generated by `oat pjm init`).
+
+This step mirrors the **Project Kickoff Handoffs** section of the pjm instruction template (`pjm/AGENTS.md`) — follow that section's semantics; do not invent divergent wording. It is **collaborative and human-gated**: kickoff-stack membership, lane count, and ordering are the operator's decisions from Step 9. Present them; do not choose them. Do not generate handoffs for parked or queued items until they are actually next.
+
+**When to run:** only after the operator has agreed a kickoff stack in the Step 9 walkthrough. If Step 9 was declined or produced no kickoff stack, skip this step.
+
+**For each item in the agreed kickoff stack**, write or refresh `.oat/repo/pjm/handoffs/<BL-id>.md` with:
+
+- the backlog item reference — its ID **and** human-readable title **and** path (never a bare ID);
+- the recommended project mode (`oat-project-quick-start` vs `oat-project-new`), including which artifacts (spec/design/plan) to pre-populate from existing research when it exists;
+- authoritative input pointers (research directories, decision records, code paths);
+- repo conventions and verification gates the item file does not restate;
+- a close-out section requiring (a) the **Backlog Lifecycle** — `oat backlog archive <id>` — executed in the same PR that ships the item, and (b) deletion of the handoff file (`git rm`) in that same PR.
+
+**Staleness:** if this alignment pass drops an item from the kickoff stack, delete its handoff (`git rm .oat/repo/pjm/handoffs/<BL-id>.md`) in the same pass rather than letting it drift.
+
+Every backlog item reference in a handoff — like every reference in review output and alignment docs — pairs the ID with its human-readable title per the **Reference Format Convention**. No bare IDs.
+
 ## Success Criteria
 
 - Every active backlog item file has a value-effort rating with rationale
@@ -234,4 +255,5 @@ When referencing backlog items inside the priority-alignment doc, the **Referenc
 - Output document follows the review template structure
 - Living review is written to `.oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review.md` (unless `--output` is explicitly overridden); dated snapshots, when emitted, live in the same `backlog/reviews/` directory and never under `.oat/repo/reviews/`
 - The operator is offered (but never forced into) a collaborative walkthrough that produces or updates `backlog/reviews/priority-alignment.md`; if the operator accepts, the file is written using the priority-alignment template and includes a Changelog entry for this pass; if the operator declines, no file is created or modified
+- When a priority-alignment pass produces an agreed kickoff stack, one handoff per kickoff-stack item is written or refreshed under `.oat/repo/pjm/handoffs/` (with item reference, recommended mode, input pointers, repo conventions/gates, and a close-out requiring the Backlog Lifecycle executed and the handoff deleted in the same shipping PR); handoffs for reprioritized-out items are deleted in the same pass; kickoff-stack membership, lane count, and ordering remain human decisions the skill presents rather than chooses
 - Every user-facing reference to a backlog item pairs the ID with a human-readable title (per the Reference Format Convention)

package/assets/skills/oat-pjm-update-repo-reference/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-pjm-update-repo-reference
-version: 1.2.0
+version: 1.3.0
 description: Use when repo reference artifacts need updating — roadmap, decision records, backlog status, or completed history. Frequently invoked at project completion, often chained from `oat-project-document`, to ensure active `.oat/repo/pjm/` state and durable `.oat/repo/reference/` records reflect what shipped.
 disable-model-invocation: false
 user-invocable: true
@@ -69,7 +69,11 @@ For recently completed or in-progress projects, read `discovery.md`, `spec.md`,
 Promote notable findings into one of:
 
 - Backlog item files under `.oat/repo/pjm/backlog/items/`
-- Completed summaries in `.oat/repo/pjm/backlog/completed.md`
+- Completed close-outs via `oat backlog archive <id>` (see Step 4) — the atomic
+  command flips the item's `status`, appends the canonical
+  `.oat/repo/pjm/backlog/completed.md` entry, moves the item file into
+  `archived/`, and regenerates the index in one step. Reserve hand-editing
+  `completed.md` for narrative touch-ups the command does not own.
 - Decision records under `.oat/repo/reference/decisions/`, created with
   `oat decision new "<title>"` (delegate to `oat-pjm-decision` for a guided
   capture). Do not hand-author decision files or write into a legacy
@@ -89,16 +93,32 @@ Update these files as applicable:
 4. `.oat/repo/pjm/backlog/items/*.md`
    - Add or update active backlog items as file-backed records.
 5. `.oat/repo/pjm/backlog/completed.md`
-   - Keep newest completed summaries first.
+   - Keep newest completed summaries first. Prefer letting `oat backlog archive <id>`
+     append the canonical entry (see below) over hand-editing.
 6. `.oat/repo/pjm/backlog/archived/*.md`
-   - Add rich historical item files only when a completed item needs preserved detail.
+   - Item files land here automatically when you run `oat backlog archive <id>`.
+     Only hand-add or enrich a file here when a completed item needs preserved
+     detail the command did not capture.
 7. `.oat/repo/reference/decisions/`
    - Create new decisions with `oat decision new` (see `oat-pjm-decision`); the
      command writes one `DR-YYMMDD-slug` record and regenerates the managed
      decision index. Do not hand-edit `reference/decisions/index.md` inside its
      managed markers.
 
-If you modify backlog item files or the completed archive structure, run:
+To close out a completed backlog item, run the atomic close-out command rather
+than moving files by hand:
+
+```bash
+oat backlog archive <id> --summary "one-line outcome"
+# abandoned work: oat backlog archive <id> --wont-do --summary "why"
+```
+
+This flips the item's `status` to a terminal value (`closed`/`wont_do` — never
+invent variants like `done`), stamps `updated`, appends the canonical
+newest-first `completed.md` entry, moves the item file from `items/` into
+`archived/`, and regenerates the managed index in one step. Only when you edit
+backlog files by hand outside this command (curated overview text, an enriched
+`archived/` record) re-run the index regeneration:
 
 ```bash
 oat backlog regenerate-index