@open-agent-toolkit/cli 0.1.39 → 0.1.41

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/configuration.md

@@ -232,6 +232,8 @@ reading config keys directly:
 
 ```bash
 oat project dispatch-ceiling resolve --provider codex --json
+oat project dispatch-ceiling resolve --provider codex --role implementer --preferred medium --json
+oat project dispatch-ceiling resolve --provider claude --role implementer --preferred sonnet --orchestrator-tier sonnet --json
 oat project dispatch-ceiling resolve --provider claude --orchestrator-tier sonnet --json
 ```
 

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/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/workflows/projects/dispatch-ceiling.md

@@ -61,11 +61,20 @@ Before dispatching a subagent, the orchestrator calls:
 oat project dispatch-ceiling resolve --provider <provider> --role <implementer|reviewer> --preflight --json
 ```
 
+For implementer or fix dispatch, pass the runtime classification too. In Codex
+this is the preferred effort; in Claude it is the preferred model tier:
+
+```bash
+oat project dispatch-ceiling resolve --provider codex --role implementer --preferred medium --json
+oat project dispatch-ceiling resolve --provider claude --role implementer --preferred sonnet --json
+```
+
 The resolver:
 
 1. reads the concrete `providers.<provider>` value (config precedence, then project state) — **never the preset label**;
 2. looks up that provider's **adapter** in the provider ceiling registry;
-3. returns a per-provider result: `{ value, mode, mechanism, dispatchArgs }`.
+3. applies `--preferred` for implementer/fix dispatch, capping it against the ceiling;
+4. returns a per-provider result: `{ value, mode, mechanism, dispatchArgs, selection }`.
 
 `mode` is the honest enforcement status, computed right there and never persisted:
 
@@ -89,8 +98,8 @@ The same ceiling intent produces different — but honest — behavior per provi
 
 ### Why the mechanisms differ
 
-- **Codex** dispatches through **pinned, sync-time role variants**. Per-call reasoning-effort proved unreliable in practice, so OAT generates committed `oat-phase-implementer-{low..xhigh}` / `oat-reviewer-{low..xhigh}` role files and dispatches the variant matching the resolved effort.
-- **Claude** uses the **per-call Task `model` parameter**, which is reliable and bidirectional (a Sonnet orchestrator can dispatch an Opus subagent and vice-versa) and overrides agent frontmatter — so OAT simply passes `model` at dispatch and needs no variant files.
+- **Codex** dispatches through **pinned, sync-time role variants**. Per-call reasoning-effort proved unreliable in practice, so OAT generates committed `oat-phase-implementer-{low..xhigh}` / `oat-reviewer-{low..xhigh}` role files. Implementer/fix dispatch passes `--preferred` so `dispatchArgs.variant` matches the selected capped effort; reviewer dispatch uses the variant matching the resolved ceiling.
+- **Claude** uses the **per-call Task `model` parameter**, which is reliable and bidirectional (a Sonnet orchestrator can dispatch an Opus subagent and vice-versa) and overrides agent frontmatter. Implementer/fix dispatch passes `--preferred` as the preferred model tier and receives the capped selected `model`; reviewer dispatch uses the ceiling model. OAT needs no variant files.
 - **Unsupported providers** (any without a registered adapter) resolve to `unsupported` with `dispatchArgs: null`. The resolve command **returns cleanly and never blocks** — the ceiling is recorded as intent and applied if/when an adapter ships, while the provider runs at its own capabilities.
 
 A **provider adapter registry** is what lets these genuinely different mechanisms sit behind one resolver, so the lifecycle skills consume `dispatchArgs` without ever branching on provider.
@@ -104,6 +113,8 @@ The ceiling means slightly different things for the two dispatch roles:
 
 Both providers honor this distinction (Codex selects the matching variant; Claude passes the matching model).
 
+Generic sidecars such as built-in `explorer` are outside this implementer/reviewer/fix contract. They may run at provider default when they are read-only advisory helpers. In that case, dispatch logs should say `Preferred effort: provider-default`, `Selected effort: provider-default`, and `Effort axis: provider-default`; only log a concrete selected effort when the actual sidecar payload pins a reliable provider control.
+
 ## Verify-on-upgrade
 
 Only a request for a tier **above** the orchestrator's current tier risks a silent plan/entitlement fallback. So the adapter verifies the actually-dispatched model **only** on that upgrade path; capping down or staying lateral needs no check. OAT never logs `enforced` unless the requested control was actually honored.

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

@@ -108,9 +108,9 @@ Model and effort are separate axes. Each axis logs one of these states:
 - `not-applicable` — this host/API has no meaningful per-dispatch concept for that axis.
 - `host-auto` — exceptional; the host uses that axis internally but the orchestrator cannot read or pin it.
 
-In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and select `min(preferred, resolved_ceiling)`. The selected effort maps to the matching pinned role: `oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`, or `oat-phase-implementer-xhigh`. Reviewer dispatch uses the reviewer variant matching the resolved ceiling (`oat-reviewer-low|medium|high|xhigh`) for deterministic quality gates. Base/unpinned Codex roles are provider-default fallbacks; they should be logged as `provider-default`, not as inherited parent-session ceiling.
+In Codex, implementation and fix dispatch classify a preferred effort (`low`, `medium`, `high`, or `xhigh`) and pass it to `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <effort>`. The resolver selects `min(preferred, resolved_ceiling)` and returns the matching pinned role: `oat-phase-implementer-low`, `oat-phase-implementer-medium`, `oat-phase-implementer-high`, or `oat-phase-implementer-xhigh`. Reviewer dispatch uses the reviewer variant matching the resolved ceiling (`oat-reviewer-low|medium|high|xhigh`) for deterministic quality gates. Base/unpinned Codex roles are provider-default fallbacks; they should be logged as `provider-default`, not as inherited parent-session ceiling.
 
-In Claude Code, subagent model selection is a model axis when available and is capped by `workflow.dispatchCeiling.providers.claude` (or the compiled concrete value from a preset) or project `oat_dispatch_ceiling`. The separate effort axis is `not-applicable`.
+In Claude Code, implementation and fix dispatch classify a preferred model tier (`haiku`, `sonnet`, or `opus`) and pass it to `oat project dispatch-ceiling resolve --provider claude --role implementer --preferred <model> --orchestrator-tier <current-orchestrator-tier>`. The resolver selects `min(preferred, resolved_ceiling)` and returns the `model` argument to pass at dispatch. Reviewer dispatch targets the resolved Claude ceiling directly. The separate effort axis is `not-applicable`.
 
 Dispatch logs use a consistent structured block so provider behavior is comparable without flattening the model and effort axes:
 
@@ -151,10 +151,24 @@ Model axis: host-auto
 Effort axis: host-auto
 Dispatch target: host default
 Rationale: host does not expose readable or pinnable dispatch controls; rationale maps to standard effort.
+
+OAT Dispatch: p02-t10 sidecar exploration
+Host: Codex
+Preferred effort: provider-default
+Dispatch ceiling: xhigh
+Selected effort: provider-default
+Ceiling source: project state
+Provider default effort: xhigh
+Model axis: inherited
+Effort axis: provider-default
+Dispatch target: explorer
+Rationale: read-only sidecar exploration; generic explorer payload does not pin an OAT-managed effort variant.
 ```
 
 Phase and review scope packets include dispatch context when the orchestrator has resolved it: `model_axis`, `effort_axis`, `dispatch_ceiling`, `ceiling_source`, `provider_default_effort`, and `dispatch_rationale`.
 
+Generic sidecars such as built-in `explorer` are not OAT-managed implementer, reviewer, or fix roles. If a sidecar payload does not pin a reliable effort/model control, log it as provider-default rather than classifying the task complexity as a selected effort. Sidecar results are advisory context; implementation and review/fix gates still follow the OAT-managed dispatch rules above.
+
 ### Dispatch Profile overrides
 
 `plan.md` should omit `## Dispatch Profile` by default. Missing dispatch rows are normal, because runtime selection has fresher phase context and host capability information at execution time.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.39",
-  "docs-config": "0.1.39",
-  "docs-theme": "0.1.39",
-  "docs-transforms": "0.1.39"
+  "cli": "0.1.41",
+  "docs-config": "0.1.41",
+  "docs-theme": "0.1.41",
+  "docs-transforms": "0.1.41"
 }

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

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.23
+version: 2.0.24
 description: Use when plan.md is ready for execution. Dispatches phase-level subagents with bounded fix loops; supports plan-declared parallel phase groups with worktree-isolated execution and ordered fan-in.
 oat_gateable: true
 argument-hint: '[--retry-limit <N>] [--dry-run]'
@@ -204,7 +204,13 @@ Resolution order:
       "mode": "enforced",
       "mechanism": "pinned-variant",
       "dispatchArgs": { "variant": "oat-phase-implementer-high" },
-      "verifyOnDispatch": false
+      "verifyOnDispatch": false,
+      "selection": {
+        "role": "implementer",
+        "preferredValue": null,
+        "selectedValue": "high",
+        "capped": false
+      }
     }
   }
 }
@@ -212,8 +218,10 @@ Resolution order:
 
 Read `providers.<active-provider>` for the concrete dispatch controls. The
 `dispatchArgs` field carries the provider-specific argument to pass through
-(Codex: `variant` name; Claude: `model` string). Never re-derive these from the
-preset label — the resolver is the single compilation/join point.
+(Codex: `variant` name; Claude: `model` string). For implementer/fix dispatch,
+pass `--preferred <preferred-effort>` and use `selection.selectedValue` as the
+selected axis value. Never re-derive these from the preset label or a ceiling-only
+variant — the resolver is the single compilation/join point.
 
 Print before phase work:
 
@@ -311,7 +319,7 @@ Codex rules:
    - `high`: broad architecture, security/auth/redaction boundaries, subtle state behavior, or repeated substantive review failures
    - `xhigh`: highest-risk work that requires the configured ceiling to allow xhigh
 3. Selected effort is `min(preferred, resolved_ceiling)` for implementer/fix work.
-4. For implementer/fix dispatch: call `oat project dispatch-ceiling resolve --provider codex --role implementer`; read `providers.codex.dispatchArgs.variant` for the role name (e.g., `oat-phase-implementer-high`). Pass that variant name directly — do not re-derive it from the ceiling value.
+4. For implementer/fix dispatch: call `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <preferred-effort>`; read `providers.codex.selection.selectedValue` and `providers.codex.dispatchArgs.variant` for the selected role name (e.g., `oat-phase-implementer-medium`). The resolver caps the preferred effort against the ceiling; never pass a ceiling-only implementer variant when `selection.selectedValue` is lower.
 5. For review dispatch: call `oat project dispatch-ceiling resolve --provider codex --role reviewer`; read `providers.codex.dispatchArgs.variant` for the reviewer role name (e.g., `oat-reviewer-high`). Reviewer always targets the ceiling for deterministic quality gate behavior.
 6. Use base/unpinned Codex roles only as a fallback or explicit provider-default choice. Log `Selected effort: provider-default`, display provider default effort when known, and do not describe this as parent-ceiling inheritance.
 7. Do not use top-level per-call `reasoning_effort` as the standard OAT selected-effort path; dogfooding showed that path can be inconsistent.
@@ -319,9 +327,9 @@ Codex rules:
 Claude rules:
 
 - Claude ceiling is model-based: `haiku < sonnet < opus`.
-- Implementer dispatch: select the lowest sufficient model capped by the resolved Claude ceiling (`min(preferred, ceiling)`).
+- Implementer/fix dispatch: classify the preferred model (`haiku`, `sonnet`, or `opus`) and pass it to the resolver as `--preferred <preferred-model>`. The resolver selects the lowest sufficient model capped by the resolved Claude ceiling (`min(preferred, ceiling)`).
 - Review dispatch: target the resolved Claude ceiling directly.
-- Call `oat project dispatch-ceiling resolve --provider claude --role implementer --orchestrator-tier <current-orchestrator-tier>` (or `--role reviewer`); read `providers.claude.dispatchArgs.model` for the model string to pass. Pass `--orchestrator-tier` so the resolver can flag above-orchestrator upgrade requests and set `verifyOnDispatch` correctly.
+- For implementer/fix dispatch, call `oat project dispatch-ceiling resolve --provider claude --role implementer --preferred <preferred-model> --orchestrator-tier <current-orchestrator-tier>`; for review dispatch, call the same resolver with `--role reviewer` and no `--preferred`. Read `providers.claude.selection.selectedValue` and `providers.claude.dispatchArgs.model` for the selected model string to pass. Pass `--orchestrator-tier` so the resolver can flag above-orchestrator upgrade requests and set `verifyOnDispatch` correctly.
 - Pass `model: "<value>"` when `model_axis=selected:<value>` on the Task tool call.
 - Keep `effort_axis=not-applicable`; Claude Code has no separate per-dispatch effort axis.
 
@@ -336,7 +344,7 @@ Structured dispatch log:
 ```text
 OAT Dispatch: Phase {phase_id} {implementation | fix | review}
 Host: {Claude Code | Codex | Cursor | other host}
-Preferred effort: {low | medium | high | xhigh | not-applicable}
+Preferred effort: {low | medium | high | xhigh | provider-default | not-applicable}
 Dispatch ceiling: {resolved ceiling value}
 Selected effort: {low | medium | high | xhigh | provider-default | not-applicable}
 Ceiling source: {repo config | project state | preflight prompt}
@@ -395,6 +403,29 @@ Dispatch target: oat-reviewer
 Rationale: base unpinned role fallback; effective effort follows Codex provider default.
 ```
 
+Generic sidecar/explorer dispatch:
+
+- Built-in or generic sidecars such as `explorer` are not OAT-managed implementer, reviewer, or fix roles.
+- If a sidecar spawn payload does not explicitly pin a reliable effort/model control, log `Preferred effort: provider-default`, `Selected effort: provider-default`, and `Effort axis: provider-default`.
+- Do not classify a generic sidecar as `Preferred effort: low|medium|high|xhigh` unless the actual host invocation contains the corresponding reliable selection. If the host has no reliable effort control for that sidecar, use provider-default wording instead.
+- Sidecar outputs are advisory context only. Implementation work and review/fix gates still follow the OAT-managed dispatch rules above.
+
+Codex generic explorer example:
+
+```text
+OAT Dispatch: p02-t10 sidecar exploration
+Host: Codex
+Preferred effort: provider-default
+Dispatch ceiling: xhigh
+Selected effort: provider-default
+Ceiling source: project state
+Provider default effort: xhigh
+Model axis: inherited
+Effort axis: provider-default
+Dispatch target: explorer
+Rationale: read-only sidecar exploration; generic explorer payload does not pin an OAT-managed effort variant.
+```
+
 Include resolved dispatch context in scope packets when known:
 
 ```yaml
@@ -740,8 +771,8 @@ For each phase `pNN` in the plan (or each phase in the current parallel group),
 
 2. Perform a pre-dispatch assertion against the host invocation parameters. The Phase Scope fields are audit/context fields; selected axes must also be represented in the actual host dispatch call.
    - Codex implementer/fix dispatch:
-     - Before building the `spawn_agent` argument map, classify the phase complexity and choose preferred effort (`low`, `medium`, `high`, or `xhigh`), then cap it to the resolved Codex dispatch ceiling.
-     - Build the `spawn_agent` argument map before logging the dispatch. If `effort_axis=selected:low|medium|high|xhigh`, the argument map MUST use the matching `agent_type`: `"oat-phase-implementer-low"`, `"oat-phase-implementer-medium"`, `"oat-phase-implementer-high"`, or `"oat-phase-implementer-xhigh"`. Then derive the `OAT Dispatch:` block `Effort axis:` field from that same argument map.
+     - Before building the `spawn_agent` argument map, classify the phase complexity and choose preferred effort (`low`, `medium`, `high`, or `xhigh`), then call `oat project dispatch-ceiling resolve --provider codex --role implementer --preferred <preferred-effort>`.
+     - Build the `spawn_agent` argument map from `providers.codex.selection.selectedValue` and `providers.codex.dispatchArgs.variant` before logging the dispatch. If `effort_axis=selected:low|medium|high|xhigh`, the argument map MUST use the matching `agent_type`: `"oat-phase-implementer-low"`, `"oat-phase-implementer-medium"`, `"oat-phase-implementer-high"`, or `"oat-phase-implementer-xhigh"`. Then derive the `OAT Dispatch:` block `Effort axis:` field from that same argument map.
      - Example selected low payload shape: `agent_type: "oat-phase-implementer-low"` and a Phase Scope message containing `effort_axis: selected:low`.
      - Immediately after spawning, compare the returned Codex status line with the selected effort before waiting on the agent. If the spawned status reports a different effort than the selected value (for example, the log says `effort_axis=selected:medium` but the spawn result reports `gpt-5.5 high`), treat this as an orchestration deviation. Stop, record the deviation in `implementation.md`, and redispatch with corrected parameters before continuing. Do not use work from the mismatched dispatch.
      - If `effort_axis=provider-default`, use base `agent_type: "oat-phase-implementer"` and omit `reasoning_effort`. The dispatch rationale MUST say this is a base/unpinned fallback and include provider default effort when known.

package/assets/templates/pjm-agents.md

@@ -10,4 +10,83 @@ This directory owns active project-management state.
 - `current-state.md` records the present operating picture.
 - `roadmap.md` records prioritized direction and sequencing.
 - `backlog/` stores file-per-record backlog items and generated indexes.
-- Do not store durable research, brainstorms, imported plans, or decision history here.
+- `handoffs/` stores one-shot project-kickoff prompts for backlog items
+  (see `handoffs/README.md`); each is deleted in the PR that ships its item.
+- Do not store durable research, brainstorms, imported plans, or decision
+  history here.
+
+## Backlog Lifecycle
+
+Invariant: `backlog/items/` holds only active work (`status: open` or
+`in_progress`). Completed and abandoned records live in `backlog/archived/`.
+`backlog/completed.md` is the newest-first summary of what shipped.
+
+**Trigger.** Close an item out when either is true:
+
+- an item's `status` changes to `closed` or `wont_do` (these are the only
+  terminal values — never invent variants like `done`), or
+- a commit or PR satisfies an item's acceptance criteria — **even when the work
+  happened outside an OAT project lifecycle** (small doc commits included).
+
+The agent or person shipping the work owns the close-out, in the same
+commit/PR as the work whenever practical.
+
+**Close-out (primary path).** Run `oat backlog archive <id>` — add `--wont-do`
+for abandoned work and `--summary "<text>"` to record the outcome. The command
+performs the whole close-out atomically: it flips `status` to the terminal
+value and bumps `updated`, appends the canonical `backlog/completed.md` entry
+(always for `closed`; for `wont_do` only when `--summary` is given), moves the
+item file from `backlog/items/` to `backlog/archived/`, and regenerates
+`backlog/index.md`. Stage the resulting changes with the shipping commit/PR.
+
+**Manual fallback.** These are the steps the command automates — follow them, in
+order, only when closing out by hand:
+
+1. In the item file, set `status: closed` (or `wont_do`) and bump `updated`.
+2. Append a summary entry to `backlog/completed.md` (newest first; entry format
+   is documented at the top of that file). Add the entry for a `wont_do` item
+   only when the abandonment itself is worth recording (an explicit summary).
+3. `git mv` the item file from `backlog/items/` to `backlog/archived/`.
+4. Run `oat backlog regenerate-index` and stage the regenerated
+   `backlog/index.md`.
+5. If the completion changes the operating picture, refresh
+   `current-state.md` and the curated overview section of `backlog/index.md`.
+
+A partial close-out (status flipped or `completed.md` updated, but the file
+left in `items/`) is how drift starts — finish all steps or none. `oat pjm
+doctor` surfaces this drift.
+
+**When reviewing backlog state** (e.g. `oat-pjm-review-backlog`), cross-check
+recent commits against open items: work that shipped without a close-out
+should be closed retroactively with a note.
+
+## Project Kickoff Handoffs
+
+`handoffs/` holds one-shot kickoff prompts — consumable context for turning a
+backlog item into a project, not documentation. The item file and `reference/`
+remain the source of truth. See `handoffs/README.md` for the directory
+convention.
+
+- **When to generate:** when a priority-alignment pass concludes (e.g. the
+  walkthrough at the end of `oat-pjm-review-backlog`), write or refresh one
+  handoff per item in the agreed kickoff stack. Kickoff-stack membership, lane
+  count, and ordering are the human's call — present them, do not choose them.
+  Do not generate handoffs for parked or queued items until they are actually
+  next.
+- **Naming:** one file per backlog item, `handoffs/<BL-id>.md`.
+- **Required content:**
+  - 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** above executed
+    in the same PR that ships the item and (b) deletion of the handoff file
+    (`git rm`) in that same PR.
+- **Staleness:** if a later alignment pass drops an item from the kickoff
+  stack, delete its handoff in that pass rather than letting it drift.
+- Every backlog item reference — in review output, alignment docs, and
+  handoffs — pairs the ID with its human-readable title. No bare IDs.

package/assets/templates/pjm-handoffs-readme.md

@@ -0,0 +1,21 @@
+---
+oat_template: true
+oat_template_name: pjm-handoffs-readme
+---
+
+# PJM Handoffs
+
+One-shot kickoff context for backlog items about to become OAT projects. Each
+file stitches the backlog item, existing research, code pointers, and mode
+guidance into a single prompt an operator passes as context when starting a
+project (`oat-project-quick-start` or `oat-project-new`).
+
+Conventions:
+
+- One file per backlog item, named `<BL-id>.md`.
+- Handoffs are **consumable, not durable**: once the project is created and the
+  content is absorbed into project artifacts, delete the handoff (`git rm`) in
+  the same PR that ships the work. Durable knowledge belongs in the item file,
+  `reference/`, or project artifacts — never here.
+- Each handoff carries its own deletion instruction so the consuming agent
+  needs no outside context.

package/assets/templates/reference-agents.md

@@ -12,3 +12,16 @@ This directory owns append-mostly reference material.
 - `external-plans/` stores imported provider or external plans.
 - Create research, brainstorm, and deck folders on demand when a workflow needs them.
 - Do not put active roadmap, current-state, or backlog records directly under `reference/`.
+
+## Source of Truth
+
+| Topic                                  | Canonical location                                                          |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| Backlog close-out / lifecycle workflow | `../pjm/AGENTS.md` (Backlog Lifecycle)                                      |
+| Project kickoff handoffs               | `../pjm/AGENTS.md` (Project Kickoff Handoffs) + `../pjm/handoffs/README.md` |
+| Durable decisions                      | `decisions/`                                                                |
+| Active operating picture / roadmap     | `../pjm/current-state.md`, `../pjm/roadmap.md`                              |
+
+**Update rule.** Do not restate the backlog close-out workflow here. When it
+changes, edit `../pjm/AGENTS.md` and link to it — this directory defers to that
+section rather than duplicating it.

package/assets/templates/repo-agents.md

@@ -11,3 +11,7 @@ Use this directory as the canonical OAT repo-reference root.
 - Durable append-mostly references live in `reference/`.
 - Keep generated indexes inside their managed marker pairs.
 - When an index conflicts, regenerate it with the owning OAT command and stage the result.
+- Backlog close-out follows the **Backlog Lifecycle** in `pjm/AGENTS.md` — run
+  `oat backlog archive <id>` in the same PR that ships the work.
+- `README.md` is the human-facing orientation for this directory; agent-facing
+  rules live in the `AGENTS.md` files alongside each subdirectory.