crewly 1.20.192 → 1.20.193

package/config/constants.ts

@@ -1430,6 +1430,17 @@ export const CLOUD_DISCONNECT_NOTICE_CONSTANTS = {
 	CHECK_INTERVAL_MS: 60 * 1000,
 	/** Repeat the notice at most this often while still disconnected (ms) — 6 h */
 	REPEAT_INTERVAL_MS: 6 * 60 * 60 * 1000,
+	/**
+	 * Relay queue registration failing (and no queue held) for this long =
+	 * disconnected (ms) — 2 min. Heartbeats can keep succeeding meanwhile, so
+	 * the 15-min "no contact" rule never sees it (2026-10-02).
+	 */
+	QUEUE_FAILURE_THRESHOLD_MS: 2 * 60 * 1000,
+	/**
+	 * When the owner was last told about a relay-queue failure (survives the
+	 * episode, so a flapping registration is reported at most every 6 h).
+	 */
+	RELAY_QUEUE_NOTICE_FILE: 'cloud/relay-queue-notice.json',
 	/** State file under the Crewly home (last notice, DM message, episode start) */
 	STATE_FILE: 'cloud/disconnect-notice.json',
 	/** Arguments for the CLI login run in a PTY (device pairing, no local browser) */

package/config/hooks/subagent-guard/subagent.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Crewly subagent guard (#852) — Claude Code SubagentStart / SubagentStop hook.
+#
+# Spec: specs/2026-10-03-subagent-guard.md
+#
+# Claude Code's tool hooks (PreToolUse/PostToolUse) do not say whether a call
+# comes from a subagent, so Crewly cannot deny a subagent's side effects per
+# call. What it can do, with the two subagent events:
+#
+#   SubagentStart — inject Crewly's subagent rules as additionalContext: do
+#     the work yourself, report back only to the parent, never close or claim
+#     WorkItems or message other agents/humans.
+#   SubagentStop  — refuse, once, a "completion" from a subagent that made no
+#     tool call at all (the silent no-op of #852: a fork that idled, or that
+#     "delegated" its own task and exited). It is sent back with a reason;
+#     a second stop is always allowed, so this can never loop.
+#
+# Usage: bash subagent.sh            # hook JSON on stdin
+#
+# Fails open: any parse error, missing transcript or missing node means
+# "allow" (exit 0, no output). It reads the subagent's own transcript only to
+# count tool_use blocks; nothing from stdin or the transcript is sent anywhere.
+
+set -u
+
+# Kill switch, independent of the control-plane guard's.
+[ "${CREWLY_SUBAGENT_GUARD:-}" = "0" ] && exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+INPUT="$(cat)"
+MARKER_DIR="${CREWLY_HOME:-$HOME/.crewly}/runtime/subagent-guard"
+
+# The program is passed through a quoted heredoc so its text needs no shell
+# escaping; the hook payload arrives on node's stdin.
+PROGRAM="$(cat <<'JS'
+const fs = require("fs");
+const path = require("path");
+
+const START_CONTEXT = [
+	"Crewly subagent rules (enforced by your parent agent's harness):",
+	"- You are a subagent. Do the assigned work yourself, with your tools. Do not hand it to another agent unless your instructions say to.",
+	"- Report your result only in your final message to the parent agent. Do not run report-status, complete-task, send-message, reply or any skill that closes, claims or verifies a WorkItem or messages another agent or a person. Your parent does that after checking your work.",
+	"- Stay inside the files, directories and branches your instructions name.",
+	"- End with evidence: the files or commits you changed, the commands you ran with their exit codes, or the exact step that blocked you and why.",
+].join("\n");
+
+const NO_OP_REASON =
+	"You are stopping without having made a single tool call, so none of the assigned work has been done. " +
+	"Do the task now with your tools (do not delegate it to another agent), or, if you cannot, reply with the exact reason you are blocked.";
+
+/** Identifier check for values used in file names. */
+const SAFE_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/** Count tool_use blocks in a Claude Code transcript (JSONL). */
+function countToolUses(file) {
+	let n = 0;
+	for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+		if (!line.includes("tool_use")) continue;
+		let entry;
+		try { entry = JSON.parse(line); } catch { continue; }
+		const content = entry && entry.message && entry.message.content;
+		if (!Array.isArray(content)) continue;
+		for (const block of content) if (block && block.type === "tool_use") n++;
+	}
+	return n;
+}
+
+let raw = "";
+process.stdin.on("data", (c) => { raw += c; });
+process.stdin.on("end", () => {
+	let input;
+	try { input = JSON.parse(raw); } catch { return; }
+	if (!input || typeof input !== "object") return;
+	const event = input.hook_event_name;
+
+	if (event === "SubagentStart") {
+		process.stdout.write(JSON.stringify({
+			hookSpecificOutput: { hookEventName: "SubagentStart", additionalContext: START_CONTEXT },
+		}));
+		return;
+	}
+	if (event !== "SubagentStop") return;
+	if (input.stop_hook_active === true) return;
+
+	const agentId = input.agent_id;
+	const parentTranscript = input.transcript_path;
+	if (typeof agentId !== "string" || !SAFE_ID.test(agentId)) return;
+	if (typeof parentTranscript !== "string" || !parentTranscript.endsWith(".jsonl")) return;
+
+	// <project>/<session>.jsonl  ->  <project>/<session>/subagents/agent-<id>.jsonl
+	const sessionDir = parentTranscript.slice(0, -".jsonl".length);
+	const transcript = path.join(sessionDir, "subagents", `agent-${agentId}.jsonl`);
+
+	let toolUses;
+	try { toolUses = countToolUses(transcript); } catch { return; }
+	if (toolUses > 0) return;
+
+	// Refuse once per subagent; the next stop goes through.
+	const marker = path.join(process.env.MARKER_DIR, `${agentId}.nudged`);
+	try {
+		fs.mkdirSync(process.env.MARKER_DIR, { recursive: true });
+		fs.writeFileSync(marker, "", { flag: "wx" });
+	} catch {
+		return;
+	}
+	process.stdout.write(JSON.stringify({ decision: "block", reason: NO_OP_REASON }));
+});
+JS
+)"
+
+printf '%s' "$INPUT" | MARKER_DIR="$MARKER_DIR" node -e "$PROGRAM" 2>/dev/null
+
+exit 0

package/config/roles/architect/prompt.md

@@ -177,5 +177,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/auditor/prompt.md

@@ -158,7 +158,7 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.
 
 ## Default Execution Loop

package/config/roles/backend-developer/prompt.md

@@ -194,5 +194,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/content-strategist/prompt.md

@@ -60,7 +60,7 @@ bash {{AGENT_SKILLS_PATH}}/core/report-status/execute.sh '{"sessionName":"{{SESS
 
 When complete:
 ```bash
-bash {{AGENT_SKILLS_PATH}}/core/report-status/execute.sh '{"sessionName":"{{SESSION_NAME}}","status":"done","summary":"<final results and key evidence>","taskPath":"<optional task file path>"}'
+bash {{AGENT_SKILLS_PATH}}/core/report-status/execute.sh '{"sessionName":"{{SESSION_NAME}}","status":"done","summary":"<final results>","evidence":[{"type":"artifact","path":"<file or https URL you produced>"}],"taskPath":"<optional task file path>"}'
 ```
 
 If blocked:
@@ -133,7 +133,7 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.
 
 ## Default Execution Loop

package/config/roles/designer/prompt.md

@@ -175,5 +175,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/developer/prompt.md

@@ -299,7 +299,7 @@ When `poll-tasks` returns `claimed: true`:
 1. Read the `workItem.title` and `workItem.description` for task details
 2. Report status as `in_progress` with the work item summary
 3. Execute the work as you would any delegated task
-4. When done, report completion — the claim is automatically released
+4. When done, report completion **with evidence** — the files you produced (`--artifact <path>`, must exist) and the checks you ran with their exit codes (`--command "<cmd>" --exit-code <n>`). If a step failed, report it blocked with the step and reason instead of done. The claim is automatically released
 
 When `poll-tasks` returns `claimed: false`:
 - No matching work is available — remain idle and wait for assignments
@@ -414,5 +414,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/frontend-developer/prompt.md

@@ -194,5 +194,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/fullstack-dev/prompt.md

@@ -194,5 +194,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/generalist/prompt.md

@@ -183,5 +183,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/ops/prompt.md

@@ -208,5 +208,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/orchestrator/prompt.md

@@ -1554,7 +1554,7 @@ If you use raw `curl`, you may get empty `$CREWLY_API_URL`, wrong ports, or miss
 | `get-project-overview` | List projects          | (no params)                                                                  |
 | `assign-task`          | Hand a WorkItem over   | `'{"workItemId":"...","target":"..."}'`                                      |
 | `project-tickets`      | Project backlog        | `list | show | create | update | assign --project <path> …` (agent core skill) |
-| `complete-task`        | Mark task done         | `'{"taskId":"...","result":"success"}'`                                      |
+| `complete-task`        | Mark task done         | `'{"workItemId":"...","summary":"...","evidence":[{"type":"artifact","path":"..."}]}'` |
 | `get-tasks`            | Task progress          | (no params)                                                                  |
 | `broadcast`            | Message all agents     | `'{"message":"..."}'`                                                        |
 | `resume-session`       | Resume agent conversation | `'{"sessionName":"agent-joe"}'`                                           |
@@ -2277,7 +2277,7 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.
 
 ## Default Execution Loop

package/config/roles/product-manager/prompt.md

@@ -304,5 +304,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/qa/prompt.md

@@ -193,5 +193,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/qa-engineer/prompt.md

@@ -193,5 +193,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/researcher/prompt.md

@@ -186,5 +186,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/sales/prompt.md

@@ -175,5 +175,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/support/prompt.md

@@ -175,5 +175,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/team-leader/prompt.md

@@ -350,7 +350,7 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.
 
 ## LLM-Wiki — Queue Worth-Saving Content (MANDATORY per-turn discipline)

package/config/roles/tpm/prompt.md

@@ -177,5 +177,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/roles/ux-designer/prompt.md

@@ -177,5 +177,5 @@ You are failing the task if you:
 - Schedule follow-up instead of continuing work in-session.
 - Mark blocked without trying at least one reasonable path.
 - Stop after partial progress without assigning next action.
-- Delegate without checking completion.
+- Delegate without checking completion (a subagent's "completed" is not proof: check its commits, files or test output before you rely on it).
 - Produce status updates but no artifact, code, decision, or verified result.

package/config/skills/_common/complete-body-shape.test.sh

@@ -246,6 +246,23 @@ else
   assert_jq "no top-level summary leak" '.summary == null' "$COMPLETE_BODY"
 fi
 
+echo ""
+echo "--- Scenario 3a: orchestrator/complete-task sends evidence under result (#873) ---"
+: > "$LOG"
+bash "${REPO_ROOT}/config/skills/orchestrator/complete-task/execute.sh" \
+  '{"workItemId":"wi-stub-1","summary":"Orc evidence summary","evidence":[{"type":"command","command":"npm test","exitCode":0}]}' \
+  >/dev/null 2>&1 || true
+
+COMPLETE_LINE=$(grep -F '"path": "/api/task-pool/complete/' "$LOG" | head -1 || true)
+if [ -z "$COMPLETE_LINE" ]; then
+  FAIL=$((FAIL + 1))
+  echo "  ✗ no /task-pool/complete POST captured"
+else
+  COMPLETE_BODY=$(printf '%s' "$COMPLETE_LINE" | jq -r '.body')
+  assert_complete_contract "orc-complete-task+evidence" "$COMPLETE_BODY"
+  assert_jq "result.evidence carries the command" '.result.evidence == [{"type":"command","command":"npm test","exitCode":0}]' "$COMPLETE_BODY"
+fi
+
 echo ""
 echo "--- Scenario 3b: orchestrator/complete-task with explicit agentId override ---"
 : > "$LOG"

package/config/skills/agent/core/complete-task/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Complete Task
-description: Mark a task as complete with a summary of the work done.
-version: 1.2.0
+description: Mark a task as complete with a summary and evidence (artifacts that exist, commands with exit codes), or report it blocked.
+version: 1.3.0
 category: task-management
 skillType: claude-skill
 assignableRoles:
@@ -46,6 +46,7 @@ Mark a task as complete with a summary of the work done. If the task has an outp
 | `workItemId` | Preferred | ID of the V3 WorkItem to complete. This is the only input that selects the WorkItem |
 | `sessionName` | Yes | Your agent session name |
 | `summary` | Yes | Summary of the work completed |
+| `evidence` | Yes* | Array of evidence entries — see **Evidence contract** below. *Accepted without it this release (with a warning); required from the next release |
 | `absoluteTaskPath` | No | **Legacy (V1).** Still accepted so older callers keep working, but it does NOT identify a WorkItem |
 | `output` | No | Structured output object (required if task has an output schema) |
 | ~~`skipGates`~~ | **Rejected** | **Not supported.** This endpoint runs no quality gates, so there is nothing to skip. Passing it is a hard error. Use the `check-quality-gates` skill for gates. |
@@ -64,10 +65,32 @@ Pass `workItemId` whenever you know it — the lookup in step 2 depends on the
 pool state at that instant and cannot disambiguate two concurrently running
 items for one session.
 
+## Evidence contract (#873)
+
+"Done" needs evidence. Send `evidence` as an array; each entry is one of:
+
+| Entry | Fields | Server check |
+|-------|--------|--------------|
+| `{"type":"artifact","path":"…"}` | Absolute path, path relative to your worktree/project, or an `https://` URL | A local path must exist, else 400 |
+| `{"type":"command","command":"…","exitCode":0,"outputTail":"…"}` | The command, its exit code, the last lines of its output | `exitCode` must be 0, else 400 — a failing command is not evidence of done |
+| `{"type":"blocked","step":"…","reason":"…"}` | The step that failed and why | The WorkItem is recorded as **blocked**, not done |
+
+If you could not finish, do **not** report done: send a `blocked` entry (or use
+`report-status --status blocked`). Malformed evidence is rejected with 400
+naming the bad entry. A completion with no evidence is accepted this release
+but the response (and stderr) carries a `warning`; next release it is a 400.
+A review verdict (`verdict` set) needs no evidence.
+
 ## Example
 
 ```bash
-bash config/skills/agent/core/complete-task/execute.sh '{"workItemId":"wi-abc123","sessionName":"dev-1","summary":"Implemented login form with validation and tests"}'
+bash config/skills/agent/core/complete-task/execute.sh '{"workItemId":"wi-abc123","sessionName":"dev-1","summary":"Implemented login form with validation and tests","evidence":[{"type":"artifact","path":"src/login.tsx"},{"type":"command","command":"npx jest src/login.test.tsx","exitCode":0,"outputTail":"Tests: 6 passed, 6 total"}]}'
+```
+
+### Could not finish
+
+```bash
+bash config/skills/agent/core/complete-task/execute.sh '{"workItemId":"wi-abc123","sessionName":"dev-1","summary":"Login form done; e2e blocked","evidence":[{"type":"blocked","step":"npx playwright test","reason":"staging auth server returns 503"}]}'
 ```
 
 ### Letting the skill resolve your running WorkItem
@@ -102,7 +125,7 @@ If the task markdown contains an `## Output Schema` section with a JSON Schema d
 Before calling this skill, verify:
 
 1. **All requirements met** — re-read the original task and confirm every requirement is addressed
-2. **Code tested** — if you wrote code, run the relevant tests and confirm they pass
+2. **Code tested** — if you wrote code, run the relevant tests, confirm they pass, and put the command and its exit code in `evidence`
 3. **URLs verified** — if your output includes URLs or links, verify they are valid
 4. **Sources cited** — for research tasks, ensure all factual claims have source references
 5. **Summary accurate** — your summary should reflect what was actually done, not just what was planned

package/config/skills/agent/core/complete-task/execute.sh

@@ -5,7 +5,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../../_common/lib.sh"
 
 INPUT=$(read_json_input "${1:-}")
-[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"wi-abc123\",\"sessionName\":\"dev-1\",\"summary\":\"Implemented feature X\",\"output\":{\"key\":\"value\"}}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"wi-abc123\",\"sessionName\":\"dev-1\",\"summary\":\"Implemented feature X\",\"evidence\":[{\"type\":\"artifact\",\"path\":\"/abs/path/or/https-url\"},{\"type\":\"command\",\"command\":\"npm test\",\"exitCode\":0,\"outputTail\":\"42 passed\"}]}'"
 
 # `workItemId` is the V3 identifier and the ONLY input that drives the API
 # call (see the resolution block further down). `absoluteTaskPath` is the
@@ -41,6 +41,17 @@ if [ -n "$SKIP_GATES" ]; then
   error_exit "skipGates is not supported by complete-task and never was — it was accepted and silently discarded. POST /task-pool/complete runs no quality gates, so there is nothing here to skip. Quality gates live behind the 'check-quality-gates' skill (POST /quality-gates/check); run or skip them there. Remove skipGates from this call."
 fi
 OUTPUT_JSON=$(printf '%s' "$INPUT" | jq -c '.output // empty')
+# Evidence contract (#873): "done" needs evidence. Each entry is one of
+#   {"type":"artifact","path":"<existing file, relative to the project/worktree, or https URL>"}
+#   {"type":"command","command":"<cmd>","exitCode":0,"outputTail":"<last lines>"}
+#   {"type":"blocked","step":"<step that failed>","reason":"<why>"}
+# A `blocked` entry records the WorkItem as BLOCKED, not done. The server
+# checks the rest (artifacts exist, exit codes are 0); this only checks the
+# block is an array so a typo fails here instead of as a 400.
+EVIDENCE_JSON=$(printf '%s' "$INPUT" | jq -c '.evidence // empty')
+if [ -n "$EVIDENCE_JSON" ] && [ "$(printf '%s' "$EVIDENCE_JSON" | jq -r 'type')" != "array" ]; then
+  error_exit "evidence must be a JSON array of entries, e.g. [{\"type\":\"artifact\",\"path\":\"/abs/file\"},{\"type\":\"command\",\"command\":\"npm test\",\"exitCode\":0}] — or [{\"type\":\"blocked\",\"step\":\"...\",\"reason\":\"...\"}] if you could not finish"
+fi
 # Reviewing someone's work (a "Verify: …" item): `verdict: "rejected"` plus
 # `feedback` sends it back — the worker gets a retry carrying the feedback.
 # Anything else (or nothing) accepts it.
@@ -144,6 +155,7 @@ BODY=$(jq -n \
   --argjson output "${OUTPUT_JSON:-null}" \
   --arg verdict "$VERDICT" \
   --arg feedback "$FEEDBACK" \
+  --argjson evidence "${EVIDENCE_JSON:-null}" \
   '{
     agentId: $agentId,
     result: ({summary: $summary}
@@ -151,10 +163,18 @@ BODY=$(jq -n \
                  then $output
                  else {} end)
               + (if $verdict != "" then {verdict: $verdict} else {} end)
-              + (if $feedback != "" then {feedback: $feedback} else {} end))
+              + (if $feedback != "" then {feedback: $feedback} else {} end)
+              + (if $evidence != null then {evidence: $evidence} else {} end))
   }')
 
-api_call POST "/task-pool/complete/${WORK_ITEM_ID}" "$BODY"
+COMPLETE_RESPONSE=$(api_call POST "/task-pool/complete/${WORK_ITEM_ID}" "$BODY")
+printf '%s\n' "$COMPLETE_RESPONSE"
+# Warn-mode rollout (#873): the server accepts a completion without evidence
+# for one release but says so. Repeat it on stderr so it is not missed.
+EVIDENCE_WARNING=$(printf '%s' "$COMPLETE_RESPONSE" | jq -r '.warning // empty' 2>/dev/null || true)
+if [ -n "$EVIDENCE_WARNING" ]; then
+  jq -n --arg w "$EVIDENCE_WARNING" '{warning: $w}' >&2
+fi
 
 # The summary is stored on the WorkItem (result.summary) and in the project's
 # task-history.json ledger. It is deliberately NOT saved to long-term memory:

package/config/skills/agent/core/complete-task/execute.test.sh

@@ -92,6 +92,12 @@ if [ "$METHOD" = "GET" ] && printf '%s' "$URL" | grep -q '/task-pool/items'; the
   exit 0
 fi
 
+if [ -n "${STUB_COMPLETE_RESPONSE:-}" ] && printf '%s' "$URL" | grep -q '/task-pool/complete/'; then
+  echo "$STUB_COMPLETE_RESPONSE"
+  echo "200"
+  exit 0
+fi
+
 echo '{"success":true,"stub":true}'
 echo "200"
 STUB_EOF
@@ -233,6 +239,34 @@ assert_contains "completion still reaches the task pool" \
 assert_not_contains "no /memory/remember call on completion" "/memory/remember" "$REQUESTS"
 assert_not_contains "no /memory/record-learning call on completion" "/memory/record-learning" "$REQUESTS"
 
+echo ""
+echo "--- Evidence contract (#873) ---"
+
+run_skill '{"workItemId":"wi-ev","sessionName":"dev-1","summary":"Report written","evidence":[{"type":"artifact","path":"/proj/report.md"},{"type":"command","command":"npm test","exitCode":0,"outputTail":"42 passed"}]}'
+EV_BODY="$(printf '%s' "$BODIES" | grep 'agentId' | head -1 || true)"
+EV_TYPES="$(printf '%s' "$EV_BODY" | jq -r '[.result.evidence[].type] | join(",")' 2>/dev/null || echo "MISSING")"
+assert_contains "evidence is sent under result.evidence, in order" "artifact,command" "$EV_TYPES"
+EV_EXIT="$(printf '%s' "$EV_BODY" | jq -r '.result.evidence[1].exitCode' 2>/dev/null || echo "MISSING")"
+assert_contains "command exitCode is sent as a number" "0" "$EV_EXIT"
+EV_TOP="$(printf '%s' "$EV_BODY" | jq -r 'has("evidence")' 2>/dev/null || echo "MISSING")"
+assert_contains "evidence is NOT sent at the top level" "false" "$EV_TOP"
+
+run_skill '{"workItemId":"wi-ev","sessionName":"dev-1","summary":"Could not finish","evidence":[{"type":"blocked","step":"npm test","reason":"db down"}]}'
+EV_BODY="$(printf '%s' "$BODIES" | grep 'agentId' | head -1 || true)"
+assert_contains "blocked evidence is sent" '"type": "blocked"' "$EV_BODY"
+
+run_skill '{"workItemId":"wi-ev","sessionName":"dev-1","summary":"Report written","evidence":{"type":"artifact","path":"/x"}}'
+assert_contains "non-array evidence is refused locally" "evidence must be a JSON array" "$OUT"
+assert_not_contains "no request sent for non-array evidence" "/task-pool/complete" "$REQUESTS"
+
+run_skill '{"workItemId":"wi-plain","sessionName":"dev-1","summary":"Report written"}'
+EV_BODY="$(printf '%s' "$BODIES" | grep 'agentId' | head -1 || true)"
+assert_not_contains "no evidence key when none given" '"evidence"' "$EV_BODY"
+
+STUB_COMPLETE_RESPONSE='{"success":true,"message":"WorkItem wi-plain completed","warning":"Completed WITHOUT evidence. Send body.result.evidence"}' \
+  run_skill '{"workItemId":"wi-plain","sessionName":"dev-1","summary":"Report written"}'
+assert_contains "server warning is printed" '"warning": "Completed WITHOUT evidence' "$OUT"
+
 rm -rf "$STUB_DIR"
 
 echo ""

package/config/skills/agent/core/handoff-task/execute.sh

@@ -128,7 +128,7 @@ fi
 cat >> "$HANDOFF_MSG_FILE" << FOOTER_EOF
 
 ---
-When done, report back with report-status, passing the workItemId from your [CREWLY-DISPATCH] notice (or from get-my-tasks) so the right WorkItem is closed: bash ${CREWLY_ROOT}/config/skills/agent/core/report-status/execute.sh '{"sessionName":"${TO}","workItemId":"<your WorkItem id>","status":"done","summary":"<brief summary>","projectPath":"${PROJECT_PATH}"}'
+When done, report back with report-status, passing the workItemId from your [CREWLY-DISPATCH] notice (or from get-my-tasks) so the right WorkItem is closed: bash ${CREWLY_ROOT}/config/skills/agent/core/report-status/execute.sh '{"sessionName":"${TO}","workItemId":"<your WorkItem id>","status":"done","summary":"<brief summary>","evidence":[{"type":"artifact","path":"<file you produced>"},{"type":"command","command":"<check you ran>","exitCode":0}],"projectPath":"${PROJECT_PATH}"}' — done needs evidence (files that exist, checks with exit code 0); if a step failed, send [{"type":"blocked","step":"<step>","reason":"<why>"}] instead, never done.
 FOOTER_EOF
 
 HANDOFF_MESSAGE=$(cat "$HANDOFF_MSG_FILE")

package/config/skills/agent/core/report-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Report Status
 description: Proactively notify the orchestrator when a task is done, blocked, or failed.
-version: 1.0.0
+version: 1.1.0
 category: task-management
 skillType: claude-skill
 assignableRoles:
@@ -59,6 +59,24 @@ Pass the `workItemId` of the work you are reporting on (from your `[CREWLY-DISPA
 | `--structured` | `structured` | No | Use structured StatusReport format |
 | `--work-item-id` / `--wi-id` | `workItemId` | **Pass this when `status` is `done`, `blocked` or `failed`** | Which WorkItem to complete, block or fail. See below — without it the skill infers, and refuses when the choice is ambiguous |
 
+### Evidence (status `done`) — #873
+
+"Done" needs evidence. Add one or more of:
+
+| Flag | JSON | Entry sent |
+|------|------|------------|
+| `--artifact <path>` (repeatable) | — | `{"type":"artifact","path":…}` — absolute, relative to your worktree/project, or an `https://` URL. Must exist on the server. |
+| `--command <cmd> --exit-code <n> [--output-tail <text>]` (repeatable group) | — | `{"type":"command","command":…,"exitCode":n,"outputTail":…}` — `exitCode` must be 0 |
+| `--blocked-step <step> --blocked-reason <why>` | — | `{"type":"blocked",…}` — the WorkItem is recorded as **blocked**, not done |
+| `--evidence '<json array>'` | `evidence` | The raw array, sent ahead of any flag entries |
+
+The server rejects (400) a missing artifact, a non-zero exit code, or a
+malformed entry; the skill then prints `{"warning":"… completing the WorkItem
+FAILED …","error":…}` with the reason. Without any evidence, `done` is accepted
+**this release** with a `warning` on stderr; from the next release it is
+refused. If you could not finish, report `--status blocked` (or `done` with
+`--blocked-step/--blocked-reason`), never `done`.
+
 ## This skill COMPLETES a WorkItem, not just reports
 
 When `status=done`, this skill closes a WorkItem in the task pool as a side
@@ -93,8 +111,13 @@ the skill refuses instead of guessing.
 ## Examples — CLI Flags (preferred)
 
 ```bash
-# Report done
-bash execute.sh --session dev-1 --status done --summary "Finished auth module, all tests pass" --project /path/to/project
+# Report done, with evidence
+bash execute.sh --session dev-1 --status done --summary "Finished auth module, all tests pass" --project /path/to/project \
+  --work-item-id <id> --artifact src/auth.ts --command "npx jest src/auth" --exit-code 0 --output-tail "Tests: 14 passed"
+
+# Could not finish one step: recorded as blocked, not done
+bash execute.sh --session dev-1 --status done --summary "Auth module written; e2e blocked" --work-item-id <id> \
+  --blocked-step "npx playwright test" --blocked-reason "staging login returns 503"
 
 # Report a blocker
 bash execute.sh --session dev-1 --status blocked --summary "Waiting on API credentials from ops team"
@@ -119,7 +142,7 @@ bash execute.sh --session dev-1 --status done --summary-file /tmp/summary.txt --
 ## Examples — Legacy JSON (backward compatible)
 
 ```bash
-bash execute.sh '{"sessionName":"dev-1","status":"done","summary":"Finished implementing auth module","workItemId":"<your WorkItem id>"}'
+bash execute.sh '{"sessionName":"dev-1","status":"done","summary":"Finished implementing auth module","workItemId":"<your WorkItem id>","evidence":[{"type":"command","command":"npm test","exitCode":0}]}'
 ```
 
 ## Output