@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,318 @@
+# Expiry and stuck units
+
+Expire an attempt at these limits. Never drop an expired unit from the spec.
+
+**Count progress, not attempts: expire after 2 cycles without progress, and
+never after a fixed number of cycles.** A fix cycle makes progress only when
+its count reaches a new low, below every earlier cycle of the attempt; a
+commit alone is not progress. Lows only fall, so the loop always ends.
+Example: CI fails 5 tests, then 3, then 3, then 3: expire after the fourth
+cycle. 3, 2, 3, 2 expires too: the second 2 is no new low. 5, 4, 3, 2, 1
+never expires. A failing journey run, local or dispatched, counts as one
+failing check, so count its furthest checkpoint instead (the last step its
+log reports passing): login, store, charge, charge, charge expires;
+login, store, charge, receipt keeps going. Checkpoints are finite, so this
+loop ends too.
+
+| Scope | Count that must reach a new low | Expire after |
+|---|---|---|
+| Exploration | size-check problems plus empty units | 2 continuations without progress |
+| Implement, validate, self-review | failing checks and tests | 2 fix cycles without progress |
+| Warehouse canary | distinct errors | 2 attempts without progress; record a follow-up, never block |
+| Review | open P0/P1 path rows | `review-verdict.mjs` verdict `handback` ([review.md](review.md#fix-loop)) |
+| CI and merge | failing checks and tests; a failing journey run (local or `gh workflow run`) is one check, so it progresses when it passes a checkpoint no earlier run of the attempt passed | 2 fix-and-watch cycles without progress |
+| Any worker the harness reports stuck, late, or at its ceiling | none: a resume [progresses](#retry-by-failure-mode) when it adds work the unit's PR needs (product code, tests, CI config, a fix of what blocks it) or meets another acceptance criterion; diagnostics and records alone are not progress | 2 resumes in a row that add neither |
+
+Leave timing to the harness; never stop a worker still making progress.
+
+### Retry by failure mode
+
+**Name the failure mode before any retry, and respond to the mode, never with
+the same attempt.** Record it as the block's `failureMode`.
+
+| Mode | How it shows | Response | Attempts |
+|---|---|---|---|
+| `cap-hit` | the worker hit its context, output, or turn ceiling | resume in the kept workspace with only the remaining scope; split what still does not fit | while each resume makes progress (above) |
+| `oom` | killed for memory or disk, or the host reserve is gone | rerun with smaller scope or fewer heavy jobs at once | 2 |
+| `network` | EOF, TLS reset, 5xx, rate limit, runner offline: the same command passes elsewhere or later | rerun it unchanged at about 5, 15, then 45 minutes; then block the blocker unit as `external-blocker` | 3, then rechecked over time |
+| `tool-error` | a tool crashes, the model refuses or drops its stream, the worker dies (`spawn-death`) | retry on another permitted model, or with another tool when the model is pinned | 2 |
+| `denied` | the sandbox or harness refuses a command | one permission request through the harness, then a different permitted action that reaches the same outcome (never the same action by another channel or with a sandbox, hook, or setting turned off); with none, a handback step | 1 |
+| `test-fail` | a test, check, or CI job fails on the change | find the cause and fix it ([Infrastructure failures](#infrastructure-failures) when it is not the change) | until 2 cycles without a new low |
+| `stalled` | 2 cycles without a new low, or resumes that make no progress | change the strategy, the scope, or the model; never resend the brief | 1 replan |
+| unknown | none of the above | retry once, then name the mode from what that run shows | 1 |
+
+This table is the one retry ladder: the attempts here run inside a cycle, and the scheduler's
+timed rechecks (below) start only after them. When a mode's attempts run out, abandon that
+approach, not the unit and never the run: block the unit with its `blockedReason`, `failureMode`, and
+`blockedAt`; the scheduler retries it over time (below) while every other
+unit keeps going.
+
+## Decide before you defer
+
+**A unit stalled on a choice needs an answer, not another attempt.** Every
+stop is one of two kinds: the work is not improving (the counts above), or it
+waits on a choice: what the spec means, which design, which approach. A
+retry, a resume with the same brief, or a deferral never makes a choice, so
+none of them unblocks the unit.
+
+- Workers report a choice in their result's `decisionNeeded`: the question,
+  the options, and a recommendation. A failure they can fix is not a choice.
+- `review-verdict.mjs` returns `decide` when a spec finding comes back with
+  the same trigger and the same open paths; its decide file holds the
+  question ([review.md](review.md#fix-loop)).
+- `next-actions.mjs`, invoked with [live capacity](implementation.md#live-capacity), prints `decide` for the unit until a `decisions` entry
+  whose `answers` names the question's file answers it; the unit takes no
+  other step until then, and in `rush-issues` the run cannot finish.
+- Answer it with the [automatic answer](preflight.md#never-block-on-the-human). Then the unit's next step
+  follows: a resume or fix that carries the decision. That attempt always
+  runs, whatever the no-progress count; the ones after it count as usual.
+- Defer a choice only when every answer loosens an acceptance criterion, a
+  required check, or a merge rule, or needs access the run does not have;
+  record that as the decision, with the reason. First trace each side of a
+  conflict to the human's criteria: a requirement that comes from how the
+  run chose to meet a criterion is a design choice the run can change.
+- A recommendation to stay blocked, keep a candidate retained, or defer is
+  not an answer: answer the question beneath it (which way meets the
+  criterion); a limit that is not a [standing order](task-plan.md#standing-orders)
+  rules no way out.
+  Example: a worker recommended keeping a deploy-check unit blocked because
+  no permitted way could read the staging logs; the "no log access" limit
+  came from a split an earlier run filed and one denied command, so the
+  answer was to read the logs through the repository's documented CLI.
+
+Example: #2533's fix worker returned "needs a boundary that proves the upload
+body completed"; the run resumed it twice with the same brief and deferred
+it. Deciding "verify by reading back the exact generation it wrote" was the
+step that unblocked it. Likewise, a report job that held every row in memory
+broke its 2 GB memory criterion; the criterion asked for the report, not
+in-memory rows, so streaming the rows kept the limit and needed no human.
+
+## Waits
+
+**Every wait has a deadline; silence past it is a failure, not progress.**
+Example: a worker ran from 08:16; its workspace last changed at 09:10, and
+nothing was checked until the human asked at 11:19. It had been stuck for two
+hours.
+
+- Record `workerSince` when you start a worker. While any worker runs, keep
+  one heartbeat running (a background `sleep 1800`) so a completion notice
+  reaches you even when no worker finishes; on each notice read fresh capacity
+  and run `next-actions.mjs` with the [live capacity arguments](implementation.md#live-capacity).
+  When it prints only `wait`, keep the heartbeat and end the turn: the harness
+  wakes the run at the printed time.
+- `check-worker` means the worker changed no workspace file for
+  `--quiet-minutes` (45 by default): read its latest output. Stuck: stop it
+  and take the `timeout-task` response. Still working (a long test run with
+  live output): let it run.
+- A watcher that ends with nothing new (a queue `STALLED` with no failing
+  check) is a wait: restart it and report it in one line, or not at all.
+
+### Reason codes
+
+Record why a unit stopped in its `note`: `retry-explore`, `retry-implement`,
+`retry-canary`, `retry-review`, `retry-ci`, `timeout-task`, `spawn-death`,
+`rebase-conflict`, `external-blocker`, `human-decision`, `review-handback`.
+**A unit stays `blocked` only with a `blockedReason` from this subset:**
+`retry-explore`, `retry-implement`, `retry-review`, `retry-ci`,
+`timeout-task`, `spawn-death` (each after its cycles without progress),
+`external-blocker` (a blocker unit whose cause lies outside the run, such as
+a shared runner outage or a provider fault: [Infrastructure failures](#infrastructure-failures) step 4),
+`human-decision` (an item on the [human-only](#human-only) list, named as
+`humanItem` 1–5 with `humanNeed`, what the human must do; without both,
+`next-actions.mjs` reopens it),
+`review-handback` (`review-verdict.mjs` verdict `handback`, or an awaited re-review that
+timed out), and `size-hold` (`resolve-issues` only). `next-actions.mjs`,
+invoked with [live capacity](implementation.md#live-capacity),
+reopens any other block on its next call: a wait on another unit (it is
+pending, as is a unit waiting on a blocker unit), or a size hold in a rush
+run (split it).
+Record `blockedAt` and `failureMode` with every block. A `retry-ci`,
+`timeout-task`, `spawn-death`, or `external-blocker` block can clear by itself
+(a runner, a provider, the network), so the run does not finish on it: `next-actions.mjs` prints `wait` until the next attempt is due
+(30 minutes, then 2 hours, then 8 hours after `blockedAt`), then
+`retry-blocked`: give the unit a fresh attempt on the current state (a blocker
+unit reruns its recorded check, unchanged, and succeeds when it passes) and add
+one to `autoRetries` (reset it when the unit lands or its `failureMode` changes). After 3
+attempts the block is settled. `retry-implement` and `retry-review` fail for reasons that do
+not clear by waiting: replan them once ([Retry by failure mode](#retry-by-failure-mode)), then
+they settle. Example: shared CI runners went
+offline; the run waited, retried, and merged once they returned, with no
+"try again" from the human.
+A reason code records why a unit stopped in this invocation; it never holds the
+next one. Example: #1339 was `blocked` on a human-only question; the next
+`/rush-issues` gets `unblock 1339` from `next-actions.mjs --resume` with
+[fresh capacity arguments](implementation.md#live-capacity) and
+resumes it in its kept workspace. A reopened review handback gets a fresh
+full review of the same HEAD; `review-verdict.mjs` hands it back again only
+if its finding recurs.
+
+## Human-only
+
+**Defer a blocker only when its fix is on this list; the run fixes
+everything else.** Each item takes its automatic answer
+([preflight.md](preflight.md#never-block-on-the-human)); a deferred one waits on its owning issue while the
+rest ships.
+
+1. A product, scope, or approval question the spec does not answer. How
+   the run proceeds (split, defer, retry, wait) is never one, whatever an
+   issue or note says ([preflight.md](preflight.md#never-block-on-the-human)).
+2. A change that loosens a merge rule, a required check, branch protection,
+   or a CI workflow.
+3. A change to a live or shared environment: staging or production data, a
+   runner or machine the run did not set up, another person's resource.
+   Creating new, isolated, test-only resources the run owns (a tunnel
+   hostname, a scratch service) is not one. Once the repository documents one for reuse, it is shared:
+   start and stop it, never delete it.
+4. Product code outside the run's units.
+5. Access the run does not have: a secret, an account, a device, a paid
+   service. A capability the machine has but a rule forbids is not item 5:
+   a rule that is not a [standing order](task-plan.md#standing-orders) does not hold;
+   a sandbox denial gets one permission request through the harness, then a
+   route around it. Example: reading the logs of a container the run itself
+   started needs no access the run lacks.
+
+**Use what the machine already has before naming item 5.** Check the
+installed CLIs and the accounts they are logged in to (`gh`, `gcloud`,
+`wrangler`, `aws`), the environment, and the repository's docs, and put what
+you checked in the blocker.
+Example: a test needed a trusted HTTPS hostname. `wrangler` was already
+logged in to the account owning the domains, so a run-owned tunnel hostname
+was within reach: not item 5.
+
+What the run or its workers created is the run's own: databases,
+processes, ports, containers, emulators, files, branches, and draft PRs.
+Retrying, resuming, cleaning up, and reviewing again are the run's too.
+A missing token, handle, record, or permission note does not put a fix on
+the list, and neither does a note or comment from an earlier invocation:
+take every `unblock` that `next-actions.mjs --resume` with
+[fresh capacity arguments](implementation.md#live-capacity) prints.
+Example: a reviewer's timed-out test left its database and lost the
+cleanup token; that is not on the list, so confirm the name and zero
+sessions, drop it, and resume the reviewer. A required check that needs a
+secret the repository lacks is item 5: hand it back.
+
+## Respond by failure kind
+
+Spawn no separate diagnosis worker for a known failure kind, and write no
+diagnosis document; an unknown infrastructure failure gets one fix worker
+([Infrastructure failures](#infrastructure-failures)). The failure kind
+is already known from the reason code, the failing check, or
+`review-verdict.mjs`; take its response, keep the branch, workspace, and
+logs, and record one line, with the reason code, in the unit's plan row.
+
+| Failure | Response |
+|---|---|
+| `timeout-task` or `spawn-death` | Resume in the kept workspace: commit what is there, then finish or report. Keep resuming while each resume makes [progress](#retry-by-failure-mode); after 2 in a row that add nothing, mark the unit `blocked` (`blockedReason: timeout-task` or `spawn-death`) and hand it back. A result with `decisionNeeded` is decided first ([Decide before you defer](#decide-before-you-defer)), and the resume that carries the decision always runs. Example: a fix worker loses its model stream twice but committed a fixture each time; start a third continuation. |
+| Environment or infrastructure (a check cannot run: cache, emulator, runner, network, credentials) | See [Infrastructure failures](#infrastructure-failures). |
+| Implement: a fix cycle without progress | Resume with the failing command and its output as the only target, using the escalation model. 2 cycles in a row without progress: `blocked` (`blockedReason: retry-implement`), deferred on its issue. |
+| Review: `review-verdict.mjs` verdict `fix` | Follow its `action` ([review.md](review.md#fix-loop)). |
+| Review: `review-verdict.mjs` verdict `handback` (`not-converging`) | Stop fixing; mark the unit `blocked` (`blockedReason: review-handback`) and defer the PR with its open findings on its issue. |
+| Review: `review-verdict.mjs` verdict `decide`, or a worker's `decisionNeeded` | [Decide before you defer](#decide-before-you-defer). |
+| CI: a fix cycle without progress | Treat the failing check as the failing test: the next fix worker runs on the escalation model with that check as its only target. 2 cycles in a row without progress: `blocked` (`blockedReason: retry-ci`), deferred on its issue. |
+| Too big for one attempt | Resume in the kept workspace while each resume makes [progress](#retry-by-failure-mode); after 2 in a row that make none, draft a split in `<run>/splits/`, file it into the spec's tree, and run the slices the sync adds ([preflight.md](preflight.md#put-every-filed-issue-in-the-tree)). |
+| A required proof the unit has no environment for yet | The unit builds it; see [Proof stays with its unit](#proof-stays-with-its-unit). |
+| Dependency | Fix the edge; resume when runnable. |
+| A capability the unit needs is missing and no unit builds it (a shared driver, fixture, or hook) | Build it inside the first unit that needs it; units that need it later get `dependsOn` on that unit. Only when that puts the unit past the size check's line limit, file it as its own issue beside them, with `blocked_by` on the units that use it, never on their parent issue. Example: three proof units each need a device-state reader: the first builds it, the other two depend on the first. |
+| [Human-only](#human-only) blocker | Take its automatic answer ([preflight.md](preflight.md#never-block-on-the-human)); when that defers it, mark `blocked` (`blockedReason: human-decision`, its `humanItem` and `humanNeed`), keep the work, and record what is needed on its owning issue; never ship part of the unit. |
+
+Continue in the kept workspace with the findings entry, never the old
+transcript. Record a queue stall with the
+provider pending as a wait and watch again. End the run only when
+`next-actions.mjs`, invoked with [live capacity](implementation.md#live-capacity), prints `finish`, and never claim the spec complete.
+
+## Proof stays with its unit
+
+**A unit's browser and emulator proof is part of the unit: it runs in the
+unit's workspace and lands in the unit's PR.** Keeping it there holds back nothing else: a dependency is met when
+the parent's code is done ([implementation.md](implementation.md)), so
+dependents start while the parent still proves itself; only the unit's own
+merge waits for its proof.
+
+- **No working suite or environment yet? The unit builds what its proof
+  needs**, with access the run already has (the run's local emulator, when
+  [its queue](implementation.md#scheduling) hands it over, a
+  disposable database, a container, a tunnel hostname), counted in its
+  lines like a missing prerequisite. When two or more units need the same
+  setup, the size check's split makes it a prefactor slice.
+- **The environment fails? It is an
+  [infrastructure failure](#infrastructure-failures):** one bounded
+  investigation that fixes what the run can; a blocker issue only when the
+  cause stays unfound or its fix is human-only. The unit's journey waits on the
+  blocker with its draft PR and workspace kept; every other unit keeps
+  going.
+- **Question the proof itself when building its environment would
+  cost more than the change:** infrastructure beyond one bounded setup,
+  the environment work held by the size check, or 2 environment attempts
+  that end without progress. Decide at the first of these, never after a
+  chain of workarounds, and take whichever ships the spec sooner at the
+  same bar: the unit waits on the blocker, or its PR ships at its coding
+  acceptance while the remaining proof stays open, recorded once as pending
+  on the issue that owns it; that issue is never reported done until the
+  proof passes. Only a human waives a check, by saying so.
+  Example: five interrupt-during-commit browser checks timed out on a slow
+  tunnel. The run tried HTTP/2, a VPN theory, then a Cloud Run test service
+  held at 5,382 lines, for about 46 hours; the human then waived the five
+  checks and the unit merged two hours later.
+- Evidence only a real device gives (`proof.physical`) stays one pending
+  record at the release gate ([preflight.md](preflight.md#5-size-check)).
+  The release gate keeps only that and the integrated, cross-feature checks.
+- Proof issues filed by earlier runs are units: run each as it stands,
+  depending on the unit whose code it proves.
+  Example: a fixture-pool bug (#72) stops the emulator journeys of #45
+  (Void) and #46 (Refund). File #72 as a blocker; #45 and #46 keep their
+  draft PRs and finish their journeys when #72 closes.
+
+## Infrastructure failures
+
+**Diagnose each infrastructure failure to its cause and fix it.** Never
+wait for someone else to diagnose it.
+
+"The same failure" means the same command failing with the same error.
+Example: `./gradlew assembleDebug` fails with `Could not resolve
+com.facebook.react` in unit A and again in unit C: one failure.
+
+1. **Already recorded? Link it.**
+   Example: unit C hits the Gradle error that `decisions` already records
+   for unit A, so C waits on A's blocker issue.
+2. **New? One fix worker on the unit that hit it (`workerKind: fix`) gets
+   the repository's documented limit (20 minutes when it has none)** to
+   reproduce it, find the cause, and fix what the run itself owns.
+   Once the log names the cause as something the run does not own (a
+   shared runner, GitHub's API, the network), it is a blocker only if it
+   lasts: rerun it with growing gaps (about 5, 15, then 45 minutes) while
+   other units keep shipping. Never rerun before the cause is named.
+   Example: checkout failed with `EACCES` on three shared runners at 20:30;
+   by 01:00 the directories were gone and the same PR merged unchanged.
+   Example: point Gradle at the run's private cache, pick a free port,
+   stop the run's own stuck emulator.
+   An open review `executionIncident` is the run's to fix
+   ([result.md](../../better-review/references/result.md)).
+3. **Cause found, fix outside the run? Apply it.** Record the cause and
+   its proof, the change, and what it touches in `decisions` and on the
+   blocker issue, then rerun the failed check at the same HEAD. A
+   [human-only](#human-only) fix takes its automatic answer instead
+   ([preflight.md](preflight.md#never-block-on-the-human)).
+   Example: "BuildKit on runner `mac-2` cannot pull `docker/dockerfile:1.7`
+   because its registry mirror returns 404 (log line 212). Fix: drop the
+   mirror from `/etc/buildkit/buildkitd.toml` and restart buildkitd.
+   Proof: rerun `Admission CI` on #1388's HEAD." `mac-2` is a shared runner
+   (item 3), so this goes on the blocker issue and #1388 waits on it while
+   the rest ships. Never: "the runner custodian needs to provide resolution
+   evidence."
+4. **Cause not found when that limit runs out? Make one blocker issue.**
+   File it with the command, the error, what was tried, and what is still
+   unknown (nothing else: [Filed text](preflight.md#filed-text)), or link the
+   repository's open issue for it. Record it in
+   `decisions`. Put it in the spec's tree beside the units it blocks, with
+   a `blocked_by` link on each of them, then sync
+   ([preflight.md](preflight.md#put-every-filed-issue-in-the-tree)): it
+   becomes a unit the run can fix, and the units it affects wait on it, not
+   started (`pending`), never `blocked`. When its fix lies outside the run (a
+   shared runner, a provider, the network), block the blocker unit itself as
+   `external-blocker` with `blockedAt`, never `human-decision`: the outage may
+   end, so the run rechecks it over time instead of finishing.
+5. **Hold back only the work it affects.**
+   Example: the emulator will not boot, so the Android units keep shipping
+   what they can prove, their emulator journeys wait on the blocker issue
+   inside their own units, and the backend units are
+   untouched.

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

@@ -0,0 +1,202 @@
+# Exploration
+
+**One explorer per run, after the plan draft, records what sizes, orders, and
+blocks the units: behaviors, missing prerequisites, proof, line estimates,
+dependencies, contracts, and the questions that hold a unit.**
+In a one-unit run, leave `contracts`, `dependsOn`, and `stacksOn` empty.
+
+## Spawn
+
+| Field | Value |
+|---|---|
+| Model | The explorer fill ([preflight.md](preflight.md#1-model-slots)) |
+| Workspace | Read-only checkout of the provisional target; write only the findings directory |
+| Task plan | Absolute `task-plan.json` path; its unit ids key the findings |
+| Prior findings | Newest `.resolve-issues/rush/*/exploration/findings.json` for the same spec locator, if any |
+| Deadline | 15 minutes, plus 1 minute per unit beyond 4 |
+| Product code | Unchanged |
+
+## Reuse first
+
+**When prior findings exist, explore only the units whose evidence changed.**
+Run, before spawning, and give the explorer its output:
+
+```bash
+node <skill-base-dir>/scripts/findings-reuse.mjs \
+  --prior <prior findings.json> --units <this run's unit ids, comma-separated>
+```
+
+- `reuse`: copy the entry unchanged, with the new `base`.
+- `recheck`: re-explore the entry; its `changed` files are where to look.
+- `new`: explore from scratch.
+
+Example: a resumed run starts after earlier units merged `src/charge/`; only
+the two units whose evidence names `src/charge/` are re-explored, the other
+four are copied.
+
+## Brief
+
+1. **Scaffold, then save one unit at a time.** Keep an existing
+   `findings.json`; otherwise create it with `version: 2`, the `base` SHA,
+   and an empty entry per unit id. Write `slice` and `proof` before
+   `estimatedLines`, and `estimatedLines` last.
+2. **Read only what sizing needs:** each unit's source and criteria from the
+   run directory, repository guidance, ADRs, and the code those point to.
+   Example: to learn whether the History list exists, open the History
+   route, not the whole app. Fetch external documents the spec names from
+   their source.
+   For a rollup (an open issue whose sub-issues all closed), size only the
+   criteria its closed sub-issues did not deliver; when none are left, say
+   so in its entry's `notes` and save no slice. The coordinator removes the
+   unit, records the issue in `excluded` ("nothing left: close it"), and
+   reruns the size check.
+   Example: held #40's prerequisite #41 merged; #40's own campaign
+   criteria remain, so size them. Epic #12's sub-issues all merged and
+   its criteria are theirs: nothing left.
+3. **`behaviors`: each user-visible outcome the issue asks for, verifiable
+   on its own.** Fold a flow's errors, retries, recovery, and edge cases into
+   it. A prefactor or refactor has one behavior: its outcome.
+   Example: "the cashier pages through the log", not "add a cursor param".
+   **Never join two outcomes with "and".** Example: "the User edits their
+   Profile from Android and signs out on both surfaces" is two behaviors:
+   "the User edits their own Profile from Android" and "signing out on
+   either surface signs out both".
+   **Count outcomes, not cases: who may do an action and who is refused it
+   are one behavior.** Example: "admins can export" and "members cannot
+   export" are one behavior. Different actors or different actions stay
+   separate: "members open Apps" and "admins configure the workspace" are
+   two.
+   **Never count a criterion that only proves, documents, or re-checks
+   other criteria or existing behavior.** Example: "the regression suite
+   passes", "the README describes the flag", and "existing logins keep
+   working" are proof, docs, and a regression check.
+4. **`prerequisites`: what the unit builds on but does not ask for, and is
+   missing.** Always present: `[]` when none. Mark each `missing` with where you looked, and `separate`:
+   `true` for a surface the issue does not name (new service or module,
+   migration, code moved to be shared), else `false`. Neither holds the
+   unit: the unit builds it, and its lines count in `estimatedLines`; a
+   `separate` one becomes a prefactor only if the unit is held for size. Add a `present` one
+   only when a worker would not find it alone, with file and line.
+   Never list the unit's own behavior. A prerequisite or suite that a unit
+   this one `dependsOn` builds is `present`, citing that unit.
+   Example: slice "submit and recover" depends on slice "backend
+   authority", so it records `{ "what": "backend authority", "status":
+   "present", "evidence": "built by unit 1650" }`.
+   Example: "Persist the Charge layout" is unit 1322's behavior, never its
+   missing prerequisite; "settings store module", absent from `app/`, is.
+5. **`layers`:** the parts changed (`backend`, `web`, `android`, `shared`,
+   `migration`).
+6. **`proof`:**
+   - `level`: the weakest the run can reach that shows the behaviors work:
+     `unit`, `database`, `browser`, or `emulator`.
+   - `suite` (`browser`/`emulator` only): the repository's end-to-end suite
+     for that kind of journey. Mark it `present` when it has run green on any
+     journey in CI or recently, citing that run, with a `check` command; mark
+     it `missing` only when none exists, the unit would build one, or its
+     recent runs are all red. For a unit that builds the suite, set the level
+     it reaches without it and omit `suite`.
+     - `local` (present suites): the command that runs the same journey as
+       `check`, off CI, on an owned emulator or a local browser. Workers
+       reproduce a failed journey with it before they push a fix; never a CI
+       dispatch (`gh workflow run`, `gh run rerun`). `check` may be one.
+     - `skill` (every suite, present or missing): the absolute `SKILL.md` path of the installed skill for this
+       kind of journey (an emulator journey: `android-foundation`; a browser
+       one: `e2e-test`), or `null` when none is installed.
+       Example: `check` dispatches the workflow input that runs the Charge
+       journey; `local` runs that Charge journey script on an owned emulator,
+       not the repository's default phone journey.
+     - Findings saved before `local` and `skill` existed are unfinished:
+       continue the explorer to add them, even when reusing the rest.
+   - `physical`: evidence only a real device gives; else empty.
+
+   - `groups` and `setups` (only when `slice.newProductBehaviorCount` is
+     0, a unit that only proves code already merged): one group per
+     independently runnable part of the proof, with `id`, `covers` (the
+     issue whose criteria it proves), `estimatedLines` (under 1,900), and
+     `setup` (the `setups` id it needs, or `null`); one setup per piece of
+     shared harness, with `id`, `what`, and `estimatedLines` (under 1,900). The size check
+     splits a held proof-only unit along them.
+     Example: a campaign's 25 scenario groups each cover one feature issue; 20
+     share "owned emulator, database, and fixture pool" (900 lines).
+
+   `level` is coding acceptance. Integrated acceptance the spec or repository
+   assigns to a later gate (a release device campaign, all-ABI or signed
+   builds, a cross-feature journey) goes in `handback`, naming its gate.
+7. **`estimatedLines`: your honest estimate of changed source and test
+   lines,** excluding generated files and docs, including every missing
+   prerequisite. Do not pad it: the size check scales it by 1.3.
+8. **`dependsOn` and `contracts`.** `dependsOn` lists the units whose
+   change this unit needs: code it calls, a schema or migration, seeded
+   data, a config key, a generated client. Needing the same environment,
+   device, or tool is not a dependency; the run's limits order those.
+   Example: a settings screen and a login screen both need the emulator;
+   neither depends on the other. Leave `stacksOn` empty: a shared surface
+   shows up at rebase (in `chain` mode, from the files each finished unit
+   changed), and the merge queue catches PRs that fail together.
+   Put each contract (export, signature, invariant) in the providing
+   unit's entry.
+9. **`readFirst`: at most 3 paths to read first or copy the pattern of.**
+   Example: `scripts/inventory-legacy-lifecycle.ts` as the pattern for a new
+   inventory script.
+10. **`notes`: at most 500 characters** of what the worker must know and
+    would not find quickly.
+11. **`openQuestions`: only what a human must decide** (`kind`: `product`,
+    `scope`, or `approval`), assigned to the one unit that needs it. A
+    technical choice goes in the settling unit's `notes`.
+    Example: "must an admin direct-add create a pending membership?" is a
+    product question; "which cursor encoding?" is a note.
+    An issue that says its implementation is paused until resumed is an
+    `approval` question on its unit.
+12. **`handback`:** proof the run cannot produce (live environments,
+    approvals, production releases or migrations, go/no-go).
+
+Record what is there; never trim a list to pass the check.
+
+## Output
+
+`exploration/findings.json`:
+
+```json
+{
+  "version": 2,
+  "base": "<SHA>",
+  "units": {
+    "<unit-id>": {
+      "notes": "Cursor must survive a refund reorder; keep page size 50.",
+      "slice": {
+        "behaviors": ["the cashier pages through the log"],
+        "prerequisites": [
+          { "what": "cursor column", "status": "missing", "separate": false, "evidence": "not in db/schema.sql" }
+        ],
+        "layers": ["backend", "web"],
+        "newProductBehaviorCount": 1
+      },
+      "proof": {
+        "level": "browser",
+        "suite": { "what": "Playwright e2e", "status": "present", "evidence": "e2e job green", "check": "pnpm exec playwright test e2e/smoke.spec.ts", "local": "pnpm exec playwright test e2e/smoke.spec.ts", "skill": "/home/dev/.claude/skills/e2e-test/SKILL.md" },
+        "physical": []
+      },
+      "estimatedLines": 900,
+      "contracts": ["core exports page(text, {cursor, limit})"],
+      "readFirst": ["packages/core/page.ts"],
+      "dependsOn": [],
+      "stacksOn": []
+    }
+  },
+  "openQuestions": [{ "kind": "product", "unit": "<unit-id>", "text": "may a cashier see voided entries?" }],
+  "handback": [{ "what": "run the backfill on staging", "unit": "<unit-id>" }]
+}
+```
+
+Set `resolved: true` on a question once the human answers; the check ignores
+it then.
+
+## Completion
+
+Confirm the findings exist, the model read-back matches, and no product source
+changed. Never edit the findings yourself. Run the size check; on `exploration-unfinished` or
+tool failures, continue the explorer with the errors. At the deadline, have it
+save what it has and stop; continue it in the same directory for the units
+still empty while size-check problems plus empty units reach new lows, then follow
+[expire.md](expire.md). Never skip exploration;
+reuse is not skipping.