Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/skills/refactor/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .gitattributes
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion docs/internal/VENDORED-CODE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
2 changes: 1 addition & 1 deletion docs/internal/agent-rules/always-in-scope.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
2 changes: 1 addition & 1 deletion docs/internal/agent-rules/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
8 changes: 6 additions & 2 deletions docs/internal/agent-rules/toolchain.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,12 @@ list and this one the same.
(`.agents/scripts/commit-msg-check.mjs`) refuses a subject on
`<kind>/<n>` that is not `<type>(<scope>): <what> (#<n>)`, and on
`bug/<n>-repro` one that is not `test: reproduce #<n> — <claim>`.
- **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` 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
Expand Down
2 changes: 1 addition & 1 deletion docs/internal/agent-rules/vendor-and-third-party-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/internal/templates/manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 11 additions & 4 deletions lefthook.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,22 @@ 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:
# 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
Expand Down
File renamed without changes.
10 changes: 4 additions & 6 deletions src/docs-audience.test.ts → src/docs-audience.repo.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,15 @@ 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",
maxBuffer: 32 * 1024 * 1024,
})
.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 {
Expand All @@ -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/";
Expand All @@ -53,7 +52,6 @@ const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

const internalName = (name: string) => new RegExp(`(?<![\\w-])${escape(name)}(?![\\w-])`, "i");

/** What documentation rule 2 forbids an end-user doc from naming. */
const FORBIDDEN: RegExp[] = [
/docs\/internal\b/,
// why: `internal/` starting a path: a link or a path in backticks or prose.
Expand All @@ -64,13 +62,13 @@ const FORBIDDEN: RegExp[] = [
];

/**
* Documentation rule 2 (`docs/internal/agent-rules/documentation.md`): an end-user doc never
* why: documentation rule 2 (`docs/internal/agent-rules/documentation.md`): an end-user doc never
* cites an ADR and never points into `docs/internal/` -- by link, by path, or by an internal
* doc's bare file name, in any case ("see ARCHITECTURE.md").
*/
describe("end-user docs", () => {
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([
Expand Down
2 changes: 1 addition & 1 deletion src/docs-manuals.test.ts → src/docs-manuals.repo.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
File renamed without changes.
File renamed without changes.
2 changes: 1 addition & 1 deletion src/labels.test.ts → src/labels.repo.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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", () => {
Expand Down
File renamed without changes.
File renamed without changes.
2 changes: 1 addition & 1 deletion vendor/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
Loading