@open-agent-toolkit/cli 0.1.40 → 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/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/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.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/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.

package/assets/templates/repo-readme.md

@@ -0,0 +1,35 @@
+---
+oat_template: true
+oat_template_name: repo-readme
+---
+
+# OAT Repo Reference
+
+Human-facing orientation for this OAT repo-reference root — the canonical
+project-management and durable-reference surface for the repository.
+Agent-facing rules live in the `AGENTS.md` files alongside each directory.
+
+## Layout
+
+| Path                       | What it is                                               | Maintained by                                              |
+| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
+| `pjm/current-state.md`     | Present operating picture                                | Curated                                                    |
+| `pjm/roadmap.md`           | Now / Next / Later direction                             | Curated                                                    |
+| `pjm/backlog/items/`       | Active backlog items, one file each                      | Curated + `oat backlog`                                    |
+| `pjm/backlog/archived/`    | Completed/abandoned item files                           | Moved here at close-out                                    |
+| `pjm/backlog/completed.md` | Newest-first completion summaries                        | Appended at close-out                                      |
+| `pjm/backlog/index.md`     | Curated overview + generated item table                  | Overview curated; table via `oat backlog regenerate-index` |
+| `pjm/handoffs/`            | One-shot project-kickoff prompts (deleted when consumed) | Backlog walkthroughs; removed in the shipping PR           |
+| `reference/decisions/`     | Durable decision records + generated index               | `oat decision`                                             |
+
+## Conventions
+
+- **Generated vs. curated.** Generated tables live inside `<!-- OAT ... -->`
+  marker pairs; regenerate them with the owning `oat` command instead of
+  hand-editing. Everything outside those markers is curated by hand.
+- **IDs.** Backlog items follow `BL-YYMMDD-slug` (`oat backlog generate-id`);
+  decisions follow `DR-YYMMDD-slug`. Pair every backlog item ID with its
+  human-readable title — no bare IDs in prose or handoffs.
+- **Close-out.** When work ships that satisfies a backlog item's acceptance
+  criteria, the item is closed and archived in the same commit/PR — run
+  `oat backlog archive <id>`. See the Backlog Lifecycle in `pjm/AGENTS.md`.

package/dist/commands/backlog/archive.d.ts

@@ -0,0 +1,33 @@
+import { type BacklogItemStatus } from './shared/item-status.js';
+/** Result of an {@link archiveBacklogItem} run. */
+export interface ArchiveBacklogItemResult {
+    id: string;
+    result: 'archived' | 'noop';
+    status: BacklogItemStatus | null;
+    completedEntry: 'written' | 'scaffolded' | 'skipped';
+    movedTo: string | null;
+    indexRegenerated: boolean;
+    warnings: string[];
+}
+export interface ArchiveBacklogItemOptions {
+    wontDo?: boolean;
+    summary?: string;
+    /** Injectable clock for deterministic tests; defaults to the current time. */
+    now?: Date;
+}
+/**
+ * Actionable close-out failure (unknown id, invalid current status). The
+ * command wrapper maps `exitCode` onto `process.exitCode` and logs `message`.
+ */
+export declare class BacklogArchiveError extends Error {
+    readonly exitCode: 1 | 2;
+    constructor(message: string, exitCode?: 1 | 2);
+}
+/**
+ * Atomic backlog close-out. Validates the current status, sets the terminal
+ * status and `updated`, records a canonical `completed.md` entry, moves the
+ * item file into `archived/`, and regenerates the index. Idempotent when the
+ * item is already archived.
+ */
+export declare function archiveBacklogItem(backlogRoot: string, id: string, options?: ArchiveBacklogItemOptions): Promise<ArchiveBacklogItemResult>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/commands/backlog/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/archive.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,iBAAiB,EAGvB,MAAM,sBAAsB,CAAC;AAoB9B,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5B,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,cAAc,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;gBAEb,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,CAAC,GAAG,CAAK;CAKjD;AAkID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CAkHnC"}

package/dist/commands/backlog/archive.js

@@ -0,0 +1,229 @@
+import { execFile } from 'node:child_process';
+import { access, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { getFrontmatterBlock } from '../shared/frontmatter.js';
+import YAML from 'yaml';
+import { regenerateBacklogIndex } from './regenerate-index.js';
+import { BACKLOG_ITEM_STATUSES, extractBacklogStatus, isValidBacklogStatus, } from './shared/item-status.js';
+const execFileAsync = promisify(execFile);
+const COMPLETED_HEADING = '## Completed Items';
+const TODO_SUMMARY = 'TODO: summarize outcome';
+const STARTER_COMPLETED = [
+    '# OAT Backlog Completed',
+    '',
+    '> Summary archive for completed backlog work. Keep newest entries first. Use `backlog/archived/` for full file-per-item historical records when a completed item still needs rich context.',
+    '',
+    '## Entry Format',
+    '',
+    '- `YYYY-MM-DD — BL-YYMMDD-slug — Title — one-line outcome summary`',
+    '',
+    COMPLETED_HEADING,
+    '',
+].join('\n');
+/**
+ * Actionable close-out failure (unknown id, invalid current status). The
+ * command wrapper maps `exitCode` onto `process.exitCode` and logs `message`.
+ */
+export class BacklogArchiveError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'BacklogArchiveError';
+        this.exitCode = exitCode;
+    }
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error
+            ? String(error.code)
+            : null;
+        if (code !== 'ENOENT') {
+            throw error;
+        }
+        return false;
+    }
+}
+async function isInsideGitWorkTree(cwd) {
+    try {
+        await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the item `title` from its frontmatter. Parses the YAML block (rather
+ * than a line regex) so a legitimate `#` inside a quoted title — e.g.
+ * `title: 'Fix #123 crash'` — is preserved instead of being stripped as an
+ * inline comment.
+ */
+function readItemTitle(content) {
+    const block = getFrontmatterBlock(content);
+    if (!block) {
+        return '';
+    }
+    const parsed = YAML.parse(block);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return '';
+    }
+    return String(parsed.title ?? '').trim();
+}
+/**
+ * Minimal-diff frontmatter rewrite: replace only the `status:` value (keeping
+ * any inline enum comment) and the `updated:` value, leaving all surrounding
+ * formatting untouched.
+ */
+function rewriteFrontmatter(content, status, updatedIso) {
+    let next = content.replace(/^(status:[ \t]*)(\S+)([ \t]*#.*)?$/m, (_match, prefix, _value, comment) => `${prefix}${status}${comment ?? ''}`);
+    next = next.replace(/^(updated:)[ \t]*.*$/m, (_match, prefix) => `${prefix} '${updatedIso}'`);
+    return next;
+}
+/**
+ * Insert `entryLine` as the first bullet beneath the `## Completed Items`
+ * heading. When the heading is absent it is scaffolded (with a warning). The
+ * returned flag distinguishes a plain append from one that had to scaffold the
+ * section.
+ */
+function insertCompletedEntry(completed, entryLine) {
+    const lines = completed.split('\n');
+    const headingIndex = lines.findIndex((line) => line.trim() === COMPLETED_HEADING);
+    if (headingIndex === -1) {
+        const trimmed = completed.replace(/\s*$/, '');
+        const content = `${trimmed}\n\n${COMPLETED_HEADING}\n\n${entryLine}\n`;
+        return {
+            content,
+            scaffolded: true,
+            warning: `Completed log was missing a \`${COMPLETED_HEADING}\` heading; a new section was scaffolded and the entry appended.`,
+        };
+    }
+    let insertAt = headingIndex + 1;
+    while (insertAt < lines.length && lines[insertAt].trim() === '') {
+        insertAt += 1;
+    }
+    lines.splice(insertAt, 0, entryLine);
+    // Guarantee exactly one blank line between the heading and the first entry.
+    if (lines[headingIndex + 1] !== '') {
+        lines.splice(headingIndex + 1, 0, '');
+    }
+    let content = lines.join('\n');
+    if (!content.endsWith('\n')) {
+        content += '\n';
+    }
+    return { content, scaffolded: false, warning: null };
+}
+async function moveItemFile(backlogRoot, fromPath, toPath, warnings) {
+    if (await isInsideGitWorkTree(backlogRoot)) {
+        try {
+            await execFileAsync('git', ['mv', fromPath, toPath], {
+                cwd: backlogRoot,
+            });
+            return;
+        }
+        catch {
+            warnings.push(`\`git mv\` failed for ${fromPath}; falling back to a plain filesystem rename (the move is no longer staged).`);
+        }
+    }
+    await rename(fromPath, toPath);
+}
+/**
+ * Atomic backlog close-out. Validates the current status, sets the terminal
+ * status and `updated`, records a canonical `completed.md` entry, moves the
+ * item file into `archived/`, and regenerates the index. Idempotent when the
+ * item is already archived.
+ */
+export async function archiveBacklogItem(backlogRoot, id, options = {}) {
+    const itemsPath = join(backlogRoot, 'items', `${id}.md`);
+    const archivedPath = join(backlogRoot, 'archived', `${id}.md`);
+    const warnings = [];
+    // Idempotent no-op: already archived.
+    if (await pathExists(archivedPath)) {
+        // Conflicting duplicate: the same id lives in BOTH `items/` and
+        // `archived/`. Treating this as a clean no-op would silently leave the live
+        // `items/` copy unarchived, while auto-archiving would clobber the existing
+        // archived record. Refuse and make the user reconcile the duplicate.
+        if (await pathExists(itemsPath)) {
+            throw new BacklogArchiveError(`Backlog item ${id} exists in both \`items/\` (${itemsPath}) and \`archived/\` (${archivedPath}). Auto-archiving would clobber the existing archived record, so this is left untouched. Fix: reconcile the duplicate manually — decide which of the two files is authoritative and remove the other — then re-run \`oat backlog archive ${id}\`.`);
+        }
+        let status = null;
+        try {
+            const extracted = extractBacklogStatus(await readFile(archivedPath, 'utf8'));
+            status = extracted && isValidBacklogStatus(extracted) ? extracted : null;
+        }
+        catch {
+            status = null;
+        }
+        warnings.push(`Backlog item ${id} is already archived at ${archivedPath}; nothing to do.`);
+        return {
+            id,
+            result: 'noop',
+            status,
+            completedEntry: 'skipped',
+            movedTo: archivedPath,
+            indexRegenerated: false,
+            warnings,
+        };
+    }
+    if (!(await pathExists(itemsPath))) {
+        throw new BacklogArchiveError(`Backlog item ${id} not found at ${itemsPath}. Confirm the id and that the file lives under \`items/\`, then re-run \`oat backlog archive ${id}\`.`);
+    }
+    const content = await readFile(itemsPath, 'utf8');
+    const currentStatus = extractBacklogStatus(content);
+    if (currentStatus === null || !isValidBacklogStatus(currentStatus)) {
+        throw new BacklogArchiveError(`Backlog item ${itemsPath} has invalid status "${currentStatus ?? ''}". Valid statuses: ${BACKLOG_ITEM_STATUSES.join(', ')}. Fix: correct the \`status\` field manually, then re-run \`oat backlog archive ${id}\`.`);
+    }
+    const targetStatus = options.wontDo ? 'wont_do' : 'closed';
+    const now = options.now ?? new Date();
+    const updatedIso = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const entryDate = updatedIso.slice(0, 10);
+    const title = readItemTitle(content);
+    // 4. Rewrite frontmatter in place (before the move) so a crash leaves the
+    //    detectable "terminal status still in items/" drift, never corruption.
+    await writeFile(itemsPath, rewriteFrontmatter(content, targetStatus, updatedIso), 'utf8');
+    // 5. completed.md entry — always for `closed`; only with a summary for
+    //    `wont_do`.
+    let completedEntry = 'skipped';
+    const shouldWriteEntry = targetStatus === 'closed' || Boolean(options.summary);
+    if (shouldWriteEntry) {
+        const summary = options.summary?.trim()
+            ? options.summary.trim()
+            : TODO_SUMMARY;
+        const entryLine = `- ${entryDate} — ${id} — ${title} — ${summary}`;
+        const completedPath = join(backlogRoot, 'completed.md');
+        let scaffoldedFile = false;
+        let existing;
+        if (await pathExists(completedPath)) {
+            existing = await readFile(completedPath, 'utf8');
+        }
+        else {
+            existing = STARTER_COMPLETED;
+            scaffoldedFile = true;
+        }
+        const inserted = insertCompletedEntry(existing, entryLine);
+        if (inserted.warning) {
+            warnings.push(inserted.warning);
+        }
+        await writeFile(completedPath, inserted.content, 'utf8');
+        completedEntry =
+            scaffoldedFile || inserted.scaffolded ? 'scaffolded' : 'written';
+    }
+    // 6. Move items/<id>.md -> archived/<id>.md (git mv with rename fallback).
+    await moveItemFile(backlogRoot, itemsPath, archivedPath, warnings);
+    // 7. Regenerate the index via the exported core.
+    const regeneration = await regenerateBacklogIndex(backlogRoot);
+    warnings.push(...regeneration.warnings);
+    return {
+        id,
+        result: 'archived',
+        status: targetStatus,
+        completedEntry,
+        movedTo: archivedPath,
+        indexRegenerated: true,
+        warnings,
+    };
+}

package/dist/commands/backlog/index.d.ts

@@ -1,6 +1,7 @@
 import { buildCommandContext } from '../../app/command-context.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
+import { archiveBacklogItem } from './archive.js';
 import { initializeBacklog } from './init.js';
 import { regenerateBacklogIndex } from './regenerate-index.js';
 interface BacklogCommandDependencies {
@@ -8,6 +9,7 @@ interface BacklogCommandDependencies {
     resolveProjectRoot: typeof resolveProjectRoot;
     initializeBacklog: typeof initializeBacklog;
     regenerateBacklogIndex: typeof regenerateBacklogIndex;
+    archiveBacklogItem: typeof archiveBacklogItem;
     pathExists: (path: string) => Promise<boolean>;
 }
 export declare function createBacklogCommand(overrides?: Partial<BacklogCommandDependencies>): Command;

package/dist/commands/backlog/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAe5D,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAyCD,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAgIT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAuB,MAAM,WAAW,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAC3C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAqB5D,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AA0CD,wBAAgB,oBAAoB,CAClC,SAAS,GAAE,OAAO,CAAC,0BAA0B,CAAM,GAClD,OAAO,CAiMT"}

package/dist/commands/backlog/index.js

@@ -4,6 +4,7 @@ import { buildCommandContext } from '../../app/command-context.js';
 import { readGlobalOptions } from '../shared/shared.utils.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { Command } from 'commander';
+import { archiveBacklogItem, BacklogArchiveError } from './archive.js';
 import { initializeBacklog } from './init.js';
 import { regenerateBacklogIndex } from './regenerate-index.js';
 import { generateBacklogId } from './shared/generate-id.js';
@@ -27,6 +28,7 @@ const DEFAULT_DEPENDENCIES = {
     resolveProjectRoot,
     initializeBacklog,
     regenerateBacklogIndex,
+    archiveBacklogItem,
     pathExists: pathExistsDefault,
 };
 async function resolveBacklogRoot(context, configuredRoot, dependencies = DEFAULT_DEPENDENCIES) {
@@ -65,15 +67,67 @@ export function createBacklogCommand(overrides = {}) {
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         const backlogRoot = await resolveBacklogRoot(context, options.backlogRoot, dependencies);
-        await dependencies.regenerateBacklogIndex(backlogRoot);
+        const { itemCount, warnings } = await dependencies.regenerateBacklogIndex(backlogRoot);
         if (context.json) {
-            context.logger.json({ status: 'ok', backlogRoot });
+            context.logger.json({ status: 'ok', backlogRoot, itemCount, warnings });
         }
         else {
+            for (const warning of warnings) {
+                context.logger.warn(warning);
+            }
             context.logger.info(`Regenerated backlog index at ${backlogRoot}`);
         }
         process.exitCode = 0;
     });
+    cmd
+        .command('archive')
+        .description('Close out a backlog item: set a terminal status, record it in completed.md, move it to archived/, and regenerate the index')
+        .argument('<id>', 'Backlog item id (`BL-YYMMDD-slug`)')
+        .option('--wont-do', 'Close the item as `wont_do` instead of `closed`')
+        .option('--summary <text>', 'One-line outcome summary for completed.md')
+        .option('--backlog-root <path>', 'Backlog root directory (defaults to .oat/repo/pjm/backlog)')
+        .action(async (id, options, command) => {
+        const context = dependencies.buildCommandContext(readGlobalOptions(command));
+        const backlogRoot = await resolveBacklogRoot(context, options.backlogRoot, dependencies);
+        try {
+            const result = await dependencies.archiveBacklogItem(backlogRoot, id, {
+                wontDo: options.wontDo,
+                summary: options.summary,
+            });
+            if (context.json) {
+                context.logger.json(result);
+            }
+            else {
+                for (const warning of result.warnings) {
+                    context.logger.warn(warning);
+                }
+                if (result.result === 'noop') {
+                    context.logger.info(`Backlog item ${id} is already archived.`);
+                }
+                else {
+                    context.logger.success(`Archived ${id} as ${result.status} (moved to ${result.movedTo}).`);
+                }
+            }
+            process.exitCode = 0;
+        }
+        catch (error) {
+            if (error instanceof BacklogArchiveError) {
+                if (context.json) {
+                    context.logger.json({
+                        result: 'error',
+                        id,
+                        message: error.message,
+                    });
+                }
+                else {
+                    context.logger.error(error.message);
+                }
+                process.exitCode = error.exitCode;
+                return;
+            }
+            throw error;
+        }
+    });
     cmd
         .command('generate-id')
         .description('Generate a backlog item identifier (`BL-YYMMDD-slug`) from a title or slug')

package/dist/commands/backlog/regenerate-index.d.ts

@@ -1,2 +1,6 @@
-export declare function regenerateBacklogIndex(backlogRoot: string): Promise<void>;
+export interface RegenerateBacklogIndexResult {
+    itemCount: number;
+    warnings: string[];
+}
+export declare function regenerateBacklogIndex(backlogRoot: string): Promise<RegenerateBacklogIndexResult>;
 //# sourceMappingURL=regenerate-index.d.ts.map

package/dist/commands/backlog/regenerate-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regenerate-index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/regenerate-index.ts"],"names":[],"mappings":"AAmGA,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CA+Cf"}
+{"version":3,"file":"regenerate-index.d.ts","sourceRoot":"","sources":["../../../src/commands/backlog/regenerate-index.ts"],"names":[],"mappings":"AAwGA,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,4BAA4B,CAAC,CAsDvC"}

package/dist/commands/backlog/regenerate-index.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { getFrontmatterBlock } from '../shared/frontmatter.js';
 import { computeManagedIndexUpdate } from '../shared/managed-index.js';
 import YAML from 'yaml';
+import { BACKLOG_ITEM_STATUSES, isValidBacklogStatus, } from './shared/item-status.js';
 const INDEX_START = '<!-- OAT BACKLOG-INDEX -->';
 const INDEX_END = '<!-- END OAT BACKLOG-INDEX -->';
 const PRIORITY_ORDER = {
@@ -71,10 +72,14 @@ export async function regenerateBacklogIndex(backlogRoot) {
         .map((entry) => entry.name)
         .sort();
     const items = [];
+    const warnings = [];
     for (const entry of entries) {
         const filePath = join(itemsDir, entry);
         const item = parseItemFrontmatter(await readFile(filePath, 'utf8'), filePath);
         if (item) {
+            if (item.status !== '' && !isValidBacklogStatus(item.status)) {
+                warnings.push(`Backlog item ${filePath} has invalid status "${item.status}". Valid statuses: ${BACKLOG_ITEM_STATUSES.join(', ')}.`);
+            }
             items.push(item);
         }
     }
@@ -91,7 +96,8 @@ export async function regenerateBacklogIndex(backlogRoot) {
     // write. Only rewrite on a genuine content change.
     const { content: updated } = computeManagedIndexUpdate(content, startIndex, endIndex + INDEX_END.length, renderManagedSection(items));
     if (updated === null) {
-        return;
+        return { itemCount: items.length, warnings };
     }
     await writeFile(indexPath, updated, 'utf8');
+    return { itemCount: items.length, warnings };
 }

package/dist/commands/backlog/shared/item-status.d.ts

@@ -0,0 +1,13 @@
+export declare const BACKLOG_ITEM_STATUSES: readonly ["open", "in_progress", "closed", "wont_do"];
+export type BacklogItemStatus = (typeof BACKLOG_ITEM_STATUSES)[number];
+export declare const TERMINAL_BACKLOG_STATUSES: readonly BacklogItemStatus[];
+export declare function isValidBacklogStatus(value: string): value is BacklogItemStatus;
+export declare function isTerminalBacklogStatus(value: string): boolean;
+/**
+ * Extract the `status` value from backlog item content. Accepts either full
+ * item content (with `---` fences) or a bare frontmatter block. Inline enum
+ * comments (`status: closed # ...`) are stripped. Returns `null` when no
+ * `status` field is present.
+ */
+export declare function extractBacklogStatus(frontmatterContent: string): string | null;
+//# sourceMappingURL=item-status.d.ts.map

package/dist/commands/backlog/shared/item-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-status.d.ts","sourceRoot":"","sources":["../../../../src/commands/backlog/shared/item-status.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,qBAAqB,uDAKxB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,eAAO,MAAM,yBAAyB,EAAE,SAAS,iBAAiB,EAGjE,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,iBAAiB,CAE5B;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,kBAAkB,EAAE,MAAM,GACzB,MAAM,GAAG,IAAI,CAUf"}

package/dist/commands/backlog/shared/item-status.js

@@ -0,0 +1,34 @@
+// Single source of truth for backlog item statuses. Kept dependency-free so
+// cross-directory consumers (archive, regenerate-index, pjm doctor) can import
+// it via the `@commands/...` alias without pulling in a dependency chain.
+export const BACKLOG_ITEM_STATUSES = [
+    'open',
+    'in_progress',
+    'closed',
+    'wont_do',
+];
+export const TERMINAL_BACKLOG_STATUSES = [
+    'closed',
+    'wont_do',
+];
+export function isValidBacklogStatus(value) {
+    return BACKLOG_ITEM_STATUSES.includes(value);
+}
+export function isTerminalBacklogStatus(value) {
+    return TERMINAL_BACKLOG_STATUSES.includes(value);
+}
+/**
+ * Extract the `status` value from backlog item content. Accepts either full
+ * item content (with `---` fences) or a bare frontmatter block. Inline enum
+ * comments (`status: closed # ...`) are stripped. Returns `null` when no
+ * `status` field is present.
+ */
+export function extractBacklogStatus(frontmatterContent) {
+    const fenced = frontmatterContent.match(/^---\n([\s\S]*?)\n---/);
+    const block = fenced ? fenced[1] : frontmatterContent;
+    const match = block.match(/^status:\s*(.+)$/m);
+    if (!match) {
+        return null;
+    }
+    return match[1].replace(/\s*#.*$/, '').trim();
+}

package/dist/commands/instructions/instructions.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAE,uBACrC,CAAC;AAKZ,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC;AAqBD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AAoLD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiO7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAoBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,GACR,EAAE,4BAA4B,GAAG,uBAAuB,CAWxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAmCR"}
+{"version":3,"file":"instructions.utils.d.ts","sourceRoot":"","sources":["../../../src/commands/instructions/instructions.utils.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAE5B,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AACtD,eAAO,MAAM,iCAAiC,EAAE,uBACrC,CAAC;AAcZ,UAAU,4BAA4B;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC;AAiCD,wBAAgB,8BAA8B,CAC5C,QAAQ,CAAC,EAAE,uBAAuB,GACjC,uBAAuB,CAEzB;AA2LD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,uBAA4B,EACrC,SAAS,GAAE,OAAO,CAAC,4BAA4B,CAAM,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiO7B;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,gBAAgB,EAAE,EAC3B,OAAO,EAAE,uBAAuB,EAAE,GACjC,mBAAmB,CAoBrB;AAgBD,wBAAgB,wBAAwB,CAAC,EACvC,IAAI,EACJ,OAAO,EACP,OAAO,GACR,EAAE,4BAA4B,GAAG,uBAAuB,CAWxD;AAED,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,uBAAuB,EAChC,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAmCR"}

package/dist/commands/instructions/instructions.utils.js

@@ -4,6 +4,23 @@ export const EXPECTED_CLAUDE_CONTENT = '@AGENTS.md\n';
 export const DEFAULT_INSTRUCTION_SYNC_STRATEGY = 'pointer';
 const ROOT_EXCLUDED_DIRECTORIES = new Set(['.git', '.oat', '.worktrees']);
 const GLOBAL_EXCLUDED_DIRECTORIES = new Set(['node_modules']);
+// The only excluded-subtree re-entry points: a root-level directory is excluded
+// wholesale, but a named subdirectory holds tracked instruction files that
+// sync/validate must manage, so it is carved back into the scan. `.oat` is
+// excluded at the repo root, yet `.oat/repo/**` carries AGENTS.md/CLAUDE.md
+// pairs; `.oat/templates`, `.oat/projects`, and `.oat/sync` stay unscanned.
+const ROOT_EXCLUDED_DIRECTORY_CARVE_INS = new Map([
+    ['.oat', 'repo'],
+]);
+async function directoryExists(dependencies, directoryPath) {
+    try {
+        const stats = await dependencies.stat(directoryPath);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function getErrorCode(error) {
     return error && typeof error === 'object' && 'code' in error
         ? String(error.code)
@@ -97,6 +114,13 @@ async function scanInstructionDirectories(repoRoot, dependencies, debug) {
                     continue;
                 }
                 if (isRootLevel && ROOT_EXCLUDED_DIRECTORIES.has(entry.name)) {
+                    const carveIn = ROOT_EXCLUDED_DIRECTORY_CARVE_INS.get(entry.name);
+                    if (carveIn) {
+                        const carveInPath = join(entryPath, carveIn);
+                        if (await directoryExists(dependencies, carveInPath)) {
+                            queue.push(carveInPath);
+                        }
+                    }
                     continue;
                 }
                 queue.push(entryPath);

package/dist/commands/pjm/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/doctor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA0I9C,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,sBAAsB,IAAI,WAAW,CAQpD;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC,CAyJxB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/doctor.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA6L9C,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,sBAAsB,IAAI,WAAW,CAQpD;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,EAAE,CAAC,CAoTxB"}

package/dist/commands/pjm/doctor.js

@@ -1,5 +1,6 @@
 import { access, readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { BACKLOG_ITEM_STATUSES, extractBacklogStatus, isTerminalBacklogStatus, isValidBacklogStatus, } from '../backlog/shared/item-status.js';
 import { getFrontmatterBlock } from '../shared/frontmatter.js';
 import { CANONICAL_REPO_REFERENCE_PATHS } from './init.js';
 const ALLOWED_TOP_LEVEL_DIRECTORIES = new Set([
@@ -108,6 +109,45 @@ function containsTemplateFrontmatter(content) {
         (/\boat_template\s*:/i.test(frontmatter) ||
             /\boat_template_name\s*:/i.test(frontmatter)));
 }
+const BACKLOG_ITEMS_DIRECTORY = 'pjm/backlog/items';
+const BACKLOG_ARCHIVED_DIRECTORY = 'pjm/backlog/archived';
+const BACKLOG_COMPLETED_FILE = 'pjm/backlog/completed.md';
+// Best-effort backlog id scan: `BL-YYMMDD-slug` (legacy lowercase `bl-`
+// matched case-insensitively). The six-digit requirement keeps the literal
+// `BL-YYMMDD-slug` format placeholder in `completed.md` from matching.
+const BACKLOG_ID_PATTERN = /\bbl-\d{6}-[a-z0-9][a-z0-9-]*/gi;
+/**
+ * Single frontmatter pass over both backlog directories. Every drift check
+ * derives from this scan so the filesystem is walked once. `index.md` is the
+ * managed index, not an item, so it is excluded.
+ */
+async function collectBacklogItems(repoRoot) {
+    const records = [];
+    const directories = [
+        { directory: 'items', relativeDir: BACKLOG_ITEMS_DIRECTORY },
+        { directory: 'archived', relativeDir: BACKLOG_ARCHIVED_DIRECTORY },
+    ];
+    for (const { directory, relativeDir } of directories) {
+        const fileNames = await listMarkdownFiles(join(repoRoot, relativeDir));
+        for (const fileName of fileNames) {
+            if (fileName === 'index.md') {
+                continue;
+            }
+            const content = await readIfExists(join(repoRoot, relativeDir, fileName));
+            records.push({
+                directory,
+                relativePath: `${relativeDir}/${fileName}`,
+                id: fileName.replace(/\.md$/, ''),
+                status: content ? extractBacklogStatus(content) : null,
+            });
+        }
+    }
+    return records;
+}
+/** Best-effort scan of completed-log content for backlog item ids. */
+function extractCompletedIds(content) {
+    return [...content.matchAll(BACKLOG_ID_PATTERN)].map((match) => match[0]);
+}
 function checkStatus(missing) {
     return missing.length === 0 ? 'pass' : 'fail';
 }
@@ -246,5 +286,126 @@ export async function runPjmDoctorChecks(repoRoot, options = {}) {
             ? undefined
             : 'Move active operational docs to pjm/ and leave reference/ for durable append-mostly artifacts.',
     });
+    const backlogItems = await collectBacklogItems(repoRoot);
+    const terminalInItems = backlogItems
+        .filter((item) => item.directory === 'items' &&
+        item.status !== null &&
+        isTerminalBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    checks.push({
+        name: 'pjm:backlog_terminal_in_items',
+        description: 'Terminal-status backlog items awaiting archive',
+        status: checkStatus(terminalInItems),
+        message: terminalInItems.length === 0
+            ? 'No terminal-status backlog items remain under items/.'
+            : `Terminal-status backlog items still under items/: ${terminalInItems.join(', ')}`,
+        fix: terminalInItems.length === 0
+            ? undefined
+            : 'Run `oat backlog archive <id>` to move each closed/wont_do item into archived/.',
+    });
+    // A missing/empty `status:` is as much a drift as an out-of-enum value: the
+    // `oat backlog archive` command rejects both, so `pjm doctor` must surface
+    // both rather than leaving status-less items silently invisible.
+    const missingStatusItems = backlogItems
+        .filter((item) => item.status === null || item.status.trim() === '')
+        .map((item) => item.relativePath);
+    const outOfEnumStatusItems = backlogItems
+        .filter((item) => item.status !== null &&
+        item.status.trim() !== '' &&
+        !isValidBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    const invalidStatus = [...outOfEnumStatusItems, ...missingStatusItems];
+    const invalidStatusDetails = [];
+    if (outOfEnumStatusItems.length > 0) {
+        invalidStatusDetails.push(`out-of-enum status: ${outOfEnumStatusItems.join(', ')}`);
+    }
+    if (missingStatusItems.length > 0) {
+        invalidStatusDetails.push(`missing status: ${missingStatusItems.join(', ')}`);
+    }
+    checks.push({
+        name: 'pjm:backlog_invalid_status',
+        description: 'Backlog items with a missing or out-of-enum status',
+        status: checkStatus(invalidStatus),
+        message: invalidStatus.length === 0
+            ? 'All backlog item statuses are within the valid enum.'
+            : `Backlog items with an invalid status (${invalidStatusDetails.join('; ')}). Valid statuses: ${BACKLOG_ITEM_STATUSES.join(', ')}.`,
+        fix: invalidStatus.length === 0
+            ? undefined
+            : `Set a valid status (${BACKLOG_ITEM_STATUSES.join(', ')}) on each listed item.`,
+    });
+    const archivedOpen = backlogItems
+        .filter((item) => item.directory === 'archived' &&
+        item.status !== null &&
+        isValidBacklogStatus(item.status) &&
+        !isTerminalBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    checks.push({
+        name: 'pjm:backlog_archived_open',
+        description: 'Archived backlog items with a non-terminal status',
+        status: warnStatus(archivedOpen),
+        message: archivedOpen.length === 0
+            ? 'No archived backlog items carry an open status.'
+            : `Archived backlog items still marked open/in_progress: ${archivedOpen.join(', ')}`,
+        fix: archivedOpen.length === 0
+            ? undefined
+            : 'Set a terminal status (closed/wont_do) on each archived item, or move it back under items/.',
+    });
+    // A single id must never live in both `items/` and `archived/`: the live copy
+    // shadows the archived record and `oat backlog archive` refuses to reconcile
+    // it automatically (auto-archiving would clobber the archived file). Derive
+    // from the same single scan so the filesystem is not re-walked.
+    const backlogPathsByIdAndDir = new Map();
+    for (const item of backlogItems) {
+        const key = item.id.toLowerCase();
+        const entry = backlogPathsByIdAndDir.get(key) ?? {};
+        entry[item.directory] = item.relativePath;
+        backlogPathsByIdAndDir.set(key, entry);
+    }
+    const duplicateIdPairs = [];
+    for (const entry of backlogPathsByIdAndDir.values()) {
+        if (entry.items && entry.archived) {
+            duplicateIdPairs.push(`${entry.items} + ${entry.archived}`);
+        }
+    }
+    checks.push({
+        name: 'pjm:backlog_duplicate_id',
+        description: 'Backlog ids present in both items/ and archived/',
+        status: checkStatus(duplicateIdPairs),
+        message: duplicateIdPairs.length === 0
+            ? 'No backlog id is present in both items/ and archived/.'
+            : `Backlog ids present in both items/ and archived/: ${duplicateIdPairs.join('; ')}`,
+        fix: duplicateIdPairs.length === 0
+            ? undefined
+            : 'Reconcile each duplicate manually: decide whether the active (items/) or archived copy is authoritative, remove the other, then re-run `oat backlog archive <id>` if the item still needs archiving.',
+    });
+    const itemPathsById = new Map();
+    for (const item of backlogItems) {
+        if (item.directory === 'items') {
+            itemPathsById.set(item.id.toLowerCase(), item.relativePath);
+        }
+    }
+    const completedContent = await readIfExists(join(repoRoot, BACKLOG_COMPLETED_FILE));
+    const completedUnarchived = [];
+    const seenUnarchived = new Set();
+    if (completedContent) {
+        for (const completedId of extractCompletedIds(completedContent)) {
+            const relativePath = itemPathsById.get(completedId.toLowerCase());
+            if (relativePath && !seenUnarchived.has(relativePath)) {
+                seenUnarchived.add(relativePath);
+                completedUnarchived.push(relativePath);
+            }
+        }
+    }
+    checks.push({
+        name: 'pjm:backlog_completed_unarchived',
+        description: 'Completed-log entries whose item file is still under items/',
+        status: warnStatus(completedUnarchived),
+        message: completedUnarchived.length === 0
+            ? 'No completed backlog entries reference an item still under items/.'
+            : `Completed log references items still under items/: ${completedUnarchived.join(', ')}`,
+        fix: completedUnarchived.length === 0
+            ? undefined
+            : 'Run `oat backlog archive <id>` to archive each completed item still under items/.',
+    });
     return checks;
 }

package/dist/commands/pjm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAiBnE,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA6FD,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CAsJT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAA0B,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAiBnE,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA6FD,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CAuJT"}

package/dist/commands/pjm/index.js

@@ -7,7 +7,7 @@ import { resolveProjectRoot } from '../../fs/paths.js';
 import { formatDoctorResults } from '../../ui/output.js';
 import { Command } from 'commander';
 import { runPjmDoctorChecks } from './doctor.js';
-import { initializeRepoReference } from './init.js';
+import { initializeRepoReference, INSTRUCTIONS_SYNC_HINT } from './init.js';
 import { migratePjmRepo, readPjmMigrationPrompt } from './migrate.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -111,6 +111,7 @@ export function createPjmCommand(overrides = {}) {
                 if (result.skipped.length > 0) {
                     context.logger.info(`Skipped existing: ${result.skipped.join(', ')}`);
                 }
+                context.logger.info(INSTRUCTIONS_SYNC_HINT);
             }
             process.exitCode = 0;
         }

package/dist/commands/pjm/init.d.ts

@@ -8,6 +8,7 @@ export interface RepoReferenceInitResult {
     created: string[];
     skipped: string[];
 }
-export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/roadmap.md" | "reference/AGENTS.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/index.md"];
+export declare const INSTRUCTIONS_SYNC_HINT: string;
+export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/roadmap.md" | "reference/AGENTS.md" | "README.md" | "pjm/handoffs/README.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/index.md"];
 export declare function initializeRepoReference(options: InitializeRepoReferenceOptions): Promise<RepoReferenceInitResult>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/pjm/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAwBD,eAAO,MAAM,8BAA8B,wQAIjC,CAAC;AAyEX,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAgElC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAoBD,eAAO,MAAM,sBAAsB,QAEiD,CAAC;AAWrF,eAAO,MAAM,8BAA8B,iTAIjC,CAAC;AAyEX,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAgElC"}

package/dist/commands/pjm/init.js

@@ -9,7 +9,14 @@ const TEMPLATE_TARGETS = [
     { template: 'current-state.md', target: 'pjm/current-state.md' },
     { template: 'roadmap.md', target: 'pjm/roadmap.md' },
     { template: 'reference-agents.md', target: 'reference/AGENTS.md' },
+    { template: 'repo-readme.md', target: 'README.md' },
+    { template: 'pjm-handoffs-readme.md', target: 'pjm/handoffs/README.md' },
 ];
+// Next-step hint printed after init/backfill. `oat pjm init` never writes
+// CLAUDE.md shims itself — strategy ownership stays with `oat instructions
+// sync`, so we point the operator at it (with the `--dry-run` preview).
+export const INSTRUCTIONS_SYNC_HINT = 'Next step: run `oat instructions sync` to create CLAUDE.md shims for the ' +
+    'repo-reference AGENTS.md files (preview with `oat instructions sync --dry-run`).';
 const BACKLOG_PATHS = [
     'pjm/backlog/index.md',
     'pjm/backlog/completed.md',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.40"
+    "@open-agent-toolkit/control-plane": "0.1.41"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",