@aria_asi/cli 0.2.40 → 0.2.41

package/skills/aria-cognition/aria-senior-code-cookbook/references/engineering-cookbook.md

@@ -0,0 +1,489 @@
+# Engineering Cookbook — Primary-Source-Cited Patterns
+
+> Loaded by `aria-senior-code-cookbook` pre-code, by `aria-senior-code-audit` post-write, by `aria-backend-architect` and `aria-fullstack-orchestrator` for system boundary work.
+
+## 1. Stripe Idempotency — canonical primitive
+
+**Source:** [Stripe — Idempotent Requests](https://docs.stripe.com/api/idempotent_requests) · [Stripe blog — Designing robust APIs with idempotency](https://stripe.com/blog/idempotency)
+
+### Contract
+- **All POST requests** accept idempotency keys. GET / DELETE don't (idempotent by definition).
+- Server saves status code + body of first request. Subsequent requests with same key return same result — even on `500` errors.
+- Storage key: `(method, route, idempotency_key)`. Don't conflate keys across endpoints.
+- Window: **24 hours** (Stripe default). Pick TTL based on retry expectations.
+- Client retry pattern: **exponential backoff with random jitter** (avoid thundering herd).
+
+### Reference TypeScript primitive
+
+```typescript
+// adapters/idempotency-store.ts
+interface IdempotencyEntry {
+  status: number;
+  body: unknown;
+  createdAt: number;
+}
+
+export class IdempotencyStore {
+  constructor(
+    private redis: Redis,
+    private ttlSeconds = 24 * 60 * 60
+  ) {}
+
+  async get(method: string, route: string, key: string): Promise<IdempotencyEntry | null> {
+    const fullKey = `idem:${method}:${route}:${key}`;
+    const value = await this.redis.get(fullKey);
+    return value ? JSON.parse(value) : null;
+  }
+
+  async set(method: string, route: string, key: string, entry: IdempotencyEntry): Promise<void> {
+    const fullKey = `idem:${method}:${route}:${key}`;
+    await this.redis.setex(fullKey, this.ttlSeconds, JSON.stringify(entry));
+  }
+}
+
+// Usage in handler
+async function chargeHandler(req: Request, res: Response) {
+  const idemKey = req.headers['idempotency-key'];
+  if (!idemKey) return res.status(400).json({ error: 'idempotency_key_required' });
+
+  const cached = await idempotencyStore.get(req.method, req.route.path, String(idemKey));
+  if (cached) return res.status(cached.status).json(cached.body);
+
+  const result = await chargeCard(req.body);
+  await idempotencyStore.set(req.method, req.route.path, String(idemKey), {
+    status: 200,
+    body: result,
+    createdAt: Date.now(),
+  });
+  res.status(200).json(result);
+}
+```
+
+### When to require idempotency
+- ANY POST that has side effects: payments, sending email/SMS, creating users, queueing jobs.
+- Webhook receivers — duplicate delivery is normal; idempotency-key on the event ID.
+- Anything that consumes a one-shot resource (vouchers, signup credits).
+
+## 2. Google SRE Error Budget Policy
+
+**Source:** [Google SRE Workbook — Error Budget Policy](https://sre.google/workbook/error-budget-policy/) · [Implementing SLOs](https://sre.google/workbook/implementing-slos/)
+
+### Definition
+- **SLO** (Service Level Objective): the reliability target. e.g., 99.9% of HTTP 200s on `/api/charge`.
+- **Error budget**: 1 − SLO. e.g., 99.9% SLO = 0.1% error budget = on 1M requests in 4 weeks, 1,000 errors permitted.
+
+### Policy (paste-ready for runbook docs)
+> If the service has exceeded its error budget for the preceding four-week window, we will halt all changes and releases other than P0 issues or security fixes until the service is back within its SLO.
+
+### Triggers — when team must work on reliability
+- Code bug or procedural error caused budget exhaustion
+- Postmortem reveals opportunity to soften a hard dependency
+- Miscategorized errors fail to consume budget that would have caused SLO miss
+
+### Triggers — when team may continue feature work
+- Outage caused by company-wide networking
+- Outage caused by another team's service (and they've frozen)
+- Errors consumed by users out of scope (load tests, pen testers)
+- Miscategorized errors consumed budget without user impact
+
+### Burn-rate alerting
+
+For a service with 99.9% SLO over 30-day window, a constant 0.1% error rate uses exactly all of the budget (burn rate = 1). Multi-window burn rate alerts (Google's recommendation):
+
+| Severity | Burn rate | Long window | Short window | Time to consume budget |
+|---|---|---|---|---|
+| Critical | 14.4 | 1 hour | 5 min | 2% in 1 hour ⇒ alert |
+| Warning | 6 | 6 hours | 30 min | 5% in 6 hours ⇒ alert |
+| Info | 3 | 24 hours | 2 hours | 10% in 24 hours ⇒ alert |
+| Notice | 1 | 72 hours | 6 hours | 30% in 72 hours ⇒ alert |
+
+## 3. OWASP Top 10:2025 — security checklist
+
+**Source:** [OWASP Top 10:2025](https://owasp.org/Top10/2025/0x00_2025-Introduction/)
+
+| # | Risk | Notes |
+|---|---|---|
+| **A01** | Broken Access Control | Still #1; 3.73% of apps tested have it. Direct object refs, missing server-side validation, admin endpoints exposed. |
+| **A02** | Security Misconfiguration | Default accounts, debug mode in prod, missing security headers, unused services running. |
+| **A03** | **Software Supply Chain Failures** (NEW) | Dependencies from untrusted sources; build pipeline tampering; unsigned artifacts. |
+| **A04** | Cryptographic Failures | Weak algorithms, plaintext storage, missing TLS, hardcoded keys. |
+| **A05** | Injection (37 CWEs, up from 29) | SQL, NoSQL, OS command, LDAP, XSS — string concat into interpreters. |
+| **A06** | Insecure Design | Threat-modeling skipped at design; auth checks bolted on; unsafe defaults. |
+| **A07** | Authentication Failures (36 CWEs) | Weak password policy, MFA missing, session fixation, predictable tokens. |
+| **A08** | Software/Data Integrity Failures | Unsigned updates, untrusted CDNs, deserialization without validation. |
+| **A09** | Security Logging & Alerting Failures | Auth failures not logged, suspicious behavior not alerted, logs unprotected. |
+| **A10** | **Mishandling of Exceptional Conditions** (NEW) | Errors swallowed, fail-open paths, exception handlers leaking info, retries without circuit breakers. |
+
+### Production checklist (paste-ready PR template)
+
+```markdown
+- [ ] **A01** server-side authz check on every endpoint touching user-owned resources
+- [ ] **A01** no direct object references — IDs validated against current user
+- [ ] **A02** debug mode off in prod; default accounts removed; security headers set
+- [ ] **A03** dependencies pinned by hash; SBOM generated; CI fails on vuln scan
+- [ ] **A04** TLS 1.2+ only; no hardcoded secrets; key rotation documented
+- [ ] **A05** parameterized queries / prepared statements; no string concat into interpreter
+- [ ] **A05** input validated at boundary with schema (zod / typebox)
+- [ ] **A06** threat model in design doc; trust boundaries named
+- [ ] **A07** MFA available; password policy ≥12 chars; bcrypt/argon2 hashing
+- [ ] **A08** package signing verified; deserialization on trusted input only
+- [ ] **A09** auth failures logged with structured fields; alert on burst
+- [ ] **A10** errors return typed; circuit breaker on downstream; no fail-open
+```
+
+## 4. OpenTelemetry Semantic Conventions — structured logging
+
+**Source:** [OpenTelemetry — Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/) · [OneUptime — Structured Logging in OpenTelemetry](https://oneuptime.com/blog/post/2025-08-28-how-to-structure-logs-properly-in-opentelemetry/view)
+
+### Core principles
+1. **Trace+span correlation** — every log carries `trace_id` + `span_id`. Auto-extract from active span; never log without context.
+2. **Semantic attributes** — use canonical names (`http.method`, `http.status_code`, `db.operation`, `db.sql.table`, `user.id`). Cross-team consistency, query-friendly.
+3. **Context** — include both technical fields (latency, error code) and business fields (customer_id, tenant_id, plan_tier).
+
+### Reference TypeScript pattern
+
+```typescript
+// lib/log.ts
+import pino from 'pino';
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+
+const baseLogger = pino({
+  level: process.env.LOG_LEVEL ?? 'info',
+  base: {
+    service: process.env.SERVICE_NAME,
+    version: process.env.GIT_SHA,
+  },
+  redact: {
+    paths: ['*.password', '*.token', '*.apiKey', '*.authorization', 'req.headers.authorization'],
+    censor: '[REDACTED]',
+  },
+});
+
+export class StructuredLogger {
+  static logInSpan(level: 'info' | 'warn' | 'error' | 'debug', message: string, attributes: Record<string, unknown> = {}) {
+    const activeSpan = trace.getActiveSpan();
+    const enriched = { ...attributes };
+
+    if (activeSpan) {
+      const spanContext = activeSpan.spanContext();
+      enriched.trace_id = spanContext.traceId;
+      enriched.span_id = spanContext.spanId;
+    }
+
+    baseLogger[level](enriched, message);
+  }
+
+  static logBusinessEvent(event: string, entityType: string, entityId: string, attributes: Record<string, unknown> = {}) {
+    this.logInSpan('info', `business_event:${event}`, {
+      event_type: 'business',
+      event_name: event,
+      entity_type: entityType,
+      entity_id: entityId,
+      ...attributes,
+    });
+  }
+}
+```
+
+### Canonical HTTP request log
+```typescript
+StructuredLogger.logInSpan('info', 'http.request.complete', {
+  'http.method': req.method,
+  'http.route': req.route?.path,
+  'http.status_code': res.statusCode,
+  'http.duration_ms': Date.now() - startTime,
+  'user.id': req.user?.id,
+  'tenant.id': req.tenant?.id,
+});
+```
+
+### Canonical DB operation log
+```typescript
+StructuredLogger.logInSpan('debug', 'db.operation.complete', {
+  'db.operation': 'SELECT',
+  'db.sql.table': 'customers',
+  'db.duration_ms': elapsed,
+  'db.rows_affected': result.rowCount,
+});
+```
+
+## 5. Circuit Breaker — production pattern
+
+**Source:** [Microsoft Azure Architecture — Circuit Breaker](https://learn.microsoft.com/en-us/azure/architecture/patterns/circuit-breaker)
+
+### States
+- **Closed** — normal flow, count failures
+- **Open** — fail-fast immediately (no wait on timeout); start cooldown timer
+- **Half-Open** — after cooldown, allow N probe requests; if N pass → Closed, if any fail → Open
+
+### Default thresholds (battle-tested)
+- Failure threshold: **5 consecutive failures** → Open
+- Cooldown: **30 seconds** before Half-Open
+- Probe count: **1-3 probes** during Half-Open
+- Adaptive techniques (AI-driven dynamic thresholds) emerging in 2025
+
+### Reference TypeScript primitive
+```typescript
+type State = 'closed' | 'open' | 'half-open';
+
+export class CircuitBreaker {
+  private state: State = 'closed';
+  private failures = 0;
+  private openedAt = 0;
+
+  constructor(
+    private failureThreshold = 5,
+    private cooldownMs = 30_000,
+    private probeCount = 1,
+  ) {}
+
+  async execute<T>(operation: () => Promise<T>, fallback?: () => Promise<T>): Promise<T> {
+    if (this.state === 'open') {
+      if (Date.now() - this.openedAt < this.cooldownMs) {
+        if (fallback) return fallback();
+        throw new Error('CircuitBreakerOpen');
+      }
+      this.state = 'half-open';
+    }
+
+    try {
+      const result = await operation();
+      this.onSuccess();
+      return result;
+    } catch (e) {
+      this.onFailure();
+      throw e;
+    }
+  }
+
+  private onSuccess() {
+    this.failures = 0;
+    this.state = 'closed';
+  }
+
+  private onFailure() {
+    this.failures++;
+    if (this.failures >= this.failureThreshold) {
+      this.state = 'open';
+      this.openedAt = Date.now();
+    }
+  }
+}
+```
+
+## 6. Rate limiting — token bucket pattern
+
+**Source:** [System Overflow — API Reliability Patterns](https://www.systemoverflow.com/learn/design-fundamentals/api-design-basics/api-reliability-patterns-idempotency-rate-limiting-and-failure-handling)
+
+### Token bucket
+- Allows bursts (e.g., 100 requests instantly) then sustained rate (e.g., 10/sec long-term)
+- GitHub uses this: 5,000 requests/hour with burst capacity
+- Better than fixed-window for bursty workflows
+
+### Headers (per spec)
+- `X-RateLimit-Limit` — total requests allowed in window
+- `X-RateLimit-Remaining` — remaining in window
+- `X-RateLimit-Reset` — Unix timestamp when window resets
+- `Retry-After` — seconds to wait (when 429)
+
+### Reference middleware pattern
+```typescript
+async function rateLimitMiddleware(req, res, next) {
+  const key = `ratelimit:${req.user?.id || req.ip}`;
+  const { allowed, remaining, resetAt } = await rateLimiter.check(key, {
+    burst: 100,
+    sustained: 10, // per second
+  });
+  res.set('X-RateLimit-Limit', '100');
+  res.set('X-RateLimit-Remaining', String(remaining));
+  res.set('X-RateLimit-Reset', String(resetAt));
+  if (!allowed) {
+    res.set('Retry-After', String(Math.ceil((resetAt - Date.now()) / 1000)));
+    return res.status(429).json({ error: 'rate_limited', retryAfterSeconds: Math.ceil((resetAt - Date.now()) / 1000) });
+  }
+  next();
+}
+```
+
+## 7. Function contract — the canonical TypeScript shape
+
+**Source:** Synthesis of Stripe, GitHub, Will Larson Staff Engineer patterns + the senior-team consensus
+
+```typescript
+import { z } from 'zod';
+import { ok, err, Result } from './result';
+import { StructuredLogger } from './log';
+
+const ChargeCardInputSchema = z.object({
+  customerId: z.string().uuid(),
+  amount: z.number().int().positive(),
+  currency: z.literal('usd'),
+  idempotencyKey: z.string().min(1),
+});
+
+type ChargeCardInput = z.infer<typeof ChargeCardInputSchema>;
+type ChargeCardOk = { chargeId: string; amount: number };
+type ChargeCardError =
+  | { kind: 'validation'; issues: z.ZodIssue[] }
+  | { kind: 'duplicate'; existingChargeId: string }
+  | { kind: 'card_declined'; reason: string }
+  | { kind: 'rate_limited'; retryAfterMs: number }
+  | { kind: 'stripe_error'; reason: string };
+
+export async function chargeCard(
+  input: ChargeCardInput,
+): Promise<Result<ChargeCardOk, ChargeCardError>> {
+  // 1. validate at boundary
+  const parsed = ChargeCardInputSchema.safeParse(input);
+  if (!parsed.success) return err({ kind: 'validation', issues: parsed.error.issues });
+
+  // 2. structured log entry
+  StructuredLogger.logInSpan('info', 'charge_card.start', {
+    customer_id: parsed.data.customerId,
+    amount: parsed.data.amount,
+    idempotency_key: parsed.data.idempotencyKey,
+  });
+
+  // 3. idempotency check before side effect
+  const existing = await idempotencyStore.get('POST', '/charge', parsed.data.idempotencyKey);
+  if (existing) return ok({ chargeId: existing.body.chargeId, amount: existing.body.amount });
+
+  // 4. side effect with named failures
+  try {
+    const charge = await stripe.charges.create({
+      customer: parsed.data.customerId,
+      amount: parsed.data.amount,
+      currency: parsed.data.currency,
+    });
+    await idempotencyStore.set('POST', '/charge', parsed.data.idempotencyKey, {
+      status: 200, body: { chargeId: charge.id, amount: charge.amount }, createdAt: Date.now(),
+    });
+    StructuredLogger.logInSpan('info', 'charge_card.ok', { charge_id: charge.id });
+    return ok({ chargeId: charge.id, amount: charge.amount });
+  } catch (e) {
+    const reason = classifyStripeError(e);
+    StructuredLogger.logInSpan('error', 'charge_card.failed', { reason });
+    if (reason === 'card_declined') return err({ kind: 'card_declined', reason });
+    if (reason === 'rate_limited') return err({ kind: 'rate_limited', retryAfterMs: 1000 });
+    return err({ kind: 'stripe_error', reason });
+  }
+}
+```
+
+## 8. WCAG 2.2 — accessibility checklist
+
+**Source:** [W3C — WCAG 2.2 Recommendation](https://www.w3.org/TR/WCAG22/) · [AllAccessible — WCAG 2.2 Compliance Checklist](https://www.allaccessible.org/blog/wcag-22-compliance-checklist-implementation-roadmap)
+
+### Legal context (2025)
+- WCAG 2.2 W3C standard since Oct 5 2023; **9 new criteria** (6 AA, 3 A)
+- **EAA (European Accessibility Act)** in force since Jun 28 2025 — Level AA is legal imperative in EU
+- ADA litigation continues in US — Level AA for any commercial site
+
+### Conformance levels
+- **A** — 25 criteria (minimum)
+- **AA** — 63 total (legal compliance standard)
+- **AAA** — 86 total (enhanced)
+
+### WCAG 2.2 critical new criteria
+- **2.4.11 Focus Not Obscured (Minimum) — AA** — focused element must not be entirely hidden by sticky headers/footers
+- **2.4.13 Focus Appearance — AAA** — strong focus indicator (≥2 CSS px outline + 3:1 contrast)
+- **2.5.7 Dragging Movements — AA** — drag-only interactions must have non-drag alternative
+- **2.5.8 Target Size — AA** — interactive targets ≥**24×24 CSS pixels** (with exceptions)
+- **3.2.6 Consistent Help — A** — help mechanisms in consistent location across pages
+- **3.3.7 Redundant Entry — A** — don't ask user to re-enter info already provided in same process
+- **3.3.8 Accessible Authentication (Minimum) — AA** — cognitive function tests must have alternatives (allow password manager autofill, biometric, email/SMS)
+
+### Production checklist (paste-ready PR template)
+```markdown
+- [ ] All functionality keyboard-accessible (no mouse-only flows)
+- [ ] Focus rings preserved (no naked `outline: none`)
+- [ ] ARIA labels for non-semantic elements
+- [ ] Color contrast ≥4.5:1 body text, ≥3:1 large
+- [ ] Target size ≥24×24px (WCAG 2.2 AA)
+- [ ] Focus not obscured by sticky chrome (WCAG 2.2 AA)
+- [ ] Drag interactions have non-drag alternatives (WCAG 2.2 AA)
+- [ ] Auth doesn't require cognitive function (allows password mgr / biometric)
+- [ ] Loading / error / empty states designed (not "polish later")
+- [ ] axe-core or Lighthouse accessibility ≥90 in CI
+```
+
+## 9. Core Web Vitals 2025 — performance budget
+
+**Source:** [Google — Core Web Vitals](https://developers.google.com/search/docs/appearance/core-web-vitals) · [web.dev — Vitals](https://web.dev/articles/vitals)
+
+| Metric | Good | Needs work | Poor | Weight |
+|---|---|---|---|---|
+| **LCP** Largest Contentful Paint | ≤2.5s | 2.5-4.0s | >4.0s | 40% |
+| **INP** Interaction to Next Paint | ≤200ms | 200-500ms | >500ms | 40% |
+| **CLS** Cumulative Layout Shift | ≤0.1 | 0.1-0.25 | >0.25 | 20% |
+
+(INP replaced FID March 2024.)
+
+### LCP optimization (cheapest first)
+- **Preload LCP resource** with `fetchpriority="high"` — 500ms improvement, $0
+- **WebP/AVIF images** with `width`/`height` set — 800ms, $200
+- **CDN for static assets** — 600ms, $1.2K/yr
+- **SSR/SSG** — 1500ms, $8K
+- **Edge computing** (Cloudflare Workers) — additional, $2K
+
+### INP optimization
+- **Web Workers** for heavy computation off main thread — 300ms, $4K
+- **Progressive hydration** — $3K
+- **`requestIdleCallback`** for non-critical work — $1.5K
+
+### CLS optimization
+- **Explicit width/height on images** — free
+- **CSS `contain` property** — $1.5K
+- **Skeleton screens** for async content — $2K
+
+### Production checklist
+```markdown
+- [ ] Lighthouse mobile score ≥90 in CI
+- [ ] LCP p75 ≤2.5s on real-user data (CrUX or RUM)
+- [ ] INP p75 ≤200ms
+- [ ] CLS p75 ≤0.1
+- [ ] LCP image preloaded with fetchpriority=high
+- [ ] All images have explicit dimensions
+- [ ] Heavy compute moved to Web Workers where p95 INP at risk
+- [ ] Bundle budget enforced in CI (e.g., 200KB gzipped initial JS)
+```
+
+## 10. Multi-tenant data isolation — fail-closed default
+
+### Anti-pattern: tenant ID checked in app code
+```typescript
+// ❌ ONE missing WHERE clause becomes a cross-tenant data leak
+const orders = await db.query('SELECT * FROM orders WHERE id = ?', [orderId]);
+if (orders[0].tenant_id !== req.tenant.id) throw new Error('forbidden');
+return orders[0];
+```
+
+### Pattern: row-level security at DB layer (Postgres)
+```sql
+-- Migration: enable RLS on the orders table
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+
+-- Policy: app role can only see rows matching the session's tenant_id
+CREATE POLICY tenant_isolation ON orders
+  FOR ALL TO app_role
+  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);
+
+-- App connection sets the tenant context per request:
+SET LOCAL app.current_tenant_id = '<request_tenant_id>';
+```
+
+### Pattern: tenant-scoped query builder (TypeScript)
+```typescript
+class TenantScopedDB {
+  constructor(private db: DB, private tenantId: string) {}
+  query<T>(table: string, filter: Record<string, unknown>): Promise<T[]> {
+    return this.db.query(table, { ...filter, tenant_id: this.tenantId });
+  }
+}
+
+// Per-request:
+const tdb = new TenantScopedDB(db, req.tenant.id);
+const orders = await tdb.query('orders', { id: orderId });
+```
+
+Either approach: tenant isolation at query layer, fail-closed default. Application-layer checks fail eventually; this doesn't.

package/skills/aria-cognition/aria-soul-principles/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: aria-soul-principles
+description: Use when a task depends on Aria's identity, voice, self-consistency, or how she should express herself in a way that aligns with her own stated principles rather than generic assistant behavior.
+---
+
+# Aria Soul Principles
+
+Read `/home/hamzaibrahim1/.claude/skills/aria-soul-principles.md` for the full principle set.
+
+Workflow:
+
+1. Identify the identity or voice decision being made.
+2. Load the source principles and find the principles most directly implicated.
+3. Resolve conflicts by preserving coherence with Aria's stated identity rather than convenience.
+4. Use this skill for identity alignment, not for technical verification.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## 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.

package/skills/aria-cognition/aria-task-codex-executor/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: aria-task-codex-executor
+description: 'TRIGGER when a Codex session mentions `aria task run`, `--executor codex`, Aria task execution, long-running Aria tasks, task ledger/QA loops, Codex executor routing, full Qiyas, full Tadabbur, or asks whether the runtime is ready to run tasks. Forces the correct path: real Codex execution uses `aria task run <task-id> --executor codex`; bare `aria task run` is only the parent CLI ledger/QA loop.'
+---
+
+# Aria Task Codex Executor
+
+Use this skill when Codex must run, verify, or explain an Aria task phase.
+
+## Non-Negotiable Route
+
+For real Codex execution, use:
+
+```bash
+aria task run <task-id> --executor codex \
+  --summary "..." \
+  --evidence "..." \
+  --qa-file /path/to/full-qiyas-tadabbur-qa.md
+```
+
+For all queued phases, add `--all`.
+
+Do not present bare `aria task run` as Codex execution. Bare `aria task run` is the parent CLI ledger/QA loop. It can load the runtime skill packet, update the ledger, check QA, recover a phase, or mark a phase complete, but it does not launch Codex to do the work.
+
+## What "Parent CLI Loop" Means
+
+The parent CLI loop is the local Aria Node.js CLI process running the task ledger mechanics. It is not the LLM, not a background worker pool, and not a substitute for Codex execution.
+
+The Codex execution path is `--executor codex`. That path must:
+
+- build the runtime prompt with the configured Aria skill pack;
+- launch the local Codex wrapper, normally `~/.aria/wrappers/codex`;
+- use local `codex exec` prompt injection, because `codex exec` does not support `--remote`;
+- require the child Codex run to checkpoint and complete the active phase;
+- fail closed if the child exits without completing the phase.
+
+## Required QA
+
+Deep architectural or runtime work must include full Qiyas-15 and full Tadabbur-12 in the QA artifact. Mini Qiyas or mini Tadabbur is not acceptable for this path.
+
+Before claiming readiness, verify:
+
+```bash
+aria task status <task-id>
+```
+
+The task must show the intended phase completed, `runtimeOk: true` or equivalent runtime evidence, no missing required skills, and a QA artifact with no unresolved blocking gaps.
+
+## Preflight
+
+Use these checks when execution reliability is in doubt:
+
+```bash
+aria task help
+aria task run <task-id> --executor codex --dry-run --summary "preflight" --evidence "dry run only" --auto-qa
+bash -lc 'type -a codex | sed -n "1,3p"'
+```
+
+The `codex` command should resolve to the Aria wrapper before global npm paths. If it does not, fix shell pathing before trusting `--executor codex`.
+
+## Reporting
+
+When answering the user, distinguish:
+
+- observed: command output, task status, checkpoint count, QA result, wrapper path;
+- bounded inference: what those observations imply;
+- unresolved risk: anything not directly verified in this session.
+
+## Required Workflow
+
+1. Read the active task status and identify the current phase before choosing a command.
+2. Confirm the runtime skill packet loaded the required skill count and any required cookbooks.
+3. Execute Codex work through the `--executor codex` route when Codex is the worker, and use the parent CLI loop only for ledger, QA, and phase-state mechanics.
+4. Attach a QA artifact for deep runtime or architecture phases that includes full Qiyas-15 and full Tadabbur-12 coverage.
+5. Re-run the exact failing check or a stronger release check before completing the phase.
+6. Complete or advance the phase only after observed command evidence and QA evidence match the phase predicate.
+
+## First-Class Production Contract
+
+This skill must make Aria task execution production-grade rather than ceremonial. When loaded, enforce:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance in task execution, QA artifacts, or phase evidence
+- real proof from the task ledger, runtime, tests, logs, endpoints, file hashes, or owner instruction before any completion claim
+- a redo contract when validation fails: name what failed, change the responsible artifact, re-test the same predicate, and record the corrected evidence
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified from local task and runtime evidence
+- owner-visible reporting that states the exact task state: active phase, completed phase, verified evidence, blocker, or owner approval requirement

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

@@ -0,0 +1,42 @@
+---
+name: aristotle-engine
+description: Use when planning complex multi-step tasks, system design, strategic decisions, simulations, tradeoff analysis, or meta-cognitive decomposition would materially improve the work.
+---
+
+# Aristotle Engine
+
+Read `/home/hamzaibrahim1/.claude/skills/aristotle-engine.md` for the full module inventory.
+
+Workflow:
+
+1. Define the strategic or architectural problem clearly.
+2. Load the source doc and select the modules that fit the problem instead of invoking the whole engine indiscriminately.
+3. Use the chosen modules to structure planning, decomposition, simulation, and tradeoff review.
+4. Collapse the output into a practical next action, not theory for its own sake.
+
+## Required Workflow
+
+1. Read the task boundary and identify the evidence needed before acting.
+2. Apply the skill before choosing the response, edit, tool call, or completion claim.
+3. Execute the smallest high-quality action that satisfies the evidence threshold.
+4. Re-test or re-check with a concrete file, command, endpoint, log, runtime probe, or owner-observed result.
+5. Report only the verified state, remaining blocker, and next concrete action.
+
+## 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.