crewly 1.20.192 → 1.20.194

package/config/skills/agent/core/experiment-card/execute.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# =============================================================================
+# experiment-card — attach an experiment to an optimisation ticket; Crewly
+# captures the baseline when it ships and measures it when the window ends.
+#
+# Backed by /api/experiments (specs/experiment-cards.md, issue #986).
+#
+# Usage:
+#   bash execute.sh create --hypothesis "…" --source gsc|ga4 --measure M --config /abs/seo-ops.config.json
+#                          [--page P] [--page-match exact|contains] [--query Q] [--query-match exact|contains]
+#                          [--event NAME] [--channel all] [--label "…"] [--title "…"]
+#                          [--from A] [--to B] [--direction increase|decrease] [--window-days 14]
+#                          [--confidence 0.6] [--project P --ticket ID | --tkt TKT-12]
+#   bash execute.sh ship    --id EXP-3 [--shipped-at ISO]
+#   bash execute.sh show    --id EXP-3
+#   bash execute.sh list    [--status planned|running|done|cancelled] [--ticket ID]
+#   bash execute.sh measure --id EXP-3
+#   bash execute.sh cancel  --id EXP-3 [--reason "…"]
+#   bash execute.sh '{"action":"create","hypothesis":"…","metric":{…},"ticket":{…}}'
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh create --hypothesis "change X → metric Y from a to b" --source gsc|ga4 --measure M
+                         --config /abs/path/seo-ops.config.json [filters] [--from A] [--to B]
+                         [--window-days 14] [--confidence 0.6] [--project P --ticket ID | --tkt TKT-12]
+      gsc measures: clicks impressions ctr position   (filters: --page URL --query Q, --page-match/--query-match exact|contains)
+      ga4 measures: sessions events                   (filters: --page /path, --event NAME, --channel all)
+  bash execute.sh ship    --id EXP-3 [--shipped-at ISO]   The change is live (automatic when the ticket is done)
+  bash execute.sh show    --id EXP-3                      Card, baseline, result and timeline
+  bash execute.sh list    [--status S] [--ticket ID]
+  bash execute.sh measure --id EXP-3                      Measure now (only once it is due)
+  bash execute.sh cancel  --id EXP-3 [--reason "…"]
+EOF_USAGE
+}
+
+ACTION=""; ID=""; JSON_BODY=""
+HYPOTHESIS=""; TITLE=""; SOURCE=""; MEASURE=""; CONFIG=""; PAGE=""; PAGE_MATCH=""; QUERY=""; QUERY_MATCH=""
+EVENT=""; CHANNEL=""; LABEL=""; FROM=""; TO=""; DIRECTION=""; WINDOW=""; CONFIDENCE=""; PROJECT=""; TICKET=""; TKT=""
+SHIPPED_AT=""; STATUS=""; REASON=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  J=$(read_json_input "$1"); shift
+  ACTION=$(printf '%s' "$J" | jq -r '.action // empty')
+  ID=$(printf '%s' "$J" | jq -r '.id // empty')
+  SHIPPED_AT=$(printf '%s' "$J" | jq -r '.shippedAt // empty')
+  STATUS=$(printf '%s' "$J" | jq -r '.status // empty')
+  REASON=$(printf '%s' "$J" | jq -r '.reason // empty')
+  TICKET=$(printf '%s' "$J" | jq -r 'if (.ticket|type) == "string" then .ticket else empty end')
+  JSON_BODY=$(printf '%s' "$J" | jq -c 'del(.action, .id, .shippedAt, .status, .reason)')
+fi
+if [[ -z "$ACTION" && $# -gt 0 && ${1:0:1} != '-' ]]; then ACTION="$1"; shift; fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id)            [ $# -ge 2 ] || error_exit "--id requires a value"; ID="$2"; shift 2 ;;
+    --hypothesis)    [ $# -ge 2 ] || error_exit "--hypothesis requires a value"; HYPOTHESIS="$2"; shift 2 ;;
+    --title)         [ $# -ge 2 ] || error_exit "--title requires a value"; TITLE="$2"; shift 2 ;;
+    --source)        [ $# -ge 2 ] || error_exit "--source requires a value"; SOURCE="$2"; shift 2 ;;
+    --measure)       [ $# -ge 2 ] || error_exit "--measure requires a value"; MEASURE="$2"; shift 2 ;;
+    --config)        [ $# -ge 2 ] || error_exit "--config requires a value"; CONFIG="$2"; shift 2 ;;
+    --page)          [ $# -ge 2 ] || error_exit "--page requires a value"; PAGE="$2"; shift 2 ;;
+    --page-match)    [ $# -ge 2 ] || error_exit "--page-match requires a value"; PAGE_MATCH="$2"; shift 2 ;;
+    --query)         [ $# -ge 2 ] || error_exit "--query requires a value"; QUERY="$2"; shift 2 ;;
+    --query-match)   [ $# -ge 2 ] || error_exit "--query-match requires a value"; QUERY_MATCH="$2"; shift 2 ;;
+    --event)         [ $# -ge 2 ] || error_exit "--event requires a value"; EVENT="$2"; shift 2 ;;
+    --channel)       [ $# -ge 2 ] || error_exit "--channel requires a value"; CHANNEL="$2"; shift 2 ;;
+    --label)         [ $# -ge 2 ] || error_exit "--label requires a value"; LABEL="$2"; shift 2 ;;
+    --from)          [ $# -ge 2 ] || error_exit "--from requires a value"; FROM="$2"; shift 2 ;;
+    --to)            [ $# -ge 2 ] || error_exit "--to requires a value"; TO="$2"; shift 2 ;;
+    --direction)     [ $# -ge 2 ] || error_exit "--direction requires a value"; DIRECTION="$2"; shift 2 ;;
+    --window-days)   [ $# -ge 2 ] || error_exit "--window-days requires a value"; WINDOW="$2"; shift 2 ;;
+    --confidence)    [ $# -ge 2 ] || error_exit "--confidence requires a value"; CONFIDENCE="$2"; shift 2 ;;
+    --project|-p)    [ $# -ge 2 ] || error_exit "--project requires a value"; PROJECT="$2"; shift 2 ;;
+    --ticket)        [ $# -ge 2 ] || error_exit "--ticket requires a value"; TICKET="$2"; shift 2 ;;
+    --tkt)           [ $# -ge 2 ] || error_exit "--tkt requires a value"; TKT="$2"; shift 2 ;;
+    --shipped-at)    [ $# -ge 2 ] || error_exit "--shipped-at requires a value"; SHIPPED_AT="$2"; shift 2 ;;
+    --status)        [ $# -ge 2 ] || error_exit "--status requires a value"; STATUS="$2"; shift 2 ;;
+    --reason)        [ $# -ge 2 ] || error_exit "--reason requires a value"; REASON="$2"; shift 2 ;;
+    --help|-h)       print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1" ;;
+  esac
+done
+
+enc() { jq -rn --arg v "$1" '$v|@uri'; }
+CARD='{id, status, title, hypothesis, metric: (.metric | {source, measure, page, query, event, label} | with_entries(select(.value != null))), windowDays, ticket, shippedAt, dueAt, baseline: (.baseline.total // null), result: (.result.total // null), verdict, verdictReason, lastError, traceId}'
+
+case "$ACTION" in
+  create)
+    if [ -n "$JSON_BODY" ] && [ "$JSON_BODY" != "{}" ]; then
+      BODY="$JSON_BODY"
+    else
+      require_param "hypothesis (--hypothesis)" "$HYPOTHESIS"
+      require_param "source (--source gsc|ga4)" "$SOURCE"
+      require_param "measure (--measure)" "$MEASURE"
+      require_param "config (--config, the seo-ops site config)" "$CONFIG"
+      if [ -n "$TICKET" ] && [ -z "$PROJECT" ]; then error_exit "--ticket needs --project (or use --tkt TKT-n for a harness ticket)"; fi
+      BODY=$(jq -cn \
+        --arg h "$HYPOTHESIS" --arg t "$TITLE" --arg s "$SOURCE" --arg m "$MEASURE" --arg c "$CONFIG" \
+        --arg page "$PAGE" --arg pm "$PAGE_MATCH" --arg q "$QUERY" --arg qm "$QUERY_MATCH" --arg ev "$EVENT" \
+        --arg ch "$CHANNEL" --arg lb "$LABEL" --arg from "$FROM" --arg to "$TO" --arg dir "$DIRECTION" \
+        --arg win "$WINDOW" --arg conf "$CONFIDENCE" --arg proj "$PROJECT" --arg tic "$TICKET" --arg tkt "$TKT" '
+        def opt($k; $v): if $v == "" then {} else {($k): $v} end;
+        {hypothesis: $h}
+        + opt("title"; $t)
+        + {metric: ({source: $s, measure: $m, config: $c}
+            + opt("page"; $page) + opt("pageMatch"; $pm) + opt("query"; $q) + opt("queryMatch"; $qm)
+            + opt("event"; $ev) + opt("channel"; $ch) + opt("label"; $lb))}
+        + (if $from == "" and $to == "" then {} else {expected: (opt("from"; $from) + opt("to"; $to))} end)
+        + opt("direction"; $dir) + opt("windowDays"; $win) + opt("confidence"; $conf)
+        + (if $tkt != "" then {ticket: {kind: "harness", id: $tkt}}
+           elif $tic != "" then {ticket: {kind: "project", project: $proj, id: $tic}}
+           else {} end)')
+    fi
+    api_call POST "/experiments" "$BODY" | jq "{success, experiment: (.data | ${CARD})}"
+    ;;
+  ship)
+    require_param "id (--id EXP-n)" "$ID"
+    BODY=$(jq -cn --arg at "$SHIPPED_AT" 'if $at == "" then {} else {shippedAt: $at} end')
+    api_call POST "/experiments/$(enc "$ID")/ship" "$BODY" | jq "{success, experiment: (.data | ${CARD})}"
+    ;;
+  show)
+    require_param "id (--id EXP-n)" "$ID"
+    api_call GET "/experiments/$(enc "$ID")" | jq "{success, experiment: (.data | ${CARD} + {timeline})}"
+    ;;
+  list)
+    QS=""
+    [ -n "$STATUS" ] && QS="status=$(enc "$STATUS")"
+    [ -n "$TICKET" ] && QS="${QS:+$QS&}ticket=$(enc "$TICKET")"
+    api_call GET "/experiments${QS:+?$QS}" | jq "{success, experiments: [.data[] | ${CARD}]}"
+    ;;
+  measure)
+    require_param "id (--id EXP-n)" "$ID"
+    api_call POST "/experiments/$(enc "$ID")/measure" '{}' | jq "{success, experiment: (.data | ${CARD})}"
+    ;;
+  cancel)
+    require_param "id (--id EXP-n)" "$ID"
+    BODY=$(jq -cn --arg r "$REASON" 'if $r == "" then {} else {reason: $r} end')
+    api_call POST "/experiments/$(enc "$ID")/cancel" "$BODY" | jq "{success, experiment: (.data | ${CARD})}"
+    ;;
+  ""|help) print_usage; [ -n "$ACTION" ] || exit 1 ;;
+  *) error_exit "Unknown action: $ACTION (create, ship, show, list, measure, cancel)" ;;
+esac

package/config/skills/agent/core/experiment-card/execute.test.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# Tests for experiment-card — run with: bash execute.test.sh
+# A python HTTP stub plays the backend; asserts the calls and the output.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+PORT=18853
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+E = {'id': 'EXP-1', 'traceId': 'exp:EXP-1', 'status': 'planned', 'title': 'T', 'hypothesis': 'H',
+     'metric': {'source': 'gsc', 'measure': 'clicks', 'config': '/c.json', 'page': 'https://x/'}, 'windowDays': 14,
+     'baseline': {'total': 100, 'days': [1, 2]}, 'timeline': [{'at': 'a', 'event': 'created'}], 'createdBy': 'ella'}
+class H(BaseHTTPRequestHandler):
+    def reply(self, code, obj):
+        self.send_response(code); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps(obj).encode())
+    def record(self, body=None):
+        open(LOG, 'w').write(json.dumps({'method': self.command, 'path': self.path, 'body': body, 'agent': self.headers.get('X-Agent-Session')}))
+    def do_GET(self):
+        self.record()
+        if self.path.startswith('/api/experiments/'):
+            return self.reply(200, {'success': True, 'data': E})
+        return self.reply(200, {'success': True, 'data': [E, dict(E, id='EXP-2', status='done', verdict='worked')]})
+    def do_POST(self):
+        n = int(self.headers.get('content-length', '0')); body = json.loads(self.rfile.read(n).decode() or '{}')
+        self.record(body)
+        if self.path.endswith('/measure'):
+            return self.reply(409, {'success': False, 'error': 'EXP-1 is not due until 2026-10-28'})
+        return self.reply(200, {'success': True, 'data': E})
+    def log_message(self, *a, **k): pass
+HTTPServer(('127.0.0.1', PORT), H).serve_forever()
+PY
+STUB_PID=$!
+disown "$STUB_PID" 2>/dev/null || true
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -f "$STUB_LOG"' EXIT
+for i in $(seq 1 30); do curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/" 2>/dev/null && break; sleep 0.1; done
+
+run() { CREWLY_SESSION_NAME=ella CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { CREWLY_SESSION_NAME=ella CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1 >/dev/null; }
+last() { jq -r "$1" "$STUB_LOG"; }
+
+# --- create on a project ticket: metric, expectation, window ---
+OUT=$(run create --hypothesis "FAQ schema → clicks 100 to 140" --source gsc --measure clicks --config /c.json \
+  --page https://x/ --from 100 --to 140 --window-days 21 --project ce --ticket T-12)
+check "create: path" "$(last .path)" "/api/experiments"
+check "create: body" "$(last '.body | tostring')" '{"hypothesis":"FAQ schema → clicks 100 to 140","metric":{"source":"gsc","measure":"clicks","config":"/c.json","page":"https://x/"},"expected":{"from":"100","to":"140"},"windowDays":"21","ticket":{"kind":"project","project":"ce","id":"T-12"}}'
+check "create: agent header" "$(last .agent)" "ella"
+check "create: card" "$(printf '%s' "$OUT" | jq -c '.experiment | [.id, .baseline, .metric.page]')" '["EXP-1",100,"https://x/"]'
+
+# --- create on a harness ticket with GA4 form events ---
+run create --hypothesis "Shorter form" --source ga4 --measure events --event generate_lead --channel all --config /c.json --tkt TKT-40 >/dev/null
+check "create ga4: body" "$(last '.body | tostring')" '{"hypothesis":"Shorter form","metric":{"source":"ga4","measure":"events","config":"/c.json","event":"generate_lead","channel":"all"},"ticket":{"kind":"harness","id":"TKT-40"}}'
+
+# --- create from JSON passes the body through ---
+run '{"action":"create","hypothesis":"J","metric":{"source":"gsc","measure":"ctr","config":"/c.json"}}' >/dev/null
+check "create json: body" "$(last '.body | tostring')" '{"hypothesis":"J","metric":{"source":"gsc","measure":"ctr","config":"/c.json"}}'
+
+# --- missing params / a ticket without its project ---
+check "create: missing" "$(run_err create --hypothesis h --source gsc --measure clicks | grep -c 'config')" "1"
+check "create: ticket w/o project" "$(run_err create --hypothesis h --source gsc --measure clicks --config /c --ticket T-1 | grep -c 'needs --project')" "1"
+
+# --- ship / show / list / cancel ---
+run ship --id EXP-1 --shipped-at 2026-10-01T10:00:00Z >/dev/null
+check "ship: path" "$(last .path)" "/api/experiments/EXP-1/ship"
+check "ship: body" "$(last '.body | tostring')" '{"shippedAt":"2026-10-01T10:00:00Z"}'
+OUT=$(run show --id EXP-1)
+check "show: timeline" "$(printf '%s' "$OUT" | jq -c '.experiment.timeline | map(.event)')" '["created"]'
+OUT=$(run list --status done --ticket TKT-40)
+check "list: path" "$(last .path)" "/api/experiments?status=done&ticket=TKT-40"
+check "list: rows" "$(printf '%s' "$OUT" | jq -c '[.experiments[] | [.id, .verdict]]')" '[["EXP-1",null],["EXP-2","worked"]]'
+run cancel --id EXP-1 --reason dup >/dev/null
+check "cancel: body" "$(last '.body | tostring')" '{"reason":"dup"}'
+
+# --- measure refused before it is due: the error reaches the agent ---
+check "measure: not due" "$(run_err measure --id EXP-1 | grep -c 'not due')" "1"
+
+# --- unknown action / option ---
+check "unknown action" "$(run_err frobnicate | grep -c 'Unknown action')" "1"
+check "unknown option" "$(run_err list --nope | grep -c 'Unknown option')" "1"
+
+echo "experiment-card: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

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

package/config/skills/agent/core/report-status/execute.sh

@@ -9,7 +9,12 @@ print_usage() {
   cat <<'EOF_USAGE'
 Usage:
   # CLI flags (preferred — avoids shell escaping issues)
-  bash execute.sh --session dev-1 --status done --summary "Fixed the bug" --project /path/to/project
+  bash execute.sh --session dev-1 --status done --summary "Fixed the bug" --project /path/to/project \
+    --artifact src/fix.ts --command "npm test" --exit-code 0 --output-tail "42 passed"
+
+  # Could not finish: done with a blocked step is recorded as BLOCKED, not done
+  bash execute.sh --session dev-1 --status done --summary "Fix written, tests blocked" \
+    --blocked-step "npm test" --blocked-reason "test DB unreachable"
 
   # Summary from stdin (for multi-line or special characters)
   echo "Fixed the bug — it's working" | bash execute.sh --session dev-1 --status done --project /path
@@ -37,6 +42,18 @@ Options:
   --progress        Progress percentage (0-100, for structured format)
   --structured      Use structured StatusReport format (true/false)
   --json     | -j   Raw JSON payload (same as legacy)
+
+Evidence (status done — #873: "done" needs evidence):
+  --artifact <path>        A file the work produced (absolute, relative to the
+                           project/worktree, or an https URL). Must exist. Repeatable.
+  --command <cmd>          A command you ran. Follow it with --exit-code (required)
+  --exit-code <n>          and optionally --output-tail. Repeatable as a group.
+  --output-tail <text>     Last lines of that command's output.
+  --blocked-step <step>    You could not finish: the step that failed ...
+  --blocked-reason <why>   ... and why. The WorkItem is recorded as BLOCKED, not done.
+  --evidence <json>        Raw evidence array, e.g. '[{"type":"artifact","path":"/abs/f"}]'
+  A non-zero --exit-code or a missing artifact is rejected by the server. Without
+  any evidence, done is accepted this release with a warning; next release it is refused.
   --help     | -h   Show this help
 EOF_USAGE
 }
@@ -52,6 +69,28 @@ TASK_ID=""
 WORK_ITEM_ID=""
 PROGRESS=""
 STRUCTURED="false"
+# Evidence entries built from flags (#873), as a JSON array.
+FLAG_EVIDENCE='[]'
+BLOCKED_STEP=""
+BLOCKED_REASON=""
+EVIDENCE_ARG=""
+
+# add_evidence <jq-object-expression> [jq --arg pairs...]
+# Appends one entry to FLAG_EVIDENCE.
+add_evidence() {
+  local expr="$1"; shift
+  FLAG_EVIDENCE=$(printf '%s' "$FLAG_EVIDENCE" | jq -c "$@" ". + [${expr}]")
+}
+
+# set_last_command_field <field> <jq value expression> [jq --arg/--argjson pairs...]
+# Sets a field on the most recent --command entry; refuses when there is none.
+set_last_command_field() {
+  local field="$1" valexpr="$2" flag="$3"; shift 3
+  if [ "$(printf '%s' "$FLAG_EVIDENCE" | jq -r 'if length > 0 and .[-1].type == "command" then "yes" else "no" end')" != "yes" ]; then
+    error_exit "${flag} must follow --command <cmd>"
+  fi
+  FLAG_EVIDENCE=$(printf '%s' "$FLAG_EVIDENCE" | jq -c "$@" ".[-1].${field} = ${valexpr}")
+}
 
 # Detect legacy JSON argument as the first parameter
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
@@ -109,6 +148,35 @@ while [[ $# -gt 0 ]]; do
       INPUT_JSON="$2"
       shift 2
       ;;
+    --artifact)
+      add_evidence '{type: "artifact", path: $p}' --arg p "$2"
+      shift 2
+      ;;
+    --command)
+      add_evidence '{type: "command", command: $c}' --arg c "$2"
+      shift 2
+      ;;
+    --exit-code)
+      [[ "$2" =~ ^-?[0-9]+$ ]] || error_exit "--exit-code must be an integer (got \"$2\")"
+      set_last_command_field exitCode '($n | tonumber)' --exit-code --arg n "$2"
+      shift 2
+      ;;
+    --output-tail)
+      set_last_command_field outputTail '$t' --output-tail --arg t "$2"
+      shift 2
+      ;;
+    --blocked-step)
+      BLOCKED_STEP="$2"
+      shift 2
+      ;;
+    --blocked-reason)
+      BLOCKED_REASON="$2"
+      shift 2
+      ;;
+    --evidence)
+      EVIDENCE_ARG="$2"
+      shift 2
+      ;;
     --help|-h)
       print_usage
       exit 0
@@ -152,6 +220,7 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$AGENT_ROLE" ] && AGENT_ROLE=$(printf '%s' "$INPUT" | jq -r '.role // .agentRole // empty')
   ARTIFACTS=$(printf '%s' "$INPUT" | jq -c '.artifacts // empty')
   BLOCKERS=$(printf '%s' "$INPUT" | jq -c '.blockers // empty')
+  [ -z "$EVIDENCE_ARG" ] && EVIDENCE_ARG=$(printf '%s' "$INPUT" | jq -c '.evidence // empty')
   USE_STRUCTURED=$(printf '%s' "$INPUT" | jq -r '.structured // "false"')
   [ "$USE_STRUCTURED" = "true" ] && STRUCTURED="true"
 else
@@ -159,6 +228,24 @@ else
   BLOCKERS=""
 fi
 
+# Assemble the evidence block (#873): --evidence / JSON `evidence` first, then
+# the entries from --artifact / --command / --blocked-step flags.
+if [ -n "$EVIDENCE_ARG" ]; then
+  if ! printf '%s' "$EVIDENCE_ARG" | jq -e 'type == "array"' >/dev/null 2>&1; then
+    error_exit "evidence must be a JSON array, e.g. '[{\"type\":\"artifact\",\"path\":\"/abs/file\"}]'"
+  fi
+else
+  EVIDENCE_ARG='[]'
+fi
+if [ -n "$BLOCKED_STEP" ] || [ -n "$BLOCKED_REASON" ]; then
+  [ -n "$BLOCKED_STEP" ] && [ -n "$BLOCKED_REASON" ] || error_exit "--blocked-step and --blocked-reason go together: name the step that failed and why"
+  add_evidence '{type: "blocked", step: $s, reason: $r}' --arg s "$BLOCKED_STEP" --arg r "$BLOCKED_REASON"
+fi
+if [ "$(printf '%s' "$FLAG_EVIDENCE" | jq '[.[] | select(.type == "command" and (has("exitCode") | not))] | length')" != "0" ]; then
+  error_exit "every --command needs --exit-code <n> after it: the exit code is the evidence"
+fi
+EVIDENCE=$(jq -cn --argjson a "$EVIDENCE_ARG" --argjson b "$FLAG_EVIDENCE" '$a + $b')
+
 require_param "sessionName (--session)" "$SESSION_NAME"
 require_param "status (--status)" "$STATUS"
 require_param "summary (--summary)" "$SUMMARY"
@@ -297,18 +384,31 @@ if [ "$STATUS" = "done" ]; then
     # `completeItem`). Prior shape `{summary}` 400'd with
     # `agentId is required` + `summary required in body.result`,
     # forcing every worker into a direct-curl workaround.
+    #
+    # #873: the evidence block goes in result.evidence. Omitted when empty
+    # (the server then warns this release, refuses the next).
     COMPLETE_BODY=$(jq -n \
       --arg agentId "$SESSION_NAME" \
       --arg summary "$SUMMARY" \
-      '{agentId: $agentId, result: {summary: $summary}}')
+      --argjson evidence "$EVIDENCE" \
+      '{agentId: $agentId, result: ({summary: $summary} + (if ($evidence | length) > 0 then {evidence: $evidence} else {} end))}')
     # No `|| true`. A swallowed failure here is the inverse of the bug above:
     # report-status would announce success while the WorkItem stayed open, and
     # that is equally invisible. Report what actually happened either way.
     if COMPLETE_RESULT=$(api_call POST "/task-pool/complete/${TARGET_WI_ID}" "$COMPLETE_BODY" 2>&1); then
       # Echo the resolved id even on the happy path. Silent-but-correct is how
       # this class hides — the caller must be able to see WHICH item closed.
-      jq -n --arg id "$TARGET_WI_ID" --arg how "$WI_RESOLUTION" \
-        '{completedWorkItem: $id, resolvedBy: $how}' >&2
+      # A `blocked` evidence entry is recorded as blocked, not done (#873);
+      # a completion without evidence carries the server's warning.
+      COMPLETE_WARNING=$(printf '%s' "$COMPLETE_RESULT" | jq -rs '(map(select(type == "object" and has("success"))) | last // {}) | .warning // empty' 2>/dev/null || true)
+      COMPLETE_RECORDED=$(printf '%s' "$COMPLETE_RESULT" | jq -rs '(map(select(type == "object" and has("success"))) | last // {}) | .recordedAs // empty' 2>/dev/null || true)
+      if [ "$COMPLETE_RECORDED" = "blocked" ]; then
+        jq -n --arg id "$TARGET_WI_ID" --arg how "$WI_RESOLUTION" \
+          '{workItem: $id, markedAs: "blocked", resolvedBy: $how, note: "blocked evidence: recorded as blocked, not done"}' >&2
+      else
+        jq -n --arg id "$TARGET_WI_ID" --arg how "$WI_RESOLUTION" --arg w "$COMPLETE_WARNING" \
+          '{completedWorkItem: $id, resolvedBy: $how} + (if $w != "" then {warning: $w} else {} end)' >&2
+      fi
     else
       jq -n --arg id "$TARGET_WI_ID" --arg err "$COMPLETE_RESULT" \
         '{warning: "status reported, but completing the WorkItem FAILED — it is still open", workItemId: $id, error: $err}' >&2

package/config/skills/agent/core/todo-add/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: To Do Add
-description: Add a task to one of the owner's Microsoft To Do lists — title, optional due date, note and importance (via the Microsoft grant held by Crewly Cloud).
-version: 1.0.0
+description: Add a task to one of the owner's Microsoft To Do lists — title, optional due date, note, importance and steps (checklist items) (via the Microsoft grant held by Crewly Cloud).
+version: 1.1.0
 category: productivity
 skillType: claude-skill
 assignableRoles:
@@ -18,6 +18,7 @@ triggers:
   - add a microsoft to do task
   - remind me in to do
   - create an outlook task
+  - add a task with steps
 tags:
   - microsoft
   - todo
@@ -35,8 +36,13 @@ execution:
 ```bash
 bash execute.sh --title "Buy milk"                     # default list ("Tasks")
 bash execute.sh --list Work --title "Send deck to Ann" --due 2026-10-01 --importance high --note "v3 is in Drive"
+bash execute.sh --list Groceries --title "Costco" --steps "Eggs,Milk,Bread"   # ONE task with three steps
 ```
 
+When the owner asks for items as **steps of one task** (a shopping run, a
+packing list), use `--steps` — do not put them in the note, and do not make
+one task per item unless he asked for separate tasks.
+
 | Flag | Meaning |
 |---|---|
 | `--title` | Task title (required) |
@@ -44,13 +50,21 @@ bash execute.sh --list Work --title "Send deck to Ann" --due 2026-10-01 --import
 | `--due` | Due date `YYYY-MM-DD` |
 | `--note` | Note shown under the task |
 | `--importance` | `low` \| `normal` \| `high` |
+| `--steps` | Comma-separated steps (checklist items), in order |
+| `--step` | One step; repeat it for more (for a step that contains a comma) |
 
 ## Output
 
 ```json
 {"success":true,"list":"Work","task":{"id":"AAMk…","title":"Send deck to Ann","status":"notStarted","importance":"high","due":"2026-10-01","note":"v3 is in Drive"}}
+{"success":true,"list":"Groceries","task":{"id":"AAMk…","title":"Costco","status":"notStarted","steps":[{"id":"…","title":"Eggs","checked":false},{"id":"…","title":"Milk","checked":false}]}}
 ```
 
+Steps are created after the task. If one fails, the task still exists and
+the answer lists it in `failedSteps` (`[{"step":"Milk","error":"…"}]`):
+add it with todo-update `--add-steps` — do **not** run todo-add again, that
+would make a second task.
+
 A list that does not exist is not created — make it with todo-lists
 `--create` first.
 

package/config/skills/agent/core/todo-add/execute.sh

@@ -7,6 +7,7 @@
 # Usage:
 #   bash execute.sh --title "Buy milk"                                  # default list
 #   bash execute.sh --list Work --title "Send deck to Ann" --due 2026-10-01 --importance high --note "v3 in Drive"
+#   bash execute.sh --list Groceries --title "Costco" --steps "Eggs,Milk,Bread"     # one task, three steps
 #   bash execute.sh '{"list":"Groceries","title":"Eggs"}'
 # =============================================================================
 set -euo pipefail
@@ -18,7 +19,8 @@ print_usage() {
 Usage:
   bash execute.sh --title "Buy milk"                                  # default list
   bash execute.sh --list Work --title "Send deck to Ann" --due 2026-10-01 --importance high --note "v3 in Drive"
-  bash execute.sh '{"list":"Groceries","title":"Eggs"}'
+  bash execute.sh --list Groceries --title "Costco" --steps "Eggs,Milk,Bread"     # one task, three steps
+  bash execute.sh '{"list":"Groceries","title":"Costco","steps":["Eggs","Milk"]}'
 
 Options:
   --title, -t    Task title (required)
@@ -26,6 +28,8 @@ Options:
   --due          Due date, YYYY-MM-DD
   --note         Note text shown under the task
   --importance   low | normal | high
+  --steps        Comma-separated steps (checklist items) to create on the task
+  --step         One step; repeat for more (use when a step contains a comma)
   --help | -h    Show this help
 EOF_USAGE
 }
@@ -38,6 +42,12 @@ fail_from() {
 
 uri() { jq -rn --arg v "$1" '$v|@uri'; }
 
+# Append step titles to a JSON array: $1 = array, $2 = text, $3 = "split" to
+# split the text on commas. Titles are trimmed; empty ones are dropped.
+add_steps() {
+  jq -c --arg v "$2" --arg mode "${3:-}" '. + (if $mode == "split" then ($v | split(",")) else [$v] end | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0)))' <<<"$1"
+}
+
 # api_call may print a one-line warning to stderr (no CREWLY_SESSION_NAME);
 # the backend answer is always the last line. On failure print the mapped
 # failure JSON (fail_from) and return 1.
@@ -52,7 +62,7 @@ if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
   INPUT_JSON="$1"
   shift || true
 fi
-TITLE=""; LIST=""; DUE=""; NOTE=""; IMPORTANCE=""
+TITLE=""; LIST=""; DUE=""; NOTE=""; IMPORTANCE=""; STEPS='[]'
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --title|-t)   [ $# -ge 2 ] || error_exit "--title requires a value";      TITLE="$2";      shift 2 ;;
@@ -60,6 +70,8 @@ while [[ $# -gt 0 ]]; do
     --due)        [ $# -ge 2 ] || error_exit "--due requires a value";        DUE="$2";        shift 2 ;;
     --note)       [ $# -ge 2 ] || error_exit "--note requires a value";       NOTE="$2";       shift 2 ;;
     --importance) [ $# -ge 2 ] || error_exit "--importance requires a value"; IMPORTANCE="$2"; shift 2 ;;
+    --steps)      [ $# -ge 2 ] || error_exit "--steps requires a value";      STEPS=$(add_steps "$STEPS" "$2" split); shift 2 ;;
+    --step)       [ $# -ge 2 ] || error_exit "--step requires a value";       STEPS=$(add_steps "$STEPS" "$2");       shift 2 ;;
     --help|-h)    print_usage; exit 0 ;;
     *) error_exit "Unknown option: $1" ;;
   esac
@@ -71,14 +83,18 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$DUE" ]        && DUE=$(printf '%s' "$INPUT" | jq -r '.due // empty')
   [ -z "$NOTE" ]       && NOTE=$(printf '%s' "$INPUT" | jq -r '.note // empty')
   [ -z "$IMPORTANCE" ] && IMPORTANCE=$(printf '%s' "$INPUT" | jq -r '.importance // empty')
+  if [ "$STEPS" = '[]' ]; then
+    STEPS=$(printf '%s' "$INPUT" | jq -c '.steps // [] | if type == "string" then split(",") else map(tostring) end | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))')
+  fi
 fi
 [ -n "$TITLE" ] || error_exit "--title is required"
 if [ -n "$DUE" ] && ! [[ "$DUE" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then error_exit "--due must look like 2026-10-01"; fi
-BODY=$(jq -cn --arg title "$TITLE" --arg list "$LIST" --arg due "$DUE" --arg note "$NOTE" --arg imp "$IMPORTANCE" \
+BODY=$(jq -cn --arg title "$TITLE" --arg list "$LIST" --arg due "$DUE" --arg note "$NOTE" --arg imp "$IMPORTANCE" --argjson steps "$STEPS" \
   '{title: $title}
       + (if $list != "" then {list: $list} else {} end)
       + (if $due != "" then {due: $due} else {} end)
       + (if $note != "" then {note: $note} else {} end)
-      + (if $imp != "" then {importance: $imp} else {} end)')
+      + (if $imp != "" then {importance: $imp} else {} end)
+      + (if ($steps | length) > 0 then {steps: $steps} else {} end)')
 RESPONSE=$(call POST "/microsoft-todo/tasks" "$BODY") || { printf '%s\n' "$RESPONSE"; exit 1; }
-printf '%s' "$RESPONSE" | jq -c '{success: true, list: .data.list.name, task: .data.task}'
+printf '%s' "$RESPONSE" | jq -c '{success: true, list: .data.list.name, task: .data.task} + (if .data.failedSteps then {failedSteps: .data.failedSteps} else {} end)'