sum-deliver

Files (1)

• SKILL.md

SKILL.md (first lines)

# Deliver

A worker report is a claim.
Read the saved task, its report, relevant changes, and outstanding decisions.
`sumctl show TASK_ID` carries `evidence_view`: every report, handoff, reviewer finding, verification, and PR observation, each bound to a candidate SHA and marked `current` against the checkout HEAD, plus `closure.missing`, the prerequisites still absent.
Worker claims (`source: worker`), reviewer findings (`reviewer`), your own verification (`coordinator`), and GitHub observations (`github`) stay separate records.
A legacy prose report appears as unstructured evidence.
`sumctl context TASK_ID --role reviewer` is the bounded handoff for a reviewer you launch: the approved task, the current candidate with its latest handoff, paged evidence, and the delivery skill as an explicit file reference; worker-supplied artifact paths are classified by scope, never opened.
`--section evidence --kind review --after N` pages further records; counts and `next_after` say what a page left out.
Its `environment.dev` block is the task-local environment record: the repository's declared commands (references, never run by sum), the URLs the worker observed with their ownership and state, log paths, and related terminals/containers, each with an observation time.
A `stale` flag or `not-listening` state means the fact was not confirmed at the last observation; `sumctl env inspect TASK_ID` re-observes once on demand without starting or stopping anything.
Reading the view observes nothing.

## Verify

Confirm the checkout, branch, candidate SHA, and actual diff.
Confirm the reported verification commands and evidence.
Apply the shared engineering rubric at `.agents/skills/verify/references/engineering-principles.md` when the target carries it.
Name concrete affected files and invariants, and separate blocking correctness or ownership defects from advisory suggestions.
The target repository's nearest owner README, canonical example and executable verification command remain authoritative; this rubric adds review procedure, not application architecture.
The delivery order is fixed.
The worker agent ran verification, you run it again yourself, you own the independent review, and the user decides the merge.
The second run is intentional, never duplicate work to skip; the worker's run (`evidence_view.verification.worker_run`, source `worker`) is a claim you check against, never your result.
When the task was dispatched into a standardized checkout (`verification_policy.status: standardized`, also `env show`/`env discover` `verification_contract`), execute the contract under your own run id against the exact candidate: `sumctl verify TASK_ID --candidate SHA --execute` creates a separate detached checkout of that SHA beside the task record, runs `.agents/skills/verify/scripts/verify_run.py --base <task base>` there, keeps `run.json` and `verify.log` under `.sum/tasks/TASK_ID/verification/`, removes the checkout, and records the run; the worker's checkout is never written to and its `.artifacts/` are never read as the result.
When you ran the runner yourself instead (in the worker's checkout only while it is stopped, or in a checkout of your own), attach that record with `sumctl verify TASK_ID --candidate SHA --run path/to/run.json`.
A run id already on the task is refused; a record for another SHA is refused; a `--check` record is not a run; a dirty-tree run is `inconclusive`.
Read the record for `outcome`, `certifies`, `not_exercised`, and `requires_root_review`: a candidate that changed `VERIFY.md`, `mise.toml`, `mise-tasks/`, the feature maps, or the verify skill cannot certify itself, and closure then also needs findings recorded with `review --policy-reviewed` after you read those files line by line.
A `not-yet-standardized` project keeps its existing commands and the prose record (`--result ... --text ...`).
Both forms stay the same public `sumctl verify` command.
`verify --execute` acquires its own execution reservation under the configured global and per-repository limits before creating a checkout.
When the worker has exited, `execution park TASK_ID --attempt ID` can free its slot without accepting its report or archiving the task.
Park releases only after verified stop evidence for that attempt, instance, occupant, terminal, process, and checkout.
A missing, stale, or unobservable process identity, an idle terminal, a dead parent with a surviving owned child, or an unresolved owned service still holds capacity.
A missing native terminal alone is insufficient; park requires exact process stop and survivor evidence and stops nothing itself.
An interrupted verifier keeps its reservation until that evidence permits release; inspect its ID with `execution show TASK_ID` before explicit `execution park` reconciliation.
Parking leaves any remaining verification checkout in place for inspection.
Capacity refusal does not waive independent verification or authorize raising the limits.
`verify --execute` runs no codegraph and builds no index in its detached checkout; the worker's index, if one was requested, is never read or written by coordinator verification, and a reviewer you launch may use the CLI commands from the task brief against the task checkout read-only, after `sync`.
A graph result is exploration, never a run, a review finding, or feature-map coverage.
Never run mutating checks concurrently against the same files: while the worker may still be writing, use `--execute` (its own checkout) rather than the task checkout.
Build and dependency caches may be reused when valid; a verification verdict is never reused.
Blocked or not-run outcomes stay visible in the record; a screenshot, a codegraph result, a green CI badge, or a worker's "done" is not a run.
For a behavior-changing candidate in a standardized checkout also run `python3 .agents/skills/maintain-verification/scripts/verify_audit.py --base <base SHA>` there: its `affected-map` notes name the feature maps the diff touches, an `unmapped-change` finding means the worker changed source no map covers and recorded no rationale, and `policy-changed` lists the verification files your review must read line by line.
The audit runs nothing and edits nothing; a candidate that only changed the map has authored a claim, not produced evidence.
When the run record lists `evidence.missing`, a map row names a screenshot, screencast, or red/green pair that no comparison manifest for this candidate backs, and the Test gate blocks: the record reads `blocked` with the scenarios named, `pipeline run` stops before Push, and `pipeline push` refuses.
The way out is the worker capturing, so send the instruction with `repair send`.
Only when the user decides the proof is not worth the round trip do you record their decision with `sumctl verify TASK_ID --candidate SHA --execute --accept-missing-evidence`, which stamps the waiver with your endpoint and turns the row into an explicit "evidence waived"; ask them first, because waiving is the coordinator's recorded act on their behalf, never your own judgement.
`pipeline push --allow-missing-evidence` is refused until that waiver is on the record.
Root verification runs in a fresh checkout of the candidate, so it reads the evidence root the handoff's `comparison.json` paths point at; a worker that lists no artifacts leaves nothing for it to find.
Read the worker's `comparison.json` (`.agents/skills/evidence/`) only as a claim about the paths it names, check `verdict` (`red-green`, `after-only` with `before-unavailable`, `mismatch`, `capture-failed`) against the task kind, and never treat an image without matching assertions or a comparison from another SHA as proof.
Use the repo's configured MADE/No Mistakes route when available.
Otherwise arrange a fresh-context review through a separately launched reviewer or the harness's supported independent-review facility.
Before `reviewer launch`, append an `intended` line to `.sum/action-log.md` the way `skills/sum-dispatch/SKILL.md` does for dispatch, with the task and candidate SHA as the target, then append `done` or `failed` after; it is a draft-tier side effect.
A new candidate is a new target; the same candidate inside six hours is `skipped-duplicate` unless the user asked for the launch again.
Launch a separately accountable reviewer with `./bin/sumctl reviewer launch TASK_ID`.
HC creates a unique bounded native reviewer name and exact terminal at the Git checkout; no tab, split or workspace API is involved.
Explicit `--harness`, `--model`, `--reasoning`, or `--preset` flags choose the reviewer for that launch; otherwise the saved reviewer preset (`reviewer.preset`) supplies the harness and argv, and without one the command uses the coordinator's recorded launch harness.
The preset is a launch shortcut only: it applies solely to a reviewer Sum is responsible for starting, never wraps or overrides MADE or the repository's own verification tool, and its absence changes nothing.
Terminal creation, candidate binding and opening-message outcome are separate saved facts.
A proven-unsent opening message has one explicit recovery: `sumctl reviewer redeliver TASK_ID --attempt ATTEMPT_ID`.
Never manually prompt it or automatically replay an uncertain message.
For a new candidate, run `reviewer launch TASK_ID` again: it reuses the verified live endpoint without a duplicate terminal; a replacement requires conclusive stop evidence for the previous exact endpoint and process.
A missing or mismatched task checkout is a refusal, never permission to recreate or overwrite work.
A surviving foreground process or a reviewer on another machine or unsupported core/session scope is refused rather than silently replaced.
A live reviewer cannot be silently replaced; a native address alone confers no authority.
The candidate's `requires_root_review` policy remains required and a modified policy cannot certify itself.
Use the review route required by the repository; independent review never substitutes for the coordinator's own verification.
A candidate whose verification record requires root review gets the `--policy-reviewed` guidance in the reviewer kickoff.
The reviewer receives the task contract and candidate, not an instruction to rubber-stamp the worker's summary.
Do not have simultaneous writers in the checkout.
Treat any added code comment or edit to an existing code comment in the candidate diff as a blocking finding.
This covers line and block comments, docblocks and doc comments, and comment text in fixtures and configuration files.
Do not flag comments left unchanged while surrounding code changes.
Commit messages, PR descriptions and `sumctl report` text are not code comments.
Lines or comments required for a tool or format to work are allowed, including shebangs, repository-required license headers, build tags, lint-disable pragmas, and directives such as `// @ts-expect-error`; a directive may be added only when the code cannot work without it and must include no explanatory prose.
Treat any added or expanded test, and any deleted, rewritten, skipped or disabled existing test, in the candidate diff as a blocking finding, unless the user explicitly asked for that test in this task.
Do not flag a candidate because existing tests still run.
If a separate reviewer is unavailable, say independent review was not performed; do not label the result fully reviewed.
Check `sumctl brief list TASK_ID`: the report is bound to a brief revision, and `verification_policy_changed_since` means a later revision changed the worker procedure or brief schema, or `contract_changed_since_dispatch` shows the `VERIFY.md` the worker's own run saw no longer hashes to what dispatch recorded.
Review under the current policy before accepting that evidence.
Tie the review to the exact candidate SHA.
Re-run required checks for later candidates; review the intervening changes rather than treating the previous SHA's approval as current.
A nit is not automatically a blocker.
Limit repair cycles; escalate repeated failure rather than opening an endless review/fix loop.
Use `repair send TASK_ID --attempt ID --key KEY --file FILE` for a controlled corrective instruction to a settled worker.
The default `in-scope` class covers whatever the worker needs to satisfy its approved brief and consumes nothing; `--class expansion --reason TEXT` is for work outside the brief and consumes the task's persisted allowance.
Execution resumes consume no allowance.
An uncertain expansion send stays charged and its key is never automatically replayed; a send HC refuses before delivery records nothing and charges nothing.
At exhaustion, present the saved budget decision instead of launching another expansion repair.
Record additional iterations only after the user's explicit approval, using `repair extend` with that question ID and the actual decision text.

A reviewer terminal saves its findings with `sumctl review TASK_ID --verdict approve|changes-requested|blocked|comment --candidate SHA --file findings.md` plus the compact notes the PR will publish: repeatable `--focus`, `--finding`, and `--limitation`, or `--notes notes.json` (`kind` is `review-focus`, `open-finding`, or `limitation`).
Keep the full findings in `--file`; they stay on the task record.
The PR `### Review summary` renders only those notes, as one to three bullets, and omits empty categories.
A completed review with nothing extra to tell the human reviewer omits the section.
Open findings keep severity, consequence, and the required action.
Limitations distinguish source inspection, inspection of test assertions, recorded results, independently executed checks, and live browser verification.
The first such terminal becomes the task's recorded reviewer endpoint, and saved findings are the prerequisite for closing that terminal later.
The worker terminal cannot review its own candidate.

To adopt an inspected replacement after the prior reviewer is proven stopped, use `sumctl bind TASK_ID --reviewer-terminal ADDRESS`.
It verifies native and process identity, task checkout and role/attempt evidence; it refuses the worker and any live previous reviewer.
The rebind is appended to task evidence and later review records name the replacement.
The replacement terminal's cwd must match the task checkout.
The old exact reviewer process and any foreground occupant must be proven stopped, with no surviving process bound to that checkout; a missing address or a changed cwd is not permission to replace a live reviewer.
A normal `review` never silently replaces a live endpoint.

Every recorded review, including `--tool made`, is a `review:ID` return to you, delivered like a report through the same bounded notice (the task, verdict, candidate, and the `context ... --kind review` command to read it).
Act on it: take an approved candidate on with `verify`, `pipeline push`, `pipeline pr`, `pipeline ci`, or `pr reconcile`, send the worker back with `repair send`, or bring a `blocked` verdict to the user, whose decision ends in one of those records or in archiving the task.
Any of those records after the verdict closes the return, and a newer candidate supersedes it; the notice itself closes nothing and approves nothing.
Record what you verified yourself with `sumctl verify TASK_ID --candidate SHA --result pass|fail|inconclusive --text '...'`, or with `--run`/`--execute` as above.
A newer candidate marks earlier records as not current; it deletes nothing and restarts nothing.

When the repository's configured MADE/No Mistakes route owns the review, record its result yourself from your terminal with `sumctl review TASK_ID --verdict ... --candidate SHA --tool made --run report.json`.
The file is a JSON report with `repository`, `candidate`, `run_id`, `outcome`, optional `findings` (`path`, `invariant`, `severity` blocking or advisory), and `limitations`.
A SHA or repository mismatch is refused.
An approve with blocking findings is refused.
The command does not invoke `made`, push, open a PR, or start a second reviewer loop.
A worker handoff saying `review: performed` or a `--text 'made passed'` string is a claim, not that record.
A coordinator verification run that fails parks the task with that evidence (`closure.missing` names the failed run); it stops no other worker and reinterprets no earlier claim.

From douglasjarquin/sum, MIT.

More from douglasjarquin/sum