@open-agent-toolkit/cli 0.2.4 → 0.2.6

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.5.3
+version: 1.5.4
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -91,6 +91,7 @@ remain valid.
 ```bash
 ARCHIVE_PREF=$(oat config get workflow.archiveOnComplete 2>/dev/null || true)
 PR_ON_COMPLETE=$(oat config get workflow.createPrOnComplete 2>/dev/null || true)
+PROJECT_RECAP_CONFIG=$(oat config get workflow.explainers.projectRecap --json 2>/dev/null || true)
 ```
 
 - **If `ARCHIVE_PREF` is `true`:** Set `SHOULD_ARCHIVE="true"`. Skip the archive question. Print `Archive on complete: enabled (from workflow.archiveOnComplete).`
@@ -103,6 +104,19 @@ PR_ON_COMPLETE=$(oat config get workflow.createPrOnComplete 2>/dev/null || true)
 
 The "Ready to mark complete?" confirmation is always asked — it is a meaningful "are you sure" moment, not a preference.
 
+Resolve `projectRecap` intent before presenting the batched completion prompt.
+Use the `oat-explainer-kit` lifecycle intent resolver in interactive mode with
+the current `oat_project_recap` value from the same `state.md` read and the
+source-aware `workflow.explainers.projectRecap` preference. Preserve the state
+content hash required by the adapter's safe intent persistence contract.
+
+When resolution returns `needsPrompt: true`, add exactly one project-recap question to that same batched prompt: "Generate a final project recap as part of completion?" Do not open a second prompt. Resolve the answer as `generate` or `skip`, then use the adapter's intent persistence helper with the captured state hash. Persist either `generate` or `skip` as the returned `interactive` record before continuing. If persistence reports a stale write, re-read state and resolve precedence again; never retry the stale record blindly. A valid persisted `oat_project_recap` decision prevents another prompt.
+
+Set `SHOULD_GENERATE_RECAP="true"` only when the final resolved decision is
+`generate`; otherwise set it to `"false"`. Direct `always` or `never` workflow
+preference results are effective for this run but are not copied into project
+state.
+
 Also preflight summary status using the same freshness rules as `oat-project-summary`:
 
 - `summary.md` is `missing` when `{PROJECT_PATH}/summary.md` does not exist
@@ -116,7 +130,8 @@ Also preflight summary status using the same freshness rules as `oat-project-sum
 3. **Generate or refresh summary** (only if summary status is `missing` or `stale`): present the status explicitly:
    - Missing example: "A summary has not been generated yet. Would you like me to generate it now as part of completion?"
    - Stale example: "The project summary is out of date. Would you like me to refresh it now as part of completion?"
-4. **Open PR:** "Open a PR in GitHub after generating the PR description?" — ask this only when no tracked open PR already exists.
+4. **Generate final project recap** (only when recap intent resolution returned `needsPrompt: true`): "Generate a final project recap as part of completion?"
+5. **Open PR:** "Open a PR in GitHub after generating the PR description?" — ask this only when no tracked open PR already exists.
 
 If `oat_pr_status` is `open`, do not ask the Open PR question. Set `SHOULD_OPEN_PR="false"` and treat the existing PR as already tracked.
 
@@ -127,12 +142,13 @@ Ready to complete project **{PROJECT_NAME}**?
 
 1. Archive the project after completion? (yes/no)
 2. A summary has not been generated yet. Generate it now as part of completion? (yes/no)
-3. Open a PR in GitHub? (yes/no)
+3. Generate a final project recap as part of completion? (yes/no)
+4. Open a PR in GitHub? (yes/no)
 ```
 
 If the user declines the completion confirmation, exit gracefully.
 
-Store the answers as `SHOULD_ARCHIVE`, `SHOULD_GENERATE_SUMMARY`, and `SHOULD_OPEN_PR` for use in later steps.
+After the user accepts the completion confirmation, store the answers as `SHOULD_ARCHIVE`, `SHOULD_GENERATE_SUMMARY`, `SHOULD_GENERATE_RECAP`, and `SHOULD_OPEN_PR` for use in later steps. Persist a prompted recap answer only after that confirmation is accepted.
 
 If the summary status is `current`, set `SHOULD_GENERATE_SUMMARY="false"` and note that a current summary is already available.
 
@@ -257,7 +273,26 @@ Check if `{PROJECT_PATH}/summary.md` exists and whether it is current against th
   - Used as source for the PR description (in Step 7)
   - Preserved in the archived project directory (in Step 8)
 
-### Step 3.6: Project Log Completion Gate
+### Step 3.6: Select Final Project Recap
+
+Run this gate after the optional summary refresh and before any lifecycle
+mutation. Initialize `SELECTED_PROJECT_RECAP_RUN=""`.
+
+When `SHOULD_GENERATE_RECAP="true"`, inspect manifests under
+`{PROJECT_PATH}/explainers/` before generating. A fresh `project-recap` manifest for the current completed implementation is reused without invoking the adapter again. Fresh means the manifest identifies recipe `project-recap`, belongs to this project, has a terminal outcome, and its recorded source hashes match the current approved implementation inputs, including the refreshed summary when present.
+
+If no fresh recap exists, invoke `scripts/run.mjs#runOatExplainer` exactly once with recipe `project-recap`, project invocation, the active project, and unattended lifecycle mode so approved OAT artifacts do not trigger a second content prompt. A failed adapter run warns but does not block completion. Use a returned valid terminal `project-recap` manifest as the selected run; do not rerun to improve its outcome.
+Supply the provider-neutral critic callback (or validated critic module entry point for JSON/CLI invocation) on every federated adapter run.
+
+Set `SELECTED_PROJECT_RECAP_RUN` only to the final selected `project-recap` run. The value must be project-relative in the form `explainers/<run-slug>` so it can be passed safely to the archive CLI. An incomplete, stale, wrong-project, or `project-explainer` manifest is never selected as the final recap.
+
+When recap intent resolves to `skip`, or generation produces no valid final recap, leave `SELECTED_PROJECT_RECAP_RUN` empty and complete without a recap. Record any failed recap attempt as a warning rather than changing project completion status.
+
+`project-explainer` runs are active-project working artifacts, not durable post-completion reference products. Do not export, re-attest, or add archive-aware PR or summary reference links for a `project-explainer` run.
+
+For `IS_SHARED_PROJECT="false"`, never export a tracked project recap and never construct or pass `--project-recap-run`. A local-scope recap remains `built-not-durable` unless its manifest already contains independently verified publish evidence. Do not treat local filesystem presence as durability. Completion-bookkeeping durability, relocation re-attestation, and archive-aware recap links are handled by the later durability stage, not by this selection gate.
+
+### Step 3.7: Project Log Completion Gate
 
 Run the project-log status probe before any lifecycle mutation or archive work:
 
@@ -309,7 +344,7 @@ oat project log append \
   --body "Completion sealed at $(date -u +%Y-%m-%dT%H:%M:%SZ); project-log roll-up status: ok."
 ```
 
-Only append this seal after Step 3.6 has either confirmed there are no entries
+Only append this seal after Step 3.7 has either confirmed there are no entries
 to roll up or obtained `status: "ok"`. If the append fails for an existing log,
 stop before setting lifecycle complete or archiving. No project-log append may follow the seal.
 
@@ -405,6 +440,10 @@ When archiving, the project artifacts at `{PROJECT_PATH}/{plan,implementation,di
   - When `archive.summaryExportPath` is unset or `summary.md` is missing, omit this bullet rather than emit a broken link.
 - **Keep References bullets** that resolve independently of the archive: backlog item links under `.oat/repo/pjm/backlog/`, decision record links under `.oat/repo/reference/decisions/`, repo-reference docs, ticket URLs, and anything else under tracked paths outside the project directory.
 - Apply the existing `localPaths`-based exclusion rule from `oat-project-pr-final` Step 4 on top of these rules — it already covers `.oat/**/pr` and `.oat/**/reviews/archived` and may catch additional patterns configured per repo.
+- Do not add a durable reference for any `project-explainer` run. Only the selected final `project-recap` can enter the tracked completion export path.
+- When a final project recap is selected, defer its summary and PR link until
+  Step 8 returns `projectRecapExport.exportRoot`. Do not predict that path from
+  the date or project name.
 
 Anti-pattern: do not "rescue" a dropped artifact by linking to its archived path under `.oat/projects/archived/<name>/...`. That path is gitignored on every checkout and never reaches the remote.
 
@@ -412,7 +451,7 @@ Anti-pattern: do not "rescue" a dropped artifact by linking to its archived path
 
 **Skip if `SHOULD_ARCHIVE` is false or `IS_SHARED_PROJECT` is false.**
 
-This conditional skips archive movement only; it does not skip the Step 3.6
+This conditional skips archive movement only; it does not skip the Step 3.7
 seal append for an existing project log.
 
 Archive happens after PR description generation (so artifacts are readable at tracked paths) but before commit+push (so the archive deletion is included in the commit).
@@ -421,26 +460,60 @@ The archive-side effects in this step are CLI-owned. Do not reimplement local ar
 
 ```bash
 ARCHIVE_OUTPUT=""
-if ! ARCHIVE_OUTPUT=$(oat project archive "$PROJECT_PATH" 2>&1); then
+ARCHIVE_ARGS=("$PROJECT_PATH")
+if [[ -n "$SELECTED_PROJECT_RECAP_RUN" ]]; then
+  ARCHIVE_ARGS+=("--project-recap-run" "$SELECTED_PROJECT_RECAP_RUN")
+fi
+
+if ! ARCHIVE_OUTPUT=$(oat project archive "${ARCHIVE_ARGS[@]}" --json 2>&1); then
   printf '%s\n' "$ARCHIVE_OUTPUT" >&2
   echo "Error: Project archive failed." >&2
   exit 1
 fi
 
 printf '%s\n' "$ARCHIVE_OUTPUT"
+```
 
-ARCHIVE_PATH=$(printf '%s\n' "$ARCHIVE_OUTPUT" | sed -nE 's/^Archived project `[^`]+` to `(.+)`\.$/\1/p' | tail -1)
-if [[ -z "$ARCHIVE_PATH" ]]; then
-  echo "Error: oat project archive did not report the archived path." >&2
-  exit 1
-fi
+Parse `ARCHIVE_OUTPUT` as the `oat project archive --json` report. Require
+`status: "ok"`, `mode: "apply"`, and a non-empty `archivePath`; use its
+`s3Path`, `summaryExportFile`, and `warnings` fields for later reporting. Set
+`ARCHIVE_PATH` from `archivePath`, then set `PROJECT_PATH="$ARCHIVE_PATH"`.
 
-PROJECT_PATH="$ARCHIVE_PATH"
-ARCHIVE_S3_PATH=$(printf '%s\n' "$ARCHIVE_OUTPUT" | sed -nE 's/^S3 archive: (.+)$/\1/p' | tail -1)
-ARCHIVE_S3_CONTEXT=$(printf '%s\n' "$ARCHIVE_OUTPUT" | grep -E '^Archive S3 sync: .*profile=.*region=' | tail -1 || true)
-```
+When `SELECTED_PROJECT_RECAP_RUN` is non-empty, also require the report's
+`projectRecapExport.sourceRunRoot`, `projectRecapExport.exportRoot`, and
+`projectRecapExport.manifest.relativePath === "manifest.json"`. Confirm the
+reported source is the selected run under the pre-archive project path and the
+export root is inside the tracked
+`.oat/repo/reference/project-recaps/` root. Record:
+
+- `sourceRunRoot` as the relocation source;
+- `exportRoot` as the final recap run root; and
+- `exportRoot/manifest.relativePath` as the final manifest.
+
+Do not infer or reconstruct the recap export root. The archive report is
+authoritative. A missing, malformed, mismatched, outside-root, or gitignored
+export report is an archive failure; stop before lifecycle bookkeeping.
+Never use the gitignored archive as evidence or a link target.
 
-Use `ARCHIVE_S3_CONTEXT` in Step 12 if the command reports profile/region details. If S3 sync ran and only `ARCHIVE_S3_PATH` is available, report the destination and note that credential context was not emitted by the command.
+SELECTED_PROJECT_RECAP_RUN must be project-relative. Never add `--project-recap-run` when `SELECTED_PROJECT_RECAP_RUN` is empty. The empty case remains the existing archive behavior. Because this step runs only for shared projects, local-scope projects never pass a recap archive argument.
+
+The no-recap invocation remains `oat project archive "$PROJECT_PATH"` with
+`--json` added only to select the machine-readable report.
+Use `ARCHIVE_S3_CONTEXT` in Step 12 if the command reports profile/region details.
+
+#### Step 8.5: Finalize Archive-Aware Recap Links
+
+Run this only when archive returned a `projectRecapExport`.
+
+Rewrite recap links in the tracked summary export and the PR description body from `projectRecapExport.exportRoot`; do not derive them from the local archive.
+Use a repository-relative path under
+`.oat/repo/reference/project-recaps/` and a blob URL on the current head branch
+while the PR is open. If `summaryExportFile` is non-null, update its concise
+`Explainer Outcome` recap link. Update the archived PR-description artifact
+used by Step 11 or 11.5 so its recap reference points to the same tracked root.
+Omit either link when its containing artifact does not exist.
+
+Use the current head branch for the blob URL while the PR is open. Never link to `.oat/projects/archived/`; it is gitignored and will return 404 remotely.
 
 ### Step 9: Regenerate Dashboard
 
@@ -452,7 +525,9 @@ oat state refresh
 
 ### Step 10: Commit + Push Bookkeeping (Required)
 
-Completion is not done until bookkeeping changes are committed and pushed. This prevents local-only `state.md` updates that leave project status stale for later sessions/reviews.
+Completion is not done until lifecycle changes are committed. This commit also
+anchors commit durability for a selected shared-project recap. Do not push yet
+when recap attestation is pending.
 
 Expected changes may include:
 
@@ -463,21 +538,80 @@ Expected changes may include:
 - `.oat/state.md` is regenerated locally in Step 9 but should not be staged; it is generated dashboard state and normally gitignored.
 - `.oat/config.local.json` (if `activeProject` cleared)
 - Shared-project deletions under `{PROJECTS_ROOT}/{PROJECT_NAME}` (if archived)
+- The complete tracked recap export and tracked summary export reported by
+  archive (if present)
 
 Run:
 
 ```bash
 git status --short
-git add -A
+git add -- <exact completion and lifecycle paths>
 git commit -m "chore(oat): complete project lifecycle for ${PROJECT_NAME}"
-git push
+LIFECYCLE_COMMIT=$(git rev-parse HEAD)
 ```
 
 Rules:
 
-- If there are unrelated unstaged/staged changes, stage and commit only the completion/bookkeeping files (do not sweep unrelated work into this commit).
+- If there are unrelated unstaged/staged changes, stage and commit only the
+  completion/bookkeeping files. Never use a repository-wide `git add -A` when
+  unrelated changes exist.
 - If there is nothing to commit, state that explicitly and verify whether the completion bookkeeping was already committed in a prior commit.
-- If push fails, report the failure and do not claim completion is fully recorded.
+- The lifecycle bookkeeping commit is the artifact commit for final recap
+  durability. It must contain the final run's immutable paths.
+- Snapshot unrelated working-tree changes before finalization so the shared
+  finalizer can verify they remain unchanged.
+
+### Step 10.5: Re-attest Final Project Recap
+
+Skip when no final recap was selected, for local-scope projects, or when the
+selected recap is already durable solely through independently verified publish
+evidence.
+
+For an archived recap, consume the exact `projectRecapExport` values recorded
+in Step 8. Plan finalization through
+`oat-explainer-kit/scripts/finalize-tracked-run.mjs#planTrackedRunFinalization`
+with:
+
+- `runRoot`: `projectRecapExport.exportRoot`;
+- `manifestPath`:
+  `projectRecapExport.exportRoot/projectRecapExport.manifest.relativePath`;
+- commitMode: `completion-bookkeeping`;
+- relocatedFrom: `sourceRunRoot`; and
+- context `artifactCommit`: the full `LIFECYCLE_COMMIT` SHA.
+
+For a shared project that was not archived, use the selected active run and
+omit `relocatedFrom`, but keep the same `completion-bookkeeping` mode.
+
+The lifecycle bookkeeping commit is the artifact commit. Call the compatible
+core's `recordDurability(...)` with the finalizer's planned request. Submit only immutable paths under `projectRecapExport.exportRoot` as commit evidence for an archived recap; `manifest.json` and `build-record.json` are mutable records and
+must not appear in that evidence path list. The successful exported-path
+attestation supersedes the prior active-path evidence. Verify the resulting
+manifest records the old evidence in `supersedes` and reports the final
+tracked export path.
+
+Never submit the gitignored archive path as commit evidence. Local archive
+presence cannot make a recap durable.
+
+A failed exported recap attestation does not fail project completion. Preserve
+the tracked export, report `built-not-durable`, retain actionable recovery
+details, and continue to the evidence commit.
+
+### Step 10.6: Commit Evidence + Push
+
+When Step 10.5 ran, create the evidence update. Commit only the exported `manifest.json` and `build-record.json` as the evidence update, including warning-bearing records from a failed attestation. On failure, commit the warning-bearing `manifest.json` and `build-record.json`. Run
+`verifyTrackedRunFinalization(...)` with the artifact commit, immediate evidence
+commit parent/order, exact evidence paths, attestation outcome, and unchanged
+unrelated-change snapshots.
+
+Archive completion is exactly two commits when recap attestation runs:
+
+1. lifecycle bookkeeping, including the tracked recap export; then
+2. final recap evidence records.
+
+Push once after both commits exist so they travel together. If no attestation
+ran, push the lifecycle bookkeeping commit once. If verification detects
+contamination or wrong commit order, do not push. If push fails, report the
+failure and do not claim completion is fully recorded.
 
 ### Step 11: Open PR in GitHub (Conditional)
 
@@ -491,10 +625,9 @@ Steps:
 1. Locate the PR description artifact at `{PROJECT_PATH}/pr/project-pr-*.md`.
 2. Write the stripped body to a temporary file (remove all lines from the opening `---` through the closing `---`, inclusive).
 3. Verify the temp file does not start with YAML frontmatter keys.
-4. Push and create the PR:
+4. Create the PR from the branch already pushed in Step 10.6:
 
 ```bash
-git push -u origin "$(git rev-parse --abbrev-ref HEAD)"
 gh pr create --base main --title "{title}" --body-file "$TMP_BODY"
 ```
 
@@ -506,7 +639,7 @@ Do not assume `gh` is installed; if missing, instruct manual PR creation using t
 
 **Run only when `WAS_PR_OPEN_AT_START="true"` AND `SHOULD_ARCHIVE="true"`.**
 
-When the PR was already open at the start of this skill (typically because `oat-project-pr-final` ran earlier in the lifecycle) AND we just archived, the GitHub PR description authored by `oat-project-pr-final` still points to the active artifact paths. Step 8 moved those artifacts to a gitignored archive location and Step 10 pushed the move, so any blob link in the open PR body now 404s. Push the regenerated archive-aware body to the existing PR.
+When the PR was already open at the start of this skill (typically because `oat-project-pr-final` ran earlier in the lifecycle) AND we just archived, the GitHub PR description authored by `oat-project-pr-final` still points to the active artifact paths. Step 8 moved those artifacts to a gitignored archive location and Step 10.6 pushed the move, so any blob link in the open PR body now 404s. Push the regenerated archive-aware body to the existing PR.
 
 Skip this step when:
 
@@ -540,7 +673,8 @@ Failure handling:
 
 - If `gh` is missing, warn and print the path to the regenerated artifact body so the user can paste it into the PR manually. Do not fail the skill.
 - If `gh pr edit` fails (e.g. PR was merged between Step 2 and now, or the auth token lacks edit permission), warn and continue. Step 12's completion summary should call out that the PR body was not updated and surface the artifact path so the user can update it manually.
-- Never re-archive or re-commit on failure here — the lifecycle bookkeeping in Step 10 already shipped.
+- Never re-archive or re-commit on failure here — the lifecycle bookkeeping
+  and any recap evidence update in Step 10.6 already shipped.
 
 ### Step 12: Confirm to User
 
@@ -549,7 +683,11 @@ Show user:
 - "Project **{PROJECT_NAME}** marked as complete."
 - If archived: "Archived location: **{PROJECT_PATH}**"
 - If S3 archive sync ran: include `ARCHIVE_S3_CONTEXT` when the archive command reported profile/region details. If only `ARCHIVE_S3_PATH` is available, include the S3 destination and note that profile/region context was not reported by the command. Never echo raw credentials (`AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, etc.).
-- Include commit hash and push result for the bookkeeping changes.
+- Include both lifecycle bookkeeping and recap evidence commit hashes when
+  attestation ran, plus the single push result.
+- Report the final recap outcome and tracked reference root. A failed
+  attestation is a warning with `built-not-durable`, not a project-completion
+  failure.
 - If PR was opened: include the PR URL.
 - If `oat_pr_url` is present, show it in the completion summary even when PR creation was skipped because the project already tracked an open PR.
 - If Step 11.5 ran, report whether the PR description was synced (e.g. `PR description synced: <PR URL>`) or warn that the sync failed and surface the artifact path so the user can update it manually.

package/assets/skills/oat-project-document/references/docs/autonomy-contract.md

@@ -142,6 +142,7 @@ remains.
 | PLAN-09          | `oat-project-plan`               | Plan artifact-review findings                 | Accept offered Medium/Minor fixes                         | Apply unambiguous artifact-local fixes and re-review; unresolved Critical or material ambiguity stops                                                                                                                                                                        | `auto-resolve` / `boundary:unresolved-critical-findings`                        | Plan review row and residuals                                        |
 | PLAN-10          | `oat-project-plan`               | Parallel-group proposal                       | Confirm a candidate group                                 | Accept only when write-set and dependency evidence proves independence; otherwise keep sequential and record why                                                                                                                                                             | `auto-resolve`                                                                  | Plan Parallelism section                                             |
 | PLAN-11          | `oat-project-plan`               | Configured exit gate                          | `block`, `prompt`, or `warn` after failure                | Apply configured failure semantics; `prompt` becomes a reported boundary                                                                                                                                                                                                     | `auto-resolve` / `boundary:repository-policy-approval`                          | Structured gate result and disposition                               |
+| PLAN-12          | `oat-project-plan`               | Project-explainer intent                      | Generate or skip the project explainer                    | Preserve explicit or persisted intent; in autonomy generate only when kickoff explicitly requested it and never prompt                                                                                                                                                       | `auto-resolve`                                                                  | Persisted project-explainer intent                                   |
 | IMPORT-01        | `oat-project-import-plan`        | Inherited dirty tree                          | Commit, proceed, or abort                                 | Proceed without staging unrelated files; destructive cleanup stops                                                                                                                                                                                                           | `auto-resolve` / `boundary:destructive-change-risk`                             | Import preflight note                                                |
 | IMPORT-02        | `oat-project-import-plan`        | Missing project                               | Ask for project identity                                  | Use explicit invocation context; otherwise stop rather than guess                                                                                                                                                                                                            | `boundary:product-judgment`                                                     | Resolved project path                                                |
 | IMPORT-03        | `oat-project-import-plan`        | Source plan selection or extension exception  | Choose a candidate/path or confirm nonstandard Markdown   | Use an explicit unique source; ambiguity or nonstandard content stops                                                                                                                                                                                                        | `auto-resolve` / `boundary:product-judgment`                                    | Import reference metadata                                            |
@@ -169,6 +170,7 @@ remains.
 | IMPLEMENT-16     | `oat-project-implement`          | Final HiLL approval                           | Approve, decline, or defer between pre/post steps         | After passing auto-review and successful pre-approval steps, record approval and continue post-approval steps; otherwise stop                                                                                                                                                | `auto-resolve` / `boundary:unresolved-critical-findings`                        | Sequence snapshot, review artifact, dispatch record                  |
 | IMPLEMENT-17     | `oat-project-implement`          | Next-step prompt                              | Choose lifecycle tail actions                             | Unreachable when the autonomous sequence snapshot exists; never present the prompt                                                                                                                                                                                           | `auto-resolve`                                                                  | Completed sequence snapshot                                          |
 | IMPLEMENT-18     | `oat-project-implement`          | Configured exit gate                          | `block`, `prompt`, or `warn` after validated findings     | Apply configured failure semantics only to a validated, receive-eligible `blocked` envelope after durable receive; all operational, validation, correlation, malformed/contradictory-envelope, launch, and receive failures stop regardless of `onFailure`, including `warn` | `auto-resolve` / `boundary:repository-policy-approval`                          | Validated structured gate result, completed receive, and disposition |
+| IMPLEMENT-19     | `oat-project-implement`          | Implementation-tail project recap             | Generate or skip the final project recap                  | In autonomy attempt one recap when no fresh recap exists; preserve resolved interactive intent otherwise, and never block completion on recap outcome                                                                                                                        | `auto-resolve`                                                                  | Recap manifest and outcome record                                    |
 | DOCUMENT-01      | `oat-project-document`           | Missing project path                          | Ask for a path                                            | Use explicit/active project only; otherwise stop                                                                                                                                                                                                                             | `boundary:product-judgment`                                                     | Resolved project path                                                |
 | DOCUMENT-02      | `oat-project-document`           | Documentation delta approval                  | Apply all, individual, or skip                            | Invoke the existing `--auto` path and apply all non-destructive recommendations                                                                                                                                                                                              | `auto-resolve`                                                                  | Documentation delta and state update                                 |
 | DOCUMENT-03      | `oat-project-document`           | Delete or restructure docs                    | Require explicit approval                                 | Stop before destructive or broad restructuring not already authorized by the plan                                                                                                                                                                                            | `boundary:destructive-change-risk`                                              | Documentation blocker                                                |
@@ -256,7 +258,9 @@ remains immutable baseline evidence for the original p01-t01 verification.
 | `oat-dispatch-subagents/references/provider-cursor.md`         | `ca11e28923eb -> NG`; `be0a84c48fc0 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `oat-dispatch-subagents/references/record-schema.md`           | `78f8069274a8 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `oat-project-dispatch-subagents/SKILL.md`                      | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `oat-project-complete/SKILL.md`                                | `b4934a85feee -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `oat-project-plan/SKILL.md`                                    | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `oat-project-implement/references/completion-and-closeout.md`  | `6909a5a5a1fa -> IMPLEMENT-19`; `a7c02ef670fd -> IMPLEMENT-19`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `oat-project-complete/SKILL.md`                                | `ffad9f909dba -> COMPLETE-01`; `ffe636f736e8 -> COMPLETE-01`; `ea2dced337be -> COMPLETE-01`; `93d3e4ee3355 -> COMPLETE-01`; `2407ebed0921 -> NG`; `0177956707aa -> NG`; `8305b5bb65ef -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 ## Prompt-scan comparison
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 2.1.5
+version: 2.1.7
 description: Use when plan.md is ready for execution. Dispatches one phase implementer per phase, owns independent phase review and bounded fix routing, and supports plan-declared worktree-isolated parallel phases.
 oat_gateable: true
 argument-hint: '[--retry-limit <N>] [--dry-run]'

package/assets/skills/oat-project-implement/references/completion-and-closeout.md

@@ -310,7 +310,10 @@ oat_implement_exit_gate:
   max_attempts: 2
   attempts_completed: 0
   reviewed_head: null
+  implementation_base_ref: null
   implementation_fingerprint: null
+  freshness_head: null
+  freshness_fingerprint: null
   launch_state: not_started # not_started | intent_persisted | accepted | result_persisted | not_accepted
   launch_attempt_id: null
   launch_started_at: null
@@ -343,6 +346,29 @@ pending` before any gate launch. Missing state means unresolved, never no gate.
 A `null` resolution persists `allowed/no_gate` with `disposition: no_gate`,
 null run/artifact/receive provenance, and the current implementation basis.
 
+New generations persist `implementation_fingerprint` as
+`sha256:effective-delta-v1:<digest>`. Resolve the logical integration base from
+the tracked PR's exact base ref, then the repository's configured remote default
+branch; missing or ambiguous resolution fails closed. Persist the logical base
+ref as `implementation_base_ref`; require exactly one merge base between that
+ref and each compared HEAD.
+
+Prefix the fingerprint input with the bytes `effective-delta-v1\0`. Hash the
+exact NUL-delimited byte stream from Git
+`--raw -z --no-renames --no-abbrev` output, which includes both base and final
+modes and full object IDs for blobs, symlinks, deletions, and gitlinks. Run with
+`LC_ALL=C` from the unique merge base to the compared HEAD. Git's raw `-z`
+format owns path framing and byte ordering; do not parse and reserialize it,
+abbreviate object IDs, enable rename detection, or hash human patch output.
+
+Exclude only the exact `$PROJECT_PATH/state.md` checkpoint carrier to avoid a
+self-referential digest. Use Git's literal exclusion pathspec, not a glob.
+Validate that file independently as the structured transition above. Every
+other path remains fingerprinted. Set `freshness_head` to `reviewed_head` and
+`freshness_fingerprint` to `implementation_fingerprint` when the generation
+starts. These rolling fields preserve the accepted tree outcome after later
+authorized closeout transitions without changing the immutable reviewed basis.
+
 An in-flight `pending` or `blocked` generation reuses its persisted resolved
 configuration and never re-resolves it. Recompute the fingerprint from those
 persisted inputs before resume. If the persisted resolved configuration does
@@ -476,19 +502,43 @@ disposition.
   policy, or persistence boundary.
 - A fresh `allowed` result resumes after the gate without executing the gate or
   receive a second time. Reuse requires a valid disposition, complete
-  configured-gate provenance when configured, an unchanged implementation
-  fingerprint, and any eligible receive marked complete.
+  configured-gate provenance when configured, an unchanged immutable
+  implementation fingerprint, a valid rolling freshness checkpoint, and any
+  eligible receive marked complete.
 - Closeout-only descendants include configured gate artifacts and receipts,
   project tracking, `project-log.md` appends, summary/documentation/PR sequence
   outputs, final HiLL bookkeeping, and completion bookkeeping. Classify
   gate-owned `oat project log append` mutations introduced with PR #156 as
-  closeout-only; they do not invalidate the reviewed implementation basis.
-- Determine freshness from every path changed after `reviewed_head`, and require
-  each descendant commit to contain only recognized closeout work. An unknown
-  changed path fails closed as substantive implementation change.
-  Implementation, test, skill, template, or workflow configuration changes
-  make the prior result `stale`. Preserve its provenance for audit, require a
-  current final lifecycle review for the new basis, and start a new generation.
+  closeout-only. A path category alone is insufficient: the corresponding
+  persisted gate or sequence transition must own that descendant boundary;
+  unknown or mixed work is substantive.
+- For a qualified `sha256:effective-delta-v1:<digest>` value, require the
+  persisted `implementation_base_ref`, `freshness_head`, one current merge base,
+  and 64-character lowercase hexadecimal implementation and freshness digests.
+  Missing or malformed inputs fail closed. Walk descendants after
+  `freshness_head` in commit order. Ignore a checkpoint-persistence commit only
+  after verifying its diff changes the exact state carrier and nothing else.
+  After a corroborated closeout-only transition, hash the complete current
+  effective delta and persist the rolling freshness checkpoint. Record the
+  transition's last non-checkpoint commit as `freshness_head`; the following
+  state-only persistence commit is the verified carrier exception above. For a
+  merge, rebase, or base-update boundary, recompute the complete effective delta
+  against the current merge base. A merge, rebase, or base update is not
+  substantive by itself. When it matches the rolling fingerprint, preserve the
+  allowed generation and persist an advanced rolling checkpoint without
+  rerunning gate or receive. A mismatch, unknown commit, or mixed
+  closeout/substantive boundary marks the generation `stale`.
+  Conflict resolution or branch-owned implementation, test, skill, template, or
+  workflow changes that alter the effective delta are substantive.
+- Legacy unqualified `sha256:<digest>` values keep the descendant-path policy
+  and are never reinterpreted or migrated in place. Determine freshness from
+  every path changed after `reviewed_head`, and require each descendant commit
+  to contain only recognized closeout work. An unknown changed path fails closed
+  as substantive implementation change. Implementation, test, skill, template,
+  or workflow configuration changes make the prior result `stale`.
+- Every stale transition preserves prior provenance for audit, requires a
+  current final lifecycle review for the changed basis, and starts a new
+  generation using the qualified fingerprint format.
 
 Before approval-aware sequencing, final HiLL approval, implementation
 completion, or success output, run the configured gate:
@@ -683,6 +733,31 @@ A pre-approval failure leaves `approval: pending`; a post-approval failure
 retains `approval: approved`. Fail fast with the boundary, failed step, and
 exact resume command: `oat-project-implement`.
 
+For qualified gate state, treat each committed sequence step as a corroborated
+closeout boundary. Recompute the complete effective delta, record that step
+commit as `freshness_head`, and persist `freshness_fingerprint` in a separate
+state-only checkpoint commit before dispatching the next step. Apply the same
+checkpoint protocol to gate bookkeeping, final HiLL bookkeeping, and completion
+bookkeeping. A mixed commit, missing child transition, or non-state path in the
+checkpoint-persistence commit fails closed as stale.
+
+**Implementation-Tail Project Recap:**
+
+The final-closeout orchestrator owns one project-recap gate. Run this recap gate after the final code review has passed and configured pre-approval summary/document steps have completed, but before final HiLL approval. Preserve the stored order of all other pre-approval steps and the existing final review sequence; the recap gate does not replace or repeat either.
+
+Before generating, inspect the active project's explainer runs. A fresh `project-recap` manifest for the current completed implementation deduplicates the lifecycle-tail run: reuse it and do not invoke the adapter again. Fresh means the manifest identifies recipe `project-recap`, belongs to this project, has a terminal outcome, and its recorded source hashes match the current approved implementation inputs. A merely present, incomplete, wrong-recipe, or stale manifest does not satisfy this check.
+
+Resolve recap intent through `oat-explainer-kit`. When `OAT_AUTONOMOUS=1` and no fresh recap exists, attempt `project-recap` exactly once; missing or stale persisted intent cannot suppress this autonomous attempt. Interactive mode honors the adapter's resolved persisted or workflow intent.
+
+Invoke the `oat-explainer-kit` adapter first, then run its shared tracked-run finalizer in `dedicated` mode for a successful build. Use the adapter result and finalizer result as returned; do not improvise commits, durability evidence, or reruns. Outcomes `failed` and `built-not-durable` are recorded warnings, never blockers for final HiLL approval, completion reporting, or later PR steps.
+Supply the provider-neutral critic callback (or validated critic module entry point for JSON/CLI invocation) on every federated adapter run.
+
+Always include the selected or attempted recap's outcome and run path in the
+implementation completion report. If `summary.md` exists, append or refresh its
+single concise `Explainer Outcome` section using the manifest and build record;
+never append a second outcome section. If no recap was attempted or reused,
+leave the summary unchanged.
+
 1. Dispatch incomplete `pre_approval` steps in stored order.
 2. When they succeed and a final checkpoint exists, commit `status:
 awaiting_approval` with `approval: pending` before asking for final HiLL