@rosh100yx/outlier 0.4.25 → 0.10.2

package/README.md

@@ -1,53 +1,69 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/rosh100yx/outlier/main/assets/cover.jpg" alt="Outlier: AI Code Governance and Policy Engine" width="100%" />
   <h1>Outlier: The Governance & Policy Engine for AI Engineering</h1>
-  <p><b>Measure AI adoption. Enforce Zero-Trust. Protect Human Mastery.</b></p>
-  <p><i>Outlier is an open-source, local-first CLI tool that measures AI code reliance, enforces zero-trust telemetry, and protects developers from deskilling by auditing local agent logs (Claude, Cursor) and Git history.</i></p>
+  <p><b>Measure AI adoption. See what your agents can reach. Keep your skill.</b></p>
+  <p><i>A local-first CLI for when you are building in a room full of agents — it measures how much of your code AI wrote, what it cost, and what your agents can actually touch, all without a single byte leaving your terminal.</i></p>
   <br/>
   
   <p>
-    <img src="https://img.shields.io/badge/Compliance-Strict-blue?style=for-the-badge" />
-    <img src="https://img.shields.io/badge/AI_Safety-Enabled-green?style=for-the-badge" />
-    <img src="https://img.shields.io/badge/Zero_Trust-Verified-orange?style=for-the-badge" />
+    <a href="https://www.npmjs.com/package/outlier-audit"><img src="https://img.shields.io/npm/v/outlier-audit?style=for-the-badge&color=cb3837&logo=npm" /></a>
+    <img src="https://img.shields.io/badge/Local_First-Zero_Trust-orange?style=for-the-badge" />
+    <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" />
   </p>
 
   <p>
     <b>Get Started Instantly:</b><br/>
-    <code>npx @rosh100yx/outlier@latest</code>
+    <code>npx outlier-audit@latest</code>
   </p>
 
   <br/>
   
   ```text
-  ┌────────────────────────────────────────────────────────┐
-  │ █▀█ █░█ ▀█▀ █░░ █ █▀▀ █▀█  :: THERMAL AUDIT RECEIPT    │
-  │ █▄█ █▄█ ░█░ █▄▄ █ ██▄ █▀▄  :: TIMESTAMP: 2026-06-23    │
-  ├────────────────────────────────────────────────────────┤
-  │  [ COGNITIVE BUDGET ]                                  │
-  │  AI Authorship     ................. ▇▇▇▇░░░░░░ 40%    │
-  │  Human Sovereignty ................. ▇▇▇▇▇▇░░░░ 60%    │
-  │                                                        │
-  │  ↳ Verdict: (=^ ◡ ^=) CENTAUR                          │
-  │    Healthy symbiosis. You orchestrate agents           │
-  │    but maintain architectural authority.               │
-  ├────────────────────────────────────────────────────────┤
-  │  [ FINANCIAL & COMPUTE TOLL ]                          │
-  │  Tokens Burnt      ................. 3.12M vs Human    │
-  │  Cache Bloat       ................. ▇▇▇▇▇▇▇▇░░ 80%    │
-  │  Regional Grid     ................. 1.54 kgCO2        │
-  └────────────────────────────────────────────────────────┘
+  ┌──────────────────────────────────────────────────────────────────┐
+  │ █▀█ █░█ ▀█▀ █░░ █ █▀▀ █▀█  :: CODE AUDIT                          │
+  │ █▄█ █▄█ ░█░ █▄▄ █ ██▄ █▀▄  :: my-repo · JUN 23, 2026              │
+  ├──────────────────────────────────────────────────────────────────┤
+  │  WHO WROTE THE CODE                                              │
+  │ AI    ▰▰▰▰░░░░░░ 40%   (64 of 160 commits)                       │
+  │ You   ▰▰▰▰▰▰░░░░ 60%                                             │
+  │ Typical: solo devs 10–40% · AI-framework repos up to ~80%        │
+  │ You're driving — you still write the core. Good.                 │
+  ├──────────────────────────────────────────────────────────────────┤
+  │  WHAT IT COST                                                    │
+  │ Tokens used      3.1M                                            │
+  │ Est. spend       $18.40                                          │
+  │ Re-used context  ▰▰▰▰▰▰▰▰░░ 80%                                  │
+  │ Energy           0.12kg CO2 (Global Average grid)                │
+  │ Source: estimated · Claude Code transcripts                      │
+  ├──────────────────────────────────────────────────────────────────┤
+  │  WHAT YOUR AGENTS CAN REACH                                      │
+  │ Blast radius   HIGH · 13 tools, 5 can write/deploy               │
+  │ Full map (deploy/push/write tools): outlier capabilities         │
+  ├──────────────────────────────────────────────────────────────────┤
+  │  YOUR LIMIT                                                      │
+  │ AI cap   70% · change with: outlier policy                       │
+  │ Status   Within limit · Nothing to do.                           │
+  ├──────────────────────────────────────────────────────────────────┤
+  │  WHAT TO DO                                                      │
+  │ ⚠ Blast radius HIGH                                              │
+  │   → Disable the write/deploy MCP tools you don't need now.       │
+  └──────────────────────────────────────────────────────────────────┘
   ```
 </div>
 
+> *"In a room full of agents" shifts the perspective. The developer is no longer a solo coder — they are a manager of bots. Outlier exists to make sure the human doesn't get lazy while managing them. We all want our time back; we don't want to lose control of the craft.*
+
+> **Note:** the npm package is `outlier-audit`; the command it installs is `outlier`. So `npx outlier-audit` runs `outlier …`.
+
 ## How It Works
 ```text
-┌───────────┐   ┌────────────┐   ┌───────────┐   ┌─────────────┐
-│ AI CODING │──▸│ GIT COMMIT │──▸│  BOUNCER  │──▸│ AUDIT TRACE │
-└───────────┘   └────────────┘   └───────────┘   └─────────────┘
-                                       │ (Fails)
-                                 ┌───────────┐
-                                 │ MENTORING │
-                                 └───────────┘
+┌───────────┐   ┌────────────┐   ┌──────────┐   ┌──────────────┐
+│ AI CODING │──▸│ GIT + LOGS │──▸│  OUTLIER │──▸│ AUDIT + WARN │
+└───────────┘   └────────────┘   └──────────┘   └──────────────┘
+                                       │ (over your limit)
+                                 ┌──────────────┐
+                                 │ REVIEW PROMPT │  (warns, never blocks)
+                                 └──────────────┘
 ```
 **Step 1:** Developer delegates code generation to an AI agent (Claude Code, Cursor).  
 **Step 2:** `outlier` reads the local trace — git history + AI logs — already on the machine.  
@@ -77,22 +93,40 @@ We are deliberately honest about this:
 
 | Capability | Ungoverned AI | Outlier Governed |
 |------------|---------------|------------------|
-| **Deskilling** | Silent skill atrophy | JIT Mentoring Triggers on high-reliance |
-| **Commit Gate**| Accepts hallucinated code | Physically blocks code over AI-thresholds |
-| **Context** | Blind token spend | Detects "Cache Bloat" and context waste |
-| **Security** | Opaque MCP access | Maps and audits active skills/capabilities |
+| **Deskilling** | Silent skill atrophy | Flags high AI-authorship as a deskilling risk |
+| **Commit Gate**| Ships AI code unchecked | A local hook *warns* when AI authorship is over your limit |
+| **Context** | Blind token spend | Surfaces re-used context (the part that's most of your bill) |
+| **Agent reach** | Opaque MCP access | Maps what your agents can reach + a **blast-radius** score |
+| **Agents & CI** | No machine signal | `--json` audit a supervisor agent or pipeline can act on |
 
 ## Commands
 | Command | Purpose |
 |---------|---------|
-| `npx @rosh100yx/outlier` | Run the full AI reliance & capability audit |
-| `npx @rosh100yx/outlier authorship` | Scan git history for AI co-authorship ratio |
-| `npx @rosh100yx/outlier carbon` | Scan local logs for context waste & token costs |
-| `npx @rosh100yx/outlier capabilities` | Audit active MCPs, skills, and orchestrations |
-| `npx @rosh100yx/outlier policy` | Configure Personal, Team, or Enterprise guardrails in CI |
+| `npx outlier-audit` | Run the full AI reliance & capability audit |
+| `npx outlier-audit authorship` | Scan git history for AI co-authorship ratio |
+| `npx outlier-audit carbon` | Scan local logs for context waste & token costs |
+| `npx outlier-audit capabilities` | Map what your agents can reach + blast radius |
+| `npx outlier-audit policy` | Configure Personal, Team, or Enterprise guardrails in CI |
+| `npx outlier-audit --json` | Machine-readable audit for agents, CI, and swarms |
+
+### For agents, CI & swarms (`--json`)
+
+`outlier --json` emits a clean, ANSI-free JSON audit and nothing else — so an agent (or a supervisor in a swarm) can read its own authorship, cost, carbon, and **blast radius** before it acts, and CI can gate on it. Local-first: it still never leaves the machine.
+
+```jsonc
+{
+  "tool": "outlier",
+  "authorship": { "aiPercent": 7.4, "provenance": "proxy" },
+  "cost": { "totalTokens": 137700000, "estUsd": 63.76, "provenance": "measured" },
+  "carbon": { "co2Kg": 0.10, "region": "Global Average", "provenance": "estimated" },
+  "reach": { "blastRadius": "HIGH", "toolCount": 13, "writeOrDeployCount": 5,
+             "reasons": ["can deploy to production", "can push to your remote repos"] },
+  "policy": { "aiCapPercent": 70, "status": "within" }
+}
+```
 
 ### The UX Flow
-If you run `npx @rosh100yx/outlier` directly, you'll instantly get your Thermal Receipt and a simple list of follow-up commands:
+If you run `npx outlier-audit` directly, you'll instantly get your audit receipt and a simple list of follow-up commands:
 ```text
   └────────────────────────────────────────────────────────┘
 
@@ -111,30 +145,29 @@ If you run `npx @rosh100yx/outlier` directly, you'll instantly get your Thermal
 
 **Prerequisites:** You need Node/Bun installed and to be inside a Git repository.
 
-1. **Set the Trap (Install the Bouncer)**
+1. **Run your first audit**
    ```bash
-   npx @rosh100yx/outlier policy
+   npx outlier-audit
    ```
-   *Select the "Team (70% Max AI)" tier.*
+   *See who wrote the code, what it cost, and what your agents can reach.*
 
-2. **Trigger the Bouncer**
-   Write a massive feature using 100% AI. Attempt to commit it:
+2. **Set a limit (optional)**
    ```bash
-   git commit -am "added massive ai feature"
+   npx outlier-audit policy
    ```
-   *Watch the Bouncer physically block your commit for deskilling risk.*
+   *Pick a tier (e.g. "Team — 70% max AI"). It installs a local pre-commit hook that **warns** when AI authorship goes over your limit — it never silently blocks your work.*
 
-3. **Measure the Damage**
+3. **Wire it into agents or CI**
    ```bash
-   npx @rosh100yx/outlier
+   npx outlier-audit --json
    ```
-   *Instantly generate your Thermal Receipt to see your exact AI Authorship ratio and Token Waste.*
+   *A clean JSON audit a supervisor agent, a swarm, or a CI pipeline can read and act on.*
 
 ## Theoretical Foundations
 `outlier` is the live, technical implementation of an academic thesis on the thermodynamics of AI code generation and digital sovereignty. 
 - **The Geographic Tax:** Western tech companies ship highly compute-intensive AI tools globally, but local infrastructure in the Global South is forced to absorb the carbon cost. `outlier` proves this by weighting session carbon by regional grid intensity (e.g., proving identical work imports 31x more carbon in Vietnam than France).
 - **Disempowerment:** Incremental AI substitution erodes human influence. `outlier` acts as a sovereignty shield against opaque AI platforms.
-- **Deskilling:** Delegating operators lose supervisory skills. By parsing `Co-Authored-By` Git trailers, `outlier` tracks AI reliance per-individual and flags high reliance as a "Deskilling Risk", triggering mandatory mentoring checkpoints.
+- **Deskilling:** Delegating operators lose the skills they need to supervise (Bainbridge, 1983). By parsing `Co-Authored-By` Git trailers, `outlier` tracks AI reliance per-individual and flags high reliance as a "Deskilling Risk" — a prompt to review before you delegate more, not a wall.
 
 ## FAQ
 
@@ -145,14 +178,14 @@ If you run `npx @rosh100yx/outlier` directly, you'll instantly get your Thermal
 `outlier` is IDE-agnostic. It works by parsing standard `Co-Authored-By` Git trailers, meaning it supports Claude Code, Cursor, Aider, and manual generation.
 
 **Can I run this in CI/CD like GitHub Actions?**  
-Yes. Use the `--strict` flag (`npx @rosh100yx/outlier audit --strict`) to return standard zero-exit-code parsing for headless CI environments.
+Yes. Use the `--strict` flag (`npx outlier-audit audit --strict`) to return standard zero-exit-code parsing for headless CI environments.
 
 ## Who is this for?
 
 If you hold one of these roles, `outlier` was built specifically for you. Please help us improve the framework by running an audit and sharing your terminal screenshot on X.com or your favorite developer community!
 
 - **Engineering Managers & CTOs:** Stop flying blind. Measure true AI adoption, enforce zero-trust security on your IP, and cut your API token bloat.
-- **Principal & Staff Engineers:** Protect the craft. Use the Bouncer hook to enforce architectural standards and prevent your team from deskilling.
+- **Principal & Staff Engineers:** Protect the craft. See your team's blast radius (what your agents can deploy/push/write) and use the warn-on-commit hook to keep humans in the loop.
 - **Developers & "Vibe Coders":** Prove your mastery. Run the audit, check your vibe, and post your "Artisan" or "Centaur" terminal status to the community.
 
 ## Support the Thesis & Collaborate