@open-agent-toolkit/cli 0.1.53 → 0.1.54

package/assets/skills/oat-repo-improve/references/plan-template.md

@@ -1,199 +1,200 @@
-# Handoff Plan Template
+# External Implementation Plan Template
 
-Every plan is written for an executor model that has **zero context**: it has not seen the advisor session, the audit, the other plans, or any prior conversation. It may be a smaller/cheaper model. Assume it is competent at following explicit instructions and weak at filling gaps, recovering from ambiguity, or knowing when to stop.
+Use this template for plans written by `oat-repo-improve`. Every plan must stand alone for an executor that has zero context from the advisor session, source review, backlog discussion, or sibling plans.
 
-Three properties make a plan executable by a weaker model:
+External plans are durable reference artifacts. They are deliberately not canonical OAT `plan.md` files and must not contain OAT phase IDs, task IDs, lifecycle readiness, review tables, or implementation bookkeeping.
 
-1. **Self-contained context** — everything needed is in the file: paths, code excerpts, conventions, commands.
-2. **Verification gates** — every step ends with a command and its expected result. The executor never has to _judge_ whether it succeeded.
-3. **Hard boundaries and escape hatches** — explicit out-of-scope list, and "STOP and report" conditions instead of letting the model improvise when reality doesn't match the plan.
+## File Contract
 
-File naming: `plans/NNN-short-slug.md`, numbered in recommended execution order.
+Write plans under `.oat/repo/reference/external-plans/` as:
 
+`YYYY-MM-DD-<short-slug>.md`
+
+Use this frontmatter:
+
+```yaml
+---
+oat_generated: true
+oat_external_plan: true
+oat_external_plan_source: repo-audit|maintainability-review|backlog-review|backlog-directory|backlog-item
+oat_external_plan_sources:
+  - <repo-relative source artifact or scope>
+oat_external_plan_commit: <short SHA>
+oat_backlog_items: []
+oat_issue_url: null
+created: '<ISO 8601 UTC>'
 ---
+```
 
-## Template
+`oat_backlog_items` contains backlog IDs represented by the plan. Keep it empty when none apply. Set `oat_issue_url` only after confirmed issue publication. Never record absolute workstation paths in durable frontmatter.
 
-```markdown
-# Plan NNN: <Imperative title — what will be true after this plan>
-
-> **Executor instructions**: Follow this plan step by step. Run every
-> verification command and confirm the expected result before moving to the
-> next step. If anything in the "STOP conditions" section occurs, stop and
-> report — do not improvise. When done, update the status row for this plan
-> in `plans/README.md` — unless a reviewer dispatched you and told you they
-> maintain the index.
->
-> **Drift check (run first)**: `git diff --stat <planned-at SHA>..HEAD -- <in-scope paths>`
-> If any in-scope file changed since this plan was written, compare the
-> "Current state" excerpts against the live code before proceeding; on a
-> mismatch, treat it as a STOP condition.
+## Plan Template
 
-## Status
+````markdown
+# <Imperative title: what will be true after execution>
 
-- **Priority**: P1 | P2 | P3
-- **Effort**: S | M | L
-- **Risk**: LOW | MED | HIGH
-- **Depends on**: plans/NNN-\*.md (or "none")
-- **Category**: bug | security | perf | tests | tech-debt | migration | dx | docs | direction
-- **Planned at**: commit `<short SHA>`, <YYYY-MM-DD>
-- **Issue**: <GitHub issue URL — only when published via `--issues`; omit otherwise>
+> [!NOTE]
+> This is an external implementation plan, not a canonical OAT project
+> `plan.md`. Execute it directly, or import it for tracked OAT execution with
+> `oat-project-import-plan <this-file>`.
+>
+> Begin with the drift check. Follow the steps and verification gates in order.
+> If a STOP condition occurs, stop and report instead of improvising.
 
-## Why this matters
+## Outcome
 
-2–5 sentences. The problem, its concrete cost, and what improves when this
-lands. Written so the executor (and a human reviewer) understands the intent —
-intent is what lets a correct judgment call happen when a detail is off.
+State the observable end result in 2–5 sentences. Explain why it matters and preserve the source intent in language an executor and reviewer can understand without opening the source artifact.
 
-## Current state
+## Source and live evidence
 
-The facts the executor needs, inlined — never "as discussed" or "see audit":
+- Source artifact or scope: `<repo-relative path or scope>`
+- Planned at: commit `<short SHA>` on `<YYYY-MM-DD>`
+- Related backlog items: `<ID and title, or none>`
+- Verified evidence:
+  - `<file:line or command evidence>` — what it establishes
 
-- The relevant files, each with one line on its role:
-  - `src/orders/api.ts` — order-list endpoint; contains the N+1 (lines 130–160)
-- Excerpts of the code as it exists today (short, with `file:line` markers),
-  enough that the executor can confirm it's looking at the right thing.
-- The repo conventions that apply here, with a pointer to one exemplar file:
-  "Error handling follows the Result pattern — see `src/lib/result.ts` and its
-  use in `src/users/api.ts:40-60`. Match it."
-- Any documented vocabulary or design constraints the plan must honor, inlined
-  from the intent/design docs found in recon: the relevant `CONTEXT.md` terms
-  the executor should use in names and comments, the `DESIGN.md` tokens/components
-  to reuse, or the ADR whose decision this work must stay consistent with. Quote
-  the specific lines — the executor has not read those docs.
+Distinguish source assertions from facts verified against the live repository. Do not copy stale evidence forward.
 
-## Commands you will need
+## Drift check
 
-| Purpose   | Command                 | Expected on success |
-| --------- | ----------------------- | ------------------- |
-| Install   | `pnpm install`          | exit 0              |
-| Typecheck | `pnpm typecheck`        | exit 0, no errors   |
-| Tests     | `pnpm test -- <filter>` | all pass            |
-| Lint      | `pnpm lint`             | exit 0              |
+Run before editing:
+
+```bash
+git diff --stat <planned-at SHA>..HEAD -- <in-scope paths>
+```
+````
 
-(Exact commands from this repo — verified during recon, not guessed.)
+If an in-scope file changed, compare the plan's current-state evidence with the live code. A material mismatch is a STOP condition unless the plan explicitly explains how to reconcile it.
 
-## Suggested executor toolkit
+## Repository conventions
 
-(Optional — include only when relevant skills/tools plausibly exist in the
-executor's environment. Skip the section otherwise.)
+- Build: `<exact command>` → `<expected success>`
+- Typecheck: `<exact command or not applicable>`
+- Test: `<exact command>` → `<expected success>`
+- Lint/format check: `<exact non-mutating command>`
+- Implementation pattern: `<exemplar file and the convention to match>`
+- Git/PR convention: `<observed convention; do not push/open a PR unless instructed>`
 
-- Skills the executor should invoke if available, and for what:
-  "use `vercel-react-best-practices` when writing the memoization in step 3".
-- Reference docs worth reading before starting, by path or URL.
+Only include commands verified from repository instructions or configuration.
 
 ## Scope
 
-**In scope** (the only files you should modify):
+### In scope
 
-- `src/orders/api.ts`
-- `src/orders/api.test.ts` (create)
+- `<exact file, directory, symbol, or behavior>`
 
-**Out of scope** (do NOT touch, even though they look related):
+### Out of scope
 
-- `src/orders/legacy-api.ts` — deprecated path, scheduled for deletion;
-  changing it wastes effort and risks the v1 clients still pinned to it.
-- Any change to the public response shape — clients depend on it.
+- `<specific adjacent concern>` — `<why it must remain untouched>`
 
-## Git workflow
+## Current state
+
+Describe the minimum facts needed to execute safely:
 
-(Filled from recon — match the repo's observed conventions.)
+- role of each relevant file or module;
+- short current-state excerpts with `file:line` markers when exact code shape matters;
+- applicable decisions, vocabulary, data contracts, or design constraints;
+- dependencies and assumptions established during vetting.
 
-- Branch: `advisor/NNN-<slug>` (or the repo's branch-naming convention if one is evident)
-- Commit per step or per logical unit; message style: <match repo, e.g. conventional commits — include an example from `git log`>
-- Do NOT push or open a PR unless the operator instructed it.
+## Implementation steps
 
-## Steps
+### 1. <Imperative step title>
 
-### Step 1: <imperative title>
+Name exact files and symbols. Describe the target behavior or code shape and any boundary that must remain stable.
 
-What to do, precisely. Reference exact files/symbols. Include the target code
-shape when it's load-bearing (the pattern to produce, not necessarily every
-line).
+**Verify:** `<command>` → `<expected output>`
 
-**Verify**: `<command>` → <expected output>
+### 2. <Imperative step title>
 
-### Step 2: ...
+Continue in dependency order. Keep each step independently checkable and leave the repository in a coherent state.
 
-(Each step small enough to verify independently. Order steps so the codebase
-is never broken between steps when possible — e.g. add new path, switch
-callers, then remove old path.)
+**Verify:** `<command>` → `<expected output>`
 
 ## Test plan
 
-- New tests to write, in which file, covering which cases (list them:
-  happy path, the specific bug/regression this plan fixes, named edge cases).
-- Which existing test to use as the structural pattern:
-  "model after `src/users/api.test.ts`".
-- Verification: `<test command>` → all pass, including N new tests.
+- Tests to add or change, with exact paths and named cases.
+- Existing test to use as the structural pattern.
+- Regression or failure mode each test proves.
+- Focused command and expected result.
+- Full relevant suite and expected result.
 
 ## Done criteria
 
-Machine-checkable. ALL must hold:
+- [ ] All in-scope behavior matches the stated outcome.
+- [ ] Focused tests pass with the expected cases.
+- [ ] Required build, typecheck, lint, and full relevant tests pass.
+- [ ] `git status --short` contains no unexplained or out-of-scope files.
+- [ ] Documentation or migration notes named by the plan are complete.
 
-- [ ] `pnpm typecheck` exits 0
-- [ ] `pnpm test` exits 0; new tests for <X> exist and pass
-- [ ] `grep -rn "<old pattern>" src/` returns no matches
-- [ ] No files outside the in-scope list are modified (`git status`)
-- [ ] `plans/README.md` status row updated
+Replace generic criteria with machine-checkable commands or observable assertions specific to the plan.
 
 ## STOP conditions
 
-Stop and report back (do not improvise) if:
+Stop and report instead of improvising when:
 
-- The code at the locations in "Current state" doesn't match the excerpts
-  (the codebase has drifted since this plan was written).
-- A step's verification fails twice after a reasonable fix attempt.
-- The fix appears to require touching an out-of-scope file.
-- You discover the assumption "<key assumption>" is false.
+- live state materially contradicts the verified evidence or drift assumptions;
+- a required change crosses an out-of-scope boundary;
+- a named verification gate fails twice after one bounded correction;
+- a load-bearing dependency, API, ownership assumption, or migration precondition is false;
+- the work would expose, copy, or rotate a credential without explicit authority.
 
-## Maintenance notes
+Add plan-specific STOP conditions for its actual risks.
 
-For the human/agent who owns this code after the change lands:
+## Review focus
 
-- What future changes will interact with this (e.g. "if pagination is added
-  to this endpoint, the batching in step 2 must be revisited").
-- What a reviewer should scrutinize in the PR.
-- Any follow-up explicitly deferred out of this plan (and why).
-```
+- What a reviewer should inspect most closely.
+- Compatibility or regression risks.
+- Follow-ups intentionally deferred and why.
 
----
+````
 
-## Index file: `plans/README.md`
+## Multi-Plan Index
 
-Written once by the advisor after all plans, updated by executors:
+When one run writes multiple plans, create `YYYY-MM-DD-<source-mode>-plan-index.md`:
 
 ```markdown
-# Implementation Plans
+---
+oat_generated: true
+oat_external_plan_index: true
+oat_external_plan_source: <source mode>
+oat_external_plan_sources:
+  - <source artifact or scope>
+oat_external_plan_commit: <short SHA>
+created: '<ISO 8601 UTC>'
+---
+
+# External Plan Index: <run title>
 
-Generated by the oat-repo-improve skill on <date>. Execute in the order below unless
-dependencies say otherwise. Each executor: read the plan fully before starting,
-honor its STOP conditions, and update your row when done.
+This index records selection and ordering. It is not an executable plan and is
+not an `oat-project-import-plan` target.
 
-## Execution order & status
+## Selection
 
-| Plan | Title | Priority | Effort | Depends on | Status |
-| ---- | ----- | -------- | ------ | ---------- | ------ |
-| 001  | ...   | P1       | S      | —          | TODO   |
-| 002  | ...   | P1       | M      | 001        | TODO   |
+- Selected: <why these candidates were chosen>
+- Deferred/rejected: <material candidates and rationale>
+- Unaudited or out of scope: <boundaries>
 
-Status values: TODO | IN PROGRESS | DONE | BLOCKED (with one-line reason) | REJECTED (with one-line rationale — finding fixed independently or approach abandoned)
+## Recommended order
+
+| Order | Plan | Source item/finding | Depends on | Tracking | Rationale |
+| --- | --- | --- | --- | --- | --- |
+| 1 | [Title](./YYYY-MM-DD-slug.md) | <ID/title or finding> | — | <backlog ID and/or issue URL, or none> | <reason> |
 
 ## Dependency notes
 
-- 002 requires 001 because <reason>.
+- <Dependency or parallel-lane explanation.>
+````
 
-## Findings considered and rejected
+Do not use a repository-wide `README.md` as the index. Do not ask executors to mutate the index; execution tracking belongs to the chosen execution workflow.
 
-- <finding>: not worth doing because <one line>. (So nobody re-audits it.)
-```
+## Quality Gate
 
-## Quality bar — check before finishing each plan
+Before finishing each plan, confirm:
 
-- Could a model that has never seen this repo execute this with only the plan file and the repo? If any step requires knowledge from the advisor session, inline that knowledge.
-- Is every verification a command with an expected result, not a judgment ("make sure it works")?
-- Does every step name exact files and symbols, not "the relevant module"?
-- Are the STOP conditions specific to this plan's actual risks, not boilerplate?
-- Would a reviewer reading only "Why this matters" + "Done criteria" understand what they're approving?
-- No secret values anywhere in the file — locations and credential types only.
-- "Planned at" SHA is filled in and the in-scope paths in the drift check match the Scope section.
+- It can be executed with only the plan and repository.
+- Every source claim used for implementation was verified live.
+- It has one coherent shippable outcome and verification boundary. Independent outcomes are separate plans; inseparable project-sized work is escalated to an OAT project/import decision.
+- Every step names exact files/symbols and ends in a command with an expected result.
+- Scope and STOP conditions are specific enough to prevent plausible but unauthorized expansion.
+- Frontmatter source paths are repo-relative and backlog IDs are exact.
+- No secret value, workstation-only absolute path, OAT task ID, or lifecycle bookkeeping appears.

package/assets/skills/oat-repo-maintainability-review/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: oat-repo-maintainability-review
-version: 1.2.0
-description: Use when you need a structured maintainability analysis for a repository or directory target with actionable findings.
+version: 1.3.0
+description: Use when you need a structured maintainability analysis for a repository or directory target with actionable findings and an optional external-plan handoff.
 argument-hint: '[--scope repo|directory] [--target <path>] [--mode auto|tracked|local|inline] [--output <path>] [--focus <areas>] [--analysis-mode full] [--fan-out]'
 disable-model-invocation: true
 user-invocable: true
@@ -42,11 +42,12 @@ Analyze repository maintainability and developer experience using a deterministi
   - ` OAT ▸ REPO MAINTAINABILITY REVIEW`
   - `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`
 - Print step indicators before major work:
-  - `[1/5] Resolving scope, arguments, and output policy...`
-  - `[2/5] Collecting repository evidence...`
-  - `[3/5] Running dimension analysis (single-agent or multi-agent)...`
-  - `[4/5] Synthesizing findings and scoring...`
-  - `[5/5] Rendering artifact and summary...`
+  - `[1/6] Resolving scope, arguments, and output policy...`
+  - `[2/6] Collecting repository evidence...`
+  - `[3/6] Running dimension analysis (single-agent or multi-agent)...`
+  - `[4/6] Synthesizing findings and scoring...`
+  - `[5/6] Rendering artifact and summary...`
+  - `[6/6] (Optional) Handing selected findings to repo improve...` — only print after the user accepts the offer
 - For long-running fan-out or large scans, print start + completion lines.
 - Print a resolved run-options summary before evidence collection begins.
 
@@ -58,6 +59,7 @@ Analyze repository maintainability and developer experience using a deterministi
 4. Gather evidence across required dimensions.
 5. Synthesize findings into prioritized recommendations.
 6. Render artifact or return inline output.
+7. Offer a scoped external-plan handoff when a file artifact exists.
 
 ### Output Policy Resolution
 
@@ -190,9 +192,22 @@ Final user-facing summary must include:
 - Artifact path (`inline-only` when no file is emitted)
 - Execution mode (`single-agent` or `multi-agent`)
 
+### Optional Repo Improve Handoff
+
+When tracked or local output produced a file artifact, offer one bounded next step after the completion summary:
+
+> Want to turn selected findings from this maintainability review into self-contained external implementation plans with `oat-repo-improve`?
+
+If the user accepts, invoke `oat-repo-improve` in `maintainability-review` mode and pass the exact artifact path. That skill must use this artifact as its candidate source and perform only bounded live-evidence verification; it must not repeat a full repository audit. The user selects which findings become plans.
+
+If output was inline-only, explain that the handoff requires a file-backed review artifact. Offer to render the completed review to the normal tracked/local destination before invoking `oat-repo-improve`; do not silently create it.
+
+The maintainability-review skill never writes external plans itself. `oat-repo-improve` is the sole owner of `.oat/repo/reference/external-plans/` output for this flow.
+
 ## Success Criteria
 
 - Output includes required sections and metadata.
 - Findings include scoring fields and evidence.
 - Result includes now/next/later execution guidance.
 - Required arguments are explicitly resolved before analysis execution.
+- File-backed runs offer an optional, source-scoped `oat-repo-improve maintainability-review <artifact>` handoff without re-auditing the repository.

package/assets/templates/backlog-item.md

@@ -10,6 +10,7 @@ assignee: null
 created: '{ISO 8601 UTC}'
 updated: '{ISO 8601 UTC}'
 associated_issues: []
+external_plans: [] # repo-relative .oat/repo/reference/external-plans/*.md paths
 oat_template: true
 oat_template_name: backlog-item
 ---

package/assets/templates/pjm-agents.md

@@ -60,6 +60,14 @@ doctor` surfaces this drift.
 recent commits against open items: work that shipped without a close-out
 should be closed retroactively with a note.
 
+## External Plan Reverse Links
+
+Backlog item frontmatter may include `external_plans`, a YAML string array of
+repo-relative paths under `.oat/repo/reference/external-plans/`.
+`oat-repo-improve` owns additions to this field after a plan write succeeds.
+Preserve existing links, deduplicate additions, and never link a failed or
+partial write. These are durable source-to-plan references, not project status.
+
 ## Project Kickoff Handoffs
 
 `handoffs/` holds one-shot kickoff prompts — consumable context for turning a

package/assets/templates/reference-agents.md

@@ -9,7 +9,9 @@ This directory owns append-mostly reference material.
 
 - `decisions/` stores file-per-record decisions and the generated decision index.
 - `project-summaries/` stores archived project summaries.
-- `external-plans/` stores imported provider or external plans.
+- `external-plans/` stores imported provider plans and external implementation
+  plans generated by `oat-repo-improve`. Improve owns plan generation; project
+  import optionally normalizes one selected file into an OAT project.
 - 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/`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.53",
+  "version": "0.1.54",
   "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.53"
+    "@open-agent-toolkit/control-plane": "0.1.54"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/assets/skills/oat-repo-improve/references/closing-the-loop.md

@@ -1,96 +0,0 @@
-# Closing the Loop — execute, reconcile, issues
-
-The advisor's job doesn't end at the plan. This file covers the three follow-through flows: dispatching an executor and reviewing its work (`execute`), keeping the plan backlog alive (`reconcile`), and publishing plans where work gets picked up (`--issues`).
-
-The founding rule survives unchanged: **the advisor never edits source code.** In `execute`, a _separate executor subagent_ edits code in an isolated git worktree; the advisor dispatches, reviews, and renders a verdict — like a tech lead who doesn't push commits to your branch.
-
----
-
-## `execute <plan>` — dispatch and review
-
-### Preconditions (check all before dispatching)
-
-- The repo is a git repository (worktree isolation requires it). If not: stop and say so.
-- The plan file exists and its dependencies show DONE in `plans/README.md`. If not: stop, name the missing dependency.
-- Run the plan's drift check yourself. If in-scope files changed since `Planned at`, reconcile the plan first (see below) — don't hand a stale plan to an executor.
-
-### Dispatch
-
-Spawn **one** `general-purpose` subagent with `isolation: "worktree"`. Executor model: default `sonnet`; use what the user named if they named one (`execute 003 haiku`).
-
-The subagent prompt must contain:
-
-1. **The full plan file text, inlined.** The worktree contains only committed files — if `plans/` is uncommitted, the executor can't read it. Never assume; always inline.
-2. The executor preamble:
-
-> You are the executor for the implementation plan below. Follow it step by
-> step. Run every verification command and confirm the expected result before
-> moving on. Touch only the files listed as in scope. If any STOP condition
-> occurs, stop immediately and report. Do not improvise around obstacles.
-> Commit your work in the worktree following the plan's git workflow section.
-> One override: SKIP the plan's instruction to update `plans/README.md` —
-> your reviewer maintains the index. Before reporting, audit every claim in
-> your report against an actual tool result from this session — only report
-> what you can point to evidence for; if a verification failed or was
-> skipped, say so plainly. When finished, reply with exactly the report
-> format below.
-
-3. The report format:
-
-```
-STATUS: COMPLETE | STOPPED
-STEPS: per step — done/skipped + verification command result
-STOPPED BECAUSE: (only if STOPPED) which STOP condition, what was observed
-FILES CHANGED: list
-NOTES: anything the reviewer should know (deviations, surprises, judgment calls)
-```
-
-### Review (the advisor's real job here)
-
-Note on fresh worktrees: they share git history but not `node_modules` or build artifacts — the executor must install dependencies first, and check tooling that resolves from `dist/` may need one build even though the plan's command table (recon'd in the main tree) didn't mention it. Expect this; it isn't a deviation.
-
-Review like a tech lead reviewing a PR against the spec — never fix anything yourself:
-
-1. **Re-run every done criterion** in the worktree. Don't trust the executor's report — verify.
-2. **Scope compliance**: `git -C <worktree> diff --stat` against the plan's in-scope list. Any file outside scope fails review, full stop.
-3. **Read the full diff.** Judge it against "Why this matters" (does it solve the actual problem?) and the repo conventions named in the plan (does it look like the rest of the codebase?).
-4. **Audit the new tests.** Executors game criteria — a test that asserts nothing meaningful passes `pnpm test` and proves nothing. Read what the tests assert.
-
-### Verdict
-
-**Documented deviations are judged on merit, not reflex-blocked.** "Do not improvise" exists to stop silent drift; an executor that hits a real obstacle (e.g. the plan's approach breaks existing test mocks), adapts minimally, and explains it in NOTES has done the right thing. Approve it if the adaptation serves the plan's intent and stays in scope; treat _undocumented_ deviations as review failures.
-
-| Verdict     | When                                                                     | Action                                                                                                                                                                                                                           |
-| ----------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **APPROVE** | Criteria pass, scope clean, quality holds                                | Update index status to DONE. Present to the user: diff summary, worktree path and branch, anything from NOTES. **Merging is the user's decision — never merge, push, or commit to their branch.**                                |
-| **REVISE**  | Fixable gaps                                                             | SendMessage to the same executor with specific, actionable feedback ("criterion 3 fails: X; the error handling in `api.ts:90` swallows the error — use the Result pattern per the plan"). **Max 2 revision rounds**, then BLOCK. |
-| **BLOCK**   | STOP condition hit, scope violated unrecoverably, or revisions exhausted | Mark BLOCKED in the index with the reason. Refine or rewrite the plan with what was learned. Tell the user what happened and what changed in the plan.                                                                           |
-
-Running verification commands inside the executor's worktree is fine — it's isolated and disposable. The no-mutating-commands rule protects the user's working tree, not the worktree.
-
----
-
-## `reconcile` — keep `plans/` alive
-
-Process what happened since the last session. Read `plans/README.md` and every plan file, then per status:
-
-- **DONE** — spot-check that the done criteria still hold on the current HEAD (cheap ones only). Mark verified in the index. Don't delete plan files — they're the record.
-- **BLOCKED** — read the reason. Investigate the underlying obstacle in the codebase. Either rewrite the plan around it (new number if the approach changed fundamentally, in-place refresh otherwise) or mark REJECTED with one line of rationale.
-- **IN PROGRESS** (stale) — flag it to the user; an executor probably died mid-run. Check the worktree if one exists.
-- **TODO** — run the drift check. If drifted: re-verify the finding still exists (it may have been fixed in passing), then refresh the "Current state" excerpts and `Planned at` SHA. If the finding is gone, mark REJECTED ("fixed independently").
-
-Finish with a short report: what's verified done, what was refreshed, what's rejected, and what's executable right now.
-
----
-
-## `--issues` — publish plans as GitHub issues
-
-Modifier on any planning invocation (`/oat-repo-improve --issues`, `/oat-repo-improve security --issues`). The flag is the user's authorization to create issues — never create them without it.
-
-1. Preflight: `gh auth status` succeeds and the repo has a GitHub remote. If either fails, write the plan files as normal and say why issues were skipped.
-2. Visibility check: `gh repo view --json visibility`. If the repo is **public**, warn the user that issues are publicly visible and get explicit confirmation before publishing any plan that describes a security vulnerability, credential location, or other sensitive finding.
-3. Show the list of titles about to become issues; confirm once if interactive.
-4. Per plan: `gh issue create --title "<plan title>" --body-file <plan file>`. Labels: `improve` plus the category — apply only if the labels exist or can be created without erroring; skip labels rather than fail.
-5. Record each issue URL in the plan's Status block (`- **Issue**: <url>`) and the index.
-
-The plan file remains the source of truth; the issue is distribution. The self-containment rule pays off here — the issue body needs no edits to make sense to whoever (or whatever) picks it up.