{"id":51631903,"url":"https://github.com/foundryside-dev/plainweave","last_synced_at":"2026-07-13T08:30:52.663Z","repository":{"id":367401624,"uuid":"1279958739","full_name":"foundryside-dev/plainweave","owner":"foundryside-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-25T20:22:06.000Z","size":667,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T22:03:38.312Z","etag":null,"topics":["agent","intent","mcp","python","requirements","traceability","weft"],"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":"CONTRIBUTING.md","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-25T06:37:46.000Z","updated_at":"2026-06-25T20:03:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/foundryside-dev/plainweave","commit_stats":null,"previous_names":["foundryside-dev/plainweave"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/foundryside-dev/plainweave","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fplainweave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fplainweave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fplainweave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fplainweave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foundryside-dev","download_url":"https://codeload.github.com/foundryside-dev/plainweave/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foundryside-dev%2Fplainweave/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35416386,"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-07-13T02:00:06.543Z","response_time":119,"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":["agent","intent","mcp","python","requirements","traceability","weft"],"created_at":"2026-07-13T08:30:52.137Z","updated_at":"2026-07-13T08:30:52.650Z","avatar_url":"https://github.com/foundryside-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plainweave\n\n**Permission for code to exist.**\n\nPlainweave is the Weft federation member that holds the team's **code-grounded\nintent**: a traceability graph in which every code entity must earn its\nexistence by laddering up to a requirement, and every requirement must ladder up\nto a strategic goal. A node with no upward edge — at any level — is a reviewable\nquestion:\n\n- a public capability with no requirement → *\"why does this code exist?\"*\n- a requirement with no goal → *\"what am I doing here?\"*\n\nThe point is **not** catching orphan code (that is one query). The point is that\nbinding code to requirements accretes a **living, readable requirements corpus**\nan agent or human can reason over — *\"why do we have three requirements for\nreporting that are all the same?\"* — and consolidate. Plainweave **moves the\nrefactor lever up the Meadows leverage hierarchy**: from the lowest altitude\n(rename this function, extract that class) to a high one (*why does this\nsubmodule exist; does it still serve a goal we hold?*).\n\n\u003e **Status — 1.0.** The build is complete and stable: the intent graph, the read\n\u003e primitives, the authoring surface, the cross-member seams, and `doctor` ship with\n\u003e versioned JSON envelopes, strict typing, and a green gate (lint, mypy strict, tests\n\u003e at ≥90% coverage). This is stable *behaviour and contracts* — cross-language coverage\n\u003e *completeness* (e.g. Rust public-surface tagging upstream) is a documented roadmap\n\u003e item, not a 1.0 gate. Formal Weft suite membership / launch-cutover inclusion remains\n\u003e **owner-gated**. Reframed and renamed from the `~/charter` precursor; the backlog\n\u003e lives in this repo's `.filigree` tracker.\n\n## The model — a traceability graph of intent\n\n```text\nstrategic goal ──▲── requirement ──▲── code SEI (leaf)\n   (root intent)        (obligation)        (the thing that exists)\n```\n\n- **Leaves** are code entities — Loomweave SEIs (modules + public surfaces).\n  **Interior nodes** are typed intent nodes (requirement, strategic goal) at any\n  altitude; altitudes are just node types, the graph does not fix the number of\n  levels.\n- **Edges** mean *\"justified by / satisfies.\"*\n- **Requirements are trivially mintable** (shells welcome). The corpus tolerates\n  mess by design — value comes from the mess being *visible and queryable*, then\n  consolidated. Cheap minting *feeds* the corpus.\n- **Code leaves are keyed by Loomweave SEI**, so bindings survive rename/move.\n- **Default trace altitude:** modules and public/exported surfaces must trace;\n  private internals inherit their container's justification.\n\n## A thin member — Plainweave builds none of its siblings' machinery\n\nPlainweave is **advisory by default** and deliberately thin on teeth and audit.\nIt owns the intent graph and the reasoning reads; it delegates everything else.\n\n| Tool          | Owns                                                                                                                   | Plainweave does **not** rebuild         |\n| ------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |\n| **Plainweave** | the intent graph (goals ↔ requirements ↔ SEI bindings) + the reasoning reads. Its domain: **accreted, code-grounded intent.** | —                                       |\n| **Loomweave**  | the entity catalog (what exists; public vs internal), SEI identity, the **rename feed**, and the **semantic-search engine**.   | identity/rename tracking; embeddings    |\n| **Legis**      | the **git/CI boundary surfacing**, **all graded enforcement** (advisory default; dial-up per repo via policy cells), and the **audit trail**. | enforcement engine; override/audit      |\n\nBindings reuse the **ADR-029 entity-association contract** (SEI-keyed, with\n`content_hash_at_attach` drift detection — the same pattern Filigree uses to\nbind issues to code), not a new link store.\n\n## Surfaces\n\n**Write path — authoring-time binding** (\"speak SEI at entry,\" extended to\nintent). When an agent creates or commits a module / public entity, Plainweave\noffers an inline bind: *link this SEI to a requirement* (existing or a freshly\nminted shell) and optionally *ladder that requirement to a goal*. Cheap, inline,\nattributed. Code that skips the bind is exactly what surfaces as an orphan.\n\n**Read surfaces — three composable graph primitives** (built for unanticipated\nagent use, not canned reports):\n\n- `orphans(level)` — unlinked nodes at the code / requirement / goal altitude.\n- `trace(node)` — up to goals, down to code.\n- `corpus()` — the readable dump of requirements with their code- and goal-links:\n  the artifact a curator reads to spot *\"these three are the same.\"* Consolidation\n  is **agent-driven**; Plainweave serves the substrate, not an automated verdict.\n\nOver these three sits **`coverage()`** — the self-computed *intent-coverage*\nnorth-star: the fraction of public surfaces that answer *\"why does this exist?\"*\nIt is honestly qualified in-band (namespace scoping, `denominator_complete`,\n`present_plugins`, bounded evidence) and never reports a silent clean when the\ndenominator is partial.\n\n**Boundary** — coverage facts ride out at the git/CI boundary through Legis\n(*\"this change adds N public entities bound to no requirement\"*). **Advisory by\ndefault;** any repo wanting teeth dials it up through Legis's policy cells.\nPlainweave adds no enforcement of its own.\n\n**Optional similarity hint** — Loomweave now ships semantic search, so a thin\n*\"these requirements look like the same thing\"* hint becomes **reuse of a proven\nsibling capability** rather than a from-scratch ML build. It *assists* the\ncurator; it is explicitly not a dedup engine.\n\n## Doctrine fit\n\n- **Coordinate, not gate** — advisory default.\n- **Enrich-only** — Plainweave absent → Loomweave, Legis, and the code are\n  unaffected; solo mode degrades to manual file/symbol refs.\n- **Speak-SEI-at-entry** — binding at authoring keeps code on the moat.\n- **Don't-duplicate** — Legis owns teeth + audit; Loomweave owns identity +\n  semantics.\n- **Prescribe-nothing** — a general graph + queries; agents compose uses we\n  haven't imagined.\n\n## Cross-member seams\n\nThe seams (Plainweave → Loomweave catalog/rename/semantic; Plainweave → Legis\nboundary) are **hub-blessed** and **prove-the-need**: built as additive adapters\non Plainweave's side, never pre-frozen sibling obligations until the need is\nshown live (golden vector / live consumption). Each seam ships with a\nblast-radius map + dated counterpart tickets.\n\n## Documentation\n\n- [`docs/design/2026-06-18-plainweave-permission-to-exist.md`](docs/design/2026-06-18-plainweave-permission-to-exist.md)\n  — the canonical design (\"permission for code to exist\"). **Start here.**\n- [`docs/MODULE-MAP.md`](docs/MODULE-MAP.md) — what the precursor core carries\n  forward vs. what the reframe reshapes.\n- [`docs/README.md`](docs/README.md) — index of canon vs. precursor-era docs.\n\n## Installation\n\n```bash\npip install plainweave\n```\n\nOr with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv pip install plainweave   # add to an environment\nuvx plainweave --help       # or run it without installing\n```\n\nPlainweave requires Python ≥ 3.12. Installing exposes two console commands:\n\n- `plainweave` — the CLI: `init`, `intent` (`coverage` / `orphans` / `trace` /\n  `corpus`), `req`, `goal`, `bind`, `catalog`, `criterion`, `verify`, `status`,\n  `dossier`, `baseline`, `actor`, `install`, `doctor`, the cross-member\n  peer-facts surfaces (`wardline-peer-facts`, `requirements-enrichment`), and\n  the operator `web` UI.\n- `plainweave-mcp` — the read-only MCP server that mirrors the intent reads for\n  agents (`mutates:false`, `local_only:true`).\n\nPlainweave also ships an agent skill — `plainweave-workflow` (under\n`src/plainweave/skills/`) — the federation-standard `SKILL.md` + reference sheets\nthat teach an agent the read/author/verify workflow and the doctrine invariants.\n\nQuick start:\n\n```bash\nplainweave init             # create a local store under .plainweave/\nplainweave install          # register the plainweave MCP server for agents\nplainweave intent coverage  # the north-star: how much public surface is justified\nplainweave doctor           # check store, sibling bindings, MCP surface + registration\n```\n\n## Development\n\nPlainweave uses [uv](https://docs.astral.sh/uv/), `hatchling`, `ruff`, `mypy`,\nand `pytest`.\n\n```bash\nuv sync --group dev\nmake ci          # lint + typecheck + test (coverage-gated)\n```\n\nThe runtime package depends on the official Python MCP SDK for `plainweave-mcp`.\n\n### Web UI (optional)\n\nInstall the extra and launch the operator console:\n\n    pip install 'plainweave[web]'\n    plainweave web --actor human:\u003cyou\u003e\n\nBrowse the corpus, author requirements, and ratify agent-proposed drafts and\ntrace links. Local-first, single-operator; advisory only (no release verdicts).\n\n#### Accessibility (AT gate — manual)\n\nBefore shipping the review surface, run an NVDA (Windows) or VoiceOver (macOS)\npass over the `/review` queue. Each approve / accept / reject action must:\n\n1. **Announce the outcome** via the `#sr-status` live region\n   (`role=\"status\" aria-live=\"polite\"`), e.g. \"Approved: Requirement title\".\n2. **Move focus** to the next action button in the queue (or to the \"All caught\n   up\" heading when the queue empties).\n3. **On the last item**, announce \"Queue is now empty\" and place focus on the\n   \"All caught up\" heading.\n\nStructural contracts (live region presence, skip-link, labelled search input,\nper-item `aria-label` on Approve buttons) are locked by\n`tests/web/test_a11y_contracts.py`. The focus-management and announcement\nbehaviour above require a live AT session and cannot be automated in the\ncurrent test harness.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundryside-dev%2Fplainweave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoundryside-dev%2Fplainweave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoundryside-dev%2Fplainweave/lists"}