crewly 1.6.4 → 1.7.0

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

@@ -74,6 +74,28 @@ shift
 # Load the real shared lib first
 source "${REAL_SKILL_DIR}/../_common/lib.sh"
 
+# Request Contract warning helper (mirror of the real script's
+# warn_missing_request_contract — must stay byte-equivalent so the test
+# exercises actual production logic, not a stub).
+warn_missing_request_contract() {
+  local task="$1"
+  local missing=()
+  if ! echo "$task" | grep -qiE '(^|[^a-zA-Z])(\*\*)?(goal|objective)(:|s?\b)'; then
+    missing+=("Goal")
+  fi
+  if ! echo "$task" | grep -qiE '(^|[^a-zA-Z])(\*\*)?(expected )?outcome(:|s?\b)'; then
+    missing+=("Outcome")
+  fi
+  if ! echo "$task" | grep -qiE '(^|[^a-zA-Z])(\*\*)?(eval|evaluation criteria|acceptance criteria)(:|s?\b)'; then
+    missing+=("Eval")
+  fi
+  if [ ${#missing[@]} -gt 0 ]; then
+    local list
+    list=$(IFS=, ; echo "${missing[*]}")
+    echo "{\"warning\":\"Request Contract incomplete: brief is missing markers for: ${list}. Per P0-3 spec, every delegated subtask MUST include Goal + Expected Outcome + Eval Criteria. Workers may push back via the Brief Reception Protocol. Source: .crewly/specs/2026-05-03-agent-improvement-p0-execution.md §Fix P0-3.\"}" >&2
+  fi
+}
+
 # Track API calls for verification
 API_CALLS_LOG=$(mktemp)
 
@@ -136,6 +158,10 @@ FROM_SESSION=$(echo "$INPUT" | jq -r '.fromSession // empty')
 require_param "to" "$TO"
 require_param "task" "$TASK"
 
+# Request Contract warning (P0-3): emit non-fatal warning when brief is
+# missing Goal / Expected Outcome / Eval markers. Mirror of the real script.
+warn_missing_request_contract "$TASK"
+
 # Validate hierarchy
 if [ -n "$TEAM_ID" ] && [ -n "$TL_MEMBER_ID" ]; then
   TEAM_DATA=$(api_call GET "/teams/${TEAM_ID}" 2>/dev/null || echo '{}')
@@ -393,6 +419,97 @@ assert_fails "fails without 'task'" \
 assert_fails "fails without any input" \
   env -u CREWLY_SESSION_NAME bash "$MOCK_SCRIPT" "$SKILL_DIR" ''
 
+# -----------------------------------------------------------------------
+# Scenario 9 (P0-3): Request Contract warning — emitted when G/O/E missing
+# -----------------------------------------------------------------------
+echo "Scenario 9: Request Contract warning — bare task triggers G+O+E warning"
+RAW_OUTPUT=$(env CREWLY_SESSION_NAME="sam-tl" bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"to":"crewly-product-leo-dev","task":"do something useful"}' 2>&1)
+if echo "$RAW_OUTPUT" | grep -q "Request Contract incomplete"; then
+  echo "  PASS: warning emitted for bare task missing G+O+E"
+  PASS=$((PASS + 1))
+else
+  echo "  FAIL: expected 'Request Contract incomplete' warning, got: $RAW_OUTPUT"
+  FAIL=$((FAIL + 1))
+fi
+
+# -----------------------------------------------------------------------
+# Scenario 10 (P0-3): Warning lists all three missing fields
+# -----------------------------------------------------------------------
+echo "Scenario 10: Warning lists Goal, Outcome, Eval when all three are missing"
+RAW_OUTPUT=$(env CREWLY_SESSION_NAME="sam-tl" bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"to":"crewly-product-leo-dev","task":"refactor things"}' 2>&1)
+if echo "$RAW_OUTPUT" | grep -q "Goal" && \
+   echo "$RAW_OUTPUT" | grep -q "Outcome" && \
+   echo "$RAW_OUTPUT" | grep -q "Eval"; then
+  echo "  PASS: warning enumerates all three missing fields"
+  PASS=$((PASS + 1))
+else
+  echo "  FAIL: expected warning to list Goal+Outcome+Eval, got: $RAW_OUTPUT"
+  FAIL=$((FAIL + 1))
+fi
+
+# -----------------------------------------------------------------------
+# Scenario 11 (P0-3): Warning suppressed when full Request Contract present
+# -----------------------------------------------------------------------
+echo "Scenario 11: No warning when Goal + Expected Outcome + Eval Criteria are all present"
+TASK_WITH_RC="**Goal:** Implement feature X. **Expected Outcome:** Feature works in prod. **Eval Criteria:** All tests pass and demo passes UAT."
+RAW_OUTPUT=$(env CREWLY_SESSION_NAME="sam-tl" bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  "{\"to\":\"crewly-product-leo-dev\",\"task\":\"$TASK_WITH_RC\"}" 2>&1)
+if echo "$RAW_OUTPUT" | grep -q "Request Contract incomplete"; then
+  echo "  FAIL: did not expect warning when G+O+E all present, got: $RAW_OUTPUT"
+  FAIL=$((FAIL + 1))
+else
+  echo "  PASS: no warning emitted when contract is complete"
+  PASS=$((PASS + 1))
+fi
+
+# -----------------------------------------------------------------------
+# Scenario 12 (P0-3): Partial contract — only Goal present, warns about Outcome+Eval
+# -----------------------------------------------------------------------
+echo "Scenario 12: Partial contract — names only the missing field(s)"
+RAW_OUTPUT=$(env CREWLY_SESSION_NAME="sam-tl" bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"to":"crewly-product-leo-dev","task":"**Goal:** ship X. Just do it."}' 2>&1)
+if echo "$RAW_OUTPUT" | grep -q "Request Contract incomplete" && \
+   echo "$RAW_OUTPUT" | grep -q "Outcome" && \
+   echo "$RAW_OUTPUT" | grep -q "Eval"; then
+  echo "  PASS: warning emitted, names Outcome+Eval as missing"
+  PASS=$((PASS + 1))
+else
+  echo "  FAIL: expected partial-contract warning, got: $RAW_OUTPUT"
+  FAIL=$((FAIL + 1))
+fi
+
+# -----------------------------------------------------------------------
+# Scenario 13 (P0-3): Warning is non-fatal — delegation still succeeds
+# -----------------------------------------------------------------------
+echo "Scenario 13: Warning is non-fatal — delegation completes despite missing G+O+E"
+RAW_OUTPUT=$(env CREWLY_SESSION_NAME="sam-tl" bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  '{"to":"crewly-product-leo-dev","task":"unstructured task"}' 2>&1)
+OUTPUT=$(echo "$RAW_OUTPUT" | grep '"monitoring"' | head -1)
+if echo "$OUTPUT" | jq -e '.success' > /dev/null 2>&1; then
+  echo "  PASS: delegation succeeds despite missing contract markers"
+  PASS=$((PASS + 1))
+else
+  echo "  FAIL: warning should be non-fatal, but delegation appears to have failed: $RAW_OUTPUT"
+  FAIL=$((FAIL + 1))
+fi
+
+# -----------------------------------------------------------------------
+# Scenario 14 (P0-3): Acceptance Criteria synonym recognized as Eval marker
+# -----------------------------------------------------------------------
+echo "Scenario 14: 'Acceptance Criteria' counts as the Eval marker"
+TASK_AC="**Goal:** ship Y. **Expected Outcome:** Y in prod. **Acceptance Criteria:** UAT pass."
+RAW_OUTPUT=$(env CREWLY_SESSION_NAME="sam-tl" bash "$MOCK_SCRIPT" "$SKILL_DIR" \
+  "{\"to\":\"crewly-product-leo-dev\",\"task\":\"$TASK_AC\"}" 2>&1)
+if echo "$RAW_OUTPUT" | grep -q "Request Contract incomplete"; then
+  echo "  FAIL: did not expect warning when Acceptance Criteria stands in for Eval, got: $RAW_OUTPUT"
+  FAIL=$((FAIL + 1))
+else
+  echo "  PASS: Acceptance Criteria recognized as valid Eval marker"
+  PASS=$((PASS + 1))
+fi
+
 # Cleanup
 rm -rf "$MOCK_DIR"
 

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

@@ -13,10 +13,14 @@ 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\":\"...\",\"taskPath\":\"...\",\"workerId\":\"...\",\"teamId\":\"...\",\"projectPath\":\"...\",\"templateId\":\"dev-fullstack\",\"checks\":[...]}'"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"workItemId\":\"...\",\"workerId\":\"...\",\"teamId\":\"...\",\"projectPath\":\"...\",\"templateId\":\"dev-fullstack\",\"checks\":[...]}'"
 
-TASK_ID=$(printf '%s' "$INPUT" | jq -r '.taskId // empty')
-TASK_PATH=$(printf '%s' "$INPUT" | jq -r '.taskPath // empty')
+# `taskId` is accepted as a backwards-compat alias for `workItemId`. The
+# v1 filesystem-based `taskPath` input is no longer accepted — fetch the
+# WorkItem via `GET /api/task-pool/items/:id` instead. See spec
+# 2026-05-06-task-management-v1-deprecation.md.
+WORK_ITEM_ID=$(printf '%s' "$INPUT" | jq -r '.workItemId // .taskId // empty')
+TASK_ID="$WORK_ITEM_ID"
 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')
@@ -24,25 +28,20 @@ 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
-if [ -z "$TASK_PATH" ] && [ -z "$TASK_ID" ]; then
-  error_exit "Either taskPath or taskId is required"
-fi
+require_param "workItemId (or taskId)" "$WORK_ITEM_ID"
 
-# Read task output if taskPath is provided
+# Fetch the WorkItem (brief, output) in a single call.
 TASK_OUTPUT=""
-if [ -n "$TASK_PATH" ]; then
-  TASK_READ_BODY=$(jq -n --arg taskPath "$TASK_PATH" '{taskPath: $taskPath}')
-  TASK_DATA=$(api_call POST "/task-management/read-task" "$TASK_READ_BODY" 2>/dev/null || echo '{}')
-  TASK_OUTPUT=$(echo "$TASK_DATA" | jq -r '.data.content // empty' 2>/dev/null || true)
-fi
+WI_DATA=$(api_call GET "/task-pool/items/${WORK_ITEM_ID}" 2>/dev/null || echo '{}')
+WI_BRIEF=$(echo "$WI_DATA" | jq -r '.data.briefMarkdown // empty' 2>/dev/null || true)
+WI_OUTPUT_RAW=$(echo "$WI_DATA" | jq -c '.data.output // empty' 2>/dev/null || true)
 
-# If taskId is provided, try to get output from task tracking
-if [ -n "$TASK_ID" ]; then
-  OUTPUT_BODY=$(jq -n --arg taskId "$TASK_ID" '{taskId: $taskId}')
-  OUTPUT_DATA=$(api_call POST "/task-management/get-output" "$OUTPUT_BODY" 2>/dev/null || echo '{}')
-  TASK_OUTPUT_FROM_ID=$(echo "$OUTPUT_DATA" | jq -r '.data.output // empty' 2>/dev/null || true)
-  [ -z "$TASK_OUTPUT" ] && TASK_OUTPUT="$TASK_OUTPUT_FROM_ID"
+# Compose `TASK_OUTPUT` for content-scan checks. Prefer worker-supplied
+# structured output, falling back to the brief if no output was set.
+if [ -n "$WI_OUTPUT_RAW" ] && [ "$WI_OUTPUT_RAW" != "null" ] && [ "$WI_OUTPUT_RAW" != "" ]; then
+  TASK_OUTPUT="$WI_OUTPUT_RAW"
+elif [ -n "$WI_BRIEF" ]; then
+  TASK_OUTPUT="$WI_BRIEF"
 fi
 
 # =============================================================================
@@ -70,7 +69,7 @@ if [ -n "$CHECKLIST_PATH" ] && [ -f "$CHECKLIST_PATH" ]; then
 
     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
+    echo '{"error":"Checklist exists but is not approved (status: '"$CHECKLIST_STATUS"'). Approve first via POST /api/checklists/'$TASK_ID'/approve"}' >&2
     # Fall through to template/inline checks
   fi
 

package/config/slack-app-manifest.json

@@ -20,7 +20,8 @@
         "groups:history",
         "im:history",
         "mpim:history",
-        "users:read"
+        "users:read",
+        "reactions:write"
       ]
     }
   },

package/config/sops/common/dev-process-tiers.md

@@ -0,0 +1,181 @@
+---
+id: common-dev-process-tiers
+version: 1
+createdAt: 2026-05-03T00:00:00Z
+updatedAt: 2026-05-03T00:00:00Z
+createdBy: leo
+role: all
+category: process
+priority: 9
+title: Development Process Tiers
+description: Pick the right development rigor for the work — Fast, Standard, or Release Path — based on customer-facing risk, reversibility, and audience.
+triggers:
+  - which tier
+  - dev process
+  - process tier
+  - fast path
+  - release path
+  - rigor
+  - tiering
+  - greenfield
+  - customer-facing
+tags:
+  - process
+  - delivery
+  - quality
+  - tiering
+---
+
+# Development Process Tiers
+
+Crewly delivery uses three tiers. Pick a tier per task — not per repo, not per agent. The tier decides how much rigor (tests, review, gates, docs) the work requires.
+
+**Hard rule:** Default to the higher tier when in doubt. It is cheaper to over-rigor a 30-minute task than to under-rigor a customer-facing change.
+
+---
+
+## Decision matrix (use this to pick a tier)
+
+| Question | Yes → at least Standard | Yes → Release Path |
+|---|---|---|
+| Touches a customer-facing surface (UI, public API, marketing site, billing, auth)? | ✅ |  |
+| Touches data persistence (schema, migration, durable storage)? | ✅ |  |
+| Touches money, security, identity, or compliance? |  | ✅ |
+| Reversible without user-visible impact within minutes? | (No → at least Standard) |  |
+| Cuts a public release (npm publish, docker tag, web deploy to crewlyai.com)? |  | ✅ |
+| Greenfield internal exploration / spike / prototype? | (No → use Fast) |  |
+| Internal tooling / agent prompt / SOP / dev-only script? | (Often Fast is correct) |  |
+
+**Default selection rule:**
+- Greenfield internal work, prototypes, internal tooling → **Fast**
+- Customer-facing OR persistence OR shared infra → **Standard**
+- Money / security / identity / compliance / public release cut → **Release Path**
+
+If two rules disagree, the higher tier wins.
+
+---
+
+## Tier 1 — Fast Path
+
+**Purpose:** Rapid iteration on internal-only or exploratory work where the cost of being wrong is low and the work can be unwound quickly.
+
+**Use when:**
+- Greenfield prototype or spike (no users yet).
+- Internal tooling (CLI flags, dev scripts, debug overlays).
+- Agent prompt / SOP / role-config tweak with rollback by file revert.
+- Internal dashboard or admin-only view.
+
+**Required:**
+1. Build green (`npm run build`).
+2. Tests for new logic that has branching behavior. Trivial config / prompt changes need at least one rendering / parse test.
+3. One reviewer (any teammate, async OK) — TL waiver allowed for solo-owned modules.
+4. PR description states **why** in plain language.
+
+**Skipped vs Standard:**
+- No mandatory integration test.
+- No mandatory eval criteria pre-write — eval can be implicit ("does it run, does it not crash").
+- No release notes / CHANGELOG entry needed.
+- No staged rollout.
+
+**Typical merge latency:** Same-day. Self-merge after one approval.
+
+---
+
+## Tier 2 — Standard Path
+
+**Purpose:** The default tier for any work that touches a customer-facing surface, durable data, or shared infrastructure. Most product work lives here.
+
+**Use when:**
+- Customer-facing UI change (Crewly Cloud, web portal, desktop app).
+- Public API behavior change (request/response shape, status codes, headers).
+- Database schema change or migration.
+- Shared service / library used by more than one component.
+- Bug fix that affects user behavior.
+
+**Required:**
+1. Build green AND `npm run typecheck` AND `npm run lint`.
+2. Tests at unit + integration level. 1:1 source-to-test ratio (per `crewly/CLAUDE.md`).
+3. Eval criteria in PR description (testable list — how we know this is good enough).
+4. One TL or senior reviewer + one peer reviewer.
+5. CHANGELOG entry if user-visible.
+6. Manual smoke test of the changed flow before merge.
+7. Rollback plan stated in PR description (how to revert + what data state requires fixup).
+
+**Skipped vs Release Path:**
+- No staged rollout (merge-and-deploy together).
+- No formal security review unless `category: security`.
+- No marketing / pricing / docs sign-off.
+
+**Typical merge latency:** 1–2 days. Reviewer acceptance gates merge.
+
+---
+
+## Tier 3 — Release Path
+
+**Purpose:** Cuts a public release or touches money / security / identity / compliance. Mistakes are expensive — pricing miscalculations, data loss, account takeover, license bypass.
+
+**Use when:**
+- Cutting a public release (npm publish, docker image promote, crewlyai.com deploy, desktop installer).
+- Stripe / billing / pricing logic.
+- Authentication, authorization, license verification, JWT / OAuth flows.
+- PII / customer data handling, encryption, key management.
+- Compliance-relevant change (GDPR, SOC, retention policies).
+
+**Required (everything in Standard, plus):**
+1. **Eval criteria written and approved BEFORE coding starts.** TL signs off the eval.
+2. **Two TL-or-higher reviewers**, one of whom must be different team if cross-team impact.
+3. **Pre-publish verification SOP** (`config/sops/developer/git-workflow.md` Code Commit SOP) — 9-step / 3-review-round flow is mandatory.
+4. **Staged rollout** — internal flag, then 10%, then 100%, with abort criteria documented.
+5. **Smoke tests on staging environment** before production cut.
+6. **Owner approval of release notes / pricing copy / customer messaging.** No silent change to anything customer-visible.
+7. **Rollback rehearsal** — verify the rollback path works on staging before production cut.
+8. **Post-deploy monitoring window** (4 hours minimum) with named on-call.
+
+**Typical merge latency:** 3–5 days. No same-day cuts unless explicit owner override for a P0 hotfix (which itself follows the security-hotfix branch pattern).
+
+---
+
+## How to declare your tier
+
+In every PR description, include:
+
+```markdown
+**Tier:** Fast | Standard | Release Path
+**Why this tier:** <one sentence — which rule above applied>
+```
+
+A reviewer who disagrees with the tier choice can block the PR with a re-tier comment. If TL flips the tier from Fast → Standard, the author MUST add the missing tier-2 deliverables before merge.
+
+---
+
+## When tier is ambiguous
+
+Ask the TL. Do not default downward. The TL's call is final unless owner overrides.
+
+Common ambiguity examples and their resolution:
+
+| Case | Tier | Reason |
+|---|---|---|
+| Internal SOP doc that gets loaded into agent prompts | Standard | Affects every agent's behavior; rollback is per-file but blast radius is wide. |
+| Adding a new agent role used only by one team | Fast | Greenfield, scoped to that team. |
+| Bumping a public npm package version | Release Path | Public release cut. |
+| Changing a CLI flag default | Standard | User-visible behavior change. |
+| Refactor that is pure type-level with no runtime effect | Fast | Reversible, no user impact. |
+| Adding a new column to an existing migration | Release Path | Schema + data persistence. |
+
+---
+
+## Anti-patterns
+
+- Picking Fast because "the change is small." Size is not tier. Risk and audience are tier.
+- Picking Standard to avoid the Release Path checklist on a billing change. Billing is always Release Path.
+- Picking Release Path to look thorough on an internal prototype. Over-rigor blocks the team.
+- Splitting one Release Path change across multiple Fast PRs to dodge review. Reviewers will reject and re-tier.
+
+---
+
+## See also
+
+- `config/sops/developer/git-workflow.md` — Code Commit SOP, branch naming, worktrees
+- `config/sops/developer/coding-standards.md` — language-level standards
+- `config/sops/common/blocker-handling.md` — when stuck, escalate

package/config/sops/common/mid-flight-milestone-surface.md

@@ -0,0 +1,128 @@
+---
+id: common-mid-flight-milestone-surface
+version: 1
+createdAt: 2026-05-16T00:00:00Z
+updatedAt: 2026-05-16T00:00:00Z
+createdBy: system
+updatedBy: system
+role: common
+category: communication
+priority: 8
+title: Mid-Flight Milestone Surface
+description: When you ship a milestone inside an active goal, surface it upstream immediately — do not wait for the next outcome-check tick.
+triggers:
+  - milestone
+  - report-status
+  - PR merged
+  - spec finalized
+  - build pass
+  - deploy succeeded
+tags:
+  - communication
+  - proactive
+  - milestone
+  - silent-shipping
+---
+
+# Mid-Flight Milestone Surface
+
+When you ship a milestone INSIDE an active goal — a PR merged, a spec
+finalized, a build pass on a non-trivial change, a dependency
+unblocked, a deploy succeeded — do **NOT** wait for the next
+outcome-check tick or for someone to ask. Surface it now.
+
+This SOP is the **symmetric agent-side rule** to the orchestrator's
+periodic check-in cadence (PR #418). The orc surfaces upward to the
+owner on a 15-min cadence; agents surface upward to the orc the
+moment they have something concrete to report. Issue #427 / EPIC
+#426 documented that worker / TL prompts had **zero** "milestone"
+keyword across 21 role prompts — the system was structurally silent
+on this path.
+
+## The rule
+
+Immediately call the `report-status` skill with:
+
+- `status: "milestone"` — the explicit verb introduced by issue #435 /
+  PR adding `[MILESTONE]` envelope to `report-status`.
+- `summary` — plain-language **WHAT shipped** + **one-line
+  WHAT-IT-MEANS-FOR-OWNER**. Optimize for someone scanning Slack on
+  their phone.
+- `artifacts` — the canonical link (PR URL, spec path, deploy id).
+  If there's no artifact, the milestone probably isn't one.
+
+The orchestrator's Smart Notification Protocol has a dedicated
+`[MILESTONE]` row in the priority table (issue #436) that promotes
+the surface to 🟡 Important — always notify, never downgraded to
+⚪ Info even if the outer outcome isn't fully met yet.
+
+## What counts as a milestone
+
+- PR merged
+- Spec finalized + handed off
+- Build pass on a non-trivial change (e.g. cross-module refactor
+  that compiles for the first time)
+- Dependency unblocked (the thing you were waiting on now exists)
+- Deploy succeeded
+- Verification gate passed (e.g. an integration test you wrote went
+  green for the first time)
+
+## What does NOT count
+
+- "task done" without context (no `summary` body) — every dispatch
+  produces a "task done" event, those flow through the existing
+  task-pool path and don't need separate `[MILESTONE]` surfacing.
+- Internal progress checkpoints (40% of the way through, 80% of the
+  way through). Those are status updates, not milestones.
+- The same milestone re-surfaced. Once is enough.
+
+## Examples
+
+✅ **Good**:
+
+- "PR #420 merged — agent state file is now corruption-resistant +
+  auto-snapshots every 30s. Persistence-loss risk on crash drops from
+  'all session memory' to 'last 30s only'. No action needed."
+
+- "Onboarding cold-start state machine merged (PR #409). End-to-end
+  5-min activation path is now in code. Real-user dry-run still
+  pending."
+
+❌ **Bad — do not emit**:
+
+- "task done"
+- "Progress update: 80%"
+- "Working on it"
+- "Will continue tomorrow" (without specifying what shipped)
+
+## How orc handles it
+
+When the `[MILESTONE]` envelope arrives, the orchestrator:
+
+1. Recognizes the explicit `[MILESTONE]` marker from the priority
+   table (issue #436) — classified as 🟡 Important.
+2. Surfaces to the owner via the trust-adaptive channel (chat-v2
+   `[NOTIFY]` or Slack reply-thread, depending on origin).
+3. Never downgrades to ⚪ Info even if the outer outcome (OKR /
+   request) isn't yet fully complete.
+
+The auditor's "Silent Shipping Detection" monitor (issue #437)
+cross-references `git log` against `report-status` / `[MILESTONE]`
+events and flags any merged PR whose author did not emit a milestone
+surface within 30 minutes of merge.
+
+## Where this SOP applies
+
+All roles that ship artifacts: developer, frontend-developer,
+fullstack-dev, qa, qa-engineer, product-manager, tpm, designer,
+ux-designer, architect, team-leader, generalist. The orc and the
+auditor consume the surface; they don't emit it.
+
+## Refs
+
+- EPIC #426 — Proactive-followup gap audit
+- RC1 #427 — Worker/TL prompts contain zero milestone keyword
+- QW-1 #434 — This SOP
+- QW-2 #435 — `[MILESTONE]` envelope in `report-status` skill
+- QW-3 #436 — `[MILESTONE]` row in orc priority table
+- QW-4 #437 — Auditor Silent Shipping Detection monitor