@homericintelligence/athena-opencode 0.4.4 → 0.5.1

package/skills/finalize-plan/SKILL.md

@@ -1,129 +1,237 @@
 ---
 name: finalize-plan
 license: BSD-3-Clause
-description: Materialize one exact, actor-owned, GO-reviewed issue-planning epoch into its implementation-facing issue body. Use after plan-issue and issue-review approve a plan; `--draft` is read-only and every missing, foreign, stale, ambiguous, or unverifiable input fails closed.
+description: Create an issue body after `plan-issue` and `issue-review` approve one exact actor-owned epoch with `GO`. `--draft` is read-only. Stop if an input is missing, foreign, stale, ambiguous, or not verifiable.
 argument-hint: "[--draft] ISSUE_NUMBER_OR_URL"
 allowed-tools: [Read, Bash, Grep, Glob]
 ---
 
 # Finalize an approved issue plan
 
-Why: an approved plan should be the readable implementation entry point without
-turning review history, suggestions, or a generated body into new requirements.
-
-Use the shared [issue-planning contract](../../docs/review/issue-planning.md),
-[review contract](../../docs/review/common.md),
-[design-document structure](../../docs/review/design-docs.md),
-[language routing](../../docs/review/language-routing.md), and
-[behavior-first testing](../../docs/review/behavior-first-testing.md).
+Purpose: Make the approved plan the implementation entry point. Do not convert review history,
+suggestions, or generated text into requirements.
+
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to all
+prose that it produces.
+
+Use the shared [issue-planning contract](../_support/docs/review/issue-planning.md),
+[review contract](../_support/docs/review/common.md),
+[design-document structure](../_support/docs/review/design-docs.md),
+[language routing](../_support/docs/review/language-routing.md), and
+[behavior-first testing](../_support/docs/review/behavior-first-testing.md).
+
+## Engineering principles
+
+Use the canonical [engineering-principles catalog](../_support/docs/principles/README.md) to make these
+finalization decisions:
+
+- [P010 Scope Fidelity](../_support/docs/principles/README.md#p010): Change only the issue body and the two
+  sealed, actor-owned comments for the verified epoch.
+- [P061 Separate Decision from High-Impact Execution](../_support/docs/principles/README.md#p061): Before a
+  write, make sure that the epoch and authority agree with this skill's delivery contract.
+- [P062 Human Approval for Irreversible or High-Risk Actions](../_support/docs/principles/README.md#p062):
+  If the delivery contract gives authority for the write, continue without a second approval.
+- [P063 Requirement-to-Code Traceability](../_support/docs/principles/README.md#p063): Map each source
+  requirement to the issue body without information loss.
+- [P065 Verify Before Claiming Completion](../_support/docs/principles/README.md#p065): Before you report
+  that finalization is completed, read the issue body. Make sure that it is the same as the approved
+  body.
+- [P044 Atomicity Where Possible](../_support/docs/principles/README.md#p044): Use one body update for the
+  replacement.
+- [P083 Irreversible Actions Last](../_support/docs/principles/README.md#p083): Do not remove an applicable
+  comment before you verify the body update.
+- [P031 Propagate Rather Than Swallow](../_support/docs/principles/README.md#p031): Report each partial or
+  unknown outcome. Do not report a different outcome. Do not automatically retry the update.
 
 ## Scope and delivery
 
-`--draft` is read-only. Without it, this skill may replace the resolved issue
-body once and, only after exact body readback, delete the two sealed,
-actor-owned plan and review comments. It must not update the title, labels,
-assignment, milestone, project fields, state, branches, pull requests, or
-repository files. The finalized body retains the required provenance after
-those intermediate comments are removed.
-
-Use the forge's native issue-body mechanism. If the host cannot authenticate the
-actor, enumerate and delete exact comments, read the issue body, compare
-identities, or make and read back one exact body update, return a
-ready-to-publish draft and identify the capability gap. Never create, adopt,
-edit, or replace plan or review comments to make finalization possible.
+`--draft` is read-only. If you do not use `--draft`, first revalidate the authority and target under
+[P061 Separate Decision from High-Impact Execution](../_support/docs/principles/README.md#p061). This skill
+can then replace the resolved issue body one time. Only after an exact body readback, it can delete
+the two sealed, actor-owned plan and review comments. Do not update these items:
+
+- title;
+- labels;
+- assignment;
+- milestone;
+- project fields;
+- state;
+- branches;
+- pull requests; or
+- repository files.
+
+After the skill removes the intermediate comments, the finalized body must retain the required
+provenance.
+
+Use the forge's native issue-body mechanism. The host must have these capabilities:
+
+- authenticate the actor;
+- enumerate exact comments;
+- delete exact comments;
+- read the issue body;
+- compare identities;
+- make one exact body update; and
+- read back that body update.
+
+If one capability is not available, return a ready-to-publish draft. Identify the capability gap.
+Do not create plan or review comments to make finalization possible. Do not adopt plan or review
+comments for this purpose. Do not edit plan or review comments for this purpose. Do not replace plan
+or review comments for this purpose.
 
 ## Finalized planning epoch
 
-An epoch has these sealed source identities:
+A planning epoch is one set of these sealed source identities:
 
-- `R`: the canonical digest of the original issue requirements: exact issue ID,
-  title, body, and acceptance criteria before finalization;
-- `P`: one actor-owned `<!-- athena:plan-issue -->` comment ID and canonical
-  plan-content digest; and
-- `V`: one actor-owned `<!-- athena:issue-review -->` comment ID and
-  review-content digest.
+- `R` is the canonical digest of the original issue requirements. It contains the exact issue ID,
+  title, body, and acceptance criteria before finalization.
+- `P` identifies one actor-owned `<!-- athena:plan-issue -->` comment ID and its canonical plan-content
+  digest.
+- `V` identifies one actor-owned `<!-- athena:issue-review -->` comment ID and its review-content
+  digest.
 
-The review must embed and exactly match the same issue, `R`, plan-comment ID,
-and `P`. It must have an exact `GO` disposition with no unresolved `critical`,
-`major`, or other `required` finding. A conditional, partial, malformed, stale,
-foreign, duplicated, absent, or unverifiable artifact is not authorization.
+The review must contain the same issue, `R`, plan-comment ID, and `P`. These values must match
+exactly. The review must have the exact `GO` disposition. It must not have an unresolved `critical`,
+`major`, or other `required` finding. Do not write if an artifact is conditional, partial,
+malformed, stale, foreign, duplicated, absent, or not verifiable.
 
-The rendered body records exactly one marker:
-`<!-- athena:finalize-plan R=<R> P=<P> V=<V> F=<F> -->`. Define `F` by hashing
-the final body after replacing that marker's `F` value with the literal
-`<F>` placeholder; do not hash a marker containing its own digest. The marker
-lets a host distinguish sealed source identities from the generated body and
-verify later readback without recursion.
+Record exactly one marker in the rendered body:
+`<!-- athena:finalize-plan R=<R> P=<P> V=<V> F=<F> -->`. Before you calculate `F`, use the literal
+`<F>` placeholder as the marker's `F` value. Calculate `F` from the final body. Do not calculate a
+digest from a marker that contains its own digest. The marker identifies the sealed source
+identities separately from the generated body. It also permits later readback verification without
+recursion.
 
 ## Finalize
 
-1. Resolve one exact issue, including node or URL, title, body, state, and
-   authenticated actor. Enumerate every current comment before interpreting a
-   marker.
-2. Resolve exactly one actor-owned plan marker and one actor-owned review marker.
-   Compute `R`, `P`, and `V`, then verify the review's embedded bindings and
-   clean GO result. Any ownership, multiplicity, binding, disposition, or
-   required-finding failure returns no write.
-3. Build a compact, lossless synthesis. Lead with **Why** (the preserved
-   original problem, outcome, and non-negotiable requirements), then include a
-   compact system-shape diagram only when it makes at least three relationships,
-   boundaries, or state transitions materially clearer. Follow with architecture
-   breakdown, implementation plan, operations, and provenance.
-4. Preserve every acceptance criterion, implementation boundary, validation,
-   migration or cutover step, rollback condition, dependency, residual risk, and
-   out-of-scope decision. Record review suggestions as optional residual context
-   unless the reviewed canonical plan already adopted them. Do not invent files,
-   commands, requirements, architecture, implementation results, or validation
-   evidence; do not copy historical revision transcripts or duplicate the plan
-   and review verbatim when a smaller lossless synthesis suffices.
-5. Add the finalized marker and compute `F` over its non-self-referential
-   canonical representation. In `--draft`, return the complete body, `R/P/V/F`,
-   source links, and all withheld-write reasons without invoking a forge write.
-6. Immediately before publication, resolve the issue, actor, every comment and
-   marker, `R/P/V`, review disposition, and target body again. If any input
-   drifted, return the ready-to-publish body as stale; do not write.
-7. Publish exactly one issue-body replacement. Read the issue back immediately
-   and verify the exact body, marker, `R/P/V`, and `F`. A timeout, indeterminate
-   response, or mismatched readback is an unknown outcome: do not retry or make
-   another mutation.
-8. After successful body readback, re-read each sealed comment by its exact ID,
-   actor, marker, and digest, then delete the plan comment and review comment.
-   Delete no foreign, replacement, or drifted comment. A failed, timed-out, or
-   indeterminate deletion is a partial-cleanup unknown outcome: do not retry,
-   compensate, or remove the finalized body; report the surviving identities.
-
-## Re-finalization and restart
-
-If the live body exactly verifies its finalized marker and both sealed comments
-are absent, re-running for that epoch returns a documented no-change result. A
-surviving sealed comment is partial cleanup, not authorization to retry a prior
-deletion. If the marker is absent, malformed, foreign, or its canonical `F` does
-not match, the epoch is not valid evidence. A later material human edit is a new
-requirements state and must pass a fresh `plan-issue` plus `issue-review` cycle
-before another finalization. Do not treat generated plan text or provenance
-fields as newly authored requirements.
+1. Resolve one exact issue with its node or URL, title, body, state, and authenticated actor.
+2. Before you interpret a marker, enumerate each current comment.
+3. Resolve exactly one actor-owned plan marker.
+4. Resolve exactly one actor-owned review marker.
+5. Calculate `R/P/V`.
+6. Verify the review bindings and the clean `GO` result.
+7. If ownership, multiplicity, binding, disposition, or required-finding verification fails, do not
+   write.
+8. Build a compact and lossless final body.
+9. Apply [P001 KISS — Keep It Simple, Stupid](../_support/docs/principles/README.md#p001) only to the
+   sealed content.
+10. Make the presentation simple.
+11. Do not remove a requirement.
+12. Do not change the meaning of the approved architecture.
+13. Start the final body with **Why**.
+14. Preserve the original problem, outcome, and requirements that cannot change.
+15. If a system diagram makes at least three relationships, boundaries, or state transitions
+    clearer, include it.
+16. Include the architecture description, implementation plan, operations, and provenance.
+17. Preserve all items in this list:
+
+   - acceptance criteria;
+   - implementation boundaries;
+   - validation;
+   - migration or cutover steps;
+   - rollback conditions;
+   - dependencies;
+   - residual risks; and
+   - out-of-scope decisions.
+
+18. Unless the reviewed canonical plan adopted a review suggestion, record the suggestion as optional
+    residual context.
+19. Do not invent files, commands, requirements, architecture, implementation results, or validation
+    evidence.
+20. If a smaller lossless result is sufficient, do not copy historical revision transcripts.
+21. If a smaller lossless result is sufficient, do not duplicate the plan and review verbatim.
+22. Add the finalized marker.
+23. Calculate `F` from its canonical representation that does not contain its own value.
+24. If the user selects `--draft`, return the complete body, `R`, `P`, `V`, `F`, and source links.
+25. For `--draft`, return all reasons for withheld writes.
+26. For `--draft`, do not make a forge write.
+27. Immediately before publication, apply
+    [P061 Separate Decision from High-Impact Execution](../_support/docs/principles/README.md#p061).
+28. For this check, resolve the issue, actor, each comment and marker, `R`, `P`, `V`, review
+    disposition, and target body again.
+29. If an input changed, return the ready-to-publish body with the `stale` status.
+30. After an input changes, do not write.
+31. Under [P044 Atomicity Where Possible](../_support/docs/principles/README.md#p044), publish exactly one
+    issue-body replacement.
+32. Immediately read the issue again.
+33. Under [P065 Verify Before Claiming Completion](../_support/docs/principles/README.md#p065), verify the
+    exact body, marker, `R`, `P`, `V`, and `F`.
+34. If a timeout, indeterminate response, or readback mismatch occurs, report `unknown-outcome`.
+35. After a timeout, indeterminate response, or readback mismatch, do not retry.
+36. After a timeout, indeterminate response, or readback mismatch, do not make another mutation.
+37. Only after a successful body readback, use
+    [P083 Irreversible Actions Last](../_support/docs/principles/README.md#p083) to read each sealed comment
+    again.
+38. Verify the exact ID, actor, marker, and digest of each sealed comment.
+39. Delete the plan comment only after its exact verification.
+40. Delete the review comment only after its exact verification.
+41. Do not delete a foreign, replacement, or changed comment.
+42. If deletion fails, times out, or has an indeterminate result, report `partial-cleanup`.
+43. State that an indeterminate deletion result is unknown.
+44. After a deletion failure, timeout, or indeterminate result, do not retry.
+45. After a deletion failure, timeout, or indeterminate result, do not compensate.
+46. After a deletion failure, timeout, or indeterminate result, do not remove the finalized body.
+47. After a deletion failure, timeout, or indeterminate result, report the identities of the comments
+    that remain.
+
+If the final material contains architecture, test, error, or security decisions, preserve the
+reviewed use of these principles:
+
+- [P015 Architecture Conformance](../_support/docs/principles/README.md#p015);
+- [P022 Test Behavior, Not Implementation](../_support/docs/principles/README.md#p022);
+- [P029 Generalize Error Policy; Preserve Specific Cause](../_support/docs/principles/README.md#p029); and
+- [P048 Secure by Design](../_support/docs/principles/README.md#p048).
+
+Finalization does not reopen these decisions. Do not make new decisions.
+
+## Finalize again or restart
+
+If the live body verifies its finalized marker exactly and both sealed comments are absent, a second
+run returns a documented `no-change` result. If a sealed comment remains, report
+`partial-cleanup`. Its presence does not authorize another deletion attempt. If the marker is absent,
+malformed, foreign, or has a canonical `F` mismatch, do not use the epoch as evidence. A later
+substantive edit by a person creates a new requirements state. Before another finalization, this new
+state must pass a new `plan-issue` and `issue-review` cycle. Do not treat generated plan text or
+provenance fields as new requirements from a person.
 
 ## Behavior-first verification
 
-Use controlled issue, comment, actor, and forge fixtures to demonstrate:
+Use controlled issue, comment, actor, and forge fixtures to demonstrate these behaviors:
+
+- A clean `GO` plan and review epoch preserves requirements and operational details.
+- `--draft` returns the body without a forge mutation.
+- Publication makes one body update. It verifies the exact readback. Then it deletes only the two
+  sealed actor-owned comments.
+- A sealed epoch that did not change is idempotent.
+- Each absent, foreign, duplicate, mismatched, stale, `NO-GO`, required-finding, drift,
+  unsupported-write, timeout, readback-mismatch, or deletion-uncertainty case stops before an unsafe
+  mutation or retry.
+
+Verify the identities and order classes. Verify content preservation and the number and scope of
+mutations. Verify that failures occur before a write. Do not make tests depend on editorial wording,
+headings, paragraph counts, or an example issue body.
 
-- one clean GO plan/review epoch preserves requirements and operational details;
-- `--draft` returns the body without a forge mutation;
-- publish performs one body update, verifies its exact readback, then deletes
-  only the two sealed actor-owned comments;
-- an unchanged sealed epoch is idempotent; and
-- every absent, foreign, duplicate, mismatched, stale, NO-GO, required-finding,
-  drift, unsupported-write, timeout, readback-mismatch, or deletion-uncertainty
-  case fails before an unsafe mutation or retry.
+## Failed approaches
 
-Assert identities, ordering classes, preservation, mutation count and scope, and
-failure-before-write behavior. Do not freeze editorial wording, headings,
-paragraph counts, or an example issue body.
+- Do not finalize an epoch again without a new request or a new requirements state.
+- Do not treat generated plan text or sealed provenance fields as new executable requirements from
+  a person.
+- Do not replace behavior-first verification with wording checks. Do not invent files, commands, or
+  validation evidence during synthesis.
+- After a timeout or readback mismatch, do not retry. Report `unknown-outcome`.
+- After an indeterminate deletion, do not retry. Report `partial-cleanup`. State that the deletion
+  result is unknown.
 
 ## Result
 
-Return the issue and actor identities; `R/P/V/F`; GO decision and finding
-summary; requirement-preservation map; draft, no-change, published, stale,
-partial-cleanup, or unknown-outcome status; body-update receipt, readback
-evidence, deleted-comment receipts when present; and every unresolved capability
-or residual risk.
+Return these items:
+
+- issue and actor identities;
+- `R/P/V/F`;
+- the `GO` decision and finding summary;
+- the requirement-preservation map;
+- the exact `draft`, `no-change`, `published`, `stale`, `partial-cleanup`, or `unknown-outcome`
+  status;
+- the body-update receipt;
+- readback evidence;
+- deleted-comment receipts, if present; and
+- each unresolved capability or residual risk.

package/skills/git-worktrees/SKILL.md

@@ -1,112 +1,161 @@
 ---
 name: git-worktrees
 license: BSD-3-Clause
-description: Use when starting feature work that needs isolation from current workspace — creates isolated git worktrees with safety verification
+description: Use for feature work that needs an isolated Git worktree. If Git does not ignore a project-local directory, use the verified temporary-directory fallback. If repository guidance requires the local directory, report the problem. In that case, stop before creation. If the helper cannot verify a clean base commit, report the problem. In that case, stop before creation. Do not delete anything.
 argument-hint: <branch-name or feature description>
 allowed-tools: [Bash, Read]
 ---
 
-# Using Git Worktrees
+# Use Git worktrees
 
 ## Overview
 
-Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
-
-**Core principle:** Systematic directory selection + safety verification = reliable isolation.
-
-**When NOT to use this skill manually:** The `myrmidon-swarm` skill owns worktree creation for its
-background subagents. Use this skill for manual development work, not to duplicate swarm setup.
-
-## Directory Selection
+Git worktrees are isolated workspaces that share one repository. You can work on multiple branches
+at the same time. You do not have to switch the active branch.
+
+Apply the [ASD-STE100 technical-English policy](../TECHNICAL_ENGLISH.md) to this skill and to all
+prose that it produces.
+
+**Rule:** Select the directory systematically. Then complete the safety checks. These actions give
+reliable isolation.
+
+**Do not use this skill for `myrmidon-swarm` worktrees.** That skill creates worktrees for its
+background subagents. Use this skill for manual development work.
+
+## Engineering principles
+
+Use the [canonical engineering-principles catalog](../_support/docs/principles/README.md) for these
+workflow-specific rules:
+
+- [P010 — Scope Fidelity](../_support/docs/principles/README.md#p010): Make only the requested isolated
+  branch and worktree. Delegate cleanup and unrelated changes to the applicable workflows.
+- [P012 — Evidence Before Modification](../_support/docs/principles/README.md#p012): Before creation,
+  examine repository guidance, the selected base revision, directory state, ignore rules, and
+  baseline checks.
+- [P021 — Evolutionary and Reversible Design](../_support/docs/principles/README.md#p021): Put feature work
+  in an isolated worktree at the selected base commit. Only if you have user authority and can use
+  the cleanup workflow, remove the worktree.
+- [P033 — State-Safe Failure Semantics](../_support/docs/principles/README.md#p033): If validation is not
+  satisfactory, stop before creation. If setup or a test after creation is not satisfactory, keep
+  the worktree.
+- [P053 — Validate at Trust Boundaries](../_support/docs/principles/README.md#p053): Use the tested helper
+  to validate branch, base, path, and path-root values. Do not use these values in a Git command
+  without the helper.
+- [P058 — Bounded Agent Authority](../_support/docs/principles/README.md#p058): Make only the named branch
+  and worktree for the requested feature. Use the selected start commit and validated destination.
+- [P065 — Verify Before Claiming Completion](../_support/docs/principles/README.md#p065): Before you report
+  that you prepared the worktree, do the repository checks for a clean baseline. Report the path
+  and start commit.
+- [P083 — Irreversible Actions Last](../_support/docs/principles/README.md#p083): Before creation, complete
+  the dry-run. Before creation, complete the safety validation. Use `tidy` for removal.
+
+## Select the directory
 
 Follow this priority order:
 
-### 1. Check Existing Directories
+### 1. Check existing directories
 
 The tested `scripts/prepare_worktree.py` helper checks `.worktrees` and then `worktrees`. If both
-exist, `.worktrees` wins.
+directories exist, the helper selects `.worktrees`.
 
 ### 2. Check repository guidance
 
-Read `AGENTS.md` and its referenced repository guidance. If a preference is specified, pass it to
-the helper with `--directory DIRECTORY`.
+Read `AGENTS.md` and its referenced repository guidance. If repository guidance specifies a
+preference, pass it to the helper with `--directory DIRECTORY`.
 
 ### 3. Portable default
 
-When no repository preference exists, use the host's temporary directory from
-`tempfile.gettempdir()` with `<project>-<branch>`. This is commonly `/tmp` on Unix-like hosts and
-avoids polluting the project directory.
+If the repository does not specify a location, use the host temporary directory from
+`tempfile.gettempdir()` with `<project>-<branch>`. On Unix-like hosts, this directory is usually
+`/tmp`. This location keeps the worktree outside the project directory.
 
 The helper computes the project name from the repository root.
 
-## Safety Verification
+## Verify safety
 
-### For Project-Local Directories (.worktrees or worktrees)
+### For project-local directories
 
-**MUST verify directory is ignored before creating worktree.** The helper fails closed when its
-project-local directory is not ignored.
+Before you create a project-local worktree, verify that Git ignores its directory. If Git does not
+ignore the directory, the helper stops before it makes a change.
 
-**If NOT ignored:**
+#### If Git does not ignore the directory
 
-1. Add `.worktrees/` to `.gitignore`
-2. Commit the change
-3. Then proceed with worktree creation
+1. Do not edit `.gitignore`.
+2. Do not commit `.gitignore`.
+3. Do not create the project-local worktree.
+4. If repository guidance requires the project-local directory, report the ignore-policy
+   prerequisite.
+5. If repository guidance requires the project-local directory, stop.
+6. Change `.gitignore` only in a separate authorized change.
+7. After that change is validated and committed, prepare the worktree again.
+8. If repository guidance does not require the project-local directory, get `<temporary-root>` from
+   the host.
+9. Give preference to a safe temporary destination.
+10. Pass `--path <temporary-root>/<project>-<branch>` and `--path-root <temporary-root>` to the helper.
+11. Report the fallback path.
 
-**Why critical:** Prevents accidentally committing worktree contents to repository.
+This check prevents Git from tracking the worktree contents.
 
-### For /tmp Locations
+### For `/tmp` locations
 
-No `.gitignore` verification needed — outside the project entirely.
+You do not have to verify `.gitignore` for a path under `/tmp`. This path is outside the project.
 
-## Creation Steps
+## Create the worktree
 
-1. Resolve and record the intended base commit SHA.
-2. Keep the target repository as the current working directory. Resolve `scripts/prepare_worktree.py`
-   against this installed skill directory and invoke that absolute helper path with
-   `BRANCH_NAME --start-point BASE_SHA --dry-run`. For a contract requiring a distinct branch and
-   path, also pass exact `--path` and `--path-root` values.
-3. Create it with the same arguments without `--dry-run`, optionally supplying the documented
-   repository preference through `--directory`. Never replace the recorded SHA with ambient HEAD.
-4. Change to the returned path and run the repository-defined bootstrap when one exists.
-5. Verify a clean baseline with the repository-defined tests and report the path, start SHA, and result.
+1. Resolve the intended base commit SHA.
+2. Record the intended base commit SHA.
+3. Keep the target repository as the current working directory.
+4. Resolve `scripts/prepare_worktree.py` from this installed skill directory.
+5. Prepare `BRANCH_NAME --start-point BASE_SHA --dry-run` as the helper arguments.
+6. If the contract requires a distinct branch and path, add exact `--path` and `--path-root` values.
+7. If repository guidance specifies a directory, add it through `--directory`.
+8. If an unignored local directory requires the temporary fallback, retain the exact `--path` and
+   `--path-root` values.
+9. For this fallback, use those values for both helper calls.
+10. Invoke the helper by its absolute path with the prepared dry-run arguments.
+11. Create the worktree with the same arguments without `--dry-run`.
+12. Do not replace the recorded SHA with the current `HEAD`.
+13. Change to the returned path.
+14. If the repository defines a bootstrap, run it.
+15. Use the repository tests to verify a clean baseline.
+16. Report the path, start SHA, and result.
 
-**If tests fail:** Report failures, ask whether to proceed or investigate.
+**If the tests fail:** Report the failures. Ask whether to continue or investigate.
 
-**If tests pass:** Report ready.
+**If the tests pass:** Report that the worktree is ready.
 
-## Cleanup
+## Clean up
 
-When work is done, invoke `tidy` for branch and worktree cleanup. It prepares the trusted
-Hephaestus dependency and delegates directly to `hephaestus-tidy`, whose interactive workflow owns
-discovery, preservation rules, deletion prompts, rebases, and cleanup safeguards. Do not duplicate
-that policy or improvise deletion commands in this skill.
+When the work is complete, invoke `tidy` for branch and worktree cleanup. `tidy` prepares the trusted
+Hephaestus dependency. It delegates the work directly to `hephaestus-tidy`. The interactive workflow
+controls discovery, preservation rules, deletion prompts, rebases, and cleanup safeguards. Do not
+duplicate that policy. Do not write deletion commands in this skill.
 
 Preserve the worktree by default. Delivery, merge, abandonment, or a general cleanup request does
-not itself authorize this skill to remove it; route any cleanup through `tidy` and leave the
-decision to the Hephaestus workflow and the user's answers to its prompts.
+not authorize this skill to remove the worktree. Use `tidy` for each cleanup. The Hephaestus
+workflow and the user's answers to its prompts control the removal decision.
 
 ## Quick Reference
 
 | Situation | Action |
 | ----------- | -------- |
-| `.worktrees/` exists + ignored | Use it |
+| `.worktrees/` exists and is ignored | Use it. |
 | Neither exists | Use the host temporary directory with `<project>-<branch>` |
-| Directory not ignored | Add to `.gitignore` + commit first |
-| Tests fail at baseline | Report failures + ask before proceeding |
-
-## Common Mistakes
+| Directory is not ignored | Use an explicit temporary path. Report the path. If the repository requires a local path, stop. |
+| Tests fail at baseline | Report the failures. Ask before you continue. |
 
-- **Skipping ignore verification** for project-local worktrees → contents get tracked
-- **Proceeding with failing baseline** → can't distinguish new bugs from pre-existing
-- **Not cleaning up** → stale worktrees accumulate
+## Failed approaches
 
-## Integration
+- Do not skip ignore verification for a project-local worktree. Git can track the worktree contents.
+- If the baseline tests fail, do not continue unless the user explicitly tells you to continue. You
+  cannot separate new defects from existing defects.
+- When cleanup is authorized, use `tidy`. Do not leave stale worktrees.
 
-**Pairs with:**
+## Related workflow
 
 - Invoke `tidy` for dependency-locked delegation to Hephaestus branch and worktree cleanup.
-- Verify with fresh runnable evidence per the evidence-integrity policy before finishing and
-  cleaning up.
+- Before you report completion or start cleanup, get fresh runnable evidence. Follow the
+  evidence-integrity policy.
 
 ---