coding-os 0.3.2__py3-none-any.whl

templates/_base/fragments/retrieval-routing.md.tmpl

@@ -0,0 +1,23 @@
+## Retrieval Routing (pick before you retrieve)
+
+Each retrieval layer answers a different question shape. Classify the query *before* calling any tool:
+
+| Query shape | Tool | Why |
+|---|---|---|
+| Exact identifier (function, file, {% if modules.tasks %}`TASK-NNN`, {% endif %}snake_case, CamelCase, backticked code) | **Grep / Glob** | Lexical match wins on token cost and recall when the token is present. |
+{% if modules.docs %}| Conceptual / synonym-heavy ("auth flow", "money handling", "payment split") | `cos_doc_search` | Embedding index finds chunks where the spec uses a synonym of the agent's query. |
+{% endif %}{% if modules.memory %}| "Have I seen this before?" / past pattern / prior solution | `cos_search` + `cos_learn_suggest` | Memory has 5-signal ranking + spaced repetition. |
+{% endif %}{% if modules.tasks %}| Task graph / dependency / status | `cos_task_*` | Structured tasks table, dependency JSON walks. |
+{% endif %}{% if modules.graph %}| Structural code question (who calls X, blast radius, rename, API surface) | `cos_graph_references` / `cos_graph_impact` / `cos_graph_context` | Graph traversal is symbol-precise where grep floods on common names. |
+{% endif %}| Behavioral rule / protocol (how to classify, how to verify) | **full-read `core/rules/*.md`** | Rule is already in context — never retrieve it. |
+
+Every `cos_*` response carries `data.meta.layer` (`memory|docs|tasks|metrics|routing|graph|health|learning`) and `data.meta.tokens_estimated`. If you got the wrong layer, re-route; if `data.meta.truncated=true`, page with a smaller `limit`.
+
+{% set pref_layers = [] %}{% if modules.memory %}{% set _ = pref_layers.append('Memory') %}{% endif %}{% if modules.docs %}{% set _ = pref_layers.append('Docs') %}{% endif %}{% if modules.tasks %}{% set _ = pref_layers.append('Tasks') %}{% endif %}{% if pref_layers | length > 1 %}Order of preference when two layers look equally plausible: **{{ pref_layers | join(' → ') }}.**{% if modules.memory %} Memory already ranks by past outcome success; the rest are static index lookups.{% endif %}
+{% endif %}
+
+{% if modules.memory %}**Versioned lessons — `.agents/memory/MEMORY.md` (committed):** the portable, in-repo mirror of the memory layer (Trusted lessons + imported notes), so cross-session knowledge survives a fresh clone. It is the SAME layer as `cos_search`, not a fifth store — the DB is machine-local, this file travels. Claude auto-loads it (the harness memory dir is symlinked to `.agents/memory/`); **other runtimes have no auto-load — read `.agents/memory/MEMORY.md` yourself during Orient.**
+{% endif %}
+
+{% if modules.docs %}**Freshness contract (Phase H).** Every Write/Edit on a file matched by `rag-config.yaml` triggers an automatic incremental re-index via the `auto-reindex-docs` PostToolUse hook. Agents MUST NOT assume `make docs-index` is needed after a doc edit — `cos_doc_search` already reflects the latest `mtime`. If you suspect staleness, run `cos hooks-log | grep auto-reindex-docs` to confirm the hook fired. **Adapter note:** on Codex (no Write/Edit PostToolUse surface), rely on `COS_BACKGROUND_INDEX=1` or a manual `make docs-index` until Codex exposes those matchers.
+{% endif %}

templates/_base/fragments/session-handoff.md.tmpl

@@ -0,0 +1,3 @@
+## Session Handoff
+
+Triggers: 15+ reads or 10+ writes, degraded recall, user ends session, compaction event. Protocol: record outcome{% if modules.tasks %} → update task Notes checkpoint{% endif %}{% if modules.memory %} → `cos_learn_narrative` if breakthrough{% endif %}. Next session: `make session-init`{% if modules.memory %} + Orient Memory Check{% endif %}.

templates/_base/fragments/skills.md.tmpl

@@ -0,0 +1,3 @@
+## Skills
+
+{{ substitutions.INSTALLED_SKILLS }}. Config: `$COS_STATE_DIR/settings.json`.

templates/_base/fragments/ssot-map.md.tmpl

@@ -0,0 +1,3 @@
+## SSOT Map
+
+{{ substitutions.SSOT_MAP }}

templates/_base/fragments/stop-conditions.md.tmpl

@@ -0,0 +1,3 @@
+## Stop Conditions
+
+Stop when: SSOT files conflict, product intent not inferable, production-impacting execution required, risky assumption changes behavior/schema/security. {% if modules.tasks %}Log: `make task-block`.{% else %}Surface the blocker to the user before continuing.{% endif %}

templates/_base/fragments/subagent-dispatch.md.tmpl

@@ -0,0 +1,3 @@
+## Subagent Dispatch
+
+Default: single-agent. Subagents are allowed **only** for parallel read-only research, inventory, or verification (max 3 workers). Never pass `isolation: "worktree"` — write-capable parallel dispatch is disabled (orphaned worktrees + locked branches caused recurring deadlocks). All write work runs single-agent on the main working tree. Details: `docs/governance/agent-workflow.md` § Execution Mode.

templates/_base/fragments/task-authoring.md.tmpl

@@ -0,0 +1,69 @@
+{% if modules.tasks %}## Task Authoring (Phase L Scrumban)
+
+Tasks live at `docs/tasks/TASK-NNN-slug.md`. They are written in lean
+Phase L format: YAML frontmatter + Outcome + Read First (links only) +
+Acceptance (G/W/T) + Work Log.
+
+### The four categorization axes
+
+| Axis | Field | Rule |
+|---|---|---|
+| Domain | `swimlane` | From `.coding-os/scrumban-config.yaml` — pick ONE |
+| Type | `kind` | Closed enum: feature\|bug\|chore\|spike\|docs\|refactor\|test\|security |
+| Initiative | `epic` | Optional free string (e.g. `phase-l`, `mvp`, `oncall-q2`) |
+| Tags | `labels` | Free list; MUST NOT contain `kind` values |
+
+### Preferred path — use MCP tools, not hand-written YAML
+
+When creating a task:
+```
+cos_task_create(title, swimlane, kind, priority='P2', appetite='1d', epic=?, labels=?, outcome=?, read_first=[...])
+```
+
+When transitioning status:
+```
+cos_task_move(task_id, to='in_progress', reason=?)
+```
+
+When logging work (Codex MUST call this — no PostToolUse hook):
+```
+cos_work_log_append(task_id, summary, agent_session=?)
+```
+
+When picking next: `cos_task_pick()`. When starting session: `cos_task_daily()`.
+
+### Rule 15 — Tasks are pointers, not specs
+
+Task body MUST NOT inline content from `docs/**`, `core/rules/**`,
+`CLAUDE.md`, or `AGENTS.md`. `Read First` lists *paths*; the body
+describes *delta* (outcome + acceptance + work log). Duplicated
+content is a bug — fix by linking, or by creating a real doc first.
+
+### WIP limit — solo-dev defense
+
+Default: **1 task in_progress**. If you need to start another, either:
+- complete one first, or
+- transition the current to `blocked` / `ready`, or
+- set `COS_WIP_OVERRIDE=1` (rare — leaves a metric).
+
+### MCP outage — retry policy
+
+`cos_task_move` / `cos_work_log_append` return `fail("transient", retryable=True)` on transient errors.
+Retry ONCE after 2 seconds. On second failure, fall back to direct MD
+edit via the `Edit` tool — the `validate-task-frontmatter.sh` hook still
+enforces safety at the file-system layer.
+
+### Multi-session handoff
+
+Every session appends ONE line to the active task's Work Log via
+`capture-work-log.sh` (Claude, automatic) or `cos_work_log_append`
+(Codex, explicit). Next session reads the last 5 lines from the MCP
+response to know "where I was". Work Log is append-only — never rewrite.
+
+### Daily ritual (observability, never shame)
+
+`cos daily` prints yesterday's progress + today's pick candidates +
+blockers + WIP state. If no check-in in 24h, `remind-daily.sh` prints
+a banner. Streak data is purely observability — NEVER use it to
+pressure the human (ADHD-friendly default).
+{% endif %}

templates/_base/fragments/task-logging.md.tmpl

@@ -0,0 +1,8 @@
+{% if modules.tasks %}## Task Logging
+
+Files: `docs/tasks/TASK-NNN-slug.md`. **Phase L lean format** — frontmatter
+with `status` (enum: `icebox | ready | emergency | in_progress | testing |
+complete | blocked | archive`), `swimlane`, `kind`, `priority`, `appetite` +
+Acceptance (Given/When/Then). See `task-authoring` section below for the
+four-axis taxonomy. Legacy `[ ] [/] [x]` markers still parse via fallback.
+{% endif %}

templates/_base/fragments/tool-routing.md.tmpl

@@ -0,0 +1,9 @@
+## Tool Routing
+{% if modules.tasks %}
+**Legacy task flow (backward-compat):** `make session-init`, `task-next`, `task-start TASK=N`, `task-done TASK=N TYPE=t MSG="m" WHAT="w" FILES="f"`, `task-block TASK=N REASON="r"`, `task-create NUM=N TITLE="t"`, `task-context TASK=N`, `task-list STATUS=open`.
+
+**Scrumban board (Phase L — preferred):** `cos board [--web]`, `cos task-create --title ... --swimlane ... --kind ...`, `cos task-start TASK-NNN`, `cos task-move TASK-NNN --to testing`, `cos task-done TASK-NNN`, `cos task-pick`, `cos daily`, `cos retro`, `cos wip`. MCP: `cos_task_create`, `cos_task_board`, `cos_task_move`, `cos_task_pick`, `cos_task_daily`, `cos_task_retro`, `cos_task_wip_check`, `cos_work_log_append` (Codex: must call explicitly).
+{% endif %}
+Log: `log-latest [N]`, `log-write TYPE=t MSG="m" WHAT="w" FILES="f"`, `log-search QUERY="q"`.
+Health: `cos-health`, `verify-hooks`.
+Impl: {{ substitutions.TOOL_ROUTING_IMPL }}

templates/_base/fragments/verification-matrix.md.tmpl

@@ -0,0 +1,12 @@
+## Verification Matrix
+
+Domain-aware enforcement via `enforce-verify.sh` — detects changed files and requires matching suites:
+
+| Changed files | Required suites | Make commands |
+|---|---|---|
+| {{ substitutions.VERIFY_BACKEND_GLOB }} | {{ substitutions.VERIFY_BACKEND_SUITES }} | {{ substitutions.VERIFY_BACKEND }} |
+| {{ substitutions.VERIFY_FRONTEND_GLOB }} | {{ substitutions.VERIFY_FRONTEND_SUITES }} | {{ substitutions.VERIFY_FRONTEND }} |
+| {{ substitutions.VERIFY_DOCS_GLOB }} | {{ substitutions.VERIFY_DOCS_SUITES }} | {{ substitutions.VERIFY_DOCS }} |
+| {{ substitutions.VERIFY_HOOKS_GLOB }} | verify-hooks | `make verify-hooks` |
+
+Results stored in `$COS_STATE_DIR/.last-verify.json` per-suite with timestamps. Each suite must be PASS and < 30 min old.{% if modules.tasks %} `make task-done` is **BLOCKED** if any required suite is missing or stale.{% endif %}

templates/_base/lang/dart/analysis_options.yaml

@@ -0,0 +1,7 @@
+# Dart/Flutter lint baseline (coding-os language bundle).
+# Activates the recommended Flutter lints; needs flutter_lints as a dev_dependency.
+include: package:flutter_lints/flutter.yaml
+
+linter:
+  rules:
+    # Tune project rules here; see https://dart.dev/tools/linter-rules.

templates/_base/lang/php/phpcs.xml.dist

@@ -0,0 +1,10 @@
+<?xml version="1.0"?>
+<!-- PHP lint baseline (coding-os language bundle): PHP_CodeSniffer, PSR-12. -->
+<ruleset name="coding-os">
+  <description>PHP_CodeSniffer baseline — PSR-12.</description>
+  <file>src</file>
+  <arg name="colors"/>
+  <arg value="sp"/>
+  <rule ref="PSR12"/>
+  <exclude-pattern>*/vendor/*</exclude-pattern>
+</ruleset>

templates/_base/lang/python/pyproject.toml

@@ -0,0 +1,19 @@
+# Python toolchain baseline (coding-os language bundle): ruff lint+format + pytest.
+# Consumer-editable — tune as the project grows; ruff/pytest auto-discover this file.
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = [".coding-os", "migrations"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "C4"]
+# ruff format owns line wrapping, so E501 (line-too-long) stays off in lint.
+ignore = ["E501"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pytest.ini_options]
+addopts = "-q --strict-markers"
+python_files = ["test_*.py", "*_test.py"]
+testpaths = ["src"]

templates/_base/lang/rust/clippy.toml

@@ -0,0 +1,5 @@
+# Rust lint baseline (coding-os language bundle): Clippy thresholds.
+# Discovered by `cargo clippy` from the crate directory upward.
+cognitive-complexity-threshold = 30
+too-many-arguments-threshold = 8
+type-complexity-threshold = 250

templates/_base/lang/rust/rustfmt.toml

@@ -0,0 +1,3 @@
+# Rust format baseline (coding-os language bundle): rustfmt (stable keys only).
+edition = "2021"
+max_width = 100

templates/_base/lang/typescript/eslint.config.js

@@ -0,0 +1,26 @@
+// TypeScript/JS lint baseline (coding-os language bundle): ESLint v9 flat config.
+// Framework stacks (Angular/Vue/Svelte/Next) layer their own plugin on top of this.
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: [
+      "**/dist/**",
+      "**/build/**",
+      "**/.next/**",
+      "**/coverage/**",
+      "**/node_modules/**",
+      ".coding-os/**",
+    ],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "@typescript-eslint/consistent-type-imports": "error",
+    },
+  },
+);

templates/_base/lang/typescript/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "build", ".coding-os"]
+}

templates/_base/lang/typescript/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/**/*.{test,spec}.{ts,tsx}"],
+    coverage: { provider: "v8", reporter: ["text", "lcov"] },
+  },
+});

templates/_base/scaffold/changes.log

@@ -0,0 +1 @@
+# Project Change Log

templates/_base/scaffold/docs/00-index.md

@@ -0,0 +1,55 @@
+<!-- domain:ALL | layer:index | ssot:true | updated:{{DATE}} -->
+# {{PROJECT_NAME}} — Master Index
+
+> {{PROJECT_DESCRIPTION}}
+
+Purpose: Primary navigation hub for SSOT documentation across product, architecture, governance, and playbooks.
+Read when: You need to route to the canonical file for the active task.
+Skip when: `AGENTS.md` or a playbook has already routed you to the exact target file.
+Read next: The relevant playbook or domain doc below.
+
+## Core Navigation
+
+- [AGENTS](../AGENTS.md)
+- Active tasks — run `cos board` (Scrumban; task files under `./tasks/`)
+- [Questions Log](./_meta/questions.md)
+- [Change Log](../changes.log)
+- [Foundation Map](./_meta/foundation-map.md)
+- [Roadmap](./_meta/roadmap.md)
+- [Feature Tree](./_meta/feature-dependency-tree.md)
+
+## Governance
+
+- [Docs System](./governance/docs-system.md)
+- [Agent Workflow](./governance/agent-workflow.md)
+- [Task Lifecycle](./governance/task-lifecycle.md)
+- [Risk Register](./governance/risk-register.md)
+- [Decision Records](./governance/decision-records.md)
+- [Wrapper Derivation](./governance/wrapper-derivation.md)
+- [MCP Tool Inventory](./governance/mcp-tool-inventory.md)
+- [Workflow Guide](./workflow/workflow-guide.md)
+
+## Product and Content
+<!-- if-module:docs -->
+
+- [PRD Index](./prd/00-index.md)
+<!-- end-if -->
+<!-- Add when nextjs/web template installed: - [Content Specs Index](./pages-content-spec/00-index.md) -->
+
+## API Contracts
+
+- [API Contracts Index](./api-contracts/00-index.md)
+- [Error Format](./api-contracts/error-format.md)
+
+## Engineering and Delivery
+
+- [Architecture Index](./architecture/00-index.md)
+- [ADR Index](./architecture/adr/00-index.md)
+- [Ops Index](./ops/00-index.md)
+- [Insights](./insights/00-index.md)
+<!-- Add when stack-specific design system installed: - [Design Index](./design/00-index.md) -->
+
+## Quick Routing
+
+<!-- Routing entries are stack-specific. The CLI populates this section based on installed templates. -->
+{{QUICK_ROUTING}}

templates/_base/scaffold/docs/_meta/feature-dependency-tree.md

@@ -0,0 +1,30 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:{{DATE}} -->
+# Feature Dependency Tree
+
+Purpose: Visualize cross-feature dependencies so the planner knows what must ship before what.
+Read when: Sequencing tasks for a release, identifying blockers, or onboarding new contributors.
+Skip when: Working on a single isolated feature with no upstream/downstream impact.
+Read next: `./roadmap.md`, `../tasks/`
+
+> Nav: [Docs Index](../00-index.md) | [Roadmap](./roadmap.md)
+
+## Format
+
+```text
+Feature
+├── depends on: [feature/task ids]
+├── blocks: [feature/task ids]
+└── status: planning | in-progress | shipped
+```
+
+## Tree
+
+<!-- Add features below as the project grows. Example:
+
+User Authentication
+├── depends on: schema design, secrets rotation
+├── blocks: user profile, account settings, payment
+└── status: planning
+-->
+
+(empty — populate as features are planned)

templates/_base/scaffold/docs/_meta/foundation-map.md

@@ -0,0 +1,56 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:{{DATE}} -->
+# Foundation Map (`REF:*` Shortcodes)
+
+Purpose: Short canonical reference map for task files and other docs that need compact links.
+Read when: Adding `Read First` refs or task-scoped navigation.
+Skip when: Direct relative links are clearer than a shortcode.
+Read next: The target doc referenced by the shortcode you need.
+
+> Nav: [Docs Index](../00-index.md)
+
+## Core Navigation
+
+- `REF:AGENTS` → `../../AGENTS.md`
+- `REF:DOCS-INDEX` → `../00-index.md`
+- `REF:CHANGES` → `../../changes.log`
+- `REF:ROADMAP` → `./roadmap.md`
+- `REF:QUESTIONS` → `./questions.md`
+- `REF:FEATURE-TREE` → `./feature-dependency-tree.md`
+
+## Governance
+
+- `REF:GOV-INDEX` → `../governance/docs-system.md`
+- `REF:DOCS-SYSTEM` → `../governance/docs-system.md`
+- `REF:AGENT-WORKFLOW` → `../governance/agent-workflow.md`
+- `REF:TASK-LIFECYCLE` → `../governance/task-lifecycle.md`
+- `REF:RISK-REG` → `../governance/risk-register.md`
+- `REF:DECISIONS` → `../governance/decision-records.md`
+- `REF:WRAPPER-DERIVE` → `../governance/wrapper-derivation.md`
+- `REF:MCP-INVENTORY` → `../governance/mcp-tool-inventory.md`
+
+## Product
+
+- `REF:PRD-INDEX` → `../prd/00-index.md`
+
+## API
+
+- `REF:API-INDEX` → `../api-contracts/00-index.md`
+- `REF:API-ERRORS` → `../api-contracts/error-format.md`
+
+## Architecture
+
+- `REF:ARCH-INDEX` → `../architecture/00-index.md`
+- `REF:ADR-INDEX` → `../architecture/adr/00-index.md`
+
+## Ops
+
+- `REF:OPS-INDEX` → `../ops/00-index.md`
+
+## Insights
+
+- `REF:INSIGHTS-INDEX` → `../insights/00-index.md`
+
+<!-- Stack-specific REF codes are appended by template overlays.
+     Add new REF codes as the project grows. Keep this list compact —
+     direct relative links are still allowed for one-off references. -->
+{{STACK_REF_CODES}}

templates/_base/scaffold/docs/_meta/questions.md

@@ -0,0 +1,8 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:{{DATE}} -->
+# Open Questions
+
+> Nav: [Docs Index](../00-index.md)
+
+<!-- Blocker questions are logged here automatically by `cos task-block`.
+     Format: each question is `Q-NNN: <question>` followed by context lines.
+     Resolve a question by removing it and adding to the related task or ADR. -->

templates/_base/scaffold/docs/_meta/roadmap.md

@@ -0,0 +1,33 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:{{DATE}} -->
+# Roadmap
+
+Purpose: Phased plan of milestones and the tasks that compose each one.
+Read when: Session start (`make session-init` reads this), planning sequencing, or estimating release scope.
+Skip when: Working on a single task whose phase is already known.
+Read next: `../tasks/`, `./feature-dependency-tree.md`
+
+> Nav: [Docs Index](../00-index.md) | [Tasks](../tasks/)
+
+## Current Phase
+
+<!-- Update this when starting a new phase. session-init shows this line. -->
+Phase 0 — Project bootstrap
+
+## Phase 0 — Bootstrap
+
+- [ ] Project scaffolding complete
+- [ ] AGENTS.md routing configured
+- [ ] First architecture doc drafted
+- [ ] First task created via `cos task-create`
+
+## Phase 1 — MVP
+
+(define your MVP scope here)
+
+## Phase 2 — Hardening
+
+(define your hardening scope here)
+
+## Backlog
+
+(unscheduled features and ideas)

templates/_base/scaffold/docs/api-contracts/00-index.md

@@ -0,0 +1,58 @@
+<!-- domain:API | layer:index | ssot:true | updated:{{DATE}} -->
+# API Contracts — Index
+
+Purpose: Navigation hub for API contract documentation (request/response shapes, error codes, auth requirements).
+Read when: Implementing or consuming an API endpoint, or aligning frontend types with backend.
+Skip when: The task is purely internal logic with no API surface.
+Read next: The specific endpoint contract file relevant to your task.
+
+> Nav: [Docs Index](../00-index.md)
+
+## Files
+
+- [Error Format](./error-format.md) — Universal error envelope and codes
+<!-- Add as APIs are documented:
+- [Auth Endpoints](./auth-endpoints.md)
+- [Catalog Endpoints](./catalog-endpoints.md)
+-->
+
+## Format
+
+Each endpoint contract follows this structure:
+
+```markdown
+## POST /api/v1/<resource>
+
+### Request
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| ... | ... | ... | ... |
+
+### Response (2xx)
+
+```json
+{ ... }
+```
+
+### Errors
+
+| Status | Code | When |
+|---|---|---|
+| 400 | VALIDATION_ERROR | Invalid input |
+| 401 | UNAUTHORIZED | Missing/invalid auth |
+| 403 | FORBIDDEN | Insufficient permissions |
+| 404 | NOT_FOUND | Resource missing |
+
+### Auth
+
+Required scope: `...`
+```
+
+## Authoring Rules
+
+- One file per resource group (auth, catalog, orders, etc.).
+- Document both request and response in full — the contract is the SSOT.
+- All errors follow `error-format.md`.
+- When OpenAPI/Swagger is generated from code, link to the spec file but keep this human-readable doc up to date.
+- Breaking changes require an ADR (`../architecture/adr/`) and a versioned endpoint path.

templates/_base/scaffold/docs/api-contracts/error-format.md

@@ -0,0 +1,58 @@
+<!-- domain:API | layer:spec | ssot:true | updated:{{DATE}} -->
+# Error Format
+
+Purpose: Canonical error envelope used by all API endpoints.
+Read when: Implementing an endpoint, mapping errors in the frontend, or adding a new error code.
+Skip when: The task is internal and does not return errors over the wire.
+Read next: Specific endpoint contracts in `./` for per-endpoint error matrices.
+
+> Nav: [API Index](./00-index.md)
+
+## Envelope
+
+All API errors return JSON with this shape:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Human-readable message safe to show end-users.",
+    "details": {
+      "field_name": ["Field-level error"]
+    },
+    "request_id": "req_abc123"
+  }
+}
+```
+
+### Field Rules
+
+- `error.code` — UPPER_SNAKE_CASE machine-readable identifier. Stable across versions.
+- `error.message` — Human-readable, localizable, never leaks internal details (SQL, stack, file paths).
+- `error.details` — Optional. Field-level errors as `{field_name: [messages]}` or empty object.
+- `error.request_id` — Correlation ID for log lookups. Always present.
+
+## Standard Error Codes
+
+| HTTP Status | Code | When |
+|---|---|---|
+| 400 | `VALIDATION_ERROR` | Input failed validation rules |
+| 400 | `MALFORMED_REQUEST` | JSON parse failed, content-type wrong |
+| 401 | `UNAUTHORIZED` | Missing or invalid credentials |
+| 401 | `TOKEN_EXPIRED` | Auth token expired, refresh needed |
+| 403 | `FORBIDDEN` | Authenticated but lacks permission |
+| 404 | `NOT_FOUND` | Resource does not exist or hidden by ACL |
+| 405 | `METHOD_NOT_ALLOWED` | HTTP method not supported on this route |
+| 409 | `CONFLICT` | State conflict (e.g. duplicate, version mismatch) |
+| 422 | `UNPROCESSABLE_ENTITY` | Semantically invalid (e.g. invalid state transition) |
+| 429 | `RATE_LIMITED` | Too many requests, retry after `Retry-After` header |
+| 500 | `INTERNAL_ERROR` | Unexpected server error. Generic message only. |
+| 503 | `SERVICE_UNAVAILABLE` | Maintenance or downstream dependency failure |
+
+## Authoring Rules
+
+- Never leak SQL, stack traces, file paths, or internal variable names in `error.message`.
+- Validation errors use `details` for field-level messages.
+- New error codes require updating this table and any affected endpoint contracts.
+- Backend raises typed exceptions; an exception handler maps them to this envelope.
+- Frontend maps `error.code` to localized user messages, never displays raw `error.message` for `INTERNAL_ERROR`.

templates/_base/scaffold/docs/architecture/00-index.md

@@ -0,0 +1,42 @@
+<!-- domain:ARCH | layer:index | ssot:true | updated:{{DATE}} -->
+# Architecture — Index
+
+Purpose: Navigation hub for architecture documentation.
+Read when: Starting a task that touches system design, infrastructure, or cross-cutting concerns.
+Skip when: The task is isolated to a single module already covered by its playbook.
+Read next: The relevant numbered architecture doc or ADR below.
+
+> Nav: [Docs Index](../00-index.md) | [ADR Index](./adr/00-index.md)
+
+## Suggested Structure
+
+Architecture is split into focused files. Populate as the project grows. Recommended order:
+
+- `01-executive-summary.md` — One-page system overview
+- `02-tech-stack.md` — Languages, frameworks, libraries with version pins
+- `03-project-structure.md` — Directory layout and module boundaries
+- `04-security-guardrails.md` — Authn, authz, secrets, web security
+- `05-testing-strategy.md` — Test pyramid, coverage targets, CI gates
+- `06-deployment-infra.md` — Hosting, runtime, CI/CD, environments
+- `07-observability.md` — Logging, metrics, tracing, alerts
+- `08-data-architecture.md` — Database, caching, search, analytics
+- `09-integrations.md` — External services and API dependencies
+
+## Architecture Decision Records (ADRs)
+
+ADRs capture immutable architectural decisions. See `./adr/00-index.md`.
+
+## Format
+
+Each architecture doc follows the standard header:
+
+```html
+<!-- domain:ARCH | layer:spec | ssot:true | updated:YYYY-MM-DD -->
+```
+
+## Authoring Rules
+
+- Architecture docs describe **what is** (current state) and **why** (rationale).
+- Aspirational architecture goes in `../_meta/roadmap.md` or a new ADR with `Status: Proposed`.
+- When code diverges from architecture docs, update the docs in the same PR that changes the code.
+- For new domains, follow the Extension Protocol in `../governance/docs-system.md`.

templates/_base/scaffold/docs/architecture/adr/00-index.md

@@ -0,0 +1,39 @@
+<!-- domain:ARCH | layer:index | ssot:true | updated:{{DATE}} -->
+# Architecture Decision Records — Index
+
+Purpose: Index of all immutable architecture decisions.
+Read when: Considering a change that touches a previously-decided area, or onboarding to architectural choices.
+Skip when: The active task is in a domain with no relevant ADR.
+Read next: The specific ADR file referenced from your task.
+
+> Nav: [Architecture Index](../00-index.md) | [Docs Index](../../00-index.md)
+
+## ADRs
+
+<!-- Add ADRs in chronological order. Format:
+- [ADR-001](./ADR-001-short-title.md) — One-line summary
+-->
+
+(empty — populate as decisions are recorded)
+
+## Process
+
+1. When a long-lived architectural decision is needed, create `ADR-NNN-kebab-title.md`.
+2. Number sequentially. Never reuse numbers, even when an ADR is superseded.
+3. Use the template in `../../governance/decision-records.md` § ADR Template.
+4. Status starts as `Proposed`, moves to `Accepted` after implementation, or `Superseded by ADR-XXX` when replaced.
+5. Add the new ADR to the list above.
+6. Reference the ADR ID from related task files and architecture docs.
+
+## When to Create an ADR
+
+See `../../governance/decision-records.md` § When to Create an ADR.
+
+Common triggers:
+
+- Provider choice (payment, email, hosting, search)
+- Library/framework version pin with migration cost
+- Security model change
+- Data store choice
+- API contract strategy
+- Build/deploy strategy