@1aboveio/skills 1.0.10 → 1.0.11

package/skills/engineering/resolve-issues/references/task-plan.md

@@ -5,16 +5,17 @@ worker and stage transition.
 
 ## Initialize the run
 
-1. Reclaim disk from idle runs, then create a run directory:
-
-   ```bash
-   node <skill-base-dir>/scripts/cleanup-runs.mjs --repo <repo-root> --apply
-   ```
-
-   It deletes downloads from runs idle 3+ days and keeps their records and
-   logs; logs go after 30 days. Report its last line; never block on it. After the approval, give each unit a branch and
-   workspace on the target, or on its blocking parent's branch in `stack`
-   or `chain` mode. Never reuse a dirty, unrelated checkout.
+1. Create the run directory, and reclaim nothing by age: a tree is removed only
+   by its own unit's proven cleanup ([workspaces.md](workspaces.md#cleanup-after-delivery-before-finish)).
+   Record `workspaceLifecycle: 1`, `repoRoot` (the canonical absolute main
+   checkout) and `targetBranch`. After the approval, plan each unit a branch and
+   workspace on the target, or on its blocking parent's branch in `stack` or
+   `chain` mode, and prepare it when its first worker is admitted
+   ([workspaces.md](workspaces.md#prepare-at-admission-once)). Never reuse a
+   dirty, unrelated checkout. On start and on resume, first run
+   `cleanup-runs.mjs recover --repo <repo-root> --json`: read-only, it reports
+   unfinished prepare and cleanup operations of any age, and hands the plan back
+   ([workspaces.md](workspaces.md#resume-recover-inventory)).
 2. Make each issue one unit: every open issue in the spec's tree with no
    open sub-issue (a plain issue, an epic's open leaf, or a rollup whose
    sub-issues all closed); a spec without issues is one unit.
@@ -50,9 +51,10 @@ worker and stage transition.
   task-plan.json
   issue-tree.json             # spec's GitHub issue tree, saved by each sync
   exploration/findings.json
-  units/<unit>/               # unit workspace; cleanup-runs.mjs strips it after merge, keeping logs
+  units/<unit>/               # the unit's workspace; removed by its cleanup after the merge
+  resources/<unit>/<role>/    # scratch or tool cache, only when the unit needs one
   splits/<unit>.md            # drafted sub-issues for a held unit
-  reviews/<unit>/             # review clone, reused every round
+  reviews/<unit>/clone/       # the unit's one review clone, reused every round
   reviews/<unit>-r<N>.json    # one per round
   reviews/<unit>-r<N>.fix.json  # fixBrief from review-verdict.mjs
   reviews/<unit>-r<N>.decide.json  # question from review-verdict.mjs verdict decide
@@ -63,6 +65,12 @@ worker and stage transition.
 
 ## Shape
 
+Write each unit's `title` as a short action in plain language, usually 3-7 words:
+"Fix checkout errors" or "Add the Todo toggle". Keep implementation details and
+acceptance criteria in the source and findings, not the Todo label. A long GitHub
+issue heading need not be copied verbatim; preserve its issue reference and full
+source requirements.
+
 Fleet rows: `explore`, then per unit `implement`, `review`, `ci`, `canary`.
 Fleet `status`: `pending`, `in-flight`, `succeeded`, `failed`,
 `blocked`, `cancelled`, `not-applicable`, or `merged` (`ci` only). Set
@@ -72,6 +80,7 @@ Fleet `status`: `pending`, `in-flight`, `succeeded`, `failed`,
 |---|---|
 | `id`, `title`, `issue`, `source` | Identity and locator |
 | `workspace`, `branch`, `base` | Absolute workspace, branch, and base |
+| `lifecycle` | The owned workspace and resources with their kind, base SHA, identity, and cleanup state, as `cleanup-runs.mjs` returns them ([workspaces.md](workspaces.md)) |
 | `dependsOn`, `stacksOn` | Blocking and shared-surface parent ids (in `stack` and `chain` mode, `stacksOn` is the parent `next-actions.mjs` names at open) |
 | `files` | The unit's own changed files, recorded when its code is done (`stack` and `chain` mode pick the parent from them) |
 | `parentHead` | `stack` and `chain` mode: the parent's HEAD this branch is rebased on; a line ships only when every link matches |
@@ -100,7 +109,8 @@ and nothing earlier. Until the merge it stays
 Example: #1201's code is done and its PR is in review, so it is
 `stage: done`, `status: in-flight`, `delivery: review`. In `supervised` mode, a
 merge-ready PR handed back stays `in-flight` with the note "merge-ready,
-handed back"; it is never `succeeded` until the human merges it.
+handed back"; it is never `succeeded` until the human merges it. Its
+`lifecycle.cleanup` follows that merge and never changes `status`.
 
 Run fields: optional `installation` holds the explicit native installation descriptor
 (one absolute root, layout, resource metadata path/digest, release identity, and
@@ -108,6 +118,7 @@ pinned external root mappings). Capture from the selected bundle and preserve it
 through workers and recovery; never replace it with a newer cache or shared copy.
 Other run fields: `skill` (`resolve-issues` or `rush-issues`; the scheduler and
 rehydrate read it, and `next-actions.mjs` exits 2 without it), `planRevision`, models and efforts, `targetBranch`,
+`workspaceLifecycle: 1` and `repoRoot` ([workspaces.md](workspaces.md)),
 `deliveryMode` and its check, `mergeMode`, run directory, `specLocator`
 (`owner/name#N` or an issue URL; any other name turns off the issue-tree sync),
 exploration path, `decisions`, `standingOrders`, `schedulerMode` (`full`, `narrow`, or `off`), timestamps, and `excluded` (issues in the
@@ -152,8 +163,8 @@ run state.** Every open issue in the tree with no open sub-issue is a unit,
 ordered by `blocked_by` links. On every call with
 [live capacity arguments](implementation.md#live-capacity), `next-actions.mjs` diffs the plan against
 the tree and prints `add-unit`, `drop-unit`, `set-deps`,
-`move-link`, and `blocked-outside` first; apply each through `update_plan` (or,
-for `move-link`, on GitHub) before anything else. A unit waits only on its own
+`move-link`, and `blocked-outside` first; apply each through the available
+checkpoint mechanism below (or, for `move-link`, on GitHub) before anything else. A unit waits only on its own
 issue's `blocked_by` links, never on a link on its parent issue.
 Example: someone files #61 under epic #12 mid-run; the next resume prints
 `add-unit 61`, so explore it, rerun the size check, and schedule it.
@@ -192,10 +203,28 @@ normally.
 
 ## Checkpoints
 
-### Pi: bind or reload with update_plan
+### Optional Harness Outcome & Todo
+
+Use only tools advertised in the current turn. Pi's `/harness-settings` Outcome & Todo
+feature defaults to off; never enable it or make it a precondition. When `update_todo`
+is available, capture the known objective before substantive work with
+`update_todo({outcome:{objective:<objective>}})`. An outcome alone is valid; a checklist
+is not required. Include known criteria, boundaries or source only when useful; do not
+invent criteria or duplicate a large canonical requirement. The source requirements and
+criteria remain authoritative. The latest user correction takes precedence, and a reminder
+does not authorize continuing work. Merely discovering or reading this skill never
+initializes an outcome; capture it only for the accepted task being executed.
+There is no separate setup step. Goal controls triggering and continuation, not
+the business outcome.
+
+When the workflow plan exists, read its `planRevision`, then bind it using `update_todo`
+with the absolute path and that revision, optionally including the known outcome:
+
+```text
+update_todo({workflow:{path:<absolute-plan-path>,revision:<persisted-planRevision>}, outcome:{objective:<objective>}})
+```
 
-`update_plan` is the universal plan entrypoint. Read the saved plan's
-`planRevision`, then bind it with the absolute path and that revision:
+For example, the workflow payload is:
 
 ```json
 {"workflow":{"path":"/absolute/project/.resolve-issues/rush/<run-id>/task-plan.json","revision":12}}
@@ -207,11 +236,11 @@ With no `event`, this is a read-only binding: it does not mutate the plan or
 bump its revision. Do not invent a transition just to display or reload the
 board.
 
-After binding, save each transition through `update_plan`, using the current
+After binding, save each transition through `update_todo`, using the current
 persisted revision and the tool's supported change entries:
 
 ```text
-update_plan({workflow:{event:"unit-validated",revision:12,changes:[...],decision?}})
+update_todo({workflow:{event:"unit-validated",revision:12,changes:[...],decision?}})
 ```
 
 `decision?` denotes an optional field, not a literal key; supply it when the
@@ -222,20 +251,28 @@ transition. Binding and the first transition may be one call with
 `path`, `revision`, `event`, and `changes` inside the same `workflow` object
 (and `decision` when needed).
 
-Never edit `task-plan.json` directly after binding. On rejection, reread the
+While the interface is enabled and bound, never edit `task-plan.json` directly. On rejection, reread the
 saved plan, reconcile the intended changes, and retry with its persisted revision; use a path-and-revision
 call with no event when only reloading. Never force a stale revision or
 display rejected changes as saved.
 
-Generic checklists still use `update_plan({plan:[...]})` unchanged. They are
-not a workflow binding or transition: never copy this run's units into a
-generic editable checklist.
+`get_todo`, when advertised, reads the outcome, checklist and workflow. Generic work
+may use `update_todo({todo:[...]})` with the tool's `id`, `step`, `status` and
+`dependsOn` fields. It is not a workflow binding or transition: never copy this
+run's units into a generic editable checklist. Todo is an interface label, not a
+rename of `task-plan.json`, `planRevision`, profiling or their schemas.
 
 ### Other harnesses and display
 
-Use a workflow-capable plan tool when available. Only when none can write
-the workflow and the plan is not bound, edit run state directly and bump
-`planRevision`. This fallback is not a way around a rejected bound update.
+With `update_todo` absent or disabled, including on Codex and other harnesses,
+the skill still owns its canonical run records. Use the existing file transition:
+edit run state, preserve the schema and existing records, bump `planRevision`, and
+record any profiling entry the workflow requires. A binding retained after the
+human disables the interface is history, not an active exclusive writer. Reload
+the actual persisted revision if the interface is later enabled again.
+`plan-sync.mjs` only reports scope differences; it is not a transition API. Never
+use this fallback to bypass a rejected update from an available tool: reconcile
+and retry through that tool. A validation error is not tool absence.
 
 Render the board from the saved plan only. Without a harness view, show the
 text board. Keep the board and file in agreement. Never show an unsaved transition or reuse an old board.

package/skills/engineering/resolve-issues/references/workspaces.md

@@ -0,0 +1,164 @@
+# Workspaces
+
+One rule set for the trees a run creates. A unit's workspace and resources are
+owned by the plan, never by a path pattern or a timestamp: nothing is created
+before the plan records it, and nothing is removed without proof of ownership
+and delivery.
+
+## What the plan records
+
+Run fields: `workspaceLifecycle: 1`, `repoRoot` (the canonical absolute main
+checkout) and `targetBranch`. A unit already records `workspace`, `branch` and
+`base`; with `workspaceLifecycle` it also records `lifecycle`:
+
+```json
+{ "version": 1,
+  "workspace": { "kind": "worktree|clone", "state": "preparing|ready",
+                 "baseSha": "<exact SHA>", "identity": "<returned by the helper>" },
+  "resources": [ { "role": "review|scratch|tools", "kind": "directory|clone|worktree",
+                   "path": "<absolute>", "disposable": true,
+                   "state": "preparing|ready", "identity": "<returned by the helper>" } ],
+  "cleanup": { "state": "pending|applying|complete|retained",
+               "headSha": "<the unit's headSha>", "reason": "<retained only>" } }
+```
+
+| Tree | Path |
+|---|---|
+| Workspace | `<run>/units/<unit>` |
+| Review clone | `<run>/reviews/<unit>/clone`, the resource with `role: review` |
+| Scratch, tool cache | `<run>/resources/<unit>/<role>` |
+
+A resource is a path strictly inside one of those three roots (the workspace's
+children, `<run>/resources/<unit>/`, `<run>/reviews/<unit>/`), and it is planned
+before it exists. Nothing else in the run is an owned tree. Record every path in
+the canonical form the helper resolves (a `/var` path and its `/private/var`
+realpath are different strings): `repoRoot`, the run directory, the workspace and
+every resource.
+
+`identity` is the helper's own observation (real path, device, inode, Git
+common dir, head): persist what it returns, never compose or edit it. You are
+the plan's only writer ([task-plan.md](task-plan.md)); the helper returns
+observations and the next lifecycle value, and writes no plan.
+Persist every lifecycle transition using the canonical
+[checkpoint mechanism](task-plan.md#checkpoints): the optional bound harness
+interface when enabled, otherwise the revisioned file transition. The optional
+interface's absence never blocks workspace preparation or cleanup.
+
+Prepare materializes each resource according to its recorded kind: a review clone
+must be a real independent Git tree before it becomes ready. Its empty
+`<run>/reviews/<unit>` parent is a run container, not a second clone.
+
+## Prepare: at admission, once
+
+Prepare a unit's workspace when its **first worker is admitted**, not for every
+planned unit up front and not at the approval. Disk then tracks live workers,
+not plan size. Prepare the review resource when its reviewer is admitted.
+Do not admit another worker while that owner's cleanup is `applying`; the
+`recover-workspace` action resolves the existing operation and its postconditions first.
+
+1. Before `--apply`, record through the checkpoint mechanism: the unit's workspace, branch,
+   base SHA, `lifecycle.workspace` intent (`state: preparing`, chosen `kind`)
+   and each resource you will use (`state: preparing`). The helper refuses a
+   workspace or resource path the plan does not own, and creates only the
+   resources the plan lists.
+2. Run it. Without `--apply` it creates nothing and names the action
+   (`create` or `verify`):
+
+   ```bash
+   node <skill-base-dir>/scripts/cleanup-runs.mjs prepare --run <run> --unit <unit> \
+     --revision <saved planRevision> [--kind worktree|clone] --apply --json
+   ```
+
+   Exit 0 is a create or a verification; exit 2 is a refusal with a code
+   (`workspace-layout`, `revision-mismatch`, `unowned-tree`, `locked`, ...): fix
+   the plan or the call, never the tree.
+3. Persist the returned `nextLifecycle` on the unit **before** spawning the
+   worker, and give the worker that workspace path and only the resources it
+   needs. Resources are recorded before they are used.
+4. Reuse it. Retries, fix rounds, and every review round run in the same
+   workspace and the same review clone; a later prepare verifies identity,
+   branch, and base instead of recreating. Never reset, replace, or allocate a
+   second tree for one attempt, and plan a private tool cache or scratch copy
+   only when the work needs one.
+
+`kind`: a linked `worktree` where a plain checkout is enough; an independent
+`clone` when the first Git-mutating worker runs in a sandbox that cannot write a
+linked worktree's `.git` file. Prepare falls back to a clone only when it
+created nothing it can identify. Once the clone exists, do not pass the
+harness's `git_clone_workspace` again, and never turn the sandbox off to work
+around it: the prepared tree already isolates the unit.
+
+## Cleanup: after delivery, before finish
+
+Clean a unit when it is `status: succeeded` with `delivery: merged`, and in
+`supervised` mode once the human has merged the handed-back PR. Cleanup runs
+alongside every independent unit and in every scheduler mode (`full`, `narrow`,
+`off`), and settles before the run's handoff.
+
+1. Record the intent first, so a crash cannot hide it: `lifecycle.cleanup`
+   `{state: "applying", headSha: <the unit's headSha>}` through the checkpoint mechanism.
+2. Run:
+
+   ```bash
+   node <skill-base-dir>/scripts/cleanup-runs.mjs cleanup --run <run> --unit <unit> \
+     --revision <saved planRevision> --apply --json
+   ```
+
+3. Persist the returned `nextLifecycle`: `complete` with its receipt, or
+   `retained` with the current head and the helper's reason. Exit 0 is a removal
+   or an `already-complete` postcondition, 1 is a retention (read `action` and
+   `reason`; do not retry the same removal to make it pass), and 2 is a refusal
+   or a bad call that must be fixed. A refusal is never recorded as complete.
+
+The helper removes exactly the recorded workspace and its declared disposable
+resources, and only after it proved: the unit is completed and its delivery
+merged; its owner has no recorded running worker and no process uses any removal
+path (unrelated workers continue); the tree matches its recorded
+identity, kind, branch, and head; no process uses it; no stash, interrupted Git
+operation, nested repository, uncommitted or untracked path, undeclared ignored
+path, local ref, or reflog commit is unpublished; and the head is on a freshly
+fetched target. A squash merge instead needs the provider's PR identity (repo,
+number, head repo/branch/SHA, destination) with a merge commit on that fresh
+target.
+
+It removes nothing else: no ignored-file stripping, no pruning, and no
+`--merged <path>` on its own, because a path proves no owner. Every unknown
+answer retains everything, whole. Keep, never clean: a blocked, cancelled,
+pending, or supervised merge-ready unit's environment, whatever its timestamp; a
+tree a worker may still use; a tree whose ownership or delivery cannot be proved.
+No cleanup runs by age, idle time, or a name pattern, and a legacy
+`*-workspaces` directory is never adopted or deleted.
+
+## Evidence and handoff
+
+Record required evidence while the unit runs as
+`lifecycle.evidence: [{path, required: true}]`, each path outside every
+disposable path. The helper retains an environment whose required evidence still
+lives inside it. Copy no logs, transcripts, or screenshots just to free a tree.
+
+`retained` is an honest handback: report the environment as **not cleaned** with
+the helper's reason, and name it in the run record. `pending` and `applying`
+cleanup block `finish`; settle each delivered unit's cleanup first
+([done.md](done.md#clean-before-handoff)).
+
+## Resume, recover, inventory
+
+On startup, before scheduling, read only:
+
+```bash
+node <skill-base-dir>/scripts/cleanup-runs.mjs recover --repo <repo-root> --json
+```
+
+It lists unfinished recorded operations — a `preparing` workspace, an `applying`
+cleanup, a lock, an orphaned worktree — in every run regardless of age. It
+activates no workflow and cleans nothing by itself: continue the plan, then
+prepare or clean what it names and persist the result.
+
+```bash
+node <skill-base-dir>/scripts/cleanup-runs.mjs inventory --repo <repo-root> [--root <explicit root>] --json
+```
+
+is read-only and bounded: it lists the managed root (`<repo>/.resolve-issues/rush`)
+with each tree's owning unit, and marks unowned entries. Use it to answer what is
+on disk, never as authority to delete. Legacy `*-workspaces` directories and
+unrecorded trees appear there as inventory only.