coding-os 0.3.2__py3-none-any.whl

core/hooks/session-end.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# Stop hook: Record enriched session summary to coding-os.db.
+# Agent-agnostic: uses COS_STATE_DIR and COS_DB_PATH.
+# Fire-and-forget — never blocks or errors visibly.
+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
+
+# Resolve physical hooks dir for symlink-safe thinking_os lookup.
+_cos_src="${BASH_SOURCE[0]}"
+while [ -L "$_cos_src" ]; do
+  _cos_dir="$(cd -P "$(dirname "$_cos_src")" && pwd)"
+  _cos_src="$(readlink "$_cos_src")"
+  [[ "$_cos_src" != /* ]] && _cos_src="${_cos_dir}/${_cos_src}"
+done
+_COS_HOOKS_PHYS="$(cd -P "$(dirname "$_cos_src")" && pwd)"
+unset _cos_src _cos_dir
+
+# Upgrade panel id from the Stop payload's session_id so $COS_SESSION_FILE
+# resolves THIS panel — without it, a Stop that never saw a
+# SessionStart for the panel reads an empty session-id and every downstream
+# summary/enrich/recap silently no-ops.
+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=""
+if [ -f "$COS_SESSION_FILE" ]; then
+  SESSION_ID=$(cat "$COS_SESSION_FILE" 2>/dev/null || true)
+fi
+# Fallbacks: stdin session_id, then legacy agent-dir session-id.
+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
+# No extra `session=` in the detail — cos_log_hook already emits the
+# identity triplet (agent=X session=Y task=Z) in the standard prefix.
+cos_log_hook session-end fire
+
+if [ ! -f "$COS_DB_PATH" ]; then
+  exit 0
+fi
+
+ACTIVE_TASK=""
+_TASK_CURRENT="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.task-current"  # panel-first
+if [ -f "$_TASK_CURRENT" ]; then
+  ACTIVE_TASK=$(grep -oE 'TASK-([A-Z][A-Z0-9]*-)?[0-9]+' "$_TASK_CURRENT" 2>/dev/null | head -1 || true)
+fi
+
+run_bounded_python() {
+  local script="$1"
+  local timeout_s="${2:-2}"
+  local rc
+  rc=$(python3 -c '
+import subprocess
+import sys
+
+script, timeout_s, *args = sys.argv[1:]
+try:
+    p = subprocess.run(
+        [sys.executable, script, *args],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        timeout=float(timeout_s),
+        check=False,
+    )
+    print(p.returncode)
+except Exception:
+    pass
+' "$script" "$timeout_s" "$SESSION_ID" "$ACTIVE_TASK" "$COS_DB_PATH" 2>/dev/null || true)
+  # A broken as-file script exits non-zero but its stderr is DEVNULL'd — leave
+  # one breadcrumb in `cos hooks-log` so the failure is visible. A timeout (no
+  # rc printed) or a clean exit stays silent.
+  if [[ "$rc" =~ ^[1-9][0-9]*$ ]]; then
+    cos_log_hook session-end child-failed "script=$(basename "$script") rc=${rc}" 2>/dev/null || true
+  fi
+}
+
+# Find scripts in coding-os core — physical path resolves symlinked installs.
+SUMMARY_PY="${_COS_HOOKS_PHYS}/../thinking_os/session_summary.py"
+if [ -f "$SUMMARY_PY" ]; then
+  run_bounded_python "$SUMMARY_PY" 2
+fi
+
+ENRICH_PY="${_COS_HOOKS_PHYS}/../thinking_os/session_enrich.py"
+if [ -f "$ENRICH_PY" ]; then
+  run_bounded_python "$ENRICH_PY" 2
+fi
+
+# Auto-trajectory: derive trajectory snapshot from this session's
+# formula_dispatches + backtrack_events → future sessions inherit project intent.
+AUTOSNAP_PY="${_COS_HOOKS_PHYS}/_helpers/trajectory_autosnap.py"
+if [ -f "$AUTOSNAP_PY" ]; then
+  run_bounded_python "$AUTOSNAP_PY" 2
+fi
+
+# Responsive learning — extract patterns same-day once enough new task_outcomes
+# accrue (scheduled config threshold) instead of waiting for the nightly cron.
+# Shares the .last-extract marker with nightly.py so the paths stay idempotent.
+RESPONSIVE_PY="${_COS_HOOKS_PHYS}/../scheduled/responsive_extract.py"
+if [ -f "$RESPONSIVE_PY" ]; then
+  run_bounded_python "$RESPONSIVE_PY" 3
+fi
+
+# End-of-turn visible recap — Stop hooks accept hookSpecificOutput JSON, which
+# Claude Code surfaces as a labeled additionalContext block between turns.
+# Mirrors the always-on caveman pattern so the operator never sees a silent
+# session boundary. Bounded fire-and-forget — never blocks.
+RECAP_PY="${_COS_HOOKS_PHYS}/_helpers/session_recap.py"
+if [ -f "$RECAP_PY" ] && [ -f "$COS_DB_PATH" ] && [ -n "$SESSION_ID" ]; then
+  python3 "$RECAP_PY" "$COS_DB_PATH" "$SESSION_ID" 2>/dev/null || true
+fi
+
+# Uncommitted-work advisory: surface work the agent may have forgotten to commit
+# at end-of-turn — docs/**/*.md (audit-trail truth) AND non-docs code (src/**,
+# tests/, …). Fire-and-forget — never blocks (exit stays 0 regardless). Two
+# deliberate scope limits (TASK-564):
+#   • no still-open-task nudge here — the sibling warn-abandoned-task.sh Stop hook
+#     already emits it (debounced per session); duplicating it would double-nudge.
+#   • no unpushed-commits nudge — push is deferred to task-close by the trunk
+#     workflow, so a per-turn "N unpushed" line would be noise that fights the rule.
+if command -v git >/dev/null 2>&1; then
+  # Anchor every status query to the repo TOP-LEVEL: a cwd-relative `git status`
+  # fired from a SUBDIR only sees that subtree, so root-level changes were missed
+  # entirely (TASK-566 J). Skip the block cleanly when not inside a repo.
+  _top=$(git rev-parse --show-toplevel 2>/dev/null || true)
+  if [ -n "$_top" ]; then
+    # Audit-trail docs: ANY uncommitted file under docs/ EXCEPT board churn under
+    # docs/tasks/. Count non-.md too — a png/json/asset under docs/ is audit trail
+    # and was previously counted by NEITHER advisory (TASK-566 N).
+    _uncommitted_docs=$(git -C "$_top" status --porcelain -- docs ':(exclude)docs/tasks' 2>/dev/null | grep -cE '.' 2>/dev/null || true)
+    if [ "${_uncommitted_docs:-0}" -gt 0 ] 2>/dev/null; then
+      echo "advisory: ${_uncommitted_docs} uncommitted doc(s) under docs/ — commit so the audit trail matches the repo (git status -- docs)." >&2
+    fi
+    # Non-docs code: porcelain entries outside docs/ (board churn under docs/tasks/
+    # is excluded, so this fires only on genuine code left uncommitted).
+    _uncommitted_code=$(git -C "$_top" status --porcelain -- . ':(exclude)docs' 2>/dev/null | grep -cE '.' 2>/dev/null || true)
+    if [ "${_uncommitted_code:-0}" -gt 0 ] 2>/dev/null; then
+      echo "advisory: ${_uncommitted_code} uncommitted code change(s) outside docs/ — commit each logical unit before ending the turn (git status)." >&2
+    fi
+    unset _uncommitted_docs _uncommitted_code 2>/dev/null || true
+  fi
+fi

core/hooks/session-skill-primer.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# SessionStart hook — prime agent with required-skill card per active stack.
+#
+# Purpose: At fresh-startup, emit a compact additionalContext card
+# listing the skills that PreToolUse Write/Edit (enforce-skill.sh) will
+# BLOCK without. Closes the gap where the agent only discovers required
+# skills reactively after the first block. Reads SSOT:
+#   $COS_STATE_DIR/installed-manifest.json::templates   → active stacks
+#   src/templates/<stack>/stack.yaml                    → primary_skill + skill_enforcement
+#
+# SessionStart::startup fires once per session — no debounce needed.
+# Always exits 0.
+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 session-skill-primer fire
+
+# Resolve physical hooks dir so the helper path works even when
+# .claude/hooks/<script>.sh is a symlink into src/core/hooks/.
+_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/skill_primer.py"
+if [[ ! -f "$HELPER" ]]; then
+  exit 0
+fi
+
+CONTEXT=$(python3 "$HELPER" 2>/dev/null || true)
+if [[ -z "$CONTEXT" ]]; then
+  exit 0
+fi
+
+printf '%s' "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"
+
+exit 0

core/hooks/snapshot-transcript.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# snapshot-transcript.sh (Stop) — copy the live session transcript into the
+# repo so a workflow session is auditable in-tree, not only in the agent
+# runtime's global store (~/.claude/projects/...). Fires on Stop (the
+# canonical session-end signal — Claude Code has no SessionEnd event).
+# Fail-open telemetry: never blocks, only copies when the source moved.
+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 snapshot-transcript enter || true
+
+# Opt-in only: snapshotting the full chat transcript is OFF by default — the
+# conversation is NOT saved into the repo unless explicitly enabled (privacy).
+# Set COS_SNAPSHOT_TRANSCRIPT=1 to re-enable (e.g. for cognition trace-replay).
+if [[ "${COS_SNAPSHOT_TRANSCRIPT:-0}" != "1" ]]; then
+  cos_log_hook snapshot-transcript skip || true
+  exit 0
+fi
+
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# transcript_path is provided by the agent runtime in the Stop payload.
+# Absent (or file gone) → nothing to snapshot; fail-open.
+TRANSCRIPT=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null || echo "")
+if [[ -z "$TRANSCRIPT" || ! -f "$TRANSCRIPT" ]]; then
+  exit 0
+fi
+
+# Name the snapshot by this panel's session-id so it lines up with the
+# tasks.agent_session attribution (that IS the task↔session link).
+SID=""
+if [[ -n "${COS_SESSION_FILE:-}" && -f "$COS_SESSION_FILE" ]]; then
+  SID=$(tr -d '\n\r' < "$COS_SESSION_FILE" 2>/dev/null || true)
+fi
+[[ -z "$SID" ]] && SID="${COS_PANEL_ID:-unknown}"
+# Strip anything path-hostile from the id before using it as a filename.
+SID=$(printf '%s' "$SID" | tr -c 'A-Za-z0-9_.-' '-')
+[[ -z "$SID" ]] && exit 0
+
+DEST_DIR="${COS_AGENT_DIR:-.coding-os}/sessions/transcripts"
+mkdir -p "$DEST_DIR" 2>/dev/null || true
+DEST="${DEST_DIR}/${SID}.jsonl"
+
+# Stop fires every turn, so only copy when the transcript actually grew —
+# avoids re-copying a multi-MB jsonl on every turn of a long session.
+if [[ ! -f "$DEST" || "$TRANSCRIPT" -nt "$DEST" ]]; then
+  TMP="${DEST}.tmp.$$"
+  if cp -f "$TRANSCRIPT" "$TMP" 2>/dev/null; then
+    mv -f "$TMP" "$DEST" 2>/dev/null || rm -f "$TMP" 2>/dev/null || true
+  fi
+fi
+
+cos_log_hook snapshot-transcript ok || true
+exit 0

core/hooks/sync-task-current.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# sync-task-current.sh (PostToolUse) — fan-out: auto-write the per-panel
+# .task-current marker when a task transitions to in_progress, so the agent
+# never hand-runs `write-state.sh .task-current` after cos task-start /
+# cos_task_move (the screenshot-3 anti-pattern).
+#
+# Panel-env reliable: a PostToolUse hook runs in the session process
+# lineage, so write-state.sh resolves the correct $COS_PANEL_DIR (the MCP
+# server and a `cos` CLI subprocess do NOT — they resolve a stale/other
+# panel). That is why this fan-out is a hook, not an MCP/CLI side effect.
+#
+# Fail-open: always exit 0; a failed marker write never affects the move.
+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
+
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# Fast-path: this fan-out only acts on task transitions — the cos_task_move
+# tool or a Bash `cos task-start|task-move|task-done`. Every trigger contains
+# the literal "task". If the raw payload has no "task" there is nothing to sync;
+# bail before the panel-upgrade + jq spawns (fires on EVERY Bash tool call).
+case "$INPUT" in
+  *task*) ;;
+  *) exit 0 ;;
+esac
+
+# Upgrade panel id from stdin session_id so the write-state.sh
+# subprocess below resolves THIS panel's dir, not a stale ppid-derived one.
+command -v cos_panel_upgrade_from_payload >/dev/null 2>&1 && cos_panel_upgrade_from_payload "$INPUT" 2>/dev/null || true
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+# A task leaving active work (complete/done/archived/blocked) must FREE the
+# marker — otherwise it fossilises (the TASK-052 stale marker) and a later
+# commit / banner is wrongly attributed to a finished task. testing keeps the
+# marker (still the active task; tests run before done).
+_CLEAR_STATES='complete|done|archived|blocked'
+
+TASK_ID=""        # set the marker to this
+CLEAR_FOR=""      # clear the marker IF it points at this
+case "$TOOL" in
+  *cos_task_move*)
+    TO=$(echo "$INPUT" | jq -r '.tool_input.to // empty' 2>/dev/null || echo "")
+    TID=$(echo "$INPUT" | jq -r '.tool_input.task_id // empty' 2>/dev/null || echo "")
+    if [[ "$TO" == "in_progress" ]]; then
+      TASK_ID="$TID"
+    elif [[ "$TO" =~ ^(${_CLEAR_STATES})$ ]]; then
+      CLEAR_FOR="$TID"
+    else
+      exit 0
+    fi
+    ;;
+  Bash)
+    CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+    if printf '%s' "$CMD" | grep -qE 'cos +task-start +TASK-([A-Z][A-Z0-9]*-)?[0-9]+' 2>/dev/null; then
+      TASK_ID=$(printf '%s' "$CMD" | grep -oE 'TASK-([A-Z][A-Z0-9]*-)?[0-9]+' | head -1 || echo "")
+    elif printf '%s' "$CMD" | grep -qE 'cos +task-move +TASK-([A-Z][A-Z0-9]*-)?[0-9]+.*--to +in_progress' 2>/dev/null; then
+      TASK_ID=$(printf '%s' "$CMD" | grep -oE 'TASK-([A-Z][A-Z0-9]*-)?[0-9]+' | head -1 || echo "")
+    elif printf '%s' "$CMD" | grep -qE 'cos +task-done +TASK-([A-Z][A-Z0-9]*-)?[0-9]+' 2>/dev/null; then
+      CLEAR_FOR=$(printf '%s' "$CMD" | grep -oE 'TASK-([A-Z][A-Z0-9]*-)?[0-9]+' | head -1 || echo "")
+    elif printf '%s' "$CMD" | grep -qE "cos +task-move +TASK-([A-Z][A-Z0-9]*-)?[0-9]+.*--to +(${_CLEAR_STATES})" 2>/dev/null; then
+      CLEAR_FOR=$(printf '%s' "$CMD" | grep -oE 'TASK-([A-Z][A-Z0-9]*-)?[0-9]+' | head -1 || echo "")
+    fi
+    ;;
+  *) exit 0 ;;
+esac
+
+if [[ -n "$CLEAR_FOR" ]]; then
+  # Only clear when THIS panel's marker actually points at the finished task —
+  # never wipe a sibling task the panel may have switched to.
+  marker="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os/claude}}/.task-current"
+  if [[ -f "$marker" ]] && grep -q "$CLEAR_FOR" "$marker" 2>/dev/null; then
+    # Remove the marker at the exact path we read — write-state.sh rejects an
+    # empty value (`${2:?}`), so clearing means deleting the per-panel file.
+    # An absent .task-current reads as task=none; a later task-start recreates it.
+    rm -f "$marker" 2>/dev/null || true
+    cos_log_hook sync-task-current "cleared task=${CLEAR_FOR}" 2>/dev/null || true
+  fi
+  exit 0
+fi
+
+[[ -z "$TASK_ID" ]] && exit 0
+bash "$(dirname "$0")/write-state.sh" .task-current "$TASK_ID" 2>/dev/null || true
+cos_log_hook sync-task-current "set task=${TASK_ID}" 2>/dev/null || true
+exit 0

core/hooks/test-first-reminder.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# PostToolUse Write|Edit hook: nudge about test file after code changes.
+#
+# Goal: prevent shipping untested code. This is a soft reminder only —
+# many edits legitimately don't need tests (renaming, docstring, trivial
+# typo fix). Blocking would be noisy. A one-line nudge is cheap and
+# catches the "I forgot to update the test" case that's the common one.
+#
+# Heuristic: after Edit/Write on a code file that is NOT itself a test,
+# look for a sibling test file. Two search patterns:
+#   Python:      test_<basename>.py  or  <basename>_test.py
+#   JS/TS:       <basename>.test.ts(x)  or  <basename>.spec.ts(x)
+# If no test file exists, suggest a path. If one exists, print it.
+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 "")
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# Only nudge on code files that could have tests.
+case "$FILE_PATH" in
+  *.py|*.ts|*.tsx|*.js|*.jsx) ;;
+  *) exit 0 ;;
+esac
+
+# Skip test files, migrations, caches, internal state.
+BASENAME_FILE=$(basename "$FILE_PATH")
+case "$BASENAME_FILE" in
+  test_*|*_test.*|*.test.*|*.spec.*|conftest.py) exit 0 ;;
+esac
+case "$FILE_PATH" in
+  */tests/*|*/__pycache__/*|*/migrations/*|*/node_modules/*) exit 0 ;;
+  */.venv/*|*/.coding-os/*|*/.claude/*|*/.codex/*) exit 0 ;;
+esac
+
+BASE="${BASENAME_FILE%.*}"
+EXT="${BASENAME_FILE##*.}"
+DIR=$(dirname "$FILE_PATH")
+
+# Walk up from DIR to find the nearest project root (has pyproject.toml,
+# package.json, or .coding-os.yaml). Fall back to cwd.
+ROOT="$DIR"
+while [[ "$ROOT" != "/" ]]; do
+  if [[ -f "$ROOT/pyproject.toml" ]] || [[ -f "$ROOT/package.json" ]] || [[ -f "$ROOT/.coding-os.yaml" ]]; then
+    break
+  fi
+  ROOT=$(dirname "$ROOT")
+done
+[[ "$ROOT" == "/" ]] && ROOT="$PWD"
+
+# Debounce: remind at most once per file per session. The find
+# scan below sweeps up to ~6k files under ROOT; repeating it on every edit of
+# the same file is the dominant per-edit cost of this hook. The marker dir is
+# cleared each SessionStart (session-context.sh).
+_TFR_DIR="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os/claude}}/.test-first-reminded"
+mkdir -p "$_TFR_DIR" 2>/dev/null || true
+_TFR_KEY=$(printf '%s' "$FILE_PATH" | tr -c 'A-Za-z0-9' '_' | cut -c1-80)
+[[ -f "$_TFR_DIR/$_TFR_KEY" ]] && exit 0
+touch "$_TFR_DIR/$_TFR_KEY" 2>/dev/null || true
+
+# Candidate test filenames by extension.
+CANDIDATES=()
+case "$EXT" in
+  py)
+    CANDIDATES+=("test_${BASE}.py" "${BASE}_test.py") ;;
+  ts|tsx|js|jsx)
+    CANDIDATES+=("${BASE}.test.${EXT}" "${BASE}.spec.${EXT}") ;;
+esac
+
+# Build a session-cached index of every test file ONCE, then look candidates
+# up by grep. Replaces a full `find` per edited file — at 100K files that walk
+# was the dominant per-edit cost. The cache lives in the panel dir and is
+# cleared each SessionStart with the other markers. TASK-229.
+_TEST_CACHE="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os/claude}}/.test-locations.cache"
+if [[ ! -s "$_TEST_CACHE" ]]; then
+  find "$ROOT" -maxdepth 6 -type f \
+    \( -name 'test_*' -o -name '*_test.*' -o -name '*.test.*' -o -name '*.spec.*' \) \
+    -not -path '*/node_modules/*' -not -path '*/.venv/*' -not -path '*/.git/*' \
+    > "$_TEST_CACHE" 2>/dev/null || true
+fi
+FOUND=""
+for name in "${CANDIDATES[@]}"; do
+  # grep exits 1 on no-match; without `|| true` pipefail aborts the hook before
+  # the no-companion-test branch (the common case) can suggest a path.
+  match=$(grep -F "/$name" "$_TEST_CACHE" 2>/dev/null | head -1 || true)
+  if [[ -n "$match" ]]; then
+    FOUND="$match"
+    break
+  fi
+done
+
+echo ""
+if [[ -n "$FOUND" ]]; then
+  REL="${FOUND#$ROOT/}"
+  echo "  🧪 [test] Code edited. Related test file:"
+  echo "     → $REL"
+  echo "     Keep it in sync — run the suite before \`cos task-done\`."
+else
+  # Suggest a canonical location.
+  case "$EXT" in
+    py)
+      SUGGEST="$(dirname "$FILE_PATH")/test_${BASE}.py"
+      ;;
+    *)
+      SUGGEST="$(dirname "$FILE_PATH")/${BASE}.test.${EXT}"
+      ;;
+  esac
+  REL_SUGGEST="${SUGGEST#$ROOT/}"
+  echo "  🧪 [test] Code edited but no companion test file found."
+  echo "     Suggested: $REL_SUGGEST"
+  echo "     Reminder only — skip if this edit genuinely doesn't need a test."
+fi
+
+exit 0

core/hooks/test-governor.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# test-governor.sh (PreToolUse Bash) — multi-agent test-run governance (TASK-330).
+#
+# Gates pytest invocations three ways (in order):
+#   1. Full sweep (bare pytest / pytest tests/ / >=3 test roots) → BLOCK unless
+#      COS_FULL_SWEEP_OK=1 with COS_OVERRIDE_REASON >=15 chars (Rule 20, audited).
+#   2. Dedup — the suite is already green on THIS tree within TTL (commit-keyed
+#      ledger, TASK-328) → BLOCK with reuse message; COS_TEST_FORCE=1 re-runs.
+#   3. Concurrency — $COS_STATE_DIR/.test-run.lock held by a live run → BLOCK
+#      naming the holder. The lock is a per-repo JSON file (TTL-bounded); the
+#      PostToolUse leg record-verify-auto.sh deletes it when pytest exits, and
+#      the owner-agent pid in it lets a crashed run free early. No host-global
+#      pgrep (it phantom-holds across repos + false-clears on wrapper/xdist
+#      argv). flock(1) is absent on macOS and a PreToolUse hook exits before the
+#      tool runs, so it cannot hold an advisory lock anyway.
+# Sweep gate is fail-closed; everything else fails open (exit 0 on internal error).
+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
+
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# Fast-path: this governor gates pytest invocations AND make-target verify
+# suites (verify-hooks / docs-lint / ui-test …) for dedup. If the raw payload
+# mentions neither "pytest" nor "make " there is nothing to gate — bail before
+# any jq spawn (fires on EVERY Bash command).
+case "$INPUT" in
+  *pytest*|*"make "*) ;;
+  *) exit 0 ;;
+esac
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+[[ -n "$COMMAND" ]] || exit 0
+
+# Match `make ` only at a command-word boundary (start, or after a shell
+# separator) — a plain substring would also fire on cmake/gmake/remake, which
+# contain "make " and would then pay the match-command spawn for nothing.
+_MAKE_WORD_RE='(^|[[:space:]&|;(])make[[:space:]]'
+if [[ "$COMMAND" != *pytest* ]] && [[ ! "$COMMAND" =~ $_MAKE_WORD_RE ]]; then
+  exit 0
+fi
+case "$COMMAND" in
+  *--collect-only*|*" --co"*) exit 0 ;;
+esac
+
+PROJECT_ROOT="${COS_PROJECT_ROOT:-$(pwd)}"
+if command -v uv >/dev/null 2>&1; then
+  PYRUN=(uv run --quiet python)
+else
+  PYRUN=(python3)
+fi
+MATCH=$(cd "$PROJECT_ROOT" && "${PYRUN[@]}" -m core.board_os.verify_suites_cli match-command --command "$COMMAND" 2>/dev/null) || MATCH='{}'
+
+FULL_SWEEP=$(echo "$MATCH" | jq -r '.full_sweep // false' 2>/dev/null || echo false)
+SUITE=$(echo "$MATCH" | jq -r '.suite // empty' 2>/dev/null || echo "")
+FRESH=$(echo "$MATCH" | jq -r '.fresh // false' 2>/dev/null || echo false)
+IS_PYTEST=$(echo "$MATCH" | jq -r '.pytest_invocation // false' 2>/dev/null || echo false)
+
+# Not a pytest run AND not a recognised suite — the command merely MENTIONS the
+# trigger (echo/jq/heredoc payload), or MATCH was unavailable ({}). Bail fail-open.
+# A make-target verify suite (pytest_invocation=false but SUITE set) stays in for
+# dedup below (TASK-669).
+if [[ "$IS_PYTEST" != "true" && -z "$SUITE" ]]; then
+  exit 0
+fi
+
+# Inline overrides: an agent writes `COS_TEST_FORCE=1 pytest …` as ONE Bash
+# command — the assignment lives in the command STRING, never in this hook's
+# environment. Honor both forms.
+INLINE_FORCE=false
+[[ "$COMMAND" == *"COS_TEST_FORCE=1"* ]] && INLINE_FORCE=true
+INLINE_SWEEP_OK=false
+[[ "$COMMAND" == *"COS_FULL_SWEEP_OK=1"* ]] && INLINE_SWEEP_OK=true
+INLINE_REASON=$(echo "$COMMAND" | { grep -oE "COS_OVERRIDE_REASON=('[^']*'|\"[^\"]*\")" || true; } | head -1 | sed -E "s/^COS_OVERRIDE_REASON=//; s/^['\"]//; s/['\"]$//")
+
+# ── 1. Full-sweep gate (fail-closed, audited override) ──────────────
+if [[ "$FULL_SWEEP" == "true" ]]; then
+  REASON="${COS_OVERRIDE_REASON:-$INLINE_REASON}"
+  SWEEP_OK="${COS_FULL_SWEEP_OK:-}"
+  $INLINE_SWEEP_OK && SWEEP_OK=1
+  if [[ "$SWEEP_OK" == "1" && "${#REASON}" -ge 15 ]]; then
+    cos_log_hook test-governor override "full-sweep reason=$REASON" 2>/dev/null || true
+  else
+    cos_log_hook test-governor block "full-sweep" 2>/dev/null || true
+    {
+      echo "BLOCKED: full pytest sweep mid-task (Rule 20 — ~4,100 tests, minutes of CPU, melts concurrent sessions)."
+      echo "  Run the matrix suite for what you changed instead (AGENTS.md § Verification Matrix)."
+      echo "  Pre-merge / cross-cutting / user asked? Override (audited):"
+      echo "    COS_FULL_SWEEP_OK=1 COS_OVERRIDE_REASON='...>=15 chars' <your command>"
+      echo "  Tip: prefix with 'nice -n 19' to keep the laptop responsive."
+    } >&2
+    exit 2
+  fi
+fi
+
+# ── 2. Dedup — suite already green on this exact tree ────────────────
+if [[ -n "$SUITE" && "$FRESH" == "true" && "${COS_TEST_FORCE:-}" != "1" ]] && ! $INLINE_FORCE; then
+  BY=$(echo "$MATCH" | jq -r '.recorded_by // "unknown"' 2>/dev/null || echo unknown)
+  TAIL=$(echo "$MATCH" | jq -r '.session_tail // ""' 2>/dev/null || echo "")
+  AGE=$(echo "$MATCH" | jq -r '.age_min // 0' 2>/dev/null || echo 0)
+  cos_log_hook test-governor block "dedup suite=$SUITE by=$BY" 2>/dev/null || true
+  {
+    echo "BLOCKED: $SUITE is already green on this exact tree — passed ${AGE}min ago by ${BY}${TAIL:+ (ses=$TAIL)}."
+    echo "  Reuse that result; the ledger invalidates it automatically when the tree changes."
+    echo "  Re-run anyway: COS_TEST_FORCE=1 <your command>"
+  } >&2
+  exit 2
+fi
+
+# Make-target verify suites (verify-hooks / docs-lint / ui-test) get dedup above
+# but NOT the pytest run-lock — the lock governs heavy pytest concurrency and
+# re-architecting it is out of scope (TASK-669). A non-pytest suite that survived
+# dedup just runs.
+if [[ "$IS_PYTEST" != "true" ]]; then
+  exit 0
+fi
+
+# ── 3. Concurrency lock (TTL + liveness; never queue-wait) ───────────
+LOCK_FILE="${COS_STATE_DIR}/.test-run.lock"
+LOCK_TTL=1800
+NOW=$(date +%s)
+if [[ -f "$LOCK_FILE" ]]; then
+  STARTED=$(jq -r '.started_ts // 0' "$LOCK_FILE" 2>/dev/null || echo 0)
+  H_TAIL=$(jq -r '.session_tail // ""' "$LOCK_FILE" 2>/dev/null || echo "")
+  H_AGENT_PID=$(jq -r '.agent_pid // 0' "$LOCK_FILE" 2>/dev/null || echo 0)
+  OUR_TAIL="${COS_PANEL_ID:-}"
+  OUR_TAIL="${OUR_TAIL: -8}"
+  AGE=$(( NOW - STARTED ))
+  HELD=false
+  # Held = the lock is present and within TTL. The PostToolUse leg
+  # (record-verify-auto.sh) deletes this file the instant THIS repo's pytest
+  # exits, so a surviving unexpired lock means a sibling run is genuinely in
+  # flight. No host-global `pgrep -f pytest`: it phantom-holds across repos
+  # (repo A blocked by repo B's unrelated pytest) and false-clears on
+  # `uv run`/pytest-xdist worker argv (a sibling then double-runs).
+  if [[ "$AGE" -lt "$LOCK_TTL" ]]; then
+    HELD=true
+    # Owner agent gone while the lock is still present ⇒ the run crashed before
+    # its release fired — free it now instead of waiting out the TTL (the lock
+    # is per-repo on one machine, so its pid is always same-host).
+    if [[ "$H_AGENT_PID" =~ ^[0-9]+$ && "$H_AGENT_PID" -gt 0 ]] && ! kill -0 "$H_AGENT_PID" 2>/dev/null; then
+      HELD=false
+    fi
+  fi
+  # A lock carrying OUR session tail is a finished/failed run whose PostToolUse
+  # cleanup never fired — reclaim it rather than self-block (a panel runs Bash
+  # serially, so an OUR-tail lock is never a concurrent self-run).
+  if [[ -n "$OUR_TAIL" && "$H_TAIL" == "$OUR_TAIL" ]]; then
+    HELD=false
+  fi
+  if $HELD; then
+    H_AGENT=$(jq -r '.agent // "unknown"' "$LOCK_FILE" 2>/dev/null || echo unknown)
+    H_SUITE=$(jq -r '.suite // "a test run"' "$LOCK_FILE" 2>/dev/null || echo "a test run")
+    cos_log_hook test-governor block "lock-held by=$H_AGENT" 2>/dev/null || true
+    {
+      echo "BLOCKED: $H_AGENT${H_TAIL:+ (ses=$H_TAIL)} is running $H_SUITE on this machine (started ${AGE}s ago)."
+      echo "  Concurrent heavy suites swap this laptop. Retry after it finishes —"
+      echo "  the lock clears automatically (or expires after ${LOCK_TTL}s)."
+    } >&2
+    exit 2
+  fi
+fi
+
+# Acquire: record this run so sibling sessions queue behind it.
+SESSION_TAIL="${COS_PANEL_ID:-}"
+SESSION_TAIL="${SESSION_TAIL: -8}"
+printf '{"suite": "%s", "agent": "%s", "session_tail": "%s", "agent_pid": %s, "started_ts": %s}\n' \
+  "${SUITE:-adhoc-pytest}" "${COS_AGENT:-unknown}" "$SESSION_TAIL" "${PPID:-0}" "$NOW" \
+  > "$LOCK_FILE" 2>/dev/null || true
+
+cos_log_hook test-governor allow "suite=${SUITE:-adhoc}" 2>/dev/null || true
+exit 0