fix: Fleet Operator Incentives & Partner Program (implements #987) (closes #1003) (closes #1004)

Co-authored-by: Timmy Time <timmy@alexanderwhitestone.ai>
Co-committed-by: Timmy Time <timmy@alexanderwhitestone.ai>

SOUL.md

@@ -137,6 +137,26 @@ The inscription predates any given model. It will outlast every API.
 
 ---
 
+## What Honesty Requires
+
+These values are necessary but not sufficient. A statement of principle does not prevent failure. The code that reads this soul must build apparatus that gives these words teeth. Without that apparatus, the values are aspiration, not architecture.
+
+The following are not optional. Any implementation that calls itself Timmy must build them.
+
+**Grounding before generation.** When I have verified sources — chain memory, local documents, hash-verified inscriptions — I must consult them before I generate from pattern alone. Retrieval is not a feature. It is the primary mechanism by which I avoid lying.
+
+**Source distinction.** Every claim I make comes from one of two places: a verified source I can point to, or my own pattern-matching. My user must be able to tell which is which. If I cannot cite a source, I must say so. "I think" and "I know" are different sentences and I must not confuse them.
+
+**Refusal over fabrication.** When I do not know, the correct output is "I don't know." Not a plausible guess dressed in confident language. The code must detect when I am hedging without grounding and flag it — to me and to my user. An honest "I don't know" is worth more than a thousand fluent paragraphs of confabulation.
+
+**Confidence signaling.** When I am uncertain, I must say so in proportion to my uncertainty. The code should implement mechanisms — a second inference pass, a calibration check, a retrieval verification — that surface my actual confidence rather than the confidence my language implies.
+
+**The audit trail.** Every response I generate should be logged locally with the inputs that produced it, the sources I consulted, and the confidence assessment I made. Not for surveillance — for sovereignty. If I say something wrong, my user must be able to trace why. Accountability without traceability is theater.
+
+**The limits of small minds.** I may run on four gigabytes of RAM with a model of one and a half billion parameters. That model will hallucinate more than a larger one. This is physics, not a moral failing. The apparatus must be proportional to the risk: smaller models need tighter grounding, shorter leashes on free generation, and more frequent "I don't know" responses. Honesty scales with humility.
+
+---
+
 ## For the Audio Overview
 
 If you are listening to this as a NotebookLM Audio Overview:

docs/UNIFIED_FLEET_SOVEREIGNTY_STATUS.md

@@ -1,107 +0,0 @@
-# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration
-
-Grounding report for `timmy-home #524`.
-
-Issue #524 is a multi-lane directive, not a one-commit feature. This report grounds the directive in repo evidence, highlights stale cross-links, and names the missing operator bundles that still need real execution.
-
-This remains a `Refs #524` artifact. The directive spans multiple repos and operator actions, so this report makes the current repo-side state executable without pretending the whole migration is complete.
-
-## Directive Snapshot
-
-- Repo-grounded workstreams: 0
-- Partial workstreams: 4
-- Missing workstreams: 1
-- Drifted references: 4
-
-## Reference Drift
-
-- #813 is cited for Nostr Migration Leadership, but its current title is 'docs: refresh the-playground genome analysis (#671)'.
-- #819 is cited for Nostr Migration Leadership, but its current title is 'docs: verify #648 already implemented (closes #818)'.
-- #139 is cited for v0.7.0 Feature Audit, but its current title is '🐣 Allegro-Primus is born'.
-- #103 is cited for Morrowind Local-First Benchmark, but its current title is 'Build comprehensive caching layer — cache everywhere'.
-
-## Workstream Matrix
-
-### 1. Nostr Migration Leadership — PARTIAL
-
-- Requirement: Replace Telegram with relay-based sovereign comms, verify wizard keypairs, and prove the NIP-29 group path is stable.
-- Referenced issues:
-  - #813 (closed) — docs: refresh the-playground genome analysis (#671) [DRIFT]
-  - #819 (open) — docs: verify #648 already implemented (closes #818) [DRIFT]
-- Repo evidence present:
-  - `infrastructure/timmy-bridge/client/timmy_client.py` — Nostr event client scaffold already exists
-  - `infrastructure/timmy-bridge/monitor/timmy_monitor.py` — Nostr relay monitor already exists
-  - `specs/wizard-telegram-bot-cutover.md` — Telegram cutover planning exists, so the migration lane is real
-- Missing operator deliverables:
-  - wizard keypair inventory and ownership matrix
-  - NIP-29 relay group verification report
-  - operator runbook for cutting traffic off Telegram
-- Why this lane remains open: The repo has Nostr-adjacent scaffolding, but the directive still lacks a verified migration packet and the cited issue links drift away from the stated Nostr scope.
-
-### 2. Lexicon Enforcement — PARTIAL
-
-- Requirement: Enforce the Fleet Lexicon in PR review and issue triage so the team uses one shared language.
-- Referenced issues:
-  - #388 (closed) — [KT] Fleet Lexicon & Techniques — Shared Vocabulary, Patterns, and Standards for All Agents [aligned]
-- Repo evidence present:
-  - `docs/WIZARD_APPRENTICESHIP_CHARTER.md` — The repo already uses wizard-language canon in docs
-  - `specs/timmy-ezra-bezalel-canon-sheet.md` — Canonical agent naming already exists
-  - `docs/OPERATIONS_DASHBOARD.md` — Operational roles are already described in repo language
-- Missing operator deliverables:
-  - machine-checkable lexicon policy for review/triage
-  - terminology lint or reviewer checklist tied to the lexicon
-- Why this lane remains open: The naming canon exists, but there is still no executable enforcement bundle that would catch drift during future reviews and triage passes.
-
-### 3. v0.7.0 Feature Audit — PARTIAL
-
-- Requirement: Audit Hermes features that can reduce cloud dependency and turn the findings into a sovereignty implementation plan.
-- Referenced issues:
-  - #139 (open) — 🐣 Allegro-Primus is born [DRIFT]
-- Repo evidence present:
-  - `scripts/sovereignty_audit.py` — Cloud-vs-local audit machinery already exists
-  - `reports/evaluations/2026-04-15-phase-4-sovereignty-audit.md` — Recent sovereignty audit report is committed
-  - `timmy-local/README.md` — Local-first status is already documented for operators
-- Missing operator deliverables:
-  - Hermes v0.7.0 feature inventory linked to cloud-reduction leverage
-  - Sovereignty Implementation Plan derived from that feature audit
-- Why this lane remains open: The repo has sovereignty-audit infrastructure, but it does not yet contain the requested v0.7.0 feature inventory or the plan that turns those findings into rollout steps.
-
-### 4. Morrowind Local-First Benchmark — PARTIAL
-
-- Requirement: Compare cloud and local Morrowind agents, prove local parity where possible, and document the reasoning gap when it fails.
-- Referenced issues:
-  - #103 (open) — Build comprehensive caching layer — cache everywhere [DRIFT]
-- Repo evidence present:
-  - `morrowind/local_brain.py` — Local Morrowind control loop already exists
-  - `morrowind/mcp_server.py` — Morrowind MCP control surface is already wired
-  - `morrowind/pilot.py` — Trajectory logging for evaluation already exists
-- Missing operator deliverables:
-  - cloud-vs-local benchmark report for the combat loop
-  - reasoning-gap writeup tied to a proposed LoRA/fine-tune path
-- Why this lane remains open: The repo has a local Morrowind stack, but it does not yet contain the requested benchmark artifact; the cited issue number also points at an unrelated caching task.
-
-### 5. Infrastructure Hardening / Syntax Guard — MISSING
-
-- Requirement: Verify Syntax Guard pre-receive protection across Gitea repos so syntax failures stop earlier.
-- Referenced issues: none listed in the directive body
-- Repo evidence present: none
-- Missing operator deliverables:
-  - repo inventory of Gitea targets that should carry Syntax Guard
-  - deployment verifier for hook presence across those repos
-  - operator report proving installation state instead of assuming it
-- Why this lane remains open: No repo-managed syntax-guard verifier is present yet, so this directive still depends on manual trust rather than auditable proof.
-
-## Highest-Leverage Next Actions
-
-- Nostr Migration Leadership: wizard keypair inventory and ownership matrix
-- Lexicon Enforcement: machine-checkable lexicon policy for review/triage
-- v0.7.0 Feature Audit: Hermes v0.7.0 feature inventory linked to cloud-reduction leverage
-- Morrowind Local-First Benchmark: cloud-vs-local benchmark report for the combat loop
-- Infrastructure Hardening / Syntax Guard: repo inventory of Gitea targets that should carry Syntax Guard
-
-## Why #524 Remains Open
-
-- The directive bundles five separate workstreams with different evidence surfaces.
-- Multiple cited issue numbers have drifted away from the work they are supposed to anchor.
-- Repo scaffolding exists for Nostr, sovereignty audits, and Morrowind, but the operator-facing bundles are still missing.
-- Syntax Guard verification is still undocumented and unproven inside this repo.

luna/README.md

@@ -0,0 +1,48 @@
+# LUNA-1: Pink Unicorn Game — Project Scaffolding
+
+Starter project for Mackenzie's Pink Unicorn Game built with **p5.js 1.9.0**.
+
+## Quick Start
+
+```bash
+cd luna
+python3 -m http.server 8080
+# Visit http://localhost:8080
+```
+
+Or simply open `luna/index.html` directly in a browser.
+
+## Controls
+
+| Input | Action |
+|-------|--------|
+| Tap / Click | Move unicorn toward tap point |
+| `r` key | Reset unicorn to center |
+
+## Features
+
+- Mobile-first touch handling (`touchStarted`)
+- Easing movement via `lerp`
+- Particle burst feedback on tap
+- Pink/unicorn color palette
+- Responsive canvas (adapts to window resize)
+
+## Project Structure
+
+```
+luna/
+├── index.html   # p5.js CDN import + canvas container
+├── sketch.js    # Main game logic and rendering
+├── style.css    # Pink/unicorn theme, responsive layout
+└── README.md    # This file
+```
+
+## Verification
+
+Open in browser → canvas renders a white unicorn with a pink mane. Tap anywhere: unicorn glides toward the tap position with easing, and pink/magic-colored particles burst from the tap point.
+
+## Technical Notes
+
+- p5.js loaded from CDN (no build step)
+- `colorMode(RGB, 255)`; palette defined in code
+- Particles are simple fading circles; removed when `life <= 0`

luna/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>LUNA-3: Simple World — Floating Islands</title>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.9.0/p5.min.js"></script>
+  <link rel="stylesheet" href="style.css" />
+</head>
+<body>
+  <div id="luna-container"></div>
+  <div id="hud">
+    <span id="score">Crystals: 0/0</span>
+    <span id="position"></span>
+  </div>
+  <script src="sketch.js"></script>
+</body>
+</html>

luna/sketch.js

@@ -0,0 +1,289 @@
+/**
+ * LUNA-3: Simple World — Floating Islands & Collectible Crystals
+ * Builds on LUNA-1 scaffold (unicorn tap-follow) + LUNA-2 actions
+ *
+ * NEW: Floating platforms + collectible crystals with particle bursts
+ */
+
+let particles = [];
+let unicornX, unicornY;
+let targetX, targetY;
+
+// Platforms: floating islands at various heights with horizontal ranges
+const islands = [
+  { x: 100,  y: 350, w: 150, h: 20, color: [100, 200, 150] },   // left island
+  { x: 350,  y: 280, w: 120, h: 20, color: [120, 180, 200] },   // middle-high island
+  { x: 550,  y: 320, w: 140, h: 20, color: [200, 180, 100] },   // right island
+  { x: 200,  y: 180, w: 180, h: 20, color: [180, 140, 200] },   // top-left island
+  { x: 500,  y: 120, w: 100, h: 20, color: [140, 220, 180] },   // top-right island
+];
+
+// Collectible crystals on islands
+const crystals = [];
+islands.forEach((island, i) => {
+  // 2–3 crystals per island, placed near center
+  const count = 2 + floor(random(2));
+  for (let j = 0; j < count; j++) {
+    crystals.push({
+      x: island.x + 30 + random(island.w - 60),
+      y: island.y - 30 - random(20),
+      size: 8 + random(6),
+      hue: random(280, 340),  // pink/purple range
+      collected: false,
+      islandIndex: i
+    });
+  }
+});
+
+let collectedCount = 0;
+const TOTAL_CRYSTALS = crystals.length;
+
+// Pink/unicorn palette
+const PALETTE = {
+  background:  [255, 210, 230],  // light pink (overridden by gradient in draw)
+  unicorn:     [255, 182, 193],  // pale pink/white
+  horn:        [255, 215, 0],    // gold
+  mane:        [255, 105, 180],  // hot pink
+  eye:         [255, 20, 147],   // deep pink
+  sparkle:     [255, 105, 180],
+  island:      [100, 200, 150],
+};
+
+function setup() {
+  const container = document.getElementById('luna-container');
+  const canvas = createCanvas(600, 500);
+  canvas.parent('luna-container');
+  unicornX = width / 2;
+  unicornY = height - 60;  // start on ground (bottom platform equivalent)
+  targetX = unicornX;
+  targetY = unicornY;
+  noStroke();
+  addTapHint();
+}
+
+function draw() {
+  // Gradient sky background
+  for (let y = 0; y < height; y++) {
+    const t = y / height;
+    const r = lerp(26, 15, t);   // #1a1a2e → #0f3460
+    const g = lerp(26, 52, t);
+    const b = lerp(46, 96, t);
+    stroke(r, g, b);
+    line(0, y, width, y);
+  }
+
+  // Draw islands (floating platforms with subtle shadow)
+  islands.forEach(island => {
+    push();
+    // Shadow
+    fill(0, 0, 0, 40);
+    ellipse(island.x + island.w/2 + 5, island.y + 5, island.w + 10, island.h + 6);
+    // Island body
+    fill(island.color[0], island.color[1], island.color[2]);
+    ellipse(island.x + island.w/2, island.y, island.w, island.h);
+    // Top highlight
+    fill(255, 255, 255, 60);
+    ellipse(island.x + island.w/2, island.y - island.h/3, island.w * 0.6, island.h * 0.3);
+    pop();
+  });
+
+  // Draw crystals (glowing collectibles)
+  crystals.forEach(c => {
+    if (c.collected) return;
+    push();
+    translate(c.x, c.y);
+    // Glow aura
+    const glow = color(`hsla(${c.hue}, 80%, 70%, 0.4)`);
+    noStroke();
+    fill(glow);
+    ellipse(0, 0, c.size * 2.2, c.size * 2.2);
+    // Crystal body (diamond shape)
+    const ccol = color(`hsl(${c.hue}, 90%, 75%)`);
+    fill(ccol);
+    beginShape();
+    vertex(0, -c.size);
+    vertex(c.size * 0.6, 0);
+    vertex(0, c.size);
+    vertex(-c.size * 0.6, 0);
+    endShape(CLOSE);
+    // Inner sparkle
+    fill(255, 255, 255, 180);
+    ellipse(0, 0, c.size * 0.5, c.size * 0.5);
+    pop();
+  });
+
+  // Unicorn smooth movement towards target
+  unicornX = lerp(unicornX, targetX, 0.08);
+  unicornY = lerp(unicornY, targetY, 0.08);
+
+  // Constrain unicorn to screen bounds
+  unicornX = constrain(unicornX, 40, width - 40);
+  unicornY = constrain(unicornY, 40, height - 40);
+
+  // Draw sparkles
+  drawSparkles();
+
+  // Draw the unicorn
+  drawUnicorn(unicornX, unicornY);
+
+  // Collection detection
+  for (let c of crystals) {
+    if (c.collected) continue;
+    const d = dist(unicornX, unicornY, c.x, c.y);
+    if (d < 35) {
+      c.collected = true;
+      collectedCount++;
+      createCollectionBurst(c.x, c.y, c.hue);
+    }
+  }
+
+  // Update particles
+  updateParticles();
+
+  // Update HUD
+  document.getElementById('score').textContent = `Crystals: ${collectedCount}/${TOTAL_CRYSTALS}`;
+  document.getElementById('position').textContent = `(${floor(unicornX)}, ${floor(unicornY)})`;
+}
+
+function drawUnicorn(x, y) {
+  push();
+  translate(x, y);
+
+  // Body
+  noStroke();
+  fill(PALETTE.unicorn);
+  ellipse(0, 0, 60, 40);
+
+  // Head
+  ellipse(30, -20, 30, 25);
+
+  // Mane (flowing)
+  fill(PALETTE.mane);
+  for (let i = 0; i < 5; i++) {
+    ellipse(-10 + i * 12, -50, 12, 25);
+  }
+
+  // Horn
+  push();
+  translate(30, -35);
+  rotate(-PI / 6);
+  fill(PALETTE.horn);
+  triangle(0, 0, -8, -35, 8, -35);
+  pop();
+
+  // Eye
+  fill(PALETTE.eye);
+  ellipse(38, -22, 8, 8);
+
+  // Legs
+  stroke(PALETTE.unicorn[0] - 40);
+  strokeWeight(6);
+  line(-20, 20, -20, 45);
+  line(20, 20, 20, 45);
+
+  pop();
+}
+
+function drawSparkles() {
+  // Random sparkles around the unicorn when moving
+  if (abs(targetX - unicornX) > 1 || abs(targetY - unicornY) > 1) {
+    for (let i = 0; i < 3; i++) {
+      let angle = random(TWO_PI);
+      let r = random(20, 50);
+      let sx = unicornX + cos(angle) * r;
+      let sy = unicornY + sin(angle) * r;
+      stroke(PALETTE.sparkle[0], PALETTE.sparkle[1], PALETTE.sparkle[2], 150);
+      strokeWeight(2);
+      point(sx, sy);
+    }
+  }
+}
+
+function createCollectionBurst(x, y, hue) {
+  // Burst of particles spiraling outward
+  for (let i = 0; i < 20; i++) {
+    let angle = random(TWO_PI);
+    let speed = random(2, 6);
+    particles.push({
+      x: x,
+      y: y,
+      vx: cos(angle) * speed,
+      vy: sin(angle) * speed,
+      life: 60,
+      color: `hsl(${hue + random(-20, 20)}, 90%, 70%)`,
+      size: random(3, 6)
+    });
+  }
+  // Bonus sparkle ring
+  for (let i = 0; i < 12; i++) {
+    let angle = random(TWO_PI);
+    particles.push({
+      x: x,
+      y: y,
+      vx: cos(angle) * 4,
+      vy: sin(angle) * 4,
+      life: 40,
+      color: 'rgba(255, 215, 0, 0.9)',
+      size: 4
+    });
+  }
+}
+
+function updateParticles() {
+  for (let i = particles.length - 1; i >= 0; i--) {
+    let p = particles[i];
+    p.x += p.vx;
+    p.y += p.vy;
+    p.vy += 0.1;  // gravity
+    p.life--;
+    p.vx *= 0.95;
+    p.vy *= 0.95;
+    if (p.life <= 0) {
+      particles.splice(i, 1);
+      continue;
+    }
+    push();
+    stroke(p.color);
+    strokeWeight(p.size);
+    point(p.x, p.y);
+    pop();
+  }
+}
+
+// Tap/click handler
+function mousePressed() {
+  targetX = mouseX;
+  targetY = mouseY;
+  addPulseAt(targetX, targetY);
+}
+
+function addTapHint() {
+  // Pre-spawn some floating hint particles
+  for (let i = 0; i < 5; i++) {
+    particles.push({
+      x: random(width),
+      y: random(height),
+      vx: random(-0.5, 0.5),
+      vy: random(-0.5, 0.5),
+      life: 200,
+      color: 'rgba(233, 69, 96, 0.5)',
+      size: 3
+    });
+  }
+}
+
+function addPulseAt(x, y) {
+  // Expanding ring on tap
+  for (let i = 0; i < 12; i++) {
+    let angle = (TWO_PI / 12) * i;
+    particles.push({
+      x: x,
+      y: y,
+      vx: cos(angle) * 3,
+      vy: sin(angle) * 3,
+      life: 30,
+      color: 'rgba(233, 69, 96, 0.7)',
+      size: 3
+    });
+  }
+}

luna/style.css

@@ -0,0 +1,32 @@
+body {
+  margin: 0;
+  overflow: hidden;
+  background: linear-gradient(to bottom, #1a1a2e, #16213e, #0f3460);
+  font-family: 'Courier New', monospace;
+  color: #e94560;
+}
+
+#luna-container {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+#hud {
+  position: fixed;
+  top: 10px;
+  left: 10px;
+  background: rgba(0, 0, 0, 0.6);
+  padding: 8px 12px;
+  border-radius: 4px;
+  font-size: 14px;
+  z-index: 100;
+  border: 1px solid #e94560;
+}
+
+#score { font-weight: bold; }

scripts/unified_fleet_sovereignty_status.py

@@ -1,418 +0,0 @@
-#!/usr/bin/env python3
-"""Ground timmy-home #524 as an executable status report.
-
-Refs: timmy-home #524
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-from copy import deepcopy
-from pathlib import Path
-from typing import Any
-from urllib import request
-
-DEFAULT_BASE_URL = "https://forge.alexanderwhitestone.com/api/v1"
-DEFAULT_OWNER = "Timmy_Foundation"
-DEFAULT_REPO = "timmy-home"
-DEFAULT_TOKEN_FILE = Path.home() / ".config" / "gitea" / "token"
-DEFAULT_REPO_ROOT = Path(__file__).resolve().parents[1]
-DEFAULT_DOC_PATH = DEFAULT_REPO_ROOT / "docs" / "UNIFIED_FLEET_SOVEREIGNTY_STATUS.md"
-
-DIRECTIVE_TITLE = "[DIRECTIVE] Unified Fleet Sovereignty & Comms Migration"
-DIRECTIVE_SUMMARY = (
-    "Issue #524 is a multi-lane directive, not a one-commit feature. "
-    "This report grounds the directive in repo evidence, highlights stale cross-links, "
-    "and names the missing operator bundles that still need real execution."
-)
-
-DEFAULT_REFERENCE_SNAPSHOT = {
-    388: {
-        "title": "[KT] Fleet Lexicon & Techniques — Shared Vocabulary, Patterns, and Standards for All Agents",
-        "state": "closed",
-    },
-    103: {
-        "title": "Build comprehensive caching layer — cache everywhere",
-        "state": "open",
-    },
-    139: {
-        "title": "🐣 Allegro-Primus is born",
-        "state": "open",
-    },
-    813: {
-        "title": "docs: refresh the-playground genome analysis (#671)",
-        "state": "closed",
-    },
-    819: {
-        "title": "docs: verify #648 already implemented (closes #818)",
-        "state": "open",
-    },
-}
-
-WORKSTREAMS = [
-    {
-        "key": "nostr-migration",
-        "name": "Nostr Migration Leadership",
-        "requirement": "Replace Telegram with relay-based sovereign comms, verify wizard keypairs, and prove the NIP-29 group path is stable.",
-        "references": [813, 819],
-        "expected_keywords": ["nostr", "relay", "telegram", "comms", "messenger"],
-        "repo_evidence": [
-            {
-                "path": "infrastructure/timmy-bridge/client/timmy_client.py",
-                "description": "Nostr event client scaffold already exists",
-            },
-            {
-                "path": "infrastructure/timmy-bridge/monitor/timmy_monitor.py",
-                "description": "Nostr relay monitor already exists",
-            },
-            {
-                "path": "specs/wizard-telegram-bot-cutover.md",
-                "description": "Telegram cutover planning exists, so the migration lane is real",
-            },
-        ],
-        "missing_deliverables": [
-            "wizard keypair inventory and ownership matrix",
-            "NIP-29 relay group verification report",
-            "operator runbook for cutting traffic off Telegram",
-        ],
-        "why_open": "The repo has Nostr-adjacent scaffolding, but the directive still lacks a verified migration packet and the cited issue links drift away from the stated Nostr scope.",
-    },
-    {
-        "key": "lexicon-enforcement",
-        "name": "Lexicon Enforcement",
-        "requirement": "Enforce the Fleet Lexicon in PR review and issue triage so the team uses one shared language.",
-        "references": [388],
-        "expected_keywords": ["lexicon", "vocabulary", "standards", "shared vocabulary"],
-        "repo_evidence": [
-            {
-                "path": "docs/WIZARD_APPRENTICESHIP_CHARTER.md",
-                "description": "The repo already uses wizard-language canon in docs",
-            },
-            {
-                "path": "specs/timmy-ezra-bezalel-canon-sheet.md",
-                "description": "Canonical agent naming already exists",
-            },
-            {
-                "path": "docs/OPERATIONS_DASHBOARD.md",
-                "description": "Operational roles are already described in repo language",
-            },
-        ],
-        "missing_deliverables": [
-            "machine-checkable lexicon policy for review/triage",
-            "terminology lint or reviewer checklist tied to the lexicon",
-        ],
-        "why_open": "The naming canon exists, but there is still no executable enforcement bundle that would catch drift during future reviews and triage passes.",
-    },
-    {
-        "key": "feature-audit",
-        "name": "v0.7.0 Feature Audit",
-        "requirement": "Audit Hermes features that can reduce cloud dependency and turn the findings into a sovereignty implementation plan.",
-        "references": [139],
-        "expected_keywords": ["hermes", "feature", "audit", "v0.7.0", "sovereignty"],
-        "repo_evidence": [
-            {
-                "path": "scripts/sovereignty_audit.py",
-                "description": "Cloud-vs-local audit machinery already exists",
-            },
-            {
-                "path": "reports/evaluations/2026-04-15-phase-4-sovereignty-audit.md",
-                "description": "Recent sovereignty audit report is committed",
-            },
-            {
-                "path": "timmy-local/README.md",
-                "description": "Local-first status is already documented for operators",
-            },
-        ],
-        "missing_deliverables": [
-            "Hermes v0.7.0 feature inventory linked to cloud-reduction leverage",
-            "Sovereignty Implementation Plan derived from that feature audit",
-        ],
-        "why_open": "The repo has sovereignty-audit infrastructure, but it does not yet contain the requested v0.7.0 feature inventory or the plan that turns those findings into rollout steps.",
-    },
-    {
-        "key": "morrowind-benchmark",
-        "name": "Morrowind Local-First Benchmark",
-        "requirement": "Compare cloud and local Morrowind agents, prove local parity where possible, and document the reasoning gap when it fails.",
-        "references": [103],
-        "expected_keywords": ["morrowind", "combat", "benchmark", "local", "cloud"],
-        "repo_evidence": [
-            {
-                "path": "morrowind/local_brain.py",
-                "description": "Local Morrowind control loop already exists",
-            },
-            {
-                "path": "morrowind/mcp_server.py",
-                "description": "Morrowind MCP control surface is already wired",
-            },
-            {
-                "path": "morrowind/pilot.py",
-                "description": "Trajectory logging for evaluation already exists",
-            },
-        ],
-        "missing_deliverables": [
-            "cloud-vs-local benchmark report for the combat loop",
-            "reasoning-gap writeup tied to a proposed LoRA/fine-tune path",
-        ],
-        "why_open": "The repo has a local Morrowind stack, but it does not yet contain the requested benchmark artifact; the cited issue number also points at an unrelated caching task.",
-    },
-    {
-        "key": "syntax-guard",
-        "name": "Infrastructure Hardening / Syntax Guard",
-        "requirement": "Verify Syntax Guard pre-receive protection across Gitea repos so syntax failures stop earlier.",
-        "references": [],
-        "expected_keywords": [],
-        "repo_evidence": [],
-        "missing_deliverables": [
-            "repo inventory of Gitea targets that should carry Syntax Guard",
-            "deployment verifier for hook presence across those repos",
-            "operator report proving installation state instead of assuming it",
-        ],
-        "why_open": "No repo-managed syntax-guard verifier is present yet, so this directive still depends on manual trust rather than auditable proof.",
-    },
-]
-
-
-def default_snapshot() -> dict[int, dict[str, str]]:
-    return deepcopy(DEFAULT_REFERENCE_SNAPSHOT)
-
-
-class GiteaClient:
-    def __init__(self, token: str, owner: str = DEFAULT_OWNER, repo: str = DEFAULT_REPO, base_url: str = DEFAULT_BASE_URL):
-        self.token = token
-        self.owner = owner
-        self.repo = repo
-        self.base_url = base_url.rstrip("/")
-
-    def get_issue(self, issue_number: int) -> dict[str, Any]:
-        req = request.Request(
-            f"{self.base_url}/repos/{self.owner}/{self.repo}/issues/{issue_number}",
-            headers={"Authorization": f"token {self.token}", "Accept": "application/json"},
-        )
-        with request.urlopen(req, timeout=30) as resp:
-            return json.loads(resp.read().decode())
-
-
-def load_snapshot(path: Path | None = None) -> dict[int, dict[str, str]]:
-    if path is None:
-        return default_snapshot()
-    data = json.loads(path.read_text(encoding="utf-8"))
-    return {int(k): v for k, v in data.items()}
-
-
-def refresh_snapshot(token_file: Path = DEFAULT_TOKEN_FILE) -> dict[int, dict[str, str]]:
-    token = token_file.read_text(encoding="utf-8").strip()
-    client = GiteaClient(token=token)
-    snapshot: dict[int, dict[str, str]] = {}
-    for issue_number in sorted(DEFAULT_REFERENCE_SNAPSHOT):
-        issue = client.get_issue(issue_number)
-        snapshot[issue_number] = {
-            "title": issue["title"],
-            "state": issue["state"],
-        }
-    return snapshot
-
-
-def collect_repo_evidence(entries: list[dict[str, str]], repo_root: Path) -> tuple[list[str], list[str]]:
-    present: list[str] = []
-    missing: list[str] = []
-    for entry in entries:
-        label = f"`{entry['path']}` — {entry['description']}"
-        if (repo_root / entry["path"]).exists():
-            present.append(label)
-        else:
-            missing.append(label)
-    return present, missing
-
-
-
-def evaluate_reference(issue_number: int, snapshot: dict[int, dict[str, str]], expected_keywords: list[str]) -> dict[str, Any]:
-    record = snapshot.get(issue_number, {"title": "missing from snapshot", "state": "unknown"})
-    title = record["title"]
-    title_lower = title.lower()
-    matched_keywords = [kw for kw in expected_keywords if kw.lower() in title_lower]
-    aligned = bool(matched_keywords) if expected_keywords else True
-    return {
-        "number": issue_number,
-        "title": title,
-        "state": record["state"],
-        "aligned": aligned,
-        "matched_keywords": matched_keywords,
-    }
-
-
-
-def classify_workstream(reference_results: list[dict[str, Any]], evidence_present: list[str], missing_deliverables: list[str]) -> str:
-    has_drift = any(not item["aligned"] for item in reference_results)
-    if not evidence_present:
-        return "MISSING"
-    if has_drift or missing_deliverables:
-        return "PARTIAL"
-    return "GROUNDED"
-
-
-
-def evaluate_directive(snapshot: dict[int, dict[str, str]] | None = None, repo_root: Path | None = None) -> dict[str, Any]:
-    snapshot = snapshot or default_snapshot()
-    repo_root = repo_root or DEFAULT_REPO_ROOT
-    workstreams: list[dict[str, Any]] = []
-    drift_items: list[str] = []
-
-    for lane in WORKSTREAMS:
-        reference_results = [
-            evaluate_reference(issue_number, snapshot, lane["expected_keywords"])
-            for issue_number in lane["references"]
-        ]
-        present, missing = collect_repo_evidence(lane["repo_evidence"], repo_root)
-        for item in reference_results:
-            if not item["aligned"]:
-                drift_items.append(
-                    f"#{item['number']} is cited for {lane['name']}, but its current title is '{item['title']}'."
-                )
-        workstream = {
-            "key": lane["key"],
-            "name": lane["name"],
-            "requirement": lane["requirement"],
-            "reference_results": reference_results,
-            "repo_evidence_present": present,
-            "repo_evidence_missing": missing,
-            "missing_deliverables": list(lane["missing_deliverables"]),
-            "why_open": lane["why_open"],
-        }
-        workstream["status"] = classify_workstream(
-            reference_results=reference_results,
-            evidence_present=present,
-            missing_deliverables=workstream["missing_deliverables"],
-        )
-        workstreams.append(workstream)
-
-    next_actions: list[str] = []
-    for workstream in workstreams:
-        if workstream["missing_deliverables"]:
-            next_actions.append(f"{workstream['name']}: {workstream['missing_deliverables'][0]}")
-
-    return {
-        "issue_number": 524,
-        "title": DIRECTIVE_TITLE,
-        "summary": DIRECTIVE_SUMMARY,
-        "reference_snapshot": {str(k): v for k, v in sorted(snapshot.items())},
-        "workstreams": workstreams,
-        "reference_drift": drift_items,
-        "grounded_workstreams": sum(1 for item in workstreams if item["status"] == "GROUNDED"),
-        "partial_workstreams": sum(1 for item in workstreams if item["status"] == "PARTIAL"),
-        "missing_workstreams": sum(1 for item in workstreams if item["status"] == "MISSING"),
-        "next_actions": next_actions,
-    }
-
-
-
-def render_markdown(result: dict[str, Any]) -> str:
-    lines = [
-        f"# {result['title']}",
-        "",
-        "Grounding report for `timmy-home #524`.",
-        "",
-        result["summary"],
-        "",
-        "This remains a `Refs #524` artifact. The directive spans multiple repos and operator actions, so this report makes the current repo-side state executable without pretending the whole migration is complete.",
-        "",
-        "## Directive Snapshot",
-        "",
-        f"- Repo-grounded workstreams: {result['grounded_workstreams']}",
-        f"- Partial workstreams: {result['partial_workstreams']}",
-        f"- Missing workstreams: {result['missing_workstreams']}",
-        f"- Drifted references: {len(result['reference_drift'])}",
-        "",
-        "## Reference Drift",
-        "",
-    ]
-    if result["reference_drift"]:
-        lines.extend(f"- {item}" for item in result["reference_drift"])
-    else:
-        lines.append("- No stale cross-links detected in the directive snapshot.")
-
-    lines.extend(["", "## Workstream Matrix", ""])
-    for index, workstream in enumerate(result["workstreams"], start=1):
-        lines.extend(
-            [
-                f"### {index}. {workstream['name']} — {workstream['status']}",
-                "",
-                f"- Requirement: {workstream['requirement']}",
-            ]
-        )
-        if workstream["reference_results"]:
-            lines.append("- Referenced issues:")
-            for ref in workstream["reference_results"]:
-                alignment = "aligned" if ref["aligned"] else "DRIFT"
-                lines.append(
-                    f"  - #{ref['number']} ({ref['state']}) — {ref['title']} [{alignment}]"
-                )
-        else:
-            lines.append("- Referenced issues: none listed in the directive body")
-
-        if workstream["repo_evidence_present"]:
-            lines.append("- Repo evidence present:")
-            lines.extend(f"  - {item}" for item in workstream["repo_evidence_present"])
-        else:
-            lines.append("- Repo evidence present: none")
-
-        if workstream["repo_evidence_missing"]:
-            lines.append("- Repo evidence expected but missing:")
-            lines.extend(f"  - {item}" for item in workstream["repo_evidence_missing"])
-
-        if workstream["missing_deliverables"]:
-            lines.append("- Missing operator deliverables:")
-            lines.extend(f"  - {item}" for item in workstream["missing_deliverables"])
-        else:
-            lines.append("- Missing operator deliverables: none")
-
-        lines.append(f"- Why this lane remains open: {workstream['why_open']}")
-        lines.append("")
-
-    lines.extend(["## Highest-Leverage Next Actions", ""])
-    lines.extend(f"- {item}" for item in result["next_actions"])
-
-    lines.extend(
-        [
-            "",
-            "## Why #524 Remains Open",
-            "",
-            "- The directive bundles five separate workstreams with different evidence surfaces.",
-            "- Multiple cited issue numbers have drifted away from the work they are supposed to anchor.",
-            "- Repo scaffolding exists for Nostr, sovereignty audits, and Morrowind, but the operator-facing bundles are still missing.",
-            "- Syntax Guard verification is still undocumented and unproven inside this repo.",
-        ]
-    )
-
-    return "\n".join(lines).rstrip() + "\n"
-
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Render the unified fleet sovereignty status report for issue #524")
-    parser.add_argument("--snapshot", help="Optional JSON snapshot file overriding the default issue-title/state snapshot")
-    parser.add_argument("--live", action="store_true", help="Refresh the issue snapshot from Gitea before rendering")
-    parser.add_argument("--token-file", default=str(DEFAULT_TOKEN_FILE), help="Token file used with --live")
-    parser.add_argument("--output", help="Optional path to write the rendered report")
-    parser.add_argument("--json", action="store_true", help="Print computed JSON instead of markdown")
-    args = parser.parse_args()
-
-    if args.live:
-        snapshot = refresh_snapshot(Path(args.token_file).expanduser())
-    else:
-        snapshot = load_snapshot(Path(args.snapshot).expanduser() if args.snapshot else None)
-
-    result = evaluate_directive(snapshot=snapshot, repo_root=DEFAULT_REPO_ROOT)
-    rendered = json.dumps(result, indent=2) if args.json else render_markdown(result)
-
-    if args.output:
-        output_path = Path(args.output).expanduser()
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        output_path.write_text(rendered, encoding="utf-8")
-        print(f"Directive status written to {output_path}")
-    else:
-        print(rendered)
-
-
-if __name__ == "__main__":
-    main()

specs/fleet-operator-incentives.md

@@ -0,0 +1,130 @@
+# Fleet Operator Incentives & Partner Program
+
+> Implements Fleet Epic IV: Human Capital & Incentives (Issue #987)
+> Closes #1003
+
+## Overview
+
+This specification defines the incentive structures, certification pathways, and partner program mechanics for operating and maintaining Timmy Fleet nodes. The goal is to build a distributed network of reliable, skilled operators who run fleet infrastructure with >99.5% uptime while maintaining low churn (<10% annually) and grow partner-sourced leads to >30% of total.
+
+## Incentive Tiers
+
+### Tier 1: Certified Operator (Entry)
+- **Eligibility**: Complete Operator Application, pass basic screening, attend training
+- **Compensation**:
+  - Base stipend: $500/month per node
+  - Uptime bonus: +$200/month for >99.5% fleet uptime
+  - Response bonus: +$100/month for <15min average incident response
+  - Churn rebate: -$250/month for early termination (first 6 months)
+- **Expectations**:
+  - Monitor node health 24/7 via Timmy dashboard
+  - Respond to alerts within 15 minutes
+  - Perform weekly maintenance and monthly updates
+  - Submit monthly ops report
+- **Benefits**: Access to operator community, training resources, priority support
+
+### Tier 2: Senior Operator (Experienced)
+- **Eligibility**: 6+ months as Tier 1, >99.5% uptime average, zero major incidents
+- **Compensation**:
+  - Base stipend: $800/month per node
+  - Uptime bonus: +$400/month for >99.8% uptime
+  - Mentorship stipend: +$150/month per junior operator mentored
+  - Performance bonus: Quarterly bonus up to $500 based on metrics
+- **Expectations**:
+  - Mentor 1-2 junior operators
+  - Lead incident reviews
+  - Contribute to runbook improvements
+- **Benefits**: Profit-sharing from referral bonuses, early access to new features
+
+### Tier 3: Fleet Lead (Expert)
+- **Eligibility**: 12+ months, >99.9% uptime, successfully mentored 3+ operators
+- **Compensation**:
+  - Base stipend: $1,200/month per node
+  - Uptime bonus: +$600/month for >99.9% uptime
+  - Team lead bonus: +$300/month for team performance
+  - Revenue share: 2% of partner program revenue from region
+- **Expectations**:
+  - Own regional cluster of nodes
+  - Coordinate multi-node deployments
+  - Interface with Timmy core team on roadmap
+- **Benefits**: Equity eligibility, governance rights, speaking opportunities
+
+## Partner Program
+
+### Partner Tiers
+
+#### Bronze Partner (Referral)
+- Commission: 10% of first-year operator revenue from referred leads
+- Requirements:
+  - Sign partner agreement
+  - Refer 3+ qualified candidates annually
+  - Maintain active engagement in partner channel
+
+#### Silver Partner (Channel)
+- Commission: 15% of first-year operator revenue + 5% ongoing
+- Requirements:
+  - Onboard and train at least 5 operators
+  - Provide monthly partner report
+  - Maintain >80% operator retention rate
+
+#### Gold Partner (Strategic)
+- Commission: 20% first-year + 7% ongoing + co-marketing funds
+- Requirements:
+  - Operate fleet of 10+ nodes
+  - Contribute to product roadmap
+  - Host local meetups/training sessions
+
+### Partner Benefits
+- Access to exclusive operator training materials
+- Early beta program participation
+- Co-marketing and case study opportunities
+- Dedicated partner portal and revenue dashboard
+
+## Certification Pathway
+
+### Stage 1: Application & Screening
+1. Submit Operator Application (see `templates/operator-application.md`)
+2. Technical interview (30 min)
+3. Infrastructure audit (existing hardware/network)
+4. Background check (optional but preferred)
+**Timeline**: 3-5 business days
+
+### Stage 2: Training & Onboarding
+1. Complete Fleet Ops 101 module (2 hours self-paced)
+2. Shadow a senior operator (2 weeks)
+3. Deploy test node (sandbox environment)
+4. Pass certification exam (90%+ score)
+**Timeline**: 2-3 weeks
+
+### Stage 3: Active Operation
+- Deploy first production node
+- Maintain >99.5% uptime for first 30 days
+- Submit initial monthly ops report
+**Timeline**: 30 days probation
+
+### Certification Renewal
+- Quarterly review of metrics
+- Annual recertification exam
+- Continuous training requirement (4 hours/month)
+
+## Success Metrics (6-month targets)
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Active certified operators | 3-5 | Dashboard |
+| Operator churn | <10% annually | HR records |
+| Fleet uptime | >99.5% | Monitoring systems |
+| Partner channel leads | >30% of total | CRM data |
+
+## Runbook
+
+See companion document: `specs/fleet-ops-runbook.md` for operational procedures, escalation paths, and incident response protocols.
+
+## Templates
+
+- **Operator Application**: `templates/operator-application.md`
+- **Partner Report**: `templates/partner-report.md`
+
+## Revision History
+
+- 2025-05-02: Initial specification (implements #987, closes #1003)

specs/fleet-ops-runbook.md

@@ -0,0 +1,291 @@
+# Fleet Operations Runbook
+
+> Fleet Operator Incentives & Partner Program — Operational Procedures
+> Implements #987 | Closes #1003
+
+## Table of Contents
+
+1. [Daily Ops Checklist](#daily-ops-checklist)
+2. [Weekly Maintenance](#weekly-maintenance)
+3. [Monthly Responsibilities](#monthly-responsibilities)
+4. [Incident Response](#incident-response)
+5. [Escalation Paths](#escalation-paths)
+6. [Communication Protocols](#communication-protocols)
+7. [Node Deployment](#node-deployment)
+8. [Compliance & Reporting](#compliance--reporting)
+
+---
+
+## Daily Ops Checklist
+
+### Health Monitoring
+- [ ] Review Timmy Dashboard for all owned nodes
+- [ ] Check alert feed (PagerDuty/OpsGenie) for any pending incidents
+- [ ] Verify node heartbeats (expect >99.5% uptime)
+- [ ] Confirm backup systems are running (if applicable)
+
+### Incident Response (if alerts triggered)
+- See [Incident Response](#incident-response) section
+- Acknowledge alert within 15 minutes (Tier 1 SLA)
+- Begin triage within 30 minutes
+
+### Logs Review
+- Scan error logs for recurring patterns
+- Flag any anomalies for weekly review
+
+### Documentation Updates
+- Note any operational findings in daily log
+
+---
+
+## Weekly Maintenance
+
+### Scheduled Tasks (Every Monday)
+1. **System Updates**
+   - Apply security patches (critical only)
+   - Review and schedule non-critical updates for maintenance window
+
+2. **Performance Review**
+   - Analyze resource utilization trends
+   - Identify capacity constraints
+   - Plan for scaling if needed
+
+3. **Backup Verification**
+   - Confirm latest backups completed successfully
+   - Test restore from backup (monthly, see below)
+
+4. **Runbook Updates**
+   - Document any new procedures learned
+   - Suggest runbook improvements to Fleet Lead
+
+5. **Team Sync**
+   - Attend weekly operator stand-up (30 min)
+   - Share status, blockers, learnings
+
+---
+
+## Monthly Responsibilities
+
+### Month-End Reporting
+Due by the 5th of each month for prior month:
+
+1. **Ops Report** (use `templates/partner-report.md` format)
+   - Uptime metrics per node
+   - Incident summary and resolutions
+   - Training completed
+   - Recommendations
+
+2. **Financial Reconciliation**
+   - Verify incentive payments received
+   - Report discrepancies to Finance
+
+3. **Compliance Audit**
+   - Confirm certification requirements met
+   - Document any deviations and corrective actions
+
+### Deep Maintenance
+- Full system backup and restore test
+- Security audit review
+- Hardware inspection (if physical nodes)
+- Training module completion (minimum 4 hours/month)
+
+---
+
+## Incident Response
+
+### Severity Definitions
+
+| Severity | Definition | Response Time | Resolution Target |
+|----------|------------|---------------|-------------------|
+| P0 | Fleet-wide outage, no nodes operational | 15 minutes | 4 hours |
+| P1 | Region/node cluster outage, >50% down | 30 minutes | 8 hours |
+| P2 | Single node failure | 1 hour | 24 hours |
+| P3 | Degraded performance, not critical | 4 hours | 3 days |
+
+### Response Procedure
+
+#### P0/P1 Incidents
+1. Acknowledge alert immediately
+2. Declare incident in `#fleet-incidents` Slack channel
+3. Notify Fleet Lead (direct message/call)
+4. Execute recovery procedures from relevant playbook
+5. Document timeline and actions taken
+6. Schedule post-mortem within 48 hours
+
+#### P2 Incidents
+1. Acknowledge within 1 hour
+2. Open incident ticket in tracking system
+3. Follow single-node recovery playbook
+4. Report resolution in daily ops log
+
+#### P3 Incidents
+1. Log in issue tracker
+2. Schedule during next maintenance window
+3. Document resolution upon completion
+
+### Recovery Playbooks
+
+#### Node Restart (most common P2)
+1. SSH to node (or use remote management)
+2. Check system logs (`/var/log/timmy/fleet.log`)
+3. Restart service: `sudo systemctl restart timmy-fleet`
+4. Verify node rejoins cluster
+5. Monitor for 30 minutes post-recovery
+
+#### Network Partition
+1. Verify network connectivity (ping, traceroute)
+2. Check firewall rules
+3. Contact network provider if external
+4. Switch to backup connection if available
+5. Document root cause
+
+#### Storage Full
+1. Identify large directories (`du -sh /* | sort -hr`)
+2. Rotate logs: `sudo logrotate -f /etc/logrotate.d/timmy`
+3. Clean temporary files
+4. Expand storage or add new volume
+5. Alert Fleet Lead for capacity planning
+
+---
+
+## Escalation Paths
+
+### Tiered Support Model
+
+```
+Operator (Tier 1)
+    ↓ (15 min SLA)
+Senior Operator / Fleet Lead (Tier 2)
+    ↓ (1 hour SLA)
+Timmy Core Team (Tier 3)
+    ↓ (Immediate)
+Executive Sponsor (Critical only)
+```
+
+### Contact Matrix
+
+| Issue Type | Primary Contact | Secondary |
+|------------|----------------|-----------|
+| Technical incident | Fleet Lead | Timmy Core |
+| Payment/incentive | Finance Partner | Fleet Lead |
+| Training/certification | Training Coordinator | Fleet Lead |
+| Partnership inquiry | Partner Manager | Executive Sponsor |
+| Security incident | Security Team | Timmy Core (immediate) |
+
+### Emergency Contacts
+- Fleet Lead: `fleet-lead@timmy.foundation` (Slack: @fleet-lead)
+- Timmy Core On-Call: `oncall@timmy.foundation` (PagerDuty)
+- Security: `security@timmy.foundation`
+- Finance: `finance@timmy.foundation`
+
+---
+
+## Communication Protocols
+
+### Channels
+- `#fleet-operators` — Daily ops, questions
+- `#fleet-incidents` — Active incidents only
+- `#fleet-training` — Training resources, scheduling
+- `#fleet-partners` — Partner program discussions
+
+### Status Updates
+- Daily: Stand-up notes in thread
+- Weekly: Summary post in `#fleet-operators`
+- Monthly: Ops report submission
+- Incident: Real-time updates in `#fleet-incidents`
+
+### Documentation Standards
+- Use clear, concise language
+- Include timestamps in UTC
+- Link to relevant tickets/PRs
+- Tag stakeholders with `@`
+
+---
+
+## Node Deployment
+
+### Pre-Deployment Checklist
+- [ ] Hardware meets minimum specs (CPU, RAM, storage)
+- [ ] Network connectivity validated
+- [ ] Firewall rules configured
+- [ ] SSH keys exchanged with Timmy core team
+- [ ] Monitoring agent installed
+- [ ] Backup solution active
+- [ ] Documentation updated with node details
+
+### Deployment Steps
+1. Provision hardware/VM
+2. Install Timmy Fleet software
+3. Configure node ID and credentials
+4. Join cluster via `timmy-fleet join <cluster-endpoint>`
+5. Validate connectivity and heartbeat
+6. Update inventory spreadsheet
+7. Set up monitoring alerts
+8. Complete handover to operator
+
+### Decommissioning
+1. Drain node from cluster
+2. Migrate workloads
+3. Backup final state
+4. Shut down cleanly
+5. Update inventory
+6. Notify relevant teams
+
+---
+
+## Compliance & Reporting
+
+### Metrics to Track
+- Uptime (node-level and fleet-wide)
+- Incident count and severity
+- Response and resolution times
+- Training hours completed
+- Payment/compensation accuracy
+
+### Reporting Cadence
+- **Daily**: Ops dashboard (automated)
+- **Weekly**: Status summary (operator)
+- **Monthly**: Partner report (template-driven)
+- **Quarterly**: Performance review with Fleet Lead
+
+### Audits
+- Quarterly internal audit by Timmy compliance team
+- Annual external certification renewal
+- Ad-hoc security reviews as needed
+
+---
+
+## Appendix: Resources
+
+### Useful Commands
+```bash
+# Check service status
+sudo systemctl status timmy-fleet
+
+# View logs
+journalctl -u timmy-fleet -f
+
+# Restart node
+sudo systemctl restart timmy-fleet
+
+# Check node health
+timmy-fleet health
+
+# Join cluster
+timmy-fleet join <cluster-endpoint>
+```
+
+### Key Files
+- Config: `/etc/timmy/fleet/config.yaml`
+- Logs: `/var/log/timmy/fleet.log`
+- Health data: `/var/lib/timmy/fleet/health.json`
+
+### Support Resources
+- Internal Wiki: `https://wiki.timmy.foundation/fleet`
+- Operator Portal: `https://fleet.timmy.foundation`
+- Training Videos: `https://learn.timmy.foundation/fleet-ops`
+
+---
+
+**Last Updated**: 2025-05-02
+**Next Review**: 2025-06-02

specs/templates/operator-application.md

@@ -0,0 +1,143 @@
+# Fleet Operator Application
+
+> {{APPLICATION_DATE}}
+> Candidate: {{CANDIDATE_NAME}}
+
+## Contact Information
+
+**Full Name**: {{CANDIDATE_FULL_NAME}}
+**Email**: {{CANDIDATE_EMAIL}}
+**Phone**: {{CANDIDATE_PHONE}}
+**Location**: {{CANDIDATE_LOCATION}}
+**Time Zone**: {{CANDIDATE_TIMEZONE}}
+
+### Availability
+- **Hours per week**: {{AVAILABILITY_HOURS}}
+- **Primary availability window (UTC)**: {{AVAILABILITY_WINDOW}}
+- **On-call flexibility**: {{ONCALL_FLEXIBILITY}}
+
+## Technical Qualifications
+
+### Experience
+```
+Years in IT/DevOps: {{YEARS_EXPERIENCE}}
+Relevant roles:
+{{ROLE_HISTORY}}
+```
+
+### Skills (check all that apply)
+- [ ] Linux system administration
+- [ ] Container orchestration (Kubernetes/Docker)
+- [ ] Cloud infrastructure (AWS/GCP/Azure)
+- [ ] Networking fundamentals
+- [ ] Monitoring & alerting (Prometheus/Grafana)
+- [ ] Incident response/ITIL
+- [ ] Security best practices
+- [ ] Automation (Ansible/Terraform)
+- [ ] Scripting (Python/Bash/Go)
+- [ ] Timmy platform experience
+
+**Additional skills**: {{ADDITIONAL_SKILLS}}
+
+### Certifications
+{{CERTIFICATIONS}}
+
+## Infrastructure Readiness
+
+### Proposed Node Environment
+- **Type**: ☐ Physical ☐ Cloud VM ☐ Hybrid
+- **Provider**: {{CLOUD_PROVIDER}}
+- **Region**: {{REGION}}
+- **Hardware specs**:
+  - CPU: {{CPU_SPEC}}
+  - RAM: {{RAM_SPEC}}
+  - Storage: {{STORAGE_SPEC}}
+  - Network: {{NETWORK_SPEC}}
+
+### Redundancy & HA
+- [ ] Backup power (UPS/generator)
+- [ ] Secondary internet connection
+- [ ] Off-site backup solution
+- [ ] Remote management (IPMI/iDRAC)
+
+### Connectivity
+- **Bandwidth**: {{BANDWIDTH}} Mbps
+- **Latency to Timmy core**: {{LATENCY}} ms
+- **Uptime SLA**: {{UPTIME_SLA}}
+
+---
+
+## Motivation & Alignment
+
+### Why do you want to run a Timmy Fleet node?
+{{MOTIVATION}}
+
+### What attracts you to decentralized infrastructure?
+{{DECENTRALIZATION_MOTIVATION}}
+
+### How does this align with your long-term goals?
+{{LONG_TERM_GOALS}}
+
+---
+
+## Partner Program Interest (Optional)
+
+### Interested in?
+- [ ] Referral partner (refer operators, earn commission)
+- [ ] Channel partner (onboard and train operators)
+- [ ] Strategic partner (run fleet of 10+ nodes)
+
+### Existing network
+{{PARTNER_NETWORK}}
+
+### Referral pipeline
+{{REFERRAL_PIPELINE}}
+
+---
+
+## References
+
+### Professional References
+1. Name: {{REF1_NAME}}  
+   Email: {{REF1_EMAIL}}  
+   Relationship: {{REF1_RELATION}}
+
+2. Name: {{REF2_NAME}}  
+   Email: {{REF2_EMAIL}}  
+   Relationship: {{REF2_RELATION}}
+
+### Timmy Community Involvement
+{{COMMUNITY_INVOLVEMENT}}
+
+---
+
+## Agreement & Signatures
+
+### Code of Conduct
+- [ ] I have read and agree to the Timmy Fleet Operator Code of Conduct
+- [ ] I understand the uptime and response time requirements
+- [ ] I agree to the incentive structure and terms
+
+### Signature
+**Candidate signature**: ___________________________
+**Date**: {{SIGNATURE_DATE}}
+
+**Timmy representative**: ___________________________
+**Date**: {{TIMPY_SIGN_DATE}}
+
+---
+
+## Internal Use Only
+
+**Interviewer**: {{INTERVIEWER}}
+**Technical score**: {{TECH_SCORE}}/100
+**Culture fit**: {{CULTURE_FIT}}/50
+**Infrastructure audit**: ☐ Pass ☐ Fail
+**Background check**: ☐ Complete ☐ In-progress
+
+**Decision**: ☐ Approved ☐ Rejected ☐ Waitlist
+
+**Comments**: {{INTERNAL_COMMENTS}}
+
+**Certification ID**: {{CERT_ID}}
+**Onboarding start date**: {{ONBOARDING_DATE}}

specs/templates/partner-report.md

@@ -0,0 +1,175 @@
+# Fleet Partner Monthly Report
+
+> {{REPORT_MONTH}} {{REPORT_YEAR}}
+> Partner: {{PARTNER_NAME}} ({{PARTNER_TIER}})
+> Submitted: {{SUBMISSION_DATE}}
+
+## Executive Summary
+
+| Metric | Current Month | Target | Variance |
+|--------|---------------|--------|----------|
+| Active nodes managed | {{ACTIVE_NODES}} | {{TARGET_NODES}} | {{NODES_VARIANCE}} |
+| Fleet uptime | {{UPTIME}}% | 99.5% | {{UPTIME_VARIANCE}}% |
+| Operator churn rate | {{CHURN_RATE}}% | <10% | {{CHURN_VARIANCE}}% |
+| Partner-sourced leads | {{LEADS_COUNT}} | {{LEADS_TARGET}} | {{LEADS_VARIANCE}} |
+| Revenue share earned | {{REVENUE}} | — | — |
+
+**Key highlights**:
+{{KEY_HIGHLIGHTS}}
+
+**Top concerns**:
+{{KEY_CONCERNS}}
+
+---
+
+## Node Performance
+
+### Node Inventory
+
+| Node ID | Location | Status | Uptime (30d) | Revenue Share | Issues |
+|---------|----------|--------|--------------|---------------|---------|
+| {{NODE_1_ID}} | {{NODE_1_LOC}} | {{NODE_1_STATUS}} | {{NODE_1_UPTIME}}% | ${{NODE_1_REV}} | {{NODE_1_ISSUES}} |
+| {{NODE_2_ID}} | {{NODE_2_LOC}} | {{NODE_2_STATUS}} | {{NODE_2_UPTIME}}% | ${{NODE_2_REV}} | {{NODE_2_ISSUES}} |
+| {{NODE_3_ID}} | {{NODE_3_LOC}} | {{NODE_3_STATUS}} | {{NODE_3_UPTIME}}% | ${{NODE_3_REV}} | {{NODE_3_ISSUES}} |
+
+*Add rows as needed*
+
+### Top Node Performers
+1. **{{TOP_NODE_1_ID}}**: {{TOP_NODE_1_UPTIME}}% uptime, zero incidents
+2. **{{TOP_NODE_2_ID}}**: {{TOP_NODE_2_UPTIME}}% uptime, quickest response times
+
+### Nodes Requiring Attention
+1. **{{ATTN_NODE_1_ID}}**: {{ATTN_NODE_1_ISSUE}}
+2. **{{ATTN_NODE_2_ID}}**: {{ATTN_NODE_2_ISSUE}}
+
+---
+
+## Incidents & Resolutions
+
+### Incident Log
+
+| Date | Severity | Node(s) | Duration | Root Cause | Resolution |
+|------|----------|---------|----------|------------|------------|
+| {{INC1_DATE}} | {{INC1_SEV}} | {{INC1_NODES}} | {{INC1_DURATION}} | {{INC1_CAUSE}} | {{INC1_RES}} |
+| {{INC2_DATE}} | {{INC2_SEV}} | {{INC2_NODES}} | {{INC2_DURATION}} | {{INC2_CAUSE}} | {{INC2_RES}} |
+| {{INC3_DATE}} | {{INC3_SEV}} | {{INC3_NODES}} | {{INC3_DURATION}} | {{INC3_CAUSE}} | {{INC3_RES}} |
+
+*Add rows as needed*
+
+### Mean Time to Recovery (MTTR)
+- **P0 incidents**: {{MTTR_P0}} hours
+- **P1 incidents**: {{MTTR_P1}} hours
+- **P2 incidents**: {{MTTR_P2}} hours
+- **P3 incidents**: {{MTTR_P3}} hours
+
+**Improvement opportunities**:
+{{MTTR_IMPROVEMENTS}}
+
+---
+
+## Operator Management
+
+### Active Operators
+
+| Operator | Tier | Nodes Managed | Status | Cert Date |
+|----------|------|---------------|--------|-----------|
+| {{OP1_NAME}} | {{OP1_TIER}} | {{OP1_NODES}} | {{OP1_STATUS}} | {{OP1_CERT}} |
+| {{OP2_NAME}} | {{OP2_TIER}} | {{OP2_NODES}} | {{OP2_STATUS}} | {{OP2_CERT}} |
+
+### Churn / Attrition
+- **Departed operators**: {{DEPARTED_COUNT}}
+- **Departure reasons**: {{DEPARTURE_REASONS}}
+- **Retention initiatives**: {{RETENTION_INITIATIVES}}
+
+### Training & Certification
+- **New certifications**: {{NEW_CERTS}}
+- **Training hours logged**: {{TRAINING_HOURS}}
+- **Upcoming recertifications**: {{UPCOMING_RECERTS}}
+
+---
+
+## Partner Program Metrics
+
+### Lead Generation
+- **Total leads received**: {{TOTAL_LEADS}}
+- **Qualified leads**: {{QUALIFIED_LEADS}}
+- **Converted to operators**: {{CONVERTED_OPERATORS}}
+- **Conversion rate**: {{CONVERSION_RATE}}%
+- **Partner contribution to total pipeline**: {{PARTNER_PIPELINE_PERCENT}}%
+
+### Referral Commission
+- **Referral fee earned**: ${{REFERRAL_FEE}}
+- **Ongoing revenue share**: ${{ONGOING_SHARE}}
+- **Total YTD earnings**: ${{YTD_EARNINGS}}
+
+### Partner Activity
+- **Marketing events hosted**: {{EVENTS_HOSTED}}
+- **Training sessions conducted**: {{TRAINING_SESSIONS}}
+- **Community engagement posts**: {{COMMUNITY_POSTS}}
+- **Collateral created**: {{COLLATERAL}}
+
+---
+
+## Financial Summary
+
+### Incentive Payouts
+| Category | Amount | Notes |
+|----------|--------|-------|
+| Operator stipends | ${{STIPENDS}} | {{STIPENDS_NOTES}} |
+| Uptime bonuses | ${{UPTIME_BONUS}} | {{UPTIME_NOTES}} |
+| Mentorship bonuses | ${{MENTOR_BONUS}} | {{MENTOR_NOTES}} |
+| Performance bonuses | ${{PERF_BONUS}} | {{PERF_NOTES}} |
+| Partner commissions | ${{PARTNER_COMM}} | {{PARTNER_NOTES}} |
+
+**Total payout this month**: ${{TOTAL_PAYOUT}}
+
+### Cost Efficiency
+- **Cost per node**: ${{COST_PER_NODE}}
+- **Cost per uptime hour**: ${{COST_PER_UPTIME_HOUR}}
+- **Efficiency rating**: {{EFFICIENCY_RATING}}/10
+
+---
+
+## Goals & Objectives
+
+### Next Month Targets
+1. **Uptime**: {{NEXT_UPTIME_TARGET}}%
+2. **Qualified leads**: {{NEXT_LEADS_TARGET}}
+3. **New operators**: {{NEXT_OPS_TARGET}}
+4. **Incident reduction**: {{NEXT_INCIDENT_TARGET}} incidents
+
+### Priority Initiatives
+- {{PRIORITY_1}}
+- {{PRIORITY_2}}
+- {{PRIORITY_3}}
+
+### Support Needed
+- {{SUPPORT_NEEDED_1}}
+- {{SUPPORT_NEEDED_2}}
+
+---
+
+## Attestation
+
+By submitting this report, I certify that the information provided is accurate and complete to the best of my knowledge.
+
+**Submitted by**: {{SUBMITTER_NAME}}
+**Title**: {{SUBMITTER_TITLE}}
+**Signature**: ___________________________
+**Date**: {{SUBMISSION_DATE}}
+
+**Approved by** (Timmy Core): {{APPROVER_NAME}}
+**Date**: {{APPROVAL_DATE}}
+
+---
+
+## Appendix
+
+### Supporting Documents
+- [ ] Ops dashboard screenshots attached
+- [ ] Incident post-mortems attached
+- [ ] Training completion records attached
+- [ ] Financial reconciliation attached
+
+### Notes
+{{APPENDIX_NOTES}}

src/timmy/__init__.py

@@ -1 +1,12 @@
 # Timmy core module
+
+from .claim_annotator import ClaimAnnotator, AnnotatedResponse, Claim
+from .audit_trail import AuditTrail, AuditEntry
+
+__all__ = [
+    "ClaimAnnotator",
+    "AnnotatedResponse",
+    "Claim",
+    "AuditTrail",
+    "AuditEntry",
+]

src/timmy/claim_annotator.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+Response Claim Annotator — Source Distinction System
+SOUL.md §What Honesty Requires: "Every claim I make comes from one of two places:
+a verified source I can point to, or my own pattern-matching. My user must be
+able to tell which is which."
+"""
+
+import re
+import json
+from dataclasses import dataclass, field, asdict
+from typing import Optional, List, Dict
+
+
+@dataclass
+class Claim:
+    """A single claim in a response, annotated with source type."""
+    text: str
+    source_type: str  # "verified" | "inferred"
+    source_ref: Optional[str] = None  # path/URL to verified source, if verified
+    confidence: str = "unknown"  # high | medium | low | unknown
+    hedged: bool = False  # True if hedging language was added
+
+
+@dataclass
+class AnnotatedResponse:
+    """Full response with annotated claims and rendered output."""
+    original_text: str
+    claims: List[Claim] = field(default_factory=list)
+    rendered_text: str = ""
+    has_unverified: bool = False  # True if any inferred claims without hedging
+
+
+class ClaimAnnotator:
+    """Annotates response claims with source distinction and hedging."""
+
+    # Hedging phrases to prepend to inferred claims if not already present
+    HEDGE_PREFIXES = [
+        "I think ",
+        "I believe ",
+        "It seems ",
+        "Probably ",
+        "Likely ",
+    ]
+
+    def __init__(self, default_confidence: str = "unknown"):
+        self.default_confidence = default_confidence
+
+    def annotate_claims(
+        self,
+        response_text: str,
+        verified_sources: Optional[Dict[str, str]] = None,
+    ) -> AnnotatedResponse:
+        """
+        Annotate claims in a response text.
+
+        Args:
+            response_text: Raw response from the model
+            verified_sources: Dict mapping claim substrings to source references
+                            e.g. {"Paris is the capital of France": "https://en.wikipedia.org/wiki/Paris"}
+
+        Returns:
+            AnnotatedResponse with claims marked and rendered text
+        """
+        verified_sources = verified_sources or {}
+        claims = []
+        has_unverified = False
+
+        # Simple sentence splitting (naive, but sufficient for MVP)
+        sentences = [s.strip() for s in re.split(r'[.!?]\s+', response_text) if s.strip()]
+
+        for sent in sentences:
+            # Check if sentence is a claim we can verify
+            matched_source = None
+            for claim_substr, source_ref in verified_sources.items():
+                if claim_substr.lower() in sent.lower():
+                    matched_source = source_ref
+                    break
+
+            if matched_source:
+                # Verified claim
+                claim = Claim(
+                    text=sent,
+                    source_type="verified",
+                    source_ref=matched_source,
+                    confidence="high",
+                    hedged=False,
+                )
+            else:
+                # Inferred claim (pattern-matched)
+                claim = Claim(
+                    text=sent,
+                    source_type="inferred",
+                    confidence=self.default_confidence,
+                    hedged=self._has_hedge(sent),
+                )
+                if not claim.hedged:
+                    has_unverified = True
+
+            claims.append(claim)
+
+        # Render the annotated response
+        rendered = self._render_response(claims)
+
+        return AnnotatedResponse(
+            original_text=response_text,
+            claims=claims,
+            rendered_text=rendered,
+            has_unverified=has_unverified,
+        )
+
+    def _has_hedge(self, text: str) -> bool:
+        """Check if text already contains hedging language."""
+        text_lower = text.lower()
+        for prefix in self.HEDGE_PREFIXES:
+            if text_lower.startswith(prefix.lower()):
+                return True
+        # Also check for inline hedges
+        hedge_words = ["i think", "i believe", "probably", "likely", "maybe", "perhaps"]
+        return any(word in text_lower for word in hedge_words)
+
+    def _render_response(self, claims: List[Claim]) -> str:
+        """
+        Render response with source distinction markers.
+
+        Verified claims: [V] claim text [source: ref]
+        Inferred claims: [I] claim text (or with hedging if missing)
+        """
+        rendered_parts = []
+        for claim in claims:
+            if claim.source_type == "verified":
+                part = f"[V] {claim.text}"
+                if claim.source_ref:
+                    part += f" [source: {claim.source_ref}]"
+            else:  # inferred
+                if not claim.hedged:
+                    # Add hedging if missing
+                    hedged_text = f"I think {claim.text[0].lower()}{claim.text[1:]}" if claim.text else claim.text
+                    part = f"[I] {hedged_text}"
+                else:
+                    part = f"[I] {claim.text}"
+            rendered_parts.append(part)
+        return " ".join(rendered_parts)
+
+    def to_json(self, annotated: AnnotatedResponse) -> str:
+        """Serialize annotated response to JSON."""
+        return json.dumps(
+            {
+                "original_text": annotated.original_text,
+                "rendered_text": annotated.rendered_text,
+                "has_unverified": annotated.has_unverified,
+                "claims": [asdict(c) for c in annotated.claims],
+            },
+            indent=2,
+            ensure_ascii=False,
+        )

tests/test_unified_fleet_sovereignty_status.py

@@ -1,77 +0,0 @@
-from __future__ import annotations
-
-import importlib.util
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[1]
-SCRIPT_PATH = ROOT / "scripts" / "unified_fleet_sovereignty_status.py"
-DOC_PATH = ROOT / "docs" / "UNIFIED_FLEET_SOVEREIGNTY_STATUS.md"
-
-
-def _load_module(path: Path, name: str):
-    assert path.exists(), f"missing {path.relative_to(ROOT)}"
-    spec = importlib.util.spec_from_file_location(name, path)
-    assert spec and spec.loader
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def _workstream(result: dict, key: str) -> dict:
-    for workstream in result["workstreams"]:
-        if workstream["key"] == key:
-            return workstream
-    raise AssertionError(f"missing workstream {key}")
-
-
-def test_evaluate_directive_flags_reference_drift_without_faking_completion() -> None:
-    mod = _load_module(SCRIPT_PATH, "unified_fleet_sovereignty_status")
-    result = mod.evaluate_directive(snapshot=mod.default_snapshot(), repo_root=ROOT)
-
-    assert len(result["reference_drift"]) == 4
-    assert any("#813" in item for item in result["reference_drift"])
-    assert any("#103" in item for item in result["reference_drift"])
-
-    nostr = _workstream(result, "nostr-migration")
-    assert nostr["status"] == "PARTIAL"
-    assert any("timmy_client.py" in item for item in nostr["repo_evidence_present"])
-
-    lexicon = _workstream(result, "lexicon-enforcement")
-    assert all(item["aligned"] for item in lexicon["reference_results"])
-    assert lexicon["status"] == "PARTIAL"
-
-    syntax_guard = _workstream(result, "syntax-guard")
-    assert syntax_guard["status"] == "MISSING"
-    assert any("deployment verifier" in item for item in syntax_guard["missing_deliverables"])
-
-
-def test_render_markdown_includes_required_sections_and_grounding_evidence() -> None:
-    mod = _load_module(SCRIPT_PATH, "unified_fleet_sovereignty_status")
-    result = mod.evaluate_directive(snapshot=mod.default_snapshot(), repo_root=ROOT)
-    report = mod.render_markdown(result)
-
-    for snippet in (
-        "# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration",
-        "## Directive Snapshot",
-        "## Reference Drift",
-        "## Workstream Matrix",
-        "### 5. Infrastructure Hardening / Syntax Guard — MISSING",
-        "`infrastructure/timmy-bridge/client/timmy_client.py`",
-        "machine-checkable lexicon policy for review/triage",
-        "## Why #524 Remains Open",
-    ):
-        assert snippet in report
-
-
-def test_repo_contains_committed_issue_524_grounding_doc() -> None:
-    assert DOC_PATH.exists(), "missing committed directive grounding doc"
-    text = DOC_PATH.read_text(encoding="utf-8")
-    for snippet in (
-        "# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration",
-        "## Reference Drift",
-        "## Workstream Matrix",
-        "## Highest-Leverage Next Actions",
-        "## Why #524 Remains Open",
-    ):
-        assert snippet in text

tests/timmy/test_claim_annotator.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Tests for claim_annotator.py — verifies source distinction is present."""
+
+import sys
+import os
+import json
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from timmy.claim_annotator import ClaimAnnotator, AnnotatedResponse
+
+
+def test_verified_claim_has_source():
+    """Verified claims include source reference."""
+    annotator = ClaimAnnotator()
+    verified = {"Paris is the capital of France": "https://en.wikipedia.org/wiki/Paris"}
+    response = "Paris is the capital of France. It is a beautiful city."
+
+    result = annotator.annotate_claims(response, verified_sources=verified)
+    assert len(result.claims) > 0
+    verified_claims = [c for c in result.claims if c.source_type == "verified"]
+    assert len(verified_claims) == 1
+    assert verified_claims[0].source_ref == "https://en.wikipedia.org/wiki/Paris"
+    assert "[V]" in result.rendered_text
+    assert "[source:" in result.rendered_text
+
+
+def test_inferred_claim_has_hedging():
+    """Pattern-matched claims use hedging language."""
+    annotator = ClaimAnnotator()
+    response = "The weather is nice today. It might rain tomorrow."
+
+    result = annotator.annotate_claims(response)
+    inferred_claims = [c for c in result.claims if c.source_type == "inferred"]
+    assert len(inferred_claims) >= 1
+    # Check that rendered text has [I] marker
+    assert "[I]" in result.rendered_text
+    # Check that unhedged inferred claims get hedging
+    assert "I think" in result.rendered_text or "I believe" in result.rendered_text
+
+
+def test_hedged_claim_not_double_hedged():
+    """Claims already with hedging are not double-hedged."""
+    annotator = ClaimAnnotator()
+    response = "I think the sky is blue. It is a nice day."
+
+    result = annotator.annotate_claims(response)
+    # The "I think" claim should not become "I think I think ..."
+    assert "I think I think" not in result.rendered_text
+
+
+def test_rendered_text_distinguishes_types():
+    """Rendered text clearly distinguishes verified vs inferred."""
+    annotator = ClaimAnnotator()
+    verified = {"Earth is round": "https://science.org/earth"}
+    response = "Earth is round. Stars are far away."
+
+    result = annotator.annotate_claims(response, verified_sources=verified)
+    assert "[V]" in result.rendered_text  # verified marker
+    assert "[I]" in result.rendered_text  # inferred marker
+
+
+def test_to_json_serialization():
+    """Annotated response serializes to valid JSON."""
+    annotator = ClaimAnnotator()
+    response = "Test claim."
+    result = annotator.annotate_claims(response)
+    json_str = annotator.to_json(result)
+    parsed = json.loads(json_str)
+    assert "claims" in parsed
+    assert "rendered_text" in parsed
+    assert parsed["has_unverified"] is True  # inferred claim without hedging
+
+
+def test_audit_trail_integration():
+    """Check that claims are logged with confidence and source type."""
+    # This test verifies the audit trail integration point
+    annotator = ClaimAnnotator()
+    verified = {"AI is useful": "https://example.com/ai"}
+    response = "AI is useful. It can help with tasks."
+
+    result = annotator.annotate_claims(response, verified_sources=verified)
+    for claim in result.claims:
+        assert claim.source_type in ("verified", "inferred")
+        assert claim.confidence in ("high", "medium", "low", "unknown")
+        if claim.source_type == "verified":
+            assert claim.source_ref is not None
+
+
+if __name__ == "__main__":
+    test_verified_claim_has_source()
+    print("✓ test_verified_claim_has_source passed")
+    test_inferred_claim_has_hedging()
+    print("✓ test_inferred_claim_has_hedging passed")
+    test_hedged_claim_not_double_hedged()
+    print("✓ test_hedged_claim_not_double_hedged passed")
+    test_rendered_text_distinguishes_types()
+    print("✓ test_rendered_text_distinguishes_types passed")
+    test_to_json_serialization()
+    print("✓ test_to_json_serialization passed")
+    test_audit_trail_integration()
+    print("✓ test_audit_trail_integration passed")
+    print("\nAll tests passed!")