crewly 1.20.392 → 1.20.394

package/config/constants.ts

@@ -1666,6 +1666,22 @@ export const PROJECT_TICKET_CONSTANTS = {
  * runs in CI (`.github/workflows/oss-boundary.yml`) and inside the jest suite.
  * Every path here is relative to the repository root.
  */
+/**
+ * Rule metadata (issue #877): every SOP records the failure it prevents, the
+ * model where that was seen, and a review date — so rules can be re-tested
+ * and deleted when they stop making a difference.
+ */
+export const RULE_METADATA_CONSTANTS = {
+	/** Directory of SOP files whose frontmatter is audited */
+	SOPS_DIR: 'config/sops',
+	/** The three frontmatter fields (plus the optional `source` link) */
+	FIELDS: { PREVENTS: 'prevents', SEEN_ON: 'seenOn', REVIEW_BY: 'reviewBy', SOURCE: 'source' } as const,
+	/** Share of SOPs that must carry all three fields for the check to pass */
+	MIN_COVERAGE: 0.8,
+	/** `prevents` starts with this when no failure was ever recorded for the rule */
+	NO_RECORDED_FAILURE: 'none recorded',
+} as const;
+
 export const OSS_BOUNDARY_CONSTANTS = {
 	/** Allowlist of explicit exceptions; every entry carries a one-line reason */
 	ALLOWLIST_FILE: 'config/oss-boundary-allowlist.json',

package/config/index.ts

@@ -43,6 +43,7 @@ import {
   EVENT_DEBOUNCE_MS,
   CLOUD_DEVICE_PAIRING_CONSTANTS,
   OSS_BOUNDARY_CONSTANTS,
+  RULE_METADATA_CONSTANTS,
 
   // Type helpers
   type AgentStatus,
@@ -75,6 +76,7 @@ export {
   EVENT_DEBOUNCE_MS,
   CLOUD_DEVICE_PAIRING_CONSTANTS,
   OSS_BOUNDARY_CONSTANTS,
+  RULE_METADATA_CONSTANTS,
 
   // Type helpers
   type AgentStatus,

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

@@ -49,6 +49,9 @@ Mark a task as complete with a summary of the work done. If the task has an outp
 | `evidence` | Yes* | Array of evidence entries — see **Evidence contract** below. *Required: refused without it (400 `evidence_required`), except a review `verdict` |
 | `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) |
+| `decisions` | No | Array of short strings: the key decisions you made — see **Decision record** below |
+| `notTaken` | No | Array of short strings: options you considered and did not take, each with the reason |
+| `assumptions` | No | Array of short strings: what you relied on without checking |
 | `taskKind` | No | What kind of task this was (`revision`, `new-build`, `new-capability`, `research`, `review`, or your own kebab-case word). Used for task timing; without it the kind named in `report-progress`, then the title, decides |
 | ~~`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. |
 
@@ -92,6 +95,21 @@ naming the bad entry. A completion with no evidence is refused with 400
 `evidence_required` and nothing is completed (#1312).
 A review verdict (`verdict` set) needs no evidence.
 
+## Decision record (#875)
+
+Evidence shows the work exists; the record shows how you got there. Send any
+of `decisions`, `notTaken`, `assumptions` as arrays of short strings (one
+sentence each). The reviewer sees them in the Verify item under "Worker's
+record" and checks that they hold — a wrong assumption or a road not taken
+for a bad reason is a reason to send the work back, even when every test
+passes. Leave a field out when there is nothing to say; an empty list is fine.
+
+```json
+"decisions":["Kept the v1 schema; the new field goes in metadata"],
+"notTaken":["A new table — needs a migration the owner has not approved"],
+"assumptions":["The relay runs 1.5.24 in production (checked the compose file, not the container)"]
+```
+
 ## Example
 
 ```bash

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

@@ -35,7 +35,7 @@ SUMMARY=$(printf '%s' "$INPUT" | jq -r '.summary // empty')
 # ignoring a field is the worst disposition: the caller believes it did
 # something, and nothing ever fails. So every field this skill does not use
 # fails loudly, with its name, before any request is sent.
-ALLOWED_FIELDS='["workItemId","absoluteTaskPath","sessionName","summary","output","evidence","verdict","feedback","checks","taskId","artifacts","testResults","structured","taskKind"]'
+ALLOWED_FIELDS='["workItemId","absoluteTaskPath","sessionName","summary","output","evidence","verdict","feedback","checks","taskId","artifacts","testResults","structured","taskKind","decisions","notTaken","assumptions"]'
 SKIP_GATES=$(printf '%s' "$INPUT" | jq -r 'has("skipGates")')
 if [ "$SKIP_GATES" = "true" ]; 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."
@@ -59,6 +59,18 @@ EVIDENCE_JSON=$(printf '%s' "$INPUT" | jq -c '.evidence // empty')
 if [ -n "$EVIDENCE_JSON" ] && [ "$(printf '%s' "$EVIDENCE_JSON" | jq -r 'type')" != "array" ]; then
   error_exit "evidence must be a JSON array of entries, e.g. [{\"type\":\"artifact\",\"path\":\"/abs/file\"},{\"type\":\"command\",\"command\":\"npm test\",\"exitCode\":0}] — or [{\"type\":\"blocked\",\"step\":\"...\",\"reason\":\"...\"}] if you could not finish"
 fi
+# Decision record (#875): the key decisions made, the options considered and
+# not taken (with the reason), the assumptions relied on. Each is optional, a
+# JSON array of short strings (a lone string is accepted as one entry). The
+# reviewer reads them beside the evidence in the Verify item.
+DECISIONS_JSON=$(printf '%s' "$INPUT" | jq -c '
+  def list(k): if has(k) then (if (.[k] | type) == "string" then [.[k]] elif (.[k] | type) == "array" then .[k] else "bad" end) else null end;
+  {decisions: list("decisions"), notTaken: list("notTaken"), assumptions: list("assumptions")}
+  | with_entries(select(.value != null))')
+BAD_DECISION_FIELD=$(printf '%s' "$DECISIONS_JSON" | jq -r 'to_entries[] | select(.value == "bad" or (.value | type) == "array" and ([.value[] | select(type != "string")] | length) > 0) | .key' | head -1)
+if [ -n "$BAD_DECISION_FIELD" ]; then
+  error_exit "${BAD_DECISION_FIELD} must be a JSON array of strings, e.g. \"${BAD_DECISION_FIELD}\":[\"Kept the v1 schema; a new table needs a migration\"]. Nothing was completed."
+fi
 # Reviewing someone's work (a "Verify: …" item): `verdict: "rejected"` plus
 # `feedback` sends it back — the worker gets a retry carrying the feedback.
 # Anything else (or nothing) accepts it.
@@ -187,6 +199,7 @@ BODY=$(jq -n \
   --argjson evidence "${EVIDENCE_JSON:-null}" \
   --argjson checks "${CHECKS_JSON:-null}" \
   --arg taskKind "$TASK_KIND" \
+  --argjson decisions "${DECISIONS_JSON:-{\}}" \
   '{
     agentId: $agentId,
     result: ({summary: $summary}
@@ -197,7 +210,8 @@ BODY=$(jq -n \
               + (if $feedback != "" then {feedback: $feedback} else {} end)
               + (if $evidence != null then {evidence: $evidence} else {} end)
               + (if $checks != null then {checks: $checks} else {} end)
-              + (if $taskKind != "" then {taskKind: $taskKind} else {} end))
+              + (if $taskKind != "" then {taskKind: $taskKind} else {} end)
+              + $decisions)
   }')
 
 COMPLETE_RESPONSE=$(api_call POST "/task-pool/complete/${WORK_ITEM_ID}" "$BODY")

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

@@ -328,6 +328,24 @@ KIND_BODY="$(printf '%s' "$BODIES" | grep 'agentId' | head -1 || true)"
 assert_contains "taskKind rides inside result" "revision" "$(printf '%s' "$KIND_BODY" | jq -r '.result.taskKind // empty')"
 assert_contains "the timing line reaches the agent" '"timing":"This was a revision. It took 18 min."' "$(printf '%s' "$OUT" | tail -1)"
 
+echo ""
+echo "--- Decision record (#875): decisions / notTaken / assumptions ride inside result ---"
+
+run_skill '{"workItemId":"wi-rec","sessionName":"dev-1","summary":"done","decisions":["Kept the v1 schema"],"notTaken":"A new table — needs a migration","assumptions":["Relay is on 1.5.24"]}'
+assert_not_contains "the decision fields are accepted" "does not accept" "$OUT"
+REC_BODY="$(printf '%s' "$BODIES" | grep 'agentId' | head -1 || true)"
+assert_contains "decisions ride inside result" "Kept the v1 schema" "$(printf '%s' "$REC_BODY" | jq -r '.result.decisions[0] // empty')"
+assert_contains "a lone string becomes a one-entry list" "A new table" "$(printf '%s' "$REC_BODY" | jq -r '.result.notTaken | if type == "array" then .[0] else "NOT_A_LIST" end')"
+assert_contains "assumptions ride inside result" "Relay is on 1.5.24" "$(printf '%s' "$REC_BODY" | jq -r '.result.assumptions[0] // empty')"
+
+run_skill '{"workItemId":"wi-rec2","sessionName":"dev-1","summary":"done"}'
+PLAIN_BODY="$(printf '%s' "$BODIES" | grep 'agentId' | head -1 || true)"
+assert_not_contains "no record sent -> no record fields in the body" "decisions" "$PLAIN_BODY"
+
+run_skill '{"workItemId":"wi-rec3","sessionName":"dev-1","summary":"done","decisions":[{"what":"object"}]}'
+assert_contains "a non-string entry is refused by name" "decisions must be a JSON array of strings" "$OUT"
+assert_not_contains "a refused record completes nothing" "agentId" "$BODIES"
+
 rm -rf "$STUB_DIR"
 
 echo ""

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

@@ -1,6 +1,6 @@
 #!/bin/bash
 # get-my-active-work — fetch the live Request + WorkItem briefing for this
-# agent. Backs the recovery protocol's Step 1.5 freshness escape hatch:
+# agent. Backs the recovery protocol's Step 2 freshness escape hatch:
 # the startup briefing is already injected at registration time, but a
 # long-running session can call this skill to refresh after the snapshot
 # ages out (e.g. >5min after registration).

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

@@ -47,6 +47,11 @@ Retrieve your accumulated context including memories, learnings, and project kno
 | `agentId` | Yes | Your agent ID |
 | `agentRole` | Yes | Your role (e.g., `"developer"`, `"qa"`) |
 | `projectPath` | Yes | Absolute path to the current project |
+| `context` | No | What to recall for (`--context`). Default: `"<role> agent context for current work"`. At startup pass `"<role> session startup, recent tasks, unfinished work, blockers, key decisions"` |
+
+This skill **includes your memory recall** (plus goals, focus, today's log, learnings
+and your task timings). Do not run `recall` as well at startup — that is the same
+search twice (#857).
 
 ## Example
 

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

@@ -18,6 +18,8 @@ Options:
   --agent    | -a   Agent session name/ID (required)
   --role     | -r   Agent role: product-manager, developer, etc. (required)
   --project  | -p   Project root path (required)
+  --context  | -c   What to recall for (optional; default: "<role> agent context for current work").
+                    This is your ONE memory search at startup — do not run recall as well (#857)
   --json     | -j   Raw JSON payload (same as legacy)
   --help     | -h   Show this help
 EOF_USAGE
@@ -27,6 +29,7 @@ INPUT_JSON=""
 AGENT_ID=""
 AGENT_ROLE=""
 PROJECT_PATH=""
+RECALL_CONTEXT=""
 
 # Detect legacy JSON argument as the first parameter
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
@@ -48,6 +51,10 @@ while [[ $# -gt 0 ]]; do
       PROJECT_PATH="$2"
       shift 2
       ;;
+    --context|-c)
+      RECALL_CONTEXT="$2"
+      shift 2
+      ;;
     --json|-j)
       INPUT_JSON="$2"
       shift 2
@@ -85,6 +92,7 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$AGENT_ID" ] && AGENT_ID=$(printf '%s' "$INPUT" | jq -r '.agentId // empty')
   [ -z "$AGENT_ROLE" ] && AGENT_ROLE=$(printf '%s' "$INPUT" | jq -r '.agentRole // empty')
   [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+  [ -z "$RECALL_CONTEXT" ] && RECALL_CONTEXT=$(printf '%s' "$INPUT" | jq -r '.context // empty')
 fi
 
 require_param "agentId (--agent)" "$AGENT_ID"
@@ -95,6 +103,8 @@ BODY=$(jq -n \
   --arg agentId "$AGENT_ID" \
   --arg agentRole "$AGENT_ROLE" \
   --arg projectPath "$PROJECT_PATH" \
-  '{agentId: $agentId, agentRole: $agentRole, projectPath: $projectPath}')
+  --arg context "$RECALL_CONTEXT" \
+  '{agentId: $agentId, agentRole: $agentRole, projectPath: $projectPath}
+   + (if $context != "" then {context: $context} else {} end)')
 
 api_call POST "/memory/my-context" "$BODY"

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

@@ -38,7 +38,7 @@ execution:
 
 # Get My Tasks
 
-Retrieve all tasks assigned to your current agent session for a specific project. This includes tasks in `open`, `in_progress`, and `done` states.
+Retrieve the tasks assigned to your current agent session. By default only **open** work comes back (queued, scheduled, proposed, accepted, running, blocked, escalated, done_by_worker, rejected); pass `--all` for finished tasks too. At startup your `## Your Active Work` section already has this — don't call it on top (#857).
 
 ## Parameters
 
@@ -46,6 +46,7 @@ Retrieve all tasks assigned to your current agent session for a specific project
 |------|-----------|----------|-------------|
 | `--session` / `-s` | `sessionName` | Yes | Your agent session name |
 | `--project` / `-p` | `projectPath` | Yes | Absolute path to the current project |
+| `--all` | `all` | No | Include finished tasks (verified / done / failed / cancelled) |
 
 ## Examples — CLI Flags (preferred)
 

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

@@ -17,6 +17,7 @@ Usage:
 Options:
   --session  | -s   Agent session name (required)
   --project  | -p   Project root path (required)
+  --all             Include finished tasks (verified/done/failed/cancelled). Default: open work only (#857)
   --json     | -j   Raw JSON payload (same as legacy)
   --help     | -h   Show this help
 EOF_USAGE
@@ -25,6 +26,7 @@ EOF_USAGE
 INPUT_JSON=""
 SESSION_NAME=""
 PROJECT_PATH=""
+INCLUDE_ALL="false"
 
 # Detect legacy JSON argument as the first parameter
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
@@ -42,6 +44,10 @@ while [[ $# -gt 0 ]]; do
       PROJECT_PATH="$2"
       shift 2
       ;;
+    --all)
+      INCLUDE_ALL="true"
+      shift
+      ;;
     --json|-j)
       INPUT_JSON="$2"
       shift 2
@@ -78,6 +84,7 @@ if [ -n "$INPUT_JSON" ]; then
   INPUT=$(read_json_input "$INPUT_JSON")
   [ -z "$SESSION_NAME" ] && SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
   [ -z "$PROJECT_PATH" ] && PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
+  [ "$INCLUDE_ALL" = "false" ] && INCLUDE_ALL=$(printf '%s' "$INPUT" | jq -r 'if .all == true then "true" else "false" end')
 fi
 
 require_param "sessionName (--session)" "$SESSION_NAME"
@@ -85,8 +92,15 @@ require_param "sessionName (--session)" "$SESSION_NAME"
 # for backwards compat with callers who pass it.
 
 # 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")`.
+# queries the V3 task-pool. By default it returns the WorkItems targeted at
+# this agent session that are still open (#857: one startup pulled 472 items /
+# 194 KB, mostly long-verified); `--all` adds the finished ones. Callers
+# wanting only the running one can filter on
+# `.workItems[] | select(.status=="running")`.
+OPEN_STATUSES="queued,scheduled,proposed,accepted,running,blocked,escalated,done_by_worker,rejected"
 ENCODED_SESSION=$(printf '%s' "$SESSION_NAME" | jq -sRr @uri)
-api_call GET "/task-pool/items?target=${ENCODED_SESSION}"
+if [ "$INCLUDE_ALL" = "true" ]; then
+  api_call GET "/task-pool/items?target=${ENCODED_SESSION}"
+else
+  api_call GET "/task-pool/items?target=${ENCODED_SESSION}&status=${OPEN_STATUSES}"
+fi

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

@@ -43,6 +43,10 @@ WI_OUTPUT_RAW=$(echo "$WI_DATA" | jq -c '.data.output // empty' 2>/dev/null || t
 # or on an item completed before #1312 — so it is not verified on its summary alone.
 WI_FOUND=$(echo "$WI_DATA" | jq -r 'if (.data // null) != null then "yes" else "no" end' 2>/dev/null || echo "no")
 WI_EVIDENCE=$(echo "$WI_DATA" | jq -c 'if (.data.output.evidence | type) == "array" then .data.output.evidence else [] end' 2>/dev/null || echo '[]')
+# The worker's decision record (#875): decisions, options not taken, assumptions.
+# Shown to the reviewer as `record`; null when the worker sent none.
+WI_RECORD=$(echo "$WI_DATA" | jq -c '.data.output | {decisions, notTaken, assumptions} | with_entries(select(.value != null)) | if length == 0 then null else . end' 2>/dev/null || echo 'null')
+[ -z "$WI_RECORD" ] && WI_RECORD=null
 EVIDENCE_WARNING=""
 if [ "$WI_FOUND" = "yes" ]; then
   if [ "$(printf '%s' "$WI_EVIDENCE" | jq 'length')" = "0" ]; then
@@ -349,6 +353,7 @@ fi
 jq -n \
   --argjson evidence "$WI_EVIDENCE" \
   --arg evidenceWarning "$EVIDENCE_WARNING" \
+  --argjson record "$WI_RECORD" \
   --arg passed "$PASSED" \
   --arg score "$SCORE" \
   --arg feedback "$FEEDBACK" \
@@ -362,6 +367,7 @@ jq -n \
     evidence: ($evidence | to_entries | map(.value + {index: .key})),
     acceptWith: "complete-task with \"verdict\":\"verified\" and \"checks\":[{\"entry\":<evidence index, or null for a direct look>,\"did\":\"<what you did and saw>\",\"outcome\":\"pass\"}] (#1314)",
     evidenceWarning: (if $evidenceWarning != "" then $evidenceWarning else null end),
+    record: $record,
     passed: ($passed == "true"),
     score: ($score | tonumber),
     feedback: $feedback,

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

@@ -28,6 +28,9 @@ case "$url" in
   */api/task-pool/items/wi-ev)
     printf '%s\n200' '{"success":true,"data":{"id":"wi-ev","status":"done_by_worker","output":{"summary":"Report written","evidence":[{"type":"artifact","path":"/proj/report.md"},{"type":"command","command":"npm test","exitCode":0}]}}}'
     ;;
+  */api/task-pool/items/wi-rec)
+    printf '%s\n200' '{"success":true,"data":{"id":"wi-rec","status":"done_by_worker","output":{"summary":"Done","evidence":[{"type":"artifact","path":"/proj/a.md"}],"decisions":["Kept the v1 schema"],"assumptions":["Relay is on 1.5.24"]}}}'
+    ;;
   */api/task-pool/items/wi-noev)
     printf '%s\n200' '{"success":true,"data":{"id":"wi-noev","status":"done_by_worker","output":{"summary":"Trust me"}}}'
     ;;
@@ -128,6 +131,12 @@ assert_json_field "evidence is the first key of the verdict" \
   '{"workItemId":"wi-ev"}' 'keys_unsorted[0]' 'evidence'
 assert_json_field "each evidence entry carries its index for the checks (#1314)" \
   '{"workItemId":"wi-ev"}' '.evidence[1].index' '1'
+assert_json_field "the worker's decision record is surfaced as record (#875)" \
+  '{"workItemId":"wi-rec"}' '.record.decisions[0]' 'Kept the v1 schema'
+assert_json_field "record omits fields the worker did not send (#875)" \
+  '{"workItemId":"wi-rec"}' '.record | has("notTaken")' 'false'
+assert_json_field "no record -> record is null (#875)" \
+  '{"workItemId":"wi-ev"}' '.record' 'null'
 assert_json_field "evidence block is surfaced from output.evidence" \
   '{"workItemId":"wi-ev"}' '[.evidence[].type] | join(",")' 'artifact,command'
 assert_json_field "no evidence warning when evidence is present" \

package/config/sops/common/blocker-handling.md

@@ -19,6 +19,11 @@ tags:
   - escalation
   - blockers
   - help
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded — part of the original default SOP library (2026-01-29); re-test before keeping"
+seenOn: "unknown"
+reviewBy: 2026-12-31
+source: https://github.com/stevehuang0115/crewly/commit/77d504515
 ---
 
 # Blocker Handling

package/config/sops/common/communication-protocol.md

@@ -19,6 +19,11 @@ tags:
   - communication
   - team
   - protocol
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded — part of the original default SOP library (2026-01-29); re-test before keeping"
+seenOn: "unknown"
+reviewBy: 2026-12-31
+source: https://github.com/stevehuang0115/crewly/commit/77d504515
 ---
 
 # Communication Protocol

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

@@ -24,6 +24,11 @@ tags:
   - delivery
   - quality
   - tiering
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "Every change ran the full 9-step, 3-review process regardless of risk, so an internal one-line fix cost as much as a customer-facing release (P0 plan 2026-05-03, decision 3)"
+seenOn: "claude-code, model not recorded (2026-05)"
+reviewBy: 2027-01-31
+source: https://github.com/stevehuang0115/crewly/pull/411
 ---
 
 # Development Process Tiers

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

@@ -22,6 +22,11 @@ tags:
   - proactive
   - milestone
   - silent-shipping
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "Workers and team leads shipped milestones silently: 21 role prompts had 0–1 mentions of 'milestone', so progress surfaced only when someone asked (RC1, QW-1)"
+seenOn: "claude-code, model not recorded (2026-05)"
+reviewBy: 2027-01-31
+source: https://github.com/stevehuang0115/crewly/issues/427
 ---
 
 # Mid-Flight Milestone Surface

package/config/sops/common/owner-facing-communication.md

@@ -22,6 +22,11 @@ tags:
   - owner
   - external
   - tone
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "Owner-facing messages leaked task ids, session names and tier codes, gave a status with no decision/reason/impact, and asked the owner questions the agent could decide (P0 plan 2026-05-03, decision 6)"
+seenOn: "claude-code, model not recorded (2026-05)"
+reviewBy: 2027-01-31
+source: https://github.com/stevehuang0115/crewly/pull/413
 ---
 
 # Owner-Facing Communication Standard

package/config/sops/common/writing-for-agents.md

@@ -21,6 +21,11 @@ tags:
   - authoring
   - prompts
   - skills
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded as an incident — skills and norms were written for human readers (long prose, vague verbs, no examples); borrowed from mattpocock/skills, enforced by the skill lint"
+seenOn: "unknown (2026-10)"
+reviewBy: 2027-01-31
+source: https://github.com/stevehuang0115/crewly/pull/1277
 ---
 
 # Writing for Agents

package/config/sops/developer/coding-standards.md

@@ -19,6 +19,11 @@ tags:
   - standards
   - quality
   - typescript
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded — part of the original default SOP library (2026-01-29); re-test before keeping"
+seenOn: "unknown"
+reviewBy: 2026-12-31
+source: https://github.com/stevehuang0115/crewly/commit/77d504515
 ---
 
 # Coding Standards

package/config/sops/developer/debugging.md

@@ -22,6 +22,11 @@ tags:
   - debugging
   - testing
   - quality
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded as an incident — no debugging SOP existed; added with a pre-commit scan for leftover [DEBUG- markers, borrowed from mattpocock/skills"
+seenOn: "unknown (2026-10)"
+reviewBy: 2027-01-31
+source: https://github.com/stevehuang0115/crewly/pull/1277
 ---
 
 # Debugging

package/config/sops/developer/git-workflow.md

@@ -22,6 +22,11 @@ tags:
   - workflow
   - version-control
   - worktree
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded — part of the original default SOP library (2026-01-29); re-test before keeping"
+seenOn: "unknown"
+reviewBy: 2026-12-31
+source: https://github.com/stevehuang0115/crewly/commit/77d504515
 ---
 
 # Git Workflow

package/config/sops/developer/testing-requirements.md

@@ -19,6 +19,11 @@ tags:
   - testing
   - quality
   - coverage
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded — part of the original default SOP library (2026-01-29); re-test before keeping"
+seenOn: "unknown"
+reviewBy: 2026-12-31
+source: https://github.com/stevehuang0115/crewly/commit/77d504515
 ---
 
 # Testing Requirements

package/config/sops/pm/progress-tracking.md

@@ -19,6 +19,11 @@ tags:
   - tracking
   - reporting
   - status
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded — part of the original default SOP library (2026-01-29); re-test before keeping"
+seenOn: "unknown"
+reviewBy: 2026-12-31
+source: https://github.com/stevehuang0115/crewly/commit/77d504515
 ---
 
 # Progress Tracking

package/config/sops/pm/task-decomposition.md

@@ -19,6 +19,11 @@ tags:
   - planning
   - workflow
   - tasks
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded — part of the original default SOP library (2026-01-29); re-test before keeping"
+seenOn: "unknown"
+reviewBy: 2026-12-31
+source: https://github.com/stevehuang0115/crewly/commit/77d504515
 ---
 
 # Task Decomposition

package/config/sops/qa/testing-procedures.md

@@ -19,6 +19,11 @@ tags:
   - testing
   - quality
   - qa
+# Rule metadata (#877): what this rule prevents, where seen, when to re-test
+prevents: "none recorded — part of the original default SOP library (2026-01-29); re-test before keeping"
+seenOn: "unknown"
+reviewBy: 2026-12-31
+source: https://github.com/stevehuang0115/crewly/commit/77d504515
 ---
 
 # Testing Procedures

package/dist/backend/backend/src/constants.d.ts

@@ -1826,6 +1826,17 @@ export declare const COMPLETION_EVIDENCE_CONSTANTS: {
     };
     /** Worker evidence entries listed, numbered, in a review item's description (#1314). */
     readonly REVIEW_LISTED_ENTRIES: 10;
+    /**
+     * The worker's decision record (#875): optional completion fields the
+     * reviewer reads beside the evidence. Each is a list of short strings.
+     */
+    readonly DECISION_FIELDS: readonly ["decisions", "notTaken", "assumptions"];
+    /** Heading the review brief gives each decision field (#875). */
+    readonly DECISION_LABELS: Record<string, string>;
+    /** Entries of one decision field shown in a review brief (#875). */
+    readonly REVIEW_LISTED_DECISIONS: 5;
+    /** Max characters of one decision entry in a review brief (#875). */
+    readonly DECISION_ENTRY_MAX_CHARS: 300;
     /** Outcomes a reviewer records for one check (#1314). */
     readonly CHECK_OUTCOMES: readonly string[];
     /** The shape of a reviewer's check record, quoted in every refusal (#1314). */
@@ -2767,6 +2778,10 @@ export declare const SLACK_CLOUD_CONSTANTS: {
     readonly ROOM_JOIN_PATH: "/rooms/join";
     /** Event type of the Cloud-pushed room-join envelope */
     readonly ROOM_JOIN_EVENT_TYPE: "crewly_room_join";
+    /** `POST` — the asked machine reports a room-join outcome; Cloud relays it to the asking machine (crewly#1430) */
+    readonly ROOM_JOIN_RESULT_PATH: "/rooms/join/result";
+    /** Event type of the Cloud-pushed room-join-result envelope */
+    readonly ROOM_JOIN_RESULT_EVENT_TYPE: "crewly_room_join_result";
     /** `GET` — the account's Slack routing log (where each channel message went and why, 14 days) */
     readonly ROUTING_DECISIONS_PATH: "/routing-decisions";
     /** GET → who is who across the account (instances, teams, agents, bot users) */
@@ -8052,6 +8067,30 @@ export declare const TRACE_CONSTANTS: {
  * one ladder: the agent once, then its lead once, then one plain line to the
  * owner. The owner is never the retry loop.
  */
+/**
+ * Daily spot check of verified work (crewly#1315): a few verified WorkItems
+ * from the last day are re-checked for their artifacts still existing.
+ */
+export declare const VERIFIED_SPOT_CHECK_CONSTANTS: {
+    /** `=0` switches the sampler off */
+    readonly ENV_SWITCH: "CREWLY_VERIFIED_SPOT_CHECK";
+    /** Verified items completed within this window are candidates */
+    readonly WINDOW_MS: number;
+    /** Most WorkItems re-checked per run */
+    readonly SAMPLE_SIZE: 10;
+    /** How often the service asks whether today's run is still owed */
+    readonly CHECK_INTERVAL_MS: number;
+    /** Delay before the first check after boot */
+    readonly BOOT_DELAY_MS: number;
+    /** State file under CREWLY_HOME: the last run's day and result */
+    readonly STATE_FILE: "verified-spot-check.json";
+    /** Title of the owner alert when a sampled artifact is gone */
+    readonly OWNER_ALERT_TITLE: "Verified work spot check";
+    /** Discrepancies listed under the digest line (the rest are counted) */
+    readonly MAX_LISTED_DISCREPANCIES: 5;
+    /** Longest WorkItem title quoted in a discrepancy row */
+    readonly TITLE_MAX_CHARS: 60;
+};
 export declare const STALL_WATCHER_CONSTANTS: {
     /** `=false` switches the watcher off entirely */
     readonly ENV_KILL_SWITCH: "CREWLY_STALL_WATCHER";