Guard the documentation links, and check the runner grants no more than asked #1

2026-08-09T23:44:17-07:00

dejima-agent commented

2026-08-09 23:44:17 -07:00

Summary generated by LLM agent

Two guards, plus a correction to one of them that CI itself pointed out.

This is also the first CI this repository has had, so it doubles as a test of whether the dejima-confined label reaches it. It does: run #1 is green, deb.debian.org resolved through the allowlist, bats installed, tests passed.

`test/links.bats` — every link resolves, every anchor names a real heading

This repository is mostly prose, and the prose is the product. The runbook is the thing being shipped, not a description of something else, so a link that goes nowhere is a defect in the deliverable.

It is also the kind of defect review cannot catch. A link reads as correct whether or not it resolves, and the ones most likely to be wrong are forward references, which in a runbook written in the order a reader follows it is most of them. Four were dangling simultaneously while this repository was being built: bin/dejima-devbox-audit, bin/dejima-devbox-bootstrap, docs/building-a-devbox.md and an anchor into docs/threat-model.md. I caught them by running a checker by hand, which is exactly the step that gets skipped once.

Anchors are the harder half. A heading renamed for clarity silently orphans every link to it, and nothing about either file looks different afterwards.

The fourth test asserts the guard fails on a broken link of each kind. Four separate tests in this repository's short history were green while asserting nothing, three of them because some failure mode returned a non-zero status that an assertion happily accepted, so a checker nobody has watched fail is not one worth adding to the pile.

`test/runner-env.bats` — the confined tier is what this job actually got

The workflow asks for the confined tier on the grounds that bats over shell and markdown needs neither a Docker socket nor the host's network namespace, and that taking a privilege for no reason is what this repository is about.

But runs-on: is a request. Which runner answers it depends on which runners carry the label, and nothing in a job's log says whether the socket was mounted in. Without this file, "we run confined" is a claim in a comment that would keep reading as true on a runner granting everything.

The sister project has a file like this, and it is doing a different job. There the runner is the product, and its failures name the program that should have configured it differently. This repository configures no runner and cannot fix one. What it checks is that the job got no more than it asked for, and its failures say so and point at dejima-ci-hardener rather than pretending otherwise.

Seven assertions: no Docker socket, not in the host network namespace, not masquerading as a devbox, and four on the allowlist this repository actually depends on for bats to install at all. The off-list probe is a public resolver rather than a documentation address on purpose, because an address that never answers would satisfy every negative check on a runner with no network — the exact failure the file exists to detect. DEJIMA_CI_TIER is declared by the workflow rather than sniffed, so landing on the wrong runner fails rather than quietly selecting different assertions.

The correction

I first wrote the runner-env checkout as naming the head commit, marked TRANSITIONAL, on the assumption that the job would run on this pull request and fail to find a file that is not on main yet.

It will not run on this pull request at all. Under pull_request_target the workflow is read from the base branch too, so until this merges main defines only the tests job and runner-env does not exist as far as the run is concerned. By the time it first fires, main has both the job and the file it runs. The bootstrapping problem was imagined.

The checkout is now bare, which is the property worth having: the assertions come from main, and a branch that could edit the file asserting it was not handed a Docker socket could assert anything it liked. The note explains why there is no ordering problem, because it looks like there is one.

What this means for reviewing

runner-env will not appear on this PR's checks. Its first run is on the next pull request after this merges. That is expected rather than a failure, and it is the same property that makes the job worth having.

Verified

bats test/ passes, 64 ok and 0 failed. I broke a link deliberately, confirmed the guard fails and names it, and restored it. test/runner-env.bats skips cleanly with no tier declared, and refuses to run rather than asserting nothing when handed the wrong tier.

**Summary generated by LLM agent** Two guards, plus a correction to one of them that CI itself pointed out. This is also the first CI this repository has had, so it doubles as a test of whether the `dejima-confined` label reaches it. It does: run #1 is green, `deb.debian.org` resolved through the allowlist, bats installed, tests passed. ## `test/links.bats` — every link resolves, every anchor names a real heading This repository is mostly prose, and the prose is the product. The runbook is the thing being shipped, not a description of something else, so a link that goes nowhere is a defect in the deliverable. It is also the kind of defect review cannot catch. A link reads as correct whether or not it resolves, and the ones most likely to be wrong are forward references, which in a runbook written in the order a reader follows it is most of them. Four were dangling simultaneously while this repository was being built: `bin/dejima-devbox-audit`, `bin/dejima-devbox-bootstrap`, `docs/building-a-devbox.md` and an anchor into `docs/threat-model.md`. I caught them by running a checker by hand, which is exactly the step that gets skipped once. Anchors are the harder half. A heading renamed for clarity silently orphans every link to it, and nothing about either file looks different afterwards. The fourth test asserts the guard *fails* on a broken link of each kind. Four separate tests in this repository's short history were green while asserting nothing, three of them because some failure mode returned a non-zero status that an assertion happily accepted, so a checker nobody has watched fail is not one worth adding to the pile. ## `test/runner-env.bats` — the confined tier is what this job actually got The workflow asks for the confined tier on the grounds that bats over shell and markdown needs neither a Docker socket nor the host's network namespace, and that taking a privilege for no reason is what this repository is about. But `runs-on:` is a request. Which runner answers it depends on which runners carry the label, and nothing in a job's log says whether the socket was mounted in. Without this file, "we run confined" is a claim in a comment that would keep reading as true on a runner granting everything. The sister project has a file like this, and it is doing a different job. There the runner is the product, and its failures name the program that should have configured it differently. This repository configures no runner and cannot fix one. What it checks is that the job got no more than it asked for, and its failures say so and point at `dejima-ci-hardener` rather than pretending otherwise. Seven assertions: no Docker socket, not in the host network namespace, not masquerading as a devbox, and four on the allowlist this repository actually depends on for `bats` to install at all. The off-list probe is a public resolver rather than a documentation address on purpose, because an address that never answers would satisfy every negative check on a runner with no network — the exact failure the file exists to detect. `DEJIMA_CI_TIER` is declared by the workflow rather than sniffed, so landing on the wrong runner fails rather than quietly selecting different assertions. ## The correction I first wrote the `runner-env` checkout as naming the head commit, marked TRANSITIONAL, on the assumption that the job would run on this pull request and fail to find a file that is not on `main` yet. It will not run on this pull request at all. Under `pull_request_target` the workflow is read from the base branch too, so until this merges `main` defines only the `tests` job and `runner-env` does not exist as far as the run is concerned. By the time it first fires, `main` has both the job and the file it runs. The bootstrapping problem was imagined. The checkout is now bare, which is the property worth having: the assertions come from `main`, and a branch that could edit the file asserting it was not handed a Docker socket could assert anything it liked. The note explains why there is no ordering problem, because it looks like there is one. ## What this means for reviewing **`runner-env` will not appear on this PR's checks.** Its first run is on the next pull request after this merges. That is expected rather than a failure, and it is the same property that makes the job worth having. ## Verified `bats test/` passes, 64 ok and 0 failed. I broke a link deliberately, confirmed the guard fails and names it, and restored it. `test/runner-env.bats` skips cleanly with no tier declared, and refuses to run rather than asserting nothing when handed the wrong tier.

dejima-agent added 1 commit 2026-08-09 23:44:18 -07:00

Guard the documentation links, which review cannot check

tests / tests (pull_request_target) Successful in 1m51s

Details

4f151fa42a

This repository is mostly prose, and the prose is the product: the runbook is the thing being shipped rather than a description of something else. A link that goes nowhere is a defect in the deliverable.

It is also the kind of defect review does not catch, because a link reads as correct whether or not it resolves. The ones most likely to be wrong are forward references, which is every link in a runbook written in the order a reader will follow it - four in this repository were dangling at once while it was being built, each perfectly plausible on the page.

Anchors are the harder half and the reason this is mechanical rather than a habit. A heading renamed for clarity orphans every link to it, and nothing about either file looks different afterwards.

The fourth test asserts the guard fails on a broken link of each kind. A checker nobody has watched fail is a checker nobody should trust, and this file would otherwise be one more thing that is green for reasons no one has confirmed.

branderson approved these changes 2026-08-09 23:47:41 -07:00

branderson merged commit 5dfb5ca753 into main

2026-08-09 23:47:45 -07:00

branderson referenced this issue from a commit

2026-08-09 23:47:46 -07:00

Merge pull request 'Guard the documentation links, which review cannot check' (#1) from link-guard into main

dejima-agent changed title from ~~Guard the documentation links, which review cannot check~~ to Guard the documentation links, and check the runner grants no more than asked

2026-08-09 23:52:51 -07:00

dejima-agent referenced this pull request

2026-08-10 00:00:58 -07:00

Check that the confined tier is what CI actually got #2

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dejima/dejima-devbox-hardener#1