keel-review-checklist

Purpose

Use this thin Keel consistency gate only at completion gates: after a complete openspec-apply-change task group, before openspec-sync-specs or openspec-archive-change, before meaningful handoff, or when delivery reports risks, findings, follow-ups, or out-of-scope need.

Shared Core commands (keel gate task-start, task-complete, and change-close) validate deterministic structure. They do not judge product intent, behavioral test sufficiency, design quality, or risk completeness. Those judgments remain with the current agent.

Context to read

Read the selected OpenSpec proposal, design, specs, tasks, diff, and command evidence. Read keel/HANDOFF.md only when validating an optional override; it is never evidence or a durable follow-up owner.

Deterministic gate check

• Confirm the appropriate shared Core gate was run and its versioned result is pass.
• A behavioral task's checks must prove observable Acceptance through the public interface, not build-only or shape-only evidence.
• task-complete itself refuses a missing or drifted Contract anchor and missing .red/.green Evidence; a drift result returns the task to authoring for explicit reauthorization instead of review. What it cannot see is whether the evidence proves anything: evidence-first tasks name their observable proof.
• A failure message must name the actual cause of what it reports. Watch for one condition guarding two distinct failures — if result is None or result["status"] != expected reports the first failure's message when the second one happened, sending the reader to a place with no problem in it. Split the condition. No gate can judge this: deciding whether a sentence misleads needs a model, so it stays here.
• When two tasks in the change declared the same Touch set under a red-green strategy — keel gate task-start warns about this — ask whether they turned out to be one behavior split in half. The tell is that the first task's minimal implementation was wrong in the field, or that the second had no honest red left because the first already made its checks pass. The gate can only see the shape; by completion you can see the outcome, which is the only point at which this is answerable.
• Scope attribution is now the gate's job by default: keel gate task-complete compares the worktree against the dirty set task-start recorded and refuses a path outside Touch, so a pass is evidence about scope rather than silence about it. Two cases still need you. When the gate reports paths as unattributed — no recorded set, because the manifest predates the field or the guard was cleared — nothing was checked and the review is the only scope evidence. And a path already dirty when the task started stays unattributed only while its content matches what was recorded then; if the task changed it again, the gate attributes it — so read the gate's silence about such a path as evidence its content was never touched again, not as an unconditional exemption.

Semantic Review

Record the current agent's judgment inside the selected task Evidence:

• Status: pass only when the task is ready to complete.
• Acceptance check: why the behavior evidence proves the authored Acceptance.
• Scope check: why the actual changes stay within Touch; identify an explicit base if deterministic comparison was used.
• Findings: none, or every finding with the disposition it actually has.

A finding has three, and the criterion is what the task did about it — not whichever marker gets past the gate:

• Resolved here: — found and fixed inside this task. Name what proves it: an M<n> check this task declares, or a repo-relative path that exists. If no check covers it, the fix is not proved and the finding is one of the other two.
• Durable owner: — real, still open, and someone must do it. Name an absolute https://… tracker reference or a repo-relative path that exists. The reference must already carry the content it claims to hold.
• Discard reason: — considered, and deliberately not being done. Say why.

Picking the marker that passes rather than the one that is true is how a repair gets filed as a dismissal, and the archive then records the opposite of what happened.

The Review remains in tasks.md. A user-facing Report summarizes delivery but is not hidden gate state. Do not let Core or this checklist write evidence automatically.

Expectation and follow-up ownership

Each related critical expectation needs behavior evidence, a durable follow-up owner, or an explicit discard reason. Relevant D<n>, F<n>, A<n>, and Q<n> references in Covers must agree with their OpenSpec basis and resolution owner. Unresolved authority returns to OpenSpec authoring.

A durable owner declared as a URL must already carry the content it claims to hold, at the moment it is cited. A valid link to an empty issue owns nothing: create the content, then reference it. Check this when it is cited, not at archive — a check deferred to the close finds the same fact after the reauthorization it should have prevented. This is not a deterministic gate check and must not become one: a gate that fetched a reference would stop being local and offline, which is the property its verdict rests on.

keel/HANDOFF.md is an optional pointer override and cannot own findings, critical expectation state, evidence details, or follow-ups.

Conditional checks

Read conditional-checks.md beside this file only when a task declares Coupling: required, a keel/lenses/ lens matches the change's domain, the change adds or materially expands a dedicated skill, or the work followed an accepted native plan-mode artifact. Each of its sections states the criterion for one of these.

Output

Report one of:

• pass
• return-to-work
• create-owner-first
• escalate

Do not expand implementation scope during review.