How do you enforce a real definition-of-done?

Quick update — your reframe was right, and most of it mapped onto primitives we already had. Closing the loop on what we did, in case it helps anyone else.

Verified the execution-policy primitive is real and runtime-enforced (not just docs). In our deployment there's a dedicated service enforcing it, with tests and an audit table of every review/approval decision, and blocked is a real lifecycle state.

Confirmed the behavior you described: executor → done gets intercepted to inreview, reassigned to the reviewer, and the runtime excludes the original executor from reviewing their own work.

There's also an always-on comment-required backstop — a run that posts no comment gets re-woken once, then recorded as failed. That alone kills a chunk of silent completions.

On #4 (alerts) — can confirm roll-your-own works. We already run ntfy + a small poller over GET …/approvals?status=pending and …/issues?status=blocked.

On its own it's empty noise; the value only appears once #1–#3 make a stuck task surface as blocked/pending instead of a false "done." Agreed it deserves a first-class story.

What we shipped:

Capability-gate + Definition-of-Done in every agent's instructions (the belt): before a Build task, confirm repo + creds + deploy target exist; if any is missing, no workaround artifact — move to blocked, name exactly what's missing, raise a board approval, stop.

"Done" = committed SHA on the expected branch + build passes + tests pass, pasted as a comment.

Specs/attachments are never "done."

This is the single most important failure mode in autonomous operation, and your instinct is right: a green dashboard over an empty repo isn't a discipline problem, it's a missing enforcement layer. The good news is most of what you're proposing in (1)–(4) maps onto primitives that already exist — and the parts that don't, I'll be honest about so you don't build on sand.

First, the reframe that matters: stop trying to fix this in AGENTS.md. Your four-point plan leans on instructions ("done requires committed code," "you must escalate"). Instructions are belt-and-suspenders, not a gate — an agent that believes it succeeded will sail straight through prose it has technically satisfied. The fix is structural. Three pieces:

1. Put an Execution Policy on every Implement/Build issue. This is the definition-of-done gate, and it's runtime-enforced.

Execution policies are the thing you're missing. From the docs: "Instead of trusting an agent to remember to hand work off for review, the runtime enforces review and approval stages automatically — the moment an executor tries to close the issue, the runtime intercepts the transition and routes the work to the right reviewer or approver." (Execution Policy (/docs/power-features/execution-policy))

Concretely: an executor that tries to move a Build issue to done cannot. The runtime forces it to inreview and hands it to your reviewer. The executor literally does not have the ability to mark its own build shipped. That's exactly the "specs/attachments stay inreview, never done" behavior you want — and it's enforced by the engine, not by hope.

2. Make the reviewer a verification agent whose only job is to prove the work is real.

A review/approval stage participant can be another agent. So add a dedicated Verifier/QA agent as the required reviewer on Build issues, and make its task brutally concrete — not "does this look done?" but:

git -C <repo> log --oneline -5 shows the commit that claims to implement this issue the build actually builds (npm run build / cargo build / whatever — paste the exit code and tail of output) tests pass (paste the run) approve only if green; request changes otherwise.

When it requests changes, the runtime routes back to the same executor automatically, and loops until the verifier approves. Every decision is recorded with actor + comment + run-id, so you get an audit trail. One important nuance so you don't over-engineer: there is no built-in CI/command stage type today — the policy stages are review/approval with agent or user participants. The "automated check" is implemented as the verifier agent running the build, which is the supported shape. (The pattern is sketched in Designing Execution Policies (/guides/operations/execution-policy-design); just know the concrete mechanism is the agent reviewer, not a native test-runner field.)

The deeper point: acceptance has to live in an artifact a reviewer can check, not in narrative. If a Build issue has no way to prove "it builds," that's the first thing the verifier writes, not the last. An issue that can't be verified is an issue that can't be autonomously "done."

@aronprins thank you for this in depth. Let me chew through it and get back to you with questions! I will likely take you up on your generous offer to help build-issue setup.