@open-agent-toolkit/cli 0.2.59 → 0.2.63

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.63"
 }

package/assets/docs/cli-utilities/config-and-local-state.md

@@ -120,6 +120,7 @@ Use `oat config` for repo runtime config inspection and supported key mutation.
 
 - `oat config get <key>` - read one resolved config value
 - `oat config set <key> <value>` - update a supported shared or repo-local key
+- `oat config unset <key>` - remove a supported key from one surface, with the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. Pruning removes any parent object the removal empties, and the resolved value falls back to the next surface or the built-in default. A key the surface does not hold reports an already-unset outcome and exits 0; `--json` adds a `removed` boolean that distinguishes that no-op from a real removal. Five classes are refused with exit 1: unknown keys (including the uncatalogued `documentation.index`), lifecycle state (`activeProject`, `lastPausedProject`, cleared with `oat config set <key> ''`), pack intent (`tools.*`, removed with `oat tools remove --pack <pack> --scope project`), the aggregate read views `workflow.dispatchCeiling` and `workflow.dispatchCeiling.providers`, and environment-shadowed keys with nothing stored on the target surface. See [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags) for the full contract
 - `oat config list` - show the resolved command-surface values with source information
 - `oat config dump --json` - emit the full merged config payload with per-key source attribution, suitable for automation and debugging
 - `oat config describe` - list supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config

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

@@ -18,13 +18,13 @@ For the deep file-by-file reference, see:
 
 ## The five config surfaces
 
-| Surface                   | File                      | Typical contents                                                                                                                                      | Primary CLI surface                            |
-| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| Shared repo config        | `.oat/config.json`        | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, `archive.*`, `tools.*`, and shared `workflow.*` defaults | `oat config get/set/list/describe`, `oat gate` |
-| Repo-local config         | `.oat/config.local.json`  | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, repo-local `activeIdea`, and local `workflow.*` overrides        | `oat config get/set/list/describe`, `oat gate` |
-| User config               | `~/.oat/config.json`      | User-level state such as global `activeIdea` fallback and personal `workflow.*` defaults                                                              | `oat config describe`, `oat gate`              |
-| Project sync config       | `.oat/sync/config.json`   | Provider enablement, sync strategy, and repo-level known stray settings                                                                               | `oat providers set`, `oat config describe`     |
-| User provider sync config | `~/.oat/sync/config.json` | User sync strategy and personal known provider strays                                                                                                 | Provider-sync commands, `oat config describe`  |
+| Surface                   | File                      | Typical contents                                                                                                                                      | Primary CLI surface                                  |
+| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Shared repo config        | `.oat/config.json`        | Repo-wide non-sync settings such as `projects.root`, `git.defaultBranch`, `documentation.*`, `archive.*`, `tools.*`, and shared `workflow.*` defaults | `oat config get/set/unset/list/describe`, `oat gate` |
+| Repo-local config         | `.oat/config.local.json`  | Per-developer state for this checkout, such as `activeProject`, `lastPausedProject`, repo-local `activeIdea`, and local `workflow.*` overrides        | `oat config get/set/unset/list/describe`, `oat gate` |
+| User config               | `~/.oat/config.json`      | User-level state such as global `activeIdea` fallback and personal `workflow.*` defaults                                                              | `oat config get/set/unset/describe`, `oat gate`      |
+| Project sync config       | `.oat/sync/config.json`   | Provider enablement, sync strategy, and repo-level known stray settings                                                                               | `oat providers set`, `oat config describe`           |
+| User provider sync config | `~/.oat/sync/config.json` | User sync strategy and personal known provider strays                                                                                                 | Provider-sync commands, `oat config describe`        |
 
 The main split is:
 
@@ -51,6 +51,7 @@ What each command is for:
 - `oat config list` shows the currently resolved command-surface values for shared and repo-local keys.
 - `oat config get <key>` reads one supported key value.
 - `oat config set <key> <value>` updates supported shared or repo-local keys.
+- `oat config unset <key>` removes a supported key from one surface, using the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. The resolved value then falls back to the next surface down, or to the built-in default. A key the surface does not hold exits 0 as already-unset (`--json` adds a `removed` boolean to tell the two apart). Unknown keys, lifecycle state, `tools.*` pack intent, the `workflow.dispatchCeiling` aggregate read views, and environment-shadowed keys with nothing stored are refused with exit 1 — see [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags).
 - `oat config describe` shows the supported config catalog across shared repo, repo-local, user, and sync/provider surfaces.
 - `oat config describe <key>` shows file, scope, default, mutability, owning command, and description for one key.
 
@@ -91,6 +92,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.requireForProjectCompletion` — whether docs sync is a completion gate
 - `archive.s3Uri` — base S3 archive prefix
 - `archive.s3SyncOnComplete` — upload archived projects to S3 during completion
@@ -768,7 +770,7 @@ Workflow preferences resolve through three config surfaces, with `local > shared
 
 ### Setting preferences
 
-`oat config set` supports mutually exclusive surface flags for workflow keys:
+`oat config set` and `oat config unset` support the same mutually exclusive surface flags for workflow keys:
 
 ```bash
 # User-level: applies to all repos on this machine

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

@@ -71,6 +71,22 @@ oat project log append \
 Structural entries require `--structural`, `--producer`, `--ref`, and `--body`.
 Do not combine structural flags with judgment flags.
 
+### Idempotent append and commit
+
+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.
+- `--commit` — stage and commit the log after appending, retrying a bounded
+  three attempts when the failure is a transient `.git/index.lock`.
+
+Together they are the recovery entry point for a gate whose project-log
+finalization could not commit. See
+[Workflow Gates](./workflow-gates.md#project-log-finalization) for the receipt
+and the exact recovery command.
+
 The helper produces these heading grammars in UTC:
 
 ```text

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.
@@ -375,14 +375,14 @@ once an artifact exists, its `generatedAt` (the artifact's seconds-precision
 `oat_generated_at`), so a caller can correlate the result to the exact artifact
 and disambiguate re-gate rounds:
 
-| `status`                       | Exit | Meaning                                                      |
-| ------------------------------ | ---- | ------------------------------------------------------------ |
-| `ok`                           | 0    | Review completed; gate passed at the threshold.              |
-| `blocked`                      | 1    | Review completed; findings at/above the threshold.           |
-| `review_failed`                | ≠0   | The provider target exited non-zero; no verdict.             |
-| `artifact_missing`             | 1    | The child exited cleanly without producing an artifact.      |
-| `artifact_validation_failed`   | 1    | Artifact format or configured invocation fields are invalid. |
-| `targeting_correlation_failed` | 1    | Identity did not correlate; do not run review-receive.       |
+| `status`                       | Exit | Meaning                                                         |
+| ------------------------------ | ---- | --------------------------------------------------------------- |
+| `ok`                           | 0    | Review completed; gate passed at the threshold.                 |
+| `blocked`                      | 1    | Review completed; findings at/above the threshold.              |
+| `review_failed`                | ≠0   | No validated verdict: the target or post-selection work failed. |
+| `artifact_missing`             | 1    | The child exited cleanly without producing an artifact.         |
+| `artifact_validation_failed`   | 1    | Artifact format or configured invocation fields are invalid.    |
+| `targeting_correlation_failed` | 1    | Identity did not correlate; do not run review-receive.          |
 
 Only `ok` and `blocked` are positive, receive-eligible review outcomes: both
 follow successful identity corroboration and carry a non-null `handoff`.
@@ -400,6 +400,37 @@ bookkeeping finish inline or through a synchronously awaited child, then start
 a new gate run. Do not use review-fix retries or review-receive for the failed
 run.
 
+Post-selection recovery covers work that fails _after_ the reviewer already
+committed a run-correlated artifact: corroboration, the threshold, handoff
+construction, or result writing. Recovery means re-validation, never re-review.
+The gate re-runs the same eligibility pipeline the normal path uses (project
+containment, `oat_generated_at` validity, verdict parsing, gate-invocation
+corroboration, the `oat_review_invocation: gate` marker, and the threshold)
+against the immutable content/signature snapshot selected at correlation time.
+It re-validates that snapshot rather than re-parsing whatever the path now
+holds, and it never dispatches a second reviewer. The artifact must still be
+present and unchanged for re-validation to succeed: a deleted or rewritten
+artifact fails re-validation and the run stays failed.
+When that re-validation succeeds the gate returns the ordinary `ok` or
+`blocked` envelope with an additive `postSelectionRecovery: true`. Like
+`lateCompletion`, that is recovery telemetry rather than a new status: route
+review-receive from `status`, `receiveEligible`, and `handoff` as usual.
+
+When no artifact was selected, or the selected snapshot does not re-validate,
+the run stays `review_failed` with `outcome:
+unexpected_post_selection_failure`. That envelope names the failing sub-step in
+`postSelection.step` (`target-dispatch`, `artifact-scan`,
+`artifact-correlation`, `artifact-validation`, `verdict-parse`,
+`invocation-corroboration`, or `verdict-disposition`) and a routable
+`postSelection.code`: the thrown error's own `code` or constructor name, the
+eligibility cause when a committed artifact failed re-validation, or
+`recovery_revalidation_failed` when the re-validation attempt itself threw. That
+last case also emits a `gate-recovery-failed` diagnostic, so a persistent
+non-recovery stays distinguishable from the transient failure that triggered it.
+Replacement bytes at the artifact path, a missing artifact, a non-gate
+invocation marker, and an artifact targeting another project never recover. Route deterministically on those
+fields instead of re-dispatching the reviewer.
+
 `ok` and `blocked` also include `receiveEligible: true`, `outcome`,
 `artifactPath`, `counts`, `scope`, `handoff`, `gateInvocation`, and
 `corroboration`. Invoke review-receive only when all three conditions hold:
@@ -445,6 +476,81 @@ oat --json gate review \
 Read the resulting envelope and exit code; that is the whole completion
 contract.
 
+### Project log finalization
+
+After the envelope is written, the gate appends one structural entry to the
+project's `project-log.md` and commits it, so the run does not leave a dirty
+worktree for whatever executes next. The entry body ends with
+`run=<runId>` — the same run id the envelope carries. That token is the entry's
+stable identity: a retry or a later recovery recognizes the entry it already
+wrote instead of appending a second one.
+
+Staging and committing the log retries **three attempts** separated by two
+waits (250 ms, then 500 ms) when, and only when, git itself reports index-lock
+contention: `Unable to create '…/index.lock': File exists`, or git's `Another
+git process seems to be running in this repository` advice in output that also
+names an index lock. Every other failure — a hook,
+signing, identity, or pathspec error — is reported immediately rather than
+retried, including one whose output merely mentions `index.lock`. The gate never
+deletes, moves, or forces a lock it did not take. A lock whose mtime is
+unchanged across the whole retry window is reported as `persistent-index-lock`;
+one that moves is `transient-index-lock`. If a competing writer commits the same
+entry while the gate retries, the gate reports the work as already committed
+instead of a failure — but only when the committed log still carries this run's
+entry.
+
+When the retries are exhausted the append has landed but the commit has not, so
+the gate writes a durable receipt to
+`<project>/gate-receipts/<runId>.json` and emits a
+`gate-project-log-partial-finalization` diagnostic naming the receipt and
+printing its recovery command verbatim. The gate result is unchanged: a passing
+review still exits `ok`.
+
+The receipt must not dirty the worktree, so this repository ignores
+`**/gate-receipts/` repository-wide rather than under `.oat/projects` alone:
+`projects.root` is settable, and the receipt follows the resolved project. A
+repository whose ignore rules do not cover the receipt still gets the receipt —
+losing the finalization would be worse than a tracked file — plus a
+`gate-project-log-receipt-warning` diagnostic naming the path, so the gap
+surfaces before the next repository-wide `git add`.
+
+The receipt completes the finalization from a later process, with no reviewer
+and no second gate run:
+
+```bash
+oat project log append --project <projectPath> --structural \
+  --producer 'oat gate review' --ref <ref> --body <body> \
+  --idempotency-key <runId> --commit
+```
+
+Before appending anything, that command validates the receipt against the live
+tree: the project path must resolve to the same project, `worktreeRoot` must
+match `git rev-parse --show-toplevel`, and the review artifact must still exist
+with its recorded sha256 signature. A receipt that names no artifact — the gate
+correlated none, so `artifactPath` and `artifactSignature` are both `null` — is
+bound by run id, project, worktree, and the entry fields alone; a receipt that
+names an artifact _without_ a signature is malformed and refused. The replayed
+entry must also be the entry
+the receipt describes — `--producer`, `--ref`, and `--body` are compared against
+the receipt, and the receipt's own run id must be the `--idempotency-key` that
+names its file — so a receipt can never be consumed while some other entry is
+written. Any mismatch exits non-zero with a
+`gate-project-log-receipt-mismatch` diagnostic and touches nothing. On a match
+it appends (or reports `already-appended` when the entry is already there),
+commits with the same bounded retry, and deletes the receipt. Running it twice
+is safe: the second run appends nothing and creates no commit.
+
+At the start of a run, a receipt still sitting under the project produces a
+`gate-project-log-receipt-pending` diagnostic naming the receipt and its
+recovery command. Its `state` is `stale` only when the _committed_ log
+(`HEAD:project-log.md`) already carries that run id and entry — the append
+landed and was committed, so recovery will observe `already-appended` and clear
+the receipt. Everything else is `pending`, including the ordinary case where
+the entry is in the working tree but no commit succeeded: that is precisely
+what the receipt exists to finish, so it is never reported as leftovers. A
+receipt naming another tree's log, or a committed log that cannot be read back,
+also stays `pending`. The warning is discovery only; the gate still runs.
+
 ## Exec targets
 
 `oat gate cross-provider-exec` chooses from `workflow.gates.execTargets`.
@@ -610,7 +716,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.
 
@@ -884,14 +990,16 @@ those artifacts; correct the project/run correlation and start a new gate run.
 
 ### Incident-to-regression mapping
 
-| Observed failure                                         | Regression coverage                                                                                                    |
-| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Headless reviewer could not complete an async delegation | route unit matrix plus canonical checkout-local command, strict receipt, headless inline, and structured-refusal cases |
-| Large final review exceeded the old 15-minute budget     | scope-aware resolver tests plus scaled final-scope fake-runtime case                                                   |
-| Silent child looked idle while transcripts grew          | metadata-probe tests plus timeout-with-advancing-transcript fixture                                                    |
-| Timeout or child failure produced no artifact            | fail-closed `noOutputProduced` fixture                                                                                 |
-| Artifact carried the wrong gate run ID                   | provenance-mismatch fixture                                                                                            |
-| Passing artifact lost receive routing                    | handoff and `receiveEligible` fixture                                                                                  |
+| Observed failure                                                      | Regression coverage                                                                                                    |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Headless reviewer could not complete an async delegation              | route unit matrix plus canonical checkout-local command, strict receipt, headless inline, and structured-refusal cases |
+| Large final review exceeded the old 15-minute budget                  | scope-aware resolver tests plus scaled final-scope fake-runtime case                                                   |
+| Silent child looked idle while transcripts grew                       | metadata-probe tests plus timeout-with-advancing-transcript fixture                                                    |
+| Timeout or child failure produced no artifact                         | fail-closed `noOutputProduced` fixture                                                                                 |
+| Artifact carried the wrong gate run ID                                | provenance-mismatch fixture                                                                                            |
+| Passing artifact lost receive routing                                 | handoff and `receiveEligible` fixture                                                                                  |
+| Passing review reported as a failed gate after a post-selection error | post-selection recovery cases plus snapshot-replacement, non-gate-marker, and foreign-target controls                  |
+| Transient index lock turned a completed review into a failed gate     | index-lock retry cases plus persistent/transient classification, receipt fixture, and fresh-process recovery control   |
 
 ## Current limits
 

package/assets/docs/provider-sync/commands.md

@@ -210,6 +210,7 @@ Key behavior:
 - Supports `--strategy pointer|symlink|copy` to validate the expected file shape
 - Reports `ok`, `missing`, `content_mismatch`, and `stray` states
 - Detects Claude-only adoptable directories and unreadable/broken instruction paths as drift
+- Skips the derived documentation content root and any `documentation.instructionPointerExcludes` paths, using the same exclusions as `oat instructions sync`
 - Exit code `0` when all entries are valid, `1` when drift is detected
 - Detailed behavior: [`Instruction Sync`](instruction-sync.md)
 
@@ -227,5 +228,7 @@ Key behavior:
 - Adopts Claude-only stray files by writing canonical `AGENTS.md` content first, then regenerating `CLAUDE.md`
 - Skips mismatched files unless `--force` is provided
 - Skips unreadable canonical or Claude-only sources and reports manual-repair guidance instead of forcing recovery
+- Skips the documentation content tree (`<documentation.root>/docs` when that is a directory, otherwise `documentation.root`) plus any `documentation.instructionPointerExcludes` paths, so authored pages never receive pointers; app-level instruction files such as `apps/oat-docs/AGENTS.md` are still synced
+- Never deletes an existing `CLAUDE.md` inside an excluded tree
 - Uses pointer content `@AGENTS.md\n`, file symlinks, or hard copies depending on the selected strategy
 - Detailed behavior and examples: [`Instruction Sync`](instruction-sync.md)

package/assets/docs/provider-sync/instruction-sync.md

@@ -23,8 +23,115 @@ Instruction sync is currently project-only.
 - It supports nested directories all the way down the tree.
 - It skips provider-irrelevant or local-only roots such as `.git`, `.oat`, `.worktrees`, and `node_modules`.
 - Exception: `.oat/repo/**` is scanned even though the rest of `.oat/` is skipped, so the curated `AGENTS.md` files there (repo root guidance, `pjm/`, `reference/`) get their sibling `CLAUDE.md` shims managed and validated like any other directory. The rest of `.oat/` (`templates/`, `projects/`, `sync/`) stays excluded.
+- It skips the documentation content tree by default, and any path you add to `documentation.instructionPointerExcludes`. See [Documentation trees](#documentation-trees) below.
 - It does not scan user-level provider roots such as `~/.claude` in this release.
 
+## Documentation Trees
+
+A documentation tree holds authored pages, not instructions for agents. A
+`CLAUDE.md` written into one becomes a published page, and a page legitimately
+named `CLAUDE.md` is content that must not be treated as a pointer. Both
+`oat instructions validate` and `oat instructions sync` therefore skip the
+documentation content root, so validate never reports drift that sync refuses
+to fix.
+
+The content root is derived from `documentation.root` in `.oat/config.json`:
+
+- `<documentation.root>/docs` when that path is a directory;
+- otherwise `documentation.root` itself.
+
+This is the same derivation `oat docs generate-index` uses to pick its default
+docs directory, so the excluded tree and the indexed tree agree by
+construction. (`oat docs generate-index --docs-dir` overrides the index side
+only; it does not change what instruction sync excludes.)
+
+**App-level instruction files are still synced.** `documentation.root`
+canonically names the docs _app_ root, and a file like
+`apps/oat-docs/AGENTS.md` is instructions for working on the docs app rather
+than a documentation page. When the app root has a `docs` child, only that
+child is skipped, and the app root keeps receiving its `CLAUDE.md` pointer. Opt
+the app root out explicitly if you do not want it synced.
+
+Add further paths with `documentation.instructionPointerExcludes`, a list of
+repository-relative directories. Set it with
+`oat config set documentation.instructionPointerExcludes "vendor,third_party/docs"`
+(an empty value clears it, and `oat config unset` removes it), or write it
+directly:
+
+```json
+{
+  "documentation": {
+    "root": "apps/oat-docs",
+    "instructionPointerExcludes": ["vendor", "third_party/docs"]
+  }
+}
+```
+
+Each entry excludes that directory and everything beneath it, matching the
+directory path exactly rather than by prefix — excluding `apps/docs` leaves a
+sibling `apps/docs-legacy` scanned. Entries are repository-relative and
+normalized, so `apps/./docs`, `apps//docs`, and `apps/docs/` all name the same
+tree; absolute paths and paths escaping the repository are dropped with a
+warning when they are already stored — and refused outright by
+`oat config set` — and the repository root itself cannot be excluded. A structurally malformed value
+(anything other than an array of non-empty strings) is rejected with exit code
+`2` rather than silently ignored.
+
+The list is additive to the derived content root, and it is applied after the
+`.oat/repo` carve-in, so excluding _another_ tree can never collaterally leave
+`.oat/repo/**` unscanned. `.oat/repo` itself is never excludable — listing it
+is reported as having no effect rather than silently honoured, and its
+`AGENTS.md` keeps its pointer. A deliberate opt-out naming a path _beneath_
+it, such as `.oat/repo/pjm`, is honoured: descendants are reached by ordinary
+traversal, so only the carve-in root is protected from exclusion.
+
+### When an exclusion does nothing
+
+An entry that is well formed but cannot protect anything — it names a
+directory that does not exist, differs in case from the real path on a
+case-insensitive filesystem such as APFS, is absolute, escapes the repository,
+or is the unexcludable `.oat/repo` — does not fail the command. It is reported
+as a warning naming the entry, and it is never counted as protection.
+
+The warning channel depends on the mode: in human mode warnings are written to
+stderr, and under `--json` they are carried in the `exclusionWarnings` payload
+field instead, because `--json` suppresses stderr warnings entirely.
+
+That distinction matters most on a case-insensitive filesystem: a
+`documentation.root` of `Apps/Docsapp` resolves happily while the scan compares
+the real `apps/docsapp`, so the tree would be scanned after all. Trust
+`effectiveExcludedPaths`, not `excludedPaths`, when deciding whether a tree is
+protected — and read `exclusionWarnings` for the reason, since the stderr
+warnings are silent under `--json`.
+
+Because both commands read `.oat/config.json` to resolve exclusions, they
+inherit its validation. Any value that fails a _fail-closed_ field check —
+including keys these commands do not otherwise use, such as
+`documentation.excludes` — makes `oat instructions sync` and
+`oat instructions validate` exit `2` until it is repaired. Not every key is
+fail-closed: a wrong-typed scalar such as `documentation.root` is dropped
+rather than rejected, so it never aborts the command (a dropped `root` simply
+leaves the content root underived, and no default exclusion applies).
+
+Exclusion only stops a directory from being scanned. Nothing is deleted: a
+`CLAUDE.md` that already exists inside an excluded tree is left exactly as it
+is. When any exclusion is configured, `--json` output carries three additional
+fields.
+
+- `excludedPaths` lists the configured exclusions — a statement of intent, not
+  a per-directory skip log, so `.oat` appearing there does not contradict
+  `.oat/repo` still being scanned.
+- `effectiveExcludedPaths` lists the subset that names a real, case-exact
+  directory the scan actually pruned. It is present whenever `excludedPaths`
+  is, including as an empty array when every configured entry turned out to be
+  inert.
+- `exclusionWarnings` lists one message per configured exclusion that will not
+  protect anything — the `--json` counterpart of the stderr warnings above.
+
+Each field is omitted when it would be empty. `exclusionWarnings` is
+independent of the other two: an absolute or repository-escaping entry is
+dropped before `excludedPaths` is built, so it appears only here.
+
 ## Canonical Model
 
 - `AGENTS.md` is canonical.