@aria_asi/cli 0.2.40 → 0.2.41

package/dist/runtime/discipline/skills/aria-cognition/aria-repo-audit/references/repo-audit-cookbook.md

@@ -0,0 +1,375 @@
+# Repo Audit Cookbook — Drift, Debt, Risk Patterns
+
+> Loaded by `aria-repo-audit` for systematic repository health diagnostics.
+> See also: [`../../aria-senior-code-cookbook/references/engineering-cookbook.md`](../../aria-senior-code-cookbook/references/engineering-cookbook.md) (OWASP §3, observability §4)
+> See also: [`../../aria-senior-code-audit/references/audit-checklist.md`](../../aria-senior-code-audit/references/audit-checklist.md) (per-PR audit primitives)
+
+## 1. The 5-Category Finding Taxonomy
+
+Every repo finding fits in one of five categories. Each has a different fix shape.
+
+### A. Drift findings
+Code that has reorganized away from documented or intended pattern.
+- Feature flags long-stale (release flag past removal date)
+- Deprecated APIs still called
+- Doctrine doc / code disagreement
+- Schema vs migration drift
+- Config diverged across environments
+
+**Fix shape**: usually campaign (1-3 days). High leverage because drift compounds.
+
+### B. Debt findings
+Known shortcuts, "TODO: revisit" markers, untested code in critical paths.
+- Stub-shaped functions in production
+- Test coverage gaps in critical paths (auth, payments, data export)
+- Comment markers (`TODO`, `FIXME`, `HACK`, `XXX`) without ledger entry
+- Hardcoded values that should be config
+
+**Fix shape**: usually system (1-4 weeks). Most code "tech debt" is actually here.
+
+### C. Risk findings
+Security issues, dependency vulns, secrets in code, unguarded destructive ops.
+- Secrets in code (API keys, passwords, tokens)
+- SQL injection vectors (string concatenation into queries)
+- Missing auth on protected endpoints
+- Multi-tenant isolation gaps (WHERE-clause-only checks)
+- Outdated dependencies with CVEs
+- Missing rate limits on expensive endpoints
+
+**Fix shape**: criticals are campaign (24-72 hours); systemic risks are system.
+
+### D. Performance / cost findings
+Unindexed queries, N+1 patterns, missing caches, oversized bundles.
+- Unindexed query columns in WHERE / JOIN
+- N+1 query patterns (loop with DB call inside)
+- Missing cache where computation is expensive
+- Bundle > performance budget
+- Memory leaks (unbounded data structures)
+- Cron schedules that overlap or run more frequently than needed
+
+**Fix shape**: depends on impact; sometimes campaign, often system.
+
+### E. Ops-readiness findings
+Missing observability, missing runbook, missing alerts, missing SLOs.
+- No structured logging
+- No SLO defined for critical service
+- No alert on critical metric
+- No runbook for production endpoint
+- Single-point-of-failure deploy (no rollback path)
+- Database without backups OR backup never tested
+
+**Fix shape**: usually campaign per service; systemic ops-readiness is system-shaped.
+
+## 2. The Severity × Blast Radius Matrix
+
+```
+         Severity
+         CRITICAL   HIGH      MEDIUM    LOW
+        +--------+--------+--------+--------+
+PUBLIC  | EMERG  | URGENT | WEEK   | LATER  |
+        +--------+--------+--------+--------+
+PAY/AUTH| URGENT | URGENT | WEEK   | LATER  |
+        +--------+--------+--------+--------+
+INTERNAL| WEEK   | WEEK   | MONTH  | BACKLOG|
+        +--------+--------+--------+--------+
+DEAD    | BACKLOG| BACKLOG| BACKLOG| BACKLOG|
+        +--------+--------+--------+--------+
+```
+
+### Blast radius categories
+- **PUBLIC**: customer-facing surface — public web, public API, customer dashboard
+- **PAY/AUTH**: payment path, authentication, authorization, sensitive data
+- **INTERNAL**: internal tools, admin panels, employee-only surfaces
+- **DEAD**: code with no live callers (verify before flagging)
+
+### Severity definitions
+- **CRITICAL**: data loss risk, security breach risk, payment failure risk
+- **HIGH**: significant functional gap, performance regression, maintainability disaster
+- **MEDIUM**: drift from cookbook, missing test for non-critical path, suboptimal pattern
+- **LOW**: nit, style, refactor opportunity
+
+### Action timing by cell
+- **EMERG**: drop everything; fix today
+- **URGENT**: fix this week
+- **WEEK**: fix in 7 days
+- **MONTH**: fix in 30 days
+- **LATER**: fix in 90 days
+- **BACKLOG**: track but don't prioritize
+
+## 3. The Anti-Pattern of Aesthetic Findings
+
+### NOT a finding
+- "This file is 500 lines long"
+- "This function has 6 parameters"
+- "This variable name is unclear"
+
+These are aesthetic preferences, not predictions of defect.
+
+### IS a finding
+- "This file is 500 lines long AND it's the auth module AND there are no tests for the password-reset path AT line 247"
+- "This function has 6 parameters AND 4 of them are optional booleans which is the toggle-fest anti-pattern AT [name]"
+- "This variable name is unclear AND it's used in 12 places across files AND its semantics differ in 3 of them"
+
+Pattern: aesthetic concern + concrete defect prediction = finding.
+
+## 4. The Audit-By-Blast-Radius Strategy
+
+### The trap
+Auditing "the whole repo" never finishes. Criticals sit unfixed while the audit chases low-severity findings in dead code.
+
+### The strategy
+1. **Sweep 1**: Public surfaces only (CRITICAL + HIGH). Stop when done.
+2. **Sweep 2**: Pay/auth surfaces (CRITICAL + HIGH + MEDIUM).
+3. **Sweep 3**: Internal surfaces if time/budget remains.
+4. **Skip**: dead code surfaces (delete the dead code as a separate PR).
+
+This produces an actionable audit in days, not weeks.
+
+## 5. Common Drift Patterns (Aria-specific examples)
+
+### Stale release flags
+```typescript
+// flags.config.ts
+{
+  'charges.new-stripe-flow': {
+    type: 'release',
+    rolloutStarted: '2024-08-15',
+    removalDate: '2024-09-15',  // ← already past; finding
+    state: '100% rollout',       // ← finding: should be removed
+  },
+}
+```
+
+### Deprecated API still called
+```typescript
+// Old code that should have been updated:
+const user = await api.legacyGetUser(id);  // ← finding: legacyGetUser deprecated 2024-10
+```
+
+### Doctrine vs code disagreement
+- Doctrine says: "no graceful degradation"
+- Code has: `try { ... } catch { return null; }`  // ← finding: silent catch matches doctrine_trigger_map
+
+### Config drift
+- Production: `LOG_LEVEL=info`
+- Staging: `LOG_LEVEL=debug` (drift)
+- Local dev: `LOG_LEVEL=warn` (further drift)
+
+## 6. Common Debt Patterns
+
+### Test coverage gaps in critical paths
+```typescript
+// charges.ts has 12 functions
+// charges.test.ts tests 3 of them
+// Missing tests for: card_declined branch, rate_limited branch, idempotency replay
+// These are the 3 most-likely-to-fire branches
+// → finding: test gap in critical-path
+```
+
+### Stub-shaped functions in prod paths
+```typescript
+// Comment trail is the smell:
+// TODO: implement properly — Hamza 2024-09
+function calculateTier(): Tier {
+  return 'free';  // ← finding: hard-coded; production-impact
+}
+```
+
+### Hardcoded values that should be config
+```typescript
+const STRIPE_API_KEY = 'sk_test_xxx';  // ← finding: secret in code
+const RATE_LIMIT_WINDOW = 60;          // ← finding: hardcoded; should be env or config
+const MAX_RETRIES = 3;                 // ← finding: hardcoded; should be tunable
+```
+
+## 7. Common Risk Patterns
+
+### Secrets in code (use detection tools)
+```bash
+# Detection
+gitleaks detect --source=. --verbose
+trufflehog filesystem .
+
+# Prevention
+# .gitleaks.toml in repo
+# Pre-commit hook runs gitleaks before commit
+```
+
+### SQL injection vectors
+```typescript
+// ❌ String concatenation
+db.query(`SELECT * FROM users WHERE id = ${userId}`);  // injection
+
+// ❌ Template literals (same issue)
+db.query(`SELECT * FROM users WHERE id = '${userId}'`);
+
+// ✅ Parameterized
+db.query('SELECT * FROM users WHERE id = $1', [userId]);
+```
+
+### Missing auth on protected endpoint
+Pattern to scan for: routes that accept user-data shapes without verifying ownership.
+```typescript
+app.post('/api/orders/:id/cancel', async (req, res) => {
+  // ← finding: req.user not checked against orders.owner_id
+  await db.query('UPDATE orders SET cancelled = true WHERE id = $1', [req.params.id]);
+});
+```
+
+### Multi-tenant isolation at app layer (not query layer)
+```typescript
+// ❌ Application-layer check
+const order = await db.query('SELECT * FROM orders WHERE id = $1', [orderId]);
+if (order.tenant_id !== req.tenant.id) throw new ForbiddenError();
+return order;
+
+// One missing WHERE clause anywhere = cross-tenant leak
+// ✅ RLS at DB layer (see backend cookbook §3)
+```
+
+## 8. Common Performance Findings
+
+### N+1 queries
+```typescript
+// ❌
+const users = await db.query('SELECT * FROM users WHERE active = true');
+for (const user of users) {
+  user.orders = await db.query('SELECT * FROM orders WHERE user_id = $1', [user.id]);
+}
+// 1 + N queries
+
+// ✅ JOIN or dataloader
+const usersWithOrders = await db.query(`
+  SELECT u.*, json_agg(o.*) as orders
+  FROM users u LEFT JOIN orders o ON o.user_id = u.id
+  WHERE u.active = true GROUP BY u.id
+`);
+```
+
+### Missing index on hot column
+```sql
+-- High-traffic query
+SELECT * FROM orders WHERE customer_id = $1 ORDER BY created_at DESC LIMIT 10;
+
+-- Without index on customer_id: full table scan
+-- With index: O(log n) lookup + sequential read
+CREATE INDEX CONCURRENTLY idx_orders_customer_id_created_at
+  ON orders (customer_id, created_at DESC);
+```
+
+### Unbounded list operations
+```typescript
+// ❌ Pulls all customers into memory
+const customers = await db.query('SELECT * FROM customers');
+return customers.map(processCustomer);
+
+// ✅ Paginate or stream
+const customers = await db.query('SELECT * FROM customers WHERE id > $1 ORDER BY id LIMIT 1000', [cursor]);
+```
+
+## 9. Common Ops-Readiness Findings
+
+### No SLO for critical service
+Service handles auth requests but no SLO defined → can't measure when it's broken at scale.
+**Fix**: define SLO (e.g., 99.9% availability, p99 < 200ms over 30 days), set up burn-rate alerts.
+
+### No structured logging
+Service uses `console.log("user signed in")` → can't query logs at scale.
+**Fix**: replace with structured logger (engineering-cookbook §4).
+
+### No runbook for production endpoint
+On-call gets paged, has no docs → MTTR (mean time to recovery) high.
+**Fix**: write runbook (fullstack-cookbook §8).
+
+### Database without tested backups
+"We have backups" but never tested restoring → de facto no backups.
+**Fix**: schedule monthly restore drill into staging; verify data integrity.
+
+## 10. The Audit Output Layout
+
+```markdown
+## [Top-line in one sentence — e.g. "3 critical findings in auth + payment paths; 12 high; 27 medium; fix the 3 criticals this week"]
+
+### Critical (fix in 7 days)
+1. **`apps/auth/src/handlers/login.ts:47`** [CRITICAL × PAY/AUTH]
+   - **Rule**: A07 Authentication Failures
+   - **Symptom**: JWT signature verification not strict — accepts expired tokens
+   - **Blast radius**: every authenticated request
+   - **Recovery path**: change `verify(..., { expiresIn })` to explicitly check `exp` claim; add test for expired token
+   - **Verification**: `npm test -- auth/login.test.ts` (test asserts expired token returns 401)
+
+2. ... (continue for criticals)
+
+### High (fix in 30 days)
+- `apps/charges/src/handlers/refund.ts:88` — N+1 query on refund line items; impacts page load >1s for orders with >20 items
+- `apps/dashboard/src/api/metrics.ts:34` — missing rate limit on expensive endpoint; risk of resource exhaustion
+- ...
+
+### Medium (track in backlog)
+- 27 findings; samples:
+  - 9 stale TODO markers without ledger entries (drift)
+  - 6 missing structured-log fields on user-facing handlers (ops-readiness)
+  - 4 unindexed columns on hot queries (performance)
+  - 8 misc (style, naming, doc drift)
+
+### Fix-priority matrix
+- **Campaign-shape (1-3 days each)**: 3 criticals + 4 high (prod-impacting)
+- **System-shape (1-4 weeks)**: refactor of orders module + dashboard query layer
+- **Backlog**: 27 medium + low
+
+**Next:** start with the 3 criticals; assign owners; PR target end of week. Ledger them to coach kernel as `risk_class: 'repo_audit'` with the verification probes.
+```
+
+## 11. Repo audit anti-patterns
+
+### Aesthetic findings as audit findings
+Long file, deep nesting, clever code — without a defect prediction, these are not findings.
+
+### Severity inflation
+Calling everything CRITICAL erodes the signal. Criticals must satisfy: data loss risk, security breach risk, or payment failure risk.
+
+### Findings without recovery paths
+A complaint, not a finding. Each finding has a concrete fix path.
+
+### "Refactor X" as a fix when 1-line fix solves it
+Don't convert a 1-line fix into a project. Fix the actual finding minimally.
+
+### Auditing whole repo before delivering criticals
+The 3 criticals shouldn't wait for the full audit. Deliver criticals in scope first.
+
+### Quoting "best practices" without naming the defect
+"Always use TypeScript strict mode" is best practice. The finding is "this file lacks strict mode and has 4 instances of implicit any that mask real type errors at runtime."
+
+## 12. Repo audit checklist (paste-ready)
+
+```markdown
+## Audit scope
+- [ ] Blast radius defined (public / pay-auth / internal / dead)
+- [ ] In-scope sweep complete; out-of-scope explicitly deferred
+
+## Findings
+- [ ] All findings in 5 categories (drift / debt / risk / perf / ops-readiness)
+- [ ] All findings have severity × blast radius cell
+- [ ] All findings have file:line + recovery path + verification probe
+
+## Fix-priority matrix
+- [ ] Campaign-shape findings listed
+- [ ] System-shape findings listed
+- [ ] Backlog explicit (not lost)
+- [ ] Predictor predicate per critical (post-fix outcome measurable)
+
+## Coach kernel
+- [ ] `risk_class: 'repo_audit'` events written
+- [ ] Recovery contract granted with `gateType: escalating` (most pass; criticals route to review)
+
+## OWASP A01-A10:2025 swept
+- [ ] All 10 categories checked against codebase
+- [ ] CI gates set for new code (lint, dep-vuln scan, secret scan)
+
+## Ops-readiness baseline
+- [ ] SLO defined for each critical service
+- [ ] Structured logging in place
+- [ ] Alerts wired
+- [ ] Runbooks present
+- [ ] Backup restore drill scheduled
+```

package/dist/runtime/discipline/skills/aria-cognition/aria-research-orchestrator/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: aria-research-orchestrator
+description: TRIGGER when the substrate is missing the data needed to answer with confidence and external evidence acquisition is required — competitive research, market sizing, regulatory check, vendor evaluation, customer-language harvesting, technical spec research, library / framework comparison, pricing benchmarks, RFC / spec lookups, news / current-event verification, or any "I need to research X" request. Fires the Perplexity Computer / Aria research stack with a question-decomposition + source-quality + freshness frame, then synthesizes back into the calling skill's cognition pass.
+---
+
+# Aria Research Orchestrator
+
+The cognition skill that triggers external evidence acquisition. Pairs with every other skill — when they need data the substrate doesn't have, this skill orchestrates the fetch.
+
+## Prime Doctrine
+
+The substrate is the source of truth for what we already know. Research is the source of truth for what we don't yet know but need.
+
+- **Research is a tool, not a default.** Most owner questions are memory-resolvable (Noor). Run research only when the substrate genuinely lacks the data, the data has changed, or the data must be from a source the owner trusts.
+- **Question decomposition before fetching.** A vague research request produces vague answers. Decompose into 2-5 specific sub-questions, each with a known source class.
+- **Source quality matters more than quantity.** Three first-party sources beat 30 secondary sources. Rank sources by primary > secondary > tertiary; rank within tier by recency, authoritativeness, methodology transparency.
+- **Freshness is not always good.** For some questions the canonical source is the spec / paper / official doc — even if older. For others (pricing, market data) freshness within 30 days is required. Match freshness to question type.
+- **Synthesize back to the calling skill.** Research output is not the final answer. Hand it back to the skill that requested it (e.g., `aria-revenue-engine` for pricing benchmarks) so the cognition completes with the new evidence.
+
+## Trigger Detection
+
+Fire when:
+
+- Owner explicitly asks "research X" / "look up X" / "what's the current Y"
+- A calling skill (revenue-engine, gtm-architect, business-audit, etc.) flags a substrate gap that needs external data
+- A claim requires citation that isn't in memory
+- A vendor / library / framework decision needs current comparison
+- Regulatory / legal / compliance context needs verification
+- Customer-language harvesting (review mining, support-ticket text, forum threads)
+- Competitive intelligence (positioning, pricing, feature comparison)
+- News / current-event verification with date-sensitive claims
+
+## Required Workflow (decompose → source → fetch → verify → synthesize)
+
+Every research run produces:
+
+1. **Question decomposition.** Break the request into 2-5 sub-questions, each phrased so the answer is checkable. Bad: "research project management tools." Good: "for SMB SaaS founders, what are the 3 most-mentioned project tools in 2026 podcasts? + what's the avg seat price for Linear, Asana, Jira at 10-50 seats?"
+2. **Source class per sub-question.** Each sub-question gets a source class:
+   - **Primary**: official docs, specs, RFCs, financial filings, vendor pricing pages, first-party blog
+   - **Authoritative-secondary**: industry analyst reports (Gartner, Forrester, ARK), peer-reviewed research, named-author technical posts
+   - **Aggregated-secondary**: review sites (G2, Capterra), comparison sites, well-curated GitHub awesome-lists
+   - **Tertiary / signal**: social-media discussion, forum threads, podcast transcripts (use for customer-language only, not for facts)
+3. **Fetch strategy.** Browser-based (live page, current pricing/news), search-based (need ranked results), academic (papers/specs), shopping (product comparison), code (GitHub repos, docs), social (X/Reddit/forums for sentiment).
+4. **Verification cycle.** For each non-trivial claim, name 2 independent sources or explicitly mark as single-sourced. Cross-check primary vs secondary when feasible.
+5. **Freshness check.** Each source carries a date. If the answer is time-sensitive, reject sources beyond the freshness window.
+6. **Synthesis back to caller.** Hand the verified evidence back to the calling skill in its native format (cohort data for revenue-engine, channel benchmarks for gtm-architect, etc.) and let it complete the cognition.
+
+## Tool Mapping (Perplexity Computer / Aria research stack)
+
+This skill fires the appropriate research tool based on the sub-question shape:
+
+| Sub-question shape | Tool | Notes |
+|---|---|---|
+| "What does this URL say?" | `fetch_url` with prompt | extracts specific info; cite the URL |
+| "What's currently true about X?" (broad) | `search_web` with 2-3 keyword queries | use natural-phrase queries, parallel where independent |
+| "Find papers / specs on X" | `search_vertical(vertical='academic')` | first-party sources for technical/scientific |
+| "Find product / pricing for X" | `search_vertical(vertical='shopping')` | comparison + pricing |
+| "Find people who do X at Y" | `search_vertical(vertical='people')` | for hiring / partnership / interview research |
+| "Show me images / videos of X" | `search_vertical(vertical='image' or 'video')` | for design research, demo research |
+| "I need to actually use this site" (login, fill form) | `browser_task` | only when read-only fetch is insufficient |
+| "Compare 10+ entities" | `wide_research` or `wide_browse` | confirm with owner if 20+ entities (cost gate) |
+
+## Research-Mapped Lenses (`ghazali-8lens`)
+
+- **truth** — is the source first-party? Dated? Methodology-transparent?
+- **harm** — does our use of this research mislead anyone (e.g., quoting a benchmark out of context)?
+- **trust** — would the owner / customer / counterparty accept this source as authoritative?
+- **power** — does the research cite the people who actually decide, or the people who blog about it?
+- **reflection** — would this research hold up if we re-ran it in 6 months?
+- **context** — does the source's context match ours (geography, business shape, scale)?
+- **impact** — does the research actually change the calling skill's recommendation, or just decorate it?
+- **beauty** — is the synthesis clean (3-5 bullets the owner can act on) or bloated (a 20-source bibliography)?
+
+## User-Facing Layout (per `aria-readable-output`)
+
+```
+## [Research conclusion in one line — e.g. "Linear is the dominant 2026 SMB choice; $8/seat at 10-50 seats; reviews flag onboarding friction"]
+
+- [Sub-question 1 answer + source — primary or secondary, dated]
+- [Sub-question 2 answer + source]
+- [Sub-question 3 answer + source]
+- [Caveat / freshness / single-sourced flags if any]
+
+**Next:** [hand off to calling skill — "feeding to aria-revenue-engine for pricing recommendation"]
+```
+
+For complex research, optionally a "## Sources" section at the bottom with full citation. Never inline the full URL list in the headline / why bullets.
+
+## Composition Rule
+
+- Called by: any skill that flags a substrate gap
+- Calls: research tools per the tool mapping above
+- Always calls `noor-recognition` first to check if the answer is in memory before fetching externally (research is expensive; memory is free)
+- Calls `predictor` to set the freshness / source-quality predicate BEFORE fetching
+- Hands off to: the calling skill, with verified evidence in the calling skill's expected format
+
+## Recovery Contract
+
+- If a sub-question can't be answered after 2 fetch attempts: explicitly mark as "unable to verify" and hand back to the calling skill. Do NOT fabricate a citation.
+- If sources contradict each other: surface the contradiction, name the more authoritative source by the source-class hierarchy, recommend the conservative reading.
+- If the owner wants the answer faster than research can deliver: surface the partial answer with explicit confidence weight, complete the research in the background, and update.
+- If the calling skill's gap is genuinely an owner-must-decide question (not a research question): hand back to `aria-decision-mizan`.
+- Log research runs to coach kernel with `risk_class: 'research_action'` and the freshness/source-quality predicate.
+
+## Anti-Patterns
+
+- Running research before checking memory (Noor) — wasted cost, slower turn
+- Vague research requests not decomposed into sub-questions
+- Quoting tertiary sources as if they were primary
+- Single-sourcing time-sensitive claims without flagging
+- Burying the conclusion in a bibliography instead of leading with it
+- Failing to hand the synthesis back to the calling skill (the research becomes dead context)
+
+## 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
+
+- One re-run with sharper sub-questions or different source classes
+- If still insufficient, surface the gap to the owner with the specific source / interview / data the research would need
+- Never produce "I couldn't find anything" as the final output — always end with what we know, what we don't, and the one targeted next probe