linespec

LineSpec v1.3.0

Provenance Records - Structured YAML artifacts for documenting architectural decisions
LineSpec Testing - DSL-based integration testing for containerized services (Beta)

---

Overview

LineSpec is a tool for managing Provenance Records - structured decision documents that capture the intent, constraints, and reasoning behind architectural changes. It includes a powerful CLI for creating, validating, and enforcing these records.

The default installation includes only the stable Provenance Records functionality. LineSpec Testing features are available as a beta opt-in.

---

Installation

Homebrew (Recommended)

# Install stable version (Provenance Records only)
brew tap livecodelife/linespec
brew install linespec

# Or install beta version (includes LineSpec Testing)
brew install linespec-beta

Go Install

# Stable version (Provenance Records only)
go install github.com/livecodelife/linespec/cmd/linespec@v1.3.0

# Beta version (includes LineSpec Testing)
go install -tags beta github.com/livecodelife/linespec/cmd/linespec@v1.3.0

GitHub Releases

Download pre-built binaries from the releases page.

• linespec_1.3.0_* - Stable version (Provenance only)
• linespec-beta_1.3.0_* - Beta version (All features)

---

Quick Start - Provenance Records (Stable)

# 1. Install LineSpec
brew tap livecodelife/linespec
brew install linespec

# 2. Create your first provenance record
linespec provenance create --title "Add user authentication"

# 3. View the decision graph
linespec provenance graph

# 4. Validate all records
linespec provenance lint

Example Provenance Record

id: prov-2026-001
title: "Use PostgreSQL for primary data store"
status: open
created_at: "2026-03-15"
author: "dev@example.com"

intent: >
  After evaluating options, we choose PostgreSQL for our primary
  data store due to better JSON support and concurrent write handling.

constraints:
  - All new tables must use PostgreSQL
  - Use connection pooling (min 10, max 100)

affected_scope:
  - pkg/db/**
  - migrations/**

associated_specs:
  - path: tests/db/postgres_integration_spec.rb
    type: rspec

tags:
  - architecture
  - database

Complete Provenance Records Reference →

---

Feature Comparison

Feature	Provenance Records (v1.0.0)	LineSpec Testing (Beta)
Status	✅ Stable	🚧 Beta
Commands	provenance	test, proxy
Maturity	Production-ready	Active development
Installation	Default	Requires -tags beta
Documentation	Complete	In progress

---

Provenance Records - Full Feature Set

CLI Commands

# Record management
linespec provenance create          # Create new record
linespec provenance lint            # Validate records
linespec provenance status          # View status
linespec provenance graph           # Render decision graph

# Semantic search (requires embedding configuration)
linespec provenance search          # Search by semantic similarity
linespec provenance audit           # Audit changes against history
linespec provenance index           # Index records for search

# Git integration
linespec provenance check           # Check commits for violations
linespec provenance install-hooks   # Install git hooks

# Lifecycle management
linespec provenance lock-scope      # Lock scope to allowlist
linespec provenance complete        # Mark as implemented
linespec provenance deprecate       # Mark as deprecated

# Output formats
linespec provenance lint --format json     # JSON output for CI
linespec provenance lint --format sarif    # SARIF output for GitHub Code Scanning

Key Features

• Structured YAML format - Clear, version-controlled decision records
• Scope enforcement - Automatic validation of what files can be modified
• Git integration - Pre-commit hooks and commit message validation
• Graph visualization - Query and visualize decision relationships
• Monorepo support - Service-specific records with ID suffixes
• CI/CD ready - JSON output and strict enforcement modes
• SARIF output - GitHub Code Scanning integration

SARIF Output for GitHub Code Scanning

LineSpec can emit lint results in SARIF (Static Analysis Results Interchange Format) 2.1.0 format for integration with GitHub Code Scanning:

# Generate SARIF output
linespec provenance lint --format sarif > provenance-results.sarif

# Upload to GitHub Code Scanning (in your CI workflow)
- name: Lint provenance records
  run: linespec provenance lint --format sarif > provenance-results.sarif
  continue-on-error: true

- name: Upload to Code Scanning
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: provenance-results.sarif
    category: linespec-provenance

The SARIF output includes:

• 19 stable rule IDs (PROV001-PROV019) for consistent alerting
• File hashes for GitHub's deduplication
• %SRCROOT% base for proper path resolution
• Severity mapping (error→error, warning→warning, hint→note)

Documentation

• PROVENANCE_RECORDS.md - Complete reference guide
• AGENTS.md - Guidelines for AI agents using LineSpec

---

LineSpec Testing (Beta)

🚧 Beta Feature: LineSpec Testing is in active development. Build with -tags beta to enable.

LineSpec Testing is a DSL-based integration testing framework for containerized services. It intercepts database and HTTP traffic at the protocol level, making tests language-agnostic and framework-independent.

Installation (Beta)

# Build from source with beta tag
go build -tags beta -o linespec ./cmd/linespec

# Or install via go install
go install -tags beta github.com/livecodelife/linespec/cmd/linespec@v1.3.0

Beta Commands

# Run integration tests
linespec test <path-to-linespec-files>

# Start protocol proxies
linespec proxy mysql <listen> <upstream>
linespec proxy postgresql <listen> <upstream>
linespec proxy http <listen> <upstream>
linespec proxy kafka <listen> <upstream>

Example LineSpec Test

TEST create-user
RECEIVE HTTP:POST http://localhost:3000/users
WITH {{payloads/user_create_req.yaml}}

EXPECT WRITE:MYSQL users
WITH {{payloads/user_db_write_record.yaml}}
VERIFY query MATCHES /\bpassword_digest\b/
VERIFY query NOT_CONTAINS '`password`'

RESPOND HTTP:201
WITH {{payloads/user_create_resp.yaml}}
NOISE
  body.id
  body.created_at

Beta Documentation

• LINESPEC.md - DSL syntax reference (Beta)
• AGENTS.md - Testing guidelines (Beta section)

---

Configuration

Create a .linespec.yml in your repository root:

# Provenance Records configuration
provenance:
  dir: provenance                    # Records directory
  enforcement: warn                  # none|warn|strict
  commit_tag_required: false         # Require IDs in commits
  auto_affected_scope: true           # Auto-populate from git
  shared_repos: []                    # Additional directories (monorepos)
  
  # Semantic search configuration (optional - supports voyage or openai)
  embedding:
    provider: voyage                 # Embedding provider: voyage or openai
    index_model: voyage-4-large     # Model for indexing (2048 dims for voyage)
    query_model: voyage-4-lite      # Model for queries (2048 dims for voyage)
    api_key: ${VOYAGE_API_KEY}      # API key from environment
    similarity_threshold: 0.50        # Minimum similarity for results
    index_on_complete: true         # Auto-index on complete

# LineSpec Testing configuration (Beta)
service:
  name: my-service
  type: web
  port: 3000
  framework: rails                    # rails, fastapi, django, express, or custom
  start_command: bundle exec rails server  # Optional: override framework default
  migration_command: bundle exec rake db:migrate  # Optional: custom migration command
  warmup_endpoint: /health            # Optional: custom warmup endpoint
  warmup_delay_ms: 100                # Optional: warmup delay in milliseconds
  
database:
  type: mysql
  port: 3306
  database: my-service_development    # Database name (default: {service}_development)
  username: my-service_user           # Username (default: {service}_user)
  password: my-service_password       # Password (default: {service}_password)
  host: db                            # Host for external DBs

infrastructure:
  database: true
  kafka: false

# Container naming configuration (optional)
container_naming:
  database_container: linespec-shared-db
  network_name: linespec-shared-net
  network_alias: real-db
  migrate_container: linespec-migrate-

Framework Support:

Framework	Start Command	Migration Command	Needs Warmup
rails	bundle exec rails server	bundle exec rails db:migrate	Yes
fastapi	uvicorn main:app	None	No
django	python manage.py runserver	python manage.py migrate	Yes
express	npm start	None	No
Custom	Via start_command	Via migration_command	Via needs_warmup

---

Development

# Clone repository
git clone https://github.com/livecodelife/linespec.git
cd linespec

# Build stable version (Provenance only)
go build -o linespec ./cmd/linespec

# Build beta version (all features)
go build -tags beta -o linespec ./cmd/linespec

# Run tests
go test ./...

# Run integration tests (requires Docker)
make test-integration

# Run with beta features
./linespec test ./examples/

---

Documentation Index

Document	Status	Description
PROVENANCE_RECORDS.md	✅ Stable	Complete provenance reference
README.md	✅ Stable	This file - overview and installation
AGENTS.md	✅ Stable	Guidelines for AI agents
LINESPEC.md	🚧 Beta	DSL syntax for integration testing
RELEASE_PLAN.md	✅ Stable	v1.0.0 release strategy

Reading Order

1. Start here (README.md) - Installation and overview
2. PROVENANCE_RECORDS.md - Complete reference for stable features
3. AGENTS.md - If using AI agents with LineSpec
4. LINESPEC.md - If using beta testing features

---

FAQ

What's the difference between stable and beta?

Stable (default): Includes only Provenance Records - fully tested and production-ready.

Beta: Includes Provenance Records + LineSpec Testing - active development, may have bugs.

Can I install both versions?

Yes! Using Homebrew:

brew install linespec        # Stable
brew install linespec-beta   # Beta (installed as 'linespec-beta')

When will LineSpec Testing be stable?

LineSpec Testing will reach v1.0.0 in a future release. The beta is available now for early adopters who want to test and provide feedback.

How do I migrate from the old repository?

The module path changed from github.com/calebcowen/linespec to github.com/livecodelife/linespec. Update your imports and use the new installation path.

Where are my compiled YAML files?

LineSpec doesn't generate YAML files. Provenance Records are the authoritative source and are executed directly.

---

Contributing

1. Check for an existing provenance record covering your work
2. If none exists, create a new record describing your decision
3. Make your changes
4. Run the linter: linespec provenance lint
5. Submit a pull request

See AGENTS.md for detailed guidelines.

---

License

MIT License - See LICENSE for details.

---

Support

• Issues: https://github.com/livecodelife/linespec/issues
• Discussions: https://github.com/livecodelife/linespec/discussions
• Releases: https://github.com/livecodelife/linespec/releases

---

LineSpec v1.0.4 - Built with Provenance Records