@avi2dg/checks 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.29.0
+
+Released 2026-09-28.
+
+### Breaking changes
+
+- **docs:** hold agent files to a 3,000-character router where every entry points [#101](https://github.com/avi2d/checks/pull/101)
+
+### Fixes
+
+- **testing:** run checks-test with CI=true so focused tests fail locally [#100](https://github.com/avi2d/checks/pull/100)
+
+## 0.28.0
+
+Released 2026-09-28.
+
+### Features
+
+- **dependencies:** add checks-advisories gate for advisories a bun.lock change adds [#98](https://github.com/avi2d/checks/pull/98)
+
 ## 0.27.0
 
 Released 2026-09-27.

package/README.md

@@ -124,9 +124,10 @@ The table groups the gates by vector, the part of a repository each one judges.
 | quality | [`checks-comment-gate`](docs/gates/checks-comment-gate.md) | the range | every repository |
 | testing | [`checks-test-layout`](docs/gates/checks-test-layout.md) | the working tree | a repository tracking `*.ts` or `*.tsx` |
 | testing | [`checks-quarantine-clock`](docs/gates/checks-quarantine-clock.md) | the range | every repository |
-| docs | [`checks-docs`](docs/gates/checks-docs.md) | the range | every repository |
+| docs | [`checks-docs`](docs/gates/checks-docs.md) | the range, and every agent file at the head commit | every repository |
 | delivery | [`checks-commit-identity`](docs/gates/checks-commit-identity.md) | the range | every repository |
 | delivery | [`checks-ci-wiring`](docs/gates/checks-ci-wiring.md) | the working tree | every repository |
+| dependencies | [`checks-advisories`](docs/gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
 
 <!-- end generated gates -->
 

package/dist/templates/agents.md

@@ -7,11 +7,3 @@
 <Leave this section out when the lead holds every constraint.>
 
 - <A constraint an agent cannot infer from the code, and the file that holds its detail.>
-
-## Maintaining this file
-
-Keep this file for knowledge useful to almost every future agent session in this project.
-Do not repeat what the codebase already shows.
-Point to the authoritative file or command instead.
-Prefer rewriting or pruning existing entries over appending new ones.
-When updating this file, preserve this bar for all agents and keep entries concise.

package/docs/design.md

@@ -86,6 +86,7 @@ npm adds `package.json`, `README.md` and `LICENSE` whatever `files` says.
 `bun pm pack` builds the same tarball the registry serves, and the consumer e2e test installs that tarball.
 
 Each oxlint plugin ships compiled under `dist/`, because Node refuses to strip types from a `.ts` file under `node_modules`.
+`@oxlint/plugins` ships no RuleTester, so each `effect-channel`, `readability` and `data-shape` rule is proven red and green against an installed consumer in `tests/e2e/consumer.test.ts`.
 `dist/` is committed, with the doc templates in `dist/templates/`, and so is `CHANGELOG.md`, which the same build writes.
 No `prepack` or `prepublishOnly` script rebuilds them, so a publish ships the committed files.
 CI runs `git diff --exit-code` over the whole tree after `bun run build`.
@@ -140,7 +141,8 @@ That flag reports a repeated block as new once its text changes, so a change tha
 ## checks-test runs the suite itself
 
 `checks-test` runs bun itself rather than reading a report that another run left.
-A skip taken only on CI shows only in CI's own run, and an earlier run's report may be stale or narrowed.
+A `"ci"` skip gated on a daemon or tool that CI lacks shows in CI's own run, and an earlier run's report may be stale or narrowed.
+When the same resource is also absent locally, the test skips there too, and its `"ci"` declaration leaves that skip undeclared, so the local run fails.
 It reads the JUnit report bun writes to a temporary directory, because bun has no other per-test output meant for a program.
 
 ## Quarantine has one limit
@@ -175,7 +177,8 @@ A repository adopts the templates as its files change, and an untouched file is
 The prose rules judge only the lines a change adds or edits.
 A report about the past is refused the way a promise about the future is, because history on a living page reads as current fact.
 Text nobody touched never breaks the templates or the prose rules, and a record keeps the words it was written in.
-A repository needs no cleanup pass before the gate runs.
+A repository needs no cleanup pass before the gate runs, except on its agent files.
+The ceiling, the rule against a `## Maintaining this file` section and the entry rule judge every agent file at the head commit, because an agent reads the whole file every session, touched or not.
 Review, not the check, keeps a task heading verb first.
 No word list tells `Test layout` from `Test the layout`, and a check that passes the noun would be worse than none.
 
@@ -213,6 +216,28 @@ So `checks-vendor` strips an owner write bit and checks the tree against its rec
 A write it finds there still fails the run.
 A group or other write bit fails the run, because another user could have edited `.git/config` through it before `git status` reads it.
 
+## Advisories fail only the range that adds them
+
+`checks-advisories` compares the advisories at both ends of a range instead of failing on every advisory at the head.
+An advisory published against a package that landed a month earlier would otherwise fail every open pull request, including one that touches only docs.
+The scheduled `--all` run finds those advisories, and `advisory-acks.json` carries the ones a repository accepts for a while.
+
+The gate runs OSV-Scanner rather than Trivy, Grype or `bun audit`.
+Trivy 0.74.0 reads a nested `bun.lock` entry such as `mkdirp/minimist` under a name no advisory carries, so it misses every package bun nests.
+Grype 0.119.0 drops the dev dependencies of `bun.lock` with no setting that keeps them.
+`bun audit` asks the npm registry on every run and has no offline mode.
+OSV.dev's npm export also holds OpenSSF's reports of malicious packages, which GitHub's reviewed advisories leave out.
+
+The kit pins the scanner by version and by the SHA-256 of each build, because a scanner release is code that runs on every runner.
+Trivy's own advisory GHSA-69fq-xp46-6x23 records a malicious release published with stolen credentials.
+The scan runs offline against a database refreshed once a day, so most runs need no network.
+
+The acknowledgement file belongs to the kit rather than to `osv-scanner.toml`.
+OSV-Scanner's `ignoreUntil` accepts any day, such as 2099-01-01, and measures it against the clock of the machine that runs the scan.
+The kit caps each entry at 30 days and measures a range from the head's dates, as `checks-quarantine-clock` does, so a commit gets the same verdict on every run.
+`--all` measures from the current time instead, because a head's dates never move in a repository that takes no commit, and an entry measured from them would never expire.
+The file is JSON because `Bun.TOML` cannot parse a TOML date.
+
 ## Related topics
 
 - [checks](../README.md)

package/docs/gates/checks-advisories.md

@@ -0,0 +1,128 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-advisories
+
+`checks-advisories` is the gate that fails a range whose `bun.lock` change adds a package version with a known security advisory.
+
+## What it checks
+
+It scans `bun.lock` at both ends of the range with OSV-Scanner and fails on each advisory the head's lockfile has and the base's lockfile lacks.
+It matches an advisory across the range by package name and the id OSV-Scanner reports, so a range that moves a package between two affected versions adds nothing.
+It ignores aliases, because two live advisories can list each other as aliases.
+An advisory published against a package the base already held shows at both ends, so it fails no range, and `--all` reports it instead.
+Each failure names the package, its version, the advisory id, its severity and its summary.
+A range that leaves `bun.lock` unchanged runs no scan.
+It also holds `advisory-acks.json` to the rules in [The acknowledgement file](#the-acknowledgement-file) on every run.
+
+## What it reads
+
+It reads `bun.lock` at the base and at the head of the range from git, not from the working tree.
+It scans copies of both in a scratch directory with an empty config, so a repository's own `osv-scanner.toml` takes no part.
+It reads the advisories OSV.dev exports for npm, which hold GitHub's reviewed advisories and OpenSSF's reports of malicious packages.
+
+It runs OSV-Scanner 2.6.0, pinned by the SHA-256 of each platform's build.
+On first use it downloads the build from the scanner's GitHub release into `~/.cache/avi2dg-checks/osv-scanner/2.6.0/`.
+It checks the SHA-256 again on every run and exits 2 on a copy that differs.
+Builds are pinned for macOS and Linux, each on x64 and arm64.
+On any other platform it exits 2, and no setting runs a scanner other than the pinned build.
+
+It scans offline against OSV-Scanner's npm database in `~/.cache/avi2dg-checks/osv-scanner/db/`.
+When the last refresh is more than 24 hours old, the scan asks for the database again, and OSV-Scanner downloads it only when the copy differs.
+A last refresh dated ahead of the clock counts as no refresh.
+When that download fails, it scans the cached copy and says so, as long as that copy was refreshed within 7 days.
+With no copy refreshed within 7 days it exits 2.
+A cold cache downloads about 55 MB of scanner and 217 MB of database.
+
+`--all` appends its report to the file `GITHUB_STEP_SUMMARY` names, which is the job summary.
+
+## The acknowledgement file
+
+`advisory-acks.json` at the repository root lists the advisories the repository accepts for a while, such as a false positive or a fix that waits on an upstream release:
+
+```json
+[
+  {
+    "package": "minimist",
+    "id": "GHSA-xvch-5gv4-984h",
+    "until": "2026-10-20",
+    "reason": "mkdirp 0.5.1 never parses untrusted argv here, and leaves with the next test runner"
+  }
+]
+```
+
+It reads the file at the head of the range.
+Each entry names the package, the advisory's id as OSV-Scanner reports it, the day the entry stops holding, and why the repository accepts the advisory.
+An entry covers only the advisory with that id, so one naming an alias covers nothing.
+An entry holds until its `until` day begins in UTC.
+A range measures from the later of the head's author and committer dates, so a commit gets the same verdict on every run.
+`--all` measures from the current time, so an entry expires in a repository that takes no commit.
+An entry whose `until` falls more than 30 days after that moment fails the run and covers nothing, and no setting raises the limit.
+Once that moment passes `until`, the entry fails every run until it is deleted or renewed with a later `until`, whether or not the range touches `bun.lock`.
+Delete it once the package is upgraded.
+When a scan runs, an entry that matches no advisory at the head fails, so the file holds only live entries.
+A file that does not decode as that list exits 2.
+
+## Arguments
+
+```sh
+checks-advisories <base-ref> <head-ref>
+checks-advisories <ref>
+checks-advisories --all
+```
+
+With two arguments it judges the range from their merge base to the head.
+With one it judges that commit against its parent, or against an empty tree for a repository's first commit.
+With `--all` it fails on every advisory in `bun.lock` at `HEAD` that no entry covers.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the range adds no advisory to `bun.lock`, and every acknowledgement holds |
+| 1 | the range adds an advisory no acknowledgement covers, or an acknowledgement does not hold |
+| 2 | a ref does not resolve, `advisory-acks.json` does not decode, or no verified scanner or usable database is at hand |
+
+## Sample output
+
+```
+advisories: the range adds 2 advisory(ies) to bun.lock (0 at the head predate the range, 0 acknowledged); upgrade each package, or acknowledge its advisory in advisory-acks.json:
+  lodash@4.17.20 GHSA-35jh-r3h4-6jhm high: Command Injection in lodash
+  minimist@0.0.8 GHSA-xvch-5gv4-984h critical: Prototype Pollution in minimist
+advisories: 1 acknowledgement(s) in advisory-acks.json do not hold:
+  qs GHSA-4mjr-xmp4-gh2g expired on 2026-10-20; upgrade the package and delete the entry, or renew it with a later day
+```
+
+## When it runs
+
+`checks-lint` runs it over each pull request's range in a repository that tracks `bun.lock`, as [checks-lint](checks-lint.md) says.
+A range that leaves `bun.lock` unchanged runs in under a second, and one that changes it scans for about 10 seconds on a warm cache.
+
+## Running it on a schedule
+
+A range never fails on an advisory published after its package landed, so a scheduled `--all` run finds those:
+
+```yaml
+on:
+  schedule:
+    - cron: "41 4 * * *"
+  workflow_dispatch:
+jobs:
+  advisories:
+    runs-on: self-hosted
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: ./node_modules/.bin/checks-advisories --all
+```
+
+A self-hosted runner keeps `~/.cache/avi2dg-checks/` between runs, so it downloads the scanner once per pinned version and the database about once a day.
+A hosted runner starts each run with an empty cache, so each run downloads both.
+
+## Related topics
+
+- [checks-lint](checks-lint.md)
+- [Why it is shaped this way](../design.md)

package/docs/gates/checks-docs.md

@@ -13,6 +13,8 @@ It holds each doc file a change touches to the template for its kind.
 It lists every other doc file that does not match its template yet, and does not fail on it.
 It holds each line a change adds or edits in a living doc or an agent file to the prose rules, as [The prose rules](#the-prose-rules) says.
 It fails when a living doc or an agent file names a path, link or command that does not resolve, and the range added or broke it.
+It fails when an agent file holds more than 3,000 characters or a `## Maintaining this file` section, whatever the range touches, as [Agent files](#agent-files) says.
+It fails when an entry in an agent file names no tracked path, link or `bun run` command, whatever the range touches.
 It fails when a living doc or an agent file names a code span the range removed from every file outside the docs, on any line.
 [Paths, links and commands](#paths-links-and-commands) says how each reference resolves.
 The package ships one template per kind under `dist/templates/`, and a repository starts a new doc file by copying one:
@@ -142,6 +144,24 @@ audience: consumers
 ---
 ```
 
+## Agent files
+
+An agent file holds the router its template sketches, and the rules below hold its shape whatever the range touches.
+A file over 3,000 characters fails.
+Move each part's notes into the people doc that covers that part, and delete what a check or the code already holds.
+A file that holds a `## Maintaining this file` section fails, because this gate holds the shape the section asked for.
+Each entry names at least one of these, or it fails:
+
+- A path in inline code that git tracks at the head commit, a file or a directory, such as `package.json`, `LICENSE` or `.gitignore`.
+  It resolves from the root or from the file's directory, `./` and `../` included, and a path that ends in `/` or `/.` names a directory, never a file.
+- A Markdown link written `[text](target)` with a destination and a closing parenthesis, and not an image.
+- A `bun run` command.
+
+Whether the link or the command resolves is the reference rule's call, as [Paths, links and commands](#paths-links-and-commands) says, and it fails when the range adds or breaks one.
+An entry is any list item a reader sees, the items above the first section included.
+A list item inside an HTML comment, an HTML block or an indented code block is not an entry.
+A fresh file passes the ceiling, and its entries pass once each names the file that holds its detail.
+
 ## What it reads
 
 It reads each Markdown file at the head commit, and uses its path or front matter to choose its kind.
@@ -150,6 +170,7 @@ It reads the lines the range adds or edits from the diff, with renames detected,
 It reads the files tracked at both ends of the range, and the `scripts` of each `package.json` a living doc or an agent file sits under.
 It compares each code span a living doc or an agent file names with the text git tracks outside the docs at both ends of the range.
 It reads the repository's own name and its direct dependencies from the root `package.json` at the head commit.
+It reads each agent file at the head commit for the ceiling, its sections and its entries, whatever the range touches.
 A name that an installed direct dependency still holds counts as present.
 From the working tree it reads the ignore files git reads, `node_modules/.bin`, and the directory of each direct dependency under `node_modules`.
 
@@ -167,8 +188,8 @@ With one it is that commit against its parent, or against the empty tree for a r
 
 | Code | When |
 | --- | --- |
-| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules, it adds or breaks no reference that does not resolve, and no code span a living doc or an agent file names vanished from every file outside the docs |
-| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule, the range adds or breaks a reference that does not resolve, or the range removes a name a living doc or an agent file still carries |
+| 0 | every doc file the range touches holds to its template, every line it adds to a living doc or an agent file holds to the prose rules, it adds or breaks no reference that does not resolve, every agent file holds to the ceiling and holds no `## Maintaining this file`, every entry in an agent file names a tracked path, a link or a command, and no code span a living doc or an agent file names vanished from every file outside the docs |
+| 1 | a doc file the range touches does not hold to its template, a line the range adds to a living doc or an agent file breaks a prose rule, the range adds or breaks a reference that does not resolve, an agent file is over the ceiling or holds `## Maintaining this file`, an entry in an agent file names no tracked path, link or command, or the range removes a name a living doc or an agent file still carries |
 | 2 | a `package.json` does not decode, a ref does not resolve, or `grep` cannot read an installed direct dependency |
 
 ## Sample output
@@ -191,6 +212,7 @@ docs: advisory, 1 path(s), link(s) or command(s) the living docs or agent files
 
 `checks-lint` runs it over each pull request's range in every repository, as [checks-lint](checks-lint.md) says.
 A repository adopts the templates as its files change, and the prose rules as its lines change, because an untouched file or line never fails those checks.
+It reshapes its agent files when it adopts the gate, because [Agent files](#agent-files) judges each one whatever the range touches.
 A name the range removes fails wherever a doc still carries it, because the removal is what turned the line stale.
 
 ## Related topics

package/docs/gates/checks-lint.md

@@ -10,6 +10,7 @@ audience: consumers
 
 It runs the gates under [What runs](../../README.md#what-runs), each in its own process.
 Gates requiring tracked TypeScript files begin running when the repository tracks TypeScript.
+`checks-advisories` begins running when the repository tracks `bun.lock`.
 All other gates run for every repository.
 
 ## What it reads
@@ -44,7 +45,7 @@ With two arguments, the base and head override range discovery.
 
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
-checks-lint: 1 of 11 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 12 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

package/docs/gates/checks-repetition.md

@@ -12,6 +12,7 @@ The gate runs jscpd at 50 tokens and 5 lines against the base and head revisions
 It compares repeated lines for each file, so a decrease in another file never offsets a rise.
 It follows an edited rename back to the original file.
 A file that repeats lines without a rise is advisory.
+A block two bins need goes into a module both import, as `rangeFromArgs` and `checkoutFiles` in `src/core/git.ts` show.
 
 ## What it reads
 

package/docs/gates/checks-test.md

@@ -9,6 +9,7 @@ audience: consumers
 ## What it checks
 
 It runs the default suite with `bun test --randomize` and reads Bun's JUnit report from that run.
+It runs Bun with `CI=true`, so `test.only` fails the run in every environment.
 Bun exits zero when tests skip, so `checks-test` checks every skipped test against its source declaration.
 A test that `test.skip`, `test.skipIf`, `test.if`, `test.todo` or an enclosing `describe.skip` skips fails unless the test declares its reason.
 
@@ -33,6 +34,8 @@ A skip is declared on the test itself and only there.
 Add `"ci"` or `"local"` as the third `skipReason` argument when a declaration applies to one environment.
 Omit the third argument when it applies in both environments.
 A declaration for the other environment is not judged in the current run.
+Bun sees `CI` set in every `checks-test` run, so a `"ci"` skip whose condition reads `process.env.CI` also skips in a local run and fails there as undeclared.
+Gate a `"ci"` skip on what CI lacks, such as a daemon or a tool, and never on `process.env.CI`.
 
 A declaration whose test passes or does not register fails a CI run.
 A local run warns about the same declaration because a condition can depend on the machine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avi2dg/checks",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Deterministic checks shared across a set of TypeScript repositories",
   "license": "MIT",
   "repository": {
@@ -53,6 +53,11 @@
     "src/docs/docs.ts",
     "src/dependencies/vendor.ts",
     "src/dependencies/vendor-args.ts",
+    "src/dependencies/cache-root.ts",
+    "src/dependencies/advisories.ts",
+    "src/dependencies/advisory-rules.ts",
+    "src/dependencies/osv-scanner.ts",
+    "src/docs/doc-agents.ts",
     "src/docs/doc-outline.ts",
     "src/docs/doc-rules.ts",
     "src/docs/doc-references.ts",
@@ -100,7 +105,8 @@
     "checks-exports": "src/complexity/exports.ts",
     "checks-quarantine-clock": "src/testing/quarantine-clock.ts",
     "checks-docs": "src/docs/docs.ts",
-    "checks-vendor": "src/dependencies/vendor.ts"
+    "checks-vendor": "src/dependencies/vendor.ts",
+    "checks-advisories": "src/dependencies/advisories.ts"
   },
   "scripts": {
     "prepare": "bun src/dependencies/vendor.ts --library effect --package effect --repository https://github.com/Effect-TS/effect.git --tag 'effect@{version}' --path packages/effect/package.json",

package/src/complexity/knip.ts

@@ -27,7 +27,7 @@ const hasKnipConfig = Effect.fn("hasKnipConfig")(function* (root: string) {
   const manifest: unknown = yield* fs.readFileString(path.join(root, "package.json")).pipe(
     Effect.flatMap((text) =>
       Effect.try({
-        try: () => JSON.parse(text),
+        try: (): unknown => JSON.parse(text),
         catch: () => new KnipError({ message: "package.json does not parse as JSON" }),
       })
     ),

package/src/core/gates.ts

@@ -19,6 +19,7 @@ export type KitGate = {
   readonly vector: Vector;
   readonly file: string;
   readonly reads: "tree" | "range";
+  readonly alsoReads?: string;
   readonly args?: readonly string[];
   readonly appliesTo: typeof EVERY_REPOSITORY | TrackedContent;
 };
@@ -31,6 +32,8 @@ export const DEFAULT_BRANCH = "main";
 
 const TYPESCRIPT_SOURCE: TrackedContent = { pathspecs: ["*.ts", "*.tsx"], content: "TypeScript source" };
 
+const BUN_LOCKFILE: TrackedContent = { pathspecs: ["bun.lock"], content: "a bun lockfile" };
+
 export const KIT_GATES = [
   { bin: "checks-lint-coverage", vector: "quality", file: "lint-coverage.sh", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-test-layout", vector: "testing", file: "test-layout.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
@@ -38,9 +41,10 @@ export const KIT_GATES = [
   { bin: "checks-comment-gate", vector: "quality", file: "comment-gate.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-suppressions-ratchet", vector: "complexity", file: "suppressions-ratchet.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-ci-wiring", vector: "delivery", file: "ci-wiring.ts", reads: "tree", appliesTo: EVERY_REPOSITORY },
-  { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-docs", vector: "docs", file: "docs.ts", reads: "range", alsoReads: "every agent file at the head commit", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-repetition", vector: "complexity", file: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-unused", vector: "complexity", file: "unused.ts", reads: "tree", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-exports", vector: "complexity", file: "exports.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-quarantine-clock", vector: "testing", file: "quarantine-clock.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
+  { bin: "checks-advisories", vector: "dependencies", file: "advisories.ts", reads: "range", appliesTo: BUN_LOCKFILE },
 ] as const satisfies readonly KitGate[];

package/src/core/git.ts

@@ -205,6 +205,16 @@ export const commitOf = Effect.fn("commitOf")(function* (rev: string, cwd?: stri
   return (yield* git(["rev-parse", "--verify", `${rev}^{commit}`], cwd)).trim();
 });
 
+// The later of the author and committer dates, in seconds, so a rebase neither restarts nor stops a clock read from it.
+export const writtenAt = Effect.fn("writtenAt")(function* (rev: string, cwd?: string) {
+  const shown = yield* git(["show", "-s", "--format=%at %ct", rev], cwd);
+  const dates = shown.trim().split(" ").map(Number);
+  if (dates.length !== 2 || !dates.every(Number.isInteger)) {
+    return yield* new GitFailure({ message: `cannot read when ${rev} was written` });
+  }
+  return Math.max(...dates);
+});
+
 // A scratch index leaves the repository's own index and working tree untouched.
 export const checkoutFiles = Effect.fn("checkoutFiles")(function* (rev: string, files: readonly string[], scratch: string, cwd?: string) {
   const path = yield* Path.Path;

package/src/dependencies/advisories.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env bun
+import { Clock, Config, Console, Effect, FileSystem, type Layer, Option, Path, Schema } from "effect";
+import { changedPaths, commitOf, git, pathsAt, rangeFromArgs, writtenAt } from "../core/git.ts";
+import type { BunServices } from "@effect/platform-bun";
+import { runMain, Usage } from "../core/main.ts";
+import {
+  ACKNOWLEDGEMENTS,
+  clockOf,
+  decodeAcknowledgements,
+  decodeOsvReport,
+  findingsIn,
+  judge,
+  LOCKFILE,
+  passes,
+  report,
+  summaryOf,
+  type AcknowledgementClock,
+  type Outcome,
+} from "./advisory-rules.ts";
+import { cacheRoot } from "./cache-root.ts";
+import { scanLockfiles, Scanner } from "./osv-scanner.ts";
+
+const NAME = "advisories";
+const ALL = "--all";
+const USAGE = `usage: advisories.ts <ref> | <base-ref> <head-ref> | ${ALL}`;
+const SIDES = ["base", "head"] as const;
+
+class AdvisoriesError extends Schema.TaggedError<AdvisoriesError>()("AdvisoriesError", {
+  message: Schema.String,
+}) {}
+
+type Request = { readonly kind: "range"; readonly base: string; readonly head: string } | { readonly kind: "head"; readonly head: string };
+
+const requestOf = Effect.fn("requestOf")(function* (args: readonly string[]) {
+  if (args[0] === ALL) {
+    if (args.length > 1) return yield* new Usage({ message: USAGE });
+    return { kind: "head", head: yield* commitOf("HEAD") } satisfies Request;
+  }
+  const { base, head } = yield* rangeFromArgs(args, USAGE);
+  return { kind: "range", base, head: yield* commitOf(head) } satisfies Request;
+});
+
+const fileAt = Effect.fn("fileAt")(function* (rev: string, file: string, root: string) {
+  if (!(yield* pathsAt(rev, [file], root)).includes(file)) return Option.none<string>();
+  return Option.some(yield* git(["show", `${rev}:${file}`], root));
+});
+
+const acknowledgementsAt = Effect.fn("acknowledgementsAt")(function* (head: string, root: string) {
+  const text = yield* fileAt(head, ACKNOWLEDGEMENTS, root);
+  if (Option.isNone(text)) return [];
+  return yield* decodeAcknowledgements(text.value).pipe(
+    Effect.mapError((cause) => new AdvisoriesError({ message: `${ACKNOWLEDGEMENTS} at ${head} does not decode: ${cause.message}` })),
+  );
+});
+
+type Lockfiles = Readonly<Record<(typeof SIDES)[number], Option.Option<string>>>;
+
+// Scanning copies keeps the working tree and a repository's own osv-scanner.toml out of the verdict.
+const findingsOf = Effect.fn("findingsOf")(function* (lockfiles: Lockfiles) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dir = yield* fs.makeTempDirectoryScoped({ prefix: "checks-advisories-" });
+  const config = path.join(dir, "empty.toml");
+  yield* fs.writeFileString(config, "");
+  const written: string[] = [];
+  for (const side of SIDES) {
+    const text = lockfiles[side];
+    if (Option.isNone(text)) continue;
+    yield* fs.makeDirectory(path.join(dir, side));
+    yield* fs.writeFileString(path.join(dir, side, LOCKFILE), text.value);
+    written.push(path.join(dir, side, LOCKFILE));
+  }
+  const cache = yield* cacheRoot();
+  const { stdout, note } = yield* scanLockfiles(yield* (yield* Scanner).binary(cache), cache, config, written);
+  if (Option.isSome(note)) yield* Console.error(`${NAME}: ${note.value}`);
+  const scanned = yield* decodeOsvReport(stdout).pipe(
+    Effect.mapError((cause) => new AdvisoriesError({ message: `cannot read the report OSV-Scanner wrote: ${cause.message}` })),
+  );
+  const at = (side: string) => (source: string) => source.endsWith(`${path.sep}${side}${path.sep}${LOCKFILE}`);
+  return { base: findingsIn(scanned, at("base")), head: findingsIn(scanned, at("head")) };
+}, Effect.scoped);
+
+const outcomeOf = Effect.fn("outcomeOf")(function* (request: Request, root: string, clock: AcknowledgementClock) {
+  if (request.kind === "range" && (yield* changedPaths(request.base, request.head, [LOCKFILE], root)).length === 0) {
+    return { kind: "unchanged", problems: clock.problems } satisfies Outcome;
+  }
+  const head = yield* fileAt(request.head, LOCKFILE, root);
+  const base = request.kind === "range" ? yield* fileAt(request.base, LOCKFILE, root) : Option.none<string>();
+  const findings = Option.isNone(head) ? { base: [], head: [] } : yield* findingsOf({ base, head });
+  return { kind: "scanned", scope: { kind: request.kind }, judged: judge(findings.base, findings.head, clock) } satisfies Outcome;
+});
+
+const toStepSummary = Effect.fn("toStepSummary")(function* (text: string) {
+  const stepSummary = yield* Config.option(Config.String("GITHUB_STEP_SUMMARY"));
+  if (Option.isNone(stepSummary)) return;
+  yield* (yield* FileSystem.FileSystem).writeFileString(stepSummary.value, `${summaryOf(text)}\n`, { flag: "a" });
+});
+
+const advisories = Effect.gen(function* () {
+  const request = yield* requestOf(process.argv.slice(2));
+  const root = (yield* git(["rev-parse", "--show-toplevel"])).trim();
+  const dates = { head: (yield* writtenAt(request.head, root)) * 1000, now: yield* Clock.currentTimeMillis };
+  const clock = clockOf(yield* acknowledgementsAt(request.head, root), { kind: request.kind }, dates);
+  const outcome = yield* outcomeOf(request, root, clock);
+  const text = report(outcome);
+  yield* Console.log(text);
+  if (request.kind === "head") yield* toStepSummary(text);
+  return passes(outcome);
+});
+
+export function main(scanner: Layer.Layer<Scanner, never, BunServices.BunServices>): void {
+  runMain(NAME, advisories.pipe(Effect.provide(scanner)));
+}
+
+if (import.meta.main) main(Scanner.pinned);

package/src/dependencies/advisory-rules.ts

@@ -0,0 +1,206 @@
+import { Schema } from "effect";
+
+export const LOCKFILE = "bun.lock";
+export const ACKNOWLEDGEMENTS = "advisory-acks.json";
+const ACKNOWLEDGEMENT_DAYS = 30;
+const DAY_MS = 86_400_000;
+const UNRATED = "unrated";
+
+// Date.parse rolls a day past the month's end, such as 2026-02-30, into the next month, so the round trip catches it.
+function isCalendarDay(day: string): boolean {
+  const ms = Date.parse(`${day}T00:00:00Z`);
+  return !Number.isNaN(ms) && new Date(ms).toISOString().startsWith(day);
+}
+
+const Day = Schema.String.check(
+  Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/, { message: "is not a day such as 2026-10-20" }),
+  Schema.makeFilter((day: string) => isCalendarDay(day) || "is not a day of the calendar"),
+);
+
+const Acknowledgement = Schema.Struct({
+  package: Schema.NonEmptyString,
+  id: Schema.NonEmptyString,
+  until: Day,
+  reason: Schema.NonEmptyString,
+});
+
+export type Acknowledgement = typeof Acknowledgement.Type;
+
+export const decodeAcknowledgements = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Array(Acknowledgement)));
+
+const Vulnerability = Schema.Struct({
+  id: Schema.String,
+  summary: Schema.optionalKey(Schema.String),
+  database_specific: Schema.optionalKey(Schema.Struct({ severity: Schema.optionalKey(Schema.String) })),
+});
+
+const OsvReport = Schema.Struct({
+  results: Schema.Array(
+    Schema.Struct({
+      source: Schema.Struct({ path: Schema.String }),
+      packages: Schema.Array(
+        Schema.Struct({
+          package: Schema.Struct({ name: Schema.String, version: Schema.String }),
+          vulnerabilities: Schema.optionalKey(Schema.Array(Vulnerability)),
+        }),
+      ),
+    }),
+  ),
+});
+
+type OsvReport = typeof OsvReport.Type;
+
+export const decodeOsvReport = Schema.decodeUnknownEffect(Schema.fromJsonString(OsvReport));
+
+export type Finding = {
+  readonly name: string;
+  readonly version: string;
+  readonly id: string;
+  readonly severity: string;
+  readonly summary: string;
+};
+
+// OSV-Scanner leaves a lockfile with no advisory out of its results, so an absent lockfile reads as clean.
+export function findingsIn(scanned: OsvReport, lockfile: (path: string) => boolean): readonly Finding[] {
+  return scanned.results
+    .filter(({ source }) => lockfile(source.path))
+    .flatMap(({ packages }) => packages)
+    .flatMap(({ package: { name, version }, vulnerabilities = [] }) =>
+      vulnerabilities.map((vulnerability) => ({
+        name,
+        version,
+        id: vulnerability.id,
+        severity: vulnerability.database_specific?.severity?.toLowerCase() ?? UNRATED,
+        summary: vulnerability.summary ?? "",
+      })),
+    );
+}
+
+// Two live records can list each other as aliases, so only the id the scan reports names an advisory.
+function keyOf({ name, id }: { readonly name: string; readonly id: string }): string {
+  return `${name} ${id}`;
+}
+
+// Keyed by name and id rather than version, so moving between two affected versions adds nothing.
+export function introducedBy(base: readonly Finding[], head: readonly Finding[]): readonly Finding[] {
+  const known = new Set(base.map(keyOf));
+  return head.filter((finding) => !known.has(keyOf(finding)));
+}
+
+type AcknowledgementProblem =
+  | { readonly kind: "expired"; readonly acknowledgement: Acknowledgement }
+  | { readonly kind: "too-far"; readonly acknowledgement: Acknowledgement; readonly latest: string }
+  | { readonly kind: "unmatched"; readonly acknowledgement: Acknowledgement };
+
+export type AcknowledgementClock = {
+  readonly live: readonly Acknowledgement[];
+  readonly problems: readonly AcknowledgementProblem[];
+};
+
+type Scope = { readonly kind: "range" } | { readonly kind: "head" };
+
+export type Dates = { readonly head: number; readonly now: number };
+
+// A range reads the head's date so a commit gets one verdict, and --all reads today so an entry expires in an idle repository.
+function measuredFrom(scope: Scope, { head, now }: Dates): number {
+  return scope.kind === "head" ? now : head;
+}
+
+function dayOf(ms: number): string {
+  return new Date(ms).toISOString().slice(0, "YYYY-MM-DD".length);
+}
+
+export function clockOf(acknowledgements: readonly Acknowledgement[], scope: Scope, dates: Dates): AcknowledgementClock {
+  const from = measuredFrom(scope, dates);
+  const limit = from + ACKNOWLEDGEMENT_DAYS * DAY_MS;
+  const live: Acknowledgement[] = [];
+  const problems: AcknowledgementProblem[] = [];
+  for (const acknowledgement of acknowledgements) {
+    const until = Date.parse(`${acknowledgement.until}T00:00:00Z`);
+    if (until <= from) problems.push({ kind: "expired", acknowledgement });
+    else if (until > limit) problems.push({ kind: "too-far", acknowledgement, latest: dayOf(limit) });
+    else live.push(acknowledgement);
+  }
+  return { live, problems };
+}
+
+function covers(acknowledgement: Acknowledgement, finding: Finding): boolean {
+  return acknowledgement.package === finding.name && acknowledgement.id === finding.id;
+}
+
+type Judged = {
+  readonly failing: readonly Finding[];
+  readonly acknowledged: number;
+  readonly predating: number;
+  readonly problems: readonly AcknowledgementProblem[];
+};
+
+export function judge(base: readonly Finding[], head: readonly Finding[], clock: AcknowledgementClock): Judged {
+  const added = introducedBy(base, head);
+  const failing = added.filter((finding) => !clock.live.some((acknowledgement) => covers(acknowledgement, finding)));
+  const unmatched = clock.live
+    .filter((acknowledgement) => !head.some((finding) => covers(acknowledgement, finding)))
+    .map((acknowledgement): AcknowledgementProblem => ({ kind: "unmatched", acknowledgement }));
+  return {
+    failing,
+    acknowledged: added.length - failing.length,
+    predating: head.length - added.length,
+    problems: [...clock.problems, ...unmatched],
+  };
+}
+
+export type Outcome =
+  | { readonly kind: "unchanged"; readonly problems: readonly AcknowledgementProblem[] }
+  | { readonly kind: "scanned"; readonly scope: Scope; readonly judged: Judged };
+
+export function passes(outcome: Outcome): boolean {
+  if (outcome.kind === "unchanged") return outcome.problems.length === 0;
+  return outcome.judged.failing.length === 0 && outcome.judged.problems.length === 0;
+}
+
+function problemLine(problem: AcknowledgementProblem): string {
+  const { package: name, id, until } = problem.acknowledgement;
+  switch (problem.kind) {
+    case "expired":
+      return `  ${name} ${id} expired on ${until}; upgrade the package and delete the entry, or renew it with a later day`;
+    case "too-far":
+      return `  ${name} ${id} runs until ${until}, more than ${ACKNOWLEDGEMENT_DAYS} days out; name a day no later than ${problem.latest}`;
+    case "unmatched":
+      return `  ${name} ${id} matches nothing in ${LOCKFILE} at the head; delete it`;
+  }
+}
+
+function problemLines(problems: readonly AcknowledgementProblem[]): readonly string[] {
+  if (problems.length === 0) return [];
+  return [`advisories: ${problems.length} acknowledgement(s) in ${ACKNOWLEDGEMENTS} do not hold:`, ...problems.map(problemLine)];
+}
+
+function findingLine({ name, version, id, severity, summary }: Finding): string {
+  return `  ${name}@${version} ${id} ${severity}${summary === "" ? "" : `: ${summary}`}`;
+}
+
+function scannedLines(scope: Scope, { failing, acknowledged, predating }: Judged): readonly string[] {
+  const fix = `upgrade each package, or acknowledge its advisory in ${ACKNOWLEDGEMENTS}:`;
+  if (scope.kind === "head") {
+    if (failing.length === 0) return [`advisories: ${LOCKFILE} at the head holds no unacknowledged advisory (${acknowledged} acknowledged)`];
+    return [`advisories: ${LOCKFILE} at the head holds ${failing.length} unacknowledged advisory(ies); ${fix}`, ...failing.map(findingLine)];
+  }
+  const counts = `${predating} at the head predate the range, ${acknowledged} acknowledged`;
+  if (failing.length === 0) return [`advisories: the range adds no advisory to ${LOCKFILE} (${counts})`];
+  return [`advisories: the range adds ${failing.length} advisory(ies) to ${LOCKFILE} (${counts}); ${fix}`, ...failing.map(findingLine)];
+}
+
+export function report(outcome: Outcome): string {
+  if (outcome.kind === "unchanged") {
+    return [`advisories: ${LOCKFILE} is unchanged in the range, so nothing was scanned`, ...problemLines(outcome.problems)].join("\n");
+  }
+  return [...scannedLines(outcome.scope, outcome.judged), ...problemLines(outcome.judged.problems)].join("\n");
+}
+
+// The job summary is Markdown, where an indented line would merge into the paragraph above it.
+export function summaryOf(text: string): string {
+  return text
+    .split("\n")
+    .map((line) => (line.startsWith("  ") ? `- ${line.trim()}` : line))
+    .join("\n");
+}

package/src/dependencies/cache-root.ts

@@ -0,0 +1,15 @@
+import { Config, Effect, Path, Schema } from "effect";
+
+const CACHE_HOME = ".cache/avi2dg-checks";
+
+class CacheUnrooted extends Schema.TaggedError<CacheUnrooted>()("CacheUnrooted", {
+  message: Schema.String,
+}) {}
+
+export const cacheRoot = Effect.fn("cacheRoot")(function* () {
+  const path = yield* Path.Path;
+  const home = yield* Config.NonEmptyString("HOME").pipe(
+    Effect.mapError(() => new CacheUnrooted({ message: "HOME is missing, so the shared cache has no root" })),
+  );
+  return path.join(home, CACHE_HOME);
+});

package/src/dependencies/osv-scanner.ts

@@ -0,0 +1,176 @@
+import { Clock, Context, Crypto, Effect, Encoding, FileSystem, Layer, Option, Path, Schema } from "effect";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { collect } from "../core/git.ts";
+
+export const OSV_SCANNER_VERSION = "2.6.0";
+const RELEASES = `https://github.com/google/osv-scanner/releases/download/v${OSV_SCANNER_VERSION}`;
+const EXECUTABLE_MODE = 0o755;
+const HOUR_MS = 3_600_000;
+const DAY_MS = 24 * HOUR_MS;
+export const REFRESH_HOURS = 24;
+export const USABLE_DAYS = 7;
+const FOUND_NOTHING = 0;
+const FOUND_ADVISORIES = 1;
+const FOUND_NO_PACKAGE = 128;
+const NO_RESULTS = JSON.stringify({ results: [] });
+
+type Build = { readonly asset: string; readonly sha256: string };
+
+// The SHA-256 of each asset as osv-scanner_SHA256SUMS of the release lists it.
+const BUILDS: Readonly<Record<string, Build>> = {
+  "darwin-arm64": { asset: "osv-scanner_darwin_arm64", sha256: "98c460dcd37de25819babd757d04542045b6243113e209edcd4d89fedb0256b4" },
+  "darwin-x64": { asset: "osv-scanner_darwin_amd64", sha256: "60c5296637e977b28eeda5c7f13573e447659a632922737f94d11fa7e30ad6ca" },
+  "linux-arm64": { asset: "osv-scanner_linux_arm64", sha256: "2c71403eb443d05891c4f268c3ad771cf4f16e5443463fd7851ef8f454d3c7e4" },
+  "linux-x64": { asset: "osv-scanner_linux_amd64", sha256: "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108" },
+};
+
+class OsvScannerError extends Schema.TaggedError<OsvScannerError>()("OsvScannerError", {
+  message: Schema.String,
+}) {}
+
+export function buildFor(platform: string, arch: string): Option.Option<Build> {
+  return Option.fromNullishOr(BUILDS[`${platform}-${arch}`]);
+}
+
+const sha256Of = Effect.fn("sha256Of")(function* (bytes: Uint8Array) {
+  const crypto = yield* Crypto.Crypto;
+  return Encoding.encodeHex(yield* crypto.digest("SHA-256", bytes));
+});
+
+const verified = Effect.fn("verified")(function* (binary: string, sha256: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const found = yield* sha256Of(yield* fs.readFile(binary));
+  if (found !== sha256) {
+    return yield* new OsvScannerError({ message: `${binary} has SHA-256 ${found}, not the pinned ${sha256}; delete it and rerun` });
+  }
+  return binary;
+});
+
+const download = Effect.fn("download")(function* (url: string) {
+  const response = yield* HttpClient.get(url).pipe(Effect.flatMap(HttpClientResponse.filterStatusOk));
+  return new Uint8Array(yield* response.arrayBuffer);
+}, Effect.provide(FetchHttpClient.layer));
+
+// The binary lands through a rename in its own directory, so a concurrent run sees it whole or not at all.
+export const installPinned = Effect.fn("installPinned")(function* (url: string, sha256: string, binary: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  if (yield* fs.exists(binary)) return yield* verified(binary, sha256);
+  const bytes = yield* download(url).pipe(
+    Effect.mapError((cause) => new OsvScannerError({ message: `cannot download ${url}: ${cause.message}` })),
+  );
+  const found = yield* sha256Of(bytes);
+  if (found !== sha256) {
+    return yield* new OsvScannerError({ message: `${url} has SHA-256 ${found}, not the pinned ${sha256}, so nothing was installed` });
+  }
+  yield* fs.makeDirectory(path.dirname(binary), { recursive: true });
+  const staging = yield* fs.makeTempDirectoryScoped({ directory: path.dirname(binary), prefix: `.${path.basename(binary)}-` });
+  const staged = path.join(staging, path.basename(binary));
+  yield* fs.writeFile(staged, bytes);
+  yield* fs.chmod(staged, EXECUTABLE_MODE);
+  yield* fs.rename(staged, binary);
+  return binary;
+}, Effect.scoped);
+
+const pinnedBinary = Effect.fn("pinnedBinary")(function* (cache: string) {
+  const build = buildFor(process.platform, process.arch);
+  if (Option.isNone(build)) {
+    return yield* new OsvScannerError({ message: `no pinned OSV-Scanner build runs on ${process.platform}-${process.arch}` });
+  }
+  const path = yield* Path.Path;
+  const { asset, sha256 } = build.value;
+  return yield* installPinned(`${RELEASES}/${asset}`, sha256, path.join(cache, "osv-scanner", OSV_SCANNER_VERSION, asset));
+});
+
+type PinnedBinary = ReturnType<typeof pinnedBinary>;
+
+export class Scanner extends Context.Service<
+  Scanner,
+  { readonly binary: (cache: string) => Effect.Effect<string, Effect.Error<PinnedBinary>> }
+>()("@avi2dg/checks/dependencies/Scanner") {
+  static readonly pinned = Layer.effect(
+    Scanner,
+    Effect.gen(function* () {
+      const services = yield* Effect.context<Effect.Services<PinnedBinary>>();
+      return Scanner.of({ binary: (cache) => pinnedBinary(cache).pipe(Effect.provideContext(services)) });
+    }),
+  );
+}
+
+type RefreshPlan = "refresh" | "offline";
+
+export function refreshPlan(refreshedAgo: Option.Option<number>): RefreshPlan {
+  return Option.isSome(refreshedAgo) && refreshedAgo.value <= REFRESH_HOURS * HOUR_MS ? "offline" : "refresh";
+}
+
+export function usableWithoutRefresh(refreshedAgo: Option.Option<number>): boolean {
+  return Option.isSome(refreshedAgo) && refreshedAgo.value <= USABLE_DAYS * DAY_MS;
+}
+
+type Database = { readonly dir: string; readonly marker: string };
+
+// An unparsable marker gives NaN and one dated ahead of the clock a negative age, and neither says how old the database is.
+export function refreshAge(recorded: Option.Option<string>, now: number): Option.Option<number> {
+  return Option.filter(Option.map(recorded, (text) => now - Date.parse(text.trim())), (ago) => ago >= 0);
+}
+
+const refreshedAgo = Effect.fn("refreshedAgo")(function* ({ marker }: Database) {
+  const fs = yield* FileSystem.FileSystem;
+  const recorded = yield* fs.readFileString(marker).pipe(Effect.option);
+  return refreshAge(recorded, yield* Clock.currentTimeMillis);
+});
+
+const FLAGS: Readonly<Record<RefreshPlan, readonly string[]>> = {
+  refresh: ["--offline-vulnerabilities", "--download-offline-databases", "--no-resolve"],
+  offline: ["--offline"],
+};
+
+type Scanned =
+  | { readonly kind: "scanned"; readonly stdout: string }
+  | { readonly kind: "no-package" }
+  | { readonly kind: "failed"; readonly reason: string };
+
+const scanOnce = Effect.fn("scanOnce")(function* (binary: string, database: Database, config: string, lockfiles: readonly string[], plan: RefreshPlan) {
+  const args = ["scan", "source", ...FLAGS[plan], "--format", "json", "--config", config, ...lockfiles.flatMap((file) => ["-L", file])];
+  const { stdout, stderr, exitCode } = yield* collect(binary, args, undefined, { env: { OSV_SCANNER_LOCAL_DB_CACHE_DIRECTORY: database.dir } }).pipe(
+    Effect.mapError((cause) => new OsvScannerError({ message: `cannot run ${binary}: ${cause.message}` })),
+  );
+  if (exitCode === FOUND_NOTHING || exitCode === FOUND_ADVISORIES) return { kind: "scanned", stdout } satisfies Scanned;
+  if (exitCode === FOUND_NO_PACKAGE) return { kind: "no-package" } satisfies Scanned;
+  const reason = stderr.trim().split("\n").at(-1) ?? "";
+  return { kind: "failed", reason: `${binary} exited ${exitCode}: ${reason}` } satisfies Scanned;
+});
+
+type ScanResult = { readonly stdout: string; readonly note: Option.Option<string> };
+
+// A failed refresh leaves the cached database in place, which still serves until USABLE_DAYS pass without a refresh.
+export const scanLockfiles = Effect.fn("scanLockfiles")(function* (binary: string, cache: string, config: string, lockfiles: readonly string[]) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dir = path.join(cache, "osv-scanner", "db");
+  const database = { dir, marker: path.join(dir, "refreshed") };
+  const ago = yield* refreshedAgo(database);
+  const plan = refreshPlan(ago);
+  const first = yield* scanOnce(binary, database, config, lockfiles, plan);
+  // A lockfile with no package stops the scanner before it downloads anything, so no refresh is recorded.
+  if (first.kind === "no-package") return { stdout: NO_RESULTS, note: Option.none() } satisfies ScanResult;
+  if (first.kind === "scanned") {
+    if (plan === "refresh") {
+      yield* fs.makeDirectory(dir, { recursive: true });
+      yield* fs.writeFileString(database.marker, `${new Date(yield* Clock.currentTimeMillis).toISOString()}\n`);
+    }
+    return { stdout: first.stdout, note: Option.none() } satisfies ScanResult;
+  }
+  if (plan === "offline") return yield* new OsvScannerError({ message: first.reason });
+  if (Option.isNone(ago) || !usableWithoutRefresh(ago)) {
+    return yield* new OsvScannerError({
+      message: `could not refresh the OSV database, and no copy was refreshed in the last ${USABLE_DAYS} days: ${first.reason}`,
+    });
+  }
+  const fallback = yield* scanOnce(binary, database, config, lockfiles, "offline");
+  if (fallback.kind === "failed") return yield* new OsvScannerError({ message: fallback.reason });
+  if (fallback.kind === "no-package") return { stdout: NO_RESULTS, note: Option.none() } satisfies ScanResult;
+  const days = Math.floor(ago.value / DAY_MS);
+  return { stdout: fallback.stdout, note: Option.some(`could not refresh the OSV database, so the scan read the copy refreshed ${days} day(s) ago: ${first.reason}`) } satisfies ScanResult;
+});

package/src/dependencies/vendor.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
-import { Config, Console, Effect, FileSystem, Option, Path, Schema } from "effect";
+import { Console, Effect, FileSystem, Option, Path, Schema } from "effect";
 import { git } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
+import { cacheRoot } from "./cache-root.ts";
 import { librariesFrom, NAME, OPENER, type Library } from "./vendor-args.ts";
 
-const CACHE_HOME = ".cache/avi2dg-checks";
 const RECORD_SUFFIX = ".commit";
 const LINKS = "repos";
 const VERSION_TOKEN = "{version}";
@@ -303,14 +303,6 @@ const vend = Effect.fn("vend")(function* (root: string, cache: string, library:
   yield* ensureLink(root, library, dir);
 });
 
-const cacheRoot = Effect.fn("cacheRoot")(function* () {
-  const path = yield* Path.Path;
-  const home = yield* Config.NonEmptyString("HOME").pipe(
-    Effect.mapError(() => new VendorError({ message: "HOME is missing, so the shared cache has no root" })),
-  );
-  return path.join(home, CACHE_HOME);
-});
-
 const main = Effect.gen(function* () {
   const libraries = yield* librariesFrom(process.argv.slice(2));
   if (libraries.length === 0) {

package/src/docs/doc-agents.ts

@@ -0,0 +1,106 @@
+import { commandNames, type Snapshot } from "./doc-references.ts";
+import { AGENT_NAMES, scanMarkdown, type MarkdownLine } from "./prose-matchers.ts";
+
+export const AGENT_CEILING = 3000;
+
+const LIST_ITEM = /^(?:\s*>)*\s*(?:[-*+]|\d{1,9}[.)])(?:\s|$)/;
+const INDENT = /^[ \t]*/;
+const CODE_INDENT = 4;
+const INLINE_LINK =
+  /(?<![!\\])\[(?:[^[\]\\]|\\.|\[[^\]]*\])*\]\(\s*(?:<[^<>\n]+>|[^\s()<>]+(?:\([^\s()]*\)[^\s()<>]*)*)(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g;
+const MAINTAINING = /^\s{0,3}#{1,6}\s+Maintaining this file(?:\s+#+)?\s*$/;
+
+export type AgentFinding = {
+  readonly line: number | undefined;
+  readonly message: string;
+};
+
+export function isAgentFile(repositoryPath: string): boolean {
+  return AGENT_NAMES.includes(repositoryPath.slice(repositoryPath.lastIndexOf("/") + 1));
+}
+
+export function ceilingFinding(text: string): AgentFinding | undefined {
+  if (text.length <= AGENT_CEILING) return undefined;
+  return {
+    line: undefined,
+    message: `is ${text.length} characters, over the 3,000-character ceiling for agent files. Keep what nearly every session needs plus one pointer per part, move each part's notes into the people doc that covers that part, and delete what a check already holds`,
+  };
+}
+
+export function maintainingFinding(text: string): AgentFinding | undefined {
+  const heading = scanMarkdown(text).find(({ kind, raw }) => kind === "heading" && MAINTAINING.test(raw));
+  if (heading === undefined) return undefined;
+  return {
+    line: heading.line,
+    message: "holds `## Maintaining this file`, which a router leaves out. Delete the section, since checks-docs holds the file's shape",
+  };
+}
+
+function indentOf(raw: string): number {
+  return (INDENT.exec(raw)?.[0] ?? "").replaceAll("\t", "    ").length;
+}
+
+export function entries(text: string): readonly MarkdownLine[] {
+  let inList = false;
+  let afterBlank = true;
+  return scanMarkdown(text).filter((line) => {
+    const blank = line.raw.trim() === "";
+    const indented = !blank && indentOf(line.raw) >= CODE_INDENT && !line.raw.trimStart().startsWith(">");
+    const listItem = line.kind === "prose" && LIST_ITEM.test(line.prose) && (inList || !indented);
+    if (listItem) inList = true;
+    else if (!blank && !indented && (afterBlank || line.kind !== "prose")) inList = false;
+    afterBlank = blank;
+    return listItem;
+  });
+}
+
+type Tracked = Pick<Snapshot, "files" | "directories">;
+
+const STAYS = new Set(["", "."]);
+
+function joined(directory: string, segment: string): string {
+  return directory === "" ? segment : `${directory}/${segment}`;
+}
+
+function enter(directory: string, segment: string, tracked: Tracked): string | undefined {
+  if (STAYS.has(segment)) return directory;
+  if (segment === "..") return directory === "" ? undefined : directory.slice(0, Math.max(directory.lastIndexOf("/"), 0));
+  const next = joined(directory, segment);
+  return tracked.directories.has(next) ? next : undefined;
+}
+
+function resolvesFrom(directory: string, span: string, tracked: Tracked): boolean {
+  const segments = span.split("/");
+  const last = segments.pop() ?? "";
+  const walked = segments.reduce<string | undefined>((at, segment) => (at === undefined ? undefined : enter(at, segment, tracked)), directory);
+  if (walked === undefined) return false;
+  if (!STAYS.has(last) && last !== ".." && tracked.files.has(joined(walked, last))) return true;
+  const end = enter(walked, last, tracked);
+  return end !== undefined && end !== "" && end !== directory;
+}
+
+function namesTrackedPath(agentFile: string, span: string, tracked: Tracked): boolean {
+  const directory = agentFile.includes("/") ? agentFile.slice(0, agentFile.lastIndexOf("/")) : "";
+  const fromFile = resolvesFrom(directory, span, tracked);
+  return fromFile || (!span.startsWith("./") && !span.startsWith("../") && resolvesFrom("", span, tracked));
+}
+
+function namesLink({ raw, prose }: MarkdownLine): boolean {
+  return [...raw.matchAll(INLINE_LINK)].some(({ index }) => prose.charAt(index) === "[");
+}
+
+function points(agentFile: string, line: MarkdownLine, tracked: Tracked): boolean {
+  return line.code.some((span) => namesTrackedPath(agentFile, span, tracked)) || namesLink(line) || commandNames(line).length > 0;
+}
+
+export function entryFindings(agentFile: string, text: string, tracked: Tracked): readonly AgentFinding[] {
+  return entries(text).flatMap((line) => {
+    if (points(agentFile, line, tracked)) return [];
+    return [
+      {
+        line: line.line,
+        message: "names no tracked path, link or `bun run` command. Name the file, link or command that holds the detail",
+      },
+    ];
+  });
+}

package/src/docs/doc-references.ts

@@ -131,6 +131,10 @@ function commandsOn({ kind, raw, code }: MarkdownLine): readonly string[] {
   return texts.flatMap((text) => [...text.matchAll(RUN)].map(([, name = ""]) => name.replace(/[),.;:]+$/, "")));
 }
 
+export function commandNames(line: MarkdownLine): readonly string[] {
+  return commandsOn(line).filter((name) => !NOT_A_NAME.test(name));
+}
+
 export type Judging = { readonly commands: boolean };
 
 export function unresolvedIn(doc: string, text: string, snapshot: Snapshot, { commands }: Judging): readonly Unresolved[] {

package/src/docs/doc-templates.ts

@@ -57,14 +57,6 @@ const BEFORE_YOU_BEGIN = fixed("Before you begin", REQUIRED, ["- <each prerequis
 
 const STEPS = ["To <do the task>:", "", "1. <step>", "1. <step>"];
 
-const MAINTAINING = [
-  "Keep this file for knowledge useful to almost every future agent session in this project.",
-  "Do not repeat what the codebase already shows.",
-  "Point to the authoritative file or command instead.",
-  "Prefer rewriting or pruning existing entries over appending new ones.",
-  "When updating this file, preserve this bar for all agents and keep entries concise.",
-];
-
 export const CHANGE_GROUPS = ["Breaking changes", "Features", "Fixes", "Performance", "Reverts"] as const;
 export type ChangeGroup = (typeof CHANGE_GROUPS)[number];
 
@@ -122,7 +114,6 @@ export const TEMPLATES: Readonly<Record<Kind, Template>> = {
       open("<A topic an agent needs>", "any", optional("the lead holds every constraint"), [
         "- <A constraint an agent cannot infer from the code, and the file that holds its detail.>",
       ]),
-      fixed("Maintaining this file", REQUIRED, MAINTAINING),
     ],
   },
   claude: {

package/src/docs/docs.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 import { Console, Effect } from "effect";
-import { rootsOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
+import { ceilingFinding, entryFindings, isAgentFile, maintainingFinding } from "./doc-agents.ts";
+import { rootsOf, snapshotOf, unresolvedIn, type Judging, type Unresolved } from "./doc-references.ts";
 import { ADR_DIRECTORY, judge, placementOf, placementProblem, speaksToConsumers, type Placement } from "./doc-rules.ts";
 import { vanishedNames } from "./doc-names.ts";
 import { readTexts, snapshotAt, stillMissing } from "./doc-snapshot.ts";
@@ -18,6 +19,7 @@ type Judged = {
   readonly held: readonly string[];
   readonly edited: { readonly docs: number; readonly lines: number };
   readonly named: number;
+  readonly agents: number;
   readonly findings: readonly Finding[];
   readonly advisory: ReadonlyMap<string, number>;
   readonly brokenBefore: readonly Finding[];
@@ -109,13 +111,27 @@ const runDocs = Effect.fn("runDocs")(function* (root: string, base: string, head
   const referenced = new Map(proseDocs.map(({ path }) => [path, text(path)]));
   const references = yield* referenceFindings({ root, base, head, roots, changed, renamedFrom }, referenced, judging);
   const vanished = yield* vanishedNames(root, base, head, referenced, references.failed);
+  const agents = proseDocs.filter(({ path }) => isAgentFile(path));
+  const tracked = snapshotOf(yield* pathsAt(head, [], root), new Map(), new Map());
+  const shapes = agents.flatMap(({ path }) =>
+    [ceilingFinding(text(path)), maintainingFinding(text(path))].flatMap((finding) => (finding === undefined ? [] : [{ path, ...finding }])),
+  );
+  const entries = agents.flatMap(({ path }) => entryFindings(path, text(path), tracked).map((finding) => ({ path, ...finding })));
   const advisory = new Map<string, number>();
   for (const { path } of templated.filter((finding) => !touched.has(finding.path))) advisory.set(path, (advisory.get(path) ?? 0) + 1);
   return {
     held: judged.map(({ path }) => path).filter((path) => touched.has(path)),
     edited: { docs: edited.length, lines: edited.reduce((sum, { path }) => sum + (changed.get(path)?.size ?? 0), 0) },
     named: referenced.size,
-    findings: [...templated.filter((finding) => touched.has(finding.path)), ...prose, ...references.failing, ...vanished].toSorted(inPathOrder),
+    agents: agents.length,
+    findings: [
+      ...templated.filter((finding) => touched.has(finding.path)),
+      ...prose,
+      ...references.failing,
+      ...vanished,
+      ...shapes,
+      ...entries,
+    ].toSorted(inPathOrder),
     advisory,
     brokenBefore: references.brokenBefore.toSorted(inPathOrder),
   } satisfies Judged;
@@ -125,13 +141,14 @@ function describe({ path, line, message }: Finding): string {
   return `  ${path}${line === undefined ? "" : `:${line}`}: ${message}`;
 }
 
-export function report({ held, edited, named, findings, advisory, brokenBefore }: Judged): string {
+export function report({ held, edited, named, agents, findings, advisory, brokenBefore }: Judged): string {
   const verdict =
     findings.length === 0
       ? [
           `${NAME}: ${held.length} doc file(s) the range touches hold to their templates`,
           `${NAME}: ${edited.lines} line(s) the range adds or edits in ${edited.docs} living doc(s) or agent file(s) hold to the prose rules`,
           `${NAME}: the range breaks no path, link or command the ${named} living doc(s) or agent file(s) name`,
+          `${NAME}: the ${agents} agent file(s) hold to the ceiling, and every entry names a tracked path, a link or a command`,
         ]
       : [`${NAME}: ${findings.length} violation(s):`, ...findings.map(describe)];
   const unconformed =

package/src/testing/quarantine-clock.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import { Console, Effect, Schema } from "effect";
-import { commitOf, git, isShallowBoundary, refArgs } from "../core/git.ts";
+import { commitOf, git, isShallowBoundary, refArgs, writtenAt } from "../core/git.ts";
 import { runMain } from "../core/main.ts";
 import { TEST_FILE } from "./test-layout.ts";
 
@@ -125,19 +125,10 @@ const entryAt = Effect.fn("entryAt")(function* (root: string, head: string, file
   return { file, at: entry.at, day: entry.day };
 });
 
-const headAt = Effect.fn("headAt")(function* (root: string, head: string) {
-  const shown = yield* git(["show", "-s", "--format=%at %ct", head], root);
-  const dates = shown.trim().split(" ").map(Number);
-  if (dates.length !== 2 || !dates.every(Number.isInteger)) {
-    return yield* new QuarantineError({ message: `cannot read when ${head} was written` });
-  }
-  return Math.max(...dates);
-});
-
 export const runHead = Effect.fn("runHead")(function* (root: string, head: string) {
   const files = yield* filesAt(root, head);
   const entries = yield* Effect.forEach(files, (file) => entryAt(root, head, file));
-  return { checked: files.length, overdue: overdueOf(entries, yield* headAt(root, head)) } satisfies ClockResult;
+  return { checked: files.length, overdue: overdueOf(entries, yield* writtenAt(head, root)) } satisfies ClockResult;
 });
 
 const clock = Effect.gen(function* () {

package/src/testing/test.ts

@@ -118,7 +118,13 @@ const runSuite = Effect.fn("runSuite")(function* (outfile: string, tier: TestTie
   const tierArgs = tier === undefined ? [] : ["--path-ignore-patterns", "", `./tests/${tier}`];
   const args = ["test", "--randomize", ...tierArgs, ...reporterArgs(outfile)];
   return yield* spawner.exitCode(
-    ChildProcess.make(process.execPath, args, { stdin: "ignore", stdout: "inherit", stderr: "inherit" }),
+    ChildProcess.make(process.execPath, args, {
+      stdin: "ignore",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: { CI: "true" },
+      extendEnv: true,
+    }),
   );
 });