Imported from KaolaBrother/Kaola-Workflow (plugins/kaola-workflow/skills/kaola-workflow-finalize/SKILL.md). Install upstream with npx skills add KaolaBrother/Kaola-Workflow --skill kaola-workflow-finalize. Copyright stays with the author.

Kaola-Workflow Finalize

Closes out a run and records what it delivered.

Finalization operation authority

Recovery marker: KW-COMPACT-RECOVERY-V2. This complete prompt owns Finalization procedure. After compact, the native V2 carrier restores global contract and dispatch, rereads durable state, then completely reloads this prompt; no tool-use hook injects it. Read project AGENTS.md; it supplements verified local facts and constraints. A project exception must state its scope and must not weaken higher-priority instructions or host safety boundaries. Then resume from existing finalization receipts.

Delegation

Runtime dispatch contract (always loaded).

Choose dispatch or inline per item: re-evaluate the choice for every mission item; one item's choice never establishes a run-wide default. The absence of an exact named role is not proof that all native subagent dispatch is unavailable. Keep one owner for the current cohesive production surface when handoff and integration cost exceed the benefit, but that scope does not absorb independent research, test authorship, documentation, or review items. Dispatch when it materially reduces main-context residue, lets a clean context check what your own cannot, or enables genuinely independent parallel work. Both modes are first-class; width follows the true work frontier. No dispatch count, cap, disjointness proof, justification, approval, or fallback stigma attaches to the judgment.

A subagent is an executor in a clean context, not a judge; where Kaola installs profiles it runs the subagent default binding. Its handback is evidence. You hold the verdict, and you reach it by reading the candidate — the diff, the findings, the command output — never the result prose alone. The subagent burns its own narrow context, which is cheap; what you read back burns the main context, which is the most expensive one there is and the one compaction eats. So ask for small, structured handbacks rather than fanning out and reading everything. Fan out where breadth pays and every handback stays small: exploring, measuring, refuting one stated claim, reviewing the same frozen diff along different cuts (correctness, test custody, trust boundary), or producing candidates you then choose between. Do not fan out to write the same production surface in parallel, and do not ask the same question again expecting a different answer; more dispatch changes the cut, not the count. When the cheaper child keeps failing an item, take it over and finish it inline; there is no escalation ladder.

Treat the active runtime adapter below as fact authority. Inspect its effective profile discovery and precedence, live call schema and verified fields, the subagent default binding, model/effort/thought carrier or inheritance, tool and custody boundaries, and native background, parallel, resume, nesting, reload, and session limits. Unknown fields stay unknown; live schema wins.

Use named, built-in, and generic routes only under their real identities. The subagent default binding guides selection but never disables a task-sensitive override the host actually exposes. If an exact role is absent, inspect adequate native routes; use one only when it satisfies custody, evidence, and stop boundaries. Otherwise work inline, record the specific capability_gap, and re-evaluate the next item. Never let a generic route claim a named role's identity. On a runtime that installs no Kaola role profiles, the absence of a named role is design, not a capability gap; choose a native route or work inline per item.

Before dispatch, write the mission's dispatched locator. Send a bounded, self-sufficient brief naming the outcome, evidence, worktree or commit, custody, and stop condition. Reconcile the promised output, not the worker.

Runtime adapter facts

Host: Codex. If the running host is not Codex, ignore this adapter section entirely and use the Kaola adapter installed for the actual host; if none is installed, record capability_gap: no Kaola adapter for host <name> and work inline.

Find the effective project or user .codex/config.toml, inspect its managed [agents.<role>] registration, then inspect the referenced .codex/agents/kaola-workflow/<role>.toml profile; agents.toml is installer source, not an installed lookup path. Dispatch with the spawn_agent schema exposed by this Codex host and agent_type: "<role>"; omit per-call model and reasoning_effort because the TOML profile pins gpt-5.6-luna / max and file values take precedence, while preserving supported fork_turns and service-tier choices.

Subagent default: every installed Kaola TOML profile pins model = "gpt-5.6-luna" and model_reasoning_effort = "max"; file values take precedence over spawn parameters and the parent session, so omit per-call model and reasoning_effort. Roles: code-explorer, code-reviewer, doc-updater, implementer, investigator, knowledge-lookup, tdd-guide.

The Codex host policy owns the actual tool boundary; the generated TOML profile owns the role behavior, not a duplicated tool list. Native alternatives include the general default, implementation-owning worker, read-heavy explorer, and any other type the host reports; use each only under its real contract. Honor the current session's multi-agent exposure, V1/V2 call schema, type catalog, history-fork choices, and host-owned nesting/concurrency limits; a missing custom agent_type does not hide other spawn_agent routes.

Consent. Irreversible and value-laden calls belong to the user — ask, in conversation, before taking one. Closing issues with open work, reorganizing forge work, force-pushing, rewriting history, and resolving real content conflicts require the proposal, reason, and user's answer.

Finalization validates, docks docs, writes terminal records, settles closure, archives, commits, and sinks. It is not a Mission List item. Read workflow-state.md and mission-list.md; completed mission results are immutable. The last mission establishes readiness, while the summary, closure, archive, and sink receipts own terminal truth.

Card: validation, acceptance, and documentation

Read the claim and Mission List. Finalization is a transaction, never a mission item. A failed command, intermediate finding, repair attempt, or review round does not by itself create a mission. Freeze a candidate; mutation invalidates prior PASS evidence for changed bytes.

On this self-host, run producer-selected diff-scoped chains after the candidate is frozen:

kaola_script(){ _n="$1"; _p="plugins/kaola-workflow/scripts/$_n"; [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; _p="$(find "$HOME/.codex/plugins/cache" -path "*/kaola-workflow/*/scripts/$_n" -print -quit 2>/dev/null)"; [ -n "$_p" ] && [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; return 1; }
CLAIM_JS="$(kaola_script kaola-workflow-claim.js)"; KAOLA_SCRIPTS="$(dirname "$CLAIM_JS")"
node "$KAOLA_SCRIPTS/kaola-workflow-run-chains.js" --project {project}

For a consumer without test:kaola-workflow:*, run its own validation and record the exact command:

kaola_script(){ _n="$1"; _p="plugins/kaola-workflow/scripts/$_n"; [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; _p="$(find "$HOME/.codex/plugins/cache" -path "*/kaola-workflow/*/scripts/$_n" -print -quit 2>/dev/null)"; [ -n "$_p" ] && [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; return 1; }
CLAIM_JS="$(kaola_script kaola-workflow-claim.js)"; KAOLA_SCRIPTS="$(dirname "$CLAIM_JS")"
node "$KAOLA_SCRIPTS/kaola-workflow-validation-runner.js" record \
  --project {project} --verdict pass --command "<exact command>"

The recorder writes .cache/final-validation.md with column-0 verdict: pass, the exact command, and validated_candidate_hash; run it from the candidate worktree the finalize transaction reads.

On failure, repair a trivial correction inline, or dispatch a suggested route: tdd-guide or yourself for acceptance meaning; implementer or yourself for a build, type, lint, or tooling failure; after your own verdict on a review finding, implementer or yourself for the fix. Use the live runtime adapter and a self-sufficient brief.

The runner measures the receipt and reports what it found. It does not refuse; you own the verdict. Record its typed result under validation in finalization-summary.md; preserve chain-receipt.json and final-validation.md. Fix meaningful findings, re-freeze, then rerun affected evidence.

Summarize acceptance honestly: automated/local/manual/UAT legs, exact commands, outputs, commit, and anything unexecuted. Do not claim unavailable service, device, or physical UAT. A user may own an explicit acceptance exception; record its boundary.

Walk the issue statement for every claimed member and name what satisfies each part: a covering test, validation receipt, or prose evidence, judged in context. Mission results record the run's answers, but there is no mechanical match; a part you cannot satisfy is a blocker, not a footnote.

Review AGENTS.md's documentation checklist against changed public behavior — APIs, setup, architecture, environment, validation, README, API docs, architecture docs, changelog, and examples — and follow it; do not relist its files here. Dispatch doc-updater when useful; it must transcribe real signatures, JSON/help/schema or return BLOCK, never invent fields. Write one docking evidence file, .cache/doc-docking.md, with checked files, fixes/no-impact reasons, and DOCKED/BLOCKED; continue only when docked.

The finalize transaction reports changed_paths. Put it under ## Changed Paths; Nothing compares that list against a guessed write set. ## Validation and ## Changed Paths are where the finalize transaction's own findings land.

Card: summary

Create finalization-summary.md with Delivered, Files Changed, Test Coverage, ## Validation, ## Changed Paths, Documentation Docking, Follow-Up Items, and final readiness status.

Scan all run records for deferred items, partial work, conflicts, review follow-ups, and user value decisions. Ask before reorganizing forge work. A run may intentionally keep the whole issue set open only through the recorded closure decision; never silently mix per-member outcomes.

Card: file or correct run-discovered work

For each real run-discovered defect, file a follow-up and record filed: #N. Give it a priority tier in the same breath: an issue filed without a P0–P3 label sorts last on the open list, beneath every tiered issue.

## Measured carries only what this run observed; every figure there names the commit it was measured at and the command or artifact it came from. ## Hypothesis carries attributions no run has confirmed; a cause derived by reading code lands there by default. ## Proposed remedy (non-binding) is optional and carries that label when it appears. Add one searched: line recording the duplicate probe you actually ran — its query and its hit count.

After filing, confirm the issue exists and its body is non-empty, and record that in this run's own finalize-transaction record — never in a completed Mission's result, which stays immutable.

When evidence corrects the current issue, post that correction as a comment on the issue before it closes. Never close quietly against text now known to be wrong. A correction is not a follow-up: a follow-up is new work with its own filed: #N; a correction is the record of what this issue turned out to be, and it lands on the issue it corrects.

If the project links issues, close every GitHub issue in the set — but only after acceptance and the closure decision. Keep-open applies to the entire claimed set, releases all claims, and is merge-sink-only; otherwise every issue closes or none does.

Card: close, archive, sink, and reconcile

Capture branch, sink kind, issue and issue_numbers before archive. --issue-numbers closes the whole set or none:

kaola_script(){ _n="$1"; _p="plugins/kaola-workflow/scripts/$_n"; [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; _p="$(find "$HOME/.codex/plugins/cache" -path "*/kaola-workflow/*/scripts/$_n" -print -quit 2>/dev/null)"; [ -n "$_p" ] && [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; return 1; }
CLAIM_JS="$(kaola_script kaola-workflow-claim.js)"; KAOLA_SCRIPTS="$(dirname "$CLAIM_JS")"
SINK_STATE_FILE="kaola-workflow/{project}/workflow-state.md"
if [ ! -f "$SINK_STATE_FILE" ]; then
  _COORD="$(git rev-parse --git-common-dir)"; [[ "$_COORD" != /* ]] && _COORD="$(pwd)/$_COORD"
  SINK_STATE_FILE="$(dirname "$_COORD")/$SINK_STATE_FILE"
fi
SINK_BRANCH=$(awk '/^branch:/{print $2}' "$SINK_STATE_FILE")
SINK_ISSUE=$(grep '^issue_number:' "$SINK_STATE_FILE" | awk '{print $2}')
SINK_KIND=$(awk '/^## Sink/,0' "$SINK_STATE_FILE" | awk '/^sink:/{print $2}'); SINK_KIND=${SINK_KIND:-merge}
SINK_ISSUE_NUMBERS=$(awk '/^issue_numbers:/{print $2}' "$SINK_STATE_FILE" | tail -1)
SINK_ISSUE_FLAG=""; [ -n "$SINK_ISSUE" ] && [ "$SINK_ISSUE" != unset ] && SINK_ISSUE_FLAG="--issue $SINK_ISSUE"
SINK_ISSUE_NUMBERS_FLAG=""; [ -n "$SINK_ISSUE_NUMBERS" ] && SINK_ISSUE_NUMBERS_FLAG="--issue-numbers $SINK_ISSUE_NUMBERS"
SINK_ISSUE_ACTION=$(awk '/^## Sink/,0' "$SINK_STATE_FILE" | awk '/^issue_action:/{print $2}'); SINK_ISSUE_ACTION=${SINK_ISSUE_ACTION:-close}
SINK_KEEP_OPEN_FLAG=""; [ "$SINK_ISSUE_ACTION" = comment_keep_open ] && SINK_KEEP_OPEN_FLAG="--keep-issue-open"
ACTIVE_WORKTREE_PATH=$(awk '/^worktree_path:/{print $2}' "$SINK_STATE_FILE"); [ -d "$ACTIVE_WORKTREE_PATH" ] || ACTIVE_WORKTREE_PATH="$PWD"

Run the read-only check as one precondition checklist, clear every reported reason, then run the same ONE resumable script transaction. It never authors implementation commits. The transaction owns worktree-to-main project-folder sync; never hand-copy a staler main copy. If sync fails because the main project folder is not writable, repair that destination's access and rerun the check:

(cd "$ACTIVE_WORKTREE_PATH" && node "$CLAIM_JS" finalize --project {project} --keep-worktree --check --json)
(cd "$ACTIVE_WORKTREE_PATH" && node "$CLAIM_JS" finalize --project {project} --keep-worktree $SINK_KEEP_OPEN_FLAG)

Stage only this project; never stage another run's archive/state or unrelated user changes. The archive still fails loudly if it would lose a file. Every run file must land under kaola-workflow/archive/. Then use the captured metadata for the forge-specific sink:

# keep-open is merge-sink-only — a PR sink would close the kept-open issue.
if [ "$SINK_KIND" != merge ] && [ -n "$SINK_KEEP_OPEN_FLAG" ]; then exit 1; fi
case "$SINK_KIND" in
  pr)
    node "$KAOLA_SCRIPTS/kaola-workflow-sink-pr.js" --branch "$SINK_BRANCH" $SINK_ISSUE_FLAG --project {project}
    ;;
  merge|*)
    node "$KAOLA_SCRIPTS/kaola-workflow-sink-merge.js" --branch "$SINK_BRANCH" $SINK_ISSUE_FLAG $SINK_ISSUE_NUMBERS_FLAG $SINK_KEEP_OPEN_FLAG --project {project} --sink --json
    ;;
esac

Keep-open is whole-run and merge-only. Close/archive/sink truth belongs to their receipts, not the Mission List. Journals are never deliverables and successful cleanup removes only this lane.

The sink does not judge your work; it is a reporting mechanism, not a workflow judging your work. It reports validation, ancestry, publication, closure, and cleanup findings and stops without merging when it cannot preserve truth. This is not "merge anyway and report." You remain the person who is accountable for the branch ending up right: get the merge correct, resynchronize, or publish a review request instead. Then clean up after the sink; never touch another session's branch/worktree/folder, and ask on real content conflict.

Run the closure audit after success as an after-the-fact drift detector:

kaola_script(){ _n="$1"; _p="plugins/kaola-workflow/scripts/$_n"; [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; _p="$(find "$HOME/.codex/plugins/cache" -path "*/kaola-workflow/*/scripts/$_n" -print -quit 2>/dev/null)"; [ -n "$_p" ] && [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; return 1; }
CLAIM_JS="$(kaola_script kaola-workflow-claim.js)"; KAOLA_SCRIPTS="$(dirname "$CLAIM_JS")"
node "$KAOLA_SCRIPTS/kaola-workflow-closure-audit.js" --project {project}            # scoped verdict, dry-run (default)
# node "$KAOLA_SCRIPTS/kaola-workflow-closure-audit.js" --project {project} --execute  # repair safe local drift, scoped

It reports scoped and outside-scope drift without turning exit zero into a verdict. If the sink reported that it did not complete, the step it names is where to resume; receipts keep retry idempotent.

Only after every issue is closed (or the user-authorized whole set is kept open), the folder is archived, and publication is proven may finalization stop and await explicit redirection.