coding-os 0.3.2__py3-none-any.whl

core/hooks/enforce-task-start.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# PreToolUse hook: BLOCK Write/Edit on code files unless a Scrumban task is active (cos task-start).
+# Session-scoped: only accepts task from the CURRENT session.
+# Allows ad-hoc CLEAR fixes by checking thinking_os-gate classification.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+# Fail-open if project state is incomplete (fresh clone, mid-init, wrong cwd).
+cos_sanity_check enforce-task-start 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 "")
+
+# Only enforce for code files
+if [[ "$FILE_PATH" != *.py ]] && [[ "$FILE_PATH" != *.ts ]] && [[ "$FILE_PATH" != *.tsx ]]; then
+  exit 0
+fi
+
+# Skip test files, migrations, generated files, config files, hook scripts
+if [[ "$FILE_PATH" == *test* ]] || [[ "$FILE_PATH" == *spec* ]] || [[ "$FILE_PATH" == *migrations* ]] || [[ "$FILE_PATH" == *node_modules* ]] || [[ "$FILE_PATH" == *__pycache__* ]] || [[ "$FILE_PATH" == *.claude/* ]] || [[ "$FILE_PATH" == *.codex/* ]] || [[ "$FILE_PATH" == *.coding-os/* ]]; then
+  exit 0
+fi
+
+# Persona-aware skip — when classify-task-mode marked the turn as a
+# read-only / exploratory mode, the agent shouldn't pay task-start
+# enforcement on incidental edits. `formal` / `propose-formal` /
+# `gov-required` still go through the full block path below.  Fail
+# open if the marker is missing (older sessions, fresh adapter).
+MODE_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.task-mode"  # panel-first
+[[ -f "$MODE_FILE" ]] || MODE_FILE="${COS_AGENT_DIR}/.task-mode"
+if [[ -f "$MODE_FILE" ]]; then
+  TASK_MODE=$(tr -d '\n\r' < "$MODE_FILE" 2>/dev/null | head -c 24)
+  case "$TASK_MODE" in
+    query|adhoc|chore|system) exit 0 ;;
+  esac
+fi
+
+
+# Allow CLEAR 1 ad-hoc fixes without a task
+source "$(dirname "$0")/check-state.sh"
+check_state "${COS_PANEL_DIR:-$COS_AGENT_DIR}/.thinking_os-gate" 7200
+if [[ "$STATE_VALID" == "true" ]]; then
+  CLASSIFICATION=$(echo "$STATE_VALUE" | awk '{print $1}')
+  DIMS=$(echo "$STATE_VALUE" | awk '{print $2}')
+  if [[ "$CLASSIFICATION" == "CLEAR" ]] && [[ "$DIMS" == "1" ]]; then
+    exit 0
+  fi
+fi
+
+# Check task-current (session-scoped, 8h timeout)
+check_state "${COS_PANEL_DIR:-$COS_AGENT_DIR}/.task-current" 28800
+
+if [[ "$STATE_VALID" != "true" ]]; then
+  echo "BLOCKED: No active task for this session. Reason: $STATE_REASON" >&2
+  echo "  Preferred:  cos task-create --title \"...\" --swimlane <domain> --kind <type>" >&2
+  echo "              cos task-start TASK-NNN" >&2
+  echo "  Trivial:    bash \".${COS_AGENT}/hooks/write-state.sh\" .thinking_os-gate \"CLEAR 1 <one-line why this is trivial>\"" >&2
+  # No manual .task-current escape here: stamping the marker without a board
+  # transition satisfies the hook while the card never leaves icebox.
+  exit 2
+fi
+
+# Advisory: warn if .persona is missing on COMPLICATED+ tasks.
+# Persona routing populates .persona when the task starts; absence means the task
+# was started before M.4 or the persona resolver failed silently.
+if [[ ! -f "${COS_AGENT_DIR}/.persona" ]]; then
+  GATE_CLASSIFICATION=$(echo "${STATE_VALUE:-}" | awk '{print $1}')
+  if [[ "$GATE_CLASSIFICATION" == "COMPLICATED" || "$GATE_CLASSIFICATION" == "COMPLEX" ]]; then
+    echo "Advisory: No persona marker found for this COMPLICATED/COMPLEX task." >&2
+    echo "  Re-run \`cos task-start TASK-NNN\` to trigger persona routing, or set manually:" >&2
+    echo "  echo 'senior-backend' > ${COS_AGENT_DIR}/.persona" >&2
+  fi
+fi
+
+exit 0

core/hooks/enforce-task-transition.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# enforce-task-transition.sh — PreToolUse Write|Edit.
+#
+# BLOCKS hand-edits that mutate a task STATUS transition
+# (status: / **Status:** / checkbox [ ]->[x]) on docs/tasks/**/*.md.
+# Status transitions must route through cos_task_move / cos task-done so the
+# board DB, WIP caps, and DoD gates stay consistent; a raw Edit bypasses all
+# of them.
+#
+# Allow-list: governance/docs-update/template-update active task, or
+# COS_ALLOW_TASK_EDIT=1. Fail-closed when the detection helper is missing
+# (COS_ALLOW_TASK_EDIT=1 escapes).
+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-task-transition" "entry" 2>/dev/null || true
+
+# One-shot override (rare, legitimate large refactors of a task doc).
+[[ "${COS_ALLOW_TASK_EDIT:-}" == "1" ]] && exit 0
+
+# Fail-closed: a status-transition guard (Rule 25 trust boundary) that cannot
+# read the edit must DENY (observability-eye I8). The override above bypasses it.
+cos_require_parser enforce-task-transition
+
+payload="$(cos_read_stdin_bounded 5)"
+
+file_path="$(printf '%s' "$payload" | cos_json_field tool_input.file_path)"
+
+# Scope: only task markdown under docs/tasks/.
+if [[ -z "$file_path" ]] || [[ "$file_path" != *"docs/tasks/"*.md ]]; then
+    exit 0
+fi
+
+# Governance allow-list — panel-scoped, session+freshness aware.
+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}/.task-current" 28800 2>/dev/null || true
+    case "${STATE_VALUE:-}" in
+        *governance*|*docs-update*|*template-update*) exit 0 ;;
+    esac
+fi
+
+# Mutation detection — delegate to helper (Rule 8: no python heredoc).
+# Resolve the physical hooks dir through the .claude/hooks symlink.
+_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/detect_status_transition.py"
+if [[ ! -f "$HELPER" ]]; then
+  # Fail-CLOSED: cannot tell a status hand-edit from a body edit without the
+  # helper, so deny the task-md write rather than let a forged status through
+  # (Rule 25 / observability-eye I8/A2). Escape: COS_ALLOW_TASK_EDIT=1.
+  cos_say error hook.enforce_task_transition "detect_status_transition helper missing — failing closed on task-md edit" 2>/dev/null || true
+  cos_log_hook "enforce-task-transition" "block" "rule=helper-missing" 2>/dev/null || true
+  echo "BLOCKED: enforce-task-transition helper missing ($HELPER) — cannot verify this task edit; failing closed." >&2
+  echo "  Restore src/core/hooks/_helpers/detect_status_transition.py, or set COS_ALLOW_TASK_EDIT=1 for a one-shot bypass." >&2
+  exit 2
+fi
+
+if HELPER_OUT=$(python3 "$HELPER" "$payload" 2>&1); then
+    exit_code=0
+else
+    exit_code=$?
+    # WHY first (the helper's own message already leads with BLOCKED); one BLOCKED line.
+    echo "WHY: cognitive state lives in the board DB + docs/tasks/ — a raw status edit desyncs them; use cos_task_move / cos task-done." >&2
+    printf '%s\n' "$HELPER_OUT" >&2
+fi
+cos_log_hook "enforce-task-transition" "$([[ $exit_code -eq 0 ]] && echo allow || echo block)" 2>/dev/null || true
+exit "$exit_code"

core/hooks/enforce-template.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# PreToolUse hook: Enforce template usage for structured doc creation.
+#
+# Four classes of markdown files have canonical creation flows:
+#   docs/tasks/TASK-*.md          → `cos task-create --title "..." --swimlane <lane> --kind <kind>`
+#   docs/architecture/adr/ADR-*.md → copy docs/governance/_templates/adr-template.md
+#   docs/prd/NN-*.md              → `cos setup --mode ...`
+#   docs/insights/*.md             → cos_learn_narrative MCP tool
+#
+# This hook BLOCKS raw Write on those paths and redirects to the right
+# tool. It runs only on Write (not Edit) and only when the target does
+# not already exist — so fixing an existing task file is still free.
+#
+# Escape hatch: set $COS_AGENT_DIR/.template-override (any content) to
+# allow a one-time raw write. Useful for scaffold regeneration.
+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 "")
+
+# Only enforce on Write (true creation). Edit implies the file exists.
+if [[ "$TOOL" != "Write" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# Not a markdown file → nothing to enforce here.
+[[ "$FILE_PATH" != *.md ]] && exit 0
+
+# If the target file already exists, treat as edit → allow.
+[[ -f "$FILE_PATH" ]] && exit 0
+
+# Skip obvious internal / test paths.
+case "$FILE_PATH" in
+  */.coding-os/*|*/.claude/*|*/.codex/*|*/tests/*|*/golden/*|*/node_modules/*|*/.git/*)
+    exit 0 ;;
+esac
+
+COS_STATE_DIR="${COS_STATE_DIR:-.coding-os}"
+
+# Formula-agents that write docs (architect/documenter) produce
+# structured output by design — skip template gate when a role dispatch is active.
+ACTIVE_FORMULA_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.active-formula"  # panel-first: written to + cleared from the panel dir
+if [[ -f "$ACTIVE_FORMULA_FILE" ]]; then
+  ACTIVE_FORMULA=$(cat "$ACTIVE_FORMULA_FILE" 2>/dev/null || echo "")
+  # architect creates ADRs; documenter creates task/PRD/breakthrough docs.
+  # Both operate within structured output contracts — no template re-enforcement needed.
+  if [[ -n "$ACTIVE_FORMULA" ]]; then
+    exit 0
+  fi
+fi
+
+# One-shot escape hatch for tooling (scaffold writers, migration scripts).
+# Unified registry preferred; legacy $COS_AGENT_DIR/.template-override still honoured.
+if cos_one_shot_override template 2>/dev/null; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+
+# ── Task detail files ────────────────────────────────────────────────
+# docs/tasks/TASK-###-slug.md  — must go through the Scrumban CLI so the
+# lean L-format template is applied and the task is synced to the DB.
+if [[ "$FILE_PATH" == *docs/tasks/TASK-*.md ]]; then
+  echo "BLOCKED: do not hand-write task files." >&2
+  echo "  File:     $FILE_PATH" >&2
+  echo "  Use the Scrumban CLI instead:" >&2
+  echo "    cos task-create --title \"...\" --swimlane <domain> --kind <type>" >&2
+  echo "  This applies the lean L-format template, validates frontmatter," >&2
+  echo "  and syncs the task into the project DB in one call." >&2
+  echo "  (Override for one write: touch $COS_AGENT_DIR/.template-override)" >&2
+  exit 2
+fi
+
+# ── ADR files ────────────────────────────────────────────────────────
+# docs/architecture/adr/ADR-###-slug.md — if the project ships an ADR
+# template, require copying it; otherwise print the expected structure.
+if [[ "$FILE_PATH" == *docs/architecture/adr/ADR-*.md ]]; then
+  # Walk up from the ADR path to find docs/
+  DOCS_ROOT="$(dirname "$(dirname "$(dirname "$FILE_PATH")")")"
+  TEMPLATE="$DOCS_ROOT/governance/_templates/adr-template.md"
+  if [[ -f "$TEMPLATE" ]]; then
+    echo "BLOCKED: use the ADR template." >&2
+    echo "  Template: $TEMPLATE" >&2
+    echo "  Copy its structure into $FILE_PATH, keep H2 sections intact." >&2
+    echo "  (Override for one write: touch $COS_AGENT_DIR/.template-override)" >&2
+    exit 2
+  fi
+  # No template file yet → soft reminder, allow write.
+  echo "[template] Creating an ADR without a template file." >&2
+  echo "  Required H2 sections: ## Status · ## Context · ## Decision · ## Consequences · ## Alternatives considered" >&2
+  echo "  Consider adding $TEMPLATE for future ADRs." >&2
+  exit 0
+fi
+
+# ── PRD files ────────────────────────────────────────────────────────
+# docs/prd/NN-*.md — the cos setup command owns this bootstrap.
+if [[ "$FILE_PATH" =~ docs/prd/[0-9]+.*\.md$ ]]; then
+  echo "BLOCKED: PRD files should be bootstrapped via \`cos setup\`." >&2
+  echo "  File: $FILE_PATH" >&2
+  echo "  Use one of:" >&2
+  echo "    cos setup --mode interactive                    # 4-question wizard" >&2
+  echo "    cos setup --mode import-prd --source <path>     # split an existing PRD" >&2
+  echo "  The classifier routes sections to the right numbered file." >&2
+  echo "  (Override for one write: touch $COS_AGENT_DIR/.template-override)" >&2
+  exit 2
+fi
+
+# ── Insight files ────────────────────────────────────────────────────
+# docs/insights/*.md — auto-filed by cos_learn_narrative. Only the
+# scaffold 00-index.md is hand-written.
+if [[ "$FILE_PATH" == *docs/insights/*.md ]]; then
+  if [[ "$BASENAME" == "00-index.md" ]]; then
+    exit 0
+  fi
+  echo "BLOCKED: insight files are filed back by the MCP tool." >&2
+  echo "  File: $FILE_PATH" >&2
+  echo "  Call cos_learn_narrative with task_id, what_failed, what_worked, key_insight." >&2
+  echo "  The tool writes the markdown + the outcome_history DB row atomically." >&2
+  echo "  (Override for one write: touch $COS_AGENT_DIR/.template-override)" >&2
+  exit 2
+fi
+
+# Freeform .md paths (playbooks, engineering rules, ad-hoc notes) are allowed,
+# but a NEW docs/*.md should carry the SSOT front-matter header. WARN (never
+# block) at write time so the author sees the doc-cheat-sheet contract early —
+# the CI `docs-lint --changed` strict step is the hard gate. TASK-127.
+case "$FILE_PATH" in
+  */docs/tasks/*) ;;  # task files have their own template flow above
+  *docs/*.md)
+    CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null || echo "")
+    FIRST_LINE=$(printf '%s\n' "$CONTENT" | head -1)
+    if ! printf '%s' "$FIRST_LINE" | grep -qE '^<!-- domain:[A-Z_]+ \| layer:[a-z]+ \| ssot:(true|ref|false)'; then
+      echo "warning: new doc $FILE_PATH is missing the SSOT front-matter header" >&2
+      echo "  line 1 should be: <!-- domain:X | layer:Y | ssot:true|ref|false | updated:YYYY-MM-DD -->" >&2
+      echo "  see docs/governance/docs-system.md (doc-cheat-sheet). Advisory — not blocking." >&2
+    fi
+    ;;
+esac
+exit 0

core/hooks/enforce-verify.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# PreToolUse hook: BLOCK task-done commands unless domain-appropriate
+# verification has been run recently.
+#
+# data-driven via src/core/board_os/verify-suites.yaml.
+# No more hardcoded customer paths (frontend/app/*/checkout/* etc.).
+# Consumer projects extend by writing their own
+# .coding-os/verify-suites.yaml.
+#
+# Catches all three "complete this task" entry points:
+#   make task-done … · cos task-done … · cos task-move … --to complete
+#
+# Override (audited): COS_VERIFY_OVERRIDE=1 COS_OVERRIDE_REASON="...≥15 chars"
+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 gate only fires on task-completion commands (task-done /
+# task-move --to complete). If the raw payload mentions neither there is
+# nothing to gate — bail before any jq spawn (fires on EVERY Bash command).
+case "$INPUT" in
+  *task-done*|*task-move*) ;;
+  *) exit 0 ;;
+esac
+
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+if [[ "$TOOL" != "Bash" ]]; then
+  exit 0
+fi
+
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+
+# Match only commands that ACTUALLY run task-done — anchor on the start
+# of a logical command (^ or after `&&`/`;`/`|`/`(`) so the regex does not
+# fire on commit messages or scripts that mention these strings as text.
+# Three forms: `make task-done…`, `cos task-done…`, `cos task-move … --to complete`.
+FIRST_TOKEN_OF_EACH=$(echo "$COMMAND" | tr ';&|()' '\n' | awk '{$1=$1};1' | grep -v '^$' | head -20)
+IS_TASK_DONE=false
+while IFS= read -r segment; do
+  # TASK-335: strip leading VAR=val assignments so an inline override prefix
+  # (`COS_VERIFY_OVERRIDE=1 cos task-done …`) is still recognized as task-done
+  # and the override gets EVALUATED — not silently skipped past the gate.
+  while [[ "$segment" == *" "* ]]; do
+    _first="${segment%% *}"
+    if [[ "$_first" =~ ^[A-Za-z_][A-Za-z0-9_]*= ]]; then
+      segment="${segment#* }"
+    else
+      break
+    fi
+  done
+  case "$segment" in
+    "make "*"task-done"*)              IS_TASK_DONE=true ;;
+    "cos task-done"*)                  IS_TASK_DONE=true ;;
+    "cos task-move"*"--to complete"*)  IS_TASK_DONE=true ;;
+    "cos task-move"*"--to=complete"*)  IS_TASK_DONE=true ;;
+  esac
+done < <(printf '%s\n' "$FIRST_TOKEN_OF_EACH")  # process-sub, not <<<: consistent heredoc-deadlock-safe loop form
+
+if ! $IS_TASK_DONE; then
+  # Silent skip — logging [fire] for every Bash floods .hooks.log with
+  # noise the operator cannot act on. The hook only matters when the
+  # command IS task-done; non-matches are uninteresting.
+  exit 0
+fi
+
+cos_log_hook enforce-verify fire "tool=Bash task_done=true"
+
+# TASK-335: inline override assignments live in the command STRING, never in
+# this hook's environment — surface them to the CLI so the audited override
+# path actually evaluates instead of blocking a legitimate use.
+if [[ "$COMMAND" == *"COS_VERIFY_OVERRIDE=1"* ]]; then
+  export COS_VERIFY_OVERRIDE=1
+fi
+if [[ -z "${COS_OVERRIDE_REASON:-}" ]]; then
+  _inline_reason=$(echo "$COMMAND" | { grep -oE "COS_OVERRIDE_REASON=('[^']*'|\"[^\"]*\")" || true; } | head -1 | sed -E "s/^COS_OVERRIDE_REASON=//; s/^['\"]//; s/['\"]$//")
+  if [[ -n "$_inline_reason" ]]; then
+    export COS_OVERRIDE_REASON="$_inline_reason"
+  fi
+fi
+
+# ── Resolve required suites via Python (data-driven) ────────────────
+PROJECT_ROOT="${COS_PROJECT_ROOT:-$(pwd)}"
+cd "$PROJECT_ROOT" || exit 0
+
+CHANGED_FILES=$(git diff --name-only HEAD 2>/dev/null || true)
+if [[ -z "$CHANGED_FILES" ]]; then
+  exit 0
+fi
+
+if command -v uv >/dev/null 2>&1; then
+  PYRUN=(uv run --quiet python)
+else
+  PYRUN=(python3)
+fi
+
+# Resolve suites + check freshness in one Python call so we avoid the
+# per-suite subprocess thrash the legacy script had. The CLI prints
+# either "OK" or a multi-line block report on stderr.
+set +e
+echo "$CHANGED_FILES" | "${PYRUN[@]}" -m core.board_os.verify_suites_cli check \
+  --verify-file "${COS_STATE_DIR}/.last-verify.json"
+EXIT_CODE=$?
+set -e
+
+cos_log_hook enforce-verify "$([[ $EXIT_CODE -eq 0 ]] && echo allow || echo block)" \
+  "reason=domain-suites" 2>/dev/null || true
+exit "$EXIT_CODE"

core/hooks/enforce-wip-limit.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# PreToolUse: before transition to in_progress/emergency
+# Checks current WIP count against cap from scrumban-config.yaml.
+# Blocks if cap exceeded; env COS_WIP_OVERRIDE=1 bypasses.
+
+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-wip-limit" "entry" 2>/dev/null || true
+
+# WIP check runs through the same workflow.transition() path that MCP
+# calls — bash-level hook is a belt-and-suspenders layer for the case
+# where a task file is edited directly (bypassing cos_task_move).
+# If board_os + config are unavailable, fail-soft.
+
+payload="$(cos_read_stdin_bounded 5)"
+file_path="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")"
+
+if [[ "$file_path" != *"docs/tasks/"*.md ]]; then
+    exit 0
+fi
+
+# bash 5.3.9 deadlocks `python3 - <<HEREDOC`; helper file is the safe form.
+_src="${BASH_SOURCE[0]}"
+while [ -L "$_src" ]; do
+  _dir="$(cd -P "$(dirname "$_src")" && pwd)"
+  _src="$(readlink "$_src")"
+  [[ "$_src" != /* ]] && _src="$_dir/$_src"
+done
+HSRC="$(cd -P "$(dirname "$_src")" && pwd)"
+unset _src _dir
+HELPER="${HSRC}/_helpers/wip_limit_check.py"
+if [[ -f "$HELPER" ]]; then
+  python3 "$HELPER" "$payload"
+else
+  exit 0
+fi
+
+exit_code=$?
+cos_log_hook "enforce-wip-limit" "$([[ $exit_code -eq 0 ]] && echo allow || echo block)" 2>/dev/null || true
+exit $exit_code

core/hooks/enforce-zoom.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# PreToolUse hook: BLOCK Write/Edit on code files for COMPLICATED/COMPLEX tasks
+# unless a Zoom checkpoint (Problem Framing) has been recorded.
+# Session-scoped: only accepts checkpoints from the CURRENT session.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+
+INPUT="$(cos_read_stdin_bounded 2)"
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+if [[ "$TOOL" != "Write" && "$TOOL" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+
+# Only enforce for code files
+if [[ "$FILE_PATH" != *.py ]] && [[ "$FILE_PATH" != *.ts ]] && [[ "$FILE_PATH" != *.tsx ]]; then
+  exit 0
+fi
+
+# Skip test files, migrations, generated files, config files, hook scripts
+if [[ "$FILE_PATH" == *test* ]] || [[ "$FILE_PATH" == *spec* ]] || [[ "$FILE_PATH" == *migrations* ]] || [[ "$FILE_PATH" == *node_modules* ]] || [[ "$FILE_PATH" == *__pycache__* ]] || [[ "$FILE_PATH" == *.claude/* ]] || [[ "$FILE_PATH" == *.codex/* ]] || [[ "$FILE_PATH" == *.coding-os/* ]]; then
+  exit 0
+fi
+
+# Persona-aware skip — see classify-task-mode.sh + docs/engineering/task-mode-matrix.md
+MODE_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.task-mode"  # panel-first
+[[ -f "$MODE_FILE" ]] || MODE_FILE="${COS_AGENT_DIR}/.task-mode"
+if [[ -f "$MODE_FILE" ]]; then
+  TASK_MODE=$(tr -d '\n\r' < "$MODE_FILE" 2>/dev/null | head -c 24)
+  case "$TASK_MODE" in
+    query|adhoc|chore|system) exit 0 ;;
+  esac
+fi
+
+# Panel-first: these are per-panel markers written by
+# write-state.sh to $COS_PANEL_DIR; reading $COS_AGENT_DIR missed them and
+# blocked COMPLEX edits. Mirror the other gate readers (thinking_os-gate.sh,
+# enforce-task-start.sh, enforce-skill.sh).
+GATE_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.thinking_os-gate"
+ZOOM_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.zoom-checkpoint"
+
+# Only enforce for COMPLICATED and COMPLEX
+source "$(dirname "$0")/check-state.sh"
+check_state "$GATE_FILE" 7200
+
+if [[ "$STATE_VALID" != "true" ]]; then
+  exit 0  # No gate = thinking_os-gate.sh will handle it
+fi
+
+CLASSIFICATION=$(echo "$STATE_VALUE" | awk '{print $1}')
+
+if [[ "$CLASSIFICATION" == "CLEAR" ]] || [[ "$CLASSIFICATION" == "CHAOTIC" ]]; then
+  exit 0
+fi
+
+# COMPLICATED or COMPLEX: require zoom checkpoint (session-scoped)
+check_state "$ZOOM_FILE" 7200
+
+if [[ "$STATE_VALID" != "true" ]]; then
+  echo "BLOCKED: Task classified as $CLASSIFICATION but no Plan checkpoint for this session." >&2
+  echo "Reason: $STATE_REASON" >&2
+  echo "Record checkpoint: bash \".${COS_AGENT}/hooks/write-state.sh\" .zoom-checkpoint \"PROBLEM_FRAMED\"" >&2
+  exit 2
+fi
+
+exit 0

core/hooks/ensure-hub-up.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# SessionStart hook: ensure the global coding-os Hub daemon is up.
+#
+# Rationale: the Hub (cos hub on port 9188) is the single web entry point
+# that lists every registered project and serves board/graph/search/
+# cognition for each one.  Without it, a user who opens localhost:9188
+# in the browser sees a connection refused — but we do not want to force
+# autostart on privacy/battery-conscious users.
+#
+# Policy:
+#   - Runs only if .coding-os.yaml has `hub.enabled: true` (default true).
+#   - If already reachable → silent exit.
+#   - If down → start it in the background (`cos hub start`).  Never blocks.
+#   - Never forces the human to keep the daemon running; `cos hub stop` +
+#     `hub.enabled: false` opts out.
+set -euo pipefail
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$HOOK_DIR/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then
+  cos_log_hook() { :; }
+fi
+
+PROJECT_ROOT="$(cd "$HOOK_DIR/../.." && pwd)"
+CONFIG="$PROJECT_ROOT/.coding-os.yaml"
+HUB_PORT="${COS_HUB_PORT:-9188}"
+
+cos_log_hook ensure-hub-up fire
+
+# ── Policy check: hub.enabled must be true (default true if not set).
+if [[ -f "$CONFIG" ]]; then
+  DISABLED=$(python3 -c '
+import sys
+try:
+    import yaml
+except Exception:
+    sys.exit(0)
+try:
+    data = yaml.safe_load(open(sys.argv[1], encoding="utf-8")) or {}
+except Exception:
+    sys.exit(0)
+hub = (data.get("hub") or {})
+# Treat missing key as enabled=true.
+print("1" if hub.get("enabled", True) is False else "0")
+' "$CONFIG" 2>/dev/null || echo "0")
+  if [[ "$DISABLED" == "1" ]]; then
+    cos_log_hook ensure-hub-up skip "reason=hub_disabled"
+    exit 0
+  fi
+fi
+
+# ── Probe: is something already answering on 127.0.0.1:$HUB_PORT ?
+if curl -fsS --max-time 0.5 "http://127.0.0.1:${HUB_PORT}/health" >/dev/null 2>&1; then
+  cos_log_hook ensure-hub-up ok "reason=already_up"
+  exit 0
+fi
+
+# ── Start detached.  `cos hub start` itself spawns with start_new_session.
+if command -v cos >/dev/null 2>&1; then
+  (cos hub start --port "$HUB_PORT" >/dev/null 2>&1 &) || true
+  cos_log_hook ensure-hub-up warn "action=started_background port=${HUB_PORT}"
+  echo "[coding-os] Hub starting on http://127.0.0.1:${HUB_PORT} (background)"
+else
+  cos_log_hook ensure-hub-up skip "reason=cos_not_on_path"
+fi
+
+exit 0

core/hooks/inject-mcp-caller-session.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# inject-mcp-caller-session.sh — attribute MCP task writes to the
+# REAL calling panel under concurrent same-agent panels.
+#
+# PreToolUse hook on the attribution-critical MCP task tools. The long-lived MCP
+# server is panel-blind (ONE process for ALL panels of an agent) and otherwise
+# guesses the caller via the last-writer-wins .active-session pointer — so a task
+# moved by panel A can be stamped with panel B's session, breaking per-session
+# WIP, zombie reclaim, and banner/DB agreement. This hook reads THIS panel's
+# coding-os session from $COS_SESSION_FILE and injects it as `agent_session`
+# (resolve_agent_session treats an explicit arg as the highest-priority signal)
+# via hookSpecificOutput.updatedInput. Completes F2.
+#
+# FAIL-OPEN ALWAYS: a missing dep / unresolved session / parse error emits
+# nothing and exits 0, so the tool runs with its ORIGINAL args (status quo).
+# This hook can never block or corrupt an MCP call. Hence `set -uo pipefail`
+# WITHOUT -e: a single failed command must not abort before the final exit 0.
+set -uo 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 2>/dev/null || true)"
+[[ -z "$INPUT" ]] && exit 0
+
+# Resolve THIS panel from the stdin payload (strongest signal) before reading
+# the per-panel session file, so two sibling tabs never cross.
+cos_panel_upgrade_from_payload "$INPUT" >/dev/null 2>&1 || true
+
+# jq is required to rewrite the JSON args safely. We must NOT block the MCP
+# call (fail-open on the call), but the degradation must NOT be SILENT: without
+# injection, per-panel attribution is lost and the per-session WIP cap can
+# collapse across sibling panels. Warn once per session (debounced by a
+# persistent diagnostic marker) + log telemetry, then let the call proceed.
+if ! command -v jq >/dev/null 2>&1; then
+  _deg_marker="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.mcp-attribution-degraded"
+  if [[ ! -f "$_deg_marker" ]]; then
+    echo "warning: jq not found — MCP caller-session attribution is DISABLED; per-session WIP cap may collapse across sibling panels. Install jq to restore per-panel isolation." >&2
+    printf 'jq-missing\n' > "$_deg_marker" 2>/dev/null || true
+  fi
+  cos_log_hook inject-mcp-caller-session warn "reason=jq-missing" || true
+  exit 0
+fi
+
+SID="$(cos_current_session 2>/dev/null || true)"
+# Inject only a GENUINE coding-os session id (ses-<agent>-…). cos_current_session
+# falls back to the panel-id / ppid-hash when no session-id file exists yet;
+# injecting that as agent_session would corrupt attribution worse than the
+# status quo, so do not inject on anything that is not a real session token.
+# This is benign-normal early in a session (before the session-id file exists),
+# so it stays quiet on stderr but is logged for observability (not silent).
+if [[ "$SID" != ses-* ]]; then
+  cos_log_hook inject-mcp-caller-session skip "reason=no-session-id" || true
+  exit 0
+fi
+
+# Inject only when the caller passed NO explicit agent_session; emit updatedInput
+# only when we actually add it (jq `empty` → no stdout → no-override path).
+OUT="$(printf '%s' "$INPUT" | jq -c --arg sid "$SID" '
+  (.tool_input // {}) as $ti
+  | if (($ti.agent_session // "") | tostring | length) > 0 then empty
+    else {hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: ($ti + {agent_session: $sid})}}
+    end
+' 2>/dev/null || true)"
+
+if [[ -n "$OUT" ]]; then
+  printf '%s\n' "$OUT"
+  cos_log_hook inject-mcp-caller-session ok "sid=${SID##*-}" || true
+fi
+exit 0