coding-os 0.3.2__py3-none-any.whl

core/hooks/drain-embedding-outbox.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# drain-embedding-outbox.sh — Stop hook.
+#
+# Drains the embedding_outbox (hot-path-skipped embeddings, Wave 4) off the
+# interactive path so observations captured during the session get their
+# semantic vectors without ever blocking an Edit. Fail-open: never blocks the
+# Stop. The helper fast-paths out (zero model load) when the outbox is empty.
+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 drain-embedding-outbox enter || true
+
+[ -f "${COS_DB_PATH:-}" ] || exit 0
+
+# The drain imports the rag extra (sentence_transformers); bare python3 usually
+# lacks it, which silently no-ops the drain. Resolve the cos venv interpreter.
+RAG_PY="$(cos_resolve_python 2>/dev/null || echo python3)"
+[ -n "$RAG_PY" ] || RAG_PY=python3
+"$RAG_PY" "$(dirname "$0")/_helpers/drain_embedding_outbox.py" 2>/dev/null || true
+
+cos_log_hook drain-embedding-outbox ok || true
+exit 0

core/hooks/enforce-anti-ambiguity.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# PreToolUse Write|Edit hook: Anti-Ambiguity gate.
+#
+# Blocks code writes when the cognitive phase is EXECUTE and the
+# ambiguity cache marks failures from cos_ambiguity_check.
+#
+# Flow:
+#   1. cos_ambiguity_check records the current check's violations into the
+#      ambiguity_violations table (clearing the session's prior rows first, so a
+#      passing check leaves none).
+#   2. This hook queries that table for the current session and blocks (exit 2)
+#      when unresolved violations exist.
+#   3. CLEAR 1 tasks bypass the gate (trivial fix, no planning needed).
+#
+# Bypass: CLEAR 1 gate, no violations, or unresolvable tools/DB/session → allowed.
+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 "enforce-anti-ambiguity" "entry"
+
+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 enforce on code files
+case "$FILE_PATH" in
+  *.py|*.ts|*.tsx|*.js|*.jsx|*.go|*.rs|*.sh) ;;
+  *) exit 0 ;;
+esac
+
+GATE_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.thinking_os-gate"
+
+# CLEAR 1 → bypass (trivial fix, no planning needed)
+if [[ -f "$GATE_FILE" ]]; then
+  GATE_CONTENT=$(cat "$GATE_FILE" 2>/dev/null || echo "")
+  if [[ "$GATE_CONTENT" == CLEAR* ]]; then
+    cos_log_hook "enforce-anti-ambiguity" "allowed" "CLEAR gate bypass"
+    exit 0
+  fi
+fi
+
+# Read the CURRENT ambiguity state from the canonical DB table. Fail-open when
+# the tools / DB / session-id aren't resolvable (never block on infra absence).
+command -v sqlite3 >/dev/null 2>&1 || exit 0
+[[ -f "${COS_DB_PATH:-}" ]] || exit 0
+SESSION_ID=$(cos_current_session 2>/dev/null || true)
+[[ -z "$SESSION_ID" ]] && exit 0
+SID_ESC=${SESSION_ID//\'/\'\'}
+
+COUNT=$(sqlite3 "$COS_DB_PATH" \
+  "SELECT COUNT(*) FROM ambiguity_violations WHERE session_id='${SID_ESC}' AND datetime(ts) > datetime('now','-120 minutes');" \
+  2>/dev/null || echo 0)
+[[ "$COUNT" =~ ^[0-9]+$ ]] || COUNT=0
+
+if [[ "$COUNT" -gt 0 ]]; then
+  CRITERIA=$(sqlite3 "$COS_DB_PATH" \
+    "SELECT group_concat(criterion, ', ') FROM ambiguity_violations WHERE session_id='${SID_ESC}' AND datetime(ts) > datetime('now','-120 minutes');" \
+    2>/dev/null || echo "")
+  cos_log_hook "enforce-anti-ambiguity" "BLOCKED" "$CRITERIA"
+  echo "BLOCKED: Anti-Ambiguity gate failed ($COUNT unresolved criteria)." >&2
+  echo "  Failing criteria: $CRITERIA" >&2
+  echo "  Repair: resolve the ambiguity, then re-run cos_ambiguity_check — a pass clears the gate." >&2
+  exit 2
+fi
+
+cos_log_hook "enforce-anti-ambiguity" "allowed" "gate passed"
+exit 0

core/hooks/enforce-commit-message.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# enforce-commit-message.sh — block `git commit -m` with non-compliant message.
+#
+# PreToolUse:Bash matcher. Best-effort extracts -m "..." / -m '...' content via
+# _helpers/extract_commit_msg_arg.py, then validates with check_commit_message.py.
+# Heredoc / multi-line forms the regex can't parse defer to the git commit-msg
+# hook installed via src/scripts/install-git-hooks.sh (defense-in-depth).
+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 hook only validates `git commit` messages. If the raw payload
+# never mentions "git commit" there is nothing to check — bail before any jq
+# spawn (this hook fires on EVERY Bash command).
+case "$INPUT" in
+  *"git commit"*) ;;
+  *) exit 0 ;;
+esac
+
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+[[ "$TOOL" != "Bash" ]] && exit 0
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+echo "$COMMAND" | grep -qE 'git[[:space:]]+commit\b' || exit 0
+
+# Resolve _helpers/ through the hook's PHYSICAL location so it works through the
+# .claude/hooks/ symlinks consumer projects install — there .claude/hooks/_helpers
+# does not exist (install symlinks each .sh, never the subdir) and the consumer has
+# no src/core/ tree, so the old "$(dirname "$0")/_helpers" + src/core fallback both
+# missed and the index.lock wait AND the commit-message contract silently no-op'd.
+# Mirrors the resolution dance in branch-guard.sh.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="${_dir}/${_src}"
+done
+HELPERS_DIR="$(cd -P "$(dirname "$_src")" && pwd)/_helpers"
+unset _src _dir
+
+# Pre-emptively wait out a concurrent commit's index.lock so this commit does
+# not fail under multi-agent contention. Fail-open by contract.
+_GIL="${HELPERS_DIR}/git_index_lock.sh"
+# shellcheck source=/dev/null
+[[ -f "$_GIL" ]] && source "$_GIL" 2>/dev/null && cos_wait_for_git_index_lock || true
+
+cos_log_hook enforce-commit-message fire
+EXTRACT="${HELPERS_DIR}/extract_commit_msg_arg.py"
+CHECK="${HELPERS_DIR}/check_commit_message.py"
+if [[ ! -f "$EXTRACT" || ! -f "$CHECK" ]]; then
+  echo "warning: enforce-commit-message: helpers missing; skipping" >&2
+  exit 0
+fi
+
+MSG=$(printf '%s' "$COMMAND" | python3 "$EXTRACT")
+
+if [[ -z "$MSG" ]]; then
+  cos_log_hook enforce-commit-message skip "reason=cannot-parse-defer-to-git-hook"
+  exit 0
+fi
+
+if ! CHECK_OUT=$(printf '%s' "$MSG" | python3 "$CHECK" - 2>&1); then
+  echo "BLOCKED: git log is permanent and release-please parses the title into CHANGELOG.md — a malformed message corrupts the changelog forever." >&2
+  printf '%s\n' "$CHECK_OUT" >&2
+  cos_log_hook enforce-commit-message block "rule=commit-msg-contract"
+  exit 2
+fi
+
+cos_log_hook enforce-commit-message ok
+exit 0

core/hooks/enforce-doc-anchor.sh

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# PreToolUse Write|Edit hook: enforce the docs-first principle.
+#
+# Rule (from the project charter): "Docs are always source of truth. A
+# code change must either (a) trace to a doc, or (b) be approved by the
+# user explicitly." This hook checks that the active task has a
+# populated "Source of Truth" or "Read First" section BEFORE any code
+# Write/Edit lands.
+#
+# Flow:
+#   1. The active task's Source of Truth / Read First paths are
+#      recorded to ${COS_PANEL_DIR:-$COS_AGENT_DIR}/.doc-anchor at task start.
+#   2. This hook reads .doc-anchor and verifies it exists + is non-empty.
+#   3. If missing / placeholder → BLOCK with a clear repair path.
+#
+# Scope: runs only on CODE files (.py, .ts, .tsx, .js, .jsx, .go, .rs).
+# Docs, config, tests, and scaffold edits are exempt — they ARE the
+# source of truth, so requiring a doc anchor is circular.
+#
+# Escape hatches (all one-shot):
+#   - CLEAR 1 gate: agent has classified as trivial → allowed
+#   - $COS_AGENT_DIR/.doc-anchor-override: manual bypass (consumed on use)
+#   - Task name contains "exploratory" or "spike" → allowed
+#
+# Philosophy: fail-closed but with generous repair paths. The goal is to
+# make "I didn't read the spec" impossible to hide, not to slow down
+# every keystroke.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+# Fail-open if state dir is absent (fresh clone, mid-init, off-project cwd).
+cos_sanity_check enforce-doc-anchor state_dir 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 enforce on CODE. Docs/tests/config/state files are exempt — they
+# ARE the source of truth.
+case "$FILE_PATH" in
+  *.py|*.ts|*.tsx|*.js|*.jsx|*.go|*.rs|*.rb) ;;
+  *) exit 0 ;;
+esac
+
+BASENAME=$(basename "$FILE_PATH")
+case "$BASENAME" in
+  test_*|*_test.*|*.test.*|*.spec.*|conftest.py) exit 0 ;;
+esac
+case "$FILE_PATH" in
+  */tests/*|*/migrations/*|*/__pycache__/*|*/node_modules/*) exit 0 ;;
+  */.venv/*|*/.coding-os/*|*/.claude/*|*/.codex/*) exit 0 ;;
+  */scaffold/*) exit 0 ;;
+esac
+
+COS_STATE_DIR="${COS_STATE_DIR:-.coding-os}"
+
+file_age_seconds() {
+  local file_path="$1"
+  if [[ "$(uname)" == "Darwin" ]]; then
+    echo $(( $(date +%s) - $(stat -f %m "$file_path") ))
+  else
+    echo $(( $(date +%s) - $(stat -c %Y "$file_path") ))
+  fi
+}
+
+# --- Escape hatches --------------------------------------------------
+
+# CLEAR 1 trivial path — ad-hoc fixes don't need a doc anchor.
+source "$(dirname "$0")/check-state.sh" 2>/dev/null || true
+if type check_state >/dev/null 2>&1; then
+  check_state "${COS_PANEL_DIR:-$COS_AGENT_DIR}/.thinking_os-gate" 7200
+  if [[ "${STATE_VALID:-}" == "true" ]]; then
+    CLASS=$(echo "${STATE_VALUE:-}" | awk '{print $1}')
+    DIMS=$(echo "${STATE_VALUE:-}" | awk '{print $2}')
+    if [[ "$CLASS" == "CLEAR" ]] && [[ "$DIMS" == "1" ]]; then
+      exit 0
+    fi
+  fi
+fi
+
+# Exploratory / spike tasks — allow. The task-name marker signals intent.
+if type check_state >/dev/null 2>&1; then
+  check_state "${COS_PANEL_DIR:-$COS_AGENT_DIR}/.task-current" 28800
+  if [[ "${STATE_VALID:-}" == "true" ]]; then
+    TASK_NAME="${STATE_VALUE:-}"
+    case "$TASK_NAME" in
+      *exploratory*|*spike*|*experiment*|*scratch*|*governance*|*docs-update*)
+        exit 0 ;;
+    esac
+  fi
+fi
+
+# One-shot manual override (consumed on use). Unified registry preferred;
+# legacy $COS_AGENT_DIR/.doc-anchor-override still honoured.
+if cos_one_shot_override doc-anchor 2>/dev/null; then
+  exit 0
+fi
+
+# Fresh-project grace (TASK-372): a just-scaffolded project has no anchor and no
+# task history, so the agent's FIRST legitimate code edit would hit the BLOCK
+# below. `cos init` leaves a one-shot "$COS_STATE_DIR/.fresh-init" marker; allow
+# a single edit and consume the marker, so this can never become a standing
+# bypass — the next edit without an anchor blocks normally.
+if [[ -n "${COS_STATE_DIR:-}" && -f "$COS_STATE_DIR/.fresh-init" && ! -f "${COS_PANEL_DIR:-$COS_AGENT_DIR}/.doc-anchor" ]]; then
+  rm -f "$COS_STATE_DIR/.fresh-init" 2>/dev/null || true
+  exit 0
+fi
+
+# --- The actual check ------------------------------------------------
+
+# panel-first: write-state.sh routes .doc-anchor to the panel dir.
+ANCHOR_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.doc-anchor"
+ANCHOR_MAX_AGE=28800  # 8h — same ownership horizon as task-current.
+
+if [[ ! -f "$ANCHOR_FILE" ]]; then
+  echo "BLOCKED: docs are the contract — code without a traced spec drifts from intent. No doc anchor recorded for this session." >&2
+  echo "  Rule 0 (docs-first) + Rule 19 (docs are the contract):" >&2
+  echo "  docs are SSOT — code must trace to a spec / playbook / ADR." >&2
+  echo "  Full procedure: docs/governance/docs-first-protocol.md" >&2
+  echo "" >&2
+  echo "  File attempted: $FILE_PATH" >&2
+  echo "" >&2
+  echo "  Repair (in order — try the cheapest first):" >&2
+  echo "  1. LOCATE the spec — pick one:" >&2
+  echo "       cos_doc_search \"<topic of your change>\"" >&2
+  echo "       cos_doc_headers_by(domain=\"<DOMAIN>\", ssot=\"true\")" >&2
+  echo "       cos_graph_context \"doc:file:docs/...\"" >&2
+  echo "  2. READ it (cos_doc_header first → full read only if relevant)." >&2
+  echo "  3. ANCHOR — record the doc path(s) you read for this session:" >&2
+  echo "       bash \".${COS_AGENT}/hooks/write-state.sh\" .doc-anchor \"<doc-path> § <section>\"" >&2
+  echo "  4. If NO matching doc exists → WRITE THE DOC FIRST" >&2
+  echo "     (src/templates/doc-cheat-sheet.md picks the layer), commit it as a" >&2
+  echo "     separate change, then return for the code." >&2
+  echo "" >&2
+  echo "  Bypass paths (use sparingly — logged):" >&2
+  echo "  • trivial fix (typo, docstring):" >&2
+  echo "      bash \".${COS_AGENT}/hooks/write-state.sh\" .thinking_os-gate \"CLEAR 1 <one-line why this is trivial>\"" >&2
+  echo "  • genuinely exploratory / throwaway code:" >&2
+  echo "      bash \".${COS_AGENT}/hooks/write-state.sh\" .task-current \"exploratory-<slug>\"" >&2
+  echo "  • one-shot manual override (consumed on use):" >&2
+  echo "      touch ${COS_PANEL_DIR:-$COS_AGENT_DIR}/.doc-anchor-override" >&2
+  exit 2
+fi
+
+# D5-F3 (TASK-128): if the anchor names explicit docs/ path(s), at least one
+# must resolve on disk — catches typos + hallucinated anchors. A task-based
+# anchor (task:TASK-NNN, no direct docs/ path) is proven by the task's Read
+# First, so skip the disk check when no docs/ token is present.
+_ANCHOR_DOC_PATHS=$(grep -oE 'docs/[A-Za-z0-9._/-]+\.md' "$ANCHOR_FILE" 2>/dev/null | sort -u || true)
+if [[ -n "$_ANCHOR_DOC_PATHS" ]]; then
+  _ANCHOR_RESOLVED=0
+  for _p in $_ANCHOR_DOC_PATHS; do
+    if [[ -f "${COS_PROJECT_ROOT:-.}/$_p" || -f "$_p" ]]; then
+      _ANCHOR_RESOLVED=1
+      break
+    fi
+  done
+  if [[ "$_ANCHOR_RESOLVED" -eq 0 ]]; then
+    echo "BLOCKED: doc-anchor references docs/ path(s) that do not exist on disk:" >&2
+    for _p in $_ANCHOR_DOC_PATHS; do echo "    $_p" >&2; done
+    echo "  A hallucinated or mistyped anchor does not prove a spec exists (Rule 0)." >&2
+    echo "  Re-anchor to a real doc:" >&2
+    echo "    bash \".${COS_AGENT}/hooks/write-state.sh\" .doc-anchor \"<docs/ path> § <section>\"" >&2
+    cos_log_hook enforce-doc-anchor block "anchor_path_missing" || true
+    exit 2
+  fi
+fi
+
+# Session-aware anchors use the first line as "<session-id> task:<id>".
+# Legacy anchors (pre-session prefix) are allowed only while fresh.
+ANCHOR_HEADER=$(head -1 "$ANCHOR_FILE" 2>/dev/null || true)
+# Require a non-empty task id after `task:` so a header alone proves an
+# anchor (it names a task whose Read First lists the docs). This lets a
+# one-line anchor written by write-state.sh (`ses-… task:TASK-NNN <ref>`)
+# pass, not just the multi-line form cos-task-start writes.
+if echo "$ANCHOR_HEADER" | grep -qE '^ses-[^[:space:]]+[[:space:]]+task:[A-Za-z0-9_-]+'; then
+  if type check_state >/dev/null 2>&1; then
+    check_state "$ANCHOR_FILE" "$ANCHOR_MAX_AGE"
+    if [[ "${STATE_VALID:-}" != "true" ]]; then
+      echo "BLOCKED: Doc anchor is stale or belongs to another session." >&2
+      echo "  File: $ANCHOR_FILE" >&2
+      echo "  Reason: ${STATE_REASON:-unknown}" >&2
+      echo "  Re-run \`cos task-start TASK-NNN\` so the anchor refreshes for this session." >&2
+      exit 2
+    fi
+  fi
+  # Content = the header's own `task:<id> <ref>` (minus the session token)
+  # PLUS any continuation lines. A one-line anchor keeps its task ref;
+  # a multi-line cos-task-start anchor adds the Read First doc paths.
+  HEADER_CONTENT=$(printf '%s' "$ANCHOR_HEADER" | sed -E 's/^ses-[^[:space:]]+[[:space:]]+//')
+  ANCHOR_CONTENT=$(printf '%s\n%s' "$HEADER_CONTENT" "$(tail -n +2 "$ANCHOR_FILE" | head -20)")
+else
+  FILE_AGE=$(file_age_seconds "$ANCHOR_FILE")
+  if [[ "$FILE_AGE" -gt "$ANCHOR_MAX_AGE" ]]; then
+    echo "BLOCKED: Legacy doc anchor is stale and cannot prove session ownership." >&2
+    echo "  File: $ANCHOR_FILE" >&2
+    echo "  Re-run \`cos task-start TASK-NNN\` to refresh the anchor with a session header." >&2
+    exit 2
+  fi
+  ANCHOR_CONTENT=$(head -20 "$ANCHOR_FILE")
+fi
+
+if [[ -z "$(echo "$ANCHOR_CONTENT" | tr -d '[:space:]')" ]]; then
+  echo "BLOCKED: Doc anchor is empty for this session." >&2
+  echo "  File: $ANCHOR_FILE" >&2
+  echo "  Populate Source of Truth / Read First, then re-run \`cos task-start TASK-NNN\`." >&2
+  exit 2
+fi
+
+# Check the anchor is a real reference, not a placeholder.
+if echo "$ANCHOR_CONTENT" | grep -qiE '^\s*(-\s*)?(\{[^}]*\}|_\(unfilled\)_|_\(not[[:space:]]+recorded\)_|_\(to[[:space:]]+be[[:space:]]+defined\)_|none|tbd|n/a|`?docs/\.\.\.`?|`?path/to/code\.ext`?)\s*$|^\s*\*\*REQUIRED\b|^\s*-\s*Pre-implementation:\s*`?docs/\.\.\.`?\s*$|^\s*-\s*Post-implementation:\s*`?path/to/code\.ext`?\s*$'; then
+  echo "BLOCKED: Doc anchor is a placeholder, not a real reference." >&2
+  echo "  File: $ANCHOR_FILE" >&2
+  echo "  Populate the Source of Truth / Read First in the active task file," >&2
+  echo "  then re-run \`cos task-start\` so the anchor gets refreshed." >&2
+  exit 2
+fi
+
+exit 0

core/hooks/enforce-doc-sync.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# PostToolUse Write|Edit|MultiEdit — code → doc staleness scanner.
+#
+# WHY
+#   Closes the docs-first loop in the OTHER direction. Rule 0 (docs-first
+#   anchor) makes new code trace TO a doc; this hook makes existing docs
+#   surface when the code drifts AWAY from them. Three drift signals,
+#   ranked by confidence:
+#     1. Public symbol REMOVED/RENAMED + doc still mentions it.
+#     2. Public symbol KEPT but signature changed (param count diff).
+#        ← addresses the "agent invented a `birthdate` field" case.
+#     3. Doc mtime older than code AND doc mentions a current symbol
+#        (soft signal, only emitted when no stronger one fires).
+#
+# COLLABORATES WITH
+#   - thinking_os FTS5 index (document_chunks_fts) — used to find docs
+#     that lexically reference touched symbols. Far more accurate than
+#     path-mirror heuristics.
+#   - graph_os backend (when up) — adds "this symbol is referenced from
+#     N other locations" hint via `cos_graph_references`. Capped at
+#     200 ms; silent if backend down.
+#
+# CONTRACT
+#   - WARN class: exit 0 always; advisory stderr only.
+#   - Skips .md/.mdx (no recursion), .yaml/.json/.toml/.lock.
+#   - Triggers only on code: .py/.ts/.tsx/.js/.jsx/.go.
+#   - Hot path = local FTS query (~10 ms). Graph call only when WARN
+#     already decided.
+#
+# FORMAT (stderr)
+#     ⚠ doc-sync — code edit may have outdated docs:
+#         <doc_path> — <reason>
+#         ...
+#       ℹ graph context: `<symbol>` referenced from N other location(s)
+#
+#       Docs are source of truth (AGENTS.md A0 + W8). Either:
+#         1. update the doc to match the new code, OR
+#         2. revert the code to match the doc spec.
+
+set -euo pipefail
+
+# Resolve to source dir even when invoked via .{claude,codex}/hooks
+# symlink so we can find _helpers/. Same idiom as agent-presence.sh.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+COS_HOOK_SRC_DIR="$(cd -P "$(dirname "$_src")" && pwd)"
+unset _src _dir
+
+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=""
+if [[ ! -t 0 ]]; then
+  INPUT=$(cat 2>/dev/null || true)
+fi
+
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || true)
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+
+case "$TOOL" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+[[ -z "$FILE_PATH" ]] && exit 0
+[[ ! -f "$FILE_PATH" ]] && exit 0
+
+# Skip docs editing docs (no recursion) and config files.
+case "$FILE_PATH" in
+  *.md|*.mdx|*.yaml|*.yml|*.json|*.toml|*.lock) exit 0 ;;
+esac
+
+HELPER="$COS_HOOK_SRC_DIR/_helpers/doc_sync_check.py"
+[[ ! -f "$HELPER" ]] && { cos_log_hook enforce-doc-sync skip "reason=helper_missing"; exit 0; }
+
+# Try to recover the pre-edit content for diff signals. Edit carries
+# old_string for one chunk; MultiEdit carries an `edits` array (we use
+# the first old_string — enough to feed the symbol extractor).
+OLD_TEXT=$(printf '%s' "$INPUT" | jq -r '
+  .tool_input.old_string //
+  (.tool_input.edits[0].old_string // empty)
+' 2>/dev/null || true)
+
+HELPER_OUT=$(
+  if [[ -n "$OLD_TEXT" ]]; then
+    python3 "$HELPER" "$FILE_PATH" "$OLD_TEXT" 2>/dev/null
+  else
+    python3 "$HELPER" "$FILE_PATH" 2>/dev/null
+  fi
+) || true
+
+# ── Verification matrix reminder (D4: absorbed from verify-changed-file.sh) ──
+# Prints which test suite to run. Always emits, regardless of FTS findings.
+_VERIFY_HINT=""
+case "$FILE_PATH" in
+  *core/thinking_os/*.py)
+    _VERIFY_HINT="uv run --extra rag pytest src/core/thinking_os/tests/ -q"
+    ;;
+  *core/graph_os/*.py)
+    _VERIFY_HINT="uv run --extra graph_os pytest src/core/graph_os/tests/ -q"
+    ;;
+  *core/board_os/*.py)
+    _VERIFY_HINT="uv run --extra rag --with aiohttp --with pytest-asyncio pytest src/core/board_os/tests/ -q"
+    ;;
+  *core/hooks/*.sh|*core/scripts/*.sh)
+    _VERIFY_HINT="make verify-hooks"
+    ;;
+  *adapters/*.py|*adapters/*.sh)
+    _VERIFY_HINT="uv run pytest tests/test_adapters.py tests/test_adapter_parity.py -q"
+    ;;
+  *cli/*.py)
+    _VERIFY_HINT="uv run pytest tests/test_cli.py -q"
+    ;;
+esac
+
+if [[ -z "$HELPER_OUT" ]]; then
+  # No FTS staleness found — emit companion-doc hints as a soft reminder
+  # (D2: absorbed from doc-sync-reminder.sh).
+  COMPANION_DOCS=()
+  case "$FILE_PATH" in
+    *core/hooks/*.sh)
+      COMPANION_DOCS=(
+        "docs/engineering/hooks-reference.md"
+        "src/core/hooks/registry.yaml (SSOT — register new hooks here)"
+      )
+      ;;
+    *core/thinking_os/server.py|*core/thinking_os/tools/*.py)
+      COMPANION_DOCS=(
+        "docs/governance/mcp-tool-inventory.md"
+        "docs/engineering/mcp-error-envelope.md"
+      )
+      ;;
+    *core/thinking_os/database.py)
+      COMPANION_DOCS=("docs/architecture/meta-project.md (§ schema/migrations)")
+      ;;
+    *cli/*.py)
+      COMPANION_DOCS=(
+        "docs/architecture/meta-project.md (§ CLI)"
+      )
+      ;;
+    *adapters/*/adapter.yaml|*adapters/*/install.sh)
+      COMPANION_DOCS=("docs/engineering/adapter-parity.md")
+      ;;
+  esac
+  if [[ ${#COMPANION_DOCS[@]} -gt 0 ]]; then
+    echo "" >&2
+    echo "  📘 doc-sync hint — keep these docs in sync:" >&2
+    for d in "${COMPANION_DOCS[@]}"; do
+      echo "     → $d" >&2
+    done
+  fi
+  if [[ -n "$_VERIFY_HINT" ]]; then
+    echo "" >&2
+    echo "  ✓ verify: $_VERIFY_HINT" >&2
+  fi
+  cos_log_hook enforce-doc-sync ok "file=${FILE_PATH##*/}"
+  exit 0
+fi
+
+# Surface FTS staleness findings to the agent via stderr.
+echo "" >&2
+echo "⚠ doc-sync — code edit may have outdated docs:" >&2
+STALE_COUNT=0
+INFO_LINES=()
+while IFS=$'\t' read -r tag doc reason; do
+  case "$tag" in
+    STALE)
+      echo "    ${doc} — ${reason}" >&2
+      STALE_COUNT=$((STALE_COUNT + 1))
+      ;;
+    INFO)
+      INFO_LINES+=("$reason")
+      ;;
+  esac
+done < <(printf '%s\n' "$HELPER_OUT")  # process-sub, not <<<: no bash heredoc deadlock on large helper output
+if [[ ${#INFO_LINES[@]} -gt 0 ]]; then
+  echo "" >&2
+  for line in "${INFO_LINES[@]}"; do
+    echo "  ℹ graph context: ${line}" >&2
+  done
+fi
+echo "" >&2
+echo "  Docs are source of truth (AGENTS.md). Either:" >&2
+echo "    1. update the doc to match the new code, OR" >&2
+echo "    2. revert the code to match the doc spec." >&2
+if [[ -n "$_VERIFY_HINT" ]]; then
+  echo "" >&2
+  echo "  ✓ verify: $_VERIFY_HINT" >&2
+fi
+echo "" >&2
+
+# D5-F5 (TASK-128): opt-in strict mode turns the WARN into a BLOCK so a CI or
+# careful session can gate on stale docs. Default stays warn (exit 0).
+if [[ "${COS_ENFORCE_DOC_SYNC:-warn}" == "strict" && "$STALE_COUNT" -gt 0 ]]; then
+  echo "  COS_ENFORCE_DOC_SYNC=strict → blocking until docs and code are reconciled." >&2
+  cos_log_hook enforce-doc-sync block "file=${FILE_PATH##*/} stale=${STALE_COUNT}"
+  exit 2
+fi
+
+cos_log_hook enforce-doc-sync warn "file=${FILE_PATH##*/} stale=${STALE_COUNT}"
+exit 0