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-checkcargo test -p link-docs-check -p link-docs-check-codeThe 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.
Docs against Link's types
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_aliasorvisible_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 refreshgit diff tests/repository/trust.tomlA 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.