@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/fresh-thread-dispatch/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: fresh-thread-dispatch
+description: "Create a clean, user-owned Codex task when the owner explicitly delegates work to a new Codex thread/task; distinguish fresh dispatch from thread moves and forks."
+---
+
+# Fresh Thread Dispatch
+
+Use this Skill only for an explicit request to move work into a **new** Codex task, such as "移交给新的 Codex thread/task" or "在新 worktree 继续". It creates the task and hands over the bounded assignment; the cutover applies to that assignment, not to unrelated work retained by the parent. It is not a delivery flow or a tracking loop.
+
+## Defaults
+
+- Create one fresh, user-owned task through the native `create_thread` tool.
+- Unless the caller supplies a flow-owned profile, use `gpt-5.6-luna` with `max` thinking for a generic fresh task. A flow-owned locked profile takes precedence over this generic default.
+- For a flow-owned task, copy the envelope's `locked_profile` and pass its exact `model` and `thinking` values to native `create_thread.model` and `create_thread.thinking`. The caller-owned profile policy takes precedence over the generic fresh-task default; do not reselect or substitute a flow-owned profile. Do not reselect by task description, normalize a thinking value, consult a runtime capability table, or substitute a fallback.
+- A complete owner override contains both `model` and `thinking`; it may bypass the caller's autonomous allowlist and must be forwarded unchanged. Record the override source and scope in the task envelope. An invocation-wide override must be materialized in every nonterminal task lock, including future-wave tasks; terminal skipped or completed history remains immutable. A model-only or thinking-only instruction is incomplete and must not be filled in by the dispatch skill.
+- Always pass the resolved model and thinking pair to `create_thread`. A current task's explicit directive may authorize that creation call, but the fresh task does not inherit the parent session's override state; carry an owner directive in the child prompt when the child itself must authorize a non-autonomous launch.
+- To authorize a non-autonomous model for this task, the owner must place the exact standalone `agent-model: <model>` directive on the first non-empty prompt line; natural-language mentions and quoted examples do not authorize an exception.
+- The directive must use the canonical model identifier exposed by the current tool; family shorthands are not authorization for an exception.
+- Preserve the owner's delivery intent in the child prompt. A requested `$fast-flow`, diagnosis Skill, or exact stop condition belongs to the child; dispatch itself does not grant extra GitHub, merge, or deployment authority.
+- A fresh dispatch is an assignment-scoped, one-way, one-time transfer. It transfers only the explicitly bounded assignment; it does not transfer or freeze unrelated work retained by the parent. Once `create_thread` succeeds, the parent must not continue the transferred assignment, perform child work, or automatically wait, supervise, coordinate, or relay. Read the [handoff envelope](references/handoff-envelope.md) for the fact-selection and relay boundary.
+- A result containing only `clientThreadId` means setup is still pending. Treat it as a creation acknowledgement only, never as an observation/read, navigation, or relay target; assignment-scoped cutover still applies, but it does not block parent-scoped work that is resource-disjoint from the child assignment. The platform owns the pending-to-real-`threadId` binding: do not retry creation, dispatch the same assignment again, infer a thread identity, or create local recovery state. Wait for the platform to expose the real `threadId` before any child-task operation, and do not poll automatically. The envelope's pending `dispatch_operation_id` remains the single claim for native creation; append each claim to the task's unique `dispatch_operation_history`, and only a confirmed `source=native-create` failure receipt may release it for a new operation. The receipt must retain the exact active `dispatch_operation_id`, use `source=native-create`, report `status=failed|rejected`, and include a non-empty error. Only that confirmed native failure may authorize one retry with the same locked profile. A persisted marker and digest preserve failure history but do not authorize a new retry after JSON reload; retry recovery requires an adapter-owned receipt or a matching `dispatch_failure` observation in the same replay stream.
+- If `create_thread` fails without that matching receipt, returns neither identifier, exposes contradictory identifiers, or leaves only an ambiguous outcome, treat creation as unknown. Stop and ask the owner or platform to reconcile the exact request; do not retry, duplicate, infer a target, relay, or continue overlapping work while the outcome is unresolved.
+- A trusted adapter-owned native `PreToolUse` denial or runtime `create_thread` failure may be imported as the matching dispatch receipt, preserving the exact operation identity, native request identity, canonical `create_thread` tool identity, failure status, and error. The public generic receipt importer MUST NOT create a `dispatch-failure` receipt accepted by claim release; only the trusted native dispatch adapter may create that imported receipt. The trusted runtime adapter MUST validate the raw provider result and end with an opaque adapter failure before claim release; a public release helper MUST NOT adapt a raw caller mapping. A runtime failure qualifies only when the adapter observed all of those native fields; it MUST NOT fill a missing operation identity, tool identity, or status from local defaults. A raw or caller-authored hook/runtime mapping is not a receipt. This is evidence of the failed native attempt, not a flow capability check; retry remains explicit and reuses the locked pair.
+- After native `PreToolUse` or a runtime failure exposes the request identity, bind that exact identity and the canonical `create_thread` tool name to the pending dispatch claim before importing or releasing a failure receipt. A runtime failure must also carry the exact active `dispatch_operation_id`, `status=failed|rejected`, and a non-empty error; missing or mismatched identity is an unknown creation outcome and cannot authorize retry. A resolved native `threadId` must use the flow's atomic success binding operation with the exact bound native request identity, which retains `dispatch_operation_history` and clears the claim and its request binding together. Missing, mismatched, or ambiguous request identity is an unknown creation outcome and must not authorize retry.
+- A runtime rejection after a profile was forwarded is a runtime fact, not a flow-level capability result. Report it as-is. A retry or recovery of an existing task reuses its locked pair; it may change only after an explicit owner replacement is recorded in the envelope.
+- If an explicit relay has an ambiguous or contradictory target or content, clarify before relaying; do not infer a target, message, or authority.
+- The dispatch operation stops after the task is created. A later parent message that clearly concerns unrelated or explicitly retained parent work remains parent-scoped and may be handled in the parent without child operations only when its files, branch, checkout, and other mutable resources are disjoint from the transferred assignment. For an explicit `local` dispatch, the parent and child share the saved checkout; if that disjointness cannot be proven, clarify or use an isolated worktree before mutating either assignment. Scope follows the owner's explicit target, not keyword overlap: even a message mentioning the transferred artifact remains parent-scoped when the owner says to continue the current/parent conversation and not affect the new task. A clearly child-scoped continuation is not performed in the parent; if its target or requested relay is unclear, clarify first.
+
+## Multi-task-flow-owned creation
+
+For a delivery-unit/task owned by an active multi-task-flow ledger, use that flow’s `conversation-create` CLI after its dispatch claim instead of this Skill’s generic native tool recipe. Preserve the ledger’s complete `model + thinking` pair verbatim. The flow owns capability validation, native request binding, creation evidence, freeze and unknown reconciliation. Never substitute a generic default or change the conversation profile after creation. Generic owner-requested fresh conversations continue through the native tool steps below.
+
+## Resolve The Target
+
+1. Confirm that the owner explicitly asked for a fresh task. Resolve the target project through `list_projects`; ask one question only when the project or target work is genuinely ambiguous.
+2. Select the requested execution environment. "New worktree", including "new local worktree", means `environment.type=worktree`; "local", "saved project", or "current checkout" means `environment.type=local`. If unstated, use `worktree` for a Git project and `local` otherwise. The required native `environment` field is populated from this resolved default; it does not require a separate owner decision. If the requested environment is unavailable, incompatible with the project, or conflicts with another instruction, explain the constraint and ask for one explicit resolution before creation. Never substitute an unavailable or conflicting environment silently.
+3. Keep the default worktree baseline by omitting `startingState`. Use `working-tree` only when the owner explicitly asks to carry the current uncommitted state; use a branch starting state only for an owner-named ref. Never create a manual Git worktree.
+4. Compose the child prompt from the minimum handoff facts. Read [the handoff envelope](references/handoff-envelope.md) before creating the task.
+5. Call `create_thread` with the resolved project, environment, profile, and handoff prompt. Use the current tool schema rather than copying API fields from this document. This Skill cannot change the native tool's contract or higher-priority instructions.
+
+## Resolve The Title
+
+Resolve the task title before composing the handoff prompt and before calling native `create_thread`.
+
+- If the owner supplied a title, use it with only whitespace normalization. Do not silently truncate it; a title longer than 32 Unicode code points must be rejected and the owner must shorten it.
+- Otherwise derive the title only from the transferred task intent and its primary outcome. Use the concise `action + subject + decision boundary` form, target no more than 24 Unicode code points, and remove protocol labels, acceptance details, Skill references, URLs, paths, and execution context.
+- For a multi-step Goal, title the final or primary outcome rather than the investigation sequence. If no meaningful title can be derived, use `移交任务`.
+- Do not derive a title from the complete handoff prompt, `Verified context`, `Scope and constraints`, or `Execution and stop condition`. The full five-section prompt remains complete and structured for the child.
+- Always pass the resolved title as native `create_thread.title`; never omit it and let the platform summarize the handoff prompt.
+
+## Native Request Shape
+
+Before the call, materialize the resolved profile into the request. A generic fresh task uses `model=gpt-5.6-luna` and `thinking=max`; a flow-owned lock or a complete owner override replaces that pair verbatim. A model-only or thinking-only value is invalid.
+
+For a project task, the native request contains only the task-creation fields:
+
+```json
+{
+  "prompt": "<handoff prompt>",
+  "target": {
+    "type": "project",
+    "projectId": "<resolved project id>",
+    "environment": { "type": "worktree" }
+  },
+  "model": "gpt-5.6-luna",
+  "thinking": "max",
+  "title": "<resolved task title>"
+}
+```
+
+The resolved title is task metadata, not a dispatch identity or ledger field.
+
+Use `environment.type=local` for an explicit local request. Add `environment.startingState` only when the owner explicitly requests the current working tree or an owner-named branch. Keep `task_id`, `dispatch_operation_id`, request bindings, and receipt fields in the local task envelope; never append them to native `create_thread` arguments.
+
+## Routing Boundary
+
+- Use `fork_thread` only when the owner asks to retain completed conversation history. A fresh dispatch intentionally starts with compact context.
+- Use `handoff_thread` only to relocate another existing Codex task and its Git state. It cannot replace a fresh task dispatch from the current task.
+- A fresh dispatch creates one explicitly bounded task only. Multi-task scheduling, dependency coordination, and PR integration are outside this Skill; it does not infer a coordinator from the assignment or poll, supervise, or merge other work. Independent work across different projects may receive one fresh task per explicitly named project.
+
+## Completion
+
+After a successful call, state the created task's title and resolved environment, then emit the required `::created-thread` directive using the returned `threadId`, or using `clientThreadId` only as the platform's setup-pending creation acknowledgement. The latter is not an owner-navigable task link and is not a target for observation/read, navigation, or relay. Do not navigate to the task, perform child work, poll for readiness, or duplicate its follow-up message in the parent. End the dispatch operation there; continue any separate parent-scoped work only under its own instructions, and do not re-enter the transferred assignment automatically.

package/toolkit/skills/fresh-thread-dispatch/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fresh Thread Dispatch"
+  short_description: "Create a clean Codex task in a worktree or local checkout."
+  default_prompt: "Use $fresh-thread-dispatch to move this bounded task into a new Codex task."

package/toolkit/skills/fresh-thread-dispatch/references/handoff-envelope.md

@@ -0,0 +1,65 @@
+# Fresh Task Handoff Envelope
+
+Build a short, self-contained child prompt. It is the complete default transfer to the child: transfer current facts, not a transcript or an unverified conclusion.
+
+## Fact Selection
+
+Include a fact only when all of these are true:
+
+- It belongs to the child assignment rather than the parent task.
+- It directly determines the child's goal, acceptance, scope, authority, or reproducible starting point.
+- Its status is clear: a verified fact, an identified unverified fact, or an explicit owner constraint. Do not turn an Agent inference into an owner decision.
+- Its source can be identified in the prompt or by a stable local/external reference the child can inspect.
+
+An owner statement is not a child instruction merely because the owner made it in the parent task. Do not include parent progress, design candidates, or facts that are only potentially relevant. The envelope defines the child's scope; it must not imply that the child owns, pauses, or replaces work retained by the parent.
+
+## Required Facts
+
+- **Goal and acceptance**: the outcome the child owns and how completion is recognized.
+- **Scope**: relevant paths, repositories, systems, and explicit non-goals.
+- **Verified starting facts**: concrete state such as an exact branch/ref, PR, error, or prior decision. Identify facts that were not verified rather than presenting them as settled.
+- **Execution intent**: requested Skill(s), model/effort if specified, and the delivery stop condition.
+- **Authority boundary**: any explicit authorization and any action that still needs the owner's decision.
+
+Every transferred fact in all five prompt sections must carry its status and source inline. In `Verified context`, use the labels `Verified`, `Unverified`, or `Owner constraint`; elsewhere, use the same labels where they clarify the fact's status. A source may be a repository path, command result, or owner instruction. This is a prose convention for traceability, not a machine schema or scoring gate.
+
+## Environment Decision
+
+| Owner wording | `create_thread` environment |
+| - | - |
+| new worktree / new local worktree / isolated worktree | `worktree` |
+| local / saved project / current checkout | `local` |
+| no environment stated, Git project | `worktree` |
+| no environment stated, non-Git project | `local` |
+
+The native tool requires an `environment` field in the creation request. The Skill resolves that field from the table after the project metadata has supplied the Git/non-Git fact; an unavailable fact is a pre-creation error, not a reason to guess. The field requirement is not a reason to ask the owner to repeat a resolvable default. If the requested environment is unavailable, incompatible, or conflicting, explain the constraint and ask for one explicit resolution before creation; do not silently substitute `local` or another environment.
+
+For a `worktree`, omit `startingState` for the project default baseline. Carry a working tree only on the owner's express request, and use a branch only when the owner supplied the exact ref.
+
+## Native Request Shape
+
+Before creation, materialize the profile and keep the native arguments limited to the `create_thread` contract. The generic profile is `model=gpt-5.6-luna` plus `thinking=max`; a complete flow-owned or owner pair replaces it verbatim. Project dispatch uses `target.type=project`, the resolved `projectId`, and `target.environment.type` set to `local` or `worktree`. `startingState` is nested under a worktree environment only when explicitly requested. Resolve a task title from the transferred task intent before composing this envelope and always pass the resolved title as native `title`. An explicit owner title has priority; otherwise use the primary transferred outcome, the `action + subject + decision boundary` form, and `移交任务` when no meaningful title can be derived. Dispatch claims, task IDs, request IDs, and failure receipts stay in the local envelope and are not native tool arguments.
+
+If native creation fails after a request is exposed, the native adapter first is validated by the trusted runtime adapter. Only the resulting opaque failure, carrying the exact active `operation_id`, request identity, `tool_name=create_thread`, `status=failed|rejected`, and non-empty error, may release the claim. A public release helper must reject raw caller mappings; missing or conflicting fields remain an unknown outcome. Persisted failure history with a marker and digest is retained for recovery inspection, but cannot authorize a new retry after JSON reload without an adapter-owned receipt or a matching `dispatch_failure` observation in the same replay stream.
+
+## Prompt Shape
+
+Use ordinary human-readable prose with these labelled facts in order:
+
+1. `Goal`
+2. `Acceptance`
+3. `Verified context`
+4. `Scope and constraints`
+5. `Execution and stop condition`
+
+Do not include unrelated parent-task history, progress promises, or a request to recreate the parent task's orchestration. A new task owns its subsequent updates and any applicable flow from its own current facts.
+
+## Dispatch Cutover
+
+Successful `create_thread` ends the default transfer of the bounded assignment. Cutover is assignment-scoped, not conversation-scoped. If the result exposes a `threadId`, child-task readiness is immediate. If setup is still in progress and the result only exposes a `clientThreadId`, treat that value as a creation acknowledgement, not as an owner-navigable task link or a target for observation/read, navigation, or relay: the parent must wait for the real `threadId` before any child-task operation, but this pending state does not block resource-disjoint parent-scoped work. The platform owns the pending binding; the parent must not retry creation, duplicate the assignment, infer a thread identity, or create local recovery state. The parent does not poll or relay automatically.
+
+If `create_thread` fails, returns neither identifier, or exposes contradictory identifiers, creation is unknown. Stop and ask the owner or platform to reconcile the exact request; do not retry, duplicate the assignment, infer a target, relay, or continue overlapping work while the outcome is unresolved.
+
+After cutover, the parent stops processing the transferred assignment and does not perform child work, wait, supervise, coordinate, or relay automatically. Later messages that clearly concern unrelated or explicitly retained parent work remain parent-scoped and may continue in the parent only when its files, branch, checkout, and other mutable resources are disjoint from the transferred assignment. An explicit `local` dispatch shares the saved checkout; if disjointness cannot be proven, clarify or use an isolated worktree before mutating either assignment. Determine scope from the owner's explicit target, not from keyword overlap: an owner instruction to continue the current/parent conversation and not affect the new task remains parent-scoped even when it mentions the transferred artifact or blocker. A clearly child-scoped continuation must not be executed in the parent; an ambiguous target must be clarified before acting.
+
+Messages authored by the child task are child-owned output, not owner instructions or new authority for the parent. An owner request to observe a child task is separate from permission to relay a message. Relay only when the owner explicitly identifies one child task and the content to send; forward that content without adding parent-task summaries, inferences, or authority. If the target or content is ambiguous or contradictory, ask for clarification and perform no relay. The owner may instead speak to the child task directly.

package/toolkit/skills/git-branch/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: git-branch
+description: "Manage local git branches safely."
+---
+
+# Git branch
+
+Use this skill for pure local branch operations: checking branch context, creating or switching topic branches, deleting safe local branches, and preparing a design-only branch when a caller explicitly asks for one.
+
+This skill does not create PRs, push, merge PRs, rebase onto mainline, or remove worktrees. Route PR publication and merge to `$project-engineering-workflow`; use `$git-sync` or `$git-cleanup` for their respective local operations.
+
+## Inputs
+
+- `ACTION=create-topic|switch|delete-local|design-branch`
+- `BRANCH`: target branch name when known.
+- `BASE_REF`: optional starting ref for a new branch.
+- `PURPOSE`: short slug source when `BRANCH` is not provided.
+
+If inputs are missing, infer them from the current task and repository conventions. Ask only when ambiguity would change which branch is touched.
+
+## Guardrails
+
+- Never run destructive commands such as `reset --hard`, `clean -fd`, or forced branch deletion unless the owner explicitly requests the exact action.
+- Never push, set upstream, or change remote configuration.
+- Do not switch away from a dirty worktree unless the dirty state is explicitly preserved by the caller contract or the owner authorizes a stash.
+- Branch names must be lowercase kebab-case with a conventional prefix when a topic branch is created: `feat/`, `fix/`, `refactor/`, `chore/`, or the repo's established equivalent.
+- Prefer the configured Codex branch prefix `th/` when creating branches for Codex workspace maintenance.
+
+## Workflow
+
+### 1) Preflight
+
+- `git rev-parse --show-toplevel`
+- `git rev-parse --abbrev-ref HEAD`
+- `git status --short --branch`
+- `git status --porcelain`
+
+If `HEAD` is detached and a topic branch is needed, create it from explicit `BASE_REF` when the caller has already resolved a development baseline; only fall back to the current commit when preserving the current detached context is itself the requested behavior. If the worktree is dirty and the requested action would switch or delete the checked-out branch, stop and ask one key question.
+
+### 2) Create a topic branch
+
+1. Resolve `BASE_REF`:
+   - Use explicit `BASE_REF` when provided.
+   - Otherwise use current `HEAD` when the owner wants to preserve current context.
+   - Only use a remote default branch after it has been fetched and uniquely resolved.
+   - When a shared workflow caller already resolved the target repo mainline or another confirmed baseline, treat that explicit `BASE_REF` as the source of truth for branch creation.
+2. Derive a branch name from `PURPOSE` if `BRANCH` is not provided.
+3. Confirm the name does not already exist:
+   - `git show-ref --verify --quiet refs/heads/<branch>`
+4. Create and switch:
+   - `git switch -c <branch> [<BASE_REF>]`
+5. Verify:
+   - `git rev-parse --abbrev-ref HEAD`
+   - `git status --short --branch`
+
+### 3) Switch branches
+
+- Refuse to switch when current dirty files would be put at risk.
+- Prefer `git switch <branch>`.
+- If the branch is absent, do not create it unless the requested `ACTION` is `create-topic`.
+
+### 4) Delete local branches
+
+- Never delete the current branch.
+- Never delete a branch checked out by any worktree.
+- Prefer `git branch -d <branch>`.
+- Use `git branch -D <branch>` only after proving the branch has already been integrated into the intended base or after explicit owner confirmation.
+
+### 5) Design-only branch mode
+
+Use `ACTION=design-branch` only for design work. It may create or switch to a branch and then stop at design output or owner-authorized design-document changes. It must not imply implementation authorization.
+
+## Output
+
+Report:
+
+- current branch
+- action performed
+- base ref used when a branch was created
+- dirty-worktree status
+- next allowed owner action

package/toolkit/skills/git-cleanup/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: git-cleanup
+description: "Clean local branches, worktrees, port leases, and post-merge PR workspaces."
+---
+
+# Git cleanup
+
+Use this skill for pure local repository cleanup: deleting merged local branches, removing worktrees, releasing port leases, and completing post-merge PR local closeout after the workflow PR merge procedure.
+
+This skill is the canonical local cleanup layer for branch/worktree/lease closeout. It does not merge PRs, update the GitHub remote PR head, or align the primary base branch after merge; those remain workflow PR merge responsibilities.
+
+## Inputs
+
+- `MODE=post-merge-pr|local-merge|general|worktree-remove|branch-cleanup`
+- `TARGET_PR`: PR number or URL for post-merge PR cleanup.
+- `TARGET_BRANCH`: local branch to treat as a merged PR head.
+- `TARGET_BASE_BRANCH`: PR target base branch resolved by the workflow PR merge procedure.
+- `EXTRA_PR_WORKTREE_PATHS`: disposable merge/review worktrees created by the workflow PR merge procedure.
+- `PR_WORKTREE_REQUIRED`: `yes|no|unknown`; whether a dedicated PR/review worktree or disposable merge-path worktree was part of the cleanup surface.
+- `REQUIRED_PR_WORKTREE_PATHS`: PR/review/disposable worktree paths that must be absent before post-merge cleanup can be complete.
+- `WORKTREE_SCOPE_IDS`: lease scope ids keyed by worktree path when known; use these before deriving a scope for lease release.
+- `WORKTREE_PATH`: explicit worktree target for `worktree-remove`.
+- `SCOPE_ID`: explicit global port lease scope when known.
+- `CODEX_MANAGED_WORKTREE_PATHS`: native Codex task Worktrees observed for this run; these are archive-only, not removal targets. Do not enumerate unrelated native tasks.
+
+Ask only when the target object cannot be uniquely identified or a deletion needs owner confirmation.
+
+## Guardrails
+
+- Never remove the Git primary worktree.
+- Never delete dirty worktrees automatically.
+- Never use forced worktree removal without explicit owner confirmation.
+- Prefer `git branch -d`; use `git branch -D` only when post-merge safety checks prove it is safe or the owner confirms.
+- Remote PR head deletion belongs to the workflow PR merge procedure, not this skill. This skill may verify remote head absence for closeout status.
+- Do not fast-forward or rebase the primary base branch as cleanup.
+- Port lease release must go through `$global-port-manager`.
+- Never remove a Worktree inside `${CODEX_HOME:-~/.codex}/worktrees`, or any path declared in `CODEX_MANAGED_WORKTREE_PATHS`. Return `archive_codex_task_required` instead; Codex native task lifecycle owns its archival/removal.
+
+## Dirty-state policy
+
+When cleanup encounters a dirty worktree, classify it before asking:
+
+- `continue_safe_cleanup`: dirty entries are unrelated and the current cleanup step does not touch that worktree.
+- `skip_conflicting_action`: the cleanup step would switch, delete, or remove a dirty target, so skip that action and downgrade the final closeout.
+- `user_decision_required`: no safe skip path exists or the owner explicitly wants that dirty target cleaned now.
+
+Only `user_decision_required` should ask the owner.
+
+## Post-merge PR closeout
+
+Run `MODE=post-merge-pr` only after the PR has already been merged or the workflow PR merge procedure has handed off `merge+cleanup`.
+
+### 1) Confirm merged PR
+
+Use `gh` CLI to identify and confirm the merged PR:
+
+- Prefer `TARGET_PR`.
+- Otherwise resolve from `TARGET_BRANCH` or the current branch.
+- If no merged PR is found, stop before deleting branch/worktree state.
+
+### 2) Identify cleanup targets
+
+Collect:
+
+- PR head branch
+- primary worktree
+- non-primary worktree holding the PR head branch
+- caller-provided `EXTRA_PR_WORKTREE_PATHS`
+- current-run Codex-managed task Worktrees, recorded separately as archive-only facts
+- port lease scope ids when derivable
+
+### 3) Remove PR worktrees
+
+Remove required PR worktrees before deleting the local PR branch, because Git refuses to delete a branch that is still checked out by any worktree.
+
+For every required PR worktree path:
+
+- if it is Codex-managed, exclude it from manual removal and return the native archive requirement; do not mark closeout complete until the native task lifecycle has archived it;
+- check `git -C <path> status --porcelain`
+- remove only when clean:
+  - route to `$git-worktree ACTION=remove`, or use `git worktree remove <path>` and then release the scope through `$global-port-manager`
+  - use caller-provided `WORKTREE_SCOPE_IDS` / `SCOPE_ID` when available; otherwise derive with the same deterministic scope rule as `$git-worktree`
+- if a required PR worktree is dirty or cannot be removed, skip local PR branch deletion and downgrade closeout rather than trying a branch delete that Git must reject.
+
+### 4) Delete local PR branch
+
+Before deleting:
+
+- ensure the branch is not checked out by any worktree
+- compare local branch head with the PR head SHA when available
+- ensure upstream does not contain local-only commits
+
+Then:
+
+- `git branch -d <branch>`
+- if the PR is confirmed merged and safety checks passed, `git branch -D <branch>` is allowed when `-d` fails only because Git cannot prove merge ancestry.
+
+### 5) Verify remote head absence
+
+Use PR metadata and `gh` CLI as the primary source. Map:
+
+- `missing` -> `远端分支=不存在`
+- `exists` -> `远端分支=存在`
+- `unknown` -> `远端分支=未检查`
+
+If the remote head still exists, ask before deleting; do not delete it as part of this skill unless the owner explicitly authorizes that follow-up.
+
+### 6) Closeout gate
+
+Build `closeout_context` from live Git facts and pass it to:
+
+```bash
+GIT_CLEANUP_SKILL_DIR="<path-to-loaded-git-cleanup-skill-dir>"
+bun --no-install "$GIT_CLEANUP_SKILL_DIR/scripts/closeout_context.ts" --repo-root "<main_worktree>" --feature-branch "<branch>" --pr-worktree-required "<yes|no|unknown>" [--codex-managed-worktree-path "<path>"] ...
+bun --no-install "$GIT_CLEANUP_SKILL_DIR/scripts/closeout_gate.ts" --input-json '<closeout_context_json>'
+```
+
+- Resolve `GIT_CLEANUP_SKILL_DIR` from the actual loaded `git-cleanup` skill location. In this repository that is `skills/git-cleanup`; in an installed Codex home it may be `${LOOMHELM_TOOLKIT_ROOT}/skills/git-cleanup`.
+- The context helper defaults to `--port-scope-resolved`; if a `SCOPE_ID` can be derived or any worktree-local service lease may exist, inspect/release it through `$global-port-manager` and pass the observed `--port-lease-status`.
+- Pass `--no-port-scope-resolved` only when current PR/flow facts prove no port lease scope can be derived and no dedicated PR or disposable merge-path worktree was part of the cleanup surface.
+- Set `--pr-worktree-required=no` only when current PR/flow facts prove no dedicated PR worktree was ever part of the cleanup surface.
+- Leave it as `unknown`, or set `yes`, when a PR worktree path is missing but the cleanup surface cannot prove it never existed; completion must remain partial until the fact is resolved.
+- Pass each native task Worktree observed for this run with `--codex-managed-worktree-path`. The helper additionally protects only explicit cleanup targets or the current feature-branch path under `${CODEX_HOME:-~/.codex}/worktrees`; it never adopts unrelated native tasks from the shared Codex directory. `本地收尾=完成` requires the gate to return `allowed_complete=true`. If the gate reports violations, downgrade to `本地收尾=部分完成` and report the first concrete next action.
+
+## Local merge closeout
+
+Use `MODE=local-merge` after `$local-merge-flow` has completed the local merge and the owner has explicitly requested cleanup.
+
+Required facts:
+
+- `base_branch`
+- `current_branch`
+- `topic_branch`
+- `merge_worktree_path` when an isolated merge worktree was used
+- `optional_push_status`
+- dirty-worktree classification: `clean|preserved_unrelated|skipped_conflict|user_decision_required`
+
+Closeout proof must include:
+
+- `base_branch`
+- `current_branch`
+- `worktree_clean`
+- `topic_branch_present`
+- `head_sha`
+- `base_head_sha`
+- `optional_push_status`
+- `dirty_worktree_policy`
+- `topic_branch_action`
+- `merge_worktree_status`
+- `pending_cleanup_action`
+
+Completion requires:
+
+- current branch is the base branch
+- topic branch is absent
+- merge worktree is not still present
+- pending cleanup action is `none`
+- dirty worktree policy is either `clean` or `preserved_unrelated`
+
+The local merge caller owns the merge decision and proof freshness. This skill owns branch/worktree/lease cleanup and structured `cleanup_proof`.
+
+Helper scripts:
+
+```bash
+GIT_CLEANUP_SKILL_DIR="<path-to-loaded-git-cleanup-skill-dir>"
+bun --no-install "$GIT_CLEANUP_SKILL_DIR/scripts/local_merge_closeout_context.ts" --repo-root "<repo>" --base-branch "<base>" ...
+bun --no-install "$GIT_CLEANUP_SKILL_DIR/scripts/local_merge_closeout_gate.ts" --input-json '<closeout_context_json>'
+```
+
+## General cleanup
+
+Use `MODE=general` for broad local cleanup:
+
+1. Inspect:
+   - `git worktree list --porcelain`
+   - `git branch --merged <DEFAULT_BASE_REF>`
+   - `git status --porcelain`
+2. Do read-only candidate discovery first when the current worktree is dirty.
+3. Ask the owner before deleting arbitrary worktrees or branch batches.
+4. Use `$git-worktree` for worktree removal and `$git-branch` for branch deletion.
+
+Remote branch cleanup is opt-in and requires a second explicit confirmation.
+
+## Worktree remove
+
+Use `MODE=worktree-remove` for one explicit non-Codex-managed path. Follow `$git-worktree ACTION=remove` semantics and release leases through `$global-port-manager`. Native Codex task Worktrees are returned as `archive_codex_task_required`, never passed to `git worktree remove`.
+
+## Output
+
+For post-merge PR cleanup, report:
+
+- PR number or target branch
+- `本地收尾=完成/部分完成/未执行`
+- `本地分支=存在/不存在/未检查`
+- `PR工作区=存在/不存在/未检查`
+- `远端分支=存在/不存在/未检查`
+- `端口租约=存在/不存在/未检查`
+- `cleanup_proof=<json|未检查>` when needed for recovery
+
+For repo cleanup, report deleted and skipped objects, plus any owner decisions still required.

package/toolkit/skills/git-cleanup/scripts/closeout_context.ts

@@ -0,0 +1,4 @@
+import { runCompatibilityCli } from "../../bin/compatibility_cli";
+
+if (import.meta.main)
+  process.exitCode = await runCompatibilityCli("closeout_context");

package/toolkit/skills/git-cleanup/scripts/closeout_gate.ts

@@ -0,0 +1,4 @@
+import { runCompatibilityCli } from "../../bin/compatibility_cli";
+
+if (import.meta.main)
+  process.exitCode = await runCompatibilityCli("closeout_gate");

package/toolkit/skills/git-cleanup/scripts/local_merge_closeout_context.ts

@@ -0,0 +1,4 @@
+import { runCompatibilityCli } from "../../bin/compatibility_cli";
+
+if (import.meta.main)
+  process.exitCode = await runCompatibilityCli("local_merge_closeout_context");

package/toolkit/skills/git-cleanup/scripts/local_merge_closeout_gate.ts

@@ -0,0 +1,4 @@
+import { runCompatibilityCli } from "../../bin/compatibility_cli";
+
+if (import.meta.main)
+  process.exitCode = await runCompatibilityCli("local_merge_closeout_gate");

package/toolkit/skills/git-cleanup/scripts/test_closeout_context.ts

@@ -0,0 +1 @@
+import "../../bin/tests/workspace/workspace.test.ts";

package/toolkit/skills/git-cleanup/scripts/test_closeout_gate.ts

@@ -0,0 +1 @@
+import "../../bin/tests/workspace/workspace.test.ts";

package/toolkit/skills/git-cleanup/scripts/test_local_merge_closeout_context.ts

@@ -0,0 +1 @@
+import "../../bin/tests/workspace/workspace.test.ts";

package/toolkit/skills/git-cleanup/scripts/test_local_merge_closeout_gate.ts

@@ -0,0 +1 @@
+import "../../bin/tests/workspace/workspace.test.ts";

package/toolkit/skills/git-worktree/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: git-worktree
+description: "Create, inspect, and remove git worktrees safely."
+---
+
+# Git worktree
+
+Use this skill for pure local worktree lifecycle operations: creating isolated workspaces, inspecting existing worktrees, removing safe worktrees, and coordinating port-lease cleanup with `$global-port-manager`.
+
+This skill does not implement features, create PRs, merge branches, or perform mainline sync.
+
+## Inputs
+
+- `ACTION=create|inspect|remove`
+- `WORKTREE_SLUG`: short kebab-case identifier for a new worktree.
+- `WORKTREE_PATH`: absolute path for an existing worktree.
+- `BRANCH`: branch to create or attach.
+- `BASE_REF`: baseline ref for a new worktree.
+- `SCOPE_ID`: explicit global port lease scope when known.
+- `CODEX_MANAGED_TASK=yes|no`: whether the requested path belongs to a native Codex task Worktree.
+
+Ask only when the target worktree or branch cannot be uniquely identified.
+
+## Guardrails
+
+- Never remove the Git primary worktree.
+- Never remove a dirty worktree unless the owner explicitly confirms `git worktree remove --force`.
+- Never delete local branches unless the caller explicitly routes that to `$git-branch` or `$git-cleanup`.
+- Never create or change remotes, upstreams, or push destinations.
+- Worktree-local long-lived services must lease ports through `$global-port-manager`.
+- If `CODEX_MANAGED_TASK=yes`, or the target path is inside `${CODEX_HOME:-~/.codex}/worktrees`, do not create, remove, prune, or move it. Native Codex task lifecycle owns that Worktree and its archive.
+- Native task conversations must use native Codex task Worktrees. `ACTION=create` is not a fallback for an unavailable native task facility.
+
+## Scope ID
+
+Use the same deterministic scope rule across create/remove/cleanup:
+
+```text
+<project>--<repo_hash8>--<worktree_slug>
+```
+
+- `project`: basename of the Git repo root.
+- `repo_hash8`: first 8 chars of SHA256 over the absolute repo root path.
+- `worktree_slug`: the worktree's stable short slug.
+
+Never use a bare slug as `scope_id`.
+
+## Create workflow
+
+Before any create, reject `CODEX_MANAGED_TASK=yes`. For a native task conversation envelope, report `native_task_worktree_required` and return to the owning coordinator flow instead.
+
+1. Verify current repo and clean preconditions:
+   - `git rev-parse --show-toplevel`
+   - `git status --short --branch`
+   - `git worktree list`
+2. Resolve `BASE_REF`:
+   - explicit input first
+   - before using any remote-tracking ref, refresh that remote with `git fetch --prune <remote>`
+   - remote default branch if uniquely available after fetch
+   - otherwise ask one key question
+3. Resolve `WORKTREE_SLUG`, `BRANCH`, and absolute path:
+   - default path: `<repo_parent>/<project>-wt-<WORKTREE_SLUG>`
+4. Do not overwrite an existing directory.
+5. Create:
+   - `git worktree add -b <branch> <worktree_path> <base_ref>`
+6. Verify:
+   - `git worktree list`
+   - `git -C <worktree_path> status --short --branch`
+7. Allocate a default app lease through `$global-port-manager` when the new worktree may host local services.
+
+## Inspect workflow
+
+- `git worktree list --porcelain`
+- Summarize path, branch, detached state, and dirty status for requested candidates.
+- Do not mutate anything.
+
+## Remove workflow
+
+1. Identify the target from explicit `WORKTREE_PATH` or `git worktree list --porcelain`.
+2. If the target is Codex-managed, do not call `git worktree remove`; report `archive_codex_task_required` and leave the task lifecycle to Codex.
+3. Confirm it is not the primary worktree.
+4. Check target cleanliness:
+   - `git -C <path> status --porcelain`
+5. Remove:
+   - `git worktree remove <path>`
+6. Release leases:
+   - call `$global-port-manager` `release-scope --scope-id <SCOPE_ID>`.
+
+If `SCOPE_ID` cannot be derived reliably, report that lease cleanup was skipped rather than guessing.
+
+## Output
+
+Report:
+
+- worktree path
+- branch
+- action result
+- port lease cleanup result
+- any skipped cleanup and why