crewly 1.20.319 → 1.20.321

package/config/skills/team-leader/decompose-goal/SKILL.md

@@ -60,7 +60,15 @@ Where `/tmp/decompose.json` contains:
       "description": "Create a React login form with email/password fields and validation",
       "requiredRole": "frontend-developer",
       "acceptanceCriteria": "- Form renders correctly\n- Client-side validation works\n- Accessible (ARIA labels)",
-      "priority": "high"
+      "priority": "high",
+      "blockedBy": ["Implement JWT token service"]
+    },
+    {
+      "title": "Wire login form to the token service",
+      "description": "Call the token service from the form and store the session; cover the full path with an end-to-end test",
+      "requiredRole": "frontend-developer",
+      "acceptanceCriteria": "- A user can log in end to end\n- E2E test passes",
+      "blockedBy": [0, 1]
     }
   ]
 }
@@ -80,6 +88,8 @@ Where `/tmp/decompose.json` contains:
 | `tasks[].requiredRole` | No | Role best suited for this task (default: `developer`) |
 | `tasks[].acceptanceCriteria` | No | Criteria for task verification |
 | `tasks[].priority` | No | Task priority: `low`, `normal`, `high` (default: `normal`) |
+| `tasks[].blockedBy` | No | Tasks of this same call that must finish first: 0-based indexes or exact titles. Becomes the WorkItem `dependsOn`; the task stays `blocked` and is not dispatched until every blocker is done. Unknown/ambiguous references and cycles are rejected and nothing is created |
+| `--dry-run` | No | Print the breakdown (title / blockedBy / delivers) in creation order and create nothing. Use it to review a large decomposition first |
 
 ## Output
 
@@ -98,11 +108,15 @@ Where `/tmp/decompose.json` contains:
 
 ## Best Practices
 
-1. **Be specific**: Each sub-task should be completable by a single worker in one session
-2. **Include acceptance criteria**: Workers need clear success metrics
-3. **Match roles**: Set `requiredRole` to help with delegation
-4. **Order matters**: List tasks in dependency order when possible
-5. **Don't over-split**: 2-5 sub-tasks per objective is typical
+1. **Cut vertical slices**: each task is a narrow but COMPLETE path through every layer (schema, API, UI, tests), not a horizontal slice of one layer.
+2. **Demoable alone**: a finished slice can be demoed or verified on its own.
+3. **Fresh-context size**: size each slice to fit a single fresh context window (the test for "completable by one worker in one session").
+4. **Prefactor first**: any prefactoring is its own first task that the slices depend on.
+5. **Wide refactors**: expand (add the new path), migrate in batches, contract (remove the old path). Each batch is its own task with `blockedBy` the expand task.
+6. **Name the blockers**: put every real prerequisite in `blockedBy`. A task with no blockers can start now; work the frontier (tasks whose blockers are all done).
+7. **Include acceptance criteria**: Workers need clear success metrics.
+8. **Match roles**: Set `requiredRole` to help with delegation.
+9. **Don't over-split**: 2-5 sub-tasks per objective is typical.
 
 ## Related Skills
 

package/config/skills/team-leader/decompose-goal/execute.sh

@@ -13,17 +13,19 @@ source "${SCRIPT_DIR}/../_common/lib.sh"
 # (the [TICKET:TKT-123 <id>] line of the message being worked on). Also
 # accepted as `"requestId"` in the JSON.
 REQUEST_ID=""
+DRY_RUN=0
 POSITIONAL=()
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --request-id|-R) REQUEST_ID="${2:-}"; shift 2 ;;
+    --dry-run) DRY_RUN=1; shift ;;
     *) POSITIONAL+=("$1"); shift ;;
   esac
 done
 set -- "${POSITIONAL[@]+"${POSITIONAL[@]}"}"
 
 INPUT=$(read_json_input "${1:-}")
-[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"objective\":\"Build auth module\",\"projectPath\":\"/path/to/project\",\"requestId\":\"<ticket id, optional>\",\"tasks\":[{\"title\":\"...\",\"description\":\"...\",\"requiredRole\":\"developer\",\"acceptanceCriteria\":\"...\",\"priority\":\"high\"}]}' [--request-id <id>]"
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"objective\":\"Build auth module\",\"projectPath\":\"/path/to/project\",\"requestId\":\"<ticket id, optional>\",\"tasks\":[{\"title\":\"...\",\"description\":\"...\",\"requiredRole\":\"developer\",\"acceptanceCriteria\":\"...\",\"priority\":\"high\"}]}' [--request-id <id>] [--dry-run]  (optional per task: \"blockedBy\":[<index or title>, ...])"
 
 OBJECTIVE=$(printf '%s' "$INPUT" | jq -r '.objective // empty')
 PROJECT_PATH=$(printf '%s' "$INPUT" | jq -r '.projectPath // empty')
@@ -39,11 +41,52 @@ if [ "$TASK_COUNT" = "0" ]; then
   error_exit "tasks array must contain at least one task"
 fi
 
+# Blocking edges: tasks[].blockedBy lists tasks of this same call (0-based
+# index or exact title). Resolve to indexes, reject unknown/ambiguous
+# references and cycles (a self-reference is a cycle) BEFORE creating anything, and derive a creation order
+# in which every blocker comes first.
+PLAN=$(printf '%s' "$TASKS" | jq -c '
+  . as $t
+  | [ to_entries[] | (.value.blockedBy // []) | map(
+        if type == "number" then (if . >= 0 and . < ($t | length) and . == floor then . else null end)
+        elif type == "string" then (. as $s | [$t | to_entries[] | select(.value.title == $s) | .key] | if length == 1 then .[0] else null end)
+        else null end) ] as $deps
+  | ([ $deps | to_entries[] | select(.value | any(. == null)) | .key ]) as $bad
+  | { deps: $deps, bad: $bad }
+  | . as $p
+  | ($p.deps | length) as $n
+  | ({ done: [], rem: [range(0; $n)], stuck: false }
+     | until((.rem | length) == 0 or .stuck;
+         . as $s
+         | [ $s.rem[] | . as $i | select($p.deps[$i] | all(. as $d | any($s.done[]; . == $d))) ] as $ready
+         | if ($ready | length) == 0 then .stuck = true else (.done += $ready | .rem -= $ready) end)) as $o
+  | { deps: $p.deps, bad: $p.bad, order: $o.done, cyclic: $o.rem }')
+BAD=$(printf '%s' "$PLAN" | jq -c '.bad')
+CYCLIC=$(printf '%s' "$PLAN" | jq -c '.cyclic')
+if [ "$BAD" != "[]" ]; then
+  error_exit "blockedBy has an unknown, ambiguous or invalid reference in task index(es) ${BAD}; nothing created"
+fi
+if [ "$CYCLIC" != "[]" ]; then
+  error_exit "blockedBy forms a cycle among task index(es) ${CYCLIC}; nothing created"
+fi
+
+if [ "$DRY_RUN" = "1" ]; then
+  printf '%s' "$TASKS" | jq -c --argjson plan "$PLAN" --arg objective "$OBJECTIVE" '
+    . as $t
+    | { dryRun: true, objective: $objective, tasks: [ $plan.order[] | . as $i | {
+          index: $i, title: $t[$i].title,
+          blockedBy: [ $plan.deps[$i][] | $t[.].title ],
+          delivers: ($t[$i].description // "") } ] }'
+  exit 0
+fi
+
 CREATED_TASKS="[]"
 ERRORS="[]"
+# index -> WorkItem id, for resolving blockedBy into dependsOn
+declare -a CREATED_ID_BY_INDEX=()
 
-# Create each sub-task via the task-management API
-for i in $(seq 0 $((TASK_COUNT - 1))); do
+# Create each sub-task via the task-pool API, blockers first
+for i in $(printf '%s' "$PLAN" | jq -r '.order[]'); do
   TASK_TITLE=$(echo "$TASKS" | jq -r ".[$i].title // empty")
   TASK_DESC=$(echo "$TASKS" | jq -r ".[$i].description // empty")
   TASK_ROLE=$(echo "$TASKS" | jq -r ".[$i].requiredRole // \"developer\"")
@@ -55,6 +98,21 @@ for i in $(seq 0 $((TASK_COUNT - 1))); do
     continue
   fi
 
+  # Resolve blockers to WorkItem ids; a blocker that failed to create blocks this task too.
+  DEPENDS_ON="[]"
+  DEP_FAILED=0
+  for d in $(printf '%s' "$PLAN" | jq -r ".deps[$i][]"); do
+    if [ -n "${CREATED_ID_BY_INDEX[$d]:-}" ]; then
+      DEPENDS_ON=$(echo "$DEPENDS_ON" | jq --arg id "${CREATED_ID_BY_INDEX[$d]}" '. + [$id]')
+    else
+      DEP_FAILED=1
+    fi
+  done
+  if [ "$DEP_FAILED" = "1" ]; then
+    ERRORS=$(echo "$ERRORS" | jq --arg msg "Skipped (a blocker was not created): ${TASK_TITLE}" '. + [$msg]')
+    continue
+  fi
+
   # Compose the brief markdown for the WorkItem.
   BRIEF="${TASK_DESC}"
   [ -n "$TASK_CRITERIA" ] && BRIEF="${BRIEF}
@@ -83,13 +141,14 @@ Required role: ${TASK_ROLE}"
     --arg role "$TASK_ROLE" \
     --arg priority "$TASK_PRIORITY" \
     --arg requestId "$REQUEST_ID" \
+    --argjson dependsOn "$DEPENDS_ON" \
     '{
       title: $title,
       type: "delegate",
       owner: "system",
       briefMarkdown: $brief,
       metadata: { projectPath: $projectPath, milestone: $milestone, requiredRole: $role, priority: $priority }
-    } + (if $requestId != "" then {requestId: $requestId} else {} end)')
+    } + (if $requestId != "" then {requestId: $requestId} else {} end) + (if ($dependsOn | length) > 0 then {dependsOn: $dependsOn} else {} end)')
 
   # No envelope: addItem reads req.body directly as the CreateWorkItemInput.
   CREATE_BODY="$WORK_ITEM"
@@ -97,12 +156,14 @@ Required role: ${TASK_ROLE}"
   CREATED_ID=$(echo "$CREATE_RESULT" | jq -r '.data.id // .workItem.id // empty' 2>/dev/null || true)
 
   if [ -n "$CREATED_ID" ]; then
+    CREATED_ID_BY_INDEX[$i]="$CREATED_ID"
     CREATED_TASKS=$(echo "$CREATED_TASKS" | jq \
       --arg title "$TASK_TITLE" \
       --arg role "$TASK_ROLE" \
       --arg id "$CREATED_ID" \
       --arg priority "$TASK_PRIORITY" \
-      '. + [{title: $title, requiredRole: $role, workItemId: $id, priority: $priority}]')
+      --argjson dependsOn "$DEPENDS_ON" \
+      '. + [{title: $title, requiredRole: $role, workItemId: $id, priority: $priority} + (if ($dependsOn | length) > 0 then {dependsOn: $dependsOn} else {} end)]')
   else
     ERRORS=$(echo "$ERRORS" | jq --arg msg "Failed to create WorkItem: ${TASK_TITLE}" '. + [$msg]')
   fi

package/config/skills/team-leader/decompose-goal/execute.test.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# Tests for decompose-goal (TL) — run with: bash execute.test.sh
+# A python HTTP stub plays the backend; asserts the POST /task-pool/add bodies.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+PORT=18843
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+N = [0]
+class H(BaseHTTPRequestHandler):
+    def reply(self, code, obj):
+        self.send_response(code); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps(obj).encode())
+    def do_GET(self):
+        return self.reply(200, {'ok': True})
+    def do_POST(self):
+        n = int(self.headers.get('content-length', '0')); body = json.loads(self.rfile.read(n).decode() or '{}')
+        if not self.path.endswith('/task-pool/add'):
+            return self.reply(200, {'success': True})
+        with open(LOG, 'a') as f: f.write(json.dumps(body) + '\n')
+        if body.get('title') == 'Fails':
+            return self.reply(500, {'success': False})
+        return self.reply(200, {'success': True, 'data': {'id': 'wi-' + body['title']}})
+    def log_message(self, *a, **k): pass
+HTTPServer(('127.0.0.1', PORT), H).serve_forever()
+PY
+STUB_PID=$!
+disown "$STUB_PID" 2>/dev/null || true
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -f "$STUB_LOG"' EXIT
+for i in $(seq 1 30); do curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/" 2>/dev/null && break; sleep 0.1; done
+
+run() { CREWLY_SESSION_NAME=tl-sam CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1; }
+posts() { wc -l < "$STUB_LOG" | tr -d ' '; }
+
+# 1. No blockedBy: unchanged behaviour, no dependsOn on the wire.
+: > "$STUB_LOG"
+OUT=$(run '{"objective":"O","tasks":[{"title":"A","description":"a"},{"title":"B","description":"b"}]}')
+check "plain: two created" "$(printf '%s' "$OUT" | jq -r .tasksCreated)" "2"
+check "plain: no dependsOn" "$(jq -c 'has("dependsOn")' "$STUB_LOG" | sort -u)" "false"
+
+# 2. Dependency chain (titles and indexes mixed), listed out of order: blockers are created first.
+: > "$STUB_LOG"
+OUT=$(run '{"objective":"Auth","tasks":[
+  {"title":"UI","description":"u","blockedBy":["API"]},
+  {"title":"Schema","description":"s"},
+  {"title":"API","description":"a","blockedBy":[1]},
+  {"title":"E2E","description":"e","blockedBy":["UI","API"]}]}')
+check "chain: all created" "$(printf '%s' "$OUT" | jq -r .tasksCreated)" "4"
+check "chain: creation order" "$(jq -r .title "$STUB_LOG" | paste -sd, -)" "Schema,API,UI,E2E"
+check "chain: API depends on Schema" "$(jq -c 'select(.title=="API") | .dependsOn' "$STUB_LOG")" '["wi-Schema"]'
+check "chain: UI depends on API" "$(jq -c 'select(.title=="UI") | .dependsOn' "$STUB_LOG")" '["wi-API"]'
+check "chain: E2E depends on API and UI" "$(jq -c 'select(.title=="E2E") | .dependsOn | sort' "$STUB_LOG")" '["wi-API","wi-UI"]'
+check "chain: Schema has no dependsOn" "$(jq -c 'select(.title=="Schema") | has("dependsOn")' "$STUB_LOG")" "false"
+
+# 3. Cycle / unknown / self reference: error, nothing created.
+: > "$STUB_LOG"
+OUT=$(run '{"objective":"O","tasks":[{"title":"A","description":"a","blockedBy":["B"]},{"title":"B","description":"b","blockedBy":["A"]}]}')
+check "cycle: error" "$(printf '%s' "$OUT" | grep -c 'cycle')" "1"
+check "cycle: nothing created" "$(posts)" "0"
+OUT=$(run '{"objective":"O","tasks":[{"title":"A","description":"a","blockedBy":["Nope"]}]}')
+check "unknown title: error" "$(printf '%s' "$OUT" | grep -c 'unknown')" "1"
+OUT=$(run '{"objective":"O","tasks":[{"title":"A","description":"a","blockedBy":[5]}]}')
+check "index out of range: error" "$(printf '%s' "$OUT" | grep -c 'unknown')" "1"
+OUT=$(run '{"objective":"O","tasks":[{"title":"A","description":"a","blockedBy":[0]}]}')
+check "self reference: error" "$(printf '%s' "$OUT" | grep -c 'cycle')" "1"
+check "errors: nothing created" "$(posts)" "0"
+
+# 4. A blocker that fails to create also blocks its dependents from being created.
+: > "$STUB_LOG"
+OUT=$(run '{"objective":"O","tasks":[{"title":"Fails","description":"f"},{"title":"After","description":"x","blockedBy":["Fails"]}]}')
+check "failed blocker: success false" "$(printf '%s' "$OUT" | jq -r .success)" "false"
+check "failed blocker: dependent skipped" "$(grep -c '"After"' "$STUB_LOG")" "0"
+
+# 5. --dry-run prints the breakdown, creates nothing.
+: > "$STUB_LOG"
+OUT=$(run '{"objective":"O","tasks":[{"title":"B","description":"b","blockedBy":["A"]},{"title":"A","description":"a"}]}' --dry-run)
+check "dry-run: order" "$(printf '%s' "$OUT" | jq -c '[.tasks[] | .title]')" '["A","B"]'
+check "dry-run: blockedBy titles" "$(printf '%s' "$OUT" | jq -c '.tasks[1].blockedBy')" '["A"]'
+check "dry-run: nothing created" "$(posts)" "0"
+
+echo "decompose-goal: ${PASS} passed, ${FAIL} failed"
+[ "$FAIL" -eq 0 ]

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

@@ -99,7 +99,7 @@ If two rules disagree, the higher tier wins.
 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).
+7. Merge Danger filled in on the PR (Door + Blast radius). A one-way door needs the rollback rehearsal from Tier 3. One-way = data migration, deletion, published artifact (npm, docker, deploy), outbound message.
 
 **Skipped vs Release Path:**
 - No staged rollout (merge-and-deploy together).

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

@@ -0,0 +1,45 @@
+---
+id: common-writing-for-agents
+version: 1
+createdAt: 2026-10-13T00:00:00Z
+updatedAt: 2026-10-13T00:00:00Z
+createdBy: system
+type: norm
+role: all
+category: quality
+priority: 8
+title: Writing for Agents
+description: How to word skills, prompts, roles and SOPs so agents act on them at low context cost
+triggers:
+  - write skill
+  - write prompt
+  - skill description
+  - author sop
+  - role prompt
+  - steering text
+tags:
+  - authoring
+  - prompts
+  - skills
+---
+
+# Writing for Agents
+
+Long form: mattpocock/skills `writing-for-agents`. Skill descriptions and always-loaded steering text cost context on every turn. Check new text against these six points. `skill-lint` (config/skills/_conventions) enforces the mechanical ones.
+
+1. **Pointer wording decides when material is read.** Front-load the leading word of a description. One trigger per branch; synonyms of one trigger are one branch written twice. Cut identity the body already carries.
+2. **End every step on a completion criterion.** The agent must be able to tell done from not-done. The best criteria are checkable and exhaustive ("the command exits 0", not "make sure it works").
+3. **Say what to do, not what to avoid.** A prohibition puts the forbidden behavior into context and makes it more available. Prefer "Run the check, then report its exit code" over "NEVER report without checking".
+4. **Do not restate the environment.** A doc that copies `package.json` scripts or config is a cache that goes stale. Cache only what cannot be found by looking; point to the file otherwise.
+5. **Hunt no-ops.** If the model already does it by default, the sentence costs load and changes nothing. Keep a sentence only if removing it would change behavior (the same test for #877 rule cleanup).
+6. **Keep emphasis rare.** Capitals and HARD RULE lose force when everything has them.
+
+## Example (real skill: `agent/core/publish-app`)
+
+Before (612 chars, why-it-works history and edge cases in the pointer):
+
+> Publish a small web app (HTML/JS) you wrote to https://apps.crewlyai.com/<appId> so the owner can open it on their phone. Creates the app the first time, uploads a new version each time after (same app for the same directory), supports rollback, and can post an "Open app" card to the owner (...). Can ask the owner to make an app public, or to publish it as a template on the Crewly Marketplace (...). The owner's edits, comments on elements, and anonymous visitors' submissions on a public app, come back to you as an [APP CHANGES] message.
+
+After (under 200 chars, one trigger, detail moves to the SKILL.md body):
+
+> Publish an HTML/JS app you wrote to apps.crewlyai.com so the owner can open it on their phone. Also: new version, rollback, make public.

package/config/sops/developer/debugging.md

@@ -0,0 +1,53 @@
+---
+id: dev-debugging
+version: 1
+createdAt: 2026-10-13T00:00:00Z
+updatedAt: 2026-10-13T00:00:00Z
+createdBy: system
+type: sop
+role: developer
+category: debugging
+priority: 9
+title: Debugging
+description: How to debug a failure — a red-capable loop first, ranked falsifiable hypotheses, tagged debug logs, cleanup
+triggers:
+  - debug
+  - failing test
+  - bug
+  - regression
+  - flaky
+  - broken
+  - repro
+tags:
+  - debugging
+  - testing
+  - quality
+---
+
+# Debugging
+
+Long form: mattpocock/skills `diagnosing-bugs`. Redact secrets in every command and artifact you show.
+
+## 1. Loop first
+
+Name **one command** you have already run at least once that shows the user's exact symptom (red-capable), is deterministic, fast and runnable by you. If you are reading code to build a theory before this command exists, stop and build the command.
+
+## 2. Reproduce and minimise
+
+Cut inputs one at a time. Done when every remaining element is load-bearing.
+
+## 3. Hypotheses
+
+Write 3-5 ranked hypotheses before testing any. Each is falsifiable: "If X is the cause, then changing Y makes the bug disappear." If you cannot state the prediction, it is a guess. Test one at a time.
+
+## 4. Instrument
+
+Tag every debug log with a unique prefix, e.g. `[DEBUG-a4f2]`, so cleanup is one grep. Untagged logs survive; tagged logs die. If no correct seam exists to test the bug, that is itself the finding.
+
+## 5. Fix with a regression test
+
+Turn the loop into a test. See it fail first, then fix (see `testing-requirements`: red before green).
+
+## 6. Clean up
+
+`grep -rn "\[DEBUG-" .` returns nothing. The pre-commit hook rejects a staged `[DEBUG-` line.

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

@@ -85,6 +85,10 @@ git worktree remove /tmp/crewly-{ticket-name}-{owner}
 
 **Solo work exception:** if you are the only developer active in the team and you're not parking work for parallel review, working directly in the main repo is acceptable. The worktree pattern is required only when there is a real risk of branch-state collision.
 
+## Destructive Git Is Blocked
+
+A hook blocks these in your Bash tool: force-push (`--force`, `-f`, `--force-with-lease`, `+ref`), any push to `main`/`master`, `reset --hard`, `clean -f`, `branch -D`, `checkout .`, `restore .`. Plain `git push origin feat/x` is fine. Instead: `git stash -u` before discarding, `branch -d` for merged branches, push a normal commit and open a PR. If you truly need one, ask your team lead. Limit: interpreter one-liners and variable-built commands are not seen.
+
 ## Before Pushing
 
 1. Run `npm run typecheck`

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

@@ -56,6 +56,20 @@ describe('ComponentName', () => {
 - No test interdependencies
 - Clean up after tests
 
+When a test fails and the cause is unclear, follow the `debugging` SOP (red-capable loop first).
+
+## Anti-patterns
+
+Coverage percentage rewards all three. Avoid them.
+
+- **Tautological**: the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`). Tell: it can never disagree with the code. Take expected values from a literal, a worked example or the spec. Prove a test is not tautological with the mutation check: break the code on purpose and see the test fail.
+- **Implementation-coupled**: the test checks how (private calls, call order), not what. Tell: it breaks on a refactor that changes no behavior.
+- **Horizontal slicing**: all tests first, then all code. Tell: many tests, none ever seen red. Work one test, one implementation, repeat. **Red before green**: see the new test fail before the fix.
+
+## Seams
+
+Test at agreed seams (public function, API route, CLI entry), not at every internal. For each seam write one line: what it catches and what it misses.
+
 ## Coverage Goals
 
 - Minimum 80% for new code

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

@@ -1040,7 +1040,7 @@ export declare const CONTROL_PLANE_GUARD_CONSTANTS: {
     /** Files under CREWLY_HOME that agents must not read with the built-in tools either. */
     readonly CREWLY_HOME_READ_DENIED_FILES: readonly ["api-token"];
     /** Write-protected directories under the install root (whole subtree). */
-    readonly INSTALL_DIRS: readonly ["config/skills/orchestrator/stop-agent", "config/skills/orchestrator/start-agent", "config/skills/orchestrator/terminate-agent", "config/skills/orchestrator/stop-team", "config/skills/orchestrator/start-team", "config/skills/orchestrator/restart-crewly", "config/hooks/control-plane-guard", "config/hooks/agent-status", "config/hooks/subagent-guard", "config/hooks/credential-guard", "config/hooks/live-checkout-guard", "dist"];
+    readonly INSTALL_DIRS: readonly ["config/skills/orchestrator/stop-agent", "config/skills/orchestrator/start-agent", "config/skills/orchestrator/terminate-agent", "config/skills/orchestrator/stop-team", "config/skills/orchestrator/start-team", "config/skills/orchestrator/restart-crewly", "config/hooks/control-plane-guard", "config/hooks/agent-status", "config/hooks/subagent-guard", "config/hooks/credential-guard", "config/hooks/live-checkout-guard", "config/hooks/destructive-git-guard", "dist"];
     /** Write-protected files under the install root. */
     readonly INSTALL_FILES: readonly ["config/skills/_common/lib.sh"];
     /** Write-protected directories under the agent's project path (whole subtree). */
@@ -1063,6 +1063,21 @@ export declare const LIVE_CHECKOUT_GUARD_CONSTANTS: {
     /** Codex tools the hook is attached to (shell, plus its patch tool). */
     readonly CODEX_MATCHER: "Bash|apply_patch|Edit|Write";
 };
+/**
+ * Destructive-git guard: blocks force-push, push to main/master, reset --hard,
+ * clean -f, branch -D, checkout . and restore . in an agent's Bash tool, so an
+ * agent cannot destroy its own unmerged work.
+ */
+export declare const DESTRUCTIVE_GIT_GUARD_CONSTANTS: {
+    /** Backend env var; `0` turns the guard off for sessions launched by this backend (the owner/TL override). */
+    readonly KILL_SWITCH_ENV: "CREWLY_DESTRUCTIVE_GIT_GUARD";
+    /** Value of KILL_SWITCH_ENV that disables the guard. */
+    readonly KILL_SWITCH_OFF_VALUE: "0";
+    /** The hook script (node), relative to the install root. */
+    readonly HOOK_SCRIPT: "config/hooks/destructive-git-guard/guard.mjs";
+    /** Claude Code tool the hook is attached to. */
+    readonly CLAUDE_MATCHER: "Bash";
+};
 /**
  * Credential guard (specs/2026-10-04-agent-credential-isolation.md, layer 2):
  * a pre-tool hook, on every runtime that has one, that refuses an agent's
@@ -1482,6 +1497,14 @@ export declare const TUI_INPUT_GUARD: {
     readonly RULE_STALE_PREFIX_MIN_CHARS: 40;
     /** Most status/footer lines allowed below an input box */
     readonly FOOTER_MAX_LINES: 6;
+    /**
+     * Most rows below the bottom rule when searching for a Claude Code /
+     * Antigravity box. Claude Code lists background agents and shells under
+     * the box, so a busy session can have well over FOOTER_MAX_LINES rows
+     * there (crewly#1113). Only the box search uses this; turn-signal reading
+     * keeps FOOTER_MAX_LINES.
+     */
+    readonly BOX_FOOTER_MAX_LINES: 14;
     /** Most lines an input box may span */
     readonly MAX_BOX_LINES: 60;
     /**
@@ -3300,6 +3323,20 @@ export declare const ORC_CONVERSATION_CONSTANTS: {
     /** Most of an earlier handover carried into a new one when the source conversation is unreadable */
     readonly CHAINED_HANDOVER_MAX_CHARS: 16000;
 };
+/** Pointer header (open work, suggested skills) written at the top of a handover file. */
+export declare const HANDOVER_POINTERS_CONSTANTS: {
+    /** Task pool file under CREWLY_HOME (dir, file) */
+    readonly POOL_DIR: "task-pool";
+    readonly POOL_FILE: "pool.json";
+    /** WorkItem statuses that count as still open for the agent */
+    readonly OPEN_STATUSES: readonly string[];
+    readonly MAX_OPEN_WORK: 15;
+    readonly MAX_LINKS: 10;
+    readonly TITLE_CHARS: 80;
+    /** Markers around the header, so a chained handover can strip it */
+    readonly START_MARK: "<!-- handover-pointers -->";
+    readonly END_MARK: "<!-- /handover-pointers -->";
+};
 /**
  * Fresh conversation per new task for Claude Code team members (never the
  * orchestrator): before a work item with a different root than the last one
@@ -5332,6 +5369,12 @@ export declare const CLOUD_SYNC_CONSTANTS: {
      * backs off so a relay that is refusing (quota, outage) is not hammered.
      */
     readonly REGISTER_RETRY_BACKOFF_MS: readonly number[];
+    /**
+     * Upper bound (ms) on honouring a relay 429 `Retry-After`. A daily-limit
+     * 429 can ask for hours; we re-check at most this often so a limit that was
+     * raised or reset is noticed without a restart.
+     */
+    readonly RETRY_AFTER_MAX_MS: number;
     /** Device considered offline after this threshold (ms) */
     readonly OFFLINE_THRESHOLD_MS: 60000;
     /** HTTP request timeout for sync API calls (ms) */
@@ -6799,6 +6842,12 @@ export declare const DECISION_CONSTANTS: {
      * (specs/2026-10-02-decision-card-thread-answers.md §2) (ms)
      */
     readonly WAIT_REMINDER_DELAY_MS: number;
+    /**
+     * `wait` default: a card still unanswered this long after its one reminder
+     * (a lifted reply question: after the deadline notice, it never gets a
+     * reminder) expires instead of staying open for days (#1243) (ms)
+     */
+    readonly WAIT_EXPIRE_AFTER_REMINDER_MS: number;
     /** Max characters of a withdrawn card's reason ("Closed — <reason>") */
     readonly CLOSED_REASON_MAX_CHARS: 120;
     /** Withdraw reasons the harness itself uses (cancelWhere notes) */
@@ -6882,6 +6931,18 @@ export declare const OPEN_ITEMS_CONSTANTS: {
     readonly YES_LABEL: "Yes";
     readonly NO_LABEL: "No";
     readonly REPLY_LABEL: "Reply in thread";
+    /** A lifted question shorter than this (characters) gets its subject prepended (#1242) */
+    readonly QUESTION_MIN_CHARS: 20;
+    /** Still shorter than this after the subject was added (characters): too vague for a card, tracked without one */
+    readonly QUESTION_VAGUE_CHARS: 12;
+    /** Suffix of the option the agent recommended */
+    readonly RECOMMENDED_SUFFIX: " (recommended)";
+    /** A sentence that recommends something ("我推荐 A", "I recommend B") */
+    readonly RECOMMENDATION_PATTERN: RegExp;
+    /** A recommendation that argues against doing it ("不建议", "don't recommend") */
+    readonly RECOMMENDATION_NEGATIVE_PATTERN: RegExp;
+    /** A project ticket id named in a promise ("CE-16"); the work done under it fulfils the promise wherever it ran (crewly#1037) */
+    readonly PROJECT_TICKET_REF_PATTERN: RegExp;
     /** `WorkItem.metadata` key of a follow-up WorkItem */
     readonly FOLLOW_UP_METADATA_KEY: "openItemFollowUp";
     /**
@@ -7679,6 +7740,11 @@ export declare const OWNER_THREAD_SENTINEL_CONSTANTS: {
     readonly DEADLINE_FACTOR: 1.5;
     /** Floor of a promise deadline (ms) */
     readonly MIN_DEADLINE_MS: number;
+    /**
+     * A promise with no stated time ("做好发到 #x", "I'll post the result") is
+     * overdue after this much silence from the agent in the thread (#1240) (ms)
+     */
+    readonly NO_ETA_SILENCE_MS: number;
     /** Longest promise the sentinel times (longer ones are not timed) */
     readonly MAX_PROMISE_MINUTES: number;
     /** Slot freeing / idle stop spare an agent whose owner message or promise is this recent */
@@ -8283,4 +8349,22 @@ export declare const CANVAS_CONSTANTS: {
     /** A Chrome session counts as the agent's browser while it was active this recently (ms) */
     readonly BROWSER_ACTIVE_MS: number;
 };
+/**
+ * Hand-off of an owner-approved change to a recurring job to the agent that
+ * runs it (crewly#1137).
+ */
+export declare const RECURRING_CHANGE_HANDOFF_CONSTANTS: {
+    /** Share of the schedule's name/title terms the decision text must contain */
+    readonly MIN_COVERAGE: 0.6;
+    /** Distinct terms the decision and the schedule must share */
+    readonly MIN_SHARED_TERMS: 2;
+    /** ...or this many shared terms whatever the coverage (labels mixing two languages) */
+    readonly SURE_SHARED_TERMS: 3;
+    /** Terms shorter than this (Latin words) are noise */
+    readonly MIN_WORD_CHARS: 3;
+    /** `WorkItem.metadata` marker on the hand-off WorkItem */
+    readonly METADATA_KEY: "recurringChangeHandoff";
+    /** Option labels / answers that decline a change (nothing to hand off) */
+    readonly DECLINE_PATTERN: RegExp;
+};
 //# sourceMappingURL=constants.d.ts.map