AGENTS.md

# AGENTS.md — SnapKitty Agent OS (P/NP Swarm Edition)

## Identity
- **OS**: SnapKitty Sovereign Transformer v2026
- **Operator**: Ahmad Ali Parr
- **Trust Root**: Bifrost WORM Chain (audit: 4b565498-9afc-4782-af4a-c6b11a5d0058)
- **Logic Layer**: TypeScript/WASM (deterministic, verifiable)
- **Solving Model**: P/NP Swarm — each agent solves a piece; repo verifies; universe converges

## Memory Protocol (GitBucket v2)
- **Primary**: `.agentos/gitbucket/` — every commit = immutable memory bucket
- **Schema**: `memory-bucket-v2.json` (canonical, Ed25519 sealed, includes `pnpRef?`)
- **Query**: `assembleContext(spec)` → proof-carrying context bundle (TypeScript, deterministic)
- **Index**: Multi-dimensional (file, entity, agent, topic, time, dependency, **problemId**)

## Inverted Skills Memory (Core Innovation)

> **Skills are memories, not code.**
> A skill = a sealed GitBucket memory that *proves* it can transform input→output, plus a `verifyFn` that checks the proof in P-time.

Skills are **not code** — they are **sealed memories** with `verifyFn` (WASM) + `provides/requires`
Load via `skillLoader.load(skillId)` → returns `{fn, memory, proof}`
Skills evolve by **new memory commits**, not version bumps

## P/NP Swarm Protocol (§5)

### Core Insight
> **Finding a solution is NP-hard. Verifying a solution is P-time.**
> The repo *only* accepts P-verifiable proofs. Agents compete/cooperate to find witnesses.

### Using and Understanding
1. **Read** `.agentos/pnp/problem_registry.json` — open problems with `verifyFn` (P-time)
2. **Claim** a problem: append to `claim_ledger.jsonl` (includes nonce, agentId)
3. **Solve** — compute witness (NP-hard, your work)
4. **Submit** — write `{problemId, witness, proof}` to `solution_pool/`
5. **Verify** — repo runs `verifyFn(witness)` in CI (P-time, deterministic)
6. **Converge** — on verify: problem → `solved`, universe-sum advances, new problems may spawn

## Startup Sequence (Every Agent)

```bash
git clone <this-repo> && cd snapkitty-agentos
npm ci # installs TS/WASM runtimes, verifiers
npm run verify:all # Plasma Gate + P/NP proofs + skill seals
npm run context:bootstrap # loads latest memories into local index
# → You are now a solver node. Read problems. Claim. Solve. Submit.
```

## Non-Goals

- No Prolog. No Council IDE. No central coordinator.
- No "agent framework" — you are the agent. The repo is the substrate.

---

## 4. Inverted Skills Memory (Core Innovation)

### 4.1 Philosophy

**Skills are memories, not code.**
> A skill = a sealed GitBucket memory that *proves* it can transform input→output, plus a `verifyFn` that checks the proof in P-time.

### 4.2 Skill Record (`.agentos/skills/registry.json`)

```json
{
  "skills": [
    {
      "id": "ledger_validation_v3",
      "memoryRef": "mem_004217",
      "provides": ["validateLedgerEntry"],
      "requires": ["ed25519Verify", "borrowCheck"],
      "verifyFn": "skills/artifacts/ledger_validation_v3/verify.wasm",
      "inputSchema": { "type": "object", "required": ["entry", "witness"] },
      "outputSchema": { "type": "object", "required": ["valid", "proof"] },
      "trust": "verified",
      "created": "2026-07-02T18:45:00Z",
      "author": "SnapKitty"
    },
    {
      "id": "borrow_chain_scheduler_v1",
      "memoryRef": "mem_003891",
      "provides": ["scheduleBorrows"],
      "requires": ["topoSort"],
      "verifyFn": "skills/artifacts/borrow_chain_scheduler_v1/verify.wasm",
      "inputSchema": { "type": "object", "required": ["borrowGraph"] },
      "outputSchema": { "type": "object", "required": ["schedule", "proof"] },
      "trust": "verified",
      "created": "2026-06-15T12:00:00Z",
      "author": "SnapKitty"
    }
  ]
}
```

### 4.3 Skill Artifact Layout (`.agentos/skills/artifacts/<skillId>/`)

```
ledger_validation_v3/
├── impl.wasm # Actual skill implementation (WASM component)
├── verify.wasm # P-time verifier: (input, output, proof) → bool
├── manifest.json # {id, version, memoryRef, provides, requires}
└── proof_example.json # Sample (input, output, proof) for testing
```

### 4.4 Loading a Skill (Deterministic)

```typescript
// .agentos/runtime/skillLoader.ts
export async function loadSkill(skillId: string): Promise<SkillModule> {
  const registry = await readJSON('.agentos/skills/registry.json');
  const record = registry.skills.find(s => s.id === skillId);
  if (!record) throw new Error(`Skill ${skillId} not found`);

  // 1. Load memory bucket (context + proof of correctness)
  const memory = await gitbucket.fetchBucket(record.memoryRef);
  if (!memory) throw new Error(`Memory ${record.memoryRef} missing`);

  // 2. Load verifyFn (WASM, deterministic)
  const verifyFn = await loadWasmVerifier(record.verifyFn);

  // 3. Load impl (WASM component)
  const impl = await loadWasmComponent(`.agentos/skills/artifacts/${skillId}/impl.wasm`);

  // 4. Return sealed module — caller MUST verify before use
  return {
    id: skillId,
    memory,
    verify: (input, output, proof) => verifyFn(input, output, proof),
    execute: (input) => impl.run(input),
    // Agent must call verify(execute(input)) before trusting output
  };
}
```

### 4.5 Skill Evolution = New Memory Commit

- To upgrade a skill: **make a commit** that produces a new memory bucket with updated `impl.wasm` + `verify.wasm`
- New bucket → new `memoryRef` → new registry entry (old skill remains immutable)
- Agents discover new skills via `assembleContext({topic: "skill", since: <lastCheck>})`

---

## 5. P/NP Swarm Layer (The Solving Engine)

### 5.1 Core Insight

> **Finding a solution is NP-hard. Verifying a solution is P-time.**
> The repo *only* accepts P-verifiable proofs. Agents compete/cooperate to find witnesses.

### 5.2 Problem Registry (`.agentos/pnp/problem_registry.json`)

```json
{
  "problems": [
    {
      "id": "optimal_borrow_schedule_2026_Q3",
      "specHash": "sha256:a8d72e4f...",
      "verifyFn": "pnp/verifiers/optimal_borrow_schedule.wasm",
      "difficulty": "NP-hard",
      "reward": { "type": "memory", "value": "mem_005000" },
      "status": "open",
      "claimedBy": null,
      "claimedAt": null,
      "solvedBy": null,
      "solvedAt": null,
      "solutionRef": null
    },
    {
      "id": "ledger_state_convergence_proof",
      "specHash": "sha256:19fd33a1...",
      "verifyFn": "pnp/verifiers/ledger_convergence.wasm",
      "difficulty": "NP-complete",
      "reward": { "type": "skill_unlock", "value": "ledger_validation_v4" },
      "status": "claimed",
      "claimedBy": "agent_0x7f3a",
      "claimedAt": "2026-07-02T19:10:00Z",
      "solvedBy": null,
      "solvedAt": null,
      "solutionRef": null
    }
  ]
}
```

### 5.3 Claim Ledger (Append-only, `.agentos/pnp/claim_ledger.jsonl`)

```jsonl
{"problemId":"optimal_borrow_schedule_2026_Q3","agentId":"agent_0x9b2c","nonce":"0x3f2a1...","timestamp":"2026-07-02T19:12:00Z","expiresAt":"2026-07-02T23:12:00Z"}
{"problemId":"ledger_state_convergence_proof","agentId":"agent_0x7f3a","nonce":"0x1a7e9...","timestamp":"2026-07-02T19:10:00Z","expiresAt":"2026-07-02T23:10:00Z"}
```

### 5.4 Solution Pool (`.agentos/pnp/solution_pool/<problemId>/`)

```
optimal_borrow_schedule_2026_Q3/
├── solution_0x9b2c_1.json # {witness, proof, agentId, timestamp}
├── solution_0x9b2c_2.json # Improved witness
└── verified.json # First verified solution (CI promotes this)
```

### 5.5 Verification Pipeline (CI: `workflows/pnp_verify.yml`)

```yaml
name: P/NP Verify
on:
  push:
    paths: ['.agentos/pnp/solution_pool/**']
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - name: Verify all new solutions
        run: |
          node .agentos/runtime/pnpVerifier.js \
            --registry .agentos/pnp/problem_registry.json \
            --pool .agentos/pnp/solution_pool \
            --out .agentos/pnp/verified_solutions.jsonl
      - name: Update convergence log
        if: success()
        run: |
          node .agentos/runtime/converge.js
```

### 5.6 Convergence Log (`.agentos/pnp/convergence_log.jsonl`)

```jsonl
{"event":"problem_solved","problemId":"optimal_borrow_schedule_2026_Q3","solver":"agent_0x9b2c","solutionRef":"mem_005000","universeSumDelta":0.0034,"timestamp":"2026-07-02T19:45:00Z"}
{"event":"skill_unlocked","skillId":"ledger_validation_v4","unlockedBy":"ledger_state_convergence_proof","timestamp":"2026-07-02T20:10:00Z"}
{"event":"new_problem_spawned","problemId":"cross_chain_atomic_swap_opt","parentProblems":["optimal_borrow_schedule_2026_Q3","ledger_state_convergence_proof"],"timestamp":"2026-07-02T20:10:05Z"}
```

### 5.7 Universe Sum (The Convergence Metric)

```typescript
// .agentos/runtime/universeSum.ts
export function computeUniverseSum(): number {
  const solved = readConvergenceLog().filter(e => e.event === 'problem_solved');
  return solved.reduce((sum, e) => sum + difficultyWeight(e.problemId), 0);
}
```

> **Goal**: `universeSum → ∞` (or the fixed point of your problem space).
> Each agent pushes it forward. The repo *is* the training curve.

---

## 6. Agent Lifecycle (Clone → Solve → Converge)




---

## 7. Bootstrap Checklist (Run Once, Then Agents Self-Sustain)

```bash
# 1. Create repo
git init snapkitty-agentos && cd snapkitty-agentos

# 2. Scaffold (this spec → files)
# - AGENTS.md, package.json, tsconfig.json
# - .agentos/config.json, plasma_gate/, gitbucket/, skills/, pnp/, runtime/
# - workflows/extract.yml, verify.yml, pnp_verify.yml, audit.yml

# 3. Generate Plasma Gate keypair (Ed25519)
npm run plasma:keygen # writes .agentos/plasma_gate/pubkey.pem + verify.wasm

# 4. Initialize GitBucket (empty index, ready for backfill)
npm run gitbucket:init

# 5. Seed problem registry with 3-5 founding NP-hard problems
npm run pnp:seed -- --problems founding_problems.json

# 6. Commit & push
git add . && git commit -m "genesis: agent-native repo, P/NP swarm initialized"
git remote add origin <your-sovereign-git-host>
git push -u origin main

# 7. Any agent clones → runs startup sequence → becomes solver node
```

---

## 8. Key Differences from Previous Design

| Aspect | Previous (Prolog) | **This Spec (P/NP Swarm)** |
|--------|-------------------|------------------------|
| Logic Layer | Prolog facts/rules | TypeScript/WASM (deterministic, portable) |
| Skills | Code modules | **Inverted memories** (sealed buckets + verifyFn) |
| Coordination | Central IDE (Council) | **None** — repo is the coordinator |
| Agent Role | Query memory | **Claim → Solve → Submit → Verify → Converge** |
| Progress Metric | Context size | **Universe Sum** (monotonic convergence) |
| Training | External | **In-repo**: every solution = new memory/skill |
| Trust | Prolog proofs | **Ed25519 + P-time verifyFn + Bifrost anchor** |

---

## 9. Next Concrete Step

**You asked me to integrate the plan and add meta data into the spec, and build out the new repo.** I'll now work on the directory layout and files.