@open-agent-toolkit/cli 0.2.59 → 0.2.63

package/assets/docs/workflows/projects/pr-flow.md

@@ -17,10 +17,12 @@ Expected artifacts:
 - Required (all modes): `plan.md`
 - Required (spec-driven mode): `spec.md`, `design.md`
 - Optional (quick/import): `spec.md`, `design.md`
+- Not expected (lite): `discovery.md`, `spec.md`, or `design.md`
 - Recommended (quick mode): `discovery.md`
 - Recommended (import mode): `references/imported-plan.md`
 - Recommended: `implementation.md` final summary
 - Recommended: `summary.md` — pr-final treats it as the primary source for the PR Summary section and automatically refreshes it first when missing or stale
+- Lite source row: `oat-project-pr-final` uses the plan's Summary, Decisions, and Validation Criteria plus the `implementation.md` Final Summary; it does not create `summary.md` unless lite closeout explicitly opts in
 - Required gate for final PR: review table final row should be `passed`
 
 ## Output

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

@@ -173,7 +173,7 @@ This feature is opt-in and disabled by default (missing or `enabled: false`). Fo
 
 Generated planning and analysis artifacts have a separate review loop from code/phase reviews.
 
-For plans, `oat-project-plan`, `oat-project-quick-start`, and `oat-project-import-plan` run a bounded `plan.md` artifact review before marking the plan ready for implementation. The loop dispatches `oat-reviewer` in structured-output artifact mode with `scope: plan`, applies unambiguous Critical and Important artifact-local fixes, offers Medium and Minor fixes, and re-runs until clean or the retry bound is exhausted. A clean result records the `plan` row in the plan's `## Reviews` table as `passed`.
+For plans, `oat-project-plan`, `oat-project-quick-start`, `oat-project-lite`, and `oat-project-import-plan` run a bounded `plan.md` artifact review before marking the plan ready for implementation. The loop dispatches `oat-reviewer` in structured-output artifact mode with `scope: plan`, applies unambiguous Critical and Important artifact-local fixes, offers Medium and Minor fixes, and re-runs until clean or the retry bound is exhausted. A clean result records the `plan` row in the plan's `## Reviews` table as `passed`.
 
 For analysis artifacts, `oat-docs-analyze` and `oat-agent-instructions-analyze` run a bounded accuracy review after writing their severity-rated artifacts. The reviewer checks cited evidence, severity, and recommendations before the matching apply workflow consumes the artifact. The analysis loop updates tracking metadata to mark the artifact verified.
 

package/assets/docs/workflows/projects/state-machine.md

@@ -32,8 +32,14 @@ flowchart TD
   FA --> FC["Fixes completed"]
   FC --> PASSED["Review passed"]
   PASSED --> I
+
+  LITE["Lite: batched interview\n(no discovery/spec/design)"] -. entry point .-> P
 ```
 
+The solid chain is the spec-driven progression. Lite enters at **Plan in
+progress** and never sets `oat_phase` to `discovery`, `spec`, or `design`;
+quick and import projects also skip part of the leading chain.
+
 ## Phase status values
 
 `oat_phase_status` in `state.md`:
@@ -65,6 +71,20 @@ Typical progression:
 12. Revision loop (optional): `pr_open` → revise → `in_progress` → implement → `pr_open`
 13. Complete
 
+Lite progression:
+
+1. Plan in progress (`oat_workflow_mode: lite`, `oat_phase: plan`)
+2. Ready for implement (one approval; no discovery, spec, or design states)
+3. Implement in progress (single phase, no HiLL checkpoint pauses)
+4. Implement complete (final review passed)
+5. PR open (`pr_open`) — lite closeout routes straight to `oat-project-pr-final`
+6. Complete
+
+A lite project that outgrows one sitting can move to the quick chain with `oat
+project promote <project-path> --to quick`, which flips `oat_workflow_mode` to
+`quick` and sets `oat_phase: discovery` with `oat_phase_status: complete`. See
+[Lifecycle](lifecycle.md#promoting-a-lite-project-to-quick).
+
 ## Review progression
 
 In `plan.md` Reviews table:

package/assets/docs/workflows/skills/explainer-kit.md

@@ -420,10 +420,16 @@ Interactive project explainer and recap preferences resolve independently from
 the built-in default is `ask`. A resolved project decision in `state.md`
 outranks those preferences.
 
-Autonomous mode has stricter policy: it always attempts a project recap, while
-a project explainer runs only when the kickoff request explicitly asks for
-one. Lifecycle-triggered runs do not publish automatically, and recap failure
-does not block project completion.
+Autonomous mode has stricter policy: it always runs the project-recap gate,
+while a project explainer runs only when the kickoff request explicitly asks
+for one. The gate probes the five seams an unattended recap needs — author,
+fact critic, browser session, visual critic, and set planner — before
+generating. It attempts the recap only when all five resolve; when a seam has
+no provider configured at all, it records a `skip` with source
+`capability_probe` and a warning instead. A seam that is configured but invalid
+is a configuration error and still fails closed. Lifecycle-triggered runs do
+not publish automatically, and neither recap failure nor an unavailable seam
+blocks project completion.
 
 See [Project Artifacts](../projects/artifacts.md) for active and durable output
 locations, and [Configuration](../../cli-utilities/configuration.md) for the

package/assets/docs/workflows/skills/index.md

@@ -18,7 +18,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
 ## Key Skills by Use Case
 
-- Start a new tracked project: `oat-project-new` or `oat-project-quick-start` (quick start accepts a project name plus optional description; if you omit the description it should ask before discovery begins)
+- Start a new tracked project: `oat-project-new`, `oat-project-quick-start`, or `oat-project-lite` for a single-sitting change with one batched interview and one approval (quick start accepts a project name plus optional description; if you omit the description it should ask before discovery begins)
 - Resume an existing project: `oat-project-open` and `oat-project-progress`
 - Execute a ready plan: `oat-project-implement`
 - Import an existing plan: `oat-project-import-plan`
@@ -58,6 +58,7 @@ Use this section when you want to choose the right OAT skill for a task. If you
 
     - `oat-project-new`
     - `oat-project-quick-start`
+    - `oat-project-lite`
     - `oat-project-import-plan`
     - `oat-project-promote-spec-driven`
     - `oat-project-open`

package/assets/docs/workflows/skills/repo-improve.md

@@ -35,7 +35,7 @@ These are findings exclusions, not absolute read prohibitions. Improve may read
 
 ## Output boundary
 
-External plans are not canonical OAT project `plan.md` files. They contain self-contained context, scope, steps, verification, done criteria, and STOP conditions, but no OAT phase/task IDs or lifecycle bookkeeping.
+External plans are not canonical OAT project `plan.md` files. They contain self-contained context, scope, steps, verification, done criteria, and STOP conditions, but no canonical OAT phase/task IDs or lifecycle bookkeeping. External execution-readiness metadata is a separate thing and is carried deliberately: it describes whether the plan's own prerequisites have merged, not how an OAT project is moving through phases.
 
 After generation, choose either execution path:
 
@@ -44,6 +44,20 @@ After generation, choose either execution path:
 
 Project-sized candidates are split when possible. If inseparable work needs multiple design decisions or lacks one coherent verification boundary, improve recommends an OAT project workflow instead of emitting a mega-plan.
 
+## Plan readiness and execution readiness
+
+Improve scores candidates on two independent axes. A candidate is plan-ready when it is understood well enough to write a self-contained executable plan, and execution-ready when every hard dependency it names has already merged.
+
+A blocked candidate is still planned. Rather than dropping work whose prerequisite has not landed, improve writes the plan and records the block:
+
+- `oat_execution_status` is `READY` or `BLOCKED` in plan frontmatter.
+- A typed `## Dependencies` table marks each row `Hard`, `Soft`, or `Satisfied`, and every `Hard` row names the state that would unblock it.
+- `## Landing-event impact` records what to re-anchor when a named PR or project lands, and `## Revalidation Before Execution` records when the plan must be re-checked against live state.
+
+Plan provenance is recorded as two separate SHAs: `oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected, and `oat_external_plan_main_commit` is the fetched `origin/main` or merge-base used only for comparison. They may differ, and normally do when planning happens on a branch.
+
+Plans written before this contract landed are read in legacy mode: a short SHA, a missing comparison SHA, missing sections, and a missing status (read as `READY`) are all accepted, and those plans are never rewritten.
+
 ## Optional tracking
 
 Plans are always the primary output. Tracking is optional and source-aware:

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.59",
-  "docs-config": "0.2.59",
-  "docs-theme": "0.2.59",
-  "docs-transforms": "0.2.59"
+  "cli": "0.2.63",
+  "docs-config": "0.2.63",
+  "docs-theme": "0.2.63",
+  "docs-transforms": "0.2.63"
 }

package/assets/skills/oat-brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-brainstorm
-version: 1.3.5
+version: 1.3.6
 description: Use when the user explicitly invokes the `brainstorm` verb, including `/oat-brainstorm`, "let's brainstorm", "brainstorm this", "can we brainstorm X", or "help me brainstorm X". For ambiguous exploratory phrasing ("I've been thinking", "what if", "help me think through"), do NOT auto-enter; respond conversationally and offer mode only after ≥2 sustained exploratory turns. Do NOT use for review, debug, PR, status, implementation, or active-workflow questions.
 disable-model-invocation: false
 user-invocable: true
@@ -233,7 +233,7 @@ ACTIVE_PROJECT_PR_STATUS=""
 if [ -n "$ACTIVE_PROJECT" ] && [ -f "$ACTIVE_PROJECT/state.md" ]; then
   ACTIVE_PROJECT_VALID="true"
   # Read state.md frontmatter — extract:
-  #   oat_workflow_mode → ACTIVE_PROJECT_MODE        (e.g., "spec-driven", "quick")
+  #   oat_workflow_mode → ACTIVE_PROJECT_MODE        (e.g., "spec-driven", "quick", "lite")
   #   oat_phase         → ACTIVE_PROJECT_PHASE       (e.g., "discovery", "design", "plan", "implement")
   #   oat_pr_status     → ACTIVE_PROJECT_PR_STATUS   (e.g., "none", "open", "closed")
 fi
@@ -396,8 +396,8 @@ The payload is staged in memory only — it is not persisted between conversatio
   - Capture as new idea → confirm slug.
   - Extend existing idea → confirm which idea (slug or path).
   - Doc-to-path → confirm path.
-  - Promote to new project → confirm slug + workflow mode (`quick` vs `spec-driven`, with skill proposing a default based on the chosen direction and scope signals).
-  - Active-project fold-back → confirm which artifact (`design.md` if exists, else `discovery.md`; user signal can override toward `discovery.md` for foundational changes).
+  - Promote to new project → confirm slug + workflow mode (`lite`, `quick`, or `spec-driven`, with skill proposing a default based on the chosen direction and scope signals).
+  - Active-project fold-back → for lite confirm `plan.md`; otherwise confirm which artifact (`design.md` if exists, else `discovery.md`; user signal can override toward `discovery.md` for foundational changes).
   - Active-project reference file → confirm filename (default `YYYY-MM-DD-<topic>.md`).
 
 - **`none`** (currently `Inline only` and `Summarize idea directly`): no per-field confirmation at this layer. For `Inline only`, write the closing summary directly. For `Summarize idea directly`, hand off — the downstream `oat-idea-summarize` surfaces its own summary for accept/refine review.
@@ -505,13 +505,50 @@ End mode assertion when the backlog-add hands control back.
 
 #### 9g — Promote to new OAT project
 
-The slug and workflow mode (`quick` vs `spec-driven`) were confirmed at step 8. Run:
+The slug and workflow mode (`lite`, `quick`, or `spec-driven`) were confirmed at
+step 8. Run:
 
 ```bash
 oat project new <slug> --mode <mode>
 ```
 
-This scaffolds the project directory under `.oat/projects/<scope>/<slug>/` with the standard core files (state.md, discovery.md, etc.).
+This scaffolds the project directory under `.oat/projects/<scope>/<slug>/` with
+the files owned by the selected mode.
+
+**Lite branch:** When mode is `lite`, use and preserve `<project>/plan.md` as
+the canonical artifact. Fill its `Summary`, `Decisions`, `Assumptions`, `Out of
+Scope`, and `Validation Criteria` sections from the synthesized payload without
+replacing an already populated section or the scaffolded `## Phase 1`. Do not
+create, write, or complete `discovery.md` or `design.md`. Set the project state
+to plan/in-progress with `oat_ready_for: oat-project-lite`, print the
+`oat-project-lite` handoff, and stop.
+
+Use this branch contract to validate the lite scaffold before the handoff:
+
+```bash
+# BEGIN LITE PROJECT PROMOTION CONTRACT
+if [ "$PROMOTION_MODE" = "lite" ]; then
+  LITE_PLAN_PATH="$PROMOTED_PROJECT/plan.md"
+  if [ ! -f "$LITE_PLAN_PATH" ]; then
+    mkdir -p "$PROMOTED_PROJECT"
+    printf '%s\n' '# Plan' '' '## Summary' '' '## Decisions' '' \
+      '## Assumptions' '' '## Out of Scope' '' '## Validation Criteria' '' \
+      '## Phase 1' > "$LITE_PLAN_PATH"
+  fi
+  if [ -e "$PROMOTED_PROJECT/discovery.md" ]; then
+    echo "oat: lite promotion must not create discovery.md" >&2
+    exit 64
+  fi
+  NEXT_SKILL="oat-project-lite"
+else
+  LITE_PLAN_PATH=""
+  NEXT_SKILL="oat-project-quick-start-or-design"
+fi
+# END LITE PROJECT PROMOTION CONTRACT
+```
+
+**Quick/spec-driven branch:** Only for those two modes, continue with the
+discovery flow below.
 
 Then **write a field-filled `discovery.md`** at `<project>/discovery.md` using the synthesized payload:
 
@@ -536,7 +573,7 @@ Print a pointer to the next skill, e.g.:
 
 **Stop here. Do NOT inline-execute the next phase.** The deliberate transition is the point — the user runs the next skill at their own pace.
 
-End mode assertion.
+End mode assertion after the selected branch stops.
 
 #### 9h — Active-project router (3-way picker)
 
@@ -556,14 +593,25 @@ The 3-way router fires once per session. After convergence resumes (e.g., the us
 
 #### 9i — Active project: fold-back to upstream artifact
 
-Uniform across spec-driven and quick modes. Differs only in which plan-authoring skill the handoff prompt addresses (resolved by `ACTIVE_PROJECT_MODE` and `ACTIVE_PROJECT_PR_STATUS`).
+Uniform across spec-driven, quick, and lite modes. Differs only in which plan-authoring skill the handoff prompt addresses (resolved by `ACTIVE_PROJECT_MODE` and `ACTIVE_PROJECT_PR_STATUS`).
 
 **Step 1 — Pick upstream artifact.** Prefer the most-specific existing one:
 
+- For lite, always select `<ACTIVE_PROJECT>/plan.md`. Append `## Brainstorming Update` immediately above `## Phase 1`; lite has no discovery or design artifact.
 - `<ACTIVE_PROJECT>/design.md` if it exists (any mode — quick lightweight design counts).
 - Otherwise `<ACTIVE_PROJECT>/discovery.md`.
 - The user's signal during the conversation can override toward `discovery.md` even when `design.md` exists ("this is foundational" → discovery; "this is a design refinement" → design).
 
+Use this executable artifact-selection contract before confirming the path:
+
+```bash
+# BEGIN LITE FOLD-BACK CONTRACT
+if [ "$ACTIVE_PROJECT_MODE" = "lite" ]; then
+  ARTIFACT_PATH="$ACTIVE_PROJECT/plan.md"
+fi
+# END LITE FOLD-BACK CONTRACT
+```
+
 Confirm the chosen artifact with the user (minimal confirmation per `references/destinations.md`). Set `ARTIFACT_PATH` to the absolute path.
 
 **Persistence invariant:** shared and local project artifacts remain ordinary
@@ -602,7 +650,7 @@ beside another dirty project file must take Step 4.
    ## Brainstorming Update: YYYY-MM-DD — <topic>
    ```
 
-   Section body contains: `chosenDirection` (with rationale), key decisions (extracted from the conversation), and a transcript appendix (`transcriptSessionNote`). Optionally include `openQuestions` and `nextSteps` if surfaced.
+   Section body contains: `chosenDirection` (with rationale), key decisions (extracted from the conversation), and a transcript appendix (`transcriptSessionNote`). Optionally include `openQuestions` and `nextSteps` if surfaced. In lite mode, insert this section above `## Phase 1` in `plan.md` rather than appending after the task plan.
 
 2. Persist **only** the artifact under the scope guard:
 
@@ -621,7 +669,7 @@ beside another dirty project file must take Step 4.
 
    For non-synced projects, use the explicit `--` filename form. **Never `git add -A`. Never directory globs.** Other working-tree paths are not touched by this commit. For synced projects, `FOLD_BACK_COMMIT_SHA` comes from the push JSON rather than the parent branch.
 
-3. `<artifact-basename>` is `design.md` or `discovery.md` depending on which was chosen. `<project-name>` is the active project's slug.
+3. `<artifact-basename>` is `plan.md` for lite, otherwise `design.md` or `discovery.md` depending on which was chosen. `<project-name>` is the active project's slug.
 
 4. If the guarded persistence succeeded → proceed to step 5 (handoff prompt).
 
@@ -695,7 +743,8 @@ Resolve the handoff target by `ACTIVE_PROJECT_MODE` and `ACTIVE_PROJECT_PR_STATU
 | ----------- | ---------------------------- | ------------------------- |
 | spec-driven | none / closed                | `oat-project-plan`        |
 | quick       | none / closed                | `oat-project-quick-start` |
-| either      | open (`oat_pr_status: open`) | `oat-project-revise`      |
+| lite        | none / closed                | `oat-project-lite`        |
+| any mode    | open (`oat_pr_status: open`) | `oat-project-revise`      |
 
 Print the handoff prompt template, substituting `<skill-name>`, `<artifact>`, `<hash>`, and `<subject>` from the actual branch commit or synced push receipt:
 
@@ -771,6 +820,6 @@ End mode assertion when the split handoff completes or reports its own blocker.
 - ✅ Each handoff branch (9a-9k) reads the correct downstream `SKILL.md` path and enters at the documented step. Project promotion writes `discovery.md` only — never `design.md` — and does not auto-chain into the next phase.
 - ✅ Doc-to-path validation handles all four cases: path-is-directory, parent-missing (with explicit out-of-repo confirmation), file-already-exists (overwrite or rename), unwritable (surface OS error).
 - ✅ Fold-back persistence safety contract honored: preflight `git status --porcelain -- "$ARTIFACT_PATH"` runs before any artifact mutation; clean → append + exact-path branch commit for shared/local or validated `oat project push --json` for synced; dirty → three-option picker (persist-prior-first / mix / abort-to-reference-file); handoff prompt prints only after the scope-appropriate receipt succeeds.
-- ✅ Handoff target for fold-back resolves correctly per `oat_workflow_mode` + `oat_pr_status`: `oat-project-plan` (spec-driven, no/closed PR) / `oat-project-quick-start` (quick, no/closed PR) / `oat-project-revise` (either mode, open PR).
+- ✅ Handoff target for fold-back resolves correctly per `oat_workflow_mode` + `oat_pr_status`: `oat-project-plan` (spec-driven, no/closed PR) / `oat-project-quick-start` (quick, no/closed PR) / `oat-project-lite` (lite, no/closed PR) / `oat-project-revise` (any mode, open PR).
 - ✅ Active-project 3-way router (related / independent / supplementary) fires before the standard pack-filtered picker when both `WORKFLOWS_INSTALLED == "true"` and `ACTIVE_PROJECT_VALID == "true"`.
 - ✅ Skill validates cleanly under `pnpm oat:validate-skills` (frontmatter contract, allowed-tools, mode-assertion structure).

package/assets/skills/oat-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-docs
-version: 1.0.1
+version: 1.0.2
 description: Use when a user asks questions about OAT workflows, CLI commands, skill authoring, configuration, or project lifecycle. Answers questions by reading locally-bundled OAT documentation.
 argument-hint: '[question]'
 disable-model-invocation: false
@@ -145,7 +145,7 @@ Based on the docs, here's how OAT project workflows work: [answer]
 You can read more in `guide/workflow/lifecycle.md`.
 
 Would you like me to:
-- Start a new project? (I'd invoke oat-project-quick-start)
+- Start a new project? (I'd invoke oat-project-lite for single-sitting work, or oat-project-quick-start for a larger quick workflow)
 - Check your current project status? (I'd read your active project's state.md)
 ```
 
@@ -158,22 +158,27 @@ Would you like me to:
 **Response:**
 
 ```
-To create a new OAT project, you have two main approaches:
+To create a new OAT project, you have three main approaches:
 
-1. **Quick mode** (recommended for most tasks):
+1. **Lite mode** (recommended for single-sitting changes):
+   oat-project-lite <project-name> "project description"
+
+2. **Quick mode** (recommended for larger bounded work):
    oat-project-quick-start <project-name> "project description"
 
-2. **Spec-driven mode** (for complex features):
+3. **Spec-driven mode** (for complex features):
    oat-project-new <project-name>
 
-Quick mode goes straight from discovery to plan. Spec-driven mode adds
-formal spec and design phases. If you invoke quick mode with only a
+Lite combines the interview and requirements contract in one plan for a
+single sitting. Quick mode goes straight from discovery to plan. Spec-driven
+mode adds formal spec and design phases. If you invoke quick mode with only a
 project name, it should ask you for the missing project description
 before discovery starts.
 
 Both create a project directory under your projects root
 (default: .oat/projects/shared/<project-name>/) with standard artifacts:
-state.md, discovery.md, plan.md, and implementation.md.
+state.md, plan.md, and implementation.md; quick and spec-driven modes also use
+discovery.md.
 
 See: guide/workflow/lifecycle.md, guide/getting-started.md
 

package/assets/skills/oat-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-doctor
-version: 1.2.0
+version: 1.2.1
 description: Use when you need to diagnose your OAT setup, check for outdated skills, identify misconfigurations, or get a summary of installed tools and config. Runs health checks and recommends corrective actions.
 argument-hint: '[--summary]'
 disable-model-invocation: true
@@ -174,7 +174,7 @@ it, and lists every skill that pack ships.
 - oat-project-capture, oat-project-clear-active, oat-project-complete
 - oat-project-design, oat-project-dispatch-subagents, oat-project-discover
 - oat-project-document, oat-project-implement, oat-project-import-plan
-- oat-project-new, oat-project-next, oat-project-open
+- oat-project-lite, oat-project-new, oat-project-next, oat-project-open
 - oat-project-plan, oat-project-plan-writing, oat-project-pr-final
 - oat-project-pr-progress, oat-project-progress, oat-project-promote-spec-driven
 - oat-project-quick-start, oat-project-reconcile, oat-project-retro
@@ -238,7 +238,7 @@ OAT ▸ DOCTOR SUMMARY
 | --------- | ------- | ------ | -------- |
 | core      | user    | 2/2    | current  |
 | docs      | project | 7/7    | current  |
-| workflows | project | 39/39  | current  |
+| workflows | project | 40/40  | current  |
 | ideas     | user    | 4/4    | current  |
 | project-management | project | 4/4 | current |
 | research  | project | 6/6    | current  |

package/assets/skills/oat-explainer-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-explainer-kit
-version: 1.0.6
+version: 1.0.7
 description: Use when building project explainers or recaps from OAT configuration, state, and lifecycle artifacts.
 disable-model-invocation: false
 user-invocable: true
@@ -18,6 +18,7 @@ Adapt OAT project context into the versioned request consumed by the canonical
 - Resolve typed OAT configuration with source attribution.
 - Derive canonical project or repository output roots.
 - Bind OAT lifecycle artifacts to generic recipe source roles.
+- Probe recap seam availability before an unattended run is attempted.
 - Resolve project explainer and recap intent before invoking the core.
 - Resolve one provider-neutral set planner for unattended project recaps.
 - Require lifecycle callers to construct a brief-aware author seam.
@@ -79,6 +80,18 @@ source evidence, and medium rationale. The installed core continues reading
 `project-recap@1` for replay; the adapter never rewrites a retained request's
 recipe selector.
 
+Before an unattended `project-recap`, call
+`scripts/probe-recap-seams.mjs#probeRecapSeams` with the seam inputs you are
+about to pass. The probe is pure and checks all five required seams — author,
+fact critic, browser session, visual critic, and set planner — using the same
+rules `run.mjs` applies. `seams-unavailable` means no provider is configured
+for a required seam: pass the probe result to the intent resolver as
+`seamProbe`, which returns a recordable `skip` with source `capability_probe`
+and a warning. `seams-invalid` means a supplied seam violates a resolution
+rule: fail closed and report the configuration error; it is never a skip. When
+the probe returns `ok: true`, invoke the adapter with unchanged behavior, and
+treat any later failure as `failed` rather than as a skip.
+
 Before invocation, read `references/author-callback.md`. Unattended
 `project-recap` runs require exactly one provider-neutral set planner:
 in-process callers supply `planSet`, while JSON/CLI callers supply

package/assets/skills/oat-explainer-kit/references/config-contract.md

@@ -27,6 +27,18 @@ do not write config. Recipe, slug, fact-base path, output root, per-run art
 direction, and private wrapper lanes are invocation inputs rather than config
 keys and are rejected from the runtime config-override map.
 
+## Seams are invocation inputs, not configuration
+
+No supported key names an author, fact critic, browser session, visual critic,
+or set planner. Every seam is supplied per invocation as a callback or a module
+entry point, so seam availability is discovered by
+`scripts/probe-recap-seams.mjs#probeRecapSeams` against the inputs a caller is
+about to pass, not read from stored config. A host on which those inputs are
+absent has no configuration to correct: the probe reports `seams-unavailable`
+and the lifecycle caller records a `skip / capability_probe` recap intent. The
+`workflow.explainers.projectRecap` preference expresses whether a host _wants_
+a recap and cannot make an unavailable seam available.
+
 ## Source-sensitive paths
 
 A shared theme bundle path is repository-relative and must remain inside the

package/assets/skills/oat-explainer-kit/references/lifecycle-contract.md

@@ -18,11 +18,31 @@ now })` is pure. Its result contains the effective `decision`, the
 `resolutionSource`, whether a prompt is needed, an optional state `record`, and
 warnings.
 
-In autonomous mode, `projectRecap` always resolves to `generate` with source
-`autonomous_policy`. A lower-precedence skip or `never` preference is overridden
-and reported as a warning. Autonomous `projectExplainer` resolves to `generate`
-only when the kickoff prompt explicitly requested it; otherwise it resolves to
-`skip` without writing an invalid prompt-source skip record.
+In autonomous mode, `projectRecap` resolves to `generate` with source
+`autonomous_policy` on any host whose recap seams resolve. A lower-precedence
+skip or `never` preference is overridden and reported as a warning. Autonomous
+`projectExplainer` resolves to `generate` only when the kickoff prompt
+explicitly requested it; otherwise it resolves to `skip` without writing an
+invalid prompt-source skip record.
+
+Autonomous `projectRecap` resolution accepts an optional `seamProbe`, the
+result of `scripts/probe-recap-seams.mjs#probeRecapSeams`. It is a pre-flight
+capability input, never a post-hoc reaction to a failed run:
+
+- `ok: true` leaves resolution unchanged, so a configured host still forces
+  `generate / autonomous_policy`.
+- `seams-unavailable` — no callback and no module path is supplied for a seam
+  this mode requires — resolves `skip` with source `capability_probe` and a
+  warning naming the unavailable seams.
+- `seams-invalid` — a seam is supplied but violates a resolution rule — throws
+  `E_RECAP_SEAMS_INVALID` and fails closed exactly as the runtime would. A
+  configured-but-invalid seam is a configuration error, never a capability
+  skip.
+
+A seam probe is scoped to autonomous `projectRecap`; supplying one for
+`projectExplainer` or for interactive resolution is an error. A recap that
+fails after a passing probe stays `failed` and is never reinterpreted as a
+skip.
 
 In interactive mode, an existing valid project record prevents another prompt.
 Preferences `always` and `never` resolve directly but are not copied into
@@ -47,12 +67,22 @@ oat_project_recap:
 
 Allowed decision/source pairs are:
 
-| Product            | Allowed pairs                                                            |
-| ------------------ | ------------------------------------------------------------------------ |
-| `projectExplainer` | `generate/interactive`, `skip/interactive`, `generate/kickoff_prompt`    |
-| `projectRecap`     | `generate/interactive`, `skip/interactive`, `generate/autonomous_policy` |
+| Product            | Allowed pairs                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------- |
+| `projectExplainer` | `generate/interactive`, `skip/interactive`, `generate/kickoff_prompt`                             |
+| `projectRecap`     | `generate/interactive`, `skip/interactive`, `generate/autonomous_policy`, `skip/capability_probe` |
 
-In particular, `skip/autonomous_policy` is invalid.
+In particular, `skip/autonomous_policy` is invalid: an autonomous skip is
+recordable only as the probe-driven `skip/capability_probe`, and that pair is
+product-scoped to `projectRecap`. `generate/capability_probe` is invalid too,
+because a probe can only withhold a run, never authorize one.
+
+The pair is product-scoped but not mode-scoped, and that is deliberate. Only
+autonomous resolution can _produce_ a `skip/capability_probe`, but once one is
+persisted a later interactive resolution reads it back as a valid recorded
+decision and honors it, exactly as it honors `skip/interactive`. A resumed
+project therefore neither re-prompts nor fails validation on a legitimately
+recorded capability skip.
 
 ## Safe persistence
 
@@ -120,6 +150,23 @@ the relative path and public URL. Neither summary contract is mutated in place.
 
 ## Browser and visual-review execution
 
+Lifecycle callers probe seam availability before attempting an unattended
+`project-recap`. `scripts/probe-recap-seams.mjs#probeRecapSeams({ mode, ...
+seams })` is pure: it applies the same resolution and exclusivity rules this
+adapter applies at run time, but never imports a module, calls a callback,
+validates a session brand, or touches the filesystem. Unattended runs require
+all five seams — author, fact critic, browser session, visual critic, and set
+planner — and interactive runs require the author and fact critic. A probe that
+checks only four of the five passes on a host with no set planner and the
+adapter still throws `E_SET_PLANNER_REQUIRED`, so the planner is probed with
+the rest.
+
+The probe classifies each seam as resolved, `missing`, or `invalid` and never
+conflates them. Only `missing` may become a recorded skip. Requirements below
+are unchanged for every run that is actually attempted: the probe gates whether
+a run is attempted, and never weakens the evidence a run that happens must
+produce.
+
 Every unattended `project-recap` must provide exactly one browser-evidence
 session and exactly one whole-set visual critic through the adapter's
 first-class boundary. In-process callers pass `browserSession`, created by the

package/assets/skills/oat-explainer-kit/scripts/check-terminal-outcome.mjs

@@ -8,9 +8,25 @@ const TERMINAL_OUTCOMES = new Set([
   'failed',
 ]);
 
-export function checkTerminalOutcome({ intent, outcome }) {
+/**
+ * A skip reason is the recorded `source` of the skip decision, so the guard
+ * accepts exactly the sources that may produce a `skip` recap record.
+ */
+const SKIP_REASONS = new Set(['interactive', 'capability_probe']);
+
+export function checkTerminalOutcome({ intent, outcome, reason }) {
+  if (reason !== undefined && !SKIP_REASONS.has(reason)) {
+    throw recapOutcomeError(
+      `Recap skip reason must be one of ${[...SKIP_REASONS].join(', ')}.`,
+    );
+  }
   if (intent === 'skip') {
-    return { ok: true, intent, outcome: null };
+    return { ok: true, intent, outcome: null, reason: reason ?? null };
+  }
+  if (reason !== undefined) {
+    throw recapOutcomeError(
+      'A recap skip reason applies only to a skip intent.',
+    );
   }
   if (intent !== 'generate') {
     throw recapOutcomeError('Recap intent must be generate or skip.');
@@ -24,7 +40,7 @@ export function checkTerminalOutcome({ intent, outcome }) {
 }
 
 async function main(argv) {
-  const { intent, manifestPath } = parseArguments(argv);
+  const { intent, manifestPath, reason } = parseArguments(argv);
   let outcome;
   if (manifestPath !== undefined) {
     let manifest;
@@ -37,12 +53,17 @@ async function main(argv) {
     }
     outcome = manifest?.outcome;
   }
-  return checkTerminalOutcome({ intent, outcome });
+  return checkTerminalOutcome({
+    intent,
+    outcome,
+    ...(reason !== undefined && { reason }),
+  });
 }
 
 function parseArguments(argv) {
   let intent;
   let manifestPath;
+  let reason;
   for (let index = 0; index < argv.length; index += 2) {
     const flag = argv[index];
     const value = argv[index + 1];
@@ -53,11 +74,13 @@ function parseArguments(argv) {
       intent = value;
     } else if (flag === '--manifest') {
       manifestPath = value;
+    } else if (flag === '--skip-reason') {
+      reason = value;
     } else {
       throw recapOutcomeError(`Unsupported argument: ${flag}.`);
     }
   }
-  return { intent, manifestPath };
+  return { intent, manifestPath, reason };
 }
 
 function recapOutcomeError(message) {