coding-os 0.3.2__py3-none-any.whl

core/hooks/registry.yaml

@@ -0,0 +1,1262 @@
+# Hook Registry — SSOT for hook registration metadata.
+#
+# Each hook is declared ONCE here. src/cli/hook_renderer.py reads this file
+# and produces adapter-specific settings files:
+#   src/adapters/claude/settings.template.json  (rendered)
+#   src/adapters/codex/hooks.template.json      (rendered)
+#
+# Adding a hook:
+#   1. Drop the script in src/core/hooks/<name>.sh
+#   2. Append an entry here (fields below)
+#   3. Run: make regen-adapter-templates
+#   4. Run: make dogfood-full  (re-install adapters in this repo)
+#
+# Hook fields:
+#   id            — logical name (= script basename without .sh)
+#   script        — filename in src/core/hooks/
+#   description   — one-line purpose (shown in `cos hooks-list`)
+#   category      — safety | enforcement | observability | reminder | meta
+#   phase         — development phase when added (0 | E | F | G | ...)
+#   timeout       — SECONDS (Claude Code / Codex contract); omit if none.
+#                   Verified empirically 2026-05-19 against
+#                   `Slow PreToolUse hooks: 1500057ms` log line that
+#                   matched timeout=1500 exactly. Keep values <= 30 so
+#                   a single hung hook can't stall the agent for
+#                   minutes (or the 60s subprocess-init ceiling fires).
+#   events        — list of {event, matcher, status_message}
+#
+# Event/matcher pairs are filtered against each adapter's declared
+# capabilities in src/adapters/<agent>/adapter.yaml::capabilities. A pair
+# the adapter cannot fire is skipped in that adapter's output.
+
+version: 1
+
+hooks:
+  # ── safety ─────────────────────────────────────────────────────────
+  - id: block-secrets
+    script: block-secrets.sh
+    description: Scans command and file content for credentials (AWS keys, tokens, .env leaks).
+    category: safety
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "🔒 Scanning command for credentials..."
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🔒 Scanning file content for credentials..."
+
+  - id: block-dangerous-commands
+    script: block-dangerous-commands.sh
+    description: Blocks destructive commands (rm -rf, force-push, reset --hard) without confirmation.
+    category: safety
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "🛡️ Checking command safety (rm, force-push, reset)..."
+
+  - id: branch-guard
+    script: branch-guard.sh
+    description: Enforces trunk-based git integrity — blocks branch/worktree creation AND HEAD-rewriting ops (`reset <ref>`, `checkout/switch <other-branch>`) in trunk mode.
+    category: enforcement
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "🌳 Enforcing trunk-based workflow (no branches)..."
+
+  - id: enforce-commit-message
+    script: enforce-commit-message.sh
+    description: Enforces commit message contract — title ≤100 chars, body ≤3 non-empty lines, no Claude/Anthropic/USER/Co-Authored-By attribution, no Persian prompt quotes.
+    category: enforcement
+    phase: G
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "📝 Validating commit message contract..."
+
+  - id: inject-mcp-caller-session
+    script: inject-mcp-caller-session.sh
+    description: Injects the calling panel's coding-os session as `agent_session` into MCP task-tool args so the panel-blind MCP server attributes writes to the real caller, not the last-writer-wins .active-session pointer. Fail-open; completes F2.
+    category: task
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: mcp__coding-os__cos_task_move
+        status_message: "🪪 Attributing task move to this panel..."
+      - event: PreToolUse
+        matcher: mcp__coding-os__cos_task_create
+        status_message: "🪪 Attributing task create to this panel..."
+      - event: PreToolUse
+        matcher: mcp__coding-os__cos_work_log_append
+        status_message: "🪪 Attributing work-log to this panel..."
+
+  - id: block-uv-heredoc
+    script: block-uv-heredoc.sh
+    description: Blocks `uv run ... <<EOF` pattern (Rule #9 — silently hangs).
+    category: safety
+    phase: E
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "⚠️ Inspecting uv-run heredoc pattern (rule #9)..."
+
+  - id: block-bad-patterns
+    script: block-bad-patterns.sh
+    description: "Rejects bare `except: pass`, mock-where-real-needed, and other anti-patterns."
+    category: safety
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🚫 Checking for anti-patterns (bare except: pass, …)..."
+
+  - id: block-protected-files
+    script: block-protected-files.sh
+    description: Blocks edits to governance-protected files unless the active task is a governance task.
+    category: safety
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🔐 Checking protected governance files..."
+
+  - id: block-shared-tree-edit
+    script: block-shared-tree-edit.sh
+    description: "pr-mode only — blocks Write/Edit/MultiEdit on the shared integration checkout so every change is isolated in a worktree. Inert in trunk mode."
+    category: safety
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit|MultiEdit
+        status_message: "🌳 pr-mode: enforcing worktree edit isolation..."
+
+  - id: enforce-task-transition
+    script: enforce-task-transition.sh
+    description: |
+      Blocks hand-edits that mutate a task STATUS transition
+      (status: / **Status:** / checkbox [ ]->[x]) on docs/tasks/**/*.md.
+      Status changes must route through cos_task_move / cos task-done so the
+      board DB, WIP caps, and DoD gates stay consistent; a raw Edit bypasses
+      them. Allow-list: governance/docs-update/template-update active task,
+      or COS_ALLOW_TASK_EDIT=1.
+    category: safety
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🚦 Checking task status transition..."
+
+  - id: block-migration-conflict
+    script: block-migration-conflict.sh
+    description: Detects duplicate migration version numbers in db.py (Rule #10 — append-only migrations).
+    category: safety
+    phase: E
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🗃️ Checking migration version conflicts (rule #10)..."
+
+  - id: block-hardcoded-literals
+    script: block-hardcoded-literals.sh
+    description: Rejects hardcoded stack/adapter name literals in cli/*.py (Rule #12 — data-driven CLI).
+    category: safety
+    phase: E
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🎯 Scanning cli/*.py for hardcoded literals (rule #12)..."
+
+  # ── enforcement ────────────────────────────────────────────────────
+  - id: enforce-verify
+    script: enforce-verify.sh
+    description: Blocks `task-done` commands unless the required verification suite has recorded a recent pass.
+    category: enforcement
+    phase: "0"
+    timeout: 10
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "✅ Verifying suites before task-done..."
+
+  - id: test-governor
+    script: test-governor.sh
+    description: PreToolUse Bash — governs pytest invocations for multi-agent laptop safety (TASK-330). BLOCKs full sweeps without audited override (Rule 20), BLOCKs re-runs of a suite already green on the same tree (commit-keyed ledger, COS_TEST_FORCE=1 re-runs), and BLOCKs concurrent heavy runs via a TTL+liveness lockfile. Sweep gate fail-closed; rest fail-open. Spec at docs/engineering/test-governance.md.
+    category: enforcement
+    phase: "0"
+    timeout: 15
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "🧪 Test-governor: dedup/lock/sweep check..."
+
+  - id: record-verify-auto
+    script: record-verify-auto.sh
+    description: PostToolUse Bash — auto-records completed verify-suite commands (data-driven match against verify-suites.yaml) as PASS/FAIL with commit keys into .last-verify.json, and clears the test-run lockfile (TASK-329). Also fires on PostToolUseFailure so a failed suite records FAIL and frees the lock immediately (TASK-335). Fail-open, always exit 0.
+    category: observability
+    phase: O
+    timeout: 15
+    events:
+      - event: PostToolUse
+        matcher: Bash
+        status_message: "🧾 Recording verify-suite result..."
+      - event: PostToolUseFailure
+        matcher: ""
+        status_message: "🧾 Recording failed suite result..."
+
+  - id: enforce-template
+    script: enforce-template.sh
+    description: Requires structured task / ADR / PRD / insight documents to follow the template.
+    category: enforcement
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "📋 Checking doc templates (task / ADR / PRD / insight)..."
+
+  - id: thinking_os-gate
+    script: thinking_os-gate.sh
+    description: Requires a recorded Complexity Gate classification before code writes.
+    category: enforcement
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🧠 Verifying Complexity Gate recorded..."
+
+  - id: enforce-scaffold-boundary
+    script: enforce-scaffold-boundary.sh
+    description: TASK-163 — block Write/Edit when target path violates an installed stack's `forbids_writing_in`. Reads aggregated $COS_STATE_DIR/scaffold-boundary.yaml; fail-open when missing.
+    category: enforcement
+    phase: O
+    timeout: 10
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🚧 Checking scaffold-boundary (multi-stack subtree isolation)..."
+
+  - id: enforce-task-start
+    script: enforce-task-start.sh
+    description: Requires an active task marker so every edit is traceable.
+    category: enforcement
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "📌 Verifying active task..."
+
+  - id: enforce-doc-anchor
+    script: enforce-doc-anchor.sh
+    description: Blocks code writes without a recorded doc anchor (Rule #0 — docs-first principle).
+    category: enforcement
+    phase: E
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "📎 Verifying doc anchor (docs-first principle)..."
+
+  - id: enforce-memory-check
+    script: enforce-memory-check.sh
+    description: Requires a cos_search memory check before code writes on COMPLICATED/COMPLEX tasks.
+    category: enforcement
+    phase: F
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🔎 Verifying Memory Check (cos_search) recorded..."
+
+  - id: enforce-skill
+    script: enforce-skill.sh
+    description: Requires a domain skill to be invoked before editing stack-scoped code files.
+    category: enforcement
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🛠️ Verifying domain skill invoked..."
+
+  - id: enforce-zoom
+    script: enforce-zoom.sh
+    description: Requires a Plan checkpoint for COMPLICATED/COMPLEX tasks before code writes.
+    category: enforcement
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🔍 Verifying Plan checkpoint for COMPLICATED+..."
+
+  - id: enforce-doc-sync
+    script: enforce-doc-sync.sh
+    description: |
+      PostToolUse Write|Edit|MultiEdit — code → doc staleness scanner.
+      Closes the docs-first loop in the OTHER direction. Three signals:
+      (1) public symbol removed/renamed + doc still mentions it,
+      (2) signature changed (param count diff) on a kept symbol — catches
+      the "agent invented a non-spec'd field" case, (3) doc mtime older
+      than code AND mentions a current symbol (soft).
+      Collaborates with thinking_os FTS5 doc index (better than path-mirror
+      heuristic) + graph_os reference count when backend is up. WARN class,
+      never blocks. Helper: _helpers/doc_sync_check.py.
+    category: enforcement
+    phase: "0"
+    timeout: 30
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit|MultiEdit
+        status_message: "📚 Scanning related docs for drift..."
+
+  # ── observability ──────────────────────────────────────────────────
+  - id: capture-observation
+    script: capture-observation.sh
+    description: Fire-and-forget observation recording to thinking_os memory (PostToolUse Write|Edit|MultiEdit).
+    category: observability
+    phase: "0"
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit|MultiEdit
+        status_message: "🧠 Recording observation + embedding to memory..."
+
+  - id: auto-reindex-docs
+    script: auto-reindex-docs.sh
+    description: Incremental re-index of docs (md) AND code / config (.py/.ts/.tsx/.sh/.yaml/.go) on Write/Edit. Dispatches to the matching graph_os extractor; fire-and-forget.
+    category: retrieval
+    phase: H
+    timeout: 30
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "♻️ Re-indexing doc/code for cos_doc_search + graph_os freshness..."
+
+  - id: nudge-reuse-first
+    script: nudge-reuse-first.sh
+    description: After a Write/Edit under src/services/, nudge (non-blocking, debounced) to promote a symbol duplicated across same-language services into src/shared/<lang>/ — reuse-first placement (project-anatomy.md). Fail-open.
+    category: reminder
+    phase: H
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "♻️ Checking cross-service reuse (src/shared/ nudge)..."
+
+  - id: auto-graph-reconcile-shell
+    script: auto-graph-reconcile-shell.sh
+    description: PostToolUse Bash — single ordered reconciler (replaces auto-reindex-shell-ops + auto-prune-deleted-files). On rm/mv/cp/git/find of a tracked file it walks the touched paths once and prunes-if-gone THEN reindexes-if-present in one job, eliminating the N10 race where the two old hooks hit the graph DB in parallel; bulk ops schedule one debounced full reindex.
+    category: retrieval
+    phase: O
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Bash
+        status_message: "🔁 Reconciling graph for shell file op (prune + reindex)..."
+
+  - id: auto-regen-doc-index
+    script: auto-regen-doc-index.sh
+    description: TASK-161 freshness — regenerate the affected docs/<dir>/00-index.md from frontmatter on every Write/Edit of a docs/**/*.md file. Debounced (5s/dir), fire-and-forget; failures land in $COS_STATE_DIR/.regen-doc-index-errors.log.
+    category: retrieval
+    phase: O
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "📑 Regenerating affected docs/<dir>/00-index.md from frontmatter..."
+
+  # ── graph_os enforcement ──────────────────────────────
+  - id: enforce-graph-first-read
+    script: enforce-graph-first-read.sh
+    description: |
+      PreToolUse Read on a load-bearing meta-repo file
+      WARNS (or BLOCKS in strict) when the agent reaches for Read before
+      any cos_graph_* tool has been called this session. Reuses the same
+      enforce_context_on glob list from .coding-os/rag-config.yaml. Silent
+      if the per-file .graph-context-<sha> marker exists. Toggle via
+      COS_ENFORCE_GRAPH_FIRST=off|1|strict.
+    category: enforcement
+    phase: I
+    timeout: 10
+    events:
+      - event: PreToolUse
+        matcher: Read
+        status_message: "🧭 Checking graph-first discipline before Read..."
+
+  - id: enforce-graph-context
+    script: enforce-graph-context.sh
+    description: Warn (strict-mode = block) before editing a load-bearing file listed under `.coding-os/rag-config.yaml::graph.enforce_context_on` without a prior cos_graph_context consultation marker.
+    category: enforcement
+    phase: I
+    timeout: 10
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🧭 Verifying graph-context marker for load-bearing file..."
+
+  - id: warn-destructive-edit
+    script: warn-destructive-edit.sh
+    description: Warn (strict-mode = block) before a large net-deletion/overwrite of a load-bearing file (docs/** + graph.enforce_context_on globs); surfaces the last commit + git pull command. Fail-open, self-throttling. Spec docs/engineering/destructive-edit-guard.md.
+    category: enforcement
+    phase: I
+    timeout: 10
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit|MultiEdit
+        status_message: "🛡️ Checking for destructive deletion of load-bearing content..."
+
+  - id: warn-diff-size
+    script: warn-diff-size.sh
+    description: PreToolUse Bash — when a `git commit` is about to run, warn (never block) if the staged diff exceeds COS_DIFF_SIZE_THRESHOLD lines (default 400), nudging diff-minimal commits. Fail-open.
+    category: enforcement
+    phase: "0"
+    timeout: 10
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "📏 Checking staged diff size..."
+
+  - id: enforce-rename-plan
+    script: enforce-rename-plan.sh
+    description: Warn (strict-mode = block) when an Edit performs an identifier-rename-shaped string swap without a prior cos_graph_rename_plan marker in this session.
+    category: enforcement
+    phase: I
+    timeout: 10
+    events:
+      - event: PreToolUse
+        matcher: Edit
+        status_message: "✏️  Verifying rename-plan marker..."
+
+  - id: verify-rename-callers
+    script: verify-rename-callers.sh
+    description: PostToolUse Edit — when an Edit looks like an identifier rename, greps the repo for unreplaced callers and warns. Closes the gap left by enforce-rename-plan (which verifies plan-existence, not site-completeness). Always non-blocking.
+    category: enforcement
+    phase: O
+    timeout: 30
+    events:
+      - event: PostToolUse
+        matcher: Edit
+        status_message: "🔁 Checking for unreplaced rename callers..."
+
+  - id: search-enforce-inventory
+    script: search-enforce-inventory.sh
+    description: PreToolUse Bash — when a bulk replace (sed -i, xargs sed, python replace) is about to run, extracts the OLD pattern, stores it in session state, and emits the inventory grep command for the agent to run. Does NOT run grep itself (full-repo grep exceeds PreToolUse timeout on large codebases). Companion PostToolUse hook (search-verify-remaining) runs bounded verify grep after replace. Always non-blocking.
+    category: enforcement
+    phase: O
+    timeout: 30
+    events:
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "🔎 Running search inventory before bulk replace..."
+
+  - id: search-verify-remaining
+    script: search-verify-remaining.sh
+    description: PostToolUse Bash — after a bulk replace, reads session state from search-enforce-inventory and re-runs verify grep. Reports remaining match count vs ground truth. Warns if > 0 remain with file list. Closes the "declared done but 20 remain" gap for Bash-based replace operations. Always non-blocking.
+    category: enforcement
+    phase: O
+    timeout: 30
+    events:
+      - event: PostToolUse
+        matcher: Bash
+        status_message: "✅ Verifying 0 matches remain after replace..."
+
+  # ── board_os Scrumban ──────────────────────────────────
+  - id: validate-task-frontmatter
+    script: validate-task-frontmatter.sh
+    description: Validates lean frontmatter (swimlane/kind/epic/labels/status/priority/appetite) on task MD writes. Blocks malformed YAML or enum violations.
+    category: safety
+    phase: L
+    timeout: 30
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🧾 Validating task frontmatter..."
+
+  - id: enforce-wip-limit
+    script: enforce-wip-limit.sh
+    description: Enforces WIP caps from scrumban-config.yaml when a task transitions to in_progress/emergency. Bypass via COS_WIP_OVERRIDE=1.
+    category: safety
+    phase: L
+    timeout: 30
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🚦 Checking WIP limit before status change..."
+
+  - id: capture-work-log
+    script: capture-work-log.sh
+    description: Appends one-line Work Log entry to the active task on code Write/Edit. Fire-and-forget; flock-serialized for multi-agent safety.
+    category: observability
+    phase: L
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit|MultiEdit
+        status_message: "📝 Appending Work Log entry..."
+
+  - id: link-commit-to-task
+    script: link-commit-to-task.sh
+    description: After a real `git commit`, appends the new HEAD sha + subject to the active task's Work Log so cos_task_history links the code commits, not just commits that touched the task .md. Dedup by sha; fire-and-forget.
+    category: observability
+    phase: L
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Bash
+        status_message: "🔗 Linking commit to task..."
+
+  - id: auto-task-sync
+    script: auto-task-sync.sh
+    description: Re-syncs single task file into DB cache on Write/Edit. Fire-and-forget; keeps the board fresh within one hook latency.
+    category: retrieval
+    phase: L
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "♻️ Re-syncing task to DB..."
+
+  - id: sync-task-current
+    script: sync-task-current.sh
+    description: |
+      PostToolUse fan-out — auto-writes the per-panel .task-current marker
+      when a task transitions to in_progress via cos_task_move (MCP) or
+      `cos task-start` / `cos task-move --to in_progress` (Bash). Panel-env
+      reliable (a hook runs in the session lineage; the MCP server / cos CLI
+      subprocess resolve a stale panel). Removes the manual `write-state.sh
+      .task-current` step (TASK-059). Fire-and-forget; always exits 0.
+    category: task
+    phase: L
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: mcp__coding-os__cos_task_move
+        status_message: "📌 Syncing .task-current..."
+      - event: PostToolUse
+        matcher: Bash
+        status_message: "📌 Syncing .task-current..."
+
+  - id: advance-role
+    script: advance-role.sh
+    description: |
+      PostToolUse — advances the active role (.role) along the composed chain
+      by work phase: Write/Edit/MultiEdit → implementer/refactorer/debugger,
+      test/verify Bash → reviewer. Only ever selects a role already IN the
+      chain (never invents one). Makes the banner roles= field track what the
+      agent is DOING rather than a frozen chain lead (TASK-057 F2.3). Fail-open.
+    category: cognition
+    phase: L
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit|MultiEdit
+      - event: PostToolUse
+        matcher: Bash
+
+  - id: check-mcp-extras
+    script: check-mcp-extras.sh
+    description: SessionStart — verifies global cos binary has required Python extras (graph_os, board_os, rag). If missing, MCP crashes silently and all cos_* tools fail. Emits loud warning with exact fix command before agent uses any MCP tools. Fast (<200ms, no server start). Always non-blocking.
+    category: safety
+    phase: "0"
+    timeout: 30
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "🔌 Checking MCP extras health..."
+
+  - id: remind-daily
+    script: remind-daily.sh
+    description: On SessionStart, nags if `cos daily` hasn't run in >24h. Non-blocking banner; ADHD-friendly (no shame).
+    category: observability
+    phase: L
+    timeout: 10
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "🗓️  Checking daily check-in recency..."
+      - event: SessionStart
+        matcher: resume
+        status_message: "🗓️  Checking daily check-in recency..."
+
+  - id: ensure-hub-up
+    script: ensure-hub-up.sh
+    description: SessionStart — if .coding-os.yaml has hub.enabled (default true), probe http://127.0.0.1:9188 and start `cos hub` in the background when down.
+    category: observability
+    phase: "0"
+    timeout: 30
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "🛰️  Ensuring Coding OS Hub is up..."
+
+  - id: lint-task
+    script: lint-task.sh
+    description: Rule 15 enforcement. Warns task files >1.5k tokens, blocks >3k.
+    category: safety
+    phase: L
+    timeout: 10
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "📏 Lint task (Rule 15)..."
+
+  - id: check-doc-size
+    script: check-doc-size.sh
+    description: Soft size budget per `layer:` (index/playbook/spec/policy/reference/adr/task). Warn-only — complements lint-task with non-task layers.
+    category: reminder
+    phase: O
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "📐 Checking doc size budget..."
+
+  - id: enforce-task-body
+    script: enforce-task-body.sh
+    description: DoR/DoD validator. Blocks transitions to in_progress/complete when task body fails the kind's rules. SSOT in src/core/board_os/transition-gates.yaml.
+    category: enforcement
+    phase: L
+    timeout: 30
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🚦 Validating transition gates (DoR/DoD)..."
+
+  - id: track-skill
+    script: track-skill.sh
+    description: Tracks which skills have been invoked this session.
+    category: observability
+    phase: "0"
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: Skill
+        status_message: "🛠️ Tracking skill invocation..."
+
+  - id: pr-reap
+    script: pr-reap.sh
+    description: "pr-mode only — SessionStart orphan reaper: GC worktrees/branches/PRs of presence-offline sessions; drain the cleanup ledger. Inert in trunk."
+    category: safety
+    phase: "0"
+    timeout: 10
+    events:
+      - event: SessionStart
+        matcher: startup|resume
+        status_message: "🌳 pr-mode: reaping orphaned worktrees..."
+
+  - id: session-context
+    script: session-context.sh
+    description: Loads session context + memory digest on session start / compact / resume.
+    category: observability
+    phase: "0"
+    timeout: 30
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "🚀 Loading session context + memory digest..."
+      - event: SessionStart
+        matcher: compact|resume
+        status_message: "🔄 Recovering workflow context + memory digest..."
+      - event: UserPromptSubmit
+        matcher: ""
+        status_message: "🔄 Checking workflow state..."
+
+  - id: session-end
+    script: session-end.sh
+    description: |
+      Stop hook — fires at end-of-turn (NOT end-of-conversation). Claude Code
+      emits `Stop` after each agent turn, so the same session_id persists
+      across many `session-end` invocations. The hook writes per-turn
+      summary + memory enrichment; idempotent UPSERT on session_summaries.
+      "session" in the hook name refers to the agent loop session-id, which
+      is rotated only on a fresh `SessionStart startup` (see
+      session-context.sh for rotation logic).
+    category: observability
+    phase: "0"
+    timeout: 30
+    events:
+      - event: Stop
+        matcher: ""
+        status_message: "📝 Writing turn summary + enrichment to memory..."
+
+  - id: warn-abandoned-task
+    script: warn-abandoned-task.sh
+    description: |
+      Stop hook — warns once per session when a task this session moved
+      to in_progress is still in_progress at turn-end. Catches the
+      "agent started a task but never moved it to testing/complete"
+      abandonment pattern. Fail-open: nudges via Stop additionalContext,
+      never blocks. Debounced per session-id via .abandoned-task-warned.
+    category: observability
+    phase: "0"
+    timeout: 5
+    events:
+      - event: Stop
+        matcher: ""
+        status_message: "🩹 Checking for tasks left in_progress..."
+
+  - id: nudge-reentry
+    script: nudge-reentry.sh
+    description: |
+      UserPromptSubmit twin of warn-abandoned-task — softly reminds once per
+      (session, open-set) when this session holds an in_progress task not bound
+      to .task-current. Closes the re-entry blind spot the Stop-time hook 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, so a sibling session's WIP never false-triggers. Fail-open:
+      nudges via UserPromptSubmit additionalContext, never blocks. Debounced per
+      (session, in_progress-set) via .reentry-nudged.
+    category: observability
+    phase: O
+    timeout: 5
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+
+  - id: drain-embedding-outbox
+    script: drain-embedding-outbox.sh
+    description: |
+      Stop hook — drains the embedding_outbox (Wave 4) off the interactive
+      path. The capture hot-path enqueues instead of embedding (so an Edit is
+      never blocked by a model load); this hook embeds the backlog at turn-end.
+      Fail-open, never blocks; the helper fast-paths out with zero model load
+      when the outbox is empty (the common case).
+    category: retrieval
+    phase: "0"
+    timeout: 60
+    events:
+      - event: Stop
+        matcher: ""
+        status_message: "🧮 Draining deferred embeddings..."
+
+  - id: agent-presence
+    script: agent-presence.sh
+    description: 'Live per-session presence file (.coding-os/<agent>/sessions/<sid>.json). Powers 3-state active/present/offline on the board — uses PPID + PID liveness so "thinking" agents don''t appear offline between tool calls. Updated 2026-05-04 — also fires on SubagentStart/SubagentStop/PostToolUseFailure so parent-session activity stays accurate while sub-agents work. Updated 2026-05-22 — also fires on PostToolUse Bash so read-only sessions (verify/git/pytest, no Write/Edit) refresh last_tool_at and stay visible past the 300s TTL.'
+    category: observability
+    phase: "0"
+    timeout: 5
+    events:
+      - event: SessionStart
+        matcher: startup
+      - event: SessionStart
+        matcher: compact|resume
+      - event: UserPromptSubmit
+        matcher: ""
+      - event: PostToolUse
+        matcher: Write|Edit
+      - event: PostToolUse
+        matcher: Bash
+      - event: PostToolUseFailure
+        matcher: ""
+      - event: SubagentStart
+        matcher: ""
+      - event: SubagentStop
+        matcher: ""
+      - event: Stop
+        matcher: ""
+      - event: SessionEnd
+        matcher: ""
+
+  - id: warn-mcp-down
+    script: warn-mcp-down.sh
+    description: Probes thinking_os MCP liveness at session start; loud banner if unreachable. Capped at 2s probe (perl alarm 2 + 500ms slack).
+    category: observability
+    phase: F
+    timeout: 30
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "🩺 Probing MCP coding-os liveness..."
+      - event: SessionStart
+        matcher: compact|resume
+        status_message: "🩺 Probing MCP coding-os liveness..."
+
+  - id: auto-brain-decay
+    script: auto-brain-decay.sh
+    description: SessionStart runs Ebbinghaus confidence decay on learned_patterns once per 24 h. Fire-and-forget, bounded at 10s; debounces via $COS_STATE_DIR/.last-decay.
+    category: observability
+    phase: G
+    timeout: 30
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "📉 Debounced pattern-decay sweep..."
+      - event: SessionStart
+        matcher: compact|resume
+        status_message: "📉 Debounced pattern-decay sweep..."
+
+  - id: reclaim-sweep
+    script: reclaim-sweep.sh
+    description: SessionStart reclaims zombie in_progress/testing tasks of dead predecessor sessions (board_os.cos_task_reclaim). Consumer-robust recovery leg — needs no SessionEnd event or cron. Fire-and-forget, detached, ~30m debounce via $COS_PANEL_DIR/.reclaim-sweep.
+    category: observability
+    phase: G
+    timeout: 15
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "♻️  Reclaiming zombie tasks of dead sessions..."
+      - event: SessionStart
+        matcher: compact|resume
+        status_message: "♻️  Reclaiming zombie tasks of dead sessions..."
+
+  - id: warn-graph-empty
+    script: warn-graph-empty.sh
+    description: SessionStart one-shot nudge when graph_os has no indexed nodes. Non-blocking; debounced per session; never auto-indexes.
+    category: observability
+    phase: I
+    timeout: 10
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "🕸️  Checking graph_os index state..."
+      - event: SessionStart
+        matcher: compact|resume
+        status_message: "🕸️  Checking graph_os index state..."
+
+  - id: check-capture-worked
+    script: check-capture-worked.sh
+    description: Session-end recap — warns if zero observations captured despite code edits.
+    category: observability
+    phase: F
+    timeout: 10
+    events:
+      - event: Stop
+        matcher: ""
+        status_message: "📊 Session recap: verifying observations captured..."
+
+  # ── reminder ───────────────────────────────────────────────────────
+  - id: regen-reminder
+    script: regen-reminder.sh
+    description: Reminds to regenerate derived artifacts when their sources change.
+    category: reminder
+    phase: E
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "🔄 Checking if derived artifacts need regeneration..."
+
+  - id: test-first-reminder
+    script: test-first-reminder.sh
+    description: Points at the companion test file after a code edit (or suggests one if absent).
+    category: reminder
+    phase: E
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "🧪 Checking for companion test file..."
+
+  - id: remind-learn-validate
+    script: remind-learn-validate.sh
+    description: Surfaces cos_learn_validate reminder after task-done so the agent feeds back.
+    category: reminder
+    phase: F
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: Bash
+        status_message: "💡 Checking if learn-validate reminder is due..."
+
+  - id: nudge-learn-narrative
+    script: nudge-learn-narrative.sh
+    description: |
+      Stop hook — when a session shows real learning signal (a file reworked
+      >=3x, or a backtrack), nudges the agent ONCE to record a structured lesson
+      via cos_learn_narrative (→ docs/insights + memory). Signal-gated (silent on
+      trivial sessions), debounced per session, warn-only, fail-open. The channel
+      for deep engineering lessons that friction/commit mining can't capture.
+    category: reminder
+    phase: "0"
+    timeout: 5
+    events:
+      - event: Stop
+        matcher: ""
+        status_message: "🧠 Checking if a lesson is worth recording..."
+
+  - id: jit-recall
+    script: jit-recall.sh
+    description: |
+      PreToolUse Write|Edit just-in-time recall — surfaces a past friction
+      lesson about the file being edited plus any convention-rule one-liner
+      mapped to the path in jit-rules.tsv, at the moment it matters. Warn-only,
+      debounced per (file, session) / (rule, session).
+    category: reminder
+    phase: O
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: "Write|Edit"
+        status_message: "🧠 Checking for a past lesson on this file..."
+
+  # ── meta (coding-os meta-project specific) ────────────────
+  - id: check-agents-md-size
+    script: check-agents-md-size.sh
+    description: Warns when AGENTS.md approaches Codex's 32 KiB read cap.
+    category: meta
+    phase: G
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "📏 Checking AGENTS.md size (Codex 32 KiB cap)..."
+
+  - id: check-agents-md-refs
+    script: check-agents-md-refs.sh
+    description: Flags AGENTS.md references to src/core/rules or src/core/skills that no longer exist.
+    category: meta
+    phase: G
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "🔗 Checking AGENTS.md path references are alive..."
+
+  - id: remind-dogfood
+    script: remind-dogfood.sh
+    description: Reminds to run `make dogfood-full` after edits to core/ or adapters/.
+    category: meta
+    phase: G
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: Write|Edit
+        status_message: "🧬 Checking if meta-project dogfood refresh is needed..."
+
+  # ── cognition (formula-agent supervisor) ───────────────────
+  - id: enforce-anti-ambiguity
+    script: enforce-anti-ambiguity.sh
+    description: Blocks code writes at EXECUTE phase when Anti-Ambiguity gate has failures. Bypassed for CLEAR 1.
+    category: cognition
+    phase: M
+    timeout: 5
+    events:
+      - event: PreToolUse
+        matcher: Write|Edit
+        status_message: "🔍 Anti-Ambiguity gate check..."
+
+  - id: track-backtrack
+    script: track-backtrack.sh
+    description: Non-blocking advisor that fires when cos_backtrack_log records ≥3 backtracks per session.
+    category: cognition
+    phase: M
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: mcp__coding-os__cos_backtrack_log
+        status_message: "↩️ Backtrack counter updated..."
+
+  - id: track-discovery
+    script: track-discovery.sh
+    description: |
+      Discovery Protocol auto-trigger. Scans Write/Edit output for
+      discovery signal phrases (new actor, missing dependency,
+      undocumented behavior, etc.). On ≥2 matches, emits a non-blocking
+      reminder to call cos_discovery with impact assessment + decision.
+      Reminder cooldown: 5 minutes per session to avoid spam.
+      Spec: formulas-en.md §Navigation Protocol §4 (Discovery Protocol).
+    category: cognition
+    phase: N
+    timeout: 5
+    events:
+      - event: PostToolUse
+        matcher: "Write|Edit"
+        status_message: "🔍 Scanning for discoveries..."
+
+  - id: capture-tool-failure
+    script: capture-tool-failure.sh
+    description: |
+      Capture meaningful tool failures (especially hook-blocked
+      events) to the observations table so they feed failure_pattern_query
+      and learn_extract. Only captures blocked events and repeated failures —
+      transient Bash errors are skipped to avoid noise. This closes the
+      "experience capture" gap: previously the system only learned from
+      completed outcomes, not from what failed mid-execution.
+    category: observability
+    phase: EVO
+    timeout: 5
+    events:
+      - event: PostToolUseFailure
+        matcher: ""
+
+  - id: auto-trace-rotate
+    script: auto-trace-rotate.sh
+    description: |
+      Stop hook — rotate trace JSONL. gzip files older than
+      COS_TRACE_GZIP_AGE_DAYS (default 3). Delete (gz or jsonl) older than
+      COS_TRACE_DELETE_AGE_DAYS (default 30). Bounded, fire-and-forget.
+      Closes the unbounded growth gap on .coding-os/<agent>/traces/*.jsonl.
+    category: observability
+    phase: O
+    timeout: 30
+    events:
+      - event: Stop
+        matcher: ""
+        status_message: "🧹 Rotating old trace files..."
+
+  - id: snapshot-transcript
+    script: snapshot-transcript.sh
+    description: |
+      Stop hook — snapshot the live session transcript (transcript_path from
+      the Stop payload) into $COS_AGENT_DIR/sessions/transcripts/<session-id>.jsonl
+      so a workflow session is auditable in-tree, not only in the agent
+      runtime's global store (~/.claude/projects/...). Copies only when the
+      source grew (Stop fires per turn); fail-open when transcript_path is
+      absent. The task↔session link is the existing tasks.agent_session id.
+    category: observability
+    phase: O
+    timeout: 30
+    events:
+      - event: Stop
+        matcher: ""
+        status_message: "📑 Snapshotting session transcript..."
+
+  - id: nudge-thinking-os
+    script: nudge-thinking-os.sh
+    description: |
+      UserPromptSubmit nudge — heuristic Complexity Gate + Rule 18 task reconciliation.
+      Counts signal words (design, architect, debug, investigate, refactor,
+      best way, optimize, etc.) plus length. For COMPLICATED+ emits a
+      stdout additional-context block mandating: (1) cos_task_board check per
+      Rule 18, (2) Complexity Gate recording, (3) thinking_os skill load,
+      (4) cos_compose_chain call. Debounced once per session via
+      .zoom-prompt-suggested marker; skipped if .thinking_os-gate already exists.
+    category: cognition
+    phase: O
+    timeout: 10
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+
+  - id: auto-compose-roles
+    script: auto-compose-roles.sh
+    description: |
+      UserPromptSubmit auto-trigger — for the recorded complexity gate
+      (COMPLICATED/COMPLEX): (1) composes the 11-role chain via formula_composer
+      and stamps .roles/.role so the Hub Roles panel + session banner reflect
+      real activity; (2) runs learn_suggest and writes .learn-suggestions so the
+      Orient recall arc fires and remind-learn-validate has input to validate.
+      Closes the dead-trigger + dead-recall gaps (TASK-055) where
+      cos_compose_chain / cos_learn_suggest had no automatic caller. Debounced
+      once per (session, gate-class) via .roles-composed. Fail-open.
+    category: cognition
+    phase: O
+    timeout: 10
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+
+  - id: classify-task-mode
+    script: classify-task-mode.sh
+    description: |
+      UserPromptSubmit — classify the prompt into a persona-aware
+      task-mode and write the verdict to $COS_AGENT_DIR/.task-mode.
+      Modes: formal | propose-formal | query | chore | adhoc |
+      gov-required. Downstream enforcement hooks read the marker so a
+      Q&A turn does not pay the same cost as a multi-file refactor —
+      Rule 18 ("task reconciliation mandatory") is honored without
+      forcing a TASK-NNN onto every analytical question.  Decision
+      matrix lives in docs/engineering/task-mode-matrix.md.
+    category: cognition
+    phase: O
+    timeout: 5
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+
+  - id: nudge-graph-os
+    script: nudge-graph-os.sh
+    description: |
+      UserPromptSubmit nudge — graph_os discovery. Pattern-matches the prompt
+      against 13 structural-question patterns (callers, rename, blast radius,
+      contracts, trace, similar, communities, context, detect-changes,
+      entrypoints, doctor, export, path) — bilingual (EN + Persian) — and
+      emits a one-line additional-context block recommending the exact
+      cos_graph_* tool to call before Read/grep. Closes the dogfood gap
+      where the agent never reaches the graph layer. Debounced per session
+      via .graph-nudge-suggested marker.
+    category: cognition
+    phase: I
+    timeout: 10
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+
+  - id: nudge-model-routing
+    script: nudge-model-routing.sh
+    description: |
+      UserPromptSubmit nudge — model-routing directive (TASK-319). When
+      hub-settings.json::model_routing.enabled, injects a one-line
+      additional-context directive (once per session) telling the agent to
+      consult cos_route_model at Classify and pass model+complexity at
+      dispatch — CLI/VSCode parity with the hub chat Auto option. Toggle
+      off = silent exit, zero injected tokens. Contract:
+      src/core/rules/model-routing.md.
+    category: cognition
+    phase: I
+    timeout: 10
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+
+  - id: nudge-git-mode
+    script: nudge-git-mode.sh
+    description: |
+      UserPromptSubmit nudge — pr-mode directive (TASK-615). When
+      COS_GIT_WORKFLOW=pr, injects a one-line additional-context directive
+      (once per session) telling the agent to start with `cos pr open` and
+      edit inside the worktree, so pr-mode is surfaced proactively instead of
+      learned by being block-shared-tree-edit BLOCKed. Trunk (default) =
+      silent exit, zero injected tokens. Contract: docs/playbooks/pr-workflow.md.
+    category: cognition
+    phase: I
+    timeout: 10
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+
+  - id: nudge-task-discovery
+    script: nudge-task-discovery.sh
+    description: |
+      Task-discovery nudge — three events, all fail-open + debounced per
+      session per leg. UserPromptSubmit: task-reference intent (TASK-NNN,
+      check/show/look-at task; bilingual EN + Persian) → additionalContext
+      recommending `cos task-show TASK-NNN` / cos_task_search / cos_task_show
+      (MCP) over cat/grep on docs/tasks/. PreToolUse Bash: warns (non-blocking)
+      when a command reads docs/tasks/ directly (ls/grep/cat/find/head/tail/
+      awk/sed/less/more/bat/rg/wc/nl/tac). PreToolUse Read: warns when the Read
+      tool targets a docs/tasks/** path. Closes the screenshot-2 gap. Mirrors
+      nudge-graph-os mechanism.
+    category: cognition
+    phase: O
+    timeout: 10
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+      - event: PreToolUse
+        matcher: Bash
+        status_message: "🗂️ Suggesting cos task-show over docs/tasks read..."
+      - event: PreToolUse
+        matcher: Read
+        status_message: "🗂️ Suggesting cos task-show over a docs/tasks Read..."
+
+  - id: nudge-docs-first
+    script: nudge-docs-first.sh
+    description: |
+      UserPromptSubmit nudge — docs-first SSOT discovery. Pattern-matches
+      the prompt for code-edit intent (refactor, rename, fix, add,
+      implement, change function/endpoint/handler/...; bilingual EN +
+      Persian) AND no .doc-anchor populated AND task-mode not in
+      query/chore/adhoc → emits a one-line additional-context block
+      pointing to cos_doc_search / cos_doc_header and the procedure in
+      docs/governance/docs-first-protocol.md. Closes the gap where
+      enforce-doc-anchor.sh fires only on Write/Edit, but user intent
+      already signals "code coming" at prompt time. Debounced per session
+      via .docs-first-nudged marker.
+    category: cognition
+    phase: O
+    timeout: 10
+    events:
+      - event: UserPromptSubmit
+        matcher: ""
+
+  - id: session-skill-primer
+    script: session-skill-primer.sh
+    description: |
+      SessionStart prime card — emits a compact additionalContext block
+      listing the skills that enforce-skill.sh (PreToolUse Write/Edit)
+      will BLOCK without. Reads SSOT:
+      $COS_STATE_DIR/installed-manifest.json::templates → active stacks;
+      src/templates/<stack>/stack.yaml → primary_skill + skill_enforcement
+      table. Closes the gap where the agent only discovers required
+      skills reactively after the first block. Fires on startup AND on
+      compact|resume — in a multi-hour session a compaction can outlive
+      the 120-min .active-skill marker, so the card must re-prime after
+      context loss (mirrors rules-primer). SessionStart
+      fires once per boundary, so no debounce is needed. Always exits 0.
+    category: cognition
+    phase: P
+    timeout: 10
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "🧠 Priming required-skill card..."
+      - event: SessionStart
+        matcher: compact|resume
+        status_message: "🧠 Re-priming required-skill card..."
+
+  - id: rules-primer
+    script: rules-primer.sh
+    description: |
+      SessionStart prime card — injects a ~200-token workflow-integrity card
+      at every session boundary (startup, compact, resume) so the agent enters
+      turn-1 knowing Critical Rule 25: task status changes go through
+      cos_task_move / cos task-done (never a hand-Edit;
+      enforce-task-transition BLOCKs it), task lookup via
+      cos task-show / cos_task_search (never ls/grep on docs/tasks), gate via
+      cos_classify_prompt, and that cos_* tools are deferred (ToolSearch first).
+      Full contract: critical-rules.md § Rule 25.
+      Always exits 0.
+    category: cognition
+    phase: P
+    timeout: 10
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "📋 Priming workflow-integrity rules card..."
+      - event: SessionStart
+        matcher: compact|resume
+        status_message: "📋 Re-priming workflow-integrity rules card..."
+
+  - id: ensure-agent-memory-link
+    script: ensure-agent-memory-link.sh
+    adapter_scope: claude
+    description: |
+      SessionStart — turns the harness's machine-local memory dir
+      (~/.claude/projects/<slug>/memory) into a symlink onto the repo's
+      committed .agents/memory, migrating existing files without clobber.
+      Portable agent memory: a fresh clone reconnects on the first session.
+      Idempotent, self-repairing, fail-open. Spec:
+      docs/engineering/learning-extraction.md § Versioned agent memory.
+    category: observability
+    phase: "0"
+    timeout: 10
+    events:
+      - event: SessionStart
+        matcher: startup
+        status_message: "🔗 Linking versioned agent memory..."
+      - event: SessionStart
+        matcher: resume
+        status_message: "🔗 Re-checking agent memory link..."
+
+  - id: sync-agent-memory
+    script: sync-agent-memory.sh
+    adapter_scope: claude
+    description: |
+      Stop — renders Trusted lessons into .agents/memory/MEMORY.md (generated
+      block, manual notes preserved) and harvests foreign notes back into
+      learned_patterns with a content-hash ledger so exported lessons are
+      never re-imported. Fail-open. Spec:
+      docs/engineering/learning-extraction.md § Versioned agent memory.
+    category: observability
+    phase: "0"
+    timeout: 30
+    events:
+      - event: Stop
+        matcher: ""