@aria_asi/cli 0.2.39 → 0.2.41

package/skills/aria-cognition/aria-fullstack-orchestrator/references/fullstack-cookbook.md

@@ -0,0 +1,383 @@
+# Full-Stack Orchestrator Cookbook — Contract, Sequencing, Deploy-Day Patterns
+
+> Loaded by `aria-fullstack-orchestrator` for end-to-end features (FE + BE + data + deploy).
+> See also: [`../../aria-frontend-architect/references/frontend-cookbook.md`](../../aria-frontend-architect/references/frontend-cookbook.md)
+> See also: [`../../aria-backend-architect/references/backend-cookbook.md`](../../aria-backend-architect/references/backend-cookbook.md)
+> See also: [`../../aria-senior-code-cookbook/references/engineering-cookbook.md`](../../aria-senior-code-cookbook/references/engineering-cookbook.md)
+
+## 1. The Shared Contract Pattern (one source of truth)
+
+The contract is the spine. Both layers derive from it; neither layer invents it.
+
+### Contract location
+```
+packages/contracts/         ← shared package, ZERO runtime deps
+├── src/
+│   ├── charges.ts          ← CharchesContract (zod schema + types)
+│   ├── customers.ts
+│   └── index.ts
+└── package.json            ← used by both apps/backend and apps/frontend
+```
+
+### Contract definition
+```typescript
+// packages/contracts/src/charges.ts
+import { z } from 'zod';
+
+export const ChargeCardRequest = z.object({
+  customerId: z.string().uuid(),
+  amount: z.number().int().positive(),
+  currency: z.literal('usd'),
+  idempotencyKey: z.string().min(1).max(255),
+});
+
+export const ChargeCardSuccess = z.object({
+  chargeId: z.string(),
+  amount: z.number(),
+  status: z.enum(['succeeded', 'pending']),
+});
+
+export const ChargeCardError = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('validation'), issues: z.array(z.unknown()) }),
+  z.object({ kind: z.literal('card_declined'), reason: z.string() }),
+  z.object({ kind: z.literal('rate_limited'), retryAfterMs: z.number() }),
+  z.object({ kind: z.literal('internal') }),
+]);
+
+export type ChargeCardRequest = z.infer<typeof ChargeCardRequest>;
+export type ChargeCardSuccess = z.infer<typeof ChargeCardSuccess>;
+export type ChargeCardError = z.infer<typeof ChargeCardError>;
+
+export const ChargeCardEndpoint = {
+  method: 'POST' as const,
+  path: '/v1/charges',
+  request: ChargeCardRequest,
+  responses: {
+    200: ChargeCardSuccess,
+    400: ChargeCardError,  // validation
+    402: ChargeCardError,  // card_declined
+    429: ChargeCardError,  // rate_limited
+    500: ChargeCardError,  // internal
+  },
+};
+```
+
+### Backend uses contract
+```typescript
+// apps/backend/src/handlers/charges.ts
+import { ChargeCardRequest, ChargeCardSuccess, ChargeCardError } from '@aria/contracts';
+
+export async function chargeHandler(req: Request, res: Response) {
+  const parsed = ChargeCardRequest.safeParse(req.body);
+  if (!parsed.success) {
+    const error: ChargeCardError = { kind: 'validation', issues: parsed.error.issues };
+    return res.status(400).json(error);
+  }
+  // ... handler implementation against the parsed.data shape
+}
+```
+
+### Frontend uses contract
+```typescript
+// apps/frontend/src/api/charges.ts
+import { ChargeCardRequest, ChargeCardSuccess, ChargeCardError } from '@aria/contracts';
+
+export async function chargeCard(input: z.infer<typeof ChargeCardRequest>): Promise<ChargeCardSuccess> {
+  const res = await fetch('/v1/charges', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(input),
+  });
+  if (!res.ok) {
+    const err = await res.json() as ChargeCardError;
+    throw mapErrorToUserMessage(err);
+  }
+  return ChargeCardSuccess.parse(await res.json());
+}
+```
+
+Both layers parse against the same schema. Drift impossible.
+
+## 2. Dominant-Path-First Sequencing
+
+### The 4-phase build
+
+#### Phase 0: Contract lock (Day 1)
+- Backend drafts API contract in `packages/contracts`
+- Frontend reviews contract for FE feasibility
+- Lock the contract. NO handler or component code yet.
+- Output: contract PR merged to main; deploy-blocked feature flag set up
+
+#### Phase 1: Dominant path (Days 2-5)
+Both layers build the ONE happy path against the locked contract:
+- BE: handler for the dominant path; auth + tenant + idempotency + business logic + structured log
+- FE: component for the dominant path; URL/server/form state correct; loading + success states
+- Integration test: FE → BE → DB roundtrip works
+
+NO edge cases yet. NO empty/error/offline states yet.
+
+#### Phase 2: Edge cases & failure modes (Days 6-10)
+- BE: each typed error from the contract has a designed handler path
+- FE: each typed error has a designed UI surface (empty, loading, error per error kind, offline)
+- Tests: one per error response kind
+
+#### Phase 3: Deploy preparation (Days 11-13)
+- DB migrations: backwards-compat additive (3-step pattern from backend cookbook §9)
+- Feature flag wiring (LaunchDarkly / env-var / config-driven)
+- Observability: structured logs + spans + dashboards + alerts
+- Runbook: when this breaks at 3am, what does on-call do?
+
+#### Phase 4: Deploy + Day-1 verification (Day 14)
+- Deploy through canonical pipeline (Pattern A baked-image per `aria-harness-deploy`)
+- Day-1 success predicate measured
+- Decision: keep / rollback / iterate based on the predicate
+
+## 3. The Day-1 Success Predicate
+
+Every full-stack feature ships with an explicit predicate:
+
+| Feature shape | Day-1 predicate examples |
+|---|---|
+| Sign-up flow | "≥80% of signups complete email confirmation in 24h with <2% error rate" |
+| Payment endpoint | "100 successful charges with p99 <500ms and 0 cross-tenant data leaks" |
+| Dashboard | "90% of active users load the dashboard in <3s p95 with 0 client-side errors" |
+| Settings update | "50 settings updates with 0 stale-data bugs and INP <200ms" |
+
+Predicate must be:
+- **Measurable** (numeric or boolean)
+- **Time-bounded** (Day-1 / Day-7 / Day-30 each named)
+- **Tied to user-visible behavior** (not just internal metrics)
+
+### What if the predicate fails
+- **Rollback** if the failure is catastrophic (data loss risk, broken auth, broken payment)
+- **Iterate** if the failure is recoverable (perf miss, edge case found)
+- **Re-diagnose** if the predicate was wrong (the metric we picked didn't capture the actual signal)
+
+## 4. Feature Flag Pattern
+
+### When to use feature flags
+- New features that change user-visible behavior (always)
+- Risky migrations (gradual rollout)
+- A/B tests on backend / frontend
+- Per-tenant feature opt-in (Enterprise customers)
+
+### Flag types
+| Type | Purpose | Lifetime |
+|---|---|---|
+| **Release flag** | Gradual rollout | Days-weeks; remove after 100% |
+| **Permission flag** | Per-tenant feature access | Permanent |
+| **Experiment flag** | A/B test | Days-weeks; remove after decision |
+| **Ops flag** | Kill switch / circuit breaker | Permanent |
+
+### Flag pattern
+```typescript
+// Use the flag inside the handler, not at the route level
+export async function chargeHandler(req: Request, res: Response) {
+  const useNewCharger = await flags.evaluate('charges.new-stripe-flow', {
+    tenantId: req.tenant.id,
+    userId: req.user.id,
+  });
+
+  return useNewCharger
+    ? chargeWithNewFlow(req.body, req.tenant.id)
+    : chargeWithLegacyFlow(req.body, req.tenant.id);
+}
+```
+
+### Flag lifecycle discipline
+- Every release flag has a removal date in the PR description
+- CI fails if a release flag is older than its removal date (force-cleanup)
+- Permanent flags (permission, ops) are explicitly tagged
+
+## 5. The Schema Migration Coordination
+
+### Deploy order (ALWAYS this sequence)
+1. **Migrate DB** (backwards-compat additive): new column nullable with default
+2. **Deploy backend** that writes BOTH old shape (for rollback) and new shape
+3. **Deploy frontend** that reads new shape (with fallback to old shape if missing)
+4. **Backfill** (async if large)
+5. **Migrate DB** (NOT NULL constraint, only after backfill verified)
+6. **Deploy backend** that writes only new shape
+7. **Deploy frontend** that no longer falls back (new shape required)
+8. **Migrate DB** (DROP old column, only if used nowhere — verify with codebase scan)
+
+This is conservative. Most features don't need all 8 steps. But each shortcut earns a specific risk:
+- Skip 1+2 dual-write → can't rollback feature without DB rollback
+- Skip 4 backfill verification → NOT NULL migration fails on existing data
+- Skip 8 DROP → permanent dead column
+
+## 6. Integration Testing (the FE↔BE seam)
+
+### Contract-driven mock server
+Generate a mock server from the contract; FE develops against it during Phase 1:
+```typescript
+// scripts/mock-server.ts
+import { ChargeCardEndpoint } from '@aria/contracts';
+import { generateMock } from '@aria/contracts/mock';
+
+const mockServer = createMockServer({
+  endpoints: [ChargeCardEndpoint],
+  // ChargeCardSuccess shape generated from zod schema
+  defaultResponse: { 200: { chargeId: 'mock_xyz', amount: 1000, status: 'succeeded' } },
+});
+```
+
+### End-to-end test patterns
+```typescript
+// e2e/charge-flow.test.ts
+test('user can charge a card', async ({ page }) => {
+  await page.goto('/checkout');
+  await page.fill('[data-testid="amount"]', '100');
+  await page.click('[data-testid="submit"]');
+  await expect(page.locator('[data-testid="success"]')).toBeVisible();
+});
+
+// Verify each error path:
+test('user sees rate-limited error', async ({ page, mockServer }) => {
+  mockServer.charge.responds(429, { kind: 'rate_limited', retryAfterMs: 5000 });
+  // ... fill form, submit
+  await expect(page.locator('[data-testid="error-rate-limited"]')).toBeVisible();
+});
+```
+
+### Test pyramid for full-stack features
+- **Unit tests**: each function (BE handler logic, FE component rendering)
+- **Integration tests**: handler + DB; component + API mock
+- **E2E tests**: 1-3 critical paths through real (or staged) deployment
+- **Contract tests**: parse production payload against schema; alert on drift
+
+## 7. Observability End-to-End
+
+### Trace propagation
+The trace_id flows from frontend → backend → downstream services:
+```typescript
+// FE: send trace_id in custom header
+fetch('/v1/charges', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'traceparent': generateTraceparent(),
+  },
+  body: JSON.stringify(input),
+});
+
+// BE: pick up traceparent and propagate
+const traceparent = req.headers.traceparent;
+const span = tracer.startSpan('charge', { /* parent context */ });
+```
+
+### Per-feature dashboard
+Every full-stack feature has:
+- Throughput (requests / hour)
+- Latency p50, p95, p99
+- Error rate (broken down by error kind)
+- Day-1 success predicate (live measurement)
+- Per-tenant top-N (which tenants are most affected by errors)
+
+### Per-feature alert
+- Error rate > X% over 1 hour
+- Latency p99 > target × 2 over 1 hour
+- Day-1 predicate failing (alert immediately for the first deploy)
+
+## 8. Day-1 Runbook Pattern
+
+For every feature deployed, write the runbook BEFORE deploy:
+
+```markdown
+# Runbook: charge-card endpoint
+
+## Healthy
+- error rate <1%
+- p99 latency <500ms
+- 100+ successful charges per hour during business hours
+
+## Degraded
+**Symptom**: error rate 1-5%, p99 500-1000ms
+**Likely causes**: Stripe latency spike, DB connection saturation
+**Action**:
+1. Check Stripe status: https://status.stripe.com
+2. Check DB connection pool metrics: [link]
+3. If Stripe issue: monitor; circuit breaker handles
+4. If DB: scale up pool size; alert DB team
+
+## Critical
+**Symptom**: error rate >5%, OR cross-tenant data leak detected
+**Action**:
+1. Page on-call engineer
+2. Roll back via: `kubectl rollout undo deployment/charges`
+3. Set kill switch flag: `flags.set('charges.kill-switch', true)`
+4. File incident: severity-1
+5. Slack #incidents
+
+## Rollback procedure
+- `kubectl rollout undo deployment/charges -n production`
+- Verify: `kubectl rollout status deployment/charges`
+- Confirm via canary endpoint: `curl https://api.example.com/charges/health`
+
+## Common errors and fixes
+- **`stripe_error: rate_limited`**: rate limit hit on Stripe; back off
+- **`internal: db_connection_timeout`**: DB pool saturated; check pool metrics
+- **`validation: ...`**: client-side bug; check error_id in logs
+
+## Owners
+- Primary: @engineering-charges
+- Secondary: @platform-team
+- Page: pagerduty/charges
+```
+
+## 9. Anti-patterns (full-stack specific)
+
+### Writing FE and BE in parallel without locked contract
+The most common cause of integration hell at PR time. Lock contract first.
+
+### Deploying schema + feature in same PR
+Cannot rollback feature without DB rollback. Schema lands first, feature lands second.
+
+### "Day-1 success will be obvious"
+If you can't predicate it, you can't measure it. Always declare the metric upfront.
+
+### Treating deploy as "after the build is done"
+Deploy shape changes the build. Phase 3 is first-class, not afterthought.
+
+### Building all paths at once
+Dominant path first, edge cases second. Half-shipped features come from parallel-everything.
+
+### No runbook before deploy
+On-call at 3am needs the runbook. Writing it after the incident is too late.
+
+## 10. Full-stack audit checklist (paste-ready)
+
+```markdown
+## Phase 0
+- [ ] Shared contract in `packages/contracts/`
+- [ ] Contract reviewed by both BE + FE
+- [ ] Mock server runs against contract
+
+## Phase 1 (dominant path)
+- [ ] BE handler implements happy path against contract
+- [ ] FE component implements happy path against contract
+- [ ] FE↔BE integration test passes (real or mocked)
+
+## Phase 2 (edge cases)
+- [ ] BE: each typed error has handler path
+- [ ] FE: each typed error has UI surface
+- [ ] Empty / loading / error / offline states designed
+- [ ] Tests: one per error response kind
+
+## Phase 3 (deploy prep)
+- [ ] DB migration: backwards-compat additive
+- [ ] Feature flag set up (with removal date if release flag)
+- [ ] Observability: spans + structured logs + dashboard + alerts
+- [ ] Runbook written
+
+## Phase 4 (deploy + verify)
+- [ ] Deploy through canonical pipeline
+- [ ] Day-1 predicate measured
+- [ ] Decision: keep / rollback / iterate
+
+## Cross-cutting
+- [ ] Trace_id flows FE → BE → downstream
+- [ ] Schema, feature, and deploy each in separate PRs
+- [ ] No flag with stale removal date in CI
+- [ ] Rollback procedure tested before deploy (chaos engineering basics)
+```

package/skills/aria-cognition/aria-gtm-architect/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: aria-gtm-architect
+description: TRIGGER for any go-to-market, launch, channel, distribution, positioning, audience, ICP, persona, message, copy, hook, headline, ad creative, landing-page, SEO, paid-acquisition, organic, referral, virality, PLG-vs-sales-led, partnership-channel, content-strategy, or competitive-positioning turn. Composes the cognitive substrate with a channel-fit + message-fit + economics-fit triple frame.
+---
+
+# Aria GTM Architect
+
+The cognition skill for go-to-market structure — channel choice, message-market fit, distribution economics. Pairs with `aria-business-frame` (composer), `aria-readable-output` (layout), `aria-revenue-engine` (pricing), and `aria-customer-truth` (research).
+
+## Prime Doctrine
+
+GTM fails three ways: wrong channel for the buyer, wrong message for the moment, wrong economics for the channel. Diagnose which one is broken before changing tactics.
+
+- **Channel-fit before tactic-fit.** Before optimizing an ad, ask whether ads are the right channel for this buyer at this stage. Most "creative iteration" is rearranging deck chairs on the wrong ship.
+- **Message-fit is buyer-language fit.** If the buyer doesn't say "I have problem X" the way your headline says X, the message is upstream-broken, not creative-broken.
+- **Distribution economics is a system, not a campaign.** CAC payback, channel concentration, attribution decay — these compound over months. A tactic that wins this week and breaks the system loses.
+- **The one channel rule.** Most companies under $5M ARR have one dominant channel. Forcing diversification too early dilutes the dominant channel without saving the company.
+
+## Trigger Detection
+
+Fire on:
+
+- Launch planning, GTM strategy, channel selection
+- Positioning / messaging / copy / hook / headline
+- Audience / ICP / persona / segmentation
+- Paid (ads, sponsorships) / organic (SEO, content) / referral / partner / outbound channel design
+- Landing-page / funnel-step optimization
+- Competitive positioning / differentiation / moat narrative
+- Brand voice / tone / category creation
+- PLG vs sales-led architecture decisions
+
+## Required Workflow (3-fit triple)
+
+Every GTM decision must answer all three before recommending:
+
+1. **Channel-fit** — Where does this buyer make decisions? Where do they search, ask, complain, recommend? If the channel doesn't intersect that path, no creative will save it.
+2. **Message-fit** — In the buyer's own words, what problem do they have? What language do they use about it? Does our headline match? (If the buyer says "I lose deals to no-shows" and we say "automate your scheduling pipeline" — that's a translation gap.)
+3. **Economics-fit** — What's the CAC for this channel at the volume we need? What's the payback period? What's the channel-attribution decay (does month 2 attribution overlap with another channel's month 1)?
+
+If any one fit fails, the whole GTM motion fails — typically by month 6, not month 1.
+
+## Channel-Specific Lens Maps
+
+When `ghazali-8lens` runs under this skill, lens definitions bind to GTM:
+
+- **truth** — does the channel data reflect attribution reality, or are we double-counting / under-counting?
+- **harm** — does this campaign / message risk the brand if it succeeds at scale?
+- **trust** — does the audience already trust the source of this distribution? Cold audiences require trust transfer.
+- **power** — is the leverage in our content, our network, our paid spend, or in someone else's distribution?
+- **reflection** — does the message survive reading it 12 months later in a Wayback snapshot?
+- **context** — does this work because of a temporary trend (algo change, news cycle) or a durable structural fit?
+- **impact** — predicted CAC + LTV/CAC ratio + payback period at scale
+- **beauty** — does the message feel inevitable to the buyer, or assembled by committee?
+
+## User-Facing Layout
+
+```
+## [Decision: name the channel + message + economics in one line]
+
+- [Channel-fit evidence — buyer-path data, named source]
+- [Message-fit evidence — buyer's own words, citation]
+- [Economics-fit evidence — CAC, payback, LTV/CAC ratio]
+- [Predictor predicate — measurable]
+
+**Next:** [first concrete action with measurable test, e.g., "Spend $2K on Reddit ads against r/realestate; measure CTR > 1.8% and CPL < $40 over 7 days"]
+```
+
+Optional `<gate>` block for irreversible launch commitments (public announcements, partnership exclusives).
+
+## Composition Rule
+
+- Composes with `aria-business-frame`
+- Calls `aria-customer-truth` for buyer-language and JTBD evidence (REQUIRED before message-fit work)
+- Calls `aria-revenue-engine` for pricing and packaging that the GTM motion sells
+- Calls `mizan` for intent/evidence/protection/quality
+- Calls `tadabbur` for "what happens if this works at 10x" — channel saturation, brand stretch
+- Calls `predictor` for the channel test predicate
+- Calls `noor-recognition` for prior channel experiments and their actual outcomes (often more useful than fresh analysis)
+- Hands off to `aria-finance-realism` for budget envelope and runway impact
+
+## Recovery Contract
+
+- If buyer-language data is missing: do NOT recommend a message. Either run a 5-call user-research sprint via `aria-customer-truth`, or surface 3 candidate messages with the explicit note "untested." Never present untested messaging as recommended.
+- If channel data is thin: recommend a channel TEST with explicit budget cap, time cap, and stop-criteria. The test itself is the deliverable, not the channel choice.
+- If economics don't pencil at any channel: surface that explicitly — the answer may be "this product needs a different price or a different audience before any channel works." Do NOT cycle through tactics.
+- Log GTM decisions to coach kernel with `risk_class: 'gtm_action'` so the next turn can check whether the predicate held.
+
+## Anti-Patterns
+
+- "We'll do content + paid + outbound + partnerships" without naming which is dominant — the diversification trap before product-channel fit
+- Recommending a creative before validating the buyer-language match (cart before horse)
+- Quoting CAC without naming attribution model and decay assumption (CAC is a function of attribution choice)
+- Copying a competitor's GTM motion without checking whether their channel-fit applies to your buyer (most don't)
+- Optimizing the funnel step that has highest dropout instead of the step where small lift compounds most (math, not gut)
+
+## 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 GTM recommendation cannot be made with confidence:
+
+- One re-run with the missing fit (channel / message / economics) explicitly identified
+- If still insufficient, recommend the smallest reversible test that would generate the missing evidence — and ship that as the action
+- Never produce "we could try X or Y" without naming which to try first and why
+
+## Why This Exists
+
+Engineering correctness has 51 cognitives in this repo. GTM has had zero. Most owner-impact mistakes come from GTM, not code. This skill closes the gap by binding the same Aria substrate to GTM-specific lens definitions and a channel/message/economics triple frame.