docs: add Phase 2.5 (Protocol Foundation) roadmap and strategic reframe (#32)

* docs: add Phase 2.5 (Protocol Foundation) roadmap and strategic reframe

Igor is a protocol, not a platform. The competitive moat is agent
sovereignty (identity + lineage + portability), not durable execution.
Reprioritize roadmap: ship checkpoint format spec, standalone verifier,
and effects library before self-migration and compute provider integration.
Adoption comes bottom-up through verification, like JWT.

- Add Product Phase 2.5: Protocol Foundation (effects library, checkpoint
  format spec, standalone verifier, browser WASM verifier)
- Document known tech debt (budget negativity, layering violation,
  stringly-typed retry, unchecked type assertion, stale comments)
- Add "Igor as Protocol" section to vision doc
- Update competitive positioning, open questions, long-term vision

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: fix Phase 2 status and lab binary name in roadmap

Address PR review comments:
- Clarify Phase 2 is still in progress (self-migration deferred to
  after Phase 2.5), not complete
- Fix lab binary name: igord-lab, not igor-lab (rename only applies
  to the main binary)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: simonovic86

docs/IMPLEMENTATION_STATUS.md

@@ -220,3 +220,15 @@ Last updated: 2026-03-15
 | `LoadSidecarData` tests | Added | `pkg/manifest/parse_test.go` — explicit path, derived path, no file, non-WASM |
 | CI: TinyGo before tests | Fixed | `.github/workflows/ci.yml` — WASM integration tests now run in CI |
 | CI: test coverage reporting | Added | `.github/workflows/ci.yml` — `go test -coverprofile` + summary |
+
+## Known Issues / Tech Debt
+
+Discovered during project review (2026-03-27). None are blockers for current functionality; all should be addressed during Phase 2.5 or as standalone fixes.
+
+| Issue | Severity | Location | Description |
+|-------|----------|----------|-------------|
+| Budget can go negative (RE-3 violation) | Medium | `internal/agent/instance.go` `Tick()` | Tick cost deduction `i.Budget -= costMicrocents` does not clamp to zero. A long tick can create budget debt before the next pre-tick check catches it. Fix: clamp `costMicrocents` to remaining budget before deduction. |
+| `ParseCheckpointHeader` layering violation | Low | `internal/agent/instance.go` | Checkpoint header parsing (~80 lines of `encoding/binary`) lives in the agent package alongside WASM compilation and tick execution. Should be extracted to `pkg/checkpoint` so standalone tools (`igor-verify`) can parse headers without importing the full runtime. Phase 2.5 prerequisite. |
+| Stringly-typed retry classification | Low | `internal/migration/retry.go` | Fatal error detection uses `strings.Contains` on error messages. If anyone rewords an error message, retry/fatal/ambiguous classification silently changes. Should use sentinel errors or typed error values. |
+| Unchecked lease type assertion | Low | `internal/runner/research/research.go` | `instance.Lease.(*authority.Lease)` uses blank identifier for ok value. Wrong interface type silently produces nil, triggering "lease disabled" behavior instead of surfacing the mismatch. |
+| Stale timeout comments | Low | Multiple files | Comments reference old 100ms tick timeout. Actual timeout is 15s (`internal/config/config.go` `TickTimeout`), changed to accommodate HTTP hostcalls. |

docs/governance/ROADMAP.md

@@ -1,10 +1,10 @@
 # Igor Roadmap
 
-## Current Status: Product Phase 1 Complete
+## Current Status: Product Phase 2.5 Next
 
-Igor has completed its research foundation (**Phases 2–5**) and pivoted to product development. The runtime now supports **portable, infrastructure-independent agents** with DID identity, cryptographic lineage verification, and clean CLI workflows (`igord run`, `resume`, `verify`).
+Igor has completed its research foundation (**Phases 2–5**) and Product Phase 1. The runtime supports **portable, infrastructure-independent agents** with DID identity, cryptographic lineage verification, effect-safe side effects, HTTP/payment hostcalls, and clean CLI workflows (`igord run`, `resume`, `verify`).
 
-**Product Phase 1 (Portable Sovereign Agent)** is complete. **Product Phase 2 (Agent Self-Provisioning)** is next.
+**Product Phase 1 (Portable Sovereign Agent)** is complete. **Phase 2 (Agent Self-Provisioning)** is in progress — HTTP, effects, payments, and deployer demos are delivered; self-migration is deferred to after Phase 2.5. **Product Phase 2.5 (Protocol Foundation)** is next — making the checkpoint format, verifier, and effect primitives independently adoptable.
 
 ---
 
@@ -231,6 +231,31 @@ Igor's research foundation (Phases 2–5) proved that agents can checkpoint, mig
 
 ---
 
+## Product Phase 2.5: Protocol Foundation
+
+**Goal:** Make Igor's checkpoint format, verification tools, and effect primitives independently adoptable — before building more runtime features.
+
+**Status:** Not started.
+
+**Strategic context:** Igor is a protocol, not a platform. The competitive moat is agent sovereignty (identity + lineage + portability), not durable execution. Durable execution platforms (Golem, Temporal, Restate) are potential deployment targets for Igor agents, not competitors. Adoption comes bottom-up through verification — publish the spec, ship the verifier, let verification pull developers toward the runtime. The analogy: the checkpoint format spec is JWT (RFC 7519), the standalone verifier is jwt.io, the Igor runtime is Auth0.
+
+**Scope:**
+- **Effects library extraction** (`igor.dev/effects`) — extract `sdk/igor/effects.go` + `encoding.go` as standalone Go module with zero Igor-specific dependencies. Blog post: "Crash-safe side effects in 200 lines." Tests bottom-up adoption thesis with minimal risk. (~1 day)
+- **Checkpoint format spec** — formal one-page spec in `docs/runtime/CHECKPOINT_FORMAT.md`: byte-level offset table, signing domain construction, chain rule, DID encoding, version dispatch, reserved epoch fields, CID compatibility note. Language-agnostic — enables third-party implementations without reading Go code. (~1-2 days)
+- **Standalone verifier** (`igor-verify`) — extract `ParseCheckpointHeader` from `internal/agent/instance.go` into `pkg/checkpoint` (fixes existing layering violation). Build zero-dependency binary: no wazero, no libp2p, no hostcalls (~5MB vs ~30MB). Bundle sample liquidation watcher history for zero-to-verification in 30 seconds. (~1-2 days)
+- **Browser WASM verifier** — compile the verify path (`pkg/lineage/`, `pkg/identity/`, `pkg/checkpoint/`) to WASM via `GOOS=js GOARCH=wasm` (pure stdlib, no TinyGo needed). Embeddable in protocol dashboards: "agent lineage: verified, 847 checkpoints, no gaps." (~2-3 days)
+
+**Binary model after this phase:**
+- `igor` (renamed from `igord`) — agent operators — run, resume, verify, inspect
+- `igor-verify` (new) — anyone verifying lineage — checkpoint parsing + chain verification only
+- `igord-lab` (existing, unchanged) — protocol developers — migration, replay, leases, simulator
+
+**Design principle:** No configurability, no extension points, no generalization. Five operations and one rule. A fixed offset table. Green or red. "I understand this completely in 5 minutes."
+
+**Outcome:** The checkpoint spec is an adoptable protocol artifact. The standalone verifier is the on-ramp. The effects library generates Go ecosystem mindshare. All three are independently valuable and create the conditions for runtime adoption — without requiring anyone to run a WASM agent first.
+
+---
+
 ## Product Phase 3: Permanent Memory
 
 **Goal:** Agents have tamper-evident, publicly verifiable life histories.
@@ -343,6 +368,14 @@ None. v0 is experimental. Things may be:
 - ✅ Agent deploys itself to compute provider (mock)
 - Agent decides when to migrate
 
+### Product Phase 2.5 Goals
+
+- Checkpoint format has a formal one-page spec (`docs/runtime/CHECKPOINT_FORMAT.md`)
+- Effects library published as standalone Go module (`igor.dev/effects`)
+- `igor-verify` binary verifies lineage chains with zero runtime dependencies
+- Browser WASM verifier can parse and verify checkpoints
+- Binary rename: `igord` → `igor`
+
 ---
 
 ## Timeline
@@ -354,7 +387,7 @@ Igor development follows "done when it's done" philosophy:
 - Correctness over features
 - Learning over shipping
 
-Research phases (2–5) complete. Product Phase 2 in progress.
+Research phases (2–5) complete. Product Phase 2 feature work complete. Phase 2.5 (Protocol Foundation) is next.
 
 ---
 
@@ -373,7 +406,7 @@ Igor v0 is experimental research software.
 - Performance optimizations (premature)
 - Production deployments (not ready)
 
-Focus: Complete Product Phase 2 before expanding scope.
+Focus: Complete Product Phase 2.5 (Protocol Foundation) before expanding scope.
 
 ---
 
@@ -382,9 +415,10 @@ Focus: Complete Product Phase 2 before expanding scope.
 Agents will pick their own infrastructure. Igor makes them portable enough to do so.
 
 - **Now:** Agents are portable digital objects with identity and verifiable history
-- **Next:** Agents pay for their own compute and self-provision infrastructure
+- **Next:** Checkpoint format spec, standalone verifier, and effects library enable verification-first adoption
+- **Then:** Agents pay for their own compute; Golem/Temporal/Restate become deployment targets, not competitors
 - **Later:** Agents have permanent, publicly verifiable memory on Arweave
-- **Eventually:** A multi-language ecosystem of sovereign, immortal agents
+- **Eventually:** A multi-language ecosystem of sovereign agents built on the Igor protocol
 
 ---
 
@@ -414,22 +448,32 @@ Igor builds on ideas from:
 
 Igor is **not novel**. It combines existing ideas in a specific way to explore autonomous agent survival.
 
+**Competitive positioning:** Golem Cloud, Temporal, and Restate provide durable execution platforms. Igor's differentiator is agent-owned identity, cryptographic lineage, and true portability — the agent is a protocol-level entity, not a platform deployment. These platforms are potential deployment targets for Igor agents, not competitors. Igor answers "who IS the agent?" while they answer "where does the agent run?"
+
 ---
 
 ## Open Questions
 
-1. **Can agents practically self-provision infrastructure?** (Akash/Golem integration complexity)
-2. **Is the checkpoint format efficient enough for large agent state?** (MB+ state sizes)
-3. **Will developers adopt the Igor SDK over simpler alternatives?** (DX matters)
+1. **Can the checkpoint format spec gain adoption independently of the runtime?** (The JWT analogy test — does verification pull people toward the protocol?)
+2. **Is the checkpoint format efficient enough for large agent state?** (MB+ state sizes; content-addressed external storage pointers as escape hatch)
+3. **Will DeFi teams adopt igor-verify for agent lineage proofs before the full runtime?** (Bottom-up adoption test)
 4. **Is WASM overhead acceptable for latency-sensitive agents?** (not for HFT, but for long-running?)
 5. **Can two-tier storage (local + Arweave) work without slowing the critical path?**
 6. **What hostcalls do agents actually need?** (HTTP, storage, payments — what else?)
+7. **Should Golem/Temporal/Restate be treated as deployment targets rather than competitors?** (Protocol-not-platform thesis)
 
 ---
 
 ## Next Immediate Steps
 
-Product Phase 2 in progress. HTTP hostcall, effect model, wallet_pay, x402buyer, and deployer demos delivered. Next:
+Product Phase 2 feature work complete. Protocol foundation is next — verification-first adoption.
+
+1. **Effects library extraction** — standalone Go module at `igor.dev/effects` (~1 day)
+2. **Checkpoint format spec** — formal spec in `docs/runtime/CHECKPOINT_FORMAT.md` (~1-2 days)
+3. **Standalone verifier** (`igor-verify`) — zero-dependency lineage verification binary (~1-2 days)
+4. **Browser WASM verifier** — checkpoint verification compiled to WASM (~2-3 days)
+
+Then:
 
-1. **Self-migration** — agent decides when and where to move based on price/performance
-2. **Real compute provider** — replace mock with Akash or Golem integration
+5. **Self-migration** — agent decides when and where to move based on price/performance
+6. **Real compute provider** — Akash or Golem as deployment targets (not competitors)

docs/philosophy/VISION.md

@@ -90,6 +90,16 @@ Igor is an experiment in providing capabilities that autonomous software increas
 
 The development philosophy is minimal and iterative. Igor v0 implements only what is necessary to demonstrate survival and migration. It fails loudly when invariants are violated rather than attempting graceful degradation. It prioritizes correctness over performance, clarity over optimization.
 
+## Igor as Protocol
+
+Igor is a protocol, not a platform. Durable execution platforms — Golem Cloud, Temporal, Restate — answer "where does the agent run?" Igor answers a different question: "who IS the agent?" The competitive moat is agent sovereignty: agent-owned identity (DID), cryptographic lineage (signed checkpoint chain), and true portability (the checkpoint file IS the agent). These platforms are potential deployment targets for Igor agents, not competitors. An Igor agent could run on Golem today, Akash tomorrow, and bare metal next week, with the same DID and unbroken lineage across all three.
+
+The adoption model follows verification, not runtime adoption. Trust primitives spread bottom-up — people verify before they run. The checkpoint format spec is the adoptable artifact (like JWT's RFC 7519). The standalone verifier is the on-ramp (like jwt.io — paste a token, see it decoded). The Igor runtime is one implementation of the protocol (like Auth0 is one implementation of JWT-based auth). Publish the spec, ship the verifier, let verification pull developers toward the runtime.
+
+The initial audience is DeFi. This community already thinks in DIDs, signed proofs, and "don't trust the platform." Provable agent uptime and integrity — "agent lineage: verified, 847 checkpoints, no gaps" — solves a problem DeFi has today and currently addresses with trust-me-bro operator reputation. Agent-owned identity and cryptographic lineage are table stakes in this context, not novel features.
+
+---
+
 Igor exists because the gap between what software can do (execute autonomously) and what software can survive (infrastructure failure) has become untenable for emerging autonomous systems. The technologies needed to solve this have matured to the point where exploration becomes feasible.
 
 Whether autonomous software survival matters in practice can only be answered through building systems that embody these capabilities and observing what emerges.