@azure-id/orc 0.55.0

package/templates/skills/orc-pattern/references/be-express.md

@@ -0,0 +1,82 @@
+# Playbook — Express (BE)
+
+Generic best-practice defaults for Express 4/5 (Node/TS). The codifier OVERRIDES
+the Conventions with the project's observed style; the Invariants always stand.
+
+**Activation triggers:** Express, `app.use`, middleware, `Router()`, req/res/next,
+node backend, REST API in package.json with `express`.
+
+## Conventions (PROJECT-OVERRIDABLE — match the codebase)
+- Router-per-resource (`routes/<resource>.ts`) with handlers delegated to a
+  service/controller layer — match the project's split (fat routes vs services).
+- Validation layer: match the project (zod, joi, express-validator, celebrate).
+- Error handling funneled to a single error middleware (match its error shape).
+- Async style: match the project (async/await + wrapper vs explicit next(err)).
+- Config loading: match the project (dotenv, convict, env objects).
+
+## Invariants (ALWAYS — BLOCKING)
+- Every async handler routes rejections to `next(err)` (wrapper or try/catch) —
+  an unhandled rejection must never crash or hang a request.
+- Validate every request body/param/query BEFORE use — no raw `req.body` into
+  the DB or business logic.
+- Parameterized queries ONLY; never string-interpolate SQL.
+- Central error middleware returns typed 4xx for expected failures; never leak
+  stack traces, internal messages, or secrets in a response.
+- Config/secrets via env — never hardcoded.
+- Pagination on every collection endpoint.
+- Never mount user input into `res.redirect`/headers unvalidated.
+
+## Validation gate (default acceptance checks; measurable-only)
+Enforce only what is machine-checkable in the target repo; anything needing
+tooling the project lacks is advisory, never gating.
+- Every new endpoint returns the expected status codes: 200 read · 201 create ·
+  404 missing id · 409 conflict · 400/422 invalid body (match the project's
+  validator convention).
+- Build/type-check clean IF the project uses TS; lint clean IF it has a linter.
+- Every new async handler visibly routes errors to `next` (wrapper or catch).
+- Every new collection endpoint paginates (params visible in the signature).
+- Advisory only (never gate; requires tooling the project may lack): coverage
+  target on the new surface, p95 latency budget.
+
+## Worked example (SHAPE REFERENCE — the project's observed layout ALWAYS wins)
+Imitate the SHAPE (validate → service → typed error → central middleware),
+never this exact layout/naming when the project differs.
+
+```ts
+// routes/orders.ts — validated input, async-safe, paginated
+import { Router } from "express";
+import { z } from "zod";
+
+const router = Router();
+
+const CreateOrder = z.object({ itemId: z.number().int(), quantity: z.number().int().positive() });
+const ListQuery = z.object({ limit: z.coerce.number().max(100).default(50), offset: z.coerce.number().default(0) });
+
+router.post("/", async (req, res, next) => {
+  try {
+    const data = CreateOrder.parse(req.body);          // validate BEFORE use
+    const order = await orderService.create(data);
+    res.status(201).json(order);
+  } catch (err) { next(err); }                          // always to the funnel
+});
+
+router.get("/", async (req, res, next) => {
+  try {
+    const { limit, offset } = ListQuery.parse(req.query);
+    res.json(await orderService.list({ limit, offset })); // paginated
+  } catch (err) { next(err); }
+});
+
+export default router;
+
+// middleware/error.ts — single funnel, typed 4xx, no leaks
+export function errorHandler(err: unknown, req: Request, res: Response, _next: NextFunction) {
+  if (err instanceof z.ZodError) return res.status(400).json({ error: "Invalid input" });
+  if (err instanceof NotFoundError) return res.status(404).json({ error: err.publicMessage });
+  logger.error(err);                                    // full detail stays server-side
+  res.status(500).json({ error: "Internal error" });    // never the stack trace
+}
+```
+
+## Delivery order
+route → validation schema → service → error wiring → test.

package/templates/skills/orc-pattern/references/be-fastapi.md

@@ -0,0 +1,107 @@
+# Playbook — FastAPI (BE)
+
+Generic best-practice defaults for FastAPI. The codifier OVERRIDES the Conventions
+with the project's observed style; the Invariants always stand.
+
+**Activation triggers:** FastAPI, Pydantic, async Python, APIRouter, Depends,
+BaseModel, endpoint, router, CRUD.
+
+## Conventions (PROJECT-OVERRIDABLE — match the codebase)
+- One `APIRouter` per resource (match the project's file layout — e.g.
+  `app/routers/<resource>.py`, CRUD split into `app/crud/` if the project does).
+- Pydantic v2 schemas per resource (match the project's In/Out suffix + location).
+- DI via `Depends(...)` (match the project's session/dependency names).
+- Pagination style: match the project (limit/offset or cursor).
+
+## Invariants (ALWAYS — BLOCKING)
+- `async def` for all I/O paths; never block the event loop with sync I/O.
+- Validate every request body/param with a Pydantic model — no raw dicts in.
+- Parameterized queries ONLY; never string-interpolate SQL.
+- Typed HTTP errors (`HTTPException` w/ correct 4xx), never a generic 500 leak.
+- Never expose passwords, secrets, or stack traces in a response.
+- Config/secrets via settings/env — never hardcoded.
+- Pagination on every collection endpoint.
+
+## Validation gate (default acceptance checks; measurable-only)
+Enforce only what is machine-checkable in the target repo; anything needing
+tooling the project lacks is advisory, never gating.
+- Every new endpoint returns the expected status codes: 200 read · 201 create ·
+  404 missing id · 409 conflict/duplicate · 422 invalid body (FastAPI default).
+- Every collection endpoint paginates (params visible in the signature).
+- Every request body/param passes through a Pydantic model (no raw `dict` params).
+- Import/type check clean with the project's own tools (`ruff`/`mypy` IF present).
+- OpenAPI (`/docs`) reflects the real contract (schemas registered, not `Any`).
+- Advisory only (never gate; requires tooling the project may lack): coverage
+  target on the new surface, p95 latency budget.
+
+## Worked example (SHAPE REFERENCE — the project's observed layout ALWAYS wins)
+A minimal-complete slice showing all layers. Imitate the SHAPE (schema → router
+→ CRUD → dependency), NEVER this exact layout/naming when the project differs —
+the codifier's reconciled conventions override everything here.
+
+```python
+# schemas/order.py — In/Out models (v2)
+from pydantic import BaseModel, Field
+
+class OrderIn(BaseModel):
+    item_id: int
+    quantity: int = Field(gt=0)
+
+class OrderOut(BaseModel):
+    id: int
+    item_id: int
+    quantity: int
+    model_config = {"from_attributes": True}
+
+# crud/order.py — data access, parameterized only
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from models import Order
+
+async def create_order(db: AsyncSession, data: "OrderIn") -> Order:
+    order = Order(**data.model_dump())
+    db.add(order)
+    await db.commit()
+    await db.refresh(order)
+    return order
+
+async def get_order(db: AsyncSession, order_id: int) -> Order | None:
+    return await db.scalar(select(Order).where(Order.id == order_id))
+
+# deps.py — one isolated auth dependency
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+async def current_user(token: str = Depends(oauth2_scheme)) -> "User":
+    user = await resolve_user(token)          # however the project resolves it
+    if user is None:
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "Invalid credentials")
+    return user
+
+# routers/order.py — endpoint wiring: typed errors, DI, pagination
+from fastapi import APIRouter, Depends, HTTPException, status
+
+router = APIRouter(prefix="/orders", tags=["orders"])
+
+@router.post("", response_model=OrderOut, status_code=status.HTTP_201_CREATED)
+async def create(data: OrderIn, db: AsyncSession = Depends(get_db),
+                 user: User = Depends(current_user)) -> OrderOut:
+    return await crud.create_order(db, data)
+
+@router.get("/{order_id}", response_model=OrderOut)
+async def read(order_id: int, db: AsyncSession = Depends(get_db)) -> OrderOut:
+    order = await crud.get_order(db, order_id)
+    if order is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "Order not found")
+    return order
+
+@router.get("", response_model=list[OrderOut])
+async def list_orders(limit: int = 50, offset: int = 0,
+                      db: AsyncSession = Depends(get_db)) -> list[OrderOut]:
+    return await crud.list_orders(db, limit=limit, offset=offset)
+```
+
+## Delivery order
+schema → router/endpoint → CRUD/service → dependency wiring → test.

package/templates/skills/orc-pattern/references/be-go.md

@@ -0,0 +1,96 @@
+# Playbook — Go (BE)
+
+Generic best-practice defaults for idiomatic Go services (HTTP + gRPC, with Redis
+and SQL data layers). The codifier OVERRIDES the Conventions with the project's
+observed style; the Invariants always stand. Covers the golang-pro surface:
+concurrency, errors, interfaces, generics, project structure, testing — plus
+transport (gRPC) and data (Redis/SQL).
+
+**Activation triggers:** Go, Golang, goroutines, channels, context, gRPC, protobuf,
+Redis, database/sql, sqlx, pgx, generics, `go.mod`, microservices.
+
+## Conventions (PROJECT-OVERRIDABLE — match the codebase)
+- **Layout:** small, consumer-defined interfaces; composition over inheritance.
+  Match the project's `cmd/` (entrypoints), `internal/` (private), `pkg/` (public).
+- **Config:** functional options or env-loaded struct (match the project's approach).
+- **Transport:** match the project's router (net/http, chi, gin, echo) and, for
+  gRPC, its proto layout + generated-code location + interceptor chain.
+- **Data:** match the project's DB access (database/sql, sqlx, pgx, or an ORM) and
+  its Redis client usage (go-redis) + key-naming scheme.
+- **Concurrency:** match the project's worker-pool / errgroup / channel patterns.
+
+## Invariants (ALWAYS — BLOCKING)
+**Errors & control flow**
+- Handle EVERY error explicitly — no bare `_` discards of an `error`.
+- Wrap propagated errors with `fmt.Errorf("...: %w", err)` (preserve the chain).
+- Never `panic` for normal control flow.
+
+**Concurrency**
+- Pass `context.Context` as the first arg to all blocking/I/O ops; honor
+  cancellation (`<-ctx.Done()`) in every worker — no goroutine without a clear
+  lifecycle/shutdown path (no leaks).
+- Protect shared state (mutex/channel); code must pass the race detector.
+
+**Transport (HTTP / gRPC)**
+- Every inbound handler/RPC threads the request `context.Context` down to I/O.
+- Set server + client timeouts / deadlines; never an unbounded call.
+- gRPC: return proper `status.Error(codes.…)` codes, never leak internal errors;
+  validate every request message; register health + reflection as the project does.
+- Never expose secrets, stack traces, or internal error strings to callers.
+
+**Data (Redis / SQL)**
+- Parameterized queries ONLY; never string-interpolate SQL.
+- Always close/release rows, statements, and acquired connections (`defer`).
+- Redis: set TTLs on cache keys (no unbounded growth); handle cache-miss as a
+  normal path, not an error; never store secrets in plaintext cache values.
+- Config/secrets (DSNs, Redis URLs, tokens) via env — never hardcoded.
+
+## Validation gate (default acceptance checks; measurable-only)
+Enforce only what is machine-checkable in the target repo; anything needing
+tooling the project lacks is advisory, never gating.
+- `go build ./...` and `go vet ./...` clean.
+- `golangci-lint run` clean IF the project uses it.
+- Tests pass under the **race detector** (`go test -race ./...`).
+- No bare `_` error discards and no un-wrapped propagated errors in the diff.
+- For gRPC changes: proto regenerated + committed; server starts and serves.
+- Advisory only (never gate; requires tooling the project may lack): coverage
+  target on the new surface, p95 latency budget.
+
+## Worked example (SHAPE REFERENCE — the project's observed layout ALWAYS wins)
+Imitate the SHAPE (consumer-defined interface → implementation with wrapped
+errors → ctx-aware worker), never this exact layout/naming when the project differs.
+
+```go
+// order/service.go — consumer-defined contract + implementation
+type OrderStore interface {
+    GetOrder(ctx context.Context, id int64) (*Order, error)
+}
+
+func (s *Service) OrderSummary(ctx context.Context, id int64) (*Summary, error) {
+    order, err := s.store.GetOrder(ctx, id)          // ctx threads down to I/O
+    if err != nil {
+        return nil, fmt.Errorf("order summary %d: %w", id, err)  // wrap, keep chain
+    }
+    return buildSummary(order), nil
+}
+
+// order/worker.go — goroutine with a clear lifecycle
+func (s *Service) RunDigest(ctx context.Context, every time.Duration) error {
+    t := time.NewTicker(every)
+    defer t.Stop()
+    for {
+        select {
+        case <-ctx.Done():
+            return ctx.Err()                          // clean shutdown path
+        case <-t.C:
+            if err := s.sendDigest(ctx); err != nil {
+                s.log.Error("digest", "err", err)     // handle, never discard
+            }
+        }
+    }
+}
+```
+
+## Delivery order
+proto/interface (contract) → implementation → data/transport wiring →
+table-driven test (`-race`).

package/templates/skills/orc-pattern/references/be-nestjs.md

@@ -0,0 +1,86 @@
+# Playbook — NestJS (BE)
+
+Generic best-practice defaults for NestJS. The codifier OVERRIDES the Conventions
+with the project's observed style; the Invariants always stand.
+
+**Activation triggers:** NestJS, `@Injectable`, `@Controller`, module, provider,
+DTO, guard, pipe, `@nestjs/swagger`.
+
+## Conventions (PROJECT-OVERRIDABLE — match the codebase)
+- Feature module per domain: `*.module.ts` wiring `*.controller.ts` +
+  `*.service.ts` + `dto/*.dto.ts` (match the project's folder layout).
+- Constructor injection for all services (match the project's provider naming).
+- DTOs with `class-validator` decorators (match project's In/Out/Create naming).
+- Swagger annotations on endpoints (match the project's decorator usage).
+
+## Invariants (ALWAYS — BLOCKING)
+- Dependency injection ONLY — never `new SomeService()`; use `@Injectable()` +
+  constructor injection.
+- Global `ValidationPipe` + `class-validator` on every DTO — no unvalidated input.
+- Typed exceptions (`NotFoundException`, `ConflictException`), never generic errors.
+- Never expose passwords, secrets, or stack traces in responses.
+- Config/secrets via `ConfigModule`/env — never hardcoded.
+- No circular module deps; `forwardRef()` is a last resort, not a default.
+- No unjustified `any`.
+
+## Validation gate (default acceptance checks; measurable-only)
+Enforce only what is machine-checkable in the target repo; anything needing
+tooling the project lacks is advisory, never gating.
+- Every new endpoint returns the expected status codes: 200 read · 201 create ·
+  404 missing id · 409 conflict · 400 invalid body (ValidationPipe default).
+- `nest build` clean; dependency graph resolves (no circular-dep errors).
+- Every new DTO field carries a `class-validator` decorator (visible in diff).
+- Lint clean IF the project has a linter.
+- Swagger reflects the real contract IF the project uses `@nestjs/swagger`.
+- Advisory only (never gate; requires tooling the project may lack): coverage
+  target on the new surface, p95 latency budget.
+
+## Worked example (SHAPE REFERENCE — the project's observed layout ALWAYS wins)
+A minimal-complete feature slice. Imitate the SHAPE (module → controller →
+service → DTO), never this exact layout/naming when the project differs.
+
+```ts
+// dto/create-order.dto.ts — validated input
+import { IsInt, IsPositive } from "class-validator";
+
+export class CreateOrderDto {
+  @IsInt() itemId: number;
+  @IsInt() @IsPositive() quantity: number;
+}
+
+// order.service.ts — typed errors, injected deps
+@Injectable()
+export class OrderService {
+  constructor(private readonly repo: OrderRepository) {}
+
+  async findOne(id: number): Promise<Order> {
+    const order = await this.repo.findById(id);
+    if (!order) throw new NotFoundException(`Order ${id} not found`);
+    return order;
+  }
+
+  async create(dto: CreateOrderDto): Promise<Order> {
+    return this.repo.create(dto);
+  }
+}
+
+// order.controller.ts — thin, status codes explicit
+@Controller("orders")
+export class OrderController {
+  constructor(private readonly orders: OrderService) {}
+
+  @Post()
+  @HttpCode(HttpStatus.CREATED)
+  create(@Body() dto: CreateOrderDto) { return this.orders.create(dto); }
+
+  @Get(":id")
+  findOne(@Param("id", ParseIntPipe) id: number) { return this.orders.findOne(id); }
+}
+
+// order.module.ts — feature module wiring
+@Module({ controllers: [OrderController], providers: [OrderService, OrderRepository] })
+export class OrderModule {}
+```
+
+## Delivery order
+module → controller → service → DTOs → unit test.

package/templates/skills/orc-pattern/references/be-postgres.md

@@ -0,0 +1,98 @@
+# Playbook — Postgres data-access (BE, cross-cutting)
+
+Generic best-practice defaults for **Postgres query & data-access code** — the
+`getDataUser`-style layer: repositories, DAOs, query builders, raw SQL, ORM calls.
+Unlike a framework playbook this is **cross-cutting**: it co-applies on TOP of the
+task's framework pattern (Express/FastAPI/NestJS/Django/Go/…) whenever a task
+touches the DB layer. The codifier OVERRIDES the Conventions with the project's
+observed data-access style; the Invariants always stand. Never connects to a
+database — everything here is reconciled from the repo's own files.
+
+**Activation triggers:** Postgres, `pg`, `psycopg`, `asyncpg`, `pgx`, `lib/pq`,
+`Npgsql`, Prisma `provider = "postgresql"`, `postgrex`/Ecto, SQLAlchemy,
+`repository`/`dao`/`queries` modules, `.sql` files, migrations, "query the DB",
+`SELECT`/`INSERT`/`UPDATE`/`DELETE`, `getX`/`findX`/`listX` data-access functions.
+
+## Conventions (PROJECT-OVERRIDABLE — match the codebase)
+- Access path: match the project — raw driver, query builder (Knex/Drizzle/sqlc),
+  or ORM (Prisma/TypeORM/SQLAlchemy/ActiveRecord/Ecto). NEVER introduce a second
+  client/ORM alongside the one already in use.
+- Where data-access lives: match the project's layout (`repositories/`, `dao/`,
+  `db/queries/`, `models/`, co-located `*.sql`) and its file-per-resource split.
+- Column selection: match the project — if it lists explicit columns, list them
+  (no `SELECT *`); if it maps rows to a DTO/entity, return that same type.
+- Naming: match the project's table/column case (usually `snake_case`) and its
+  mapping to app-side field names.
+- Error surface: match how the project turns a DB error / not-found into an app
+  error (typed error, `Result`, nullable return) — don't invent a new shape.
+- Migrations: match the project's tool (Prisma, Alembic, Flyway, Liquibase,
+  `db/migrate`, sqlc) and file convention.
+
+## Invariants (ALWAYS — BLOCKING)
+- **Parameterized / bound queries ONLY.** Never build SQL by string
+  concatenation or interpolation of any caller-supplied value — bind every
+  parameter. (SQL-injection.) Dynamic identifiers (table/column names) must come
+  from a fixed allow-list, never raw input.
+- **No credentials or connection strings hardcoded** in data-access code — read
+  from the project's existing config/env source.
+- **Atomic multi-write = one transaction.** Two+ writes that must all-or-nothing
+  succeed run in a single transaction with a clear commit/rollback path.
+- **No DDL or migrations from a request/data-access function** — schema changes
+  go through the project's migration tool, not inline.
+- **Use the configured connection pool** — never open a per-call connection or
+  bypass the pool.
+- **Never leak DB errors verbatim** to the caller/response (no raw driver
+  messages, SQLSTATE, or query text in a user-facing error).
+
+## Validation gate (default acceptance checks; measurable-only)
+Enforce only what is machine-checkable in the target repo; anything needing
+tooling the project lacks is advisory, never gating.
+- Every new query uses bound parameters — no user value inside the SQL string
+  (visible in the diff).
+- New data-access functions go through the existing client/pool, not a fresh
+  connection.
+- Multi-write operations are wrapped in a transaction (visible in the code).
+- Build/type-check clean IF the project uses a typed stack; lint clean IF it has
+  a linter.
+- Advisory only (never gate; needs tooling/data the project may lack): `EXPLAIN`
+  plan review, index coverage for new filter/join columns, N+1 audit under load.
+
+## Worked example (SHAPE REFERENCE — the project's observed layer ALWAYS wins)
+Imitate the SHAPE (bound params → existing client → typed return → transaction on
+multi-write), never this exact driver/naming when the project differs.
+
+```ts
+// repositories/users.ts — bound params, pooled client, explicit columns, typed return
+import { pool } from "../db/client";           // the project's existing pool
+import type { User } from "../types";
+
+export async function getDataUser(id: number): Promise<User | null> {
+  const { rows } = await pool.query(
+    `SELECT id, email, name, created_at
+       FROM users
+      WHERE id = $1`,                            // $1 bound — never `${id}`
+    [id],
+  );
+  return rows[0] ?? null;                        // not-found handled explicitly
+}
+
+// atomic multi-write → one transaction
+export async function transferCredits(fromId: number, toId: number, amount: number) {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    await client.query(`UPDATE accounts SET balance = balance - $1 WHERE id = $2`, [amount, fromId]);
+    await client.query(`UPDATE accounts SET balance = balance + $1 WHERE id = $2`, [amount, toId]);
+    await client.query("COMMIT");
+  } catch (err) {
+    await client.query("ROLLBACK");
+    throw err;                                   // wrapped to a typed app error upstream
+  } finally {
+    client.release();                            // always back to the pool
+  }
+}
+```
+
+## Delivery order
+migration (if schema changes) → data-access function (bound query) → app-error
+mapping → wire into the calling service → test.

package/templates/skills/orc-pattern/references/fe-a11y.md

@@ -0,0 +1,36 @@
+# Rule pack — Frontend Accessibility (impact-ordered, capped)
+
+NOT a language playbook — a reviewer re-check pack. The orchestrator passes
+these rules as `fe_rules[]` when the run touched FE files; the reviewer checks
+ONLY the diff against them and emits **file:line** findings classified P1–P3 by
+real user impact (an a11y rule hit is never automatic P0 — invariants own P0).
+
+Deliberately capped at 15 rules, highest-impact first. Do NOT extend ad hoc —
+a 100-rule sweep per FE slice buries real findings and blows the review context.
+
+## Rules (impact-ordered)
+
+1. Interactive elements are REAL controls — `<button>`/`<a>`/`<input>`, not
+   `div onClick` (keyboard + AT reachability). *(usually P1)*
+2. Every form input has a programmatic label (`<label for>`, `aria-label`, or
+   `aria-labelledby`) — placeholder text is not a label. *(P1)*
+3. Keyboard path exists for every new flow: focusable, Enter/Space activates,
+   no positive `tabindex`, no keyboard trap. *(P1)*
+4. Focus is managed on view changes: modals trap + restore focus; route changes
+   move focus to the new content. *(P1)*
+5. Images: meaningful images have real `alt`; decorative ones have `alt=""` —
+   never a missing attribute. *(P2)*
+6. Color is never the only signal (error states, required fields, chart series
+   also get text/icon/pattern). *(P2)*
+7. Text contrast meets 4.5:1 (3:1 for large text) against its actual background. *(P2)*
+8. Heading levels are hierarchical — no skipped levels, one `<h1>` per view. *(P2)*
+9. Dynamic status updates announce via `role="status"`/`aria-live` (loading,
+   save confirmations, async errors). *(P2)*
+10. Disabled/loading states communicated to AT (`aria-disabled`, `aria-busy`),
+    not just styled. *(P2)*
+11. Touch targets ≥ 44×44 CSS px on new interactive elements. *(P2)*
+12. `prefers-reduced-motion` respected for new animations/transitions. *(P3)*
+13. Semantic landmarks for new page regions (`<nav>`, `<main>`, `<aside>`)
+    instead of bare divs. *(P3)*
+14. Language of parts: content in another language gets a `lang` attribute. *(P3)*
+15. Autocomplete attributes on common personal fields (name, email, address). *(P3)*

package/templates/skills/orc-pattern/references/fe-angular.md

@@ -0,0 +1,87 @@
+# Playbook — Angular (FE)
+
+Generic best-practice defaults for Angular 17+ (standalone components, signals).
+The codifier OVERRIDES the Conventions with the project's observed style; the
+Invariants always stand.
+
+**Activation triggers:** Angular, `@Component`, `@Injectable`, standalone,
+signals, RxJS, `angular.json`, NgModule, directive, `HttpClient`.
+
+## Conventions (PROJECT-OVERRIDABLE — match the codebase)
+- Standalone components (match the project — NgModule projects stay NgModule).
+- State: match the project (signals, RxJS services, NgRx) — never mix a new
+  state style in.
+- Feature-folder layout (`features/<domain>/`) — match the project's structure.
+- Data access via injected services wrapping `HttpClient`; components stay thin.
+- Template style: match the project (control-flow `@if/@for` vs `*ngIf/*ngFor`).
+
+## Invariants (ALWAYS — BLOCKING)
+- Every subscription is cleaned up (`takeUntilDestroyed`, `async` pipe, or
+  explicit unsubscribe) — no leaked subscriptions.
+- `track` (or `trackBy`) on every `@for`/`*ngFor` over mutable lists.
+- Never call functions with side effects from templates; keep change detection safe.
+- Sanitize/never bypass DOM sanitization (`bypassSecurityTrust*` is a last
+  resort with justification, never a convenience).
+- No secrets in client code or environment files that ship to the browser.
+- Accessibility: semantic HTML + ARIA on interactive elements; label every input.
+- HTTP errors handled (typed error path or interceptor) — no silent `subscribe()`.
+
+## Validation gate (default acceptance checks; measurable-only)
+Enforce only what is machine-checkable in the target repo; anything needing
+tooling the project lacks is advisory, never gating.
+- `ng build` clean — **zero type errors** (strict IF the project uses it).
+- Lint clean IF the project has a linter.
+- Every new `@for`/`*ngFor` has a `track`/`trackBy` (visible in the diff).
+- Every new subscription shows its cleanup path (visible in the diff).
+- Advisory only (never gate; requires tooling the project may lack):
+  bundle-size budget, Lighthouse score on changed routes.
+
+## Worked example (SHAPE REFERENCE — the project's observed layout ALWAYS wins)
+Standalone + signals flavor shown. Imitate the SHAPE (thin component → injected
+service → cleaned-up stream), never this exact style when the project differs.
+
+```ts
+// features/orders/order.service.ts — data access lives in the service
+@Injectable({ providedIn: "root" })
+export class OrderService {
+  private http = inject(HttpClient);
+  getOrder(id: string): Observable<Order> {
+    return this.http.get<Order>(`/api/orders/${id}`);
+  }
+}
+
+// features/orders/order-status.component.ts — thin, cleaned-up, tracked
+@Component({
+  selector: "app-order-status",
+  standalone: true,
+  template: `
+    @if (order(); as o) {
+      <section aria-label="Order status">
+        <h2>{{ o.title }}</h2>
+        <ul>
+          @for (item of o.items; track item.id) {
+            <li>{{ item.name }}</li>
+          }
+        </ul>
+      </section>
+    } @else {
+      <p role="status">Loading order…</p>
+    }
+  `,
+})
+export class OrderStatusComponent {
+  private route = inject(ActivatedRoute);
+  private orders = inject(OrderService);
+
+  order = toSignal(
+    this.route.paramMap.pipe(
+      map((p) => p.get("id")!),
+      switchMap((id) => this.orders.getOrder(id)),
+      takeUntilDestroyed(),          // cleanup, always
+    ),
+  );
+}
+```
+
+## Delivery order
+service → component → template/styles → route wiring → test.

package/templates/skills/orc-pattern/references/fe-nextjs.md

@@ -0,0 +1,65 @@
+# Playbook — Next.js (FE)
+
+Generic best-practice defaults for Next.js App Router. The codifier OVERRIDES the
+Conventions with the project's observed style; the Invariants always stand.
+
+**Activation triggers:** Next.js, App Router, RSC, Server Components, Server
+Actions, `use client`, route handlers, `generateMetadata`, revalidate.
+
+## Conventions (PROJECT-OVERRIDABLE — match the codebase)
+- Server Components by default; add `'use client'` only at the LEAF that needs it.
+- Route handlers in `app/**/route.ts`; pages in `app/**/page.tsx`.
+- Mutations via Server Actions; call `revalidatePath()`/`revalidateTag()` after.
+- Explicit cache directives on fetches (`next: { revalidate: N }` or `cache`).
+- Metadata via `generateMetadata`/`metadata` export, not hand-written `<meta>`.
+- (Project may still use the Pages Router — if so, MATCH it, don't force App Router.)
+
+## Invariants (ALWAYS — BLOCKING)
+- Never put a plain `<img>` for content images — use `next/image`.
+- Never leak server-only secrets into client components or `NEXT_PUBLIC_*`.
+- Server Actions validate their input server-side (never trust the client).
+- No blocking sync work in a Server Component render path.
+- Accessibility: semantic HTML + ARIA; label every input.
+
+## Validation gate (default acceptance checks; measurable-only)
+Enforce only what is machine-checkable in the target repo; anything needing
+tooling the project lacks is advisory, never gating.
+- `next build` locally → **zero type errors**.
+- `NEXT_PUBLIC_*` vs server-only env vars correctly separated (visible in diff).
+- Every new Server Action validates its input server-side (visible in diff).
+- Content images in new code use `next/image`, not `<img>` (visible in diff).
+- Advisory only (never gate; requires tooling the project may lack):
+  Lighthouse/Core Web Vitals score on changed routes, bundle-size budget.
+
+## Worked example (SHAPE REFERENCE — the project's observed layout ALWAYS wins)
+Imitate the SHAPE (RSC fetch + validated Server Action), never this exact
+layout/naming when the project differs — including Pages Router projects.
+
+```tsx
+// app/orders/[id]/page.tsx — async Server Component, explicit cache directive
+export default async function OrderPage({ params }: { params: { id: string } }) {
+  const res = await fetch(`${process.env.API_URL}/orders/${params.id}`, {
+    next: { revalidate: 60 },
+  });
+  if (!res.ok) notFound();
+  const order: Order = await res.json();
+  return <OrderView order={order} />;
+}
+
+// app/orders/actions.ts — Server Action: validate server-side, then revalidate
+"use server";
+import { z } from "zod";
+import { revalidatePath } from "next/cache";
+
+const UpdateQty = z.object({ orderId: z.string(), quantity: z.coerce.number().int().positive() });
+
+export async function updateQuantity(formData: FormData) {
+  const parsed = UpdateQty.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) return { error: "Invalid input" };  // never trust the client
+  await db.order.update(parsed.data);                      // the project's data layer
+  revalidatePath(`/orders/${parsed.data.orderId}`);
+}
+```
+
+## Delivery order
+page/layout → server component(s) → client leaf → server action → config → test.