Specgate work delivery

Delivering Work

Apply the SpecGate operating contract. This phase implements the approved contract, then stops at the next actor. Never approve an artifact or make a human delivery decision.

1. Load the exact contract

Start with the named work item:

specgate work show "$WORK_REF" --json
specgate work context "$WORK_REF" --json
specgate change status "$WORK_REF" --json

Stop before editing when approval is absent, the Context Pack is stale, or criteria are missing or placeholders. Quick work may lack an artifact. When artifact-backed work lacks its approved version, hand that blocker to the human or specgate-work-preparation.

Read only change status.data:

• If data.next_actor is not implementing_agent, hand off without editing.
• For review_pending, require next_command to be exactly one specgate CLI command without shell operators. Otherwise hand off. Run it verbatim immediately before sections 2–5. On failure, go to section 7. On success, reread only Change status and route again; stop if still review_pending.
• For rework_requested, record guidance and missing, then carry this sequence through later steps: focused fix, affected checks, updated evidence, submit, fresh status. Never submit old evidence first.
• Otherwise record missing and guidance, then enter next_command's named section; stop if none matches.

Completion criterion: every change/check maps to a criterion or required repository-doc update.

2. Resume safely

When resuming, check the persisted receipt:

specgate change status "$WORK_REF" --json

Continue only when freshness confirms a match. Stop on any mismatch signaled by stale: true. Treat an unavailable comparison as a blocker. Receipt metadata is not proof.

Completion criterion: the receipt matches this checkout, or mismatch is a human-owned blocker.

3. Check artifact drift

Skip when no artifact exists. Otherwise dispatch tasks, locate spec_repo_drift, and follow its frozen skill_content:

specgate gates tasks dispatch "$ARTIFACT_ID" --json
specgate gates tasks list "$ARTIFACT_ID" --json
specgate gates tasks submit-result <task-id> \
  --file .specgate/work/gate-<task-id>.json --json

tasks list returns skill_content and both digests; never call tasks show. Copy digests exactly. Put examined_docs and repo_commit under evidence; keep findings top-level. Report out-of-scope drift without editing it.

Completion criterion: the exact drift task has a result, or no artifact exists.

4. Implement and verify

Implement approved scope and preserve non-goals. Record required tests, lint, type checks, builds, and every skip reason. Never mutate an approved snapshot; a new artifact version belongs to specgate-work-preparation.

For a pull or merge request, include <!-- specgate-work-ref: $WORK_REF --> in its description. Never infer work identity from branches, titles, commits, filenames, headings, or keywords.

Completion criterion: every criterion is implemented or explicitly not done, and every required check has an observed result or explained skip.

5. Report criterion evidence

Create the CLI-owned scaffold:

specgate delivery report "$WORK_REF" --init --json

Keep returned data.path verbatim as $COMPLETION_PATH. Reuse an existing regular scaffold's exact error.details.path only when its change_request_id matches work show and any context_digest matches the Context Pack. Never overwrite automatically; stop when attribution is unsafe.

Fill agent.name, summary, affected_files, checks[], and exactly one criteria[] entry per canonical criterion. Give each criterion an independently reviewable claim and evidence. Anchor a local path with line, or with a heading that appears verbatim in that file: a path alone records unanchored and a wrong heading records heading_not_found, and neither carries an excerpt for the reviewer. A command name alone is not evidence. Replace every pending check with pass, fail, or skipped plus observed detail; submission rejects untouched placeholders. Evidence paths must exist. satisfied cannot depend on a failed, missing, or skipped required check. Every non-skipped checks[].command must be non-interactive and valid for sh -c.

Review the completion file, especially its shell commands, then submit:

specgate change submit "$WORK_REF" \
  --file "$COMPLETION_PATH" --run-checks --yes --json

change submit returns the same status payload; use its data, never refetch. --run-checks replaces self-reported results with observed ones. Fix failures before claiming completion.

Completion criterion: submission succeeded and its returned status was read.

6. Follow the authoritative actor

Use only change status.data. For implementing_agent, complete missing, run the supplied next_command at its named step, then reread status. A scaffold command does not complete work.

Hand off next_command verbatim.

For human_reviewer, maintainer, or none, stop. awaiting_review belongs to the human reviewer. Run peer review only when the human explicitly requests it; use a different review-only agent:

specgate delivery peer-review "$WORK_REF" --init --json
specgate delivery peer-review "$WORK_REF" \
  --file "$PEER_REVIEW_PATH" --json

Keep data.path as $PEER_REVIEW_PATH; same existing-file rule.

A pass means ready for human review, not accepted. The implementing agent never runs a human-decision command.

Export a teammate-readable review request only when the human requests one:

specgate delivery handoff export "$WORK_REF" --json

Report data.path to commit, and data.git_ignored when true — an ignored bundle never reaches the reviewer. Never commit or decide.

Completion criterion: the implementing agent has no remaining authoritative action, or one exact blocker is reported.

7. Show the delivery handoff

Read specgate change status "$WORK_REF" --json immediately before responding. For awaiting_acceptance, render:

SpecGate delivery receipt — <title> (<ref>)
Evidence: <evidence>
Assurance: <assurance>
Decision: <decision>
Receipt: <receipt>
Freshness: <freshness>
[<verdict>] <criterion text> — <why>   (one line per data.criteria entry)
[Stale: <stale_reason> — only when stale]
Next (<next_actor>): <next_command>

Preserve values verbatim, including every criterion line. Stale is a warning, not a state override. For any other state, show a compact SpecGate delivery handoff with state, missing, next_actor, and next_command; never success wording. Report a failed status as failure. Echo accepted without claiming this agent accepted it.

In Full mode only, use the URL returned by specgate open "$WORK_REF" --print --json. In Local mode, never call open. Never reread the completion file, call stats or audit, or claim cleanup eligibility, bugs prevented, time saved, accepted, or delivered without authoritative status.

Completion criterion: the response names state, evidence quality, freshness, next actor, and next command without crossing authority.