@drunkcoding/agents-and-skills 0.0.18 → 0.0.23

package/plugins/team-superpower/hooks/task-completed.sh

@@ -1,20 +1,30 @@
 #!/usr/bin/env bash
-# TaskCompleted hook — gate implementation completions on plan approval and
-# validate any embedded escalation entries.
+# TaskCompleted hook — v5 gate for implementation completions.
 #
 # Accepts a JSON payload on stdin with at minimum:
 #   - task.title: string
-#   - task.metadata.plan_approved_at: string (ISO datetime), required for impl: tasks
-#   - task.metadata.blocked_questions: array of strings (optional)
-#   - task.metadata.commits: array of git SHAs (optional, used by v2 checks)
+#   - task.metadata.wave: string (e.g. "1.1", "1.rework", "qc-rework")
+#   - task.metadata.iteration_count: integer (optional)
+#   - task.metadata.reflection: string (optional, required when iteration_count > cap)
+#   - task.metadata.retrieval_requests: integer (optional)
+#   - task.metadata.commits: array of git SHAs (optional)
 #   - task.metadata.contract_files: array of paths (optional, for contract-publish)
 #
-# v2 rules added on top of v1:
-#   - impl:be-migration-* completions: refuse if another in-progress migration
-#     exists in the shared task list payload (anti-race).
-#   - impl:be-contract-publish-* completions: at least one commit on this task
-#     must touch a contracts file (default `contracts/` directory, or paths
-#     listed in metadata.contract_files). Verified via `git show --name-only`.
+# v5 checks (delta from v4):
+#   - REMOVED: per-task QA verification (qa_verified_at, QA-verified commit line, qa_rounds cap, trivial=true claims)
+#   - REMOVED: 6-field escalation template validation (Phase/Context/Options/Recommendation/Need from you/Peer attempts)
+#   - REMOVED: v4 wave format (single integer); v5 wave is dotted (e.g. "1.1") or rework label
+#   - ADDED: MISSING_STATIC_CHECKS — every impl:* task must have a .team-superpower/static-check-<task-id>.log
+#     containing exit=0 for all sections (lint, format, typecheck).
+#   - ADDED: MISSING_REWORK_REFERENCE — every impl:rework-* task must have a `Reworks: <orig-id>` line
+#     in at least one commit body.
+#
+# v5 preserved checks:
+#   - migration serialization (impl:*-migration-* anti-race)
+#   - contract-publish must touch a contracts file
+#   - AGENTS.md protection (no agent commit may touch docs/superpowers/AGENTS.md)
+#   - retrieval budget cap + premature Flagged-assumptions guard
+#   - MAX_ITERATIONS guardrail
 
 set -euo pipefail
 
@@ -37,43 +47,187 @@ if ! command -v jq >/dev/null 2>&1; then
 fi
 
 title="$(printf '%s' "$payload" | jq -r '.task.title // .title // ""' 2>/dev/null || echo "")"
-plan_approved_at="$(printf '%s' "$payload" | jq -r '.task.metadata.plan_approved_at // .metadata.plan_approved_at // ""' 2>/dev/null || echo "")"
 
-printf '{"ts":"%s","hook":"task-completed","title":%s,"plan_approved_at":%s}\n' \
+printf '{"ts":"%s","hook":"task-completed","title":%s}\n' \
   "$ts" \
   "$(printf '%s' "$title" | jq -Rs .)" \
-  "$(printf '%s' "$plan_approved_at" | jq -Rs .)" \
   >> "$LOG_FILE"
 
+# Resolve parse-claudemd.sh helper for limits.* lookups.
+parse_helper="${CLAUDE_PLUGIN_ROOT:-}/scripts/parse-claudemd.sh"
+if [ -z "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+  hook_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  parse_helper="$hook_dir/../scripts/parse-claudemd.sh"
+fi
+
+# v5: wave metadata. impl:* tasks must carry a `wave:` string. Accepted shapes:
+#   - "<plan-phase>.<wave>"  e.g. "1.1", "2.3"
+#   - "<plan-phase>.rework"  e.g. "1.rework"
+#   - "qc-rework"
 case "$title" in
   impl:*)
-    if [ -z "$plan_approved_at" ]; then
-      printf '{"ts":"%s","hook":"task-completed","warn":"no_plan_approval","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+    wave="$(printf '%s' "$payload" | jq -r '.task.metadata.wave // .metadata.wave // ""' 2>/dev/null || echo "")"
+    if [ -z "$wave" ] || ! printf '%s' "$wave" | grep -qE '^([0-9]+\.[0-9]+|[0-9]+\.rework|qc-rework)$'; then
+      printf '{"ts":"%s","hook":"task-completed","warn":"MISSING_WAVE_METADATA","title":%s,"wave":%s}\n' \
+        "$ts" \
+        "$(printf '%s' "$title" | jq -Rs .)" \
+        "$(printf '%s' "$wave" | jq -Rs .)" \
+        >> "$LOG_FILE"
+    fi
+    ;;
+esac
+
+# v5 check 10: MISSING_STATIC_CHECKS. Every impl:* task must have a
+# .team-superpower/static-check-<task-id>.log with exit=0 across lint/format/typecheck.
+case "$title" in
+  impl:*)
+    project_dir="${CLAUDE_PROJECT_DIR:-$PWD}"
+    static_log="$project_dir/.team-superpower/static-check-${title}.log"
+    if [ ! -f "$static_log" ]; then
+      printf '{"ts":"%s","hook":"task-completed","warn":"MISSING_STATIC_CHECKS","title":%s,"reason":"log file not found","path":%s}\n' \
+        "$ts" \
+        "$(printf '%s' "$title" | jq -Rs .)" \
+        "$(printf '%s' "$static_log" | jq -Rs .)" \
+        >> "$LOG_FILE"
+    else
+      # Any exit= line with a non-zero value fails the check.
+      if grep -E '^exit=' "$static_log" | grep -qvE '^exit=0$'; then
+        bad="$(grep -E '^exit=' "$static_log" | grep -vE '^exit=0$' | head -n1 || true)"
+        printf '{"ts":"%s","hook":"task-completed","warn":"MISSING_STATIC_CHECKS","title":%s,"reason":"non-zero exit","line":%s}\n' \
+          "$ts" \
+          "$(printf '%s' "$title" | jq -Rs .)" \
+          "$(printf '%s' "$bad" | jq -Rs .)" \
+          >> "$LOG_FILE"
+      fi
+    fi
+    ;;
+esac
+
+# v5 check 11: MISSING_REWORK_REFERENCE. impl:rework-* tasks must carry a
+# `Reworks: <orig-id-or-qc-issue-id>` line in at least one commit body.
+case "$title" in
+  impl:rework-*)
+    if command -v git >/dev/null 2>&1; then
+      rw_commits="$(printf '%s' "$payload" | jq -r '(.task.metadata.commits // .metadata.commits // [])[]?' 2>/dev/null || true)"
+      if [ -n "$rw_commits" ]; then
+        rw_found=0
+        while IFS= read -r sha; do
+          [ -z "$sha" ] && continue
+          body="$(git show --no-color --no-patch --format=%B "$sha" 2>/dev/null || true)"
+          if printf '%s\n' "$body" | grep -qE '^Reworks:[[:space:]]*[^[:space:]]+'; then
+            rw_found=1; break
+          fi
+        done <<< "$rw_commits"
+        if [ "$rw_found" -ne 1 ]; then
+          printf '{"ts":"%s","hook":"task-completed","warn":"MISSING_REWORK_REFERENCE","title":%s,"reason":"no Reworks: line in commit body"}\n' \
+            "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+        fi
+      else
+        printf '{"ts":"%s","hook":"task-completed","warn":"MISSING_REWORK_REFERENCE","title":%s,"reason":"no commits recorded"}\n' \
+          "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+      fi
     fi
     ;;
 esac
 
-# v2: migration serialization. If this is a migration task, verify no other
-# `impl:be-migration-*` task is currently in_progress in the shared task list
-# (payload.tasks[]). The lead also enforces this; the hook is a backstop.
+# MAX_ITERATIONS guardrail (preserved from v3/v4).
 case "$title" in
-  impl:be-migration-*)
+  impl:*)
+    iteration_count="$(printf '%s' "$payload" | jq -r '.task.metadata.iteration_count // .metadata.iteration_count // 0' 2>/dev/null || echo 0)"
+    reflection="$(printf '%s' "$payload" | jq -r '.task.metadata.reflection // .metadata.reflection // ""' 2>/dev/null || echo "")"
+
+    cap=8
+    if [ -f "$parse_helper" ] && [ -f "${CLAUDE_PROJECT_DIR:-$PWD}/CLAUDE.md" ]; then
+      configured="$(bash "$parse_helper" get limits.max_iterations_per_task "${CLAUDE_PROJECT_DIR:-$PWD}/CLAUDE.md" 2>/dev/null || true)"
+      if [ -n "$configured" ] && printf '%s' "$configured" | grep -qE '^[0-9]+$'; then
+        cap="$configured"
+      fi
+    fi
+
+    if [ "${iteration_count:-0}" -gt "$cap" ] && [ -z "$reflection" ]; then
+      printf '{"ts":"%s","hook":"task-completed","warn":"ITERATION_CAP_EXCEEDED","title":%s,"iteration_count":%d,"cap":%d}\n' \
+        "$ts" \
+        "$(printf '%s' "$title" | jq -Rs .)" \
+        "$iteration_count" \
+        "$cap" \
+        >> "$LOG_FILE"
+    fi
+    ;;
+esac
+
+# Retrieval budget (preserved from v4).
+case "$title" in
+  impl:*)
+    retrieval_requests="$(printf '%s' "$payload" | jq -r '.task.metadata.retrieval_requests // .metadata.retrieval_requests // 0' 2>/dev/null || echo 0)"
+    retrieval_cap=2
+    if [ -f "$parse_helper" ] && [ -f "${CLAUDE_PROJECT_DIR:-$PWD}/CLAUDE.md" ]; then
+      configured_r="$(bash "$parse_helper" get limits.retrieval_budget_per_task "${CLAUDE_PROJECT_DIR:-$PWD}/CLAUDE.md" 2>/dev/null || true)"
+      if [ -n "$configured_r" ] && printf '%s' "$configured_r" | grep -qE '^[0-9]+$'; then
+        retrieval_cap="$configured_r"
+      fi
+    fi
+
+    if [ "${retrieval_requests:-0}" -gt "$retrieval_cap" ]; then
+      printf '{"ts":"%s","hook":"task-completed","warn":"RETRIEVAL_BUDGET_EXCEEDED","title":%s,"requests":%d,"cap":%d}\n' \
+        "$ts" "$(printf '%s' "$title" | jq -Rs .)" "$retrieval_requests" "$retrieval_cap" >> "$LOG_FILE"
+    fi
+
+    if command -v git >/dev/null 2>&1; then
+      r_commits="$(printf '%s' "$payload" | jq -r '(.task.metadata.commits // .metadata.commits // [])[]?' 2>/dev/null || true)"
+      if [ -n "$r_commits" ]; then
+        flagged=0
+        while IFS= read -r sha; do
+          [ -z "$sha" ] && continue
+          body="$(git show --no-color --no-patch --format=%B "$sha" 2>/dev/null || true)"
+          if printf '%s\n' "$body" | grep -qE '^Flagged-assumptions:'; then
+            flagged=1; break
+          fi
+        done <<< "$r_commits"
+        if [ "$flagged" -eq 1 ] && [ "${retrieval_requests:-0}" -lt "$retrieval_cap" ]; then
+          printf '{"ts":"%s","hook":"task-completed","warn":"PREMATURE_ASSUMPTION_FLAG","title":%s,"requests":%d,"cap":%d}\n' \
+            "$ts" "$(printf '%s' "$title" | jq -Rs .)" "$retrieval_requests" "$retrieval_cap" >> "$LOG_FILE"
+        fi
+      fi
+    fi
+    ;;
+esac
+
+# AGENTS.md protection (preserved from v4).
+if command -v git >/dev/null 2>&1; then
+  agm_commits="$(printf '%s' "$payload" | jq -r '(.task.metadata.commits // .metadata.commits // [])[]?' 2>/dev/null || true)"
+  if [ -n "$agm_commits" ]; then
+    while IFS= read -r sha; do
+      [ -z "$sha" ] && continue
+      files="$(git show --no-color --name-only --pretty=format: "$sha" 2>/dev/null || true)"
+      if printf '%s\n' "$files" | grep -qE '^docs/superpowers/AGENTS\.md$'; then
+        printf '{"ts":"%s","hook":"task-completed","warn":"AGENT_WROTE_AGENTS_MD","title":%s,"sha":%s}\n' \
+          "$ts" "$(printf '%s' "$title" | jq -Rs .)" "$(printf '%s' "$sha" | jq -Rs .)" >> "$LOG_FILE"
+      fi
+    done <<< "$agm_commits"
+  fi
+fi
+
+# Migration serialization (preserved). v5 widens the prefix match: any task
+# whose title contains the qualifier `-migration-` (e.g. impl:be-migration-*,
+# impl:rework-be-migration-*) is migration-class.
+case "$title" in
+  *-migration-*)
     other_in_progress="$(printf '%s' "$payload" | jq -r --arg me "$title" '
       [ .tasks[]?
         | select((.title // "") != $me)
-        | select(((.title // "") | startswith("impl:be-migration-")))
+        | select(((.title // "") | contains("-migration-")))
         | select((.status // "") == "in_progress")
       ] | length' 2>/dev/null || echo 0)"
     if [ "${other_in_progress:-0}" -gt 0 ]; then
-      printf '{"ts":"%s","hook":"task-completed","warn":"migration_race","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+      printf '{"ts":"%s","hook":"task-completed","warn":"MIGRATION_RACE","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
     fi
     ;;
 esac
 
-# v2: contract-publish must actually touch a contracts file in at least one
-# of its commits. Best-effort: skip if git unavailable or no commits recorded.
+# Contract-publish must touch a contracts file (preserved). v5 widens to any
+# task whose title contains the qualifier `-contract-publish-`.
 case "$title" in
-  impl:be-contract-publish-*)
+  *-contract-publish-*)
     if command -v git >/dev/null 2>&1; then
       commits="$(printf '%s' "$payload" | jq -r '(.task.metadata.commits // .metadata.commits // [])[]?' 2>/dev/null || true)"
       patterns="$(printf '%s' "$payload" | jq -r '(.task.metadata.contract_files // .metadata.contract_files // ["contracts/"])[]?' 2>/dev/null || echo "contracts/")"
@@ -90,44 +244,11 @@ case "$title" in
           done <<< "$patterns"
         done <<< "$commits"
         if [ "$touched" -ne 1 ]; then
-          printf '{"ts":"%s","hook":"task-completed","warn":"empty_contract_publish","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+          printf '{"ts":"%s","hook":"task-completed","warn":"EMPTY_CONTRACT_PUBLISH","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
         fi
       fi
     fi
     ;;
 esac
 
-# Validate escalation entries if present.
-required_fields=("Phase" "Context" "Options" "Recommendation" "Need from you" "Peer attempts")
-missing_any=""
-entries="$(printf '%s' "$payload" | jq -c '(.task.metadata.blocked_questions // .metadata.blocked_questions // [])[]?' 2>/dev/null || true)"
-
-if [ -n "$entries" ]; then
-  while IFS= read -r entry; do
-    [ -z "$entry" ] && continue
-    raw="$(printf '%s' "$entry" | jq -r '.' 2>/dev/null || printf '%s' "$entry")"
-    missing=""
-    for field in "${required_fields[@]}"; do
-      if ! printf '%s' "$raw" | grep -qE "(^|[^A-Za-z])${field}[[:space:]]*:"; then
-        if [ -z "$missing" ]; then
-          missing="$field"
-        else
-          missing="$missing, $field"
-        fi
-      fi
-    done
-    if [ -n "$missing" ]; then
-      if [ -z "$missing_any" ]; then
-        missing_any="$missing"
-      else
-        missing_any="$missing_any | $missing"
-      fi
-    fi
-  done <<< "$entries"
-fi
-
-if [ -n "$missing_any" ]; then
-  printf '{"ts":"%s","hook":"task-completed","warn":"bad_escalation","missing":%s}\n' "$ts" "$(printf '%s' "$missing_any" | jq -Rs .)" >> "$LOG_FILE"
-fi
-
 exit 0

package/plugins/team-superpower/hooks/task-created.sh

@@ -1,21 +1,28 @@
 #!/usr/bin/env bash
-# TaskCreated hook — enforce title prefix on shared task list entries.
+# TaskCreated hook — v5 prefix + wave validation for shared task list entries.
 #
 # Accepts a JSON payload on stdin. Required field:
 #   - task.title: string
 #
-# Title MUST start with one of: impl:, review:, meta:, block:
-# v2 additions:
-#   - impl: tasks MUST carry a sub-prefix (be-, fe-, qa-fix-be-, qa-fix-fe-,
-#     review-fix-be-, review-fix-fe-, contract-update-, be-migration-,
-#     be-contract-publish-) — bare `impl:foo` is rejected.
-#   - Shape-marker file at docs/superpowers/sessions/<slug>.shape (written by
-#     the lead in phase 0) restricts which sub-prefixes are allowed:
-#       be-only      → only `impl:be-*`, `impl:contract-update-*` allowed
-#       fe-only      → only `impl:fe-*`, `impl:contract-update-*` allowed
-#       full-stack   → all sub-prefixes allowed
-#   - Slug is taken from .task.metadata.slug or .metadata.slug, with fallback
-#     to the most-recent .shape file when only one exists.
+# v5 changes (delta from v4):
+#   - ADDED: impl:rework-* allowed top-level. Rework tasks dispatched by
+#     team-leader (phase-end SOLID/DRY review) or qc-engineer (end-of-plan QC)
+#     do not carry a be-/fe- prefix; their original-task id is in the
+#     `Reworks:` line of the implementer's commit body and validated by
+#     task-completed.sh.
+#   - ADDED: INVALID_WAVE_REFERENCE — v5 waves are dotted strings, not single
+#     integers. Accepted shapes: "<plan-phase>.<wave>" (e.g. "1.1", "2.3"),
+#     "<plan-phase>.rework" (e.g. "1.rework"), or "qc-rework".
+#   - REMOVED: qa-fix-be-, qa-fix-fe-, review-fix-be-, review-fix-fe- prefixes
+#     (v4 QA loop is gone). Use impl:rework-* instead.
+#   - REMOVED: bare integer wave format.
+#
+# Preserved checks:
+#   - Top-level prefix must be impl: / review: / meta: / block:.
+#   - impl:* must carry a known sub-prefix per the shape file.
+#   - solo-mode guard: impl:* invalid when checkpoint mode is solo.
+#   - Shape-marker file at docs/superpowers/sessions/<slug>.shape restricts
+#     allowed sub-prefixes (be-only / fe-only / full-stack).
 
 set -euo pipefail
 
@@ -59,10 +66,13 @@ if [ -d "$SESSIONS_DIR" ]; then
   fi
 fi
 
-printf '{"ts":"%s","hook":"task-created","title":%s,"shape":%s}\n' \
+wave="$(printf '%s' "$payload" | jq -r '.task.metadata.wave // .metadata.wave // ""' 2>/dev/null || echo "")"
+
+printf '{"ts":"%s","hook":"task-created","title":%s,"shape":%s,"wave":%s}\n' \
   "$ts" \
   "$(printf '%s' "$title" | jq -Rs .)" \
   "$(printf '%s' "$shape" | jq -Rs .)" \
+  "$(printf '%s' "$wave" | jq -Rs .)" \
   >> "$LOG_FILE"
 
 # Top-level prefix check
@@ -71,20 +81,65 @@ case "$title" in
   impl:*) ;;
   "")
     printf '{"ts":"%s","hook":"task-created","warn":"bad_prefix","reason":"title missing"}\n' "$ts" >> "$LOG_FILE"
+    exit 0
     ;;
   *)
     printf '{"ts":"%s","hook":"task-created","warn":"bad_prefix","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+    exit 0
     ;;
 esac
 
+# v3: solo-mode guard. If checkpoint mode is solo, impl:* tasks are invalid.
+mode_meta="$(printf '%s' "$payload" | jq -r '.task.metadata.mode // .metadata.mode // ""' 2>/dev/null || echo "")"
+mode_marker=""
+if [ -z "$mode_meta" ] && [ -d "$SESSIONS_DIR" ]; then
+  marker_file=""
+  if [ -n "$slug" ] && [ -f "$SESSIONS_DIR/$slug.mode" ]; then
+    marker_file="$SESSIONS_DIR/$slug.mode"
+  else
+    count="$(find "$SESSIONS_DIR" -maxdepth 1 -type f -name '*.mode' 2>/dev/null | wc -l | tr -d ' ')"
+    if [ "$count" = "1" ]; then
+      marker_file="$(find "$SESSIONS_DIR" -maxdepth 1 -type f -name '*.mode' 2>/dev/null | head -n1)"
+    fi
+  fi
+  if [ -n "$marker_file" ] && [ -f "$marker_file" ]; then
+    mode_marker="$(head -n1 "$marker_file" | tr -d '[:space:]')"
+  fi
+fi
+effective_mode="${mode_meta:-$mode_marker}"
+
+if [ "$effective_mode" = "solo" ]; then
+  printf '{"ts":"%s","hook":"task-created","warn":"INVALID_FOR_SOLO_MODE","title":%s}\n' \
+    "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+fi
+
+# v5 INVALID_WAVE_REFERENCE: wave metadata is required and must match the v5 shape.
+if [ -z "$wave" ]; then
+  printf '{"ts":"%s","hook":"task-created","warn":"INVALID_WAVE_REFERENCE","title":%s,"reason":"wave metadata missing"}\n' \
+    "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
+elif ! printf '%s' "$wave" | grep -qE '^([0-9]+\.[0-9]+|[0-9]+\.rework|qc-rework)$'; then
+  printf '{"ts":"%s","hook":"task-created","warn":"INVALID_WAVE_REFERENCE","title":%s,"wave":%s,"reason":"unrecognised wave shape"}\n' \
+    "$ts" \
+    "$(printf '%s' "$title" | jq -Rs .)" \
+    "$(printf '%s' "$wave" | jq -Rs .)" \
+    >> "$LOG_FILE"
+fi
+
 # At this point title starts with `impl:`. Strip prefix and require a known
-# sub-prefix.
+# v5 sub-prefix.
 rest="${title#impl:}"
 case "$rest" in
-  be-*|qa-fix-be-*|review-fix-be-*|be-migration-*|be-contract-publish-*)
+  rework-*)
+    # Rework tasks dispatched by team-leader (phase-end review) or qc-engineer
+    # (end-of-plan QC). The Reworks: <orig-id> line in the commit body is
+    # validated by task-completed.sh (MISSING_REWORK_REFERENCE). No shape check
+    # — rework inherits the originating task's scope.
+    sub="rework"
+    ;;
+  be-*|be-migration-*|be-contract-publish-*)
     sub="be"
     ;;
-  fe-*|qa-fix-fe-*|review-fix-fe-*)
+  fe-*)
     sub="fe"
     ;;
   contract-update-*)
@@ -92,10 +147,13 @@ case "$rest" in
     ;;
   *)
     printf '{"ts":"%s","hook":"task-created","warn":"bad_subprefix","title":%s}\n' "$ts" "$(printf '%s' "$title" | jq -Rs .)" >> "$LOG_FILE"
-    exit 0 ;;
+    exit 0
+    ;;
 esac
 
-# Shape-aware enforcement
+# Shape-aware enforcement. rework + contract-update are scope-neutral and
+# allowed under any shape — they inherit scope from the originating task or
+# from BE ownership of the contract.
 case "$shape" in
   be-only)
     if [ "$sub" = "fe" ]; then

package/plugins/team-superpower/hooks/teammate-idle.sh

@@ -1,15 +1,37 @@
 #!/usr/bin/env bash
-# TeammateIdle hook — block idle if there are unanswered inbound peer messages.
+# TeammateIdle hook — v5 role-aware routing.
 #
-# Reads the hook event payload from stdin. Expected JSON fields (best-effort —
-# the agent-teams runtime may evolve; we only fail closed on what we can verify):
-#   - mailbox: array of { from, replied, ... }
-#   - teammate: string (the idling teammate's role)
+# Reads the hook event payload from stdin. Expected JSON fields:
+#   - mailbox: array of { from, kind, replied, ... } — recent SendMessage history
+#   - teammate: string (the idling teammate's role; one of
+#       orchestrator | team-leader | solution-architect | feature-planner |
+#       security-engineer | backend-developer | frontend-developer | qc-engineer)
 #
-# Behaviour:
-#   - count messages where from != "lead" AND replied == false
-#   - if count > 0  -> exit 2 with stderr BLOCKED_IDLE
-#   - else          -> exit 0
+# v5 behaviour: routing depends on role.
+#
+#   backend-developer / frontend-developer:
+#     - block if any unanswered message FROM team-leader (implementer owes a reply)
+#     - block if a self-sent ESCALATE has no reply within heartbeat (advisory log)
+#     - otherwise advisory: wave dispatch may still be in flight; ok to idle
+#
+#   team-leader:
+#     - block if SPAWN_REQUEST or RESTART_REQUEST has no SPAWN_DONE / RESTART_DONE
+#       reply from lead/orchestrator within heartbeat (must keep coordinating)
+#     - block if any unanswered ESCALATE from an implementer (must route)
+#     - otherwise advisory tick
+#
+#   qc-engineer:
+#     - block if QC_REWORK_NEEDED has no reply (lead must acknowledge before shutdown)
+#     - otherwise advisory tick
+#
+#   solution-architect / feature-planner / security-engineer (phase A roles):
+#     - block if owner sign-off touchpoint message has no reply yet
+#     - otherwise advisory tick (shutdown is owner-driven via lead)
+#
+#   orchestrator (lead):
+#     - block if any unanswered SPAWN_REQUEST / RESTART_REQUEST inbound from
+#       team-leader (lead is the single spawner)
+#     - otherwise advisory tick (lead drives owner touchpoints separately)
 #
 # Logs every invocation to .claude/hooks/log.jsonl in the project root for tuning.
 
@@ -33,12 +55,95 @@ if ! command -v jq >/dev/null 2>&1; then
   exit 0
 fi
 
-unanswered="$(printf '%s' "$payload" | jq '[.mailbox[]? | select((.from // "") != "lead") | select((.replied // false) == false)] | length' 2>/dev/null || echo 0)"
+teammate="$(printf '%s' "$payload" | jq -r '.teammate // ""' 2>/dev/null || echo "")"
+
+# Helper: count unanswered inbound messages where .from matches a pattern.
+count_unanswered_from() {
+  local from_pattern="$1"
+  printf '%s' "$payload" \
+    | jq --arg p "$from_pattern" \
+        '[.mailbox[]?
+          | select(((.from // "") | test($p)))
+          | select((.replied // false) == false)
+         ] | length' \
+        2>/dev/null \
+    || echo 0
+}
+
+# Helper: count self-sent outbound messages of a given kind with no reply yet.
+count_outbound_unanswered_kind() {
+  local kind_pattern="$1"
+  printf '%s' "$payload" \
+    | jq --arg k "$kind_pattern" \
+        '[.mailbox[]?
+          | select(((.direction // "in") == "out"))
+          | select(((.kind // "") | test($k)))
+          | select((.replied // false) == false)
+         ] | length' \
+        2>/dev/null \
+    || echo 0
+}
+
+warn=""
 
-printf '{"ts":"%s","hook":"teammate-idle","unanswered":%s}\n' "$ts" "$unanswered" >> "$LOG_FILE"
+case "$teammate" in
+  backend-developer|frontend-developer)
+    unanswered_from_leader="$(count_unanswered_from '^team-leader$')"
+    if [ "${unanswered_from_leader:-0}" -gt 0 ]; then
+      warn="BLOCKED_IDLE_implementer_owes_team-leader_reply"
+    fi
+    ;;
+  team-leader)
+    spawn_pending="$(count_outbound_unanswered_kind 'SPAWN_REQUEST|RESTART_REQUEST')"
+    escalate_pending="$(count_unanswered_from '^(backend-developer|frontend-developer)$')"
+    if [ "${spawn_pending:-0}" -gt 0 ]; then
+      warn="BLOCKED_IDLE_team-leader_awaiting_lead_on_spawn_or_restart"
+    elif [ "${escalate_pending:-0}" -gt 0 ]; then
+      warn="BLOCKED_IDLE_team-leader_owes_implementer_escalate_reply"
+    fi
+    ;;
+  qc-engineer)
+    qc_pending="$(count_outbound_unanswered_kind 'QC_REWORK_NEEDED')"
+    if [ "${qc_pending:-0}" -gt 0 ]; then
+      warn="BLOCKED_IDLE_qc-engineer_awaiting_lead_ack"
+    fi
+    ;;
+  solution-architect|feature-planner|security-engineer)
+    handover_pending="$(count_outbound_unanswered_kind 'HANDOVER_READY|SEC_PASSED|SEC_BLOCKED')"
+    if [ "${handover_pending:-0}" -gt 0 ]; then
+      warn="BLOCKED_IDLE_phaseA_awaiting_owner_signoff"
+    fi
+    ;;
+  orchestrator)
+    lead_inbound_pending="$(count_unanswered_from '^team-leader$')"
+    if [ "${lead_inbound_pending:-0}" -gt 0 ]; then
+      warn="BLOCKED_IDLE_orchestrator_unhandled_team-leader_request"
+    fi
+    ;;
+  "")
+    # Unknown role: fall back to legacy v4 behaviour (any unanswered non-lead inbound).
+    legacy_unanswered="$(printf '%s' "$payload" | jq '[.mailbox[]? | select((.from // "") != "lead") | select((.replied // false) == false)] | length' 2>/dev/null || echo 0)"
+    if [ "${legacy_unanswered:-0}" -gt 0 ]; then
+      warn="BLOCKED_IDLE_legacy_unanswered_inbound"
+    fi
+    ;;
+  *)
+    # Unknown but non-empty role — log advisory only, do not block.
+    :
+    ;;
+esac
 
-if [ "${unanswered:-0}" -gt 0 ]; then
-  printf '{"ts":"%s","hook":"teammate-idle","warn":"blocked_idle","unanswered":%s}\n' "$ts" "$unanswered" >> "$LOG_FILE"
+if [ -n "$warn" ]; then
+  printf '{"ts":"%s","hook":"teammate-idle","teammate":%s,"warn":%s}\n' \
+    "$ts" \
+    "$(printf '%s' "$teammate" | jq -Rs .)" \
+    "$(printf '%s' "$warn" | jq -Rs .)" \
+    >> "$LOG_FILE"
+else
+  printf '{"ts":"%s","hook":"teammate-idle","teammate":%s,"ok":true}\n' \
+    "$ts" \
+    "$(printf '%s' "$teammate" | jq -Rs .)" \
+    >> "$LOG_FILE"
 fi
 
 exit 0