ilp — Intent Lineage Protocol

A CLI tool for maintaining traceable chains from human decisions to running code.

Intent (why)  →  Dialogue (decisions)  →  Spec (what)  →  Code (how)  →  Trust (verified?)

Every layer links to the one above. From any line of code, you can trace back to why it exists.

Install

cargo install --path .

Quick Start

# Initialize a project
ilp init

# Write specs in specs/features/checkout.spec
# Check for errors
ilp check specs

# View the lineage graph
ilp lineage --graph --path specs

# Generate tests from examples/properties
ilp generate --tests-only specs --lang rust

# Run verification
ilp verify specs --level example

# Show trust report
ilp trust --path specs

# Detect spec/code drift
ilp drift specs

# Project overview
ilp status specs

.spec File Format

// Intent: why does this exist?
@id intent:purchase-flow
intent "Product Purchase Flow" {
  reason "Core e-commerce functionality"
  priority critical
}

// Dialogue: key decisions made
@id dialogue:checkout
@links intent:purchase-flow
dialogue checkout {
  decisions {
    "All items must be in stock. No partial orders."
    "Payment retry: 3 times with exponential backoff"
  }
}

// Spec: formal specification
@id spec:checkout
@links dialogue:checkout
@source "src/checkout.rs"
spec checkout(cart: Cart, payment: PaymentMethod) -> Result<Order, CheckoutError>
  requires cart.items.nonEmpty
  ensures order.total == cart.total
  effects [Database, PaymentGateway, Email]
  error InsufficientStock when exists item in cart.items: !in_stock(item)

  examples {
    checkout(cartWith2Items, validCard) == Ok(order { total: 3000 })
    checkout(emptyCart, validCard) == Err(EmptyCart)
  }

  properties {
    checkout(cart, payment).isOk implies order.total == cart.total
  }

// Trust: verification status
trust {
  checkout:
    spec_level: formal
    verified: property_test
    last_verified: 2026-02-26
}

Commands

Command	Description
ilp init	Initialize project (creates ilp.toml, specs/)
ilp check	Static analysis of .spec files
ilp lineage	Explore the lineage DAG (upstream/downstream)
ilp generate	Generate test code from spec examples/properties
ilp verify	Run generated tests, calculate trust levels
ilp retroactive	Generate specs from existing source code
ilp trust	Show trust report (verification status)
ilp drift	Detect spec/code divergence via git
ilp status	Project dashboard
ilp lsp	Start LSP server (editor integration)
ilp mcp	Start MCP server (AI tool integration)

Lineage Annotations

@id layer:name          Unique identifier
@links layer:name       Link to upstream element
@source "path/to/file"  Link to implementation
@retroactive            Mark as added after implementation

Incremental Formalization

Specs can start informal and become formal over time:

// Level 0: natural language only
spec checkout
  "Process the cart items for purchase"

// Level 1: typed signature
spec checkout(cart: Cart) -> Result<Order, Error>
  "Process the cart items for purchase"

// Level 2: formal contracts
spec checkout(cart: Cart) -> Result<Order, Error>
  requires cart.items.nonEmpty
  ensures order.total == cart.total
  effects [Database]

AI Tool Integration

MCP Server

# Start MCP server for Claude Code / Cursor
ilp mcp --path specs

Available tools: ilp_read_spec, ilp_check, ilp_lineage, ilp_trust, ilp_drift, ilp_list_specs

LSP Server

# Start LSP server for editor integration
ilp lsp

Features: diagnostics, hover (lineage info), go-to-definition (@links -> @id)

Existing Code Integration

# Analyze existing source and generate spec scaffolds
ilp retroactive src/ --recursive --output specs/retroactive/

# Then review and refine the generated specs

Architecture

src/
  ast.rs          AST definitions (.spec file structure)
  parser.rs       Hand-written recursive descent parser
  check.rs        Static analysis (duplicate IDs, broken links)
  lineage.rs      DAG construction and traversal
  generate.rs     Test code generation (Rust/TypeScript)
  verify.rs       Test execution and trust level calculation
  retroactive.rs  Source code analysis (Rust/TypeScript/Python)
  drift.rs        Git-based spec/code drift detection
  trust.rs        Trust report and management
  mcp.rs          MCP server (JSON-RPC 2.0 over stdio)
  lsp.rs          LSP server (Content-Length framed JSON-RPC)
  main.rs         CLI entry point (clap)

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.