coding-os 0.3.2__py3-none-any.whl

core/hooks/jit-recall.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# jit-recall.sh — PreToolUse Write|Edit just-in-time recall.
+#
+# Right before an edit, surface (1) a past friction lesson about THIS file and
+# (2) any convention-rule one-liner mapped to the path in jit-rules.tsv, so the
+# reminder lands at the moment it matters. Warn-only (exit 0, stderr), debounced
+# per (file, session) / (rule, session). Fail-open: never blocks a tool call.
+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)"
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# Debounce markers live in the .jit-nudge/ dir so session-context.sh prunes
+# them wholesale each session (same convention as .graph-nudge/ .task-nudge/).
+NUDGE_DIR="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os}}/.jit-nudge"
+[[ -d "$NUDGE_DIR" ]] || mkdir -p "$NUDGE_DIR" 2>/dev/null || true
+
+# Resolve the PHYSICAL hooks dir — consumers symlink the .sh files but not
+# sibling data/helpers, so $(dirname "$0") lands in a dir without them.
+if command -v _cos_helpers_dir >/dev/null 2>&1; then
+  HOOKS_PHYS_DIR="$(dirname "$(_cos_helpers_dir)")"
+else
+  HOOKS_PHYS_DIR="$(dirname "$0")"
+fi
+
+# Convention-rule reminders: glob<TAB>rule_id<TAB>message, once per (rule, session).
+# Globs assume a leading slash; normalize relative paths (Codex apply_patch).
+MATCH_PATH="$FILE_PATH"
+[[ "$MATCH_PATH" != /* ]] && MATCH_PATH="/$MATCH_PATH"
+RULES_MAP="$HOOKS_PHYS_DIR/jit-rules.tsv"
+if [[ -f "$RULES_MAP" ]]; then
+  while IFS=$'\t' read -r pattern rule_id message; do
+    [[ -z "$pattern" || "$pattern" == \#* || -z "$rule_id" || -z "$message" ]] && continue
+    # shellcheck disable=SC2053  # unquoted RHS is the point: pattern is a glob
+    if [[ "$MATCH_PATH" == $pattern ]]; then
+      RULE_MARKER="$NUDGE_DIR/rule-${rule_id}"
+      [[ -f "$RULE_MARKER" ]] && continue
+      : > "$RULE_MARKER" 2>/dev/null || true
+      printf 'warning: 📏 [rule] %s\n' "$message" >&2
+      cos_log_hook jit-recall rule-surfaced || true
+    fi
+  done < "$RULES_MAP"
+fi
+
+# Debounce once per (file, session) — only set the marker when we actually surface.
+FILE_HASH=$(printf '%s' "$FILE_PATH" | shasum 2>/dev/null | cut -c1-12 || echo "nohash")
+MARKER="$NUDGE_DIR/file-${FILE_HASH}"
+[[ -f "$MARKER" ]] && exit 0
+
+DB="${COS_DB_PATH:-${COS_STATE_DIR:-.coding-os}/coding-os.db}"
+[[ -f "$DB" ]] || exit 0
+
+LESSON="$(python3 "$HOOKS_PHYS_DIR/_helpers/jit_recall.py" "$DB" "$FILE_PATH" 2>/dev/null || true)"
+if [[ -n "$LESSON" ]]; then
+  : > "$MARKER" 2>/dev/null || true
+  printf 'warning: 🧠 [recall] past lesson for this file — %s\n' "$LESSON" >&2
+  cos_log_hook jit-recall warn || true
+  exit 0
+fi
+cos_log_hook jit-recall ok || true
+exit 0

core/hooks/link-commit-to-task.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# link-commit-to-task.sh (PostToolUse Bash) — after a real `git commit`, append
+# the new HEAD sha + subject to the active task's Work Log, so cos_task_history
+# surfaces the CODE commits, not just the commits that touched the task .md
+# (TASK-273). cos_task_history::_git_commits_from_worklog greps the work log for
+# 7-40 hex SHAs and links them, so recording the sha here is the whole contract.
+#
+# Fire-and-forget: dedups by sha, fail-open (exit 0) on any error, never blocks.
+# Claude-only in practice (Codex lacks reliable PostToolUse delivery; it records
+# commits via cos_work_log_append explicitly).
+set -eu  # NOT -o pipefail — tolerate soft failures.
+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 "link-commit-to-task" "entry" 2>/dev/null || true
+
+payload="$(cos_read_stdin_bounded 5)"
+
+# Fast-path: this hook fires on EVERY Bash command, so the common (non-commit)
+# case must cost a single string match, not two python3 spawns. If the raw
+# payload doesn't even mention a commit, bail before parsing.
+case "$payload" in
+    *"git commit"*) ;;
+    *) exit 0 ;;
+esac
+
+# Parse tool_name + command + the sha THIS command minted, in one spawn.
+# The sha comes from the git output line "[branch abc1234] subject" inside
+# tool_response — never from a bare rev-parse HEAD: under concurrent
+# sessions HEAD is whoever committed last, and the old HEAD read cross-
+# linked sibling sessions' commits (TASK-340 repro, 2026-06-10 15:59).
+mapfile -t _parsed < <(echo "$payload" | python3 -c '
+import json, re, sys
+try:
+    d = json.load(sys.stdin)
+    ti = d.get("tool_input", {}) or {}
+    tr = d.get("tool_response", "") or ""
+    if isinstance(tr, dict):
+        out = " ".join(str(tr.get(k, "") or "") for k in ("stdout", "output", "stderr"))
+    else:
+        out = str(tr)
+    m = re.search(r"\[[^]\n]+ ([0-9a-f]{7,40})\]", out)
+    print(d.get("tool_name", ""))
+    print((ti.get("command", "") or "").replace("\n", " "))
+    print(m.group(1) if m else "")
+except Exception:
+    print(""); print(""); print("")
+' 2>/dev/null)
+tool_name="${_parsed[0]:-}"
+command="${_parsed[1]:-}"
+sha="${_parsed[2]:-}"
+
+[[ "$tool_name" == "Bash" ]] || exit 0
+case "$command" in
+    *"git commit"*) ;;
+    *) exit 0 ;;
+esac
+# A dry-run / help invocation creates no commit — don't link the prior HEAD.
+case "$command" in
+    *--dry-run*|*--help*) exit 0 ;;
+esac
+
+# Upgrade panel resolution from the payload's session_id — env-derived
+# COS_PANEL_DIR can be a ppid-* fallback that misses this panel's state.
+cos_panel_upgrade_from_payload "$payload" 2>/dev/null || true
+
+# Resolve active task (panel-first: .task-current is per-panel) and verify
+# OWNERSHIP: write-state.sh stamps "<session-id> <value>"; a marker stamped
+# by a different session is another panel's fossil — linking to it would
+# attribute this commit to a task this session never started.
+task_current_file="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os/claude}}/.task-current"
+[[ -f "$task_current_file" ]] || exit 0
+task_line="$(head -n 1 "$task_current_file" 2>/dev/null || true)"
+owner="${task_line%% *}"
+case "$owner" in
+    ses-*|ppid-*)
+        current_session="$(cos_current_session 2>/dev/null || true)"
+        [[ -n "$current_session" && "$owner" == "$current_session" ]] || exit 0
+        ;;
+esac
+task_id="$(echo "$task_line" | grep -oE 'TASK-([A-Z][A-Z0-9]*-)?[0-9]+' | head -1 || true)"
+[[ -n "$task_id" ]] || exit 0
+
+root="${COS_PROJECT_ROOT:-$PWD}"
+if [[ -z "$sha" ]]; then
+    # Output was piped/filtered (e.g. `git commit … | tail -1`) so the
+    # "[branch sha]" line is gone. Safe fallback: the single commit minted
+    # recently — 5 min because this repo's pre/post-commit hook suite can
+    # hold the Bash call for minutes after the object lands. Two or more
+    # candidates = a sibling session is also committing — skip rather than
+    # guess (a missing link beats a wrong one).
+    mapfile -t _recent < <(git -C "$root" log --format='%h' --since='5 minutes ago' -n 2 2>/dev/null || true)
+    [[ ${#_recent[@]} -eq 1 && -n "${_recent[0]:-}" ]] || exit 0
+    sha="${_recent[0]}"
+fi
+sha="$(git -C "$root" rev-parse --short=10 "$sha" 2>/dev/null || true)"
+[[ -n "$sha" ]] || exit 0
+subject="$(git -C "$root" log -1 --format=%s "$sha" 2>/dev/null || true)"
+
+# Dedup: skip when this commit is already in the task's Work Log. Match a
+# 7-char prefix so an entry the git post-commit hook (TASK-175) wrote with a
+# shorter `--short` sha is still recognised — avoids a double link.
+task_file="$(ls "$root"/docs/tasks/"${task_id}"-*.md 2>/dev/null | head -1 || true)"
+if [[ -n "$task_file" ]] && grep -q "${sha:0:7}" "$task_file" 2>/dev/null; then
+    exit 0
+fi
+
+summary="commit ${sha} — ${subject}"
+summary="${summary:0:120}"
+
+# bash 5.3.9 deadlocks `python3 - <<HEREDOC`; reuse _helpers/work_log_append.py.
+_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
+# COS_WORKLOG_HELPER override keeps the append mechanism stubbable in tests
+# (same seam as the git post-commit body, src/scripts/_post_commit_body.sh).
+# SYNCHRONOUS on purpose: a `… &` here can die with the hook process before
+# the append lands — the "linked" log line lied while the Work Log stayed
+# empty (TASK-340). Locking lives inside the helper (fcntl — flock(1) does
+# not exist on macOS); the append costs ms and commits are infrequent.
+HELPER="${COS_WORKLOG_HELPER:-${HSRC}/_helpers/work_log_append.py}"
+linked="false"
+if [[ -f "$HELPER" ]]; then
+    if COS_PROJECT_ROOT="${COS_PROJECT_ROOT:-$PWD}" \
+        python3 "$HELPER" "$task_id" "$summary" >/dev/null 2>&1; then
+        linked="true"
+    fi
+fi
+if [[ "$linked" != "true" ]]; then
+    cos_log_hook "link-commit-to-task" "append-failed ${sha}" 2>/dev/null || true
+    exit 0
+fi
+
+cos_log_hook "link-commit-to-task" "linked ${sha}" 2>/dev/null || true
+cos_record_activity worklog "commit ${sha} ${task_id}" 2>/dev/null || true
+printf '%s' "{\"systemMessage\":\"[worklog] commit ${sha} → ${task_id}\"}"
+
+exit 0

core/hooks/lint-task.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# PostToolUse: Rule 15 — tasks are pointers, not specs.
+# Warns task bodies > 1.5k tokens; blocks > 3k tokens.
+# Token estimate: word_count * 1.3.
+
+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 "lint-task" "entry" 2>/dev/null || true
+
+payload="$(cos_read_stdin_bounded 5)"
+file_path="$(echo "$payload" | python3 -c '
+import json, sys
+try:
+    print(json.load(sys.stdin).get("tool_input", {}).get("file_path", ""))
+except Exception:
+    print("")
+' 2>/dev/null || echo "")"
+
+if [[ "$file_path" != *"docs/tasks/"*.md ]] || [[ ! -f "$file_path" ]]; then
+    exit 0
+fi
+
+# Estimate tokens = words × 1.3
+word_count=$(wc -w < "$file_path" 2>/dev/null || echo 0)
+tokens=$(( word_count * 13 / 10 ))
+
+if (( tokens >= 3000 )); then
+    echo "ERROR lint-task: $file_path is ~${tokens} tokens (cap 3000)." >&2
+    echo "  Rule 15: tasks are pointers, not specs. Link to docs; don't inline." >&2
+    exit 2
+elif (( tokens >= 1500 )); then
+    echo "WARN lint-task: $file_path is ~${tokens} tokens (soft limit 1500)." >&2
+    echo "  Consider moving content to a doc + linking (Rule 15)." >&2
+fi
+
+cos_log_hook "lint-task" "ok tokens=$tokens" 2>/dev/null || true
+exit 0

core/hooks/nudge-docs-first.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — Docs-first nudge.
+#
+# Purpose: When the user's prompt looks like a code-edit intent (refactor,
+# rename, fix bug, add feature, change function, etc.) AND the session has
+# no .doc-anchor populated yet, surface a one-line additional-context block
+# telling the agent: docs are SSOT, locate the doc first via
+# cos_doc_search / cos_doc_header before touching code.
+#
+# Closes the gap where enforce-doc-anchor.sh fires only on Write/Edit but
+# the user-prompt phase already signals intent — agents that get the nudge
+# at prompt time avoid the BLOCK at edit time.
+#
+# Debounced per session via marker file. Always exits 0.
+# Bilingual: matches both English + Persian intent patterns.
+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 "")
+
+LEN=${#PROMPT}
+if [[ "$LEN" -lt 15 ]]; then
+  exit 0
+fi
+
+# Session-scoped debounce — one nudge per session is enough.
+MARKER="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.docs-first-nudged"  # panel-first: matches session-context panel-scope clear
+if [[ -f "$MARKER" ]]; then
+  exit 0
+fi
+
+# If the doc-anchor already exists for this session, the agent has already
+# done the right thing — skip silently.
+ANCHOR="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.doc-anchor"  # panel-first: write-state routes .doc-anchor to the panel dir
+if [[ -f "$ANCHOR" ]] && [[ -s "$ANCHOR" ]]; then
+  exit 0
+fi
+
+# Skip if task-mode marker says this is a query / chore / adhoc — those
+# bypass the doc-anchor requirement anyway.
+MODE_FILE="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.task-mode"  # panel-first: .task-mode is per-panel
+if [[ -f "$MODE_FILE" ]]; then
+  MODE=$(cat "$MODE_FILE" 2>/dev/null | head -1 | tr -d '[:space:]')
+  case "$MODE" in
+    query|chore|adhoc) exit 0 ;;
+  esac
+fi
+
+# Lowercase prompt for matching.
+PL=$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+# Code-edit intent patterns (English). Conservative: only fire on
+# unambiguous mutation verbs paired with code targets. Asking a question
+# or reading code does NOT trigger.
+CODE_INTENT_RE='(\b(refactor|rename|implement|add|fix|change|modify|update|extend|patch|migrate|replace|remove|delete|introduce|wire|integrate)\b.*\b(function|method|class|module|endpoint|route|handler|component|hook|tool|test|adapter|skill|api|schema|migration|config)\b)|(\.(py|ts|tsx|go|js|jsx|rs|sh)\b)'
+
+if ! printf '%s' "$PL" | grep -qE "$CODE_INTENT_RE" 2>/dev/null; then
+  exit 0
+fi
+
+cos_log_hook nudge-docs-first fire "len=${LEN}"
+touch "$MARKER" 2>/dev/null || true
+
+CONTEXT="[docs-first] Code-edit intent detected — docs are SSOT (Rule 0 + 19). BEFORE touching code: (1) cos_doc_search \"<topic>\" or cos_doc_header(path) to locate the spec, (2) read it, (3) record the anchor: write-state.sh .doc-anchor \"<doc-path> § <section>\". Procedure: docs/governance/docs-first-protocol.md."
+
+printf '%s' "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"
+
+exit 0

core/hooks/nudge-git-mode.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — pr-mode directive injector (TASK-615).
+#
+# Config propagation is reactive: nothing tells the agent the project runs
+# pr-mode — it only finds out when block-shared-tree-edit BLOCKs its first
+# shared-tree edit, and a mid-session toggle flip changes the rails with no
+# warning. When COS_GIT_WORKFLOW=pr, inject a ONE-LINE directive (once per
+# session) so the agent starts with `cos pr open` and edits inside the
+# worktree. Trunk (default) = silent exit before any output: zero injected
+# tokens, zero behavior change. Fail-open: never blocks a prompt.
+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_GIT_WORKFLOW:-trunk}" == "pr" ]] || exit 0
+
+# Once per session — same marker family as the other nudges; the panel dir is
+# session-scoped (cleared at SessionStart) so a new session re-injects once.
+MARKER="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.git-mode-nudged"
+[[ -f "$MARKER" ]] && exit 0
+touch "$MARKER" 2>/dev/null || true
+
+CONTEXT="[pr-mode ON] This project's git workflow is pr (COS_GIT_WORKFLOW=pr): do NOT edit the shared checkout — start with 'cos pr open' (or --adhoc), work INSIDE the worktree, then 'cos pr submit' and drive CI with Skill pr-mode-driver. Direct edits/commits to the shared tree are branch-guard / block-shared-tree-edit BLOCKed. Contract: docs/playbooks/pr-workflow.md"
+
+cos_log_hook nudge-git-mode ok || true
+printf '%s' "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"
+
+exit 0

core/hooks/nudge-graph-os.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — heuristic graph_os discovery nudge.
+#
+# Purpose: Surface the right cos_graph_* tool when the prompt asks a
+# structural question (callers, blast radius, rename, contracts, trace,
+# similarity, cycles, dead-code, test-gaps, centrality, ranking) OR a
+# conceptual "how does X work / explain / what is" question. Closes the
+# dogfood gap where the agent never reaches the graph layer because no
+# other hook surfaces it — the conceptual case is the one that used to
+# fall through to silence and let the agent default to memory.
+#
+# Debounced per session via marker file. Always exits 0.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi
+
+INPUT="$(cos_read_stdin_bounded 2)"
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || echo "")
+
+LEN=${#PROMPT}
+if [[ "$LEN" -lt 15 ]]; then
+  exit 0
+fi
+
+# Per-pattern marker — different structural questions get different
+# nudges. Same pattern asked twice in one session stays silent.
+MARKER_DIR="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.graph-nudge"  # panel-first: cleared at panel scope each SessionStart
+mkdir -p "$MARKER_DIR" 2>/dev/null || true
+
+# Lowercase, whitespace-collapsed for matching.
+PL=$(printf '%s' "$PROMPT" | tr '[:upper:]' '[:lower:]')
+
+# Each pattern → recommended cos_graph_* tool. First match wins, so
+# more-specific patterns come BEFORE more-generic siblings (e.g.
+# detect_changes before impact, doctor before export).
+# English structural-question patterns (English-default pre-classifier).
+declare -a PATTERNS=(
+  # graph health / why empty / why broken — must precede generic graph words
+  "graph (is |seems |looks |went )?(empty|broken|stale|down|dead)|why .* graph|graph health:cos_graph_doctor"
+  # detect changes / pre-commit / diff impact / what did i change — before impact
+  "pre.?commit|what did i change|diff impact|since last commit|impact of (my )?change|recent change|recent commit:cos_graph_detect_changes"
+  # diff of a git range / PR review — before impact, after detect_changes
+  "diff between|compare .* (commit|branch|ref|sha)|pr review|review (the )?(pr|diff|range)|blast radius of (the )?(pr|diff):cos_graph_diff"
+  # rename — rename_plan
+  "rename|renaming|rename plan:cos_graph_rename_plan"
+  # symbol DEFINITION lookup ("defined", not "called") — before references
+  "where (is|are) .* defined|defined where|find (the )?(symbol|function|class|method)|symbol named|function named|class named:cos_graph_query"
+  # who calls / references / used by — references
+  "who calls|who uses|where (is|are) .* (called|used|referenced)|callers of|references to|used by|^references|usages|call.?sites?:cos_graph_references"
+  # blast radius / impact / what breaks — impact
+  "blast radius|impact|what breaks|what will break|downstream|upstream|affected:cos_graph_impact"
+  # circular dependencies / cycles / SCC
+  "circular (dependency|dependencies|import|imports)|dependency cycle|cyclic|import cycle|\\bscc\\b:cos_graph_cycles"
+  # dead / unused / unreferenced code
+  "dead code|unused (code|function|symbol)|unreferenced|never (called|used)|can i (delete|remove)|safe to (delete|remove):cos_graph_dead_code"
+  # test coverage gaps / untested
+  "test gap|test coverage|untested|missing tests|coverage gap|not tested|lacks tests:cos_graph_test_gap"
+  # most-connected / hub / chokepoint — centrality
+  "most connected|chokepoint|bottleneck node|hub node|central node|centrality:cos_graph_centrality"
+  # importance ranking / pagerank
+  "most important|importance ranking|pagerank|rank .* by importance|key files:cos_graph_ranking"
+  # contracts / api surface / endpoints / mcp tools
+  "api surface|all endpoints|all routes|all mcp tools|all handlers|contract surface:cos_graph_contracts"
+  # trace / data flow / execution path — before path (trace pattern is more
+  # explicit; "from X to Y" appears in both, so put trace first when the
+  # word "trace" or "execution path" or "data flow" is present)
+  "^trace |trace the |trace .* execution|execution path|data flow|how does .* flow|step.?by.?step from:cos_graph_trace"
+  # path between / shortest / how connected
+  "shortest path|path from .* to|path between|how .* connected|how .* reach:cos_graph_path"
+  # similar / duplicate / near-clone
+  "similar|near.?duplicate|clone|equivalent|like .* but:cos_graph_similar"
+  # subsystems / clusters / communities / map of
+  "subsystem|cluster|community|map of|architecture map|onboard:cos_graph_communities"
+  # context / surrounding / depend on this
+  "context around|surrounding|neighbour|neighbor|depend on this|surrounding context:cos_graph_context"
+  # entry points / where does it start
+  "entry point|where does .* start|main entry|how do users:cos_graph_entrypoints"
+  # resolve a label / path / partial id to a canonical uid
+  "canonical uid|resolve .* to .* uid|which uid|partial uid:cos_graph_resolve"
+  # diagram / mermaid / dot
+  "diagram|mermaid|dot graph|visualize:cos_graph_export"
+  # CONCEPTUAL "how does X work / explain / what is / overview" — GENERIC,
+  # placed LAST so every specific structural pattern wins first. This is the
+  # case that used to fall through to silence (and the agent defaulted to
+  # memory). Route it to free-text code search; codebase-explorer is the
+  # paired skill for end-to-end conceptual reading.
+  "how (does|do|is|are) .*(work|works|implemented|structured|organi[sz]ed)|^explain |^what is |overview of|walk me through|understand (how|the):cos_graph_search"
+)
+
+MATCHED_TOOL=""
+for entry in "${PATTERNS[@]}"; do
+  re="${entry%:*}"
+  tool="${entry##*:}"
+  if printf '%s' "$PL" | grep -qE "$re" 2>/dev/null; then
+    MATCHED_TOOL="$tool"
+    break
+  fi
+done
+
+if [[ -z "$MATCHED_TOOL" ]]; then
+  exit 0
+fi
+
+# Per-pattern debounce — silent only if THIS specific tool already
+# nudged in this session. New structural pattern → new nudge.
+PATTERN_MARKER="${MARKER_DIR}/${MATCHED_TOOL}"
+if [[ -f "$PATTERN_MARKER" ]]; then
+  exit 0
+fi
+
+cos_log_hook nudge-graph-os fire "tool=${MATCHED_TOOL} len=${LEN}"
+touch "$PATTERN_MARKER" 2>/dev/null || true
+
+CONTEXT="[graph_os nudge] Structural/conceptual code question detected — call ${MATCHED_TOOL} BEFORE Read/grep (for end-to-end conceptual reading, the codebase-explorer skill pairs with it). The graph is the code retrieval layer; one envelope (~300 tok) replaces 5–10 file reads. See docs/engineering/graph-hallucination-cures.md."
+printf '%s' "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"
+
+exit 0

core/hooks/nudge-learn-narrative.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# nudge-learn-narrative.sh (Phase O) — Stop hook (the C path).
+#
+# When a session shows REAL learning signal (a file reworked >=3x, or a
+# backtrack), nudge the agent ONCE to record a structured lesson via
+# cos_learn_narrative (→ docs/insights/ + memory) — the channel for the deep
+# engineering knowledge that auto-mining (friction/commit subjects) can't capture.
+# Signal-gated (silent on trivial sessions), debounced once per session,
+# warn-only, fail-open (Stop never blocks). Contract: docs/engineering/learning-extraction.md.
+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 nudge-learn-narrative enter || true
+
+SESSION="$(cos_current_session 2>/dev/null || echo "")"
+[[ -z "$SESSION" || "$SESSION" == "?" ]] && exit 0
+
+# Debounce once per session (per-panel marker, session-tail keyed).
+MARKER="${COS_PANEL_DIR:-${COS_AGENT_DIR:-.coding-os}}/.narrative-nudged-${SESSION##*-}"
+[[ -f "$MARKER" ]] && exit 0
+
+DB="${COS_DB_PATH:-${COS_STATE_DIR:-.coding-os}/coding-os.db}"
+[[ -f "$DB" ]] || exit 0
+
+REASON="$(python3 "$(dirname "$0")/_helpers/narrative_signal.py" "$DB" "$SESSION" 2>/dev/null || true)"
+if [[ -n "$REASON" ]]; then
+  : > "$MARKER" 2>/dev/null || true
+  printf 'warning: 🧠 [learn] This session hit real friction (%s). If you solved something non-obvious, record ONE lesson so a future session reuses it:\n' "$REASON" >&2
+  printf '  cos_learn_narrative(task_id, what_failed, what_worked, key_insight) — files to docs/insights/ + memory. Be specific (situation -> why -> rule).\n' >&2
+  cos_log_hook nudge-learn-narrative warn || true
+  exit 0
+fi
+cos_log_hook nudge-learn-narrative ok || true
+exit 0

core/hooks/nudge-model-routing.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — model-routing directive injector (TASK-319).
+#
+# When hub-settings.json::model_routing.enabled is true, inject a ONE-LINE
+# directive (once per session) telling the agent to consult cos_route_model
+# at Classify and honor it at dispatch — CLI/VSCode parity with the hub
+# chat Auto option. Toggle off = exit silently before any output: zero
+# injected tokens, zero behavior change. Fail-open: never blocks a prompt.
+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
+
+SETTINGS_FILE="${COS_STATE_DIR:-.coding-os}/hub-settings.json"
+[[ -f "$SETTINGS_FILE" ]] || exit 0
+
+ENABLED=$(jq -r '.model_routing.enabled // false' "$SETTINGS_FILE" 2>/dev/null || echo "false")
+[[ "$ENABLED" == "true" ]] || exit 0
+
+# Once per session — same marker family as the other nudges; the panel dir
+# is cleared at SessionStart so a new session re-injects exactly once.
+MARKER="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.model-routing-nudged"
+[[ -f "$MARKER" ]] && exit 0
+touch "$MARKER" 2>/dev/null || true
+
+ORCH=$(jq -r '.model_routing.orchestrator_model // ""' "$SETTINGS_FILE" 2>/dev/null || echo "")
+CONTEXT="[model-routing ON] After recording the gate (cos_classify_prompt), call cos_route_model(complexity=<gate>) and honor it at dispatch (pass model+complexity to cos_dispatch_formula_run). Cold history -> orchestrator_model '${ORCH}' (settings), else adapter default. Contract: src/core/rules/model-routing.md"
+
+cos_log_hook nudge-model-routing ok || true
+printf '%s' "{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":$(printf '%s' "$CONTEXT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}}"
+
+exit 0

core/hooks/nudge-reentry.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# nudge-reentry.sh — UserPromptSubmit hook.
+#
+# Softly reminds the agent, once per (session, open-set), when a new prompt
+# arrives while THIS session holds an in_progress task not bound to
+# .task-current. Closes the re-entry blind spot the Stop-time
+# warn-abandoned-task cannot cover — a turn that never reached Stop, or
+# .task-current drifting from the DB (common on Codex, whose MCP task-moves
+# fire no .task-current sync). Session-scoped (agent_session), so a sibling
+# session's WIP never false-triggers — the board-global banner wip= count
+# cannot make that distinction. Fail-open: emits one additionalContext line
+# and exits 0, never blocks. Debounced per (session, in_progress-set).
+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 nudge-reentry enter || true
+
+[ -f "${COS_DB_PATH:-}" ] || exit 0
+command -v sqlite3 >/dev/null 2>&1 || exit 0
+
+# Upgrade panel id from the payload so $COS_SESSION_FILE / $COS_PANEL_DIR
+# resolve THIS panel; fall back to stdin session_id then legacy agent-dir.
+INPUT="$(cos_read_stdin_bounded 2 2>/dev/null || true)"
+command -v cos_panel_upgrade_from_payload >/dev/null 2>&1 && cos_panel_upgrade_from_payload "$INPUT" 2>/dev/null || true
+SESSION_ID="$(cat "${COS_SESSION_FILE:-}" 2>/dev/null || true)"
+if [ -z "$SESSION_ID" ] && [ -n "$INPUT" ] && command -v jq >/dev/null 2>&1; then
+  SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // .sessionId // empty' 2>/dev/null || true)
+fi
+if [ -z "$SESSION_ID" ] && [ -f "${COS_AGENT_DIR}/session-id" ]; then
+  SESSION_ID=$(cat "${COS_AGENT_DIR}/session-id" 2>/dev/null || true)
+fi
+[ -n "$SESSION_ID" ] || exit 0
+# Session-id is alnum + dash only; reject anything else before it reaches SQL.
+case "$SESSION_ID" in
+  *[!A-Za-z0-9-]*) exit 0 ;;
+esac
+
+# in_progress tasks owned by THIS session. `testing` is excluded — it is a
+# legitimate parked state (verification running) that .task-current may not
+# point at, so only actively-owned in_progress work counts as "unbound".
+OPEN="$(sqlite3 "$COS_DB_PATH" \
+  "SELECT group_concat(task_id, ',') FROM tasks
+   WHERE status = 'in_progress' AND agent_session = '$SESSION_ID';" \
+  2>/dev/null || true)"
+[ -n "$OPEN" ] || exit 0
+
+# Bound task marker (panel-first, matching session-context's TASK_CUR read).
+# write-state.sh prefixes a session id ("<sid> <task>"), so take the LAST
+# whitespace field — a raw cat|head -c 32 only ever saw the 31-char sid and
+# made this bound-check dead code in production.
+TASK_CUR="$(awk '{print $NF}' "${COS_PANEL_DIR:-$COS_AGENT_DIR}/.task-current" 2>/dev/null | head -1 || true)"
+[ -n "$TASK_CUR" ] || TASK_CUR="$(awk '{print $NF}' "${COS_AGENT_DIR}/.task-current" 2>/dev/null | head -1 || true)"
+TASK_CUR="$(printf '%s' "$TASK_CUR" | tr -d '\n\r' | head -c 32)"
+
+# Bound iff .task-current names one of the session's in_progress tasks. When it
+# does, the agent is correctly re-entered — stay silent.
+case ",$OPEN," in
+  *",$TASK_CUR,"*) [ -n "$TASK_CUR" ] && exit 0 ;;
+esac
+
+# A task bound in a LIVE sibling panel is actively driven there — drop it from
+# this panel's nudge set. Two panels can share one session id (resumed
+# conversation mirrors the agent-level id), and nudging the idle one about its
+# sibling's live work invited the "rescue" parks recorded as phantom
+# NULL-reason in_progress→icebox reverts. Real strands still nudge.
+if command -v cos_task_bound_in_live_sibling >/dev/null 2>&1; then
+  KEEP=""
+  OLDIFS=$IFS; IFS=','
+  for t in $OPEN; do
+    [ -n "$t" ] || continue
+    if cos_task_bound_in_live_sibling "$t"; then continue; fi
+    KEEP="${KEEP:+$KEEP,}$t"
+  done
+  IFS=$OLDIFS
+  OPEN="$KEEP"
+  if [ -z "$OPEN" ]; then
+    cos_log_hook nudge-reentry skip "reason=sibling_bound" || true
+    exit 0
+  fi
+fi
+
+# Debounce keyed on (session, open-set), not session alone — so the nudge
+# re-arms when the in_progress set changes but an unchanged mismatch stays
+# quiet (no alarm fatigue). Panel-first marker matches session-context scope.
+MARKER="${COS_PANEL_DIR:-$COS_AGENT_DIR}/.reentry-nudged"
+OPEN_SIG=$(printf '%s' "$OPEN" | cksum | cut -d' ' -f1)
+DEBOUNCE_KEY="${SESSION_ID}:${OPEN_SIG}"
+if [ -f "$MARKER" ] && grep -qF "$DEBOUNCE_KEY" "$MARKER" 2>/dev/null; then
+  exit 0
+fi
+echo "$DEBOUNCE_KEY" >> "$MARKER"
+
+cos_log_hook nudge-reentry warn || true
+MSG="[board] This session holds in_progress task(s) not bound to .task-current: ${OPEN}. Re-bind with \`cos task-start ${OPEN%%,*}\` (or park via \`cos task-move --to blocked --reason '<why>'\`) so the pulse, work-log capture, and DoD gate track the right task. Never park work you did not start this conversation."
+printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":%s}}\n' \
+  "$(printf '%s' "$MSG" | jq -R -s '.')"
+
+cos_log_hook nudge-reentry ok || true
+exit 0