@open-agent-toolkit/cli 0.2.66 → 0.2.68

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.66"
+  "oatVersion": "0.2.68"
 }

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

@@ -93,7 +93,7 @@ Common keys in `.oat/config.json`:
 - `git.defaultBranch` — base branch fallback for PR workflows
 - `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership
 - `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
-- `documentation.instructionPointerExcludes` — a JSON array of repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip by default (see [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees)). `oat config set` takes the list as one comma-separated value (`"vendor/generated,apps/oat-docs/docs"`) and stores it as an array of repository-relative POSIX paths, trimmed and de-duplicated; an empty value clears the key, and `oat config unset documentation.instructionPointerExcludes` removes it. An entry that could never exclude anything — an absolute path, or one escaping the repository with `..` — is rejected with exit code `1` rather than stored. A structurally malformed value already on disk (a non-array, or an empty or non-string entry) is rejected with exit code `2` and a repair message, and `oat config set` can still replace it. Entries that are well formed but cannot exclude anything — among them absolute paths, paths escaping the repository, paths that match no directory (matching is case-sensitive), and the unexcludable `.oat/repo` carve-in root — never abort the command; they are reported as warnings and are not counted as protection. Warnings go to stderr in human mode and to the `exclusionWarnings` field under `--json`
+- `documentation.instructionPointerExcludes` — a JSON array of repository-relative directories that `oat instructions sync` and `oat instructions validate` must not treat as pointer sites, additive to the documentation content root they already skip by default (see [Instruction Sync](../provider-sync/instruction-sync.md#documentation-trees)). `oat config set` takes the list as one comma-separated value (`"vendor/generated,apps/oat-docs/docs"`) and stores it as an array of repository-relative POSIX paths, trimmed and de-duplicated; an empty value clears the key, and `oat config unset documentation.instructionPointerExcludes` removes it. An entry that could never exclude anything — an absolute path, or one escaping the repository with `..` — is rejected with exit code `1` rather than stored. A structurally malformed value already on disk (a non-array, or an empty or non-string entry) is rejected with exit code `2` and a repair message, and `oat config set` can still replace it. Entries that are well formed but cannot exclude anything — among them absolute paths, paths escaping the repository, paths that match no directory (matching is case-sensitive, and the warning names the on-disk spelling when the path differs only in case), paths that resolve elsewhere through a symlink (the warning names the resolved target instead of blaming case-sensitivity), and the unexcludable `.oat/repo` carve-in root — never abort the command; they are reported as warnings and are not counted as protection. Warnings go to stderr in human mode and to the `exclusionWarnings` field under `--json`
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
 - `archive.s3Uri` — base S3 archive prefix
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
@@ -274,6 +274,19 @@ packaged `assets/` directory next to the installed CLI. Setting a non-empty
   unset the override, never to rebuild or reinstall the CLI; a packaged-bundle
   failure keeps the rebuild/reinstall guidance. A directory that exists but
   cannot be read reports the underlying error code.
+- The published npm tarball is held to the same seven-directory shape. The
+  CLI's public-package contract names a concrete file under each of the seven
+  directories, and release validation requires each one in the build workspace
+  and again in the packed tarball. The tarball check is the stronger of the two,
+  because a path can exist in the workspace and still never reach the tarball —
+  an empty directory that `npm pack` drops, or a `files`/symlink exclusion. So a
+  published package cannot ship a bundle whose top-level shape would fail
+  `validateBundleStructure`. That is a narrower promise than the exit-2 list
+  above: release validation does not check bundle metadata beyond its presence,
+  so a malformed or version-mismatched `bundle-metadata.json` is not covered.
+  The regression evidence is the negative pack control in
+  `packages/cli/src/release/public-package-contract.test.ts`:
+  `fails release validation when a required bundle directory is empty in the tarball`.
 - Produce a matching bundle with `bash packages/cli/scripts/bundle-assets.sh`
   while `OAT_ASSETS_DIR` points at the target directory (the script already
   honors the variable as its destination).

package/assets/docs/cli-utilities/project-log.md

@@ -77,8 +77,10 @@ Two optional flags let an interrupted append be replayed safely:
 
 - `--idempotency-key <key>` — skip the append when an existing entry body
   already carries `key`, reporting `already-appended` instead of writing a
-  duplicate. The key must appear in `--body`, since that is how a replay
-  recognizes the entry it already wrote.
+  duplicate. The key must appear in `--body` as its own whitespace-delimited
+  word, since that is how a replay recognizes the entry it already wrote; a key
+  glued to varying text such as a timestamp never matches its earlier self.
+  Deduplication does not require `--commit`.
 - `--commit` — stage and commit the log after appending, retrying a bounded
   three attempts when the failure is a transient `.git/index.lock`.
 
@@ -101,6 +103,14 @@ instead.
 
 Run `oat project log append --help` for the complete entry contract.
 
+Bodies may use line feeds or CRLF line endings. A CRLF body is accepted and
+stored normalized to line feeds, and the result then carries
+`normalizedLineEndings: true`, so the bytes on disk are known to differ from the
+bytes passed. A lone carriage return, U+2028, or U+2029 anywhere in a body — including
+at its very start or end — is refused, because those are the terminators the
+log's readers do not all agree about. Structural entries take one line and
+accept no line terminator at all.
+
 ## Automatic workflow integration
 
 When project logging is enabled, OAT lifecycle surfaces append structural
@@ -149,6 +159,25 @@ oat project log check --project .oat/projects/shared/example --json
 entry counts by class, type, and scope; the last entry date; and invalid
 hand-written headings. It reads only `project-log.md`.
 
+It also reports whether the log carries a completion seal:
+
+- `sealed`: `true` once the log holds a structural entry whose producer is
+  `oat-project-complete` and whose ref is `seal`. Both halves are required — a
+  `seal` ref from another producer is an ordinary entry.
+- `seal`: `null` when unsealed, otherwise the first seal's `heading` and
+  `date`, whether it is `keyed`, and the `count` of seal entries. A `count`
+  above one is a log sealed twice before the seal append became idempotent.
+
+`status` keeps its `ok` / `absent` / `synthesis_pending` values on a sealed log;
+sealing is reported alongside the status, not as a status value. The one
+additional status is `ambiguous`: a `##` heading, or a dated `###` entry
+heading, starts a line after a lone carriage return, U+2028, or U+2029 rather
+than a line feed, so the log's structure can be read two ways; or a seal is
+physically present outside the parseable `## Entries` region. `check` then
+exits 1 and reports an `ambiguity` reason instead of a clean verdict, every
+writing command (`append`, `synthesize`, `rollup`) refuses the same file, and
+the lifecycle skills stop rather than treat the log as empty.
+
 Use `--require-synthesis` to exit with status 1 while synthesis is pending:
 
 ```bash
@@ -156,7 +185,8 @@ oat project log check --require-synthesis
 ```
 
 Without that flag, normal `absent`, `ok`, and `synthesis_pending` results exit
-successfully so lifecycle skills can decide whether to warn or enforce.
+successfully so lifecycle skills can decide whether to warn or enforce;
+`ambiguous` always exits 1.
 
 ## Complete the synthesis
 
@@ -201,15 +231,44 @@ deduplicate by date and area. The command is idempotent.
 
 The structured result contains:
 
-- `status`: `ok` or `failed`
+- `status`: `ok`, `failed`, or `ambiguous`
 - `summarySection`: `written` or `updated`
 - `ledgerOutcome`: `appended`, `deduplicated`, `skipped_permitted`, or `failed`
 - `entriesRolledUp`: number of log entries written to the summary section
 
+An `ambiguous` result carries only `status` and an `ambiguity` reason, and exits
+1: the log's structure has two readings, so no count would mean anything and
+neither `summary.md` nor the ledger is written. The other fields are absent
+rather than zeroed, because `entriesRolledUp: 0` for an unreadable log is
+indistinguishable from the same result for an empty one.
+
 `skipped_permitted` means the default repository reference layer is absent and
 no ledger path was explicitly configured; `status` remains `ok`. An explicitly
 configured ledger write failure returns `status: "failed"`. Completion must not
 seal or archive a project with entries until roll-up reports `status: "ok"`.
 
+## The completion seal
+
+The seal is the last entry a project log may ever receive, and `append`
+enforces that rather than leaving it to convention:
+
+- Replaying the seal reports `already-appended` and leaves exactly one seal
+  entry. This holds for a seal carrying the completion skill's
+  `oat-seal:<project>` key and for an unkeyed seal written before that
+  convention, which is recognized by its heading instead.
+- Every append carrying **new** content is refused with `status: "sealed"` and a
+  non-zero exit, naming the seal that closed the log.
+- A replay that `--idempotency-key` recognizes as its own earlier entry is the
+  one exception: it reports `already-appended` and exits 0 even on a sealed log.
+  Nothing is appended — the entry it finds necessarily predates the seal — so
+  the seal stays the final entry. This is what keeps a gate
+  partial-finalization receipt replayable after the project is completed. The
+  key matches a whole word in an existing entry body, so an unrelated append
+  whose key happens to occur in some earlier entry is reported the same way
+  and likewise writes nothing.
+
+A resumed completion therefore reads `sealed` from `check` and skips the
+roll-up and the seal instead of duplicating them.
+
 `rollup` requires an existing `summary.md`; summary authoring remains the
 responsibility of the project summary workflow.

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`), and
-the named-file `test:release` set. Steps 5 and 6 are the version-lockstep
+`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
 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.
 
@@ -73,8 +73,12 @@ checkout with neither `origin/main` nor `main` skips the whole gate (CI uses
 `fetch-depth: 0`). Test files under `packages/cli/src/` count as publishable
 changes for this gate.
 
-CI runs neither `pnpm lint` nor `pnpm format` — run both whenever a change
-touches `tools/smoke` or `.agents/skills`, since nothing else covers them.
+CI runs neither `pnpm lint` nor `pnpm format`. `pnpm check` now covers the
+formatting of `.agents/skills/**`, `apps/oat-docs/docs`, and `tools/smoke`
+through `format:root`, but `pnpm lint`'s root `oxlint` pass over `tools/smoke`
+and `.agents/skills`, and `packages/control-plane`'s `format` (it defines no
+`check` script), still run in no CI gate — run both whenever a change touches
+those paths.
 For narrower changes, use package-specific checks when possible, but do not
 merge without passing the relevant workspace gates.
 

package/assets/docs/contributing/skills.md

@@ -203,15 +203,19 @@ resolution. `resolveSkillVersion` in
 `packages/cli/src/commands/shared/frontmatter.ts` owns that order, so the
 runtime helper and the validators cannot disagree.
 
-The top-level `version` field remains supported as a deprecated alias. Every
-bundled skill now declares `metadata.version` and carries no top-level
-`version`, so `pnpm oat:validate-skills` reports no alias warnings on the
-bundled tree. The alias is retained for third-party skills installed from
-packs, which may still carry it; it retires on the schedule recorded in
-`DR-260908-bundled-skills-declare` — the warning becomes an error in the first
-release after 0.2.65 that changes the validator, and the resolver's top-level
-read is removed one release after that error has produced no findings on the
-bundled tree.
+The top-level `version` field remains supported as a deprecated alias, and a
+skill that declares it is now reported as an **error**. Every bundled skill
+declares `metadata.version` and carries no top-level `version`, so
+`pnpm oat:validate-skills` reports no alias findings on the bundled tree. The
+alias is still read for third-party skills installed from packs, which may
+carry it; it retires on the schedule recorded in
+`DR-260908-bundled-skills-declare`. Step 1 of that schedule — promoting the
+alias finding from a warning to an error — ships in the first release after
+0.2.65 that changes the validator. Step 2 removes the resolver's top-level read
+one release after that error has produced no findings on the bundled tree; it
+is tracked by `BL-260908-remove-the-top-level-skill` and must account for the
+canonical agent roles, which the bump gate now enforces while they still
+declare the top-level field.
 
 A skill that carries both fields with different values is a conflict. The
 resolver reports the `metadata.version` value together with the conflict, and
@@ -220,7 +224,7 @@ than silently picking one, and canonical role resolution treats the identity as
 invalid. The runtime version readers still return the `metadata.version` value,
 so an installed-versus-bundled comparison keeps working while the conflict is
 being fixed. Carrying both with the _same_ value resolves without a conflict and
-without an alias warning, because `metadata.version` wins. A bundled skill must
+without an alias finding, because `metadata.version` wins. A bundled skill must
 still carry `metadata.version` alone: the corpus sweep in
 `packages/cli/src/validation/skills.test.ts` fails on any column-0 `version:`
 line under `.agents/skills`, which is the only check that catches the
@@ -228,16 +232,24 @@ same-value case.
 
 ### The version is gated
 
-Changing any canonical skill's `SKILL.md` requires bumping its frontmatter
-version in the same PR — one bump per changed skill in the final PR diff,
-even if the skill was edited multiple times on the branch. The gate reads the
-resolved version, so it enforces the bump whether the skill declares
+Changing any bundled file of a canonical skill — anything under
+`.agents/skills/<name>/` except `tests/`, because `tests/` is the one subtree
+the bundle strips — requires bumping that skill's `metadata.version` in the
+same PR, one bump per changed skill in the final PR diff, even if the skill was
+edited multiple times on the branch. A change to a skill's `scripts/` or
+`references/` therefore needs the bump just as an edit to `SKILL.md` does: both
+ship to every `oat tools install` consumer. Changing a canonical agent role
+under `.agents/agents/*.md` requires bumping that file's top-level `version:`;
+agent roles deliberately keep the top-level field, so the gate accepts either
+declaration shape and never demands `metadata.version` of them. The gate reads
+the resolved version, so it enforces the bump whether the file declares
 `metadata.version` or the top-level alias. The rule is enforced by
 `pnpm run check:skill-bumps`, which runs locally (root `AGENTS.md` Definition
 of Done) and in CI; a changed skill whose version matches `origin/main` fails
-the gate. The deprecation warning above is deliberately not part of that gate:
-`check:skill-bumps` fails on any finding it receives, so an alias warning
-routed through it would fail every changed skill that still carried one.
+the gate. The alias finding above is deliberately not part of that gate:
+`check:skill-bumps` fails on any finding it receives regardless of severity, so
+an alias finding routed through it would fail every changed skill that still
+carried one.
 
 ## Practical Authoring Flow
 

package/assets/docs/docs-tooling/commands.md

@@ -132,11 +132,13 @@ Key behavior:
 - treats explicitly supplied `--docs-dir` / `--output` paths as overrides resolved from the current directory
 - fails with exit code `2` before generating or writing anything when an omitted path has no non-empty `documentation.root` to resolve against, or when the configured root is not a directory
 - refuses unsafe output targets with exit code `1` before generation, for derived and explicit paths alike, comparing symlink-resolved paths: inside the docs directory it indexes, equal to `documentation.config`, or ending in `.yml` / `.yaml` in any case. A derived output whose existing file lacks the `AUTOGENERATED` header is refused too; naming that path with `--output` overwrites it explicitly. A refused target is an actionable flag error (`1`); unusable path configuration is a separate condition and exits `2`, so scripts can branch on the two
+- refuses a symlink chain that exceeds its own 32-hop cap, naming the path you supplied or the CLI derived rather than an intermediate link, and addressing the flag that owns it: an unusable **output** chain names `--output` and exits `1`; an unusable **docs directory** chain names `--docs-dir` and, when the directory was derived from `documentation.root` rather than passed explicitly, also names the `oat config set documentation.root <path>` repair and exits `2` as unusable path configuration. That cap governs the dangling links the command walks itself; a chain the operating system refuses first surfaces as its own `ELOOP` error with exit `1`, which is what a too-deep chain reports on a platform whose own limit is 32 or lower
 - writes configuration only for the Fumadocs manifest transition — recording the manifest it just wrote inside `documentation.root` in `documentation.index`, when `documentation.tooling` is `fumadocs` or the config declares neither `tooling` nor `config`. MkDocs configurations are never written, and `documentation.root` and `documentation.config` are never modified
 - prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
 - should be freshness-checked against authored `docs/**/index.md` `## Contents` maps before treating it as navigation evidence
 - sorting: `index.md` first, then directories before files, then lexical
-- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`
+- reports the derived docs directory in human output and as `docsDir` / `docsDirSource` under `--json`, alongside `excludes` — the effective exclusion list, `documentation.excludes` merged with the `--exclude` flags exactly as it was handed to the generator
+- says where to look when a manifest is empty rather than reporting a bare `0 entries`: which exclusion patterns were active, or that the docs directory held no indexable pages. The wording is observational — the command reports indexed entries, not pattern matches, so it names the exclusions without asserting they are the cause. An empty manifest is a report, not a failure — the file is still written, so a stale index is never left behind, and the command still exits `0`
 - omits pages matching the exclusion list. Nothing is excluded by default; once listed, non-page Markdown such as `CLAUDE.md` or `AGENTS.md` stops reaching the manifest. Patterns come from `documentation.excludes` in `.oat/config.json` and from repeated `--exclude` flags, and the flags **extend** the configured list rather than replacing it. A directory left empty by exclusion emits no heading, and an empty list produces byte-identical output to no exclusions at all
 
 Supported flags:

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -95,8 +95,8 @@ the manifest.
 
 - `missing-additive` — active, supported, no manifest entry, nothing at the expected path: the only true projection gap
 - `removed` — a manifest entry exists but the provider file is gone
-- `modified` — a manifest entry exists and the view no longer agrees with what the last sync recorded, or its version has fallen behind canonical. A `copy` view also reaches this class through the known limitation below, where the difference may be nothing but the generated banner
-- `in-sync` — a symlinked, collection-aliased, or natively read view _is_ the canonical file; a `copy` view matches the content recorded at its last sync
+- `modified` — a manifest entry exists and the view no longer agrees with what the last sync recorded, or its version has fallen behind canonical
+- `in-sync` — a symlinked, collection-aliased, or natively read view _is_ the canonical file; a `copy` view matches the content recorded at its last sync. A managed directory copy is compared with its OAT-managed banner and its `.oat-generated` sentinel excluded, so a freshly synced copy reads `in_sync` rather than drifted (owned by `skill-view-convergence.integration.test.ts`, "converges a copy-strategy skill directory")
 - `untracked` — something exists at the expected path that no manifest entry tracks; stray detection skips provider entries whose name matches a canonical entry, so `oat status` does not report it as a stray and reports the untracked projection as `missing` instead
 - `unverified` — the view's state is unknown: either a manifest entry arrived with no drift observation, or reading that one view failed and the row carries the redacted reason
 - `inactive`, `unsupported`, `excluded` — no projection is expected in this scope, so none of them is reported as missing
@@ -173,22 +173,6 @@ declared values and says the comparison was skipped, so the ambiguity is
 visible rather than silently resolved. When the resolver's answer happens to
 agree with canonical, nothing is withheld and the detail says so instead.
 
-### Known limitation: copy-strategy skill views
-
-A `copy` skill view is reported `modified` immediately after a successful sync,
-and stays that way. The engine writes an OAT-managed banner into the copied
-`SKILL.md` and an `.oat-generated` sentinel beside it, and neither is accounted
-for in the manifest hash, so `oat status` reports `drifted:modified` and every
-later `oat sync --dry-run` plans another `update_copy`. Because no sync clears
-that state, `oat tools info` prints no repair line when a `modified` copy's
-version still matches canonical.
-
-That suppression is a conservative heuristic rather than a proof: equal versions
-do not establish equal bodies, so an edit to the canonical source or to the copy
-that kept the version reaches the same branch, and a sync _would_ repair that
-one. The class detail says so and names the concrete scope command to run if you
-know either side was edited. Tracked as `BL-260908-make-copy-strategy-skill`.
-
 ## Stray adoption
 
 `oat init` and `oat status` can offer adoption of unmanaged provider entries into canonical `.agents`.

package/assets/docs/provider-sync/scope-and-surface.md

@@ -109,8 +109,9 @@ child accepted by the native route that later returns `BLOCKED` are not
 role-selection rejection and do not permit fallback.
 
 Project workflows construct and redact the complete dispatch payload before
-the native call, then persist its accepted or `blocked-before-start` result
-immediately under the active project's `dispatch/` directory. The generic
+the native call, then record its accepted or `blocked-before-start` result in
+the project's run record; persisting it under the project's `dispatch/`
+directory is optional and off by default. The generic
 record remains provider-neutral. OAT-specific canonical role, rejection,
 fallback, and runtime facts live only under its `oat` namespace. A qualifying
 fallback is a fresh request that preserves exact target and controls and is

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

@@ -153,7 +153,7 @@ Notable commands introduced in the current CLI surface:
 - `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 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).
 - `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.

package/assets/docs/workflows/projects/evidence-layers.md

@@ -75,9 +75,12 @@ This layer maps to Dispatch Report V1 and its provenance record; see the
 [Dispatch Report V1 / producer provenance](dispatch-ceiling.md#dispatch-report-v1-and-producer-provenance)
 section.
 
-For project-aware work, OAT persists this native dispatch lineage as one
-generic record per request under the project's `dispatch/` directory. The
-generic snake-case fields remain authoritative. A namespaced `oat` block adds
+For project-aware work, the calling workflow records each launch in its run
+record in `implementation.md` (request ID, `Dispatch:` stamp, launch status,
+terminal outcome). Persisting one generic record per request under the
+project's `dispatch/` directory with `oat project dispatch record` is optional
+and off by default; no lifecycle skill or command consumes those files. When a
+host opts in, the generic snake-case fields remain authoritative. A namespaced `oat` block adds
 only canonical-role identity, proven pre-start rejection, fallback linkage,
 and optional runtime observation. `DispatchReportV1` and the parseable
 `Dispatch:` compatibility stamp keep their existing byte shape.

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

@@ -73,9 +73,10 @@ The root does not implement phase tasks while an accepted phase launch owns
 that scope.
 
 Before a native launch, the root constructs and redacts the complete generic
-dispatch record and OAT role event. Immediately after the host returns, it runs
-`oat project dispatch record --project <project-path> --event-file - --json`
-with the accepted or `blocked-before-start` result. An accepted launch closes
+dispatch record and OAT role event. When the host returns, it writes the
+request ID, the `Dispatch:` stamp, and the accepted or `blocked-before-start`
+result into the run record in `implementation.md`; persisting a per-dispatch
+file with `oat project dispatch record` is optional and off by default. An accepted launch closes
 replacement. Only an explicit rejection proving no child started permits one
 fresh request that preserves the exact target and controls and is labeled as
 an approximation. Timeout, `BLOCKED`, refusal after acceptance, runtime

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

@@ -113,6 +113,15 @@ and retro is not added to the lite closeout sequence.
 On completion, OAT treats archive handling as an explicit closeout choice:
 
 - When archiving is selected, the local archive is written to `.oat/projects/archived/<project>/`.
+- Every completion that will actually archive — any durable (`shared` or
+  `synced`) project with archive selected — keeps the `activeProject` pointer
+  until the archive returns a validated receipt, and only then clears it.
+  `local` projects are never durable and never archive, so they clear the
+  pointer immediately, as does any completion that declines archive. An archive
+  failure therefore leaves the pointer intact and the completion directly
+  resumable. See
+  [Picking Up a Project](picking-up-projects.md#archive-contents) for the
+  post-archive resume and its manual recovery path.
 - 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
@@ -183,6 +192,14 @@ each finding as a `deferred advisory` warning and continues, a project with no l
 final completion summary, and a resumed completion whose log already
 carries a seal runs report-only and appends nothing.
 
+A resume detects that seal from `oat project log check`, which reports a
+`sealed` field, rather than by re-reading the log. The invariant is enforced in
+the CLI: replaying the seal reports `already-appended` and leaves exactly one
+seal entry; a replay recognized by its own idempotency key reports
+`already-appended` even on a sealed log (nothing is appended), and every
+append carrying new content is refused with `status: "sealed"` and a non-zero
+exit.
+
 Repositories that never adopted PJM skip the sweep with a one-line note. A
 missing planning surface degrades the sweep, never the closeout.
 

package/assets/docs/workflows/projects/orchestration-model.md

@@ -123,10 +123,12 @@ launch.
 ## Native Dispatch Lineage
 
 The launcher constructs and redacts the complete generic record plus the
-namespaced OAT role event before it calls the native host. Immediately after
-the host returns, the project adapter validates and persists the accepted or
-`blocked-before-start` state with `oat project dispatch record`. The command is
-a recorder only; it never launches a provider or changes selection authority.
+namespaced OAT role event before it calls the native host. When the host
+returns, the calling workflow writes the accepted or `blocked-before-start`
+state into its run record in `implementation.md`. Persisting a per-dispatch
+file with `oat project dispatch record` is optional and off by default; the
+command is a recorder only and never launches a provider or changes selection
+authority.
 
 An accepted handle owns the scope and closes replacement. One fresh fallback
 record is legal only when the native wrapper proves no child started, links the

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

@@ -99,6 +99,24 @@ If closeout is interrupted after terminal archive identity exists, rerun
 completion so it can resume from the completed ref and archive metadata. Do not
 use `pull` or `open` to recreate an active record or checkout.
 
+For a `shared` project, archive moves the project into
+`.oat/projects/archived/<project>/` and removes the source directory, while
+completion keeps the `activeProject` pointer until the receipt validates.
+Rerunning completion after an interruption between the archive and that clear
+recognizes exactly this state — the pointer names a source directory that no
+longer exists and the archive carries `oat_lifecycle: complete` plus the
+`Lifecycle complete; archived locally` phase marker — so it validates the
+discovered archive and clears the pointer without archiving a second time or
+sealing the project log again. An interruption before the archive leaves the
+source directory in place, so completion simply reruns from the start and skips
+the work it already finished.
+
+If the archive cannot be discovered — the source directory is gone and either
+no archived project or several match the name — completion stops and leaves the
+pointer untouched. Recover manually: locate the archive directory under
+`.oat/projects/archived/`, confirm `oat_lifecycle: complete` in its `state.md`,
+then clear the pointer with `oat config set activeProject ""`.
+
 ## Related
 
 - [Reviewing OAT PRs](reviewing-oat-prs.md)

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

@@ -72,9 +72,13 @@ Failure to publish a backlog item or issue does not invalidate a successfully wr
 
 Full repository audits use bounded read-only reconnaissance while the root
 agent retains classification, vetting, prioritization, cross-lane synthesis,
-and plan writing. Before launch, the caller loads the durable task classes and
-model-selection principles from `subagent-orchestration` plus exactly one
-active-provider selection reference.
+and plan writing. Plan writes never move below the caller's model class — a
+parallelized author runs on the caller's model and every plan is
+caller-reviewed before publication or wave composition; the
+`keeps external-plan writes on the caller's model class` case in
+`skills-bundled-docs-contract.test.ts` is the backstop. Before launch, the
+caller loads the durable task classes and model-selection principles from
+`subagent-orchestration` plus exactly one active-provider selection reference.
 
 The internal `oat-dispatch-subagents` skill then owns capability checks, live
 catalog intersection, exact route selection, launch acceptance, recovery, and

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.66",
-  "docs-config": "0.2.66",
-  "docs-theme": "0.2.66",
-  "docs-transforms": "0.2.66"
+  "cli": "0.2.68",
+  "docs-config": "0.2.68",
+  "docs-theme": "0.2.68",
+  "docs-transforms": "0.2.68"
 }