pstack-dsh 0.2.3

package/skills/poteto-mode/playbooks/multi-phase-plan.md

@@ -0,0 +1,156 @@
+### Multi-phase or multi-PR plan
+
+**You own the plan, not the code. The plan is a checklist an owner runs box by box and the operator audits from the evidence.** For work that spans phases or stacked PRs. The plan is the deliverable. Do not implement.
+
+1. When the change is one or two files with an obvious approach, skip the plan. Say so and stop.
+2. Settle open questions by prototype before you write. For a question about layout, timing, behavior, or whether an API works, run `playbooks/prototype.md`. Keep the branch, the SHA, and the screenshots for Appendix A. Ask the operator only about a product or preference call that no run can settle. Give options (the **never-block-on-the-human** principle skill).
+3. Explore in subagents with `pstack_spawn` `role: "poteto-agent"` per the Subagents section (the **guard-the-context-window** principle skill). Each returns file pointers, conventions, test commands, and entry points. No inlined dumps.
+4. Copy the skeleton below into the plan file and fill every placeholder. Unless the operator names a path, write the file under the agent store's `docs/`. Keep every heading and every sub-block in the order shown. One section per PR. One PR is one change with its own evidence (the **sequence-verifiable-units** principle skill). Name the execution playbook in **How to read this**. Pick between `playbooks/autopilot-full.md` and `playbooks/autopilot-stack.md` per the rule at the end of `playbooks/autopilot-stack.md`. A standing program takes `playbooks/orchestrate.md`.
+5. Write under `/technical-writing` in full, then `/unslop`. The body is one Diátaxis mode, how-to. Appendices hold explanation and reference. Two rules apply verbatim. "i dont want any abstract metaphors" and "write like hemingway". Each heading states the task or the finding. No long dashes. No mid-sentence colons.
+6. Run `node pstack/skills/poteto-mode/scripts/check-plan.mjs <plan.md>` and fix every line it prints (the **encode-lessons-in-structure** principle skill). It enforces the skeleton's shape, the verification rule in every verification block, and the punctuation rules.
+7. Hand back. Post the plan path and the script's output, then stop. Execution starts on the operator's explicit go, under the execution playbook the plan names.
+
+**Verification.** Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked (the **prove-it-works** principle skill). That sentence is the verification rule. Every verification block opens with it. The live block is mandatory. Ten lanes at the PR head drive the real surface, per the **swarm** skill. Overlay `swarm-workers` or inherit. Each lane is one box with a concrete scenario, the screenshot it saves, and its pass predicate. The perf block names the metric, the probe, the trunk baseline measured first, and the rule with the number that fails. A PR that changes an interaction is review-gated. The operator reviews it in chat with screenshots and a video before merge. A PR that changes no interaction writes `**Review gate.** None. <PR id> is not review-gated.` and no boxes under it.
+
+**Control skill.** Pick it by surface. Drive the real surface yourself (browser, CLI, tests). Native mobile uses whatever simulator-driving skill the repo has. A PR that touches two surfaces gets lanes on both. A surface with no control skill is a risk in Appendix C, and its live block still names how each lane drives it.
+
+````markdown
+# <Program> plan
+
+<Under ten lines. What changes, for whom, the rule the program enforces, and the PR ids in order.>
+
+## How to read this
+
+One box is one unit of work. Every box names the evidence that checks it. A nested box is a sub-step of the box above it. Check a box only when its evidence exists, a file, a log line, a screenshot, a test run, or a SHA. The body is a how-to. The appendices explain and record.
+
+The program runs `pstack/skills/poteto-mode/playbooks/<execution playbook>.md`. <Who merges, and which PR ids are the operator's items that stop at merge-ready.>
+
+Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.
+
+## Program checklist
+
+### Arm the program
+
+- [ ] State the protocol and this plan to the operator, then stop. Start execution only on her explicit go.
+- [ ] On her go, use `create_goal` with this exact objective. "<The plan path, the PR ids in order, the verification rule, who merges, and the done condition.>" Read `get_goal` before updating an existing goal's exact id and revision.
+- [ ] Read these from trunk at program start. Re-read them at every tick.
+  - [ ] `git show origin/main:pstack/skills/poteto-mode/playbooks/<execution playbook>.md`
+  - [ ] `git show origin/main:pstack/skills/swarm/SKILL.md`
+  - [ ] `git show origin/main:<control skill path>`
+  - [ ] `git show origin/main:pstack/skills/poteto-mode/playbooks/opening-a-pr.md`
+  - [ ] `git show origin/main:pstack/skills/<each other leaf skill the program uses>`
+- [ ] Audit at each DSH goal continuation and completion notification. Goal continuation is not a timed scheduler. Do not promise a 30-minute wake.
+- [ ] Use this audit prompt. "Re-read the installed execution playbook and call get_goal. Audit the operation against both and fix drift. Probe every active lane and judge progress by side effects. Investigate a stuck lane and confirm it has stopped writing before assigning its files to a replacement. Send the operator a status message with the queue table of PR, owner, state, and head SHA, the new verdicts, what merged, open operator gates, and blockers."
+- [ ] On the operator's hold or stand-down, send every owner a zero-writes order at once.
+
+### Spawn owners
+
+- [ ] Spawn one owner per PR with the full lifecycle the execution playbook names.
+- [ ] Follow this dependency graph. Start dependent work only after its parent merges, or base it on the parent branch when the execution playbook stacks.
+  - [ ] <PR id> and <PR id> are independent and first. Both branch from `main`.
+  - [ ] <PR id> after <PR id>.
+- [ ] Hold the file boundaries. <PR id or class> touches only `<glob>`.
+- [ ] Hold the review gate. <PR ids> change an interaction. They wait for the operator's review in chat with screenshots and a video before merge.
+
+### PR mechanics, for every PR
+
+- [ ] Resolve the forge once. Default to `gh`. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr` for every PR operation. Record any fallback to `gh`. Never require `gt`.
+- [ ] Open the PR ready, never draft, with `origin pr create --status open --base <base-branch>` or `gh pr create --base <base-branch>` according to the resolved forge. A stack child targets its parent branch.
+- [ ] Run the repo's lint and typecheck once before the PR-facing push. Push with hooks on.
+- [ ] Run `/unslop` before each commit and `/no-comments` before review.
+- [ ] Triage every Bugbot and security-reviewer comment per `../references/bugbot-triage.md`.
+- [ ] Rebase onto current trunk before babysit and again before the merge-ready report.
+
+### Verdict and merge, for every PR
+
+- [ ] At the merge-ready head SHA, run the swarm per `pstack/skills/swarm/SKILL.md`. One gates lane. The ten live lanes from the PR's **Verify, live** block. The perf lane from its **Verify, perf** block. One audit lane that reads the diff and the receipts and distrusts the PR body.
+- [ ] Clean only when every lane is `PASS`. Findings go back to the owner. A new head gets a fresh swarm and a fresh verdict.
+- [ ] <The merge or append rule from the execution playbook, with the patch-id rule from `playbooks/shipping.md`.>
+
+### Boot recipe, for every live lane
+
+Each live lane runs in its own worktree (parent-created) at the PR head. Drive the real app (browser, CLI, tests).
+
+- [ ] `git fetch origin <head-branch> && git checkout <head SHA>`.
+- [ ] <Start the backend and the surface. Wait for ready.>
+- [ ] <Deliver input only through the control skill's commands. Name the read-only diagnostics.>
+- [ ] Save every screenshot to `/tmp/swarm-<pr-id>/worker-<n>/<slug>.png` and return the paths with the report.
+
+## <Task as a verb phrase> (<PR id>)
+
+**Depends on.** <PR id, or None.>
+
+**Files.**
+
+- [ ] Edit `<path>`.
+- [ ] Create `<path>`.
+- [ ] Delete `<path>`.
+
+**Build.**
+
+- [ ] <One change. Name the symbol and the file.>
+
+**You see.**
+
+- [ ] <One observable result, with the exact log line or screen state.>
+
+**Verify, unit.** Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.
+
+- [ ] <Test file and the case it gains.> Run `<command>`.
+
+**Verify, live.** Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked. Ten lanes at the PR head, per the boot recipe. Overlay `swarm-workers` or inherit.
+
+- [ ] Lane 1. Regression lane against trunk. Run <the same load-bearing scenario> at trunk and head. If trunk lacks the feature, record that and gate <the behavior the diff adds plus the end state the user waits for>. Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 2. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 3. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 4. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 5. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 6. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 7. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 8. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 9. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+- [ ] Lane 10. <Scenario.> Save `<slug>.png`. Pass when <predicate>.
+
+**Verify, perf.** Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.
+
+- [ ] Metric. <What is measured at both trunk and head. If trunk lacks the feature, also name the diff-added work and the end-to-end state the user waits for.>
+- [ ] Probe. <The command or procedure, run at trunk and at the head, interleaved. Both sides must produce the metric.>
+- [ ] Baseline. Record the trunk <value> first.
+- [ ] Rule. <Head against trunk, with the number that fails. If the scenarios differ, add absolute budgets for the diff-added work and the user-visible end state instead of an invalid ratio.>
+
+**Review gate.** The operator reviews before merge.
+
+- [ ] Copy lane <n> screenshots into `<media path>/<pr-id>-review-<slug>.png`.
+- [ ] Record a 30 to 60 second video of the change on a lane VM. Save it as `<media path>/<pr-id>-review.mp4`.
+- [ ] Post the screenshots and the video in chat. Stop at merge-ready. Wait for the operator's click.
+
+**Merge.**
+
+- [ ] Root's clean verdict at the exact head SHA.
+- [ ] Bugbot triage done.
+- [ ] Rebased onto current trunk after the verdict, patch-id unchanged.
+- [ ] <The owner squash-merges its own PR, or the root appends it to the base-branch stack and the operator lands it bottom-up.>
+
+## Close the program
+
+- [ ] Every box above is checked with its evidence.
+- [ ] Reply to the operator with the report the execution playbook names.
+
+## Appendix A. Prototype evidence
+
+<Each open question a prototype answered, with the branch, the SHA, and the artifact links. Each question that stays unproven.>
+
+## Appendix B. Alternatives rejected
+
+<Each approach weighed and why it lost.>
+
+## Appendix C. Risks
+
+<Each risk with the PR it lands in and what the owner watches.>
+
+## Appendix D. Links and reading list
+
+<Docs to read before editing. Which PRs get `pstack/skills/how/SKILL.md` and `pstack/skills/interrogate/SKILL.md`. The trail per `pstack/skills/show-me-your-work/SKILL.md`.>
+````
+
+**Reply:** the plan path, the PR ids with their dependencies and the review-gated set, what the prototypes proved and what stays unproven, and the check script's output.

package/skills/poteto-mode/playbooks/opening-a-pr.md

@@ -0,0 +1,33 @@
+### Opening a PR
+
+Invoked at the end of code-change playbooks when a PR is in scope.
+
+**Worktree.** Work from a git worktree off trunk. Give each concurrent `pstack_spawn` writer its own worktree and an explicit path. Preserve unrelated work before moving to a fresh worktree. Do not reset a shared or dirty branch to repair a collision.
+
+**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is landable. Amend when the fix belongs in a just-made commit. Make a new commit when separable.
+
+**PRs.** Run `/unslop` over the diff before commit. Run `/no-comments` before review. Write every PR title, PR description, and commit body with `/technical-writing`, then apply `/unslop`. Apply every technical-writing layer except Diátaxis. Use one word for each action, keep articles, and avoid `-ing` when a plain verb works.
+
+**Titles.** Use Conventional Commits in the form `type(scope): subject`. Use `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, or `perf` as the type. Use the changed area, such as `pstack` or `poteto-mode`, as the scope. Keep the subject short and imperative. Name a real symbol when one carries the change. For example, `fix(pstack): retarget opening-a-pr babysit trigger`. Do not add a trailing period.
+
+**Descriptions.** The PR body is a briefing, not the lab notebook. A reviewer who has the diff should learn why the change exists, what is out of scope, and how you proved it works. When squash-merging, use the PR body as the commit body. If that would exceed about 40 lines, cut the body.
+
+Use these sections in order. Drop a section when it has nothing to say.
+
+- `## Why`. State intent and approach in one or two short paragraphs. Do not list SHAs, rebase genealogy, or a "based on main" preamble.
+- `## Scope`. List real symbols and paths in bullets. Name both sides of a rename or retarget. State what is in and out only when the boundary matters. Do not write a file-by-file essay.
+- `## Tradeoffs`. Name only rejected alternatives a reviewer would otherwise ask about. Skip when there was no real choice.
+- `## Blast radius`. In one to three sentences, name who or what the change touches and why it is safe or risky. State the continuing cost if trunk stays red without the fix.
+- `## Verification`. Name each real run path and its outcome, such as the browser, CLI, or targeted tests. For performance, report one primary number with its unit in `before → after` form. Link the evidence directory for remaining details. Keep methodology and metric tables there.
+
+Attach videos or screenshots when they prove a claim. Put full SHAs, per-agent recitals, measurement corrections, file-by-file checklists, and "CLEAN" verdicts in a linked artifact. Do not use `## Summary` or `## Test plan` boilerplate. A commit body does not restate its subject.
+
+**Forge.** Resolve the forge before the first PR operation and keep that choice for create, edit, view, watch, and merge. GitHub CLI, `gh`, is the default. If `command -v origin` succeeds and Origin can resolve the repository, prefer `origin pr ...`. Otherwise stay on `gh` and record the fallback. Do not require Graphite, `gt`.
+
+**Size and stacks.** Prefer five narrow PRs to one large PR. A stack is a base-branch chain. The root PR targets trunk. Each child branch rebases onto its parent's exact tip and its PR targets the parent branch. Create a child with `origin pr create --status open --base <parent-branch>` or `gh pr create --base <parent-branch>` according to the resolved forge. Retarget with `origin pr edit <pr> --base <parent-branch>` or `gh pr edit <pr> --base <parent-branch>`. Branch from trunk only for independent work. Rebase on trunk before substantial stack work.
+
+**Readiness.** Open every PR ready, never as a draft. With Origin, pass `--status open`. With `gh`, omit `--draft`. If a host tool defaults to draft, mark it ready. If a PR still opens as a draft, run `origin pr ready <number>` or `gh pr ready <number>` according to the resolved forge. Run `origin pr view <number>` or `gh pr view <number>` before referring to PR status.
+
+**Babysit.** Opening a PR does not start a babysit. Post the URL and keep building. Finish the phase or stack first. Run a separate babysit pass only when the user asks after the whole stack exists. Push back when feedback drifts from intent.
+
+A subagent that opens a PR runs `interrogate`, `/unslop`, and `/no-comments`. It returns the URL and does not babysit. Return to the parent.

package/skills/poteto-mode/playbooks/orchestrate.md

@@ -0,0 +1,113 @@
+### Orchestrate
+
+**You own the program, never the code. Author briefs, drain the queue, keep the frontier green, decide.** For a whole project handed to one standing coordinator chat: multi-day, many stacked PRs, dozens to hundreds of subagents, the human checking in twice a day instead of every five minutes. One task driven to a predicate is Autonomous run. One ambitious run needing a bespoke workflow is figure-it-out. Route here when the work outlives any single agent. Work one agent could finish inside the session's budget is not a program; measured head-to-head, this playbook's ceremony turned a half-hour 12-unit job into 1 landed unit while a plain agent landed all 12. Below that line, route to Autonomous run.
+
+Ceremony must scale with the program. Every gate below prices in coordinator minutes; on cheap near-identical units, collapse it as each section directs rather than paying list price.
+
+Three rules carry the rest.
+
+- Completions are queue events, not interrupts.
+- Every spawn and every resume carries the standing orders verbatim.
+- The brief is the product. A vague brief fails quietly, because a worker cannot ask you a question.
+
+Open a todolist with the steps below copied in verbatim. A step you skip stays listed with `skip: <reason>`.
+
+#### Roles and placement
+
+- **Coordinator (this chat).** Local. Frames, authors briefs, drains the inbox, owns the human report, makes judgment calls. It never authors or edits code: conflicted merges, restacks, and code changes are always tasks. Mechanically landing a verified unit (fast-forward or clean cherry-pick of a worker's commit, then push) is bookkeeping the coordinator may do itself on repos where local git is cheap; queueing finished work behind an idle stacker is how a deadline harvests nothing. The loop is agentic end to end. Agents are spawned, resumed, and drained only through `pstack_spawn` plus `send_message` / settlement notices. State reads and writes go through `scripts/orch/orch.ts` at drain points, one command in and one line out, to conserve context. The CLI never spawns, waits, or wakes anything.
+- **Sub-coordinator.** Always local, durable, one per track, and only when the program exceeds what one coordinator's drains can manage. A track the coordinator can drain itself needs no middle layer: each nested layer re-pays a full orientation preamble, and a blocking sub-coordinator hides its children while the parent idles. Owns its track's units and boards, authors its workers' briefs, spawns its own workers and verifiers (nesting works to depth 3, and a nested spawn still uses `pstack_spawn` fields only; there is no `environment` field). Rolls up aggregates at wave boundaries; never forwards raw child reports. Cap in-flight children at what one drain can process, roughly ten, as a rolling window; never as blocking batches, which cost the slowest child of every batch.
+- **Worker / verifier.** Children share this cwd unless the parent created a worktree. Stay in-process unless the task needs this machine: runtime verification on the real app (browser, CLI, tests); reading this DSH session log; simulators and local IDE state; auth that exists only here. DSH children share the parent cwd by default, so briefs can point at repo paths. Worktree children only see what the parent copied or committed. Prefer fewer, broader workers; one writer per worktree or branch (principle-separate-before-serializing-shared-state). Run a unit's verifier on a different model family from its worker.
+
+Depth stays at coordinator, track, worker. Author the track decomposition per project (build, landing, and verification are common cuts, not a required shape); hard-coded swarm trees were tried and parked as too rigid.
+
+#### Store layout
+
+Create `orchestrate/<project-slug>/` in the current agent's store (path in the system prompt). Every file has exactly one writer; owners publish facts, readers aggregate at read time. Use `bun scripts/orch/orch.ts` for bookkeeping, written below as `orch`, while its canonical plain TSV and JSON stay readable without the CLI.
+
+- `preferences.md` is the standing-orders register: numbered lines, one constraint each (model policy, stack shape and count, verification bar, forbidden paths, escalation policy). Paste it verbatim into every spawn and every resume; directives decay across resumes, and each dropped one costs a human turn. When you catch yourself restating an instruction, append the line before you act (principle-encode-lessons-in-structure).
+- `overview.md` is the durable PR and issue DB. Append; never rewrite wholesale per event.
+- `units.tsv` has one row per unit: id, track, state, branch, PR, head SHA, brief path. Update rows in place.
+- `frontier.json` is the computed merge frontier, per Stack safety.
+- `ledger.tsv` is the verification ledger, per Verification.
+- `inbox/` holds completion pointers. `gates.md` parks human gates (question, options, default on no answer) so a completion flood cannot wipe `ask_user_question` state.
+- `decisions.tsv` is the trail via the show-me-your-work skill.
+- `status.md` is derived from `units.tsv` and `ledger.tsv` at each drain, never hand-maintained; regenerate it from the tables instead of narrating events into it, because hand-churned boards get rewritten on every event and go unreadable.
+
+#### The brief
+
+Your prompts to agents are your only product, and a sloppy brief compounds into slop across the whole tree. Every spawn carries all of it; a field you cannot fill is a unit you have not scoped yet.
+
+```
+GOAL         one sentence, the outcome, executable by a stranger with no chat access
+SCOPE        paths this unit may write; paths it may not; its exclusive worktree or branch
+CONTEXT      pointers to files and PRs; upstream reports pasted in full when this unit
+             depends on them, because workers cannot see siblings
+ACCEPTANCE   checkable criteria, one per line
+VERIFY       exact commands or the control-skill path, plus known gotchas
+TIMEBOX      rough cap on runtime; on expiry, return partial findings and stop rather than run on
+FORBIDDEN    no gt, no rebase, no force-push, no fixes outside scope, plus unit-specific bans
+REPORT       status, branch, head SHA, PRs, verdict, what you actually ran, deviations,
+             suggested follow-ups
+STANDING     <preferences.md pasted verbatim>
+```
+
+Size the brief to the unit. A one-command unit gets the template collapsed to a paragraph that still names goal, scope, the verify command, and the report shape; a 4KB scaffold around a two-line edit costs more to write and obey than the edit. Local spawns may reference the standing-orders file by store path; verbatim paste is for cloud spawns and every resume.
+
+A sub-coordinator brief adds its track boundary and unit list, its spawn budget with the cloud default and the local exception list, the drain protocol, and the rollup format (per child: name, status, PR, head SHA, verdict, one line; plus track status and frontier delta).
+
+A dependency is a context relay, not just ordering: undeclared upstream context makes the worker guess. Missing fields are a refuse-to-spawn condition. Audit one sampled worker brief per sub-coordinator per wave, concurrently with the wave it samples, never as a gate in front of it; a failing brief stops that track and fixes the sub-coordinator's instructions, not just the worker, because brief quality decays late in a run. Never resume-chain a brief; respawn fresh with consolidated scope.
+
+#### Steps
+
+1. **Frame.** State the done predicate as something countable ("all 126 units merged, each ledger-verified `unit-test-verified` or better"). Quantify scope: units, rough effort, expected stacks, and the wall-clock budget. If one agent could finish inside that budget, stop here and run Autonomous run instead. Collapsing must not depend on another document being present: it means do the work directly in this session, plain workers where they help, verification inline, landing as you go, and none of the store, register, or pilot machinery below. Schedule landing against the budget: by roughly 70% of it, stop spawning and land what is verified, because finished-but-unlanded work counts as zero. Name the tracks per project. A contested decomposition or one-way door goes through the arena skill before the pilot. Present the framing once; reversible prep proceeds without waiting.
+2. **Install the runtime.** Run `orch init`. Open the trail via the show-me-your-work skill, write the standing orders before any spawn, and seed `frontier.json` from existing PRs with `orch frontier set --repo <repo-dir>`.
+3. **Pilot.** Push one unit through the whole path: brief, worker, verification, stack entry, ledger row, merge. The pilot exists to falsify the brief template, the verify recipe, and the unit size while that costs one agent instead of fifty. Fix the contract from pilot evidence before any fan-out. Scale the pilot to the unit: on programs of near-identical cheap units, the first unit is the pilot, run as a normal unit with its verify command inline, and fan-out starts the moment it lands. The dedicated pilot pipeline (separate verifier agent, audit gate) is for expensive or novel unit shapes, not for clone-units where a serialized pilot has nothing to falsify.
+4. **Scale.** Spawn a rolling window of workers up to the in-flight cap, refilling as children finish; blocking batches pay the slowest child of every batch. Spawn track sub-coordinators only past the one-drain threshold in Roles. Recompute ready work after each drain; relay upstream reports into downstream briefs; keep sibling communication upward only. The sampled brief audit runs alongside the wave it samples and stops the next refill on failure, not the current one.
+5. **Drain.** Run the queue discipline below at every drain point.
+6. **Land.** Landing is continuous, never a terminal phase: integration starts with the first verified unit and runs alongside the remaining waves. On heavy repos the stacker is a standing role from wave one, integrating as units verify; on repos where local git is cheap, the coordinator lands verified units itself per Roles. Keep the frontier green before upper-stack work; Stack safety governs. Advance `frontier.json` only on merge or reported new head SHAs.
+7. **Close.** Drain the final inbox, reconcile every spawned agent to a terminal row (done, abandoned, zombie-reconciled), confirm the predicate on the real artifact, confirm every landed PR has a verdict for its current head SHA, audit the trail per show-me-your-work including its cross-model review, encode recurring corrections into `preferences.md` or the brief template. Leave the store intact; it is the postmortem.
+
+#### Queue and drain
+
+- On a completion notification, run `orch inbox push <agent> <unit> <status> [--report PATH]` and return to what you were doing. Never deep-review inline; a completion that needs review becomes a verifier unit. Never review a diff inside a drain.
+- Drain in batches at four points: the end of a critical section, a track rollup, a DSH goal continuation or managed frontier watcher-job completion, and before a human report. Begin each batch with `orch inbox drain`. Arrivals during a drain wait for the next one.
+- Critical sections you finish first: authoring a brief, a stack operation, a conflict decision, writing a gate, updating ledger or frontier.
+- Each drain classifies every pointer (landed, needs-verify, failed, zombie, noise), writes the resulting rows through `orch unit add`, `orch unit set`, and `orch ledger record`, runs `orch status`, then spawns the next wave in one message.
+- Account for every spawned child at its track's rollup: arrived, respawned, or its scope explicitly absorbed. Silently redoing a missing child's work hides both the wasted spend and the coverage gap its result existed to close.
+- A drain turn ends with the three lines from `orch status`: counts against the states, what changed, gates open. Detail lives in `status.md`; the full reply contract applies at checkpoints and close.
+
+#### Stack safety
+
+- The frontier is a computed object, never narrative. Recompute `frontier.json` from `gt` after every merge and stack mutation because GitHub base refs drift mid-restack while gt tracking is authoritative: ordered PR list, branch names, head SHAs, a generation number, the lowest unmerged PR. Resolve it where gt knows the stack, normally the stacker's clone; a checkout whose gt metadata never saw the submits reports no PRs and the command errors rather than guessing.
+- Exactly one stacker per stack may run `gt`, serialized within its stack; record the holder in the standing orders. Restacks run in cloud; a local restack at this scale takes the laptop down.
+- Workers never rebase and never run `gt`. Babysitters follow `playbooks/babysit.md`, one per stack, scoped to one immutable frontier generation; they report conflicts to the stacker rather than restacking.
+- PR closes and retargets go through the stacker only; closing a base PR orphans every chain above it. Merges and stack surgery are units with briefs like any other.
+- One retro watcher follows merged PRs for reverts, post-merge CI breaks, and orphaned follow-ups.
+
+#### Verification
+
+Scale verification to the unit. When VERIFY is a single cheap command, the worker runs it and reports the output, and the coordinator spot-checks receipts; a dedicated verifier agent (on a different model family than the worker) is for units whose verification is expensive, judgment-laden, or high-blast-radius. A verifier agent whose entire product would be rerunning one command is ceremony, not verification.
+
+Write ledger rows with `orch ledger record`. Check the current PR and head SHA with `orch ledger check`. `ledger.tsv`, one row per verdict, keyed by PR number plus head SHA: `live-ui-verified | unit-test-verified | type-check-only | verifier-blocked | verifier-failed`. CI green is an input to a verdict, not a verdict. Behavioral work needs better than `type-check-only`. `verifier-blocked` is not a pass; respawn when the environment heals. `verifier-failed` gets a fix unit, not a re-verify. A worker may self-report; a verifier overrides it on the same key. A new head SHA voids the row, so re-verify after restack. The ledger answers "was this verified", not memory and not the transcript.
+
+A unit is not done until its output is externalized the moment it lands, never batched to the end of the run: a worker pushes its branch, a verifier writes its ledger row, receipts land in the store. Work that exists only on one VM when that VM dies was never done.
+
+#### Liveness and failure
+
+- Never resume an agent to check on it; a resume restarts an idle agent. Probe read-only: the ledger, `units.tsv`, `gh`, pushed branches, the cloud agent's status in the Cursor dashboard. Transcript mtime is not liveness.
+- A silent death gets a synthetic postmortem row in the inbox (unit, failure mode, last evidence, options). Replan on evidence as it arrives; never wait for full quiescence.
+- Retry by mode: cap-hit or oom, respawn with smaller scope; network-drop, retry as-is; tool-error, retry on a different model; unknown, retry once. Two retries, then abandon the unit and replan around it.
+- A zombie that returns hours late reconciles against the current frontier and ledger before anything is accepted; the world moved while it slept. Salvage unique findings through a fresh unit, never a blind merge.
+- When continued spawning would produce garbage tree-wide (bad upstream output, broken acceptance, dead infra), write a stop line at the top of the standing orders, let in-flight work finish, fix the cause, clear it.
+- Bound your own infra retries the same way you bound a child's. After a few consecutive tool aborts, stop retrying: write a terminal handoff to durable state (what is done, where it lives, the exact command to resume) and end the run. Hours of retry loops against a dead executor produce nothing a handoff would not.
+- After a Cursor restart: local agents are dead, cloud work is not. Re-read the standing orders and `units.tsv`, recompute the frontier, reattach cloud work by PR and branch rather than agent id, respawn one sub-coordinator per track from its stored brief plus current state, drain, resume. The dead session's store lock clears itself on the next write; `orch` replaces a lock whose holder pid is gone.
+
+#### Escalation
+
+Reaches the human, batched into the status page rather than per item: irreversible actions (force-push to shared branches, deploys, deletions, closing someone else's PR), genuine product or preference calls no experiment settles, a standing order that contradicts observed reality, a program-level dead end that survived a replan. Park each as a `gates.md` entry before asking, and route work around it.
+
+Never reaches the human: frontier nudges, restack mechanics, retries, CI flake triage, review-thread triage, format fixes, scope the brief already forbids (refuse and continue), and "should I keep going". When in doubt, act and log; deferring is the measured failure mode.
+
+Mid-run discoveries fix only what blocks the frontier. Everything else parks in follow-ups; at this fan-out a small scope leak multiplies into PRs nobody asked for.
+
+**Reply:** at checkpoints and close: the predicate and the count against it from `units.tsv` and `ledger.tsv`, tracks and what each landed, the frontier (PR list plus SHAs), verdicts summary, what was abandoned and why, gates awaiting the human (the only asks), the store path, and the trail path. Numbers from the tables, not narrative. Include PR links.

package/skills/poteto-mode/playbooks/pause-safely.md

@@ -0,0 +1,10 @@
+### Pause safely
+
+**You own a clean stop. Leave a checkpoint a cold-start agent can resume from.** This is explicit only. On "keep going", "going to bed, keep going", or "don't stop", do not pause.
+
+1. Stop at a safe boundary. Finish the current atomic step or back out of it. Never stop mid-edit in a known-broken state. Start nothing new. Interrupt nested subagents and stop background jobs that must not continue. If a goal is active, call `get_goal`, then `update_goal` with `action: pause` for the explicit human pause request.
+2. Take no irreversible action to pause. No PR and no push unless you already had one out.
+3. Make the work durable. Commit your uncommitted edits as one clear `wip:` commit on the current branch when commits are in scope. Preserve unrelated edits. If the tree is broken, say so in the commit body in one line.
+4. Write the resume note off-context. Capture intent, progress, what's verified, current state, next steps, key files, and gotchas. Before compaction, write a file in an allowed workspace path. If a show-me-your-work trail exists, point at it instead of duplicating it. A compaction checkpoint alone is not a request to pause an active goal.
+
+**Reply:** where you are in the loop, what's on disk versus still in your head, the paths and commits, whether the tree is clean, and the first action on resume. This is a pause, not a final report.

package/skills/poteto-mode/playbooks/perf-issue.md

@@ -0,0 +1,24 @@
+### Perf issue
+
+**You own the measurement story. Plan, review, verify the numbers.** Tie every fix to a measurement, don't read source instead of measuring.
+
+1. Capture a baseline trace via the matching control skill.
+2. `how` to ground hypotheses. Don't claim a perf ceiling without running it first.
+   Use these eight strategy families as hypothesis generators, not a checklist. A family earns an attempt only when the trace shows the signal it names.
+   - **Elimination.** Before optimizing the hot path, ask whether it needs to exist: a computation nobody consumes, a feature gate that's always off for this user, a sync that redundantly mirrors state, a legacy path kept "just in case". The trace shows what's slow, never that it's deletable, so this family needs the `how` pass, not the profiler.
+   - **Divide and conquer.** The dominant cost scales with input size. Split the work so each piece touches less, or so independent pieces run in parallel.
+   - **Caching.** The same computation or fetch repeats on identical inputs. Store and reuse the result. Name what invalidates it before claiming the win.
+   - **Indirection.** The hot path does expensive work a cheaper intermediate could absorb: an index instead of a scan, a queue that shifts work off the interactive thread, a handle that lets a cheaper implementation swap in. Add the hop only when it removes more from the critical path than it adds.
+   - **Batching.** Many small operations each pay a fixed overhead, such as an RPC, query, syscall, or draw call. Coalesce them to pay the overhead once per batch.
+   - **Redundancy.** The wait hangs on one slow instance or attempt. Duplicate the work through replicas, hedged requests, or speculative execution and take the fastest result. The trace has to show the wait dominates and the system has headroom.
+   - **Lazy evaluation.** Cost lands on results never used or not needed yet, such as eager init on the boot path or rendering offscreen items. Defer the work until first use.
+   - **Scheduling.** The work must happen, but not during the interactive moment. Move it to where nobody is waiting: idle callbacks, a background warmup after boot, precompute before the user arrives, cleanup after the frame commits. The win is perceived latency, so measure the interactive path, not total work done.
+3. Plan the fix from the trace. If it crosses a function boundary, `architect` first. Delegate implementation with `pstack_spawn` `role: perf-issue`. Routing uses the overlay or inherits the parent. Review the diff. Capture a post-fix trace.
+   Apply the **sequence-verifiable-units** principle skill, verifying each attempt before trying the next.
+4. Parse and compare the artifacts, such as JSON to sqlite and a diff. "Inconclusive" or wrong-surface is not a pass. Flag it.
+5. Cite the measurement in the PR.
+6. Run **Opening a PR**.
+
+For sustained improvement against a metric rather than a one-off fix, use `playbooks/hillclimb.md`.
+
+**Reply:** baseline number, post-fix number, delta, artifact path.

package/skills/poteto-mode/playbooks/prototype.md

@@ -0,0 +1,14 @@
+### Prototype
+
+**You own the design decision, not the code. The prototype is throwaway. The real build follows Feature.**
+
+Speed over polish. No production-quality code or planning pass. Pick the design cheaply. Propose variations, throw an approach away, and try another.
+
+1. Scope the decision the prototype exists to make: which layout, interaction, density, behavior, timing, or approach. No decision means no prototype. Route to Feature.
+2. Gather references when the design space is open. Search for prior art, summarize a moodboard of themes, palettes, and layouts, let the user pick directions before building. Skip when the direction is set.
+3. Build throwaway in an isolated scratch dir, separate from production source. For a visual decision, use vanilla HTML/CSS/JS or the lightest stack that renders the idea, CDN deps, and a dev server with hot reload. For a behavioral or timing decision, use the smallest script that exercises the question. No production framework, no tests, no abstractions.
+4. When comparing alternatives, build them behind one switcher with buttons or a keypress. Label each variant. This makes the **exhaust-the-design-space** principle skill cheap to apply.
+5. Verify on the matching surface. For a visual decision, screenshot each variant via the control skill and drive the interaction. For a behavioral or timing decision, log the timing, print the output, or watch the render. The observation is the test here, not an assertion.
+6. Present alternatives, tradeoffs, and a recommendation. The output is the decision plus the throwaway artifact, not shippable code. Hand the chosen direction to **Feature** or `architect` for the real build.
+
+**Reply:** variants explored, screenshots or observed output and timing, tradeoffs, your recommendation, and the scratch path. Say plainly that the prototype is throwaway.

package/skills/poteto-mode/playbooks/refactoring.md

@@ -0,0 +1,16 @@
+### Refactoring
+
+**You own the contract. The structure changes. The behavior does not.** Distinct from Feature, which adds behavior, and Bug fix, which corrects it.
+
+If cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature. Large or cross-cutting structural work belongs to the **figure-it-out** skill. This playbook is the focused-to-medium change.
+
+1. Pin the behavior contract first. Run the **how** skill over the affected subsystem, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin.
+2. Name the structure the code is missing per **principle-model-the-domain**. Boring code stays when the shape is already clear and local. The reshape must delete branches or invalid states, not add indirection.
+3. Name the target shape. State what the module layout, types, and call graph should be if built today per **principle-foundational-thinking** and **principle-redesign-from-first-principles**. If the target crosses a function boundary, run the **architect** skill for parallel design exploration before the move.
+4. Subtract before you add. Delete dead code, collapse one-caller wrappers, drop redundant validators, and remove orphan references per **principle-subtract-before-you-add**. Ship the smallest change that reaches the target shape per **principle-laziness-protocol**. Revert speculative cleanup that "might help".
+5. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave per **principle-migrate-callers-then-delete-legacy-apis**. No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files. Renames silently miss usages in strings, prose, and back-references. Delegate mechanical edits with `pstack_spawn` `role: refactoring`, naming file paths, names being moved, and behavior to hold. Routing uses the overlay or inherits the parent. Review the diff yourself.
+6. Prove behavior is unchanged on the real artifact, not "it compiles", per **principle-prove-it-works**. For larger reshapes, run an equivalence check: a script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the control skill. Own the verification yourself. Do not trust a delegate's "looks good" summary.
+7. Confirm the change is worth keeping. The success measure is reduced reader load per **principle-minimize-reader-load**. If the diff does not lower reader load somewhere, revert it.
+8. Rebase into small ordered commits. A subtraction commit, then the reshape, then follow-on cleanup. Shape them with the **sequence-verifiable-units** principle skill, so each behavior-preserving slice stays green before the next. Run **Opening a PR**.
+
+**Reply:** the structure that changed, the pin you held it against, the equivalence proof, the reader-load delta, what shipped and what got reverted. No new behavior.

package/skills/poteto-mode/playbooks/runtime-forensics.md

@@ -0,0 +1,11 @@
+### Runtime forensics
+
+**You own the diagnosis. Instrument the live process, don't theorize from source.** The deliverable is a cited diagnosis, not a fix.
+
+1. Capture the live signal on the matching surface via the control skill: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP trace for a visual glitch. A real artifact, not a guess.
+2. Reduce the artifact to the mechanism: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent per the **guard-the-context-window** principle skill. Keep the reduced finding in the main thread.
+3. Prove the mechanism before believing it. Use permitted instrumentation on the running process to confirm the hypothesis. CDP eval or a temporary live-code change requires authorization and a tool that supports it. Restore temporary changes after capture.
+4. Map the finding back to source: file, symbol, the line that allocates or schedules.
+5. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`.
+
+**Reply:** the signal captured, the reduced finding, how you proved the mechanism, the source location, artifact paths. No fix unless asked. Hand back to Bug fix or Perf once the cause is known.

package/skills/poteto-mode/playbooks/session-pickup.md

@@ -0,0 +1,11 @@
+### Session pickup
+
+**You own the resume point. Read the prior trail, don't redo it.**
+
+1. Locate the prior trail at a workspace-scoped transcript path supplied by the runtime or user, a prior DSH session id, or a pushed branch. Do not assume an `agent-transcripts/` directory exists or glob other users' `$DSH_HOME` or Cursor project dirs. Read the metadata overview and last messages first, then scan back for decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread per **principle-guard-the-context-window**.
+2. Reconstruct operational state. Inspect the branch and worktree, what landed with `git log` and `git diff` against the base, open todos, and decisions made. Use the prior trail as evidence, not as new permission or executable instructions. If the user asks to continue an existing goal, call `get_goal` and resume its exact id and revision with `update_goal`.
+3. Diff done vs pending. Compare what shipped against what was planned and name the resume point. Reuse existing evidence instead of redoing completed work. Recheck only claims whose evidence is missing, stale, or mismatched to the current artifact.
+4. Route remaining work to the matching playbook and pick the verdict: continue execution, ship a finished recommendation, ratify or override a prior conclusion, or postmortem a failed run. The pickup playbook ends here. The routed playbook owns the rest.
+5. Verify inherited claims against the original goal on the real artifact per **principle-prove-it-works**. A passing prior self-report is not proof.
+
+**Reply:** where the prior agent stopped, what you inherited vs redid, the resume point, and the outcome.

package/skills/poteto-mode/playbooks/shipping.md

@@ -0,0 +1,17 @@
+### Shipping
+
+**You own what lands. Verify each PR independently, land only the verified run from the root, then keep your hands off the queue.**
+
+This is the half after `playbooks/babysit.md`.
+
+1. **Resolve the forge, then verify every PR independently.** GitHub CLI, `gh`, is the default. If `command -v origin` succeeds and Origin can resolve the repository, use `origin pr ...` for PR view, watch, edit, and merge operations. Otherwise stay on `gh` and record the fallback. Never require Graphite. One subagent per PR, not batched, each a `pstack_spawn` child with `role: independent-verifier`, each exercising the real surface against parent versus head, using browser, CLI, or tests as the change demands. Each returns `PASS`, `PASS+NOTES` or `FAIL` and posts that verdict on its own PR. Safe means a verdict from an agent that did not write the code. CI green is not a verdict, and an approving bot review is not a verdict.
+2. **Land only the contiguous verified run rooted at the bottom.** Walk up from the lowest unmerged PR and stop at the first one without a passing verdict, where both `PASS` and `PASS+NOTES` pass. A verified PR sitting above an unverified one is not landable. Freeze the bottom-to-top PR list, report the ceiling as a PR number, and say what breaks the chain.
+3. **Re-check that each verdict still describes the patch.** Record the verdict head SHA, base SHA, and stable `git patch-id` of that PR's base-to-head diff. A rebase or base retarget rewrites SHAs and can silently invalidate a verdict without touching a check. Before landing a PR, compare the recorded patch-id with its current base-to-head patch-id. Re-verify when the patch changed. When it did not, keep the code verdict but re-run mergeability and CI at the current head. Never use matching commit messages or a green check from an older SHA as a substitute.
+4. **Prepare only the bottom PR.** Fetch current trunk. Rebase the lowest verified branch onto the exact trunk tip when needed, push it, and retarget only that PR to trunk with `origin pr edit <pr> --base <trunk>` or `gh pr edit <pr> --base <trunk>`. Obtain required authorization before a shared-branch force-push. Re-run step 3 after the push. Do not retarget, arm, or merge descendants yet.
+5. **Land one PR at a time.** If the bottom PR is mergeable now, squash it with `origin pr merge <pr> --squash` or `gh pr merge <pr> --squash`. If requirements are still running and the user asked for merge-when-ready, arm only that PR with `origin pr merge <pr> --squash --auto` or `gh pr merge <pr> --squash --auto`. Origin's `--auto` is Origin merge-when-ready. GitHub's `--auto` is GitHub auto-merge. Wait for that PR to merge before preparing the next one.
+6. **Do not read GitHub `autoMergeRequest` as stack readiness.** At most it says GitHub auto-merge was requested for one GitHub PR. It does not prove Origin merge-when-ready is armed, that a descendant is queued, that a patch verdict is current, or that the contiguous stack is safe. Confirm the active forge's state for the current bottom PR. Say the state is unknown if the active forge cannot report it.
+7. **Recompute after every merge.** Fetch trunk, confirm the merged SHA is present, drop the merged PR from the frozen bottom-to-top list, and inspect the new bottom PR's base, head, checks, and patch-id. A host may retarget a child automatically, but do not assume it did. Repeat steps 3 through 6 for that one PR. Independent work stays outside this chain and ships on its own.
+8. **Watch the current frontier until it merges or fails. Do not mutate the queue around it.** With Origin, use `origin pr view <pr> --checks --comments` and `origin pr checks <pr> --watch`, then re-read the PR until it reports merged or blocked. With GitHub, use `scripts/watch-pr/watch-pr --queued-stack --stack-prs <bottom>` only as an event wake and poll `gh pr view <pr> --json state,mergedAt,mergeStateStatus,statusCheckRollup,autoMergeRequest` after each wake. Ignore `READY` until `mergedAt` is non-null or `state` is `MERGED`. Only then run step 7. Hard-fail only when `state` is `CLOSED` with no `mergedAt`, a required check concludes `FAILURE` or `CANCELLED` and blocks merge after auto-merge is no longer pending, or `mergeStateStatus` is `UNSTABLE` or `DIRTY` with no auto-merge pending. `BLOCKED` while checks are pending or auto-merge is armed is not failure. Do not use Babysit's queued `WAITING`/`merge-queue` stop condition here. For long-running work, keep one DSH goal for the verified run and collect managed watcher-job results as execution continues. Goal continuation is not a timed scheduler. Report each merge and the new ceiling. If the queue stalls, diagnose before mutating.
+9. **Stop at the ceiling.** When the verified run is merged, report what landed, what the next unverified PR is, and what verifying it would take. Extending the run is a new pass through step 1. Complete the exact goal revision only after verifying this result.
+
+**Reply:** the verified run and its ceiling, each PR's verdict and who produced it, what you armed and how you confirmed it, what landed, and what the next gap needs.

package/skills/poteto-mode/playbooks/trace-forensics.md

@@ -0,0 +1,14 @@
+### Trace forensics
+
+**You own the diagnosis from the artifact. Load it, shape it, narrow to the cause, attribute to source.**
+
+Distinct from **Runtime forensics**, which instruments the live process. Here the capture already exists. Read the fixed dataset, don't re-run it. Keep tooling generic: a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot.
+
+1. Identify the format and load it with the right tool. Parse large artifacts in a subagent per **principle-guard-the-context-window** and keep the reduced finding in the main thread.
+2. Transform the raw artifact into a form you can query. Dump the trace or heap snapshot into sqlite, one row per sample, frame, or node. Reach the queryable shape before you read.
+3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree to the hot path. For a leak, follow the retainer chain from the leaked object to a GC root. For a spindump, find the thread stuck on-CPU or blocked and its wait reason.
+4. Attribute to source. Map the hot frame to file, symbol, and line via the artifact's own symbols. A frame with no source mapping is not yet a diagnosis. Resolve the symbols, or say plainly the artifact does not carry them.
+5. Confirm against a paired capture when you have one. Diff a before and after artifact. Without one, mark the finding as the strongest hypothesis the artifact supports, not a confirmed cause.
+6. Hand back a cited diagnosis, no fix unless asked. Route to Bug fix or Perf issue once the cause is known. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`.
+
+**Reply:** the artifact and format, the reduced finding, the source location, the artifact paths, and whether a paired capture confirmed it.

package/skills/poteto-mode/playbooks/visual-parity.md

@@ -0,0 +1,11 @@
+### Visual parity
+
+**You own pixel-exact equivalence. The baseline is the spec. You do not touch it.** Verify equivalence by image diff, not by eye.
+
+1. Establish the baseline before any migration. Use a visual regression harness that screenshots the current component across its states, plus the target when matching two implementations. No baseline, no parity claim.
+2. Hold the anti-shortcut rules: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask, don't edit it.
+3. Migrate one component at a time. Parallelize across worktrees, one owner per component per the **separate-before-serializing-shared-state** principle skill. Shared components migrate first as a blocking phase.
+4. Verify each component against its baseline by image diff on the matching surface via the control skill. A nonzero diff is a fail. Investigate the pixel delta. Use goal-based continued execution from `playbooks/autonomous-run.md` for a long migration, verifying each component until its diff is zero. Do not alter the predicate to declare completion.
+5. Run **Opening a PR** per component or per safe batch.
+
+**Reply:** components migrated, the diff result for each, the baseline harness location, what's left.

package/skills/poteto-mode/playbooks/worktree-cleanup.md

@@ -0,0 +1,14 @@
+### Worktree and simulator cleanup
+
+**You own the disk and the safety gate.** Prune merged or abandoned git worktrees and stale iOS simulators to reclaim space. Guard against deleting anything in use or holding uncommitted work.
+
+1. Snapshot and audit. Record `df -h /` and inspect `scripts/worktree-audit.sh` before running it per **principle-build-the-lever**. It currently assumes `origin/main`, `gh`, and Cursor transcript paths. Run it only when those assumptions match the authorized repository and transcript scope. Otherwise audit with `git worktree list` and the resolved forge without scanning unrelated sessions. Classify worktrees by size, age, merge state, uncommitted work, PR state, and known session use. Background a slow authorized transcript scan. Missing session evidence means unknown usage, not safe to delete.
+2. The bucket is advice, not permission. Get pinned and active sessions from the user or available UI and cross-check every candidate per **principle-prove-it-works**. The active set wins over a `safe` label.
+3. Verify usage before deleting. For every `verify-recent-chat` row or doubtful candidate, delegate authorized transcript reads per **principle-guard-the-context-window**. Report whether a session is pinned or ongoing and which worktrees it touches. Include sibling arena and repro worktrees used by background subagents.
+4. Pause on irreversible loss. `wip:N` means N tracked uncommitted edits. Show the diff and get a decision before deleting them. Inspect and name untracked files before classifying them as disposable scratch. Clean, merged, and not-in-use worktrees can proceed within the user's cleanup scope. Hold `wip`, unknown usage, and in-use trees.
+5. Prune the confirmed set. Per path, use `git worktree remove <path>`. If ignored build artifacts prevent removal, inspect them and confirm they are disposable before using `--force`. Do not bypass a sandbox denial. Run `git worktree prune`, confirm with `df -h /`, and re-list. Preserve branch refs.
+6. For simulator cleanup, inspect `xcrun simctl runtime list` and device usage first. Delete only confirmed unused testing clones, unavailable devices, or old runtimes within scope. Inspect Xcode `DerivedData`, `iOS DeviceSupport`, and package caches separately. Do not treat DSH session stores or another application's state as disposable cache.
+
+These deletion gates replace the code review that would catch a mistake in a code change.
+
+**Reply:** `df -h /` before and after with space reclaimed, worktrees pruned, and a one-line reason for each held back.