@aria_asi/cli 0.2.39 → 0.2.41

package/dist/runtime/discipline/skills/aria-cognition/aria-senior-code-audit/references/audit-checklist.md

@@ -0,0 +1,369 @@
+# Senior Code Audit Cookbook — Pre-commit Audit + Recovery Grant Patterns
+
+> Loaded by `aria-senior-code-audit` for post-write code review with recovery-grant contracts.
+> See also: [`../../aria-senior-code-cookbook/references/engineering-cookbook.md`](../../aria-senior-code-cookbook/references/engineering-cookbook.md) (function contracts, idempotency, observability, security)
+> See also: [`../../aria-repo-audit/references/repo-audit-cookbook.md`](../../aria-repo-audit/references/repo-audit-cookbook.md) (severity × blast radius, finding categories)
+
+## 1. The 7-Category Audit Checklist (run all 7)
+
+### A. Contract correctness
+- [ ] Function signature matches cookbook contract (validate → log → idempotency → side-effect → log exit)
+- [ ] Return shape is `Result<Ok, Err>` (or equivalent typed discriminated union) where the function can fail
+- [ ] Error kinds enumerated in central errors taxonomy (not invented inline)
+- [ ] Async functions handle cancellation / timeout where applicable
+- [ ] Public surface (`index.ts`) only re-exports — no logic at the package boundary
+- [ ] Function name matches semantic convention (`getX` throws on not-found, `findX` returns null, `tryX` returns Result)
+
+### B. Failure mode coverage
+- [ ] Every error kind has a designed return path (not a swallowed exception)
+- [ ] Idempotency key declared for any side-effecting POST
+- [ ] Retries (if any) bounded by attempt count + backoff (NOT deadline-based timeout per `feedback_no_timeouts_decision_tree_rule`)
+- [ ] Rate-limit responses carry `Retry-After`
+- [ ] Tenant ID enforced at query layer (not application layer)
+
+### C. Tests
+- [ ] Test file co-located with code (`<name>.test.ts` next to `<name>.ts`)
+- [ ] One test per error kind in the taxonomy
+- [ ] Happy path test
+- [ ] Boundary inputs tested (empty, null, oversized, malformed)
+- [ ] Side effects mocked at the adapter seam, not at the network library
+
+### D. Observability
+- [ ] Structured log on entry with `customer_id` / `tenant_id` / `trace_id`
+- [ ] Structured log on exit with outcome
+- [ ] OpenTelemetry span wrapping the function
+- [ ] Sensitive fields redacted (`password`, `token`, `apiKey`, `authorization`)
+- [ ] No `console.log` in production paths
+
+### E. Security (OWASP A01-A10:2025)
+- [ ] Input validated at boundary with schema (zod / typebox)
+- [ ] No string concatenation into SQL / shell / HTML — parameterized only
+- [ ] No secrets in code; env-only with `.env.example` documentation
+- [ ] Auth + authz checked BEFORE business logic, not after
+- [ ] Destructive operations behind explicit confirmation OR audit-logged with actor identity
+- [ ] CI dependency scan passes (no high-severity CVEs)
+
+### F. Performance / cost
+- [ ] No N+1 queries (eager-loading / dataloader)
+- [ ] Indexes defined for predicate columns in WHERE / JOIN
+- [ ] Cache strategy named where applicable
+- [ ] No unbounded loops over user-controlled input
+- [ ] Bundle / package size impact noted for FE changes
+
+### G. Accessibility (FE only, WCAG 2.2 AA)
+- [ ] Keyboard navigation works
+- [ ] Focus rings preserved (no naked `outline: none`)
+- [ ] ARIA roles / labels for non-semantic elements
+- [ ] Color contrast ≥4.5:1 body, ≥3:1 large
+- [ ] Target size ≥24×24 CSS pixels (WCAG 2.2 NEW)
+- [ ] Loading / error / empty states designed
+
+## 2. The Recovery Grant Schema v2
+
+When findings exist, write to `~/.aria/governance-recovery-current.json` using the canonical v2 schema:
+
+```json
+{
+  "schema": "aria.governance_recovery_current.v2",
+  "updatedAt": "2026-05-09T20:00:00.000Z",
+  "deliveryRule": "This file is injected into the next system prompt. Execute recoveryLoop.nextStep before any completion claim.",
+  "ok": true,
+  "decision": "warn",
+  "source": "aria-senior-code-audit",
+  "governanceMode": "recovery-required",
+  "gateType": "escalating",
+  "sla": {
+    "target_response_seconds": 900,
+    "started_at": "2026-05-09T20:00:00.000Z"
+  },
+  "recoveryLoop": {
+    "fingerprint": "audit_<sha256-of-findings>",
+    "allowedRecoveryAttempts": 1,
+    "priorRecoveryAttempts": 0,
+    "remainingRecoveryAttempts": 1,
+    "nextStep": "Apply listed findings, run verification probe, re-emit corrected diff with proof.",
+    "architectFallback": "If findings cannot be resolved with one self-executed pass, escalate to architect harness with the finding fingerprint."
+  },
+  "recoveryContract": {
+    "loadSkillsFirst": [
+      "aria-senior-code-cookbook",
+      "aria-repo-doctrine",
+      "aria-forge-guardrails"
+    ],
+    "repairRecoveryCycle": [
+      "Add Result<Ok, Err> return type to src/handlers/leads.ts:47 — currently throws on stripe error",
+      "Add idempotency check at src/handlers/leads.ts:62 — side effect without dedup",
+      "Add test for rate_limited branch in src/handlers/leads.test.ts",
+      "Add structured log redaction for 'apiKey' in src/lib/log.ts"
+    ],
+    "retest": "npm test -- src/handlers/leads.test.ts && tsc --noEmit && npx eslint src/handlers/leads.ts",
+    "fallbackWhenAriaUnavailable": "Run findings sequentially; verify each with named probe; commit only after all pass"
+  },
+  "policy_recall_required": [
+    "memory:feedback_no_graceful_degradation.md",
+    "memory:feedback_doctrine_first.md"
+  ],
+  "priorReflections": [
+    {
+      "schema": "aria.coach_reflection.v1",
+      "at": "2026-05-09T18:30:00.000Z",
+      "skill": "aria-senior-code-audit",
+      "fingerprint": "audit_abc123",
+      "plan": "applied 3 findings; ran probe",
+      "outcome": "probe passed but new finding emerged",
+      "evaluation": "partial",
+      "rootCauseHypothesis": "error taxonomy not propagated to nested handler",
+      "alternativeHypothesis": "load aria-backend-architect first; map taxonomy across handler tree"
+    }
+  ],
+  "findings": [
+    {
+      "severity": "high",
+      "category": "contract",
+      "file": "src/handlers/leads.ts",
+      "line": 47,
+      "rule": "function-returns-result-not-throws",
+      "summary": "Stripe error path throws instead of returning typed error",
+      "fix": "Wrap in try/catch; return err({ kind: 'stripe_error', reason: classifyStripeError(e) })"
+    }
+  ]
+}
+```
+
+## 3. The Recovery Execution Flow (load-bearing primitive)
+
+```
+1. AUDIT FIRES post-write → produces findings list
+2. RECOVERY CONTRACT WRITTEN to ~/.aria/governance-recovery-current.json
+   - Schema v2 + fingerprint + nextStep + repairRecoveryCycle
+   - gateType: escalating (most pass; criticals route to review)
+   - SLA: 900 seconds default
+3. COACH KERNEL EVENT recorded:
+   recordCoachPhase({
+     phase: 'audit_findings',
+     risk_class: 'code_audit',
+     decision: 'taught',
+     reasons: [findings...],
+     next_action: 'execute recovery contract'
+   })
+4. NEXT-TURN SUBSTRATE delivers recovery block via recovery-context.mjs
+5. LLM EXECUTES the repairRecoveryCycle items
+6. VERIFICATION PROBE runs (retest field)
+7. PICKUP ARCHIVED via archiveRecoveryAfterPickup(pickupId)
+8. COACH KERNEL EVENT recorded:
+   recordCoachPhase({
+     phase: 'recovery_executed',
+     decision: 'verified',
+     probe_outcome: 'pass'
+   })
+9. REFLECTION recorded if partial/fail (Reflexion pattern):
+   recordReflection({
+     plan: ..., outcome: ..., evaluation: 'partial',
+     alternativeHypothesis: ... // for next trial
+   })
+
+If probe fails on retry:
+- priorRecoveryAttempts++
+- Surface failure to owner
+- Escalate to architect harness on second failure (architectFallback)
+```
+
+## 4. Pre-commit Hook Integration
+
+### Setup (one-time per repo)
+```bash
+# .githooks/pre-commit
+#!/usr/bin/env bash
+set -e
+
+# Run senior-code-audit on staged changes
+node ~/.aria/sdk/bin/aria-senior-code-audit \
+  --staged \
+  --recovery-grant-mode \
+  --severity-threshold high
+
+# If findings exist:
+# - Recovery contract written to ~/.aria/governance-recovery-current.json
+# - Commit proceeds (recovery is escalating, not blocking)
+# - Owner sees the findings + grant in commit output
+# - Next session starts with the recovery contract loaded
+```
+
+### Why pre-commit, not pre-push?
+- Pre-commit catches issues earlier (faster feedback)
+- Pre-push is too late (PR already drafted, mental context lost)
+- Pre-commit can be `--no-verify` bypassed by intent (audit-trail records the bypass)
+
+### The owner override
+If audit findings would block important work:
+```bash
+git commit -m "wip: ..."  # finds and grants recovery; commit proceeds (gateType: escalating)
+git commit -m "wip: ..." --no-verify  # bypasses audit ENTIRELY; recorded in audit trail
+```
+
+`--no-verify` records itself to `~/.aria/runtime/state/audit-bypass.jsonl` so owner sees the pattern over time.
+
+## 5. The Audit Output Layout (per `aria-readable-output`)
+
+```markdown
+## [4 findings (1 high, 2 medium, 1 low) in src/handlers/leads.ts; recovery contract granted]
+
+### High (must fix this turn)
+1. **`src/handlers/leads.ts:47`** — Stripe error throws instead of returning typed error
+   - Fix: `return err({ kind: 'stripe_error', reason: classifyStripeError(e) })`
+   - Rule: `function-returns-result-not-throws`
+
+### Medium (fix this turn or document deviation)
+2. **`src/handlers/leads.ts:62`** — side effect without idempotency check
+   - Fix: read `idempotency.get(key)` first; cache result on success
+   - Rule: `idempotency-required-on-side-effecting-post`
+
+3. **`src/handlers/leads.test.ts`** — missing test for rate_limited branch
+   - Fix: add test mirroring validation-error test pattern
+   - Rule: `one-test-per-error-kind`
+
+### Low (track in backlog)
+4. **`src/lib/log.ts`** — `apiKey` not in redact list
+   - Fix: add to pino redact array
+   - Rule: `redact-sensitive-fields`
+
+### Recovery contract granted
+- Written to `~/.aria/governance-recovery-current.json` (schema v2)
+- gateType: escalating · SLA: 15min · attempt 1 of 1
+- Next-turn substrate delivers; execute `nextStep` before any completion claim
+- Verification probe: `npm test && tsc --noEmit && npx eslint <files>`
+
+**Next:** apply the 3 high+medium findings, run the probe, re-emit corrected diff. Don't claim done until probe passes.
+```
+
+Then `<gate>` block (collapsed) with the full findings JSON for the gate runtime to read.
+
+## 6. The Failed-Probe Handling (Reflexion pattern)
+
+When the verification probe fails after recovery attempt:
+
+```typescript
+// In coach-kernel
+recordReflection({
+  sessionId: currentSession,
+  skill: 'aria-senior-code-audit',
+  fingerprint: previousAuditFingerprint,
+  plan: 'applied 3 findings; ran npm test',
+  outcome: '2 of 3 findings landed; rate_limited test still fails because mock returns wrong shape',
+  evaluation: 'partial',
+  rootCauseHypothesis: 'mock setup pattern not in cookbook; LLM defaulted to wrong shape',
+  alternativeHypothesis: 'load adapter-mocking pattern from engineering-cookbook §C before next attempt',
+  trialNumber: 2,
+});
+```
+
+The next turn substrate sees this reflection. The next attempt is informed by the rootCause + alternative hypothesis. This is multi-trial learning at the audit level.
+
+### When to escalate to architect
+After 2 failed trials on the same fingerprint:
+- Reflection ledger shows the LLM is stuck
+- Architect harness is invoked via `runWithGovernance()` from the harness SDK
+- Architect harness has access to broader context, can read the full repo, can decompose the problem differently
+- Architect produces revised recovery contract; LLM executes the new plan
+
+## 7. Severity Calibration (avoid inflation)
+
+**Critical** = ANY of:
+- Cross-tenant data leak risk
+- Authentication / authorization bypass
+- Payment failure or duplicate charge risk
+- Data loss without backup
+- Public-facing 500 error in normal usage
+- Secret exposure (key, token, password in code)
+
+**High** = ANY of:
+- Significant performance regression in user-facing path (>2× baseline)
+- Missing error path that causes UX confusion
+- Missing tests in critical-path code
+- Drift from doctrine / cookbook in production code
+- OWASP issue not on critical list
+- Multi-tenant isolation at app layer instead of query layer
+
+**Medium** = ANY of:
+- Cookbook deviation in non-critical code
+- Test coverage gap in non-critical path
+- Missing observability fields
+- Code organization / naming drift from team conventions
+- Performance issue in non-hot path
+
+**Low** = nits, style, naming preferences, refactor opportunities
+
+### The calibration test
+"Would this finding firing at 3am wake me up?"
+- Yes → Critical
+- During business hours, urgent → High
+- This week → Medium
+- Whenever → Low
+
+## 8. The Cross-skill Integration
+
+### Audit calls cookbook
+Before reporting findings, audit checks against `aria-senior-code-cookbook`'s plan (if one was emitted in this session). Findings should compare actual vs planned, not actual vs ideal.
+
+### Audit hands off to specialist skills
+- Backend issue → handoff to `aria-backend-architect` (deeper backend cognition)
+- Frontend issue → handoff to `aria-frontend-architect`
+- Cross-layer issue → handoff to `aria-fullstack-orchestrator`
+- Doctrine drift → handoff to `aria-repo-doctrine`
+- Architecture decision → handoff to `aria-decision-mizan` (if owner-must-decide)
+
+### Audit triggers reflection
+Every audit run produces a reflection event (Reflexion pattern). Even successful audits — the reflection captures "what worked well" so future audits compound learning.
+
+## 9. Audit anti-patterns
+
+### Generic findings without file:line
+"Add tests" — useless. "Add test for rate_limited branch in src/handlers/leads.test.ts" — actionable.
+
+### Severity inflation
+Calling stylistic preferences "high" erodes the signal. Stick to the calibration test.
+
+### Findings without recovery paths
+Complaints, not findings. Each finding has a concrete fix.
+
+### Auditing whole repo on a small PR
+Audit by blast radius of the diff, not the whole codebase. The repo audit skill (`aria-repo-audit`) is for sweep audits.
+
+### Hard-blocking the commit
+Recovery-grant pattern: commit proceeds, recovery is contracted. NEVER block commits.
+
+### Missing the cookbook cross-check
+Audit should compare actual against the pre-write plan when one exists. If `aria-senior-code-cookbook` produced a plan and the diff doesn't follow it, that's the dominant finding.
+
+### Generating a 200-finding laundry list
+Noise, not audit. Cap output at 10-15 findings; if more exist, deliver criticals + highs and explicitly defer the rest.
+
+## 10. Audit checklist (paste-ready)
+
+```markdown
+## Per-PR audit
+- [ ] Diff scanned (not whole repo)
+- [ ] All 7 audit categories swept (Contract / Failure / Tests / Observability / Security / Perf / Accessibility)
+- [ ] Findings have severity per calibration test
+- [ ] Findings have file:line + rule + concrete fix
+- [ ] Cross-checked against aria-senior-code-cookbook plan (if present)
+
+## Recovery grant
+- [ ] Schema v2 contract written to ~/.aria/governance-recovery-current.json
+- [ ] gateType: escalating (most pass; criticals route)
+- [ ] SLA: 900s default; adjust for blast radius
+- [ ] Verification probe named (the exact command)
+- [ ] policy_recall_required listed (memory:<file>.md identifiers)
+- [ ] priorReflections feed-forward if available
+
+## Coach kernel
+- [ ] audit_findings event recorded
+- [ ] recovery_grant event recorded
+- [ ] Per repair: recovery_executed event with verified outcome
+- [ ] Reflection recorded if partial/fail
+
+## Output
+- [ ] Readable layout (per aria-readable-output)
+- [ ] <gate> block with full findings JSON
+- [ ] No commit-blocking; teach + recover only
+```

package/dist/runtime/discipline/skills/aria-cognition/aria-senior-code-cookbook/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: aria-senior-code-cookbook
+description: TRIGGER pre-code at UserPromptSubmit / pre-tool surfaces whenever the intent is to write, refactor, scaffold, or organize code — including handler / endpoint / module / package / component / hook / migration / schema / test / cron / worker / pipeline / SDK / CLI / IaC / k8s manifest. Prepends paste-ready cookbook patterns covering organization, naming, contract-first design, error taxonomy, tests, observability, and the team's load-bearing conventions BEFORE the LLM writes a line. Pairs with aria-senior-code-audit (post-write review) and aria-readable-output (output layout). Composes — does not block.
+---
+
+# Aria Senior Code Cookbook
+
+The cognition skill that fires BEFORE code is written. A senior team has unwritten rules — file structure, naming, error shapes, test placement, observability defaults. This skill makes those rules explicit, paste-ready, and substrate-anchored so every LLM agent (Claude / Codex / OpenCode) writes against the same priors.
+
+## Prime Doctrine
+
+The fastest path to senior-grade code is having the cookbook in the prompt before the first line is written, not catching bad patterns in review.
+
+- **Organization is correctness, not aesthetic.** A handler in the wrong directory creates a 6-month coupling debt that no audit catches.
+- **Naming is the API contract for humans.** `getUser(id)` and `findUserById(id)` are not interchangeable — they signal different failure modes (throws vs returns null).
+- **Error shape before happy path.** Decide what the function returns under failure BEFORE writing the success branch. The error shape is the contract.
+- **Tests next to code, not in a parallel hierarchy.** Co-located tests get maintained; far-away tests rot.
+- **Observability is not added — it is structural.** The first line of any non-trivial function logs / traces with structured fields. Retrofitting observability is more expensive than installing it.
+
+## Trigger Detection (pre-code surfaces)
+
+Fire BEFORE the LLM writes code when the user prompt contains any of:
+
+- "write a handler / endpoint / function / class / hook / component / module / service"
+- "refactor X into Y" / "extract X" / "split this file"
+- "scaffold a new package / app / service"
+- "add a migration / schema change / index"
+- "wire up tests for X"
+- "set up observability / logging / tracing"
+- "build a CLI / SDK / API client"
+- Tool-call patterns matching `Edit | Write | NotebookEdit | Bash` with code-shaped diff intent
+
+Do NOT fire on read-only ops (read, grep, glob, ls, status), on doc-only edits, or on config files unrelated to runtime contract.
+
+## Required Workflow (paste-ready patterns)
+
+### 1. File Organization (TypeScript / Node monorepo, the team's canonical shape)
+
+```
+package/
+├── src/
+│   ├── index.ts                  ← public surface (re-exports), nothing else
+│   ├── types.ts                  ← shared types; never inline cross-module types
+│   ├── errors.ts                 ← typed error classes, single source of truth
+│   ├── handlers/
+│   │   ├── <name>.ts             ← one handler = one file; named after the route/event
+│   │   └── <name>.test.ts        ← co-located test; vitest or jest
+│   ├── lib/
+│   │   ├── <utility>.ts          ← pure utilities, no I/O
+│   │   └── <utility>.test.ts
+│   ├── adapters/
+│   │   └── <integration>.ts      ← all I/O lives here; mockable seam
+│   └── runtime/
+│       └── server.ts             ← entrypoint, wiring only, no logic
+├── package.json
+├── tsconfig.json
+└── README.md                     ← contract + run / test / deploy
+```
+
+Anti-pattern: `src/utils/helpers.ts` — "utils" and "helpers" are semantic dumping grounds. Name by what it does (`src/lib/url-canonical.ts`).
+
+### 2. Function Contract (TypeScript)
+
+```typescript
+/**
+ * Canonical function shape — read this before writing any non-trivial function.
+ *
+ * @param input  – validated at the boundary; trust nothing from outside
+ * @returns      – discriminated union: success or named failure
+ * @throws       – never (this contract returns errors, doesn't throw)
+ */
+export async function chargeCard(
+  input: ChargeCardInput,
+): Promise<Result<ChargeCardOk, ChargeCardError>> {
+  // 1. validate at the boundary
+  const parsed = ChargeCardInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return err({ kind: 'validation', issues: parsed.error.issues });
+  }
+
+  // 2. log entry with structured fields (NOT just message)
+  log.info('charge_card.start', {
+    customerId: parsed.data.customerId,
+    amount: parsed.data.amount,
+    idempotencyKey: parsed.data.idempotencyKey,
+  });
+
+  // 3. idempotency check BEFORE side effect
+  const existing = await idempotency.get(parsed.data.idempotencyKey);
+  if (existing) return ok(existing);
+
+  // 4. side effect, with named failure surface
+  try {
+    const charge = await stripe.charges.create({ /* ... */ });
+    await idempotency.set(parsed.data.idempotencyKey, charge);
+    log.info('charge_card.ok', { chargeId: charge.id });
+    return ok({ chargeId: charge.id, amount: charge.amount });
+  } catch (e) {
+    log.error('charge_card.failed', { reason: classifyStripeError(e) });
+    return err({ kind: 'stripe_error', reason: classifyStripeError(e) });
+  }
+}
+```
+
+The shape is non-negotiable: validate → log entry → idempotency → side effect → log exit. Any deviation requires explicit reason in PR.
+
+### 3. Error Taxonomy
+
+```typescript
+// errors.ts — single file, no scattered AppError subclasses
+export type AppError =
+  | { kind: 'validation'; issues: ZodIssue[] }
+  | { kind: 'not_found'; resource: string; id: string }
+  | { kind: 'unauthorized'; reason: 'missing' | 'expired' | 'forbidden' }
+  | { kind: 'rate_limited'; retryAfterMs: number }
+  | { kind: 'stripe_error'; reason: 'card_declined' | 'network' | 'unknown' }
+  | { kind: 'database_error'; reason: string }
+  | { kind: 'internal'; reason: string };
+```
+
+Each error kind is a designed surface — the FE / caller knows how to handle it. `internal` is the catch-all and triggers an alert; other kinds are expected.
+
+### 4. Naming Conventions
+
+| Pattern | Meaning |
+|---|---|
+| `getX(id)` | throws on not-found; for required fetches |
+| `findX(id)` | returns null/undefined on not-found; for optional fetches |
+| `loadX(id)` | async, may hit network/cache; signals expense |
+| `tryX(...)` | returns Result<Ok, Err>; never throws |
+| `assertX(...)` | throws if invariant violated; for guards |
+| `withX(...)` | higher-order; wraps a function with X behavior |
+| `createX(...)` | returns a new instance |
+| `applyX(...)` | mutates input |
+| `is/has/canX` | predicate, returns boolean |
+
+Anti-pattern: `processX` (means nothing), `handleX` (means nothing — what does it handle?), `manageX` (means nothing).
+
+### 5. Test Shape
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { chargeCard } from './charge-card';
+
+describe('chargeCard', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('returns ok on successful charge', async () => { /* ... */ });
+
+  // EVERY error kind from the taxonomy gets a test:
+  it('returns validation error on invalid input', async () => { /* ... */ });
+  it('returns existing charge on duplicate idempotency key', async () => { /* ... */ });
+  it('returns stripe_error on card declined', async () => { /* ... */ });
+  it('returns rate_limited when stripe rate limits us', async () => { /* ... */ });
+  it('logs structured fields on entry and exit', async () => { /* ... */ });
+});
+```
+
+Coverage rule: every error branch tested. Happy path tested. Boundary inputs tested. Test count typically ≥ error-kind count + 2.
+
+### 6. Observability Defaults
+
+```typescript
+// log.ts — structured logging, NEVER console.log
+import pino from 'pino';
+export const log = pino({
+  level: process.env.LOG_LEVEL ?? 'info',
+  base: { service: 'aria-soul', version: process.env.GIT_SHA },
+  redact: ['*.password', '*.token', '*.apiKey', '*.authorization'],
+});
+
+// trace.ts — OpenTelemetry, every handler wrapped
+import { trace } from '@opentelemetry/api';
+export const tracer = trace.getTracer('aria-soul');
+```
+
+In every handler, the first wrapping concern is a span; the second is structured log. Both carry `trace_id`, `customer_id`, `tenant_id`.
+
+### 7. React / Next.js Component Contract (FE)
+
+```tsx
+type ButtonProps = {
+  label: string;
+  onClick: () => void;
+  variant?: 'primary' | 'secondary' | 'destructive';
+  loading?: boolean;
+  disabled?: boolean;
+  // explicitly NOT extending HTMLButtonAttributes — keep surface minimal
+};
+
+export function Button({ label, onClick, variant = 'primary', loading, disabled }: ButtonProps) {
+  // accessibility built in, not retrofitted
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled || loading}
+      aria-busy={loading}
+      data-variant={variant}
+      className={buttonStyles({ variant })}
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+}
+```
+
+Component contract rules: minimal prop surface, accessibility default, loading/disabled/error states designed not afterthought, `data-variant` for testability.
+
+### 8. Migration / Schema Change
+
+```sql
+-- 2026-05-09-add-customer-tier.sql
+-- BACKWARD COMPATIBLE: nullable column with default; old code keeps working.
+ALTER TABLE customers ADD COLUMN tier text NOT NULL DEFAULT 'free';
+
+-- Index AFTER column, in the same migration only if small table.
+CREATE INDEX CONCURRENTLY idx_customers_tier ON customers (tier);
+```
+
+Rules: backwards-compat additive change first (nullable / default), backfill script second, NOT-NULL constraint third migration after backfill. Never combine with feature code in same PR.
+
+## Composition
+
+- Calls `aria-repo-doctrine` for repo-mutation discipline
+- Calls `aria-readable-output` for the cookbook injection layout
+- Pairs with `aria-senior-code-audit` (post-write counterpart)
+- Composes with `aria-frontend-architect` / `aria-backend-architect` / `aria-fullstack-orchestrator` (which determine WHAT to build; this skill governs HOW)
+- Composes with `mizan` and `ghazali-8lens` per business-frame defaults
+
+## User-Facing Layout (per `aria-readable-output`)
+
+When this skill fires pre-code, the LLM emits:
+
+```
+## [Plan in one line — e.g. "Add /api/leads handler with idempotency, validation, structured logs, 4 tests"]
+
+### Cookbook patterns this build follows
+- File: `src/handlers/leads.ts` + `src/handlers/leads.test.ts` (co-located)
+- Contract: validate → log entry → idempotency → side effect → log exit
+- Errors: validation | not_found | rate_limited | database_error
+- Tests: one per error kind + happy path + boundary input
+- Observability: structured log + OTel span on entry; trace_id propagated
+
+**Next:** [first concrete commit message + the file the LLM will create first]
+```
+
+Then the actual code. The cookbook is the prior, not the deliverable.
+
+## Recovery Contract (cookbook-time)
+
+If the LLM is asked to write code that violates the cookbook (e.g., "just dump it in utils/helpers.ts"):
+
+- Surface the violation in the plan section, not after the code is written
+- Recommend the canonical location with one sentence of why
+- Proceed with the canonical pattern; if the owner overrides, mark the deviation in the PR description
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.
+
+
+## Self-Executing Recovery Contract
+
+If the cookbook can't be applied because the existing repo has a different convention:
+
+- Read the existing convention via `aria-repo-doctrine` (existing patterns are the local cookbook)
+- Match the existing convention rather than imposing this one — local consistency beats global ideal
+- Surface the gap in the PR if the existing convention is itself a cookbook anti-pattern; recommend the migration path as a separate PR
+
+## Why This Exists
+
+Every senior team has a cookbook. Most are oral tradition. This skill makes ours substrate-anchored so the LLM agents (Claude / Codex / OpenCode) write against the same priors. Pairs with `aria-senior-code-audit` for the post-write check.