coding-os 0.3.2__py3-none-any.whl

core/hooks/nudge-reuse-first.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# PostToolUse Write|Edit — reuse-first placement nudge (non-blocking).
+#
+# When an edit under src/services/<svc>/ defines a symbol that is also defined
+# in a different same-language service, suggest promoting it to
+# src/shared/<lang>/ (project-anatomy.md). Advisory only: always exits 0.
+# Debounced per panel+file. Real logic lives in _nudge_reuse_first.py (Rule 8).
+# Fail-open by design: any missing dep / parser error → silent skip.
+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)"
+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 "")
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+PROJECT_ROOT="${COS_PROJECT_ROOT:-$PWD}"
+case "$FILE_PATH" in
+  "${PROJECT_ROOT}/"*) REL_PATH="${FILE_PATH#${PROJECT_ROOT}/}" ;;
+  *)                   REL_PATH="$FILE_PATH" ;;
+esac
+
+# Only cross-service edits can duplicate a symbol across services — fast-path
+# out of every other write so the hook adds no cost to the common case.
+case "$REL_PATH" in
+  src/services/*) ;;
+  *) exit 0 ;;
+esac
+
+# Debounce per panel+file: one nudge per file per window (avoids re-nudging on
+# rapid successive edits of the same file).
+_DEBOUNCE_TTL=120
+_STATE_BASE="${COS_PANEL_DIR:-${COS_STATE_DIR:-${PROJECT_ROOT}/.coding-os}}"
+_SAFE_PATH=$(printf '%s' "$REL_PATH" | tr '/ .' '_')
+_DEBOUNCE_FILE="${_STATE_BASE}/.reuse-nudge-${_SAFE_PATH}"
+_NOW=$(date +%s)
+if [[ -f "$_DEBOUNCE_FILE" ]]; then
+  _LAST=$(cat "$_DEBOUNCE_FILE" 2>/dev/null || echo 0)
+  if (( _NOW - _LAST < _DEBOUNCE_TTL )); then
+    exit 0
+  fi
+fi
+mkdir -p "$(dirname "$_DEBOUNCE_FILE")" 2>/dev/null || true
+echo "$_NOW" > "$_DEBOUNCE_FILE" 2>/dev/null || true
+
+PY_DELEGATE="$(dirname "$0")/_nudge_reuse_first.py"
+if [[ ! -f "$PY_DELEGATE" ]]; then
+  exit 0
+fi
+
+cos_log_hook nudge-reuse-first fire "file=${REL_PATH}"
+OUTPUT="$("${COS_PYTHON:-python3}" "$PY_DELEGATE" "$REL_PATH" "$PROJECT_ROOT" 2>/dev/null || true)"
+
+if [[ -n "$OUTPUT" ]]; then
+  echo "$OUTPUT" >&2
+  cos_log_hook nudge-reuse-first nudge "file=${REL_PATH}"
+fi
+
+exit 0

core/hooks/nudge-task-discovery.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# nudge-task-discovery.sh — steer task lookup to the board, not raw files.
+#
+# Three events, all fail-open (exit 0), debounced once per session per leg:
+#   UserPromptSubmit: task-reference intent (TASK-NNN, check/show/look-at
+#     task; bilingual EN + Persian) -> additionalContext recommending
+#     `cos task-show TASK-NNN` / cos_task_search / cos_task_show (MCP).
+#   PreToolUse Bash:  command reads docs/tasks/ directly (ls/grep/cat/find/
+#     head/tail/awk/sed/less/more/bat/rg/wc/nl/tac) -> stderr warning.
+#   PreToolUse Read:  Read tool targets a docs/tasks/** path -> stderr warning
+#     recommending cos task-show over a raw file Read.
+#
+# Closes the screenshot-2 gap: agent ran `ls docs/tasks | grep 058` + raw
+# Read instead of cos task-show. Mirrors nudge-graph-os.sh mechanism.
+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: every leg keys on either a "docs/tasks" path (Bash/Read) or the
+# word "task" in a prompt (UserPromptSubmit task-reference intent). If the raw
+# payload contains neither there is nothing to nudge — bail before any jq spawn
+# (fires on EVERY Bash command and every prompt). Superset of all real triggers.
+case "$INPUT" in
+  *docs/tasks*|*task*) ;;
+  *) exit 0 ;;
+esac
+
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+MARKER_DIR="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.task-nudge"  # panel-first: cleared at panel scope each SessionStart
+mkdir -p "$MARKER_DIR" 2>/dev/null || true
+
+# ---- PreToolUse Read leg ----
+# A raw Read of docs/tasks/** bypasses the board exactly like ls/grep does.
+# cos task-show / cos_task_search are MCP/CLI calls, never the Read tool, so
+# this leg only ever sees genuine file Reads.
+if [[ "$TOOL" == "Read" ]]; then
+  FP=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+  [[ -z "$FP" ]] && exit 0
+  if [[ "$FP" == *"docs/tasks/"* ]]; then
+    RM="${MARKER_DIR}/read"
+    [[ -f "$RM" ]] && exit 0
+    touch "$RM" 2>/dev/null || true
+    cos_log_hook nudge-task-discovery fire "leg=read" 2>/dev/null || true
+    echo "warning: [task nudge] Read of docs/tasks/ directly — prefer 'cos task-show TASK-NNN' (or cos_task_search) for a board-aware read instead of a raw file Read." >&2
+  fi
+  exit 0
+fi
+
+# ---- PreToolUse Bash leg ----
+if [[ "$TOOL" == "Bash" ]]; then
+  CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+  [[ -z "$CMD" ]] && exit 0
+  # Match a file-reading command targeting docs/tasks. cos task-show /
+  # cos_task_search contain no "docs/tasks" literal, so they never match.
+  # Broadened reader set — awk/sed/less/more/bat/rg/wc/nl/tac.
+  if printf '%s' "$CMD" | grep -qE '(ls|grep|cat|find|head|tail|awk|sed|less|more|bat|rg|wc|nl|tac)[^|;&]*docs/tasks' 2>/dev/null; then
+    BM="${MARKER_DIR}/bash"
+    [[ -f "$BM" ]] && exit 0
+    touch "$BM" 2>/dev/null || true
+    cos_log_hook nudge-task-discovery fire "leg=bash" 2>/dev/null || true
+    echo "warning: [task nudge] reading docs/tasks/ directly — prefer 'cos task-show TASK-NNN' (or cos_task_search) for a board-aware read instead of file hunting." >&2
+  fi
+  exit 0
+fi
+
+# ---- UserPromptSubmit leg ----
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || echo "")
+[[ ${#PROMPT} -lt 15 ]] && exit 0
+PL=$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]')
+if printf '%s' "$PL" | grep -qE '\btask-[0-9]+\b|check task|show task|look at task|open task|status of task' 2>/dev/null; then
+  PM="${MARKER_DIR}/prompt"
+  [[ -f "$PM" ]] && exit 0
+  touch "$PM" 2>/dev/null || true
+  cos_log_hook nudge-task-discovery fire "leg=prompt" 2>/dev/null || true
+  CONTEXT="[task nudge] Task reference detected — run \`cos task-show TASK-NNN\` (or cos_task_search if no ID; cos_task_show via MCP in-session) instead of ls/grep/cat on docs/tasks/. Tasks are the third retrieval layer (Rule 18 reconciliation)."
+  printf '%s' "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"
+fi
+exit 0

core/hooks/nudge-thinking-os.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — heuristic Complexity Gate nudge + Rule 18 task reconciliation.
+#
+# Reads user prompt from stdin payload. Counts signal words to classify
+# as CLEAR / COMPLICATED / COMPLEX / CHAOTIC. For COMPLICATED+ emits an
+# additional-context block mandating Rule 18 task board check (cos_task_board),
+# Complexity Gate recording, and thinking_os skill load.
+#
+# Debounce: normally fires once per session. EXCEPTION: if the gate is stale
+# (expired or wrong session), debounce is bypassed and a re-record warning is
+# emitted regardless — preventing a surprise BLOCK at Write/Edit time later.
+#
+# Always exits 0 — never blocks input.
+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)"
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || echo "")
+
+# Skip empty / very short prompts (almost certainly CLEAR).
+LEN=${#PROMPT}
+if [[ "$LEN" -lt 80 ]]; then
+  exit 0
+fi
+
+MARKER="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.zoom-prompt-suggested"  # panel-first: session-context clears it at panel scope
+GATE_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.thinking_os-gate"
+
+# Check gate validity (not just file existence).
+# A stale or session-mismatched gate WILL cause a BLOCK on next Write/Edit —
+# warn now, before the agent does work it will have to redo.
+source "$(dirname "$0")/check-state.sh"
+check_state "$GATE_FILE" 7200
+GATE_STALE=false
+if [[ "$STATE_VALID" != "true" ]] && [[ -f "$GATE_FILE" ]]; then
+  # File exists but is invalid (expired or wrong session) — this is the silent trap.
+  GATE_STALE=true
+  # Clear the debounce marker so the stale-gate warning always gets through.
+  rm -f "$MARKER" 2>/dev/null || true
+  cos_log_hook nudge-thinking-os stale-gate "reason=${STATE_REASON}"
+fi
+
+# Normal debounce: one nudge per session (unless gate is stale, handled above).
+if [[ -f "$MARKER" ]] && [[ "$GATE_STALE" != "true" ]]; then
+  exit 0
+fi
+
+# Gate valid and already recorded — no nudge needed.
+if [[ "$STATE_VALID" == "true" ]]; then
+  # Still debounce to avoid re-nudging on every prompt.
+  if [[ -f "$MARKER" ]]; then
+    exit 0
+  fi
+fi
+
+# Lowercase prompt for matching.
+PL=$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+# Signal words (English). The agent comprehends other languages itself.
+COMPLICATED_RE='design|architect|plan|debug|investigate|refactor|multiple|all of|comprehensive|deep|enterprise|trace|map |dependency|persona|scenario'
+COMPLEX_RE='best way|optimal|optimize|strategy|unknown|research|what if|trade.?off'
+CHAOTIC_RE='down|broken|crash|outage|urgent|emergency|asap|hotfix|p0'
+
+count_re() {
+  # grep -o returns 1 on no match — swallow it so pipefail does not abort
+  # the whole hook just because zero signals matched.
+  local n
+  n=$(printf '%s' "$1" | { grep -oE "$2" 2>/dev/null || true; } | wc -l | tr -d ' ')
+  printf '%s' "${n:-0}"
+}
+
+CHAOS=$(count_re "$PL" "$CHAOTIC_RE")
+COMPLEX=$(count_re "$PL" "$COMPLEX_RE")
+COMPLICATED=$(count_re "$PL" "$COMPLICATED_RE")
+
+CLASSIFICATION=""
+DIM_HINT=""
+if [[ "$CHAOS" -ge 1 ]]; then
+  CLASSIFICATION="CHAOTIC"
+  DIM_HINT="1+"
+elif [[ "$COMPLEX" -ge 1 ]]; then
+  CLASSIFICATION="COMPLEX"
+  DIM_HINT="$((COMPLEX + COMPLICATED))"
+elif [[ "$COMPLICATED" -ge 2 ]] || [[ "$LEN" -gt 600 ]]; then
+  CLASSIFICATION="COMPLICATED"
+  DIM_HINT="$COMPLICATED"
+fi
+
+if [[ -z "$CLASSIFICATION" ]]; then
+  exit 0
+fi
+
+cos_log_hook nudge-thinking-os fire "class=${CLASSIFICATION} stale=${GATE_STALE} len=${LEN} cplx=${COMPLICATED} cplex=${COMPLEX} chaos=${CHAOS}"
+
+# Set marker so we nudge at most once per session (stale-gate path already cleared it above).
+mkdir -p "$(dirname "$MARKER")" 2>/dev/null || true
+printf '%s' "$CLASSIFICATION" > "$MARKER" 2>/dev/null || true
+
+# Emit structured hookSpecificOutput JSON.
+if [[ "$GATE_STALE" == "true" ]]; then
+  CONTEXT="[thinking_os gate STALE — ${STATE_REASON}] Re-record NOW to avoid BLOCK on next Write/Edit: bash \".${COS_AGENT}/hooks/write-state.sh\" .thinking_os-gate \"${CLASSIFICATION} ${DIM_HINT}\". Then: (1) cos_task_board [Rule 18] (2) Skill(thinking_os) if COMPLICATED+."
+else
+  CONTEXT="[thinking_os ${CLASSIFICATION} ~${DIM_HINT}dim] MANDATORY: (1) cos_task_board [Rule 18] (2) write-state.sh gate (3) Skill(thinking_os) (4) /compose — composes the role chain via cos_compose_chain. Heuristic, re-classify after full read."
+fi
+printf '%s' "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"
+
+exit 0

core/hooks/pr-reap.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# pr-reap.sh — SessionStart orphan-reaper trigger (pr-mode only).
+#
+# Cleanup must be owner-independent: a crashed agent never runs its own
+# `cos pr cleanup` (the exact Rule-21 failure mode). On every SessionStart a
+# live session sweeps the repo's worktrees and GCs the ones whose owning session
+# is presence-offline (worktree + local/remote branch + PR), and drains the
+# pending-cleanup ledger. Fire-and-forget so SessionStart never blocks on git/gh
+# network calls. Inert in trunk mode (the default) → one env check and exit.
+# SPEC: docs/playbooks/pr-workflow.md § 7.
+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
+
+# Inert unless pr-mode.
+[[ "${COS_GIT_WORKFLOW:-trunk}" == "pr" ]] || exit 0
+command -v cos >/dev/null 2>&1 || exit 0
+
+cos_log_hook pr-reap fire "sweeping offline worktrees"
+# Detach so a slow git/gh sweep can never delay the session.
+( cos pr reap >/dev/null 2>&1 & ) || true
+exit 0

core/hooks/reclaim-sweep.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# reclaim-sweep.sh — SessionStart hook.
+#
+# Event-independent zombie recovery. Every new session
+# reclaims the zombie in_progress/testing tasks left by DEAD predecessor
+# sessions before doing any work. This is the consumer-robust recovery
+# leg: it does NOT rely on the dying session running anything (the Claude
+# runtime fires zero SessionEnd hooks, so a kill/crash/context-exhaustion
+# runs no closure path) nor on the nightly cron (macOS-launchd, opt-in).
+# The NEXT session that connects cleans up its predecessor.
+#
+# Reclaim itself is conservative — it only touches a task whose owner
+# session is inactive AND which has been idle past its per-status window
+# (board_os.cos_task_reclaim), so a concurrently-active peer's card is
+# never yanked. Fire-and-forget, detached, never blocks session start.
+# Debounced ~30 min via $COS_PANEL_DIR/.reclaim-sweep so rapid resumes in
+# one work burst don't re-run it.
+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 reclaim-sweep enter || true
+
+# Only when a board DB and the cos CLI both exist (the CLI runs on-disk
+# code, so it always reflects the current reclaim logic).
+[ -f "${COS_DB_PATH:-}" ] || exit 0
+command -v cos >/dev/null 2>&1 || exit 0
+
+# Upgrade panel id from the SessionStart payload so the debounce marker
+# lands in THIS panel.
+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
+
+# Time-debounce: skip if a sweep ran in the last 30 min for this panel.
+MARKER="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.reclaim-sweep"
+if [ -f "$MARKER" ]; then
+  if [ "$(uname)" = "Darwin" ]; then
+    LAST=$(stat -f %m "$MARKER" 2>/dev/null || echo 0)
+  else
+    LAST=$(stat -c %Y "$MARKER" 2>/dev/null || echo 0)
+  fi
+  NOW=$(date +%s)
+  if [ $((NOW - LAST)) -lt 1800 ]; then
+    cos_log_hook reclaim-sweep skip "reason=debounced" || true
+    exit 0
+  fi
+fi
+: > "$MARKER" 2>/dev/null || true
+
+# Detached + bounded — must never delay session startup. The reclaim is a
+# quick read + a few row updates; background it so a slow CLI cold-start
+# never blocks the user's first prompt.
+( cos task-reclaim >/dev/null 2>&1 || true ) &
+
+cos_log_hook reclaim-sweep ok || true
+exit 0

core/hooks/record-verify-auto.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# record-verify-auto.sh (PostToolUse Bash) — auto-record suite results (TASK-329).
+#
+# When a Bash command that executes a verify suite (data-driven match against
+# verify-suites.yaml via `verify_suites_cli match-command`) completes, record
+# PASS/FAIL + commit keys to $COS_STATE_DIR/.last-verify.json through
+# record-verify.sh, and clear the test-run lockfile the test-governor wrote.
+# Observation phase: fail-open, always exit 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
+
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# Fast-path: this recorder only acts on verify-suite commands. If the raw
+# payload mentions none of the suite verbs there is nothing to record — bail
+# before any jq spawn (fires on EVERY Bash tool call). The precise COMMAND-
+# level case below still gates the actual work.
+case "$INPUT" in
+  *pytest*|*"make verify-hooks"*|*"make docs-lint"*|*"make ui-test"*) ;;
+  *) exit 0 ;;
+esac
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+[[ -n "$COMMAND" ]] || exit 0
+
+# Cheap pre-filter — only suite-shaped commands reach the python matcher.
+case "$COMMAND" in
+  *pytest*|*"make verify-hooks"*|*"make docs-lint"*|*"make ui-test"*) ;;
+  *) exit 0 ;;
+esac
+case "$COMMAND" in
+  *--collect-only*|*" --co"*) exit 0 ;;
+esac
+
+EXIT_CODE=$(echo "$INPUT" | jq -r '.tool_response.exit_code // .tool_response.exitCode // 0' 2>/dev/null || echo 0)
+# TASK-335: on PostToolUseFailure the payload may carry no exit_code at all —
+# the event itself IS the failure signal; never let the `// 0` default record
+# a phantom PASS.
+EVENT_NAME=$(echo "$INPUT" | jq -r '.hook_event_name // empty' 2>/dev/null || echo "")
+if [[ "$EVENT_NAME" == "PostToolUseFailure" ]]; then
+  EXIT_CODE=1
+fi
+
+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='{}'
+SUITE=$(echo "$MATCH" | jq -r '.suite // empty' 2>/dev/null || echo "")
+IS_PYTEST=$(echo "$MATCH" | jq -r '.pytest_invocation // false' 2>/dev/null || echo false)
+
+# A completed pytest run frees the host — clear the governor's lockfile.
+# Commands that merely MENTION pytest (echo/heredoc payloads) must NOT
+# clear a sibling session's live lock.
+if [[ "$IS_PYTEST" == "true" ]]; then
+  rm -f "${COS_STATE_DIR}/.test-run.lock" 2>/dev/null || true
+fi
+
+[[ -n "$SUITE" ]] || exit 0
+
+STATUS="PASS"
+[[ "$EXIT_CODE" == "0" ]] || STATUS="FAIL"
+
+bash "$(dirname "$0")/record-verify.sh" "$SUITE" "$STATUS" >/dev/null 2>&1 || true
+cos_log_hook record-verify-auto recorded "suite=$SUITE status=$STATUS" 2>/dev/null || true
+
+# F-TST-3: a matrix-suite FAIL must be QUERYABLE (it reached only the hook jsonl
+# before). cos_say at ERROR routes through cos_say_json.py into the log_events
+# sink (DB floor WARN), so `cos_log_query` / an auto-bug-filer can surface it.
+if [[ "$STATUS" == "FAIL" ]] && command -v cos_say >/dev/null 2>&1; then
+  cos_say ERROR "verify.${SUITE}" "matrix suite failed (exit ${EXIT_CODE})" 2>/dev/null || true
+fi
+exit 0

core/hooks/record-verify.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Record a per-suite verification result to $COS_STATE_DIR/.last-verify.json
+# Usage: record-verify.sh <suite-name> <PASS|FAIL>
+# Example: record-verify.sh test-board_os PASS
+#
+# NOT a duplicate of record-verify-auto.sh: this is the shared 2-arg CLI recorder
+# (the actual ledger writer); record-verify-auto.sh is the PostToolUse Bash hook
+# that detects a suite run and DELEGATES to this script (record-verify-auto.sh:68).
+# Keep both — the hook is the trigger, this is the implementation (TASK-460).
+#
+# v2 (TASK-328): entries carry {git_head, dirty_digest, agent, session_tail}
+# so freshness is commit-keyed, not time-only. Tree state comes from
+# `verify_suites_cli tree-state` (single source — no bash/python drift); when
+# it is unavailable the entry is written without the keys and is treated as
+# stale by every v2 reader (fail-open, never blocks the recording itself).
+# JSON write is serialized via Python fcntl.flock — flock(1) does not exist
+# on stock macOS.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+SUITE="${1:?Usage: record-verify.sh <suite-name> <PASS|FAIL>}"
+STATUS="${2:?Usage: record-verify.sh <suite-name> <PASS|FAIL>}"
+VERIFY_FILE="${COS_STATE_DIR}/.last-verify.json"
+TIMESTAMP=$(date +%s)
+
+# Also write the legacy flat file for backward compatibility
+echo "$STATUS" > "${COS_STATE_DIR}/.last-verify"
+
+PROJECT_ROOT="${COS_PROJECT_ROOT:-$(pwd)}"
+if command -v uv >/dev/null 2>&1; then
+  PYRUN=(uv run --quiet python)
+else
+  PYRUN=(python3)
+fi
+TREE_JSON=$(cd "$PROJECT_ROOT" && "${PYRUN[@]}" -m core.board_os.verify_suites_cli tree-state 2>/dev/null) || TREE_JSON='{}'
+[[ -n "$TREE_JSON" ]] || TREE_JSON='{}'
+
+AGENT="${COS_AGENT:-}"
+SESSION_TAIL="${COS_PANEL_ID:-}"
+SESSION_TAIL="${SESSION_TAIL: -8}"
+
+python3 -c "
+import fcntl, json, os, sys
+
+suite, status, ts, path, tree_json, agent, session_tail = sys.argv[1:8]
+entry = {'status': status, 'ts': int(ts)}
+try:
+    tree = json.loads(tree_json)
+except json.JSONDecodeError:
+    tree = {}
+if tree.get('git_head'):
+    entry['git_head'] = tree['git_head']
+    entry['dirty_digest'] = tree.get('dirty_digest', '')
+if agent:
+    entry['agent'] = agent
+if session_tail:
+    entry['session_tail'] = session_tail
+
+with open(path + '.lock', 'w') as lk:
+    fcntl.flock(lk, fcntl.LOCK_EX)
+    data = {}
+    if os.path.exists(path):
+        try:
+            with open(path) as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            data = {}
+    data[suite] = entry
+    tmp = path + '.tmp'
+    with open(tmp, 'w') as f:
+        json.dump(data, f, indent=2)
+    os.replace(tmp, path)
+" "$SUITE" "$STATUS" "$TIMESTAMP" "$VERIFY_FILE" "$TREE_JSON" "$AGENT" "$SESSION_TAIL"

core/hooks/regen-reminder.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# PostToolUse Write|Edit hook: remind to regenerate derived artifacts when
+# source-of-truth data files change. Never blocks — the agent chooses when.
+#
+# These file classes drive generated artifacts that CI/tests expect to
+# match exactly. A stale artifact causes silent test failures in
+# test_manifest_fresh, test_golden_parity, and test_rules_fresh.
+#
+#   src/templates/<stack>/stack.yaml     → make regen-rules + make manifest-regen
+#   src/adapters/<agent>/adapter.yaml    → make manifest-regen
+#   src/templates/_base/scaffold/**      → make manifest-regen + capture_golden
+#   src/templates/<stack>/scaffold/**    → make manifest-regen + capture_golden
+#
+# Generated outputs are also flagged so the agent doesn't hand-edit them:
+#
+#   src/core/rules/dimension-registry.md  (generated — edit stack.yaml::dimensions)
+#   src/core/rules/skill-enforcement.md   (generated — edit stack.yaml::skill_enforcement)
+#   src/core/scaffold_manifest.json       (generated — run make manifest-regen)
+#   tests/golden/**                   (generated — run src/scripts/capture_golden.py)
+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
+
+COMMANDS=()
+HEADLINE=""
+
+# ── Warn on edits to generated files first ─────────────────────────
+BASENAME=$(basename "$FILE_PATH")
+case "$FILE_PATH" in
+  */core/rules/dimension-registry.md|*/core/rules/skill-enforcement.md)
+    echo ""
+    echo "  ⚠️  [regen] You edited a GENERATED rule file." >&2
+    echo "     Hand-edits will be overwritten by \`make regen-rules\`." >&2
+    echo "     Instead, edit the source field in src/templates/<stack>/stack.yaml:" >&2
+    if [[ "$BASENAME" == "dimension-registry.md" ]]; then
+      echo "       dimensions: [{name, read_files}, ...]" >&2
+    else
+      echo "       skill_enforcement: [{globs, primary, secondary}, ...]" >&2
+    fi
+    echo "     Then: make regen-rules" >&2
+    exit 0
+    ;;
+  */core/scaffold_manifest.json)
+    echo ""
+    echo "  ⚠️  [regen] You edited a GENERATED manifest." >&2
+    echo "     Run \`make manifest-regen\` to reflect templates/ state." >&2
+    exit 0
+    ;;
+  */tests/golden/*)
+    echo ""
+    echo "  ⚠️  [regen] You edited a GENERATED golden fixture." >&2
+    echo "     Regenerate via: uv run python src/scripts/capture_golden.py --section <id>" >&2
+    exit 0
+    ;;
+esac
+
+# ── Detect source-of-truth changes + emit matching regen commands ─
+case "$FILE_PATH" in
+  */templates/*/stack.yaml)
+    HEADLINE="stack.yaml changed — regenerate derived artifacts:"
+    COMMANDS+=("make regen-rules")
+    COMMANDS+=("make manifest-regen")
+    ;;
+  */adapters/*/adapter.yaml)
+    HEADLINE="adapter.yaml changed — regenerate manifest:"
+    COMMANDS+=("make manifest-regen")
+    ;;
+  */templates/_base/scaffold/*|*/templates/*/scaffold/*)
+    HEADLINE="scaffold file changed — regenerate manifest + golden fixtures:"
+    COMMANDS+=("make manifest-regen")
+    # Suggest regenerating all relevant golden sections. The user can narrow.
+    COMMANDS+=("uv run python src/scripts/capture_golden.py --section <section_id>")
+    COMMANDS+=("(or regenerate all matching sections)")
+    ;;
+  */core/hooks/*.sh)
+    # New hook file (not edit-in-place): manifest snapshot changes.
+    if [[ "$TOOL" == "Write" ]]; then
+      HEADLINE="new hook file — golden fixtures include hook list:"
+      COMMANDS+=("make manifest-regen")
+      COMMANDS+=("uv run python src/scripts/capture_golden.py --section <affected_sections>")
+    fi
+    ;;
+esac
+
+if [[ ${#COMMANDS[@]} -eq 0 ]]; then
+  exit 0
+fi
+
+echo ""
+echo "  🔄 [regen] $HEADLINE"
+for cmd in "${COMMANDS[@]}"; do
+  echo "     $ $cmd"
+done
+echo "     (Failing CI after this file? 90% of the time it's a missing regen.)"
+
+exit 0