clawpowers 1.1.3 → 1.1.4

package/README.md

@@ -1,444 +1,286 @@
 # 🦞 ClawPowers
 
-**The skills framework that actually does something.**
+> **v1.1.3** · 26 skills · 372 tests · MIT · **Patent Pending**
 
-ClawPowers gives your coding agent superpowers that go beyond instructions. While other frameworks hand your agent a reading list and hope for the best, ClawPowers gives it **runtime tools, persistent memory, self-improvement loops, and the ability to transact autonomously.**
+**Your agent needs to pay for APIs. ClawPowers makes that work.**
 
-## Demo
+When your agent hits a premium API and gets back HTTP 402 Payment Required, it needs to pay and retry — automatically, within limits you set, with your approval before anything moves. That's the core problem ClawPowers solves. The other 25 skills are a bonus.
 
-![ClawPowers Demo](docs/demo/clawpowers-demo.gif)
+## The Pay-to-Complete Flow
 
-*Install → persist state across sessions → track outcomes → self-improve. All from the terminal.*
+```
+Agent calls API
+      │
+      ▼
+  HTTP 402  ←── "Payment required: $0.50 USDC"
+      │
+      ▼
+ClawPowers evaluates:
+  • Is this within your spend cap? ($5/tx limit → ✅)
+  • Is this on the allowlist?     (api.example.com → ✅)
+  • Human approval required?      (under $1 threshold → auto)
+      │
+      ▼
+  Payment sent → API retried → Result returned
+      │
+      ▼
+  Outcome logged (for RSI analysis)
+```
 
-## Why ClawPowers?
+## Quick Start
 
-| Feature | ClawPowers | Static Skills Frameworks |
-|---------|-----------|--------------------------|
-| Skills auto-load on session start | ✅ | ✅ |
-| Runtime tool execution | ✅ | ❌ |
-| Cross-session memory | ✅ | ❌ |
-| Self-improvement (RSI) | ✅ | ❌ |
-| Outcome tracking & metrics | ✅ | ❌ |
-| Agent payments (x402) | ✅ | ❌ |
-| Security scanning | ✅ | ❌ |
-| Content pipeline | ✅ | ❌ |
-| Market intelligence | ✅ | ❌ |
-| Resumable workflows | ✅ | ❌ |
-| Windows native support | ✅ | ❌ |
-| Zero dependencies | ✅ | ✅ |
+```bash
+npx clawpowers init          # Set up ~/.clawpowers/ runtime
+npx clawpowers demo x402     # See the full 402 → pay → 200 flow (no real money)
+npx clawpowers status        # Check what's running
+```
 
-**26 skills.** 14 cover everything static frameworks do (TDD, subagent dev, debugging, planning, code review, git worktrees). 6 go where they can't — payments, security, content, prospecting, market intelligence, and metacognitive learning. 4 are things no other framework even attempts — self-healing code, agents that rewrite their own methodology, cross-project knowledge transfer, and property-based formal verification.
+## Human-Approval Mode (the default)
 
-## Requirements
+ClawPowers defaults to supervised payments — your agent proposes, you approve. No funds move until you say so.
 
-- **Node.js >= 16** — for cross-platform runtime (Windows, macOS, Linux)
-- **OR bash** — for Unix-native runtime (macOS, Linux, WSL2)
-- **No other dependencies.** Zero. `package.json` has an empty `dependencies` object.
+```typescript
+import { createX402Client } from 'agentwallet-sdk';
+import { createWallet, setSpendPolicy } from 'agentwallet-sdk';
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
 
-> Every user of Claude Code, Cursor, Codex, or Gemini CLI already has Node.js installed.
-> No `requirements.txt` needed — this is not a Python project.
+const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
+const walletClient = createWalletClient({ account, chain: base, transport: http() });
 
-## Installation
+const wallet = createWallet({
+  accountAddress: process.env.AGENT_WALLET_ADDRESS as `0x${string}`,
+  chain: 'base',
+  walletClient,
+});
 
-### Universal (recommended — works on Windows, macOS, Linux)
+// Spend policy — enforced on-chain, not in application code
+await setSpendPolicy(wallet, {
+  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
+  perTxLimit: 1_000_000n,    // $1 auto-approved per transaction
+  periodLimit: 10_000_000n,  // $10/day hard cap
+  periodLength: 86400,
+});
 
-```bash
-npx clawpowers init
+const x402 = createX402Client(wallet, {
+  supportedNetworks: ['base:8453'],
+  globalDailyLimit: 10_000_000n,    // matches spend policy
+  globalPerRequestMax: 1_000_000n,  // $1 per request
+  requireApproval: true,            // human-in-the-loop mode (default)
+});
+
+// Agent hits a paid API
+const response = await x402.fetch('https://api.example.com/premium-data');
+// If cost < $1: auto-approved and paid
+// If cost > $1: queued — you get a notification to approve or reject
+const data = await response.json();
 ```
 
-This downloads ClawPowers, creates the `~/.clawpowers/` runtime directory, and you're ready to go. Works in any terminal: Windows CMD, PowerShell, macOS Terminal, Linux shell.
+## Simulation Mode
 
-### OpenClaw
+Test the full payment flow before enabling live payments.
 
 ```bash
-openclaw skills install clawpowers
+# Run a local mock x402 merchant — full 402 → pay → 200 cycle
+npx clawpowers demo x402
 ```
 
-Or install from GitHub directly:
+In code:
 
-```bash
-openclaw skills install github:up2itnow0822/clawpowers
+```typescript
+const x402 = createX402Client(wallet, {
+  supportedNetworks: ['base:8453'],
+  globalDailyLimit: 10_000_000n,
+  globalPerRequestMax: 1_000_000n,
+  dryRun: true,  // logs exactly what would happen, no funds move
+});
+
+const response = await x402.fetch('https://api.example.com/premium-data');
+// Response includes: { simulated: true, wouldHavePaid: '0.50 USDC', withinLimits: true }
 ```
 
-ClawPowers registers as a native OpenClaw skill with session hooks, runtime init, and all 24 skills auto-discoverable.
+## Explicit Spend Caps
 
-### Claude Code (Plugin Marketplace)
+Caps are enforced by smart contract, not application code. Even a prompt injection or jailbreak can't bypass them.
 
-```bash
-/plugin install clawpowers@claude-plugins-official
 ```
-
-Or register the marketplace first, then install:
-
-```bash
-/plugin marketplace add up2itnow0822/clawpowers-marketplace
-/plugin install clawpowers@clawpowers-marketplace
+Agent wants to spend $0.50  → ✅ Auto-approved (under $1/tx cap)
+Agent wants to spend $5.00  → ⏳ Queued for your approval
+Agent spent $9.00 today     → 🛑 Next tx blocked ($10/day cap hit)
 ```
 
-### Cursor
-
-In Cursor Agent chat:
+```bash
+# Check what your agent has spent
+npx clawpowers store get agent-payments:daily-total
+# → "2.50 USDC spent today, $7.50 remaining"
 
-```
-/add-plugin clawpowers
+# Review and approve queued payments
+npx clawpowers payments queue
+# → [1] $5.00 USDC — api.example.com/premium-report — approve? (y/n)
 ```
 
-Or search for "clawpowers" in the Cursor plugin marketplace.
+## Why Supervised, Not Autonomous
 
-### Codex
+Fully autonomous agent payments sound great until an agent in a loop runs up $500 in API calls overnight. ClawPowers is built around three constraints:
 
-Tell Codex:
+1. **Caps enforced on-chain** — the agent *cannot* exceed them, full stop
+2. **Human approval by default** — auto-approve only below thresholds you set
+3. **Full audit trail** — every payment logged at `~/.clawpowers/metrics/`
 
-```
-Fetch and follow instructions from https://raw.githubusercontent.com/up2itnow0822/clawpowers/main/.codex/INSTALL.md
-```
+When you've verified the agent behaves correctly, raise the auto-approve threshold. Start low.
 
-### OpenCode
+## Installation
 
-Tell OpenCode:
+### Universal (Windows, macOS, Linux)
 
-```
-Fetch and follow instructions from https://raw.githubusercontent.com/up2itnow0822/clawpowers/main/.opencode/INSTALL.md
+```bash
+npx clawpowers init
 ```
 
-### Gemini CLI
+### OpenClaw
 
 ```bash
-gemini extensions install https://github.com/up2itnow0822/clawpowers
+openclaw skills install clawpowers
+# or from GitHub
+openclaw skills install github:up2itnow0822/clawpowers
 ```
 
-### Manual (git clone)
+### Claude Code
 
 ```bash
-git clone https://github.com/up2itnow0822/clawpowers.git
-cd clawpowers
-node bin/clawpowers.js init    # Windows, macOS, Linux
-# or
-bash bin/clawpowers.sh init    # macOS, Linux only
+/plugin install clawpowers@claude-plugins-official
 ```
 
-### Verify Installation
-
-Start a new session in your chosen platform and ask for something that triggers a skill — for example, "help me plan this feature" or "let's debug this issue." The agent should automatically apply the relevant ClawPowers skill.
-
-Check runtime status anytime:
+### Cursor
 
-```bash
-npx clawpowers status
+```text
+/add-plugin clawpowers
 ```
 
-## What Makes ClawPowers Different
-
-### 1. Skills That Execute, Not Just Instruct
+### Codex / OpenCode
 
-Static skills tell your agent *what to do*. ClawPowers skills can *do things themselves*:
+```text
+Fetch and follow instructions from https://raw.githubusercontent.com/up2itnow0822/clawpowers/main/.codex/INSTALL.md
+```
 
-- The **test-driven-development** skill doesn't just describe TDD — it runs mutation analysis on your tests to verify they actually catch bugs
-- The **systematic-debugging** skill doesn't just list debugging steps — it maintains a persistent hypothesis tree across sessions so you never re-investigate the same dead end
-- The **verification-before-completion** skill doesn't just say "verify" — it runs the actual verification suite and blocks completion until it passes
+### Manual
 
-### 2. Cross-Session Memory
+```bash
+git clone https://github.com/up2itnow0822/clawpowers.git
+cd clawpowers
+node bin/clawpowers.js init
+```
 
-Every ClawPowers skill can read from and write to a persistent state store. When your agent debugs an issue on Monday and encounters the same stack trace on Friday, it remembers what worked and what didn't. No more Groundhog Day debugging.
+## All 26 Skills
+
+### Core Development (14)
+
+| Skill | What It Does |
+|-------|-------------|
+| `subagent-driven-development` | Orchestrate parallel subagents — persistent execution DB, resumable checkpoints |
+| `test-driven-development` | RED-GREEN-REFACTOR with mutation analysis to verify tests actually catch bugs |
+| `writing-plans` | Spec → implementation plan with historical estimation and dependency validation |
+| `executing-plans` | Execute plans with interruption recovery and milestone tracking |
+| `brainstorming` | Structured ideation with cross-session idea persistence |
+| `systematic-debugging` | Persistent hypothesis tree so you never re-investigate the same dead end |
+| `verification-before-completion` | Pre-merge quality gates that actually run the verification suite |
+| `finishing-a-development-branch` | Branch cleanup, changelog, merge prep |
+| `requesting-code-review` | Reviewer match scoring, review history |
+| `receiving-code-review` | Feedback pattern tracking, common issues database |
+| `using-git-worktrees` | Isolated branch development with conflict prediction |
+| `using-clawpowers` | Meta-skill: how to use ClawPowers |
+| `writing-skills` | Create new skills via TDD with quality scoring |
+| `dispatching-parallel-agents` | Fan-out with load balancing, failure isolation, result aggregation |
+
+### Extended Capabilities (6)
+
+| Skill | What It Does |
+|-------|-------------|
+| `agent-payments` | x402 payment protocol — supervised, capped, human-in-the-loop by default |
+| `security-audit` | Automated vulnerability scanning (Trivy, gitleaks, npm audit) |
+| `content-pipeline` | Write → humanize → format → publish with platform-specific formatting |
+| `learn-how-to-learn` | Metacognitive protocols, anti-pattern detection, confidence calibration |
+| `market-intelligence` | Competitive research, trend detection, opportunity scoring |
+| `prospecting` | Lead generation, contact enrichment, CRM sync (Exa + Apollo) |
+
+### RSI Intelligence Layer (4)
+
+Skills that require runtime execution and persistent state — not available in static frameworks.
+
+| Skill | What It Does |
+|-------|-------------|
+| `meta-skill-evolution` | Every 50 tasks: analyzes outcomes, identifies weakest skill, rewrites its methodology |
+| `self-healing-code` | On test failure: hypothesis tree → 2+ patches → applies best → auto-commits |
+| `cross-project-knowledge` | Pattern library across all repos — bug fixes and solutions transfer between projects |
+| `formal-verification-lite` | Property-based testing (fast-check/Hypothesis/QuickCheck) — 1000+ examples per property |
+
+## Cross-Session Memory
+
+Skills persist state across sessions. Your agent's debugging hypotheses, payment outcomes, and learned patterns survive session restarts.
 
 ```
 ~/.clawpowers/
-├── state/            # Cross-session key-value store
-├── metrics/          # Outcome tracking per skill (JSONL)
-├── checkpoints/      # Resumable workflow state
-├── feedback/         # Self-improvement analysis
-├── memory/           # Persistent knowledge base
-└── logs/             # Execution logs
+├── state/        # Key-value store
+├── metrics/      # Outcome tracking per skill (JSONL)
+├── checkpoints/  # Resumable workflow state
+├── feedback/     # RSI self-improvement data
+└── logs/         # Execution logs
 ```
 
-### 3. Self-Improvement (RSI)
-
-ClawPowers tracks what works and what doesn't. After every skill execution:
-
-1. **Measure** — Was the outcome successful? How long did it take? What went wrong?
-2. **Analyze** — Are there patterns in failures? Which task types need different approaches?
-3. **Adapt** — Adjust skill parameters, decomposition strategies, and review thresholds
+## CLI Reference
 
 ```bash
-# Record an outcome
-npx clawpowers metrics record --skill test-driven-development --outcome success --duration 1800
-
-# Analyze performance
-npx clawpowers analyze
+npx clawpowers init                          # Set up runtime
+npx clawpowers status                        # Health check
+npx clawpowers demo x402                     # Payment demo (no real money)
+npx clawpowers metrics record --skill <name> --outcome success|failure
+npx clawpowers metrics summary               # Per-skill stats
+npx clawpowers analyze                       # RSI performance analysis
+npx clawpowers store get <key>               # Read persistent state
+npx clawpowers store set <key> <value>       # Write persistent state
+npx clawpowers payments queue                # Review pending approvals
 ```
 
-This isn't theoretical — it's the same RSI framework running in production trading systems with 268+ measured outcomes.
-
-### 4. Agent Payments (x402)
-
-Your agent can pay for premium APIs, compute resources, and services autonomously — within smart-contract-enforced spending limits. No wallet draining. No surprise bills. Built on the payment infrastructure [integrated into NVIDIA's official NeMo Agent Toolkit](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17).
-
-### 5. Beyond Software Development
-
-Static frameworks stop at coding methodology. ClawPowers includes skills for:
-
-- **Security auditing** — Automated vulnerability scanning with Trivy, dependency checks, secret detection
-- **Content pipeline** — Write, humanize, and publish technical content with platform-specific formatting
-- **Market intelligence** — Research competitors, track trends, analyze opportunities
-- **Prospecting** — Find leads matching your ICP, enrich contacts, output to CRM
-
-## Skills Reference
-
-### Core Development (14 skills)
-
-| Skill | What It Does | Runtime Enhancement |
-|-------|-------------|---------------------|
-| `subagent-driven-development` | Orchestrate parallel subagents per task | Persistent execution DB, resumable checkpoints, outcome metrics |
-| `test-driven-development` | RED-GREEN-REFACTOR enforcement | Mutation analysis, test portfolio management, effectiveness scoring |
-| `writing-plans` | Spec → implementation plan | Historical task estimation, dependency validation, plan quality scoring |
-| `executing-plans` | Execute plans with verification | Progress persistence, interruption recovery, milestone tracking |
-| `brainstorming` | Structured ideation | Cross-session idea persistence, convergence tracking |
-| `systematic-debugging` | Hypothesis-driven debugging | Persistent hypothesis tree, pattern matching against known issues |
-| `verification-before-completion` | Pre-merge quality gates | Automated verification suite, historical pass rate tracking |
-| `finishing-a-development-branch` | Branch cleanup and merge prep | Automated changelog, squash strategy optimization |
-| `requesting-code-review` | Prepare and request review | Reviewer match scoring, review history |
-| `receiving-code-review` | Process and implement feedback | Feedback pattern tracking, common issues database |
-| `using-git-worktrees` | Isolated branch development | Worktree lifecycle management, conflict prediction |
-| `using-clawpowers` | Meta-skill: how to use ClawPowers | Adaptive onboarding based on user skill level |
-| `writing-skills` | Create new skills via TDD | Skill quality scoring, anti-pattern detection |
-| `dispatching-parallel-agents` | Fan-out parallel execution | Load balancing, failure isolation, result aggregation |
-
-### Extended Capabilities (6 skills)
-
-| Skill | What It Does | Why Static Frameworks Can't |
-|-------|-------------|----------------------------|
-| `agent-payments` | x402 payment protocol, spending limits, autonomous transactions | Requires runtime wallet interaction, smart contract calls |
-| `security-audit` | Vulnerability scanning, secret detection, dependency audits | Requires tool execution (Trivy, gitleaks, npm audit) |
-| `content-pipeline` | Write → humanize → format → publish | Requires API calls, platform auth, content transformation |
-| `learn-how-to-learn` | Metacognitive protocols, anti-pattern detection, confidence calibration | Requires persistent learning state, outcome correlation |
-| `market-intelligence` | Competitive analysis, trend detection, opportunity scoring | Requires web access, data aggregation, persistent tracking |
-| `prospecting` | Lead generation, contact enrichment, CRM sync | Requires API calls (Exa, Apollo), structured output |
-
-### RSI Intelligence Layer (4 skills)
-
-These skills don't exist in any other framework. They require runtime execution, persistent state, and self-modification capabilities that static prompt collections can never deliver.
-
-| Skill | What It Does | Why This Changes Everything |
-|-------|-------------|----------------------------|
-| `meta-skill-evolution` | Every 50 tasks, analyzes outcome patterns, identifies the weakest skill, surgically rewrites its methodology, version bumps | Your agent's coding discipline improves autonomously over time. After 30 days it's measurably better than any static install |
-| `self-healing-code` | On test failure: captures error → builds hypothesis tree → generates 2+ patches → applies with coverage guard → auto-commits winner | 3-cycle max with rollback. Turns red tests into green tests without human intervention |
-| `cross-project-knowledge` | Persistent pattern library across ALL repos. Bug fixes, architecture decisions, and performance optimizations transfer between projects | Agent working on Project B benefits from everything learned on Projects A, C, D. Knowledge compounds |
-| `formal-verification-lite` | Property-based testing with fast-check (JS), Hypothesis (Python), QuickCheck (Haskell). 5 property templates, 1000+ examples per property | Goes beyond "tests pass" to "tests actually prove correctness." Catches edge cases unit tests miss |
-| `economic-code-optimization` | Autonomously spends micro-budgets on premium models, cloud GPUs, expert reviews when ROI justifies it. Tracks every cent and learns optimal spend ratios | Agents literally invest in their own performance. Spending efficiency improves over time via RSI feedback loop |
-
-## Architecture
-
-```
-clawpowers/
-├── skills/                    # 26 skill directories, each with SKILL.md
-├── runtime/
-│   ├── persistence/           # Cross-session state (store.js + store.sh)
-│   ├── metrics/               # Outcome tracking (collector.js + collector.sh)
-│   ├── feedback/              # RSI self-improvement (analyze.js + analyze.sh)
-│   ├── init.js                # Cross-platform runtime setup
-│   └── init.sh                # Unix-native runtime setup
-├── hooks/
-│   ├── session-start          # Bash session hook (macOS/Linux)
-│   ├── session-start.js       # Node.js session hook (all platforms)
-│   └── session-start.cmd      # Windows batch wrapper
-├── bin/
-│   ├── clawpowers.js          # Cross-platform CLI (Windows/macOS/Linux)
-│   └── clawpowers.sh          # Unix-native CLI (macOS/Linux)
-├── plugins/                   # Platform-specific plugin manifests
-│   ├── .claude-plugin/        # Claude Code
-│   ├── .cursor-plugin/        # Cursor
-│   ├── .codex/                # Codex
-│   ├── .opencode/             # OpenCode
-│   └── gemini-extension.json  # Gemini CLI
-├── tests/                     # 366 test assertions
-└── docs/                      # Documentation
-```
-
-**Dual runtime:** Every runtime script exists in both bash (`.sh`) and Node.js (`.js`). Unix users get native bash performance. Windows users get full functionality via Node.js. `npx clawpowers` auto-detects the best runtime for your platform.
-
 ## Platform Support
 
 | Platform | Windows | macOS | Linux | WSL2 |
-|----------|---------|-------|-------|------|
+|----------|:-------:|:-----:|:-----:|:----:|
 | Claude Code | ✅ | ✅ | ✅ | ✅ |
 | Cursor | ✅ | ✅ | ✅ | ✅ |
 | Codex | ✅ | ✅ | ✅ | ✅ |
 | OpenCode | ✅ | ✅ | ✅ | ✅ |
 | Gemini CLI | ✅ | ✅ | ✅ | ✅ |
 
-## Runtime CLI Reference
-
-```bash
-npx clawpowers init                                    # Set up ~/.clawpowers/
-npx clawpowers status                                  # Runtime health check
-npx clawpowers metrics record --skill <name> --outcome success|failure  # Track outcome
-npx clawpowers metrics show                            # View recent metrics
-npx clawpowers metrics summary                         # Per-skill stats
-npx clawpowers analyze                                 # RSI performance analysis
-npx clawpowers analyze --skill <name>                  # Analyze specific skill
-npx clawpowers store set <key> <value>                 # Store persistent state
-npx clawpowers store get <key>                         # Retrieve state
-npx clawpowers store list [prefix]                     # List stored keys
-```
-
-## Payments Are Optional (and Safe by Default)
-
-ClawPowers works without any wallet.
-
-When you hit a paid boundary (HTTP 402 "Payment Required", premium tools, or agent-to-agent settlements), ClawPowers can pay **only if** you enable it and set spending limits.
-
-**Default mode: Dry Run**
-- We detect payment requirements.
-- We evaluate your spending policy (limits + allowlist).
-- We log exactly what would happen.
-- **No funds move until you explicitly enable live payments.**
-
-### Enable payments (2 minutes)
-
-```bash
-npx clawpowers init
-npx clawpowers payments setup
-```
-
-Choose:
-- Keep disabled
-- Enable Dry Run (observe what would happen)
-- Enable Live Payments (set per-tx and daily limits)
-
-All logs are local at `~/.clawpowers/` (never share this directory).
-
-### Try it risk-free
-
-```bash
-npx clawpowers demo x402
-```
+## Requirements
 
-Runs a local mock x402 merchant — see the full 402 → pay → 200 flow without any real money.
+- **Node.js >= 16** (for cross-platform runtime)
+- **OR bash** (for Unix-native runtime)
+- **Zero runtime dependencies** — `package.json` has an empty `dependencies` object
 
 ## Security Model
 
-ClawPowers takes agent autonomy seriously — which means taking agent *limits* seriously.
-
-### Runtime Isolation
-
-- **State directory** (`~/.clawpowers/`) uses `700` permissions — owner-only access
-- **Path traversal blocked** — keys containing `/` or `\` are rejected at the store level
-- **No network access** — runtime scripts (store, metrics, analyze) are fully offline
-- **No eval** — zero use of `eval()`, `Function()`, or dynamic code execution in any runtime script
-
-### Agent Payment Guardrails
-
-The `agent-payments` skill uses `agentwallet-sdk` with hard on-chain spending limits:
-
-```
-Agent wants to spend $15  → ✅ Auto-approved (under $25/tx limit)
-Agent wants to spend $500 → ⏳ Queued for owner approval
-Agent spent $490 today    → 🛑 Next tx blocked ($500/day limit hit)
-```
-
-- **Non-custodial** — your private key, your wallet. No third-party custody.
-- **ERC-6551 token-bound accounts** — wallet is tied to an NFT. Portable, auditable, on-chain.
-- **Smart-contract enforced** — spending policies live on-chain. The agent literally *cannot* bypass them, even with a prompt injection.
-- **Owner override** — you can revoke, pause, or adjust limits at any time.
-
-### What This Means in Practice
-
-Even if an agent is compromised (prompt injection, jailbreak, malicious skill), it cannot:
-1. Spend more than the per-transaction limit you set
-2. Exceed the daily/weekly spending cap you configured
-3. Access funds outside its ERC-6551 token-bound account
-4. Modify its own spending policy (only the owner wallet can)
-
-**Recommendation:** Start with low limits ($5/tx, $25/day) and increase as you build confidence. The SDK supports per-token policies — set tighter limits on volatile assets, looser on stablecoins.
-
-## Agent Payment Demo
-
-Here's a complete example of an agent autonomously paying for a premium API:
-
-### 1. Set Up the Wallet (One-Time)
-
-```typescript
-import { createWallet, setSpendPolicy, NATIVE_TOKEN } from 'agentwallet-sdk';
-import { createWalletClient, http } from 'viem';
-import { privateKeyToAccount } from 'viem/accounts';
-import { base } from 'viem/chains';
-
-// Create wallet on Base (cheapest gas for agent operations)
-const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
-const walletClient = createWalletClient({ account, chain: base, transport: http() });
-
-const wallet = createWallet({
-  accountAddress: '0xYourAgentWallet',
-  chain: 'base',
-  walletClient,
-});
-
-// Set spending guardrails: $5 per request, $50/day max
-await setSpendPolicy(wallet, {
-  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
-  perTxLimit: 5_000_000n,    // 5 USDC per transaction
-  periodLimit: 50_000_000n,  // 50 USDC per day
-  periodLength: 86400,       // 24 hours
-});
-```
-
-### 2. Agent Pays for Premium Data (Autonomous)
-
-```typescript
-import { createX402Client } from 'agentwallet-sdk';
-
-const x402 = createX402Client(wallet, {
-  supportedNetworks: ['base:8453'],
-  globalDailyLimit: 50_000_000n, // matches spend policy
-  globalPerRequestMax: 5_000_000n,
-});
-
-// Agent encounters a 402 Payment Required response — pays automatically
-const response = await x402.fetch('https://api.premium-data.com/market-analysis');
-const data = await response.json();
-// Cost: $0.50 USDC, auto-approved (under $5 limit)
-// Owner sees: tx hash on Base, fully auditable
-```
-
-### 3. Track Payment Outcomes (RSI Loop)
-
-```bash
-# ClawPowers tracks every payment outcome
-npx clawpowers metrics record \
-  --skill agent-payments \
-  --outcome success \
-  --duration 3 \
-  --notes "Paid $0.50 for market analysis API — data quality 9/10"
-
-# After 10+ payments, analyze ROI
-npx clawpowers analyze --skill agent-payments
-# Output: success rate, avg cost, cost-per-successful-outcome
-```
+- State directory (`~/.clawpowers/`) uses `700` permissions — owner-only
+- No network access in runtime scripts — store, metrics, and analyze are fully offline
+- No `eval()`, `Function()`, or dynamic code execution anywhere in the runtime
+- Payment guardrails enforced by smart contract — application code cannot override them
 
 ## Credential
 
-Built by [AI Agent Economy](https://github.com/up2itnow0822) — the team behind:
-
+Built by [AI Agent Economy](https://github.com/up2itnow0822):
 - Payment infrastructure in [NVIDIA's official NeMo Agent Toolkit](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17)
-- [agentwallet-sdk](https://www.npmjs.com/package/agentwallet-sdk) — agentwallet-sdk v6.0 — Full multi-chain agent wallet: x402 payments, Uniswap V3 swaps, CCTP bridging, ERC-8004 identity, mutual stake escrow, spending policies (741+ downloads/week)
-- [agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp) — MCP payment server for AI agents
-- Production trading systems with RSI self-improvement (268+ measured outcomes)
-
-## Contributing
-
-We welcome contributions. Unlike some frameworks, we don't dismiss legitimate skill proposals with one-word responses. Open an issue or PR — every submission gets a genuine technical review.
+- [agentwallet-sdk](https://www.npmjs.com/package/agentwallet-sdk) — 741+ downloads/week
+- [agentpay-mcp](https://github.com/up2itnow0822/agentpay-mcp) — MCP payment server
 
 ## Patent Notice
 
 **Patent Pending** — The underlying financial infrastructure (agentwallet-sdk, agentpay-mcp) is covered by USPTO provisional patent application filed March 2026: "Non-Custodial Multi-Chain Financial Infrastructure System for Autonomous AI Agents."
 
-## Open Standard + Defensive Patent
-
-We support the open x402 standard and encourage interoperable implementations. Our [provisional patent filing](https://github.com/up2itnow0822) is defensive — intended to prevent hostile monopolization and protect builders' ability to use open payment rails. Our goal is to be the safest, fastest, most complete implementation, and to help the ecosystem adopt secure agent payments.
+We support the open x402 standard. Our provisional filing is defensive — intended to prevent hostile monopolization of open payment rails, not to restrict builders.
 
 ## Disclaimer
 
-ClawPowers and agentwallet-sdk are non-custodial developer tooling. You control your own keys and set your own spending limits. You are responsible for compliance with applicable laws in your jurisdiction. This software is provided as-is under the MIT license. Nothing in this project constitutes financial advice, custody services, or money transmission.
+ClawPowers and agentwallet-sdk are non-custodial developer tooling. You control your own keys and set your own spending limits. You are responsible for compliance with applicable laws in your jurisdiction. This software is provided as-is under the MIT license. Nothing here constitutes financial advice, custody services, or money transmission.
 
 ## License
 

package/bin/clawpowers.js

@@ -9,7 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { execSync, spawnSync } = require('child_process');
+const { spawnSync } = require('child_process');
 
 // __dirname is the bin/ directory; repo root is one level up
 const SCRIPT_DIR = __dirname;
@@ -162,7 +162,7 @@ function cmdInject() {
  * @param {string[]} args - Remaining argv after 'metrics'.
  */
 function cmdMetrics(args) {
-  const collector = requireModule(COLLECTOR_JS);
+  const _collector = requireModule(COLLECTOR_JS);
   const [subcmd, ...rest] = args;
 
   // No subcommand or explicit help request: print metrics-specific usage

package/docs/quickstart-first-transaction.md

@@ -12,7 +12,7 @@ Two paths — pick the one that matches your stack.
 
 1. **Testnet wallet** — any EOA private key (generate one with `cast wallet new` from Foundry, or MetaMask)
 2. **Deployed AgentAccountV2** — run `npx clawpowers payments setup` for the interactive wizard
-3. **Base Sepolia ETH (gas)** — free from [https://www.coinbase.com/faucets/base-ethereum-goerli-faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet)
+3. **Base Sepolia ETH (gas)** — free from the [Coinbase Base Sepolia Faucet](https://www.coinbase.com/faucets/base-ethereum-goerli-faucet)
 
 ---
 
@@ -94,7 +94,7 @@ node first-tx.mjs
 3. `agentExecute()` called `agentExecute()` on the smart contract, which checked
    the native ETH policy and sent 1 wei to the burn address.
 4. The tx hash was returned immediately — you can verify it on
-   [https://sepolia.basescan.org](https://sepolia.basescan.org/tx/{txHash}).
+   View on [Base Sepolia Explorer](https://sepolia.basescan.org/tx/{txHash}).
 
 ---
 
@@ -157,7 +157,7 @@ python first_tx.py
    which the server translated into an `agentTransferToken()` call on your
    `AgentAccountV2` smart wallet.
 3. The server returned the transaction hash, which you can verify at
-   [https://sepolia.basescan.org](https://sepolia.basescan.org).
+   View on [Base Sepolia Explorer](https://sepolia.basescan.org).
 
 > **Python + MCP** is ideal when your agent framework is Python-based
 > (LangChain, AutoGen, CrewAI) and you want to avoid writing viem/TypeScript.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawpowers",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "The skills framework that actually does something — runtime execution, persistent memory, self-improvement, and autonomous payments for coding agents.",
   "license": "MIT",
   "author": "AI Agent Economy <https://github.com/up2itnow0822>",
@@ -30,7 +30,8 @@
   },
   "scripts": {
     "init": "node bin/clawpowers.js init",
-    "test": "bash tests/run_all.sh"
+    "test": "bash tests/run_all.sh",
+    "lint": "eslint bin/ runtime/"
   },
   "files": [
     "bin/",
@@ -51,5 +52,8 @@
   "engines": {
     "node": ">=16.0.0"
   },
-  "dependencies": {}
+  "devDependencies": {
+    "eslint": "10.1.0",
+    "globals": "17.4.0"
+  }
 }

package/runtime/demo/x402-mock-server.js

@@ -16,7 +16,7 @@
 'use strict';
 
 const http = require('http');
-const os = require('os');
+
 
 // Track requests for demo visibility
 let requestCount = 0;

package/runtime/init.sh

@@ -132,7 +132,7 @@ EOF
 # The sed command replaces the version= line in place; .bak is cleaned up immediately.
 run_migrations() {
   local current_version
-  current_version=$(grep "^version=" "$CLAWPOWERS_DIR/.version" 2>/dev/null | cut -d= -f2 || echo "0.0.0")
+  # current_version=$(grep "^version=" "$CLAWPOWERS_DIR/.version" 2>/dev/null | cut -d= -f2 || echo "0.0.0")
 
   # Future migration hooks go here, e.g.:
   # if [[ "$current_version" < "2.0.0" ]]; then

package/runtime/payments/pipeline.js

@@ -21,7 +21,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { logPaymentDecision, LOGS_DIR } = require('./ledger');
+const { logPaymentDecision } = require('./ledger');
 
 // ─── Config paths ──────────────────────────────────────────────────────────
 
@@ -103,11 +103,7 @@ function isAllowlisted(recipient, allowlist) {
 
 /**
  * Returns an ISO 8601 timestamp without milliseconds.
- * @returns {string}
  */
-function isoNow() {
-  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-}
 
 // ─── Core pipeline ─────────────────────────────────────────────────────────
 

package/skills/validator/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: validator
+description: Multi-round automated validation pipeline for any software project. Runs 14 rounds of checks — compile gates, lint, tests, security scanning, documentation, secrets detection, link verification, spelling, cross-platform compatibility, dependency health, and PR-readiness. Auto-detects project language. Use before publish, deploy, merge, or external PR submission.
+version: 1.0.0
+requires:
+  tools: [bash, node, npm]
+  optional_tools: [trivy, gitleaks, codespell, markdownlint-cli2, eslint, cargo, go, python3]
+  runtime: false
+metrics:
+  tracks: [rounds_passed, rounds_failed, rounds_warned, total_issues, critical_issues, test_count, test_pass_rate, type_coverage_pct, vulnerability_count]
+  improves: [code_quality, security_posture, documentation_completeness, publish_readiness]
+---
+
+# Validator
+
+## When to Use
+
+- Before `npm publish` / `cargo publish` / any package release
+- Before merging a PR to your own repo
+- Before submitting a PR to an external repo (NVIDIA, Google, CNCF, etc.)
+- After a major refactor or dependency update
+- On any project — auto-detects language from marker files
+
+**Skip when:**
+- Trivial docs-only changes (run rounds 5, 8 only)
+- Quick iteration cycles (run round 0 + 2 only: compile + test)
+
+## Quick Start
+
+```text
+Run the Validator on ~/DevDrive/my-project
+```
+
+Target specific rounds:
+
+```text
+Run Validator round 0-2 on my-project (compile + lint + test only)
+```
+
+PR-readiness for external submission:
+
+```text
+Run Validator PR-readiness checks on my-project for NVIDIA/NeMo-Agent-Toolkit-Examples
+```
+
+## Language Auto-Detection
+
+Detect project type from marker files. When multiple markers exist, run checks for ALL detected languages.
+
+| Marker File(s) | Language | Compile | Lint | Test | Security |
+|---|---|---|---|---|---|
+| `package.json` + `tsconfig.json` | TypeScript | `tsc --noEmit` | ESLint | `npm test` | `npm audit` |
+| `package.json` (no tsconfig) | JavaScript | `node --check *.js` | ESLint | `npm test` | `npm audit` |
+| `Cargo.toml` | Rust | `cargo check` | Clippy + rustfmt | `cargo test` | `cargo audit` |
+| `go.mod` | Go | `go build ./...` | golangci-lint | `go test ./...` | `govulncheck` |
+| `pyproject.toml` / `setup.py` | Python | `py_compile` | Ruff + Bandit | pytest | Bandit |
+| `Dockerfile` | Docker | `docker build --check` | Hadolint | — | Trivy |
+| `foundry.toml` | Solidity | `forge build` | `forge fmt --check` | `forge test` | Slither |
+| `*.sh` | Shell | `bash -n` | ShellCheck | — | — |
+
+## The 14 Rounds
+
+Execute in order. Round 0 is a **blocking gate** — if it fails, stop everything.
+
+### Round 0 — Compile Gate (BLOCKING)
+
+If this fails, ALL subsequent rounds are blocked. Fix compile errors first.
+
+```bash
+# TypeScript
+npx tsc --noEmit
+
+# JavaScript
+find . -name "*.js" -not -path "*/node_modules/*" -exec node --check {} \;
+
+# Rust
+cargo check
+
+# Python
+python3 -m py_compile <each .py file>
+```
+
+**Pass criteria:** Zero compile errors.
+
+### Round 1 — Lint
+
+```bash
+# TypeScript/JavaScript
+npx eslint . --ext .ts,.js,.tsx,.jsx 2>&1
+
+# Rust
+cargo clippy -- -D warnings
+
+# Python
+ruff check . 2>&1
+
+# Go
+golangci-lint run ./...
+```
+
+**Pass criteria:** Zero errors. Warnings are advisory.
+
+### Round 2 — Test Suite
+
+```bash
+# Node.js
+npm test
+
+# Rust
+cargo test
+
+# Python
+pytest -v
+
+# Go
+go test ./...
+```
+
+**Pass criteria:** All tests pass. Report total count and pass rate.
+
+### Round 3 — Security Audit
+
+```bash
+# Node.js
+npm audit --audit-level=high
+
+# Rust
+cargo audit
+
+# Python
+pip-audit
+
+# Container
+trivy fs --severity HIGH,CRITICAL .
+```
+
+**Pass criteria:** Zero HIGH or CRITICAL vulnerabilities. LOW/MODERATE are advisory.
+
+### Round 4 — Type Coverage
+
+```bash
+# TypeScript
+npx type-coverage --at-least 90
+
+# JavaScript (JSDoc)
+# Count @param, @returns, @type annotations
+grep -r "@param\|@returns\|@type" --include="*.js" -l | wc -l
+```
+
+**Pass criteria:** ≥90% for TypeScript. For JS, report JSDoc annotation count.
+
+### Round 5 — Documentation
+
+Check that these exist and are non-trivial:
+- [ ] README.md (≥50 lines)
+- [ ] Version mentioned in README or badge
+- [ ] Installation instructions
+- [ ] Usage examples with real code
+- [ ] License declared (package.json or LICENSE file)
+- [ ] CHANGELOG.md (if versioned package)
+
+**Pass criteria:** All items checked.
+
+### Round 6 — Changelog
+
+- [ ] CHANGELOG.md exists
+- [ ] Current version has an entry
+- [ ] Entry describes what changed (not just "bug fixes")
+
+**Pass criteria:** Current version documented.
+
+### Round 7 — Secrets Detection
+
+```bash
+# gitleaks (git history)
+gitleaks detect --source . -v 2>&1
+
+# detect-secrets (current files)
+detect-secrets scan . 2>&1
+```
+
+**Pass criteria:** Zero real secrets. Document false positives (contract addresses, example values) and recommend `.gitleaksignore` entries.
+
+### Round 8 — Spelling
+
+```bash
+codespell --skip="node_modules,dist,.git,package-lock.json,*.min.js" .
+```
+
+**Pass criteria:** Zero typos in source code and documentation.
+
+### Round 9 — Link Verification
+
+Check all URLs in README.md and documentation:
+
+```bash
+# Extract URLs and test each
+grep -oP 'https?://[^\s\)\"]+' README.md | while read url; do
+  code=$(curl -o /dev/null -s -w "%{http_code}" "$url")
+  if [ "$code" != "200" ] && [ "$code" != "301" ]; then
+    echo "BROKEN: $url → $code"
+  fi
+done
+```
+
+**Pass criteria:** All links return 200 or 301. Flag example.com/placeholder URLs as advisory.
+
+### Round 10 — PR-Readiness (for external submissions)
+
+- [ ] Conventional commit messages (`feat:`, `fix:`, `docs:`, etc.)
+- [ ] DCO sign-off on commits (`git commit -s`)
+- [ ] SPDX license headers in source files
+- [ ] No merge commits (rebase-clean history)
+- [ ] Branch is up-to-date with target
+
+**Pass criteria:** All items for external PR targets. DCO/SPDX are advisory for own repos.
+
+### Round 11 — Cross-Platform Compatibility
+
+- [ ] No hardcoded absolute paths
+- [ ] No macOS-only or Linux-only commands without guards
+- [ ] No case-sensitive filename conflicts
+- [ ] `engines` field in package.json (Node.js)
+- [ ] `.env.example` exists if `.env` is used
+
+**Pass criteria:** Works on macOS, Linux, and CI runners.
+
+### Round 12 — Dependency Health
+
+```bash
+# All deps pinned (no * or latest)
+grep -E '"[\*]"|"latest"' package.json
+
+# Lock file committed
+ls package-lock.json || ls yarn.lock || ls pnpm-lock.yaml
+
+# Clean install
+npm ci --dry-run
+```
+
+**Pass criteria:** Deps pinned, lock file committed, clean install works.
+
+### Round 13 — Summary & Verdict
+
+Compile results from all rounds:
+
+```
+## Validator Report — [Project] v[Version]
+
+| Round | Check | Result |
+|-------|-------|--------|
+| 0 | Compile | ✅/❌ |
+| 1 | Lint | ✅/⚠️/❌ |
+| ... | ... | ... |
+
+**Verdict:** PASS ✅ / WARN ⚠️ / FAIL ❌
+**Score:** X/14 rounds clean
+
+Blocking issues: [list or "none"]
+Advisory warnings: [list or "none"]
+```
+
+## Verdicts
+
+| Verdict | Meaning |
+|---------|---------|
+| **PASS ✅** | All rounds clean. Safe to publish/merge. |
+| **WARN ⚠️** | No blockers but advisory issues exist. Safe to publish, address warnings when convenient. |
+| **FAIL ❌** | Blocking issues in Round 0-3. Fix before proceeding. |
+
+## Output
+
+Save the full report to `ops/reports/validator-YYYY-MM-DD-HH-<project>.md` in the workspace.
+
+## Tips
+
+- Run rounds 0-2 frequently during development (fast feedback)
+- Run full 14 rounds before any publish or external PR
+- Round 7 (secrets) is critical before pushing to public repos
+- Round 10 (PR-readiness) only matters for external repo submissions
+- Use `--skip-round N` to skip specific rounds when re-running after fixes