coding-os 0.3.2__py3-none-any.whl

templates/_base/scaffold/docs/governance/docs-first-protocol.md

@@ -0,0 +1,157 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-05-10 -->
+# Docs-First Protocol
+
+> P: Mandatory procedure — docs are SSOT; code follows. Every code edit must trace to a doc and verify the doc still matches BEFORE writing.
+> R: Any Write/Edit on `.py` `.ts` `.tsx` `.go` `.js` `.jsx` `.rs` `.sh` (production code, not tests/migrations/scaffold).
+> S: Editing docs themselves, tests, fixtures, or governance-marked tasks.
+> N: [docs-system.md](docs-system.md), [critical-rules.md](critical-rules.md#rule-0--docs-first), [agent-workflow.md](agent-workflow.md)
+
+> Nav: [Governance Index](./00-index.md) | [Docs Index](../00-index.md)
+
+## Why
+
+Code rots in isolation. Docs rot when nothing reads them. The protocol below binds both directions so a code change CAN'T land without the spec being current — and a doc edit surfaces every code site that drifts.
+
+Two rules in the critical-rules table back this:
+
+- **Rule 0 — Docs-first** ([critical-rules.md#rule-0](critical-rules.md#rule-0--docs-first)): every code Write/Edit must trace to a `.doc-anchor` (BLOCKING hook).
+- **Rule 19 — Docs are the contract** ([critical-rules.md#rule-19](critical-rules.md#rule-19--docs-are-the-contract--never-extend-code-beyond-doc-spec)): edit the doc BEFORE extending the code; `enforce-doc-sync.sh` surfaces drift PostToolUse.
+
+This file is the procedural reference both rules point to.
+
+## The protocol — five steps, every code edit
+
+```
+1. CLASSIFY → 2. LOCATE DOC → 3. READ DOC → 4. ANCHOR → 5. EDIT
+                  ↓ (no doc?)
+                  2b. WRITE DOC FIRST → loop back to 3
+```
+
+### 1. Classify
+
+Run the Complexity Gate (Q1 Cynefin × Q2 dimensions). `CLEAR 1` (trivial typo / docstring) is the only path that skips Steps 2–4 — record it via:
+
+```bash
+bash src/core/hooks/write-state.sh .coding-os/<agent>/.thinking_os-gate "CLEAR 1"
+```
+
+Anything else → continue.
+
+### 2. Locate the doc
+
+Order of attempts — stop at the first hit:
+
+| Question | Tool |
+|---|---|
+| "Which doc is SSOT for the topic I'm about to edit?" | `cos_doc_headers_by(domain=..., ssot="true")` |
+| "What's the spec?" | `cos_doc_search "<topic>"` |
+| "What does the read_next chain say to read?" | `cos_graph_context "doc:file:docs/..."` |
+| "Which doc has the function I'm changing?" | `cos_graph_references "<symbol>"` then follow `doc_anchor` edges |
+| "Is there a playbook for this kind of work?" | Load matching playbook skill |
+
+If nothing matches → go to **2b**.
+
+### 2b. No doc? Write doc first.
+
+Open [`_templates/doc-cheat-sheet.md`](_templates/doc-cheat-sheet.md), pick the layer (adr · playbook · spec · policy · runbook · reference), create the file, commit it as a separate change BEFORE the code change. Rationale: a code change that needs a NEW spec is by definition not "trivial" — splitting them keeps blame + review clean.
+
+Anti-pattern: writing code "first to see what shape it takes" then back-filling the spec. Use a `*spike*` or `*exploratory*` task marker if you genuinely need this path; the hook then exempts you, but the code is throwaway by contract.
+
+### 3. Read the doc
+
+Cheapest read first — `cos_doc_header(path)` returns frontmatter + `Purpose / Read when / Skip when / Read next` for ~100 tokens. Only full-read the body if the header signals the doc is in-scope.
+
+If the doc cites other docs via `Read next:` / `> N:` lines, walk **one hop** of those. Do not depth-first the whole graph — token waste.
+
+### 4. Anchor
+
+Record the doc path(s) you actually read into the session anchor:
+
+```bash
+bash src/core/hooks/write-state.sh \
+  "$COS_AGENT_DIR/.doc-anchor" \
+  "$(cat <<'EOF'
+ses-<session-id> task:<task-id>
+- docs/engineering/<spec>.md
+- docs/api-contracts/<contract>.md
+EOF
+)"
+```
+
+`cos task-start TASK-NNN` does this automatically from the task file's `Read First` section. Set the anchor by hand only for ad-hoc work covered by `*docs-update*` / `*governance*` markers.
+
+If the anchor exists but came from a previous session, the hook BLOCKS — re-run `cos task-start TASK-NNN` to refresh.
+
+### 5. Edit
+
+- Smallest correct change (P1, P4).
+- Behavior must match the doc you anchored to. If reality forces divergence → STOP, edit the doc first, refresh the anchor, then continue.
+- After the edit, `enforce-doc-sync.sh` (PostToolUse) lexically scans for symbols you removed/renamed that still appear in docs. Treat its WARNs as TODOs — either update the doc or revert the rename.
+
+## What the hooks actually enforce
+
+| Hook | Phase | Action | Trigger |
+|---|---|---|---|
+| `enforce-doc-anchor.sh` | PreToolUse Write/Edit | **BLOCK** | Code file edit with no populated `.doc-anchor` or `CLEAR 1` gate |
+| `enforce-doc-sync.sh` | PostToolUse Write/Edit | WARN | Code symbol removed/renamed/signature-changed AND doc still mentions it |
+| `check-doc-size.sh` | PostToolUse Write/Edit | WARN | Doc exceeds per-layer line budget |
+| `auto-regen-doc-index.sh` | PostToolUse Write/Edit | regen | `docs/<dir>/00-index.md` rebuilt from frontmatter (5s debounce) |
+| `auto-reindex-docs.sh` | PostToolUse Write/Edit | reindex | RAG chunks + graph nodes refreshed for the touched file |
+| `nudge-docs-first.sh` | UserPromptSubmit | hint | Prompt mentions code change with no `.doc-anchor` yet → recommends `cos_doc_search` first |
+
+Bypass paths (use sparingly, all logged):
+
+- `CLEAR 1` gate — trivial fixes only.
+- `*spike*` / `*exploratory*` / `*scratch*` task name — throwaway code.
+- `*docs-update*` / `*governance*` task name — when the edit IS the doc.
+- `touch $COS_AGENT_DIR/.doc-anchor-override` — one-shot, consumed on use.
+
+## When the doc is wrong
+
+The doc is SSOT, but SSOT is not infallible. When code reality contradicts the doc:
+
+1. Stop the code change.
+2. Verify the contradiction with `cos_graph_contracts` (for HTTP/MCP surfaces) or `cos_graph_impact` (for code symbol churn).
+3. Edit the doc, increment frontmatter `updated:`.
+4. The prior decision stays recoverable through git history — supersede with a normal commit; never rewrite published history.
+5. Refresh the anchor, then resume the code change.
+
+This is **not** a bypass — it is the protocol. A code agent that updates a doc to match reality is doing higher-value work than one that ships code matching nothing.
+
+## Domain-specific entry points
+
+| Edit target | First doc to read |
+|---|---|
+| `src/core/thinking_os/**` | [docs/architecture/meta-project.md](../architecture/meta-project.md), [docs/engineering/mcp-error-envelope.md](../engineering/mcp-error-envelope.md) |
+| `src/core/graph_os/**` | [docs/engineering/graph_os-queries.md](../engineering/graph_os-queries.md), [docs/engineering/graph-hallucination-cures.md](../engineering/graph-hallucination-cures.md) |
+| `src/core/board_os/**` | [docs/governance/task-lifecycle.md](task-lifecycle.md), [docs/engineering/board-thinking-os-coupling.md](../engineering/board-thinking-os-coupling.md) |
+| `src/core/hooks/**` | [docs/engineering/hooks-reference.md](../engineering/hooks-reference.md), `src/core/hooks/registry.yaml` |
+| `src/adapters/<id>/**` | [docs/playbooks/adapter-authoring.md](../playbooks/adapter-authoring.md), [docs/adapters/claude-sdk.md](../adapters/claude-sdk.md) |
+| `src/templates/<id>/**` | [docs/playbooks/template-authoring.md](../playbooks/template-authoring.md), [docs/governance/anatomy-contract.md](anatomy-contract.md), [docs/governance/scaffold-boundary-contract.md](scaffold-boundary-contract.md) |
+| `src/cli/**` | [docs/architecture/meta-project.md](../architecture/meta-project.md) |
+
+Beyond `src/core/**`, the `Dimension Registry` routes per-stack edits to the right doc set.
+
+## Verification
+
+After any non-trivial code change, before `task-done`:
+
+1. `make docs-lint` — frontmatter + nav + dead-link sweep.
+2. Confirm `cos_doc_search "<changed concept>"` still returns the doc you anchored to.
+3. If the change altered a contract — re-run the contract producer test (`tests/test_mcp_schema_traps.py` for MCP, `tests/test_adapter_parity.py` for adapters).
+
+## Anti-patterns
+
+- ❌ Editing code, then editing the doc to match.
+- ❌ Treating `enforce-doc-anchor` BLOCKs as friction; bypassing with overrides.
+- ❌ Anchoring to a doc you didn't actually read (cargo-cult anchor).
+- ❌ Filing a `*spike*` task to dodge anchor enforcement on real production work.
+- ❌ Renaming a symbol without checking `cos_graph_references` for doc citations first.
+
+## See also
+
+- [Rule 0 — Docs-first](critical-rules.md#rule-0--docs-first)
+- [Rule 19 — Docs are the contract](critical-rules.md#rule-19--docs-are-the-contract--never-extend-code-beyond-doc-spec)
+- [docs-system.md](docs-system.md) — taxonomy, headers, navigation
+- `doc-cheat-sheet.md` — pick the right layer
+- [agent-workflow.md](agent-workflow.md) — Core Loop (Classify → Orient → Plan → Execute → Verify)

templates/_base/scaffold/docs/governance/docs-system.md

@@ -0,0 +1,151 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-05-08 -->
+# Documentation System Policy
+
+Purpose: Define the canonical documentation taxonomy, naming rules, file headers, and navigation contract for all active docs.
+Read when: Creating, moving, splitting, or validating documentation files.
+Skip when: You only need to consume a playbook or domain doc without changing the docs system.
+Read next: [docs-first-protocol.md](docs-first-protocol.md), [agent-workflow.md](agent-workflow.md), [task-lifecycle.md](task-lifecycle.md)
+
+> Nav: [Docs Index](../00-index.md)
+
+## SSOT Direction — Docs First, Code Follows
+
+Docs are the source of truth; code is the implementation that must match. The full read-anchor-edit procedure lives in [docs-first-protocol.md](docs-first-protocol.md) and is enforced by:
+
+- **Rule 0** ([critical-rules.md#rule-0](critical-rules.md#rule-0--docs-first)) — `enforce-doc-anchor.sh` BLOCKS code Write/Edit without a populated `.doc-anchor`.
+- **Rule 19** ([critical-rules.md#rule-19](critical-rules.md#rule-19--docs-are-the-contract--never-extend-code-beyond-doc-spec)) — `enforce-doc-sync.sh` WARNs PostToolUse when code drift leaves docs stale.
+- **`nudge-docs-first.sh`** — UserPromptSubmit nudge that recommends `cos_doc_search` / `cos_doc_header` when a code-edit intent is detected and no anchor exists.
+
+If you are about to edit code, stop here and read [docs-first-protocol.md](docs-first-protocol.md) first.
+
+## Layer Model
+
+- `index` — navigation hub, parent/child routing only
+- `playbook` — task workflow with read selection guide and verification
+- `spec` — canonical product/content requirements
+- `policy` — process or governance rules
+- `reference` — supporting factual reference, not primary truth
+- `adr` — immutable decision record
+- `task` — execution log for a specific work item
+
+## Naming Rules
+
+- Root index: `docs/00-index.md` (master navigation hub).
+- Sub-directory indexes: `00-index.md` in directories that have many files (architecture, playbooks, api-contracts).
+- Per-file `<file>.INDEX.md` sidecars are NOT canonical — only `00-index.md` and `section-index.md` are recognized index forms.
+- Task SSOT: `docs/tasks/TASK-###-slug.md` (one detail file per active or completed task). Live board view: `cos board` (DB-mirrored from these files). There is no flat `docs/tasks.md` index.
+- Playbooks: `kebab-case.md`
+- ADRs: `ADR-###-kebab-case.md`
+- Tasks: `TASK-###-slug.md`
+- Historical archive docs: `YYYY-MM-topic.md` under `governance/archive/`
+- Other active docs: `kebab-case.md`
+- No version suffixes in filenames (`*-V1.md`, `*-v2.md`). Versioning lives in frontmatter `updated:` only.
+
+## Header Contract
+
+Every file inside `docs/` starts with:
+
+```html
+<!-- domain:XXX | layer:index|playbook|spec|policy|reference|adr|task | ssot:true|ref | updated:YYYY-MM-DD -->
+```
+
+## Opening Block Contract
+
+Immediately after the H1, every active doc includes these four lines. Two equivalent forms are accepted; pick one per file.
+
+**Long form** (default):
+
+- `Purpose:`
+- `Read when:`
+- `Skip when:`
+- `Read next:`
+
+**Short form** (token-tight, ~30% fewer header bytes — recommended for high-traffic routing files):
+
+- `> P:`
+- `> R:`
+- `> S:`
+- `> N:`
+
+`docs-lint` accepts either form. `cos_doc_header` (MCP) parses both into the same structured response (`opening_block.purpose` / `read_when` / `skip_when` / `read_next`). The `md_links` graph extractor emits `read_next` edges from either.
+
+These lines must let an agent decide within the first screenful whether to keep reading.
+
+## Playbook Read-Pack Limit
+
+Playbook read packs must not exceed 10 files. Most tasks need 3-6; complex multi-domain tasks may reach 10. If more are needed, split into a sub-playbook or a domain-specific routing hub.
+
+## Navigation Rules
+
+- `docs/00-index.md` is the single master navigation hub.
+- Directories with many files (architecture, prd, api-contracts, pages-content-spec) keep their own `00-index.md`. Smaller directories (engineering, design, governance, playbooks, ops) may not need an index.
+- Every file should include a `> Nav:` breadcrumb on the line after the opening block.
+  - Files inside a directory with a local index → Nav links to `./00-index.md`.
+  - Files inside a directory without an index → Nav links to the root `../00-index.md`.
+  - Index files → Nav links to parent index or root.
+- Use relative links only.
+- Use `REF:*` shortcodes from `docs/_meta/foundation-map.md` in task `Read First` sections where shorter references improve readability.
+
+## Task File Rules
+
+**Single SSOT (Scrumban):**
+
+- `docs/tasks/TASK-###-slug.md` — **canonical detail file**. One per active or completed task. Holds frontmatter (swimlane / kind / epic / labels / status / priority / appetite / depends_on / blocked_by / references), Outcome, Read First, Acceptance, Work Log, Rollback. Authored from `docs/governance/_templates/task-detail.md`. Token cap: warn ≥1.5k, block ≥3k (Rule 14).
+- `cos board` (or `cos board --web`) — **live view** rendered from `src/core/board_os/db.py`. The DB is a derived mirror of the detail files (mtime-incremental sync); the file is SSOT, the DB is the index.
+- Status transitions go through `cos task-move` / `cos task-start` / `cos task-done` (or the MCP `cos_task_*` family). These write the detail-file frontmatter and the DB atomically — never edit status by hand in only one place.
+- There is no flat `docs/tasks.md` index. The legacy index file has been retired in favor of `cos board` + per-task detail files.
+
+**Lifecycle:**
+
+- A task is created via `cos task-create` (writes both the detail file and the DB row).
+- Once a task is in_progress, completed, or blocked → the detail file under `docs/tasks/` is REQUIRED. DB-only mode exists in `src/core/board_os/workflow.py` but is reserved for migrations and tests, never normal authoring.
+- Companion docs (checklists, research annexes that would break the 3k cap) use `layer:reference`, link back to the parent task, and never carry canonical status.
+- `docs/governance/_templates/task-detail.md` is a template reference, not a live task record. Do not edit it as if it were a task.
+
+## Architecture Boundary
+
+- `docs/architecture/` contains evergreen architecture and ADRs only.
+- Temporary migration history and audit trails live under `docs/governance/archive/`.
+- Open risks and blind spots live in `docs/governance/risk-register.md`.
+
+## Changes Log Policy
+
+- `changes.log` lives at repo root and tracks completed task summaries.
+- Max 5 lines per task entry: title + reason + key changes + files.
+- Detailed breakdowns belong in the task file, not changes.log.
+- When changes.log exceeds 200 lines, archive entries older than 30 days to `docs/governance/archive/YYYY-MM-changes.md`.
+
+## Extension Protocol
+
+When adding a new domain to the project, follow this order:
+
+1. Architecture doc → `docs/architecture/NN-<domain>.md`
+2. Playbook → `docs/playbooks/<domain>.md`
+3. API contracts → `docs/api-contracts/<domain>-endpoints.md` (if applicable)
+4. Routing entry → `AGENTS.md` Core Loop § Execute
+5. REF codes → `docs/_meta/foundation-map.md`
+6. Index updates → `docs/00-index.md`
+7. Run `make docs-lint` to verify
+
+## Authoring a NEW Doc — Read This First
+
+Before creating any new file under `docs/`, read [`_templates/doc-cheat-sheet.md`](_templates/doc-cheat-sheet.md). It contains:
+
+- The decision tree (intent → layer → directory → token budget).
+- Mandatory frontmatter + opening block contract.
+- Required sections per layer (adr · playbook · runbook · post-mortem · spec · policy · reference · task).
+- Anti-patterns (code dumps, version-suffix files, "future work" sections).
+- Token-efficiency rules — the audience is the next agent that has to act on the doc.
+
+Available templates under `docs/governance/_templates/`:
+
+- `task-detail.md` — task execution log.
+- `runbook-template.md` — operational SOP for an alert / incident type.
+- `post-mortem-template.md` — blameless retrospective for a specific incident.
+- `playbook-template.md` — repeatable workflow.
+- `security-review-template.md` — OWASP-aligned per-change checklist.
+- `doc-cheat-sheet.md` — decision guide for new docs (read first).
+
+## Decision History
+
+A doc's decision history lives in git: every edit is a commit, reverts are `git revert` commits, and `git log --follow <path>` reconstructs the full timeline. There is no separate trail table — git is the single forensic record.

templates/_base/scaffold/docs/governance/gdpr-compliance.md

@@ -0,0 +1,66 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:{{DATE}} -->
+# GDPR / Privacy Compliance
+
+Purpose: Define data handling, consent, and retention rules for personal data in the project.
+Read when: Adding any feature that collects, stores, processes, or shares user-identifiable data.
+Skip when: Working on infrastructure or internal-only features with no PII.
+Read next: Engineering rules for logging (PII redaction) and security architecture.
+
+> Nav: [Docs Index](../00-index.md)
+
+## Personal Data Inventory
+
+<!-- List every type of personal data the project collects. Example:
+
+- Email address (auth, marketing, transactional)
+- Name (account profile, billing)
+- IP address (audit log, rate limiting, fraud detection)
+- Payment info (handled by provider, never stored locally)
+-->
+
+(empty — populate when first PII is collected)
+
+## Lawful Basis
+
+For each data type above, specify lawful basis (consent / contract / legitimate interest / legal obligation).
+
+## Retention Rules
+
+- Define maximum retention period per data type
+- Define automated deletion policy
+- Define user-initiated deletion (right to erasure) flow
+
+## Consent Management
+
+- How is consent obtained? (signup checkbox, cookie banner, etc.)
+- How is consent recorded? (timestamp, version of terms agreed to)
+- How is consent withdrawn?
+
+## Data Subject Rights
+
+Provide a path for users to:
+
+- Access their data (export)
+- Rectify their data (edit)
+- Erase their data (account deletion)
+- Object to processing
+- Port their data (machine-readable export)
+
+## Data Processor Inventory
+
+<!-- List every third-party that receives user data. Example:
+
+- Payment provider (Stripe, PayPal): payment data
+- Email provider (Postmark, SendGrid): email + name
+- Analytics (PostHog, Plausible): IP, session, user agent
+- Hosting (AWS, Cloudflare R2): all stored data
+-->
+
+(empty — populate as integrations are added)
+
+## Breach Response
+
+- Detection: monitoring + alerting
+- Containment: rotate credentials, isolate affected systems
+- Notification: notify regulator within 72 hours, notify affected users without undue delay
+- Documentation: log incident in `governance/archive/`

templates/_base/scaffold/docs/governance/mcp-tool-inventory.md

@@ -0,0 +1,112 @@
+<!-- domain:DOCS | layer:reference | ssot:true | updated:{{DATE}} -->
+# MCP Tool Inventory
+
+Purpose: Route AI agents to the correct tools for research, validation, and automation tasks.
+Read when: Starting a task that requires external research, documentation lookup, package checks, or browser verification.
+Skip when: The task is purely local code manipulation (use built-in tools directly) or the playbook already specifies tool routing.
+Read next: The domain playbook matching your task type.
+
+> Nav: [Docs Index](../00-index.md) | [AGENTS](../../AGENTS.md)
+
+## Runtime Snapshot
+
+- Verified on `{{DATE}}`
+- Standard runtime must match this doc before it is treated as available truth
+- Agent checks available tools via its session's deferred tool list
+
+## Coding-OS Provided
+
+### `coding-os` MCP server
+
+Cognitive OS — memory, graph, board, and cognition tools. SQLite backend at `.coding-os/coding-os.db`. All tools use `cos_*` prefix.
+
+<!-- Module-gated tool families (TASK-501 / DOC-3): a disabled module's MCP tools
+     are removed from the live tool list, so their inventory lines are stripped at
+     init too. Markers strip to byte-identical output when all modules are on. -->
+- **Health (1):** `cos_health` — DB stats, schema version, FTS5 status
+<!-- if-module:memory -->
+- **Memory (5):** `cos_search` (5-signal ranked), `cos_timeline` (chronological), `cos_details` (full record), `cos_promote` (pattern → rule), `cos_observation_record`
+- **Learning (4):** `cos_learn_extract`, `cos_learn_suggest`, `cos_learn_validate`, `cos_learn_narrative`
+- **Retrieval Quality (4):** `cos_retrieval_cite`, `cos_retrieval_learn`, `cos_retrieval_quality`, `cos_retrieval_enrichment_check`
+<!-- end-if -->
+<!-- if-module:observability -->
+- **Metrics (3):** `cos_metric_record`, `cos_metric_query`, `cos_metric_trend`
+<!-- end-if -->
+<!-- if-module:cognition -->
+- **Routing & Roles (6):** `cos_route_model`, `cos_route_skill`, `cos_compose_chain`, `cos_role_info`, `cos_situation_detect`, `cos_classify_prompt`
+<!-- end-if -->
+<!-- if-module:docs -->
+- **Docs RAG (3):** `cos_doc_search`, `cos_doc_header`, `cos_doc_headers_by`
+<!-- end-if -->
+<!-- if-module:graph -->
+- **Graph (17):** `cos_graph_query`, `cos_graph_resolve`, `cos_graph_context`, `cos_graph_communities`, `cos_graph_path`, `cos_graph_impact`, `cos_graph_references`, `cos_graph_rename_plan`, `cos_graph_similar`, `cos_graph_detect_changes`, `cos_graph_entrypoints`, `cos_graph_trace`, `cos_graph_contracts`, `cos_graph_export`, `cos_graph_centrality`, `cos_graph_ranking`, `cos_graph_doctor`
+<!-- end-if -->
+<!-- if-module:tasks -->
+- **Board / Tasks (13):** `cos_task_board`, `cos_task_create`, `cos_task_move`, `cos_task_pick`, `cos_task_search`, `cos_task_by_filter`, `cos_task_dependencies`, `cos_task_dependents`, `cos_task_wip_check`, `cos_task_daily`, `cos_task_retro`, `cos_task_reposition`, `cos_work_log_append`
+<!-- end-if -->
+<!-- if-module:cognition -->
+- **Cognition (5):** `cos_supervise`, `cos_supervise_record_output`, `cos_dispatch_formula`, `cos_dispatch_formula_run`, `cos_dispatch_parallel_run`
+- **Analysis (4):** `cos_analyze_task`, `cos_ambiguity_check`, `cos_backtrack_log`, `cos_discovery`
+- **Misc (3):** `cos_traceability`, `cos_takeover`, `cos_digest_regenerate`
+<!-- end-if -->
+
+## Recommended External MCPs
+
+These are commonly useful but not required. Install via Claude Code MCP settings.
+
+- `context7` — Official framework and library documentation. Use first for framework docs.
+- `ref` — URL-targeted documentation lookup and direct page reads.
+- `playwright` — Browser automation and route-state verification.
+
+## Built-in Tools
+
+- File system → Read, Write, Edit, Glob, Grep
+- Command execution → Bash (make targets, git, scripts)
+- Web search → WebSearch (current facts, fallback when MCP unavailable)
+- Web fetch → WebFetch (scrape single URL to markdown)
+- Subagents → Agent tool (read-only research/inventory/verification only; write work runs single-agent — never use `isolation: "worktree"`)
+
+## Task-to-Tool Selection Matrix
+
+- Framework/library docs → context7 first, ref as fallback, WebSearch as last resort
+<!-- if-module:memory -->
+- Memory search / past patterns → `cos_search`, `cos_timeline`, `cos_learn_suggest`
+<!-- end-if -->
+<!-- if-module:tasks -->
+- Task board / status → `cos_task_board`, `cos_task_search`, `cos_task_by_filter`
+- Task create/move/complete → `cos_task_create`, `cos_task_move`, `cos_work_log_append`
+<!-- end-if -->
+<!-- if-module:graph -->
+- File/concept relationships → `cos_graph_context`, `cos_graph_impact`, `cos_graph_references`
+- Rename planning → `cos_graph_rename_plan` (callers + impact before any rename)
+<!-- end-if -->
+<!-- if-module:docs -->
+- Doc search (semantic) → `cos_doc_search`; single-file frontmatter → `cos_doc_header`
+<!-- end-if -->
+<!-- if-module:cognition -->
+- Model/skill routing → `cos_route_model`, `cos_route_skill`, `cos_compose_chain`
+- Role chain for complex task → `cos_compose_chain` → writes `.coding-os/<agent>/.roles`
+- Formula dispatch → `cos_dispatch_formula`, `cos_dispatch_formula_run`
+<!-- end-if -->
+<!-- if-module:observability -->
+- Agent performance metrics → `cos_metric_record`, `cos_metric_query`, `cos_metric_trend`
+<!-- end-if -->
+<!-- if-module:memory -->
+- Breakthrough narrative → `cos_learn_narrative`
+<!-- end-if -->
+- Code pattern in repo → Grep (pattern) or Glob (filename)
+- Visual UI verification → playwright (if installed)
+- Lints/tests/builds → Bash (make targets per playbook)
+
+## Usage Rules
+
+1. **Local SSOT first.** Only use external tools when local docs are insufficient or recency matters.
+2. **Prefer official sources:** context7 or ref for framework docs. WebSearch for current facts.
+3. **Check runtime first:** verify tool availability via session's deferred tool list before depending on any non-built-in MCP.
+4. **Escalation path:** built-in tools → coding-os MCP → optional MCPs → WebSearch/WebFetch fallback.
+5. **Record findings** when research changes architecture: log date, versions, and source URL in task file.
+6. **Do not document aspirational tooling as available** unless runtime verification confirms it.
+
+## Update Policy
+
+Review this inventory when a new MCP is added or an existing one is removed. Update the `Verified on` date and the relevant section.

templates/_base/scaffold/docs/governance/risk-register.md

@@ -0,0 +1,26 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:{{DATE}} -->
+# Risk Register
+
+Purpose: Canonical list of active project, architecture, and workflow risks that still require mitigation or follow-up.
+Read when: Planning work, reviewing blind spots, or deciding whether a task can proceed safely.
+Skip when: The task is tightly scoped and all relevant risks are already captured in the task file.
+Read next: Relevant ADR in `../architecture/adr/` or the domain architecture doc.
+
+> Nav: [Docs Index](../00-index.md) | [ADR Index](../architecture/adr/00-index.md)
+
+## Active Risks
+
+<!-- Format: `RISK-NNN` Description (one line). Add owner and mitigation if known.
+     Example:
+     - `RISK-001` Backup automation needs operational owner before production.
+     - `RISK-002` Monitoring stack RAM footprint may exceed VPS budget.
+-->
+
+(empty — populate as risks are identified)
+
+## Usage Rules
+
+- Risks stay here while active.
+- Once resolved, move the resolution into the relevant ADR, architecture doc, or change log entry and remove or downgrade the risk.
+- Historical risk analysis belongs in archive docs, not active architecture indexes.
+- Each risk needs an ID (`RISK-NNN`), a one-line description, and ideally an owner and mitigation plan.