@avi2dg/checks 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.16.0
+
+Released 2026-09-25.
+
+### Features
+
+- **scripts:** add checks-repetition to hold new repetition in production code (#46)
+- **scripts:** add the recommended size limits, a tests budget and an overrun ratchet (#45)
+
+## 0.15.0
+
+Released 2026-09-25.
+
+### Features
+
+- **scripts:** hold living docs to prose rules and resolvable references in checks-docs (#42)
+
 ## 0.14.0
 
 Released 2026-09-25.

package/CONTRIBUTING.md

@@ -81,7 +81,7 @@ To place a change:
 
 This repository holds itself to the kit, with two exceptions of its own.
 Its `.dependency-cruiser.cjs` redeclares `no-orphans` with the plugin entry added to its `pathNot`.
-Its `.oxlintrc.json` lifts `effect-channel/no-throw` from `scripts/comment-matchers.ts`, the one file under its Effect path that a host loads without `node_modules`.
+Its `.oxlintrc.json` lifts `effect-channel/no-throw` from `scripts/comment-matchers.ts`, whose synchronous `refused()` a host loads without `node_modules`.
 
 ## Related topics
 

package/README.md

@@ -16,6 +16,7 @@ A repository declares what it opts into once, in `quality.json`, and each check
   - `@swc/core` 1.16.2
   - `dependency-cruiser` 18.4.0
   - `effect` 4.0.0-rc.115
+  - `jscpd` 5.3.2
   - `oxlint` 1.83.0
   - `oxlint-tsgolint` 7.0.2002
 
@@ -30,7 +31,7 @@ To consume the kit from a repository:
    <!-- generated install: bun run build writes it from package.json and scripts/doc-blocks.ts -->
 
    ```sh
-   bun add -d @avi2dg/checks @effect/tsgo@0.45.0 @swc/core@1.16.2 dependency-cruiser@18.4.0 effect@4.0.0-rc.115 oxlint@1.83.0 oxlint-tsgolint@7.0.2002 typescript@7.0.2
+   bun add -d @avi2dg/checks @effect/tsgo@0.45.0 @swc/core@1.16.2 dependency-cruiser@18.4.0 effect@4.0.0-rc.115 jscpd@5.3.2 oxlint@1.83.0 oxlint-tsgolint@7.0.2002 typescript@7.0.2
    ```
 
    <!-- end generated install -->
@@ -120,6 +121,7 @@ A repository leaves out a gate that does not apply to it through `gates.lint`, a
 | [`checks-docs`](docs/gates/checks-docs.md) | the range | every repository |
 | [`checks-quality`](docs/gates/checks-quality.md) | the working tree | a repository tracking `quality.json` |
 | [`checks-size-budget`](docs/gates/checks-size-budget.md) | the range | a repository tracking `*.ts` or `*.tsx` |
+| [`checks-repetition`](docs/gates/checks-repetition.md) | the range | a repository tracking `*.ts` or `*.tsx` |
 | [`checks-feature-owners`](docs/gates/checks-feature-owners.md) | the range | a repository tracking `*.ts` or `*.tsx` |
 
 <!-- end generated gates -->

package/dist/feature-rules.js

@@ -1,8 +1,8 @@
 // scripts/feature-rules.ts
-import { Schema as Schema3 } from "effect";
+import { Schema as Schema4 } from "effect";
 
 // scripts/quality-file.ts
-import { Console, Effect, FileSystem, JsonSchema, Path, Schema as Schema2 } from "effect";
+import { Console, Effect, FileSystem, JsonSchema, Path, Schema as Schema3 } from "effect";
 
 // scripts/gates.ts
 import { Schema } from "effect";
@@ -20,6 +20,7 @@ var KIT_GATES = [
   { bin: "checks-docs", script: "docs.ts", reads: "range", appliesTo: EVERY_REPOSITORY },
   { bin: "checks-quality", script: "quality.ts", reads: "tree", args: ["--check"], appliesTo: QUALITY_DECLARATION },
   { bin: "checks-size-budget", script: "size-budget.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
+  { bin: "checks-repetition", script: "repetition.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE },
   { bin: "checks-feature-owners", script: "feature-owners.ts", reads: "range", appliesTo: TYPESCRIPT_SOURCE }
 ];
 var UNCONDITIONAL = KIT_GATES.filter((gate) => gate.appliesTo === EVERY_REPOSITORY).map((gate) => gate.bin);
@@ -31,81 +32,153 @@ var LintGates = Schema.Array(Schema.Literals(KIT_GATES.map((gate) => gate.bin)))
   return `checks-lint must run ${missing.join(", ")}, which ${verb} to ${EVERY_REPOSITORY}`;
 }, { toJsonSchema: () => ({ allOf: UNCONDITIONAL.map((bin) => ({ contains: { const: bin } })) }) }));
 
+// scripts/size-rules.ts
+import { Schema as Schema2 } from "effect";
+var TESTS_DIRECTORY = "tests";
+var COUNTED = { skipBlankLines: false, skipComments: false };
+var FILE_LINES = {
+  key: "fileLines",
+  rule: "max-lines",
+  options: COUNTED,
+  measured: /has too many lines \((\d+)\)/,
+  limits: "The most lines a file may hold, blank and comment lines counted"
+};
+var FUNCTION_LINES = {
+  key: "functionLines",
+  rule: "max-lines-per-function",
+  options: COUNTED,
+  measured: /has too many lines \((\d+)\)/,
+  limits: "The most lines a function may span, blank and comment lines counted"
+};
+var STATEMENTS = {
+  key: "statements",
+  rule: "max-statements",
+  options: {},
+  measured: /has too many statements \((\d+)\)/,
+  limits: "The most statements a function may hold"
+};
+var COMPLEXITY = {
+  key: "complexity",
+  rule: "complexity",
+  options: { variant: "modified" },
+  measured: /has a complexity of (\d+)/,
+  limits: "The highest cyclomatic complexity a function may reach, a switch counted once"
+};
+var DEPTH = {
+  key: "depth",
+  rule: "max-depth",
+  options: {},
+  measured: /nested too deeply \((\d+)\)/,
+  limits: "The deepest a block may nest inside a function"
+};
+var APPLIES = ["ratchet", "all"];
+var SIZE_DEFAULTS = {
+  applies: "ratchet",
+  production: { fileLines: 400, functionLines: 100, statements: 30, complexity: 15, depth: 4 },
+  tests: { fileLines: 600, statements: 50, complexity: 15, depth: 4 }
+};
+var Limit = Schema2.Int.check(Schema2.isGreaterThan(0));
+function limit({ limits }, fallback) {
+  return Schema2.optionalKey(Limit.annotate({ description: `${limits}; ${fallback} when absent` }));
+}
+var ProductionBudget = Schema2.Struct({
+  fileLines: limit(FILE_LINES, SIZE_DEFAULTS.production.fileLines),
+  functionLines: limit(FUNCTION_LINES, SIZE_DEFAULTS.production.functionLines),
+  statements: limit(STATEMENTS, SIZE_DEFAULTS.production.statements),
+  complexity: limit(COMPLEXITY, SIZE_DEFAULTS.production.complexity),
+  depth: limit(DEPTH, SIZE_DEFAULTS.production.depth)
+});
+var TestBudget = Schema2.Struct({
+  fileLines: limit(FILE_LINES, SIZE_DEFAULTS.tests.fileLines),
+  statements: limit(STATEMENTS, SIZE_DEFAULTS.tests.statements),
+  complexity: limit(COMPLEXITY, SIZE_DEFAULTS.tests.complexity),
+  depth: limit(DEPTH, SIZE_DEFAULTS.tests.depth)
+});
+var Size = Schema2.Struct({
+  applies: Schema2.optionalKey(Schema2.Literals(APPLIES).annotate({
+    description: `Which production and test files the budget holds: ratchet, the ones a range adds or changes, to no more overrun per rule than at the range's base; all, every one. ${SIZE_DEFAULTS.applies} when absent. The rest are listed as advisory`,
+    message: "Expected ratchet or all, and ratchet replaces changed"
+  })),
+  production: Schema2.optionalKey(ProductionBudget.annotate({
+    description: `The budget of the files under sources.production, and of the files listed as advisory outside ${TESTS_DIRECTORY}/`
+  })),
+  tests: Schema2.optionalKey(TestBudget.annotate({ description: `The budget of the files under ${TESTS_DIRECTORY}/, which sets no limit on a function's lines` }))
+}).annotate({
+  description: "The size budget oxlint holds production and test files to, read by checks-size-budget",
+  messageUnexpectedKey: "Expected only applies, production and tests, since each limit is set inside production or tests"
+});
+
 // scripts/quality-file.ts
 var SEGMENT = String.raw`(?!\.\.?(?:/|$))(?:\*\*|(?:[\w.@+-]|\*(?!\*))+)`;
 var FILE = String.raw`(?:[\w.@+-]|\*(?!\*))*\.\w+`;
-var PathGlob = Schema2.String.check(Schema2.isPattern(new RegExp(`^${SEGMENT}(?:/${SEGMENT})*/${FILE}$`), {
+var PathGlob = Schema3.String.check(Schema3.isPattern(new RegExp(`^${SEGMENT}(?:/${SEGMENT})*/${FILE}$`), {
   expected: "a glob from the repository root such as src/**/*.ts: a directory first, * within a segment, ** as a whole one, a file name with an extension last"
 })).annotate({
   identifier: "PathGlob",
   description: "A glob from the repository root that oxlint, the Effect language service and git read alike: a directory first, * within a segment, ** as a whole one, a file name with an extension last, and no braces, ?, [ or leading ./"
 });
+var DocGlob = Schema3.String.check(Schema3.isPattern(new RegExp(`^(?:${SEGMENT}/)*${FILE}$`), {
+  expected: "a glob from the repository root such as README.md or docs/**/*.md: * within a segment, ** as a whole one, a file name with an extension last"
+})).annotate({
+  identifier: "DocGlob",
+  description: "A glob from the repository root that checks-docs reads: * within a segment, ** as a whole one, a file name with an extension last"
+});
 var LITERAL_SEGMENT = String.raw`(?!\.\.?(?:/|$))[\w.@+-]+`;
-var DirectoryPath = Schema2.String.check(Schema2.isPattern(new RegExp(`^${LITERAL_SEGMENT}(?:/${LITERAL_SEGMENT})*$`), {
+var DirectoryPath = Schema3.String.check(Schema3.isPattern(new RegExp(`^${LITERAL_SEGMENT}(?:/${LITERAL_SEGMENT})*$`), {
   expected: "a directory from the repository root such as src/billing, with no glob and no trailing slash"
 })).annotate({ identifier: "DirectoryPath" });
-var FilePath = Schema2.String.check(Schema2.isPattern(new RegExp(`^(?:${LITERAL_SEGMENT}/)*[\\w.@+-]*\\.\\w+$`), {
+var FilePath = Schema3.String.check(Schema3.isPattern(new RegExp(`^(?:${LITERAL_SEGMENT}/)*[\\w.@+-]*\\.\\w+$`), {
   expected: "a file from the repository root such as src/billing/index.ts, with no glob"
 })).annotate({ identifier: "FilePath" });
 var PROOF_DIRECTORY = "tests/e2e/";
-var ProofPath = Schema2.String.check(Schema2.isPattern(new RegExp(`^${PROOF_DIRECTORY}(?:${LITERAL_SEGMENT}/)*[\\w.@+-]+\\.test\\.tsx?$`), {
+var ProofPath = Schema3.String.check(Schema3.isPattern(new RegExp(`^${PROOF_DIRECTORY}(?:${LITERAL_SEGMENT}/)*[\\w.@+-]+\\.test\\.tsx?$`), {
   expected: `a test file under ${PROOF_DIRECTORY} such as ${PROOF_DIRECTORY}billing.test.ts`
 })).annotate({ identifier: "ProofPath" });
-var Command = Schema2.NonEmptyString.annotate({ identifier: "Command" });
-var RuleName = Schema2.String.check(Schema2.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a Rule name in kebab case" })).annotate({ identifier: "RuleName" });
-var Identity = Schema2.Struct({ name: Schema2.NonEmptyString, email: Schema2.NonEmptyString }).annotate({
+var Command = Schema3.NonEmptyString.annotate({ identifier: "Command" });
+var RuleName = Schema3.String.check(Schema3.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a Rule name in kebab case" })).annotate({ identifier: "RuleName" });
+var Identity = Schema3.Struct({ name: Schema3.NonEmptyString, email: Schema3.NonEmptyString }).annotate({
   identifier: "Identity"
 });
-var CommitIdentity = Schema2.Struct({
-  authors: Schema2.NonEmptyArray(Identity).annotate({
+var CommitIdentity = Schema3.Struct({
+  authors: Schema3.NonEmptyArray(Identity).annotate({
     description: "The identities allowed to author and commit, in place of the kit's default owner"
   })
 });
-var Gates = Schema2.Struct({
-  ci: Schema2.optionalKey(Schema2.NonEmptyArray(Command).annotate({
+var Gates = Schema3.Struct({
+  ci: Schema3.optionalKey(Schema3.NonEmptyArray(Command).annotate({
     description: "The commands CI runs on every pull request to the default branch, each one plain command"
   })),
-  scheduled: Schema2.optionalKey(Schema2.Array(Command).annotate({ description: "The commands a cron-scheduled workflow runs" })),
-  lint: Schema2.optionalKey(LintGates)
+  scheduled: Schema3.optionalKey(Schema3.Array(Command).annotate({ description: "The commands a cron-scheduled workflow runs" })),
+  lint: Schema3.optionalKey(LintGates)
 });
-var EffectSources = Schema2.Struct({
-  paths: Schema2.NonEmptyArray(PathGlob).annotate({
+var EffectSources = Schema3.Struct({
+  paths: Schema3.NonEmptyArray(PathGlob).annotate({
     description: "Where source is written in Effect, held to the Effect rules of oxlint and the language service"
   }),
-  exempt: Schema2.optionalKey(Schema2.Array(PathGlob).annotate({ description: "Files under paths the Effect rules pass over" }))
+  exempt: Schema3.optionalKey(Schema3.Array(PathGlob).annotate({ description: "Files under paths the Effect rules pass over" }))
 });
-var Sources = Schema2.Struct({
-  production: Schema2.optionalKey(Schema2.Array(PathGlob).annotate({ description: "The source the repository ships, as against tests and tooling" })),
-  effect: Schema2.optionalKey(EffectSources)
+var Sources = Schema3.Struct({
+  production: Schema3.optionalKey(Schema3.Array(PathGlob).annotate({ description: "The source the repository ships, as against tests and tooling" })),
+  effect: Schema3.optionalKey(EffectSources)
 });
-var LineBudget = Schema2.Int.check(Schema2.isGreaterThan(0));
-var Size = Schema2.Struct({
-  fileLines: LineBudget.annotate({ description: "The most lines a file may hold, blank and comment lines counted" }),
-  functionLines: LineBudget.annotate({
-    description: "The most lines a function may span, blank and comment lines counted"
-  }),
-  applies: Schema2.Literals(["changed", "all"]).annotate({
-    description: "Which production files the budget holds: changed, the ones a range adds or changes; all, every one. The rest are reported as advisory"
-  })
-});
-var Feature = Schema2.Struct({
-  name: Schema2.String.check(Schema2.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a feature name in kebab case" })).annotate({ description: "The owner the dependency rule and the change signal name" }),
+var Feature = Schema3.Struct({
+  name: Schema3.String.check(Schema3.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { expected: "a feature name in kebab case" })).annotate({ description: "The owner the dependency rule and the change signal name" }),
   root: DirectoryPath.annotate({ description: "The directory the feature owns" }),
-  entries: Schema2.NonEmptyArray(FilePath).annotate({
+  entries: Schema3.NonEmptyArray(FilePath).annotate({
     description: "The files under root that code outside it imports the feature through"
   }),
-  allowFrom: Schema2.optionalKey(Schema2.Array(PathGlob).annotate({
+  allowFrom: Schema3.optionalKey(Schema3.Array(PathGlob).annotate({
     description: "Files outside root that may import past its entries, such as a CLI or a harness; tests/ always may"
   })),
   proof: ProofPath.annotate({ description: "The end-to-end test that imports one of entries" })
-}).check(Schema2.makeFilter(({ root, entries }) => {
+}).check(Schema3.makeFilter(({ root, entries }) => {
   const outside = entries.filter((entry) => !entry.startsWith(`${root}/`));
   return outside.length === 0 || `lists ${outside.join(", ")} among its entries, outside its root ${root}`;
 }));
 function nests(outer, inner) {
   return outer === inner || inner.startsWith(`${outer}/`);
 }
-var Features = Schema2.Array(Feature).check(Schema2.makeFilter((features) => {
+var Features = Schema3.Array(Feature).check(Schema3.makeFilter((features) => {
   const names = features.map((feature) => feature.name);
   const repeated = names.filter((name, index) => names.indexOf(name) !== index);
   if (repeated.length > 0)
@@ -117,71 +190,74 @@ var Features = Schema2.Array(Feature).check(Schema2.makeFilter((features) => {
   }
   return true;
 }));
-var AgentRules = Schema2.Struct({
-  on: Schema2.optionalKey(Schema2.Array(RuleName).annotate({ description: "Catalogued Rules switched on here" })),
-  off: Schema2.optionalKey(Schema2.Array(RuleName).annotate({ description: "Catalogued Rules switched off here" }))
-}).check(Schema2.makeFilter(({ on = [], off = [] }) => {
+var AgentRules = Schema3.Struct({
+  on: Schema3.optionalKey(Schema3.Array(RuleName).annotate({ description: "Catalogued Rules switched on here" })),
+  off: Schema3.optionalKey(Schema3.Array(RuleName).annotate({ description: "Catalogued Rules switched off here" }))
+}).check(Schema3.makeFilter(({ on = [], off = [] }) => {
   const both = on.filter((rule) => off.includes(rule));
   return both.length === 0 || `switches ${both.join(", ")} both on and off`;
 }));
-var pagesIn = (mode) => Schema2.optionalKey(Schema2.Array(PathGlob).annotate({ description: `The pages written as ${mode}` }));
-var Docs = Schema2.Struct({
-  pages: Schema2.optionalKey(Schema2.Struct({
+var pagesIn = (mode) => Schema3.optionalKey(Schema3.Array(PathGlob).annotate({ description: `The pages written as ${mode}` }));
+var Docs = Schema3.Struct({
+  pages: Schema3.optionalKey(Schema3.Struct({
     tutorial: pagesIn("a tutorial, which teaches by building one thing"),
     "how-to": pagesIn("a how-to, which walks one task"),
     reference: pagesIn("reference, which describes a thing to be looked up"),
     explanation: pagesIn("an explanation, which says why")
   }).annotate({
     description: "The Diátaxis mode of each page, whose template checks-docs holds the page to; a page under docs/ needs one"
+  })),
+  forConsumers: Schema3.optionalKey(Schema3.Array(DocGlob).annotate({
+    description: "The living docs that speak to a repository installing this one, whose bun run commands checks-docs does not hold to this package.json"
   }))
 });
-var Quality = Schema2.Struct({
-  $schema: Schema2.optionalKey(Schema2.String),
-  defaultBranch: Schema2.optionalKey(Schema2.NonEmptyString.annotate({ description: "The branch pull requests merge into; main when absent" })),
-  gates: Schema2.optionalKey(Gates),
-  commitIdentity: Schema2.optionalKey(CommitIdentity),
-  sources: Schema2.optionalKey(Sources),
-  size: Schema2.optionalKey(Size.annotate({ description: "The line budget oxlint holds production files to, read by checks-size-budget" })),
-  features: Schema2.optionalKey(Features.annotate({
+var Quality = Schema3.Struct({
+  $schema: Schema3.optionalKey(Schema3.String),
+  defaultBranch: Schema3.optionalKey(Schema3.NonEmptyString.annotate({ description: "The branch pull requests merge into; main when absent" })),
+  gates: Schema3.optionalKey(Gates),
+  commitIdentity: Schema3.optionalKey(CommitIdentity),
+  sources: Schema3.optionalKey(Sources),
+  size: Schema3.optionalKey(Size),
+  features: Schema3.optionalKey(Features.annotate({
     description: "The feature owners dependency-cruiser holds to their entries and checks-feature-owners maps a change to"
   })),
-  changeSignal: Schema2.optionalKey(Schema2.Literal("advisory").annotate({
+  changeSignal: Schema3.optionalKey(Schema3.Literal("advisory").annotate({
     description: "Report which feature owners a change touches, without failing on it"
   })),
-  agentRules: Schema2.optionalKey(AgentRules),
-  docs: Schema2.optionalKey(Docs.annotate({ description: "What checks-docs reads to map a doc file to its template" }))
+  agentRules: Schema3.optionalKey(AgentRules),
+  docs: Schema3.optionalKey(Docs.annotate({ description: "What checks-docs reads to map a doc file to its template" }))
 }).annotate({
   title: QUALITY_FILE,
   description: "What a repository has opted into from @avi2dg/checks, read by its bins and agent Rule selection"
-}).check(Schema2.makeFilter(({ size, sources }) => size === undefined || (sources?.production ?? []).length > 0 || "declares size, which holds nothing without sources.production", {
+}).check(Schema3.makeFilter(({ size, sources }) => size === undefined || (sources?.production ?? []).length > 0 || "declares size, which holds no production file without sources.production", {
   toJsonSchema: () => ({
     if: { required: ["size"] },
     then: { required: ["sources"], properties: { sources: { required: ["production"], properties: { production: { minItems: 1 } } } } }
   })
-}), Schema2.makeFilter(({ changeSignal, features = [] }) => changeSignal === undefined || features.length > 0 || "declares changeSignal, which maps a change to no owner without features", {
+}), Schema3.makeFilter(({ changeSignal, features = [] }) => changeSignal === undefined || features.length > 0 || "declares changeSignal, which maps a change to no owner without features", {
   toJsonSchema: () => ({
     if: { required: ["changeSignal"] },
     then: { required: ["features"], properties: { features: { minItems: 1 } } }
   })
 }));
-var LegacyManifest = Schema2.Struct({
-  ciWiring: Schema2.optionalKey(Schema2.Struct({
-    gates: Schema2.optionalKey(Schema2.NonEmptyArray(Command)),
-    scheduled: Schema2.optionalKey(Schema2.Array(Command)),
-    lintGates: Schema2.optionalKey(LintGates),
-    defaultBranch: Schema2.optionalKey(Schema2.NonEmptyString)
+var LegacyManifest = Schema3.Struct({
+  ciWiring: Schema3.optionalKey(Schema3.Struct({
+    gates: Schema3.optionalKey(Schema3.NonEmptyArray(Command)),
+    scheduled: Schema3.optionalKey(Schema3.Array(Command)),
+    lintGates: Schema3.optionalKey(LintGates),
+    defaultBranch: Schema3.optionalKey(Schema3.NonEmptyString)
   })),
-  commitIdentity: Schema2.optionalKey(CommitIdentity)
+  commitIdentity: Schema3.optionalKey(CommitIdentity)
 });
 var LEGACY_KEYS = ["ciWiring", "commitIdentity"];
 
-class QualityUnreadable extends Schema2.TaggedError()("QualityUnreadable", {
-  message: Schema2.String
+class QualityUnreadable extends Schema3.TaggedError()("QualityUnreadable", {
+  message: Schema3.String
 }) {
 }
 var MANIFEST = "package.json";
-var decodeQualityJson = Schema2.decodeUnknownEffect(Schema2.fromJsonString(Quality), { onExcessProperty: "error" });
-var decodeManifestJson = Schema2.decodeUnknownEffect(Schema2.fromJsonString(LegacyManifest));
+var decodeQualityJson = Schema3.decodeUnknownEffect(Schema3.fromJsonString(Quality), { onExcessProperty: "error" });
+var decodeManifestJson = Schema3.decodeUnknownEffect(Schema3.fromJsonString(LegacyManifest));
 var decodeQuality = (text, source) => decodeQualityJson(text).pipe(Effect.mapError((cause) => new QualityUnreadable({ message: `${source}: ${cause.message}` })));
 function fromLegacy({ ciWiring, commitIdentity }) {
   const gates = {
@@ -245,7 +321,7 @@ function rulesFor(features) {
     to: { path: `^${escaped(root)}/`, pathNot: entries.map((entry) => `^${escaped(entry)}$`) }
   }));
 }
-var decode = Schema3.decodeUnknownSync(Quality);
+var decode = Schema4.decodeUnknownSync(Quality);
 function featureRules(quality) {
   return rulesFor(decode(quality, { onExcessProperty: "error" }).features ?? []);
 }

package/docs/configs/quality-file.md

@@ -19,7 +19,7 @@ The kit's bins find the file at the git root and read it there:
     "production": ["src/**/*.ts"],
     "effect": { "paths": ["src/**/*.ts"], "exempt": ["src/host/*.ts"] }
   },
-  "size": { "fileLines": 400, "functionLines": 100, "applies": "changed" },
+  "size": { "applies": "ratchet", "tests": { "fileLines": 800 } },
   "features": [
     {
       "name": "billing",
@@ -44,14 +44,15 @@ The kit's bins find the file at the git root and read it there:
 | `gates.scheduled` | `checks-ci-wiring` | the commands a schedule runs |
 | `gates.lint` | `checks-lint`, `checks-ci-wiring` | the gates `checks-lint` runs when not all apply, as [Gate selection](../gates/checks-lint.md#gate-selection) says |
 | `commitIdentity.authors` | `checks-commit-identity` | the identities allowed to author and commit, as [checks-commit-identity](../gates/checks-commit-identity.md) says |
-| `sources.production` | `checks-size-budget`, `checks-quality` | the source the repository ships, as [checks-size-budget](../gates/checks-size-budget.md) says |
+| `sources.production` | `checks-size-budget`, `checks-repetition`, `checks-quality` | the source the repository ships, as [checks-size-budget](../gates/checks-size-budget.md) and [checks-repetition](../gates/checks-repetition.md) say |
 | `sources.effect` | `checks-quality` | the paths held to the Effect rules, and the files under them that are not, as [The Effect rules](effect-rules.md) says |
-| `size` | `checks-size-budget` | the line budget, and which production files it holds |
+| `size` | `checks-size-budget` | the size budget of production and test files, and how a change is held to it, as [checks-size-budget](../gates/checks-size-budget.md) says |
 | `features` | `featureRules`, `checks-feature-owners` | each feature's root, entries, exempt importers and proof, as [checks-feature-owners](../gates/checks-feature-owners.md) says |
 | `changeSignal` | `checks-feature-owners` | `advisory` to list the feature owners a change touches |
 | `agentRules.on` | agent Rule selection, not the kit | catalogued Rules switched on for this repository |
 | `agentRules.off` | agent Rule selection, not the kit | catalogued Rules switched off for this repository |
 | `docs.pages` | `checks-docs` | the Diátaxis mode of each page, by glob, as [checks-docs](../gates/checks-docs.md) says |
+| `docs.forConsumers` | `checks-docs` | the living docs that speak to a repository installing this one, by glob, whose `bun run` commands name that repository's scripts |
 
 <!-- end generated quality-keys -->
 

package/docs/design.md

@@ -14,6 +14,13 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
 - `featureRules` ships compiled as `dist/feature-rules.js` for the same reason, with `effect` left out of the bundle so it resolves the consumer's own copy.
   dependency-cruiser uses a config's export as it is and never awaits it, so the declaration decodes synchronously, and `quality.json` exempts that one file from the Effect rules.
 - `checks-size-budget` writes the head commit's files to a temporary directory and runs oxlint there, with a configuration that sets no plugin and turns every category off, so the consumer's own `.oxlintrc.json`, its ignore files and its other rules never reach the count.
+- `checks-size-budget` ratchets against the base of the range rather than a committed baseline such as `oxlint-suppressions.json`.
+  A suppression file stores a count of sites per file and rule, and `max-lines` reports a file once however long it grows, so the count stays at one while the file doubles.
+  The gate sums how far each site runs over its limit instead, which grows with the file.
+  The base commit already holds that sum, so nothing is generated, committed or pruned.
+- `checks-repetition` writes the production files of both ends of the range to temporary directories and runs jscpd in each, so the consumer's `.jscpd.json` and ignore files never reach the count.
+  It compares each file's count of repeated lines rather than using jscpd's `--baseline-from-ref`.
+  That flag reports a repeated block as new once its text changes, so a change that shortens a grandfathered block would fail.
 - `dist/` is committed.
   No `prepack` or `prepublishOnly` builds it, so a publish ships whatever bundle the publishing worktree holds.
   Rebuild it after pulling with `bun run build`.
@@ -25,7 +32,8 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A bump not newer than the release before it is a revert: it cancels every release above the version it returns to, and a tag only keeps a reverted release that was already published.
   The committed changelog is the record of what was released: a version older than the newest it lists and absent from it was never published, and its commits go into the next release.
   A section keeps the date it was written with, since the squash merge that lands the release commit may fall on another day.
-  Entries come from commit subjects, the squash-merged pull request titles commitlint holds to the conventional format; the bodies are the branch's own messages, which nothing lints.
+  Entries come from commit subjects, the squash-merged pull request titles commitlint holds to the conventional format.
+  The bodies are the branch's own messages, which nothing lints.
   The release path needs no `contents: write`: the changelog arrives in the release commit's pull request, not from a workflow that pushes.
 - `quality.json` is JSON, not TOML or a TypeScript module: a bun bin, a hook running without `node_modules`, a `.cjs` or `.mjs` config and `jq` all parse it with nothing installed, and nobody runs a repository's own code to learn its policy.
   It holds declarations only.
@@ -71,6 +79,22 @@ Each entry below is a choice in the kit's shape and the constraint that forced i
   A repository adopts the templates as its files change, and an untouched file is listed as advisory rather than failing a change that never read it.
 - A task heading is verb first, and review holds it there rather than the check.
   No word list tells `Test layout` from `Test the layout`, and a check that passes the noun is worse than none.
+- The prose rules judge only the lines a change adds or edits, the way `checks-comment-gate` judges comments.
+  Text nobody touched never turns a change red, a record keeps the words it was written in, and a repository needs no cleanup pass before the gate runs.
+- A living doc takes one sentence per line, so a changed line is a changed sentence.
+  Under a hard wrap a one-word edit reflows a paragraph, and the gate would then demand fixes to sentences the edit never touched.
+- An agent file such as `AGENTS.md` takes the separator rules and no other prose rule.
+  One sentence per line serves the people who review a doc's diffs, and an agent file keeps each entry to one line however many sentences it holds.
+- `scripts/prose-matchers.ts` imports nothing, so the gate and a write-time hook run one matcher and refuse in the same words.
+  A hook bundle ships without `node_modules`, so a matcher that needed Vale or a package could not refuse at write time.
+- Readability grades and words such as easy stay out of the prose rules.
+  A score cannot fail a change without failing correct prose, and a suggestion nobody runs an editor for is never seen.
+- A path, link or command on a line the range leaves alone fails when the range broke it, as by deleting the file it names.
+  A reference goes stale when the code it names moves far more often than when its own line is edited, so a gate on edited lines alone would miss the usual break.
+- A path under a top directory the repository lacks names a file in another repository, such as a consumer's, and no program tells that from a typo.
+  A directory the range deletes still counts as this repository's, so a path under it reads as stale rather than foreign.
+- The command check passes over the docs a repository declares under `docs.forConsumers`.
+  This kit's README and reference pages speak to a consuming repository, whose scripts are not this one's, and no program tells an example for a consumer from an instruction for a contributor.
 
 ## Related topics
 

package/docs/gates/checks-docs.md

@@ -1,10 +1,12 @@
 # checks-docs
 
-`checks-docs` is the gate that holds each doc file a change touches to the template for its kind, and a reader looks it up to learn which template a file answers to.
+`checks-docs` is the gate that holds each doc file a change touches to the template for its kind, each line a change adds to a living doc or an agent file to the prose rules, and each path, link and command a living doc names to what the repository holds, and a reader looks it up to learn what a doc file answers to.
 
 ## What it checks
 
 It holds each doc file a change touches to the template for its kind, and lists every other doc file that does not conform yet without failing.
+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 names a path, link or command that does not resolve, and the range added it or broke it, as [Paths, links and commands](#paths-links-and-commands) says.
 The package ships one template per kind under `templates/`, and a repository starts a new doc file by copying one:
 
 ```sh
@@ -51,12 +53,81 @@ A template decides a file's structure, and the template file itself is the refer
 - A changelog lists its releases newest first, each opening with a `Released YYYY-MM-DD.` line.
 - A how-to or tutorial page numbers its steps.
 - `CLAUDE.md` is its template word for word.
-  It is a fixed agent pointer rather than a people doc, so the separator ban does not apply to it: people docs take no em dash, en dash, parenthesis or hyphen used as a dash, and no semicolon, and `checks-docs` does not check separators.
+  It is a fixed agent pointer rather than a living doc, so it takes only the prose rules for agent files.
+
+## The prose rules
+
+A line a change adds or edits in a living doc or an agent file is held to the prose rules, and a line the change leaves alone is not, so a repository needs no cleanup pass before it runs them.
+
+<!-- generated living-docs: bun run build writes it from scripts/prose-matchers.ts and scripts/doc-blocks.ts -->
+
+A living doc is one of these:
+
+- a `README.md` or `CONTRIBUTING.md` in any directory
+- a Markdown page under `docs/`
+
+An agent file is a `AGENTS.md` or `CLAUDE.md` in any directory, and takes only the rules the table below marks for agent files.
+
+These are records, and take no prose rule:
+
+- a file in `docs/adr/`
+- a file whose name opens with four digits, as in `0001-` or `2026-05-08-`
+- a `CHANGELOG.md`
+
+<!-- end generated living-docs -->
+
+<!-- generated prose-rules: bun run build writes it from PROSE_RULES in scripts/prose-matchers.ts and scripts/doc-blocks.ts -->
+
+| Refused | For example | Write instead | In agent files |
+| --- | --- | --- | --- |
+| an em dash | `—` | End the sentence, or use a comma | yes |
+| an en dash | `–` | End the sentence, or use a comma | yes |
+| a parenthesis other than the plural `(s)` | `(` | Make the aside its own sentence, or set it off with commas | yes |
+| a hyphen used as a dash | `a - b` or `a -- b` | End the sentence, or use a comma | yes |
+| a semicolon | `;` | Use two sentences | yes |
+| a promise about the future | `until #11`, `is planned`, `will soon`, `coming soon`, `in a future release` | Say what is true now | no |
+| a sentence that opens by talking about the page | `This page explains` | Talk directly about the subject | no |
+| a second sentence on one line | `It builds. It ships.` | Start it on its own line | no |
+| a sentence that runs across lines | `It builds` with `and ships.` on the next line | Join the sentence onto one line | no |
+
+<!-- end generated prose-rules -->
+
+A line holds one sentence, so a changed line is a changed sentence.
+A bold label that opens a line, as in `**Status.**`, heads the sentence after it rather than counting as one.
+Fenced code, inline code, link destinations, URLs, HTML comments and front matter are not prose, so no rule reads them.
+Readability scores and word choice, such as easy, are not checked.
+
+`scripts/prose-matchers.ts` holds the rules and a synchronous `proseRefused()`, and imports nothing.
+A host such as a hook bundle can therefore copy it alone into a directory with no `node_modules` and import it as `@avi2dg/checks/scripts/prose-matchers.ts`, to refuse the same lines at write time.
+
+## Paths, links and commands
+
+Each reference a living doc names has to resolve at the head commit:
+
+- A path in inline code that ends in a file extension, such as `scripts/lint.ts`, names a file from the root or from the doc's directory.
+- A relative Markdown link names a file or a directory, and its anchor names a heading in the file it links, as GitHub derives the anchor, or an explicit `id`.
+- A `bun run` command in code names a script in the nearest `package.json`, a bin in `node_modules/.bin`, or a file that exists.
+
+A reference that does not resolve fails when it sits on a line the range adds or edits.
+It fails on any other line when the range broke it, as by deleting the file it names or renaming the heading it links, and is listed as advisory when it was broken before the range.
+A path under a top directory the repository lacks at both ends of the range names another repository's file, such as a consumer's, and is passed over.
+So is a path git ignores, since a clean checkout lacks a generated file by design.
+
+A doc that speaks to a repository installing this one is declared under `docs.forConsumers` in `quality.json`, and its commands are not held to this repository's `package.json`:
+
+```json
+"docs": {
+  "forConsumers": ["README.md", "docs/gates/*.md"]
+}
+```
 
 ## What it reads
 
 It reads each Markdown file from the head commit, and `docs.pages` from `quality.json`.
 A file the range adds, changes or renames is held to its template, and a file it deletes is not.
+It reads the lines the range adds or edits from the diff, with renames detected, so a renamed doc is judged only on the lines the rename changed.
+It reads the files tracked at both ends of the range, the `scripts` of each `package.json` a living doc sits under, and `docs.forConsumers` from `quality.json`.
+From the working tree it reads the ignore files git reads, and `node_modules/.bin`.
 
 ## Arguments
 
@@ -72,24 +143,30 @@ 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 |
-| 1 | a doc file the range touches does not |
-| 2 | `quality.json` does not decode, or a ref does not resolve |
+| 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, and it adds or breaks no reference that does not resolve |
+| 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, or the range adds or breaks a reference that does not resolve |
+| 2 | `quality.json` or a `package.json` does not decode, or a ref does not resolve |
 
 ## Sample output
 
 ```
-docs: 2 violation(s) in the doc files the range touches:
+docs: 4 violation(s):
   README.md:1: lacks `## Where things are`
+  README.md:12: carries `;`, a semicolon. Use two sentences
+  README.md:20: names `scripts/bild.ts`, which is not in the repository
   docs/parts.md: is a page under docs/ with no mode; declare it under docs.pages in quality.json as tutorial, how-to, reference, explanation
 docs: advisory, 1 doc file(s) the range leaves alone do not hold to their templates yet:
   docs/adr/0001-quality-gates.md: 5 violation(s)
+docs: advisory, 1 path(s), link(s) or command(s) the living docs name were broken before the range:
+  docs/parts.md:9: links to `suppliers.md#prices`, and `docs/suppliers.md` has no heading with that anchor
 ```
 
 ## Opting out
 
 It applies to every repository, so no selection leaves it out.
 A file the range leaves alone is only listed as advisory, so a repository adopts the templates as its files change.
+A line the range leaves alone takes no prose rule, so a repository adopts the prose rules as its lines change.
+A doc listed under `docs.forConsumers` holds no `bun run` command to this repository's `package.json`.
 `checks-lint` runs it over each pull request's range, as [checks-lint](checks-lint.md) says.
 
 ## Related topics

package/docs/gates/checks-lint.md

@@ -64,7 +64,7 @@ It prints the range, the declared selection if there is one, each gate's own rep
 ```
 checks-lint: range 2504acf098d120e73a8ece3c96f22b934f35c6a8..10ba7d8935b73ed72624120a1542e51bd21ca7c7 from HEAD against origin/main
 ...
-checks-lint: 3 of 10 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
+checks-lint: 3 of 11 gate(s) failed: checks-commit-identity, checks-comment-gate, checks-suppressions-ratchet
 ```
 
 ## Opting out
@@ -74,7 +74,7 @@ A repository that runs its gates without `checks-lint` calls each gate's bin in
 
 ## Gate selection
 
-A repository with no TypeScript source gives `checks-lint-coverage`, `checks-test-layout`, `checks-size-budget` and `checks-feature-owners` nothing to check, and test-layout would still refuse its missing `bun test` script and `bunfig.toml`.
+A repository with no TypeScript source gives `checks-lint-coverage`, `checks-test-layout`, `checks-size-budget`, `checks-repetition` and `checks-feature-owners` nothing to check, and test-layout would still refuse its missing `bun test` script and `bunfig.toml`.
 It declares the gates `checks-lint` runs as `gates.lint`:
 
 ```json
@@ -100,10 +100,11 @@ Both `checks-lint` and `checks-ci-wiring` exit 2 on a `gates.lint` that names an
 `checks-ci-wiring` exits 1 when the selection leaves out a gate the repository's tracked files make applicable, and names the gate and the files:
 
 ```
-ci-wiring: quality.json gates.lint leaves out 4 gate(s) this repository's contents make applicable:
+ci-wiring: quality.json gates.lint leaves out 5 gate(s) this repository's contents make applicable:
   checks-lint-coverage: the repository tracks TypeScript source (src/widget.ts)
   checks-test-layout: the repository tracks TypeScript source (src/widget.ts)
   checks-size-budget: the repository tracks TypeScript source (src/widget.ts)
+  checks-repetition: the repository tracks TypeScript source (src/widget.ts)
   checks-feature-owners: the repository tracks TypeScript source (src/widget.ts)
 ```
 

package/docs/gates/checks-quality.md

@@ -34,7 +34,7 @@ A rule only this repository needs stays in its own `.oxlintrc.json`, whose overr
 - A fragment is missing, or differs from what `generate` would write from `quality.json` and the installed kit's presets.
 - A fragment is left over once `quality.json` stops declaring `sources.effect`.
 - `.oxlintrc.json` or `tsconfig.json` does not list its fragment in `extends`, so the tool never reads it.
-- A `sources.effect.paths` glob, or a `sources.production` glob while `size` is declared, matches no tracked or untracked file, so it holds nothing.
+- A `sources.effect.paths` or `sources.production` glob matches no tracked or untracked file, so it holds nothing.
 
 Two details of the fragments are easy to get wrong, so the kit's tests pin both: