coding-os 0.3.2__py3-none-any.whl

core/hooks/thinking_os-gate.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# PreToolUse hook: BLOCK Write/Edit on code files until Complexity Gate is recorded.
+# Session-scoped: only accepts gate from the CURRENT session.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+
+# Only enforce for code files
+if [[ "$FILE_PATH" != *.py ]] && [[ "$FILE_PATH" != *.ts ]] && [[ "$FILE_PATH" != *.tsx ]]; then
+  exit 0
+fi
+
+# Skip test files, migrations, generated files, config files
+if [[ "$FILE_PATH" == *test* ]] || [[ "$FILE_PATH" == *spec* ]] || [[ "$FILE_PATH" == *migrations* ]] || [[ "$FILE_PATH" == *node_modules* ]] || [[ "$FILE_PATH" == *__pycache__* ]]; then
+  exit 0
+fi
+
+if [[ "$FILE_PATH" == *.thinking_os-gate ]]; then
+  exit 0
+fi
+
+GATE_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.thinking_os-gate"
+
+# Use session-scoped check
+source "$(dirname "$0")/check-state.sh"
+check_state "$GATE_FILE" 7200  # 120 min
+
+if [[ "$STATE_VALID" != "true" ]]; then
+  echo "BLOCKED: Thinking OS Complexity Gate not valid. Reason: $STATE_REASON" >&2
+  echo "Record gate: bash \".${COS_AGENT}/hooks/write-state.sh\" .thinking_os-gate \"CLEAR 1\"" >&2
+  echo '  (or COMPLICATED/COMPLEX with dimension count)' >&2
+  cos_log_hook thinking_os-gate block "rule=gate-not-recorded" || true
+  exit 2
+fi
+
+# Validate classification
+CLASSIFICATION=$(echo "$STATE_VALUE" | awk '{print $1}')
+if [[ "$CLASSIFICATION" != "CLEAR" ]] && [[ "$CLASSIFICATION" != "COMPLICATED" ]] && [[ "$CLASSIFICATION" != "COMPLEX" ]] && [[ "$CLASSIFICATION" != "CHAOTIC" ]]; then
+  echo "BLOCKED: Invalid classification '$CLASSIFICATION'. Must be CLEAR, COMPLICATED, COMPLEX, or CHAOTIC." >&2
+  cos_log_hook thinking_os-gate block "rule=invalid-classification" || true
+  exit 2
+fi
+
+exit 0

core/hooks/track-backtrack.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# PostToolUse hook: Anti-Paralysis backtrack counter.
+#
+# Fires when cos_backtrack_log is called. Reads the session backtrack
+# count from the tool's output envelope and emits a non-blocking
+# advisory when the count reaches threshold.
+#
+# Thresholds (non-blocking, advisory only):
+#   ≥3 → warn
+#   ≥5 → stronger advisory
+#
+# This hook never blocks — it only informs. Agent autonomy is preserved.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+cos_log_hook "track-backtrack" "entry"
+
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+if [[ "$TOOL" != "mcp__coding-os__cos_backtrack_log" ]]; then
+  exit 0
+fi
+
+# Parse the advisory from the tool output envelope
+ADVISORY=$(echo "$INPUT" | jq -r '.tool_response.data.advisory // empty' 2>/dev/null || echo "")
+COUNT=$(echo "$INPUT" | jq -r '.tool_response.data.count // 0' 2>/dev/null || echo "0")
+
+if [[ -n "$ADVISORY" && "$ADVISORY" != "null" ]]; then
+  cos_log_hook "track-backtrack" "advisory" "count=$COUNT"
+  echo "[Anti-Paralysis] $ADVISORY" >&2
+fi
+
+exit 0

core/hooks/track-discovery.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Discovery Protocol auto-trigger (PostToolUse).
+# Spec: docs/phase-n-role-based-routing-plan.md §2.7
+#
+# Scans agent Write/Edit output for discovery signal phrases. If any match,
+# emits a non-blocking reminder asking the agent to call cos_discovery
+# with impact assessment + decision (backtrack_now | record_for_later).
+#
+# formulas-en.md §Navigation Protocol §4 (Discovery Protocol) mandates:
+#   Never ignore a new discovery. Ignoring = hidden gap.
+# This hook surfaces discoveries automatically rather than relying on
+# the agent to remember the rule.
+#
+# Signal phrases (regex, case-insensitive):
+#   - "I notice" / "I noticed" / "I observed"
+#   - "found a new" / "discovered that" / "turns out"
+#   - "missing (actor|dependency|capability|constraint|edge case)"
+#   - "undocumented" / "undefined" / "hidden"
+#   - "not listed" / "not in the" / "not defined"
+#
+# This hook never blocks — it only reminds. Agent autonomy preserved.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+cos_log_hook "track-discovery" "entry"
+
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+# Only scan Write/Edit — these carry agent-authored prose in file_contents
+# (for Write) or new_string (for Edit). Skip binary/content-free tools.
+case "$TOOL" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+# Pull the body that might contain a discovery signal
+BODY=""
+case "$TOOL" in
+  Write)
+    BODY=$(echo "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null || echo "")
+    ;;
+  Edit)
+    BODY=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null || echo "")
+    ;;
+esac
+
+if [[ -z "$BODY" ]]; then
+  exit 0
+fi
+
+# Regex library — match ≥2 phrases before prompting (reduces false positives)
+PATTERNS=(
+  "I not(e|ice)d?"
+  "I observed"
+  "discovered that"
+  "found a new"
+  "turns out"
+  "missing (actor|dependency|capability|constraint|edge case|scenario)"
+  "undocumented"
+  "undefined (capability|contract|endpoint|behavior)"
+  "hidden (dependency|coupling|state)"
+  "not (listed|defined|in the)"
+  "unknown (actor|dependency|behavior)"
+)
+
+MATCHES=0
+MATCHED_PHRASES=""
+for pat in "${PATTERNS[@]}"; do
+  if echo "$BODY" | grep -Eqi "$pat"; then
+    MATCHES=$((MATCHES + 1))
+    # Capture first 40 chars around the match for context
+    SAMPLE=$(echo "$BODY" | grep -Eoi "$pat" | head -1)
+    MATCHED_PHRASES="${MATCHED_PHRASES}[${SAMPLE}] "
+    if [[ $MATCHES -ge 3 ]]; then
+      break
+    fi
+  fi
+done
+
+# Threshold: need at least 2 distinct signal phrases to avoid FP noise
+if [[ $MATCHES -lt 2 ]]; then
+  exit 0
+fi
+
+# Check if agent already called cos_discovery recently (skip to avoid spam)
+MARKER="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os/claude}}/.last-discovery-reminder"  # panel-first: per-panel cooldown
+NOW=$(date +%s)
+if [[ -f "$MARKER" ]]; then
+  LAST=$(cat "$MARKER" 2>/dev/null || echo "0")
+  # Reminder cooldown: 5 minutes between reminders
+  if (( NOW - LAST < 300 )); then
+    exit 0
+  fi
+fi
+echo "$NOW" > "$MARKER"
+
+cos_log_hook "track-discovery" "reminder" "matches=$MATCHES phrases=$MATCHED_PHRASES"
+
+cat >&2 <<EOF
+[Discovery Protocol] Detected $MATCHES discovery signal phrase(s) in your output:
+  ${MATCHED_PHRASES}
+
+formulas-en.md §Navigation Protocol §4 mandates: record new discoveries
+immediately. If you identified a new actor, state, dependency, constraint,
+or risk during this formula's execution, call:
+
+  cos_discovery(
+    kind=<actor|state|dependency|constraint|risk>,
+    summary="<one-line>",
+    impact_assessment="<which prior formulas are affected>",
+    decision=<"backtrack_now"|"record_for_later">
+  )
+
+Non-blocking — continuing. But if ignored, the discovery becomes a
+hidden gap (Reviewer Layer 3 will flag it as an uncovered edge case).
+EOF
+
+exit 0

core/hooks/track-skill.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# PostToolUse hook: Track which skill was invoked by writing to
+# $COS_PANEL_DIR/.active-skill (per-panel — two Claude tabs
+# track their own skill stacks independently).
+# Session-scoped: prefixes with current session ID.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+# Upgrade panel-id from stdin so sibling Claude panels don't collide.
+INPUT="$(cos_read_stdin_bounded 2)"
+cos_panel_upgrade_from_payload "$INPUT" 2>/dev/null || true
+
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+# Only track Skill tool invocations
+if [[ "$TOOL" != "Skill" ]]; then
+  exit 0
+fi
+
+SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // empty' 2>/dev/null || echo "")
+
+if [[ -n "$SKILL_NAME" ]]; then
+  SESSION_FILE="$COS_SESSION_FILE"
+  SESSION_ID=""
+  if [[ -f "$SESSION_FILE" ]]; then
+    SESSION_ID=$(cat "$SESSION_FILE")
+  fi
+  # Fall back to panel-id when session-id file is empty (fresh panel,
+  # SessionStart never fired yet).
+  [[ -z "$SESSION_ID" && -n "${COS_PANEL_ID:-}" ]] && SESSION_ID="$COS_PANEL_ID"
+  # Write session-scoped: "session-id skill1 skill2 ..."
+  # Append skill to existing value if same session, else reset.
+  SKILL_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.active-skill"
+  mkdir -p "$(dirname "$SKILL_FILE")" 2>/dev/null || true
+  if [[ -f "$SKILL_FILE" ]]; then
+    EXISTING_SESSION=$(head -1 "$SKILL_FILE" | awk '{print $1}')
+    if [[ "$EXISTING_SESSION" == "$SESSION_ID" ]]; then
+      # Same session — append skill
+      EXISTING_SKILLS=$(head -1 "$SKILL_FILE" | cut -d' ' -f2-)
+      echo "$SESSION_ID $EXISTING_SKILLS $SKILL_NAME" > "$SKILL_FILE"
+      cos_record_activity skill "${SKILL_NAME}" 2>/dev/null || true
+      printf '{"systemMessage":%s}' "$(printf '[skill] %s' "$SKILL_NAME" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+      exit 0
+    fi
+  fi
+  # New session or no file — start fresh
+  echo "$SESSION_ID $SKILL_NAME" > "$SKILL_FILE"
+  cos_record_activity skill "${SKILL_NAME}" 2>/dev/null || true
+  printf '{"systemMessage":%s}' "$(printf '[skill] %s' "$SKILL_NAME" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+fi
+
+exit 0

core/hooks/validate-task-frontmatter.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# PreToolUse: Write/Edit on docs/tasks/*.md
+# Validates the lean frontmatter (id/swimlane/kind/epic/labels/
+# status/priority/appetite/depends_on) before the file is written.
+# Also enforces WIP caps when status transitions to in_progress/emergency,
+# and rejects dependency cycles (R-L-29).
+#
+# Fail-soft: if board_os python module is unavailable (e.g. fresh clone
+# before `uv sync`), hook warns but does NOT block — avoids bricking
+# the session on toolchain drift.
+
+set -euo pipefail
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+
+cos_log_hook "validate-task-frontmatter" "entry" 2>/dev/null || true
+
+# Read JSON payload from stdin (Claude/Codex hook input format).
+payload="$(cos_read_stdin_bounded 5)"
+
+# Only act on docs/tasks/*.md writes.
+file_path="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")"
+
+if [[ -z "$file_path" ]] || [[ "$file_path" != *"docs/tasks/"*.md ]]; then
+    exit 0
+fi
+
+# Skip if file doesn't exist yet (Write creating new) — we need the
+# candidate content. The hook protocol passes `content` in tool_input.
+# bash 5.3.9 deadlocks `python3 - <<HEREDOC`; helper file is the safe form.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+HSRC="$(cd -P "$(dirname "$_src")" && pwd)"
+unset _src _dir
+HELPER="${HSRC}/_helpers/validate_task_frontmatter.py"
+if [[ -f "$HELPER" ]]; then
+  python3 "$HELPER" "$payload"
+else
+  exit 0
+fi
+
+exit_code=$?
+cos_log_hook "validate-task-frontmatter" "$([[ $exit_code -eq 0 ]] && echo allow || echo block)" 2>/dev/null || true
+exit $exit_code

core/hooks/verify-rename-callers.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# verify-rename-callers.sh — PostToolUse Edit
+#
+# PURPOSE
+#   When an Edit performs an identifier rename (old_string/new_string are
+#   both short identifiers and look like a rename), grep the rest of the
+#   repo for the OLD name. If callers still reference it, emit a warning
+#   so the agent updates them in the same task.
+#
+#   Closes the gap left by enforce-rename-plan (which verifies a *plan*
+#   exists, not that all *call sites* were updated).
+#
+# ESCALATION (default warn, opt-in block)
+#   On unreplaced callers it records a durable `.rename-incomplete` marker
+#   (so the signal survives past this turn's stderr) and warns. Default stays
+#   non-blocking — >0 callers is a signal the agent judges (docs referencing a
+#   historical name, a BC shim). COS_VERIFY_RENAME_CALLERS=strict promotes the
+#   warning to a hard block (exit 2) for projects that enforce completeness.
+#
+# DESIGN NOTES
+#   - Skip when old_string is too short (<4 chars) or non-identifier-shaped
+#     to avoid false positives.
+#   - Skip files where the old name lives in code comments or docstrings
+#     about migration history (heuristic: "renamed from", "was called").
+#   - Cap output at 10 callers to keep the message readable.
+
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+cos_log_hook verify-rename-callers entry 2>/dev/null || true
+
+PAYLOAD="$(cos_read_stdin_bounded 2)"
+[[ -z "$PAYLOAD" ]] && exit 0
+
+OLD_NEW="$(printf '%s' "$PAYLOAD" | python3 -c '
+import sys, json
+try:
+    payload = json.loads(sys.stdin.read() or "{}")
+except Exception:
+    print("")
+    raise SystemExit(0)
+ti = payload.get("tool_input", {}) or {}
+old = ti.get("old_string", "") or ti.get("find", "")
+new = ti.get("new_string", "") or ti.get("replace", "")
+fp = ti.get("file_path", "")
+print(f"{fp}|{old}|{new}")
+' 2>/dev/null || true)"
+
+FILE_PATH="${OLD_NEW%%|*}"
+REST="${OLD_NEW#*|}"
+OLD="${REST%%|*}"
+NEW="${REST#*|}"
+
+# Bail on missing or unsuitable inputs.
+if [[ -z "$OLD" || -z "$NEW" || "$OLD" == "$NEW" ]]; then
+  exit 0
+fi
+if [[ "${#OLD}" -lt 4 || "${#OLD}" -gt 60 ]]; then
+  exit 0
+fi
+if ! [[ "$OLD" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+  exit 0
+fi
+if ! [[ "$NEW" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+  exit 0
+fi
+
+# Cheap reject: if old_string contains spaces or newlines it isn't an
+# identifier rename — likely a content edit.
+case "$OLD" in
+  *" "*|*$'\n'*) exit 0 ;;
+esac
+
+# Find repo root (so git grep works regardless of cwd).
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+[[ -z "$REPO_ROOT" ]] && exit 0
+cd "$REPO_ROOT" || exit 0
+
+# Search for unreplaced references. Word-regex prevents `frob` matching
+# `frobnicate`. Limit -l to file list, then -n on hits, capped at 10. The
+# git grep is wrapped in a 5s perl alarm (macOS lacks timeout(1)) so a
+# 100K-file working tree can never hang the edit — fail-open to no warning,
+# since cos_graph_rename_plan is the authoritative caller-finder. TASK-229.
+HITS="$(perl -e 'alarm shift; exec @ARGV' 5 git grep -l --word-regexp -- "$OLD" 2>/dev/null | grep -v "${FILE_PATH#$REPO_ROOT/}" | head -10 || true)"
+[[ -z "$HITS" ]] && {
+  cos_log_hook verify-rename-callers ok "all call sites updated" 2>/dev/null || true
+  exit 0
+}
+
+COUNT=$(printf '%s\n' "$HITS" | grep -c .)
+cos_log_hook verify-rename-callers warn "old=${OLD} unreplaced_files=${COUNT}" 2>/dev/null || true
+
+# Escalation marker — durable record that a rename was left incomplete, so the
+# signal outlives this turn's stderr (a Stop-phase reviewer / retro can act on
+# it). Panel-scoped, appended; GC'd with the rest of panel state.
+MARKER_DIR="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os}}"
+mkdir -p "$MARKER_DIR" 2>/dev/null || true
+printf '%s\t%s\t%s\t%s\n' "$OLD" "$NEW" "$COUNT" "$FILE_PATH" >> "${MARKER_DIR}/.rename-incomplete" 2>/dev/null || true
+
+cat >&2 <<MSG
+🔁 Rename caller-check — \`${OLD}\` → \`${NEW}\`
+   Edited: ${FILE_PATH}
+   But \`${OLD}\` still appears in ${COUNT} other file(s):
+$(printf '     - %s\n' $HITS)
+
+   Either:
+   • Update those call sites in the same task, OR
+   • Confirm intentional retention (docs about history, BC shim).
+
+   Verify with: cos verify --since HEAD --refs --no-tests
+MSG
+
+if [[ "${COS_VERIFY_RENAME_CALLERS:-warn}" == "strict" ]]; then
+  cos_log_hook verify-rename-callers block "old=${OLD} unreplaced_files=${COUNT}" 2>/dev/null || true
+  exit 2
+fi
+exit 0

core/hooks/warn-abandoned-task.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# warn-abandoned-task.sh — Stop hook.
+#
+# Warns at turn-end about two abandonment shapes owned by THIS session:
+#   1. a task moved to in_progress/testing and left open (the classic
+#      "started but never completed" strand), and
+#   2. a card the session CREATED and left un-ready in icebox — a silent
+#      create-then-park, invisible to cos_task_pick/claim_next (attributed
+#      via the task_status_history 'created' row; ready/parked/keep exempt).
+# Fail-open: never blocks the Stop, only nudges via a Stop additionalContext
+# block. Debounced per (session-id, open-set) so it re-arms on state change.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+cos_log_hook warn-abandoned-task enter || true
+
+[ -f "${COS_DB_PATH:-}" ] || exit 0
+# Upgrade panel id from the Stop payload so $COS_SESSION_FILE
+# resolves THIS panel; fall back to stdin session_id then legacy agent-dir.
+INPUT="$(cos_read_stdin_bounded 2 2>/dev/null || true)"
+command -v cos_panel_upgrade_from_payload >/dev/null 2>&1 && cos_panel_upgrade_from_payload "$INPUT" 2>/dev/null || true
+SESSION_ID="$(cat "${COS_SESSION_FILE:-}" 2>/dev/null || true)"
+if [ -z "$SESSION_ID" ] && [ -n "$INPUT" ] && command -v jq >/dev/null 2>&1; then
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // .sessionId // empty' 2>/dev/null || true)
+fi
+if [ -z "$SESSION_ID" ] && [ -f "${COS_AGENT_DIR}/session-id" ]; then
+  SESSION_ID=$(cat "${COS_AGENT_DIR}/session-id" 2>/dev/null || true)
+fi
+[ -n "$SESSION_ID" ] || exit 0
+# Session-id is alnum + dash only; reject anything else before it reaches SQL.
+case "$SESSION_ID" in
+  *[!A-Za-z0-9-]*) exit 0 ;;
+esac
+
+# Compute the open set FIRST so the debounce can re-arm when it changes.
+# `testing` is included: the testing-first protocol parks near-done work there,
+# so it is the status a task most often dies in. A task bound in a LIVE
+# sibling panel is skipped — two panels can share one session id (resumed
+# conversation), and warning the idle one about its sibling's live work
+# invited "rescue" parks (the phantom NULL-reason reverts).
+STUCK=""
+while IFS='|' read -r _t _s; do
+  [ -n "$_t" ] || continue
+  if command -v cos_task_bound_in_live_sibling >/dev/null 2>&1 \
+     && cos_task_bound_in_live_sibling "$_t"; then
+    continue
+  fi
+  STUCK="${STUCK:+$STUCK, }$_t ($_s)"
+done < <(sqlite3 "$COS_DB_PATH" \
+  "SELECT task_id || '|' || status FROM tasks
+   WHERE status IN ('in_progress','testing') AND agent_session = '$SESSION_ID';" \
+  2>/dev/null || true)
+
+# Create-then-park: icebox cards THIS session CREATED and left un-ready. The
+# creating session comes from the task_status_history 'created' row (old_status=''
+# sentinel written by cos_task_create), so a parked card whose tasks.agent_session
+# is NULL is still attributed to its author — the exact blind spot warn-abandoned
+# had on the parked lane. A 'ready' card is a deliberate pull-queue and a
+# 'parked'/'keep' card is deliberate backlog: both exempt (COALESCE so a card with
+# no labels_json still matches). Only silent create-then-drift is surfaced.
+PARKED="$(sqlite3 "$COS_DB_PATH" \
+  "SELECT group_concat(t.task_id, ', ') FROM tasks t
+   JOIN task_status_history h
+     ON h.task_id = t.task_id AND h.old_status = '' AND h.reason = 'created'
+   WHERE t.status = 'icebox' AND h.agent_session = '$SESSION_ID'
+     AND COALESCE(t.labels_json,'') NOT LIKE '%\"ready\"%'
+     AND COALESCE(t.labels_json,'') NOT LIKE '%\"parked\"%'
+     AND COALESCE(t.labels_json,'') NOT LIKE '%\"keep\"%';" \
+  2>/dev/null || true)"
+[ -n "$STUCK$PARKED" ] || exit 0
+
+# Debounce keyed on (session-id, both open-sets), not session-id alone — so the
+# nudge re-arms on any state-change (in_progress→testing, a close+open, a new
+# parked card) instead of going silent for the whole session after the first
+# warning (the "85%-done then stopped" gap). An unchanged set stays debounced.
+MARKER="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.abandoned-task-warned"  # panel-first: matches session-context panel-scope clear
+STUCK_SIG=$(printf '%s' "$STUCK|$PARKED" | cksum | cut -d' ' -f1)
+DEBOUNCE_KEY="${SESSION_ID}:${STUCK_SIG}"
+if [ -f "$MARKER" ] && grep -qF "$DEBOUNCE_KEY" "$MARKER" 2>/dev/null; then
+  exit 0
+fi
+
+echo "$DEBOUNCE_KEY" >> "$MARKER"
+cos_log_hook warn-abandoned-task warn || true
+MSG=""
+if [ -n "$STUCK" ]; then
+  MSG="[board] Task(s) still open for this session: ${STUCK}. Close each with \`cos task-done\` (or park via \`cos task-move --to blocked --reason '<why>'\`) — a task left in in_progress/testing is stranded on the board with no owner action. Never park work you did not start this conversation."
+fi
+if [ -n "$PARKED" ]; then
+  [ -n "$MSG" ] && MSG="${MSG}"$'\n'
+  MSG="${MSG}[board] Card(s) you created and left un-ready in icebox this session: ${PARKED}. An un-ready icebox card is invisible to \`cos_task_pick\`/\`cos_task_claim_next\` — nobody will pull it. Start it (\`cos task-start\`), queue it (\`cos task-ready\`), or add a \`parked\`/\`keep\` label if it is deliberate long-term backlog."
+fi
+printf '{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":%s}}\n' \
+  "$(printf '%s' "$MSG" | jq -R -s '.')"
+
+cos_log_hook warn-abandoned-task ok || true
+exit 0

core/hooks/warn-destructive-edit.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# warn-destructive-edit.sh
+# PreToolUse Write|Edit|MultiEdit — friction before destruction: warn (strict = block)
+# before a large net-deletion/overwrite of a load-bearing file, pointing at the git
+# command to see what was there. Self-throttling + fail-open. Spec:
+# docs/engineering/destructive-edit-guard.md
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+# Default-on at "warn". Opt-out: COS_DESTRUCTIVE_GUARD=off. Stricter: =strict (block on hit).
+MODE="${COS_DESTRUCTIVE_GUARD:-1}"
+if [[ "$MODE" == "off" || "$MODE" == "0" ]]; then
+  cos_log_hook warn-destructive-edit disabled || true
+  exit 0
+fi
+
+INPUT="$(cos_read_stdin_bounded 2 2>/dev/null || true)"
+if [[ -z "$INPUT" ]]; then
+  cos_log_hook warn-destructive-edit no-input || true
+  exit 0
+fi
+
+CONFIG="${COS_STATE_DIR:-.coding-os}/rag-config.yaml"
+[[ -f "$CONFIG" ]] || CONFIG="$(pwd)/.coding-os/rag-config.yaml"
+
+# Resolve the real hook dir (symlink-safe) to find the helper — same idiom as enforce-graph-context.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+HSRC="$(cd -P "$(dirname "$_src")" && pwd)"
+unset _src _dir
+HELPER="${HSRC}/_helpers/destructive_edit_check.py"
+if [[ ! -f "$HELPER" ]]; then
+  cos_log_hook warn-destructive-edit no-helper || true
+  exit 0
+fi
+
+VERDICT="$(printf '%s' "$INPUT" | python3 "$HELPER" "$CONFIG" 2>/dev/null || true)"
+if [[ -z "$VERDICT" ]]; then
+  cos_log_hook warn-destructive-edit no-verdict || true
+  exit 0
+fi
+
+FLAGGED="$(printf '%s' "$VERDICT" | jq -r '.flagged // false' 2>/dev/null || echo false)"
+if [[ "$FLAGGED" != "true" ]]; then
+  cos_log_hook warn-destructive-edit ok || true
+  exit 0
+fi
+
+MSG="$(printf '%s' "$VERDICT" | jq -r '.message // empty' 2>/dev/null || true)"
+if [[ "$MODE" == "strict" ]]; then
+  printf 'BLOCKED: %s\n' "$MSG" >&2
+  printf '  to proceed: split the deletion into a separate reviewed change, or set COS_DESTRUCTIVE_GUARD=warn.\n' >&2
+  cos_log_hook warn-destructive-edit block || true
+  exit 2
+fi
+printf 'warning: %s\n' "$MSG" >&2
+cos_log_hook warn-destructive-edit warn || true
+exit 0

core/hooks/warn-diff-size.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# warn-diff-size.sh
+# PreToolUse Bash — nudge toward diff-minimal commits: when a `git commit` is
+# about to run, warn (never block) if the staged diff exceeds a line threshold.
+# Fail-open: any uncertainty exits 0. Spec: docs/tasks/TASK-635.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+MODE="${COS_DIFF_SIZE_WARN:-1}"
+if [[ "$MODE" == "off" || "$MODE" == "0" ]]; then
+  cos_log_hook warn-diff-size disabled || true
+  exit 0
+fi
+
+INPUT="$(cos_read_stdin_bounded 2 2>/dev/null || true)"
+[[ -z "$INPUT" ]] && exit 0
+
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+[[ -z "$CMD" ]] && exit 0
+
+# Only react to a real `git commit` (allow a leading path / env / cd prefix).
+echo "$CMD" | grep -qE '(^|[;&|[:space:]])git([[:space:]]+-[^[:space:]]+)*[[:space:]]+commit([[:space:]]|$)' || exit 0
+# --amend rewrites an existing commit; its size is not new churn to nudge.
+echo "$CMD" | grep -qE 'commit[^|;&]*--amend' && exit 0
+
+THRESHOLD="${COS_DIFF_SIZE_THRESHOLD:-400}"
+# Measure the churn the commit will actually produce. The trunk convention is
+# `git commit <path>` (working-tree paths, never `git add`-ed), so an empty
+# staged diff falls back to the tracked working-tree diff vs HEAD.
+STAT=$(git diff --cached --numstat 2>/dev/null || true)
+[[ -z "$STAT" ]] && STAT=$(git diff --numstat HEAD 2>/dev/null || true)
+[[ -z "$STAT" ]] && exit 0
+
+TOTAL=$(echo "$STAT" | awk '{ if ($1 ~ /^[0-9]+$/) a+=$1; if ($2 ~ /^[0-9]+$/) d+=$2 } END { print a+d+0 }')
+[[ "$TOTAL" =~ ^[0-9]+$ ]] || exit 0
+
+if [ "$TOTAL" -gt "$THRESHOLD" ]; then
+  echo "⚠️  diff-size: staged commit changes $TOTAL lines (> $THRESHOLD). Anti-overengineering: prefer smaller, single-purpose commits. Tune COS_DIFF_SIZE_THRESHOLD; silence with COS_DIFF_SIZE_WARN=off." >&2
+  cos_log_hook warn-diff-size "large:$TOTAL" || true
+fi
+exit 0