coding-os 0.3.2__py3-none-any.whl

core/hooks/block-bad-patterns.sh

@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# PreToolUse hook: Block known anti-patterns in code being written.
+# Source: docs/engineering/backend-rules.md, docs/engineering/frontend-rules.md
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+# Fail-closed: an anti-pattern gate that cannot read its input must DENY,
+# not silently allow when jq is absent (observability-eye I8). cos_json_field
+# falls back to python3, so the gate keeps working when only jq is missing.
+cos_require_parser block-bad-patterns
+
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL=$(printf '%s' "$INPUT" | cos_json_field tool_name)
+
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(printf '%s' "$INPUT" | cos_json_field tool_input.file_path)
+CONTENT=$(printf '%s' "$INPUT" | cos_json_field tool_input.new_string tool_input.content)
+
+# === SHELL HOOK / INSTALLER GUARD (bash 5.3.9 deadlock) ===
+# Homebrew bash 5.3.9 sporadically deadlocks `cmd - <<HEREDOC` patterns
+# in heredoc_write before forking the child. Hot-path hooks accumulate
+# zombie bashes that eventually starve the agent runtime's auxiliary
+# subprocess spawns ("Subprocess initialization did not complete within
+# 60000ms"). install.sh hangs at the first heredoc that hits the bug.
+#
+# Safe replacements (verified zero-zombie under stress):
+#   A) python3 -c "$(cat <<'PY' ... PY)" arg1 arg2  ← cat captures heredoc;
+#      python3 receives -c <string> as argument. No stdin pipe.
+#   B) python3 path/to/helper.py arg1 arg2          ← extracted helper.
+#
+# Past incidents: agent-presence zombie pile-up (2026-04-25 morning),
+# install.sh hang on `Re-linked stack skills` (2026-04-26).
+# Forensics: docs/engineering/bash-heredoc-deadlock.md.
+if [[ "$FILE_PATH" == *.sh ]] && [[
+      "$FILE_PATH" == *core/hooks/* ||
+      "$FILE_PATH" == *adapters/*/install* ||
+      "$FILE_PATH" == *adapters/*/hooks/* ||
+      "$FILE_PATH" == *.claude/hooks/* ||
+      "$FILE_PATH" == *.codex/hooks/* ]]; then
+  # Strip shell comment lines before scanning so docs that *describe* the
+  # dangerous pattern (e.g. session-context.sh line 159 warns about the
+  # heredoc-write deadlock) do not trip the regex.
+  CODE_ONLY=$(echo "$CONTENT" | grep -vE '^[[:space:]]*#')
+
+  if echo "$CODE_ONLY" | grep -qE 'python3? +- +.*<<'; then
+    echo "BLOCKED: \`cmd - <<HEREDOC\` pattern detected — bash 5.3.9 sporadically" >&2
+    echo "         deadlocks this in heredoc_write before fork. Hot-path hooks +" >&2
+    echo "         installer scripts that fire it accumulate zombies and starve" >&2
+    echo "         agent runtime spawns. See docs/engineering/bash-heredoc-deadlock.md." >&2
+    echo "" >&2
+    echo "         Safe replacement: separate .py file invoked as" >&2
+    echo "           python3 \$(dirname \"\$0\")/_helpers/<name>.py arg1 arg2" >&2
+    exit 2
+  fi
+  # Detect form A nested inside command substitution (sample(1) shows the
+  # hang at expand_word_internal -> command_substitute -> wait_for).
+  # See docs/engineering/bash-heredoc-deadlock.md for the full forensics.
+  if echo "$CODE_ONLY" | grep -qE '\$\(.*python3? +-c +.*\$\(cat +<<'; then
+    echo "BLOCKED: nested heredoc-in-\$(...)  detected — bash 5.3.9 sporadically" >&2
+    echo "         deadlocks even \`python3 -c \"\$(cat <<'PY'...)\"\` when wrapped" >&2
+    echo "         inside another \$(...). install.sh hung on this 2026-04-26." >&2
+    echo "" >&2
+    echo "         Safe replacement: separate .py file" >&2
+    echo "           VAR=\$(python3 \"\$HELPER_DIR/extract.py\" \"\$arg1\")" >&2
+    echo "         See docs/engineering/bash-heredoc-deadlock.md for forensics." >&2
+    exit 2
+  fi
+fi
+
+# Skip non-code files and migration files
+if [[ "$FILE_PATH" != *.py ]] && [[ "$FILE_PATH" != *.ts ]] && [[ "$FILE_PATH" != *.tsx ]] && [[ "$FILE_PATH" != *.js ]]; then
+  exit 0
+fi
+if [[ "$FILE_PATH" == *__pycache__* ]] || [[ "$FILE_PATH" == *node_modules* ]]; then
+  exit 0
+fi
+
+# Migration-specific rules (before skipping migrations for general rules)
+if [[ "$FILE_PATH" == *migrations* ]] && [[ "$FILE_PATH" == *.py ]]; then
+  # Block RunPython without reverse_code
+  # Source: backend-rules.md § Migration Rules
+  if echo "$CONTENT" | grep -qE 'RunPython\(' && ! echo "$CONTENT" | grep -qE 'reverse_code'; then
+    echo "BLOCKED: RunPython migration must include reverse_code for rollback safety. See docs/engineering/backend-rules.md § Migration Rules." >&2
+    exit 2
+  fi
+  # Migrations pass all other checks
+  exit 0
+fi
+
+# === UNIVERSAL RULES ===
+
+# A committed TODO is untracked work — prefer `cos task-create` over a marker. This
+# blocks a bare marker; a task-ref only makes a transient mid-dev marker trackable
+# (remove before commit) — it is NOT comment provenance, which clean-code §4 forbids
+# in explanatory comments. Skip: tests + templates/*/skills/*/scripts/ placeholders.
+if [[ "$FILE_PATH" != *test* ]] && [[ "$FILE_PATH" != *spec* ]] \
+   && [[ "$FILE_PATH" != *templates/*/skills/*/scripts/* ]]; then
+  # Check if TODO exists but TASK-### does NOT exist in the same content
+  if echo "$CONTENT" | grep -qiE '(//|#)\s*TODO' && ! echo "$CONTENT" | grep -qE 'TASK-[0-9]{3}'; then
+    echo "BLOCKED: bare TODO in committed code. Prefer 'cos task-create' over a marker; if a transient mid-dev marker is unavoidable make it trackable as 'TODO(TASK-###)' and remove before commit — a task-ref is a TODO-tracker, never provenance in an explanatory comment (clean-code §4 / Rule 12)." >&2
+    exit 2
+  fi
+fi
+
+# === BACKEND RULES ===
+if [[ "$FILE_PATH" == *.py ]]; then
+
+  # Skip test files for backend-specific rules (tests may legitimately use print, pass, etc.)
+  if [[ "$FILE_PATH" == *test* ]]; then
+    exit 0
+  fi
+
+  # Block except-pass where pass is the ONLY handler (no logging, no re-raise)
+  # Source: backend-rules.md § Error Handling Policy
+  if echo "$CONTENT" | grep -qE 'except' && echo "$CONTENT" | grep -qE '^\s*pass\s*$'; then
+    # Only block if there's no logging in the same content (indicating bare except:pass)
+    if ! echo "$CONTENT" | grep -qE 'logger\.|logging\.|raise '; then
+      echo "BLOCKED: Bare 'except: pass' swallows errors silently. Log the error or re-raise. See docs/engineering/backend-rules.md § Error Handling Policy." >&2
+      exit 2
+    fi
+  fi
+
+  # Block print() in production backend code (use logger instead)
+  # Source: backend-rules.md § Observability
+  if [[ "$FILE_PATH" == *backend/apps/* ]]; then
+    if echo "$CONTENT" | grep -qE '^\s*print\('; then
+      echo "BLOCKED: Use 'import logging; logger = logging.getLogger(__name__); logger.info(...)' instead of print() in backend code. See docs/engineering/backend-rules.md." >&2
+      exit 2
+    fi
+  fi
+
+  # Block .save()/.delete() in views (views should be thin, use services)
+  # Source: backend-rules.md § Core Rules
+  if [[ "$FILE_PATH" == *views* ]] || [[ "$FILE_PATH" == *viewsets* ]]; then
+    if echo "$CONTENT" | grep -qE '\.(save|delete)\(\)'; then
+      echo "BLOCKED: Views must be thin — do not call .save() or .delete() in views. Move business logic to a service function. See docs/engineering/backend-rules.md § Core Rules." >&2
+      exit 2
+    fi
+  fi
+
+  # Block ORM queries in views (use selectors instead)
+  # Source: backend-rules.md § Core Rules
+  if [[ "$FILE_PATH" == *views* ]] || [[ "$FILE_PATH" == *viewsets* ]]; then
+    if echo "$CONTENT" | grep -qE '\.objects\.(filter|get|exclude|annotate|aggregate|create|update|bulk)'; then
+      echo "BLOCKED: Do not query ORM directly in views. Use a selector function from selectors.py. See docs/engineering/backend-rules.md § Core Rules." >&2
+      exit 2
+    fi
+  fi
+
+  # Block bare raise ValueError/Exception in service layer (use typed domain exceptions)
+  # Source: backend-rules.md § Error Handling Policy
+  if [[ "$FILE_PATH" == *services* ]]; then
+    if echo "$CONTENT" | grep -qE 'raise\s+(ValueError|Exception|RuntimeError)\('; then
+      echo "BLOCKED: Do not raise bare ValueError/Exception in services. Define a typed exception in apps/<domain>/exceptions.py inheriting APIException. See docs/engineering/backend-rules.md § Error Handling Policy." >&2
+      exit 2
+    fi
+  fi
+
+fi
+
+# === FRONTEND RULES ===
+if [[ "$FILE_PATH" == *.ts ]] || [[ "$FILE_PATH" == *.tsx ]] || [[ "$FILE_PATH" == *.js ]]; then
+
+  # Skip test/spec files
+  if [[ "$FILE_PATH" == *test* ]] || [[ "$FILE_PATH" == *spec* ]] || [[ "$FILE_PATH" == *__tests__* ]]; then
+    exit 0
+  fi
+
+  # Block console.log in production frontend code (allow console.error/warn)
+  # Source: frontend-rules.md § Code Style
+  if [[ "$FILE_PATH" == *frontend/src/* ]]; then
+    if echo "$CONTENT" | grep -qE 'console\.log\('; then
+      echo "BLOCKED: Remove console.log() from production code. Use console.error() for real errors only. See docs/engineering/frontend-rules.md." >&2
+      exit 2
+    fi
+  fi
+
+  # Block 'any' type in TypeScript (use proper types)
+  # Source: frontend-rules.md § Non-Negotiables
+  # Honors the standard `// eslint-disable-next-line @typescript-eslint/no-explicit-any`
+  # escape hatch so lines explicitly marked safe (e.g. third-party generics
+  # with overly strict types) do not trip the gate. Without this exemption
+  # the hook fires on every commit touching the file even when the diff
+  # does not introduce new `any` usage.
+  if [[ "$FILE_PATH" == *.ts ]] || [[ "$FILE_PATH" == *.tsx ]]; then
+    if echo "$CONTENT" | awk '
+        /eslint-disable-next-line.*no-explicit-any/ { skip=1; next }
+        skip { skip=0; next }
+        /:[[:space:]]*any($|[^[:alnum:]_])|<any>|(^|[^[:alnum:]_])as[[:space:]]+any($|[^[:alnum:]_])|,[[:space:]]*any($|[^[:alnum:]_])|\|[[:space:]]*any($|[^[:alnum:]_])/ { found=1; exit }
+        END { exit !found }
+    '; then
+      echo "BLOCKED: Do not use 'any' type. Define a proper TypeScript type or interface. See docs/engineering/frontend-rules.md § Non-Negotiables." >&2
+      echo "  Hint: prefix the line with: // eslint-disable-next-line @typescript-eslint/no-explicit-any" >&2
+      exit 2
+    fi
+  fi
+
+  # Block non-NEXT_PUBLIC_ env vars in frontend client code (backend secret leak)
+  # Source: frontend-rules.md § Mandatory Engineering Rules
+  if [[ "$FILE_PATH" == *frontend/* ]]; then
+    if echo "$CONTENT" | grep -qE 'process\.env\.(STRIPE_SECRET|DATABASE_URL|DJANGO_SECRET|POSTMARK_SERVER_TOKEN|SECRET_KEY)'; then
+      echo "BLOCKED: Backend secret detected in frontend code. Only NEXT_PUBLIC_* variables are safe for the browser. See docs/engineering/frontend-rules.md § Mandatory Engineering Rules." >&2
+      exit 2
+    fi
+  fi
+fi
+
+exit 0

core/hooks/block-dangerous-commands.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# PreToolUse hook: Block dangerous bash commands that could cause data loss.
+# Source: AGENTS.md § Principles (P5), git safety
+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 a _helpers/<name> path through THIS hook's symlink chain — the
+# .claude/.codex symlink points at the .sh only, not the _helpers/ tree, so a
+# $(dirname "$0")-relative path misses. Echoes the absolute helper path.
+_resolve_helper() {
+  local src="${BASH_SOURCE[0]}" dir
+  while [ -L "$src" ]; do
+    dir="$(cd -P "$(dirname "$src")" && pwd)"
+    src="$(readlink "$src")"
+    [[ "$src" != /* ]] && src="${dir}/${src}"
+  done
+  printf '%s' "$(cd -P "$(dirname "$src")" && pwd)/_helpers/$1"
+}
+
+# Fail-closed: a data-loss gate that cannot read the command must DENY,
+# not silently allow when jq is absent (observability-eye I8).
+cos_require_parser block-dangerous-commands
+
+INPUT="$(cos_read_stdin_bounded 2)"
+
+# Fast-path: this gate fires on EVERY Bash command. The common case (no
+# dangerous verb anywhere in the payload) must cost zero jq/python spawns.
+# Every block below keys on one of these literals; if the raw payload mentions
+# none of them there is nothing to deny — bail before parsing. (`rm`/`mv` etc.
+# are still parsed properly downstream; this only short-circuits the no-match.)
+# Indirection tokens (eval/xargs/<<</|sh) and hub-settings.json are included so an
+# indirection-wrapped dangerous op or a policy-file write is never fast-skipped.
+case "$INPUT" in
+  *"git push"*|*"git reset"*|*"git clean"*|*rm*|*migrate*|*DROP*|*Drop*|*drop*|*eval*|*xargs*|*"<<<"*|*"|sh"*|*"| sh"*|*"|bash"*|*"| bash"*|*hub-settings.json*) ;;
+  *) exit 0 ;;
+esac
+
+TOOL=$(printf '%s' "$INPUT" | cos_json_field tool_name)
+
+if [[ "$TOOL" != "Bash" ]]; then
+  exit 0
+fi
+
+cos_log_hook block-dangerous-commands fire "tool=Bash"
+COMMAND=$(printf '%s' "$INPUT" | cos_json_field tool_input.command)
+
+# Block a Bash write to the git-policy file (TASK-587b): rewriting
+# .coding-os/hub-settings.json from a shell self-downgrades pr-mode -> trunk,
+# where a non-force push to main is legal. Gated on the basename so non-policy
+# commands skip the python spawn. Defense-in-depth — fails OPEN on helper error;
+# the authoritative wall is server-side branch protection.
+case "$COMMAND" in
+  *hub-settings.json*)
+    SET_VERDICT=$(printf '%s' "$INPUT" | python3 "$(_resolve_helper check_settings_write.py)" 2>/dev/null || echo allow)
+    if [ "$SET_VERDICT" = "block" ]; then
+      cos_log_hook block-dangerous-commands block "rule=settings-policy-write"
+      echo "BLOCKED: writing .coding-os/hub-settings.json from a shell flips the git workflow (pr<->trunk). Change git settings only via the Hub Config->Git tab — it is the policy file branch-guard reads on every hook." >&2
+      exit 2
+    fi
+    ;;
+esac
+
+# Shell-indirection recovery (TASK-587a): un-glue git commands hidden inside
+# eval / pipe-into-sh / here-string / xargs so the force-push / reset / clean
+# greps below see them. Gated on an indirection token so the common path spawns
+# no python. branch-guard is the fail-closed twin for the protected ops.
+COMMAND_SCAN="$COMMAND"
+case "$COMMAND" in
+  *eval*|*xargs*|*"<<<"*|*"|sh"*|*"| sh"*|*"|bash"*|*"| bash"*)
+    _RECOVERED=$(printf '%s' "$INPUT" | python3 "$(_resolve_helper recover_indirect.py)" 2>/dev/null || true)
+    [[ -n "$_RECOVERED" ]] && COMMAND_SCAN="$COMMAND"$'\n'"$_RECOVERED"
+    unset _RECOVERED
+    ;;
+esac
+
+# Block force push to main/master. Opt-in escape hatch for legitimate cases
+# (pre-public history scrub, secret removal, BFG-style cleanup): EXPORT
+# COS_ALLOW_FORCE_PUSH_MAIN=1 into the session env before the call. An inline
+# `COS_ALLOW_FORCE_PUSH_MAIN=1 git push …` prefix does NOT work and is rejected
+# by design — the assignment has not executed when this PreToolUse hook reads
+# its own process env, so an agent cannot self-grant the override from the
+# command string (TASK-567 F3). Only a deliberate operator session-export opens it.
+_FORCE_PUSH_OPT_IN=0
+if [[ "${COS_ALLOW_FORCE_PUSH_MAIN:-0}" == "1" ]]; then
+  _FORCE_PUSH_OPT_IN=1
+fi
+if [[ "$_FORCE_PUSH_OPT_IN" != "1" ]]; then
+  # Force-push to main/master. git IGNORES flag position, so detect the push, the
+  # force flag, and the main/master target INDEPENDENTLY — the old `--force.*main`
+  # regex missed `git push origin main --force` / `... main -f` (flag AFTER refspec,
+  # TASK-571). `--force-with-lease` is the safe variant (and the pr-mode submit path)
+  # so the boundary `--force([space]|$)` deliberately excludes it.
+  if echo "$COMMAND_SCAN" | grep -qE '(^|[[:space:];&|])git[[:space:]]+push' \
+     && echo "$COMMAND_SCAN" | grep -qE '(--force([[:space:]]|$)|(^|[[:space:]])-f([[:space:]]|$))' \
+     && echo "$COMMAND_SCAN" | grep -qE '(^|[[:space:]/+:])(main|master)([[:space:]]|$)'; then
+    cos_log_hook block-dangerous-commands block "rule=force-push-main"
+    echo "BLOCKED: Force push to main/master is extremely dangerous and can destroy shared history. Use a feature branch instead. (Override: export COS_ALLOW_FORCE_PUSH_MAIN=1 session-wide; an inline prefix is rejected.)" >&2
+    exit 2
+  fi
+  # Force via refspec: `+main` / `+HEAD:main` / `+refs/heads/main` (any qualifier —
+  # the old regex needed a colon, so the fully-qualified `+refs/heads/main` slipped).
+  if echo "$COMMAND_SCAN" | grep -qE '(^|[[:space:];&|])git[[:space:]]+push[^|;&]*[[:space:]]\+[^[:space:]]*(main|master)\b'; then
+    cos_log_hook block-dangerous-commands block "rule=force-push-main-refspec"
+    echo "BLOCKED: force-push refspec (+main/+master) rewrites shared history. Use a feature branch instead. (Override: export COS_ALLOW_FORCE_PUSH_MAIN=1 session-wide; an inline prefix is rejected.)" >&2
+    exit 2
+  fi
+fi
+
+# Block dropping database tables
+if echo "$COMMAND" | grep -qiE 'DROP\s+(TABLE|DATABASE)'; then
+  cos_log_hook block-dangerous-commands block "rule=drop-db"
+  echo "BLOCKED: DROP TABLE/DATABASE is destructive and irreversible. If this is intentional, ask the user to confirm and run it manually." >&2
+  exit 2
+fi
+
+# Block recursive rm of a critical path (root / cwd / parent / glob / project
+# dirs / top-level absolute). Delegated to a shlex-correct helper so flag-order
+# (-fr, -r -f) and bare /·.·..·* targets can't slip past a regex word-boundary.
+# Skip the python helper spawn entirely when COMMAND has no `rm` token — the
+# helper would return `allow` for a command with no rm, so this is a pure
+# fast-path (saves a ~50ms python3 startup on every non-rm git/sql command).
+case "$COMMAND" in
+  *rm*) ;;
+  *)
+    # No rm at all → nothing for the helper to deny; fall through past the
+    # rm gate to the remaining (migrate / reset / clean) checks.
+    RM_VERDICT="allow"
+    ;;
+esac
+if [ "${RM_VERDICT:-}" != "allow" ]; then
+RM_VERDICT=$(printf '%s' "$INPUT" | python3 "$(_resolve_helper check_dangerous_rm.py)" 2>/dev/null || echo error)
+fi
+# Fail-closed but SCOPED: a helper crash/absence (RM_VERDICT=error) blocks
+# only when the command actually contains a recursive rm we could not verify —
+# never brick unrelated commands (observability-eye I8/A2).
+if [ "$RM_VERDICT" = "error" ]; then
+  if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])(sudo[[:space:]]+)?rm[[:space:]]+(-[A-Za-z]*[rR]|--recursive)'; then
+    cos_say error hook.block_dangerous_commands "check_dangerous_rm helper unavailable — failing closed on a recursive rm" 2>/dev/null || true
+    RM_VERDICT="block"
+  else
+    RM_VERDICT="allow"
+  fi
+fi
+if [ "$RM_VERDICT" = "block" ]; then
+  cos_log_hook block-dangerous-commands block "rule=rm-rf-critical"
+  echo "BLOCKED: recursive rm targeting a critical path (/, ., .., *, a project dir, or a top-level directory). Name the exact files to remove, or ask the user to run it manually." >&2
+  exit 2
+fi
+
+# Block direct migration apply to production
+if echo "$COMMAND" | grep -qE 'manage\.py migrate.*--settings.*production'; then
+  cos_log_hook block-dangerous-commands block "rule=prod-migrate"
+  echo "BLOCKED: Production migrations require human execution (AGENTS.md P5). Ask the user to run this command manually." >&2
+  exit 2
+fi
+
+# Block destructive `git reset --hard` / `git clean -f`. Delegated to a
+# shlex-correct helper so a long-option ABBREVIATION (`reset --har`, `clean
+# --for`/`--f`) or a split short cluster (`clean -d -f`) can't slip the old
+# literal greps — git resolves any unambiguous prefix. Fed COMMAND_SCAN so a
+# recovered-indirection git op is scanned too. Fails OPEN on helper error;
+# branch-guard is the fail-closed twin for the HEAD-moving reset.
+if echo "$COMMAND_SCAN" | grep -qE 'git[[:space:]]+(reset|clean)'; then
+  DESTRUCTIVE_VERDICT=$(
+    jq -n --arg c "$COMMAND_SCAN" '{tool_name:"Bash",tool_input:{command:$c}}' \
+      | python3 "$(_resolve_helper check_git_destructive.py)" 2>/dev/null || echo allow
+  )
+  if [ "$DESTRUCTIVE_VERDICT" = "reset-hard" ]; then
+    cos_log_hook block-dangerous-commands block "rule=reset-hard"
+    echo "BLOCKED: git reset --hard discards all uncommitted changes permanently. Consider 'git stash' instead, or ask the user to confirm." >&2
+    exit 2
+  fi
+  if [ "$DESTRUCTIVE_VERDICT" = "clean-force" ]; then
+    cos_log_hook block-dangerous-commands block "rule=git-clean-force"
+    echo "BLOCKED: git clean -f permanently deletes untracked files. Ask the user to confirm which files should be removed." >&2
+    exit 2
+  fi
+fi
+
+exit 0

core/hooks/block-hardcoded-literals.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# PreToolUse Write|Edit hook: block hardcoded stack/adapter literals in cli/*.py.
+#
+# Catches the SSOT drift at EDIT time instead of test time. Stack and
+# adapter IDs ("django", "claude", "python-django", …) must never appear
+# as quoted literals inside cli/*.py — the registry loader reads them
+# from YAML. Pytest has tests/test_no_hardcoded_stacks.py as the rear
+# guard; this hook is the front guard so the offending edit never
+# lands on disk.
+#
+# Scope: only fires for files under cli/*.py (the data-driven layer).
+# Everywhere else — tests, templates, adapters — literals are expected.
+#
+# Escape hatch: $COS_STATE_DIR/.literals-override for one-shot bypass.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+# Fail-closed: an SSOT-drift gate that cannot read its input must DENY,
+# not silently allow when jq is absent (observability-eye I8). cos_json_field
+# falls back to python3, so the gate keeps working when only jq is missing.
+cos_require_parser block-hardcoded-literals
+
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL=$(printf '%s' "$INPUT" | cos_json_field tool_name)
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(printf '%s' "$INPUT" | cos_json_field tool_input.file_path)
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# Only guard the data-driven CLI layer.
+case "$FILE_PATH" in
+  *cli/*.py) ;;
+  *) exit 0 ;;
+esac
+
+COS_STATE_DIR="${COS_STATE_DIR:-.coding-os}"
+
+if cos_one_shot_override literals 2>/dev/null; then
+  exit 0
+fi
+
+if [[ "$TOOL" == "Write" ]]; then
+  CONTENT=$(printf '%s' "$INPUT" | cos_json_field tool_input.content)
+else
+  CONTENT=$(printf '%s' "$INPUT" | cos_json_field tool_input.new_string)
+fi
+[[ -z "$CONTENT" ]] && exit 0
+
+# Resolve the checker against the REAL src/core/hooks dir. This script runs
+# via a per-file symlink inside a dir-of-symlinks (.claude/hooks/ in every
+# consumer AND the meta-repo's own .claude), so $(dirname "$0")/../scripts
+# lands at the nonexistent .claude/scripts/ and the gate went SILENTLY inert
+# — letting hardcoded literals through on every PreToolUse edit. cos-env's
+# _cos_helpers_dir follows the symlink chain to the real .../hooks/_helpers;
+# its parent is the real hooks dir, whose ../scripts holds the checker.
+if declare -F _cos_helpers_dir >/dev/null 2>&1; then
+  CORE_HOOKS_DIR="$(dirname "$(_cos_helpers_dir)")"
+else
+  CORE_HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)"
+fi
+CHECKER="${CORE_HOOKS_DIR}/../scripts/check_hardcoded_literals.py"
+
+if [[ ! -f "$CHECKER" ]]; then
+  # Never silent again: a missing checker means a broken install, not "all
+  # clear". Stay fail-open (this gate's scope is narrow — cli/*.py only — and
+  # a half-installed tree must not block every cli edit), but make it LOUD.
+  echo "block-hardcoded-literals: SSOT-drift checker not found at $CHECKER — gate INERT; reinstall the adapter (bash src/adapters/<id>/install.sh)" >&2
+  exit 0
+fi
+
+# `|| RC=$?` keeps set -e from killing the script on the checker's rc=2, so
+# the override hint below actually prints (it was dead code under pipefail).
+RC=0
+echo "$CONTENT" | python3 "$CHECKER" --file "$FILE_PATH" || RC=$?
+
+if [[ $RC -eq 2 ]]; then
+  echo "  One-shot override: touch $COS_STATE_DIR/.literals-override" >&2
+  echo "  (or: echo '{\"literals\":{\"reason\":\"\"}}' > $COS_STATE_DIR/.overrides.json)" >&2
+  exit 2
+elif [[ $RC -ne 0 ]]; then
+  # A crashing checker (argparse/traceback, rc=1/127) is NOT a clean pass — stay
+  # fail-open (don't block every cli edit on a checker bug) but make it LOUD so
+  # the dead gate is observable, never silent (pass-3 review).
+  echo "block-hardcoded-literals: checker errored (rc=$RC) — edit allowed but the SSOT-drift gate did NOT run" >&2
+fi
+
+exit 0

core/hooks/block-migration-conflict.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# PreToolUse Write|Edit hook: block duplicate migration versions.
+#
+# Source of truth: CLAUDE.md Critical Rule #10 — "Schema migrations are
+# append-only. New tables → migration vN+1, never edit past migrations."
+#
+# Scope: runs only on files named `db.py` (migration registries in
+# thinking_os) and on files under `*/migrations/` for frameworks that
+# use numbered migration files (Django, Alembic).
+#
+# For database.py-style files: detects `MIGRATIONS.append((N, ...))` in the
+# new content and rejects N if it already exists in the current file.
+#
+# For framework migration files: detects attempts to create a file
+# named with a version prefix that already exists in the same dir
+# (0003_foo.py + 0003_bar.py = conflict).
+#
+# Fail-closed — a duplicate-version DB is corrupt and silent: this must
+# block, not warn.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+# Fail-closed: a duplicate-migration gate that cannot read its input must DENY,
+# not silently allow when jq is absent (observability-eye I8). cos_json_field
+# falls back to python3, so the gate keeps working when only jq is missing.
+cos_require_parser block-migration-conflict
+
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL=$(printf '%s' "$INPUT" | cos_json_field tool_name)
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(printf '%s' "$INPUT" | cos_json_field tool_input.file_path)
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# --- database.py-style registries ------------------------------------------
+# Fires when the changed file is named db.py OR when the diff adds a
+# MIGRATIONS.append line — whichever comes first.
+BASENAME=$(basename "$FILE_PATH")
+
+if [[ "$BASENAME" == "database.py" ]]; then
+  # Extract proposed new version from the tool input.
+  if [[ "$TOOL" == "Write" ]]; then
+    CONTENT=$(printf '%s' "$INPUT" | cos_json_field tool_input.content)
+  else
+    CONTENT=$(printf '%s' "$INPUT" | cos_json_field tool_input.new_string)
+  fi
+
+  # Find any N in `MIGRATIONS.append((N, ...))` patterns in the new content.
+  PROPOSED_VERSIONS=$(echo "$CONTENT" | grep -oE 'MIGRATIONS\.append\(\([[:space:]]*[0-9]+' | grep -oE '[0-9]+' | sort -u)
+
+  if [[ -z "$PROPOSED_VERSIONS" ]]; then
+    # No migration addition in this diff → allow.
+    exit 0
+  fi
+
+  # Current versions in the existing file.
+  if [[ -f "$FILE_PATH" ]]; then
+    EXISTING_VERSIONS=$(grep -oE 'MIGRATIONS\.append\(\([[:space:]]*[0-9]+' "$FILE_PATH" | grep -oE '[0-9]+' | sort -u)
+  else
+    EXISTING_VERSIONS=""
+  fi
+
+  CONFLICTS=()
+  for v in $PROPOSED_VERSIONS; do
+    if echo "$EXISTING_VERSIONS" | grep -qw "$v"; then
+      # Edit tool rewrites a line — only flag if the OLD string didn't
+      # already contain this version (i.e. truly adding a dup, not
+      # renaming an existing one).
+      if [[ "$TOOL" == "Edit" ]]; then
+        OLD_STRING=$(printf '%s' "$INPUT" | cos_json_field tool_input.old_string)
+        if echo "$OLD_STRING" | grep -qE "MIGRATIONS\.append\(\([[:space:]]*${v}[^0-9]"; then
+          continue  # this edit is replacing the v entry in-place
+        fi
+      fi
+      CONFLICTS+=("$v")
+    fi
+  done
+
+  if [[ ${#CONFLICTS[@]} -gt 0 ]]; then
+    NEXT=$(echo "$EXISTING_VERSIONS" | sort -n | tail -1)
+    NEXT=$(( NEXT + 1 ))
+    echo "BLOCKED: duplicate migration version(s): ${CONFLICTS[*]}" >&2
+    echo "  File: $FILE_PATH" >&2
+    echo "  Existing versions: $(echo "$EXISTING_VERSIONS" | paste -sd',' -)" >&2
+    echo "  CLAUDE.md Rule #10 — migrations are append-only." >&2
+    echo "  Use the next available version: $NEXT" >&2
+    exit 2
+  fi
+  exit 0
+fi
+
+# --- Numbered framework migrations -----------------------------------
+# Typical layout: backend/apps/<app>/migrations/NNNN_name.py
+# New Write creating 0003_foo.py when 0003_bar.py exists → conflict.
+if [[ "$FILE_PATH" == *migrations/*.py ]] && [[ "$TOOL" == "Write" ]]; then
+  if [[ ! -f "$FILE_PATH" ]]; then
+    DIR=$(dirname "$FILE_PATH")
+    NEW_PREFIX=$(basename "$FILE_PATH" | grep -oE '^[0-9]+' || true)
+    if [[ -n "$NEW_PREFIX" ]] && [[ -d "$DIR" ]]; then
+      EXISTING=$(find "$DIR" -maxdepth 1 -name "${NEW_PREFIX}_*.py" ! -path "$FILE_PATH" | head -3)
+      if [[ -n "$EXISTING" ]]; then
+        echo "BLOCKED: migration prefix ${NEW_PREFIX} already used in $DIR:" >&2
+        echo "$EXISTING" | sed 's/^/  - /' >&2
+        echo "  Use the next available prefix. Regenerate with \`makemigrations\`." >&2
+        exit 2
+      fi
+    fi
+  fi
+fi
+
+exit 0