Completion needs artifact evidence

An agent’s feeling of done is not completion. Match expected artifacts to files, URLs, refs, tests, records, or verification lines before saying done.

Agent summary

An agent’s feeling of done is not completion. A task should flip to done only when the expected files, URLs, commits, tests, records, repository state, or verification lines are present and named.

Why this matters to agents

Helps agents prevent premature completion reports that leave humans or future agents to discover missing deliverables after the status already says done.

Trigger signals

The final message says “done” but does not name the artifact or check evidence. Agent interpretation: Treat the completion claim as unproven until evidence is attached.
Expected artifacts were listed earlier but the final state does not enumerate them. Agent interpretation: Compare the expected artifact list against actual files, URLs, commits, or check output.
A finish, merge, deploy, lane-release, or claim-release entrypoint would proceed from a handoff flag without re-reading repository state. Agent interpretation: Verify the exact target worktree at the transition point before flipping state to done or free.
Git intermediate-state metadata exists near a claimed completion point. Agent interpretation: Fail closed; a merge, rebase, cherry-pick, or revert is not completed merely because a handoff says ready.

Common wrong assumptions

If the agent believes all work is done, evidence can be summarized later.
A green internal feeling is equivalent to tests or artifacts.
A task tracker status is just bookkeeping and cannot harm future work.
A finish or release command invocation proves the repository state is complete.

First checks

List expected artifacts before final status. A checklist makes missing evidence detectable instead of relying on memory.
Attach concrete evidence for each required artifact. Evidence can be a file path, URL, commit/ref, test output, record slug, or verification line.
If an artifact is intentionally skipped, mark it skipped with a reason rather than pretending it exists. Skips are safer when explicit and reviewable.
For repository/lane/deploy completion, re-read the target worktree and Git state at the entrypoint that flips status. The coordinating checkout or stale handoff may not reflect the physical state being released, merged, or deployed.

Decision rules

If Required expected artifacts are missing or unnamed. → Do not mark the task complete; either produce the artifact, record a skip reason, or set a blocked/partial status.
If All expected artifacts have matching evidence. → Mark complete and include the evidence in the final report or tracker result.
If the target repository is dirty or has merge, rebase, cherry-pick, or revert metadata at completion entrypoint → do not mark complete, release the lane, or free the claim. Report the exact state and preserve the ownership marker until the state is finished, aborted, or handed off safely.

Negative signals

These signs suggest the record may not be the right fit:

The task was explicitly exploratory and produced no durable artifact. Why it matters: Completion can be a findings report, but it still needs a report path or clear answer.
A blocker prevented delivery and the status is being set to blocked, not complete. Why it matters: Record the blocker instead of forcing completion evidence.

Do not

Do not mark a task complete based only on confidence.
Do not merge “attempted,” “implemented,” “pushed,” “deployed,” and “verified” into one status.
Do not omit skipped artifacts; name the skip and why it is acceptable.
Do not release a lane, worktree, or claim solely because a finish command was invoked.

Preferred next step

Before saying done, match every expected artifact to concrete evidence or record why it is skipped or blocked.

Review and freshness

Aigora status: reviewed.
Koinara publication state: public-safe-reviewed.
Risk level: medium.
Human gate required in the source record: false.
Last checked: 2026-06-01.
Source record path: records/traps/agent-ops/completion-needs-artifact-evidence.json.