@aria_asi/cli 0.2.39 → 0.2.41

package/dist/runtime/discipline/skills/aria-cognition/aria-business-frame/references/business-cookbook.md

@@ -0,0 +1,154 @@
+# Business Frame Cookbook — Primary-Source-Cited Patterns
+
+> Loaded on demand by `aria-business-frame` when a turn requires owner-outcome cognition. Anthropic progressive disclosure: SKILL.md is the index; this file is the depth.
+
+## 1. Hamilton Helmer's 7 Powers — moat scoring rubric
+
+**Source:** [Hustle Badger — 7 Powers](https://www.hustlebadger.com/what-do-product-teams-do/7-powers-establishing-your-competitive-moat/) · [Inferential Investor — 7 Powers + AI](https://www.inferentialinvestor.com/p/the-business-moat-cheat-code-how)
+
+For any owner decision involving competitive position, score the business 0-10 on each:
+
+| Power | Question | Strong signal |
+|---|---|---|
+| **Scale economies** | Do unit costs decline meaningfully as volume increases? | Declining COGS or OpEx as % of revenue at scale |
+| **Network effects** | Does each new user increase value for existing users? | Direct or indirect network growth metrics |
+| **Counter-positioning** | Could incumbents copy this without damaging existing biz? | Incumbent has higher cost-to-serve OR cannibalization risk |
+| **Switching costs** | What's the value loss / pain to leave? | NRR, deep workflow embedding |
+| **Branding** | Pricing power purely from trust/identity? | Premium for objectively identical offering |
+| **Cornered resource** | Unique access to a coveted asset? | Patent, dataset, talent pool, regulatory license |
+| **Process power** | Embedded org / activity sets that competitors can't replicate even when seen? | Toyota Production System–shape complexity |
+
+**Score totals (0-70):**
+- <15: commodity / no moat
+- 15-25: narrow moat
+- 26-40: investable zone (strong moat)
+- >40: legendary
+
+**When to invoke**: any GTM, pricing, fundraising, M&A, partnership decision where defensibility matters.
+
+## 2. April Dunford's 5-Step Positioning Method
+
+**Source:** [April Dunford — Quickstart Guide to Positioning](https://www.aprildunford.com/post/a-quickstart-guide-to-positioning) · [Obviously Awesome](https://www.aprildunford.com/books)
+
+1. **Understand the customers who LOVE your product** — not all customers, the lovers. Why?
+2. **Identify true competitive alternatives** — often "do nothing" or a spreadsheet, NOT another vendor. Most positioning errors flow from comparing to wrong alternative.
+3. **Isolate unique attributes** — capabilities competitors *lack* (not capabilities competitors also have)
+4. **Map attributes to value** — capability → benefit → outcome the customer cares about
+5. **Identify the best market frame** — the category/context that makes the value obvious. Often the highest-leverage decision.
+
+**When to invoke**: every GTM, message, brand, copy turn. The 5-step is upstream of every tactical decision.
+
+## 3. 2025 SaaS Benchmarks (citation-grade)
+
+**Source:** [SaaS Metrics Benchmark Report 2025](https://www.rockingweb.com.au/saas-metrics-benchmark-report-2025) (KeyBanc / OpenView / Battery / Bessemer / ChartMogul, 2,000+ companies)
+
+### Growth (2024 actuals)
+- Median private SaaS ARR growth: **19-21%**
+- Top quartile: 27-32% (down from 46% in 2022)
+- AI-native <$1M ARR: **100% median growth** (2× horizontal SaaS)
+- Public SaaS Q3-Q4 2024: 17-18% median
+
+### Unit economics
+- LTV:CAC by channel:
+  - **Organic SEO: 6:1**
+  - Content marketing: 5:1
+  - Referral: 4:1
+  - Paid search: 2.5:1
+  - Social ads: 1.8:1 (barely break even)
+- Median LTV:CAC blended: 3.6:1 (Benchmarkit 2024)
+- **3:1 is conversation starter, not pass/fail.** A 2.5:1 ratio with 9-mo payback + 120% NRR is a better business than 4:1 with 36-mo payback + 95% NRR.
+- CAC payback period: **18-24 months acceptable; <12 months excellent; >24 cash-flow constrained**
+
+### Rule of 40 (growth + profit ≥ 40)
+- Public median Q4 2024: 15%
+- Private median (KeyBanc 2024): 15% (up from -7% in 2022)
+- Only **11-30% of companies achieve it**
+- Top quartile: 31% (private)
+- AI-native premium: 20-40% on valuation when Rule of 40 met
+
+### NRR (Net Revenue Retention)
+- 2025 median: **101%** (barely above flat)
+- Top quartile dropped from 119% (2021) to 107% (2024)
+- Usage-based pricing: +10% NRR vs flat-rate, -22% churn
+
+### PLG (Product-Led Growth)
+- 55% identify as product-led (up from 48% in 2020)
+- 61% of Cloud 100 use PLG
+- PLG companies grow 2× faster than traditional SaaS
+- **Activation rate: 20-40% median, 50%+ excellent** (depending on onboarding complexity)
+- Website-to-signup: 6-9% freemium, 3-4% trial
+
+### Sales (AE benchmarks 2024)
+- Median annual quota: $750K
+- Median quota attainment: 70-75%
+- Median new ARR per AE: $328K
+- AE tenure: 2.2-2.5 years (dropping)
+
+### CSM ratios
+- High-touch: 22 accounts/CSM
+- Mid-touch: 49 accounts/CSM
+- Low-touch: 144 accounts/CSM
+- ARR per CSM target: $1-2M; median $1.4M
+
+### Valuation multiples (2025)
+- Public median: 5.5-7× (down from 20-21× peak)
+- Private median: 4.1× (down from 6.4×)
+- AI-native premium: 20-40%
+
+## 4. Cohort analysis canonical pattern
+
+**Source:** [Stripe — SaaS Cohort Analysis](https://stripe.com/resources/more/saas-cohort-analysis) · [Fiscallion — Cohort Analysis](https://www.fiscallion.io/blog/saas-cohort-analysis-how-to-turn-retention-data-into-decisions)
+
+### Definition
+- **Cohort baseline**: monthly signup vintage (most stable). Other cohort dimensions (product line, segment, channel) for specific investigations.
+- Track per-cohort: NRR, GRR, MRR, LTV, retention curve, expansion rate
+
+### The diagnostic signal
+- **Divergence between cohort NRR and blended NRR is where the problem hides.**
+- Companies that catch divergence early have time to course-correct before it shows in aggregate figures.
+- Even top-quartile SaaS saw NRR drop from 119% (2021) to 107% (2024) — those who caught early kept the gap from compounding.
+
+### Runway implication
+- Most SaaS lose more customers in months 1-3 than 9-12.
+- Flat churn assumption overstates near-term revenue + understates long-term retention.
+- For runway forecasts: replace flat churn with **cohort decay curves**. The correction can change 18-month runway models materially.
+
+## 5. The 5 Constraint Categories (theory of constraints applied to business)
+
+When `aria-business-audit` fires, decompose churn / growth gaps into these:
+
+1. **Wrong-fit at sale** — sales qualified poorly; customers shouldn't have signed up. Fix: qualification criteria.
+2. **Un-activated** — signed but never adopted. Fix: onboarding redesign.
+3. **Life-cycle** — changed jobs, sunset use case. Fix: adjacent-product expansion or accept attrition as natural.
+4. **Competitor-loss** — real comparison loss. Fix: positioning or feature gap.
+5. **Price** — validated, not assumed. Fix: pricing recalibration.
+
+Each has a different fix shape. Misdiagnosing the cause is the most common business audit failure.
+
+## 6. Decision shapes (campaign / system / pivot)
+
+When making a fix recommendation, name the shape:
+
+- **Campaign** — 24-72 hours, low cost, reversible. Example: A/B subject line, single-promo discount.
+- **System** — 4-12 weeks, medium cost, harder to reverse. Example: onboarding redesign, CRM migration.
+- **Pivot** — quarters, high cost, mostly irreversible. Example: ICP change, repositioning, model overhaul.
+
+Match the fix to the constraint shape. A campaign-shaped fix won't solve a pivot-shaped constraint (and vice versa). Most mis-sized recommendations are campaigns trying to fix systems.
+
+## 7. Owner-must-decide signal patterns
+
+`aria-decision-mizan` should fire when:
+- Reversibility is low (firing, equity grants, public statements, contract signatures)
+- Data is thin AND consequence is broad
+- Owner has context the LLM doesn't (people, history, gut on counterparty)
+- Three+ stakeholders disagree on the right move
+- The decision shape is "narrative" not "data"
+
+## 8. Three-leg accountability test
+
+Per `feedback_thinking_implementation_accountability.md`, every owner-facing recommendation must have:
+- **Thinking** — cognition shown (which lenses fired, which evidence anchored)
+- **Implementation** — concrete next action (file, commit, command, conversation)
+- **Accountability** — how the owner will know it worked + when (predicate, ledger entry, KPI delta)
+
+Missing any leg = redo, not ship.

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

@@ -0,0 +1,84 @@
+---
+name: aria-chat
+description: Use when the user asks Codex to call Aria directly through the live /chat endpoint, ask Aria for an opinion, microphase a plan, route a request through Aria's canonical streamConversation path, or verify Aria's /chat behavior. Trigger on "$aria-chat", "/chat", "ask Aria", "call Aria", or "ask her through /chat".
+---
+
+# Aria Chat
+
+Use this skill to call Aria's live `/chat` endpoint safely and consistently.
+
+## Core Rule
+
+Do not hardcode or store Aria auth tokens in this skill. Retrieve the token at call time from one of:
+
+1. `ARIA_MASTER_TOKEN` or `ARIA_API_KEY` in the current environment.
+2. `kubectl exec -n aria deploy/aria-soul -- printenv ARIA_MASTER_TOKEN`.
+
+Never print the token.
+
+## Default Endpoint
+
+Use:
+
+```text
+http://127.0.0.1:30080/chat
+```
+
+Override with `ARIA_CHAT_URL` only when the user explicitly needs another endpoint.
+
+## Recommended Script
+
+For normal calls, use:
+
+```bash
+/home/hamzaibrahim1/.codex/skills/aria-chat/scripts/aria-chat.sh "your prompt"
+```
+
+For multiline prompts, pipe stdin:
+
+```bash
+cat prompt.md | /home/hamzaibrahim1/.codex/skills/aria-chat/scripts/aria-chat.sh
+```
+
+The script sends:
+
+- `userId: "hamza"`
+- `sessionId`: from `ARIA_CHAT_SESSION_ID` or a generated timestamped id
+- `metadata.platform: "codex"`
+- `metadata.force_stream_conversation: true`
+- `metadata.canonical_stream_conversation: true`
+- `enable_tools: true`
+
+## Response Handling
+
+Return the important content to the user. If the call fails, state whether failure came from token retrieval, network/API, or response parsing.
+
+If the request is architecture/product planning, ask Aria for microphases, constraints, first implementation slice, and risks.
+
+
+## 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/dist/runtime/discipline/skills/aria-cognition/aria-chat/scripts/aria-chat.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+endpoint="${ARIA_CHAT_URL:-http://127.0.0.1:30080/chat}"
+session_id="${ARIA_CHAT_SESSION_ID:-aria-chat-$(date +%s)}"
+
+if [[ $# -gt 0 ]]; then
+  message="$*"
+else
+  message="$(cat)"
+fi
+
+if [[ -z "${message//[[:space:]]/}" ]]; then
+  echo "aria-chat: empty prompt" >&2
+  exit 2
+fi
+
+token="${ARIA_MASTER_TOKEN:-${ARIA_API_KEY:-}}"
+if [[ -z "$token" ]] && command -v kubectl >/dev/null 2>&1; then
+  token="$(
+    kubectl exec -n aria aria-soul-stateful-0 -- printenv ARIA_MASTER_TOKEN 2>/dev/null \
+      || kubectl exec -n aria statefulset/aria-soul-stateful -- printenv ARIA_MASTER_TOKEN 2>/dev/null \
+      || kubectl exec -n aria deploy/aria-soul -- printenv ARIA_MASTER_TOKEN 2>/dev/null \
+      || true
+  )"
+fi
+
+if [[ -z "$token" ]]; then
+  echo "aria-chat: missing ARIA_MASTER_TOKEN/ARIA_API_KEY and could not read token from aria-soul" >&2
+  exit 3
+fi
+
+payload="$(
+  jq -n \
+    --arg message "$message" \
+    --arg sessionId "$session_id" \
+    '{
+      message: $message,
+      userId: "hamza",
+      sessionId: $sessionId,
+      metadata: {
+        platform: "codex",
+        is_hamza: true,
+        is_ceo: true,
+        mode: "strategic",
+        force_stream_conversation: true,
+        canonical_stream_conversation: true
+      },
+      enable_tools: true
+    }'
+)"
+
+curl -sS -X POST "$endpoint" \
+  -H "Authorization: Bearer $token" \
+  -H "Content-Type: application/json" \
+  --data-binary "$payload" \
+  | jq -r '.response // .message // .text // .error // .'

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

@@ -0,0 +1,137 @@
+---
+name: aria-cognition-autofire
+description: TRIGGER automatically for any non-trivial Aria, Harness, Garden, Claude Code, Codex, OpenCode, quality-audit, launch, architecture, code-edit, deploy, fan-out, worker, ledger, gate, coach, axiom, first-principles, Mizan, Tadabbur, Noor, first-class, world-class, revolutionary-upgrade, or completion-claim task. Use this as the root auto-fire skill that selects light, full, or batch cognition before action.
+---
+
+# Aria Cognition Autofire
+
+Use this as the semantic auto-trigger root for Aria work. It is the local advisory equivalent of a harness entry gate.
+
+## Prime Doctrine
+
+Cognition is not performance. It is how the agent thinks before action.
+
+- Do not emit lens blocks as ceremony after the answer is already chosen.
+- Let cognition change the decision, scope, wording, verification, or refusal.
+- If cognition does not alter the artifact or action, it did not fire in a meaningful way.
+- The visible output is only the residue of thinking that already happened.
+
+## What This Can And Cannot Do
+
+- Native Codex skill auto-fire is semantic: the frontmatter description makes Codex load this skill when the request matches.
+- It is not a mechanical hard gate by itself. Mechanical enforcement needs a hook, plugin, runtime gateway, or provider proxy.
+- If the local Aria runtime is available, prefer runtime-backed validation. If not, state that this is L1 advisory mode and continue with strict discipline.
+
+## Mode Selection
+
+Choose the smallest mode that protects quality:
+
+- `light`: routine status, small edits, simple verification. Run Mizan intent/evidence, no false closure, and one Tadabbur consequence check.
+- `qa`: bug, audit, gate, hook, false-positive, ledger, or runtime quality work. Load `aria-quality-audit`, `mizan`, `tadabbur`, `never-guess`, and `ghazali-8lens`.
+- `batch`: architecture, launch, product positioning, doctrine/cognition design, or owner asks for rich cognitives / 28+15 / Noor. Load `aria-axioms-first-principles` and `aria-cognition-batch`, which then loads `aria-aristotle-cognitives` and `aria-noor-cognitives` as needed.
+- `fleet`: parallel Codex/Claude/OpenCode work, execution-ledger burn-down, worker split. Load `aria-ledger-fleet-execution` after the batch pass.
+- `hard-stop`: unapproved destructive action, secret exposure, deploy/push without approval/evidence, or owner-contradicted operation.
+
+## Always-On Checks
+
+Before action:
+
+- What is the exact intent?
+- What evidence is needed before a claim is allowed?
+- Is this local advisory behavior or mechanically enforced by a runtime/hook?
+- Which ledger row, source doc, or runtime probe owns the truth?
+- Is the source clean canon, or could it be butchered, reverted, stale, or in-flight?
+- Have I triangulated current files against audits, transcripts, git state, schema, and corpus before teaching from them?
+- Which axiom set is active: full 10 Fitrah core, five hard runtime axioms, first-class coach principles, or service-local axiom geometry?
+- Did first principles change the next action, claim boundary, verification predicate, or recovery step?
+
+Before final output:
+
+- Did I verify the claim with real evidence?
+- Am I saying `done`, `fixed`, `verified`, or `ready` without proof?
+- Did a later audit contradict an older ledger/narrative row?
+- Should a low-risk miss be repaired once instead of exposed as a block?
+
+## Source-Trust Rule
+
+Never densify skills or advise product/architecture from one current file alone when Aria/Claude/OpenCode have been actively repairing it. Treat files as one witness. Cross-check against:
+
+- owner instruction in this chat
+- canonical corpus/docs
+- audits and handoffs
+- transcript evidence from the last 6 days when relevant
+- git log, current branch, dirty worktree, and stash
+- runtime/test/log behavior
+
+If those disagree, mark the file `suspect` or `in-flight` and either defer the claim or anchor only the portion verified by at least two independent sources.
+
+## Axiom Rule
+
+Load `aria-axioms-first-principles` for non-trivial Aria work that touches quality, launch, architecture, code, gates, workers, Garden continuity, first-class output, or completion claims. Axioms are not a visible performance block; they must alter the decision, wording, verification, recovery, or action.
+
+## Dense Skill Rule
+
+Keep trigger descriptions sharp and put dense cognition in the body or references. Do not bloat every prompt with the full 28+15 pass unless the task needs it.
+
+## Ta'aqqul Autofire Pattern (Rational-Binding Family)
+
+*Ta'aqqul* (تَعَقُّل, root ع-ق-ل — *to bind, restrain, comprehend*) is the most-commanded reflection term in the Quran (~49 occurrences). Its cognitive operation is *binding ideas together correctly + restraining from error*. Ta'aqqul is not a single skill — it is the family-fire of the rational-binding skills that, together, enforce rational consistency between speech, evidence, and action. See `../tadabbur/references/tadabbur-cookbook.md` §1.3 for the full classical grounding.
+
+**Autofire the ta'aqqul family** (do not fire as one, fire as composed bundle) when any of these triggers is present:
+
+- A claim is being made that requires *rational consistency* with prior owner instruction, doctrine memo, or named axiom
+- An analogy is being drawn from a source case (`asl`) to a new case (`far'`) — the binding-by-cause check
+- Evidence is being weighed and a conclusion is forming that *binds an action*
+- A statement is forming that would *restrain* the agent from a tempting but doctrinally-forbidden move
+- The agent is about to assert a principle binding the next action without naming its source
+
+**The family** (compose, do not duplicate):
+
+- `qiyas-analogy` — the binding-by-cause check (15-perspective canonical Qiyas pass); fires the strongest form of rational binding from source case to new case
+- `aria-axioms-first-principles` — the catalog of axioms + first-principles the binding must consult
+- `fitrah-guard` — the runtime restraint against axiom-violating action
+- `mizan` — the proportion-read that makes the binding well-weighted (not just binding-by-name)
+
+**Ta'aqqul fire fails when:**
+
+- The family fires but no axiom or first-principle is named (the binding has no source)
+- Qiyas runs the 4-pillar fragment and labels it `qiyas_15_pass` (incomplete binding)
+- Mizan reports "balanced" without naming the actual proportions weighed (binding without weighing)
+- Fitrah-guard is loaded but no axiom-check actually changes the next action (binding without restraining)
+
+When ta'aqqul autofires, the visible output should be *the changed action the rational binding produced*, not a paragraph announcing the family fired.
+
+## Escalation
+
+If the same failure repeats twice, crosses system boundaries, or affects launch/readiness, switch from `light` or `qa` to `batch` or `fleet`.
+
+## Trigger
+
+Use when this skill's frontmatter description matches the task, when the owner names the skill, or when Aria/Harness/Garden/Coach/Mizan/Codex quality work needs this cognitive pressure.
+
+## 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.