devrites 1.19.0

package/pack/.claude/skills/devrites-lib/scripts/progress.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# DevRites progress footer — render the active feature's position deterministically.
+# Run LAST (output step) by every workspace-operating rite-* skill via the standard
+# resolution snippet, the mirror of preamble.sh (which runs first). Read-only; never
+# mutates workspace files.
+#
+# Prints three lines of "chrome" the skill's own fact lines sit under:
+#   ── rite-<phase> ───────────────────────────
+#   Slice <built>/<total>  ██████░░░░  <last-built name> ✓     (or "✅ ALL BUILT" at N/N)
+#   Flow   spec ✓ define ✓ build ◉ prove ○ … ship ○
+#
+# The slice meter answers "how many steps left" (built/total); the ✅ ALL BUILT marker
+# + the `build ✓` ribbon glyph answer "is the build phase complete". The skill prints the
+# what-was-done / next-step / hygiene lines beneath; this script owns only the visuals so
+# every rite-* footer looks the same with zero model drift.
+#
+# Usage: progress.sh [slug]
+#   slug — optional override; defaults to .devrites/ACTIVE
+#
+# Paths resolve relative to CWD (the project root), like preamble.sh. Prints nothing and
+# exits 0 when there is no active workspace, so pre-spec callers stay silent.
+
+set -u
+slug="${1:-$(cat .devrites/ACTIVE 2>/dev/null)}"
+d=".devrites/work/$slug"
+s="$d/state.md"
+
+[ -n "$slug" ] && [ -f "$s" ] || exit 0
+
+# --- phase ----------------------------------------------------------------------------
+# First whitespace token after "Phase:" (ignores any trailing "  # comment").
+phase="$(awk -F': *' '/^- Phase:/{print $2; exit}' "$s" | awk '{print $1}')"
+[ -n "$phase" ] || phase="spec"
+
+# --- slice tally ----------------------------------------------------------------------
+# total / built counts + the name of the last built slice, parsed from "## Slice progress".
+read -r total built lastbuilt <<EOF
+$(awk '
+  /^## Slice progress/ { inp=1; next }
+  inp && /^## /         { inp=0 }
+  inp && /^- \[/ {
+    total++
+    name=$0
+    sub(/^- \[[^]]*\][[:space:]]*/, "", name)              # drop "- [x] "
+    sub(/^Slice[[:space:]]*[0-9]+:[[:space:]]*/, "", name) # drop "Slice N: "
+    sub(/[[:space:]]+(built|pending)[[:space:]]*$/, "", name)        # drop trailing "built|pending"
+    sub(/[[:space:]]+[^[:alnum:][:space:]]+[[:space:]]*$/, "", name) # drop the " — " separator
+    if ($0 ~ /\[[xX]\]/) { built++; last=name }
+  }
+  END { printf "%d %d %s", total+0, built+0, last }
+' "$s")
+EOF
+total="${total:-0}"; built="${built:-0}"
+
+# --- header rule ----------------------------------------------------------------------
+title="rite-${phase}"
+header="── ${title} "
+while [ "${#header}" -lt 44 ]; do header="${header}─"; done
+printf '%s\n' "$header"
+
+# --- slice meter ----------------------------------------------------------------------
+# Bar is 10 cells; filled = round(built/total*10). Skipped entirely before any slices exist.
+if [ "$total" -gt 0 ]; then
+  filled=$(( (built * 10 + total / 2) / total ))
+  [ "$filled" -gt 10 ] && filled=10
+  bar=""; i=0
+  while [ "$i" -lt "$filled" ]; do bar="${bar}█"; i=$((i+1)); done
+  while [ "$i" -lt 10 ];       do bar="${bar}░"; i=$((i+1)); done
+  if [ "$built" -ge "$total" ]; then
+    printf 'Slices %d/%d  %s  ✅ ALL BUILT\n' "$built" "$total" "$bar"
+  else
+    tail=""
+    [ -n "$lastbuilt" ] && tail="  ${lastbuilt} ✓"
+    printf 'Slice %d/%d  %s%s\n' "$built" "$total" "$bar" "$tail"
+  fi
+fi
+
+# --- flow ribbon ----------------------------------------------------------------------
+# Lifecycle spine; optional temper/vet appear only once their artifact exists.
+order=(spec)
+[ -f "$d/strategy.md" ]   && order+=(temper)
+order+=(define)
+[ -f "$d/eng-review.md" ] && order+=(vet)
+order+=(build prove polish review seal ship)
+
+# Current index in the spine. `plan` is replan → sits at build; `done` is past ship.
+cur="$phase"; [ "$cur" = "plan" ] && cur="build"
+idx=-1
+if [ "$phase" = "done" ]; then
+  idx=${#order[@]}
+else
+  for n in "${!order[@]}"; do [ "${order[$n]}" = "$cur" ] && { idx=$n; break; }; done
+fi
+
+ribbon="Flow  "
+for n in "${!order[@]}"; do
+  if   [ "$n" -lt "$idx" ]; then g="✓"
+  elif [ "$n" -eq "$idx" ]; then g="◉"
+  else                           g="○"
+  fi
+  ribbon="${ribbon} ${order[$n]} ${g}"
+done
+printf '%s\n' "$ribbon"

package/pack/.claude/skills/devrites-lib/scripts/readiness.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# Build-readiness gate for DevRites — turns /rite-build's step-0 prose checks
+# ("if Status is awaiting_human → STOP", "if no Plan approved → STOP") into a
+# deterministic exit code, the same way tick-afk.sh enforces the AFK cap. A gate
+# the model *is* stopped by beats a gate the model is *asked* to honor.
+# Read-only; never mutates the workspace.
+#
+# Usage: readiness.sh [slug]
+#   slug — optional; defaults to .devrites/ACTIVE
+#
+# Checks .devrites/work/<slug>/state.md, in order:
+#   - workspace + state.md exist
+#   - Status != awaiting_human   (a HITL gate is open)
+#   - Status != blocked
+#   - "Plan approved:" is set     (/rite-define writes it when the human confirms)
+#
+# Exit codes:
+#   0  ready to build
+#   2  plan not approved        → /rite-define (then confirm the plan)
+#   3  awaiting human           → /rite-resolve <qid> "<answer>"
+#   4  blocked                  → /rite-plan repair | unblock
+#   5  no workspace / state.md  → /rite-spec <feature>
+
+set -euo pipefail
+
+slug="${1:-$(cat .devrites/ACTIVE 2>/dev/null || true)}"
+d=".devrites/work/$slug"
+s="$d/state.md"
+if [ -z "$slug" ] || [ ! -f "$s" ]; then
+  printf 'readiness: no active workspace/state.md (slug=%s) — run /rite-spec <feature>\n' "${slug:-<unset>}" >&2
+  exit 5
+fi
+
+# Read a state.md field. Tolerates the markdown-bullet rendering ("- Key: val")
+# and a trailing " | none" / "# comment".
+field() {
+  awk -v k="$1" 'match($0, "^[[:space:]]*-?[[:space:]]*" k ":[[:space:]]*") {
+    rest = substr($0, RLENGTH + 1)
+    sub(/[[:space:]]*(#|\|).*$/, "", rest)
+    sub(/[[:space:]]+$/, "", rest)
+    print rest; exit
+  }' "$s"
+}
+
+status="$(field Status)"
+case "$status" in
+  awaiting_human)
+    printf 'readiness: STOP — Status: awaiting_human. Resume with /rite-resolve <qid> "<answer>".\n' >&2
+    exit 3 ;;
+  blocked)
+    printf 'readiness: STOP — Status: blocked. Repair with /rite-plan repair (or unblock).\n' >&2
+    exit 4 ;;
+esac
+
+approved="$(field 'Plan approved')"
+if [ -z "$approved" ] || [ "$approved" = "none" ]; then
+  printf 'readiness: STOP — plan not approved (state.md has no "Plan approved"). Run /rite-define.\n' >&2
+  exit 2
+fi
+
+printf 'readiness: OK — plan approved %s, status %s. Ready to build.\n' "$approved" "${status:-running}"
+exit 0

package/pack/.claude/skills/devrites-lib/scripts/reconcile.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Reconcile gate for /rite-build — proves the orchestrator never edited source
+# itself. The slice-wright (a dispatched subagent) is the ONLY writer of code +
+# tests; the orchestrator writes bookkeeping under .devrites/ and nothing else.
+# This turns that rule (A1: "the orchestrator never edits source") into an exit
+# code instead of a prose promise the model can rationalize past — same doctrine
+# as readiness.sh / tick-afk.sh. Read-only w.r.t. the user's git index.
+#
+# Two phases, both called by /rite-build:
+#   snapshot — step 3, right BEFORE dispatching the wright. Captures the working
+#              tree (tracked + untracked, .gitignore honored) as a git tree
+#              object, without touching the user's real index/staging. The base
+#              file doubles as the "mid-build window" marker: while it exists the
+#              optional pre-block hook (devrites-a1-guard.sh) is armed; a clean
+#              check removes it (a violation keeps it hot until re-dispatch).
+#   check    — step 6 (record), AFTER the wright returns and the orchestrator has
+#              written the wright's reported `Files changed` paths (one per line)
+#              to .devrites/work/<slug>/.reconcile-claimed. Diffs the tree against
+#              the snapshot; every changed path that is NOT under .devrites/ and
+#              NOT in the claimed manifest was edited outside the wright -> STOP.
+#
+# Usage:
+#   reconcile.sh snapshot [slug]
+#   reconcile.sh check    [slug]
+#     slug — optional; defaults to .devrites/ACTIVE
+#
+# Exit codes:
+#   0  ok — clean (check), snapshot written, or gate skipped (non-git repo /
+#      inline fallback) with a printed notice
+#   5  VIOLATION — source changed outside the wright's claimed set: STOP. A1
+#      breach; re-dispatch the wright (continue it once) or revert the edits
+#   6  setup error — bad args, missing snapshot, or missing claimed manifest
+
+set -euo pipefail
+
+mode="${1:-}"
+slug="${2:-$(cat .devrites/ACTIVE 2>/dev/null || true)}"
+
+# Non-git project: nothing to diff against. Skip rather than block the build.
+root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$root" ]; then
+  printf 'reconcile: not a git repo — gate skipped, verify the diff by hand.\n' >&2
+  exit 0
+fi
+
+d=".devrites/work/$slug"
+base="$d/.reconcile-base"
+claimed="$d/.reconcile-claimed"
+inline="$d/.reconcile-inline"
+
+if [ -z "$slug" ] || [ ! -d "$d" ]; then
+  printf 'reconcile: no active workspace (slug=%s) — nothing to reconcile.\n' "${slug:-<unset>}" >&2
+  exit 6
+fi
+
+# Capture the whole working tree (tracked + untracked, .gitignore respected) as a
+# tree object via a throwaway index, so the user's real index/staging is never
+# touched. Prints the tree sha on stdout.
+worktree_tree() {
+  local idx="${TMPDIR:-/tmp}/devrites-reconcile-$$.idx"
+  rm -f "$idx"
+  GIT_INDEX_FILE="$idx" git -C "$root" add -A >/dev/null 2>&1
+  local tree; tree="$(GIT_INDEX_FILE="$idx" git -C "$root" write-tree)"
+  rm -f "$idx"
+  printf '%s\n' "$tree"
+}
+
+# Close the mid-build window: drop the base (disarms the a1-guard hook) and the
+# per-slice manifest/sentinel. Called only when the slice is accepted clean or
+# was the inline fallback — a violation deliberately leaves the window hot.
+close_window() { rm -f "$base" "$claimed" "$inline"; }
+
+case "$mode" in
+  snapshot)
+    rm -f "$inline" "$claimed"   # clear any stale sentinel / prior-slice manifest
+    worktree_tree > "$base"      # base present == mid-build window open
+    printf 'reconcile: snapshot captured for %s.\n' "$slug"
+    exit 0 ;;
+  check)
+    # Inline fallback: the orchestrator legitimately wrote the code itself
+    # (no wright was dispatched), so the gate does not apply.
+    if [ -f "$inline" ]; then
+      printf 'reconcile: inline-fallback run (no wright dispatched) — gate skipped.\n' >&2
+      close_window
+      exit 0
+    fi
+    if [ ! -f "$base" ]; then
+      printf 'reconcile: no snapshot (.reconcile-base) — run "reconcile.sh snapshot" before dispatch.\n' >&2
+      exit 6
+    fi
+    if [ ! -f "$claimed" ]; then
+      printf 'reconcile: no claimed manifest (.reconcile-claimed) — write the wright Files-changed paths first.\n' >&2
+      exit 6
+    fi
+    base_tree="$(cat "$base")"
+    now_tree="$(worktree_tree)"
+    # Every path changed since the snapshot, minus bookkeeping (.devrites/ is the
+    # orchestrator's own legit write target). Anything left that the wright did
+    # not claim was edited by someone other than the wright.
+    viol=0
+    violist=""
+    while IFS= read -r f; do
+      [ -z "$f" ] && continue
+      case "$f" in .devrites/*) continue ;; esac
+      if ! grep -qxF "$f" "$claimed"; then
+        viol=$(( viol + 1 ))
+        violist="${violist}  - ${f}
+"
+      fi
+    done < <(git -C "$root" diff --name-only "$base_tree" "$now_tree")
+    if [ "$viol" -gt 0 ]; then
+      printf 'reconcile: STOP — %d source file(s) changed OUTSIDE the wright (A1 breach):\n' "$viol" >&2
+      printf '%s' "$violist" >&2
+      printf 'The orchestrator must NOT edit source. Re-dispatch the wright (continue it once) or revert these.\n' >&2
+      exit 5
+    fi
+    close_window
+    printf "reconcile: OK — every source change is the wright's; orchestrator touched only bookkeeping.\n"
+    exit 0 ;;
+  *)
+    printf 'reconcile: usage: reconcile.sh <snapshot|check> [slug]\n' >&2
+    exit 6 ;;
+esac

package/pack/.claude/skills/devrites-lib/scripts/resolve.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+# Resolve an open question in the active DevRites workspace.
+# Used by /rite-resolve. Keeps questions.md and state.md consistent.
+#
+# Usage:
+#   resolve.sh <qid> "<answer>"
+#   resolve.sh --drop <qid> ["<reason>"]
+#   resolve.sh --batch <path-to-yaml>
+#   resolve.sh next-qid <questions.md path>
+#
+# Exit codes:
+#   0  resolved
+#   2  no active workspace
+#   3  qid not found
+#   4  qid not open (already answered/dropped)
+#   5  bad arguments
+#   6  qid collision (next-qid: computed id already has a header)
+
+set -u
+
+die() { printf '%s\n' "$*" >&2; exit "${2:-1}"; }
+
+# next-qid: print the next sequential qid for TODAY. Counts existing
+# `## q-YYYY-MM-DD-` headers for today's date, prints q-YYYY-MM-DD-NNN with the
+# next zero-padded id, and refuses (exit 6) if that header already exists.
+# Operates on an explicit questions.md path — no active workspace required.
+if [ "${1:-}" = "next-qid" ]; then
+  qpath="${2:-}"
+  [ -n "$qpath" ] || die "Usage: resolve.sh next-qid <questions.md path>" 5
+  today="$(date +%F)"
+  # A fresh questions.md may not exist yet — treat absent as zero headers.
+  if [ -f "$qpath" ]; then
+    used="$(grep -c "^## q-${today}-" "$qpath" 2>/dev/null || true)"
+  else
+    used=0
+  fi
+  next=$(( used + 1 ))
+  qid="$(printf 'q-%s-%03d' "$today" "$next")"
+  # Defend against gaps/manual edits: never hand out an id that already exists.
+  if [ -f "$qpath" ] && grep -q "^## ${qid}\([[:space:]]\|$\)" "$qpath"; then
+    die "qid already present: $qid (questions.md edited out of sequence)" 6
+  fi
+  printf '%s\n' "$qid"
+  exit 0
+fi
+
+slug="$(cat .devrites/ACTIVE 2>/dev/null || true)"
+[ -n "$slug" ] || die "No active workspace. Run /rite-spec <feature> first." 2
+work=".devrites/work/$slug"
+qfile="$work/questions.md"
+sfile="$work/state.md"
+[ -f "$qfile" ] || die "questions.md missing at $qfile" 2
+[ -f "$sfile" ] || die "state.md missing at $sfile" 2
+
+mode=""
+qid=""
+payload=""
+case "${1:-}" in
+  --drop)
+    mode="drop"
+    qid="${2:-}"
+    payload="${3:-dropped}"
+    ;;
+  --batch)
+    mode="batch"
+    payload="${2:-}"
+    [ -f "$payload" ] || die "Batch file not found: $payload" 5
+    ;;
+  "")
+    die "Usage: resolve.sh <qid> \"<answer>\"  |  --drop <qid> [\"<reason>\"]  |  --batch <file>" 5
+    ;;
+  *)
+    mode="answer"
+    qid="$1"
+    payload="${2:-}"
+    [ -n "$payload" ] || die "Answer text required for $qid" 5
+    ;;
+esac
+
+now() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+
+# Apply a single resolution to questions.md. Awk rewrites the file atomically.
+apply_one() {
+  local _qid="$1" _status="$2" _answer="$3"
+  local _now; _now="$(now)"
+
+  awk -v qid="$_qid" -v st="$_status" -v ans="$_answer" -v ts="$_now" '
+    BEGIN { in_q=0; touched=0; found=0; status_seen=0 }
+    function flush_if_target() {
+      # called when leaving the target block
+      if (in_q && !status_seen) {
+        # malformed entry without status — append the closing fields
+        print "status: " st
+        print "answered_at: " ts
+        print "answer: " ans
+      }
+    }
+    /^## q-/ {
+      flush_if_target()
+      in_q = ($0 ~ ("^## " qid "([[:space:]]|$)"))
+      status_seen = 0
+      if (in_q) { found = 1 }
+      print
+      next
+    }
+    in_q && /^status:/ {
+      status_seen = 1
+      cur = $0; sub(/^status:[[:space:]]*/, "", cur)
+      if (cur != "open") {
+        # signal non-open with sentinel to stderr-equivalent: write file unchanged
+        # we cannot abort from awk cleanly; mark and continue
+        print "status: " cur
+        in_q = 0
+        bad_state = 1
+        next
+      }
+      print "status: " st
+      next
+    }
+    in_q && /^answered_at:/ {
+      print "answered_at: " ts
+      next
+    }
+    in_q && /^answer:/ {
+      print "answer: " ans
+      next
+    }
+    { print }
+    END {
+      flush_if_target()
+      if (!found) exit 10
+      if (bad_state) exit 11
+    }
+  ' "$qfile" > "$qfile.tmp"
+  rc=$?
+
+  if [ "$rc" -eq 10 ]; then
+    rm -f "$qfile.tmp"
+    die "qid not found: $_qid" 3
+  fi
+  if [ "$rc" -eq 11 ]; then
+    rm -f "$qfile.tmp"
+    die "qid not open (already answered/dropped): $_qid" 4
+  fi
+
+  # If the awk output is missing answered_at / answer (entry without those keys),
+  # append them at the end of the block by re-running with insertion mode.
+  mv "$qfile.tmp" "$qfile"
+
+  # Ensure answered_at + answer keys exist for the target qid (insert after `status:` if missing)
+  awk -v qid="$_qid" -v ts="$_now" -v ans="$_answer" '
+    BEGIN { in_q=0; saw_at=0; saw_ans=0; saw_status_line=0 }
+    /^## q-/ {
+      if (in_q) {
+        if (!saw_at)  print "answered_at: " ts
+        if (!saw_ans) print "answer: " ans
+      }
+      in_q = ($0 ~ ("^## " qid "([[:space:]]|$)"))
+      saw_at = 0; saw_ans = 0; saw_status_line = 0
+      print; next
+    }
+    in_q && /^answered_at:/ { saw_at = 1 }
+    in_q && /^answer:/      { saw_ans = 1 }
+    in_q && /^status:/      { saw_status_line = 1 }
+    { print }
+    END {
+      if (in_q) {
+        if (!saw_at)  print "answered_at: " ts
+        if (!saw_ans) print "answer: " ans
+      }
+    }
+  ' "$qfile" > "$qfile.tmp" && mv "$qfile.tmp" "$qfile"
+}
+
+# Update state.md: if the Awaiting human block references the qid, remove the block,
+# flip Status: awaiting_human → running, clear Next step, and append a Log entry.
+# Two-pass: scan to detect a match, then rewrite the file with the side-effects applied.
+clear_state_if_matches() {
+  local _qid="$1"
+  local _now; _now="$(now)"
+
+  # Pass 1: does the Awaiting block reference this qid?
+  local matched
+  matched="$(awk -v qid="$_qid" '
+    BEGIN { in_aw=0; m=0 }
+    /^## Awaiting human/  { in_aw=1; next }
+    in_aw && /^##[[:space:]]/ { in_aw=0 }
+    in_aw {
+      if ($0 ~ ("qid:[[:space:]]*" qid "([[:space:]]|$)")) m=1
+    }
+    END { print m }
+  ' "$sfile")"
+
+  if [ "$matched" != "1" ]; then
+    return 0
+  fi
+
+  # Pass 2: rewrite. Drop the Awaiting human block (header + body until the next `## `),
+  # flip Status, clear Next step, append a Log entry under ## Log.
+  awk -v qid="$_qid" -v ts="$_now" '
+    BEGIN { in_aw=0; in_log=0; log_appended=0 }
+    /^## Awaiting human/ { in_aw=1; next }
+    in_aw && /^##[[:space:]]/ { in_aw=0 }     # next ## header ends the block
+    in_aw { next }                              # swallow lines inside the awaiting block
+
+    /^- Status:/ {
+      print "- Status: running"
+      next
+    }
+    /^- Next step:/ {
+      print "- Next step: (resume — `/rite-build` to continue the workflow)"
+      next
+    }
+    /^## Log/ {
+      print
+      in_log = 1
+      next
+    }
+    in_log && /^##[[:space:]]/ {
+      # leaving the log section — append our entry before this header if we have not yet
+      if (!log_appended) {
+        printf "- %s build: resolved %s\n", ts, qid
+        log_appended = 1
+      }
+      in_log = 0
+      print
+      next
+    }
+    { print }
+
+    END {
+      if (in_log && !log_appended) {
+        printf "- %s build: resolved %s\n", ts, qid
+      }
+    }
+  ' "$sfile" > "$sfile.tmp" && mv "$sfile.tmp" "$sfile"
+}
+
+case "$mode" in
+  answer)
+    apply_one "$qid" "answered" "$payload"
+    clear_state_if_matches "$qid"
+    printf 'Resolved: %s\n' "$qid"
+    printf 'Status:   answered\n'
+    printf 'Workspace: questions.md + state.md updated.\n'
+    ;;
+  drop)
+    apply_one "$qid" "dropped" "$payload"
+    clear_state_if_matches "$qid"
+    printf 'Dropped:  %s\n' "$qid"
+    printf 'Reason:   %s\n' "$payload"
+    printf 'Workspace: questions.md + state.md updated.\n'
+    ;;
+  batch)
+    # Batch format: each line is `qid: <answer>` or `--drop qid: <reason>`. See answer-protocol.md.
+    while IFS= read -r line; do
+      case "$line" in
+        ''|\#*) continue ;;
+        --drop*)
+          rest="${line#--drop }"
+          bid="${rest%%:*}"
+          reason="${rest#*:}"
+          reason="${reason# }"
+          apply_one "$bid" "dropped" "$reason"
+          clear_state_if_matches "$bid"
+          printf 'Dropped:  %s — %s\n' "$bid" "$reason"
+          ;;
+        *)
+          bid="${line%%:*}"
+          ans="${line#*:}"
+          ans="${ans# }"
+          apply_one "$bid" "answered" "$ans"
+          clear_state_if_matches "$bid"
+          printf 'Resolved: %s\n' "$bid"
+          ;;
+      esac
+    done < "$payload"
+    ;;
+esac

package/pack/.claude/skills/devrites-lib/scripts/stuck.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# stuck.sh — loop detector for the unattended build. The slice-wright or orchestrator
+# appends one record per tool action; `check` flags the semantic-repeat patterns that
+# mean the agent is stuck burning tokens (the #1 silent AFK failure mode): the same
+# action repeating, an action<->error ping-pong, or one action dominating the window.
+# A detected loop pauses the build even under AFK (rules/afk-hitl.md). Deterministic;
+# matching is by (tool,target) hash, timestamps ignored.
+#
+#   stuck.sh log   <slug> <tool> [target]   # append one action record (caller)
+#   stuck.sh check <slug> [window]          # non-zero if the recent window looks stuck
+#
+# The log lives at .devrites/work/<slug>/action.log as "<epoch> <tool> <sha1>" lines.
+#
+# Exit codes:
+#   0  ok — not stuck (or logging, or no workspace: never fail the caller on log)
+#   2  bad args
+#   3  STUCK — the recent window is a loop: stop and escalate to a blocking question
+set -u
+
+cmd="${1:-}"; slug="${2:-}"
+[ -n "$cmd" ] && [ -n "$slug" ] || { echo "usage: stuck.sh log|check <slug> [...]" >&2; exit 2; }
+
+dir=".devrites/work/$slug"
+log="$dir/action.log"
+
+hash_of() {
+  if command -v sha1sum >/dev/null 2>&1; then
+    printf '%s' "$1" | sha1sum | awk '{print $1}'
+  else
+    printf '%s' "$1" | shasum | awk '{print $1}'
+  fi
+}
+
+case "$cmd" in
+  log)
+    tool="${3:-}"; target="${4:-}"
+    [ -n "$tool" ] || { echo "usage: stuck.sh log <slug> <tool> [target]" >&2; exit 2; }
+    [ -d "$dir" ] || exit 0
+    printf '%s %s %s\n' "$(date +%s)" "$tool" "$(hash_of "$tool|$target")" >> "$log"
+    ;;
+  check)
+    win="${3:-4}"
+    [ -f "$log" ] || { echo "stuck: no actions logged — not stuck."; exit 0; }
+    awk -v win="$win" '
+      { h[NR]=$3 }
+      END {
+        if (NR < win) { print "stuck: only " NR " action(s) — not stuck."; exit 0 }
+        same=1
+        for (i=NR-win+1; i<=NR; i++) if (h[i]!=h[NR]) { same=0; break }
+        if (same) { print "stuck: last " win " actions identical — STUCK."; exit 3 }
+        if (NR>=6) {
+          pp=1
+          for (i=NR-5; i<=NR; i++) { e=(((NR-i)%2)==0)?h[NR]:h[NR-1]; if (h[i]!=e) { pp=0; break } }
+          if (pp && h[NR]!=h[NR-1]) { print "stuck: A<->B ping-pong over last 6 — STUCK."; exit 3 }
+        }
+        if (NR>=8) {
+          for (i=NR-7;i<=NR;i++) c[h[i]]++
+          top=0; for (k in c) if (c[k]>top) top=c[k]
+          if (top>=6) { print "stuck: one action " top "/8 of recent window — STUCK."; exit 3 }
+        }
+        print "stuck: recent window varied — not stuck."
+      }
+    ' "$log"
+    ;;
+  *)
+    echo "usage: stuck.sh log|check <slug> [...]" >&2; exit 2 ;;
+esac