git:20260906.c3443ed to git:20260910.b2bdfe6

44 added, 15 removed. Audit A to A.

---

name: worktree-done

- description: Review, integrate, or finish a Toastty worktree task or PR from a project coordinator or another session outside the task. Assess codebase consistency and in-flight work, then perform authorized integration and local task cleanup.

+ description: Review, integrate, or finish a Toastty worktree task or PR from a session outside the task. When no target is named, discover open PRs and local worktrees with open Toastty workspaces in the current repository. Assess each task, then perform authorized integration and local task cleanup.

---

# Worktree Done

This example personal skill assesses and, when authorized, lands a task using

its repository's integration and verification rules. The finishing session can

- be a project coordinator or the original parent; the original parent need not

- stay active. The user can name the task or PR without supplying a commit SHA.

+ be the original parent or another session; the original parent need not stay

+ active. The user can name the task or PR without supplying a commit SHA, or omit

+ the target to process the discovered tasks in the current repository.

## Resolve the task and authority

- Require `TOASTTY_CLI_PATH` and `TOASTTY_SESSION_ID`. If absent, stop with

`error: worktree-done must run inside a Toastty-managed agent session`.

Use `toastty-capabilities` to discover the running CLI's supported queries

and actions before controlling sessions or workspaces.

- - Resolve the task using the durable local launch/coordination record,

+ - Resolve the task using the durable local launch record,

`git worktree list --porcelain`, `WORKTREE_HANDOFF.md`, and live

workspace/session metadata.

Match branch and canonical checkout path, then workspace and session IDs;

titles alone are insufficient. Ask only when the target remains ambiguous.

Before controlling local resources, verify the finishing session's workspace

scope. Add only workspaces assigned by the user or this authorized workflow;

a launch record establishes identity, not authority. Respect `scope_denied`.

- For remote-only PRs, review and integrate through the repository workflow

without requiring a local task workspace. Local cleanup is inapplicable when

no task-owned resources exist; do not guess resources from a PR title.

- Resolve the landing branch and its checkout from the user's instruction,

the handoff, and repository rules. Use upstream/default-branch information

as evidence when needed; do not hardcode `main` or assume the task's base

branch is the destination. Honor required PR, CI, review, and merge gates.

- Run integration from a clean landing checkout (or isolated integration

checkout when needed) and cleanup from a finishing session

outside both the target checkout and target workspace. Canonicalize paths

through symlinks and compare directory boundaries, not string prefixes. If

invoked from the child, prepare the readiness handoff and direct the user

- to a coordinator or other finishing session; do not delete the active session

+ to run this skill from another session; do not delete the active session

or expand its workspace scope.

- A request to merge and clean up authorizes both actions; do not ask again

at each step. A merge-only request does not authorize termination or deletion.

A readiness report, finished goal, or passing test does not authorize a merge.

- A review-only request authorizes assessment and a report, not changes to the

task branch, PR state, or child workspace. Do not advance into landing,

evidence archiving for cleanup, process termination, or deletion without the

corresponding authorization. Keep feedback in the finishing report or

- coordination note;

+ task record;

posting PR comments or requesting changes from the child needs authorization

for that action, which may already be part of the task.

+ ## Discover tasks when no target is named

+ - Honor an explicit task, PR, or repository scope. Otherwise infer the repository

+ from the current checkout and Toastty session metadata; ask only if those

+ cannot identify one repository. Do not search all of the user's repositories.

+ - Discover all open PRs in that repository, including additional result pages,

+ and local Git worktrees matched to currently open Toastty workspaces. Use

+ canonical checkout paths and branch/repository identity, not workspace titles.

+ Include local tasks without PRs; an open workspace is discovery evidence, not

+ proof that its task is ready. Exclude the landing checkout from local task

+ candidates. If PR access is unavailable, continue with local discovery and

+ report the access limit rather than treating it as zero open PRs.

+ - Combine both sources into one task list, deduplicating a PR and its matching

+ local worktree. Preserve repository identity for fork PRs; a matching branch

+ name alone does not establish a local resource association. Report uncertain

+ matches without guessing which resources belong to the PR.

+ - Briefly state the discovered scope, then assess every candidate through the

+ workflow below without asking the user to choose one. Discovery does not

+ grant merge, push, session-control, or cleanup authority; apply the user's

+ existing authorization to each task and prepare any remaining approval as

+ one concrete batch. Respect workspace scope and the finishing-session rule;

+ retain a task containing the current session and report its handoff separately.

+ - Use dependencies and overlapping changes to choose an order. Recheck the

+ destination and affected assessments after each integration. Keep blocked,

+ draft, or still-active tasks pending and continue with independent candidates;

+ do not land dependent work past a blocker. End with a result or blocker for

+ every candidate, or state that no candidates were found with any discovery

+ limits. This is one discovery pass, not an ongoing monitor.

## Establish readiness

- Read repository instructions first (`AGENTS.md`/`CLAUDE.md`), then the local

verify skill they name, then relevant build/test docs and CI configuration.

Use those to select and report the required review and checks for this diff.

If no verification guidance exists, choose the smallest meaningful checks

supported by the project and state what remains unverified.

- Read the PR handoff and its review/test evidence, or the durable local task

note when there is no PR. An optional Scratchpad can add visual context but

is not required. Match `ValidatedCommit: <full SHA>` to the source tip. If

evidence is missing or stale, establish the assessed head and complete the

required verification before integration; do not equate “done” with verified.

- For a PR, verify its repository, base branch, head branch, and live head SHA

against the task identity. Integration requires the PR head, any assigned

local task branch tip, and `ValidatedCommit` to agree, with required review

and CI covering that head.

Do not silently choose the newer of conflicting tips. For review-only work,

assess an explicitly identified current commit and label missing or stale

readiness evidence; it need not prevent useful read-only feedback.

- Before integration, coordinate the task owner and recheck the source head.

For an assigned local child, confirm it is idle and will not continue writing.

For local resources, capture the branch tip and worktree status, including

untracked files and content fingerprints for artifacts that will be removed. Status paths alone

cannot detect later edits to an already-untracked handoff.

Preserve uncommitted or unpublished work; never stash, reset, or force it

away. Treat the handoff as an artifact to preserve, not a product change.

- Before integration, check the landing checkout can accept it without mixing

unrelated local changes. Preserve those changes; do not clear them to make room.

Refresh the destination only as the repository requires, without discarding

local commits or bypassing its integration policy.

## Project assessment

Integration requires a completed project assessment of the exact task commit.

Run this pass before merging if no current assessment exists, even when

integration is authorized without a separate review request. It also supports

review-only requests and complements

- repository-required independent review, CI, and human testing.

+ repository-required independent review and CI; human testing follows deployment.

- Review the task diff in the context of existing code: design and ownership

boundaries, established abstractions and naming, duplicate capability,

maintenance cost, API and data contracts, failure handling, security and data

preservation, and missing tests or documentation. Keep mechanical style

checks with existing formatters/linters; explain concrete consequences for

design findings.

- Inspect the intended target branch and relevant open PRs and active worktrees

in the same repository. Use their identified commit heads, prioritizing shared

files, interfaces, data models, configuration, and overlapping product scope.

Record which work was examined and any access or discovery limits; do not

claim compatibility with work you could not inspect.

- Distinguish Git conflicts from semantic incompatibility: changes can merge

cleanly while disagreeing about a contract or expected behavior. Start with

read-only inspection. When a specific interaction cannot be resolved that

way, use a disposable integration worktree for the candidate and the relevant

changes expected to land first, then run focused checks. Record the tested

commits, order, commands, and results. Keep this worktree outside child

workspaces and use detached commits; never stash or change task/landing

checkouts for the experiment. Remove only this disposable worktree when the

checks finish, preserving useful results in the report; report any teardown

failure. This review-owned teardown does not authorize task cleanup. Do not

rebase the children's branches, test every possible combination, or require

a speculative build for every review.

- Report the assessed task/PR head, target SHA, relevant peer SHAs, coverage

limits, blocking findings, optional suggestions, and any recommended merge

order. Unresolved material conflicts or correctness risks block integration;

cosmetic preferences do not become new gates. Keep the report in the durable

- coordination/task record; a Scratchpad can present it. Publish findings on the

+ task record; a Scratchpad can present it. Publish findings on the

PR only when authorized.

- The task owner owns fixes. Return actionable findings to the user and, when

authorized, resume the existing child for accepted corrections. If that agent

is unavailable, arrange an authorized replacement using the PR and task record.

Existing task

authorization can cover routine fixes within scope; review-only requests do

not add permission to initiate edits. Changed code

invalidates readiness; require an updated PR/branch head, affected review and

checks, and revised human-testing evidence where needed. Reassess the changed

areas before landing. Do not silently take over the child's implementation

or expand its task to satisfy an optional suggestion.

- For review-only requests, stop after the report. Before an authorized merge,

recheck the live PR/task head, target branch, and relevant peer heads against

this assessment. A changed task head needs fresh readiness evidence; changes

to the target or related work need an updated conflict/interaction assessment

- and affected checks. Observe repository requirements for human testing and

- approval. No permanent monitoring service is part of this workflow.

+ and affected checks. Observe repository requirements for approval; human testing

+ follows deployment unless the PR names a pre-merge manual check. No permanent monitoring service is part of this workflow.

## Preserve evidence, land, and verify

- Before local cleanup, preserve the task handoff and status note, source identity, PR/review

links and verification evidence in a unique task directory outside the checkout

being removed. Use the repository's ignored artifact location or a durable

directory outside Git; never overwrite an earlier archive. Include canonical

checkout/branch and workspace/session IDs for resources to be removed.

Export any existing linked child Scratchpad while its session link remains.

Absence of a Scratchpad is valid; inability to preserve required evidence is

a reason to retain resources. Keep machine metadata out of public PRs.

- Integrate the validated source commit through the repository's established

merge or PR workflow. Recheck that the source tip and any local task status

have not changed before landing; stop if they have. Do not push or publish

unless authorized.

Resolve conflicts only within the agreed behavior; a material behavior

decision still needs the user.

- Inspect the landed diff for accidental handoff files or other task artifacts.

Validate the actual landed result with the repository's required checks,

including generation/build and runtime checks when applicable. Record the

landed SHA and the exact commands, targets, and results in the durable task

- or coordination record. Earlier child checks do not prove that integration works.

+ record. Earlier child checks do not prove that integration works.

- If validation fails, keep the child workspace, worktree, and branch available

while making authorized, scoped corrections. Do not claim completion merely

because the merge succeeded.

- - Preserve the PR-to-landed-commit correspondence in the coordination record.

- Integration does not prove deployment. If a `project-orchestrator` is tracking

- this work, retain its outstanding release targets after workspace cleanup;

- use the repository release workflow to establish delivery separately.

+ - Preserve the PR-to-landed-commit correspondence in the task record.

+ Integration does not prove deployment. Use the repository release workflow

+ to establish delivery separately.

## Authorized cleanup

Proceed only after integration is verified and cleanup is authorized. If the

user requested only a merge, report its result and leave cleanup pending.

- Recheck the recorded source tip and worktree status before stopping the child.

Any new edits or commits require reconciliation before cleanup. Inventory the

target workspace for other sessions, terminals, unsaved documents, or work

unrelated to this task; leave it open if closing it would discard that work.

- Stop only task-owned development servers or runtime instances using their

recorded identities and repository cleanup instructions. Terminate the actual

child agent process through supported Toastty terminal controls when authorized;

marking a session stopped is bookkeeping, not proof that its process exited.

Follow `toastty-capabilities` closing rules and never override an unsaved

document block. Verify task writers have exited; if the available API only

updates tracking, inspect processes tied to the checkout or retain it.

- Close the task workspace using supported controls once its owned processes

are stopped and documents are saved or archived. Never close the finishing

session's workspace. If the CLI cannot safely perform this step, report it as pending

and retain the worktree rather than inventing a command or broad kill pattern.

- Immediately before filesystem removal, recheck the source SHA and worktree

status and artifact contents against the captured values. Inspect ignored

files too: preserve user data and configuration, and discard only confirmed

disposable build output. Only remove task artifacts that were

archived and unchanged; any other uncommitted or untracked content blocks

deletion. Use `git worktree remove` without `--force`, then `git branch -d`

for the fully merged local branch. Never use `git branch -D`.

- Ancestry proves ordinary merges; squash or rebase requires establishing that

the validated source changes landed using the repository's integration

evidence and diff inspection. If safe branch deletion refuses, leave the

branch and report it. Do not force deletion to make cleanup appear complete.

Report the source and landed SHAs, verification, evidence archive, and which

processes, workspace, worktree, and branch were removed or retained. On partial

failure, report the completed step and remaining work. On a retry, inspect the

recorded landed result first so an already integrated task is not merged again.