@b00dea/cockpit 0.1.0 → 0.1.1

package/surfaces/skills/procedures/setup.md

@@ -20,9 +20,11 @@ budget: uncapped
   other user-guide pages cited here sit beside it.
 - When the guard asks before a command, the person decides in Claude Code; Codex and OpenCode deny
   instead, so hand the person the exact command to run in a terminal. A refusal that holds every
-  tool call (a guard message saying so, or `GUARD_AUTHORITY_UNAVAILABLE`) follows any
-  edit to `cockpit.toml` or reinstall of cockpit or Node, and clears only when a person runs
-  `./node_modules/.bin/cockpit sync --config cockpit.toml` in a terminal. A refused command is the
+  tool call (a guard message saying so, `GUARD_AUTHORITY_UNAVAILABLE` or `GUARD_CONFIG_UNSYNCED`)
+  follows any edit to `cockpit.toml` or reinstall of cockpit or Node. `GUARD_CONFIG_UNSYNCED` means
+  the edit does not widen what agents may do, so run
+  `./node_modules/.bin/cockpit sync --config cockpit.toml` yourself where `[autonomy] sync =
+  "agent"`; any other hold clears only when a person runs it in a terminal. A refused command is the
   person's to run: never reword, wrap or re-spell it to get past the guard.
 - In Codex's sandbox only `check`, `sync --dry-run` and `--help` work. Every other cockpit command
   there cannot read cockpit's state or the Docker socket, so a failure it reports is not evidence:
@@ -54,11 +56,13 @@ started it, even where it lives outside this root.
 2. **Preview.** Run `./node_modules/.bin/cockpit init . --target <tool> --json`, adding
    `--registry` only when adopting an existing registry. The preview writes nothing. Read
    `result.stage`, `result.question` and `result.interview.outstanding`: every field the interview
-   will ask, each with its inferred values and the file each came from. Done when you hold
+   will ask, each with its `proposals` (each with `provenance.kind` `derived`, `measured` or
+   `inferred`, and the file it came from) and `confirmedBy`. Done when you hold
    `result.previewSha256` and the outstanding fields.
 3. **Explore, then ask in one small round.** Read the repositories for each outstanding field
-   before asking, ask only for what the files and CLI output cannot answer, and present each
-   inferred value with its source for confirmation. Always settle these with the person:
+   before asking, ask only for what the files and CLI output cannot answer. A field with
+   `confirmedBy = "agent"` is yours to accept as read (step 4); present every other proposal with
+   its source for confirmation. Always settle these with the person:
    - **The name.** `init` proposes the cockpit root's directory name for `cockpit.name`. It scopes
      the cockpit's Compose projects, state and generated files, so changing it after the first sync
      means following the *Rename a cockpit* section of
@@ -73,11 +77,16 @@ started it, even where it lives outside this root.
      except for a directory name that is not a valid sibling slug, which refuses with
      `INIT_COCKPIT_ROOT_REQUIRED`.
    - **The test gates.** For a runnable product, `init` proposes `testing` stages and gates from the
-     test entry points it finds. Confirm which commands prove a change: the targeted gate agents
-     iterate with, and the full gate they run before handing back. A new product with no tests needs
-     the person to choose its test runner first; adding a test framework to a product repository
-     waits for their explicit yes. Answer `testing = "none"` only when they decide there are no
-     tests yet; `doctor` then reports `TESTING_GATE_UNDECLARED`.
+     test entry points it finds. Whether each proves anything is your judgement, made on evidence:
+     name the behaviours its tests exercise, break one of them on purpose, run the proposed command
+     and see it go red, then restore the file so the checkout is as you found it. That edit needs no
+     yes, because it is undone within the step. Write the behaviours into the gate's `changes` text
+     and keep the red run's output for your report; a gate that stays green on the break proves
+     nothing about that behaviour, so say so. The person confirms which gate agents iterate with and
+     which they run before handing back. A new product with no tests needs the person to choose its
+     test runner first; adopting a test framework in a product repository waits for their explicit
+     yes. Answer `testing = "none"` only when they decide there are no tests yet; `doctor` then
+     reports `TESTING_GATE_UNDECLARED`.
    - **The non-local hosts** for `guards`: the database and live vendor API hosts of every
      production, staging or shared environment. Env templates give variable names only; each host
      comes from the person.
@@ -87,12 +96,15 @@ started it, even where it lives outside this root.
    "proceed without asking" covers interview answers only. Mark every answer you chose yourself in
    the file's `[provenance]` table, for example `"environment.machine" = "agent-default"`: init then
    writes the field under `unconfirmed` in `cockpit.toml` with a comment saying the setup agent
-   chose it, and `doctor` reports `DECLARATION_UNCONFIRMED` until a person confirms it. An unmarked
-   answer is recorded as the person's. Done when the file holds every answer and marks each one you
+   chose it, and `doctor` reports `DECLARATION_UNCONFIRMED` until it is confirmed (step 7). Mark a
+   field with `confirmedBy = "agent"` as `"derived"` instead, with no value needed: init answers it
+   with what it read, refuses one that differs (`DOCUMENT_CONFIGURATION_ANSWER_NOT_DERIVED`), and
+   records the file it came from. An unmarked answer is recorded as the person's. Done when the file holds every answer and marks each one you
    chose.
 5. **Accept.** Show the person the answers file and the preview digest, then rerun with
    `--accept-preview <previewSha256> --answers <file>`. The run stops at `configuration.defaults`:
-   once the person has read the draft in `result.question.document`, rerun adding
+   once the person has read the values the draft in `result.question.document` lists under
+   "A person confirms these" (the digest covers only those), rerun adding
    `--accept-defaults` with `result.question.expectedSha256`. Each digest binds consent to the bytes
    the person saw, so take it only from the latest pending run; any other is refused
    (`INIT_PREVIEW_NOT_ACCEPTED`, `INIT_DEFAULTS_NOT_ACCEPTED`). A different value for an answer
@@ -120,11 +132,12 @@ started it, even where it lives outside this root.
    refused by the command that needs it), `needs` (why cockpit needs it) and `findings` (the
    diagnostic, its message and its fix); `noFinding` lists the ones no check reported, which is not
    proof, because a check that could not run reports nothing. Take the gaps one at a time, required
-   first: say what is missing, why cockpit needs it, and the exact change you propose. Ask before
-   touching any product repository; committing, installing cockpit, recording a remote, untracking
-   a file or adding a test changes it for everyone who works on it. Where a gap needs judgement
-   (which test runner to adopt, whether the existing tests prove anything, where characterization
-   tests for untested code should live), propose with what you read and let the person decide.
+   first: say what is missing, why cockpit needs it, and the exact change you propose. A change to a
+   product repository follows step 8: committing, installing cockpit, recording a remote, untracking
+   a file or adding a test changes it for everyone who works on it. Whether the existing tests prove
+   anything is yours to judge, as step 3 describes; where a gap needs the person's judgement (which
+   test runner to adopt, where characterization tests for untested code should live), propose with
+   what you read and let them decide.
    - The `cockpit-installed` gap clears first: `init` ran from a temporary copy, so run
      `npm install` in the cockpit root, then ask the person to run
      `./node_modules/.bin/cockpit sync --config cockpit.toml` in a terminal so the guard hook runs
@@ -135,11 +148,25 @@ started it, even where it lives outside this root.
      person to run `codex -C <cockpit root>` in a terminal (not `codex exec`), trust the folder if
      asked, and choose **Trust all and continue** when Codex shows **Hooks need review**. `doctor`
      reports `CODEX_HOOK_UNTRUSTED` until it is done.
+   - `DECLARATION_UNCONFIRMED` lists the answers no person stated. Confirm `ports.bases` (with the
+     stack up), `environment.compose_files` and `environment.machine` by observation, one at a time:
+     `./node_modules/.bin/cockpit confirm ports.bases --config cockpit.toml --json` runs the
+     observation that verifies the answer and, when it passes, removes the entry and records what
+     ran. Then run `./node_modules/.bin/cockpit sync --config cockpit.toml` where `[autonomy] sync =
+     "agent"`, or hand it to the person, before confirming the next one. A refusal
+     (`CONFIRM_OBSERVATION_FAILED`) names what the observation saw: fix that, or the value, and
+     confirm again. Never delete an `unconfirmed` entry by hand: `CONFIRM_PERSON_REQUIRED` marks the
+     answers only a person confirms (the trust decisions, `cockpit.name`, `estate.runnable`,
+     `environment.test_data`), so list them in your report with their values.
    Done when `doctor` reports no required gap and every other gap is cleared or reported.
-8. **Offer the product changes, one yes each.** "Use sensible defaults" never extends to writing
-   inside a product repository: an **AGENTS.md** pointer, a Compose file, a `package.json`, a
-   Dockerfile or a `.env.schema` in a sibling checkout each needs the person's explicit yes to that
-   exact change, because it changes the product for everyone who works on it.
+8. **Put product changes where the person reviews them.** A Dockerfile, Compose file or
+   `.env.schema` the product needs goes on a new branch in that sibling's checkout: start the branch
+   only when `git -C <sibling> status --short` prints nothing, write the files there, and put their
+   diff against the starting branch in your report. Nothing is pushed, so the person reviews it
+   before it reaches anyone else. Creating a hosted repository or a remote waits for their yes. Every
+   other product change (an **AGENTS.md** pointer, a `package.json`, a new test framework) needs the
+   person's explicit yes to that exact change, because it changes the product for everyone who works
+   on it; "use sensible defaults" never extends to it.
    - For a dedicated cockpit, offer an instruction pointer for each product repository. If the
      product has no **AGENTS.md**, show the exact proposed file as a draft; if it has one, show the
      marked block that would be appended without changing the team's text. After approval, set
@@ -152,10 +179,12 @@ started it, even where it lives outside this root.
      identities or create browser state.
    - For environment or secret adoption, follow **Secret handling** after sync has established its
      owned ignore boundary.
-   Done when each offer is applied or declined.
+   Done when each product file is on its branch with its diff in your report, and each other offer
+   is applied or declined.
 
-Report the actual result, every gap still named, and every default you chose, with its field and
-value, so the person can confirm or replace each.
+Report the actual result; every gap still named; every default you chose, with its field and
+value, so the person can confirm or replace each; your judgement of each test gate, with its red run;
+and the diff of every product branch.
 
 ## Create a local setup
 
@@ -183,13 +212,16 @@ guesses. So derive each value from what the repository shows, record it as infer
    answer is retained as a not-declared decision. A true answer is only a requirement: it remains unresolved
    until product-owned seed operations or browser authentication states are declared, and never proves that
    data or a login exists.
-5. Decide where the runnable pieces live. A Dockerfile or Compose file written into a product
-   repository is a product change, so ask the human first and show the exact path and contents.
-   Without that permission, declare an environment cockpit renders itself and leave the product
-   untouched. Done when either the human approved that specific file or no product file was written.
+5. Decide where the runnable pieces live. A Dockerfile or Compose file in the product is a product
+   change: write it on a branch in that repository's checkout, as step 8 of **Bootstrap** describes.
+   A `compose.yml` at the cockpit root that reaches the checkout through its sibling variable leaves
+   the product untouched. Done when each product file is on its branch with its diff in your report,
+   or no product file was written.
 6. Finish the configuration with the init flow in **Bootstrap**. On an existing cockpit, an edit to
-   `cockpit.toml` makes the guard hold every tool call, so a person runs
-   `./node_modules/.bin/cockpit sync --config cockpit.toml` in a terminal; then run
+   `cockpit.toml` makes the guard hold every tool call until it is synced. When the hold says the
+   edit does not widen what agents may do, run
+   `./node_modules/.bin/cockpit sync --config cockpit.toml` yourself where `[autonomy] sync =
+   "agent"`; when it names fields that widen, a person runs it in a terminal. Then run
    `./node_modules/.bin/cockpit check --config cockpit.toml --json`. Done when the check exits 0.
 7. Where a runtime is declared, measure it with
    `./node_modules/.bin/cockpit runtime measure --config cockpit.toml --image <local-image>`, using an
@@ -235,14 +267,17 @@ report secure agent secret use as unavailable unless a sandbox that has been tes
 ## Add or remove an agent tool
 
 When the team starts or stops using an agent tool, the `tool` command edits only `[surfaces]
-tools` in `cockpit.toml`. The guard asks before every `tool` command, the preview included, and
-after the edit it holds every tool call until a person syncs.
+tools` in `cockpit.toml`, and after the edit the guard holds every tool call until it is synced.
+Adding a tool does not widen what agents may do, so you may run `tool add`; removing one deletes
+that tool's guard, so the guard asks before `tool remove`, and the hold then names `surfaces.tools`
+and waits for a person.
 
 1. Preview with `./node_modules/.bin/cockpit tool add <tool> --config cockpit.toml --dry-run` (or
    `tool remove`) and show the person the list it prints. Done when they agree to that list.
 2. Run it without `--dry-run`. Tell the person first that every tool call is held after it. Done
    when the command exits 0.
-3. The person runs `./node_modules/.bin/cockpit sync --config cockpit.toml` in a terminal: an added
+3. Sync: after `tool add`, run `./node_modules/.bin/cockpit sync --config cockpit.toml` yourself
+   where `[autonomy] sync = "agent"`; after `tool remove`, the person runs it in a terminal. An added
    tool's files are written from the same sources as the others, and a removed tool's files are
    deleted as `[autonomy] stale_delete` allows. When sync refuses with
    `GENERATED_STALE_APPROVAL_REQUIRED`, they rerun it with `--interactive` and type the
@@ -254,7 +289,7 @@ after the edit it holds every tool call until a person syncs.
 Use this on an installed cockpit when a product gains or drops a repository. The `sibling`
 command edits `cockpit.toml` so the repository is declared once, with its purpose, instead of
 reached by path. The guard asks before every `sibling` command, and because the command writes
-`cockpit.toml` immediately, the guard then holds every tool call until a person syncs.
+`cockpit.toml` immediately, the guard then holds every tool call until it is synced.
 
 1. **Propose the declaration.** Read the repository and ask the person for its purpose when no
    source states it. Show the human the proposed sibling declaration before invoking the command:
@@ -271,9 +306,10 @@ reached by path. The guard asks before every `sibling` command, and because the
    which refuses and lists every reference while anything still uses the repository, and never
    deletes the checkout. The command writes cockpit.toml immediately; `--json` changes only its
    output format, so it is neither a preview nor an acceptance gate. While the stack is up, a
-   repository the stack uses is refused until a person runs
+   repository the stack uses is refused until the stack is stopped; you may stop it with
    `./node_modules/.bin/cockpit down --config cockpit.toml`. Done when the command exits 0.
-3. **Sync.** The changed declaration affects the guard, so a human runs
+3. **Sync.** Adding or removing a repository widens what agents may do (a new repository is a new
+   directory they may write), so the hold names the sibling and a person runs
    `./node_modules/.bin/cockpit sync --config cockpit.toml` in a terminal. Then run
    `./node_modules/.bin/cockpit check --config cockpit.toml --json`. Done when the check exits 0.
 4. **Instruction pointer, only on request.** When the person wants the repository's **AGENTS.md**
@@ -347,6 +383,42 @@ never applied silently. Installing a new cockpit also makes the guard hold every
 5. **Commit together.** Ask the person to commit the lockfile and the regenerated files together.
    Done when `./node_modules/.bin/cockpit check --config cockpit.toml --json` exits 0.
 
+## Keep checkouts and stacks current
+
+Each checkout of the cockpit, a linked worktree included, runs its own stack from the sibling
+checkouts it mounts. These commands keep both current; run them yourself, except where a step
+gives one to the person.
+
+1. **Update the checkouts** with `./node_modules/.bin/cockpit pull --config cockpit.toml --json`. It
+   only fetches and fast-forwards the cockpit and every sibling. A checkout it skips (`PULL_SKIPPED`:
+   modified files, a diverged branch, a failed fetch) stays as it was; report it with the command
+   the finding names. Done when every checkout is current or reported.
+2. **Serve a sibling from a worktree** with
+   `./node_modules/.bin/cockpit use sibling-slug /absolute/path/to/worktree --config cockpit.toml`,
+   and go back with `use sibling-slug --clear`. The choice holds for this cockpit checkout only, and
+   a checkout outside the directories you may already write is the person's to choose. A running
+   stack keeps the checkout it mounted, so run `down` and `up` after it. A worktree lacks the
+   ignored environment files (`SIBLING_ENVIRONMENT_FILE_MISSING`), and cockpit never copies them:
+   ask the person. Done when `doctor` names the checkout under `SIBLING_CHECKOUT_OVERRIDDEN`.
+3. **A stale stack.** `STACK_INPUTS_CHANGED` from `doctor`, `preflight` or `pull` means a mounted
+   sibling's lockfile or declared `rebuild_inputs` changed under the running stack. While the stack
+   still runs, rebuild each service whose image installs those dependencies with
+   `./node_modules/.bin/cockpit rebuild --config cockpit.toml --service service-id`, then run
+   `./node_modules/.bin/cockpit down --config cockpit.toml` and
+   `./node_modules/.bin/cockpit up --config cockpit.toml`. When `down` refuses because another
+   holder still uses the stack (`CLAIM_CO_TENANT`), leave it and report who holds it. Done when
+   `doctor` no longer warns, or the holder is reported.
+4. **Orphaned stacks.** `STACKS_ORPHANED` from `doctor` means a stack lost its checkout, usually a
+   deleted worktree. `./node_modules/.bin/cockpit stacks --config cockpit.toml --json` lists every
+   stack with its checkout and verdict; `./node_modules/.bin/cockpit stacks prune --config cockpit.toml`
+   previews what would go, and
+   `./node_modules/.bin/cockpit stacks prune --config cockpit.toml --apply` removes this cockpit's
+   orphans only. A prune that deletes volumes runs only where `[autonomy] reset = "agent"`, and
+   another cockpit's orphans need a person: for either, hand the person
+   `stacks prune --interactive` for a terminal. A stack whose worktree Git still registers, or marks
+   locked, is kept until `git worktree prune` (after `git worktree unlock` for a locked one) runs in
+   its main checkout. Done when `stacks` lists no orphaned stack, or the person has the command.
+
 ## Diagnose
 
 1. Run `./node_modules/.bin/cockpit doctor --config cockpit.toml --json` first: it reports health,
@@ -355,8 +427,9 @@ never applied silently. Installing a new cockpit also makes the guard hold every
    pass the blocking gate.
 2. Follow the fix each diagnostic names, required gaps first. When the fix is a person's step
    (trusting a Codex hook, signing in to a provider, approving a digest), hand them the exact
-   command it names. Done when `doctor` reports each gap cleared, or you have reported the ones
-   only a person can clear.
+   command it names. A stale or orphaned stack is cleared by **Keep checkouts and stacks
+   current**. Done when `doctor` reports each gap cleared, or you have reported the ones only a
+   person can clear.
 
 For an account of the result without changing anything, use the cockpit-explain skill.
 

package/surfaces/skills/procedures/work.md

@@ -20,9 +20,11 @@ budget: uncapped
   other user-guide pages cited here sit beside it.
 - When the guard asks before a command, the person decides in Claude Code; Codex and OpenCode deny
   instead, so hand the person the exact command to run in a terminal. A refusal that holds every
-  tool call (a guard message saying so, or `GUARD_AUTHORITY_UNAVAILABLE`) follows any
-  edit to `cockpit.toml` or reinstall of cockpit or Node, and clears only when a person runs
-  `./node_modules/.bin/cockpit sync --config cockpit.toml` in a terminal. A refused command is the
+  tool call (a guard message saying so, `GUARD_AUTHORITY_UNAVAILABLE` or `GUARD_CONFIG_UNSYNCED`)
+  follows any edit to `cockpit.toml` or reinstall of cockpit or Node. `GUARD_CONFIG_UNSYNCED` means
+  the edit does not widen what agents may do, so run
+  `./node_modules/.bin/cockpit sync --config cockpit.toml` yourself where `[autonomy] sync =
+  "agent"`; any other hold clears only when a person runs it in a terminal. A refused command is the
   person's to run: never reword, wrap or re-spell it to get past the guard.
 - In Codex's sandbox only `check`, `sync --dry-run` and `--help` work. Every other cockpit command
   there cannot read cockpit's state or the Docker socket, so a failure it reports is not evidence:
@@ -62,12 +64,24 @@ not the thinking: reuse the planning skills the harness already has.
    run the same command with `--interactive` in a terminal. Never type the digest yourself. Past
    `work.wip_cap` it refuses until an open order closes. Done when `work status` reports it accepted.
 3. **Work test-first inside scope.** Write the failing test for a criterion, then the code, changing
-   only what `scope` names. If the work needs more, edit the order and run `work accept` again to
-   accept the amendment; dropping or rewriting an accepted criterion always needs a person. When you
+   only what `scope` names; a file outside it that the change needs (a lockfile, a regenerated
+   reference, a changeset) is judged at grading, so change nothing else. If the work needs more, edit
+   the order and run `work accept` again to accept the amendment: dropping a criterion or gate always
+   needs a person, a rewritten criterion or widened scope needs one under `checks` grading, and
+   otherwise the next grade judges whether your amendment lowered the bar. When you
    need a person's input, run
    `./node_modules/.bin/cockpit work note --config cockpit.toml --work-order WO-001 --ask --text "<question>"`
    and stop: the order is blocked until it is answered with `work answer`, which under `answer =
-   "person"` only a person can run. Done when every criterion has code and a test that passes.
+   "person"` only a person can run. When `work accept` or `work status` lists `relatedDecisions`,
+   read those decision records before changing the code they name. When the work makes a lasting
+   decision (a format, a boundary, a dependency, an option rejected), record it with
+   `./node_modules/.bin/cockpit work note --config cockpit.toml --work-order WO-001 --decision --text "<title>"`
+   and resolve it with `work decide --decision <n> --record` (adding `--supersedes <number>` when it
+   replaces an older record), then replace every placeholder in the record it writes;
+   `--record-file <path>` cites a record that already exists, and `--none --reason "<why>"` resolves
+   one that turned out not to last. Update the documentation that describes behaviour you change.
+   This needs `[docs] decisions` in `cockpit.toml`, and nothing enforces it under
+   `[work] grading = "checks"`. Done when every criterion has code and a test that passes.
 4. **Check** with `./node_modules/.bin/cockpit work check --config cockpit.toml --work-order WO-001 --json`.
    It runs every criterion's check and the order's gates; a failure (`WORK_CHECK_FAILED`) returns
    each result's outcome and the end of its output under `result.results`. Fix and rerun. While
@@ -76,8 +90,11 @@ not the thinking: reuse the planning skills the harness already has.
    faster feedback. Done when `work check` exits 0.
 5. **Before grading, review.** Run the harness's installed simplification and code-review skills,
    with security emphasis when the change touches authentication, secrets, guards or reach to
-   non-local hosts. Fix their blocking findings and rerun `work check`. Done when no blocking
-   finding is open and `work check` still exits 0.
+   non-local hosts. Fix their blocking findings and rerun `work check`. Where `cockpit.toml` declares
+   `[docs]`, also run `./node_modules/.bin/cockpit docs check --config cockpit.toml --json` and fix
+   each finding your change caused: a living document citing a path or `make` target you removed, or
+   a decision record out of step with its index. Done when no blocking finding is open, `work check`
+   still exits 0 and `docs check` reports nothing your change caused.
 6. **Grade** with `./node_modules/.bin/cockpit work grade --config cockpit.toml --work-order WO-001 --json`.
    Under the default `independent` grading a fresh read-only evaluator grades each criterion, in
    another listed agent tool when there is one; never grade your own work. When no evaluator can run
@@ -85,21 +102,33 @@ not the thinking: reuse the planning skills the harness already has.
    rate-limited or timed out), the refusal names each tool's cause and the command that fixes it:
    report that to the person instead of retrying. A warning
    `EVALUATOR_FELL_BACK_TO_RUNNING_TOOL` means the tool doing the work graded it; pass it on. Under
-   `checks`, the checks decide. Under `self`, pass `--verdict met` or `unmet` and a `--note` saying
-   what you checked; the checks still run and a failed one fails the grade. Anything short of
-   passing (`WORK_GRADE_UNSATISFIED`) lists each criterion's verdict and note under
-   `result.criteria`, failed checks under `result.checks` and changes outside scope under
-   `result.outOfScope`: go back to step 3 for each. When the person names a grader ("use Codex to
+   `checks`, the checks decide, and any change outside scope fails. Under `self`, pass
+   `--verdict met` or `unmet` and a `--note` saying what you checked, naming each path in
+   `result.outOfScope` and each flagged test file with why its change is needed; the checks still run
+   and a failed one fails the grade. Cockpit adds standing criteria for changes outside scope
+   (`scope-changes-necessary`), flagged test changes (`test-changes-justified`) and your amendments
+   (`amendments-hold-bar`), and with `[docs]` declared for recorded decisions
+   (`decisions-recorded`) and updated documentation (`docs-updated`). Anything short of passing
+   (`WORK_GRADE_UNSATISFIED`) lists each criterion's verdict and note under `result.criteria` and
+   failed checks under `result.checks`: go back to step 3 for each, reverting a change outside scope
+   or a test change the grade calls unneeded. `WORK_TEST_WEAKENED` means a test change was not accepted: restore the test, or under
+   `checks` grading acknowledge a legitimate change with `work acknowledge --note <why>`. When
+   `amendments-hold-bar` is unmet, the next amendment is a person's: report it. When the person names a grader ("use Codex to
    grade", "use Claude for everything"), pass `--evaluator <tool>` (`codexcli`, `claudecode` or
    `opencode`) on every grade for the rest of the session; only that tool runs, with no fallback.
    Done when the grade passes.
 7. **Attempt cap.** Each failed check or grade counts an attempt; at `work.attempt_cap` the order is
-   blocked (the refusal names the cap). Record the root cause with `work note`, then report to the
-   person, who amends the contract or closes the order. Done when the person has the cause and the order's state.
+   blocked. Record the root cause with `work note`, then do what the refusal names: close it with
+   `work signoff --partial` or `--abandon`, or amend the contract, yourself where `[work.gates]` gives
+   that step to the agent, and otherwise hand the person the command. Done when the order is closed or
+   amended, or the person has the cause and the command.
 8. **Close** with `./node_modules/.bin/cockpit work signoff --config cockpit.toml --work-order WO-001`
    once graded; under `signoff = "person"` it answers `WORK_PERSON_REQUIRED` as step 2 describes.
+   It refuses while a recorded decision is unresolved or its record still holds placeholders.
    An order that cannot be finished closes with `--partial --note <what is left>` or
-   `--abandon --note <why>`. Done when `work status` names how it closed.
+   `--abandon --note <why>`. A command refused because another holds the order's lock: when that
+   command crashed, run `work recover --work-order WO-001 --apply`, which removes the lock only once it
+   has shown the holder gone and otherwise names what it could not check. Done when `work status` names how it closed.
 
 Report each criterion's verdict and note, how the order closed (`work status` names it), and any
 step you could not run.