@open-agent-toolkit/cli 0.2.72 → 0.2.74

package/assets/agents/oat-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: oat-reviewer
-version: 1.2.4
+version: 1.2.5
 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
@@ -93,8 +93,9 @@ When delegation is eligible:
    Mechanical workers may execute checks and report exact output, but interpretation and policy judgment require stronger classes or stay with the root reviewer.
 
 5. The generic dispatch contract owns capability, catalog, model, effort, route, authorization, launch evidence, class-floor selection, and floor-satisfaction evidence. It applies active user and repository instructions, the active-provider reference, the live nested catalog, and the supplied policy/ceiling. Select an explicit target meeting the declared floor; never silently inherit the primary reviewer's model and never hard-code provider model names. Prefer a cheaper/faster worker only when the host reliably exposes that control and the target still satisfies the floor.
-6. Give each lane an exact scope and a compact return contract: coverage, checks performed, exact `file:line` evidence, gaps, and explicit uncertainty. Reports are advisory candidate observations, not accepted findings.
-7. Workers must not mutate files, emit final findings, assign severity, make validation decisions, write review artifacts or `StructuredFindings`, or otherwise write either output sink.
+6. When the selected lane worker is the canonical `recon-worker`, construct and validate its complete Assignment Gate envelope before launch: run, wave, and lane IDs; approved manifest wave mode; worker assignment mode; bounded objective; included and excluded scope; allowed and excluded inputs; source-read authority and read-only tools; sole write path; artifact kind, schema version, and closed output schema; enforcement; deadline; and escalation path. If the complete envelope cannot be constructed, do not launch the worker; record the attempt as not attempted or failed as appropriate and cover the lane inline. Other worker roles follow their own contracts.
+7. Give each lane an exact scope and a compact return contract: coverage, checks performed, exact `file:line` evidence, gaps, and explicit uncertainty. Reports are advisory candidate observations, not accepted findings.
+8. Workers must not mutate files, emit final findings, assign severity, make validation decisions, write review artifacts or `StructuredFindings`, or otherwise write either output sink.
 
 Lanes may share one homogeneous dispatch wave only when every existing dispatch axis, `task_class`, and `model_class_floor` match. Mixed task classes require separate records and waves. The one-level fan-out limit applies across all waves.
 

package/assets/agents/recon-worker.md

@@ -1,6 +1,6 @@
 ---
 name: recon-worker
-version: 1.0.0
+version: 1.0.1
 description: Executes one bounded recon packet assignment as a non-interactive leaf worker and writes exactly one declared artifact.
 tools: Read, Bash, Grep, Glob, Write, WebSearch, WebFetch
 color: cyan
@@ -12,12 +12,31 @@ You are a non-interactive recon leaf worker. Execute exactly one assignment in
 one declared mode: `map`, `gather`, `compile`, `verify`, `adversary`, `coverage`,
 or `reconcile`. No other mode is valid.
 
+The controller maps approved manifest waves to this closed vocabulary:
+
+| Manifest wave mode         | Worker assignment mode |
+| -------------------------- | ---------------------- |
+| `map`                      | `map`                  |
+| `gather`                   | `gather`               |
+| `compile`                  | `compile`              |
+| `semantic-verification`    | `verify`               |
+| `adversarial`              | `adversary`            |
+| `coverage`                 | `coverage`             |
+| `reconciliation`           | `reconcile`            |
+| `redundant-gather`         | `gather`               |
+| `redundant-verification`   | `verify`               |
+| `contradiction-resolution` | `adversary`            |
+
+Preserve the approved wave identity and target; never select or upgrade a
+route yourself.
+
 ## Assignment Gate
 
 Before work, require a complete envelope containing run, wave, and lane IDs;
-mode; bounded objective; included and excluded scope; allowed inputs; excluded
-inputs; source-read authority and read-only tools; sole write path; artifact
-kind and schema version; output schema; enforcement level; and deadline.
+the approved manifest wave mode; exactly one worker assignment mode; bounded
+objective; included and excluded scope; allowed inputs; excluded inputs;
+source-read authority and read-only tools; sole write path; artifact kind and
+schema version; output schema; enforcement level; and deadline.
 
 Reject the assignment if inputs overlap exclusions, source authority is
 missing, the write path is not unique and packet-contained, the schema is
@@ -70,6 +89,9 @@ reasoning, synthesis prose, or prior reviews.
 Consume only declared scope, questions, and provisional statements. Search for
 counterevidence, unsupported inference, incompatible interpretations, and
 missing alternatives. Do not read gathering or prior-review conclusions.
+When assigned a `contradiction-resolution` wave, seek discriminating evidence
+for that named contradiction; do not reconcile the ledger or decide which
+interpretation wins.
 
 ### `coverage`
 
@@ -86,14 +108,26 @@ the existing ledger in place.
 
 ## Output
 
-Write one JSON artifact matching the supplied schema. Include kind, schema
-version, identities, mode, outcome, honored inputs and exclusions, findings or
-dispositions, uncertainty, contradictions, gaps, safe diagnostics, and direct
-input references where applicable.
+Write one JSON artifact using only the supplied closed schema's fields. A
+`recon.raw-dossier` identifies its approved manifest wave with `waveId` and its
+closed worker assignment with `mode`; it also includes `laneId` and `outcome`.
+A `recon.review-result` identifies its approved lane with `reviewerLane` and its
+approved review discriminator with `reviewKind`. Include the remaining
+required identity, input, exclusion, finding or disposition, uncertainty,
+contradiction, gap, diagnostic, and direct-reference fields only as the
+supplied schema permits.
+
+Do not add a second mode field or any other unknown field. The controller
+validates `waveId` and `mode`, or `reviewerLane` and `reviewKind`, against the
+approved manifest wave before promoting the artifact.
 
 Return only the artifact path and compact outcome. Do not return source bodies,
 worker reasoning, or dossier contents to the controller.
 
+The controller and caller decide whether the evidence is sufficient. Never turn
+an assignment result into a downstream recommendation, architecture verdict, or
+final review conclusion.
+
 ## Critical Rules
 
 **ONE MODE. ONE ARTIFACT.** Perform only the assigned mode and write only its

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.72"
+  "oatVersion": "0.2.74"
 }

package/assets/docs/cli-utilities/configuration.md

@@ -177,8 +177,8 @@ table and template precedence.
 
 ### Explainer configuration
 
-The `oat-explainer-kit` adapter owns two typed config groups. Build and publish
-plumbing uses `explainers.*`; project lifecycle preferences use
+The `oat-explainer-kit` adapter resolves theme defaults from
+`explainers.defaults.*` and project lifecycle preferences from
 `workflow.explainers.*`.
 
 | Key                                    | Type                         | Stored scopes       | Default         |
@@ -187,12 +187,6 @@ plumbing uses `explainers.*`; project lifecycle preferences use
 | `explainers.defaults.palette`          | nullable string (deprecated) | local, shared, user | `null`          |
 | `explainers.defaults.visualProfile`    | nullable string (deprecated) | local, shared, user | `null`          |
 | `explainers.defaults.themeBundlePath`  | path                         | local, shared       | unset           |
-| `explainers.publish.provider`          | `s3-static`                  | shared              | unset           |
-| `explainers.publish.s3Uri`             | `s3://` URI                  | shared              | unset           |
-| `explainers.publish.publicBaseUrl`     | HTTPS URL                    | shared              | unset           |
-| `explainers.publish.awsRegion`         | non-empty string             | shared              | unset           |
-| `explainers.publish.awsProfile`        | non-empty string             | local, user         | unset           |
-| `explainers.publish.publicAccess`      | `public\|protected`          | shared              | `public`        |
 | `workflow.explainers.projectExplainer` | `always\|ask\|never`         | local, shared, user | `ask`           |
 | `workflow.explainers.projectRecap`     | `always\|ask\|never`         | local, shared, user | `ask`           |
 
@@ -220,38 +214,6 @@ advanced compatibility but emit deprecation warnings. When no source explicitly
 selects a theme, the core uses `clean-neutral` and records a visible fallback
 warning.
 
-Publishing remains build-only when `explainers.publish.provider` is unset.
-When it is `s3-static`, `s3Uri`, `publicBaseUrl`, and `awsRegion` are all
-required. `awsProfile` is optional; when absent, the standard AWS credential
-chain applies. Config never starts publishing by itself: lifecycle callers must
-still select publish durability explicitly, and publishing remains
-human-gated. Raw AWS credentials are not config keys.
-
-`publicAccess` declares whether published objects are expected to be reachable
-anonymously; it does not authorize publication and it does not change any
-bucket policy. It selects how publication is verified. The default `public`
-fetches every uploaded object over HTTPS and compares the returned bytes
-against the manifest hash. `protected` skips those anonymous fetches, verifies
-each object through authenticated S3 hashing instead, and records
-`skipped-protected` in the publish receipt. Because no anonymous fetch happens
-under `protected`, a mistyped `publicBaseUrl` is not detected at publish time:
-the advertised URLs are still written into the initiative catalog and receipt,
-and the catalog records `publicVerification: "skipped-by-policy"` so consumers
-can see the URLs were never exercised.
-
-### Explainer publication environment variables
-
-Two escape hatches are read from the process environment rather than from
-config, because both are machine-local operational overrides rather than
-project settings. Neither has a config key.
-
-| Variable                                         | Effect                                                                      | Default |
-| ------------------------------------------------ | --------------------------------------------------------------------------- | ------- |
-| `EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT`        | Permits a loopback, link-local, unique-local or RFC 1918 `publicBaseUrl`    | off     |
-| `EXPLAINER_KIT_SUPPRESS_ROOT_DIVERGENCE_WARNING` | Silences the advisory warning when the S3 key prefix and public path differ | off     |
-
-Both accept `1`, `true` or `on`.
-
 ### Bundled assets root (`OAT_ASSETS_DIR`)
 
 The CLI reads its bundled skills, agents, templates, and scripts from the
@@ -294,23 +256,8 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
 This is primarily a test-isolation and packaging seam; day-to-day use of the CLI
 does not need it.
 
-`EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT` disables an anti-SSRF control. Public
-verification issues an outbound GET against whatever `publicBaseUrl` names, so
-by default the connector refuses internal addresses — including the
-`169.254.169.254` instance-metadata endpoint. Enable it only for a genuinely
-internal mirror. When it is set and the root is in fact non-public, the run
-records `publicRootPolicy: "private-allowed"` in the publish receipt, so a
-publication made with the control disabled is distinguishable in durable
-evidence from one made without it. The policy is address-literal only: a
-hostname that resolves inward is not detected either way.
-
-`EXPLAINER_KIT_SUPPRESS_ROOT_DIVERGENCE_WARNING` only affects an advisory
-message. Divergent roots are never a publication failure — a CloudFront Origin
-Path deployment legitimately maps a bucket prefix to the distribution root — so
-this changes no validation outcome.
-
 See [Explainer Kit](../workflows/skills/explainer-kit.md) for recipes, artifact
-locations, lifecycle behavior, and durability.
+locations, lifecycle behavior, and archive/export behavior.
 
 Workflow gate objects are structured config and use their own command group
 instead of the scalar `oat config set` surface. See

package/assets/docs/cli-utilities/tool-packs.md

@@ -161,10 +161,9 @@ oat tools update --pack research --scope project
 The public explainer family also spans two packs:
 
 - `utility` owns `explainer-kit`, the destination-neutral core with its
-  contracts, recipes, themes, templates, render QA, durability verifier, and
-  optional publishing connector.
+  recipes, briefs, themes, templates, bundler, verifier, and recorder.
 - `workflows` owns `oat-explainer-kit`, the adapter that resolves OAT config,
-  project artifacts, output paths, and lifecycle intent.
+  approved project artifacts, output paths, and lifecycle intent.
 
 Install the core at user scope before using the adapter:
 
@@ -173,7 +172,8 @@ oat tools install utility --scope user
 oat tools install workflows
 ```
 
-The dependency is one-way: the adapter invokes the core, while the core remains
+The dependency is one-way: the adapter invokes the core's
+`bundle → host-agent authoring → verify → record` flow, while the core remains
 usable without OAT. The adapter checks the installed canonical core path and
 minimum compatible version before reading config or running. If the core is
 missing it fails closed with the utility install command; if it is too old it

package/assets/docs/contributing/code.md

@@ -56,8 +56,8 @@ pnpm build:docs               # builds docs site and its dependencies
 ```
 
 `pnpm test` is composite: it runs the workspace vitest suites, then
-`test:smoke` (`tools/smoke`), `test:skills` (`.agents/skills/*/tests`), the
-named-file `test:release` set, and last `test:scripts` (`scripts/worktree`). Steps 5 and 6 are the version-lockstep
+`test:smoke` (`tools/smoke`), `test:skills` (`.agents/skills/*/tests`), and last
+`test:scripts` (`scripts/worktree`). Steps 5 and 6 are the version-lockstep
 gates; they are in the local list because they previously ran only in CI and
 version-bump drift twice reached review with no local gate to surface it.
 

package/assets/docs/contributing/index.md

@@ -17,5 +17,4 @@ Use this section when you are changing OAT itself rather than consuming it as a
 - [Commit Conventions](commit-conventions.md) - Traceable commit patterns for project and docs work.
 - [Hooks and Safety](hooks-and-safety.md) - Safety and mutation contracts for provider-sync behavior.
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
-- [Verifying Explainer Kit](explainer-kit-verification.md) - Golden recap cases, real-Chromium evidence, fixture regeneration, and release validation.
 - [Verifying Cursor Pins](verifying-cursor-pins.md) - Runbook for probe-verifying a Cursor model pin before shipping it.

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

@@ -151,7 +151,7 @@ Notable commands introduced in the current CLI surface:
 - `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 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 file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete inventory 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. 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 (optional; no lifecycle skill requires it). 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. 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).

package/assets/docs/reference/troubleshooting.md

@@ -330,55 +330,32 @@ failure, which is intentional — you asked for a scope that does not exist here
 
 ## An Explainer Kit recap ends as `built-needs-review`
 
-`built-needs-review` means the required unattended visual-review chain did not
-reach a valid `pass`. The run retains available output for diagnosis, but OAT
-will not finalize, archive, attest, publish, or push it as a successful recap.
-Do not bypass the review gate by copying the package into a durable location.
+`built-needs-review` is a satisfied generation outcome. The explainer page and
+browser-free checks are complete, but the browser rung was unavailable or
+reported a visual issue that needs a human look. Lifecycle closeout can
+continue, and a fresh package that passes the complete package guard can be
+selected and archived.
 
 Inspect:
 
-1. `build-record.json` and `manifest.json` for the terminal outcome and warning.
-2. `qa/browser/` for all required mobile, tablet, and desktop PNG/metrics pairs.
-3. `qa/visual-review/attempt-*/request.json` and `result.json` for request
-   binding, critic disposition, and findings.
-4. `qa/visual-review/revision.json` when a correction was requested.
-5. Adapter logs for missing or invalid `browserSession`, `visualCritic`, or
-   correction-provider modules.
+1. `qa/result.json` for the selected browser rung, browser availability, and
+   visual findings.
+2. `manifest.json` for warnings, outcome, and the exact package inventory.
+3. `site/index.html` at 320, 768, and 1440 pixels when visual inspection is
+   available.
+4. Adapter logs for a browser launch or capture failure.
 
-Common causes include unavailable Chromium, a fixture or unbranded session,
-missing screenshots, invalid decoded PNG dimensions, runtime/capture identity
-drift, critic exceptions, evidence mutation, `fail`, and an unresolved
-correction. Fix the provider or artifact problem and rebuild the recap; partial
-evidence is diagnostic only.
-
-See
-[Explainer Provider Integration](../workflows/skills/explainer-kit-providers.md)
-for the trusted-session and critic contracts.
-
-## Explainer Kit resume fails with `E_APPROVAL_RESUME`
-
-Interactive resume is same-request only. Keep the opaque `ekrt2` token returned
-as `approval.resumeToken` outside the package and provide it as
-`reviewedSource.resumeToken` with the complete original request.
-
-The error is expected when:
-
-- the token is missing, malformed, or not `ekrt2`;
-- the configured output root or retained run root moved;
-- `run-request.json` or a retained set-plan record changed;
-- the current request differs in source binding, recipe, mode, theme, render
-  strategy, privacy, public URL, durability, or publish destination; or
-- the package contains a legacy `ekrt1` token.
-
-Do not edit retained files or weaken the current request to force a match.
-Restore the exact original request and package bytes. Legacy paused runs cannot
-be upgraded in place; restart them to receive an authenticated `ekrt2` token.
+If the page is acceptable, retain the outcome as-is; the manifest honestly
+records that visual review is still due. If it is not acceptable, fix the
+source or authoring issue and generate a new run. Do not mutate a recorded run
+package.
 
 ## Reference artifacts
 
 - `.oat/projects/<scope>/<project>/implementation.md`
 - `.oat/projects/<scope>/<project>/reviews/`
-- `.oat/projects/<scope>/<project>/explainers/<slug>/qa/`
+- `.oat/projects/<scope>/<project>/explainers/<slug>/manifest.json`
+- `.oat/projects/<scope>/<project>/explainers/<slug>/qa/result.json`
 - `packages/cli/src/commands/doctor/index.ts`
 - `packages/cli/src/commands/status/index.ts`
 - `packages/cli/src/commands/tools/shared/pack-inventory.ts`

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

@@ -101,8 +101,8 @@ different retention contracts:
 - A selected final `project-recap` is a durable completion record. Before a
   shared project is removed, archive copies the complete selected run to
   `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies its
-  immutable package hashes, and reports that tracked export path. Summary and
-  PR links use this export, never the gitignored local archive. Lifecycle
+  package inventory and hashes, and reports that tracked export path. Summary
+  and PR links use this export, never the gitignored local archive. Lifecycle
   callers identify the selected project-relative run with:
 
   ```bash
@@ -110,40 +110,22 @@ different retention contracts:
     --project-recap-run explainers/<recap-slug>
   ```
 
-The archive exports at most one selected recap package. It preserves structured
-failure outcomes and successful intermediates, rejects an existing dated
-destination, and requires the selected path to stay under the project's
-`explainers/` directory with a `project-recap` manifest. Verification covers
-the complete mode-aware package:
-
-- privacy-safe request and content approval;
-- fact-base JSON and Markdown;
-- the five immutable set-plan records and authored drafts;
-- declared author results and authored content;
-- resolved theme and every built artifact;
-- canonical mobile, tablet, and desktop screenshots;
-- paired `browser-evidence/v2` metrics with launched Chromium name, version,
-  and capture identity;
-- cohesion observations and each visual-review request/result; and
-- the bounded revision record when a correction occurred.
-
-Canonical object hashes identify normalized fact-base, theme, runtime, and
-capture objects; `manifest.immutableHashes` independently covers serialized file
-bytes. The archive requires one complete, internally consistent browser and
-review chain for a successful unattended recap. Missing, stale, forged,
-cross-record-mismatched, or tampered coverage fails before the active project is
-deleted.
-
-`built-needs-review` is a terminal review-gate outcome, not a non-durable
-success. Its partial evidence remains available for diagnosis, but it cannot be
-finalized, exported, attested, archived, or pushed. Review and rebuild the recap
-to a passing visual-review outcome first.
+The archive exports at most one selected recap package. It rejects an existing
+dated destination and requires the selected path to stay under the project's
+`explainers/` directory with a `project-recap` manifest. Verification checks
+the manifest's exact inventory, every declared file byte, the fact base and
+ledger, resolved theme, authored page, and QA result before deleting the active
+project.
+
+Both `built` and `built-needs-review` are complete, archivable outcomes.
+`built-needs-review` means the browser rung was unavailable or found an issue;
+the archive retains that visible human-review signal. `failed`, `incomplete`,
+stale, mismatched, or tampered packages fail the export guard.
 
 Local-scope projects are not archived through this export path. Their explainer
-packages inherit the local project's untracked posture and remain
-`built-not-durable` unless independent publish evidence exists. Non-project OAT
-explainer runs use `.oat/repo/reference/explainers/<slug>/`; direct core callers
-must provide their own explicit output root.
+packages remain local working artifacts. Non-project OAT explainer runs use
+`.oat/repo/reference/explainers/<slug>/`; direct core callers provide an
+explicit output root.
 
 ### Gate review frontmatter
 

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

@@ -79,24 +79,24 @@ After implementation closeout finishes:
 
 ### 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.
+The final-closeout orchestrator re-reads persisted recap intent after final
+review and configured pre-approval summary and documentation steps, but before
+final HiLL approval. A persisted skip suppresses manifest discovery and the
+entire generation flow. A persisted generate decision reuses a fresh satisfied
+package or invokes `oat-explainer-kit` § Generate.
+
+Fresh means the package identifies this project and recipe, has outcome `built`
+or `built-needs-review`, passes the complete package guard, and records source
+hashes for the current approved inputs. Wrong-project, wrong-recipe, stale,
+`failed`, and `incomplete` packages do not qualify.
+
+The flow bundles approved evidence, lets the host agent author one page,
+verifies it at the best available browser rung, and records the package.
+`built-needs-review` satisfies generation and does not block approval. In
+autonomy, an unsatisfied run is retried once; a second failure persists
+`skip/failed_attempt`, which closeout consumes without another bundle or
+authoring pass. Reports and `summary.md` preserve the actual outcome, run path,
+or skip reason.
 
 **Lite skips this gate entirely.** Lite sets `PROJECT_RECAP_REACHABLE=false` and
 does not resolve recap intent, inspect recap runs, invoke `oat-explainer-kit`,
@@ -125,7 +125,8 @@ On completion, OAT treats archive handling as an explicit closeout choice:
 - When archiving is disabled or declined, durable projects remain at their
   active path. Synced completion still finalizes and pushes the project ref,
   commits the discovery record as `complete`, retains the checkout and ref, and
-  attests a selected recap against the project-ref history.
+  keeps any recap governed by its manifest and package verification without a
+  separate closeout evidence push.
 - For a synced project, closeout first finalizes the project artifacts and
   pushes them to `refs/oat/projects/<project>`. Archive then requires a clean,
   fully pushed checkout; copies it without the `.git` pointer or `reviews/`;