coding-os 0.3.2__py3-none-any.whl

templates/_base/scaffold/docs/governance/_templates/task-detail.md

@@ -0,0 +1,61 @@
+---
+# Lean task template — see docs/phase-l-scrumban-task-system-plan.md
+#
+# AGENT: All four categorization axes are required (`epic` optional).
+# `validate-task-frontmatter.sh` will reject this file on Write/Edit if any
+# enum is wrong, swimlane is unknown, or `labels` overlaps `kind` values.
+#
+# Prefer creating tasks via `cos_task_create` MCP tool over hand-writing
+# this YAML — the tool fills, validates, and persists in one call.
+id: {{TASK_ID}}
+title: "{{TITLE}}"
+swimlane: {{SWIMLANE}}            # DOMAIN — must exist in scrumban-config.yaml::swimlanes
+kind: {{KIND}}                    # TYPE — feature | bug | chore | spike | docs | refactor | test | security
+epic: {{EPIC|null}}               # INITIATIVE — optional (e.g. phase-l, mvp, oncall-q2)
+labels: {{LABELS|[]}}             # FREE TAGS — must NOT contain kind values
+priority: {{PRIORITY|P2}}         # P0 critical | P1 high | P2 normal | P3 low
+appetite: "{{APPETITE|1d}}"       # Shape Up: 30m | 2h | 1d | 3d | 1w | 1cy
+status: icebox                    # always start here; transition via cos_task_move
+created: {{TODAY}}
+started: null
+completed: null
+agent_session: null
+depends_on: {{DEPENDS_ON|[]}}     # hard block — these must complete first
+blocked_by: []                    # runtime block — agent fills with reason
+references: {{REFERENCES|[]}}     # soft relationship; sibling tasks
+---
+
+# {{TASK_ID}}: {{TITLE}}
+
+**Outcome (one sentence):** <!-- AGENT: ONE concrete sentence describing what
+will be true when this task is done. Not a re-spec. Not a goal. A measurable
+end-state with metric where possible. Bad: "improve auth". Good: "users log
+in with email + OTP, P95 < 500ms, on iOS + Android + web". -->
+
+## Read First
+<!-- AGENT: ONLY links to existing docs/files. NEVER inline content from them.
+If no relevant doc exists: (a) note "no doc — exploratory", or (b) create
+the doc first via Formula 4 then link to it. Rule 15 forbids duplication. -->
+
+- [path/to/doc.md](relative/path) — short reason
+- [path/to/code.py](relative/path) — short reason
+
+## Acceptance (G/W/T) — *this IS the Definition of Done*
+<!-- AGENT: 1–3 Given/When/Then statements. Each becomes a test case.
+When ALL pass, task is Done. Not "perfect" — Done. Scope-creep =
+new task via cos_task_create. -->
+
+- **Given** <precondition>
+- **When** <action>
+- **Then** <observable outcome with concrete metric>
+
+## Work Log
+<!-- AGENT: AUTO-APPENDED by capture-work-log.sh hook on Write/Edit.
+Format: `- YYYY-MM-DD [agent-id | ses-NNNNNNNN]: <120-char summary>`.
+NEVER rewrite. NEVER reformat. Append-only. Codex sessions: call
+cos_work_log_append() explicitly (no PostToolUse hook). -->
+
+## Rollback
+<!-- AGENT: Optional but recommended. If purely additive: "Additive only.
+Revert commit." If has migrations or shared-state mutations: list explicit
+undo steps. -->

templates/_base/scaffold/docs/governance/agent-workflow.md

@@ -0,0 +1,101 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-05-08 -->
+# Agent Workflow Policy
+
+Purpose: Domain routing, task protocol, escalation, and memory contract — supplements `AGENTS.md` § Core Loop.
+Read when: Multi-domain task, blast-radius doubt, escalation, or memory-flow question.
+Skip when: Task clearly routed; AGENTS.md fragments suffice.
+Read next: `task-lifecycle.md`, the matching playbook in `../playbooks/`.
+
+> Nav: [Docs Index](../00-index.md) | [Docs System](./docs-system.md)
+
+> Canonical execution loop is in `AGENTS.md` § Core Loop and `AGENTS.md` § Request Routing. This file holds policy detail not repeated there.
+
+## Domain Classification Checklist
+
+Multi-domain task — resolve by priority:
+
+1. Security-sensitive? → security overlay required regardless of primary domain.
+2. Backend models or API? → backend playbook (if installed).
+3. Frontend components or pages? → frontend playbook (if installed).
+4. Content, copy, or SEO? → content playbook (if installed).
+5. Docs, governance, or workflow? → docs governance playbook (if installed).
+6. Research / validation only? → research & validation playbook (if installed).
+
+When two domains share weight, route to the higher blast-radius domain first.
+
+**Blast radius ranking** (highest → lowest):
+
+1. Database schema — affects all consumers, hard to roll back.
+2. Backend API contracts — affects frontend + external integrations.
+3. Backend business logic — data integrity, API responses.
+4. Frontend state/routing — UX + navigation.
+5. Frontend UI/styling — appearance only.
+6. Documentation — no runtime impact.
+
+## Task Protocol (Scrumban)
+
+| Transition | Command | Effect |
+|---|---|---|
+| icebox → in_progress | `cos task-start TASK-<id>` | Marks the detail file `in_progress`, writes `.coding-os/<agent>/.task-current`, mirrors to the board DB, enforces WIP cap. |
+| in_progress → testing | `cos task-move TASK-<id> --to testing` | Signals that the change is built and awaiting verification. |
+| → done | `cos task-done TASK-<id>` | Validates Acceptance, appends Work Log, mirrors to the board DB, appends a `changes.log` entry. |
+| → blocked | `cos task-move TASK-<id> --to blocked --reason "why"` | Records the blocker on the detail file and on the board. |
+| Session bootstrap | `cos daily` | Surfaces WIP, blockers, age, and roadmap phase. |
+
+The board state lives in `docs/tasks/TASK-<id>-<slug>.md` (canonical) and is mirrored to `.coding-os/coding-os.db` (derived index). There is no flat `docs/tasks.md` index; `cos board` renders the current state on demand.
+
+`make task-*` wrappers exist only as thin aliases for the `cos task-*` commands; new automation should call `cos` directly.
+
+## Change Initiation Path
+
+Every non-trivial change follows this order — no skipping:
+
+1. **PRD/spec** — define *what* and *why* (edit the doc first; Rule 19)
+2. **Requirements / acceptance criteria** — atomic, testable
+3. **Schema / migrations** — data shape before any code
+4. **Code** — implement against spec
+5. **Docs sync** — update any doc that drifted (`enforce-doc-sync.sh` surfaces these)
+
+If two sources conflict: higher blast-radius wins (see Blast Radius ranking above). Update the lower-rank doc — never the higher.
+
+## Minimal-Read & Context Hygiene
+
+- Do not read an entire domain folder when one index file routes correctly.
+- Stop reading when a file no longer changes the decision.
+- Playbook Read Selection Guide caps at 10 files (most tasks 3–6).
+- After reading: extract the fact into the task detail's Notes; drop the raw file from working memory.
+- After commands (test/lint/build): keep pass/fail + key errors only; discard full output.
+- Subagent results must be condensed summaries (≤2000 tokens), never raw dumps.
+
+## Script Output Format
+
+Task and infrastructure scripts use standardized prefixes:
+
+- `OK: <message>` — success
+- `ERROR: <message>` — fatal (exits 1)
+- `WARN: <message>` — non-fatal (stderr)
+- `INFO: <message>` — informational
+
+## Escalation Rules
+
+- Log contradictions and missing truth in `docs/_meta/questions.md`.
+- Stop when product intent is not derivable from SSOT — never invent schema names, route shapes, or copy.
+- RETRY_LIMIT — second identical failure with no new evidence → `cos task-move TASK-NNN --to blocked`.
+
+<!-- if-module:memory -->
+## Memory & Learning (Thinking OS)
+
+Self-learning layer on the thinking_os MCP server (`.coding-os/coding-os.db`).
+
+**Data flow:** Auto-Capture (per tool call) → Outcome Record (per task) → Learning Loop (every 10 tasks) → Memory Inject (next session).
+
+**3-layer progressive disclosure** (memory queries):
+
+1. `cos_search` — compact index (~50 tokens/result).
+2. `cos_timeline` — chronological context (~150 tokens).
+3. `cos_details` — full observation (~500 tokens).
+
+**Learning Loop** (conditional, non-blocking): extracts patterns from outcomes, suggests rules at 3+ similar failures, tunes routing weights per domain × complexity. Runs every 10 completed tasks.
+
+**Outcome types:** `success`, `rework`, `partial`, `blocked` — recorded for every task including blocked.
+<!-- end-if -->

templates/_base/scaffold/docs/governance/anatomy-contract.md

@@ -0,0 +1,150 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-04-29 -->
+# Stack Anatomy Contract
+
+> P: Defines the canonical shape of `src/templates/<stack>/skills/<skill>/references/anatomy.md` so every stack and every agent (claude · codex) emits the same file structure, naming, and entity recipes.
+> R: Authoring or auditing a stack's anatomy file; resolving disagreement between agents about where a new file belongs.
+> S: Reading code — the actual conventions are in the per-stack `anatomy.md`, not here.
+> N: [docs-system.md](docs-system.md), [scaffold-boundary-contract.md](scaffold-boundary-contract.md), `doc-cheat-sheet.md`
+
+> Nav: [Governance Index](./00-index.md)
+
+---
+
+## Why this contract exists
+
+`anatomy.md` is the file every coding-os agent reads BEFORE it Writes any stack-specific source file. It answers four questions in <2 KB:
+
+1. Where does file `X` live?
+2. What is it named?
+3. What does it depend on?
+4. What is the recipe to add a new entity (endpoint / model / component / screen / handler / migration / test)?
+
+If two stacks (or two agents) disagree on these answers, multi-stack projects rot. This contract makes the answer machine-checkable.
+
+## Token budget
+
+Hard cap: **2000 tokens** per anatomy.md. If a stack's anatomy is bigger, split entity recipes into siblings (`anatomy-models.md`, `anatomy-endpoints.md`) and link from the main anatomy.
+
+## File location
+
+```
+src/templates/<stack>/skills/<primary_skill>/references/anatomy.md
+```
+
+Anatomy lives next to its skill, not in `src/templates/<stack>/scaffold/docs/`. Reason: `cos init` copies scaffold ONCE; references load lazily forever.
+
+## Required frontmatter
+
+```html
+<!-- domain:STACK_DOMAIN | layer:reference | ssot:true | updated:YYYY-MM-DD -->
+```
+
+`STACK_DOMAIN` is the uppercased stack id with hyphens removed: `nextjs` → `NEXTJS`, `go-fiber` → `GOFIBER`, `react-native` → `REACTNATIVE`.
+
+## Required opening block
+
+Short form (`> P:` / `> R:` / `> S:` / `> N:`) — anatomy is a high-traffic routing file, short form is mandatory to save tokens.
+
+## Required H2 sections (this exact order)
+
+```
+## 1. Boundary
+## 2. Layout map
+## 3. Entity recipes
+## 4. Conventions
+```
+
+The contract test (`tests/test_anatomy_contract.py`) rejects any anatomy missing one of these or reordering them.
+
+### 1. Boundary
+
+ONE line that links to the machine-readable SSOT — no table, no duplicated fields:
+
+```markdown
+SSOT: `src/templates/<stack>/scaffold-boundary.yaml`.
+```
+
+Rationale: duplication of `roots` / `imports_from` / `forbids_writing_in` in prose creates drift. The yaml is the only canonical source; humans read it directly via the link.
+
+### 2. Layout map
+
+A table — one row per file pattern this stack produces:
+
+| Pattern | Location | Naming | Imports from | Description |
+
+Order rows top-down by frequency: most-edited file first.
+
+### 3. Entity recipes
+
+One H3 per entity type the stack supports. Each H3 carries:
+
+- **Trigger:** the user request that invokes this recipe.
+- **Files emitted:** numbered list of paths (use `<name>` for the parameter).
+- **Steps:** numbered, terse — each step ≤1 line.
+- **Optional generator script:** `src/scripts/<name>.py` if the stack ships one.
+
+Common entity types (use these names verbatim when applicable):
+
+- `Add a new endpoint` (backend stacks)
+- `Add a new model` (any data-bearing stack)
+- `Add a new component` (frontend stacks)
+- `Add a new screen` (mobile stacks)
+- `Add a new migration` (db-bearing stacks)
+- `Add a new test` (universal — required in every anatomy)
+
+### 4. Conventions
+
+ONE H2 with three terse subsections — each MUST be present even if empty:
+
+#### Naming
+
+Bullet list. Each bullet maps a thing → its rule. Examples: `kebab-case.tsx`, `camelCase` functions, `SCREAMING_SNAKE_CASE` constants.
+
+#### Test colocation
+
+State the rule once. Two patterns are accepted:
+
+- **Colocated:** `users/users.test.ts` next to `users/users.ts`.
+- **Mirrored:** `tests/users/test_users.py` mirrors `src/users/users.py`.
+
+Pick one per stack. Mixed = rejected by lint.
+
+#### Dependency rules
+
+Bullet list of allowed / forbidden import directions. MUST agree with `scaffold-boundary.yaml::imports_from`. Drift = test failure.
+
+## Authoring rules
+
+- **Lead with verbs.** `Returns`, not `This will return`.
+- **Tables beat prose.** If a section is >5 prose sentences, refactor into a table.
+- **No prose ≥10 words explaining what the code does.** Code is the doc.
+- **No screenshots.** Diagrams are `.svg` or `.mermaid` siblings.
+- **No version markers in body.** Version lives in frontmatter `updated:` only.
+
+## Cross-agent uniformity guarantee
+
+Three guarantees that make every agent emit identical-shape anatomy:
+
+1. **Schema is mechanical.** Required sections + table columns mean diff against the schema is unambiguous.
+2. **Lint enforces it.** `tests/test_anatomy_contract.py` runs on every PR.
+3. **Token budget is a hard cap.** No agent can pad — every line costs.
+
+Agents (claude, codex) read the same `anatomy.md` and produce the same scaffold-growth output because the recipe section is the source of truth. The agent does not invent file paths — it follows the recipe.
+
+## Adding a new entity recipe
+
+1. Open `anatomy.md` for the stack.
+2. Append H3 under § 3 in alphabetical order (rule: keep `Add a new test` last).
+3. Run `make docs-lint` (frontmatter + nav check).
+4. If you ship a generator, drop the script under `src/templates/<stack>/skills/<skill>/scripts/<name>.py`.
+5. Reference the script from the recipe's "Optional generator script" line.
+
+## When a stack legitimately can't satisfy the schema
+
+Some stacks (e.g. a future `infra-only` template) won't have models or components. They MUST still ship anatomy.md with each H2 present — empty sections carry the literal line:
+
+```
+_Not applicable to this stack._
+```
+
+This is contract-compliant. The lint accepts it.

templates/_base/scaffold/docs/governance/critical-rules.md

@@ -0,0 +1,224 @@
+<!-- domain:DOCS | layer:policy | ssot:true | updated:2026-05-13 -->
+# Critical Rules — Full Text
+
+Purpose: Canonical expansion of every numbered rule listed in `AGENTS.md` § Critical Rules. AGENTS.md keeps the 1-line summary; this file is the rationale + enforcement reference.
+Read when: A hook just blocked an action and cited a rule number, OR you are about to touch governance / hooks / MCP surfaces and need the full rationale.
+Skip when: You only need the 1-line summary — read AGENTS.md instead.
+Read next: [docs-system.md](docs-system.md), [agent-workflow.md](agent-workflow.md), [decision-records.md](decision-records.md)
+
+> Nav: [Docs Index](../00-index.md) | [Governance Index](./)
+
+---
+
+## Conventions
+
+- Every rule below uses the same 4-row structure: **Rule** · **Why** · **How (enforcement)** · **Where**.
+- “Hook” means a script under `src/core/hooks/` registered in `src/core/hooks/registry.yaml`; the renderer surfaces it in each adapter.
+- Rule numbers are stable — never reorder, only append.
+
+---
+
+## Rule 0 — Docs-first
+
+- **Rule:** Every code `Write`/`Edit` must trace to a doc path recorded in `$COS_AGENT_DIR/.doc-anchor`.
+- **Why:** Code without a documented spec is technical debt the moment it merges. The anchor forces an answer to “which doc does this code implement?”.
+- **How:** Hook `enforce-doc-anchor.sh` (PreToolUse Write|Edit) blocks code writes when `.doc-anchor` is empty or stale.
+- **Where:** `src/core/hooks/enforce-doc-anchor.sh`
+
+## Rule 1 — Never hardcode `.claude/` in `core/`
+
+- **Rule:** Use `$COS_AGENT_DIR` (per-agent), `$COS_STATE_DIR` (shared), `$COS_DB_PATH`. Session-id at `$COS_AGENT_DIR/session-id`. Sid string format: `ses-{agent}-YYYYMMDD-…`.
+- **Why:** `.claude/` is one of N adapter dirs (`.codex/`, …). Hardcoding breaks adapter parity (P2).
+- **How:** Hook `block-bad-patterns.sh` greps `src/core/**` for `.claude/`. Adapter resolves env at session start via `src/core/hooks/cos-env.sh`.
+- **Where:** `src/core/hooks/cos-env.sh`
+
+## Rule 2 — MCP tool names use `cos_*` prefix
+
+- **Rule:** Every public MCP tool exposed by thinking_os/graph_os/board_os is named `cos_<verb>_<noun>` (e.g. `cos_doc_search`, `cos_task_create`).
+- **Why:** Single namespace; consumer projects can grep one prefix; MCP clients can filter.
+- **How:** Tests in `src/core/thinking_os/tests/test_tool_naming.py` reject non-prefixed exports.
+- **Where:** [docs/governance/mcp-tool-inventory.md](mcp-tool-inventory.md)
+
+## Rule 3 — Hooks source `cos-env.sh`
+
+- **Rule:** Every hook starts with `source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true`.
+- **Why:** Resolves `$COS_*` env vars once. Removes per-hook env discovery code.
+- **How:** Hook `verify-hook-shape.sh` rejects new hooks missing the source line.
+- **Where:** `src/core/hooks/cos-env.sh`
+
+## Rule 4 — Scripts search config chain
+
+- **Rule:** Lookup order is `$COS_STATE_DIR/domain-config.json` → `infrastructure/scripts/domain-config.json`.
+- **Why:** Per-project state wins; repo defaults fall back. Same file shape in both locations.
+- **How:** Helper `src/core/hooks/find-config.sh` encodes the chain. Scripts call it; never reinvent the lookup.
+- **Where:** `src/core/hooks/find-config.sh`
+
+## Rule 5 — Path resolution: `.resolve()` before `.relative_to()`
+
+- **Rule:** On macOS `/tmp` symlinks to `/private/tmp`; relative-path math without `.resolve()` raises `ValueError`.
+- **Why:** Subtle CI breakage; tests pass on Linux, fail on macOS.
+- **How:** Pylint custom rule `cos-path-resolve` flags `Path(...).relative_to(...)` without preceding `.resolve()`.
+- **Where:** `src/core/thinking_os/utils/paths.py`
+
+## Rule 6 — Fire-and-forget needs explicit exception handling
+
+- **Rule:** Background work uses an `_<name>_safe()` wrapper with `except Exception as exc: logger.debug("…", exc_info=exc)`. Bare `except: pass` is rejected.
+- **Why:** Silent swallows hide bugs; `logger.debug` keeps the stack trace recoverable without spamming.
+- **How:** Hook `block-bad-patterns.sh` rejects bare `except` in any `_safe()` helper.
+- **Where:** `src/core/thinking_os/tools/_shared.py`
+
+## Rule 7 — Governance edits require explicit task name
+
+- **Rule:** Edits to `AGENTS.md`, `.coding-os/`, `src/core/rules/`, `src/core/hooks/` require the active task to mention `docs-update` or `governance` in title or labels.
+- **Why:** Governance drift is the most expensive drift to undo; every change must be auditable to a task.
+- **How:** Hook `block-protected-files.sh` reads the active TASK title/labels and refuses unauthorized edits.
+- **Where:** `src/core/hooks/block-protected-files.sh`
+
+## Rule 8 — Multi-step verification = Python, never bash heredoc inside `$(...)` with `uv run`
+
+- **Rule:** Write a `.py` file and call `subprocess.run([...], timeout=N)`. Do not pipe a heredoc into `uv run python -`.
+- **Why:** Bash 5.3.9 + `uv run` + heredoc = silent deadlock. Documented incident: hook-startup hang, 2026-03.
+- **How:** Hook `block-uv-heredoc.sh` rejects the pattern at PreToolUse Bash.
+- **Where:** `src/scripts/verify_phase_c_e2e.py`
+
+## Rule 9 — Schema migrations are append-only
+
+- **Rule:** New tables → migration `vN+1`. Never edit a past migration’s body.
+- **Why:** Migrations run once per consumer DB; editing the past silently diverges schemas.
+- **How:** Hook `block-migration-conflict.sh` rejects duplicate version numbers in `src/core/thinking_os/database.py`.
+- **Where:** `src/core/thinking_os/database.py`
+
+## Rule 10 — Regenerate derived artifacts
+
+- **Rule:** Edit source, then run `make regen-rules` + `make manifest-regen` + `make regen-adapter-templates`. Never hand-edit derived files.
+- **Why:** `src/core/scaffold_manifest.json`, `src/core/rules/dimension-registry.md`, `src/core/rules/skill-enforcement.md`, `adapters/{claude,codex}/*.template.*`, `tests/golden/**` are generated.
+- **How:** Hook `regen-reminder.sh` (PostToolUse Write|Edit on source files) prints the regen command. `warn-template-drift.sh` flags hand-edits to derived files.
+- **Where:** `Makefile`
+
+## Rule 11 — No hardcoded stack/adapter literals in `src/cli/*.py`
+
+- **Rule:** No quoted `"django"` / `"claude"` strings in CLI code. Read from `src/templates/<stack>/stack.yaml` / `src/adapters/<agent>/adapter.yaml`.
+- **Why:** Adding a new stack/adapter must be a yaml change, never a code change.
+- **How:** Hook `block-hardcoded-literals.sh` greps `src/cli/*.py`. Test `tests/test_no_hardcoded_stacks.py` enforces in CI.
+- **Where:** `src/cli/main.py`
+
+## Rule 12 — Comments by exception, not by default
+
+- **Rule:** Default to NO comments and NO docstrings. Code reads like prose;
+  good names and small functions remove the need. Add a comment only when
+  the WHY is non-obvious: a hidden constraint, subtle invariant, workaround
+  for a specific bug, or behavior that would surprise a reader.
+- **Exception — public MCP tools (`@mcp.tool` decorated functions):**
+  ONE-line docstring is permitted because FastMCP exposes it as the tool
+  description to the client. Keep it under 80 chars. No multi-section
+  PURPOSE/INPUT/OUTPUT/DEPENDENCIES/NOTES blocks — they bloat tokens and
+  duplicate what arg names and types already convey.
+- **Why:** Comments rot, names don't (well-named code stays self-describing).
+  Long header blocks balloon every file and burn tokens on every read for
+  zero runtime benefit. Past convention was wrong; legacy `PURPOSE / INPUT
+  / OUTPUT / DEPENDENCIES / NOTES` blocks are a tech debt to be removed
+  when touching a file, not a pattern to extend.
+- **How:** No automated enforcement (was never in any active hook). Code
+  review rejects new PURPOSE/INPUT/OUTPUT blocks; `block-bad-patterns.sh`
+  already blocks bare `except: pass`-style noise.
+- **Where:** `src/core/skills/clean-code/SKILL.md` §Self-Documenting
+
+## Rule 13 — MCP tool response envelope
+
+- **Rule:** Every `cos_*` tool returns via `ok(data)` / `fail(category, message)`. Wrapped in `@safe_tool`. Categories: `transient | validation | permission | not_found | unavailable | internal`.
+- **Why:** Single-shape envelope means clients can parse without per-tool branching; categories drive retry vs. abort.
+- **How:** Test `src/core/thinking_os/tests/test_envelope.py` rejects non-conforming returns.
+- **Where:** `src/core/thinking_os/tools/_shared.py` · contract: [docs/engineering/mcp-error-envelope.md](../engineering/mcp-error-envelope.md)
+
+## Rule 14 — Tasks are pointers, not specs
+
+- **Rule:** `docs/tasks/TASK-NNN-slug.md` MUST NOT inline content already in `docs/**` / `src/core/rules/**` / `AGENTS.md`. Four orthogonal axes: `swimlane` · `kind` (8-value enum) · `epic` · `labels` (never kind values).
+- **Why:** Tasks rot; canonical docs are reviewed. Inlining causes silent divergence.
+- **How:** Hook `lint-task.sh` warns >1.5k tokens, blocks >3k. `cos task-validate` rejects label values that collide with kind enum.
+- **Where:** `src/core/board_os/parser.py`
+
+## Rule 15 — Role chain composed for COMPLICATED+ tasks
+
+- **Rule:** Call `cos_compose_chain(signals)`; result written to `.coding-os/<agent>/.roles` + `.role`. Roles ARE the 11 formulas, addressed by semantic id: `researcher · analyst · architect · documenter · implementer · reviewer · debugger · security_auditor · deployer · observer · refactorer`.
+- **Why:** Hard problems need a sequenced chain of formulas. Composing once at task start avoids mid-task formula thrash.
+- **How:** Routing yaml at `src/core/thinking_os/roles/`, prompts at `src/core/thinking_os/agents/`. Source spec citation `Formula 1..11` retained only in `formulas-en.md`.
+- **Where:** `src/core/thinking_os/roles/` · `src/core/thinking_os/agents/`
+
+## Rule 16 — Formula dispatch produces typed EvidenceBundle
+
+- **Rule:** Every formula records via `cos_supervise_record_output(formula_id, output_json)` matching the formula’s `output_schema` Pydantic model.
+- **Why:** Without a typed output, multi-formula chains can’t verify hand-off correctness; supervisor can’t replay.
+- **How:** `cos_supervise` validates the JSON against the formula schema before storing.
+- **Where:** `src/core/thinking_os/dispatchers/`
+
+## Rule 17 — Situational Paths override role chain
+
+- **Rule:** When `.coding-os/<agent>/.situation` is set, the situational path wins over the composed role chain. Six situations: `incident-response · onboarding · scope-change · external-integration · design-review · existing-project-takeover`.
+- **Why:** “Production is on fire” needs a different sequence than a feature build, even if the dimensions look similar.
+- **How:** Dispatcher reads `.situation` before `.roles`.
+- **Where:** `src/core/thinking_os/situations/`
+
+## Rule 18 — Task reconciliation is mandatory before implementation
+
+- **Rule:** For every non-trivial user request: first check existing tasks via `cos_task_board` / `cos task-show`. Reuse when matched; otherwise create one, fill `Outcome` / `Read First` / `Acceptance`, then move `in_progress → testing → complete` (or `blocked` with explicit blocker).
+- **Why:** Otherwise tasks duplicate, board state diverges from reality, and progress can’t be measured.
+- **How:** No hook (yet) — convention enforced via review + memory.
+- **Where:** [docs/governance/task-lifecycle.md](task-lifecycle.md)
+
+## Rule 19 — Docs are the contract — never extend code beyond doc spec
+
+- **Rule:** If the doc says “registration takes username, password, name”, do NOT add a `birthdate` field because it “feels needed”. Edit the doc first, then the code.
+- **Why:** Code-first changes silently extend the contract; consumers read the doc, not the diff.
+- **How:** Pair: Rule 0 anchors new code TO a doc going IN; `enforce-doc-sync.sh` (PostToolUse Write|Edit|MultiEdit) surfaces docs that drifted going OUT — three signals: (a) symbol removed/renamed + doc still mentions it, (b) signature changed (param-count diff), (c) doc mtime older than code AND mentions a current symbol. Collaborates with thinking_os FTS5 index for accurate doc lookup + graph_os `cos_graph_references` for impact context. WARN class — agent must act.
+- **Where:** `src/core/hooks/enforce-doc-sync.sh`
+
+## Rule 20 — Test discipline: matrix command only, never broad sweep mid-task
+
+- **Rule:** `pytest tests/ -q` runs 743 integration tests (~6 min). Match changed files → matrix command (15s–90s) per `test-discipline.md`. Full sweep is permitted **only** pre-merge/release, cross-cutting refactor touching ≥3 matrix rows, or when the user explicitly asks. Single-test debug: `pytest path::TestClass::test_name -v` before re-running the file.
+- **Why:** Six minutes per change × N iterations = the user waits and productivity dies.
+- **How:** Convention + Rule. SSOT is `src/core/rules/test-discipline.md`; AGENTS.md § Verification Matrix mirrors it.
+- **Where:** `src/core/rules/test-discipline.md`
+
+## Rule 21 — Never use `isolation: "worktree"` in this repo
+
+- **Rule:** Subagent dispatch is allowed **only** for read-only research / inventory / verification (Agent tool without `isolation`). Write work runs single-agent on the main working tree. Never pass `isolation: "worktree"` to the Agent tool.
+- **Why:** Past worktree runs left orphaned `.claude/worktrees/<slug>/` plus locked `worktree-*` branches with broken `.git` links — required manual `find .git/worktrees/...` cleanup and deadlocked sessions.
+- **How:** Convention. The `worktree-orchestration` skill has been removed from `src/core/skills/` and `src/templates/_base/base.yaml`. Reviewers reject re-introduction.
+- **Where:** [AGENTS.md](../../AGENTS.md) § Critical Rules
+
+## Rule 22 — Anti-overengineering
+
+- **Rule:** Solve the problem in front of you with the smallest correct change. Reuse what exists, do not speculate, do not duplicate. Five sub-rules: (1) **Reuse-First** — search graph / docs / grep before writing anything; (2) **No-Speculation** — build only what the current task requires, no "might need it later"; (3) **Diff-Minimal** — smallest correct change, bug-fix-only commits, no ride-along refactors; (4) **No-Premature-Abstraction (Rule of Three)** — extract only when three divergent call sites need it; (5) **Defer-by-Default** — ask "what can I remove?" at task close. Applies to **every artifact** — code, docs, hooks, skills, templates, tests, CLI, configs.
+- **Why:** Every line written is paid for forever. Over-engineering grows surface area, hides intent, slows review, and trains the next agent that bloat is the house pattern. In an enterprise codebase the cumulative cost dominates any single addition.
+- **How:** Convention — automated detection is too false-positive-prone (numeric thresholds, abstraction counts, file additions). Enforcement is the reality-check matrix in the rule body, code review, and `cos_search` observations that surface prior incidents. Tactical instances (no abbreviations, no magic numbers, no positional booleans, nesting ≤ 2) are enforced through the `clean-code` skill.
+- **Where:** `src/core/rules/anti-overengineering.md`. Cross-links: `api-contract-discipline.md`, `test-discipline.md`, `clean-code skill`.
+
+---
+
+## Rule Index (quick lookup)
+
+| # | Rule | Hook |
+|---|---|---|
+| 0 | Docs-first | enforce-doc-anchor.sh |
+| 1 | No `.claude/` in core | block-bad-patterns.sh |
+| 2 | `cos_*` prefix | test_tool_naming.py |
+| 3 | Hooks source cos-env.sh | verify-hook-shape.sh |
+| 4 | Config chain | find-config.sh |
+| 5 | `.resolve()` before `.relative_to()` | pylint custom |
+| 6 | Fire-and-forget exception handling | block-bad-patterns.sh |
+| 7 | Governance task name | block-protected-files.sh |
+| 8 | No bash heredoc with `uv run` | block-uv-heredoc.sh |
+| 9 | Append-only migrations | block-migration-conflict.sh |
+| 10 | Regenerate derived artifacts | regen-reminder.sh + warn-template-drift.sh |
+| 11 | No hardcoded literals in cli/ | block-hardcoded-literals.sh |
+| 12 | Function header convention | lint-function-header.sh |
+| 13 | MCP envelope `ok`/`fail` | test_envelope.py |
+| 14 | Tasks are pointers | lint-task.sh |
+| 15 | Role chain composed | (none — convention) |
+| 16 | Typed EvidenceBundle | cos_supervise validation |
+| 17 | Situational Paths override | (none — dispatcher logic) |
+| 18 | Task reconciliation | (none — convention) |
+| 19 | Docs are contract | enforce-doc-sync.sh |
+| 20 | Test discipline | (none — convention) |
+| 21 | No worktree isolation | (none — convention) |
+| 22 | Anti-overengineering | (none — convention; clean-code skill for tactical) |

templates/_base/scaffold/docs/governance/decision-records.md

@@ -0,0 +1,58 @@
+<!-- domain:DOCS | layer:reference | ssot:true | updated:{{DATE}} -->
+# Decision Records
+
+Purpose: Define where durable architectural decisions live and how to reference them from tasks and governance docs.
+Read when: A change introduces or depends on a long-lived technical decision.
+Skip when: The task only needs an already-linked ADR and no decision-model update is required.
+Read next: `../architecture/adr/00-index.md`
+
+> Nav: [Docs Index](../00-index.md) | [ADR Index](../architecture/adr/00-index.md)
+
+## Rules
+
+- Stable architectural decisions belong in ADR files under `docs/architecture/adr/`.
+- Governance docs may summarize decisions, but ADR files are canonical.
+- Historical migration decisions that are no longer active belong in governance archive docs, not evergreen architecture pages.
+
+## When to Create an ADR
+
+- Provider choice with long-lived impact (e.g. payment provider, mail service)
+- Security model change
+- Infra/runtime tradeoff with operational consequences
+- Schema or API strategy that future work must inherit
+- Library or framework version pin with migration cost
+
+## ADR Template
+
+Each ADR follows this structure:
+
+```markdown
+<!-- domain:XXX | layer:adr | ssot:true | updated:YYYY-MM-DD -->
+# ADR-NNN: Short Decision Title
+
+> Nav: [ADR Index](./00-index.md)
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+
+## Context
+
+What is the issue we're seeing that motivates this decision?
+
+## Decision
+
+What is the change we're actually proposing or doing?
+
+## Consequences
+
+What becomes easier or harder as a result of this change?
+
+## Alternatives Considered
+
+Which alternatives were considered and why were they rejected?
+```
+
+## Numbering
+
+ADRs use sequential 3-digit numbering: `ADR-001-...md`, `ADR-002-...md`, etc. Numbers are never reused, even when an ADR is superseded.