From cacad522ae00adff57d6219c871c887ada03e0f5 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 16:57:14 +0100 Subject: [PATCH 1/2] chore(hooks): the push hook runs CI's Fallow command and the tests of the repository's own files The audit form the hook ran exits 0 on findings that fail CI's whole-tree command. Tests that read the repository's files import no code, so pnpm test:changed never selects them; they take the name *.repo.test.ts and the hook runs them all in about a second. The manuals total rises to 160,000 characters. --- .claude/skills/refactor/SKILL.md | 2 +- .gitattributes | 2 +- docs/internal/VENDORED-CODE.md | 2 +- docs/internal/agent-rules/always-in-scope.md | 2 +- docs/internal/agent-rules/documentation.md | 2 +- docs/internal/agent-rules/toolchain.md | 7 +++++-- .../agent-rules/vendor-and-third-party-code.md | 2 +- docs/internal/templates/manual.md | 2 +- lefthook.yml | 11 +++++++++-- src/{adr-index.test.ts => adr-index.repo.test.ts} | 0 ...cs-audience.test.ts => docs-audience.repo.test.ts} | 10 ++++------ ...docs-manuals.test.ts => docs-manuals.repo.test.ts} | 2 +- ...ailures.test.ts => expected-failures.repo.test.ts} | 0 ...ands.test.ts => implementer-commands.repo.test.ts} | 0 src/{labels.test.ts => labels.repo.test.ts} | 2 +- ...ce-hygiene.test.ts => source-hygiene.repo.test.ts} | 0 src/{test-lanes.test.ts => test-lanes.repo.test.ts} | 0 vendor/README.md | 2 +- 18 files changed, 28 insertions(+), 20 deletions(-) rename src/{adr-index.test.ts => adr-index.repo.test.ts} (100%) rename src/{docs-audience.test.ts => docs-audience.repo.test.ts} (91%) rename src/{docs-manuals.test.ts => docs-manuals.repo.test.ts} (99%) rename src/{expected-failures.test.ts => expected-failures.repo.test.ts} (100%) rename src/{implementer-commands.test.ts => implementer-commands.repo.test.ts} (100%) rename src/{labels.test.ts => labels.repo.test.ts} (92%) rename src/{source-hygiene.test.ts => source-hygiene.repo.test.ts} (100%) rename src/{test-lanes.test.ts => test-lanes.repo.test.ts} (100%) diff --git a/.claude/skills/refactor/SKILL.md b/.claude/skills/refactor/SKILL.md index 2c8421e40..0fe46ff1b 100644 --- a/.claude/skills/refactor/SKILL.md +++ b/.claude/skills/refactor/SKILL.md @@ -24,7 +24,7 @@ A target is one of these, and nothing else: - **A file over a cut-off an accepted ADR sets.** ADR 0063 §3: code over 1,400 lines, a test file over 2,500, counted with `git ls-files src ui e2e scripts .agents/scripts | xargs wc -l`; the files on - `SHRINK_ONLY` in `src/source-hygiene.test.ts` count too. + `SHRINK_ONLY` in `src/source-hygiene.repo.test.ts` count too. - **A Fallow refactoring target**: `pnpm exec fallow health --format json --quiet --targets`, the first-ranked target. - **A Fallow duplication finding**: `pnpm exec fallow dupes --format json diff --git a/.gitattributes b/.gitattributes index ea35dcd0e..9e627ed8f 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,4 @@ # why: every feature adds rows to the ADR index; two features merging add different rows, and # a union merge keeps both instead of stopping the stack sync on an add/add conflict. The -# src/adr-index.test.ts check keeps the table complete and in order. +# src/adr-index.repo.test.ts check keeps the table complete and in order. docs/internal/adr/README.md merge=union diff --git a/docs/internal/VENDORED-CODE.md b/docs/internal/VENDORED-CODE.md index 965d10c1b..f8e48ede6 100644 --- a/docs/internal/VENDORED-CODE.md +++ b/docs/internal/VENDORED-CODE.md @@ -72,7 +72,7 @@ vendored while the Xcode that compiles it is not. [agent-rules/vendor-and-third-party-code.md](agent-rules/vendor-and-third-party-code.md). A binary also gets `SHA256SUMS.txt` in `shasum -c` format. 3. Add the row here and the directory to `vendor/README.md`'s index. -4. `pnpm exec vitest run --project unit src/source-hygiene.test.ts` checks the +4. `pnpm exec vitest run --project unit src/source-hygiene.repo.test.ts` checks the shape (license text, `NOTICE.md`, the digest, and that a vendored binary is excluded from the text scan for a reason it can prove). diff --git a/docs/internal/agent-rules/always-in-scope.md b/docs/internal/agent-rules/always-in-scope.md index 0e91ece55..df46a1d28 100644 --- a/docs/internal/agent-rules/always-in-scope.md +++ b/docs/internal/agent-rules/always-in-scope.md @@ -64,7 +64,7 @@ unless the maintainer explicitly authorizes its amendment. See and `vendor/README.md`'s index in the same change (vendor-and-third-party-code rule 11). A new first-level `vendor/` directory carries its license text under `LICENSES/` and a `NOTICE.md`; - `src/source-hygiene.test.ts` enforces that shape, and counts a vendored + `src/source-hygiene.repo.test.ts` enforces that shape, and counts a vendored binary as excluded from the text scan only where a `SHA256SUMS.txt` pins its digest (vendor-and-third-party-code rules 2, 3, 7). diff --git a/docs/internal/agent-rules/documentation.md b/docs/internal/agent-rules/documentation.md index 94e7d0ada..b59a1ef6d 100644 --- a/docs/internal/agent-rules/documentation.md +++ b/docs/internal/agent-rules/documentation.md @@ -59,7 +59,7 @@ grounds for rejecting a change even if the prose reads well. edited with every change. A line that restates code is deleted, not fixed. The shape and the budget are in [../templates/manual.md](../templates/manual.md), and - `src/docs-manuals.test.ts` holds them. A `CLAUDE.md` beside a manual + `src/docs-manuals.repo.test.ts` holds them. A `CLAUDE.md` beside a manual holds only `@AGENTS.md`, so Claude Code loads the manual when it reads a file in the module; other agents load it by the rule in the root `AGENTS.md`. A path that runs through several modules (startup, diff --git a/docs/internal/agent-rules/toolchain.md b/docs/internal/agent-rules/toolchain.md index 5dc208fe9..1e318e1cb 100644 --- a/docs/internal/agent-rules/toolchain.md +++ b/docs/internal/agent-rules/toolchain.md @@ -54,8 +54,11 @@ list and this one the same. (`.agents/scripts/commit-msg-check.mjs`) refuses a subject on `/` that is not `(): (#)`, and on `bug/-repro` one that is not `test: reproduce # — `. -- **Push hook:** Fallow's audit (the findings the branch adds against - `origin/main`), then the e2e typecheck. +- **Push hook:** CI's Fallow command on the whole tree, the + `*.repo.test.ts` files, the protocol and docs-surface checks, then the + e2e typecheck. A test that reads the repository's files instead of + importing code is named `*.repo.test.ts` and runs in about a second: + `pnpm test:changed` cannot select it, so the hook runs every one. - **CI:** what `pnpm check` runs, and Fallow, on every push. CI's Fallow (`fallow --ci`) checks the whole tree and fails on any dead-code finding or clone group, `warn` rules included; complexity fails above the diff --git a/docs/internal/agent-rules/vendor-and-third-party-code.md b/docs/internal/agent-rules/vendor-and-third-party-code.md index f1acb3686..ef8e400e1 100644 --- a/docs/internal/agent-rules/vendor-and-third-party-code.md +++ b/docs/internal/agent-rules/vendor-and-third-party-code.md @@ -22,7 +22,7 @@ this file is the rule that keeps the inventory true. in `src/`, `ui/`, `scripts/` or `e2e/`. `NOTICE.md`'s per-file origin table is what separates ours from theirs, and rule 6 makes that table mandatory precisely because the directory itself no longer does. The check - `src/source-hygiene.test.ts` runs is the licensing half of this claim, so a + `src/source-hygiene.repo.test.ts` runs is the licensing half of this claim, so a directory that fails it misrepresents itself. A file sitting at `vendor/`'s root is a packed archive, not a directory, and carries its license inside it (the tarball rule 1's npm case does not cover) — that is why the check is per diff --git a/docs/internal/templates/manual.md b/docs/internal/templates/manual.md index c32c964f3..e42792993 100644 --- a/docs/internal/templates/manual.md +++ b/docs/internal/templates/manual.md @@ -7,7 +7,7 @@ rule in the root `AGENTS.md`. It says what a change must not break and the code does not show (documentation rule 7). Rationale lives in ADRs; history in git. Budget: `MANUAL_CHARACTERS` for one manual and `MANUALS_TOTAL_CHARACTERS` for all of them together, both in -`src/docs-manuals.test.ts`. A new line fits in what is left or replaces +`src/docs-manuals.repo.test.ts`. A new line fits in what is left or replaces one; raising either number is a change the review sees. Before you write a line, ask: would an agent that read the module's index diff --git a/lefthook.yml b/lefthook.yml index 331521751..61033edaa 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -48,10 +48,17 @@ commit-msg: pre-push: piped: true commands: + # CI's own command (ci.yml, Fallow job): a push that passes here passes there. fallow: priority: 1 - run: pnpm exec fallow audit --base origin/main --format compact - fail_text: "Fallow found issues in your changes. Run 'pnpm fallow' to see details." + run: pnpm fallow --ci --format github-annotations + fail_text: "Fallow fails on this tree as it will in CI: fix each ::error and ::warning line (a ::notice never fails). One in a file the branch did not change means main is red: stop and report it." + # These tests read the repository's files rather than import code, so `pnpm test:changed` + # never selects them and any change can break them; together they take about a second. + repo-tests: + priority: 1 + run: pnpm exec vitest run --project unit .repo.test.ts + fail_text: "A test of the repository's own files fails (a size cap, the ADR index, a doc's audience): the output names the file and the rule." protocol-bump: priority: 1 run: node .agents/scripts/protocol-bump-check.mjs --base origin/main diff --git a/src/adr-index.test.ts b/src/adr-index.repo.test.ts similarity index 100% rename from src/adr-index.test.ts rename to src/adr-index.repo.test.ts diff --git a/src/docs-audience.test.ts b/src/docs-audience.repo.test.ts similarity index 91% rename from src/docs-audience.test.ts rename to src/docs-audience.repo.test.ts index a9d918240..e36b8836d 100644 --- a/src/docs-audience.test.ts +++ b/src/docs-audience.repo.test.ts @@ -9,7 +9,7 @@ import { blankSource } from "./test-support/source-text.js"; const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), ".."); -/** Every tracked path, from the git index, so no doc escapes by sitting in a directory the test did not name. */ +/** why: every tracked path comes from the git index, so no doc escapes by sitting in a directory the test did not name. */ const trackedFiles = execFileSync("git", ["ls-files", "-z"], { cwd: REPO_ROOT, encoding: "utf8", @@ -17,7 +17,7 @@ const trackedFiles = execFileSync("git", ["ls-files", "-z"], { }) .split("\0") .filter((name) => name.length > 0) - // A path deleted from the working tree is still listed by `git ls-files`; only regular files + // why: a path deleted from the working tree is still listed by `git ls-files`; only regular files // can be read. .filter((name) => { try { @@ -27,7 +27,6 @@ const trackedFiles = execFileSync("git", ["ls-files", "-z"], { } }); -/** A markdown file by extension, in any case: `.md` or `.markdown`. */ const isMarkdown = (name: string) => /\.(?:md|markdown)$/i.test(name); const WEBSITE_DOCS = "website/src/content/docs/"; @@ -53,7 +52,6 @@ const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); const internalName = (name: string) => new RegExp(`(? { it("include the known end-user docs, beside a list of internal-only names", () => { - // Without this, an empty enumeration would leave the scan below with nothing to read and + // why: without this, an empty enumeration would leave the scan below with nothing to read and // the suite would pass while checking no doc at all. expect(endUserDocs).toEqual( expect.arrayContaining([ diff --git a/src/docs-manuals.test.ts b/src/docs-manuals.repo.test.ts similarity index 99% rename from src/docs-manuals.test.ts rename to src/docs-manuals.repo.test.ts index f03dec458..b8e140113 100644 --- a/src/docs-manuals.test.ts +++ b/src/docs-manuals.repo.test.ts @@ -8,7 +8,7 @@ import { describe, expect, it } from "vitest"; const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), ".."); const BUDGET = 150; const MANUAL_CHARACTERS = 8000; -const MANUALS_TOTAL_CHARACTERS = 140000; +const MANUALS_TOTAL_CHARACTERS = 160000; const trackedFiles = execFileSync( "git", diff --git a/src/expected-failures.test.ts b/src/expected-failures.repo.test.ts similarity index 100% rename from src/expected-failures.test.ts rename to src/expected-failures.repo.test.ts diff --git a/src/implementer-commands.test.ts b/src/implementer-commands.repo.test.ts similarity index 100% rename from src/implementer-commands.test.ts rename to src/implementer-commands.repo.test.ts diff --git a/src/labels.test.ts b/src/labels.repo.test.ts similarity index 92% rename from src/labels.test.ts rename to src/labels.repo.test.ts index eba1d834b..23f708227 100644 --- a/src/labels.test.ts +++ b/src/labels.repo.test.ts @@ -14,7 +14,7 @@ interface Label { const labels = JSON.parse(readFileSync(LABELS, "utf8")) as readonly Label[]; -// The Labels workflow syncs this file to GitHub on every push to main. GitHub rejects the whole +// why: the Labels workflow syncs this file to GitHub on every push to main. GitHub rejects the whole // sync on the first label it refuses, so one bad entry silently leaves every later label // uncreated. describe(".github/labels.json", () => { diff --git a/src/source-hygiene.test.ts b/src/source-hygiene.repo.test.ts similarity index 100% rename from src/source-hygiene.test.ts rename to src/source-hygiene.repo.test.ts diff --git a/src/test-lanes.test.ts b/src/test-lanes.repo.test.ts similarity index 100% rename from src/test-lanes.test.ts rename to src/test-lanes.repo.test.ts diff --git a/vendor/README.md b/vendor/README.md index 0b4d0f14a..02daf8e8a 100644 --- a/vendor/README.md +++ b/vendor/README.md @@ -10,7 +10,7 @@ it holds the artifact(s), the license text(s) they require in `LICENSES/`, and a `NOTICE.md`: upstream and author, the exact commit or release, what was taken and what was left out, every deviation and why, the command that re-verifies it all against upstream, and — per file, because a directory here can hold our code -beside theirs — which files are ours. `src/source-hygiene.test.ts` enforces +beside theirs — which files are ours. `src/source-hygiene.repo.test.ts` enforces the three-part shape, and the rules are [`docs/internal/agent-rules/vendor-and-third-party-code.md`](../docs/internal/agent-rules/vendor-and-third-party-code.md); the whole inventory is [`docs/internal/VENDORED-CODE.md`](../docs/internal/VENDORED-CODE.md). From d7119b57fa942c823c1ae1d6325243f165e95d82 Mon Sep 17 00:00:00 2001 From: Szymon Chmal Date: Tue, 17 Nov 2026 17:23:55 +0100 Subject: [PATCH 2/2] docs(hooks): the push hook's comment and the toolchain line say what the checks cover Review notes R3 and R4: test:changed does select a repo test the branch edits, and the push checks cover the whole tree, not only the branch. --- docs/internal/agent-rules/toolchain.md | 3 ++- lefthook.yml | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/internal/agent-rules/toolchain.md b/docs/internal/agent-rules/toolchain.md index 1e318e1cb..28711f14c 100644 --- a/docs/internal/agent-rules/toolchain.md +++ b/docs/internal/agent-rules/toolchain.md @@ -58,7 +58,8 @@ list and this one the same. `*.repo.test.ts` files, the protocol and docs-surface checks, then the e2e typecheck. A test that reads the repository's files instead of importing code is named `*.repo.test.ts` and runs in about a second: - `pnpm test:changed` cannot select it, so the hook runs every one. + `pnpm test:changed` selects it only when the branch edits the test + itself, so the hook runs every one. - **CI:** what `pnpm check` runs, and Fallow, on every push. CI's Fallow (`fallow --ci`) checks the whole tree and fails on any dead-code finding or clone group, `warn` rules included; complexity fails above the diff --git a/lefthook.yml b/lefthook.yml index 61033edaa..e1bd3cd63 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -43,8 +43,8 @@ commit-msg: subject: run: node .agents/scripts/commit-msg-check.mjs {1} -# These audit the whole branch against main, so they run once per push rather than on every -# checkpoint commit. +# These check the whole tree, or the whole branch against main, so they run once per push +# rather than on every checkpoint commit. pre-push: piped: true commands: