{"id":50929967,"url":"https://github.com/foundryside-dev/warpline","last_synced_at":"2026-06-17T03:04:46.793Z","repository":{"id":364503923,"uuid":"1268170624","full_name":"foundryside-dev/warpline","owner":"foundryside-dev","description":"warpline — temporal change-impact authority for the Weft federation (MCP + CLI, local-first)","archived":false,"fork":false,"pushed_at":"2026-06-13T09:23:31.000Z","size":284,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T10:11:45.953Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/foundryside-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-13T08:09:02.000Z","updated_at":"2026-06-13T09:21:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/foundryside-dev/warpline","commit_stats":null,"previous_names":["foundryside-dev/heddle"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/foundryside-dev/warpline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fwarpline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fwarpline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fwarpline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fwarpline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foundryside-dev","download_url":"https://codeload.github.com/foundryside-dev/warpline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fwarpline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34431810,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-17T03:04:45.158Z","updated_at":"2026-06-17T03:04:46.787Z","avatar_url":"https://github.com/foundryside-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# warpline — temporal change-impact authority\n\nVersion 1.1.0 · Weft federation member (5th) · local-first · enrich-only\n\nwarpline is the Weft federation's **temporal / change-impact authority**. It owns\nthe one thing no other member stores — **per-entity change history across runs,\nkeyed on SEI** — and the downstream-propagation query over it. It answers, every\nsession, the question an agent asks before claiming a change is done:\n\n\u003e *Given this diff: which entities changed, by whom, when — what is\n\u003e downstream-affected over the call graph, and what must I re-verify?*\n\nThe federation split is deliberate: **loomweave owns \"now\"** (the point-in-time\ngraph and SEI minting); **warpline owns \"over time\"** (dated change facts and edge\nsnapshots). warpline is **enrich-only** — it boots, ingests, and answers with no\nsibling installed.\n\n**warpline is advisory only. It never gates a change, never enforces a policy, and\nnever decides whether a change is allowed.** This is deconfliction tooling, not\nsecurity. A warpline answer is an enhancement you can act on or ignore — never a\nverdict you must clear. It **consumes** Loomweave SEI (it never mints identity) and\n**feeds** advisory change-impact facts to governance-style surfaces such as\nLegis/Charter, which run their own policy; warpline supplies the facts and never\nmakes the call.\n\nThe product front door lives at\n[warpline.foundryside.dev](https://warpline.foundryside.dev/); the reference docs\nare under [`docs/`](docs/index.md).\n\n## Features\n\n- **6 MCP tools** for change lists, entity timelines, churn counts, impact\n  radius, reverify worklists, and dated edge-snapshot capture — each with a\n  frozen `warpline.\u003ccontract\u003e.v1` schema.\n- **Honest answers**: every response carries `completeness` + `staleness` and a\n  CLOSED `enrichment` vocabulary (`present | absent | unavailable`). Sibling\n  absence is explicit, never an implied \"clean/allowed\" state.\n- **Local-first \u0026 safe**: all state lives under `.weft/warpline/` (git-ignored);\n  the only mutating tool writes there and never touches a sibling repo.\n- **Real SEI resolution** against the live loomweave, deployment-independent.\n- **Federation member lifecycle**: `warpline install` / `warpline doctor [--fix]`\n  wire and verify MCP bindings, hooks, the agent skill, and config.\n- **Endorsed names + short shims**: e.g. `warpline_change_list` and `changed`\n  return identical schema and data.\n\n## Installation\n\nInstall as a [uv](https://docs.astral.sh/uv/) tool (recommended — provides the\n`warpline` and `warpline-mcp` executables on your `PATH`):\n\n```bash\nuv tool install warpline\nwarpline --version        # warpline 1.1.0\n```\n\nOr with pip (warpline is a zero-dependency package):\n\n```bash\npip install warpline\n```\n\nFor development from a checkout:\n\n```bash\ngit clone \u003crepo-url\u003e warpline \u0026\u0026 cd warpline\nuv run warpline --version\n```\n\n**Requires Python ≥ 3.12.**\n\n## Quick start\n\n### 1. Install warpline into a repository\n\n`warpline install` wires warpline as a federation member of the target repo —\nidempotent, atomic, and it never clobbers a sibling's config block:\n\n```bash\nwarpline install --repo /path/to/project   # MCP bindings, hooks, skill, config\nwarpline doctor  --repo /path/to/project   # verify; add --fix to autofix\n```\n\n`doctor` exits non-zero if anything is missing and prints a per-component\nreport (`--json` emits a `warpline.doctor.v1` summary).\n\n### 2. The core loop (CLI)\n\n```bash\nwarpline backfill --repo /path/to/project --json          # ingest git history\nwarpline changed  --repo /path/to/project --rev-range HEAD~1..HEAD --json\nwarpline capture-snapshot --repo /path/to/project --json  # capture loomweave edges\nwarpline reverify --repo /path/to/project --changed-entity-key-id 1 --json\n```\n\nThe post-commit hook installed in step 1 keeps the temporal store fresh as you\ncommit, so `changed`/`timeline`/`churn` answer without a manual backfill.\n\n### 3. The same flow from an MCP host\n\n1. `tools/list` — discover the surface (read/write posture, idempotency, repo\n   requirement, touched paths, federation dependencies).\n2. `warpline_change_list` (`changed`) — **call first**; read its `next_actions`.\n3. `warpline_reverify_worklist_get` (`reverify`) — the worklist to recheck.\n4. `warpline_impact_radius_get` / `warpline_entity_timeline_get` — for explanation.\n5. `warpline_edge_snapshot_capture` (`capture_snapshot`) — when impact/reverify\n   reports `NO_SNAPSHOT` and loomweave is available.\n\n## MCP tools\n\nEndorsed name and short shim are interchangeable and return identical\nschema + data.\n\n| Endorsed name | Shim | Schema | Role |\n| --- | --- | --- | --- |\n| `warpline_change_list` | `changed` | `warpline.change_list.v1` | Changed entities for a rev range; hands back ready-to-call next actions. |\n| `warpline_entity_timeline_get` | `timeline` | `warpline.entity_timeline.v1` | Ordered change history for one entity; reports `sei_resolution` only, never lineage. |\n| `warpline_entity_churn_count_get` | `churn` | `warpline.entity_churn_count.v1` | Per-entity change-event counts; a never-observed entity is `churn_count: 0`. |\n| `warpline_impact_radius_get` | `blast_radius` | `warpline.impact_radius.v1` | Downstream affected set with mandatory `completeness` + `staleness`. |\n| `warpline_reverify_worklist_get` | `reverify` | `warpline.reverify_worklist.v1` | The agent worklist to recheck before claiming completion. |\n| `warpline_edge_snapshot_capture` | `capture_snapshot` | `warpline.edge_snapshot.v1` | The only mutating tool; captures dated loomweave edges into `.weft/warpline/`. |\n\n### Response contract\n\nEvery outbound tool returns the frozen success envelope:\n\n```json\n{\n  \"schema\": \"warpline.\u003ccontract\u003e.v1\",\n  \"ok\": true,\n  \"query\": { \"repo\": \"...\", \"tool\": \"...\", \"arguments\": {}, \"sort\": {}, \"page\": {} },\n  \"data\": { },\n  \"warnings\": [],\n  \"next_actions\": {},\n  \"enrichment\": {\"sei\": \"...\", \"edges\": \"...\", \"work\": \"...\",\n                  \"risk\": \"...\", \"governance\": \"...\", \"requirements\": \"...\"},\n  \"meta\": {\"producer\": {\"tool\": \"warpline\", \"version\": \"1.1.0\"},\n            \"local_only\": true, \"peer_side_effects\": []}\n}\n```\n\n- `enrichment` is a CLOSED vocab: `present` (peer present, fact attached),\n  `absent` (peer present, no fact), `unavailable` (peer unreachable) — plus\n  `stale | partial | skipped` for `edges`. None of these is ever a transport\n  error or an implied clean state.\n- Errors use `warpline.error.v1` with a CLOSED `error_code` set and `retryability`\n  of `retry_safe | retry_with_changes | fatal`. Switch on `error_code`, not\n  message text.\n- Every entity carries both `locator` and `sei` (`loomweave:eid:...`, opaque —\n  warpline never mints or parses it). `warpline_entity_key_id` is internal and **not**\n  a federation key; key on `sei` (preferred) or `locator`.\n\nFull contract: [`docs/federation/contracts.md`](docs/federation/contracts.md)\nand the bundled `warpline-workflow` skill\n([`src/warpline/skills/warpline-workflow/`](src/warpline/skills/warpline-workflow/)).\n\n## Federation member lifecycle\n\n`warpline install` installs everything by default, or a subset via flags\n(`--claude-code`, `--codex`, `--claude-md`, `--agents-md`, `--gitignore`,\n`--hooks`, `--session-hook`, `--skills`, `--codex-skills`, `--config`):\n\n| Component | What it does |\n| --- | --- |\n| MCP bindings | Registers warpline in `.mcp.json` (Claude Code) and `~/.codex/config.toml` (Codex), stdio transport. |\n| Hooks | git `post-commit` (fail-soft `warpline ingest-commit`) + Claude `SessionStart` (`warpline session-context`). |\n| Skill | Copies `warpline-workflow` into `.claude/skills/` and `.agents/skills/`. |\n| Instructions | Injects a `warpline:instructions` block into CLAUDE.md / AGENTS.md (foreign blocks preserved). |\n| Config | Writes `.weft/warpline/config.json` + `INSTALL_VERSION`. |\n\n`warpline doctor` checks all of the above; `warpline doctor --fix` re-applies\nanything fixable.\n\n## Configuration \u0026 runtime layout\n\nwarpline is local-first; runtime state lives under `.weft/warpline/` and is\ngit-ignored:\n\n```text\n.weft/warpline/\n├── warpline.db          # SQLite temporal store (change events, edge snapshots)\n├── config.json        # member identity {prefix, name, version}\n├── INSTALL_VERSION    # schema/version marker\n└── .gitignore         # keeps ephemeral runtime files out of commits\n```\n\nThe loomweave command warpline uses for SEI resolution / edge capture is\nserver/project config — set `WARPLINE_LOOMWEAVE_COMMAND` (default `loomweave`); it\nis **not** a public MCP tool argument. `git add -A` never stages a warpline DB.\n\n## Development\n\n```bash\nuv run ruff check .          # lint\nuv run mypy                  # strict type-check\nuv run pytest                # test suite\nuv run warpline mcp-smoke --repo . --json          # live stdio MCP smoke\nuv run warpline dogfood-eval --real-member-repo /path/to/member-repo --json\n```\n\n`warpline dogfood-eval` exercises the real change → reverify loop (synthetic lanes\nplus a real-member lane against an actual loomweave index) and gates on\n`ready=True`. See [`spike/REPORT.md`](spike/REPORT.md) for the readiness verdict\nand [`CHANGELOG.md`](CHANGELOG.md) for release history.\n\n## Documentation\n\n| Topic | Where |\n| --- | --- |\n| Docs site landing / table of contents | [`docs/index.md`](docs/index.md) |\n| Getting started (install → first worklist) | [`docs/getting-started.md`](docs/getting-started.md) |\n| Concepts (mental model, advisory-not-gating, degrade) | [`docs/concepts/`](docs/concepts/index.md) |\n| CLI reference (every command, flag, exit code) | [`docs/reference/cli.md`](docs/reference/cli.md) |\n| MCP tool reference (all 6 frozen tools) | [`docs/reference/mcp-tools.md`](docs/reference/mcp-tools.md) |\n| Federation (seams, what it feeds/consumes, degrade) | [`docs/federation.md`](docs/federation.md) |\n| Federation seam contracts (frozen, internal) | [`docs/federation/contracts.md`](docs/federation/contracts.md) |\n| Agent usage (progressive-disclosure skill) | [`src/warpline/skills/warpline-workflow/`](src/warpline/skills/warpline-workflow/) |\n| Solution architecture (internal) | [`solution-architecture/`](solution-architecture/) |\n| Product workspace (vision, roadmap, PDRs) | [`docs/product/`](docs/product/) |\n| Release history | [`CHANGELOG.md`](CHANGELOG.md) |\n\nThe authoritative interface-lock specification is hub-owned\n(`2026-06-13-warpline-interface-lock.md` in the weft hub); warpline implements **to**\nit and does not edit it.\n\n## Contributing\n\nwarpline implements to a frozen cross-member contract. Changes to a tool's name,\ninput/output schema, the envelope, or the error/enrichment vocabularies are a\nhub decision — escalate with evidence rather than diverging. Internal changes\nmust keep `ruff`, `mypy --strict`, and the full test suite green, and the 14\ngolden vectors (`tests/contracts/test_golden_vectors.py`) passing.\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full workflow and\n[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) for community expectations.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE). Copyright (c) 2026 John Morrissey. Consistent\nwith the rest of the Weft federation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundryside-dev%2Fwarpline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoundryside-dev%2Fwarpline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundryside-dev%2Fwarpline/lists"}