coding-os 0.3.2__py3-none-any.whl

templates/meta/skills/graph-os-authoring/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: graph-os-authoring
+tier: stack
+domain: [architecture]
+description: Author the graph_os knowledge-graph internals — extractors, backends, indexers, queries. Use when adding a new node/edge type, writing a new extractor (Python AST, doc-headings, etc.), evolving the SQLite backend, or modifying the reindex dispatcher. Enforces idempotency on uid, append-only file_index_state, backend-agnostic tool layer, confidence-scoring discipline. Pairs with graph-explorer (which queries the graph this skill builds), python-meta-server, and mcp-tool-authoring (for `cos_graph_*` tools).
+last_reviewed: "2026-05-11"
+---
+
+# graph-os-authoring
+
+Purpose: The graph is the third retrieval layer. Authoring it correctly — idempotent extraction, backend-neutral query layer, honest confidence scores — is what makes `cos_graph_*` tools faster + more accurate than grep. Getting any one of those wrong corrupts the graph silently, and the agent starts trusting hallucinations.
+
+Read when: editing files matching:
+- `src/core/graph_os/backends/*.py` — SQLite (single backend today; Kuzu retired 2026-05-18 after benchmark showed SQLite p99 < 30 ms on 5-hop @ 1M nodes).
+- `src/core/graph_os/extractors/*.py` — Python AST / doc / config extractors.
+- `src/core/graph_os/tools/*.py` — the `cos_graph_*` MCP tools (also see [mcp-tool-authoring](../mcp-tool-authoring/SKILL.md)).
+- `src/core/graph_os/tools/reindex_dispatch.py` — incremental reindex orchestration.
+- `src/core/graph_os/types.py` — node + edge type definitions (the contract).
+
+Skip when: only querying the graph (use [graph-explorer](../../../core/skills/graph-explorer/SKILL.md) for that).
+
+## The Five Hard Contracts
+
+### 1. UID scheme (immutable across rebuilds)
+
+Every node has a uid that survives reindex. Scheme:
+
+```
+code:file:<path>
+code:function:<path>::<name>
+code:class:<path>::<name>
+code:module:<dotted-name>
+doc:file:<path>
+doc:heading:<path>#<slug>:<level>
+folder:<path>
+config:<path>::<key>
+```
+
+Path is repo-relative, POSIX, no leading slash. **Never** include line numbers in uids — line numbers shift; uids must be stable.
+
+When adding a new node type, extend the registry in [src/core/graph_os/types.py](../../../core/graph_os/types.py) and document the uid grammar there. The grammar IS the contract — agents reference uids in saved memories.
+
+### 2. Idempotent extraction (keyed on uid)
+
+Every extractor MUST be re-runnable. The contract: extracting the same file twice produces the same nodes + edges. Implementation:
+
+```python
+def extract(file_path: Path) -> ExtractionResult:
+    nodes = []
+    edges = []
+    for symbol in _walk_ast(file_path):
+        nodes.append(GraphNode(
+            uid=_make_uid(symbol),  # deterministic from file + symbol name
+            kind="function",
+            label=symbol.name,
+            file_path=str(file_path),
+            start_line=symbol.start,
+            end_line=symbol.end,
+            confidence=1.0,  # AST gives certainty
+        ))
+        for callee in symbol.callees:
+            edges.append(GraphEdge(
+                source_uid=nodes[-1].uid,
+                target_uid=_resolve_callee_uid(callee, file_path),
+                kind="calls",
+                confidence=_calc_confidence(callee),  # see §3
+            ))
+    return ExtractionResult(nodes=nodes, edges=edges)
+```
+
+**Hard rules:**
+
+- **Upsert on uid**, never blind-insert.
+- **Removed symbols are HARD-deleted** — if function `foo` disappears from a file, `delete_nodes_for_file` removes its node before the file is re-extracted. The graph mirrors HEAD-of-tree, so a symbol that left the tree is *gone*, not historical; git is the forensic record of what used to exist. There is no `deleted_at` column and no tombstone compaction — they would accumulate millions of dead rows for a property (historical uid resolution) nothing in the system needs today. The graph keeps **no deletion ledger** for node prune — it runs on every per-file reindex, so a per-prune ledger row would be pure churn. Routine node prune is logged at `logger.debug`; git is the record. If historical uid resolution is ever required, add tombstoning as a deliberate feature then — don't assume it exists.
+- **Edge confidence is part of the key idempotency** — re-extracting the same edge updates the confidence, doesn't append a duplicate.
+
+### 3. Honest confidence scores
+
+Every edge has a confidence ∈ [0, 1]. Calibrated guide:
+
+| Confidence | Meaning | Example |
+|---|---|---|
+| 1.0 | AST-certain | `import X`, `class Y(Z):` (direct inheritance), `def foo(): bar()` (direct call site) |
+| 0.7-0.9 | Strong heuristic | Attribute access through `self.something.method()` (dynamic dispatch but typed) |
+| 0.4-0.6 | Weak heuristic | String reference (`"my_module.func"`), dict-keyed dispatch |
+| 0.1-0.3 | Possible | Same-named symbol in different module (could be aliasing or coincidence) |
+| < 0.1 | Drop | Don't emit; noise |
+
+Tools (`cos_graph_impact`, `cos_graph_references`) cluster low-confidence edges into a separate "context" tier so agents can ignore them. Inflating confidence = agents trusting noise = hallucinations.
+
+### 4. Backend-agnostic tool layer
+
+The tool layer (`src/core/graph_os/tools/*.py`) MUST NOT leak SQL or Cypher into MCP tool responses. The tool calls into a backend abstraction:
+
+```python
+# src/core/graph_os/tools/_query.py
+from core.graph_os.backends import get_backend
+
+async def query_references(uid: str) -> list[GraphEdge]:
+    backend = get_backend()  # returns SqliteBackend today; abstraction kept so a future store can plug in.
+    return await backend.find_references(uid)
+```
+
+Backends implement a common Protocol:
+
+```python
+class GraphBackend(Protocol):
+    async def find_references(self, uid: str) -> list[GraphEdge]: ...
+    async def find_context(self, uid: str, depth: int) -> list[GraphEdge]: ...
+    async def upsert_nodes(self, nodes: list[GraphNode]) -> None: ...
+    async def upsert_edges(self, edges: list[GraphEdge]) -> None: ...
+    # ...
+```
+
+Adding a future backend later = new backend file only, zero changes to the tool layer.
+
+### 5. Reindex is incremental + short-circuited
+
+Full reindex of a large repo is minutes. Production cost must be milliseconds per save. Implementation:
+
+```python
+# src/core/graph_os/tools/reindex_dispatch.py
+async def dispatch(file_path: str) -> ReindexResult:
+    new_hash = _hash_file_contents(file_path)
+    old_hash = await _file_index_state.get(file_path)
+
+    if new_hash == old_hash:
+        return ReindexResult(skipped=True, reason="content unchanged")
+
+    extraction = _extract(file_path)
+    await _backend.upsert_nodes(extraction.nodes)
+    await _backend.upsert_edges(extraction.edges)
+    await _file_index_state.set(file_path, new_hash)
+    return ReindexResult(skipped=False, nodes=len(extraction.nodes), edges=len(extraction.edges))
+```
+
+`file_index_state` is the bookkeeping table mapping path → content-hash → last-indexed-at. Without it, every PostToolUse hook re-extracts unchanged files.
+
+## Extractor — the Decision Tree
+
+When adding a new extractor:
+
+1. **What kind of artifact?** Code (Python / Go / TS / etc.) → AST extractor. Docs (Markdown / RST) → header extractor. Config (YAML / TOML / JSON) → key extractor.
+2. **What nodes?** One per top-level symbol — functions, classes, modules. Sub-symbols (nested classes, methods) get their own node only if they're called from elsewhere.
+3. **What edges?** `calls`, `imports`, `inherits`, `references` (doc → code), `contains` (folder → file → class → method), `tested_by` (test → subject).
+4. **Where does ambiguity go?** Low-confidence edges. **Never** invent edges to fill in gaps.
+
+### AST extractor anatomy (Python example)
+
+```python
+# src/core/graph_os/extractors/python_ast.py
+import ast
+from pathlib import Path
+
+from core.graph_os.types import GraphNode, GraphEdge, ExtractionResult
+
+
+class PythonAstExtractor:
+    """Extracts functions, classes, imports, calls from .py files."""
+
+    def extract(self, path: Path) -> ExtractionResult:
+        source = path.read_text(encoding="utf-8")
+        tree = ast.parse(source, filename=str(path))
+        nodes: list[GraphNode] = []
+        edges: list[GraphEdge] = []
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef):
+                nodes.append(self._function_node(path, node))
+                edges.extend(self._call_edges(path, node))
+            elif isinstance(node, ast.ClassDef):
+                nodes.append(self._class_node(path, node))
+                edges.extend(self._inherit_edges(path, node))
+            elif isinstance(node, (ast.Import, ast.ImportFrom)):
+                edges.extend(self._import_edges(path, node))
+
+        return ExtractionResult(nodes=nodes, edges=edges)
+    # ... helpers below
+```
+
+Test the extractor with a representative file + assert exact uid + count of nodes/edges:
+
+```python
+def test_extracts_function_with_two_calls(tmp_path):
+    src = tmp_path / "sample.py"
+    src.write_text("""
+def outer():
+    inner()
+    other.method()
+
+def inner():
+    pass
+""")
+    result = PythonAstExtractor().extract(src)
+    assert len(result.nodes) == 2  # outer + inner
+    assert any(e.kind == "calls" and e.target_uid.endswith("::inner") for e in result.edges)
+```
+
+## Backend — the Decision Tree
+
+`graph_os` ships a single backend:
+
+- **SQLite** — embedded relational, FTS5 + JSON1, p99 < 30 ms on 5-hop traversal at 1M nodes with PRAGMA tuning + ANALYZE (benchmark 2026-05-18).
+
+The Kuzu backend was retired the same day after the benchmark showed SQLite was well inside budget for every realistic consumer scale. The abstraction (`GraphBackend` Protocol) is kept so a future graph-native store can plug in if a real workload exceeds SQLite's headroom.
+
+When adding a future backend:
+
+1. Implement the `GraphBackend` Protocol.
+2. Register it in `src/core/graph_os/backends/__init__.py`.
+3. Add parity tests against SQLite — same queries → same results (within confidence-tier tolerance).
+4. Document the backend's strengths / weaknesses in [docs/engineering/graph_os-queries.md](../../../docs/engineering/graph_os-queries.md).
+
+**Hard rule:** the backend choice is a deployment concern, never visible to the agent or tool layer. `cos_graph_references` returns identical envelope shape regardless of which backend answered.
+
+## Reindex Dispatch Patterns
+
+| Trigger | Behavior |
+|---|---|
+| PostToolUse hook (single file written) | `dispatch(path)` — extract that file only |
+| Doc indexer (markdown changed) | Same — incremental |
+| Bulk migration / `git checkout` | `cos graph-reindex --force` — re-extract everything because content hashes are now misleading |
+
+The PostToolUse path is fire-and-forget: it can't block the agent. Failures log + alert but the user's edit completes regardless.
+
+## Tool-Side (when authoring `cos_graph_*`)
+
+`cos_graph_*` tools are MCP tools — also see [mcp-tool-authoring](../mcp-tool-authoring/SKILL.md). Graph-specific contracts on top of the universal MCP contract:
+
+- **Every response carries `data.meta.layer="graph"`** so agents know which retrieval layer answered.
+- **`data.meta.backend`** tells which backend answered (`sqlite` today).
+- **`data.meta.backend_fallback=true`** when the primary backend was unavailable and an alternate answered (no alternate today — flag reserved for a future graph-native plug-in).
+- **Empty result is valid** — fresh repo, unindexed file. Don't return `fail`; return `ok({results: []})`.
+
+## Anti-patterns (reject in review)
+
+- **Non-idempotent extractor** — running twice produces duplicate edges.
+- **Confidence inflation** — labeling a weak heuristic 0.9 to make `cos_graph_impact` return it in the strong tier. Pollutes agent trust.
+- **SQL / Cypher leaking into tool responses** — breaks backend abstraction.
+- **Hardcoded backend in tool layer** — must go through `get_backend()`.
+- **Reindex without content-hash check** — kills perf.
+- **Edge to a uid that doesn't exist** — dangling reference. Validate target uid exists or queue resolution.
+- **Mutable uid** — including line number, timestamp, hash in the uid breaks cross-rebuild stability.
+- **Deleting nodes without committing or while holding a stale edge** — leaves dangling edges; `delete_nodes_for_file` deletes + commits under the write lock, and `cos_graph_doctor` sweeps any survivors.
+- **Synchronous extraction in PostToolUse hook** — blocks the agent. Always fire-and-forget.
+
+## Verification (after authoring)
+
+```bash
+# Extractor parity tests
+uv run --extra graph_os pytest src/core/graph_os/tests/extractors/ -q
+
+# Backend parity tests
+uv run --extra graph_os pytest src/core/graph_os/tests/test_backends/ -q
+
+# Tool layer tests
+uv run --extra graph_os pytest src/core/graph_os/tests/test_tools.py -q
+
+# Live graph doctor (after reindex)
+cos graph-reindex
+cos_graph_doctor   # check for dangling edges, orphan nodes, hash mismatch
+```
+
+Pre-merge: `make verify` + `cos doctor`.
+
+## Tooling
+
+Scaffold an extractor stub (idempotent uid, content-hash short-circuit, typed Node/Edge):
+`python3 scripts/new_extractor.py --lang python`
+
+## See also
+
+- [assets/graph-os-checklist.md](assets/graph-os-checklist.md) — the extractor + backend gate.
+- [graph-explorer](../../../core/skills/graph-explorer/SKILL.md) — the query-side counterpart of this skill.
+- [docs/engineering/graph_os-queries.md](../../../docs/engineering/graph_os-queries.md) — query routing + freshness contract.
+- [docs/engineering/graph-hallucination-cures.md](../../../docs/engineering/graph-hallucination-cures.md) — the 16 `cos_graph_*` tools and what each cures.
+- [mcp-tool-authoring](../mcp-tool-authoring/SKILL.md) — when authoring a `cos_graph_*` tool.
+- [python-meta-server](../python-meta-server/SKILL.md) — Python conventions for this codebase.

templates/meta/skills/graph-os-authoring/assets/graph-os-checklist.md

@@ -0,0 +1,25 @@
+<!-- domain:META | layer:asset | ssot:false | updated:2026-06-04 -->
+# graph_os Authoring Checklist
+
+Run when adding a node/edge type, an extractor, or touching the backend.
+
+## Extractor invariants
+- [ ] `bash scripts/new_extractor.py --lang <l>` used (or matches its shape).
+- [ ] `uid` is deterministic for the same symbol → upsert is idempotent.
+- [ ] Short-circuits unchanged files via `file_index_state` content hash.
+- [ ] Returns typed `Node`/`Edge` — no raw dicts.
+- [ ] Registered in the reindex dispatcher.
+
+## Backend discipline
+- [ ] Tool layer stays backend-agnostic — no raw SQL/Cypher leaks into `cos_graph_*` callers.
+- [ ] `file_index_state` writes are append-only.
+- [ ] Confidence scored on inferred edges (low-confidence clustered, not asserted).
+
+## Coverage
+- [ ] New edge/node kind documented in graph-hallucination-cures.md if it powers a `cos_graph_*` tool.
+- [ ] `cos_graph_*` envelope still `ok`/`fail` (Rule 13) for any new graph tool.
+
+## Verify
+- [ ] `uv run --extra graph_os pytest src/core/graph_os/tests/ -q`.
+- [ ] `cos graph-reindex --force` after extractor-code changes (plain reindex skips by content hash).
+- [ ] `cos graph-doctor` clean.

templates/meta/skills/graph-os-authoring/scripts/new_extractor.py

@@ -0,0 +1,76 @@
+"""Scaffold a graph_os extractor stub (idempotent on uid, content-hash short-circuit).
+
+PURPOSE:      Emit an extractor that already obeys the graph_os invariants —
+              idempotent on uid, short-circuits via file_index_state, returns
+              typed nodes/edges — so the author fills extraction logic only.
+INPUT:        --lang <python|typescript|go|...> (the language it extracts)
+              [--out <path>]  write to a file instead of printing.
+OUTPUT:       The extractor source on stdout (or to --out). Exit 0; 2 usage.
+DEPENDENCIES: stdlib only.
+NOTES:        Pure render() is unit-testable. Register the extractor in the
+              reindex dispatcher by hand. Spec: docs/engineering/graph_os-queries.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+
+TEMPLATE = '''\
+"""Extractor for {lang} files — emits graph_os nodes + edges."""
+
+from __future__ import annotations
+
+from graph_os.types import Node, Edge
+
+
+def extract_{lang}(path: str, content: str, content_hash: str) -> tuple[list[Node], list[Edge]]:
+    # Short-circuit: the dispatcher skips unchanged files via file_index_state,
+    # but guard here too so a direct call is cheap on a known hash.
+    nodes: list[Node] = []
+    edges: list[Edge] = []
+
+    # uid MUST be deterministic for the same symbol → idempotent upsert.
+    # uid = f"{lang}:{{path}}::{{symbol_name}}"
+
+    # TODO: parse `content` (tree-sitter / ast / regex fallback) and append
+    #       Node(uid=..., kind=..., name=..., file=path) and
+    #       Edge(src_uid=..., dst_uid=..., kind="calls|imports|contains|...").
+
+    return nodes, edges
+'''
+
+
+def render(lang: str) -> str:
+    safe = re.sub(r"[^a-z0-9_]", "_", lang.lower()).strip("_") or "lang"
+    return TEMPLATE.format(lang=safe)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--lang", required=True)
+    parser.add_argument("--out", default=None)
+    args = parser.parse_args(argv)
+
+    if not args.lang.strip():
+        print("error: --lang must be non-empty", file=sys.stderr)
+        return 2
+
+    code = render(args.lang)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8") as fh:
+            fh.write(code)
+        print(args.out)
+    else:
+        sys.stdout.write(code)
+    print(
+        "reminder: register the extractor in the reindex dispatcher; "
+        "verify with: uv run --extra graph_os pytest src/core/graph_os/tests/ -q",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

templates/meta/skills/hook-authoring/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: hook-authoring
+tier: stack
+domain: [governance]
+description: Author production-grade hooks for the coding-os meta-repo — Bash scripts under src/core/hooks/ and Python helpers under src/core/hooks/_helpers/. Enforces SSOT registration in registry.yaml (Rule 10), source cos-env.sh (Rule 3), agent-agnostic env vars not hardcoded .claude/ (Rule 1, P2), proper event/matcher declaration, adapter capability filtering, and the regen pipeline. Pairs with meta-engineering, clean-code, and thinking_os.
+last_reviewed: "2026-05-11"
+---
+
+# hook-authoring
+
+Purpose: Every hook in `src/core/hooks/` propagates via live symlinks to every consumer project that registers any adapter. A buggy hook breaks N projects at once. The same shape, every time, keeps the ~50 hooks coherent.
+
+Read when: editing files matching:
+- `src/core/hooks/*.sh` — hook scripts.
+- `src/core/hooks/_helpers/*.py` — Python helpers invoked by hooks.
+- `src/core/hooks/registry.yaml` — the SSOT for hook registration.
+- `src/adapters/<id>/adapter.yaml` (`hook_capabilities` block) — runtime capability filter.
+
+Skip when: editing hook *tests*, runtime presence files in `.coding-os/`, generated adapter templates.
+
+## The Three Hard Contracts
+
+Every hook MUST satisfy:
+
+### 1. Source `cos-env.sh` (Rule 3)
+
+The first non-comment lines of every hook:
+
+```bash
+#!/usr/bin/env bash
+# What this hook does, one line.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+```
+
+`cos-env.sh` exports `$COS_STATE_DIR`, `$COS_AGENT`, `$COS_AGENT_DIR`, `$COS_DB_PATH`, etc. Without it, the hook will reach for hardcoded `.claude/` paths and break on Codex/Cursor.
+
+### 2. Never hardcode `.claude/` (Rule 1, P2)
+
+```bash
+# WRONG
+state_file=".claude/state/something"
+
+# RIGHT
+state_file="$COS_AGENT_DIR/something"
+# or, if it's session-shared across agents:
+state_file="$COS_STATE_DIR/something"
+```
+
+The `block-hardcoded-literals.sh` hook audits the diff and blocks `.claude/` literals in `src/core/**`.
+
+### 3. Register in `registry.yaml` (Rule 10, SSOT)
+
+A new hook file is invisible until registered. Add an entry to [src/core/hooks/registry.yaml](../../../core/hooks/registry.yaml):
+
+```yaml
+- id: my-new-hook
+  script: my-new-hook.sh
+  event: PreToolUse        # PreToolUse | PostToolUse | UserPromptSubmit | Stop | SessionStart | PostToolUseFailure | SubagentStart | SubagentStop
+  matcher: "Write|Edit"    # tool matcher (event-specific) — empty = match-all where allowed
+  phase: gate              # gate | observation | enforcement | telemetry
+  category: governance     # documentation | governance | safety | telemetry | task | skill | graph | ...
+  description: "One line — what the hook does."
+  blocking: true           # exit 2 blocks the tool call; false = soft warn only
+  adapters: ["claude", "codex", "cursor"]  # which adapters to render this hook into
+```
+
+After registry edit:
+
+```bash
+make regen-adapter-templates
+```
+
+This rewrites `adapters/{claude,codex,cursor}/settings.template.json` from the registry, filtering by each adapter's `hook_capabilities`.
+
+## Hook Lifecycle by Phase
+
+| Phase | What it does | When it fires | Exit code semantics |
+|---|---|---|---|
+| **gate** | Block disallowed actions before they happen | PreToolUse | `exit 2` = block; `exit 0` = allow |
+| **observation** | Record state without blocking | UserPromptSubmit, PostToolUse | always `exit 0`; side effects are the point |
+| **enforcement** | Require something before the action | PreToolUse | `exit 2` = block; emits remediation message |
+| **telemetry** | Append to logs / DB without affecting flow | PostToolUse, Stop | always `exit 0` |
+
+Mixing phases (e.g. a "gate" that also writes telemetry) is fine as long as the exit code follows the gate's contract.
+
+## Adapter Capability Filtering
+
+Each adapter declares its `hook_capabilities` in `src/adapters/<id>/adapter.yaml`:
+
+```yaml
+hook_capabilities:
+  PreToolUse:
+    matchers: [Bash, "Write|Edit", "Write|Edit|MultiEdit", Skill, Read]
+  PostToolUse:
+    matchers: [Bash, "Write|Edit", "Write|Edit|MultiEdit", Skill, "mcp__coding-os__cos_backtrack_log"]
+  # ...
+```
+
+The renderer (`src/cli/hook_renderer.py`) skips registry entries whose `{event, matcher}` isn't in the adapter's capabilities. **Codex CLI, for instance, only has Bash-matcher PreToolUse/PostToolUse — so a `Write|Edit` hook is silently skipped for codex.** This is correct, not a gap.
+
+If your hook needs to fire on Codex but the matcher isn't supported, two options:
+1. Reformulate the matcher (e.g. wrap the Bash command instead of the Edit tool).
+2. Wait for the agent to ship the matcher; declare the hook only for capable adapters.
+
+**Don't** force a matcher into an adapter that doesn't support it — the install will validate against the YAML and refuse.
+
+## Reading + Writing Hook Input
+
+Hook stdin is a JSON envelope from the agent. Use the helper:
+
+```bash
+INPUT="$(cos_read_stdin_bounded 2)"      # 2 MB cap
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+PROMPT=$(echo "$INPUT" | jq -r '.user_prompt // empty' 2>/dev/null || echo "")
+```
+
+`cos_read_stdin_bounded` is sourced from `cos-env.sh`. It safely reads stdin with a size cap (protects against runaway agent output).
+
+To **block** with a message the agent will see:
+
+```bash
+echo "BLOCKED: <human-readable reason + remediation>" >&2
+exit 2
+```
+
+The message on stderr is shown to the agent — write it as advice, not just a complaint. Include the fix.
+
+## Python Helpers (`src/core/hooks/_helpers/`)
+
+When the hook needs more than ~30 lines of logic or any non-trivial parsing, write a Python helper:
+
+```python
+# src/core/hooks/_helpers/my_check.py
+"""Check XYZ and emit JSON verdict to stdout."""
+from __future__ import annotations
+import json
+import sys
+
+def main() -> int:
+    payload = json.load(sys.stdin)
+    file_path = payload.get("tool_input", {}).get("file_path", "")
+
+    if _violates_rule(file_path):
+        json.dump({"verdict": "block", "message": "..."}, sys.stdout)
+        return 0  # exit code 0 — the verdict in JSON is the signal
+
+    json.dump({"verdict": "allow"}, sys.stdout)
+    return 0
+
+
+def _violates_rule(path: str) -> bool:
+    ...
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+```
+
+Invoke from the Bash hook:
+
+```bash
+verdict_json=$(echo "$INPUT" | python3 "$(dirname "$0")/_helpers/my_check.py")
+verdict=$(echo "$verdict_json" | jq -r '.verdict')
+if [ "$verdict" = "block" ]; then
+    echo "$verdict_json" | jq -r '.message' >&2
+    exit 2
+fi
+```
+
+This pattern keeps the Bash hook thin, makes the Python testable, and centralizes stdin parsing in one place.
+
+**As-file bootstrap invariant.** A helper a hook runs *as a file* (`python3 x.py`) — not as an installed module — must self-bootstrap `src/` onto `sys.path` at import time; the editable install is absent in delivered/consumer environments, so `from core.<pkg>` (and package-qualified sibling imports) fail otherwise. Use the src/-first prelude (`_SRC = …/src`, then `_CORE`, then the module dir); `src/core/scheduled/responsive_extract.py` is the canonical shape. When you bound such a call (e.g. `run_bounded_python`), log a breadcrumb on a non-zero child rc so a broken bootstrap surfaces in `cos hooks-log` instead of being swallowed by `stderr→DEVNULL`.
+
+## State Files (`$COS_AGENT_DIR/*`)
+
+Hooks communicate via session-scoped state files:
+
+| File | Purpose | Lifecycle |
+|---|---|---|
+| `.task-current` | Active task marker | Session |
+| `.thinking_os-gate` | Cynefin classification | 120 min |
+| `.doc-anchor` | Doc-anchor for current edit | Single edit |
+| `.graph-context-<uid>` | Graph context already loaded | Session |
+| `.skill-<name>` | Skill loaded this session | Session |
+| `.swimlane` | Active swimlane (frontend/backend/...) | Session |
+
+Use `write-state.sh` to write:
+
+```bash
+bash src/core/hooks/write-state.sh "$COS_AGENT_DIR/.thinking_os-gate" "COMPLICATED 3"
+```
+
+`write-state.sh` handles atomic write + session-id prefix. Don't roll your own.
+
+## Logging
+
+Hooks should log every blocking decision to `make log-write`:
+
+```bash
+if [ "$verdict" = "block" ]; then
+    bash src/core/scripts/log-write.sh \
+        --type "hook-block" \
+        --msg "block-protected-files" \
+        --what "$(basename "$FILE_PATH")" \
+        --files "$FILE_PATH" 2>/dev/null || true
+fi
+```
+
+`|| true` so a logging failure never blocks the actual hook decision.
+
+## Testing
+
+Hook tests live in `tests/test_hooks_*.py`:
+
+```python
+# tests/test_my_hook.py
+import json
+import subprocess
+from pathlib import Path
+
+HOOK = Path(__file__).resolve().parent.parent / "core" / "hooks" / "my-new-hook.sh"
+
+
+def _run_hook(payload: dict) -> tuple[int, str, str]:
+    proc = subprocess.run(
+        ["bash", str(HOOK)],
+        input=json.dumps(payload).encode(),
+        capture_output=True,
+        timeout=5,
+    )
+    return proc.returncode, proc.stdout.decode(), proc.stderr.decode()
+
+
+def test_blocks_disallowed_file() -> None:
+    code, _, err = _run_hook({"tool_input": {"file_path": "/etc/passwd"}})
+    assert code == 2
+    assert "BLOCKED" in err
+
+
+def test_allows_normal_file() -> None:
+    code, _, _ = _run_hook({"tool_input": {"file_path": "src/main.py"}})
+    assert code == 0
+```
+
+Run: `make verify-hooks` (shellcheck warn + bash -n + behavior tests).
+
+## Anti-patterns (reject in review)
+
+- **Hook script not in `registry.yaml`** — won't be rendered to any adapter. Silently dead.
+- **Hardcoded `.claude/` path** — breaks Codex, Cursor. Use `$COS_AGENT_DIR`.
+- **Missing `source cos-env.sh`** — env vars unset, hook fails silently or wrong.
+- **Returning `exit 1` on a block** — must be `exit 2`. `1` means "tool errored", `2` means "blocked by policy".
+- **`set -e` without `set -euo pipefail`** — partial failure modes leak.
+- **Block message without remediation** — agent doesn't know how to fix it. Always include "to fix: ...".
+- **Hook that always fires even when no relevant file** — wasted overhead. Filter by matcher / first lines of stdin parse.
+- **Slow hook (>200ms)** — drags every tool call. Either fast-path-out for the no-op case or move logic to PostToolUse / async telemetry.
+- **Python helper without test** — Python failures are harder to debug from inside Bash.
+
+## Verification (after authoring)
+
+```bash
+# Syntax + shellcheck
+make verify-hooks
+
+# Behavior tests
+uv run pytest tests/test_my_hook.py -q
+
+# Adapter render
+make regen-adapter-templates
+
+# Live install smoke (Claude adapter)
+make test-install-claude
+```
+
+Pre-merge: `make verify` + `cos doctor`.
+
+## Tooling
+
+Scaffold a registry-compliant hook skeleton (sources cos-env, strict mode, log calls):
+`bash scripts/new_hook.sh --name my-guard --category enforcement`
+
+## See also
+
+- [assets/hook-checklist.md](assets/hook-checklist.md) — the authoring + registration gate.
+- [Rule 3 — Hooks source cos-env.sh](../../../docs/governance/critical-rules.md#rule-3--hooks-source-cos-envsh)
+- [Rule 10 — Regenerate derived artifacts](../../../docs/governance/critical-rules.md#rule-10--regenerate-derived-artifacts)
+- [src/core/hooks/registry.yaml](../../../core/hooks/registry.yaml) — SSOT.
+- [Hook Authoring Playbook](../../../docs/playbooks/hook-authoring.md) (if present).
+- [meta-engineering](../meta-engineering/SKILL.md) — three-layer authoring discipline.