coding-os 0.3.2__py3-none-any.whl

templates/meta/skills/hook-authoring/assets/hook-checklist.md

@@ -0,0 +1,30 @@
+<!-- domain:META | layer:asset | ssot:false | updated:2026-06-04 -->
+# Hook Authoring Checklist
+
+Run before shipping a new or modified hook. Full procedure: docs/playbooks/hook-authoring.md.
+
+## Scaffold + structure
+- [ ] `bash scripts/new_hook.sh --name <id> --category <c>` used (or matches its shape).
+- [ ] `set -euo pipefail` at the top.
+- [ ] Sources `cos-env.sh` (Rule 3); `cos_log_hook` enter/ok/warn calls.
+- [ ] Reads stdin via `cos_read_stdin_bounded`; `jq` with safe defaults.
+
+## Agent-agnostic (Rule 1, P2)
+- [ ] Never hardcodes `.claude/` — uses `$COS_AGENT_DIR`/`$COS_STATE_DIR`/`$COS_PANEL_DIR`.
+- [ ] `grep -oE`/`grep -c` wrapped with `|| true` (no pipefail kill on zero match).
+- [ ] No `$(python3 - <<HEREDOC)` — extract to `_helpers/<name>.py` (Rule 8).
+- [ ] `Path(...).resolve()` before `relative_to()` (Rule 5) in any helper.
+
+## Exit codes + fail mode
+- [ ] Exit `0` = pass/warn (stderr message); `2` = BLOCK. No other codes.
+- [ ] Enforcement/safety = fail-closed (block); observability/reminder = fail-open (always exit 0).
+- [ ] Debounce via a per-session/per-input marker where it would fire repeatedly.
+
+## Registration + render (Rule 10)
+- [ ] Registered ONCE in `src/core/hooks/registry.yaml` with id/script/category/phase/timeout/events.
+- [ ] `make regen-adapter-templates` run; Codex dispatcher updated if the event coalesces.
+- [ ] `bash src/adapters/claude/install.sh` (or `make dogfood-full`) re-rendered.
+
+## Verify
+- [ ] `make verify-hooks` (bash -n + shellcheck warning) — clean.
+- [ ] Manual smoke: pipe a synthetic JSON input, assert exit code + stderr.

templates/meta/skills/hook-authoring/scripts/new_hook.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# new_hook.sh — PURPOSE: scaffold a registry-compliant hook skeleton.
+# INPUT: --name <hook-id> [--category safety|enforcement|observability|reminder|
+#   cognition|retrieval|meta] [--root src/core/hooks] [--force].
+# OUTPUT: <root>/<name>.sh (sources cos-env, set -euo pipefail, stdin read,
+#   log calls) + the registry.yaml snippet to paste. DEPS: bash. NOTES:
+# idempotent; the script still must be registered by hand in registry.yaml then
+# `make regen-adapter-templates`. Spec: docs/playbooks/hook-authoring.md.
+set -euo pipefail
+IFS=$'\n\t'
+
+log() { printf '%s\n' "$*" >&2; }
+usage() { echo "usage: $0 --name <hook-id> [--category C] [--root DIR] [--force]" >&2; exit 2; }
+
+name=""
+category="enforcement"
+root="src/core/hooks"
+force=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name)     name="${2:?--name needs a value}"; shift 2 ;;
+    --category) category="${2:?--category needs a value}"; shift 2 ;;
+    --root)     root="${2:?--root needs a value}"; shift 2 ;;
+    --force)    force=1; shift ;;
+    -h|--help)  usage ;;
+    *) echo "unknown arg: $1" >&2; usage ;;
+  esac
+done
+[[ -n "$name" ]] || { echo "error: --name is required" >&2; usage; }
+[[ "$name" =~ ^[a-z0-9-]+$ ]] || { echo "error: --name must be kebab-case" >&2; exit 2; }
+
+mkdir -p "$root"
+target="$root/$name.sh"
+if [[ -e "$target" && "$force" -ne 1 ]]; then
+  echo "error: $target exists (use --force)" >&2
+  exit 1
+fi
+
+{
+  printf '#!/usr/bin/env bash\n'
+  printf '# %s.sh — <one-line purpose>.\n' "$name"
+  printf '#\n# <2-3 line description: events, what it reads/writes, fail-open vs closed.>\n'
+  printf 'set -euo pipefail\n\n'
+  printf 'source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true\n'
+  printf 'if ! command -v cos_log_hook >/dev/null 2>&1; then cos_log_hook() { :; }; fi\n\n'
+  printf 'cos_log_hook %s enter || true\n\n' "$name"
+  printf 'INPUT="$(cos_read_stdin_bounded 2)"\n'
+  printf '# shellcheck disable=SC2034  # placeholders — wire into your decision below\n'
+  printf 'FILE_PATH=$(echo "$INPUT" | jq -r '"'"'.tool_input.file_path // empty'"'"' 2>/dev/null || echo "")\n'
+  printf '# shellcheck disable=SC2034\n'
+  printf 'MARKER="${COS_AGENT_DIR}/.%s-marker"   # never hardcode .claude/ (Rule 1)\n\n' "$name"
+  printf '# Decide; warn (exit 0) vs block (exit 2).\n'
+  printf 'if false; then\n'
+  printf '  echo "warning: <message>" >&2\n'
+  printf '  cos_log_hook %s warn || true\n' "$name"
+  printf '  exit 0\n'
+  printf 'fi\n\n'
+  printf 'cos_log_hook %s ok || true\n' "$name"
+  printf 'exit 0\n'
+} > "$target"
+chmod +x "$target"
+
+log "wrote $target"
+log ""
+log "Now register it in src/core/hooks/registry.yaml (SSOT):"
+log "  - id: $name"
+log "    script: $name.sh"
+log "    description: <one line>"
+log "    category: $category"
+log "    phase: <PreToolUse|PostToolUse|UserPromptSubmit|SessionStart|Stop>"
+log "    timeout: 5"
+log "    events: [{event: PreToolUse, matcher: 'Write|Edit', status_message: '<msg>'}]"
+log ""
+log "Then: make regen-adapter-templates && make verify-hooks"
+printf '%s\n' "$target"

templates/meta/skills/mcp-tool-authoring/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: mcp-tool-authoring
+tier: stack
+domain: [architecture]
+description: Author production-grade MCP (Model Context Protocol) tools for the coding-os meta-repo. Use when adding a new `cos_*` tool to `src/core/thinking_os/tools/`, `src/core/graph_os/tools/`, `src/core/board_os/mcp_tools.py`, or `src/core/web/routes/` — the four canonical authoring surfaces. Enforces the @safe_tool envelope (Rule 13), name prefix `cos_` (Rule 2), append-only schema migrations (Rule 9), single-line docstring (Rule 12), deferred-tool schema discipline. Pairs with python-meta-server, graph-explorer (load before edits), and clean-code.
+last_reviewed: "2026-05-11"
+---
+
+# mcp-tool-authoring
+
+Purpose: Make every new `cos_*` MCP tool match the contract every other tool follows. Drift here breaks the agent (deferred-tool schema lookups), the envelope (Rule 13), or the migration (Rule 9). One canonical authoring path keeps the ~80 tools coherent.
+
+Read when: editing files matching:
+- `src/core/thinking_os/tools/*.py` — MCP tools registered with the FastMCP server.
+- `src/core/graph_os/tools/*.py` — graph-side tools (`cos_graph_*`).
+- `src/core/board_os/mcp_tools.py` — Scrumban / task tools.
+- `src/core/web/routes/*.py` — HTTP routes that wrap an MCP tool for the Hub UI.
+- `src/core/thinking_os/server.py` — when registering a new tool module.
+
+Skip when: editing tests, helpers, or non-tool internals.
+
+## The Five Hard Contracts
+
+Every `cos_*` tool MUST satisfy ALL of:
+
+### 1. Name prefix `cos_` (Rule 2)
+
+```python
+@mcp.tool
+@safe_tool
+async def cos_search(query: str, limit: int = 5) -> dict:
+    ...
+```
+
+Names without the `cos_` prefix are silently rejected from the tool inventory. The inventory is the SSOT for `docs/governance/mcp-tool-inventory.md` (regenerated, not hand-edited).
+
+### 2. Envelope shape via `@safe_tool` (Rule 13)
+
+Every tool returns `ok(data)` or `fail(category, message)`. The decorator does this for you:
+
+```python
+from core.thinking_os.tools._shared import safe_tool, ok, fail
+
+@mcp.tool
+@safe_tool  # converts raw exceptions to fail() envelopes
+async def cos_search(query: str, limit: int = 5) -> dict:
+    if not query:
+        return fail("invalid_input", "query is required")
+
+    rows = await _db.search(query, limit=limit)
+    return ok({"results": rows, "count": len(rows), "meta": {"layer": "memory"}})
+```
+
+`fail` categories are documented in [docs/engineering/mcp-error-envelope.md](../../../docs/engineering/mcp-error-envelope.md): `invalid_input`, `not_found`, `unavailable`, `permission_denied`, `internal_error`, `rate_limited`. Don't invent new categories without updating the contract doc.
+
+### 3. ONE-line docstring (Rule 12)
+
+The docstring becomes the FastMCP tool description shown to the agent. It's the agent's only hint about what the tool does. Format:
+
+```python
+@mcp.tool
+@safe_tool
+async def cos_search(query: str, limit: int = 5) -> dict:
+    """Search agent memory + learned patterns. Returns top-K ranked observations."""
+    ...
+```
+
+**No docstrings on internal helpers** (Rule 12). Internal helpers are private and self-documenting via naming.
+
+The description body (visible via `ToolSearch` lookup) can be richer — it's the docstring extended in the `description=` argument of `@mcp.tool(description=...)` if you need more than one line.
+
+### 4. Append-only schema (Rule 9)
+
+If your tool reads/writes the DB and needs a new table or column:
+
+- Migrations live as **callable functions in [src/core/thinking_os/database.py](../../../core/thinking_os/database.py)** (the `MIGRATIONS` list), not standalone `.sql` files. Append a new entry at the end of the list — never edit or reorder past entries.
+- **Adding a column to an existing table** → also a new migration entry (`ALTER TABLE ... ADD COLUMN ... NULL`). Backfill in a separate migration if non-trivial.
+- The migration runner (`run_migrations` in `database.py`) is idempotent by `schema_version` row; each entry runs at most once per DB.
+
+Verify with `uv run --extra rag pytest src/core/thinking_os/tests/test_db.py -q`.
+
+### 5. Type hints, no `Any` for tool args
+
+FastMCP introspects type hints to generate the JSON schema agents use. `Any` defeats this. Required:
+
+```python
+async def cos_doc_search(
+    query: str,
+    source_types: str = "",  # CSV, not list — FastMCP nested-array trap
+    limit: int = 5,
+    mode: str = "auto",       # "auto" | "semantic" | "lexical"
+) -> dict:
+    ...
+```
+
+**Schema traps** (the ones every author trips):
+
+| Trap | Wrong | Right |
+|---|---|---|
+| List args break across runtimes | `tags: list[str]` | `tags_csv: str = ""` then split server-side |
+| Optional list | `tags: list[str] \| None = None` | `tags_csv: str = ""` |
+| TaskSignals dict field types | mixed-type dicts | `dict[str, str]` and parse server-side |
+| Pydantic model arg | `task: Task` | flat primitives, construct server-side |
+
+See [docs/engineering/mcp-schema-traps.md](../../../docs/engineering/mcp-schema-traps.md) for the live list.
+
+## Authoring Steps (in order)
+
+### Step 1 — graph-first
+
+```bash
+# Find related tools
+cos_graph_query "search OR retrieval"
+
+# Read the neighborhood of a similar tool you'd model on
+cos_graph_context "code:function:src/core/thinking_os/tools/memory.py::cos_search" depth=1
+
+# Confirm no name collision
+cos_graph_references "cos_search"  # in case you're tempted to reuse a name
+```
+
+### Step 2 — doc-first (Rule 19)
+
+Add the tool to its inventory section in `docs/governance/mcp-tool-inventory.md` **before** writing code. Inventory entry shape:
+
+```markdown
+### `cos_my_new_tool`
+- **Category:** memory | retrieval | tasks | graph | cognition | observability | audit
+- **Purpose:** One-sentence what it does.
+- **Args:** `arg1: type — description. arg2: type — description (default).`
+- **Returns:** `ok({data shape})` / `fail(category, message)`.
+- **Source:** [`src/core/thinking_os/tools/<module>.py::cos_my_new_tool`](../../core/thinking_os/tools/<module>.py)
+```
+
+The doc is the contract. The code below implements it.
+
+### Step 3 — choose the home module
+
+| Concern | Module |
+|---|---|
+| Agent memory / learning | `src/core/thinking_os/tools/memory.py` |
+| Metrics / observability of agent | `src/core/thinking_os/tools/metrics.py` |
+| Doc / RAG retrieval | `src/core/thinking_os/tools/docs.py` |
+| Tasks / Scrumban | `src/core/board_os/mcp_tools.py` |
+| Knowledge graph queries | `src/core/graph_os/tools/<name>.py` |
+| Routing / classification / cognition | `src/core/thinking_os/tools/routing.py` / `cognition.py` |
+| Hub HTTP wrapper | `src/core/web/routes/<name>.py` |
+
+If your tool spans concerns, prefer the most specific module + use cross-imports — don't create a new module unless ≥3 tools justify it.
+
+### Step 4 — register the tool
+
+The MCP server registers tool modules in [src/core/thinking_os/server.py](../../../core/thinking_os/server.py). New module = new `import_module` call in the registration list.
+
+### Step 5 — write the tool
+
+```python
+# src/core/thinking_os/tools/my_module.py
+from __future__ import annotations
+
+from core.thinking_os.tools._shared import fail, ok, safe_tool
+
+
+async def cos_my_new_tool(query: str, limit: int = 5) -> dict:
+    """One-line description shown to the agent."""
+    if not query or len(query) > 1024:
+        return fail("invalid_input", "query must be 1..1024 chars")
+
+    rows = await _do_the_work(query, limit)
+    return ok({
+        "results": rows,
+        "count": len(rows),
+        "meta": {
+            "layer": "memory",  # or "docs" / "tasks" / "graph"
+            "source": "thinking_os.my_new_tool",
+            "tokens_estimated": _estimate_tokens(rows),
+            "truncated": len(rows) >= limit,
+        },
+    })
+
+
+async def _do_the_work(query: str, limit: int) -> list[dict]:
+    # Private helper — no docstring.
+    ...
+
+
+def register(mcp) -> None:
+    """Called by server.py during startup."""
+    mcp.tool(safe_tool(cos_my_new_tool))
+```
+
+### Step 6 — tests
+
+Three tests minimum per tool:
+
+```python
+# src/core/thinking_os/tests/test_my_module.py
+import pytest
+
+async def test_cos_my_new_tool_returns_envelope_on_success() -> None:
+    result = await cos_my_new_tool(query="test")
+    assert result["ok"]
+    assert "results" in result["data"]
+    assert "meta" in result["data"]
+
+
+async def test_cos_my_new_tool_rejects_empty_query() -> None:
+    result = await cos_my_new_tool(query="")
+    assert not result["ok"]
+    assert result["error"]["category"] == "invalid_input"
+
+
+async def test_cos_my_new_tool_rejects_oversize_query() -> None:
+    result = await cos_my_new_tool(query="x" * 2000)
+    assert not result["ok"]
+    assert result["error"]["category"] == "invalid_input"
+```
+
+Matrix command: `uv run --extra rag pytest src/core/thinking_os/tests/test_my_module.py -q`.
+
+### Step 7 — regen + smoke
+
+```bash
+# Regenerate the public tool inventory
+make regen-rules
+
+# Re-run MCP server self-test (instantiates server, asserts all tools registered)
+python src/core/thinking_os/server.py --test
+
+# Run the matrix command for the module you edited
+uv run --extra rag pytest src/core/thinking_os/tests/ -q
+```
+
+## Deferred-Tool Schema (Claude-specific)
+
+All ~80 `cos_*` tools are **deferred** in the Claude adapter — schemas are NOT loaded at session start. Calling a tool the first time in a session requires:
+
+```
+ToolSearch("select:cos_my_new_tool")
+```
+
+This is a runtime concern, not an authoring one — but you should know that adding a tool also means the agent will need a ToolSearch call to use it for the first time per session. The docstring is the tool's only "before-Schema-Load" identifier.
+
+## Meta-tool patterns
+
+| Pattern | Example | When to use |
+|---|---|---|
+| **Search** | `cos_search`, `cos_doc_search` | Returning ranked rows from one layer |
+| **Get-by-id / get-detail** | `cos_details`, `cos_doc_header` | Single-object fetch |
+| **Mutation** | `cos_observation_record`, `cos_task_create` | Creates a row, returns id |
+| **Action** | `cos_task_move`, `cos_supervise` | Side-effecting state change |
+| **Aggregate / query** | `cos_metric_query`, `cos_log_query` | Filter + group, no mutation |
+| **Composite / router** | `cos_route_skill`, `cos_classify_prompt` | Dispatches/classifies by signal |
+
+When in doubt, model your tool on the closest existing one.
+
+## Anti-patterns (reject in review)
+
+- **Tool without `@safe_tool`** — raw exceptions reach the agent, not the envelope.
+- **Tool name not prefixed `cos_`** — silently dropped from inventory.
+- **Multi-line docstring** — clutters FastMCP description, breaks Rule 12.
+- **Editing a past migration** — Rule 9 violation. New migration only.
+- **`Any` type hints** — defeats schema generation.
+- **List-typed args** — schema flakiness across runtimes; use CSV strings.
+- **`print` in tool body** — pollutes MCP stderr. Use `logger`.
+- **Returning a string instead of `ok(data)`** — every consumer expects the envelope.
+- **Side effects in a "search" tool** — search/get must be read-only. Use a mutation tool for writes.
+- **Tool that requires the client to know an internal id** — return resolvable identifiers (paths, uids, slugs), not row PKs.
+
+## Verification (after authoring)
+
+```bash
+# Single-tool test
+uv run --extra rag pytest src/core/thinking_os/tests/test_<your_module>.py -q
+
+# Module-level
+uv run --extra rag pytest src/core/thinking_os/tests/ -q
+
+# MCP self-test (registers + validates all tools)
+python src/core/thinking_os/server.py --test
+
+# Regen inventory
+make regen-rules
+```
+
+Pre-merge: also `make verify` (full sweep).
+
+## Tooling
+
+Scaffold a compliant `cos_*` tool stub (cos_ prefix, @safe_tool, ok/fail, one-line docstring):
+`python3 scripts/new_tool.py --name widget --layer graph`
+
+## See also
+
+- [assets/mcp-tool-checklist.md](assets/mcp-tool-checklist.md) — the authoring + registration gate.
+- [Rule 13 — MCP Envelope](../../../docs/governance/critical-rules.md#rule-13--mcp-tool-response-envelope)
+- [MCP Error Envelope contract](../../../docs/engineering/mcp-error-envelope.md)
+- [MCP Tool Inventory (SSOT)](../../../docs/governance/mcp-tool-inventory.md)
+- [MCP Schema Traps](../../../docs/engineering/mcp-schema-traps.md)
+- [python-meta-server](../python-meta-server/SKILL.md) — Python authoring conventions for this codebase.
+- [graph-explorer](../../../core/skills/graph-explorer/SKILL.md) — pre-edit graph context.

templates/meta/skills/mcp-tool-authoring/assets/mcp-tool-checklist.md

@@ -0,0 +1,29 @@
+<!-- domain:META | layer:asset | ssot:false | updated:2026-06-04 -->
+# MCP Tool Authoring Checklist
+
+Run before shipping a new `cos_*` tool. Full procedure: docs/playbooks/mcp-tool-authoring.md.
+
+## Contract
+- [ ] Name prefixed `cos_` (Rule 2).
+- [ ] Wrapped with `@safe_tool`; returns `ok(data)` / `fail(category, message)` (Rule 13).
+- [ ] `fail` category ∈ validation / not_found / unavailable / conflict / internal.
+- [ ] One-line docstring ending in a period (Rule 12) — it's the agent-facing description.
+- [ ] `meta.layer` set on success; `meta.backend_fallback=true` when a fallback answered.
+- [ ] `bash scripts/new_tool.py --name <t> --layer <l>` used (or matches its shape).
+
+## Schema (if persistent state)
+- [ ] New table → `src/core/thinking_os/migrations/vN+1_<name>.sql` (append-only, Rule 9).
+- [ ] Never edited a past migration.
+
+## Pre-edit graph moves
+- [ ] `cos_graph_context` on the target tools file (depth=1).
+- [ ] `cos_graph_references` if changing an existing tool's signature.
+
+## Register + document
+- [ ] Tool importable + registered on the MCP server.
+- [ ] `docs/governance/mcp-tool-inventory.md` updated with the new tool.
+- [ ] Deferred-schema note: callers run `ToolSearch("select:<tool>")` before first use.
+
+## Verify
+- [ ] `uv run --extra rag pytest src/core/thinking_os/tests/ -q`.
+- [ ] `python src/core/thinking_os/server.py --test` (MCP self-test).

templates/meta/skills/mcp-tool-authoring/scripts/new_tool.py

@@ -0,0 +1,74 @@
+"""Scaffold a compliant cos_* MCP tool stub (envelope + naming + docstring).
+
+PURPOSE:      Emit a tool that already obeys Rule 2 (cos_ prefix), Rule 12
+              (one-line docstring), and Rule 13 (@safe_tool + ok/fail envelope)
+              so the author fills logic, not boilerplate.
+INPUT:        --name <tool>  (without the cos_ prefix; added if missing)
+              --layer <memory|docs|tasks|graph|board|cognition|...> (meta.layer)
+              [--out <path>]  append to a file instead of printing.
+OUTPUT:       The tool source on stdout (or appended to --out). Exit 0; 2 usage.
+DEPENDENCIES: stdlib only.
+NOTES:        Pure render() is unit-testable. Register the tool + update
+              docs/governance/mcp-tool-inventory.md by hand. Spec:
+              docs/playbooks/mcp-tool-authoring.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+
+TEMPLATE = '''\
+@safe_tool
+@mcp.tool()
+def {fn}(arg: str) -> dict:
+    """{summary}"""
+    if not arg:
+        return fail("validation", "arg must be non-empty")
+    result = {fn}_impl(arg)
+    return ok({{"result": result, "meta": {{"layer": "{layer}"}}}})
+'''
+
+
+def normalize(name: str) -> str:
+    name = re.sub(r"[^a-z0-9_]", "_", name.lower()).strip("_")
+    return name if name.startswith("cos_") else f"cos_{name}"
+
+
+def render(name: str, layer: str) -> str:
+    fn = normalize(name)
+    summary = (
+        fn.replace("cos_", "").replace("_", " ").strip().capitalize() + " — one-line description."
+    )
+    return TEMPLATE.format(fn=fn, layer=layer, summary=summary)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--name", required=True)
+    parser.add_argument("--layer", default="memory")
+    parser.add_argument("--out", default=None)
+    args = parser.parse_args(argv)
+
+    if not args.name.strip():
+        print("error: --name must be non-empty", file=sys.stderr)
+        return 2
+
+    code = render(args.name, args.layer)
+    if args.out:
+        with open(args.out, "a", encoding="utf-8") as fh:
+            fh.write("\n\n" + code)
+        print(args.out)
+    else:
+        sys.stdout.write(code)
+    print(
+        "reminder: add @safe_tool/ok/fail imports from tools._shared; register + "
+        "update docs/governance/mcp-tool-inventory.md",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

templates/meta/skills/meta-engineering/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: meta-engineering
+tier: stack
+domain: [governance]
+description: Use when authoring inside coding-os itself — core/, cli/, adapters/, templates/, or src/core/hooks/. Enforces three-layer mental model (DNA → mRNA → phenotype), graph-first edit discipline, regen pipelines, dogfood verification, and the contract that meta-repo changes propagate to every consumer project. Pairs with graph-explorer (always primary), clean-code, and thinking_os.
+last_reviewed: "2026-05-11"
+
+---
+
+# meta-engineering
+
+Purpose: Internalise that **every line of code in this repo eventually
+ships to N consumer projects** and act accordingly. Without this skill,
+agents treat meta-repo files like a normal app — they grep, they edit,
+they break consumers.
+
+Read when: editing `src/core/**/*.py`, `src/cli/**/*.py`, `src/adapters/**/*.py`,
+`src/core/hooks/*.sh`, `src/core/hooks/_helpers/*.py`, `src/templates/**/stack.yaml`,
+or `src/core/hooks/registry.yaml`.
+
+Skip when: editing `docs/`, `tests/`, or `.coding-os/` runtime state.
+
+## The DNA → mRNA → phenotype contract
+
+```
+core/             ── DNA          ─ agent + stack agnostic
+src/adapters/<id>/    ── mRNA         ─ per-agent translation
+src/templates/<id>/   ── phenotype    ─ per-stack overlay
+            ↓ cli/  (factory)
+consumer project  ── organism     ─ Django+Claude, Next+Codex, …
+```
+
+**Before any edit, ask:** which layer does this belong in? Mis-layering
+is the most common meta-repo bug. If unsure, default to **lower** layer
+(more reuse) and split when a single agent or stack genuinely diverges.
+
+## Mandatory pre-edit moves (order matters)
+
+1. **Graph context first** — non-negotiable for `src/core/**/*.py`,
+   `src/cli/**/*.py`, `src/adapters/**/*.py`:
+   - `cos_graph_context(file_or_uid, depth=1)` — what's connected.
+   - `cos_graph_references(uid)` — who depends on the symbol.
+   - For a rename: `cos_graph_rename_plan(uid, new_name)` BEFORE first Edit.
+   - For a refactor: `cos_graph_impact(uid, depth=3)`.
+   The `enforce-graph-context.sh` hook records the marker for you.
+
+2. **Skill stack** — load `Skill graph-explorer` (primary), then
+   `Skill clean-code`. COMPLICATED+ adds `Skill thinking_os`.
+
+3. **Doc anchor** — every code edit must trace to a documented spec
+   (PRD / playbook / engineering rule). The `enforce-doc-anchor.sh`
+   hook BLOCKS edits without a `.doc-anchor` marker.
+
+4. **Task marker** — governance / hook-registry / rule-SSOT edits
+   require `.task-current` to name a `governance|docs-update|template-update`
+   task. `block-protected-files.sh` enforces.
+
+5. **Complexity Gate** — record before any `.py` edit:
+   `bash src/core/hooks/write-state.sh .coding-os/<agent>/.thinking_os-gate "COMPLICATED 3"`.
+
+## Layer-specific rules
+
+### `src/core/thinking_os/**`
+- All MCP tools wrapped with `@safe_tool` — return `ok(data) / fail(category, message)` (Rule 13).
+- One-line docstring on `@mcp.tool` only (Rule 12). Internal helpers: no docstrings.
+- Schema migrations append-only — new tables go to `vN+1`, never edit past (Rule 9).
+- Verify: `uv run --extra rag pytest src/core/thinking_os/tests/ -q && python src/core/thinking_os/server.py --test`.
+
+### `src/core/graph_os/**`
+- Tool layer stays backend-agnostic — never leak raw SQL into the `cos_graph_*` callers. Single backend today (SQLite); the abstraction stays so a future store can plug in.
+- Extractors idempotent on `uid`, short-circuit via `file_index_state` content hash.
+- Verify: `uv run --extra graph_os pytest src/core/graph_os/tests/ -q`.
+
+### `src/core/hooks/**`
+- Every new hook:
+  - sources `cos-env.sh` (Rule 3),
+  - registered ONCE in `src/core/hooks/registry.yaml` (SSOT),
+  - declares `event/matcher` in registry,
+  - never hardcodes `.claude/` — use `$COS_AGENT_DIR` / `$COS_STATE_DIR` (Rule 1, P2).
+- After registry edit: `make regen-adapter-templates` then `bash src/adapters/<id>/install.sh`.
+- Verify: `make verify-hooks` (passes shellcheck warning level + bash -n).
+
+### `src/cli/**`
+- No hardcoded stack/adapter literals (Rule 11). Data-driven via
+  `src/templates/<id>/stack.yaml` and `src/adapters/<id>/adapter.yaml`.
+- Test invariants: `uv run pytest tests/test_no_hardcoded_anthropic.py tests/test_no_hardcoded_stacks.py tests/test_cli.py -q`.
+
+### `src/adapters/<id>/**`
+- Adapter parity is bounded by the agent runtime's actual hook
+  capabilities — declare them in `adapter.yaml::hook_capabilities`.
+- Never import an adapter SDK from `src/core/**` (P8).
+- After edit: `bash src/adapters/<id>/install.sh` (or `make dogfood-full`).
+
+### `src/templates/<id>/**`
+- Conform to `src/core/schemas/stack.schema.json`.
+- After edits to `dimensions:` or `skill_enforcement:`: `make regen-rules`.
+- Hand-editing `src/core/rules/dimension-registry.md` or `skill-enforcement.md` directly is forbidden — both are regen targets.
+
+### `src/core/web/**`
+- Routes prefix `/api/` for HTTP, `/api/stream/` for SSE.
+- Every endpoint returns the same MCP envelope shape (`{ok, data|error}`).
+- UI in `src/core/web/ui/` — Vite + React 18 + Sigma.js.
+
+## Anti-patterns
+
+- **Bypassing graph layer** by loading `clean-code` only and editing
+  blindly — `enforce-skill.sh` BLOCKS this for `src/core/**/*.py`.
+- **Adding a hook script without registry entry** — won't be rendered to any adapter.
+- **Hand-editing regenerated rules** — drift from source-of-truth template.
+- **Hardcoding `.claude/` in src/core/** — use `$COS_AGENT_DIR`. Audit
+  hook `block-hardcoded-literals.sh` catches most cases.
+- **Running `cos init` inside meta-repo** — would scaffold a duplicate.
+- **Rename without `cos_graph_rename_plan`** — `enforce-rename-plan.sh` warns; expect missed call-sites.
+
+## Test discipline (matrix-targeted)
+
+Use only the verification matrix command for the layer you changed
+(AGENTS.md § Verification Matrix). Never `pytest tests/ -q` mid-task —
+that runs ~2K tests in ~6 minutes (full sweep is pre-merge only).
+
+## Propagation matrix
+
+| Edit | Reaches consumer via | Latency |
+|---|---|---|
+| `src/core/hooks/*.sh` | Live symlink — no rebuild | Immediate |
+| `src/core/thinking_os/**` | MCP server restart | One restart |
+| `src/core/rules/*.md`, `src/core/skills/**` | Live symlink + `cos update` | `cos update` |
+| `src/adapters/<agent>/**` | `bash src/adapters/<agent>/install.sh` | Manual |
+| `src/templates/<stack>/**` | `cos update` + `make manifest-regen` | Manual |
+| `src/cli/**` | new `cos` invocations pick up changes | Immediate (after `uv tool install --editable .`) |
+
+## When to escalate
+
+Stop and surface to user when:
+- A `core/` change breaks backward compatibility.
+- An adapter change affects another adapter.
+- An MCP tool signature changes without a migration plan.
+- You discover a stack-specific assumption inside `core/`.
+
+## Tooling
+
+Classify a path's layer + how an edit reaches consumers:
+`python3 scripts/which_layer.py src/core/hooks/foo.sh`
+
+## See also
+
+- [assets/meta-edit-checklist.md](assets/meta-edit-checklist.md) — the pre/post edit gate.
+- [docs/architecture/meta-project.md](../../../docs/architecture/meta-project.md) — full meta-project architecture.
+- [docs/governance/critical-rules.md](../../../docs/governance/critical-rules.md) — all 21 critical rules.
+- [docs/engineering/graph-hallucination-cures.md](../../../docs/engineering/graph-hallucination-cures.md) — why and when to call `cos_graph_*`.
+- [src/core/skills/graph-explorer/SKILL.md](../../../core/skills/graph-explorer/SKILL.md) — graph decision ladder.