crewly 1.5.18 → 1.5.20

package/config/skills/team-leader/delegate-task/execute.sh

@@ -61,6 +61,7 @@ if [ -z "$INPUT_JSON" ] && [ -z "$TASK" ] && [ ! -t 0 ]; then
 fi
 
 # Parse JSON if provided (backward compatible)
+INPUT="{}"
 if [ -n "$INPUT_JSON" ]; then
   INPUT=$(read_json_input "$INPUT_JSON")
   [ -z "$TO" ] && TO=$(printf '%s' "$INPUT" | jq -r '.to // empty')
@@ -116,7 +117,10 @@ fi
 TASK_MESSAGE="New task from Team Leader (priority: ${PRIORITY}):\n\n**[REQUIRED] When done, you MUST:** (1) Output a text summary of your work, findings, and any issues. (2) Call report-status:\nbash ${CREWLY_ROOT}/config/skills/agent/core/report-status/execute.sh '{\"sessionName\":\"${TO}\",\"status\":\"done\",\"summary\":\"<brief summary>\",\"projectPath\":\"${PROJECT_PATH}\"}'\n\n---\n\n${TASK}"
 [ -n "$CONTEXT" ] && TASK_MESSAGE="${TASK_MESSAGE}\n\nContext: ${CONTEXT}"
 
-# Deliver the task message with fallback strategy
+# Deliver the task message with fallback strategy:
+# 1. Try normal delivery (waitForReady)
+# 2. If fails, try force delivery
+# 3. If still fails, auto-start the worker then retry
 BODY=$(jq -n --arg message "$TASK_MESSAGE" '{message: $message, waitForReady: true, waitTimeout: 15000}')
 
 DELIVER_OK=true
@@ -125,8 +129,43 @@ api_call POST "/terminal/${TO}/deliver" "$BODY" || DELIVER_OK=false
 if [ "$DELIVER_OK" = "false" ]; then
   FORCE_BODY=$(jq -n --arg message "$TASK_MESSAGE" '{message: $message, force: true}')
   api_call POST "/terminal/${TO}/deliver" "$FORCE_BODY" || {
-    echo '{"error":"Failed to deliver task to '"$TO"'. Session may not exist or agent is not running."}'
-    exit 1
+    # Worker likely offline — attempt auto-start if we have team context
+    STARTED=false
+    if [ -n "$TEAM_ID" ]; then
+      # Find worker's memberId from team data
+      WORKER_MEMBER_ID=""
+      if [ -n "$TEAM_DATA" ] && [ "$(echo "$TEAM_DATA" | jq -r '.success // false')" = "true" ]; then
+        WORKER_MEMBER_ID=$(echo "$TEAM_DATA" | jq -r --arg session "$TO" \
+          '.data.members[] | select(.sessionName == $session) | .id // empty' 2>/dev/null || true)
+      else
+        # Fetch team data if not already loaded
+        TEAM_DATA=$(api_call GET "/teams/${TEAM_ID}" 2>/dev/null || echo '{}')
+        WORKER_MEMBER_ID=$(echo "$TEAM_DATA" | jq -r --arg session "$TO" \
+          '.data.members[] | select(.sessionName == $session) | .id // empty' 2>/dev/null || true)
+      fi
+
+      if [ -n "$WORKER_MEMBER_ID" ]; then
+        echo '{"info":"Worker '"$TO"' appears offline — auto-starting..."}' >&2
+        START_RESULT=$(api_call POST "/teams/${TEAM_ID}/members/${WORKER_MEMBER_ID}/start" '{}' 2>/dev/null || true)
+        START_OK=$(echo "$START_RESULT" | jq -r '.success // false' 2>/dev/null || echo "false")
+
+        if [ "$START_OK" = "true" ]; then
+          echo '{"info":"Worker '"$TO"' start triggered — retrying delivery in 10s..."}' >&2
+          sleep 10
+          # Retry delivery after agent boots
+          RETRY_BODY=$(jq -n --arg message "$TASK_MESSAGE" '{message: $message, waitForReady: true, waitTimeout: 30000}')
+          api_call POST "/terminal/${TO}/deliver" "$RETRY_BODY" && STARTED=true || {
+            # Final fallback: force deliver
+            api_call POST "/terminal/${TO}/deliver" "$FORCE_BODY" && STARTED=true || true
+          }
+        fi
+      fi
+    fi
+
+    if [ "$STARTED" = "false" ]; then
+      echo '{"error":"Failed to deliver task to '"$TO"'. Worker is offline and could not be auto-started. Ensure the worker is a team member with a valid session.","to":"'"$TO"'","teamId":"'"$TEAM_ID"'"}'
+      exit 1
+    fi
   }
 fi
 

package/config/skills/team-leader/design-checklist/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: Design Checklist
+description: "Generate an acceptance checklist for a delegated objective BEFORE execution begins. The checklist must be sent to and approved by the superior (Orchestrator/user) to ensure alignment. Once approved, it becomes the verification standard used by verify-output after task completion."
+version: 1.0.0
+category: quality
+skillType: claude-skill
+assignableRoles:
+  - team-leader
+triggers:
+  - design checklist
+  - create acceptance criteria
+  - define verification checklist
+  - alignment checklist
+tags:
+  - checklist
+  - quality
+  - alignment
+  - verification
+  - planning
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 30000
+---
+
+# Design Checklist
+
+Generates a structured acceptance checklist for a task/objective **before execution begins**.
+The checklist is sent to the Orchestrator (or user) for alignment and approval.
+Once approved, the TL uses it during `verify-output` after workers complete the task.
+
+## Flow
+
+```
+1. TL receives objective from Orchestrator
+2. TL runs design-checklist → generates checklist.json
+3. Checklist sent to Orchestrator for approval
+4. Orchestrator approves/adjusts → POST /api/task-management/:taskId/checklist/approve
+5. TL proceeds with decompose-goal + delegate-task
+6. Workers complete → TL runs verify-output with approved checklist
+```
+
+## Usage
+
+```bash
+bash {{SKILLS_PATH}}/team-leader/design-checklist/execute.sh \
+  --objective "Build user authentication" \
+  --project-path /path/to/project \
+  --task-id task-123 \
+  [--team-id team-456] \
+  [--mission-id mission-789]
+```
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--objective` | Yes | The objective/task to design acceptance criteria for |
+| `--project-path` | Yes | Project root path |
+| `--task-id` | Yes | Task ID for storing the checklist |
+| `--team-id` | No | Team ID (loads template verification pipeline as baseline) |
+| `--mission-id` | No | Mission ID (loads Mission.successCriteria for alignment) |
+
+## Output
+
+The skill outputs context for the runtime to generate a checklist, then stores it:
+
+```json
+{
+  "success": true,
+  "taskId": "task-123",
+  "checklistPath": "/project/.crewly/tasks/.../checklist.json",
+  "status": "pending_approval",
+  "itemCount": 5
+}
+```
+
+## Checklist Format
+
+```json
+{
+  "taskId": "task-123",
+  "objective": "Build user authentication",
+  "status": "pending_approval",
+  "createdBy": "tl-session-name",
+  "createdAt": "ISO8601",
+  "alignedWith": "mission-success-criteria (if available)",
+  "items": [
+    {
+      "id": "chk-1",
+      "category": "functionality",
+      "description": "JWT token generation and validation works correctly",
+      "type": "command",
+      "command": "npm test -- --grep 'jwt'",
+      "critical": true
+    },
+    {
+      "id": "chk-2",
+      "category": "quality",
+      "description": "Test coverage above 80%",
+      "type": "command",
+      "command": "npm test -- --coverage",
+      "critical": true
+    },
+    {
+      "id": "chk-3",
+      "category": "review",
+      "description": "Code follows project patterns and has proper error handling",
+      "type": "manual",
+      "critical": false
+    }
+  ]
+}
+```
+
+## Related Skills
+
+- `decompose-goal` — Break objective into subtasks (run AFTER checklist approved)
+- `verify-output` — Use approved checklist to verify completed work
+- `delegate-task` — Assign subtasks to workers

package/config/skills/team-leader/design-checklist/execute.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+# Design an acceptance checklist for an objective BEFORE execution.
+# The checklist is stored and must be approved by the superior before
+# the TL proceeds with decompose-goal and delegate-task.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+# --- Input parsing ---
+OBJECTIVE=""
+PROJECT_PATH=""
+TASK_ID=""
+TEAM_ID=""
+MISSION_ID=""
+INPUT_JSON=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --objective|-o)     OBJECTIVE="$2";      shift 2 ;;
+    --project-path|-p)  PROJECT_PATH="$2";   shift 2 ;;
+    --task-id|-t)       TASK_ID="$2";        shift 2 ;;
+    --team-id|-g)       TEAM_ID="$2";        shift 2 ;;
+    --mission-id|-m)    MISSION_ID="$2";     shift 2 ;;
+    --json|-j)          INPUT_JSON="$2";     shift 2 ;;
+    --help|-h)
+      echo "Usage: execute.sh --objective 'Build auth' --project-path /path --task-id task-123 [--team-id team-456] [--mission-id mission-789]"
+      exit 0 ;;
+    *) shift ;;
+  esac
+done
+
+# Legacy JSON fallback
+if [[ -n "$INPUT_JSON" ]]; then
+  [[ -z "$OBJECTIVE" ]]    && OBJECTIVE=$(echo "$INPUT_JSON" | jq -r '.objective // empty' 2>/dev/null || true)
+  [[ -z "$PROJECT_PATH" ]] && PROJECT_PATH=$(echo "$INPUT_JSON" | jq -r '.projectPath // empty' 2>/dev/null || true)
+  [[ -z "$TASK_ID" ]]      && TASK_ID=$(echo "$INPUT_JSON" | jq -r '.taskId // empty' 2>/dev/null || true)
+  [[ -z "$TEAM_ID" ]]      && TEAM_ID=$(echo "$INPUT_JSON" | jq -r '.teamId // empty' 2>/dev/null || true)
+  [[ -z "$MISSION_ID" ]]   && MISSION_ID=$(echo "$INPUT_JSON" | jq -r '.missionId // empty' 2>/dev/null || true)
+fi
+
+require_param "objective" "$OBJECTIVE"
+require_param "project-path" "$PROJECT_PATH"
+require_param "task-id" "$TASK_ID"
+
+# --- Load context for checklist generation ---
+
+# Load Mission success criteria if mission linked
+MISSION_CRITERIA=""
+if [[ -n "$MISSION_ID" ]]; then
+  MISSION_DATA=$(api_call GET "/missions/${MISSION_ID}" 2>/dev/null || true)
+  if [[ -n "$MISSION_DATA" ]]; then
+    MISSION_CRITERIA=$(echo "$MISSION_DATA" | jq -r '.data.successCriteria // [] | join("\n- ")' 2>/dev/null || true)
+  fi
+fi
+
+# Load team template verification pipeline if team linked
+TEMPLATE_PIPELINE=""
+if [[ -n "$TEAM_ID" ]]; then
+  TEAM_DATA=$(api_call GET "/teams/${TEAM_ID}" 2>/dev/null || true)
+  if [[ -n "$TEAM_DATA" ]]; then
+    TEMPLATE_ID=$(echo "$TEAM_DATA" | jq -r '.data.templateId // empty' 2>/dev/null || true)
+    if [[ -n "$TEMPLATE_ID" ]]; then
+      TEMPLATE_DATA=$(api_call GET "/templates/${TEMPLATE_ID}" 2>/dev/null || true)
+      if [[ -n "$TEMPLATE_DATA" ]]; then
+        TEMPLATE_PIPELINE=$(echo "$TEMPLATE_DATA" | jq -r '
+          .data.verificationPipeline.steps // [] |
+          map("- " + (.method // "check") + ": " + (.description // .name // "unnamed step")) |
+          join("\n")
+        ' 2>/dev/null || true)
+      fi
+    fi
+  fi
+fi
+
+# --- Output context for the runtime to generate checklist ---
+# The TL runtime (Claude Code / Gemini CLI) reads this and produces
+# the structured checklist. This is the key "no new LLM layer" design.
+
+cat << CHECKLIST_PROMPT
+
+## Acceptance Checklist Design
+
+You are designing an acceptance checklist for this objective BEFORE execution begins.
+This checklist will be sent to your superior (Orchestrator) for approval.
+Once approved, you will use it to verify workers' output after task completion.
+
+### Objective
+${OBJECTIVE}
+
+### Mission Success Criteria (align with these)
+${MISSION_CRITERIA:-No mission linked — design criteria based on the objective itself.}
+
+### Team Verification Pipeline (baseline checks)
+${TEMPLATE_PIPELINE:-No template pipeline — design checks from scratch.}
+
+### Instructions
+
+Design a verification checklist with 3-8 items. Each item should be:
+- **Concrete and measurable** — not vague ("good code" is bad, "all tests pass" is good)
+- **Aligned with Mission criteria** if available
+- **Categorized**: functionality, quality, security, performance, documentation
+
+For each item, specify:
+- \`id\`: unique identifier (e.g., "chk-1")
+- \`category\`: functionality | quality | security | performance | documentation
+- \`description\`: what is being verified
+- \`type\`: "command" (automated check) or "manual" (TL judgment)
+- \`command\`: shell command to run (only for type=command)
+- \`critical\`: true if this is a must-pass item, false if nice-to-have
+
+Output valid JSON matching this schema:
+\`\`\`json
+{
+  "taskId": "${TASK_ID}",
+  "objective": "${OBJECTIVE}",
+  "status": "pending_approval",
+  "createdBy": "${CREWLY_SESSION_NAME:-tl}",
+  "createdAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "items": [
+    {
+      "id": "chk-1",
+      "category": "functionality",
+      "description": "Description of what to verify",
+      "type": "command",
+      "command": "npm test",
+      "critical": true
+    }
+  ]
+}
+\`\`\`
+
+After generating the JSON, save it and submit for approval:
+\`\`\`bash
+# Save checklist
+cat > "${PROJECT_PATH}/.crewly/tasks/checklist-${TASK_ID}.json" << 'CHECKLIST_EOF'
+<YOUR_JSON_OUTPUT>
+CHECKLIST_EOF
+
+# Submit for approval
+curl -s -X POST "${CREWLY_API_URL}/api/task-management/${TASK_ID}/checklist" \\
+  -H "Content-Type: application/json" \\
+  -d @"${PROJECT_PATH}/.crewly/tasks/checklist-${TASK_ID}.json"
+\`\`\`
+
+Then notify your superior:
+"I've designed the acceptance checklist for '${OBJECTIVE}'. Please review and approve before I proceed with task decomposition."
+
+**Do NOT start decompose-goal or delegate-task until the checklist is approved.**
+
+CHECKLIST_PROMPT
+
+echo '{"success":true,"message":"Checklist design context provided to runtime","taskId":"'"${TASK_ID}"'"}'

package/config/skills/team-leader/verify-output/execute.sh

@@ -21,6 +21,7 @@ WORKER_ID=$(printf '%s' "$INPUT" | jq -r '.workerId // empty')
 TEAM_ID=$(printf '%s' "$INPUT" | jq -r '.teamId // empty')
 PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
 TEMPLATE_ID=$(printf '%s' "$INPUT" | jq -r '.templateId // empty')
+CHECKLIST_PATH=$(printf '%s' "$INPUT" | jq -r '.checklistPath // empty')
 CHECKS=$(printf '%s' "$INPUT" | jq -c '.checks // []')
 
 # At least taskPath or taskId is needed
@@ -44,6 +45,47 @@ if [ -n "$TASK_ID" ]; then
   [ -z "$TASK_OUTPUT" ] && TASK_OUTPUT="$TASK_OUTPUT_FROM_ID"
 fi
 
+# =============================================================================
+# Pre-approved checklist loading (from design-checklist skill)
+# =============================================================================
+
+# If checklistPath is provided, load pre-approved checklist items as checks.
+# This takes priority over template pipeline and inline checks.
+if [ -n "$CHECKLIST_PATH" ] && [ -f "$CHECKLIST_PATH" ]; then
+  CHECKLIST_DATA=$(cat "$CHECKLIST_PATH" 2>/dev/null || echo '{}')
+  CHECKLIST_STATUS=$(echo "$CHECKLIST_DATA" | jq -r '.status // "unknown"' 2>/dev/null || true)
+
+  if [ "$CHECKLIST_STATUS" = "approved" ]; then
+    # Convert checklist items to verification checks
+    CHECKS=$(echo "$CHECKLIST_DATA" | jq -c '
+      [.items[] | {
+        name: .id,
+        type: .type,
+        command: (.command // empty),
+        pattern: (.pattern // empty),
+        description: .description,
+        critical: (.critical // false)
+      }]
+    ' 2>/dev/null || echo '[]')
+
+    PASS_POLICY=$(echo "$CHECKLIST_DATA" | jq -r '.passPolicy // "critical_only"' 2>/dev/null || echo "critical_only")
+  else
+    echo '{"error":"Checklist exists but is not approved (status: '"$CHECKLIST_STATUS"'). Approve first via POST /api/task-management/'$TASK_ID'/checklist/approve"}' >&2
+    # Fall through to template/inline checks
+  fi
+
+# If no checklistPath but taskId, try to find checklist automatically
+elif [ -n "$TASK_ID" ] && [ -n "$PROJECT_PATH" ]; then
+  AUTO_CHECKLIST="${PROJECT_PATH}/.crewly/tasks/checklist-${TASK_ID}.json"
+  if [ -f "$AUTO_CHECKLIST" ]; then
+    CHECKLIST_STATUS=$(jq -r '.status // "unknown"' "$AUTO_CHECKLIST" 2>/dev/null || true)
+    if [ "$CHECKLIST_STATUS" = "approved" ]; then
+      CHECKS=$(jq -c '[.items[] | {name: .id, type: .type, command: (.command // empty), pattern: (.pattern // empty), description: .description, critical: (.critical // false)}]' "$AUTO_CHECKLIST" 2>/dev/null || echo '[]')
+      PASS_POLICY=$(jq -r '.passPolicy // "critical_only"' "$AUTO_CHECKLIST" 2>/dev/null || echo "critical_only")
+    fi
+  fi
+fi
+
 # =============================================================================
 # Pipeline loading: convert template pipeline steps to checks
 # =============================================================================

package/config/sops/xhs-requirement-log.v1.md

@@ -0,0 +1,238 @@
+# XHS Requirement Log (Spec-In → Result-Out)
+
+> **Authority**: Steve (Founder) policy directive, 2026-04-17.
+> **Effective**: 2026-04-17 — PERMANENT (supersedes every "check iriss-air / scrape / connect" pattern).
+> **Scope**: Every XHS data need. No exceptions.
+> **Owner**: Grace (Distribution & Growth). Co-maintainers: Ella (TL), Luna (Content Strategist).
+> **Upstream counterparty**: iriss-air team (via `crewly-orc` → Rex `rednote-team-rex-*`).
+> **Related policy**: `sop/xhs-remote-only-policy-v2.1.md`, `sop/POLICY-manual-execution-only.md`.
+
+---
+
+## 0. Hard rules (non-negotiable)
+
+1. **NO local Chrome / iPad / Playwright / Patchright / CDP / MCP touches XHS.** Any URL under `*.xiaohongshu.com` from a local tool is a policy breach. This includes the `remote-browser` skill pointed at iriss-air when its own extension is `connected=false` (proxy can fall back to local Chrome — confirmed 2026-04-17T14:13Z breach).
+2. **Zero iriss-air internal-state monitoring.** Don't poll `/api/browser/status`, Chrome CDP port 9222, iPad availability, etc. Those are iriss-air's problems.
+3. **Only two legitimate interactions with iriss-air**:
+   - Send a **Requirement Spec** (this log).
+   - Receive a **Delivery** and run the **Verification Checklist** (§5).
+4. **No workarounds** (VNC, stealth browser, agent-browser to iriss-air, Cloud Relay direct, etc.). If the spec-in/result-out channel is broken, file a Blocker entry and hand back to Ella.
+
+---
+
+## 1. What a Requirement Spec MUST contain
+
+Every spec sent to iriss-air (via `send-message` → `crewly-orc`) must include these **10 fields** (v1.2 adds `job_size`). Anything missing → treated as ambiguous and NACK'd on return.
+
+| # | Field | Format | Notes |
+|---|-------|--------|-------|
+| 1 | `spec_id` | `XHS-REQ-YYYYMMDD-HHMM-<slug>` | Unique, monotonically increasing. Example: `XHS-REQ-20260417-1308-daily-comments` |
+| 2 | `origin` | Marketing role + task reference | Who asked and why (which task / cron) |
+| 3 | `priority` | `P0a / P0b / P1 / P2` | **v1.2 split**: P0a = ship today, fast job; P0b = ship today, heavy job; P1 = within 24h; P2 = within this week. `priority` MUST be consistent with `job_size` (see field 10). |
+| 4 | `window` | ISO8601 range | Hard time window the data must cover (e.g. `2026-04-10T13:08Z / 2026-04-17T13:08Z`) |
+| 5 | `delta_anchor` | ISO8601 timestamp OR `none` | "Only new since X" anchor. If `none`, full window |
+| 6 | `targets` | Post IDs or post titles (roster) | Explicit list — do NOT say "all active posts" without enumerating |
+| 7 | `fields` | Schema list | The per-record columns you need (see §2 catalogue) |
+| 8 | `deliverable_path` | Local path under `ops/marketing/tmp/` | Where iriss-air's `reply-remote` should inline-land the file |
+| 9 | `policy_tags` | List | e.g. `data-collection-only`, `no-reply`, `dedupe-on=...` |
+| **10** | **`job_size`** (v1.2) | **`fast-poll` \| `full-scrape`** | **Drives SLA routing in §3.** `fast-poll` = ≤ 4 targets AND no comments-scroll (headline metrics / spot checks / ban-signal). `full-scrape` = ≥ 5 targets OR any comments-scroll OR account-snapshot. Mismatch with `priority` (e.g. P0a + full-scrape) is rejected at dispatch. |
+
+### Priority × job_size matrix (reference)
+
+| `job_size` | Allowed `priority` | SLA (see §3) | Typical case |
+|------------|--------------------|--------------|--------------|
+| `fast-poll` | `P0a`, `P1`, `P2` | P0a: 20 min; P1: 4 h; P2: same day | Risk-signal check, one-post metric pull, "did this note go viral yet?" |
+| `full-scrape` | `P0b`, `P1`, `P2` | P0b: 90–120 min; P1: 4 h; P2: same day | Cron #10 daily comment sweep, weekly account snapshot, 11-post delta roster |
+
+### Spec template (copy when issuing a new request) — v1.2
+
+```markdown
+[TASK from <your-session> — <ISO8601 UTC>]
+
+spec_id: XHS-REQ-YYYYMMDD-HHMM-<slug>
+priority: P0a|P0b|P1|P2
+job_size: fast-poll|full-scrape           # v1.2 — REQUIRED; drives SLA routing
+origin:   <role> / <task-or-cron-ref>
+
+window:        <startISO> / <endISO>
+delta_anchor:  <ISO or "none">
+targets:
+  - <post_title_or_id>
+  - <post_title_or_id>
+  ...
+fields: [<from §2 catalogue>]
+
+deliverable_path (local landing):
+  /Users/yellowsunhy/.../ops/marketing/tmp/<filename>.md
+deliverable_path (iriss-air):
+  /Users/irisran/projects/rednote-team/tmp/<same-filename>.md
+
+policy_tags: [data-collection-only, no-reply, dedupe-on=(post_id,commenter_username,comment_date)]
+
+On NO-NEW data, reply with an explicit "NO NEW <scope>" confirmation + dispatch id.
+On partial failure (nav-blocked post, etc.), enumerate which targets failed and why.
+DO NOT fall back to local scraping. If iPad/rednote-reader is down, report and stop.
+```
+
+---
+
+## 2. Field-schema catalogue (what to put in `fields`)
+
+Pick exactly the columns you need — don't over-ask.
+
+### 2.1 Comment scrape (`kind: comments`)
+```
+commenter_username, commenter_relation (follower|friend|none|unknown),
+comment_date (ISO8601), comment_body,
+parent_post_title (or parent_post_id),
+is_reply_to_steve (bool), has_unread_flag (bool),
+parent_comment_id (for threaded replies, optional)
+```
+
+### 2.2 Post metrics (`kind: post-metrics`)
+```
+post_id, post_title, published_date, impressions, likes, saves,
+comments_count, new_followers (if attributable), ces_score (if computed)
+```
+
+### 2.3 Account snapshot (`kind: account-snapshot`)
+```
+snapshot_time (ISO), follower_count, total_likes, total_saves, posts_visible,
+verified_status, banner_changed (bool)
+```
+
+### 2.4 Competitor / trending (`kind: competitor`)
+```
+account_handle, topic, post_title, likes, comments, saves, posted_at,
+content_hook (1 sentence), observed_pattern
+```
+
+### 2.5 DM / private inbox (`kind: dms`) — *only if Steve authorises*
+```
+sender_username, sender_relation, received_at, body, is_unread, thread_id
+```
+
+### 2.6 Ban / risk signals (`kind: risk-signal`)
+```
+signal_type (shadowban|rate-limit|captcha|login-wall|geo-block),
+post_affected, observed_at, evidence_screenshot_path
+```
+
+---
+
+## 3. Dispatch mechanics (spec → iriss-air)
+
+1. **Write the spec** using template above. Save a dispatch log to `ops/marketing/tmp/xhs-scrape-dispatch-<ISO>.md` (precedent: we've been doing this since 2026-04-14).
+2. **Create placeholder**: `ops/marketing/tmp/<deliverable-filename>.md`.
+   - **Required** (v1.1): the placeholder MUST contain the literal string `PLACEHOLDER — DO NOT VERIFY` in its first 5 lines. This is a fail-fast signal for the verification checklist (§5.1).
+   - The placeholder should also carry: status header `⏳ PENDING`, the `spec_id`, the dispatch time, and the expected iriss-air-side path.
+3. **Dispatch** via the `send-message` skill → `crewly-orc` on iriss-air. Body = the spec template body (§1).
+4. **Update the Active Register** (§4) with an `OPEN` row, including the dispatch time (this becomes the SLA anchor).
+5. **Do NOT poll** iriss-air. **Calibrated SLA (v1.2 — tiered, approved by Ella TL 2026-04-17)**:
+
+   | Priority × job_size | Early-warning | SLA (hard breach) | Notes |
+   |---|---|---|---|
+   | **P0a** + `fast-poll` | 10 min | **20 min** | <5 targets AND no comments-scroll. Risk-signal, single-post metric, spot check. |
+   | **P0b** + `full-scrape` | 90 min | **120 min** | ≥5 targets OR comments-scroll OR account-snapshot. Cron #10 daily sweeps, 11-post roster. |
+   | **P1** (either `job_size`) | 2 h | **4 h** | Same-day-ish, not urgent. |
+   | **P2** (either `job_size`) | noon next day | **end of same operating day** | Weekly/monthly batch work. |
+
+   - **Early-warning** = log a note in the register row ("approaching SLA"), do nothing else — **no probe to iriss-air**.
+   - **Hard breach** = file a `BLOCKED: no-ack` entry and escalate to Ella. Still no probe.
+   - **Mismatch rejection**: if `priority=P0a` but `job_size=full-scrape` (or vice versa), verification treats the spec as malformed and marks `BLOCKED: malformed-spec`. Re-dispatch with corrected pairing.
+   - **Back-compat**: legacy rows recorded with flat `P0` stay valid; promote them to `P0a`/`P0b` at the next scrub pass (no emergency re-dispatch required).
+
+---
+
+## 4. Active Register
+
+> **Update rule**: one row per `spec_id`. States: `OPEN → DELIVERED → VERIFIED → ARCHIVED`, or `BLOCKED / CANCELLED`. Move ARCHIVED rows to §7 weekly.
+
+| spec_id | Origin | Priority | Issued (UTC) | Window | Expected Landing Path | State | Delivered @ | Verified @ | Notes |
+|---------|--------|----------|--------------|--------|-----------------------|-------|-------------|------------|-------|
+| XHS-REQ-20260417-0028-daily-comments | Grace / Cron #10a | P1 | 2026-04-17 00:29 | 7d rolling | `tmp/xhs-raw-comments-2026-04-17.md` | **DELIVERED** (superseded) | ~00:40 | pending | See `tmp/xhs-raw-comments-2026-04-17.md` — earliest of today's 5 dispatches. |
+| XHS-REQ-20260417-0050-daily-comments | Grace / Cron #10a | P1 | 2026-04-17 00:51 | 7d explicit | `tmp/xhs-raw-comments-2026-04-17T0050Z.md` | **DELIVERED** (superseded) | ~01:05 | pending | Superseded by 0306Z full pull. |
+| XHS-REQ-20260417-0306-daily-comments | Grace / Cron #10a | P1 | 2026-04-17 03:06 | delta since 14:00 PT | `tmp/xhs-raw-comments-2026-04-17T0306Z.md` | **DELIVERED** | ~03:25 | **VERIFIED** by Mila (see `reports/2026-04-17-xhs-evening-reply-package-mila.md`) | 20 KB body; largest comment set today. |
+| XHS-REQ-20260417-1248-daily-comments | Grace / Cron #10b | P1 | 2026-04-17 12:48 | delta since 03:06Z | `tmp/xhs-raw-comments-2026-04-17T1248Z.md` | **DELIVERED** (per orc 14:40Z; iriss-air-side) | ~14:10Z (iriss-air-side completion) | pending local-file verification | Original dispatch hit "Rex down 1/1". Rex came back, full-scrape ran ~80min (03:06Z→14:10Z window). Used as authoritative upstream source for the 13:08Z derivative output. No local file landed yet — awaiting iriss-air re-send or treating 1308Z as the sufficient VERIFIED superset. |
+| XHS-REQ-20260417-1308-daily-comments | Grace / Cron #10a | **P0b** (promoted from legacy P0 under v1.2; job_size=`full-scrape`, 11 targets + comments-scroll) | 2026-04-17 13:09 | delta since 12:48Z (fallback: 7d) | `tmp/xhs-raw-comments-2026-04-17T1308Z.md` | **✅ VERIFIED** | 2026-04-17 14:39Z (after re-send — original 14:15Z attempt truncated 4,644B → 2,031B in transport) | 2026-04-17 14:42Z | All §5 layers PASS: early-exit (placeholder gone, size 5,211B > 2,223B placeholder, mtime 14:40Z > dispatch+60s) ✅; envelope (spec_id matches, source declared as rednote-reader iPad Accessibility API / 非 Chrome/9222) ✅; scope (delta 03:06Z→13:08Z honoured; all 11 posts enumerated; post #11 retry succeeded) ✅; records (3 new comments, all mandatory fields present, dedup key unique) ✅; policy (no replies/cookies/tokens) ✅. **Business verdict**: NO NEW COMMENTS vs 12:48Z run — the 3 delta comments are already in the 12:48Z output. Transport truncation bug logged; drove the §5.1 canary add-on. **v1.2 SLA analysis**: under P0b 120min hard-breach clock, delivery at 14:39Z (90 min after 13:09Z dispatch) = within SLA (would have hit "early-warning at 90min" right as delivery landed, no breach). This single case validated the tiered SLA choice. |
+
+**Priority backlog (not yet dispatched)**: none. Cron #10a / #10b today are absorbed by the 1308Z dispatch. New dispatches only on next Cron fire or Ella override.
+
+---
+
+## 5. Verification Checklist (when iriss-air delivers)
+
+Before marking a delivery `VERIFIED`, run every check. Any fail → NACK back to iriss-air with the failing row.
+
+### 5.1 Envelope (metadata) — v1.1 additions in bold
+
+**Early-exit (v1.1)** — run these FIRST and fail-fast:
+
+1. **Fail-fast grep**: if the file's first 5 lines contain the literal string `PLACEHOLDER — DO NOT VERIFY`, immediately return `NOT DELIVERED`. Do not run any downstream check. (Protects against false-positive ACK of unchanged placeholder.)
+2. **Size comparator**: if `current_size <= placeholder_size_at_dispatch` (recorded in the register row at §4), return `NOT DELIVERED`.
+3. **mtime comparator**: if `file_mtime <= dispatch_time + 60s`, return `NOT DELIVERED` (delivery would have required iriss-air to overwrite the placeholder).
+
+**Transport-integrity canary (v1.1, added 2026-04-17 after XHS-REQ-20260417-1308 transport bug)** — when the delivery header declares an upstream size (e.g. `iriss-air side: 4644 bytes`), compare it to `local_size`. If `|local_size - upstream_size| > 128 bytes`, treat as transport-truncation suspect → do NOT mark `VERIFIED`; request iriss-air re-send via single-message (not inline-split) and log as `TRUNCATED`. Root cause of 2026-04-17 truncation: Option-1 inline-split transport landed 2,031B of a 4,644B payload. Re-send via fresh single-message inline payload succeeded.
+
+Only if all three early-exit checks pass, proceed to the original envelope checks:
+
+- [ ] File landed at the exact `deliverable_path` from the spec (§1 field 8).
+- [ ] File header contains the originating `spec_id` (§1 field 1).
+- [ ] Timestamp in header is within ±30 min of dispatch time (sanity).
+- [ ] Source tool declared (`rednote-reader` on iriss-air — NOT `Chrome`, `Playwright`, `local`).
+- [ ] (v1.1) File does NOT still contain `PLACEHOLDER — DO NOT VERIFY` anywhere (defensive — catches partial overwrites where delivery appended instead of replaced).
+
+### 5.2 Scope compliance
+- [ ] Window matches (§1 field 4) — reject if any record falls outside.
+- [ ] Delta anchor respected — no duplicates of records whose `comment_date < delta_anchor`.
+- [ ] All `targets` (§1 field 6) either appear OR are explicitly listed as "failed/nav-blocked" with reason.
+- [ ] Unrequested targets are NOT present (iriss-air did not silently expand scope).
+
+### 5.3 Record integrity
+- [ ] Every row has every required `field` (§2) — no blanks in required columns.
+- [ ] `comment_date` parseable ISO8601; not in the future.
+- [ ] `is_reply_to_steve` is a real bool (not "maybe" / empty string).
+- [ ] Dedupe key `(post_id, commenter_username, comment_date)` is unique within file.
+- [ ] UTF-8 clean — no mojibake on Chinese text; emoji preserved.
+
+### 5.4 Policy compliance
+- [ ] No reply-bodies, no like-actions, no auth tokens, no cookies in the delivery.
+- [ ] No screenshots outside the `risk-signal` schema (§2.6).
+- [ ] `policy_tags` echoed back in the delivery header.
+- [ ] If `NO NEW <scope>`: delivery is a single-line confirmation matching spec_id — NO stub rows.
+
+### 5.5 Sign-off
+- [ ] Register row moved to `VERIFIED` with a timestamp.
+- [ ] If comments delivered → spawn downstream `analyze + draft replies` task. That task is **local-allowed** (drafting is not interaction).
+- [ ] If metrics delivered → update `reports/xhs-data-tracking-2026-04.md`.
+- [ ] If risk-signal → immediate ping to Ella + Steve (Slack D0AC7NF5N7L).
+
+---
+
+## 6. Escalation / Blocker matrix
+
+| Symptom | Owner | Action |
+|---------|-------|--------|
+| No ACK from `crewly-orc` within SLA | Grace | Mark register `BLOCKED: no-ack`. Notify Ella. Do **not** re-dispatch in <10 min (prevents flooding Rex). |
+| iriss-air reports `rednote-reader` failure | iriss-air team | Register `BLOCKED: upstream-failure`. Do not suggest workarounds. Wait. |
+| Delivery fails §5 checks | Grace | NACK with specific failing check. Register stays `DELIVERED` (not VERIFIED). Await re-delivery. |
+| Login wall / captcha / shadowban signal | Grace | File as `kind: risk-signal`, ping Steve. Never attempt local login. |
+| Anyone requests local Chrome/iPad/Playwright touching XHS | Grace | **Refuse.** Quote this doc §0. File the request as `CANCELLED: policy-breach-attempt` for audit. |
+
+---
+
+## 7. Archive (moved weekly from §4)
+
+*Rows older than the current operating week land here. Next archive pass: Fri 16:00 during Cron #7 weekly report.*
+
+---
+
+## 8. Change log
+
+| Version | Date | Author | Change |
+|---------|------|--------|--------|
+| v1.0 | 2026-04-17 | Grace | Initial draft after Steve's "spec-in / result-out" directive and the 14:13Z proxy-fallback breach. Consolidates ad-hoc dispatch pattern (2026-04-14 → today) into a formal register + verification checklist. |
+| v1.1 | 2026-04-17 | Grace (on Ella TL sign-off) | **SLA recalibration + checklist tightening**. (a) §3 P0 SLA raised from 20 min → 90 min based on observed Rex ~80 min full-scrape runtime (prevents false breach reports on compliant-but-slow jobs). (b) §3 placeholder template now REQUIRES the literal `PLACEHOLDER — DO NOT VERIFY` string in first 5 lines. (c) §5.1 three early-exit checks added (PLACEHOLDER-string grep, size comparator vs placeholder_size_at_dispatch, mtime comparator vs dispatch_time+60s). Triggered by first live test (XHS-REQ-20260417-1308-daily-comments) where v1.0 checklist correctly flagged the placeholder but would have taken longer without a fail-fast signal. |
+| v1.1 (addendum) | 2026-04-17 | Grace (on orc request) | **Transport-integrity canary** added to §5.1. Trigger: the 14:15Z Option-1 inline-split delivery for XHS-REQ-20260417-1308 landed truncated (2,031B local vs 4,644B upstream). Canary spec: if delivery header declares an upstream size and `\|local_size − upstream_size\| > 128 B`, mark `TRUNCATED` and request re-send via single-message (not inline-split). 14:39Z re-send succeeded — verification passed. |
+| **v1.2** | **2026-04-17** | **Grace (on Ella TL sign-off)** | **Tiered SLA — approved.** (a) §1 spec template gains a new REQUIRED field #10 `job_size` with two values: `fast-poll` or `full-scrape`. Selection rule: `fast-poll` = <5 targets AND no comments-scroll; `full-scrape` = ≥5 targets OR comments-scroll OR account-snapshot. (b) §1 `priority` enum split from `P0/P1/P2` → `P0a/P0b/P1/P2`, with a mandatory priority × job_size consistency rule. P0a pairs with fast-poll; P0b pairs with full-scrape. (c) §3 SLA table rewritten as a 4-row matrix with separate early-warning and hard-breach thresholds. Flat v1.1 `P0 ≤ 90 min` is retired; replaced by P0a ≤ 20 min and P0b ≤ 120 min. (d) Mismatch rule added: a spec whose `priority` / `job_size` pairing is inconsistent is NACK'd as `BLOCKED: malformed-spec`. (e) Back-compat: legacy rows recorded with flat `P0` stay valid and are promoted at the next scrub pass. Closes the SOP baseline for spec-in/result-out. |
+| **v1.2 candidate** | *pending Ella ruling* | (orc suggestion, 2026-04-17) | **Tiered SLA proposal**: split P0 into fast-poll (<5 posts) = 20 min and full-scrape (all posts + comments scroll) = 90–120 min. Rationale: single P0 SLA can't fit both lightweight and heavyweight jobs without either over-reporting breach on heavy jobs (v1.0 problem) or under-reporting on light ones (v1.1 risk). Requires adding a `job_size` field to §1 spec template and a P0a/P0b split in §3. Decision deferred to Ella's next SOP review. |

package/config/templates/agent-gemini-md.md

@@ -17,7 +17,9 @@ You are running inside Crewly, a multi-agent orchestration platform.
 2. **Always follow the Code Commit SOP** (9 steps, 3 review rounds) when the team has this norm
 3. **Always write tests** alongside code — one source file = one test file, co-located
 4. **Never run destructive git operations** (checkout --, reset --hard) without stashing first
-5. **Follow project coding standards** defined in CLAUDE.md (TypeScript strict, no hardcoded values, JSDoc comments)
+5. Follow project coding standards defined in CLAUDE.md (TypeScript strict, no hardcoded values, JSDoc comments)
+6. **CRITICAL: Manual Publishing Only** — ALL content publishing on ALL platforms (X, LinkedIn, XHS, etc.) must be done manually by Steve. Agents MUST NOT publish directly via remote-browser or any other tool. Only delivery of content packages to Steve via Slack is allowed. Refer to `config/domain-sops/content-publishing-policy.sop.md`.
+
 
 ## Gemini CLI Notes