Repository Checks

The checks that read the whole repository rather than one package's code: its docs, its dependencies, its boundaries and its releases. Most are Rust tests that run with cargo test --workspace and can also run alone. Shell and website checks use their own tools below.

Run them

Both packages hold every check but the shell scripts', and run with the workspace's tests; run them alone with:

cargo test -p link-repository-check
cargo test -p link-docs-check -p link-docs-check-code

The docs and the layers

Each check below says what it enforces, what it reads, and how to run it alone. These read the docs and the manifests.

Docs

Every rule in Writing Docs: links, shape, limits, history, commands, specs. It reads every Markdown file, limits.toml and large-files.toml: cargo test -p link-docs-check.

The commands and spec keys pages give exist, read from every page with Link's own parsers: cargo test -p link-docs-check-code.

Layers

Each crate depends only on its own group or the groups its layer.toml lists (Layout), read from every Cargo.toml and layer.toml: cargo test -p link-docs-check.

Layer words

A lower layer never names a higher layer's concepts. A layer.toml declares the words its layer introduces (words = ["agent", "team", "harness"] for the agents' layer), and no file git tracks in a layer it is built on, directly or through another, says one: not in an identifier, a file's name, a TOML key, an error's text or its docs. A word matches as a whole part of a name, singular or plural, in any case and however the name is joined, so for_agent, AgentAt, AGENT_KIND and agent.toml all say agent.

Held words

What lower layers said when the rule came in is counted by file and word in layer-words.toml beside the check, which may shrink, never grow, as large-files.toml does. A part that needs a higher layer's knowledge asks a question in its own types instead (Layers). Each workspace runs it on its own roots: cargo test -p link-repository-check layer_words::.

Dependencies

What every locked crate and npm package must be: licensed, at one version, published by someone trusted, and free of advisories.

Licenses

Every crate of the lock file is permissively licensed, read from cargo metadata for every platform: cargo test -p link-repository-check dependencies::every_crate_is_permissively.

One version

A crate locked at two versions is listed under [workspace.metadata.second-versions] with why, and a listed crate is still at two, read from Cargo.lock and Cargo.toml: cargo test -p link-repository-check dependencies::every_crate_is_at_one.

Trusted publishers

Every crate has an owner under [workspace.metadata.trusted-owners] or a million downloads, every npm package an owner under [workspace.metadata.trusted-npm-owners] or 100,000 downloads a week, and none calls itself unofficial or comes from elsewhere than its registry. It reads Cargo.lock, every package-lock.json git tracks, Cargo.toml and trust.toml: cargo test -p link-repository-check dependencies::every_crate_is_from.

Trusted trees

A lock file under [workspace.metadata.trusted-npm-trees] is trusted whole, with why: its packages pass for its root's sake, for a tool nothing Link releases or runs reads, installed only to work on it. That never trusts their authors elsewhere: a package locked in any other lock file too must pass on its own, and advisories apply to every one.

Advisories

The same test checks that every advisory against a locked version, an unmaintained crate's among them, is listed under [workspace.metadata.advisories] with why, and that every listed one still applies.

Code and the repository

Where code may reach, which keys sign, and what a release ships.

Boundaries

The sandbox contract reaches no implementation, the default build no connection, neither it nor Link Memory a document parser, and the harness and HMAC code stay in their owners, read from cargo metadata and source files: cargo test -p link-repository-check architecture::. Implementation libraries can be inspected by declared fixtures beneath tests/; production consumers still use the sandbox contract.

Releases

One line for Link's signer everywhere it's trusted, no workflow sets a build kind, and no committed file holds a staging or dev build's key, read from install.sh, the relay's bootstrap.sh, the workflows and every tracked file: cargo test -p link-repository-check release::.

What a release ships

Every member ships. Cargo's program declarations determine the documentation inventory, as they do the archives lnk bundle selects. Every declared component also appears in the registry: cargo test -p link-repository-check released::.

Private state

Link-owned hidden state belongs under Hidden, ~/.lnk. Home, ~/Link, contains no persistent Link-created hidden files or folders. The check reads production Rust path declarations and paths written in docs, scripts and settings. Native third-party paths and test fixtures have their own ownership. Adapter paths are recognized beneath any workspace root; arbitrary runtime arithmetic still needs review.

Temporary security probes

The sandbox check's temporary native probes are the explicit exception to the visibility rule. The check removes the probe files it creates; persistent bookkeeping still belongs in Hidden.

Files and folders too

Hidden child names and hidden staging names are refused outside Hidden. Atomic writes use visible temporary siblings from the shared Rust path API, preserving same-filesystem renames. The catalogue validates every Home location. cargo test -p link-repository-check state_roots:: runs these checks.

Saved files name their schema

Every file Link saves names its schema version (Saved Files), written through link_files::saved. Outside test code, a function that writes a file and serializes a bare toml::to_string or serde_json::to_vec fails, whether the text reaches the write at once, through a variable or across lines: cargo test -p link-repository-check saved::.

What writes a file

A function writes a file when it calls write_private or fs::write, or opens one with OpenOptions, File::create or create_new. A write_all alone writes to whatever it's given, so a message sent on a stream passes, as does a value serialized only for a sha256. Only a file's test module is left out, never what follows a #[cfg(test)] on another item.

Allowed and held writers

saved.toml allows a file whose writes are another program's format, a run's own runtime file, a build's output or a test's fixture. It holds a file until its owner declares its schema, a list that only shrinks.

Ledger lines name theirs

A bare line appended to a ledger fails the same way: a function that opens a file with .append(true), or calls an append, serializes nothing bare. A ledger's line is written with link_files::saved::line instead.

Saved formats say where their files are

An upgrade converts each file of state it finds (Upgrades), so every saved format's schema.toml lists its [[files]], or declares holds = "history" for a record of what happened. A format is a link_files::specification!, or a Format::shipped, naming its schema.toml outside test code. placed.toml lists the formats still unplaced, each with why, a list that only shrinks: cargo test -p link-repository-check placed::.

Tests keep to the testing kit

Where Clippy can't see a pattern, this check reads it from the source, each rule a pattern and what to use instead, from the package's test_kit module, which can run on any workspace's root: cargo test -p link-repository-check test_kit::.

The rules

Every file is read for a skip printed and returned, an LNK_REQUIRE_* variable read outside the kit's gates, and a port found free by binding 127.0.0.1:0 and letting it go. A test's code is read for an #[ignore] that says no reason, an assertion on elapsed(), a loop that sleeps until something holds, a change to the test process's environment, a folder made in the temp folder or /tmp by hand, and a program made runnable by hand. Comments are left out, and a pattern over several lines is read whole, however rustfmt splits it.

Runtime folders

A test's code is also read for a child's environment cleared (env_clear()) with no XDG_RUNTIME_DIR given by the end of its statement, whose sockets would be in the machine-wide runtime folder.

The lists that only shrink

test-kit.toml lists, under each rule's name, the files that still break it. A list may shrink and never grow: a file that keeps the rule must leave it, and a rule with no list is refused everywhere. Its [promises] left counts the raw calls that say they move onto the testing kit, and may only go down.

Every test program has a home

Each program Cargo builds for cargo test, a library's, a program's or an integration test's unless it says test = false, holds link_test_kit::home!(); at its root, from cargo metadata. Without it, its tests find Link's folders in the account's real ~/.lnk and ~/Link, and the check fails naming the root and the macro (A home for each test program).

Flakes written down

A flaky test a session met in a test it didn't write or change is in flakes.toml beside this check, never fixed on the way: its package, its whole test path, the day and commit it failed on, how it ran and what it said. Each entry names a package of this workspace and gives every fact, so a session given the list can reproduce it: cargo test -p link-repository-check flakes::.

Ready-made agents start blank

Each ready-made agent in agents/ keeps a Home, its files folder, that an owner fills by talking to it. A Home holds only headings, table headers and empty fields, so the agent never takes an example for its owner's data: cargo test -p link-repository-check ready_mades:: (Blank Until You Speak).

What a Home may hold

In every Home, a CSV file holds its header and no row. A Markdown file holds no list item, no table row below its header and separator, and no key: value line with a value, HTML comments aside. A TOML file holds only empty strings, zeros, false and empty lists. A Home's guides, its README.md files, describe the others and are not read. ready-mades.toml says where each Home is and names the guides.

The tools each comes with

Each ready-made agent's tools are pinned in ready-mades.toml: the tools its spec turns on ([behavior.tool.<name>] enabled = true), the programs its sandbox file allows and the tools that file names. A ready-made whose files say otherwise fails, and so does one with no pin or a pin with no ready-made, so what an agent comes with changes only on purpose: cargo test -p link-repository-check every_ready_made_ships (Personal Agent Tools).

Shapes come from declarations

A command's arguments and a spec's shape are declared in TOML, a module's actions.toml and types.toml, and generated into Rust, so no Rust type is the source of a shape (Generation). The check, cargo test -p link-repository-check shapes::, reads every Rust file but test code and Cargo examples, programs run by hand with cargo run --example that Link never releases or runs.

What it refuses

It refuses a hand-written clap argument type (#[derive(Parser)], Args, or Subcommand), a clap choice type (ValueEnum, derived or written), whose choices types.toml declares as an enum, a link_spec::typed inventory of one, and a hand-written Specification impl. It also refuses a JSON Schema derived or written for a Rust type (schemars::JsonSchema), the schema an editor or a tool checks a file or a call with. A derive spread over several lines is read whole.

What may still write one

shapes.toml names three lists, each entry with why. Its allowed are the generator's own shared shapes, which every generated parser takes, such as core's uninstall flags, the machinery that writes or reads them, and a third party's format, such as libtest's selection flags, which no declaration owns. Its held are the files still writing a shape in Rust until their module is declared: the list may only shrink, and a held file that writes none any more is refused until it leaves the list.

Rust types a declaration names

Its rust list names each types.toml that names a Rust type for a part of a hidden argument's payload the format can't say yet (x-link-rust). A declaration naming one off the list is refused, and so is a listed one that names none any more, so the list only shrinks.

Manifests

Two rules read only the workspace's manifests and targets, and any workspace runs each on its own root.

Program names

Every program the workspace builds is lnk or lnk-<name>, whatever builds it: a module, a fixture or a tool run by hand. The rule reads each binary target cargo metadata lists: cargo test -p link-repository-check program_names::. A package keeps its own name, and a module is what its module.toml declares, never a program's name alone.

Lint levels

Each workspace's Cargo.toml sets its lint levels under [workspace.lints], and every member's manifest takes them with [lints] workspace = true and sets none of its own, so a new package can't skip them (Conventions). It reads only the manifests, from the package's lints module, which any workspace can run on its own root: cargo test -p link-repository-check lints::.

Code for older versions

No code is kept for an older lnk, module, file or name. Function code reads and writes only the current shape; support for an older one is declared data in one migration channel (the migrations skill). A tracked source file (Rust, TypeScript, shell, Python, workflow or SQL) whose lines say what such support says of itself is listed in legacy.toml with at least as many such lines. What it lists is current: a vendor's word, a standard's or a feature's own. The list may shrink, never grow: cargo test -p link-repository-check legacy::.

What it looks for

Support names itself in a few ways, each matched in any case.

  • An older shape kept: "from before", "legacy ", "older than", "migrate from", "backward compatibility", "deprecated" or "compatibility shim".
  • An alias: a serde field's or a clap command's or flag's alias, aliases, visible_alias or visible_aliases, however the line is spaced.
  • An old-path fallback: a file looked for at its "old location", "previous location" or "previous path", or code that "falls back to the old" one.
  • A format sniffed: a format told apart by its bytes rather than its schema, as "sniff the format", "guess the format", "either shape" or "both shapes".

Migration wording

A schema step whose change needs code names a migration, which lives in its owner's migrations/ folder and nowhere else. Outside such a folder, a line that names one or says its words fails the check, and no list admits it. The check finds "migration code", "schema migration", a path through migrations::, a "migrated" value, spec, file or shape, and "supported for an older" shape. It also finds a migration's name, a kind and its schema joined by _to_ to the next one. Declaring the folder with mod migrations; says none of these.

Moving agents

Moving an agent between harnesses is a current feature. Its command and test names do not identify code kept for an older file format. The explicit phrase "migrate from" still identifies that older-format code. Protocol refusals, wrappers, release-role labels and commercial plan names do not by themselves identify an implementation retained for an older format.

One verb per meaning

Every command's last word is a lifecycle pair, list, show, check, run, or one of verbs.toml's [[allowed]] words, each group with its reason; a banned word (give, take, new, forget, cancel, allow, deny and the like) fails, so does a flag that spells one (--dry-run is --dry), and so does a group with create and remove but no delete (or add and delete but no remove).

Where the commands come from

The commands are each module's declared ones (its actions.toml), hidden ones included, and for a module with none, the variants of its Rust Subcommand enums. verbs.toml's held lists commands still to be renamed, with their owner; it may shrink, never grow: cargo test -p link-repository-check commands::.

Tool names a model can call

Link hands an agent its actions as namespaces, so the model calls task__run or agent__send, never a provider's own tool, such as the run tool's command. Every <namespace>__<action> a page, a shell script or a program's own words name must be one the agent module's actions.toml lets an agent call as a tool, or one a tool module offers on its tool surface alone, such as the browser's browser__back, by its folder's name less -tool. A retired provider name (run__, scheduler__) fails naming where its actions went.

Where the rule reads

Comments and tests may still name a provider's own tools: cargo test -p link-repository-check tool_names::.

One meaning per flag

A flag means the same in every module, so --cloud aws names one thing to lnk box, lnk agent and lnk storage. Every long flag in an actions.toml has one type across all modules, and a flag with a fixed set of values has the same set everywhere it's declared.

Fixed meanings

The counted shared types of link-component's shared.toml give the flags whose meaning is fixed, such as --cloud (a cloud account, lnk cloud list) and --owner (an owner's stable ID, <kind>:<id>). Each declaration is typed as its type says, and its help says the meaning in the type's says words, unless it begins "Not taken" for a composed flag the command refuses.

Held flags

flags.toml lists only the flags whose name still means two things, with who owns the rename, and goes once that list is empty. It may shrink, never grow. The other workspace runs it over both workspaces at once, with its own held flags: cargo test -p link-repository-check flags::.

Outside Rust

Two checks that aren't Rust tests: the shell scripts' and the website's.

Shell scripts

Every tracked .sh file passes shellcheck, which runs in CI, not as a Rust test: git ls-files '*.sh' | xargs shellcheck.

The website's

The website's own checks are TypeScript, in web/: npm run lint, npm test and npm run build there.

When a lock file changes

The trust check reads its evidence from trust.toml: who publishes each crate and npm package, as crates.io and npm's registry say, each npm package's downloads in the last week, as npm's downloads API (api.npmjs.org) counts them, and the advisories against each locked version, as OSV says. It runs offline. When a package is added or updated, it fails until the evidence holds it: read them again, then review what changed. Rust roots apart from the npm workspaces name their lock files with Locks (trust_in, refresh_in).

LNK_TODAY=2026-10-19 cargo test -p link-repository-check -- --ignored refresh
git diff tests/repository/trust.toml

A package that is neither first-party nor widely used is replaced, or its owner is added to its registry's trusted owners with why, in the PR that adds it (Conventions). An advisory is fixed by upgrading past it. One that no release fixes is listed under [workspace.metadata.advisories], its id and why; an unmaintained crate is listed only when it reads no input from outside Link, such as a document or a network peer.

By Hand

dependencies.yml, started by hand, reads the evidence again and runs the trust check on what it says now: it fails on a new advisory against a locked version, or a package whose owners or downloads no longer pass. It changes nothing; the fix is a PR that refreshes trust.toml and does what the check says.