crewly 1.13.0 → 1.13.1

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.1.0
+version: 1.2.0
 category: task-management
 skillType: claude-skill
 assignableRoles:
@@ -43,24 +43,56 @@ Mark a task as complete with a summary of the work done. If the task has an outp
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `absoluteTaskPath` | Yes | Absolute filesystem path to the task file |
+| `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 |
+| `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` | No | Set to `true` to skip quality gate checks |
+| ~~`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. |
+
+### Which WorkItem gets completed
+
+Resolution order:
+
+1. `workItemId`, if you pass it — always wins.
+2. Otherwise, a lookup of the WorkItem currently `running` against your
+   `sessionName` (`GET /api/task-pool/items?status=running&target=<session>`).
+3. If neither resolves, the skill exits non-zero with an error naming the
+   session it searched. It never reports success without completing something.
+
+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.
 
 ## Example
 
 ```bash
-bash config/skills/agent/complete-task/execute.sh '{"absoluteTaskPath":"/projects/app/tasks/implement-login.md","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"}'
+```
+
+### Letting the skill resolve your running WorkItem
+
+```bash
+bash config/skills/agent/core/complete-task/execute.sh '{"sessionName":"dev-1","summary":"Implemented login form with validation and tests"}'
 ```
 
 ### With structured output
 
 ```bash
-bash config/skills/agent/complete-task/execute.sh '{"absoluteTaskPath":"/projects/app/tasks/implement-login.md","sessionName":"dev-1","summary":"Implemented login","output":{"summary":"Login form with validation","filesChanged":["src/login.tsx","src/login.test.tsx"],"testsAdded":2}}'
+bash config/skills/agent/core/complete-task/execute.sh '{"workItemId":"wi-abc123","sessionName":"dev-1","summary":"Implemented login","output":{"summary":"Login form with validation","filesChanged":["src/login.tsx","src/login.test.tsx"],"testsAdded":2}}'
 ```
 
+Note: a `summary` key inside `output` overrides the top-level `summary`.
+
+### Legacy V1 caller (still supported)
+
+```bash
+bash config/skills/agent/core/complete-task/execute.sh '{"absoluteTaskPath":"/projects/app/.crewly/tasks/in_progress/implement-login.md","sessionName":"dev-1","summary":"Implemented login"}'
+```
+
+`absoluteTaskPath` is carried for logging context only; the WorkItem is still
+resolved by step 2 above.
+
 ## Output Schema
 
 If the task markdown contains an `## Output Schema` section with a JSON Schema definition, your `output` object must validate against that schema. If validation fails, the response will include the errors and you can retry (up to 2 retries). After max retries, the task will be moved to blocked/.

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

@@ -5,14 +5,42 @@ 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 '{\"absoluteTaskPath\":\"/path/to/task\",\"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\",\"output\":{\"key\":\"value\"}}'"
 
+# `workItemId` is the V3 identifier and the ONLY input that drives the API
+# call (see the resolution block further down). `absoluteTaskPath` is the
+# legacy V1 input: still ACCEPTED so pre-existing callers keep working, but
+# it neither selects the WorkItem nor is required.
+#
+# It used to be `require_param`'d here, contradicting this skill's own
+# resolution logic: passing `workItemId` alone — the documented V3 flow —
+# returned `{"error":"Missing required parameter: absoluteTaskPath"}`, so
+# every agent completing a V3 WorkItem had to bypass the skill and curl
+# /api/task-pool/complete by hand. Same silent-friction class as the
+# create-task `{workItem: ...}` wrapper: the skill rejected a request that
+# was, by its own contract, correct.
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
 ABSOLUTE_TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
 SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
 SUMMARY=$(printf '%s' "$INPUT" | jq -r '.summary // empty')
+# `skipGates` is REJECTED, not ignored.
+#
+# It was previously parsed here and forwarded in the request body. Nothing ever
+# read it: `completeItem` destructures only `{agentId, tokenUsage, result}`
+# (task-pool.controller.ts), and `POST /task-pool/complete/:id` runs no quality
+# gates at all — gates live behind `POST /quality-gates/check`, reached via the
+# `check-quality-gates` skill. So the field promised to skip something this
+# endpoint never runs.
+#
+# Accepting-and-ignoring is the worst of the three dispositions: the caller
+# believes gates were skipped, the belief is unfalsifiable, and nothing ever
+# fails. Honouring it is incoherent (there is nothing here to skip). So it
+# fails loudly instead. Safe to hard-error: no caller in the repo passes it.
 SKIP_GATES=$(printf '%s' "$INPUT" | jq -r '.skipGates // empty')
+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')
-require_param "absoluteTaskPath" "$ABSOLUTE_TASK_PATH"
 require_param "sessionName" "$SESSION_NAME"
 require_param "summary" "$SUMMARY"
 
@@ -48,7 +76,7 @@ fi
 
 # #186: If the task file was already moved from in_progress/ to done/ by
 # report-status (via complete-by-session), succeed silently instead of failing.
-if echo "$ABSOLUTE_TASK_PATH" | grep -q '/in_progress/'; then
+if [ -n "$ABSOLUTE_TASK_PATH" ] && echo "$ABSOLUTE_TASK_PATH" | grep -q '/in_progress/'; then
   DONE_PATH="${ABSOLUTE_TASK_PATH/\/in_progress\///done/}"
   if [ -f "$DONE_PATH" ] && [ ! -f "$ABSOLUTE_TASK_PATH" ]; then
     echo '{"success":true,"message":"Task already completed (moved to done by report-status)"}'
@@ -69,15 +97,20 @@ fi
 # The legacy `absoluteTaskPath` input is still accepted but no longer
 # drives the API call — it's only used for logging context. Callers
 # should switch to passing `workItemId`.
-WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
+#
+# WORK_ITEM_ID was read from the input up top alongside the other params,
+# so the identifier is known before any of the legacy path handling runs.
 if [ -z "$WORK_ITEM_ID" ]; then
   POOL_RESP=$(api_call GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
   WORK_ITEM_ID=$(echo "$POOL_RESP" | jq -r '.workItems[0].id // .data[0].id // empty' 2>/dev/null || true)
 fi
 
+# Neither an explicit `workItemId` nor the pool lookup produced a target.
+# Fail loudly and name both accepted identifiers — exiting 0 here would let
+# a worker believe its task was closed while the pool still shows it
+# running, which is the silent no-op this skill must never perform.
 if [ -z "$WORK_ITEM_ID" ]; then
-  echo '{"error":"Could not resolve a running WorkItem for this session — pass `workItemId` explicitly."}' >&2
-  exit 1
+  error_exit "Could not resolve a WorkItem to complete: no 'workItemId' was passed and no running WorkItem is assigned to session '${SESSION_NAME}'. Pass 'workItemId' explicitly — find it with GET /api/task-pool/items?status=running&target=${SESSION_NAME}. Note: 'absoluteTaskPath' is a legacy input and does NOT identify a WorkItem."
 fi
 
 # Hygiene #4: emit canonical body shape `{agentId, result:{summary, ...output}}`
@@ -99,7 +132,6 @@ fi
 BODY=$(jq -n \
   --arg agentId "$SESSION_NAME" \
   --arg summary "$SUMMARY" \
-  --arg skipGates "$SKIP_GATES" \
   --argjson output "${OUTPUT_JSON:-null}" \
   '{
     agentId: $agentId,
@@ -107,8 +139,7 @@ BODY=$(jq -n \
               + (if $output != null and ($output | type) == "object"
                  then $output
                  else {} end))
-  }
-   + (if $skipGates == "true" then {skipGates: true} else {} end)')
+  }')
 
 api_call POST "/task-pool/complete/${WORK_ITEM_ID}" "$BODY"
 

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

@@ -0,0 +1,213 @@
+#!/bin/bash
+# =============================================================================
+# Tests for complete-task skill
+#
+# Guards how this skill resolves WHICH WorkItem to complete.
+#
+# `absoluteTaskPath` used to be `require_param`'d, which contradicted the
+# skill's own resolution logic: the V3 path selects the WorkItem from
+# `workItemId` (or a pool lookup) and treats `absoluteTaskPath` as legacy
+# logging context only. Passing `workItemId` alone therefore returned
+# `{"error":"Missing required parameter: absoluteTaskPath"}` and agents had
+# to bypass the skill and curl /api/task-pool/complete by hand.
+#
+# These tests fail if that requirement is reintroduced, if the legacy
+# `absoluteTaskPath` path stops working, or if resolving nothing degrades
+# into a silent no-op instead of a clear error.
+#
+# `curl` is stubbed on PATH, so every case runs offline and deterministically
+# while still proving the real HTTP request the skill would have issued.
+# =============================================================================
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0
+FAIL=0
+ERRORS=""
+
+assert_contains() {
+  local test_name="$1" needle="$2" haystack="$3"
+  if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  else
+    FAIL=$((FAIL + 1))
+    ERRORS="${ERRORS}\n  ✗ ${test_name}\n    expected to contain: ${needle}\n    actual: ${haystack}"
+    echo "  ✗ ${test_name}"
+    echo "    expected to contain: ${needle}"
+  fi
+}
+
+assert_not_contains() {
+  local test_name="$1" needle="$2" haystack="$3"
+  if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    FAIL=$((FAIL + 1))
+    ERRORS="${ERRORS}\n  ✗ ${test_name}\n    expected NOT to contain: ${needle}\n    actual: ${haystack}"
+    echo "  ✗ ${test_name}"
+    echo "    expected NOT to contain: ${needle}"
+  else
+    PASS=$((PASS + 1))
+    echo "  ✓ ${test_name}"
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# curl stub
+#
+# api_call() shells out to bare `curl`, so shadowing it on PATH intercepts
+# every request without touching the skill. The stub records `METHOD URL` and
+# the request body, then emits `<body>\n<http_code>` — the exact shape
+# api_call parses because of its `-w '\n%{http_code}'`.
+#
+# GET /task-pool/items returns one WorkItem so the legacy pool-lookup path
+# resolves, or an empty list when STUB_POOL_EMPTY=1, which is how the
+# "resolves nothing" case is exercised.
+# ---------------------------------------------------------------------------
+STUB_DIR="$(mktemp -d)"
+cat > "$STUB_DIR/curl" << 'STUB_EOF'
+#!/bin/bash
+METHOD="GET"; BODY=""; URL=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -X) METHOD="$2"; shift 2 ;;
+    -d) BODY="$2";   shift 2 ;;
+    -H) shift 2 ;;
+    -w) shift 2 ;;
+    -s) shift ;;
+    *)  URL="$1";    shift ;;
+  esac
+done
+echo "${METHOD} ${URL}" >> "$CURL_LOG"
+# Flatten to one line per request: jq -n pretty-prints, and the assertions
+# below need one parseable JSON document per log line.
+printf '%s\n' "$(printf '%s' "$BODY" | tr '\n' ' ')" >> "$CURL_BODY_LOG"
+
+if [ "$METHOD" = "GET" ] && printf '%s' "$URL" | grep -q '/task-pool/items'; then
+  if [ "${STUB_POOL_EMPTY:-0}" = "1" ]; then
+    echo '{"success":true,"data":[],"count":0}'
+  else
+    echo '{"success":true,"data":[{"id":"wi-from-pool"}],"count":1}'
+  fi
+  echo "200"
+  exit 0
+fi
+
+echo '{"success":true,"stub":true}'
+echo "200"
+STUB_EOF
+chmod +x "$STUB_DIR/curl"
+
+export CREWLY_API_URL="http://stub.invalid"
+export PATH="$STUB_DIR:$PATH"
+
+# Runs execute.sh with a fresh request log. Sets OUT (stdout+stderr),
+# REQUESTS (one "METHOD URL" per line) and BODIES (request bodies).
+run_skill() {
+  CURL_LOG="$(mktemp)"; export CURL_LOG
+  CURL_BODY_LOG="$(mktemp)"; export CURL_BODY_LOG
+  OUT="$(bash "$SCRIPT_DIR/execute.sh" "$1" 2>&1)" || true
+  REQUESTS="$(cat "$CURL_LOG")"
+  BODIES="$(cat "$CURL_BODY_LOG")"
+  rm -f "$CURL_LOG" "$CURL_BODY_LOG"
+}
+
+echo "=== complete-task tests ==="
+
+echo ""
+echo "--- workItemId alone is sufficient (the reported bug) ---"
+
+run_skill '{"workItemId":"wi-explicit","sessionName":"dev-1","summary":"Implemented feature X"}'
+assert_not_contains "workItemId alone does NOT demand absoluteTaskPath" \
+  "Missing required parameter: absoluteTaskPath" "$OUT"
+assert_contains "workItemId alone reaches POST /task-pool/complete/<id>" \
+  "POST http://stub.invalid/api/task-pool/complete/wi-explicit" "$REQUESTS"
+assert_not_contains "workItemId alone skips the pool lookup entirely" \
+  "/task-pool/items" "$REQUESTS"
+
+echo ""
+echo "--- Canonical completion body ---"
+
+# The endpoint reads `result.summary`; a top-level `summary` is ignored and
+# 400s (task-pool.controller.ts `completeItem`).
+# Tolerate no-match so a regression elsewhere reports as a failed assertion
+# rather than killing the run under `set -e` / `pipefail`.
+COMPLETE_BODY="$(printf '%s' "$BODIES" | grep 'agentId' | head -1 || true)"
+assert_contains "body carries agentId" '"agentId": "dev-1"' "$COMPLETE_BODY"
+assert_contains "body nests summary under result" '"summary": "Implemented feature X"' "$COMPLETE_BODY"
+RESULT_SUMMARY="$(printf '%s' "$COMPLETE_BODY" | jq -r '.result.summary // "MISSING"' 2>/dev/null || echo "MISSING")"
+assert_contains "result.summary is populated" "Implemented feature X" "$RESULT_SUMMARY"
+
+echo ""
+echo "--- Legacy absoluteTaskPath callers keep working (no regression) ---"
+
+run_skill '{"absoluteTaskPath":"/proj/.crewly/tasks/in_progress/t.md","sessionName":"dev-2","summary":"Legacy caller"}'
+assert_contains "legacy-only call falls back to the pool lookup" \
+  "GET http://stub.invalid/api/task-pool/items" "$REQUESTS"
+assert_contains "legacy-only call completes the resolved WorkItem" \
+  "POST http://stub.invalid/api/task-pool/complete/wi-from-pool" "$REQUESTS"
+
+run_skill '{"absoluteTaskPath":"/proj/.crewly/tasks/in_progress/t.md","workItemId":"wi-both","sessionName":"dev-2","summary":"Both identifiers"}'
+assert_contains "explicit workItemId wins when both are supplied" \
+  "POST http://stub.invalid/api/task-pool/complete/wi-both" "$REQUESTS"
+
+echo ""
+echo "--- Neither identifier resolves: clear error, not a silent no-op ---"
+
+STUB_POOL_EMPTY=1 run_skill '{"sessionName":"dev-3","summary":"Nothing to complete"}'
+assert_contains "unresolvable completion reports an error" '"error"' "$OUT"
+assert_contains "error names the workItemId parameter to pass" "workItemId" "$OUT"
+assert_contains "error names the session it searched" "dev-3" "$OUT"
+assert_not_contains "unresolvable completion does NOT POST a completion" \
+  "/task-pool/complete/" "$REQUESTS"
+
+CURL_LOG="$(mktemp)"; export CURL_LOG
+CURL_BODY_LOG="$(mktemp)"; export CURL_BODY_LOG
+if STUB_POOL_EMPTY=1 bash "$SCRIPT_DIR/execute.sh" \
+     '{"sessionName":"dev-3","summary":"Nothing to complete"}' > /dev/null 2>&1; then
+  FAIL=$((FAIL + 1))
+  echo "  ✗ unresolvable completion exits non-zero"
+  ERRORS="${ERRORS}\n  ✗ unresolvable completion exits non-zero (exited 0)"
+else
+  PASS=$((PASS + 1))
+  echo "  ✓ unresolvable completion exits non-zero"
+fi
+rm -f "$CURL_LOG" "$CURL_BODY_LOG"
+
+echo ""
+echo "--- Remaining required parameters still enforced ---"
+
+run_skill '{"workItemId":"wi-1","summary":"no session"}'
+assert_contains "Missing sessionName returns error" "sessionName" "$OUT"
+
+run_skill '{"workItemId":"wi-1","sessionName":"dev-1"}'
+assert_contains "Missing summary returns error" "summary" "$OUT"
+
+OUT="$(bash "$SCRIPT_DIR/execute.sh" '' 2>&1)" || true
+assert_contains "Empty input returns usage error" "Usage" "$OUT"
+assert_contains "Usage example leads with workItemId" "workItemId" "$OUT"
+
+echo ""
+echo "--- Source-level guards ---"
+
+SRC="$(cat "$SCRIPT_DIR/execute.sh")"
+
+assert_not_contains "absoluteTaskPath is NOT a required parameter" \
+  'require_param "absoluteTaskPath"' "$SRC"
+assert_contains "absoluteTaskPath is still parsed (legacy callers accepted)" \
+  "jq -r '.absoluteTaskPath // empty'" "$SRC"
+assert_contains "sessionName is still required" 'require_param "sessionName"' "$SRC"
+assert_contains "summary is still required" 'require_param "summary"' "$SRC"
+assert_contains "unresolved WorkItem exits via error_exit" \
+  'error_exit "Could not resolve a WorkItem to complete' "$SRC"
+assert_contains "legacy in_progress shortcut only runs on the legacy path" \
+  'if [ -n "$ABSOLUTE_TASK_PATH" ] && echo "$ABSOLUTE_TASK_PATH" | grep -q' "$SRC"
+
+# Cleanup
+rm -rf "$STUB_DIR"
+
+echo ""
+echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
+if [ $FAIL -gt 0 ]; then
+  echo -e "\nFailures:${ERRORS}"
+  exit 1
+fi

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

@@ -49,6 +49,39 @@ Create a new task via the `/api/task-management/create` endpoint. This allows te
 | `--milestone` / `-m` | `milestone` | No | Milestone/sprint name (default: `delegated`) |
 | `--session` / `-s` | `sessionName` | No | Session to assign the task to (open if omitted) |
 | `--output-schema` | `outputSchema` | No | JSON object defining expected output schema |
+| `--owner` | `owner` | No | Responsible role: `orchestrator`, `team_lead`, `agent` (default), `system`. A role, not a session name — use `--session` for the session |
+| `--description` / `-d` | `description` | No | Short summary of the task |
+| `--brief` | `briefMarkdown` | No | Long-form brief in markdown. Inline text, or `@/path/to/file.md`. Max 16384 bytes |
+
+### Always attach a brief
+
+A task's title is not a contract. Every delegated task should carry **Goal**, **Expected Outcome**, and **Eval Criteria**
+— the receiving agent is expected to ask for them if they are missing, and a task without them tends to drift or come
+back unsatisfiable.
+
+Put them in `--brief`. Prefer the `@file` form: a real brief is usually too long, and too full of quotes and backticks,
+to survive being passed as a shell argument.
+
+```bash
+cat > /tmp/brief.md <<'EOF'
+## GOAL
+What the user ultimately wants.
+
+## EXPECTED OUTCOME
+What must be true when this is done.
+
+## EVAL CRITERIA
+1. Testable statement.
+2. Another one.
+EOF
+
+bash execute.sh --project-path /path/to/project --task "Implement login API" \
+  --description "Session-cookie auth for the web portal" \
+  --brief @/tmp/brief.md --session dev-max
+```
+
+An over-limit brief is **rejected, never truncated** — the error names the limit and your actual size, because what to
+cut is your call, not the tool's.
 
 ## Examples — CLI Flags (preferred)
 

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

@@ -26,6 +26,10 @@ Options:
   --milestone    | -m   Milestone/sprint name (default: delegated)
   --session      | -s   Session to assign the task to (optional; if omitted, task is open)
   --output-schema       JSON string defining expected output schema (optional)
+  --owner               Responsible role: orchestrator, team_lead, agent, system (default: agent)
+  --description  | -d   Short summary of the task (optional)
+  --brief               Long-form brief in markdown: inline text, or @/path/to/file.md
+                        Should carry Goal + Expected Outcome + Eval Criteria. Max 16384 bytes.
   --json         | -j   Raw JSON payload (same as legacy)
   --help         | -h   Show this help
 EOF_USAGE
@@ -38,6 +42,9 @@ PRIORITY=""
 MILESTONE=""
 SESSION_NAME=""
 OUTPUT_SCHEMA=""
+OWNER=""
+DESCRIPTION=""
+BRIEF=""
 
 # Detect legacy JSON argument
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
@@ -71,6 +78,18 @@ while [[ $# -gt 0 ]]; do
       OUTPUT_SCHEMA="$2"
       shift 2
       ;;
+    --owner)
+      OWNER="$2"
+      shift 2
+      ;;
+    --description|-d)
+      DESCRIPTION="$2"
+      shift 2
+      ;;
+    --brief)
+      BRIEF="$2"
+      shift 2
+      ;;
     --json|-j)
       INPUT_JSON="$2"
       shift 2
@@ -111,52 +130,92 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$MILESTONE" ] && MILESTONE=$(printf '%s' "$INPUT" | jq -r '.milestone // empty')
   [ -z "$SESSION_NAME" ] && SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
   [ -z "$OUTPUT_SCHEMA" ] && OUTPUT_SCHEMA=$(printf '%s' "$INPUT" | jq -c '.outputSchema // empty')
+  [ -z "$OWNER" ] && OWNER=$(printf '%s' "$INPUT" | jq -r '.owner // empty')
+  [ -z "$DESCRIPTION" ] && DESCRIPTION=$(printf '%s' "$INPUT" | jq -r '.description // empty')
+  [ -z "$BRIEF" ] && BRIEF=$(printf '%s' "$INPUT" | jq -r '.briefMarkdown // .brief // empty')
 fi
 
 # Apply defaults
 PRIORITY="${PRIORITY:-medium}"
 MILESTONE="${MILESTONE:-delegated}"
+OWNER="${OWNER:-agent}"
 
 require_param "projectPath (--project-path)" "$PROJECT_PATH"
 require_param "task (--task)" "$TASK"
 
-# Build a V3 WorkItem for the task-pool.
-# `addToPool` accepts the WorkItem directly (id auto-generated server-side
-# when omitted). `priority` is mapped to V3's numeric priority scale where
-# critical=1, high=2, medium=3, low=4 — lower number = higher priority.
-case "$PRIORITY" in
-  critical) PRIORITY_NUM=1 ;;
-  high)     PRIORITY_NUM=2 ;;
-  medium)   PRIORITY_NUM=3 ;;
-  low)      PRIORITY_NUM=4 ;;
-  *)        PRIORITY_NUM=3 ;;
-esac
+# `--brief @/path/to/file.md` reads the brief from a file. A real brief is
+# usually too long and too full of quotes/backticks to pass safely as a shell
+# argument, so the file form is the one callers should reach for.
+if [ -n "$BRIEF" ] && [ "${BRIEF:0:1}" = "@" ]; then
+  BRIEF_PATH="${BRIEF:1}"
+  [ -f "$BRIEF_PATH" ] || error_exit "brief file not found: ${BRIEF_PATH}"
+  BRIEF="$(cat "$BRIEF_PATH")"
+fi
 
-WI_ID="task-$(date +%s%N | cut -c1-13)-$$"
+# Enforce MAX_BRIEF_MARKDOWN_BYTES (16 * 1024) HERE rather than letting the
+# server reject it, so the caller gets the limit and their actual size instead
+# of a bare 400. Deliberately NOT truncated: silently shipping a half-brief is
+# the same class of bug this field was added to fix — trimming is the caller's
+# decision, not ours.
+if [ -n "$BRIEF" ]; then
+  BRIEF_BYTES=$(printf '%s' "$BRIEF" | wc -c | tr -d ' ')
+  if [ "$BRIEF_BYTES" -gt 16384 ]; then
+    error_exit "briefMarkdown is ${BRIEF_BYTES} bytes, over the 16384-byte limit (MAX_BRIEF_MARKDOWN_BYTES). Trim it, or attach the long form as a file and reference it from the brief. Not truncating automatically — what to cut is your call."
+  fi
+fi
+
+# Validate `owner` against the WorkItemOwner enum the endpoint accepts.
+# This is the field, not the session name — `owner` answers "which role is
+# responsible for execution", and `target` answers "which session runs it".
+# Sending a session name here fails validation with
+# "owner must be one of: orchestrator, team_lead, agent, system".
+case "$OWNER" in
+  orchestrator|team_lead|agent|system) ;;
+  *) error_exit "owner must be one of: orchestrator, team_lead, agent, system (got: '$OWNER'). This is a role, not a session name — use --session/target for the session." ;;
+esac
 
+# Build a minimal `CreateWorkItemInput` for `POST /task-pool/add`.
+#
+# The endpoint reads `req.body` DIRECTLY as the input — there is no
+# `{workItem: ...}` envelope. It accepts two shapes: this minimal input
+# (server fills id/status/createdAt/retryCount/...), or a legacy full
+# WorkItem carrying id AND status AND createdAt. We send the minimal shape,
+# matching `team-leader/delegate-task`.
+#
+# Deliberately NOT sent:
+#   - `id`     — this skill has no idempotency key worth preserving, so the
+#                server-generated uuid wins. (`CreateWorkItemInput.id` IS
+#                honoured when supplied; we simply have nothing stable to
+#                supply.)
+#   - `status` — derived server-side from dependsOn/scheduledAt.
+#   - empty `description`/`briefMarkdown` — omitted rather than sent as "",
+#                so a task filed without a brief stays a clean minimal WorkItem
+#   - top-level `priority` — NOT a WorkItem field; it is silently dropped by
+#                both body shapes. Priority travels in `metadata.priority`,
+#                which is what real pool items carry and what
+#                work-item-projection reads.
 WORK_ITEM=$(jq -n \
-  --arg id "$WI_ID" \
   --arg title "$TASK" \
   --arg target "$SESSION_NAME" \
-  --arg owner "${SESSION_NAME:-system}" \
+  --arg owner "$OWNER" \
   --arg projectPath "$PROJECT_PATH" \
   --arg milestone "$MILESTONE" \
-  --argjson priority "$PRIORITY_NUM" \
+  --arg priority "$PRIORITY" \
+  --arg description "$DESCRIPTION" \
+  --arg briefMarkdown "$BRIEF" \
   '{
-    id: $id,
     title: $title,
     type: "delegate",
     owner: $owner,
-    priority: $priority,
-    status: "queued",
     target: (if $target == "" then null else $target end),
-    metadata: { projectPath: $projectPath, milestone: $milestone }
-  } | with_entries(select(.value != null))')
+    metadata: { projectPath: $projectPath, milestone: $milestone, priority: $priority }
+  }
+  + (if $description != "" then {description: $description} else {} end)
+  + (if $briefMarkdown != "" then {briefMarkdown: $briefMarkdown} else {} end)
+  | with_entries(select(.value != null))')
 
 if [ -n "$OUTPUT_SCHEMA" ] && [ "$OUTPUT_SCHEMA" != "" ]; then
   WORK_ITEM=$(printf '%s' "$WORK_ITEM" | jq --argjson schema "$OUTPUT_SCHEMA" '.metadata += {outputSchema: $schema}')
 fi
 
-BODY=$(jq -n --argjson workItem "$WORK_ITEM" '{workItem: $workItem}')
-
-api_call POST "/task-pool/add" "$BODY"
+api_call POST "/task-pool/add" "$WORK_ITEM"

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

@@ -0,0 +1,46 @@
+#!/bin/bash
+# =============================================================================
+# NOT A SKILL — a signpost.
+#
+# `delegate-task` does not live here. It is a TEAM LEADER skill:
+#
+#     config/skills/team-leader/delegate-task/execute.sh
+#
+# This path exists because agents reach for it. Every other core skill lives at
+# config/skills/agent/core/<name>/execute.sh, so the pattern predicts a
+# delegate-task here, and project memory records at least one TL agent taking
+# that path and having to self-correct.
+#
+# It used to be a symlink — and a BROKEN one: it pointed at
+# ../../../../team-leader/delegate-task/execute.sh, which is one `../` too many
+# (four levels up from here is `config/`, not `config/skills/`). So it resolved
+# to config/team-leader/delegate-task/execute.sh, which does not exist.
+# `test -e` failed and running it printed "No such file or directory".
+#
+# That is the worst of the three states: `ls` showed a delegate-task directory
+# containing an execute.sh, so the path LOOKED real to anyone browsing, and
+# failed only on use.
+#
+# WHY A SIGNPOST RATHER THAN A REPAIRED SYMLINK
+#
+# Repairing the link would work, but it would create a SECOND working entry
+# point to one skill. Two paths to one implementation is the drift shape this
+# codebase keeps paying for — the hand-copied mock in the TL delegate-task
+# test, the template copies of norms. Anyone editing or testing delegate-task
+# would have to remember both. There are zero callers of this path, so there is
+# nothing to preserve by making it work.
+#
+# So: one canonical implementation, and a path that fails loudly and tells you
+# where to go. Same disposition as the `skipGates` rejection (#742) and the
+# `block-task` status pre-check (#747): reject, and name the remedy.
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REAL_SKILL="$(cd "${SCRIPT_DIR}/../../.." && pwd)/team-leader/delegate-task/execute.sh"
+
+cat >&2 <<EOF_MSG
+{"error":"delegate-task is a TEAM LEADER skill and does not live under agent/core. Use: ${REAL_SKILL}","correctPath":"config/skills/team-leader/delegate-task/execute.sh","calledPath":"config/skills/agent/core/delegate-task/execute.sh"}
+EOF_MSG
+
+exit 1

package/config/skills/agent/core/get-team-norms/SKILL.md

@@ -53,7 +53,7 @@ anything governance-related — delegating, escalating, deciding scope.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `trigger` | No | Filter to norms relevant to a moment (e.g. `"before_commit"`, `"before_delegate"`). Omit to read all. |
+| `trigger` | No | Filter to norms relevant to a moment (e.g. `"before_commit"`, `"delegation"`). Matched against the norm's `trigger:` list as whole tokens, case-insensitively — `"lead"` does NOT match a norm tagged `inbound_lead`. Pass several comma-separated to mean "any of these". Omit to read all. |
 | `teamId` | No | Team to read. Defaults to the team resolved from your `sessionName`. |
 | `sessionName` | No | Your session name, used to resolve the team when `teamId` is omitted. |