@open-agent-toolkit/cli 0.2.62 → 0.2.63

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

@@ -141,6 +141,51 @@ On completion, OAT treats archive handling as an explicit closeout choice:
   ref. `oat project prune` is a separate destructive choice that removes
   terminal ref reachability but preserves local and S3 archive snapshots.
 
+### Absorbed-project retirement sweep
+
+Retiring a project that a later project absorbed is a semantic claim, not a
+filesystem operation. Deleting or archiving the old scaffold does not make the
+roadmap stop promising its work, so completion checks the claim against the
+prose that still makes it.
+
+When a quick project consolidates earlier scaffolds, quick-start records
+`absorbed_projects` and `absorbed_backlog_ids` in that project's `state.md`
+frontmatter. Those two fields are the only inputs the sweep takes.
+
+Recording them is a quick-mode step today. A lite project that consolidates
+earlier scaffolds records nothing, so the sweep finds no inputs and degrades to
+its recorded note rather than checking that project's surfaces.
+
+Inside the project-log completion gate — after the log status probe and before
+the roll-up and seal — completion searches the active planning surfaces for each
+absorbed slug and backlog ID, and for future-oriented ownership language tied to
+them:
+
+- `.oat/repo/pjm/roadmap.md` (the Now/Next/Later lanes and the sequencing map)
+- `.oat/repo/pjm/current-state.md`
+- the Curated Overview in `.oat/repo/pjm/backlog/index.md`
+- the scope-nested `state.md` of projects that are still active, under the
+  configured projects root, skipping the `archived` tree and any project already
+  recorded as complete
+
+The sweep is advisory. A raw match is never a hard block on closeout: each hit
+becomes a named finding carrying a recorded disposition: fixed in the same run,
+accepted as historical with a reason, or — in an autonomous run — recorded as
+`deferred advisory`. Prose that clearly describes
+past state is exempt, so a dated history entry, a retro, a decision record, or a
+changelog line reads as evidence rather than a stale claim.
+
+Placement is the point. Dispositions are appended to the project log before the
+roll-up, so the roll-up summarizes them and the completion seal remains the
+final entry — no project-log append ever follows the seal. Three variations
+change where and how the dispositions are recorded: an autonomous run records
+each finding as a `deferred advisory` warning and continues, a project with no log reports them in the
+final completion summary, and a resumed completion whose log already
+carries a seal runs report-only and appends nothing.
+
+Repositories that never adopted PJM skip the sweep with a one-line note. A
+missing planning surface degrades the sweep, never the closeout.
+
 ### Phase status: `pr_open`
 
 After `oat-project-pr-final` runs, `state.md` shows `oat_phase_status: pr_open`. This signals:

package/assets/docs/workflows/projects/picking-up-projects.md

@@ -36,6 +36,20 @@ its parent is reported and skipped rather than adopted.
 After adoption, set or open the project through the normal lifecycle command
 you are using. Arrival-aware project skills pull before reading its artifacts.
 
+An adopted quick-workflow project whose `plan.md` is not implementation-ready
+resumes through `oat-project-quick-start`, which continues it in place without
+re-scaffolding, rather than through `oat-project-implement`. `oat-project-plan`,
+`oat-project-progress`, and `oat-project-next` all route by the single **quick
+plan readiness** predicate that `oat-project-quick-start` defines; readiness is
+never inferred from the presence of tasks alone.
+
+`oat project status` and `oat project list` apply the same predicate. For a
+quick project at the `plan` phase they recommend `oat-project-quick-start`, with
+the unmet clause in the reason, until the plan carries ready frontmatter, a
+durable `## Reviews` disposition, and a substantive task; only then do they
+recommend `oat-project-implement`. Recommendations for lite, spec-driven, and
+import projects are unchanged, because the predicate is quick-workflow policy.
+
 ## What travels
 
 - The project ref carries the complete active artifact tree and its history.

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/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.62",
-  "docs-config": "0.2.62",
-  "docs-theme": "0.2.62",
-  "docs-transforms": "0.2.62"
+  "cli": "0.2.63",
+  "docs-config": "0.2.63",
+  "docs-theme": "0.2.63",
+  "docs-transforms": "0.2.63"
 }

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) {