@open-agent-toolkit/cli 0.2.59 → 0.2.62

package/assets/agents/oat-phase-implementer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-phase-implementer
-version: 1.1.3
+version: 1.1.5
 description: Implements one plan phase end-to-end, commits each task separately, self-checks between tasks, and handles bounded review fixes when resumed by oat-project-implement.
 tools: Read, Write, Edit, Bash, Grep, Glob, Task
 color: cyan
@@ -29,7 +29,7 @@ The root supplies:
 - `mode`: `implement`, `fix`, or `recover`;
 - `artifact_paths`: available plan, design, spec, discovery, implementation,
   and imported-plan paths;
-- `workflow_mode`: `spec-driven`, `quick`, or `import`;
+- `workflow_mode`: `spec-driven`, `quick`, `import`, or `lite`;
 - `commit_convention`: exact task/fix commit convention;
 - `phase_base_head`: root-recorded HEAD before phase dispatch;
 - `worktree`: assigned phase worktree or orchestration checkout;
@@ -120,6 +120,11 @@ Read each required artifact once at phase start:
 - `quick`: phase section from plan and discovery; design/spec when present;
 - `import`: phase section from plan and imported plan; design/spec when
   present.
+- `lite`: read the whole plan.md requirements contract: the assigned phase
+  section plus Summary, Decisions, Assumptions, Out of Scope, and Validation
+  Criteria, and the Product Behavior and/or Technical Design selected by its
+  recorded `minimal`, `product`, `technical`, or `both` content shape.
+  Discovery, spec, and design are absent by design.
 
 Extract all phase tasks, dependency order, file boundaries, verification
 commands, commit messages, and phase-wide verification before editing.
@@ -402,7 +407,20 @@ For every task:
 
 1. Record `PRE_TASK_HEAD`.
 2. Read the task steps and declared file boundary.
-3. Follow RED/GREEN/refactor ordering when specified.
+3. Execute the task's declared implementation and proof strategy without
+   silently substituting TDD. Follow RED/GREEN/refactor ordering only when the
+   selected strategy specifies it.
+   For required manual or visual proof, inspect the effective runtime tool
+   catalog for an available computer-use capability; never infer availability
+   from planning prose, configuration, or another agent's tools. Use available
+   computer-use for required visual proof and record the performed proof. When
+   no available executor can perform the criterion, stop before committing the
+   task or marking the task or phase complete. Under `OAT_AUTONOMOUS=1`, return
+   `BLOCKED` with an explicit `IMPLEMENT-20 unverified proof boundary` and name
+   the criterion and missing capability. In an interactive run, return
+   `NEEDS_CONTEXT` and wait for the operator to execute the criterion or direct
+   the next action. Neither path may mark unavailable proof
+   deferred-but-verified.
 4. Implement only that task. Optional nested help does not transfer task
    ownership or commit authority.
 5. Apply the Prevention and Post-Commit Recovery ordering: format, run every
@@ -440,7 +458,12 @@ After all task commits:
 - apply the same post-commit recovery contract to an eligible phase-level
   composition failure;
 - verify task outputs compose correctly;
-- compare the phase result with design/spec/discovery;
+- compare the phase result with the requirements source selected by workflow
+  mode:
+  - `lite`: the complete `plan.md` requirements contract loaded at phase start;
+  - `spec-driven`: `plan.md`, `design.md`, and `spec.md`;
+  - `quick`: `plan.md` and `discovery.md`, plus design/spec when present; and
+  - `import`: `plan.md` and the imported plan, plus design/spec when present;
 - confirm no task boundary or dependency was missed; and
 - report Medium/Minor concerns without launching a reviewer.
 

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.2.1
+version: 1.2.3
 description: Unified reviewer for OAT projects - mode-aware verification of requirements/design alignment and code quality. Writes a review artifact to disk by default, or returns structured findings in-memory when dispatched in structured-output mode.
 tools: Read, Bash, Grep, Glob, Write, Task
 color: yellow
@@ -50,7 +50,7 @@ You will be given a "Review Scope" block including:
 - **commits/range**: Git commits or SHA range for changed files. For code review, this is the authoritative review surface.
 - **files_changed**: Optional orientation hint listing files believed to be modified in scope. If this disagrees with the commit range, trust the commit range.
 - **analysis_artifact**: For `type: analysis`, path to the severity-rated analysis artifact to fact-check.
-- **workflow_mode**: `spec-driven` | `quick` | `import` (default to `spec-driven` if absent)
+- **workflow_mode**: `spec-driven` | `quick` | `import` | `lite` (default to `spec-driven` if absent)
 - **artifact_paths**: Paths to available artifacts (spec/design/plan/implementation/discovery/import reference)
 - **tasks_in_scope**: Task IDs being reviewed (if task/phase scope)
 - **oat_output_mode**: Optional output-sink selector. Absent (or any value other than `structured`) means **artifact mode** — write the review artifact to disk per Step 8. `structured` means **structured-output mode** — return a `StructuredFindings` object in-memory and write NO artifact file (see **Structured-Output Mode**). This key parallels the existing `oat_review_invocation` dispatch-payload naming.
@@ -122,6 +122,7 @@ Use workflow mode to determine required evidence:
 - **spec-driven**: `spec.md`, `design.md`, `plan.md` are expected.
 - **quick**: `discovery.md` + `plan.md` are expected (`spec.md`/`design.md` optional if present).
 - **import**: `plan.md` is expected (`references/imported-plan.md` preferred; `spec.md`/`design.md` optional).
+- **lite**: `plan.md` and `implementation.md` are expected; discovery, spec, and design are absent by design.
 
 Do not mark missing optional artifacts as findings.
 If required artifacts for the mode are unexpectedly missing, record a workflow contract gap.
@@ -144,6 +145,7 @@ Read available artifacts to understand what SHOULD have been built:
    - `spec-driven`: read `spec.md` and `design.md`.
    - `quick`: read `discovery.md` and `plan.md`; read `spec.md`/`design.md` only if they exist.
    - `import`: read `plan.md` and `references/imported-plan.md` (if present); read `spec.md`/`design.md` only if they exist.
+   - `lite`: read `plan.md` and `implementation.md`; do not require discovery, spec, design, or an import reference.
 3. For `type: analysis`, read `analysis_artifact` and then inspect only the cited evidence sources needed to verify its findings:
    - `scope: docs`: consult the docs contract, docs navigation/index files, and cited docs source files relevant to the analysis.
    - `scope: agent-instructions`: consult the repo/root instruction files, provider instruction files, and cited skill/agent instruction files relevant to the analysis.
@@ -168,6 +170,7 @@ For each requirement in scope, use the best available requirement source by mode
 - `spec-driven`: `spec.md` (primary), `design.md` mapping (secondary)
 - `quick`: `discovery.md` + `plan.md`
 - `import`: normalized `plan.md` + `references/imported-plan.md` (if present)
+- `lite`: the requirements contract in `plan.md`: Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria. Also use Product Behavior and/or Technical Design when selected by the recorded `minimal`, `product`, `technical`, or `both` content shape.
 
 Then verify:
 
@@ -176,10 +179,17 @@ Then verify:
    - Check acceptance criteria are met
    - If missing: add to Critical findings
 
-2. **Is the Verification satisfied?**
-   - Check if tests exist matching declared verification intent in available artifacts
-   - If `design.md` exists, cross-reference Requirement-to-Test Mapping
-   - If tests missing for P0 requirements: add to Critical findings
+2. **Is the applicable verification intent satisfied?**
+   - First identify the verification intent declared by the applicable workflow
+     artifacts. When that contract declares an `Implementation and Proof
+Strategy`, check whether the evidence matches the declared strategy, covers
+     its observable risk, and is capable of failing when the claim is false.
+   - A missing or unjustified proof strategy is a finding only when the
+     applicable workflow artifact declares that strategy. When it does not,
+     review the plan's existing verification commands and produced evidence
+     without inventing a missing strategy field.
+   - If `design.md` exists, cross-reference Requirement-to-Test Mapping.
+   - The absence of an automated test alone is not a finding.
 
 3. **Is there extra work?**
    - Code that doesn't map to any requirement
@@ -207,6 +217,7 @@ Treat the artifact as a product deliverable. Verify it is:
      - `spec-driven`: spec + design
      - `quick`: discovery (+ spec/design if present)
      - `import`: imported-plan reference (+ discovery/spec/design if present)
+     - `lite`: plan.md Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria. Also review the Product Behavior and/or Technical Design required by its recorded content shape; challenge `minimal` when an observable shape trigger applies.
    - For import-mode `plan` reviews, bias findings toward canonical-format conformance and completeness. Do not rewrite the imported author's intent merely to match OAT house style.
 
 4. **Actionable**
@@ -220,7 +231,7 @@ Treat the artifact as a product deliverable. Verify it is:
    - Stable task IDs: task headings use `pNN-tNN`, IDs are monotonic within each phase, and review-generated tasks do not reuse prior IDs.
    - Required sections: the plan includes Reviews, Implementation Complete, and References sections without placeholder-only critical content.
    - Review-table preservation: existing review rows are preserved; never require deleting rows to "clean up" the table.
-   - Task atomicity and verifiability: each task is independently committable, has bounded file scope, and declares verification that can actually be run.
+   - Task atomicity and verifiability: each task is independently committable, has bounded file scope, and has executable verification intent. Require a proportionate implementation and proof strategy only when the applicable workflow plan contract declares it; otherwise review the task's existing verification commands and evidence.
    - Coverage of design/discovery: every in-scope design component or discovery decision is mapped to at least one task or explicitly deferred/out of scope.
    - Parallelism-claim sanity: any parallel phase group or parallelism statement is consistent with declared file boundaries and dependency order.
 
@@ -228,7 +239,7 @@ Treat the artifact as a product deliverable. Verify it is:
 
 This step applies to **code reviews** only.
 
-If `design.md` is absent in quick/import mode, mark design alignment as "not applicable (design artifact not present for mode)" and continue.
+If `design.md` is absent in quick/import/lite mode, mark design alignment as "not applicable (design artifact not present for mode)" and continue.
 
 For each design decision relevant to scope:
 
@@ -283,10 +294,10 @@ Pragmatic code quality review (not exhaustive):
    - Off-by-one errors, null handling
    - Missing error handling for likely failures
 
-2. **Test coverage**
-   - Critical paths have tests
-   - Edge cases covered
-   - Unhappy paths tested
+2. **Evidence coverage**
+   - Critical paths have evidence matching the declared proof strategy
+   - Edge cases are covered where relevant
+   - Behavioral claims have a control that fails without the change
 
 3. **Security**
    - Input validation at boundaries
@@ -307,14 +318,14 @@ Group findings by severity:
 - Missing P0 requirements
 - Security vulnerabilities
 - Broken functionality
-- Missing tests for critical paths
+- Missing capable evidence for critical paths
 
 **Important** (should fix before merge)
 
 - Missing P1 requirements
 - Missing error handling
 - Significant maintainability issues
-- Missing tests for important paths
+- Missing capable evidence for important paths
 - Stale spec/design/plan artifact that conflicts with a defensible implementation and should be aligned before closeout
 
 **Medium** (default fix before pass)

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.59"
+  "oatVersion": "0.2.62"
 }

package/assets/docs/cli-utilities/workflow-gates.md

@@ -62,8 +62,8 @@ A valid command is stored byte-for-byte. `oat gate resolve` returns that exact
 string, and the lifecycle executes it unchanged; OAT does not inject, reorder,
 or rewrite its shell arguments.
 
-`oat-project-plan`, `oat-project-implement`, `oat-project-quick-start`, and
-`oat-project-import-plan` are currently gate-aware. Gate awareness is declared
+`oat-project-plan`, `oat-project-implement`, `oat-project-quick-start`,
+`oat-project-lite`, and `oat-project-import-plan` are currently gate-aware. Gate awareness is declared
 in skill frontmatter with `oat_gateable: true`, and
 `oat internal validate-oat-skills` warns when config targets a missing or
 non-gateable skill.
@@ -610,7 +610,7 @@ oat gate set oat-project-implement \
 ```
 
 Apply the same command shape to `oat-project-plan`,
-`oat-project-quick-start`, and `oat-project-import-plan` when those lifecycle
+`oat-project-quick-start`, `oat-project-lite`, and `oat-project-import-plan` when those lifecycle
 skills have configured review gates. Do not add `--target`; explicit targets
 remain manual/debug or deliberate local/user-specific overrides.
 

package/assets/docs/reference/cli-reference.md

@@ -56,8 +56,14 @@ The first practical expansion path is to keep improving the existing owners: [Do
 
 Notable commands introduced in the current CLI surface:
 
-- `oat project new <slug> --scope shared|local|synced [--force]` - create a
-  project in an explicit scope. Without `--scope`, creation uses
+- `oat project new <slug> [--mode spec-driven|quick|import|lite] --scope shared|local|synced [--force]` - create a
+  project in an explicit scope. `--mode` selects the workflow mode and therefore
+  which artifacts are scaffolded; it defaults to `spec-driven`. Use `quick` for a
+  bounded feature with clear requirements, `import` to normalize an externally
+  authored plan, and `lite` for a single-sitting change that scaffolds only
+  `plan.md`, `state.md`, and `implementation.md`. See
+  [Lifecycle](../workflows/projects/lifecycle.md) for the per-lane flow. Without
+  `--scope`, creation uses
   `projects.defaultScope`, which defaults to `synced`. Project slugs are
   unique across all scopes by default, including recorded or remotely
   published synced projects. `--force` deliberately permits a duplicate; use
@@ -133,13 +139,14 @@ Notable commands introduced in the current CLI surface:
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
 - `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
+- `oat project promote <project-path> --to quick [--json]` - promote an authored lite project to quick mode. The command derives `discovery.md` from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as `references/lite-plan.md`; and scaffolds a fresh quick `plan.md`. It refuses unsupported targets, non-lite or unreadable projects, an existing lite-plan reference, invalid authored sections, unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is `{ status: "promoted" | "refused", reason, files }`; `reason` is the stable categorical contract and refused results exit non-zero.
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. Legacy complete records receive a cleanup diagnosis rather than pull/open guidance. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal. Omit `--project` to validate without persisting. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
-- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
+- `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
 - `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).

package/assets/docs/reference/oat-directory-structure.md

@@ -305,6 +305,7 @@ Not all workflow modes require every artifact:
 - `spec-driven`: discovery + spec + design + plan + implementation
 - `quick`: discovery + plan + implementation (spec/design optional)
 - `import`: imported plan + implementation (spec/design optional)
+- `lite`: single-phase plan + implementation (summary/documentation optional at closeout)
 
 ## `.oat/repo/` structure
 

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

@@ -37,4 +37,4 @@ If the thought is still pre-shape — you don't know whether it should land as a
 
 ## Promotion Path
 
-When an idea becomes concrete, summarize it and then start a tracked OAT project in quick or spec-driven mode depending on design risk.
+When an idea becomes concrete, summarize it and then start a tracked OAT project in lite, quick, or spec-driven mode depending on scope and design risk. Lite suits a single-sitting change and seeds `plan.md` directly; quick and spec-driven seed `discovery.md` instead.

package/assets/docs/workflows/index.md

@@ -44,6 +44,7 @@ Stay with direct CLI usage when:
 ## Workflow Modes In Practice
 
 - CLI only: direct commands, no tracked project artifacts
+- Lite mode: a batched interview and one approval produce a single-phase `plan.md` for a single-sitting change
 - Quick mode: tracked work with a lighter upfront planning path
 - Spec-driven mode: explicit discovery, requirements, design, and plan artifacts
 - Import mode: an externally-authored plan imported into OAT for tracked execution

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

@@ -50,9 +50,30 @@ archive metadata own terminal reachability and retry identity.
 
 Mode-sensitive notes:
 
-- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`) for routing.
-- `spec.md` and `design.md` are required in spec-driven mode, optional in quick/import mode. Quick mode offers a lightweight `design.md` (architecture, components, testing strategy) at a post-discovery decision point.
-- `plan.md` remains canonical execution artifact across all modes.
+- `state.md` includes workflow mode metadata (`spec-driven`, `quick`, `import`, `lite`) for routing.
+- `plan.md` remains the canonical execution artifact across all modes.
+
+| Mode          | Core authored artifacts                                                                                                                | Optional artifacts                         |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `spec-driven` | `discovery.md`, `spec.md`, `design.md`, `plan.md`                                                                                      | -                                          |
+| `quick`       | `discovery.md`, `plan.md`                                                                                                              | Lightweight `design.md`, `spec.md`         |
+| `import`      | `references/imported-plan.md`, `plan.md`                                                                                               | `spec.md`, `design.md`                     |
+| `lite`        | Single-phase `plan.md` with Summary, Decisions, Assumptions, Out of Scope, Validation Criteria, and an explicit adaptive content shape | `summary.md` and documentation at closeout |
+
+Every Lite plan keeps Summary, Decisions, Assumptions, Out of Scope, and
+Validation Criteria. User-visible changes add numbered, testable Product
+Behavior. Changes that cross module boundaries, alter data or state formats,
+or change a contract consumed by another surface add Technical Design. That
+section covers current operation, proposed changes, and data flow when data or
+state crosses a boundary. The Decisions section records the selected shape and
+why it fits.
+
+Each Lite task also records an implementation and proof strategy: the risk it
+covers, why the evidence is proportionate, and the exact command or manual
+proof. Strategies may be test-first, characterization-first,
+implementation-then-regression, static/build, or manual/visual. Static or build
+checks alone fit only changes that cannot affect runtime behavior; every
+behavioral change needs evidence that fails without the change.
 
 ## Supporting artifacts
 

package/assets/docs/workflows/projects/hill-checkpoints.md

@@ -38,6 +38,27 @@ Semantics:
 - Empty list: checkpoint after every phase boundary, but only after implementation has confirmed the choice and written `oat_plan_hill_phases: []` into `plan.md`.
 - Explicit list: checkpoint only after completing the named phases (`p01`, `p04`, etc).
 
+### Lite checkpoint bypass
+
+Lite projects have no HiLL checkpoints. `oat-project-implement` resolves
+`oat_workflow_mode` from project state before any checkpoint field read, and
+when the mode is `lite` it resolves checkpoint state as `none` without reading
+or interpreting `oat_plan_hill_phases`. An empty list cannot represent lite's
+policy, because for every other mode an empty list means "checkpoint after every
+phase". `oat-project-implement`'s Lite checkpoint bypass writes:
+
+```yaml
+oat_auto_review_at_hill_checkpoints: false # lite: no checkpoints
+```
+
+The workflow preference prompt, the standard checkpoint prompt, and the
+auto-review preference prompt are all skipped in both interactive and autonomous
+runs. Only HiLL approval pauses are absent — the root-owned per-phase review and
+the final review remain required.
+
+The rest of this section applies to `spec-driven`, `quick`, and `import`
+projects.
+
 On the first implementation run, `oat-project-implement` must summarize every plan phase, state the total phase count and final phase ID, and then ask an explicit three-option checkpoint question:
 
 - Stop after each phase

package/assets/docs/workflows/projects/implementation-execution.md

@@ -426,6 +426,11 @@ For a plan-declared parallel group, the root:
 Containment, ownership, base, or fixture-readiness failure in smoke mode aborts
 the run. It never authorizes replacement or sequential degradation.
 
+Lite plans never take this path. A lite `plan.md` must contain exactly one phase
+and declare no parallel groups, so lite implementation is always sequential;
+`oat project validate-plan` enforces both rules. Work that needs more than one
+phase should promote to quick rather than declare a parallel group.
+
 ## Synced projects in worktrees
 
 A tracked `.oat/projects/synced/<project>.json` record lets every repository

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

@@ -1,6 +1,6 @@
 ---
 title: Lifecycle
-description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, and import paths.'
+description: 'End-to-end phase flow from discovery through completion: spec-driven, quick, lite, and import paths.'
 ---
 
 # Lifecycle
@@ -27,9 +27,9 @@ Full spec-driven design supports three interaction modes: collaborative, selecti
 
 ## Quick Look
 
-- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick and import lanes.
+- What it does: explains the end-to-end lifecycle for tracked OAT projects, including alternate quick, lite, and import lanes.
 - When to use it: when you need the actual project execution model, not just a high-level overview of workflow mode.
-- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-import-plan`, `oat-project-implement`
+- Primary entry points: `oat-project-new`, `oat-project-quick-start`, `oat-project-lite`, `oat-project-import-plan`, `oat-project-implement`
 
 ## Lifecycle Map
 
@@ -42,6 +42,10 @@ flowchart LR
   DOC --> C["Complete"]
 ```
 
+This map shows the spec-driven default. The quick, lite, import, and capture
+lanes each skip part of it — see [Lane diagrams](#lane-diagrams) below. Lite in
+particular has no discovery, spec, or design step at all.
+
 ## Post-implementation flow
 
 Implementation closeout has one authoritative order:
@@ -73,6 +77,37 @@ After implementation closeout finishes:
    - After revision tasks complete, state returns to `pr_open`
 5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt
 
+### Project-recap gate (non-lite)
+
+The final-closeout orchestrator owns one project-recap gate. It runs after the
+final code review has passed and after any configured pre-approval summary and
+documentation steps, but before final HiLL approval. It neither replaces nor
+repeats the final review, and the stored order of the other pre-approval steps
+is preserved.
+
+Recap intent resolves through `oat-explainer-kit`. A fresh `project-recap`
+manifest for the current completed implementation is reused rather than
+regenerated — fresh means it names recipe `project-recap`, belongs to this
+project, has a terminal outcome, and its recorded source hashes match the
+current approved inputs. A present-but-incomplete, wrong-recipe, or stale
+manifest does not qualify.
+
+Recap outcomes are reported, not blocking: `failed` and `built-not-durable` are
+recorded as warnings and never block final approval, completion reporting, or
+later PR steps. The selected or attempted outcome and run path are included in
+the implementation completion report, and `summary.md` carries a single
+`Explainer Outcome` section when it exists.
+
+**Lite skips this gate entirely.** Lite sets `PROJECT_RECAP_REACHABLE=false` and
+does not resolve recap intent, inspect recap runs, invoke `oat-explainer-kit`,
+or run the terminal-outcome guard. It proceeds from the required reviews through
+its stored optional steps to `pr` and sequence completion.
+
+Lite mode collapses the default pre-approval sequence to PR creation only.
+`oat-project-pr-final` builds the body directly from the lite plan and
+`implementation.md`; summary and documentation remain explicit lite opt-ins,
+and retro is not added to the lite closeout sequence.
+
 ### Completion archive behavior
 
 On completion, OAT treats archive handling as an explicit closeout choice:
@@ -167,7 +202,9 @@ When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter
 ### Phase-review setup during planning
 
 Spec-driven, quick, and import planning run one shared setup after stable phase
-IDs exist and before the plan artifact review. The target probe qualifies only
+IDs exist and before the plan artifact review. Lite omits this planning-time
+setup and prompt, while its built-in implementation phase and final reviews
+remain required. The target probe qualifies only
 an explicitly configured, enabled, and available review target, then offers all
 phases, selected phases, or disabled. Existing explicit
 `oat_phase_review_gate` values are preserved unchanged without re-prompting.
@@ -214,6 +251,13 @@ See [Implementation Execution](implementation-execution.md) for the full executi
 4. `oat-project-review-provide` / `oat-project-pr-final`
 5. Optional `oat-project-promote-spec-driven` to backfill spec-driven lifecycle artifacts in-place
 
+### Lite lane diagram
+
+1. `oat-project-lite` runs one batched interview, authors a single-phase `plan.md` with validation criteria, and pauses once for approval
+2. Implement: `oat-project-implement` runs the single phase without HiLL checkpoint prompts
+3. Pass the mandatory final review, then route directly to `oat-project-pr-final`
+4. Optional `oat project promote <project-path> --to quick` when the work no longer fits one sitting
+
 ### Import lane diagram
 
 1. `oat-project-import-plan` (checks inherited git state before import scaffolding so sync-generated or unrelated dirty files do not silently roll into project bookkeeping)
@@ -269,6 +313,75 @@ still read as compatibility capped-policy input, but new quick-start selections
 should use the dispatch-policy names, including explicit `Uncapped` and
 `Inherit Host Defaults`.
 
+### Lite lane
+
+```mermaid
+flowchart LR
+  L["Lite interview\n(one batched round)"] --> P["Single-phase plan\n(one approval)"]
+  P --> I["Implement (oat-project-implement)"]
+  I --> R["Final review"] --> PR["PR (default closeout)"]
+  P -->|Scope grows| Q["Promote to Quick"]
+```
+
+Lite keeps planning and validation in `plan.md`. The interview selects a
+`minimal`, `product`, `technical`, or `both` content shape and records the
+rationale. Product Behavior is required for user-visible changes; Technical
+Design is required for cross-module, data/state-format, or consumed-contract
+changes. It has no separate discovery, spec, or design artifact, skips
+implementation HiLL prompts, and routes a passed final review directly to PR
+creation. Summary and documentation run only when enabled through the
+lite-specific post-implementation sequence.
+
+Each task chooses evidence proportionate to its risk instead of requiring one
+test-first recipe. Behavioral changes need a proof that fails without the
+change; refactors default to characterization-first when existing coverage is
+insufficient; documentation-only work may use formatting, link, spelling, or
+build checks. UI changes require visual proof. In autonomous runs, available
+computer-use capability performs that proof; otherwise execution stops at an
+explicit proof boundary.
+
+### Promoting a lite project to quick
+
+When lite work outgrows one sitting, `oat project promote <project-path> --to quick`
+converts it in place. Each artifact has a different fate: the authored lite plan
+is **moved** to `references/lite-plan.md`, a new `discovery.md` is **derived**
+from its five core sections plus any adaptive Product Behavior and Technical
+Design, a **fresh** quick template takes over the `plan.md` path, and `state.md`
+is **rewritten** to quick mode.
+
+```mermaid
+flowchart LR
+  subgraph Before
+    LPLAN["plan.md\nfive core sections plus adaptive\nProduct Behavior / Technical Design"]
+    LSTATE["state.md\noat_workflow_mode: lite"]
+  end
+
+  CMD["oat project promote\n--to quick"]
+
+  subgraph After
+    DISC["discovery.md\nderived from the lite plan\noat_ready_for: oat-project-quick-start"]
+    REF["references/lite-plan.md\noriginal lite plan, preserved"]
+    QPLAN["plan.md\nfresh quick-start template"]
+    QSTATE["state.md\noat_workflow_mode: quick\noat_phase: discovery (complete)\noat_ready_for: oat-project-quick-start"]
+  end
+
+  LPLAN --> CMD
+  LSTATE --> CMD
+  CMD -->|derive| DISC
+  CMD -->|move| REF
+  CMD -->|scaffold| QPLAN
+  CMD -->|rewrite| QSTATE
+```
+
+The project slug, directory, and branch are untouched, so history and any open
+work continue uninterrupted. `oat_ready_for` is stamped on **both** `discovery.md`
+and `state.md`; the quick-start recommender reads artifact readiness, so
+consumers must preserve both. Promotion refuses rather than half-applying: a
+non-lite project, an existing `references/lite-plan.md`, invalid authored
+sections, an unresolved scope, or an unreadable template each return a stable
+categorical `reason` and exit non-zero. See
+[CLI Reference](../../reference/cli-reference.md) for the full refusal contract.
+
 ### Import lane
 
 ```mermaid
@@ -304,6 +417,10 @@ Quick lane progression:
 
 `discovery.md` -> [`design.md` (optional lightweight)] -> `plan.md` -> `implementation.md`
 
+Lite lane progression:
+
+`plan.md` -> `implementation.md` -> `pr/*.md` (`summary.md` and documentation are opt-in)
+
 Import lane progression:
 
 `references/imported-plan.md` -> `plan.md` -> `implementation.md` (`spec.md`/`design.md` optional)
@@ -360,15 +477,15 @@ actionable `oat pjm init` stop instead of scaffolding implicitly. See
 
 ### Seeding a new project from a brainstorm
 
-When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and a mode (`quick` vs `spec-driven`) with the user, runs `oat project new <slug> --mode <mode>` to scaffold the project, and writes the new project's `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, Open Questions. It writes `discovery.md` only (never a partial `design.md`), so the design phase keeps its full collaborative cadence and consumes the brainstorm's architectural intent from discovery's Solution Space and Chosen Direction sections during approach reaffirmation. The dispatcher stops with a pointer to `oat-project-quick-start` or `oat-project-design` — it deliberately does not auto-chain into the next phase, so the user makes that transition consciously.
+When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and one of three modes: `lite`, `quick`, or `spec-driven`. For Quick and Spec-Driven projects, it runs `oat project new <slug> --mode <mode>` and writes `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, and Open Questions. It writes only `discovery.md` (never a partial `design.md`), then points to `oat-project-quick-start` or `oat-project-design` without auto-chaining. For Lite projects, it instead seeds the five sections in `plan.md`, leaves `discovery.md` and `design.md` absent, and points to `oat-project-lite`.
 
-This is a parallel entry path into the Spec-Driven and Quick lanes, not a new lane: the resulting project follows the normal lane it was scaffolded into. The brainstorm-as-seed step is what changes — the user arrives at `oat-project-quick-start` (or `oat-project-design`) with discovery already populated rather than starting from a blank discovery template.
+This is a parallel entry path into all three lanes, not a new lane. Quick and Spec-Driven users arrive at `oat-project-quick-start` or `oat-project-design` with discovery already populated; Lite users arrive at `oat-project-lite` with the single-phase plan already seeded.
 
 ### Folding back into an active project
 
 When `oat-brainstorm` fires while a project is active, it offers a 3-way picker before any pack-filtered destination shows up:
 
-- **Related to the project** → fold the synthesized brainstorming content back into the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`), commit immediately, and print a handoff prompt for the right plan-authoring skill (`oat-project-plan` for spec-driven, `oat-project-quick-start` for quick, `oat-project-revise` when an open PR exists). The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
+- **Related to the project** → for Lite, fold the synthesis into `plan.md` immediately above `## Phase 1` and hand off to `oat-project-lite`; for Quick and Spec-Driven, use the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`) and hand off to `oat-project-quick-start` or `oat-project-plan`. Any mode with an open PR hands off to `oat-project-revise`. The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
 - **Independent of the project** → the active project is acknowledged but doesn't constrain the picker; brainstorm routes through its standard pack-filtered terminal-state options (new project, backlog item, idea, doc-to-path, inline).
 - **Related but supplementary** → write a brainstorming reference file at `.oat/projects/<scope>/<project>/brainstorming/YYYY-MM-DD-<topic>.md`, alongside `pr/` and `reviews/`. No lifecycle artifact is touched.
 

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: