Warpline

Version 1.1.1 · Weft federation member (5th) · local-first · enrich-only

warpline is the Weft federation's temporal / change-impact authority. It owns the one thing no other member stores — per-entity change history across runs, keyed on SEI — and the downstream-propagation query over it. It answers, every session, the question an agent asks before claiming a change is done:

Given this diff: which entities changed, by whom, when — what is downstream-affected over the call graph, and what must I re-verify?

The federation split is deliberate: loomweave owns "now" (the point-in-time graph and SEI minting); warpline owns "over time" (dated change facts and edge snapshots). warpline is enrich-only — it boots, ingests, and answers with no sibling installed.

warpline is advisory only. It never gates a change, never enforces a policy, and never decides whether a change is allowed. This is deconfliction tooling, not security. A warpline answer is an enhancement you can act on or ignore — never a verdict you must clear. It consumes Loomweave SEI (it never mints identity) and feeds advisory change-impact facts to governance-style surfaces such as Legis/Plainweave, which run their own policy; warpline supplies the facts and never makes the call.

The product front door lives at warpline.foundryside.dev; the reference docs are under docs/.

Features

• 6 MCP tools for change lists, entity timelines, churn counts, impact radius, reverify worklists, and dated edge-snapshot capture — each with a frozen warpline.<contract>.v1 schema.
• Honest answers: every response carries completeness + staleness and a CLOSED enrichment vocabulary (present | absent | unavailable). Sibling absence is explicit, never an implied "clean/allowed" state.
• Local-first & safe: all state lives under .weft/warpline/ (git-ignored); the only mutating tool writes there and never touches a sibling repo.
• Real SEI resolution against the live loomweave, deployment-independent.
• Federation member lifecycle: warpline install / warpline doctor [--fix] wire and verify MCP bindings, hooks, the agent skill, and config.
• Endorsed names + short shims: e.g. warpline_change_list and changed return identical schema and data.

Installation

Install as a uv tool (recommended — provides the warpline and warpline-mcp executables on your PATH):

uv tool install warpline
warpline --version        # warpline 1.1.1

Or with pip (warpline is a zero-dependency package):

pip install warpline

For development from a checkout:

git clone <repo-url> warpline && cd warpline
uv run warpline --version

Requires Python ≥ 3.12.

Quick start

1. Install warpline into a repository

warpline install wires warpline as a federation member of the target repo — idempotent, atomic, and it never clobbers a sibling's config block:

warpline install --repo /path/to/project   # MCP bindings, hooks, skill, config
warpline doctor  --repo /path/to/project   # verify; add --fix to autofix

doctor exits non-zero if anything is missing and prints a per-component report (--json emits a warpline.doctor.v1 summary).

2. The core loop (CLI)

warpline backfill --repo /path/to/project --json          # ingest git history
warpline changed  --repo /path/to/project --rev-range HEAD~1..HEAD --json
warpline capture-snapshot --repo /path/to/project --json  # capture loomweave edges
warpline reverify --repo /path/to/project --changed-entity-key-id 1 --json

The post-commit hook installed in step 1 keeps the temporal store fresh as you commit, so changed/timeline/churn answer without a manual backfill.

3. The same flow from an MCP host

1. tools/list — discover the surface (read/write posture, idempotency, repo requirement, touched paths, federation dependencies).
2. warpline_change_list (changed) — call first; read its next_actions.
3. warpline_reverify_worklist_get (reverify) — the worklist to recheck.
4. warpline_impact_radius_get / warpline_entity_timeline_get — for explanation.
5. warpline_edge_snapshot_capture (capture_snapshot) — when impact/reverify reports NO_SNAPSHOT and loomweave is available.

MCP tools

Endorsed name and short shim are interchangeable and return identical schema + data.

Endorsed name	Shim	Schema	Role
warpline_change_list	changed	warpline.change_list.v1	Changed entities for a rev range; hands back ready-to-call next actions.
warpline_entity_timeline_get	timeline	warpline.entity_timeline.v1	Ordered change history for one entity; reports sei_resolution only, never lineage.
warpline_entity_churn_count_get	churn	warpline.entity_churn_count.v1	Per-entity change-event counts; a never-observed entity is churn_count: 0.
warpline_impact_radius_get	blast_radius	warpline.impact_radius.v1	Downstream affected set with mandatory completeness + staleness.
warpline_reverify_worklist_get	reverify	warpline.reverify_worklist.v1	The agent worklist to recheck before claiming completion.
warpline_edge_snapshot_capture	capture_snapshot	warpline.edge_snapshot.v1	The only mutating tool; captures dated loomweave edges into .weft/warpline/.

Response contract

Every outbound tool returns the frozen success envelope:

{
  "schema": "warpline.<contract>.v1",
  "ok": true,
  "query": { "repo": "...", "tool": "...", "arguments": {}, "sort": {}, "page": {} },
  "data": { },
  "warnings": [],
  "next_actions": {},
  "enrichment": {"sei": "...", "edges": "...", "work": "...",
                  "risk": "...", "governance": "...", "requirements": "..."},
  "meta": {"producer": {"tool": "warpline", "version": "1.1.1"},
            "local_only": true, "peer_side_effects": []}
}

• enrichment is a CLOSED vocab: present (peer present, fact attached), absent (peer present, no fact), unavailable (peer unreachable) — plus stale | partial | skipped for edges. None of these is ever a transport error or an implied clean state.
• Errors use warpline.error.v1 with a CLOSED error_code set and retryability of retry_safe | retry_with_changes | fatal. Switch on error_code, not message text.
• Every entity carries both locator and sei (loomweave:eid:..., opaque — warpline never mints or parses it). warpline_entity_key_id is internal and not a federation key; key on sei (preferred) or locator.

Full contract: docs/federation/contracts.md and the bundled warpline-workflow skill (src/warpline/skills/warpline-workflow/).

Federation member lifecycle

warpline install installs everything by default, or a subset via flags (--claude-code, --codex, --claude-md, --agents-md, --gitignore, --hooks, --session-hook, --skills, --codex-skills, --config):

Component	What it does
MCP bindings	Registers warpline in .mcp.json (Claude Code) and ~/.codex/config.toml (Codex), stdio transport.
Hooks	git post-commit (fail-soft warpline ingest-commit) + Claude SessionStart (warpline session-context).
Skill	Copies warpline-workflow into .claude/skills/ and .agents/skills/.
Instructions	Injects a warpline:instructions block into CLAUDE.md / AGENTS.md (foreign blocks preserved).
Config	Writes .weft/warpline/config.json + INSTALL_VERSION.

warpline doctor checks all of the above; warpline doctor --fix re-applies anything fixable.

Configuration & runtime layout

warpline is local-first; runtime state lives under .weft/warpline/ and is git-ignored:

.weft/warpline/
├── warpline.db          # SQLite temporal store (change events, edge snapshots)
├── config.json        # member identity {prefix, name, version}
├── INSTALL_VERSION    # schema/version marker
└── .gitignore         # keeps ephemeral runtime files out of commits

The loomweave command warpline uses for SEI resolution / edge capture is server/project config — set WARPLINE_LOOMWEAVE_COMMAND (default loomweave); it is not a public MCP tool argument. git add -A never stages a warpline DB.

Filigree work-state enrichment uses filigree's dashboard HTTP API when a reverify request sets include_federation=true. Set FILIGREE_API_URL to point warpline at a non-default dashboard; the default is http://localhost:8724. If the dashboard is absent or unreachable, warpline reports work enrichment as unavailable / member unreachable and still returns the local worklist.

Development

uv run ruff check .          # lint
uv run mypy                  # strict type-check
uv run pytest                # test suite
uv run warpline mcp-smoke --repo . --json          # live stdio MCP smoke
uv run warpline dogfood-eval --real-member-repo /path/to/member-repo --json

warpline dogfood-eval exercises the real change → reverify loop (synthetic lanes plus a real-member lane against an actual loomweave index) and gates on ready=True. See spike/REPORT.md for the readiness verdict and CHANGELOG.md for release history.

Documentation

Topic	Where
Docs site landing / table of contents	docs/index.md
Getting started (install → first worklist)	docs/getting-started.md
Concepts (mental model, advisory-not-gating, degrade)	docs/concepts/
CLI reference (every command, flag, exit code)	docs/reference/cli.md
MCP tool reference (all 6 frozen tools)	docs/reference/mcp-tools.md
Federation (seams, what it feeds/consumes, degrade)	docs/federation.md
Federation seam contracts (frozen, internal)	docs/federation/contracts.md
Agent usage (progressive-disclosure skill)	src/warpline/skills/warpline-workflow/
Solution architecture (internal)	solution-architecture/
Product workspace (vision, roadmap, PDRs)	docs/product/
Release history	CHANGELOG.md

The authoritative interface-lock specification is hub-owned (2026-06-13-warpline-interface-lock.md in the weft hub); warpline implements to it and does not edit it.

Contributing

warpline implements to a frozen cross-member contract. Changes to a tool's name, input/output schema, the envelope, or the error/enrichment vocabularies are a hub decision — escalate with evidence rather than diverging. Internal changes must keep ruff, mypy --strict, and the full test suite green, and the 14 golden vectors (tests/contracts/test_golden_vectors.py) passing.

See CONTRIBUTING.md for the full workflow and CODE_OF_CONDUCT.md for community expectations.

License

MIT — see LICENSE. Copyright (c) 2026 John Morrissey. Consistent with the rest of the Weft federation.