The Ground Truth Ledger for
Requirements & AI Coding Agents

Eliminate requirement drift and hallucinated specs across Cursor, Claude Code, and autonomous AI agents. Real-time AST hashing, 100% automated stale cascading, and fail-fast preflight validation.

MCP Server (npm) npx -y srs-mcp

Docker Stack docker run -d -p 3000:3000 pgsty/srs-ledger

Launch Interactive Playground View on GitHub

Join Early Access Whitelist • Priority Access

Get instant early access to real-time SRS synchronization and zero-latency AI Agent Preflight Engine.

AST Hash Tracking

Automated Stale Cascade

Fail-Fast Code 3

578 Vitest Tests

Interactive Spec Diff & Ledger Island

Live Spec Playground

In-browser markdown editor with sub-50ms AST hash recomputation, state cascade visualization, and ANSI terminal simulator.

Ledger State:Valid (Exit Code 0)

< 1ms Reactive Hash

auth_module.mdAuthoritative Spec

15 lines•803 characters•UTF-8

AST-monitored

State Ledger Visualizer7-State Machine

4 Approved

CLAR-001REQ-AUTH-001

Approved

Q:Are email addresses normalized to lowercase for login authentication?

A:Yes. All email addresses must be trimmed and converted to lowercase prior to DB lookup and JWT issuance.

CLAR-002REQ-AUTH-002

Approved

Q:What is the time step window and algorithm for TOTP code validation?

A:RFC 6238 TOTP with HMAC-SHA1, 30-second time step, and +/-1 step drift tolerance window.

CLAR-003REQ-AUTH-003

Approved

Q:Does refreshing access token with valid refresh token reset inactivity timer?

A:Yes. Active token refreshes extend the session sliding window by 15 minutes.

CLAR-004REQ-AUTH-001Cross-Module Cascade (REQ-AUTH-001, REQ-ORD-001)

Approved

Q:How does checkout flow authenticate high-value orders across modules?

A:Orders exceeding $1,000 require re-authentication with JWT issued in REQ-AUTH-001 within the last 5 minutes.

Automatic 100% Cascade Guarantee

Evaluated in 0.56ms

Core Architecture & Capabilities

Engineered for Absolute Requirements Integrity

Eliminate hallucinations before AI coding agents execute a single prompt. Four architectural pillars guarantee real-time verification and zero spec drift.

AST Parsing • LCS Diff

100% Automatic Stale Cascade

Whenever a spec section changes, the ledger computes SHA-256 anchor hashes and instantly cascades all dependent clarifications from Approved to Stale in sub-50ms. No stale requirements can sneak past agents.

Section: #login-flow [DIFF DETECTED]

REQ-AUTH-001: SHA-256 hash mutated

Cascade triggered → CLAR-001 & CLAR-004 invalidated

Deterministic Transitions

7-State Lifecycle Machine

Every requirement clarification strictly traverses an immutable state machine: Draft → Submitted → Approved, Changes Requested, Rejected, Stale, or Archived. AI coding agents only ever consume certified state.

Draft Submitted Approved Changes Rejected Stale Archived

Enforces strict transition policies • Blocks unverified draft consumption

Audited Agent Snapshots

4-Tier Zero-Leakage Whitelist Bundle

Downstream agents receive audited JSON snapshots filtered across four cryptographic tiers. Discard draft chatter, internal reviews, and stale discussions to prevent token bloat and hallucination.

Tier 1 Authoritative Requirements Normalized Markdown AST nodes

Tier 2 Approved Clarifications Strict human-verified resolutions

Tier 3 Canonical Q&A Context Disambiguated agent ground truth

Tier 4 SHA-256 Manifest Tamper-evident snapshot signature

Production Engine • 578 Vitest Suite

Production Architecture

Engineered with Fastify REST API, Drizzle ORM, and PostgreSQL 16 relational integrity. High-bandwidth MinIO S3 streaming supports massive specification documents and audit logs with 578 Vitest test suite verification.

Fastify • High-Throughput REST API

Drizzle ORM • Type-Safe SQL Queries

PostgreSQL 16 • Relational Ledger Engine

MinIO S3 • Object & Streaming Storage

578 Vitest • Comprehensive Unit Tests

Autonomous Coding Agents

Zero-Setup AI Agent Integrations

Drop-in configurations and official MCP server snippets for Cursor, Claude Code, Antigravity, and Claude Desktop.

Model Context Protocol (MCP)

Target: Claude Desktop, Cursor, Zed, & Antigravity

mcp_settings.json

Register the official published srs-mcp package into any MCP-compatible runtime to grant tools like srs_query_spec, srs_preflight_check, and srs_list_clarifications.

mcp_settings.json

{
  "mcpServers": {
    "srs": {
      "command": "npx",
      "args": ["-y", "srs-mcp"]
    }
  }
}

Cursor AI Rules

Target: .cursorrules

.cursorrules

Instruct Cursor to query the SRS Clarification Ledger and run preflight checks prior to proposing code modifications.

.cursorrules

# SRS Clarification Ledger Guardrails
Before generating, refactoring, or deleting any authentication or authorization logic:
1. Run preflight check: npx -y srs-mcp preflight --project amela-core
2. If exit code is 3 (STALE DETECTED): HALT execution and ask developer to resolve stale specifications.
3. Only use Approved requirements and certified clarifications from Tier 1-3 bundles.

Claude Code System Context

Target: CLAUDE.md

CLAUDE.md

Ensure Claude Code verifies requirement anchor integrity and respects the 7-state lifecycle machine before writing code.

CLAUDE.md

## SRS Integrity Verification Workflow
Every engineering task must respect the SRS Ground Truth Ledger:
- Verify spec freshness: `srs-ledger preflight --project <project_id>`
- Do NOT proceed if preflight returns Exit Code 3.
- Reference verified requirement tags ([REQ-AUTH-001], [REQ-AUTH-002]) in commit messages.

Antigravity Agent Skill

Target: skills/srs-preflight/SKILL.md

SKILL.md

Autonomous Antigravity agent skill that executes fail-fast preflight checks and parses AST anchor hashes before running plans.

SKILL.md

---
name: srs-preflight
description: Runs deterministic requirements preflight validation against the SRS Clarification Ledger. Halts if stale anchors are detected.
---

# Preflight Protocol
1. Execute: `npx -y srs-mcp preflight --project amela-core`
2. On Exit Code 0: Proceed with implementation.
3. On Exit Code 3: Stop planning, report invalidated anchor IDs to user.

Developer Quickstart

Get Started in 60 Seconds

Deploy via CLI sync (srs-ledger preflight), Docker Compose multi-container stack (docker run -d -p 3000:3000 pgsty/srs-ledger), or explore the Web UI.

Published on npm: https://www.npmjs.com/package/srs-mcp

Direct CLI Sync & Preflight Validation

Node 18+ or npx

Install globally with npm or execute on-demand with npx. Sync specifications against local repositories and verify requirement anchors before running AI coding agents.

# 1. Install or run directly from npm

npx -y srs-mcp

# 2. Or install CLI globally via npm

npm i -g srs-mcp

# 3. Synchronize specification AST anchors

srs-ledger sync --project amela-core

# 4. Execute deterministic preflight validation

srs-ledger preflight --project amela-core

Full Multi-Container Stack (PostgreSQL 16 + MinIO S3 + Fastify)

docker-compose.yml

Spin up the complete SRS Clarification Ledger stack with Postgres, MinIO object storage, and the Fastify REST API engine in one command.

version: '3.8'

services:
  # Relational Ledger Database
  postgres:
    image: postgres:16-alpine
    container_name: srs-postgres
    environment:
      POSTGRES_DB: srs_ledger
      POSTGRES_USER: srs_admin
      POSTGRES_PASSWORD: secret_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  # S3-Compatible Streaming Storage
  minio:
    image: minio/minio:latest
    container_name: srs-minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minio_admin
      MINIO_ROOT_PASSWORD: minio_secret_key
    ports:
      - "9000:9000"
      - "9001:9001"
    volumes:
      - minio_data:/data

  # SRS Clarification Fastify Application
  srs-server:
    image: pgsty/srs-ledger:latest
    container_name: srs-fastify
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://srs_admin:secret_password@postgres:5432/srs_ledger
      S3_ENDPOINT: http://minio:9000
    depends_on:
      - postgres
      - minio

volumes:
  postgres_data:
  minio_data:

Launch with: docker compose up -d

Priority Beta Access

Join Early Access Whitelist

Get first access to autonomous agent synchronization, multi-repository drift monitors, and private team ledger deployments.

Zero spam • Direct access to maintainers • Instant onboarding token

The Ground Truth Ledger for
Requirements & AI Coding Agents

Join Early Access Whitelist • Priority Access

Live Spec Playground

Engineered for Absolute Requirements Integrity

100% Automatic Stale Cascade

7-State Lifecycle Machine

4-Tier Zero-Leakage Whitelist Bundle

Production Architecture

Zero-Setup AI Agent Integrations

Model Context Protocol (MCP)

Cursor AI Rules

Claude Code System Context

Antigravity Agent Skill

Get Started in 60 Seconds

Direct CLI Sync & Preflight Validation

Full Multi-Container Stack (PostgreSQL 16 + MinIO S3 + Fastify)

Web UI Overview & Interactive Operations

AST Visual Tree

Stale Queue Review

Instant Query Engine

Join Early Access Whitelist

The Ground Truth Ledger for Requirements & AI Coding Agents

Join Early Access Whitelist • Priority Access

Live Spec Playground

Engineered for Absolute Requirements Integrity

100% Automatic Stale Cascade

7-State Lifecycle Machine

4-Tier Zero-Leakage Whitelist Bundle

Production Architecture

Zero-Setup AI Agent Integrations

Model Context Protocol (MCP)

Cursor AI Rules

Claude Code System Context

Antigravity Agent Skill

Get Started in 60 Seconds

Direct CLI Sync & Preflight Validation

Full Multi-Container Stack (PostgreSQL 16 + MinIO S3 + Fastify)

Web UI Overview & Interactive Operations

AST Visual Tree

Stale Queue Review

Instant Query Engine

Join Early Access Whitelist

The Ground Truth Ledger for
Requirements & AI Coding Agents