weft
MIT · foundryside-dev GitHub

Weft suite · code-grounded intent · Python

Permission for code to exist.

Code-UP traceability: every public surface earns its existence by laddering to a requirement, and every requirement to a goal. A node with no upward edge — at any level — is a reviewable question, not an error. Advisory by default; it renders no release verdict.

Plainweave holds the team's code-grounded intent — the graph that answers "why does this code exist?" — and accretes a readable requirements corpus a human or agent can reason over and consolidate. The reframed, renamed successor to Charter: Charter was requirements-down; Plainweave inverts it to code-up legitimacy.

Python v1.0.0 snapshot — 1.1.0 (web UI) untagged; see the repo
See what it gives you → Read the repo →
$ plainweave intent orphans code
walking the intent graph → public surfaces with no upward edge…
loomweave:eid:py:exported-api:billing.export_ledger → no requirement ("why does this exist?")
loomweave:eid:7f3a9c2e1b… loomweavepartial legisunavailable filigreeabsent

What it is

Binding code to requirements accretes a living, readable corpus.

Plainweave owns a directed traceability graph: the leaves are code entities (Loomweave SEIs — modules and public surfaces), the interior nodes are typed intent nodes (requirements, strategic goals), and every edge means "justified by / satisfies." Bindings key on the SEI, so they survive rename and move. The foundational value is not catching orphan code — that is one query — it is that the corpus becomes readable: a reader can ask "why do we have three near-identical reporting requirements?" and consolidate. Requirements are trivially mintable (shells welcome); the corpus tolerates mess by design, because the value is the mess being visible and queryable, then curated.

Plainweave is a deliberately thin member: it owns the intent graph and the reasoning reads, and delegates everything else — Loomweave owns code identity, the rename feed, and semantics; Legis owns the git/CI boundary, all graded enforcement, and the audit trail. The shipped core is a stable 1.0 (green gate: lint, mypy strict, tests at ≥ 90% coverage; versioned JSON envelopes); the cross-member adapters are maturing.

Advisory only — it renders no release verdict.
Plainweave attributes; it never gates. A node with no upward edge is a reviewable question, not a block. Closed work does NOT mean a requirement is satisfied, and an agent-authored binding is not accepted human truth. This is deconfliction tooling, not security — re-derive any "compliance" shimmer as advisory intent-coverage, not authorization. Any teeth live in Legis, dialed up per repo.

Key capabilities

Intent-coverage and the graph reads — reported as honestly as they are computed.

Intent coverage is a floor, never a verdict

Coverage is the fraction of in-scope public surfaces that answer "why does this exist?" When the denominator is degraded or language-partial it is flagged in-band (denominator_complete=false, present_plugins) — never a silent clean. The meter is the point: a partial answer looks partial.

loomweavepartial legisunavailable
intent-coverage · FLOOR71%
staleness: denominator_complete = false · python only

The intent graph (SEI → requirement → goal)

A local traceability graph of intent. Leaves are code SEIs; interior nodes are requirements and strategic goals; edges mean "justified by / satisfies." A node with no upward edge is the reviewable question: a public capability with no requirement asks "why does this code exist?"; a requirement with no goal asks "what am I doing here?"

plainweave init · goal · req · bind · trace · catalog record

Default trace altitude is modules + public/exported surfaces; private internals inherit their container's justification.

Intent coverage (the north-star)

A self-computed fact: the fraction of in-scope public surfaces that answer "why does this exist?" via SEI → requirement → goal. Honestly qualified in-band — namespace scoping, surface-class filter, denominator_complete, present_plugins, bounded evidence. Never a pass/fail verdict, and never a silent clean when the denominator is partial.

plainweave intent coverage [--exclude-namespace PREFIX] [--surface-class …] [--json] · MCP: plainweave_intent_coverage

Coverage *completeness* is a documented roadmap item, not a 1.0 gate — the denominator is per-repo and language-partial.

Orphans · trace · corpus (three composable graph reads)

General graph queries built for unanticipated agent use, not canned reports. orphans(level) lists unlinked nodes at the code / requirement / goal altitude. trace(node) walks up to goals and down to code. corpus() is the readable dump of requirements with their links — the artifact a curator reads to spot "these three are the same."

plainweave intent orphans <level> | trace <level> <node> | corpus · MCP: plainweave_intent_orphans / _trace / _corpus

Consolidation is agent-driven — Plainweave serves the readable substrate, not an automated dedup verdict.

Authoring-time binding (speak-SEI-at-entry)

When an agent creates or commits a module or public entity, Plainweave offers an inline bind: link this SEI to a requirement (existing or a freshly minted shell) and optionally ladder that requirement to a goal. Cheap, inline, attributed (who bound it, when). Code that skips the bind is exactly what surfaces as an orphan.

plainweave bind sei · req (draft / approve / supersede / deprecate) · goal · trace · actor

Reuses the ADR-029 entity-association contract (SEI-keyed, content_hash_at_attach drift detection) — the same pattern Filigree uses to bind issues to code. No new link store.

Verification status, dossiers, and baselines

Derived verification status with reason codes and evidence freshness; a per-requirement dossier; immutable baselines and baseline-drift facts. The read path that lets a curator see what is satisfied, by what evidence, and how stale it is.

plainweave status · dossier · verify · criterion · baseline · MCP: plainweave_verification_status_get/list · _requirement_dossier_get · _baseline_list/get/diff

Attributes, never gates: Plainweave does not decide a requirement is satisfied merely because work closed, and does not treat agent-authored bindings as accepted human truth.

Read-only MCP surface for agents

plainweave-mcp mirrors the intent reads for agents over MCP: project context, requirement search/get, trace links, orphans/trace/corpus, coverage, baselines, verification status, entity-intent-context for peer planning, and scoped preflight-facts for Legis. mutates:false, local_only:true, no peer side effects.

plainweave-mcp (console entry point) — 18 read tools incl. plainweave_entity_intent_context_get, plainweave_preflight_facts_get

preflight-facts returns scoped facts for Legis preflight and NO governance verdict; entity-intent-context degrades to a local view when live Loomweave resolution is unavailable.

doctor + --fix (federation-parity health check)

Checks the project is configured properly — the local store/schema, the Loomweave catalog binding, and the MCP surface — with --root, --json, and a non-zero exit on unresolved problems. --fix applies idempotent in-place store repairs (init/migrate) then re-checks.

plainweave doctor [--root ROOT] [--fix] [--json]

Diagnostic only; --fix repairs the local store, it touches no sibling.

Optional operator web UI

A read-and-author mirror of the intent graph for non-CLI operators: an intent dashboard (coverage, orphans, and an in-band no-silent-clean banner), corpus browse with filters, requirement detail + authoring with current-vs-draft side-by-side and two-step draft approval, goals, and a unified review queue for drafts + proposed trace links with a required-reason accept/reject. Local-first, single-operator, advisory — no release verdicts.

pip install 'plainweave[web]' · plainweave web --actor human:<you>

Optional extra; ships in 1.1.0 (released on main, tag pending). Structural a11y contracts are tested, but screen-reader focus-management requires a manual AT pass.

Read the SEI spine on the hub — the identity Plainweave consumes, never mints →

Usage snapshot

Init, cover, find the orphan, bind it.

A curated quick-start — the full CLI and MCP reference lives under this subdomain's own paths and in the repo. Plainweave is local-first; none of these need a sibling installed (solo mode degrades to file/symbol refs). This snapshot deliberately shows a degraded state — the no-silent-clean denominator banner.

$ pip install plainweave # or: uvx plainweave --help (Python ≥ 3.12)
$ plainweave init # creates a local .plainweave/ store
$ plainweave intent coverage
intent-coverage: 0.71 (32/45 in-scope public surfaces justified)
scope: exported-api, cli-command, entry-point, http-route · excluded: scripts., tests.
[WARN] DENOMINATOR DEGRADED — not a clean: denominator_complete = false
present_plugins: [python] (Rust public surface untagged upstream)
The ratio is an honest FLOOR, not a complete score. Advisory, not a verdict.
$ plainweave intent orphans code
loomweave:eid:py:exported-api:billing.export_ledger → no requirement ("why does this exist?")
$ plainweave bind sei loomweave:eid:py:exported-api:billing.export_ledger --req REQ-204
bound (actor: agent:opus · content_hash_at_attach captured · ADR-029)
$ plainweave doctor
store: ok · loomweave catalog binding: ok · mcp surface: ok exit 0
# Agents: read-only MCP server → plainweave-mcp (mutates:false, local_only:true)

The coverage number is a per-repo snapshot, not a published suite KPI — keep a "see repo" pointer next to any figure rather than restating it as a fact. The same reads run over the plainweave-mcp stdio server (18 read tools, mutates:false).

How it composes · this member's pairings

Each pairing is honest on its face.

Plainweave composes pairwise and enrich-only — never load-bearing for anyone, and no one load-bearing for it. Status is intrinsic to each row; a partial or planned pair is never rendered as live. Actor attribution — the "who" on a binding — is a reserved future coordinate, not yet a live seam; today attribution uses Plainweave's own local actor registry.

Consumes SEI; never an authority.
Plainweave keys its code-entity bindings on the Loomweave SEI, treats it as opaque, and never mints it; it falls back to file/symbol refs when Loomweave is absent. When a sibling is absent that slot reads absent — explicitly, never an implied clean state.
Plainweave Loomweave partial

Intent bound to stable code identity — every requirement keys on the SEI.

Consumes Loomweave SEI via a catalog adapter; the intent graph reproduced on two LIVE peer catalogs (Lacuna, Loomweave), not stubs (Plainweave PDR-008). Still maturing — not yet a shipped seam: catalog public-surface tagging is degraded off Loomweave, and it falls back to file/symbol refs when Loomweave is absent.

Plainweave Legis planned

Intent-coverage available to governance — Legis owns the teeth and the audit.

Authority split designed (Plainweave attributes intent; Legis governs + audits); seam not yet shipped.

Plainweave Filigree planned

Closed work checked against intent — a closed issue is not a satisfied requirement.

Designed distinction; Plainweave does not treat work-closure as requirement-satisfaction. Seam not yet shipped.

Status & honest limits

What Plainweave is, and what it is NOT.

Admitted (PDR-0030) but pre-publish — the seams that have not shipped are not presented as working.
Plainweave is an admitted member (2026-06-24) but is NOT in the five-member launch cutover and is non-gating; its launch-grade build and live integration adapters are still maturing. Public remote / PyPI publish and the final name remain owner-reserved. Read these before you wire it in.
  • Advisory only — Plainweave renders NO release verdict. Zero allow/block decisions, zero governance verdicts. It surfaces facts; any teeth live in Legis, dialed up per repo through policy cells. This is machine-enforced: the shared contract validator rejects verdict vocabulary.
  • Coverage completeness is a roadmap item, not a 1.0 gate. The public-surface denominator is per-repo and language-partial — only languages whose Loomweave plugin tags public surface are counted (Rust is untagged upstream). When the denominator is degraded, coverage flags it in-band (denominator_complete=false, present_plugins) and never reports a silent clean — the ratio is an honest floor, not a complete score.
  • Agent-authored bindings are not accepted human truth. Plainweave attributes and surfaces; it does not ratify. It does not decide a requirement is satisfied merely because work closed. Human ratification is a separate, explicit step (the web review queue's required-reason two-step).
  • Federation adapters are maturing and non-gating. Plainweave is admitted (PDR-0030, 2026-06-24) but is NOT in the five-member launch cutover. The cross-member seams are additive, hub-blessed, and prove-the-need — validated on two live peers (Lacuna, Loomweave) so far; the federation map still reads folding-in pending a propagation pass.
  • The semantic-similarity hint is deferred, not shipped (PDR-003). Consolidation is agent-driven over the readable corpus; Plainweave ships no dedup/clustering engine and emits no consolidation verdict. Do not read similarity de-duplication as a current capability.
  • Publishing a headline coverage number is owner-gated; the real-API denominator on a live peer is currently small. Treat any single coverage figure as a per-repo snapshot, not a suite-wide KPI.
  • Public remote / PyPI publish and the final name remain owner-reserved. Version is a snapshot — v1.0.0 is the tagged stable release; 1.1.0 (optional web UI + SEI conformance, additive) is released on main but not yet tagged. Point at the repo for the live version.
  • Web UI accessibility: the structural a11y contracts (live region, skip-link, labelled search, per-item aria-labels) are locked by tests, but screen-reader focus-management and outcome announcements require a manual NVDA/VoiceOver pass — not automated in the current harness.

Read-only · advisory · enrich-only — Plainweave absent, your peers and your code are unaffected (solo mode degrades to manual file/symbol refs). Deconfliction-first, not a security or compliance product.

Links · pointers

Where the authoritative facts live.

Want to see it actually run?

Lacuna runs Plainweave against a catalogued codebase as a deterministic intent-coverage tour (PDR-010 cross-member regression harness) — orphans, trace, and the no-silent-clean denominator, end to end.

See it on the specimen → Read the doctrine →