How Pathrule proves hard claims

Pathrule's technical standard is simple: a product claim needs a bounded input, defined behavior when evidence is missing, and a result that can be tested independently.

This page collects those contracts in one place. It describes shipped behavior in Pathrule Studio, the complete product, rather than treating a lightweight MCP connection as the product boundary.

Knowledge quality has several gates

Pathrule does not put every markdown file into every prompt. Knowledge moves through independent controls:

1. Selective discovery. Active instruction files, their import chain, tool rules and decision records are distinguished from general documentation. Broad documentation is offered for review instead of being imported as live instruction by default.

2. Approval before persistence. An assistant proposes lasting knowledge. A person approves the memory, rule or skill before it becomes shared workspace state.

3. Path ownership. An entry belongs to the narrowest workspace path that owns it. Work outside that path does not receive it merely because it exists in the same repository.

4. A relevance floor. An entry still has to qualify for the current request, every time. Two quantities do two jobs and never trade places: a similarity score decides whether an entry is eligible, and a separate rank decides the order among those already eligible. Learning affects only the second. It can move a proven memory from fourth place to first; it cannot move anything from ineligible to present, because the floor is tested against the raw score before any boost is applied. Volume is bounded too: a fixed top-K, so the amount delivered does not grow with the size of the knowledge base.

   This is why disciplined authoring is not a precondition for a quiet prompt. A vague or badly written entry does not become noise; it simply never clears the bar for a request it has nothing to do with. The visible cost of a weak memory is that it does not show up.

5. Measured delivery and use. Pathrule records what it delivered and what the assistant consulted. Derived layers report when they last received data, so a quiet system can be distinguished from a disconnected one.

   The same discipline applies to why an entry was not delivered. "Nothing cleared the bar", "the ranking call timed out", "the response was malformed" and "there was nothing to rank" are recorded as ten distinct outcomes rather than one word, because they are different situations with different fixes. A ranking call that times out also trips a short cooldown instead of spending the budget again on the next prompt, and says so, so a slow moment is never mistaken for an empty knowledge base.

   When the ranking finds relevant knowledge whose body is not already on the machine, it is offered by name and id rather than dropped: about sixty characters, enough for the assistant to fetch it deliberately. Discarding a correct answer for being inconveniently placed is the one outcome that is never acceptable.

6. Reviewable maintenance. Self-audit raises stale, conflicting, unused or path-invalid knowledge as suggestions. Writes are versioned, conflicts are explicit and deletion is reversible.

These gates turn shared knowledge into a small, inspectable operating system for a repository. They are why a project can compound decisions without turning its entire documentation archive into default context. See How knowledge compounds and Suggestions and self-audit.

Studio surfaces are composable

Studio provides Chat, Tasks, Design and Signals, but it does not require every team to operate all four.

The surfaces exchange one work product instead of asking people to re-enter the same context. A design hands over intent and bindings. A prepared task carries a context receipt. A Signal creates a normal task with a runtime brief. Pure coding work can stay in Chat, Tasks, source control and the terminal.

"Optional" usually means a feature you can ignore while its instructions still take up room in your agent's context. Here it is stronger than that. Signals is stored off: the workspace preference column itself defaults to false, so a workspace that never opens the setting has it off at the data layer. And the Signals instruction block is not assembled at all unless the preference is on, so a coding-only team's agent is never given it. No prompt text, no tokens, nothing competing with the instructions that team does care about. Chat is the surface a session resolves to by default; Design and Tasks are places you go, not stops on the way.

Parallel work has two safety layers

Before Run All starts, Studio predicts which files each group is likely to touch. Known file collisions are merged into one sequential lane. Groups predicted to be independent run in separate git worktrees.

The worktree is the second safety layer. If prediction misses a later file, two agents still do not overwrite one folder. Their changes remain separate branch work, and landing stops on a real merge conflict.

Studio also treats worktree storage as an engineering concern:

• When lockfiles match, it borrows the prepared dependency tree instead of installing another copy: cloned into the new checkout where the filesystem shares blocks, symlinked where it does not.
• When sharing is not safe, it states the detected install command and runs it only after consent.
• A clean provisional checkout that was armed but never claimed is swept after an age guard.
• A landed checkout is reclaimed too, once a grace period has passed, nothing is running in it, git reports it clean and Studio created it. Its branch is never deleted automatically.
• Landing is recognised from Studio's own merge record, which covers a squash merge, and independently by asking git whether the branch is already contained in its base, which covers a merge performed outside Studio. A state git cannot determine never authorises removal.
• A checkout holding an uncommitted change, one a live conversation is still running in, and one adopted from outside Studio are never removed automatically.
• After a successful landing, Studio also offers to remove the checkout immediately.
• All Studio-created checkouts live under one configurable home outside the repository.

The cost of isolation is measured, and the usual instrument is wrong

"Parallel agents plus a large monorepo means disk fills up" is the reasonable expectation. Measured on Pathrule's own monorepo it is false, and the reason is worth following, because the instrument almost everything reports is the one that gets it wrong.

Two instruments were run on the same checkout (macOS, APFS, pnpm with a warm store, August 24 2026):

A directory walk overstates a prepared checkout by about 15x. Copy-on-write is why: pnpm imports packages from its global store as APFS clones, so those bytes exist on disk once while every clone reports its full size to anything that walks files. A controlled check isolates the mechanism: cloning a 296 MB tree changed free space by 0 MB while a walk reported 296 MB.

So a checkout decomposes into three parts that scale differently, and only one of them is ever large:

The dependency figure is a property of the package manager, not of the disk, and measuring a second repository is what established that. On the same machine and the same volume, an npm project's tree cost 684 MB to install where the pnpm one cost 9 MB: the filesystem could share blocks in both cases, but only one package manager asked it to.

Studio closes that gap rather than reporting it. When the lockfiles match, it gives the new checkout its own dependency tree by cloning the prepared one, which on a copy-on-write filesystem costs 17 MB for a 45824-entry tree instead of the 684 MB an install costs. The clone is verified, not assumed: every entry present, relative .bin symlinks intact, binaries running from it, and a write inside it leaving the original untouched. That last point is the reason cloning is preferred over symlinking a shared tree, which costs nothing but means an install in one session reaches every other one.

The result is the same shape for both package managers:

Whether the disk can share blocks is measured rather than assumed, because the usual signal is unreliable: a clone-preferring copy onto a filesystem that cannot clone performs a full copy and still exits successfully. Studio writes a small probe, reads the volume, and treats an unreadable answer as unknown, which falls back to sharing the prepared tree and says "shared" in the consent line. Every create and every removal is measured the same way, and a reading that cannot be separated from other disk activity is recorded as "not measured" rather than as a zero.

Divergence, not dependencies, is what grows an isolated checkout: once an agent builds, shared blocks are rewritten into real bytes, and build outputs in this repository's main checkout measure about 343 MB.

See Isolated branches.

Task preparation produces a receipt

Auto plan is a bounded, read-only planning pass for one card. It produces a goal, ordered steps, a test path and risks. If a person-only fact is missing, the card moves to awaiting reply instead of completing a plan from a guess.

Context preparation is a separate gate. It fingerprints the current card revision, resolves target paths and relevant project knowledge, and records material dependency or conflict gaps. The run receives that receipt only while it still matches the card. A later edit invalidates the stale receipt. If the bounded model pass fails or times out, preparation falls back to deterministic context rather than waiting indefinitely.

Together with collision grouping and worktree isolation, this makes the board an execution surface with explicit preparation state, not a visual wrapper around a prompt. See Board settings.

Component and token bindings fail closed

Project component discovery is bounded and read-only. It inventories exported contracts without executing application code, supports React, Vue, Svelte, SwiftUI and Compose, and respects configured include, exclude and import-path boundaries.

A design component becomes a code binding only when the evidence is unique and compatible:

Platform isolation is structural rather than a later check: candidates are filtered by framework before scoring, and each component gets a separate binding per platform. A SwiftUI view is never a candidate for a web target, so a cross-platform binding is not rejected late, it is never constructed.

If those checks do not support one answer, the result stays unmapped or ambiguous, carrying a reason, the confidence and up to three named candidates so a person can resolve what the machine would not guess. It also carries an empty prop map and no code component, which is the part that makes abstention safe rather than merely honest: a partial prop map on an unbound component reads as a usable answer while putting real prop names against the wrong component.

Abstention with no instruction would relocate the problem into a stuck agent, so the handoff prompt says what to do instead: never invent an import, prop, token or glyph, and implement an unmapped component locally while preserving the visual contract.

This is why a hard repository, legacy or otherwise, does not produce a worse binding. It produces no binding, named as such, with the candidates it considered.

Two consequences of that design are worth making explicit, because they are decisions rather than side effects. Where two same-named components are genuinely distinguishable by their prop contract, the better match wins: that is the intended behavior, and where they are not distinguishable the result stays ambiguous for a person to settle. And option identity is verified wherever the code side declares typed options, which is what makes an enum mismatch a blocking condition rather than a runtime surprise.

What this contract guarantees is precision: a binding is emitted only on unique, compatible evidence. How often a given repository yields one is a question about that repository's own naming and typing, and is measured separately.

Token bindings have a separate contract. Library identity, token identity, variable name, mode and property scope must agree. A fill token cannot silently become a text token, and an invalid proposal remains diagnosable instead of being mistaken for a successful cleanup. See Design to code.

Design correctness is not one score

Studio checks different kinds of evidence independently:

1. Readiness reports attached systems, literal values, repeated structures and connected flows. Unknown evidence remains unknown instead of being reported as a clean zero.
2. Binding integrity checks component contracts and token identity before code generation.
3. Kernel lint reports exact design-system drift, such as a literal value where an exact token exists, while staying silent when the system has no exact answer.
4. Runtime fidelity compares the real web DOM or native accessibility tree against design structure, text, visibility, position, size, color and typography.
5. Confidence controls blocking. A pairing is made on one of three bases with a fixed confidence: node identity (1), matching text (0.7), or role and position (0.4). Anything below identity is a guess, is reported as one, and its findings are filed where they cannot gate a merge. So a wrong guess costs a low-confidence note, never a false blocking failure. Findings on a design node nothing implemented and on a rendered node the design does not describe, usually platform chrome, are also kept apart rather than summed, because one is a gap and the other is normal.
6. Flows execute against the app. Connected prototype actions become simulator actions and are checked against the authored navigation graph.

The result is a set of narrow, diagnosable gates. A clean token check does not hide a structural mismatch, and a guessed node pairing cannot produce a false blocking failure.

The report is four separate buckets rather than a score: what blocks, what is advisory, what rests on a guessed pairing, and the single worst remaining delta to watch across iterations. Findings arrive worst-first, and structure is ranked above geometry because a missing node explains every geometric symptom underneath it. An agent that fixes only the head of the list and re-runs therefore converges instead of chasing symptoms. This is what makes depth useful here: the design side is a comparator with typed outcomes, so more precision means more certainty about which difference matters, not more surface to get wrong. See Verifying a design.

Signals is proposal-first and optional

Signals is disabled until a workspace enables it. The first setup turn performs a focused read-only scan and proposes one initialization point plus a small set of high-value observation points. A person reviews that proposal before any code changes.

After approval, Studio vendors a dependency-free SDK and writes only the approved points. The SDK uses bounded queues, coalescing, redaction, retry backoff and failure isolation. It does not require users, sessions, funnels or a third-party analytics account. See Setting up Signals and How Signals works.

Dated verification

On August 23, 2026, 195 focused automated checks passed in the main Pathrule product repository. They covered:

• Knowledge discovery, import ordering and exclusion of noisy sources.
• Worktree setup, dependency sharing, lifecycle and dirty-checkout protection.
• Task context fingerprints, stale receipt rejection, bounded preparation and deterministic fallback.
• Component discovery, configured boundaries, platform isolation and incompatible variant rejection.
• Token identity, mode and property-scope validation.
• Design readiness, structural and paint fidelity, exact and heuristic identity, and native-tree degradation.
• Signals queue bounds, coalescing, redaction, backoff and failure isolation.

The public context-delivery benchmark is separately reproducible at github.com/pathrule/benchmarks. How we measure publishes its method, raw artifacts and mixed results.

A useful evaluation rule

For any Pathrule claim, ask three questions:

1. What evidence enters the decision?
2. What happens when that evidence is missing or ambiguous?
3. Which result is allowed to change or block the work?

The contracts above answer all three. That is the difference between a feature description and an engineering claim.