@open-agent-toolkit/cli 0.1.40 → 0.1.42

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.0.24
+version: 2.0.25
 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]'
@@ -679,6 +679,39 @@ This setting controls only the extra `oat-project-review-provide` lifecycle revi
 
 **On resume:** If `oat_auto_review_at_hill_checkpoints` is already present in plan.md frontmatter, skip Touchpoint A entirely — do not re-ask, do not re-read config, do not print the auto-review note. The stored value is authoritative. If only legacy `oat_auto_review_at_checkpoints` is present, treat it as authoritative for this run and write the new `oat_auto_review_at_hill_checkpoints` key on the next plan frontmatter update.
 
+### Step 2.6: Validate Optional Phase Review Gate
+
+Read `oat_phase_review_gate` from `"$PROJECT_PATH/plan.md"` frontmatter when present.
+
+This is the plan-level `phaseReviewGate` setting: an optional, non-pausing external lifecycle review gate that runs after a phase's standard per-phase self-review passes. It uses the existing `oat gate review` target configuration to run a cross-provider review, then maps the produced review artifact to a blocking/non-blocking gate result.
+
+Valid shape:
+
+```yaml
+oat_phase_review_gate:
+  enabled: true
+  phases: [] # empty or omitted = every implementation phase
+  review_type: code
+  exit_nonzero_on: important
+```
+
+Validation rules:
+
+- Missing, `null`, or `enabled: false` means disabled.
+- `enabled: true` activates the gate.
+- `phases` is optional. If missing or empty (`[]`), run after every implementation phase. If populated, every value must be a known plan phase ID.
+- `review_type` is optional and defaults to `code`. This skill only supports `code` phase gates; any other value is invalid for implementation phase execution.
+- `exit_nonzero_on` is optional and defaults to `important`. Allowed values: `critical`, `important`, `medium`, `minor`.
+
+If the setting is invalid, stop before task execution and ask the user to repair `plan.md`. Do not silently disable a malformed gate.
+
+This setting is independent from HiLL checkpoints:
+
+- It does not pause when the gate passes.
+- It does not append to `oat_hill_completed`.
+- It does not alter `oat_plan_hill_phases` or `oat_auto_review_at_hill_checkpoints`.
+- It uses the existing gate target config; do not hardcode `--target` in reusable plan execution unless the user explicitly asks for manual/debug routing.
+
 ### Step 3: Check Implementation State
 
 Check if implementation already started:
@@ -892,6 +925,43 @@ On reviewer verdict `fail`, run a bounded fix loop.
 - **Sequential mode:** STOP the run. Surface to user with phase ID, unresolved findings, review artifact path. Do not proceed to subsequent phases.
 - **Parallel group mode:** mark the phase `excluded`. Do not merge its worktree. Continue the remaining phases in the group. Report in Outstanding Items after the group completes.
 
+### Optional External Phase Review Gate
+
+After the standard per-phase reviewer passes and after the required phase bookkeeping commit is cleanly recorded, check `oat_phase_review_gate`.
+
+If the gate is enabled and the current phase is selected:
+
+1. Run the gate from the orchestration branch with the active project path:
+
+   ```bash
+   oat --json gate review \
+     --project "$PROJECT_PATH" \
+     --review-type code \
+     --review-scope "{pNN}" \
+     --exit-nonzero-on "{threshold}" \
+     '$oat-project-review-provide code {pNN}'
+   ```
+
+   - `{threshold}` comes from `oat_phase_review_gate.exit_nonzero_on` (default: `important`).
+   - `{pNN}` is the completed phase ID.
+   - Do not pass `--target` in normal execution; the existing gate config selects the cross-provider target.
+   - The gate CLI injects gate context into the review prompt. The produced review artifact must use `oat_review_invocation: gate`.
+
+2. Parse the JSON result. The gate verdict (`exit_nonzero_on: {threshold}`) decides whether the phase **stops**; it does not decide whether sub-threshold findings are ignored. Either way the produced artifact must be **consumed** — passing gate artifacts are not left unprocessed at the top level of `reviews/`.
+   - `status: "ok"` / exit code `0` means the phase gate passed at the configured threshold, so the phase does not stop. Still run `oat-project-review-receive` for the reported artifact path in non-pausing **judgment-sweep** mode (pass gate-passed context so receive selects sweep disposition). The sweep makes a per-finding judgment for each Medium/Minor — defer to final (default), address now (small/contained/low-risk fixes only), or reject with rationale — writes those durable dispositions into `implementation.md`, and archives the artifact. Then continue without pausing. Address-now fixes from a passing gate do **not** re-trigger the standard reviewer or re-gate the phase.
+   - `status: "blocked"` / non-zero exit due to review findings means blocking findings exist. Run `oat-project-review-receive` for the reported artifact path (blocking disposition) before treating the gate review as consumed.
+   - A non-zero exit caused by target execution failure, artifact validation failure, or missing review artifact is an operational failure. Stop and surface the gate output; do not continue as if the gate passed.
+
+3. If `oat-project-review-receive` adds fix tasks (blocking gate, or a sweep address-now fix that revealed a Critical/Important concern):
+   - Return to task execution for the newly added review-fix tasks.
+   - After fixes land, re-run the standard per-phase reviewer and this external phase gate for the same phase.
+   - Continue only after both the standard reviewer and the external phase gate pass.
+   - Bound these gate block → fix → re-gate rounds by `oat_orchestration_retry_limit` (from `state.md`, default `2`). If the limit is exhausted with the gate still blocking, apply the same terminal handling as the standard bounded fix loop: **sequential mode** stops the run and surfaces the phase ID, unresolved findings, and artifact path; **parallel group mode** marks the phase `excluded` and reports it in Outstanding Items.
+
+4. If the judgment sweep (passing gate) records only deferrals/rejections and no blocking fix tasks, record the receive result and continue.
+
+For a parallel group, run selected phase gates after fan-in and bookkeeping, one gate per successfully merged phase in plan order. If a phase gate blocks, stop the schedule and process that gate's review before starting later schedule entries.
+
 ### Parallel Group Execution
 
 When the current schedule entry is a multi-phase group, execute as follows.
@@ -966,7 +1036,7 @@ When the current schedule entry is a multi-phase group, execute as follows.
 
     For phases that were excluded (fix-loop exhausted), preserve the worktree and log its path in `implementation.md` Outstanding Items.
 
-8.  **Bookkeeping commit** after the group completes. Then HiLL checkpoint check.
+8.  **Bookkeeping commit** after the group completes. Then run any selected external phase review gates. After those gates pass, perform the HiLL checkpoint check.
 
 ### Step 7: Artifact Updates After Each Phase (or Group)
 
@@ -1039,7 +1109,7 @@ git add {PROJECT_PATH}/implementation.md {PROJECT_PATH}/state.md {PROJECT_PATH}/
 git commit -m "chore(oat): bookkeeping after {pNN} {pass|fail}"
 ```
 
-Then check HiLL checkpoint — if the phase ID is in `oat_plan_hill_phases`, pause for user approval before continuing.
+Then run the optional external phase review gate for the completed phase when `oat_phase_review_gate` selects it. After the gate passes or is skipped, check HiLL checkpoint — if the phase ID is in `oat_plan_hill_phases`, pause for user approval before continuing.
 
 ### Step 8: Check Plan Phase Completion
 
@@ -1130,6 +1200,7 @@ Do not use `git add -A` or glob patterns. Only commit the three project artifact
 
 - **Workflow HiLL** (`oat_hill_checkpoints` in state.md): Gates between workflow phases (discovery → spec → design → plan → implement). Checked by oat-project-progress router.
 - **Plan phase checkpoints** (`oat_plan_hill_phases` in plan.md): Gates at plan phase boundaries during implementation. `[]` means pause after every phase; a populated array pauses only after listed phases. The field may be absent only before the first implementation-run confirmation. Listed phases are where you stop AFTER completing them.
+- **Phase review gate** (`oat_phase_review_gate` in plan.md): Optional non-pausing external review gate after a completed phase passes the standard reviewer. Missing/disabled means skip; `phases: []` means gate every implementation phase. Passing gates continue automatically; blocking gates are received/fixed before execution proceeds.
 
 **Revision phase completion handling:**
 
@@ -1296,7 +1367,7 @@ echo "$FINAL_ROW"
 **If final review row exists and status is `passed`:**
 
 - Example row:
-  - `| final | code | passed | 2026-01-28 | reviews/final-review-2026-01-28.md |`
+  - `| final | code | passed | 2026-01-28 | reviews/final-review-2026-01-28T140322Z.md |`
 - Check:
   ```bash
   echo "$FINAL_ROW" | grep -qE "^\\|\\s*final\\s*\\|.*\\|\\s*passed\\s*\\|" && echo "passed"
@@ -1446,7 +1517,7 @@ Final verification:
 
 Final review:
 - Status: ✓ passed
-- Artifact: reviews/final-review-{date}.md
+- Artifact: reviews/final-review-{timestamp}.md
 
 Next: Create PR or run the oat-project-pr-final skill (when available)
 ```

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.3.8
+version: 1.3.10
 description: Use when the user explicitly asks to review an OAT project — e.g. "review project", "review the project", "run project review", or confirms a previously offered review. Do NOT auto-invoke on completed work alone. Resolves a project review scope and offers before running.
 disable-model-invocation: false
 user-invocable: true
@@ -25,11 +25,13 @@ Reviewers should distinguish implementation defects from artifact drift. If code
 
 ## Model Invocation Gate
 
-This skill is model-invokable only for explicit review asks such as "review project" or "review the project", or when the user confirms a previously offered project-review step. Do NOT auto-invoke merely because a task, phase, or implementation appears complete.
+This skill is model-invokable only for explicit review asks such as "review project" or "review the project", or when the user confirms a previously offered project-review step. A gate-originated request from `oat gate review` is also an explicit review ask. Do NOT auto-invoke merely because a task, phase, or implementation appears complete.
 
 Before acting, verify that there is an active OAT project or a user-provided review target that can be resolved to project state. If neither exists, do not run this skill; offer `oat-project-open` / `oat-project-quick-start` for project workflow setup, or `oat-review-provide` for a non-project ad-hoc review.
 
-When the gate passes, summarize the inferred review type and scope, then ask before running the review.
+When the invocation is manual, summarize the inferred review type and scope, then ask before running the review.
+
+**Gate-originated mode:** If the request context says the review is gate-originated, set `REVIEW_INVOCATION=gate`, honor any provided review type/scope arguments, and run without interactive confirmation prompts. The gate session is already the explicit authorization boundary. If subagent dispatch is unavailable, run the review inline in the current gate session instead of handing off to a fresh session.
 
 ## Mode Assertion
 
@@ -123,7 +125,7 @@ Tell user:
   - `oat-project-quick-start` (new quick project)
   - `oat-project-import-plan` (external plan import)
 
-If validation passes, derive `{project-name}` as basename of `PROJECT_PATH`. Summarize the resolved project/review target and ask before continuing to Step 1.
+If validation passes, derive `{project-name}` as basename of `PROJECT_PATH`. Summarize the resolved project/review target. For manual invocation, ask before continuing to Step 1. For `REVIEW_INVOCATION=gate`, continue without asking.
 
 ### Step 1: Parse Arguments or Ask
 
@@ -424,6 +426,8 @@ Files changed: {FILE_COUNT}
 Proceed with review?
 ```
 
+If `REVIEW_INVOCATION=gate`, print the same scope summary but do not ask `Proceed with review?`; continue directly.
+
 ### Step 4.1: Dispatch Profile Override Advisory (Artifact Plan Only)
 
 When reviewing `artifact plan`, apply this Dispatch Profile override advisory:
@@ -536,6 +540,7 @@ Detection logic:
 - If the runtime can dispatch reviewer work (`subagent_type` in Claude Code, Cursor invocation via `/name` or natural mention, or Codex multi-agent spawn/auto-spawn) → **Tier 1**.
 - If the Task tool is not available or subagent dispatch is not supported → **Tier 2**.
 - If user explicitly requests inline or confirms they are already in a fresh session → **Tier 3**.
+- If `REVIEW_INVOCATION=gate` and Tier 1 is unavailable, skip Tier 2 and use **Tier 3** inline. Do not return fresh-session instructions from a gate invocation.
 
 **Step 6b: Tier 1 — Subagent (if available)**
 
@@ -566,6 +571,7 @@ If subagent not available:
 - If user is already in a fresh session (confirmed), proceed to Tier 3.
 - If Codex reported `authorization required` and the user approved delegation, do **not** use Tier 2. Return to Tier 1 and delegate to `oat-reviewer`.
 - If user prefers fresh session: provide instructions and exit.
+- If `REVIEW_INVOCATION=gate`: do not provide fresh-session instructions; run Tier 3 inline instead.
 
 Instructions for fresh session:
 
@@ -599,13 +605,15 @@ Review storage contract:
 
 **Naming convention:**
 
-- Phase review: `{PROJECT_PATH}/reviews/pNN-review-YYYY-MM-DD.md`
-- Task review: `{PROJECT_PATH}/reviews/pNN-tNN-review-YYYY-MM-DD.md`
-- Final review: `{PROJECT_PATH}/reviews/final-review-YYYY-MM-DD.md`
-- Range review: `{PROJECT_PATH}/reviews/range-review-YYYY-MM-DD.md`
-- Artifact review: `{PROJECT_PATH}/reviews/artifact-{artifact}-review-YYYY-MM-DD.md`
+Use a seconds-precision **UTC** timestamp token (`YYYY-MM-DDTHHMMSSZ`, from `date -u +%Y-%m-%dT%H%M%SZ` — the `-u` and the trailing `Z` are mandatory), not a date-only or local-time stamp, so that same-scope re-reviews and re-gates within one day never collide and `oat review latest` orders them by recency:
+
+- Phase review: `{PROJECT_PATH}/reviews/pNN-review-YYYY-MM-DDTHHMMSSZ.md`
+- Task review: `{PROJECT_PATH}/reviews/pNN-tNN-review-YYYY-MM-DDTHHMMSSZ.md`
+- Final review: `{PROJECT_PATH}/reviews/final-review-YYYY-MM-DDTHHMMSSZ.md`
+- Range review: `{PROJECT_PATH}/reviews/range-review-YYYY-MM-DDTHHMMSSZ.md`
+- Artifact review: `{PROJECT_PATH}/reviews/artifact-{artifact}-review-YYYY-MM-DDTHHMMSSZ.md`
 
-**If file exists for today:** append `-v2`, `-v3`, etc.
+Set `oat_generated_at` in the artifact frontmatter to the matching full timestamp (`YYYY-MM-DDTHH:MM:SSZ`). Same-second collisions are effectively impossible for sequential runs; if one occurs, append `-v2`, `-v3`, etc.
 
 **Important:** `PROJECT_PATH` here must be the resolved path from Step 1.5. If a worktree was detected, this path is relative to the worktree root, ensuring the artifact is written on the correct branch.
 
@@ -636,7 +644,7 @@ Shared ad-hoc companion reference (non-project mode):
 ```markdown
 ---
 oat_generated: true
-oat_generated_at: { today }
+oat_generated_at: { full UTC timestamp, e.g. 2026-07-06T11:16:01Z }
 oat_review_scope: { scope }
 oat_review_type: { code|artifact }
 oat_review_invocation: { manual|auto|gate }
@@ -655,9 +663,13 @@ oat_project: { PROJECT_PATH }
 
 - `manual` (default): Review was manually triggered by the user. `oat-project-review-receive` uses standard disposition behavior (user prompts for triage, minors auto-deferred for non-final scopes).
 - `auto`: Review was spawned by the auto-review checkpoint trigger in `oat-project-implement`. `oat-project-review-receive` uses relaxed disposition: minors are auto-converted to fix tasks (not deferred), no user prompts for disposition decisions.
-- `gate`: Review was spawned by `oat gate review`. Gate-originated reviews use normal stateful review-provide behavior: write the review artifact, update the `## Reviews` row, and commit review bookkeeping. `oat-project-review-receive` treats gate reviews with the same standard disposition behavior as manual reviews unless a future implementation explicitly designs autonomous receive.
+- `gate`: Review was spawned by `oat gate review` for a workflow gate. Gate-originated reviews use normal stateful review-provide behavior: write the review artifact, update the `## Reviews` row, and commit review bookkeeping. The gate CLI maps the review artifact findings to exit status, and `oat-project-review-receive` dispositions gate reviews autonomously (no user prompts) — selecting convert-to-fix-tasks when the gate **blocked** at its threshold, or non-pausing judgment-sweep disposition (defer / small-fix-now / reject, with sub-threshold findings recorded durably) when the gate **passed**.
+
+When `oat-project-implement` spawns this skill for auto-review at checkpoints, it passes context indicating auto invocation. Set `oat_review_invocation: auto` in the artifact frontmatter.
+
+When `oat gate review` invokes this skill, it includes gate-originated context instructing the reviewer to write `oat_review_invocation: gate`. Honor that instruction in the artifact frontmatter.
 
-When `oat-project-implement` spawns this skill for auto-review at checkpoints, it passes context indicating auto invocation. Set `oat_review_invocation: auto` in the artifact frontmatter. When `oat gate review` spawns this skill, set `oat_review_invocation: gate`. For all other invocations (user-triggered, fresh session), use `manual`.
+For all other invocations (user-triggered, fresh session), use `manual`.
 
 Gate parsing contract:
 

package/assets/skills/oat-project-review-receive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-receive
-version: 1.5.4
+version: 1.5.6
 description: Use when the user explicitly asks to receive review findings for an OAT project — e.g. "receive review", "process review", "process the project review", or confirms a previously offered review-receive step. Do NOT auto-invoke merely because a review file exists. Resolves the latest review and offers before acting.
 disable-model-invocation: false
 user-invocable: true
@@ -102,7 +102,7 @@ fi
 
 Selection rules:
 
-- Use `oat review latest` as the first-choice resolver. It scans project reviews (`reviews/` and `reviews/archived/`) plus ad-hoc review locations and orders candidates by `oat_generated_at` frontmatter rather than filesystem mtime.
+- Use `oat review latest` as the first-choice resolver. It scans project reviews (`reviews/` and `reviews/archived/`) plus ad-hoc review locations and orders candidates by `oat_generated_at` frontmatter rather than filesystem mtime. Review artifacts carry a seconds-precision `oat_generated_at` and a matching timestamped filename, so same-scope same-day re-gates order deterministically and the newest round wins — never assume the plain `<scope>-review-<date>.md` name is current.
 - Read the JSON result:
   - `path: null` means no review target was found.
   - `kind: "project"` and `actionable: true` means this skill can process the target when the path is an active top-level project review.
@@ -267,15 +267,23 @@ Read `oat_review_type` and `oat_review_invocation` from review artifact frontmat
   - Require explicit user confirmation before applying any artifact edits.
   - Resolve findings directly in artifact files; do not convert findings into plan tasks.
   - Do not defer findings by default. Only use `rejected_with_rationale` for invalid findings, or `needs_user_direction` when user input is required.
-- If `oat_review_type == code` AND `oat_review_invocation == auto`:
-  - **Auto-disposition mode.** This review was spawned by the auto-review checkpoint trigger in `oat-project-implement`. Apply relaxed disposition defaults:
+- If `oat_review_type == code` AND `oat_review_invocation == auto`, OR `oat_review_invocation == gate` from a **blocking** gate (the gate-originated context does not indicate a passing-gate sweep):
+  - **Auto-disposition mode.** This review was spawned by the auto-review checkpoint trigger in `oat-project-implement` or by a blocking `oat gate review`. Apply relaxed disposition defaults:
     - Critical/Important/Medium: convert to fix tasks (same as manual mode)
-    - Minor: auto-convert to fix tasks unless clearly out of scope (e.g., cosmetic polish unrelated to changed code). Manual mode now also defaults minors to `convert` (see Step 9); auto mode keeps the same intent — fix everything while context is fresh — but without any user prompts.
-    - **No user prompts for disposition decisions.** The auto-review path runs fully autonomously.
+    - Minor: auto-convert to fix tasks unless clearly out of scope (e.g., cosmetic polish unrelated to changed code). Manual mode now also defaults minors to `convert` (see Step 9); auto/gate mode keeps the same intent — fix everything while context is fresh — but without any user prompts.
+    - **No user prompts for disposition decisions.** The auto/gate review path runs fully autonomously.
     - Genuinely ambiguous findings (e.g., a medium the agent disagrees with) are deferred with a note explaining why, rather than pausing for interactive resolution.
   - Follow the task-conversion flow in Steps 3-10 with these adjusted defaults.
-- If `oat_review_type == code` AND `oat_review_invocation == gate`:
-  - **Gate review mode.** This review was spawned by `oat gate review`, but receive remains standard disposition behavior. Treat `gate` the same as manual for prompts, finding conversion, artifact archival, and bookkeeping unless a future implementation explicitly designs an autonomous receive path.
+- If `oat_review_type == code` AND `oat_review_invocation == gate` from a **passing** gate (the gate-originated context indicates a passing-gate judgment sweep):
+  - **Judgment-sweep mode.** The phase gate already passed at its `exit_nonzero_on` threshold, so the phase does not stop. Consume the artifact anyway, so its sub-threshold findings become durable, ordered dispositions in `implementation.md` instead of evaporating. Fully non-pausing; no user prompts.
+    - The gate verdict decided whether the phase stops; it did **not** decide whether Medium/Minor findings are ignored. There are, by definition, no unresolved Critical/Important findings in a passing gate (if there were, the gate would have blocked).
+    - Make a per-finding **judgment call** for each Medium/Minor — do not mechanically dump them all:
+      - **Defer to final** (default): record under "Deferred Findings" (Mediums under "Deferred Findings (Medium)" so Step 8.5 resurfacing picks them up) with concrete rationale.
+      - **Address now:** only for small, contained, low-risk fixes. Apply the fix, commit it with the phase bookkeeping, and record the disposition. Do **not** re-run the standard reviewer or re-gate the phase for address-now fixes.
+      - **Reject** as false-positive / out-of-scope, with concrete rationale.
+    - `address now` is an **exception, not the norm** — when in doubt, defer. Do not let a passing gate drift into behaving like a Medium-blocking gate by habit.
+    - **Escalation exception:** if an address-now fix reveals or creates a Critical/Important concern, stop treating it as a sweep item. Convert it to a fix task and return control to the blocking-gate path (`oat-project-implement` re-runs the standard reviewer and the gate for the phase).
+    - Do not add blocking fix tasks for deferred or rejected findings. After recording all dispositions, archive the artifact (Step 7.5) and commit review bookkeeping (Step 7.6) as usual.
 - If `oat_review_type == code` (manual or `oat_review_invocation` absent):
   - Follow the existing task-conversion flow in Steps 3-10 with standard disposition behavior.
 
@@ -483,13 +491,15 @@ If the project itself is still untracked because earlier lifecycle steps never c
 
 **Bounded loop protection:**
 
-Count how many review cycles have occurred for this scope:
+Count how many review cycles have occurred for this scope. Exclude gate-originated artifacts (`oat_review_invocation: gate`): the cap measures failed fix cycles of the standard review loop, not artifact volume, and phase gate re-runs are governed by the phase review gate flow in `oat-project-implement`, not by this cap.
 
 ```bash
 {
   find "$PROJECT_PATH/reviews" -maxdepth 1 -type f -name "*$SCOPE_TOKEN*.md" 2>/dev/null
   find "$PROJECT_PATH/reviews/archived" -maxdepth 1 -type f -name "*$SCOPE_TOKEN*.md" 2>/dev/null
-} | wc -l
+} | while IFS= read -r artifact; do
+  grep -q "oat_review_invocation: gate" "$artifact" || echo "$artifact"
+done | wc -l
 ```
 
 **If 3 or more cycles:**

package/assets/skills/oat-review-provide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-review-provide
-version: 1.2.2
+version: 1.2.3
 description: Use when you need an ad-hoc review outside an active OAT project lifecycle. Reviews code or artifacts without project phase state, unlike oat-project-review-provide.
 argument-hint: '[unstaged|staged|base_branch=<branch>|base_sha=<sha>|<sha1>..<sha2>|--files <path1,path2,...>] [--output <path>] [--mode auto|local|tracked|inline]'
 disable-model-invocation: true
@@ -151,18 +151,20 @@ If user asks for tracked `.oat/repo/reviews` and it is gitignored, warn and ask
 
 Derive a **scope slug** from the resolved scope mode so that the filename indicates what was reviewed:
 
-| Scope mode             | Slug derivation                      | Example filename                              |
-| ---------------------- | ------------------------------------ | --------------------------------------------- |
-| `base_branch=<branch>` | Current branch name                  | `ad-hoc-review-2026-02-16-oat-repo.md`        |
-| `unstaged`             | Literal `unstaged`                   | `ad-hoc-review-2026-02-16-unstaged.md`        |
-| `staged`               | Literal `staged`                     | `ad-hoc-review-2026-02-16-staged.md`          |
-| `--files <paths>`      | First 2–3 basenames, joined with `-` | `ad-hoc-review-2026-02-16-auth-login.md`      |
-| `base_sha=<sha>`       | Short SHA (7 chars)                  | `ad-hoc-review-2026-02-16-abc1234.md`         |
-| `<sha1>..<sha2>`       | Both short SHAs joined with `-`      | `ad-hoc-review-2026-02-16-abc1234-def5678.md` |
+| Scope mode             | Slug derivation                      | Example filename                                      |
+| ---------------------- | ------------------------------------ | ----------------------------------------------------- |
+| `base_branch=<branch>` | Current branch name                  | `ad-hoc-review-2026-02-16T140322Z-oat-repo.md`        |
+| `unstaged`             | Literal `unstaged`                   | `ad-hoc-review-2026-02-16T140322Z-unstaged.md`        |
+| `staged`               | Literal `staged`                     | `ad-hoc-review-2026-02-16T140322Z-staged.md`          |
+| `--files <paths>`      | First 2–3 basenames, joined with `-` | `ad-hoc-review-2026-02-16T140322Z-auth-login.md`      |
+| `base_sha=<sha>`       | Short SHA (7 chars)                  | `ad-hoc-review-2026-02-16T140322Z-abc1234.md`         |
+| `<sha1>..<sha2>`       | Both short SHAs joined with `-`      | `ad-hoc-review-2026-02-16T140322Z-abc1234-def5678.md` |
 
 ```bash
 mkdir -p "$OUTPUT_DIR"
-TODAY=$(date +%Y-%m-%d)
+# Seconds-precision UTC token so same-scope same-day re-reviews never collide and
+# order by recency in `oat review latest`. The trailing Z (UTC) is mandatory.
+STAMP=$(date -u +%Y-%m-%dT%H%M%SZ)
 
 # Derive SCOPE_SLUG based on scope mode (examples):
 # base_branch → SCOPE_SLUG=$(git branch --show-current | tr '/' '-')
@@ -174,10 +176,10 @@ TODAY=$(date +%Y-%m-%d)
 # Sanitize: lowercase, replace non-alphanumeric with '-', collapse runs, trim to 40 chars
 SCOPE_SLUG=$(echo "$SCOPE_SLUG" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g; s/--*/-/g; s/^-//; s/-$//' | cut -c1-40)
 
-OUT_FILE="$OUTPUT_DIR/ad-hoc-review-${TODAY}-${SCOPE_SLUG}.md"
+OUT_FILE="$OUTPUT_DIR/ad-hoc-review-${STAMP}-${SCOPE_SLUG}.md"
 ```
 
-If the file already exists (same scope reviewed twice in one day), suffix with `-v2`, `-v3`, etc.
+Set `oat_generated_at` in the artifact frontmatter to the matching full UTC timestamp (`YYYY-MM-DDTHH:MM:SSZ`). Same-second collisions are effectively impossible for sequential runs; if one occurs, suffix with `-v2`, `-v3`, etc.
 
 ### Step 4: Run Review
 

package/assets/skills/oat-review-provide/references/review-artifact-template.md

@@ -5,7 +5,7 @@ Use this template for non-project commit-range reviews.
 ````markdown
 ---
 oat_generated: true
-oat_generated_at: YYYY-MM-DD
+oat_generated_at: YYYY-MM-DDTHH:MM:SSZ
 oat_review_type: code
 oat_review_scope: { scope }
 oat_review_scope_mode: { files|unstaged|staged|range }

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"}