coding-os 0.3.2__py3-none-any.whl

templates/laravel/skills/laravel/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: laravel
+tier: stack
+domain: [backend]
+description: Use when creating or modifying PHP files under src/backend/ in a Laravel application — routes, controllers, services, Eloquent models, Form Requests, middleware, and their tests. Triggers on any .php change under src/backend/. Covers thin controllers, the exception Handler as the single error shaper, Form Request validation, Eloquent N+1 avoidance, and mass-assignment safety. Core PHP conventions live in the php skill.
+globs: "src/backend/**/*.php"
+depends_on:
+  - clean-code
+  - backend-fundamentals
+  - php
+last_reviewed: "2026-06-14"
+---
+
+REQUIRED BACKGROUND: You MUST also follow the core `php` skill (language idioms, typing, Composer) and `clean-code`. This skill adds Laravel-specific patterns on top.
+
+# laravel
+
+## Layer contract (matches `structure.tree`)
+
+| Layer | May import | Never |
+|---|---|---|
+| `Http/Controllers/` | services, Form Requests | Eloquent queries, other controllers |
+| `Services/` | models, other services | `Request`/`Response` |
+| `Models/` | the query builder | services, controllers |
+| `Exceptions/Handler.php` | — | building responses anywhere else |
+
+Services stay framework-light so they are unit-testable and a delivery swap
+(HTTP → queue job → console) is a controller-layer-only change.
+
+## Controllers (thin)
+
+- Type-hint a Form Request to validate; the controller receives validated data.
+- Call ONE service method, return the value (Laravel serializes). No response
+  envelope by hand, no try/catch for error shaping.
+
+## Validation
+
+- Every write endpoint has a Form Request; reject fail-closed. Raw
+  `$request->all()` never crosses into a service.
+
+## Eloquent
+
+- `$fillable`/`$guarded` on every model (mass-assignment safety).
+- Eager-load relations (`with()`); a query inside a loop is an N+1 finding.
+- Queries live in models/services, never in controllers.
+
+## Error handling
+
+- ONE shaper: `app/Exceptions/Handler.php` returns the RFC 9457 problem shape
+  (`docs/api-contracts/error-format.md`). 5xx logs full detail; the client never
+  sees a stack trace.
+
+## Testing
+
+- Services: unit tests per public method. Routes: feature tests (happy + error).
+- DB tests use a disposable sqlite/in-memory connection; never the dev database.

templates/laravel/skills/laravel/references/anatomy.md

@@ -0,0 +1,65 @@
+<!-- domain:LARAVEL | layer:reference | ssot:true | updated:2026-06-27 -->
+# Laravel Anatomy
+
+> P: Canonical file map + entity recipes for the Laravel (thin-controller, service-layer) stack.
+> R: Adding any `.php` under `src/backend/`, or routing a backend task.
+> S: Reading frontend / mobile code — wrong stack.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: `src/templates/laravel/scaffold-boundary.yaml`.
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Controller | `app/Http/Controllers/<Name>Controller.php` | `<Name>Controller.php` | its service | Thin — validate, delegate, respond |
+| Form Request | `app/Http/Requests/<Name>Request.php` | `<Name>Request.php` | none | Fail-closed input validation |
+| Service | `app/Services/<Name>Service.php` | `<Name>Service.php` | models | Business logic (the only layer that thinks) |
+| Model | `app/Models/<Name>.php` | `<Name>.php` | none | Eloquent model; `$fillable`/`$guarded` set |
+| Route | `routes/api.php` | `api.php` | controllers | One route group per resource |
+| Error shaper | `app/Exceptions/Handler.php` | `Handler.php` | none | The ONLY error-response shaper |
+| Test | `tests/Feature/<Name>Test.php` | `<Name>Test.php` | source under test | PHPUnit / Pest |
+
+## 3. Entity recipes
+
+### Add a new endpoint
+- **Trigger:** "add `POST /<resource>`".
+- **Files emitted:**
+  1. `app/Http/Controllers/<Name>Controller.php`
+  2. `app/Http/Requests/<Name>Request.php`
+  3. `app/Services/<Name>Service.php`
+- **Steps:**
+  1. Controller type-hints the Form Request (validation runs first) + the service.
+  2. Service does the work, returns a model/DTO; never `$request->all()` into a service.
+  3. Register the route in `routes/api.php`.
+
+### Add a new model
+- **Trigger:** "persist `<Entity>`".
+- **Files emitted:** `app/Models/<Name>.php` + `database/migrations/<ts>_create_<table>.php`.
+- **Steps:**
+  1. Set `$fillable`; eager-load relations with `with()` (no N+1).
+
+### Add a new test
+- **Trigger:** any new endpoint / service.
+- **Files emitted:** `tests/Feature/<Name>Test.php` / `tests/Unit/<Name>Test.php`.
+- **Steps:**
+  1. Feature test hits the route (happy + error); unit-test the service per method.
+
+## 4. Conventions
+
+#### Naming
+- Classes / files: `PascalCase` (`OrderService.php`). Methods: `camelCase`.
+
+#### Test colocation
+- Mirrored: `tests/Feature/<Name>Test.php` mirrors the controller/service.
+
+#### Dependency rules
+- ✓ controller → service → model.
+- ✗ no business logic in routes; no `env()` outside `config/`.
+- ✗ `src/backend/` never imports from `src/frontend/` / `src/mobile/` — share via `src/shared/`.

templates/laravel/stack.yaml

@@ -0,0 +1,66 @@
+version: 1
+id: laravel
+language: php
+label: "Laravel + PHP"
+category: backend
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── composer.json
+    ├── public/
+    │   └── index.php        # front controller (no logic)
+    ├── routes/
+    │   └── api.php          # one route group per resource
+    └── app/
+        ├── Http/Controllers/   # thin — delegate to services
+        ├── Models/             # Eloquent models
+        ├── Services/           # business logic
+        └── Exceptions/Handler.php  # the ONLY error-response shaper
+  notes: "controllers thin, services own logic; the exception Handler is the only error-response shaper; validate via Form Requests"
+primary_skill: laravel
+skills: [laravel]
+
+substitutions:
+  DOMAIN_ROUTES: "Backend→`docs/playbooks/laravel-service.md`"
+  SKILL_ROUTES: "Backend→`laravel`"
+  ENGINEERING_RULE_ROUTING: "Backend→`docs/engineering/laravel-rules.md`, Error format→`docs/api-contracts/error-format.md`"
+  TOOL_ROUTING_IMPL: "`lint-backend`, `test-backend`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-backend + test-backend"
+  VERIFY_BACKEND: "`cd src/backend && composer lint && composer test`"
+  QUICK_ROUTING: |-
+    - Laravel controller / route task → [Laravel Service Playbook](./playbooks/laravel-service.md)
+    - Middleware / Form Request validation → [Laravel Service Playbook](./playbooks/laravel-service.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-LARAVEL` → `./playbooks/laravel-service.md`
+    - `REF:LARAVEL-RULES` → `./engineering/laravel-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-LARAVEL", path: "./playbooks/laravel-service.md", desc: "Laravel service playbook"}
+  - {code: "REF:LARAVEL-RULES",    path: "./engineering/laravel-rules.md", desc: "Laravel engineering rules"}
+
+routing_entries:
+  - "Laravel controller / route task → [Laravel Service Playbook](./playbooks/laravel-service.md)"
+
+rules:
+  - {file: rules/backend.md, globs: ["src/backend/**/*.php"]}
+
+makefile_targets:
+  - {name: lint-backend, cmd: "cd src/backend && composer lint"}
+  - {name: test-backend, cmd: "cd src/backend && composer test"}
+
+verify:
+  - {glob: "src/backend/**/*.php", suites: "lint-backend + test-backend", cmd: "cd src/backend && composer lint && composer test"}
+
+dimensions:
+  - {name: "Laravel controller",        read_files: ["docs/playbooks/laravel-service.md", "docs/engineering/laravel-rules.md"]}
+  - {name: "Route / middleware",        read_files: ["docs/engineering/laravel-rules.md"]}
+  - {name: "Eloquent model",            read_files: ["docs/engineering/laravel-rules.md"]}
+  - {name: "Form Request / validation", read_files: ["docs/engineering/laravel-rules.md", "docs/api-contracts/error-format.md"]}
+
+skill_enforcement:
+  - {globs: ["src/backend/**/*.php"], primary: laravel, secondary: [php, clean-code, backend-fundamentals, api-design, security-web, testing-strategy]}
+  - {globs: ["src/backend/**/Models/**/*.php", "src/backend/**/database/**/*.php"], primary: laravel, secondary: [php, clean-code, db-design]}
+  - {globs: ["src/backend/**/Middleware/**/*.php", "src/backend/**/auth*.php"], primary: laravel, secondary: [php, security-web, clean-code]}

templates/meta/rules/graph-first.md

@@ -0,0 +1,27 @@
+---
+description: Always-active rule when editing meta-repo authoring paths. Codifies the "graph before grep, graph before Read" discipline. Pairs with the graph-explorer skill which has the full decision ladder.
+globs: "src/core/**/*.py,src/cli/**/*.py,src/adapters/**/*.py,src/templates/**/stack.yaml,src/core/hooks/registry.yaml"
+alwaysApply: false
+---
+
+# Graph-First Rule (Meta-Stack)
+
+> **Inviolable**: when the question is *structural* — who calls, what breaks, what connects, rename, trace — call the graph **before** Read or grep. A targeted envelope (references/impact/rename of one symbol) costs a few hundred to a few thousand tokens (heuristic chars/4; measured by `make bench` → `token_cost`) and replaces grepping + reading every matching file — the saving scales with codebase size. Whole-graph dumps (`export`/`communities`) cost far more (tens of thousands of tokens); reach for them deliberately, not for a quick lookup.
+
+| Intent | Tool |
+|---|---|
+| who calls / references | `cos_graph_references(uid)` |
+| rename | `cos_graph_rename_plan(uid, new_name)` |
+| blast radius | `cos_graph_impact(uid, depth=3)` |
+| API/MCP surface | `cos_graph_contracts(kinds=[...])` |
+| data-flow trace | `cos_graph_trace(entry_uid)` |
+| similar / near-clone | `cos_graph_similar(uid)` |
+| find by description | `cos_graph_search(query)` |
+| subsystem map | `cos_graph_communities()` |
+| context around file | `cos_graph_context(uid_or_path, depth=1)` |
+
+**Coverage rule:** `meta.result_truncated` / `walk_truncated == true` ⇒ incomplete — re-query with `limit=total_count` / a higher `visit_limit`. Never act on a truncated envelope.
+
+Grep is correct only for non-symbol literals (error strings, comments, copy) and graph-excluded dirs (`node_modules/`, `.venv/`, lock files).
+
+The full decision ladder, per-task budgets, anti-patterns, and the other 13 tools live in `Skill graph-explorer` and [docs/engineering/graph-hallucination-cures.md](../../../docs/engineering/graph-hallucination-cures.md). Enforcement: `enforce-skill.sh` (BLOCK on core/cli/adapters .py without the skill), `enforce-graph-context.sh` + `enforce-rename-plan.sh` (warn; `COS_ENFORCE_GRAPH_CONTEXT=strict` to block).

templates/meta/rules/hook-author.md

@@ -0,0 +1,19 @@
+---
+description: Rule for authoring shell hooks under src/core/hooks/. Enforces SSOT registration, $COS_* env discipline, fail-closed exception handling, shellcheck compliance, and the regen pipeline that propagates a new hook to every adapter.
+globs: "src/core/hooks/*.sh,src/core/hooks/_helpers/*.py,src/core/hooks/registry.yaml"
+alwaysApply: false
+---
+
+# Hook Authoring Rule
+
+The full anatomy, helper pattern, state-file table, debounce recipes, and test harness live in `Skill hook-authoring` — load it before touching `src/core/hooks/**`. This rule keeps only the non-negotiables:
+
+1. `set -euo pipefail` + `source cos-env.sh` at the top (Rule 3); fail-open stub for `cos_log_hook`.
+2. Never hardcode `.claude/` — use `$COS_AGENT_DIR` / `$COS_STATE_DIR` / `$COS_PANEL_DIR` (Rule 1, P2).
+3. Register ONCE in [src/core/hooks/registry.yaml](../../../core/hooks/registry.yaml) (SSOT), then `make regen-adapter-templates` + re-run the adapter installer.
+4. Exit codes: `0` = pass/warn (stderr shown), `2` = BLOCK with a remediation message. Nothing else.
+5. Enforcement/safety hooks fail closed; observability/reminder hooks fail open (always exit 0).
+6. >~30 lines of logic or any parsing → Python helper in `_helpers/` (bash heredoc deadlock, Rule 8). `grep -oE` needs `|| true` under pipefail.
+7. Codex dispatcher: if the event is coalesced (UserPromptSubmit / Stop / SessionStart), also add the script to `src/adapters/codex/adapter.yaml::hook_dispatchers` + the dispatch loop.
+
+Verify: `make verify-hooks` (syntax + shellcheck) · `uv run pytest tests/test_hooks.py -q` (behavior) · manual: pipe synthetic JSON, assert exit code + stderr.

templates/meta/rules/mcp-tool-author.md

@@ -0,0 +1,18 @@
+---
+description: Rule for authoring or modifying MCP tools (cos_*) in src/core/thinking_os/tools/ or src/core/graph_os/tools/. Enforces envelope contract, safe-tool wrapper, one-line docstring, telemetry layer field, error categories.
+globs: "src/core/thinking_os/tools/*.py,src/core/graph_os/tools/*.py,src/core/board_os/mcp_tools.py,src/core/web/routes/*.py"
+alwaysApply: false
+---
+
+# MCP Tool Authoring Rule (Critical Rule 13)
+
+The worked example, pre-edit moves, and schema traps live in `Skill mcp-tool-authoring` — load it before touching a `cos_*` tool. Contract SSOT: [docs/engineering/mcp-error-envelope.md](../../../docs/engineering/mcp-error-envelope.md) · inventory: [docs/governance/mcp-tool-inventory.md](../../../docs/governance/mcp-tool-inventory.md). Non-negotiables:
+
+1. Every `cos_*` tool: `@safe_tool` + `@mcp.tool()`, returns `ok(data)` / `fail(category, message)` — never a hand-built dict.
+2. Categories (exact strings): `validation` · `not_found` · `unavailable` (retryable) · `conflict` (retryable) · `internal`.
+3. `meta.layer` required on every success (memory/docs/tasks/graph/board/cognition/metrics/learning/routing); `meta.backend_fallback=true` when a fallback answered.
+4. ONE-line docstring on `@mcp.tool` functions only (FastMCP description, ends with a period); none on internal helpers (Rule 12).
+5. New persistent table → append-only migration `vN+1` (Rule 9); never edit a past migration.
+6. New tool → update the inventory doc.
+
+Verify: `uv run --extra rag pytest src/core/thinking_os/tests/ -q` + `python src/core/thinking_os/server.py --test`.

templates/meta/rules/meta-engineering.md

@@ -0,0 +1,17 @@
+---
+description: Meta-project engineering rule — applies when editing core/, cli/, adapters/, or hook scripts in coding-os itself.
+globs: "src/core/**/*.py,src/cli/**/*.py,src/adapters/**/*.py,src/core/hooks/*.sh,src/core/hooks/_helpers/*.py,src/core/scripts/*.sh"
+alwaysApply: false
+---
+
+# Meta-Engineering Rule (coding-os DNA)
+
+Closes the dogfood gap: every principle the meta-repo enforces on consumer projects also enforces on itself. The layer-by-layer detail (thinking_os / graph_os / hooks / cli / adapters / templates) lives in `Skill meta-engineering` — load it for any non-trivial meta-repo edit. Non-negotiables:
+
+1. **Pre-edit:** `cos_graph_context(file, depth=1)` (+ `cos_graph_references` / `_impact` / `_rename_plan` as fits) and `Skill graph-explorer` + `Skill clean-code`; COMPLICATED+ adds `Skill thinking_os`.
+2. **Doc anchor** (Rule 0) — every code edit traces to a documented spec; governance edits need a `governance` / `docs-update` task marker (Rule 7).
+3. **Regen, never hand-edit:** `dimension-registry.md`, `skill-enforcement.md`, `scaffold_manifest.json`, adapter templates, golden tests → `make regen-rules` / `manifest-regen` / `regen-adapter-templates`.
+4. **Adapters:** parity bounded by `adapter.yaml::hook_capabilities`; never import an adapter SDK from `src/core/**` (P8). After adapter edit: `bash src/adapters/<id>/install.sh`.
+5. **CLI:** no hardcoded stack/adapter literals (Rule 11) — data-driven from yaml.
+6. **Tests:** matrix-targeted command only (AGENTS.md § Verification Matrix); never `pytest tests/` mid-task.
+7. **Never** run `cos init` inside the meta-repo; prefer extending an existing hook over adding a near-duplicate.

templates/meta/scaffold-boundary.yaml

@@ -0,0 +1,55 @@
+# Scaffold boundary for the meta stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+#
+# This is the meta-stack ITSELF — i.e. the boundary that applies when
+# coding-os edits its own meta-repo (not a consumer project). The
+# boundary teaches enforce-scaffold-boundary.sh which paths the meta
+# stack is responsible for and which paths are owned by other layers.
+
+version: 1
+stack: meta
+
+# Roots the meta-stack owns. Edits to files under these paths are the
+# meta-stack's responsibility — graph-explorer + clean-code + thinking_os
+# auto-load via skill_enforcement in stack.yaml.
+roots:
+  - src/core/
+  - src/cli/
+  - src/adapters/
+  - src/templates/
+
+# Concrete file globs that constitute meta-repo authoring surface.
+file_patterns:
+  - "src/core/**/*.py"
+  - "src/core/**/*.sh"
+  - "src/core/**/*.yaml"
+  - "src/core/**/*.md"
+  - "src/cli/**/*.py"
+  - "src/adapters/**/*.py"
+  - "src/adapters/**/*.sh"
+  - "src/adapters/**/*.yaml"
+  - "src/templates/**/*.yaml"
+  - "src/templates/**/*.md"
+  - "src/templates/**/*.sh"
+
+# Module imports the meta-stack may rely on.
+imports_from:
+  - src/core/
+  - src/cli/
+
+# Paths the meta-stack must NEVER write into. These belong to runtime
+# state or to other (consumer-shaped) overlays.
+forbids_writing_in:
+  - .coding-os/         # runtime state — managed by hooks, not edits
+  - .claude/            # agent-installed glue (rendered, not authored)
+  - .codex/             # agent-installed glue
+  - dist/               # build output
+  - build/              # build output
+  - coding_os.egg-info/ # build output
+
+notes:
+  - "Anything under core/ is DNA — propagates to every consumer."
+  - "Anything under src/adapters/<id>/ is mRNA — only that one agent."
+  - "Anything under src/templates/<id>/ is phenotype — only that one stack."
+  - "When ambiguous: ask 'would another agent or stack benefit?' — if yes, push to core/."
+  - "Regen targets (src/core/rules/{dimension-registry,skill-enforcement}.md) are NEVER hand-edited; edit src/templates/<stack>/stack.yaml + run `make regen-rules`."

templates/meta/skills/claude-sdk-integration/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: claude-sdk-integration
+tier: stack
+domain: [infra]
+description: Use when authoring code that uses Anthropic's Claude SDK or the claude-agent-sdk inside the meta-repo — primarily src/adapters/claude/sdk_dispatcher.py and the formula composer pipeline that spawns Claude Code sub-sessions. Covers prompt caching, tool-use loop, model selection (Fable 5, Opus 4.8, Sonnet 5, Haiku 4.5), session lifecycle, error handling, and the dispatcher protocol contract every adapter must satisfy. Pairs with python-meta-server, meta-engineering, and the claude-api skill (when working on raw API).
+last_reviewed: "2026-07-01"
+
+---
+
+# claude-sdk-integration
+
+Purpose: Make every interaction with Anthropic's Python SDKs robust,
+cache-friendly, and contract-compliant. The meta-repo dispatches Claude
+sub-sessions via `claude-agent-sdk`; agents editing this surface must
+preserve the protocol that `src/core/thinking_os/dispatcher.py` defines.
+
+Read when: editing any of:
+- `src/adapters/claude/sdk_dispatcher.py` — the SDK dispatcher.
+- `src/adapters/claude/install.sh` — adapter scaffold (when changing SDK options).
+- `src/core/thinking_os/dispatcher.py` — the protocol the dispatcher implements.
+- `src/core/thinking_os/formula_composer.py` — when changing how chains spawn sub-sessions.
+- `src/core/thinking_os/cognition.py` — when wiring `cos_dispatch_formula_run`.
+
+Skip when: editing tests under `tests/test_*sdk*`, mock fixtures.
+
+## Two libraries, two scopes
+
+```
+anthropic       — raw Claude API (Messages, tool use, streaming)
+claude-agent-sdk — high-level: spawns a Claude Code sub-session as a
+                   coroutine, handles tool-use loop, session lifecycle
+```
+
+`src/adapters/claude/sdk_dispatcher.py` uses **claude-agent-sdk** (high
+level). For raw API work (cognition tools that build prompts), use
+`anthropic`.
+
+## Dispatcher protocol contract
+
+`src/core/thinking_os/dispatcher.py` defines:
+
+```python
+class AgentDispatcher(Protocol):
+    def available(self) -> bool: ...
+    async def dispatch(self, request: DispatchRequest) -> DispatchResult: ...
+```
+
+Any adapter dispatcher (Claude, Codex, …) MUST implement this. Breaking
+the signature breaks every cognition flow.
+
+## Hard rules
+
+### 1. Prompt caching (SDK + raw)
+
+Cache markers on stable prefixes:
+
+```python
+messages = [
+    {"role": "user", "content": [
+        {"type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}},
+        {"type": "text", "text": dynamic_question},
+    ]}
+]
+```
+
+Goal: ≥80% cache hit rate on repeated dispatches. The dispatcher should
+keep the system prompt + tool list + role context BEFORE the
+question — never interleave dynamic content into the cached prefix.
+
+### 2. Model selection
+
+Default: `claude-sonnet-5`. Promote to `claude-opus-4-8` (or `claude-fable-5`
+for the most demanding reasoning) only for:
+- COMPLICATED+ tasks via `cos_compose_chain`.
+- Architect / refactorer roles.
+Current ids live in `src/adapters/claude/adapter.yaml::models` (the Hub
+picker SSOT) — check there, not this prose, before hardcoding an id.
+Never use retired model IDs (see platform.claude.com/docs/en/about-claude/model-deprecations).
+
+Haiku (`claude-haiku-4-5-20251001`) for cheap heuristic dispatches
+(formula composition, classification).
+
+### 3. Tool-use loop
+
+When using raw API with tools:
+
+```python
+while response.stop_reason == "tool_use":
+    tool_calls = [b for b in response.content if b.type == "tool_use"]
+    tool_results = [run_tool(tc) for tc in tool_calls]
+    response = client.messages.create(
+        model=...,
+        messages=messages + [
+            {"role": "assistant", "content": response.content},
+            {"role": "user", "content": [
+                {"type": "tool_result", "tool_use_id": tc.id, "content": result}
+                for tc, result in zip(tool_calls, tool_results)
+            ]},
+        ],
+        tools=tools,
+    )
+```
+
+Always check `stop_reason` — `end_turn`, `tool_use`, `max_tokens`,
+`stop_sequence`. NEVER assume the model returned plain text.
+
+### 4. Session lifecycle (claude-agent-sdk)
+
+```python
+from claude_agent_sdk import query
+
+async with query(prompt=..., options=...) as session:
+    async for message in session:
+        if message.type == "assistant":
+            ...
+```
+
+Always use `async with` so the session terminates cleanly. Leaking
+sessions = stuck child processes.
+
+### 5. EvidenceBundle — Rule 16
+
+`cos_dispatch_formula_run` records output via `cos_supervise_record_output`
+which produces a typed `EvidenceBundle`. Don't return plain strings —
+the cognition layer expects the typed shape.
+
+## Pre-edit moves
+
+1. `cos_graph_context("src/adapters/claude/sdk_dispatcher.py", depth=1)` — neighbours.
+2. `cos_graph_references("ClaudeSDKDispatcher.dispatch")` — who calls it.
+3. `cos_graph_impact("ClaudeSDKDispatcher", direction="downstream")` — blast radius before signature change.
+4. Read [docs/adapters/claude-sdk.md](../../../../docs/adapters/claude-sdk.md) for the full SDK contract.
+
+## Anti-patterns
+
+- **Hardcoded model ID strings scattered around** — define in one
+  `MODELS` const, reference everywhere.
+- **No `stop_reason` check** — silently truncated responses.
+- **Calling `client.messages.create` synchronously inside async dispatch** — blocks event loop.
+- **Cache marker on dynamic content** — destroys cache hit rate.
+- **Importing `anthropic.*` in `src/core/**`** — P8 violation; SDK code lives in
+  `src/adapters/claude/`.
+- **Using `claude-agent-sdk` for raw prompts** — overkill; use `anthropic` directly.
+- **Forgetting `--extra claude-sdk` when running tests that hit the dispatcher** — tests skip silently.
+
+## Verification
+
+- `uv run pytest tests/test_claude_dispatcher_options.py tests/test_sdk_presence.py -q`
+- `uv run python src/scripts/smoke_sdk_dispatch.py` — end-to-end smoke (real API call, opt-in via env).
+- After signature change to `dispatch()`: re-run cognition smoke — `cos_dispatch_formula_run` shouldn't break.
+
+## Tooling
+
+Flag stale/deprecated Claude model ids (update the map when the family rotates):
+`python3 scripts/check_model_ids.py src/adapters/claude/*.py`
+
+## See also
+
+- [assets/sdk-checklist.md](assets/sdk-checklist.md) — the SDK integration gate (model/caching/tool-loop/session).
+- [docs/adapters/claude-sdk.md](../../../../docs/adapters/claude-sdk.md)
+- [docs/adapters/claude-deepening-checklist.md](../../../../docs/adapters/claude-deepening-checklist.md)
+- [src/core/thinking_os/dispatcher.py](../../../../core/thinking_os/dispatcher.py)
+- [src/adapters/claude/sdk_dispatcher.py](../../../../adapters/claude/sdk_dispatcher.py)

templates/meta/skills/claude-sdk-integration/assets/sdk-checklist.md

@@ -0,0 +1,27 @@
+<!-- domain:META | layer:asset | ssot:false | updated:2026-06-04 -->
+# Claude SDK Integration Checklist
+
+Run when editing src/adapters/claude/** SDK / dispatcher code.
+
+## Model + caching
+- [ ] Model ids are current — `python3 scripts/check_model_ids.py <files>` → `clean`.
+- [ ] Model selected by tier intent (opus/sonnet/haiku), not a magic string scattered around.
+- [ ] Prompt caching on stable prefixes (system prompt, tools) — the big cost lever.
+- [ ] Max tokens / temperature set deliberately, not defaults-by-accident.
+
+## Tool-use loop
+- [ ] The tool-use loop handles `stop_reason: tool_use` → run tool → feed result → continue.
+- [ ] Tool errors returned to the model as tool_result, not thrown away.
+- [ ] Loop bounded (max iterations) — no infinite tool ping-pong.
+
+## Session + errors
+- [ ] Session lifecycle correct (create → reuse → close); no leaked sessions.
+- [ ] API errors classified (rate limit → backoff; overloaded → retry; 4xx → fail fast).
+- [ ] The dispatcher protocol contract honored (every adapter satisfies the same shape — P8).
+
+## Autonomy boundary (P8)
+- [ ] No adapter SDK imported from `src/core/**`.
+
+## Verify
+- [ ] `make bench-sdk` / `make smoke-sdk` (or the dispatcher smoke) green.
+- [ ] `uv run pytest tests/test_adapters.py -q`.

templates/meta/skills/claude-sdk-integration/scripts/check_model_ids.py

@@ -0,0 +1,97 @@
+"""Flag stale/deprecated Claude model ids in SDK code and suggest current ones.
+
+PURPOSE:      Catch a hardcoded retired model id before it 404s in production —
+              model ids rotate and old ones get deprecated.
+INPUT:        one or more source paths. [--json]
+OUTPUT:       Findings (file:line) on stderr; "clean"/"N finding(s)" on stdout.
+              Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only (regex).
+NOTES:        The CURRENT map is editable below — update it when the model family
+              rotates (this is the one place to change). Pure scan_text() is
+              unit-testable. Spec: docs/adapters/claude-sdk.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# Current generation. Cross-check against src/adapters/claude/adapter.yaml::models
+# (the Hub picker SSOT) whenever the family rotates — this script stays a
+# self-contained stdlib literal (portable to every consumer project) rather
+# than reading that YAML, so the two must be updated together by hand.
+CURRENT = {
+    "fable": "claude-fable-5",
+    "opus": "claude-opus-4-8",
+    "sonnet": "claude-sonnet-5",
+    "haiku": "claude-haiku-4-5-20251001",
+}
+
+# Any claude model id that is NOT one of the current ids → likely stale.
+MODEL_ID = re.compile(r"claude-[a-z0-9.\-]*\d[a-z0-9.\-]*")
+_DATE_SUFFIX = re.compile(r"-\d{8}$")
+
+# A pinned id may appear with or without its trailing snapshot date — e.g.
+# "claude-haiku-4-5-20251001" (Claude API ID) and "claude-haiku-4-5" (Claude
+# API alias) are both current. Tolerate that pairing only; a bare
+# "claude-sonnet-4-6" must NOT slip through as a tolerated variant of
+# "claude-sonnet-5" (that was the bug this checker exists to catch).
+CURRENT_IDS: set[str] = set()
+for _v in CURRENT.values():
+    CURRENT_IDS.add(_v)
+    _undated = _DATE_SUFFIX.sub("", _v)
+    if _undated != _v:
+        CURRENT_IDS.add(_undated)
+
+
+def _suggest(model_id: str) -> str:
+    for tier, cur in CURRENT.items():
+        if tier in model_id:
+            return cur
+    return CURRENT["sonnet"]
+
+
+def scan_text(text: str, *, filename: str = "?") -> list[str]:
+    findings: list[str] = []
+    for n, line in enumerate(text.splitlines(), 1):
+        stripped = line.lstrip()
+        if stripped.startswith(("#", "//", "*", "/*")):
+            continue
+        for m in MODEL_ID.finditer(line):
+            mid = m.group(0)
+            if mid in CURRENT_IDS:
+                continue
+            findings.append(
+                f"{filename}:{n}: stale model id '{mid}' — current is '{_suggest(mid)}'"
+            )
+    return findings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("files", nargs="+")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    all_findings: list[str] = []
+    for path in args.files:
+        try:
+            all_findings.extend(scan_text(Path(path).read_text(encoding="utf-8"), filename=path))
+        except FileNotFoundError:
+            print(f"error: {path} not found", file=sys.stderr)
+            return 2
+
+    for f in all_findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": all_findings, "count": len(all_findings)}))
+    else:
+        print("clean" if not all_findings else f"{len(all_findings)} finding(s)")
+    return 1 if all_findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))