@open-agent-toolkit/cli 0.2.59 → 0.2.63

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.5.4
+version: 1.5.5
 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
@@ -306,6 +306,7 @@ WORKFLOW_MODE=$(oat project status --project-path "$PROJECT_PATH" --field projec
 - `spec-driven`: `spec.md`, `design.md`, `plan.md`
 - `quick`: `discovery.md`, `plan.md` (`spec.md`/`design.md` optional if present)
 - `import`: `plan.md` (`references/imported-plan.md` recommended, `spec.md`/`design.md` optional)
+- `lite`: `plan.md`, `implementation.md` (`discovery.md`/`spec.md`/`design.md` are absent by design)
 
 **Required for artifact review:**
 
@@ -314,9 +315,10 @@ WORKFLOW_MODE=$(oat project status --project-path "$PROJECT_PATH" --field projec
   - reviewing `spec` requires `discovery.md`
   - reviewing `design` in `spec-driven` mode requires `spec.md`
   - reviewing `design` in `quick/import` mode requires only `discovery.md` (spec is skipped in these modes)
-  - in `quick/import` mode, missing `spec.md` must not be treated as a project review gate failure for `artifact design`; proceed with normal project-scoped review flow, artifact writing, and bookkeeping
+  - in `quick/import` mode (lite has no design artifact), missing `spec.md` must not be treated as a project review gate failure for `artifact design`; proceed with normal project-scoped review flow, artifact writing, and bookkeeping
   - reviewing `plan` in `spec-driven` mode requires `spec.md` + `design.md`
-  - reviewing `plan` in `quick/import` mode may use `discovery.md` and/or `references/imported-plan.md` instead
+  - reviewing `plan` in `quick/import` mode may use `discovery.md` and/or `references/imported-plan.md` instead; lite uses the separate rule below
+  - reviewing `plan` in `lite` mode requires only `plan.md`; its Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria sections are the complete upstream contract
 
 **If missing:** Report missing required artifacts for the current mode and stop if requirements are not met.
 
@@ -502,6 +504,8 @@ case "$SCOPE_TOKEN" in
       FILES_CHANGED=$(printf "%s\n" "$PROJECT_PATH/plan.md" "$PROJECT_PATH/spec.md" "$PROJECT_PATH/design.md")
     elif [[ "$WORKFLOW_MODE" == "quick" ]]; then
       FILES_CHANGED=$(printf "%s\n" "$PROJECT_PATH/plan.md" "$PROJECT_PATH/discovery.md")
+    elif [[ "$WORKFLOW_MODE" == "lite" ]]; then
+      FILES_CHANGED=$(printf "%s\n" "$PROJECT_PATH/plan.md")
     else
       FILES_CHANGED=$(printf "%s\n" "$PROJECT_PATH/plan.md" "$PROJECT_PATH/references/imported-plan.md")
     fi
@@ -581,10 +585,12 @@ Build the "Review Scope" metadata for the reviewer:
 **Scope:** {scope}{optional: " (" + SCOPE_RANGE + ")"}
 **Date:** {today}
 
+- Workflow mode: {WORKFLOW_MODE}
+
 **Artifact Paths:**
 
-- Spec: {PROJECT_PATH}/spec.md (required in spec-driven mode; optional in quick/import)
-- Design: {PROJECT_PATH}/design.md (required in spec-driven mode; optional in quick/import)
+- Spec: {PROJECT_PATH}/spec.md (required in spec-driven mode; optional in quick/import/lite)
+- Design: {PROJECT_PATH}/design.md (required in spec-driven mode; optional in quick/import/lite)
 - Plan: {PROJECT_PATH}/plan.md
 - Implementation: {PROJECT_PATH}/implementation.md
 - Discovery: {PROJECT_PATH}/discovery.md
@@ -622,6 +628,19 @@ Build the "Review Scope" metadata for the reviewer:
 - Do not force a code-defect framing for accepted design drift; `oat-project-review-receive` can convert artifact drift into alignment tasks or explicit deferrals.
 ```
 
+For `WORKFLOW_MODE=lite`, render the artifact-path portion of every artifact-plan
+and code-final Review Scope explicitly as:
+
+- Discovery: not required (absent by design)
+- Spec: not required (absent by design)
+- Design: not required (absent by design)
+- Import reference: not required
+- Plan: `{PROJECT_PATH}/plan.md` (Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria are the requirements contract)
+- Implementation: `{PROJECT_PATH}/implementation.md`
+
+Always pass the resolved workflow mode. Never omit it and let the reviewer fall
+back to its spec-driven default.
+
 ### Step 6: Execute Review (3-Tier Capability Model)
 
 **Canonical reviewer instructions:** Before a direct reviewer-definition read or
@@ -944,7 +963,7 @@ If running inline (Tier 3), execute the review and write artifact.
 **Review checklist (from oat-reviewer):**
 
 1. Verify scope (don't review out-of-scope changes)
-2. If code review: verify alignment to available requirements sources (`spec`/`design` for spec-driven mode; `discovery`/import reference for quick/import)
+2. If code review: verify alignment to available requirements sources (`spec`/`design` for spec-driven mode; `discovery`/import reference for quick/import; plan.md Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria for lite)
 3. If code review: verify code quality (correctness, tests, security, maintainability)
 4. If artifact review: verify completeness/clarity/readiness of the artifact and its alignment with upstream artifacts
 5. Categorize findings (Critical/Important/Medium/Minor)

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-summary
-version: 1.5.1
+version: 1.5.3
 description: Use when the user requests or confirms summarizing an active OAT project — e.g. "summarize the project", "generate the summary", "run oat-project-summary", or confirms a previously offered summary run. Do NOT auto-invoke when implementation completes. Generates summary.md from project artifacts as institutional memory.
 disable-model-invocation: false
 user-invocable: true
@@ -117,7 +117,16 @@ test -f "$PROJECT_PATH/implementation.md"
 
 ### Step 2: Read Project Artifacts
 
-Read all available artifacts for synthesis:
+For `oat_workflow_mode: lite`, use the reduced artifact contract and skip the
+ordinary artifact list below. Read the five `plan.md` sections `Summary`,
+`Decisions`, `Assumptions`, `Out of Scope`, and `Validation Criteria`, then read
+`implementation.md` for task outcomes and the shipped results in `Final
+Summary (for PR/docs)`. Read `state.md` only for routing metadata. A lite
+project accepts `discovery.md`, `spec.md`, and `design.md` as absent; do not
+read or require them. Ground the summary in what actually shipped, with
+`implementation.md` taking precedence over the plan.
+
+For every other workflow mode, read all available artifacts for synthesis:
 
 - `"$PROJECT_PATH/discovery.md"` — initial request, decisions, constraints
 - `"$PROJECT_PATH/spec.md"` — requirements, goals (optional — may not exist in quick mode)
@@ -213,39 +222,64 @@ For each section, synthesize content from the relevant artifacts. Apply these ru
 
 **Minimum viable summary:** Overview + What Was Implemented + Key Decisions. All other sections are included only when they have content worth preserving.
 
-**Section sources:**
-
-| Section                        | Primary Sources                                                        |
-| ------------------------------ | ---------------------------------------------------------------------- |
-| Overview                       | discovery.md initial request, spec.md problem statement                |
-| What Was Implemented           | implementation.md task outcomes, plan.md phase structure               |
-| Key Decisions                  | design.md decisions, implementation.md notes/decisions                 |
-| Design Deltas                  | implementation.md deviations table; review-received design drift notes |
-| Notable Challenges             | implementation.md issues/blockers in task notes                        |
-| Tradeoffs Made                 | implementation.md decisions, design.md tradeoff sections               |
-| Integration Notes              | implementation.md notes about cross-cutting concerns                   |
-| Revision History               | plan.md p-revN phases, implementation.md revision notes                |
-| Follow-up Items                | implementation.md deferred findings, plan.md deferred items            |
-| Associated Issues              | state.md `associated_issues` field                                     |
-| Workflow Observations          | project-log.md via `oat project log rollup` only                       |
-| Autonomous Execution Learnings | oat-execution-learnings.md dated entries                               |
-| Explainer Outcome              | project-recap `manifest.json` and `build-record.json`                  |
+**Lite section sources:**
+
+Use this table only for `oat_workflow_mode: lite`. It maps every canonical lite
+plan section and shipped implementation results without requiring discovery,
+spec, or design artifacts.
+
+| Summary Section      | Primary Lite Sources                                          |
+| -------------------- | ------------------------------------------------------------- |
+| Overview             | plan.md `Summary`; implementation.md `Final Summary`          |
+| What Was Implemented | implementation.md shipped results and task outcomes           |
+| Key Decisions        | plan.md `Decisions`; implementation.md accepted decisions     |
+| Tradeoffs Made       | plan.md `Assumptions`; implementation.md decisions            |
+| Follow-up Items      | plan.md `Out of Scope`; implementation.md deferred results    |
+| Integration Notes    | plan.md `Validation Criteria`; implementation.md test results |
+
+**Non-lite section sources:**
+
+| Section                        | Primary Sources                                                                   |
+| ------------------------------ | --------------------------------------------------------------------------------- |
+| Overview                       | discovery.md initial request, spec.md problem statement                           |
+| What Was Implemented           | implementation.md task outcomes, plan.md phase structure                          |
+| Key Decisions                  | design.md decisions, implementation.md notes/decisions                            |
+| Design Deltas                  | implementation.md deviations table; review-received design drift notes            |
+| Notable Challenges             | implementation.md issues/blockers in task notes                                   |
+| Tradeoffs Made                 | implementation.md decisions, design.md tradeoff sections                          |
+| Integration Notes              | implementation.md notes about cross-cutting concerns                              |
+| Revision History               | plan.md p-revN phases, implementation.md revision notes                           |
+| Follow-up Items                | implementation.md deferred findings, plan.md deferred items                       |
+| Associated Issues              | state.md `associated_issues` field                                                |
+| Workflow Observations          | project-log.md via `oat project log rollup` only                                  |
+| Autonomous Execution Learnings | oat-execution-learnings.md dated entries                                          |
+| Explainer Outcome              | project-recap `manifest.json` and `build-record.json`, or the recorded recap skip |
 
 **Explainer Outcome (conditional):**
 
-When a project-recap attempt exists, render this section:
+When a project-recap attempt or a recorded recap skip exists, render this
+section with exactly one item. A run that happened uses the first form:
+
+```markdown
+## Explainer Outcome
+
+- **project-recap:** {generated | degraded} {outcome} — `{run path}`{optional warning or recovery note}
+```
+
+A recap that never ran because a required seam was unavailable uses the second
+form, which has a reason and no run path:
 
 ```markdown
 ## Explainer Outcome
 
-- **project-recap:** {outcome} — `{run path}`{optional warning or recovery note}
+- **project-recap:** skipped — {skip reason}
 ```
 
-When a project-recap attempt exists, include exactly one concise outcome item with its recipe, outcome (`built-durable`, `built-not-durable`, or `failed`), run path, and warning or recovery note when applicable.
+Include exactly one concise item with its recipe, state (`generated`, `degraded`, or `skipped`), and either its outcome (`built-durable`, `built-not-durable`, `built-needs-review`, or `failed`) with run path, or its skip reason. Add a warning or recovery note when applicable. Use `generated` for `built-durable`, `degraded` for any other terminal outcome, and `skipped` only for a recap whose intent resolved to skip.
 
-Use `manifest.json` and `build-record.json` as the source of truth; refresh the existing item instead of appending a duplicate.
+Use `manifest.json` and `build-record.json` as the source of truth for a run, and the recorded recap intent for a skip; refresh the existing item instead of appending a duplicate.
 
-Omit `Explainer Outcome` when no project-recap attempt exists. A failed or non-durable recap remains visible as its product outcome; do not reinterpret it as project implementation failure.
+Omit `Explainer Outcome` only when no project-recap attempt and no recorded recap skip exist. A degraded or skipped recap remains visible as its own product outcome; do not reinterpret either as project implementation failure. A `capability_probe` skip means the host had no provider configured for a required seam, not that the recap failed.
 
 **Autonomous Execution Learnings (conditional):**
 
@@ -595,5 +629,6 @@ Summary tracks: last task {task_id}, {N} revision phases
   ledger graduation
 - When the PJM tool pack is available, each Key Decision is promoted to a canonical `reference/decisions/DR-YYMMDD-slug` record via `oat decision new` (status `accepted`), deduped on the date-independent slug so re-runs never create duplicate records
 - When the PJM tool pack is unavailable, decision promotion is skipped silently with no prompt
-- A project-recap attempt appears once in a concise Explainer Outcome section
-  sourced from its manifest and build record
+- A project-recap attempt or recorded capability skip appears once in a concise
+  Explainer Outcome section sourced from its manifest and build record, or from
+  the recorded recap intent

package/assets/skills/oat-repo-improve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-repo-improve
-version: 2.1.2
+version: 2.1.3
 description: Use when auditing a repository or turning maintainability reviews, backlog reviews, backlog directories, or backlog items into self-contained external implementation plans.
 argument-hint: '[repo-audit|maintainability-review|backlog-review|backlog-directory|backlog-item] [path-or-id] [quick|standard|deep] [focus] [--backlog-items] [--issues]'
 disable-model-invocation: false
@@ -162,7 +162,14 @@ Do not treat review rankings or backlog wording as verified code facts. Preserve
 
 ### Step 4: Vet and Select Plan Candidates
 
-For audit and review sources, present a concise vetted candidate table with impact/value, effort, risk, confidence, dependencies, and evidence. Keep rejected or stale candidates out of plans and explain material rejections.
+For audit and review sources, present a concise vetted candidate table with impact/value, effort, risk, confidence, `plan_ready`, `execution_ready`, dependencies, and evidence. Keep rejected or stale candidates out of plans and explain material rejections.
+
+Score the two readiness axes separately; they answer different questions:
+
+- **`plan_ready`** — is the candidate understood well enough to write a self-contained, executable plan? Its evidence is verified live, it has one coherent outcome, and its verification boundary is known.
+- **`execution_ready`** — could an executor start today? Every hard dependency the plan would name is already satisfied.
+
+Dependency state alone does not disqualify a candidate. A candidate that is `plan_ready` but not `execution_ready` is still planned: its plan records `oat_execution_status: BLOCKED`, types the blocking row `Hard` in `## Dependencies`, and names the state that would unblock it. Reject a candidate for not being `plan_ready`, never for being blocked.
 
 Ask which candidates to plan. Recommend a bounded set of 3–5 when several are viable. In a non-interactive run, select the top 3–5 by leverage and record that default in the generated index.
 
@@ -179,7 +186,18 @@ For `backlog-item`, the selected candidate is the item itself unless investigati
 
 ### Step 5: Write External Plans
 
-Read `references/plan-template.md` before writing the first plan. Record `git rev-parse --short HEAD` and write only under:
+Read `references/plan-template.md` before writing the first plan. Record plan provenance with this block before writing anything:
+
+```bash
+git rev-parse HEAD                                   # inspected baseline → oat_external_plan_commit
+git fetch origin main && git rev-parse origin/main   # comparison evidence → oat_external_plan_main_commit
+git merge-base HEAD origin/main                      # comparison evidence when HEAD is a branch
+git status --porcelain                               # must be empty, or name every dirty path in the plan
+```
+
+`oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected. Never stamp it with a fetched tip that was not read: fetching `origin/main` and recording its SHA as the planned-at commit claims evidence the plan never inspected. The fetched `origin/main` or merge-base SHA is comparison evidence and belongs in `oat_external_plan_main_commit`; the two may differ, and they normally do when planning from a branch. If `git status --porcelain` is not empty, name every dirty path in the plan's evidence section so a later executor knows what the inspected tree contained.
+
+Then write only under:
 
 `.oat/repo/reference/external-plans/`
 
@@ -196,13 +214,23 @@ The index records source artifacts, selection rationale, execution order, depend
 Each plan must:
 
 - be self-contained for an executor with no session context;
-- carry external-plan frontmatter identifying source mode, source paths, planned-at commit, and related backlog IDs;
+- carry external-plan frontmatter identifying source mode, source paths, and related backlog IDs;
+- record the full inspected `HEAD` in `oat_external_plan_commit`, the compared `origin/main` or merge-base SHA in `oat_external_plan_main_commit`, and the planning date in `oat_external_plan_date`;
+- carry `oat_execution_status: READY|BLOCKED` that agrees with its own `## Dependencies` table;
+- include a typed `## Dependencies` table whose rows are `Hard`, `Soft`, or `Satisfied` and whose `Hard` rows name an unblock state, a `## Landing-event impact` table, and a `## Revalidation Before Execution` section;
+- link back to its source backlog item or artifact from the plan body, so the link runs in both directions;
 - state explicitly that it is not a canonical OAT `plan.md`;
 - include exact paths, live-state evidence, relevant conventions, hard scope boundaries, ordered steps, tests, machine-checkable verification, done criteria, and specific STOP conditions;
-- avoid OAT phase/task IDs and lifecycle metadata;
+- avoid canonical OAT phase/task IDs and lifecycle bookkeeping, while carrying the external execution-readiness metadata above;
 - preserve source intent without copying unverified claims;
 - never contain secret values.
 
+Three document kinds live under `external-plans/`, and the readiness rules differ by kind. A plan carries the full contract. An index (`oat_external_plan_index: true`) carries provenance but no status or dependency/landing/revalidation sections. An execution program (`oat_execution_program: true`, written by `oat-wave-program`) maps plans into waves: it inspects no tree, so it carries no provenance SHAs and no status, and must instead carry `oat_program_indexes`, a `## Status Ledger` whose wave statuses are `composed`, `in-progress`, `merged`, or `done`, and a `## Wave Table`. A program has no plan date, so its mode is selected from `created`. See the "Execution Programs" section of `references/plan-template.md`.
+
+Plans written before this contract landed on 2026-09-07 are read in legacy mode and are never retrofitted. The 31 plans in the 2026-08-31 execution program stamped `oat_external_plan_commit` with the `origin/main` SHA whose content they inspected from a planning branch; legacy mode accepts that provenance as-is. Apply the full provenance rule only to plans written from now on.
+
+A plan executed inside a wave refreshes its drift check against the exact execution `HEAD` after predecessor lanes integrate, not only from the authored SHA to `origin/main`. Record that refreshed comparison rather than re-stamping the authored provenance.
+
 Before writing, apply the project-size threshold. If a candidate contains multiple independently shippable outcomes, spans subsystems that need separate design decisions, has no single coherent verification boundary, or is otherwise project-sized:
 
 1. Split separable work into bounded external plans.
@@ -219,6 +247,8 @@ After every plan write succeeds, update each source backlog item:
 - update `updated` to the current ISO 8601 UTC timestamp;
 - preserve all unrelated frontmatter and body content.
 
+Links must run in both directions: the item's `external_plans` array points at the plan, and the plan body's source section links back to the item. A plan that no source links to, or that links to no source, is only half-tracked; verify both directions before reporting the plan as written.
+
 If safe YAML mutation cannot be established, leave the item unchanged and report the missing reverse link. Never leave a reverse link to a failed or partial plan write.
 
 Plans are always the primary output. Tracking publication happens only after the relevant plan writes succeed.
@@ -298,9 +328,14 @@ Audit the repository for security and test improvements, then let me choose what
 
 **A candidate is project-sized:** Split it when possible; otherwise recommend the appropriate OAT project/import route instead of writing a mega-plan.
 
+**A candidate's dependency has not landed:** Plan it anyway when it is `plan_ready`. Record `oat_execution_status: BLOCKED`, type the blocking row `Hard` in `## Dependencies`, and name the state that unblocks it. Do not silently drop the candidate, and do not mark it `READY` to keep the table tidy — an unsatisfied hard dependency with a `READY` status is exactly the contradiction this contract exists to prevent.
+
 ## Success Criteria
 
 - Exactly one source mode and source boundary are explicit.
+- Candidates are scored for plan readiness and execution readiness separately, and a plan-ready but blocked candidate is planned as `BLOCKED` rather than dropped.
+- Every plan records the full inspected `HEAD` SHA, a separate comparison SHA, the planning date, and an `oat_execution_status` that agrees with its dependency table.
+- Every plan carries typed dependencies, landing-event impact, and revalidation triggers, and links back to its source item.
 - Repo audits disclose and lock agent-directory inclusion plus any additional user exclusions before reconnaissance.
 - Substantive repo audits use managed read-only delegation or stop for narrowing/authorization.
 - Artifact-backed modes remain scoped to their source material plus bounded verification.

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

@@ -2,7 +2,9 @@
 
 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.
 
-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.
+External plans are durable reference artifacts. They are deliberately not canonical OAT `plan.md` files and must not carry canonical OAT lifecycle state: phase IDs, task IDs, phase or task status tables, review tables, or implementation bookkeeping.
+
+External execution-readiness metadata is a different thing and is explicitly permitted and required: `oat_execution_status`, the `## Dependencies` table, `## Landing-event impact`, and `## Revalidation Before Execution`. These record whether the plan's own prerequisites have merged, not how an OAT project is progressing through phases.
 
 ## File Contract
 
@@ -19,7 +21,10 @@ 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_external_plan_commit: <full 40-character SHA of the inspected HEAD>
+oat_external_plan_main_commit: <full 40-character SHA of the compared origin/main or merge-base>
+oat_external_plan_date: '<YYYY-MM-DD>'
+oat_execution_status: READY|BLOCKED
 oat_backlog_items: []
 oat_issue_url: null
 created: '<ISO 8601 UTC>'
@@ -28,6 +33,14 @@ created: '<ISO 8601 UTC>'
 
 `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.
 
+`oat_external_plan_commit` is the full SHA of the `HEAD` whose content was actually inspected while planning — never a fetched tip that was not read. `oat_external_plan_main_commit` records the fetched `origin/main`, or the merge-base with it, as comparison evidence only. The two SHAs may differ, and they normally do when planning happens on a branch; recording them separately is what keeps "what I read" distinct from "what I compared against". `oat_external_plan_date` is the planning date. `oat_execution_status` is `READY` when no unsatisfied hard dependency blocks execution and `BLOCKED` otherwise.
+
+### Legacy plans
+
+A plan with no `oat_external_plan_date`, or dated before this contract's landing date of `2026-09-07`, is read in legacy mode. Legacy mode accepts a short `oat_external_plan_commit` SHA, a missing `oat_external_plan_main_commit`, missing `## Dependencies`, `## Landing-event impact`, and `## Revalidation Before Execution` sections, and a missing `oat_execution_status` (read as `READY`).
+
+Legacy plans are never rewritten to satisfy the prospective rules. Retrofitting durable plans is not a prerequisite for this contract, and a rule that would make an existing plan invalid or unimportable is a defect in the rule.
+
 ## Plan Template
 
 ````markdown
@@ -41,6 +54,11 @@ created: '<ISO 8601 UTC>'
 > Begin with the drift check. Follow the steps and verification gates in order.
 > If a STOP condition occurs, stop and report instead of improvising.
 
+> [!IMPORTANT]
+> **Execution status: READY|BLOCKED.** Say why in one or two sentences: assert
+> that no unsatisfied hard dependency blocks execution, or name the blocking
+> dependency and the state that would unblock it.
+
 ## Outcome
 
 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.
@@ -48,19 +66,43 @@ State the observable end result in 2–5 sentences. Explain why it matters and p
 ## Source and live evidence
 
 - 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>`
+- Inspected `HEAD`: `<full SHA>` — the tree whose content this plan actually read
+- Comparison baseline: `<full SHA>` — say which it is, the fetched `origin/main` tip or the merge-base with it; comparison evidence only, and it may differ from the inspected `HEAD`
+- Planning date: `<YYYY-MM-DD>`
+- Working tree while planning: `git status --porcelain` was empty, or every dirty path is named here
+- Related backlog items: `<ID and title, or none>` — link the item from this plan body so the link runs in both directions
 - Verified evidence:
   - `<file:line or command evidence>` — what it establishes
 
 Distinguish source assertions from facts verified against the live repository. Do not copy stale evidence forward.
 
+## Dependencies
+
+Type every dependency and name its unblock state. `Hard` blocks execution. `Soft` records an ordering, integration, or evidence preference that never blocks. `Satisfied` records a formerly hard dependency that is now met.
+
+The first word of the Type cell is the class; anything after it is a free-form qualifier, as in `Hard ordering`, `Soft adjacency`, or `Satisfied predecessor`. Earlier plans used ad-hoc type words such as `Related, distinct`, `Downstream`, or `Open question`; those stay valid in legacy mode, and a new plan expresses the same meaning as a `Soft` row with that word as its qualifier.
+
+| Type          | Dependency                   | Required state           | Current state |
+| ------------- | ---------------------------- | ------------------------ | ------------- |
+| Hard ordering | [Plan](./YYYY-MM-DD-slug.md) | Merged to `origin/main`. | Pending.      |
+| Soft ordering | [Plan](./YYYY-MM-DD-slug.md) | Never in one group.      | Landed.       |
+
+Every `Hard` row's Current state begins with a named unblock state: `Satisfied`, `Landed`, `Merged`, or `Accepted` when it is met; `Pending`, `Blocked`, or `In flight` when it is not. State plainly whether any unsatisfied hard dependency remains, and keep `oat_execution_status` in agreement with that sentence.
+
+Dependency state alone never disqualifies a plan. A well-formed plan whose prerequisites have not merged is written and recorded as `BLOCKED`, not withheld.
+
+## Landing-event impact
+
+| Event                   | Affected | Files in common | Required update                        |
+| ----------------------- | -------- | --------------- | -------------------------------------- |
+| `<PR or project>` lands | Minor    | `<shared file>` | Re-anchor `<citation>` before editing. |
+
 ## Drift check
 
 Run before editing:
 
 ```bash
-git diff --stat <planned-at SHA>..HEAD -- <in-scope paths>
+git diff --stat <inspected HEAD SHA>..HEAD -- <in-scope paths>
 ```
 ````
 
@@ -136,10 +178,24 @@ Stop and report instead of improvising when:
 - 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;
+- an unsatisfied hard dependency in `## Dependencies` still blocks execution, whatever `oat_execution_status` claims;
 - the work would expose, copy, or rotate a credential without explicit authority.
 
 Add plan-specific STOP conditions for its actual risks.
 
+## Revalidation Before Execution
+
+Revalidate this plan against live state before executing when:
+
+- substantial time passes after the planning date;
+- `origin/main` advances materially from the inspected `HEAD`;
+- a named in-flight project or PR lands;
+- a dependency named in `## Dependencies` changes state;
+- an in-scope file's step numbering, section order, or cited line anchors change;
+- a load-bearing evidence claim cannot be reproduced.
+
+Apply the `## Landing-event impact` table when one of its events has occurred. A plan executed inside a wave refreshes its drift check against the exact execution `HEAD` after predecessor lanes integrate, not only from the authored SHA to `origin/main`.
+
 ## Review focus
 
 - What a reviewer should inspect most closely.
@@ -159,7 +215,9 @@ 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>
+oat_external_plan_commit: <full 40-character SHA of the inspected HEAD>
+oat_external_plan_main_commit: <full 40-character SHA of the compared origin/main or merge-base>
+oat_external_plan_date: '<YYYY-MM-DD>'
 created: '<ISO 8601 UTC>'
 ---
 
@@ -187,6 +245,22 @@ not an `oat-project-import-plan` target.
 
 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.
 
+An index records the same provenance as a plan, but it carries no `oat_execution_status` and none of the dependency, landing-event, or revalidation sections: it is not executable, so it has no execution readiness of its own. Each indexed plan carries its own status.
+
+## Execution Programs
+
+A third document kind can appear in `external-plans/`: an execution program, marked `oat_execution_program: true`. Programs are written by `oat-wave-program`, not by this skill, and this contract only says how to read one.
+
+A program maps a corpus of plans into waves. It inspects no tree, so it carries no `oat_external_plan_commit`, no `oat_external_plan_main_commit`, and no `oat_execution_status` — asking a map for provenance or execution readiness is a category error, and each plan it lists answers those questions for itself. What a program must carry instead is its ledger:
+
+- `oat_program_indexes` listing at least one plan index path;
+- a `## Status Ledger` section with a `Wave | Theme | Lanes | Status | Record` table recording at least one wave, where every Status cell is `composed`, `in-progress`, `merged`, or `done` — the vocabulary `oat-wave-program` itself uses;
+- a `## Wave Table` section recording at least one plan; its heading may carry a coverage suffix, as in `## Wave Table (coverage: 31 plans = 31 index rows)`.
+
+A program's mode is selected by `oat_external_plan_date` when it has one and by the date part of `created` otherwise, because the producing template emits `created` and no plan date. Without that fallback every generated program would sort into legacy mode permanently and never be checked at all.
+
+A program dated on or after the contract's landing date is held to exactly the rules above; an earlier one is read in legacy mode like any other artifact. The exemption is deliberate and bounded: a program is not exempt from the contract, it is held to the part of it that applies to a map.
+
 ## Quality Gate
 
 Before finishing each plan, confirm:
@@ -197,4 +271,7 @@ Before finishing each plan, confirm:
 - 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.
+- `oat_external_plan_commit` holds the full SHA of the inspected `HEAD`, `oat_external_plan_main_commit` holds the compared `origin/main` or merge-base SHA, and `oat_external_plan_date` is set.
+- `oat_execution_status` is exactly `READY` or `BLOCKED` and agrees with the unblock states recorded in `## Dependencies`.
+- `## Dependencies`, `## Landing-event impact`, and `## Revalidation Before Execution` are all present, and the plan body links back to its source item.
+- No secret value, workstation-only absolute path, OAT phase or task ID, or canonical OAT lifecycle bookkeeping appears; external execution-readiness metadata is permitted.

package/assets/templates/plan-lite.md

@@ -0,0 +1,165 @@
+---
+oat_status: in_progress
+oat_ready_for: null
+oat_blockers: []
+oat_last_updated: YYYY-MM-DD
+oat_phase: plan
+oat_phase_status: in_progress
+oat_plan_hill_phases: []
+oat_plan_parallel_groups: []
+oat_plan_source: lite
+oat_import_reference: null
+oat_import_source_path: null
+oat_import_provider: null
+oat_generated: false
+oat_template: true
+oat_template_name: plan-lite
+---
+
+# Lite Plan: {Project Name}
+
+**Goal:** [State the outcome this single-sitting change must achieve.]
+
+## Summary
+
+[Summarize the requested behavior and the smallest coherent implementation.]
+
+## Decisions
+
+- **Content shape:** `[minimal | product | technical | both]` — [One-line rationale tied to the observable shape triggers.]
+- [Record the other decisions made during the critical interview.]
+
+## Product Behavior
+
+<!-- Include for product or both; omit this section for minimal or technical. -->
+
+1. **[Observable behavior]** — [State the testable user-visible outcome.]
+
+## Technical Design
+
+<!-- Include for technical or both; omit this section for minimal or product. -->
+
+- **Current operation:** [Describe how the affected modules and contracts work now.]
+- **Proposed changes:** [Describe the change with file-and-symbol references, not line numbers.]
+- **Data flow:** [When state or data crosses a boundary, describe its path and transformations. Omit this item otherwise.]
+
+## Assumptions
+
+- [Record assumptions the implementation and validation depend on.]
+
+## Out of Scope
+
+- [Name adjacent work intentionally excluded from this change.]
+
+## Validation Criteria
+
+- [ ] [Observable criterion] — Check: `[exact verification command]`
+- [ ] [Observable criterion] — Check: `[exact verification command]`
+
+## Parallelism
+
+This plan has one phase and executes sequentially.
+
+## Phase 1: [Phase Name]
+
+### Task p01-t01: [Task Name]
+
+**Files:**
+
+- Create: `[path/to/file.ts]`
+- Modify: `[path/to/existing.ts]`
+
+**Implementation and Proof Strategy:**
+
+- **Strategy:** `[test-first | characterization-first | implementation-then-regression | static-or-build | manual-or-visual]`
+- **Observable risk:** [Name the behavior, contract, or invariant this evidence covers.]
+- **Why proportionate:** [Explain why this is the smallest proof capable of detecting the relevant failure.]
+
+**Step 1: Implement**
+
+[Describe the bounded implementation in the order required by the selected strategy.]
+
+**Step 2: Prove**
+
+Run: `[exact proof command or manual: instruction]`
+Expected: [State the observable passing result and, for behavior changes, how this proof fails without the change.]
+
+**Step 3: Refactor and format**
+
+[Describe bounded cleanup and name the exact write-mode formatting command.]
+
+**Step 4: Verify**
+
+Run: `[exact task verification command]`
+Expected: No errors
+
+**Step 5: Commit**
+
+```bash
+git add [task files]
+git commit -m "feat(p01-t01): [description]"
+```
+
+---
+
+### Task p01-t02: [Task Name]
+
+**Files:**
+
+- Modify: `[path/to/existing.ts]`
+
+**Implementation and Proof Strategy:**
+
+- **Strategy:** `[test-first | characterization-first | implementation-then-regression | static-or-build | manual-or-visual]`
+- **Observable risk:** [Name the behavior, contract, or invariant this evidence covers.]
+- **Why proportionate:** [Explain why this is the smallest proof capable of detecting the relevant failure.]
+
+**Step 1: Implement**
+
+[Describe the bounded implementation in the order required by the selected strategy.]
+
+**Step 2: Prove**
+
+Run: `[exact proof command or manual: instruction]`
+Expected: [State the observable passing result and, for behavior changes, how this proof fails without the change.]
+
+**Step 3: Refactor and format**
+
+[Describe bounded cleanup and name the exact write-mode formatting command.]
+
+**Step 4: Verify**
+
+Run: `[exact task verification command]`
+Expected: No errors
+
+**Step 5: Commit**
+
+```bash
+git add [task files]
+git commit -m "feat(p01-t02): [description]"
+```
+
+---
+
+## Reviews
+
+| Scope  | Type     | Status  | Date | Artifact | Reviewed Head | Invocation | Gate Target |
+| ------ | -------- | ------- | ---- | -------- | ------------- | ---------- | ----------- |
+| p01    | code     | pending | -    | -        | -             | -          | -           |
+| final  | code     | pending | -    | -        | -             | -          | -           |
+| spec   | artifact | pending | -    | -        | -             | -          | -           |
+| design | artifact | pending | -    | -        | -             | -          | -           |
+
+## Implementation Complete
+
+**Summary:**
+
+- Phase 1: [N] tasks — [Description]
+
+**Total: [N] tasks**
+
+Ready for final code review and PR preparation.
+
+## References
+
+- Imported Source: `references/imported-plan.md` (when imported provenance applies)

package/assets/templates/plan.md

@@ -7,7 +7,7 @@ oat_phase: plan
 oat_phase_status: in_progress
 oat_plan_hill_phases: [] # phases to pause AFTER completing (empty = every phase)
 oat_plan_parallel_groups: [] # groups of phases that run concurrently in worktrees; [] = fully sequential
-oat_plan_source: spec-driven # spec-driven | quick | imported
+oat_plan_source: spec-driven # spec-driven | quick | imported | lite
 oat_import_reference: null # e.g., references/imported-plan.md
 oat_import_source_path: null # original source path provided by user
 oat_import_provider: null # codex | cursor | claude | null