crewly 1.6.4 → 1.7.0

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

@@ -1,6 +1,10 @@
 #!/bin/bash
-# Create a new task via the task-management API.
-# Allows TLs and agents to autonomously decompose work into sub-tasks.
+# Create a new task as a V3 WorkItem in the task-pool.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. Replaces
+# the v1 `POST /task-management/create` endpoint, which wrote a `.md` file
+# to the project's `.crewly/tasks/` filesystem. The V3 task-pool's
+# `POST /task-pool/add` endpoint is now the sole way to create new tasks.
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../../_common/lib.sh"
@@ -116,19 +120,43 @@ MILESTONE="${MILESTONE:-delegated}"
 require_param "projectPath (--project-path)" "$PROJECT_PATH"
 require_param "task (--task)" "$TASK"
 
-# Build the request body
-BODY=$(jq -n \
+# 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
+
+WI_ID="task-$(date +%s%N | cut -c1-13)-$$"
+
+WORK_ITEM=$(jq -n \
+  --arg id "$WI_ID" \
+  --arg title "$TASK" \
+  --arg target "$SESSION_NAME" \
+  --arg owner "${SESSION_NAME:-system}" \
   --arg projectPath "$PROJECT_PATH" \
-  --arg task "$TASK" \
-  --arg priority "$PRIORITY" \
   --arg milestone "$MILESTONE" \
-  --arg sessionName "$SESSION_NAME" \
-  '{projectPath: $projectPath, task: $task, priority: $priority, milestone: $milestone} +
-   (if $sessionName != "" then {sessionName: $sessionName} else {} end)')
+  --argjson priority "$PRIORITY_NUM" \
+  '{
+    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))')
 
-# Attach outputSchema if provided
 if [ -n "$OUTPUT_SCHEMA" ] && [ "$OUTPUT_SCHEMA" != "" ]; then
-  BODY=$(printf '%s' "$BODY" | jq --argjson schema "$OUTPUT_SCHEMA" '. + {outputSchema: $schema}')
+  WORK_ITEM=$(printf '%s' "$WORK_ITEM" | jq --argjson schema "$OUTPUT_SCHEMA" '.metadata += {outputSchema: $schema}')
 fi
 
-api_call POST "/task-management/create" "$BODY"
+BODY=$(jq -n --argjson workItem "$WORK_ITEM" '{workItem: $workItem}')
+
+api_call POST "/task-pool/add" "$BODY"

package/config/skills/agent/core/get-my-active-work/SKILL.md

@@ -19,8 +19,10 @@ assignableRoles:
   - generalist
   - sales
   - support
+  # Canonical convention is hyphenated (`team-lead`); the underscore variant
+  # (`team_lead`) was a duplicate-key typo discovered during the 4-piece skill-mistake
+  # audit (post-PR #446 merge). Removing it to keep the role-name surface single-shape.
   - team-lead
-  - team_lead
   - orchestrator
 triggers:
   - get my active work

package/config/skills/agent/core/get-my-tasks/execute.sh

@@ -81,10 +81,12 @@ if [ -n "$INPUT_JSON" ]; then
 fi
 
 require_param "sessionName (--session)" "$SESSION_NAME"
-require_param "projectPath (--project)" "$PROJECT_PATH"
+# `projectPath` is no longer required for V3 — kept in the input shape
+# for backwards compat with callers who pass it.
 
-# URL-encode the session name and project path for query parameters
+# Per spec 2026-05-06-task-management-v1-deprecation.md, this skill now
+# queries the V3 task-pool. Returns all WorkItems targeted at this agent
+# session that are still in a non-terminal status. Callers wanting only
+# the running one can filter on `.workItems[] | select(.status=="running")`.
 ENCODED_SESSION=$(printf '%s' "$SESSION_NAME" | jq -sRr @uri)
-ENCODED_PROJECT=$(printf '%s' "$PROJECT_PATH" | jq -sRr @uri)
-
-api_call GET "/task-management/tasks?sessionName=${ENCODED_SESSION}&projectPath=${ENCODED_PROJECT}"
+api_call GET "/task-pool/items?target=${ENCODED_SESSION}"

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

@@ -30,12 +30,12 @@ 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 '{\"sessionName\":\"from-agent\",\"to\":\"target-session\",\"reason\":\"...\",\"progress\":\"...\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"sessionName\":\"from-agent\",\"to\":\"target-session\",\"workItemId\":\"abc-123\",\"reason\":\"...\",\"progress\":\"...\"}'"
 
 # --- Parse parameters ---
 SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
 TO=$(printf '%s' "$INPUT" | jq -r '.to // empty')
-TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.taskPath // .absoluteTaskPath // empty')
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
 REASON=$(printf '%s' "$INPUT" | jq -r '.reason // "Task handoff"')
 PROGRESS=$(printf '%s' "$INPUT" | jq -r '.progress // empty')
 FINDINGS=$(printf '%s' "$INPUT" | jq -r '.findings // empty')
@@ -53,10 +53,17 @@ require_param "reason" "$REASON"
 CREWLY_ROOT="$(cd "${SCRIPT_DIR}/../../../.." && pwd)"
 TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 
-# --- Step 0: Fission guard check (rate limit before handoff) ---
+# --- Step 0: Resolve target WorkItem if not supplied ---
+# Resolve order: explicit workItemId > the agent's currently-running claim.
+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
+
+# --- Step 1: Fission guard check (rate limit before handoff) ---
 # Non-blocking: if the fission API is unavailable, proceed with handoff.
 FISSION_BODY=$(jq -n \
-  --arg parentWorkItemId "${TASK_PATH:-handoff-stub}" \
+  --arg parentWorkItemId "${WORK_ITEM_ID:-handoff-stub}" \
   --arg agentId "$SESSION_NAME" \
   '{parentWorkItemId: $parentWorkItemId, agentId: $agentId}')
 
@@ -69,40 +76,23 @@ if [ "$fission_allowed" = "false" ]; then
   exit 1
 fi
 
-# --- Step 1: Record handoff in backend (reassigns task on the task board) ---
-HANDOFF_BODY=$(jq -n \
-  --arg from "$SESSION_NAME" \
-  --arg to "$TO" \
-  --arg taskPath "${TASK_PATH:-}" \
-  --arg reason "$REASON" \
-  --arg progress "${PROGRESS:-}" \
-  --arg projectPath "${PROJECT_PATH:-}" \
-  '{from: $from, to: $to, taskPath: $taskPath, reason: $reason, progress: $progress, projectPath: $projectPath}')
-
-echo "Recording handoff ${SESSION_NAME} → ${TO}..." >&2
-handoff_result=$(api_call POST "/task-management/handoff" "$HANDOFF_BODY" 2>/dev/null) || handoff_result='{"tracked":false,"error":"handoff API unavailable"}'
-
-# --- Step 2: Append handoff metadata to task file (if provided and exists) ---
-if [ -n "$TASK_PATH" ] && [ -f "$TASK_PATH" ]; then
-  cat >> "$TASK_PATH" << HANDOFF_EOF
-
-## Handoff Record
-- **Handed off to**: ${TO}
-- **Handed off from**: ${SESSION_NAME}
-- **Reason**: ${REASON}
-- **Timestamp**: ${TIMESTAMP}
-HANDOFF_EOF
-
-  # Append progress/findings/blockers if provided
-  if [ -n "$PROGRESS" ]; then
-    printf '\n### Progress at Handoff\n%s\n' "$PROGRESS" >> "$TASK_PATH"
-  fi
-  if [ -n "$FINDINGS" ]; then
-    printf '\n### Key Findings\n%s\n' "$FINDINGS" >> "$TASK_PATH"
-  fi
-  if [ -n "$BLOCKERS" ]; then
-    printf '\n### Blockers\n%s\n' "$BLOCKERS" >> "$TASK_PATH"
-  fi
+# --- Step 2: Record handoff via V3 (reassigns target on the WorkItem) ---
+# Spec 2026-05-06-task-management-v1-deprecation.md: handoff is now a
+# `target` field flip on the WorkItem plus an audit-trail note. The legacy
+# `/task-management/handoff` endpoint (which moved a `.md` file between
+# agent task directories) is gone.
+if [ -n "$WORK_ITEM_ID" ]; then
+  HANDOFF_BODY=$(jq -n \
+    --arg fromAgent "$SESSION_NAME" \
+    --arg newTarget "$TO" \
+    --arg reason "$REASON" \
+    '{newTarget: $newTarget, fromAgent: $fromAgent, reason: $reason}')
+
+  echo "Recording handoff ${SESSION_NAME} → ${TO} on WI ${WORK_ITEM_ID}..." >&2
+  handoff_result=$(api_call POST "/task-pool/items/${WORK_ITEM_ID}/handoff" "$HANDOFF_BODY" 2>/dev/null) \
+    || handoff_result='{"tracked":false,"error":"handoff API unavailable"}'
+else
+  handoff_result='{"tracked":false,"warning":"no active WorkItem for handing-off agent"}'
 fi
 
 # --- Step 3: Build and deliver context message to target agent ---
@@ -129,14 +119,10 @@ if [ -n "$BLOCKERS" ]; then
   printf '\n## Blockers / Notes\n%s\n' "$BLOCKERS" >> "$HANDOFF_MSG_FILE"
 fi
 
-if [ -n "$TASK_PATH" ]; then
-  printf '\n## Task File\n%s\n' "$TASK_PATH" >> "$HANDOFF_MSG_FILE"
-  # Include task content if file exists (first 100 lines)
-  if [ -f "$TASK_PATH" ]; then
-    printf '\n## Original Task Content\n```\n' >> "$HANDOFF_MSG_FILE"
-    head -100 "$TASK_PATH" >> "$HANDOFF_MSG_FILE" 2>/dev/null || true
-    printf '\n```\n' >> "$HANDOFF_MSG_FILE"
-  fi
+if [ -n "$WORK_ITEM_ID" ]; then
+  printf '\n## WorkItem\n%s\n' "$WORK_ITEM_ID" >> "$HANDOFF_MSG_FILE"
+  printf '\nFetch full brief: bash %s/config/skills/agent/core/read-task/execute.sh '"'"'{"workItemId":"%s"}'"'"'\n' \
+    "$CREWLY_ROOT" "$WORK_ITEM_ID" >> "$HANDOFF_MSG_FILE"
 fi
 
 cat >> "$HANDOFF_MSG_FILE" << FOOTER_EOF
@@ -173,7 +159,7 @@ jq -n \
   --arg from "$SESSION_NAME" \
   --arg to "$TO" \
   --arg reason "$REASON" \
-  --arg taskPath "${TASK_PATH:-}" \
+  --arg workItemId "${WORK_ITEM_ID:-}" \
   --arg timestamp "$TIMESTAMP" \
   --argjson delivery "$(echo "$deliver_result" | jq '.' 2>/dev/null || echo '{"raw":"'"${deliver_result//\"/\\\"}"'"}')" \
   --argjson tracking "$(echo "$handoff_result" | jq '.' 2>/dev/null || echo '{"raw":"'"${handoff_result//\"/\\\"}"'"}')" \
@@ -183,7 +169,7 @@ jq -n \
       from: $from,
       to: $to,
       reason: $reason,
-      taskPath: (if $taskPath == "" then null else $taskPath end),
+      workItemId: (if $workItemId == "" then null else $workItemId end),
       timestamp: $timestamp
     },
     delivery: $delivery,

package/config/skills/agent/core/list-my-followups/SKILL.md

@@ -1,3 +1,21 @@
+---
+name: list-my-followups
+description: List every follow-up trigger owned by your team — call before creating a new watcher to avoid duplicates, or when auditing why something keeps firing.
+version: 1.0.0
+category: followup
+skillType: claude-skill
+tags:
+  - followup
+  - trigger
+  - audit
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 15000
+---
+
 # list-my-followups
 
 List every follow-up trigger owned by your team. Call this **before** creating

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

@@ -1,17 +1,30 @@
 #!/bin/bash
-# Read the full details of a task file by its absolute path
+# Fetch a single WorkItem by id from the V3 task-pool.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. Replaces
+# `POST /task-management/read-task`, which read the `.md` file body from
+# the project's `.crewly/tasks/` filesystem. With v1 retired, the full
+# task body, brief, and worker output live on the WorkItem itself.
+#
+# Input: { "workItemId": "abc-123" }
+# Backwards-compat shim: if `absoluteTaskPath` is supplied instead, refuse
+# with a hard error directing callers to pass `workItemId`.
+
 set -euo pipefail
 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\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"abc-123\"}'"
+
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
+LEGACY_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
 
-ABSOLUTE_TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.absoluteTaskPath // empty')
-require_param "absoluteTaskPath" "$ABSOLUTE_TASK_PATH"
+if [ -z "$WORK_ITEM_ID" ] && [ -n "$LEGACY_PATH" ]; then
+  echo '{"error":"`absoluteTaskPath` is no longer accepted — pass `workItemId`. See spec/2026-05-06-task-management-v1-deprecation.md"}' >&2
+  exit 1
+fi
 
-BODY=$(jq -n --arg absoluteTaskPath "$ABSOLUTE_TASK_PATH" \
-  --arg taskPath "$ABSOLUTE_TASK_PATH" \
-  '{absoluteTaskPath: $absoluteTaskPath, taskPath: $taskPath}')
+require_param "workItemId" "$WORK_ITEM_ID"
 
-api_call POST "/task-management/read-task" "$BODY"
+api_call GET "/task-pool/items/${WORK_ITEM_ID}"

package/config/skills/agent/core/recall/SKILL.md

@@ -4,6 +4,13 @@ description: Retrieve stored memories relevant to a given context or query.
 version: 1.0.0
 category: memory
 skillType: claude-skill
+# Per orchestrator-namespace convention: orc accesses memory via a different
+# mechanism (internal `recallFromAllAgents()` in backend/src/services/memory/memory.service.ts:1047,
+# not surfaced as a skill — orc reads the cross-agent view directly through the
+# service layer when assembling team context). If a future PR adds an
+# orc-namespaced recall wrapper, update this comment to cross-ref. Until then,
+# keep orchestrator EXCLUDED here.
+# Spec provenance: 4-piece skill-mistake fix dispatch (Sam→Quinn, post-PR #446 merge).
 assignableRoles:
   - developer
   - qa

package/config/skills/agent/core/remember/SKILL.md

@@ -46,10 +46,26 @@ Store a memory entry for future recall. Use this to persist important context, d
 | `--agent` / `-a` | `agentId` | Yes | Your agent ID / session name |
 | `--content` / `-c` | `content` | Yes | Content to remember (or pipe via stdin) |
 | `--content-file` | — | No | Read content from a file path |
-| `--category` / `-C` | `category` | Yes | Category: `pattern`, `decision`, `gotcha`, `fact`, `preference`, `relationship`, `user_preference` |
+| `--category` / `-C` | `category` | Yes | See category × scope matrix below |
 | `--scope` / `-s` | `scope` | Yes | Scope: `agent` or `project` |
 | `--project` / `-p` | `projectPath` | No | Project path (required for `project` scope) |
 
+### Valid `category` × `scope` matrix
+
+| Category          | `scope=agent` | `scope=project` | Notes |
+|-------------------|:-------------:|:---------------:|-------|
+| `fact`            | ✅            | —               | Personal best-practice / "always do X". |
+| `pattern`         | ✅            | ✅              | Reusable workflow or code pattern. |
+| `gotcha`          | ✅ (F4 fix)   | ✅              | Things to avoid; agent-scope = personal, project-scope = team-wide. |
+| `preference`      | ✅            | —               | Updates your `AgentPreferences` (verbosity, breakdown size, etc.). |
+| `decision`        | —             | ✅              | Architectural / design decision (project-only). |
+| `relationship`    | —             | ✅              | Component-to-component edge in the codebase (project-only). |
+| `user_preference` | —             | ✅              | Project-scoped user preference (project-only). |
+
+> **Aliases / common mistakes:**
+> - `workflow` is **not** a public category — use `pattern` (it maps to internal `workflow` automatically).
+> - For "this approach failed for me last time" → use `category=gotcha scope=agent` (don't pollute project memory).
+
 ## Examples — CLI Flags (preferred)
 
 ```bash

package/config/skills/agent/core/remember/execute.sh

@@ -24,7 +24,11 @@ Options:
   --agent    | -a   Agent ID / session name (required)
   --content  | -c   Memory content text (required unless piped via stdin)
   --content-file    Read content from file path
-  --category | -C   Category: pattern, decision, gotcha, fact, preference (required)
+  --category | -C   Category (required) — valid values depend on scope:
+                      scope=agent   : fact, pattern, gotcha, preference
+                      scope=project : pattern, decision, gotcha, relationship, user_preference
+                    Aliases / common mistakes:
+                      'workflow' is NOT a public category — use 'pattern' instead.
   --scope    | -s   Scope: project or agent (required)
   --project  | -p   Project path (required for project scope)
   --json     | -j   Raw JSON payload

package/config/skills/agent/core/reply-channel/SKILL.md

@@ -1,3 +1,22 @@
+---
+name: reply-channel
+description: Send an agent-authored message back to a chat channel — used by the chat MVP dispatch loop after processing a `[CHAT:<channelId>]` prompt.
+version: 1.0.0
+category: comm
+skillType: claude-skill
+tags:
+  - chat
+  - comm
+  - channel
+  - reply
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 15000
+---
+
 # reply-channel
 
 Send an agent-authored message back to a chat channel. Used by the chat MVP

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

@@ -1,30 +1,53 @@
 #!/bin/bash
-# Report progress on the current task
+# Append a progress note to the agent's currently-claimed WorkItem.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. Replaces
+# `POST /task-management/sync`, which appended progress lines to the `.md`
+# task body. Notes now accumulate under `WorkItem.metadata.notes[]`.
+#
+# Input shape:
+#   { "sessionName": "dev-1", "progress": 50, "current": "Implementing tests",
+#     "workItemId"?: "abc-123",  // optional override
+#     "completed"?: ["t1"], "nextSteps"?: ["t2"], "blockers"?: ["..."] }
+#
+# If `workItemId` is omitted, the agent's currently-running claim is
+# resolved from the pool.
+
 set -euo pipefail
 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 '{\"sessionName\":\"dev-1\",\"progress\":50,\"current\":\"Implementing tests\",\"taskGroup\":\"delegated\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"sessionName\":\"dev-1\",\"progress\":50,\"current\":\"Implementing tests\"}'"
 
 SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
 PROGRESS=$(printf '%s' "$INPUT" | jq -r '.progress // empty')
 CURRENT=$(printf '%s' "$INPUT" | jq -r '.current // empty')
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
 require_param "sessionName" "$SESSION_NAME"
 require_param "progress" "$PROGRESS"
 require_param "current" "$CURRENT"
 
-# Build body with required and optional fields
-BODY=$(printf '%s' "$INPUT" | jq '{
-  sessionName: .sessionName,
-  progress: (.progress | tonumber),
-  current: .current
-} +
-  (if .projectPath then {projectPath: .projectPath} else {} end) +
-  (if .taskGroup then {taskGroup: .taskGroup} else {} end) +
-  (if .completed then {completed: .completed} else {} end) +
-  (if .nextSteps then {nextSteps: .nextSteps} else {} end) +
-  (if .blockers then {blockers: .blockers} else {} end) +
-  (if .ticketId then {ticketId: .ticketId} else {} end)')
-
-api_call POST "/task-management/sync" "$BODY"
+# Resolve target WI: explicit > running claim for this agent
+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
+
+if [ -z "$WORK_ITEM_ID" ]; then
+  echo '{"warning":"no active WorkItem for session — progress note discarded"}' >&2
+  exit 0
+fi
+
+# Compose a single multi-line note from the structured fields
+NOTE=$(printf '%s' "$INPUT" | jq -r '
+  ([
+    "Progress: \(.progress)% — \(.current)",
+    (if (.completed // [] | length) > 0 then "Completed: \(.completed | join(", "))" else empty end),
+    (if (.nextSteps // [] | length) > 0 then "Next: \(.nextSteps | join(", "))" else empty end),
+    (if (.blockers // [] | length) > 0 then "Blockers: \(.blockers | join(", "))" else empty end)
+  ] | join("\n"))')
+
+BODY=$(jq -n --arg author "$SESSION_NAME" --arg note "$NOTE" '{author: $author, note: $note}')
+
+api_call POST "/task-pool/items/${WORK_ITEM_ID}/notes" "$BODY"

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

@@ -48,7 +48,7 @@ When `status` is `done` and a `taskPath` is provided, the task file is automatic
 | Flag | JSON Field | Required | Description |
 |------|-----------|----------|-------------|
 | `--session` / `-s` | `sessionName` | Yes | Your agent session name |
-| `--status` / `-S` | `status` | Yes | Status: `done`, `blocked`, `failed`, `in_progress`, `active` |
+| `--status` / `-S` | `status` | Yes | Status: `done`, `blocked`, `failed`, `in_progress`, `active`, `milestone`. `milestone` = a SHIPPED artifact inside an open goal (PR merged / spec finalized / build pass); emits a `[MILESTONE]` envelope that orc's Smart Notification Protocol always forwards to the owner. See `config/sops/common/mid-flight-milestone-surface.md` (#435). Summary must be ≥30 chars. |
 | `--summary` / `-m` | `summary` | Yes | Brief description (or pipe via stdin) |
 | `--summary-file` | — | No | Read summary from a file path |
 | `--project` / `-p` | `projectPath` | No | Project path for auto-remember on completion |
@@ -69,6 +69,13 @@ bash execute.sh --session dev-1 --status blocked --summary "Waiting on API crede
 # Report failure
 bash execute.sh --session dev-1 --status failed --summary "Build fails due to missing dependency"
 
+# Surface a milestone (#435) — a SHIPPED artifact inside an open goal.
+# Emits the [MILESTONE] envelope orc's Smart Notification table always
+# forwards to the owner. Summary must carry both WHAT shipped AND
+# WHAT-IT-MEANS-FOR-OWNER (≥30 chars).
+bash execute.sh --session dev-1 --status milestone \
+  --summary "PR #420 merged — agent state file is now corruption-resistant + auto-snapshots every 30s"
+
 # Multi-line summary via stdin (avoids shell escaping)
 echo "Fixed the bug — it's working now" | bash execute.sh --session dev-1 --status done --project /path
 

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

@@ -22,7 +22,12 @@ Usage:
 
 Options:
   --session  | -s   Agent session name (required)
-  --status   | -S   Status: done, blocked, failed, in_progress, active (required)
+  --status   | -S   Status: done, blocked, failed, in_progress, active, milestone (required)
+                       milestone = a SHIPPED artifact inside an open goal (PR merged,
+                       spec finalized, build pass on a non-trivial change). Emits a
+                       [MILESTONE] envelope that orc's Smart Notification Protocol
+                       always forwards to the owner. See:
+                       config/sops/common/mid-flight-milestone-surface.md (issue #435)
   --summary  | -m   Status summary text (required unless piped via stdin)
   --summary-file    Read summary from file path
   --project  | -p   Project path for auto-remember on completion
@@ -42,6 +47,7 @@ SUMMARY=""
 PROJECT_PATH=""
 TASK_PATH=""
 TASK_ID=""
+WORK_ITEM_ID=""
 PROGRESS=""
 STRUCTURED="false"
 
@@ -81,6 +87,10 @@ while [[ $# -gt 0 ]]; do
       TASK_ID="$2"
       shift 2
       ;;
+    --work-item-id|--wi-id)
+      WORK_ITEM_ID="$2"
+      shift 2
+      ;;
     --progress)
       PROGRESS="$2"
       shift 2
@@ -130,6 +140,7 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$SUMMARY" ] && SUMMARY=$(printf '%s' "$INPUT" | jq -r '.summary // empty')
   [ -z "$TASK_PATH" ] && TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.taskPath // empty')
   [ -z "$TASK_ID" ] && TASK_ID=$(printf '%s' "$INPUT" | jq -r '.taskId // empty')
+  [ -z "$WORK_ITEM_ID" ] && WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // empty')
   [ -z "$PROGRESS" ] && PROGRESS=$(printf '%s' "$INPUT" | jq -r '.progress // empty')
   [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
   ARTIFACTS=$(printf '%s' "$INPUT" | jq -c '.artifacts // empty')
@@ -145,6 +156,18 @@ require_param "sessionName (--session)" "$SESSION_NAME"
 require_param "status (--status)" "$STATUS"
 require_param "summary (--summary)" "$SUMMARY"
 
+# Gate: milestone summaries must carry a real "WHAT shipped + WHAT it means
+# for the owner" — see config/sops/common/mid-flight-milestone-surface.md
+# (issue #435). Reject anything that looks like "task done" boilerplate
+# (under 30 chars) so the [MILESTONE] envelope doesn't get diluted.
+if [ "$STATUS" = "milestone" ]; then
+  SUMMARY_LEN=${#SUMMARY}
+  if [ "$SUMMARY_LEN" -lt 30 ]; then
+    echo "{\"error\":\"milestone gate failed: summary too short (${SUMMARY_LEN} chars, minimum 30). Per the Mid-Flight Milestone Surface SOP, a milestone surface must carry both WHAT shipped AND WHAT-IT-MEANS-FOR-OWNER.\"}" >&2
+    error_exit "Summary must be at least 30 characters when reporting milestone (got ${SUMMARY_LEN})"
+  fi
+fi
+
 # Gate: before_mark_done — reject empty or trivially short summaries
 # This prevents agents from marking tasks done without meaningful output.
 if [ "$STATUS" = "done" ]; then
@@ -162,6 +185,11 @@ map_status_to_state() {
     blocked) echo "blocked" ;;
     failed) echo "failed" ;;
     in_progress|working) echo "working" ;;
+    # Issue #435: `milestone` is a SHIPPED artifact inside an open goal,
+    # not the outer goal's completion. It maps to its own state so the
+    # downstream consumer (auto-learning subscriber, milestone-notification
+    # subscriber #438, orc Smart Notification table row #436) can branch.
+    milestone) echo "milestone" ;;
     *) echo "$1" ;;
   esac
 }
@@ -201,19 +229,37 @@ BODY=$(jq -n --arg content "$MESSAGE" --arg senderName "$SESSION_NAME" \
 
 api_call POST "/chat/agent-response" "$BODY"
 
-# If task is done and taskPath provided, move task file to done folder
-if [ "$STATUS" = "done" ] && [ -n "$TASK_PATH" ]; then
-  COMPLETE_BODY=$(jq -n \
-    --arg taskPath "$TASK_PATH" \
-    --arg sessionName "$SESSION_NAME" \
-    '{taskPath: $taskPath, sessionName: $sessionName}')
-  api_call POST "/task-management/complete" "$COMPLETE_BODY" || true
-fi
-
-# Auto-complete tracked tasks when status is done
+# Mark V3 WorkItem(s) for this session as complete when status=done.
+# Per spec/2026-05-06-task-management-v1-deprecation.md, V3 task-pool is now
+# the source of truth — we no longer move .md files via the v1
+# `/task-management/complete{-by-session}` endpoints.
+#
+# Resolution order for which WorkItem to complete:
+#   1. `workItemId` in input (preferred — explicit reference)
+#   2. The agent's currently-running WI fetched from the pool
+#
+# The legacy `taskPath` input is still accepted for backwards compatibility
+# but no longer drives the API call.
 if [ "$STATUS" = "done" ]; then
-  SESSION_BODY=$(jq -n --arg sessionName "$SESSION_NAME" '{sessionName: $sessionName}')
-  api_call POST "/task-management/complete-by-session" "$SESSION_BODY" || true
+  TARGET_WI_ID="${WORK_ITEM_ID:-}"
+  if [ -z "$TARGET_WI_ID" ]; then
+    # Fall back: query pool for this session's running WIs and complete the first match.
+    POOL_RESP=$(api_call GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
+    TARGET_WI_ID=$(echo "$POOL_RESP" | jq -r '.workItems[0].id // .data[0].id // empty' 2>/dev/null || true)
+  fi
+
+  if [ -n "$TARGET_WI_ID" ]; then
+    # Hygiene #4: emit canonical body shape `{agentId, result:{summary}}`
+    # required by /api/task-pool/complete (task-pool.controller.ts
+    # `completeItem`). Prior shape `{summary}` 400'd with
+    # `agentId is required` + `summary required in body.result`,
+    # forcing every worker into a direct-curl workaround.
+    COMPLETE_BODY=$(jq -n \
+      --arg agentId "$SESSION_NAME" \
+      --arg summary "$SUMMARY" \
+      '{agentId: $agentId, result: {summary: $summary}}')
+    api_call POST "/task-pool/complete/${TARGET_WI_ID}" "$COMPLETE_BODY" || true
+  fi
 fi
 
 # Auto-persist key findings as project knowledge when task is done (#127, #219).

package/config/skills/agent/core/save-working-state/execute.sh

@@ -1,19 +1,30 @@
 #!/bin/bash
-# Save working state for current task — persists across session restarts
+# Save free-form working state for the current task — persists across session restarts.
+#
+# V3-only as of spec 2026-05-06-task-management-v1-deprecation.md. Replaces
+# `POST /task-management/save-working-notes`, which wrote a separate
+# `.md` notes file. Notes now accumulate under `WorkItem.metadata.notes[]`.
+#
+# Input shape:
+#   { "workItemId": "abc-123", "sessionName": "dev-1", "notes": "current state..." }
+#
+# Backwards-compat: a `taskId` field is accepted as an alias for
+# `workItemId` for one release window. New callers should use `workItemId`.
+
 set -euo pipefail
 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 '{\"taskId\":\"xxx\",\"sessionName\":\"crewly-product-sam-xxx\",\"notes\":\"current state...\"}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"abc-123\",\"sessionName\":\"dev-1\",\"notes\":\"current state\"}'"
 
-TASK_ID=$(printf '%s' "$INPUT" | jq -r '.taskId // empty')
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // .taskId // empty')
 SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
 NOTES=$(printf '%s' "$INPUT" | jq -r '.notes // empty')
-require_param "taskId" "$TASK_ID"
+require_param "workItemId" "$WORK_ITEM_ID"
 require_param "sessionName" "$SESSION_NAME"
 require_param "notes" "$NOTES"
 
-BODY=$(printf '%s' "$INPUT" | jq '{taskId: .taskId, sessionName: .sessionName, notes: .notes}')
+BODY=$(jq -n --arg author "$SESSION_NAME" --arg note "$NOTES" '{author: $author, note: $note}')
 
-api_call POST "/task-management/save-working-notes" "$BODY"
+api_call POST "/task-pool/items/${WORK_ITEM_ID}/notes" "$BODY"