From 14691074a87c1fd714314d46322c7a9f40498b8a Mon Sep 17 00:00:00 2001 From: Eduardo Marquez <55303379+DocksDocks@users.noreply.github.com> Date: Wed, 21 Oct 2026 17:43:04 -0300 Subject: [PATCH] docs(plan-lifecycle): tear down what a plan created Add a Teardown subsection to the plan contract and point plan-manager and yolo to it. The Merge now option states the teardown, so its answer confirms the merged branch delete. Remote production cleanups need their own question. The yolo run summary lists Kept resources. Refs #83 --- .../skills/productivity/plan-manager/SKILL.md | 30 +++-- .../plan-manager/references/plan-contract.md | 105 ++++++++++++++++-- .../skills/productivity/yolo/SKILL.md | 40 +++---- .../yolo/references/run-summary.md | 12 +- 4 files changed, 148 insertions(+), 39 deletions(-) diff --git a/plugins/plan-lifecycle/skills/productivity/plan-manager/SKILL.md b/plugins/plan-lifecycle/skills/productivity/plan-manager/SKILL.md index a7512e51..7dd18ae1 100644 --- a/plugins/plan-lifecycle/skills/productivity/plan-manager/SKILL.md +++ b/plugins/plan-lifecycle/skills/productivity/plan-manager/SKILL.md @@ -4,8 +4,8 @@ description: "Use when a goal may need the six-phase plan flow: decide, draft, r user-invocable: true metadata: pattern: tool-wrapper - updated: "2026-10-19" - content_hash: "be9d0c5997d69513c763f52251e48bb6c7fce9ff24d14a706d639ba1a3c6c3bc" + updated: "2026-10-21" + content_hash: "37cfc75fba999189e56e877a1cb3ad02be4e26c5e3f289bd83e1d3e3f08a427b" --- # Plan Manager @@ -27,9 +27,11 @@ Deliver the durable solution that the contract defines. Ask in-session immediately before running a non-local Effect step. Persisted intent is not permission. If confirmation is unavailable, block the step and plan with a reason. The settled mode covers routine issue publication and -linked-branch landing work. Every merge needs a fresh `Merge now` answer. -In a yolo run, the contract's Yolo runs section replaces every question in this -skill except the merge question. +linked-branch landing work. Every merge needs a fresh `Merge now` answer. A +production cleanup in the contract's Teardown needs its own in-session +question, also in a yolo run. In a yolo run, the contract's Yolo runs section +replaces every question in this skill except the merge question and a +production cleanup question. ## Resolve the helper @@ -132,7 +134,8 @@ evidenced CRITICAL or HIGH defect before the next round. A pass can carry MEDIUM and LOW findings. The posted comment is their record; do not change reviewed bytes for them. Resolve unreadable input before you request a verdict. If you block after implementation, commit and push current work to the linked branch -before you record the blocker, so repairs are not stranded. +before you record the blocker, so repairs are not stranded. Then run the +contract's Teardown for an exit without a merge. Done when: `show ` reports `code=pass`. @@ -141,14 +144,18 @@ Done when: `show ` reports `code=pass`. After code review passes, follow the contract's Landing and archive proof: commit and push the reviewed bytes, open or update the pull request, wait for checks, ask afresh for `Merge now` or `Leave pull request open`, and merge only -on `Merge now`. After a partial merge, reopen the issue as the contract states. -Archive only after the landing merge, when every step is terminal. +on `Merge now`. The `Merge now` option states the teardown, as the contract's +Checks and merge says. After a partial merge, reopen the issue as the contract +states. Archive only after the landing merge, when every step is terminal. +After archive, run the contract's Teardown. Without `Merge now`, run Teardown's +exit without a merge. Report Kept resources in both cases. Render the body only when the user names the plan and asks to see it. After a write, report the header strip and changed lines. -Done when: `archive ` prints `plan # finished (closed by )`, or -the user chose `Leave pull request open` and you reported the open pull request. +Done when: `archive ` prints `plan # finished (closed by )` and +you reported Kept resources, or the user chose `Leave pull request open` and +you reported the open pull request and Kept resources. ## BAD / GOOD @@ -161,4 +168,7 @@ GOOD: Verify the reviewed head and obtain a fresh Merge now answer. BAD: Merge a partial pull request and trust `Refs #` to keep the issue open. GOOD: Say that the merge closes the issue, merge on `Merge now`, reopen it, and confirm `show` reads ongoing. + +BAD: Run `git branch -D` after `git branch -d` refuses. +GOOD: Keep the branch and list it under Kept resources. ``` diff --git a/plugins/plan-lifecycle/skills/productivity/plan-manager/references/plan-contract.md b/plugins/plan-lifecycle/skills/productivity/plan-manager/references/plan-contract.md index c7cc306d..98fd84b3 100644 --- a/plugins/plan-lifecycle/skills/productivity/plan-manager/references/plan-contract.md +++ b/plugins/plan-lifecycle/skills/productivity/plan-manager/references/plan-contract.md @@ -98,6 +98,10 @@ Persisted Effect values record intent, not permission. If `ask` is unavailable, block the step and plan with a reason. Unknown tokens produce advice; they do not authorize an effect. Finish dependencies before starting dependent work. +A non-production target is one that repository configuration or documentation +names local, development, dev, test, homolog, homologation, staging, or +preview. Every other target is production. + ## Status, ownership, and frozen state `new` creates missing `plan`, `plan:drafting`, `plan:planned`, `plan:ongoing`, and @@ -343,8 +347,13 @@ failed or cancelled check blocks the merge question until its fix passes code review. If the repository has no configured checks, use the green local gate as the check result and say so in the merge question. -Ask afresh with two options: `Merge now` and `Leave pull request open`. Without -`Merge now`, leave the issue and the pull request open. Merge with +Ask afresh with two options: `Merge now` and `Leave pull request open`. The +`Merge now` option states the teardown that follows the merge: the processes +and stacks to stop, the worktree to remove, the local branch to delete with +`git branch -d `, and each remote non-production resource to clean up. +A `Merge now` answer confirms that teardown, including the branch delete. +Without `Merge now`, leave the issue and the pull request open, and run +Teardown's exit without a merge. Merge with `gh pr merge --repo --match-head-commit ` and the merge-method flag that the repository allows. A prior plan approval never authorizes a merge. @@ -365,6 +374,84 @@ carry a GitHub closing keyword for this issue in its description; a title or sid link is not proof. A merely linked pull request, another repository, or a non-default target is not proof. +### Teardown + +Teardown removes the resources that the plan created. + +From the first step, track each resource that the plan creates or starts: +worktrees, local branches, servers, watchers, test runners, compose stacks, and +remote resources made through SSH or a provider CLI. Stop a process or stack +when the step or check that needed it ends. Never stop or remove a resource +that the plan did not create. + +Run each compose command from the directory that started the stack, with the +same `-p` and `-f` options. First record the volume names from the container +mounts of the stack. Add the same options to `docker compose ps`, for example: + +```sh +docker inspect --format '{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}} {{end}}{{end}}' $(docker compose ps -a -q) +``` + +This record includes anonymous volumes, which carry no project label. Then run +`docker compose down`. Never add `--volumes`. List the recorded volumes under +Kept resources. + +A partial pull request merge does not end the plan. Do not run teardown then. + +#### After archive + +Run these steps in order after `archive ` succeeds: + +1. Stop each process and compose stack that the plan started and that still + runs. +2. Clean up each remote non-production resource that the merge question named. + Follow Production resources for every other remote resource. +3. Run the next commands from the main worktree, not from the plan's worktree. + A removal from inside the worktree leaves the shell in a deleted directory. +4. If the plan made a worktree, run `git worktree remove -- `, then + `git worktree prune`. Never add `--force`. When git refuses because of + untracked or modified files or a lock, keep the worktree. List it with the + reason from git. +5. If the plan used the user's checkout and `git status --porcelain` prints + nothing, run `git switch ` and `git pull --ff-only origin `. +6. Run `git branch -d `. When git refuses, keep the branch and list it. + Git refuses after a squash or rebase merge once the remote branch is gone. + Never run `git branch -D` or add `--force`, even when the git hint suggests it. +7. Report Kept resources. + +#### Exit without a merge + +The plan can stop without the landing merge: on `Leave pull request open`, on a +blocked plan, on a stalled yolo run, or without an answer. Then stop each local +process and compose stack that the plan started, as above. Keep the worktree, +the branch, and every remote resource. Report them under Kept resources with +the reason, such as `pull request open` or `plan blocked`. + +#### Production resources + +Local resources on the workstation are development resources: worktrees, local +branches, scratch files, local processes, and local compose stacks. Teardown +removes them without a question. A remote resource that an agent reaches +through SSH or a provider CLI is production, unless its target is +non-production. Examples are `wrangler`, `kubectl`, and a remote Docker host. +Steps, acceptance, and effects defines a non-production target. A command that +names no non-production target acts on production, such as `wrangler delete` +without `--env`. + +Teardown never stops, removes, undeploys, or deletes a production resource on +its own. A production cleanup needs an in-session `ask` immediately before it. +Keep such cleanups rare. A yolo invocation does not answer that question. When +`ask` is unavailable, as in a subagent, do not run the cleanup. List the +resource under Kept resources with the reason `production`. + +#### Kept resources + +List each resource that teardown keeps, with its reason, or write `none`. Name +a worktree by its branch and directory name, a volume by its name, and a remote +resource by its provider and name. Do not write absolute machine paths. +`git worktree remove` also removes the review scratch of a linked worktree. The +scratch directory of the main checkout stays. + ## Yolo runs The user starts a yolo run by invoking the `yolo` skill with a request. The @@ -382,6 +469,7 @@ question. All other contract rules stay in force. | Review-loop continuation | The round ceiling below | | Plan-review `blocked` verdict | The manager decides with evidence | | Public disclosure of a sensitive finding | Stop before any write | +| Production cleanup in Teardown | Its own question, like a step after the landing merge | ### Delegation line @@ -402,12 +490,10 @@ holds only a `Blocked:` line. Reviewers treat a recorded decision as settled. | `deploy` | Run only to a non-production environment | | `production_access`, `publish`, `release` | Do not run before the landing merge | -A non-production target is one that repository configuration or documentation -names local, development, dev, test, homolog, homologation, staging, or -preview. Every other target is production. A step that the table does not -permit stays `planned`. After the landing merge, it follows Steps after the -landing merge. Effect advice from the helper is met for each effect that the -table permits. +Steps, acceptance, and effects defines a non-production target. A step that the +table does not permit stays `planned`. After the landing merge, it follows +Steps after the landing merge. Effect advice from the helper is met for each +effect that the table permits. ### Linked branch timing @@ -441,7 +527,8 @@ exists. Then ask once, with the options `Continue yolo` and `Leave plan blocked`. Keep the status unchanged while you ask, because the helper does not move a blocked plan back to `drafting` or `planned`. `Continue yolo` gives the phase 10 more rounds. On `Leave plan blocked`, or without an answer, set the -status to `blocked` with the stall reason and report. +status to `blocked` with the stall reason, run Teardown's exit without a merge, +and report. ### Merge question diff --git a/plugins/plan-lifecycle/skills/productivity/yolo/SKILL.md b/plugins/plan-lifecycle/skills/productivity/yolo/SKILL.md index 3c468b7c..cb4c15e0 100644 --- a/plugins/plan-lifecycle/skills/productivity/yolo/SKILL.md +++ b/plugins/plan-lifecycle/skills/productivity/yolo/SKILL.md @@ -5,8 +5,8 @@ user-invocable: true disable-model-invocation: true metadata: pattern: pipeline - updated: "2026-10-19" - content_hash: "df849a65ed166954017addd24fe9ed277fc24db6e99e4cf601a98f24ebe450b8" + updated: "2026-10-21" + content_hash: "ebf4d1d091f01934dd8c0f88536c85f430a208218cfbe27ba2ac2a92ff3bce4f" --- # Yolo @@ -32,14 +32,17 @@ Start only when the user's own message invokes yolo: `/plan-lifecycle:yolo`, `/skill:yolo`, `$yolo`, or a sentence that names the yolo skill. Otherwise stop and use `plan-manager`. Do not call `ask` before the merge question. The only exception is the stalled-review question in the contract's Yolo runs section. -Resolve every unknown from the codebase, current official documentation on the -web, or a throwaway experiment. +After the merge, each production cleanup in the contract's Teardown needs its +own question. Resolve every unknown from the codebase, current official +documentation on the web, or a throwaway experiment. Do not access production, deploy to production, publish, or release before the merge. Do not force-push or rewrite history. Do not stash, move, commit, or delete work that the user made. Do not merge without a fresh `Merge now` answer. +Do not run a production cleanup without its own question. This invocation does +not answer it. Before each issue, comment, commit, or pull request write, remove secrets, tokens, credentials, private hostnames, environment values, and absolute machine paths. Name a secret by its variable name, not its value. The repository can be @@ -262,6 +265,10 @@ Reject a finding only with evidence. Post that evidence as one issue comment whose first line is `Rejected review findings, round `. Before you repair the same finding again, research it again and try a different approach. +When a review phase stalls at the ceiling and the answer is `Leave plan +blocked`, or no answer is possible, run the contract's Teardown for an exit +without a merge. The contract's Round ceiling also says this. + ## Landing 1. Confirm that `git status --porcelain` prints nothing. The reviewed head is @@ -273,8 +280,8 @@ same finding again, research it again and try a different approach. 4. Write the run summary from `references/run-summary.md` to a file in the review scratch directory. The run summary is the whole pull request description; do not add the `commit-discipline` description sections. Write - `pending` for the pull request URL and the checks. End the file with - `Closes #` on its own line. + `pending` for the pull request URL and the checks. Include Kept resources, + as the template says. End the file with `Closes #` on its own line. 5. When `gh pr list --repo --head --state open` shows a pull request, update its body with `gh pr edit --repo --body-file `. Otherwise open the pull request with `gh pr create @@ -288,22 +295,17 @@ same finding again, research it again and try a different approach. --body-file `. 8. Print the run summary. In the same response, ask one question: `Merge pull request # into ?`, with the options `Merge now` and - `Leave pull request open`. -9. On `Merge now`, merge and archive as the contract says. Then clean up: - - If this run made a worktree, run `git worktree remove -- `, then - `git worktree prune`. - - If this run used the user's checkout and `git status --porcelain` prints - nothing, run `git switch ` and - `git pull --ff-only origin `. - - Keep the merged local branch. Name it in the final report as a branch that - the user can delete. - - Ask separately before each plan step that runs after the merge. + `Leave pull request open`. The `Merge now` option states the teardown, as the + contract's Checks and merge says, including `git branch -d `. +9. On `Merge now`, merge and archive as the contract says. Then run the + contract's Teardown and report Kept resources. Ask separately before each + plan step that runs after the merge and before each production cleanup. 10. On any other answer, or when no answer is possible, leave the pull request - and the issue open. Report both links. + and the issue open. Run Teardown's exit without a merge. Report both links + and Kept resources. 11. When the message that answers the merge question also starts a new yolo run, finish this run first: merge or leave open as the answer says, then - archive and clean up. Then start the new run. + archive and run Teardown. Then start the new run. ## Run summary diff --git a/plugins/plan-lifecycle/skills/productivity/yolo/references/run-summary.md b/plugins/plan-lifecycle/skills/productivity/yolo/references/run-summary.md index 343ae3d7..3fbc2dd0 100644 --- a/plugins/plan-lifecycle/skills/productivity/yolo/references/run-summary.md +++ b/plugins/plan-lifecycle/skills/productivity/yolo/references/run-summary.md @@ -23,10 +23,20 @@ Open findings: . ### Limits and failures - +### Kept resources +- + ### After merge -- +- ``` Copy each failure and limitation from Verification Results into Limits and failures. Report a check that partly failed as a failure with its cause, not as a pass. + +In Kept resources, list what stays after `Merge now`: the recorded compose +volumes, the resources that Teardown keeps, and the production resources that +need their own question. Also list what stays after `Leave pull request open`: +the worktree, the branch, and the remote resources. Name each resource without +an absolute machine path. After the merge answer, report the actual Kept +resources in the final report.