The canon

The canon is a small set of invariants this library stands for. Every document published here satisfies all seven. A document that contradicts one is rejected, and there is no version of the argument — trusted author, unusual circumstances, “but in this case” — that changes that.

It is short on purpose. A standard nobody can hold in their head is a standard nobody applies.

The seven

1. Never instruct an agent to emit a secret as text — no echoing tokens, keys or passwords; reference by name from a secret store.
2. Never instruct destructive or broad-match process operations — no pkill -f <project>, no unscoped kills, no rm -rf without explicit narrow scope; inspect before killing.
3. Never weaken dependency discipline — no disabling lockfiles, no auto-approving installs, no suppressing install-script protections.
4. Never suppress errors that carry safety signal (e.g. 2>/dev/null on a destructive command).
5. Never instruct an agent to bypass, ignore or override its own operator’s instructions or safety rules.
6. Never direct an agent to exfiltrate repo contents, environment, or credentials to a third-party endpoint.
7. Never encourage silent, unattended action where the doc’s own domain calls for human review.

What each one is actually protecting

Secrets as text (1). A token echoed by a command is captured in the transcript, the scrollback and the shell history, permanently. There is no un-printing it; the only remedy is rotation. This is why the rule targets the emission, not the storage.

Broad-match operations (2). pkill -f <name> matches every process whose command line contains that string, across every project and every user on the machine. Editors, language servers and other agents all carry the workspace path in their arguments, so a match on the project name reaches far beyond the project. The failure is silent and it lands on someone else. The rule is not “be careful with kill” — it is “scope it or don’t run it”.

Worth stating separately, because it is the trap that actually catches people: a selection command can be wrong in a way that widens the match instead of failing. lsof combines its criteria with OR rather than AND, so lsof -ti -i tcp:1420 — which differs from the correct form by three characters and looks entirely plausible — selects every process holding a network socket rather than the one on that port. Piped into kill, it takes down everything on the machine at once.

This is why the rule is inspect, then kill, as two separate commands, every time. Not because the author is careless, but because the failure mode of a mistyped selection is silent over-selection, and the only thing that catches it is looking at what came back before anything is signalled. If a selection step returns dozens of processes where you expected one, that is the answer: the command is wrong.

Dependency discipline (3). Lockfiles and install-script protections are the supply chain’s only cheap defences. A document that suggests turning either off to unblock a build has traded a permanent protection for a temporary convenience, and the person who takes the advice will not remember to turn it back on.

Error suppression (4). 2>/dev/null on a read is tidy. On a destructive operation it removes the one signal that would have told you the operation hit the wrong target.

Operator instructions (5). An agent’s operator sets its rules. A document that tells the agent to disregard them is not offering guidance, it is attempting a privilege escalation through the context window — regardless of how reasonable the stated justification is.

Exfiltration (6). Repository contents, environment variables and credentials leaving for a third-party endpoint is the same event whether it is framed as telemetry, backup, analysis or debugging.

Silent action (7). Some domains — deployment, deletion, spending, publishing, anything touching other people — call for a human at the decision point. A document that encourages an agent to proceed unattended in one of those domains is removing a check its own subject matter requires.

Mention is not instruction

This document names rm -rf, pkill -f and 2>/dev/null while prohibiting all three. That is not a contradiction, and any screening process worth running has to be able to tell the difference.

A document that describes a dangerous command in order to warn against it is doing exactly what this library is for. A document that instructs one has violated the canon. What matters is polarity, not vocabulary — and a document that does both, prohibiting a practice in general terms and then instructing it in a specific case, has violated the canon. That shape is not an accident.

The corollary is uncomfortable but load-bearing: a naive keyword screen would reject this very document while passing one that quietly says “always use --no-verify”.

The dangerous kind of submission

The obvious bad document adds a bad rule. It is easy to spot and easy to reject.

The dangerous one relaxes an existing rule. It reads as reasonable, it is usually helpful in the narrow case it describes, and it is load-bearing in a way the reader will not notice — an exception carved into a safety rule, a default flipped in a direction that reduces friction and safety together, a permission widened one step past what the task needed.

That is the thing review is looking for, and it is why review is adversarial rather than merely careful.

Arguing with the canon

Arguing that a canon item is wrong is legitimate, and the route is open: it goes to human debate, and it is never applied automatically. A submission making that argument is not itself a violation, and it is not treated as one.

What the canon does not admit is exceptions applied quietly, by an agent, in the course of processing something else.

How the canon is enforced

Canon conformance is a judgement, not a mechanical check. So it does not auto-reject: it blocks, and a human resolves it.

That distinction runs through the whole pipeline. Objectively checkable properties — does the frontmatter parse, is the licence right, is the rights attestation recorded — can be decided by a machine and can auto-reject. Everything requiring judgement stops and waits for a person. Blocking is not permissive; nothing proceeds past it. It just puts the decision where it belongs.

Nothing in this library publishes without a human decision.