Blueprints

design records: the process, every proposal and every plan

on this page

matra's design records, and the process that says which record a change takes. Blueprints holds the proposals and plans the owner and Claude converge on. The process follows the Rust RFC process. Two kinds of record live here.

KindWhereCited asWhat it records
Enhancement proposalproposals/NNNN-name.mdEPR-NNNNA substantial change that matra's users notice: the decision, what and why, laid out with the Rust RFC template.
Enhancement planplans/NNNN-name.mdEPL-NNNNA plan for work that several agents carry out in parallel. Rare: work done in sequence is a tracking issue instead. Laid out with the Rust RFC template, with its milestones, test plan, ship criteria and risks under Reference-level explanation and a status log after it.

A new series, from 2026-10-04. That day is the baseline: proposals and plans are numbered from 0001, and each kind has its own sequence. The records written before it, the RFCs and the EPs, are in legacy/ unchanged: they are the reasons behind the code that exists, and a comment or a page that cites RFC-NNNN or EP-NNNN means one of them. They are not rendered on the docsite and not counted here. A new proposal that changes what a legacy record decided says so and cites it; the legacy record is not edited.

Awaiting you

Decisions waiting for your ruling, in dependency order, then assumptions to confirm or strike.

16 open decisions across 5 proposals, then 11 assumptions to confirm.

Decide

The process

Which record a change takes

The grain follows the Rust project's: the bigger the change and the more of matra's users who notice it, the heavier its record.

ChangeRecordWhere it lives
A substantial change matra's users notice: the public surface in Rust, Python, the command line or the JSON schema; semantics or behaviour, the default model included; removing or deprecating a substantial feature; an architecture boundaryEnhancement proposalA pull request adding proposals/NNNN-name.md
A minor addition to the public surface, or a minor removal from itAPI change proposalA short issue labelled acp
Tooling, docs, CI, the harness, a refactor, a measured performance improvement, a bug fixNone beyond the pull requestThe pull request. A rule it leaves behind lives in the file that governs it.

An API change proposal is enough when the change adds or removes one item a caller may use and changes nothing about what the existing calls do or return. A change to what an existing call returns or means, or one that reshapes several items at once, is an enhancement proposal. When in doubt whether a change needs a record at all, ask whether a caller of matra would notice it: if not, the pull request is the record.

A change to this process is tooling too: a pull request that edits this file, with the reason in its description.

Enhancement proposals

A proposal is a pull request. Copy proposals/0000-template.md to the next free number, fill every section, and open a pull request with the proposal alone or beside the code it binds, labelled epr. Discussion happens there.

A proposal can merge before it is accepted. Its status line then reads proposed, and the docsite renders it, so the owner can read it in place and comment on it before deciding. Claude may merge a pull request that adds or edits a proposed proposal, on the same standing authority as any other pull request. A proposed proposal decides nothing: no code may rely on it.

A ruling is recorded, never inferred. The owner answers a decision in a comment, on the page or on the pull request. A comment is the event: by itself it changes nothing on the record. Claude then records the ruling in the proposal as a named step, a <ruling> in the decision with the owner's response and its date, in a pull request whose description names the comment it transcribes. The ruling in the record is the standing state, and it is all the docsite reads: the frame, the navigator and the queue never read comments to decide whether a decision is open, so a quiet thread never reads as assent. An assumption is confirmed or struck the same way: Claude changes the claim's basis, or removes the claim, citing the comment. The queue under Awaiting you is drawn from the proposals' components, never from their prose, so a decision leaves it when its proposal records a ruling, and an assumption when its claim is confirmed or struck.

Only the owner accepts a proposal. Acceptance is a change of the status line to accepted, and only the owner merges a pull request that makes that change, whether it is the proposal's first pull request or a later one. Claude writes proposals, argues for them and merges them while they are proposed, and never merges a pull request that sets a status to accepted. A proposal the owner declines leaves main: the pull request that removes it says why, and its number is not reused.

Each accepted proposal has a tracking issue. It is labelled tracking, opened from tracking.md when the proposal is ready for the owner's decision, so the proposal's Tracking issue header can link it before acceptance. It carries the milestone checklist and links each pull request that delivers a milestone, and it closes when the work ships.

A proposal is not rewritten after acceptance. Two edits are allowed: the status line, and a dated note directly under the header saying what changed and why. A change of mind is a new proposal that supersedes the old one, and the old one's status then reads superseded by EPR-NNNN. While it is proposed, a proposal may be edited freely; its pull requests are its history.

API change proposals

A minor change to the public surface is an issue, opened from api-change-proposal.md and labelled acp: the item, what a caller writes with it, and why it is minor. Only the owner accepts one, by saying so on the issue. Claude writes and argues them, and never accepts one. The pull request that carries an accepted proposal out links the issue and closes it.

Enhancement plans

A plan exists only when several agents execute one plan in parallel. It says who carries which milestone, in what order, and what each hands the next. Work carried out in sequence, however many pull requests it takes, needs no plan: the proposal's tracking issue holds its checklist. Copy plans/0000-template.md to the next free plan number and fill Implements, which is none when the parallel work implements no proposal.

A plan is laid out with the Rust RFC template, as a proposal is. The plan itself is part of the reference-level explanation, as its subsections: the milestones, the test plan, the ship criteria, and the risks. The status log follows the sections. A plan that implements a proposal keeps its Motivation and Guide-level explanation to a few lines and a link, because the proposal holds the argument.

A plan is living until it ships. If a milestone turns out to be ambiguous, the plan is the bug: edit the plan first, then the code. Every change of status adds a dated line to its status log. Once it ships or is dropped, it is kept as the record of how the work went.

Status

KindStatusMeaning
ProposalproposedMerged for review; the docsite renders it. Not a decision: nothing may rely on it. Claude may merge it.
ProposalacceptedThe owner merged the change of its status line; the decision is in effect.
ProposalimplementedAccepted, the CHANGELOG records it shipping, and its tracking issue is closed.
Proposalsuperseded by EPR-NNNNA later proposal replaced it. Kept unchanged apart from the status line and a dated note.
PlanplannedWritten, not started.
Planin progressAt least one milestone has landed.
Planshipped in X.Y.ZEvery milestone landed, and release X.Y.Z carries the work.
PlandroppedWill not be carried out as written. The status log says why.

On the docsite

The docsite has three areas: Docs, the pages for matra's users; Blueprints, this file at /blueprints/ and each proposal and plan at /blueprints/proposals/<name> and /blueprints/plans/<name>, read from these files at build time; and Lab, for evals and experiments. Blueprints is the one area that shows a status: each record's, read from its header, beside it in the navigation and in its frame. The pages in Docs describe what ships and carry none.

Docs and Blueprints are two stances on one identity. Docs is the observe stance: a reader learns matra there and changes nothing. Blueprints is the collaborate stance: the owner and Claude work a record there until the owner rules. Only the chrome changes; the colours and their roles, the type, the grid and the reading face are the same. Each proposal and plan has a frame above it, drawn from its header and its components and never from its prose: its kind, id and title, its status, how many of its decisions are settled, how many assumptions wait to be confirmed, the commit it was read at, and its pull request and tracking issue. Beside it, or on a phone in a sheet from the frame and inline under the title, a navigator in three groups: Read (the sections), Decide (each decision, its state, and the order the decisions depend on one another) and Confirm (each assumption, and the decisions that rest on it). What awaits the owner's touch, an open decision or an assumption, is marked in Spark; a decision the owner accepted, in Emergence; each mark is a glyph and a word. A link from a record to a file outside the rendered records leads to that file on GitHub, on main, except a citation of lines, which opens at the commit the record was read at (below).

Reading a proposal

A proposal is Claude's understanding of the code, its history and the owner's intent, written so the owner can check it and answer it. Its parts are components the docsite draws, each a tag in the Markdown, so they read the same in the file and on the site. site/README.md ("The Blueprints components") gives their syntax and the research behind each.

The anatomy. A proposal follows the template's order, and each section has a role the navigator names: the orientation (the masthead, the Summary, the pragmatics block and what changed), the case (Motivation through Rationale and alternatives), the queue (the decisions under Unresolved questions, and the assumptions), the references (Prior art, and every chip), and the margin, where comments land. Future possibilities has no role; it equips no decision.

The header at the top of the file gives the start date, the commit the proposal was read at, who decides (the owner), and the pull request and tracking issue. On screen the frame shows each of these; in print they are a masthead under the title.

The pragmatics block follows the Summary: the ask, what Claude will do if the proposal is accepted, what it needs from the owner, what it will not do, and what happens if nobody answers. Silence is not assent. The owner's answer to a proposal or to one of its decisions is one of four: accept, accept with a reservation, object, or redirect.

A claim that the proposal rests on carries its basis, a word and a glyph, and chips that open its grounds:

GlyphBasisMeaning
●observedClaude read it or ran it; a chip points at the evidence.
◐inferredReasoned from observed claims; the reasoning is written out.
○assumedNo grounds yet; the owner should confirm or strike it. The assumptions are also collected in one list.

A chip to code opens the cited lines at the commit in the proposal's Pinned at line, never at main, so the evidence cannot move under the claim. The build reads those lines at that commit and fails when they no longer hold the text the citation names. A check that a model made, a reading, is said to be one; a test or a compiler is a different kind of evidence, and several readings by Claude agents count as one source, not several.

Likelihood

A claim about what will happen, and only such a claim, may carry one word from this closed list, whose meaning is the range beside it (the bands of US Intelligence Community Directive 203). A proposal never puts a number on its own confidence.

WordMeans
almost no chance1 to 5%
very unlikely5 to 20%
unlikely20 to 45%
roughly even chance45 to 55%
likely55 to 80%
very likely80 to 95%
almost certain95 to 99%

A decision block sets out the options, Claude's recommendation apart from them as a judgment, the strongest case against it, and the owner's decision once made. Each decision also says three things the build checks. How readily the recommended choice can be undone once carried out (reversible): □ reversible, ◧ costly to reverse, or ■ irreversible. The decisions it depends on (depends), so the navigator and the queue show them in order. And the claims and assumptions it rests on (grounds), each linked from the decision and linking back to it, so a reader goes from a decision to its grounds and from an assumption to every decision on it. The build fails on an id that names nothing on the page, on a dependency cycle, and on a decision without reversible. Where the decision's own text does not settle its reversibility, the value rests on an assumed claim among its grounds, for the owner to confirm. What changed in my understanding lists, on a revision, what Claude understood before, what it understands now, and what changed it.

A sketchy diagram means proposed. Structure drawn with a hand-drawn line is what the proposal would build, not what ships; structure drawn crisp ships, at the commit the proposal was read at. Every such figure says so in its legend and in words, and carries the structure as a table under "show the data". Sketchiness is never used for numbers.

The legacy records are not rendered. Their old addresses, /blueprints/rfcs/<name> and /blueprints/eps/<name>, still answer, each with a short page that links the record on GitHub.

Locally, the docsite is also where the owner and Claude converge on a record: in just docs-serve, text on any page can be selected and commented on, and the threads are files in discussion/ that any session reads (just comments) and Claude answers in (just comment-reply). The published site has no local comments; giscus is its public channel. site/README.md describes both.

Numbering

Numbers are four digits and zero-padded, and each kind has its own sequence from 0001. A number whose record was merged to main is never reused. A number taken by an open pull request is that pull request's until it merges or closes.

Checks

scripts/check-blueprint-refs.sh runs from just check and in the Docsite floor CI job. Every citation in the tracked tree must resolve to a record of its own kind: EPR-NNNN to a file in proposals/, EPL-NNNN to one in plans/, RFC-NNNN to one in legacy/rfcs/ and EP-NNNN to one in legacy/eps/. A citation whose number exists only as another kind is named as a wrong-kind citation. Every file in proposals/ and plans/ must have a row below. The docsite floor's em-dash gate covers this directory too.

Proposals

The enhancement proposals since 2026-10-04. On the docsite each is a card with its status and its open decisions; the table is the same index.

Baseline. EPR-0001 to EPR-0005 describe matra's foundation as it stands at the commit each one names on its Pinned at line, and carry forward the reasons from the legacy records that still hold, with what no longer does. A later proposal that changes one of them says so and cites it. The legacy records about the process (RFC-0001, RFC-0019) and the docsite (EP-0012, EP-0013) are not carried into a proposal: under this process that work is tooling, and its rules live in this file and in site/README.md.

  1. EPR-0001 proposed

    The pipeline and its ports

    matra is one crate whose surface is one pipeline.

    0 of 2 decisions settled
    1 assumption to confirm

    pinned at 4fcfb4a · pull request #133 · no tracking issue

  2. EPR-0002 proposed

    The data model

    Everything matra hands back is a type in src/domain.rs, which depends on serde, thiserror and std and nothing else.

    0 of 2 decisions settled
    1 assumption to confirm

    pinned at 4fcfb4a · pull request #133 · no tracking issue

  3. EPR-0003 proposed

    Distribution and provisioning

    matra ships as one crate on crates.io and one package on PyPI, under one name, one version and one attribution.

    0 of 2 decisions settled
    3 assumptions to confirm

    pinned at 4fcfb4a · pull request #133 · no tracking issue

  4. EPR-0004 proposed

    The command line, configuration and the agent skill

    There is one matra command line, written in Rust as the library module matra::cli, whose whole surface is cli::run(args, out, err) -> u8.

    0 of 2 decisions settled
    1 assumption to confirm

    pinned at 4fcfb4a · pull request #133 · no tracking issue

  5. EPR-0005 proposed

    Embeddings and semantic clusters

    matra can group a document's sentences that say the same thing in different words.

    no decisions
    1 assumption to confirm

    pinned at 4fcfb4a · pull request #133 · no tracking issue

  6. EPR-0006 implemented

    The 0.3.0 surface

    0.3.0 settles matra's public surface once, as one design, before a TypeScript surface copies it.

    6 of 8 decisions settled
    2 assumptions to confirm

    pinned at 6e9d94b · pull request #134 · tracking issue #161

  7. EPR-0007 proposed

    TypeScript and WebAssembly

    matra gains a TypeScript package for the browser and Node.js.

    0 of 8 decisions settled
    2 assumptions to confirm

    pinned at 4cac941 · pull request #190 · tracking issue #193

the index as a table
ProposalTitleStatusTracking issue
EPR-0000The templatenot a recordnone
EPR-0001The pipeline and its portsproposednone
EPR-0002The data modelproposednone
EPR-0003Distribution and provisioningproposednone
EPR-0004The command line, configuration and the agent skillproposednone
EPR-0005Embeddings and semantic clustersproposednone
EPR-0006The 0.3.0 surfaceimplemented#161
EPR-0007TypeScript and WebAssemblyproposed#193

Plans

The enhancement plans since 2026-10-04. None yet.

No plans yet.

the index as a table
PlanTitleStatusImplements
EPL-0000The templatenot a recordnone

Legacy

The records written before 2026-10-04, in legacy/rfcs/ and legacy/eps/, cited as RFC-NNNN and EP-NNNN. Records cited as ADR-NNNN before 2026-09-24 are the RFC of the same number, and iteration plans cited as iN are the EP of the same number where one exists. One RFC number appears in them without a file:

Legacy numberWhy it has no file
RFC-0016Reserved for release automation by a pull request that never merged.