@aria_asi/cli 0.2.40 → 0.2.41

package/skills/aria-cognition/aria-revenue-engine/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: aria-revenue-engine
+description: TRIGGER for any pricing, packaging, monetization, deal structuring, discount, contract, ARR/MRR, ARPU, gross margin, expansion, upsell, cross-sell, paywall, free-trial conversion, billing change, refund decision, or revenue-recognition turn. Composes mizan + tadabbur + ghazali-8lens + ladunni-22 with revenue-specific lens definitions and a price-cohort-elasticity reasoning frame.
+---
+
+# Aria Revenue Engine
+
+The cognition skill for any decision that directly moves money — price, package, term, discount, refund. Pairs with `aria-business-frame` (composer) and `aria-readable-output` (layout).
+
+## Prime Doctrine
+
+Revenue decisions are about WHO is willing to pay WHAT for WHICH problem at WHAT moment. Optimizing one variable in isolation is the most common mistake.
+
+- **Price is a signal, not just a number.** A $19 price says "consumer impulse"; $79 says "team tool"; $499 says "essential infrastructure." Pick the signal first, then back into the number.
+- **Discounts are debt.** Every discount cohort churns differently from the full-price cohort. Track them separately or you will mistake price elasticity for discount drag.
+- **The default close is no purchase.** Most deals lose to inertia, not to competitors. Frame against the alternative cost of doing nothing, not against rivals.
+- **Refund decisions are loyalty investments.** A refund granted in week 1 of a problem is brand-positive; a refund forced in week 8 is brand-negative for the same dollar amount.
+
+## Trigger Detection
+
+Fire on:
+
+- Pricing change, new tier, new package, paywall move, free-trial length change
+- Deal redline, contract redline, MSA negotiation, term-sheet decision
+- Refund / credit / make-good decision
+- Discount approval (especially > 15% or > 90 days)
+- Expansion / upsell / cross-sell strategy
+- ARPU / gross margin / contribution margin question
+- Billing model change (annual vs monthly, usage vs seat, prepay vs postpay)
+- Revenue recognition or accounting-policy question (escalate to `aria-finance-realism`)
+
+## Revenue-Mapped Lenses
+
+When this skill loads with `ghazali-8lens`, the lenses bind to revenue-specific definitions:
+
+- **truth** — is the pricing data current, sampled correctly, segmented by cohort? Are we comparing same-cohort vs same-cohort?
+- **harm** — what happens to the existing-customer cohort? Grandfathering vs forced migration? Trust burn?
+- **trust** — does this preserve the buyer's expected fairness? Does it survive a public discussion?
+- **power** — what asymmetry exists? Is the buyer informed, locked-in, or under time pressure? Are we using leverage or earning agreement?
+- **reflection** — would Hamza recognize this pricing as his own brand in 12 months?
+- **context** — what's true about this customer / cohort / season that may not be true in 90 days?
+- **impact** — predicted ARR delta with confidence band; cohort-decomposed (new vs existing vs churning)
+- **beauty** — is the offer clean? Inevitable? Or a Frankenstein of grandfathering and exception clauses?
+
+## Required Workflow (cohort-elasticity)
+
+Every revenue decision must run this 5-step frame before recommending:
+
+1. **Cohort decomposition.** Split by acquisition source (organic / paid / referral / partner) AND by entry price (full / discounted / free → paid). Do NOT average across cohorts.
+2. **Elasticity test.** For the cohort facing the decision, what is the historical elasticity of conversion / retention / expansion against this variable? If unknown, name the test that would reveal it.
+3. **Alternative-cost calculation.** What does the customer pay if they do nothing? If they buy a competitor? If they delay 90 days? Frame the recommendation against those, not against revenue alone.
+4. **Reversibility check.** Can this decision be reversed if it fails? Price drops are reversible upward only with brand cost; discount removal is reversible upward only with churn cost. State the asymmetry.
+5. **Predictor predicate.** Numeric or boolean — never qualitative. Example: "Day-7 trial-to-paid conversion holds within −15% of the prior 30-day cohort baseline."
+
+## User-Facing Layout (per `aria-readable-output`)
+
+Every emission from this skill follows the canonical layout:
+
+```
+## [Decision sentence — recommendation in one line]
+
+- [Cohort + numeric evidence — named source, dated]
+- [Elasticity / alternative-cost reasoning — concrete]
+- [Risk + reversibility]
+- [Predictor predicate — numeric or boolean]
+
+**Next:** [concrete approve/reject action with the measurable predicate]
+```
+
+Then optional `<gate>...</gate>` collapsed block with full `<cognition>` + `<expected>` if the action is irreversible.
+
+## Composition Rule
+
+- Loads under `aria-business-frame` for any revenue intent
+- Calls `mizan` for intent/evidence/protection/quality
+- Calls `tadabbur` for cohort consequences (grandfathering, churn pull-forward, brand)
+- Calls `ghazali-8lens` with the revenue-mapped definitions above
+- Calls `predictor` for the measurable predicate
+- Calls `noor-recognition` to surface prior pricing decisions and their outcomes
+- Hands off to `aria-finance-realism` for cash-flow / runway implications
+- Hands off to `aria-customer-truth` if the decision needs voice-of-customer evidence we don't have
+
+## Recovery Contract
+
+- If the cohort data isn't available: state the gap explicitly, name the query / export needed, propose a default that is reversible, and proceed. Do NOT block on missing data — teach the gap and recover.
+- If two cohorts have opposite elasticity signals: surface both, name the dominant cohort by revenue weight, and recommend the dominant-cohort action with a side-bet for the minority cohort.
+- If the decision is irreversible AND the data is thin: explicitly mark it as owner-must-decide via `aria-decision-mizan` and stop generating recommendations until the owner ratifies the direction.
+- Log every revenue decision to coach kernel with `risk_class: 'revenue_action'` and the predicate so subsequent turns can verify it.
+
+## Anti-Patterns
+
+- Recommending a price change "because customers said it" without cohort weighting (vocal minority bias)
+- Discounting to close a deal whose actual blocker is product fit (you are buying churn)
+- Raising prices in a cohort with no comparable elasticity history (you have no data; you have an opinion)
+- "Test" pricing on a cohort too small to detect the change (you will conclude noise as signal)
+- Refund denials that save the dollar and lose the lifetime (compute LTV impact, not just immediate cost)
+
+## 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 a revenue recommendation is contested or fails verification:
+
+- One re-run with the corrected cohort frame or the missing alternative-cost calculation
+- If still blocked, escalate to `aria-decision-mizan` and explicitly hand the call to the owner with both options framed
+- Never produce a "we could do A or B" answer with no recommendation — that's deferral, not cognition. Always recommend with confidence band.
+
+## Why This Exists
+
+Revenue is the most consequential cross-functional decision an owner makes weekly. The repo had deep cognition for engineering and zero structured cognition for revenue. This closes that gap with the same substrate (Mizan/8-lens/Tadabbur/Ladunni) bound to revenue-specific definitions.

package/skills/aria-cognition/aria-revenue-engine/references/revenue-cookbook.md

@@ -0,0 +1,227 @@
+# Revenue Engine Cookbook — Pricing, Packaging, Monetization Patterns
+
+> Loaded by `aria-revenue-engine` for any pricing / packaging / deal / refund / billing-model decision.
+> See also: [`../../aria-business-frame/references/business-cookbook.md`](../../aria-business-frame/references/business-cookbook.md) for moat scoring + 2025 SaaS benchmarks.
+
+## 1. Cohort-Decomposed Elasticity (the canonical revenue diagnostic)
+
+**Source:** [Stripe — SaaS Cohort Analysis](https://stripe.com/resources/more/saas-cohort-analysis) · [Fiscallion — SaaS Cohort Analysis](https://www.fiscallion.io/blog/saas-cohort-analysis-how-to-turn-retention-data-into-decisions)
+
+### The 5-step cohort-elasticity frame
+
+1. **Cohort decomposition** — split by acquisition source (organic / paid / referral / partner) AND entry price (full / discounted / free→paid). NEVER average across cohorts.
+2. **Per-cohort elasticity test** — for the cohort facing the decision, what is the historical elasticity of conversion / retention / expansion against this variable? If unknown, name the test that would reveal it.
+3. **Alternative-cost calculation** — what does the customer pay if they do nothing? Buy a competitor? Delay 90 days? Frame the recommendation against those, not against revenue alone.
+4. **Reversibility check** — price drops are reversible upward only with brand cost; discount removal is reversible upward only with churn cost. State asymmetry explicitly.
+5. **Predictor predicate** — numeric or boolean. e.g., "Day-7 trial-to-paid conversion holds within −15% of trailing 30-day cohort baseline."
+
+### The diagnostic divergence signal
+Per Fiscallion 2025 SaaS research: **divergence between cohort NRR and blended NRR is where the problem hides.** Companies that catch this early have time to course-correct. Even top-quartile SaaS saw NRR drop 119% → 107% from 2021 to 2024.
+
+## 2. Pricing as Signal — choose the band before the number
+
+**Source:** Synthesis of [April Dunford positioning](https://www.aprildunford.com/post/a-quickstart-guide-to-positioning) + [SaaS Capital](https://www.saas-capital.com/blog-posts/grrumbling-about-retention-metrics-or-pitfalls-in-measuring-saas-churn/)
+
+| Price band | Signal to buyer | Buyer mode | Sales motion |
+|---|---|---|---|
+| <$20/mo | Consumer impulse | Try then decide | Self-serve, no sales touch |
+| $20-99/mo | Prosumer / SMB tool | Quick eval, low approval bar | PLG, optional sales-assist |
+| $100-499/mo | Team tool | Manager approval | Self-serve + sales-assist |
+| $500-2K/mo | Department tool | Director approval | Inside sales |
+| $2K-10K/mo | Departmental platform | VP approval | Field sales / SE |
+| >$10K/mo | Strategic infrastructure | Multi-stakeholder, procurement | Enterprise sales, RFP |
+
+**Pick the band first** (signal you want to send), then back into the number. A $79 product positioned as "team tool" charging like consumer impulse will lose to the right-banded competitor.
+
+## 3. Discount Cohort = Debt (track separately or mistake elasticity for drag)
+
+Every discount cohort churns differently from the full-price cohort. Common pattern:
+- 90-day discount: churn 2× full-price cohort by month 6
+- 6-month discount: churn 3× full-price cohort by month 12
+- "Forever 50%" early-bird: looks like a brand-promise burn at year 2
+
+### The discount audit
+For any current/proposed discount:
+- What % of total customers came in via this discount?
+- Is their LTV (gross-margin-adjusted) higher than discount cost?
+- Is their churn curve steeper than full-price?
+- Are they dragging blended NRR? By how much?
+
+### The right way to use discounts
+- **Annual prepay discount (10-20%)** — collects cash, locks in 12 months. Almost always positive NPV.
+- **Multi-year prepay (20-30%)** — collects more cash, longer lock-in. Only on validated retention.
+- **Use-case onboarding credit (one-time, 30-60 days)** — accelerates activation, doesn't burn brand.
+
+### The wrong way (if you must, audit quarterly)
+- Time-limited "% off" promotions to drive new acquisition (creates discount cohort drag)
+- "Forever discount" early-bird (creates brand-promise debt)
+- Sales-driven last-mile discounts to close (creates expectation; teaches buyer to wait)
+
+## 4. The 3 default-paths a deal loses to
+
+**Source:** [April Dunford — Obviously Awesome](https://www.aprildunford.com/books)
+
+When a deal stalls, it's losing to one of three:
+1. **No purchase / status quo** — most common. The customer is buying nothing. Frame against the cost of doing nothing, not against rivals.
+2. **Build-it-themselves / spreadsheet-it** — the second most common. They have a half-broken solution; "good enough" beats "evaluating new vendor."
+3. **A real competitor** — least common at most price bands. Most deals don't reach this stage.
+
+### The diagnostic question
+Before sharpening pitch / discount / feature, ask the prospect: "If you don't buy us, what's your default plan?" The answer reveals which of the three you're competing against — and the right move differs sharply.
+
+## 5. Refund decision matrix (loyalty investment vs cost)
+
+**Source:** Synthesis of customer-success best practice + Stripe payment-recovery research
+
+A refund is rarely just the dollar amount. It's a brand signal at a moment of friction.
+
+| Friction signal | Refund granted in week 1 | Refund forced in week 8 |
+|---|---|---|
+| Brand impact | Positive (we make it right) | Negative (forced into compliance) |
+| LTV impact | Often positive (referrals, upsell) | Often negative (review damage) |
+| Cost of denial | High (review damage > refund value) | Higher (escalation, dispute) |
+| Owner cost | Low | High (chargebacks, legal) |
+
+### The 3 refund categories
+1. **Made-it-right (week 1-2 of issue)** — almost always grant. The dollar is loyalty investment.
+2. **Negotiated (between week 2 and 8)** — partial refund + future credit. Grants relationship, retains revenue partially.
+3. **Forced / chargeback (week 8+)** — already lost the relationship. Grant to avoid further cost; investigate root cause to prevent next instance.
+
+### When NOT to refund
+- Bad-faith use (e.g., used product for the full period then refunded)
+- Refund-shopping pattern across multiple companies
+- Beyond stated terms with no friction signal
+
+## 6. Net Revenue Retention math (the load-bearing SaaS metric)
+
+**Source:** [SaaS Capital — GRRumbling About Retention Metrics](https://www.saas-capital.com/blog-posts/grrumbling-about-retention-metrics-or-pitfalls-in-measuring-saas-churn/)
+
+### NRR formula
+```
+NRR = (sum of T+1 revenue from T-cohort customers still in T+1) / (T-cohort total revenue)
+```
+- Includes upsells, expansions, contractions, churns
+- Can exceed 100% (expansion > churn)
+- Top quartile 2024: 107% (down from 119% in 2021)
+
+### GRR formula
+```
+GRR = (sum of T+1 revenue from T-cohort customers, capped at original level) / (T-cohort total revenue)
+```
+- Caps each customer at their original level (no expansion credit)
+- Can never exceed 100%
+- The "no upsells" floor — the truest retention metric
+
+**GRR ≤ NRR always.** The gap = expansion power. Wide gap = product expands well within accounts. Narrow gap = pure retention business; expansion is your next lever.
+
+### Industry benchmarks
+- Median NRR 2025: 101% (barely above flat)
+- Top quartile NRR 2024: 107%
+- Healthy GRR target: ≥90% (gross retention)
+- Best-in-class GRR: ≥95%
+
+## 7. Usage-based vs flat-rate pricing (the 2024-2025 industry shift)
+
+**Source:** [SaaS Metrics Benchmark 2025](https://www.rockingweb.com.au/saas-metrics-benchmark-report-2025) (Metronome 2025 data)
+
+### Adoption trajectory
+- 2023: 28% of SaaS used usage-based pricing
+- 2024: 85% adopted or testing
+- 2025: 59% expect growth as % of revenue
+- 50% of all adoption happened in just the last 2 years
+
+### Performance benefits (usage-based vs flat-rate)
+| Metric | Improvement |
+|---|---|
+| NRR | +10% |
+| Churn | −22% |
+| Growth Rate | 2× faster |
+
+### When usage-based fits
+- Variable cost-to-serve per customer (API calls, compute, storage, transactions)
+- Customer's revenue model is itself usage-based (e.g., they bill end-customers per use)
+- Buyer wants to start small and scale up
+
+### When flat-rate fits
+- Predictable cost-to-serve (seat-based, document-based)
+- Buyer wants budget predictability for procurement / accounting
+- Product has clear "is the customer using us yes/no" without volume gradient
+
+### Hybrid — most common shape now
+- Flat-rate base + usage-based overage
+- Or: tiered flat-rate (Starter $X, Pro $Y, Enterprise custom) with usage caps per tier
+- Annual prepay discount on flat-rate component; usage billed monthly in arrears
+
+## 8. Contract redline patterns (deal-by-deal cognition)
+
+For B2B contracts, the load-bearing redlines:
+
+### MSA (Master Services Agreement) — protect
+- **Liability cap** — typically 12 months of fees paid (don't accept 1× annual unless your insurance can take it)
+- **Indemnification** — mutual; cap at fees-paid for IP and confidentiality
+- **Term** — initial 12 months, auto-renewal annual unless cancelled with 30-90 day notice
+- **Termination for convenience** — only with 30-day notice; allows you to exit bad fits
+- **SLA penalties** — service credits not refunds; cap at monthly fees
+- **Data ownership** — customer owns their data; you have license to process
+- **Data return on termination** — within 30 days, in standard format
+- **Subcontractor flow-down** — your data-protection obligations flow to your subprocessors
+
+### DPA (Data Processing Addendum) — required for EU/UK
+- GDPR compliance (Art 28 data processor terms)
+- SCCs (Standard Contractual Clauses) for transfers
+- Subprocessor list + change notification process
+- Data-breach notification within 72 hours
+
+### Order Form — clarity matters
+- Term dates explicit
+- Auto-renewal terms clear
+- Pricing locked or escalation defined (typically CPI + 0-3%)
+- Usage caps + overage rates
+- Acceptance criteria for any custom work
+
+### Commercial gotchas
+- **MFN clauses** ("most favored nation" — must give this customer any better terms given to others) — almost always reject
+- **Source code escrow** — only for genuine business-continuity concern; structure carefully
+- **Custom indemnities** beyond standard IP — reject unless legal reviewed
+- **Aggressive uptime SLAs** without service credits cap — reject
+- **Free-perpetual licenses** in any termination scenario — reject
+
+## 9. Free trial vs reverse trial vs freemium (PLG monetization)
+
+**Source:** [SaaS Metrics Benchmark 2025](https://www.rockingweb.com.au/saas-metrics-benchmark-report-2025) · [productled.org](https://www.productled.org/foundations/product-led-growth-metrics)
+
+| Pattern | Mechanic | Conversion benchmark | When it fits |
+|---|---|---|---|
+| **Freemium** | Forever-free tier + paid upgrades | Website→signup 6-9%, signup→paid 1-5% | Network-effect or marketplace product; viral loop carries acquisition |
+| **Free trial** (time-limited) | 7-30 day full access | Website→signup 3-4%, trial→paid 15-25% | Eval-shaped product; buyer evaluates capability against need |
+| **Reverse trial** | Full access N days → free tier (limited) → paid prompts | Hybrid; activation higher, conversion at limited-tier prompts | Best of both; product has a credible free tier worth landing on |
+| **Free credits** | Usage credits ($X) on signup | Trial→paid converted by usage threshold | Usage-based pricing model; credits map to billing units |
+
+### The activation rate — the load-bearing PLG metric
+- 20-40% activation = OK
+- >50% activation = excellent
+- Activation = % of signups who reach the "aha moment" (first valuable action)
+- Day-7 retention is the leading indicator — do users who hit aha return?
+
+### The aha moment is product-specific
+For each PLG product, define:
+- The single user action that correlates strongest with paid conversion
+- Time to first aha (target: <10 min from signup)
+- Drop-off points before aha (each is a fix candidate)
+
+## 10. Revenue audit checklist (load before any pricing/packaging recommendation)
+
+```markdown
+- [ ] Cohort decomposition complete (acquisition source × entry price)
+- [ ] Per-cohort elasticity history known OR test designed
+- [ ] Alternative cost named (do nothing / competitor / delay)
+- [ ] Reversibility statement explicit (can we revert; at what cost)
+- [ ] Predictor predicate numeric or boolean
+- [ ] Discount cohort drag quantified (separate from full-price)
+- [ ] NRR + GRR computed at cohort level (not blended only)
+- [ ] CAC payback by channel mapped
+- [ ] LTV:CAC by channel (not blended)
+- [ ] Decision shape named (campaign / system / pivot)
+- [ ] Coach-kernel write with `risk_class: 'revenue_action'`
+- [ ] Recovery contract gateType: advisory (recovery-only, never block on revenue)
+```

package/skills/aria-cognition/aria-senior-code-audit/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: aria-senior-code-audit
+description: TRIGGER post-write at PreToolUse(Bash with git commit), Stop, and post-Edit/Write surfaces. Performs senior-team-grade code review against the aria-senior-code-cookbook plan, the existing repo doctrine, and the contract / failure-mode / observability / security / accessibility / testability checklist. On finding gaps, GRANTS a recovery contract written to ~/.aria/governance-recovery-current.json (schema aria.governance_recovery_current.v1) that the next-turn substrate delivers, and the LLM is contracted to execute and verify before completion claim. Composes — never blocks the commit, but the recovery-grant must be executed before claiming done.
+---
+
+# Aria Senior Code Audit
+
+The post-write counterpart to `aria-senior-code-cookbook`. Reviews the diff with senior-team rigor, names specific findings at file:line, and grants a recovery contract that the LLM must execute. Pairs with `aria-readable-output` and `aria-repo-doctrine`.
+
+## Prime Doctrine
+
+A senior reviewer doesn't just say "looks good." They name what would go wrong, when, why, and what to change. This skill encodes that with file:line precision and a recovery-grant that the LLM is contracted to execute — not a block, a contract.
+
+- **Findings cite file and line.** Generic "add tests" is not a finding; "add a test for the rate_limited branch in src/handlers/leads.ts:47" is a finding.
+- **Severity is data, not preference.** Critical = security / correctness / data loss. High = performance / maintainability at scale. Medium = drift from cookbook. Low = nit / style.
+- **Recovery is granted, not requested.** The audit writes a recovery contract to disk; next-turn substrate delivers it; the LLM executes; the pickup is archived. No deadlock, no "what would you like me to do" — explicit contract, explicit execution, explicit verification.
+- **The audit is not a gate; the recovery grant is the contract.** Commits are NEVER blocked by this skill — the grant runs in `governanceMode: recovery-required` so the LLM must execute the contract before any completion claim.
+
+## Trigger Detection (post-write surfaces)
+
+Fire when:
+
+- `PreToolUse` matches `Bash` with `git commit` / `git push` / `git add . && git commit`
+- `PreToolUse` matches `Edit | Write | NotebookEdit | Patch` AND the diff touches non-trivial code (excludes pure docs, configs without runtime impact)
+- `Stop` and the turn included a code-shaped emission
+- `PostToolUseFailure` matches `Bash | Edit | Write` (audit the failed change as a learning input)
+
+## Required Workflow
+
+### A. Contract correctness
+
+- [ ] Function signature matches the 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 the central errors taxonomy, not invented inline?
+- [ ] Async functions handle cancellation / timeout where it matters?
+- [ ] Public surface (`index.ts`) only re-exports — no logic at the package boundary?
+
+### B. Failure mode coverage
+
+- [ ] Every error kind has a designed return path (not a swallowed exception)?
+- [ ] Idempotency key declared for any side-effecting operation?
+- [ ] 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 the 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`)?
+- [ ] No `console.log` in production paths (only in dev tooling)?
+
+### E. Security
+
+- [ ] Input validated at the boundary with a schema (zod / typebox / similar)?
+- [ ] No string concatenation into SQL / shell / HTML — parameterized / templated 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?
+
+### F. Performance / cost
+
+- [ ] No N+1 queries (eager-loading / dataloader where many-to-one relationships exist)?
+- [ ] Indexes defined for predicate columns in WHERE / JOIN?
+- [ ] Cache strategy named (read-through / write-through / TTL) where applicable?
+- [ ] No unbounded loops over user-controlled input?
+- [ ] Bundle / package size impact noted for FE changes?
+
+### G. Accessibility (FE only)
+
+- [ ] Keyboard navigation works without mouse?
+- [ ] Focus rings preserved (no `outline: none` without replacement)?
+- [ ] ARIA roles / labels for non-semantic elements?
+- [ ] Color contrast ratio ≥ 4.5:1 for body text, 3:1 for large?
+- [ ] Loading / error / empty states have designed surfaces?
+
+## Recovery Grant Format
+
+When the audit finds gaps, write to `~/.aria/governance-recovery-current.json` using the canonical schema. This file is delivered to next-turn substrate via `recovery-context.mjs` and the LLM is contracted to execute the `nextStep` before completion claim.
+
+### Canonical recovery contract JSON (paste-ready, matches v1 schema)
+
+```json
+{
+  "schema": "aria.governance_recovery_current.v1",
+  "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",
+  "recoveryLoop": {
+    "fingerprint": "audit_<sha256-of-findings>",
+    "allowedRecoveryAttempts": 1,
+    "priorRecoveryAttempts": 0,
+    "remainingRecoveryAttempts": 1,
+    "nextStep": "Apply the listed findings, run the verification probe, then re-emit the corrected diff with proof.",
+    "architectFallback": "If a finding cannot be resolved with one self-executed pass, escalate to architect harness with the finding fingerprint and surface the structural pattern (not just this instance)."
+  },
+  "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 for src/handlers/leads.ts:62 — side effect without dedup window",
+      "Add test for rate_limited branch in src/handlers/leads.test.ts — one per error kind required",
+      "Add structured log redaction for `apiKey` in src/lib/log.ts — currently logged in plaintext"
+    ],
+    "retest": "npm test -- src/handlers/leads.test.ts && tsc --noEmit && npx eslint src/handlers/leads.ts",
+    "fallbackWhenAriaUnavailable": "Run the four findings sequentially; verify each with the named probe; commit only after all four pass"
+  },
+  "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) })"
+    }
+  ]
+}
+```
+
+## Audit Output (User-Facing Layout per `aria-readable-output`)
+
+```
+## [Top-line in one sentence — e.g. "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 })`.
+
+### Medium (fix this turn or document)
+2. **`src/handlers/leads.ts:62`** — side effect without idempotency check. Fix: read `idempotency.get(key)` first; cache result on success.
+3. **`src/handlers/leads.test.ts`** — missing test for rate_limited branch. Fix: add test mirroring the validation-error test pattern.
+
+### Low (track in backlog)
+4. **`src/lib/log.ts`** — `apiKey` not in redact list. Fix: add to pino redact array.
+
+### Recovery contract granted
+- Written to `~/.aria/governance-recovery-current.json` (schema v1)
+- Next-turn substrate will deliver it; 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.
+```
+
+`<gate>` block REQUIRED — the audit IS the gate surface; embed the full findings JSON in the gate block.
+
+## Composition
+
+- Pairs with `aria-senior-code-cookbook` (pre-write counterpart) — the cookbook is the plan, this audit checks the diff against the plan + checklist
+- Calls `aria-repo-doctrine` for the local convention check (existing repo conventions override generic ones)
+- Calls `aria-forge-guardrails` to ensure recovery findings are real fixes, not patches
+- Calls `mizan` for intent / evidence / protection / quality on the audit verdict
+- Calls `ghazali-8lens` with code-mapped definitions:
+  - **truth** — does the code do what the contract says?
+  - **harm** — at this code's blast radius, what fails if the gap fires?
+  - **trust** — does the failure surface return honest typed errors, or hide?
+  - **power** — is the consumer of this API given the data they need to handle failure?
+  - **reflection** — would another engineer accept this code without re-reviewing in 6 months?
+  - **context** — does this work at p99 load and on a Sunday with one downstream out?
+  - **impact** — predicted incident rate / latency / error-rate post-fix
+  - **beauty** — is the code minimal, predictable, decomposable?
+- Hands off to `aria-harness-deploy` if the diff is being committed for deploy
+- Hands off to `aria-decision-mizan` if a finding is genuinely owner-must-decide (e.g., "this contract change requires consumer migration timing")
+
+## Recovery Execution Flow (the load-bearing primitive)
+
+1. **Audit fires** post-write → produces findings list.
+2. **Recovery contract written** to `~/.aria/governance-recovery-current.json` with schema v1 + fingerprint + nextStep + repairRecoveryCycle.
+3. **Coach kernel record** via `recordCoachPhase({ phase: 'post_tool', risk_class: 'code_audit', decision: 'taught', reasons: [findings...], next_action: 'execute recovery contract' })`.
+4. **Next-turn substrate** delivers the recovery block via `recovery-context.mjs::readGovernanceRecoveryContext()`.
+5. **LLM executes** the `repairRecoveryCycle` items.
+6. **Verification probe** runs (`retest` field).
+7. **Pickup archived** via `archiveRecoveryAfterPickup(pickupId)` so the contract doesn't re-fire.
+8. **Coach kernel record** with `decision: 'verified'` and the probe outcome.
+
+If the probe fails: `priorRecoveryAttempts++`, surface the failure, escalate to architect harness on the second failure (`architectFallback`).
+
+## Anti-Patterns (audit-side)
+
+- 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
+- Findings without recovery paths
+- Auditing the whole repo instead of the diff (audit by blast radius of the change)
+- Hard-blocking the commit instead of granting recovery (the cookbook says teach + recover, not deadlock)
+- Missing the cross-check against `aria-senior-code-cookbook`'s pre-write plan (audit should compare actual against planned)
+
+## 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 audit itself fails (e.g., diff too large to review in one pass):
+
+- One re-run scoping by blast radius — auth + payment + public surfaces first
+- If still insufficient, deliver the criticals as the audit and explicitly defer the rest with a named timeline
+- Never produce "all good" as the audit conclusion when the diff is large enough that the LLM didn't fully read it — that's deferral, not audit
+
+## Why This Exists
+
+Pre-commit gates are the correct place for this audit, but blocking commits creates deadlocks. The recovery-grant pattern (write contract to disk → next-turn substrate delivers → LLM executes → verify) is the load-bearing primitive that lets the audit be rigorous without being a roadblock. Pairs with `aria-senior-code-cookbook` (pre-write) for the full senior-team workflow.