coding-os 0.3.2__py3-none-any.whl

templates/_base/scaffold/docs/workflow/workflow-guide.md

@@ -0,0 +1,138 @@
+<!-- domain:DOCS | layer:reference | ssot:true | updated:{{DATE}} -->
+# Workflow Guide
+
+Purpose: Quick-start guide for new contributors and AI agents joining the project.
+Read when: First session in this repo, or when re-grounding after a long break.
+Skip when: Already familiar with the workflow and have an active task.
+Read next: `../governance/agent-workflow.md`, `../governance/task-lifecycle.md`
+
+> Nav: [Docs Index](../00-index.md)
+
+## TL;DR
+
+This project uses **coding-os** — a documentation-driven workflow with SSOT files,
+a Scrumban task board, and AI-agent enforcement hooks. Work flows through tasks:
+`icebox → in_progress → testing → complete` (plus `blocked` / `archive`). The `cos` CLI and slash
+commands drive the board; hooks enforce the discipline.
+
+## Daily Workflow
+
+1. **Start the session**
+
+    ```bash
+    cos daily
+    ```
+
+    Shows yesterday's progress, today's candidate tasks, blockers, and WIP status.
+    (Also available as a slash command — see the Commands section below.)
+
+2. **Pick or create a task**
+
+    ```bash
+    cos task-pick                 # top recommended tasks to work on next
+    cos board                     # full Scrumban board (add --web for the Hub UI)
+    cos task-create --title "..." --swimlane <lane> --kind <type>
+    ```
+
+    Reconcile against existing tasks first — never create a duplicate. If a
+    matching open task exists, use it.
+
+3. **Start the task**
+
+    ```bash
+    cos task-start TASK-NNN
+    ```
+
+    Enforces the WIP cap, sets the `.task-current` session marker, and moves the
+    task to `in_progress`.
+
+4. **Classify (Thinking OS Complexity Gate)**
+
+    Before writing code, classify the task and record the gate:
+
+    - CLEAR (1 dim) → just do it
+    - COMPLICATED (2-4 dims) → Zoom cycle, plan first
+    - COMPLEX (5+ dims) → full Zoom + experiments
+    - CHAOTIC → stabilize first, classify after
+
+    ```bash
+    bash .claude/hooks/write-state.sh .coding-os/claude/.thinking_os-gate "COMPLICATED 3"
+    ```
+
+    (Replace `.claude` / `claude` with your adapter dir — `.codex` / `codex` for
+    Codex. Slash-command equivalent: `/classify COMPLICATED 3`.) A hook BLOCKS
+    code writes until the gate is recorded.
+
+5. **Implement**
+
+    Follow the Core Loop in `AGENTS.md` (Classify → Orient → Plan → Execute →
+    Verify). Hooks enforce skill loading, gate recording, doc anchors, and
+    verification along the way.
+
+6. **Verify and close**
+
+    ```bash
+    cos verify                    # matrix-targeted verification for changed files
+    cos task-move TASK-NNN --to testing
+    cos task-done TASK-NNN
+    ```
+
+    (Slash-command equivalent for verification: `/verify`.) Never close a task
+    straight from `in_progress` — move to `testing`, run checks, then complete.
+
+## Slash Commands
+
+Type `/` in the agent to run a packaged workflow. Project commands live in
+`.claude/commands/` (and `.codex/commands/`) and are version-controlled:
+
+| Command | What it does |
+|---|---|
+<!-- if-module:tasks -->
+| `/board` | Show the Scrumban board grouped by swimlane × status |
+| `/daily` | Daily standup — yesterday, today's candidates, blockers, WIP |
+| `/retro` | Retrospective for a period (default 14 days) |
+| `/task TASK-NNN` | Load + summarize a task |
+<!-- end-if -->
+| `/classify Q1 Q2` | Record the Complexity Gate |
+| `/verify` | Run matrix-targeted verification for changed files |
+| `/review` | Review current changes against project standards |
+| `/diagnose` | Run system health diagnostics (`cos doctor`) |
+<!-- if-module:memory -->
+| `/memory-search <query>` | Search agent memory for cross-session context |
+<!-- end-if -->
+| `/role-<name>` | Invoke one of the 11 semantic roles (researcher, architect, …) |
+
+## Key Files
+
+- `AGENTS.md` — Routing protocol + Core Loop (read first every session)
+- `docs/00-index.md` — Master navigation hub
+- `docs/tasks/TASK-NNN-*.md` — Task detail files (the board's source of truth)
+- `docs/governance/` — Workflow policies (`agent-workflow.md`, `task-lifecycle.md`, `critical-rules.md`)
+- `docs/playbooks/` — Domain-specific routing maps (if installed)
+- `docs/engineering/` — Coding standards (if installed)
+
+## Commands Cheat Sheet
+
+| Command | What it does |
+|---|---|
+| `cos daily` | Standup view — last 24h + today's candidates + blockers |
+| `cos board [--web]` | Scrumban board (ASCII, or Hub UI) |
+| `cos task-pick` | Next recommended task |
+| `cos task-create --title "..." --swimlane <lane> --kind <type>` | Create a task |
+| `cos task-start TASK-NNN` | Start a task (sets WIP + `.task-current`) |
+| `cos task-move TASK-NNN --to <status>` | Move a task between statuses |
+| `cos task-done TASK-NNN` | Complete a task |
+| `cos task-show TASK-NNN` | Show a task's full content |
+| `cos retro` | Weekly retrospective — throughput + cycle time |
+| `cos verify` | Matrix-targeted verification for changed files |
+| `cos doctor` | Deep health check (scaffold, DB, adapter, symlinks) |
+| `cos health` | Fast health summary |
+
+## Thinking OS — Memory and Learning
+
+The `coding-os` MCP server provides tools for memory, learning, metrics, routing,
+and graph queries. See `../governance/mcp-tool-inventory.md` for the full inventory.
+
+Key flow: every tool use → captured to the DB. Every task done → outcome recorded.
+Every 10 tasks → patterns extracted. Every session start → relevant past patterns
+suggested.

templates/_base/scaffold/src/shared/README.md

@@ -0,0 +1,23 @@
+<!-- domain:ALL | layer:reference | ssot:true | updated:{{DATE}} -->
+# `src/shared/` — Cross-Stack Contract Layer
+
+Purpose: Hosts types, contracts, and constants that two or more stacks must agree on. The only directory every installed stack is allowed to import from (per each stack's `scaffold-boundary.yaml::imports_from`).
+
+Read when: Adding a field that crosses a stack boundary (e.g. backend response shape consumed by frontend or mobile).
+
+Skip when: The artifact lives entirely inside one stack — keep it there.
+
+## Layout
+
+```
+src/shared/
+├── types/         # language-neutral type declarations (e.g. TypeScript .d.ts, Pydantic JSON schemas, .proto)
+└── contracts/     # API / event / message contracts that pin producer ↔ consumer
+```
+
+## Rules
+
+- Producers (backend / api / worker) MUST update `src/shared/` BEFORE consumers (frontend / mobile) read the new shape.
+- No stack writes into another stack's root — cross-stack changes flow through `src/shared/` only.
+- See [governance/scaffold-boundary-contract.md](../../docs/governance/scaffold-boundary-contract.md) for the per-stack boundary that pins the policy.
+- See [engineering/api-contract-discipline.md](../../docs/engineering/api-contract-discipline.md) (if installed) for why consumers verify field names against producers, not memory.

templates/_base/skill-enforcement.template.md

@@ -0,0 +1,14 @@
+# Skill Loading Enforcement
+
+> **This file was the legacy hand-edited skill-enforcement table** with hardcoded per-project skills.
+> **It is no longer the source of truth.** Skill enforcement is now generated
+> from `src/templates/<stack>/stack.yaml::skill_enforcement` by `src/scripts/regen_rules.py`.
+> Generated output: [src/core/rules/skill-enforcement.md](../../core/rules/skill-enforcement.md).
+>
+> To change skill routing for a stack: edit that stack's `stack.yaml` and run
+> `make regen-rules`.
+>
+> This stub is retained because `src/templates/_base/skill-enforcement.template.md`
+> is referenced by `src/cli/_data_types.py::SkillEnforcementRow`; emptying the
+> file would break the import path. It deliberately contains no enforcement
+> rules — they live in the regenerated artifact.

templates/_base/task-detail.template.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/_presets/ai-saas.yaml

@@ -0,0 +1,9 @@
+version: 1
+id: ai-saas
+label: "AI SaaS (Next.js + FastAPI)"
+description: >-
+  The dominant AI-product shape: Next.js web app with a Python FastAPI
+  backend serving model endpoints. Ships llm-patterns and observability
+  skills so token costs and latency are first-class from day one.
+stacks: [nextjs, fastapi]
+skills: [llm-patterns, observability]

templates/_presets/django-next.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: django-next
+label: "Django + Next.js"
+description: >-
+  Batteries-included Python backend with a modern React frontend — the
+  most common enterprise migration shape (Django REST + Next.js app).
+stacks: [django, nextjs]
+skills: [api-design]

templates/_presets/dotnet-react.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: dotnet-react
+label: ".NET (ASP.NET Core) + React"
+description: >-
+  An ASP.NET Core backend (minimal API/controllers, DI, middleware) with a
+  Next.js React frontend. api-design governs the contract across the seam.
+stacks: [aspnet-core, nextjs]
+skills: [api-design]

templates/_presets/flutter-baas.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: flutter-baas
+label: "Flutter + BaaS (mobile, backend-as-a-service)"
+description: >-
+  A Flutter mobile app fronting a managed backend (Firebase/Supabase-style) —
+  screens, widgets, and provider state. state-management covers the client store.
+stacks: [flutter]
+skills: [state-management]

templates/_presets/go-react.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: go-react
+label: "Go API + React"
+description: >-
+  A pragmatic performance pairing: a Go + Fiber API backend with a Next.js
+  React frontend. api-design governs the JSON contract across the seam.
+stacks: [go-fiber, nextjs]
+skills: [api-design]

templates/_presets/hexagonal-product.yaml

@@ -0,0 +1,16 @@
+# The flagship multi-service composition (TASK-365): hexagonal product with a
+# Go business core, a go-fiber API edge, a FastAPI AI adapter and a React
+# Native app. The three backend-root stacks collide on src/backend and
+# relocate to src/services/{go,go-fiber,fastapi} per the anatomy contract
+# (semantically: core / api / ai); cross-language reuse goes through
+# src/shared/contracts only.
+version: 1
+id: hexagonal-product
+label: "Hexagonal Product (Go core + Fiber API + FastAPI AI + React Native)"
+description: >-
+  Enterprise hexagonal architecture from day one: pure-Go business core,
+  go-fiber HTTP edge, FastAPI AI adapter service and a React Native app —
+  each service owns its subtree under src/services/, contracts are the only
+  cross-language boundary.
+stacks: [go, go-fiber, fastapi, react-native]
+skills: [hexagonal-architecture, api-design]

templates/_presets/jamstack.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: jamstack
+label: "JAMstack (Astro content site)"
+description: >-
+  Content-first, statically generated sites with Astro islands — marketing,
+  docs, and SEO-driven pages. a11y keeps the rendered output accessible.
+stacks: [astro]
+skills: [a11y]

templates/_presets/laravel-vue.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: laravel-vue
+label: "Laravel + Vue"
+description: >-
+  The Laravel ecosystem's signature pairing: a Laravel PHP backend with a
+  Vue 3 + Nuxt frontend. api-design governs the contract across the seam.
+stacks: [laravel, vue-nuxt]
+skills: [api-design]

templates/_presets/mean.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: mean
+label: "MEAN (Mongo + Express + Angular + Node)"
+description: >-
+  The Angular take on the JavaScript stack: an Express/TypeScript API with an
+  Angular SPA frontend, document-store oriented. db-design covers the data model.
+stacks: [node-express, angular]
+skills: [db-design]

templates/_presets/mern.yaml

@@ -0,0 +1,9 @@
+version: 1
+id: mern
+label: "MERN (Mongo + Express + React + Node)"
+description: >-
+  The most-searched JavaScript stack: an Express/TypeScript API with a React
+  frontend (Next.js as the modern React harness), document-store oriented —
+  the React sibling of MEAN. db-design covers the data model.
+stacks: [node-express, nextjs]
+skills: [db-design]

templates/_presets/nest-angular.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: nest-angular
+label: "NestJS + Angular (full TypeScript enterprise)"
+description: >-
+  End-to-end TypeScript: a NestJS modular backend with an Angular SPA frontend —
+  shared types across the seam. api-design governs the contract.
+stacks: [nestjs, angular]
+skills: [api-design]

templates/_presets/nextjs-fastapi.yaml

@@ -0,0 +1,10 @@
+# Seed preset proving the model end-to-end (TASK-356). The famous-combo
+# catalog (T3, MERN-style, the flagship hexagonal, …) lands in TASK-371/365.
+version: 1
+id: nextjs-fastapi
+label: "Next.js + FastAPI full-stack"
+description: >-
+  TypeScript web frontend with a Python API backend — the most common
+  two-language starter. Frontend and backend own separate roots, so no
+  service relocation is triggered.
+stacks: [nextjs, fastapi]

templates/_presets/nuxt-fullstack.yaml

@@ -0,0 +1,9 @@
+version: 1
+id: nuxt-fullstack
+label: "Nuxt full-stack (Vue 3)"
+description: >-
+  Single-app full-stack Vue in the Nuxt spirit: one Nuxt codebase owning UI
+  and server routes, typed end to end — the Vue counterpart of T3-style.
+  db-design and api-design cover the data and contract decisions.
+stacks: [vue-nuxt]
+skills: [db-design, api-design]

templates/_presets/pern.yaml

@@ -0,0 +1,9 @@
+version: 1
+id: pern
+label: "PERN (Postgres + Express + React + Node)"
+description: >-
+  The classic JavaScript split: Express/TypeScript API with a React
+  frontend (Next.js as the modern React harness) over Postgres.
+  sql-authoring and db-design cover the relational core.
+stacks: [node-express, nextjs]
+skills: [sql-authoring, db-design]

templates/_presets/rails-react.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: rails-react
+label: "Rails API + React"
+description: >-
+  A Ruby on Rails API backend (controllers, ActiveRecord) with a Next.js React
+  frontend. api-design governs the JSON contract across the seam.
+stacks: [rails, nextjs]
+skills: [api-design]

templates/_presets/rn-api.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: rn-api
+label: "Mobile app + API (React Native + FastAPI)"
+description: >-
+  Mobile-first product: React Native app with a Python FastAPI backend —
+  contracts in src/shared/contracts are the single client/server boundary.
+stacks: [react-native, fastapi]
+skills: [api-design]

templates/_presets/rust-svelte.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: rust-svelte
+label: "Rust (Axum) + SvelteKit"
+description: >-
+  A performance-first stack: a Rust + Axum backend with a SvelteKit frontend —
+  low overhead on both ends. api-design governs the contract.
+stacks: [rust-axum, svelte-sveltekit]
+skills: [api-design]

templates/_presets/spring-react.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: spring-react
+label: "Spring Boot + React (enterprise JVM)"
+description: >-
+  An enterprise JVM backend (Spring Boot, controllers/services/repositories)
+  with a Next.js React frontend. api-design governs the contract between them.
+stacks: [spring-boot, nextjs]
+skills: [api-design]

templates/_presets/t3-style.yaml

@@ -0,0 +1,9 @@
+version: 1
+id: t3-style
+label: "T3-style (full-stack TypeScript Next.js)"
+description: >-
+  Single-app full-stack TypeScript in the T3 spirit: one Next.js codebase
+  owning UI and API routes, typed end to end. db-design and api-design
+  skills cover the Prisma/tRPC-shaped decisions.
+stacks: [nextjs]
+skills: [db-design, api-design]

templates/_presets/tall.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: tall
+label: "TALL-style (Tailwind + Laravel)"
+description: >-
+  A Laravel-centric server-rendered product stack — controllers, Eloquent, and
+  Blade-driven UI. security-web keeps the web surface hardened.
+stacks: [laravel]
+skills: [security-web]

templates/_presets/wordpress-cms.yaml

@@ -0,0 +1,8 @@
+version: 1
+id: wordpress-cms
+label: "WordPress CMS"
+description: >-
+  A content-managed WordPress site — theme for presentation, plugin for portable
+  business logic. security-web enforces sanitize/escape/nonce discipline.
+stacks: [wordpress]
+skills: [security-web]

templates/angular/rules/frontend.md

@@ -0,0 +1,19 @@
+---
+globs: ["src/frontend/**/*.{ts,html,css}"]
+alwaysApply: false
+---
+
+# Angular Frontend Rules (auto-loaded on src/frontend/**)
+
+When editing any file under `src/frontend/`, follow these standards:
+
+- **Standalone components only** — no NgModules; declare `imports` on the component.
+- **Signals for state** — `signal` / `computed` over manual change detection; prefer `OnPush`.
+- **Services own side effects** — components stay presentation-only; data + RxJS live in injectable services.
+- **Typed data boundaries** — every HTTP response is typed; no `any`.
+- **Accessibility** — semantic HTML, labelled inputs, keyboard-reachable interactions.
+- **One error shaper** — a global `ErrorHandler` formats errors; components never show raw server messages.
+
+Canonical policy: `docs/engineering/angular-rules.md`
+Playbook: `docs/playbooks/angular-app.md`
+Primary skill: `angular`

templates/angular/scaffold/docs/engineering/accessibility.md

@@ -0,0 +1,46 @@
+<!-- domain:FRONTEND | layer:reference | ssot:true | updated:2026-06-30 -->
+# Accessibility (a11y) Checklist — WCAG 2.2 AA (Angular)
+
+Purpose: Living checklist for accessibility compliance across the Angular frontend.
+Read when: Building or reviewing any component, route, form, or interactive widget.
+Skip when: Working on backend-only tasks.
+Read next: [Angular Engineering Rules](./angular-rules.md) for general conventions.
+
+> Nav: [Docs Index](../00-index.md) | [Angular Rules](./angular-rules.md)
+
+---
+
+## Semantics & Interactive Elements
+
+- Prefer native elements (`<button>`, `<a href>`, `<input>`) over `<div (click)>` — they ship roles, focus, and keyboard handling for free.
+- Icon-only controls MUST set `[attr.aria-label]` describing the action, not the icon.
+- Every form control MUST have an associated `<label for>` (or `aria-label` / `aria-labelledby`).
+- Required fields set `[attr.aria-required]="true"`; invalid fields set `[attr.aria-invalid]="true"` and link the message via `[attr.aria-describedby]`.
+- Custom widgets (dialog, menu, tabs, combobox) follow the matching ARIA Authoring Practices pattern — reach for `@angular/cdk/a11y` before hand-rolling roles and key handling.
+
+## Keyboard Navigation
+
+- Tab order follows reading order — never `tabindex > 0`.
+- Every interactive element is operable with Enter/Space; Escape closes overlays.
+- Trap focus inside open dialogs with the CDK `cdkTrapFocus` directive; restore focus to the trigger element on close.
+- Keep a visible focus indicator on every focusable element (`:focus-visible`) — never `outline: none` without a replacement.
+- The first focusable element of the shell is a "skip to main content" link.
+
+## Dynamic Content
+
+- Announce async state changes (toasts, validation, route changes) with the CDK `LiveAnnouncer` or an `aria-live` region — `polite` for status, `assertive` for errors.
+- On client-side navigation, move focus to the new view's `<h1>` so screen-reader users are not stranded on the old page.
+
+## Color & Motion
+
+- Contrast: normal text ≥ 4.5:1; large text (≥ 18.66px bold or ≥ 24px) ≥ 3:1; UI components and focus indicators ≥ 3:1.
+- Never convey meaning by color alone — pair it with text or an icon.
+- Honor `prefers-reduced-motion`: gate non-essential animation behind the media query.
+
+## Verify
+
+- Static: enable the `@angular-eslint` template-accessibility rules in the lint config.
+- Runtime: run axe-core (e.g. `@axe-core/playwright`) against key routes in CI and fail the build on violations.
+- Manual: tab through each new view with no mouse, then do a screen-reader pass (VoiceOver / NVDA) on forms and dialogs.
+
+See the core `a11y` skill for cross-framework rationale and screen-reader testing recipes.

templates/angular/scaffold/docs/engineering/angular-rules.md

@@ -0,0 +1,35 @@
+<!-- domain:FRONTEND | layer:rules | ssot:true | updated:{{DATE}} -->
+# Angular Engineering Rules
+
+Purpose: Non-negotiable conventions for the {{PROJECT_NAME}} Angular frontend.
+Read when: Editing anything under `src/frontend/`.
+Skip when: Backend/mobile work.
+Read next: [Angular App Playbook](../playbooks/angular-app.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Hard rules
+
+1. **Standalone only** — `standalone: true` on every component; no `@NgModule`.
+   Declare per-component `imports`; the layering table in the `angular` skill is
+   the SSOT.
+2. **Signals for state** — `signal`/`computed`/`effect` drive the view; pair
+   with `ChangeDetectionStrategy.OnPush`. Manual `ChangeDetectorRef.detectChanges`
+   in feature code is a review finding.
+3. **Services own side effects** — a component importing `HttpClient` or holding
+   shared mutable state is a build-blocking finding; that belongs in an
+   injectable service.
+4. **One error shaper** — only the global `ErrorHandler` logs full detail; the UI
+   shows a generic, mapped message — never a raw server/stack string.
+5. **Dependency injection** — inject with `inject()` or constructor params;
+   never `new` a service — it bypasses the injector and breaks test overrides.
+6. **Strict TypeScript + templates** — `tsc --noEmit` with `strictTemplates` is
+   the lint gate; `any` requires a written justification at the site.
+7. **Unsubscribe discipline** — prefer the `async` pipe or `takeUntilDestroyed`;
+   a manually-subscribed stream without teardown leaks.
+
+## Testing bar
+
+Services ≥ unit-tested per public method (signals, no DOM); components ≥ render +
+one interaction via `TestBed`, happy + error path; guards/interceptors tested in
+isolation against a stubbed `HttpClient`.

templates/angular/scaffold/docs/playbooks/angular-app.md

@@ -0,0 +1,42 @@
+<!-- domain:FRONTEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Angular App Playbook
+
+Purpose: The end-to-end recipe for adding or changing an Angular feature in {{PROJECT_NAME}}.
+Read when: Any task that adds a component, service, route, guard, or interceptor.
+Skip when: Backend/mobile work — see the relevant stack docs.
+Read next: [Angular Engineering Rules](../engineering/angular-rules.md), [Accessibility](../engineering/accessibility.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Add a feature (the only sanctioned path)
+
+1. **Component** — `src/frontend/src/app/<feature>/<feature>.component.ts`:
+   standalone, `ChangeDetectionStrategy.OnPush`, declares its own `imports`.
+   Presentation only — it reads signals and emits events.
+2. **Service** — `<feature>.service.ts`: `@Injectable({ providedIn: "root" })`,
+   owns state via `signal`/`computed` and side effects via RxJS + `HttpClient`.
+   The component never fetches or mutates global state directly.
+3. **Route** — register the component in `app.routes.ts`; lazy-load with
+   `loadComponent` once the feature is non-trivial.
+4. **Guard / interceptor** — cross-cutting concerns live under `core/` and are
+   provided in `app.config.ts`, never inline in a component.
+5. **Inputs/outputs** — pass data in with typed `input()`, signal changes out
+   with `output()`; no two-way mutation of shared state from a child.
+6. **Test** — unit-test the service in isolation (signals, no DOM) +
+   component test via `TestBed` (render + interaction, happy + error path).
+7. **Verify** — `cd src/frontend && npm run lint && npm test`.
+
+## Global wiring (set once in `app.config.ts`)
+
+`provideRouter → provideHttpClient → { provide: ErrorHandler, useClass:
+GlobalErrorHandler }`. Application-wide providers live here so every component
+inherits routing, HTTP, and one error shape.
+
+## Anti-patterns
+
+- An NgModule (`@NgModule`) — this stack is standalone-only.
+- A component calling `HttpClient` directly — data access belongs in a service.
+- `setTimeout`/manual change detection to "force" a refresh — drive the view
+  from a `signal`/`computed` instead.
+- Formatting a raw server error string into the template — the global
+  `ErrorHandler` owns logging; the UI shows a generic, mapped message.