@avi2dg/checks 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 Every release of `@avi2dg/checks`, newest first, written by the release from its conventional commits.
 
+## 0.33.0
+
+Released 2026-10-03.
+
+### Features
+
+- **docs:** report sentences over trial length caps as advisory [#120](https://github.com/avi2d/checks/pull/120)
+
+### Fixes
+
+- move effect to stable 4.0.0 [#122](https://github.com/avi2d/checks/pull/122)
+- **complexity:** accept signed numbers and earlier props names in thin-astro defaults [#115](https://github.com/avi2d/checks/pull/115)
+- **docs:** judge agent file entries and headings from a CommonMark parse [#116](https://github.com/avi2d/checks/pull/116)
+- **docs:** fail link anchors the checks-docs reference rule could not check [#114](https://github.com/avi2d/checks/pull/114)
+
+## 0.32.0
+
+Released 2026-09-29.
+
+### Features
+
+- **delivery:** add checks-secrets gate that fails a range whose commits add a secret [#112](https://github.com/avi2d/checks/pull/112)
+- **delivery:** open a release pull request daily and tag it when it merges [#111](https://github.com/avi2d/checks/pull/111)
+
 ## 0.31.0
 
 Released 2026-09-28.

package/README.md

@@ -9,12 +9,12 @@ Each repository owns its workflows and native tool configs, as [Native settings]
 <!-- generated prerequisites: bun run build writes it from package.json, .bun-version and scripts/doc-blocks.ts -->
 
 - A git repository, whose history the range gates read.
-- Bun 1.3.13, which runs every bin.
+- Bun 1.4.2, which runs every bin.
 - The peer dependencies, at the exact versions the kit pins:
   - `@effect/tsgo` 0.45.0
   - `@swc/core` 1.16.2
   - `dependency-cruiser` 18.4.0
-  - `effect` 4.0.0-rc.115
+  - `effect` 4.0.0
   - `jscpd` 5.3.2
   - `oxlint` 1.83.0
   - `oxlint-tsgolint` 7.0.2002
@@ -31,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 jscpd@5.3.2 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 jscpd@5.3.2 oxlint@1.83.0 oxlint-tsgolint@7.0.2002 typescript@7.0.2
    ```
 
    <!-- end generated install -->
@@ -127,6 +127,7 @@ The table groups the gates by vector, the part of a repository each one judges.
 | 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 |
+| delivery | [`checks-secrets`](docs/gates/checks-secrets.md) | the range | every repository |
 | dependencies | [`checks-advisories`](docs/gates/checks-advisories.md) | the range | a repository tracking `bun.lock` |
 
 <!-- end generated gates -->
@@ -141,6 +142,8 @@ These bins run on their own:
 - [`checks-changelog`](docs/gates/checks-changelog.md) writes the pending release into `CHANGELOG.md` from the conventional commits since the last release.
 - [`checks-release-notes`](docs/gates/checks-release-notes.md) writes one `CHANGELOG.md` section to a file for a GitHub release.
 - [`checks-release-report`](docs/gates/checks-release-report.md) tells whether the history holds unreleased features or fixes since the last tag.
+- [`checks-release-pr`](docs/gates/checks-release-pr.md) opens or refreshes the pull request that releases the next version, and dispatches its checks.
+- [`checks-release-tag`](docs/gates/checks-release-tag.md) tags a landed release commit with its version and dispatches the release workflow on the tag.
 - [`checks-vendor`](docs/gates/checks-vendor.md) pins each library its `prepare` arguments name to a shared read-only clone and links it under `repos/`.
 
 `checks-lint` has [its own page](docs/gates/checks-lint.md), which says which range it resolves.

package/dist/readability/index.js

@@ -400,11 +400,11 @@ var rule = {
   create(context) {
     const max = maxOf(context.options);
     const check = (node) => {
-      const score2 = node.type === "StaticBlock" ? cognitiveComplexity(node, NO_NAMES) : cognitiveComplexity(node, selfNames(node));
-      if (score2 <= max)
+      const score = node.type === "StaticBlock" ? cognitiveComplexity(node, NO_NAMES) : cognitiveComplexity(node, selfNames(node));
+      if (score <= max)
         return;
       const name = node.type === "StaticBlock" ? "static block" : `function \`${displayName(node)}\``;
-      context.report({ node, message: `${name} has a cognitive complexity of ${score2}. Maximum allowed is ${max}.` });
+      context.report({ node, message: `${name} has a cognitive complexity of ${score}. Maximum allowed is ${max}.` });
     };
     return {
       FunctionDeclaration: check,
@@ -430,6 +430,9 @@ function isAstroProps(value) {
   const { object, property } = value;
   return object.type === "Identifier" && object.name === "Astro" && property.type === "Identifier" && property.name === "props";
 }
+function isSignedNumber(value) {
+  return value.type === "UnaryExpression" && (value.operator === "-" || value.operator === "+") && value.argument.type === "Literal" && typeof value.argument.value === "number";
+}
 function isPlainValue(value, bound) {
   return value.type === "Literal" || value.type === "Identifier" && bound.has(value.name);
 }
@@ -442,17 +445,23 @@ function readsProps(expression, bound) {
   return isAstroProps(value) || readsProps(value.object, bound);
 }
 function isPlainPattern(pattern, bound) {
+  return isPlainInOrder(pattern, bound, new Set(bound));
+}
+function isPlainInOrder(pattern, bound, seen) {
   if (pattern === null)
     return true;
   if (pattern.type === "RestElement")
-    return isPlainPattern(pattern.argument, bound);
-  if (pattern.type === "AssignmentPattern")
-    return isPlainValue(pattern.right, bound) && isPlainPattern(pattern.left, bound);
+    return isPlainInOrder(pattern.argument, bound, seen);
+  if (pattern.type === "AssignmentPattern") {
+    return (isPlainValue(pattern.right, seen) || isSignedNumber(pattern.right)) && isPlainInOrder(pattern.left, bound, seen);
+  }
   if (pattern.type === "ArrayPattern")
-    return pattern.elements.every((element) => isPlainPattern(element, bound));
-  if (pattern.type === "Identifier")
+    return pattern.elements.every((element) => isPlainInOrder(element, bound, seen));
+  if (pattern.type === "Identifier") {
+    seen.add(pattern.name);
     return true;
-  return pattern.properties.every((property) => property.type === "RestElement" ? isPlainPattern(property.argument, bound) : (!property.computed || isPlainValue(property.key, bound)) && isPlainPattern(property.value, bound));
+  }
+  return pattern.properties.every((property) => property.type === "RestElement" ? isPlainInOrder(property.argument, bound, seen) : (!property.computed || isPlainValue(property.key, bound)) && isPlainInOrder(property.value, bound, seen));
 }
 function isPropsRead(declarator, bound) {
   return declarator.init !== null && readsProps(declarator.init, bound) && isPlainPattern(declarator.id, bound);

package/docs/configs/commit-messages.md

@@ -23,6 +23,11 @@ It lints the pull request title and nothing else.
 The title is the enforced subject because a squash merge uses it as the main commit subject, and per-commit messages are not linted.
 GitHub appends ` (#N)` to the squashed subject, so the workflow lints the title with that suffix attached, and the header length limit applies to the landed subject, not the bare title.
 The workflow moves git's comment character off `#`, so a title starting with `#` is linted like any other.
+The workflow also triggers on `workflow_dispatch`, since GitHub holds the `pull_request` runs of a release pull request the workflow token opens until a maintainer approves them, as [checks-release-pr](../gates/checks-release-pr.md) says.
+A dispatched run carries no pull request, so the workflow reads the title of the one open pull request its branch heads, and fails when there is none.
+That lookup needs the workflow's `pull-requests: read` permission.
+It reports a dispatched run's result on the head commit as a `commitlint` status, since GitHub keeps a dispatched run's check off the pull request.
+The kit's own `.github/workflows/commitlint.yml` shows the step.
 
 It never sees a commit's author or committer fields, nor the `Co-authored-by` trailer GitHub writes from a foreign author when it squashes, so it cannot enforce who a commit belongs to.
 [checks-commit-identity](../gates/checks-commit-identity.md) is that enforcement.

package/docs/configs/typescript-rules.md

@@ -48,7 +48,7 @@ The base loads the kit's `data-shape` plugin from `dist/` with one rule for ever
 An override in `oxlintrc.json` turns on one rule of the kit's `readability` plugin in each `.astro` file:
 
 - `readability/thin-astro` refuses a statement in the frontmatter or a script block that is neither an import, a re-export from another module, a type or interface declaration, nor a variable read from `Astro.props`.
-- A default inside an `Astro.props` destructuring passes only when it is a literal or a name read from `Astro.props` earlier, so `const { title = "Home" } = Astro.props;` passes and a call or `await` in a default is refused.
+- A default inside an `Astro.props` destructuring passes only when it is a literal, a `-` or `+` on a numeric literal, or a name read from `Astro.props` earlier, in the same pattern or a statement before it, so `const { title = "Home", heading = title } = Astro.props;` passes and a call or `await` in a default is refused.
 - Move a refused statement into a `.ts` file and import it, so the `.astro` file holds only imports, props and markup.
 - A script block loads client code with a side-effect import, as in `<script>import "../client.ts";</script>`, and the override turns off `import/no-unassigned-import` so that import passes.
 - A dynamic route re-exports `getStaticPaths` from a `.ts` file, as in `export { getStaticPaths } from "../lib/paths.ts";`.

package/docs/design.md

@@ -67,7 +67,7 @@ So the fragment lists the rules in `files`, and in `include` beside every file u
 
 The source sits under `src/<vector>/`, one directory for each thing the kit judges a repository on: complexity, quality, testing, docs, delivery and dependencies.
 `src/core/` holds what every vector runs on.
-`scripts/` holds only the kit's own build, and nothing in it ships.
+`scripts/` holds only the kit's own build and CI tooling, and nothing in it ships.
 Sorting files by what loads them would put both oxlint plugins at the root and every bin in one flat directory.
 Nothing would then say which gate a helper serves.
 A mutation runner's default scope covers `src/`, so the kit's own Stryker run mutates its source with no `mutate` list.
@@ -100,7 +100,7 @@ The `.ts` bins keep a `bun` shebang and need no build step, unlike the oxlint pl
 The bins are written in Effect.
 So `effect` is a peer dependency, and `@effect/platform-bun`, which only the bins use, is a dependency.
 `@effect/platform-node-shared` is a direct dependency only to pin its version.
-`@effect/platform-bun` asks for it with a `^` range, and a newer release candidate of it peers on a newer `effect` than consumers install.
+`@effect/platform-bun` asks for it with a `^` range, so a newer minor of it could resolve and peer on a newer `effect` than the exact version consumers install.
 So the three packages move together at one exact version.
 
 ## checks-lint runs each gate as its own bin
@@ -162,8 +162,24 @@ So a checkout without tags, a fork, and a branch that merged `main` in all write
 A section keeps the date it was written, because the squash merge that lands the release commit may fall on another day.
 Entries come from commit subjects, which are the squash-merged pull request titles that commitlint holds to the conventional format.
 A commit body holds the branch's own messages, and nothing lints it, so no entry comes from a body.
-The changelog arrives in the release pull request, and no workflow pushes to the repository.
-The only write access the release path holds is the `github-release` job's `contents: write`, which creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
+The changelog arrives in the release pull request, and no workflow pushes to a branch a person works on.
+
+## A release is cut every day
+
+A release waits for no quiet moment, since a busy repository always has work under way.
+The daily release opens the release pull request from `main` whenever it holds a feature or a fix since the last tag, and the pull request merges through the repository's usual merge path once its checks pass.
+`checks-release-pr` writes only to the `release/<branch>` branch it owns, and rebuilds that branch on `main` rather than merging `main` into it, so the changelog it carries is the one the build writes.
+`checks-release-tag` writes only the `v*` tag of a release commit that already landed.
+The `github-release` job's `contents: write` creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
+
+Both jobs act with the workflow token.
+GitHub starts no run for a push that token makes, and holds the runs of a pull request it opens until a maintainer approves them.
+A GitHub App or a personal token would start them, but either is a credential each repository stores and someone rotates.
+So `checks-release-pr` dispatches the required checks on the release head, and `checks-release-tag` dispatches the release workflow on the tag, since a dispatch is the one run the token can start.
+GitHub keeps a dispatched run's checks off the pull request, and branch protection does not count them.
+So each dispatched job reports its result as a commit status named for the job, which a required check of that name counts.
+Where a status and a check share a name, branch protection requires both, so the status never passes a pull request whose own check failed.
+The cost is a `workflow_dispatch` trigger and a status step on each workflow a release needs, a title lint that reads its title from the open pull request, and the repository setting that lets the token open a pull request.
 
 ## The docs gate judges what a change touches
 
@@ -195,6 +211,10 @@ A score cannot fail a change without failing correct prose, and a suggestion tha
 `src/docs/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 another package could not refuse at write time.
 
+The entry rule and the rule against a `## Maintaining this file` section take their list items and headings from `commonmark`, the CommonMark reference parser.
+A reader sees the blocks a renderer builds, and a line rule that guesses at blockquotes, HTML blocks and indented code misjudges each corner its guess misses.
+Only the gate runs these rules, so the parser costs no hook anything, and the line scan reads each entry's code spans and links from that entry's line alone.
+
 A path, link or command on a line the range leaves alone still fails when the range broke it, for example by deleting the file it names.
 A reference goes stale far more often because the code it names moves than because its own line is edited.
 So a gate on edited lines alone would miss the usual break.
@@ -238,6 +258,24 @@ The kit caps each entry at 30 days and measures a range from the head's dates, a
 `--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.
 
+## Secrets fail in every commit of the range
+
+`checks-secrets` scans each commit in the range rather than the files at the head.
+A secret a commit adds stays in that commit after a later commit deletes it, and a pushed branch has already sent it to the forge.
+So the fix is to rewrite the commit that added it, and to rotate the secret once it has left the machine.
+
+In a merge commit the gate scans only the merge's own resolution, the difference from the merge git would make on its own.
+A diff against the first parent would also scan what the merge brings in from the other parent, so a branch that merges main would fail on a secret main already holds, from before the range.
+Git gives no such diff for an octopus merge and warns instead of failing, so the gate refuses to scan one rather than pass a commit it never read.
+
+The gate runs gitleaks rather than a hand-written pattern list, because its default config already holds over 200 rules for the token shapes of common services.
+The kit's own rules in `src/delivery/gitleaks.toml` add only the VPN keys and proxy links those rules miss.
+The kit pins gitleaks by version and SHA-256 for the reason it pins OSV-Scanner.
+
+No finding can be accepted.
+A secret has no false positive worth keeping in git, because a placeholder carries the same shape without the value.
+So the gate ignores a repository's `.gitleaks.toml`, `.gitleaksignore` and `gitleaks:allow` comments, which would each let one repository pass what another fails.
+
 ## Related topics
 
 - [checks](../README.md)

package/docs/gates/checks-commit-identity.md

@@ -11,6 +11,9 @@ audience: consumers
 The author and committer of each commit must be allowed.
 A commit whose trailer block carries a `Co-authored-by` trailer, as git parses it, is refused.
 `GitHub <noreply@github.com>` is allowed as committer only.
+`github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>` is allowed as author only of a commit whose subject is `chore: release <version>`, with or without the pull request number a squash merge adds.
+GitHub attributes the release commit [checks-release-pr](checks-release-pr.md) makes to that bot, since it commits through the workflow token.
+Such a commit may carry a `Co-authored-by` trailer naming that bot, since GitHub adds one to some squash merges of a pull request the bot opened, and every other trailer is refused.
 
 ## What it reads
 

package/docs/gates/checks-docs.md

@@ -110,6 +110,8 @@ 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 and is not a sentence of its own.
 No rule reads fenced code, inline code, link destinations, URLs, HTML comments or front matter.
 Readability scores and word choice, such as easy, are not checked.
+A sentence over the trial length cap is listed as advisory and never fails the run.
+The cap is 20 words in an ordered list item and 25 words elsewhere.
 
 `src/docs/prose-matchers.ts` holds the rules and a synchronous `proseRefused()`, and imports nothing.
 The package exports it as `@avi2dg/checks/scripts/prose-matchers.ts`.
@@ -121,7 +123,8 @@ Each reference a living doc or an agent file names has to resolve at the head co
 
 - A path in inline code that ends in a file extension, such as `src/core/lint.ts`, names a file from the root or from the doc's directory.
 - A relative Markdown link names a file or a directory.
-  Its anchor names a heading in that file, as GitHub derives the anchor, or an explicit `id`.
+  Its anchor names a heading in that Markdown or MDX file, as GitHub derives the anchor, or an explicit `id`.
+  An anchor into a directory or any other file fails, because it names no heading the gate can check.
 - 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 code span fails when some tracked file outside the docs held that exact text at the base, and none holds it at the head.
   A span the path check already fails on is not reported again.
@@ -150,7 +153,8 @@ audience: consumers
 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.
+A file that holds a `## Maintaining this file` section a reader sees fails, because this gate holds the shape the section asked for.
+A heading inside an HTML comment, an HTML block or a code block is not such a section.
 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`.
@@ -159,7 +163,7 @@ Each entry names at least one of these, or it fails:
 - 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.
+An entry is any list item a reader sees as CommonMark renders the file, 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.
 
@@ -205,6 +209,8 @@ docs: 6 violation(s):
   docs/parts.md:9: names `gates.lint`, which the range removed from every file outside the docs. Say what holds now, or drop the line
 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 sentence(s) over the trial length caps:
+  README.md:16: carries a 27-word descriptive sentence, over the 25-word cap (procedural means an ordered list item, capped at 20 words)
 docs: advisory, 1 path(s), link(s) or command(s) the living docs or agent files 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
 ```

package/docs/gates/checks-lint.md

@@ -46,7 +46,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 12 gate(s) failed: checks-comment-gate
+checks-lint: 1 of 13 gate(s) failed: checks-comment-gate
 ```
 
 <!-- end generated lint-sample -->

package/docs/gates/checks-mutation.md

@@ -59,8 +59,9 @@ An `--incremental` run with no report stops before instrumenting with the missin
 ## When it runs
 
 A repository runs full baselines from the mutation workflow on `workflow_dispatch`.
+A repository that picks a pull request scope from a baseline also runs that workflow on a nightly schedule.
 Run scoped checks locally during development.
-A scheduled run never starts one, because a baseline costs a full Stryker run.
+A scheduled run costs a full Stryker run.
 
 ## Running it in CI
 

package/docs/gates/checks-release-notes.md

@@ -55,6 +55,7 @@ name: release
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch:
 permissions:
   contents: read
   id-token: write
@@ -65,6 +66,8 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
+      - name: ref is a tag
+        run: test "$GITHUB_REF_TYPE" = tag
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
       - run: bun run build
@@ -102,6 +105,7 @@ name: release
 on:
   push:
     tags: ["v*"]
+  workflow_dispatch:
 permissions:
   contents: read
 jobs:
@@ -113,6 +117,8 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
+      - name: ref is a tag
+        run: test "$GITHUB_REF_TYPE" = tag
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
       - run: bun run build
@@ -127,7 +133,10 @@ jobs:
         run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/release-notes.md"
 ```
 
-Cut a release by merging a pull request that holds only the version bump and the built changelog, then tagging the merge commit on the target branch and pushing the tag.
+A release is a pull request that holds only the version bump and the built changelog, which [checks-release-pr](checks-release-pr.md) opens once a day.
+When it lands, [checks-release-tag](checks-release-tag.md) tags the merge commit and dispatches this workflow on the tag.
+A tag the workflow token pushes starts no `push` run, so the workflow triggers on `workflow_dispatch` as well, and refuses a dispatch on a ref that is not a tag.
+A tag a person pushes starts the same workflow through its `push` trigger.
 The workflow refuses a tag that disagrees with `package.json`, so the tag always names the section the notes come from.
 
 ## When it runs

package/docs/gates/checks-release-pr.md

@@ -0,0 +1,185 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-pr
+
+`checks-release-pr` opens or refreshes the one pull request that releases the next version, and dispatches its checks on its head.
+
+## What it checks
+
+It lists the unreleased changes the way [checks-release-report](checks-release-report.md) does, and does nothing when there are none.
+It bumps the version `package.json` holds by the kit's rule:
+
+| Unreleased changes | Below 1.0.0 | From 1.0.0 |
+| --- | --- | --- |
+| a breaking change | minor | major |
+| a feature and no breaking change | minor | minor |
+| only fixes, performance changes or reverts | patch | patch |
+
+It refuses when the last release tag names a version other than the one `package.json` holds, since an untagged bump means a release landed that nothing published.
+The refusal points at the `tag` job of `daily-release` on the release commit, whose own refusal says what to fix, rather than at a tag pushed by hand.
+It refuses a version that is not a plain `major.minor.patch`.
+It writes the next version into `package.json`, runs `bun run build` so the build writes `CHANGELOG.md`, and commits every tracked file the build changed as `chore: release <version>`.
+The commit's one parent is `HEAD`.
+It makes the commit through the GitHub API, which attributes it to `github-actions[bot]` and signs it, so the job sets no git identity.
+It checks that the tree GitHub built matches the tree the build wrote.
+It points the branch `release/<branch>` at the commit, where `<branch>` is the branch `HEAD` is on.
+It opens a pull request from that branch into `<branch>` titled `chore: release <version>`, with the body `Release <version>.`, or retitles the open one to the new version.
+It then dispatches each workflow its arguments name on the release branch.
+GitHub holds the `pull_request` runs of a pull request the workflow token opens until a maintainer approves them, so the dispatch is what runs the required checks on the release head.
+GitHub keeps a dispatched run's checks off the pull request, so each dispatched job reports its result as a commit status named for the job, which the required check of that name counts.
+When the release branch already holds this version on top of `HEAD` and its pull request carries the right title, it pushes nothing and dispatches nothing.
+It leaves the working tree as it found it.
+
+## What it reads
+
+It reads the `v*` tags, the commit subjects since the last one and `package.json` from the checkout.
+It refuses a shallow checkout, a detached `HEAD` and a working tree with changes to tracked files.
+It reads the release branch from `origin` with `git ls-remote` and `git fetch`.
+It calls the GitHub API through `gh api`, which takes the repository from the checkout's remote and the token from `GH_TOKEN`.
+The token needs `contents: write`, `pull-requests: write` and `actions: write`.
+The repository needs **Allow GitHub Actions to create and approve pull requests** turned on under its Actions settings, or GitHub refuses the pull request.
+
+## Arguments
+
+```sh
+checks-release-pr <workflow>...
+```
+
+Each argument names a workflow file under `.github/workflows/` whose jobs report the checks the default branch requires, such as `ci.yml` and `commitlint.yml`.
+Each named workflow triggers on `workflow_dispatch`.
+Name no workflow that runs something else on dispatch, such as a mutation baseline.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | nothing is unreleased, or the release pull request is open on the current `HEAD` and its checks are dispatched |
+| 2 | the arguments do not parse, a refusal above applies, the build fails, or a GitHub API call fails |
+
+## Sample output
+
+A run that opens the pull request prints the build's own output, then one line:
+
+```
+release-pr: opened https://github.com/acme/widget/pull/12 to release 0.4.0, and dispatched ci.yml, commitlint.yml on release/main
+```
+
+A run on the same `HEAD` the next day prints one line:
+
+```
+release-pr: https://github.com/acme/widget/pull/12 releases 0.4.0 from 3f2a9c81d0b4 and is current
+```
+
+## When it runs
+
+The daily release workflow below runs it once a day on the default branch.
+Run the workflow by hand with `gh workflow run daily-release` to refresh the release pull request sooner.
+
+## Running it in CI
+
+A repository takes the daily release as `.github/workflows/daily-release.yml`.
+The `pull-request` job runs on the schedule, and the `tag` job runs when a release commit lands on `main`, as [checks-release-tag](checks-release-tag.md) says:
+
+```yaml
+name: daily-release
+on:
+  schedule:
+    - cron: "29 3 * * *"
+  workflow_dispatch:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  pull-request:
+    if: github.event_name != 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    concurrency:
+      group: release-pull-request
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - name: open or refresh the release pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./node_modules/.bin/checks-release-pr ci.yml commitlint.yml
+  tag:
+    if: "github.event_name == 'push' && startsWith(github.event.head_commit.message, 'chore: release ')"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - name: tag the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./node_modules/.bin/checks-release-tag release.yml
+```
+
+A public repository keeps `runs-on: ubuntu-latest`.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || fromJSON('["self-hosted","Linux","X64","winbox"]') }}` on both jobs, as its other workflows do.
+A repository whose build needs more than Bun adds the steps its `.github/workflows/ci.yml` runs before `bun run build` to both jobs, and nothing after it.
+Neither job runs a test suite or a mutation run.
+On a hosted runner the `pull-request` job takes about 25 seconds, which GitHub bills as one minute, whether it opens, refreshes or leaves the pull request alone.
+A private repository runs it on its self-hosted runner, which bills no minutes.
+The `tag` job runs only when a release lands, and a job its `if` skips bills nothing.
+The checks it dispatches are the release pull request's own required checks, and they run again only when `main` moves under it.
+The pull request also lists its own `pull_request` runs as waiting for approval.
+Nothing requires them, and approving them runs the same checks again.
+
+The daily release needs the repository's other workflows to accept the dispatch:
+
+- `.github/workflows/ci.yml` and `.github/workflows/commitlint.yml` trigger on `workflow_dispatch`, grant `statuses: write`, and end each required job with the step below.
+  `commitlint.yml` also grants `pull-requests: read`, which the title lookup needs.
+- The title lint reads the title of the one open pull request its branch heads when the event carries none, as [Commit messages](../configs/commit-messages.md) says.
+- `.github/workflows/release.yml` triggers on `workflow_dispatch` and refuses a ref that is not a tag, as [checks-release-notes](checks-release-notes.md) shows.
+- **Allow GitHub Actions to create and approve pull requests** is on, which the call after the step sets.
+- A release pull request holds current `main` when it merges.
+  One that merges behind `main` lands a changelog short of the commits `main` gained, and `checks-release-tag` refuses to tag it.
+
+The step reports a dispatched run's result as a commit status on the head commit:
+
+```yaml
+      - name: report the result on the head commit
+        if: always() && github.event_name == 'workflow_dispatch'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          STATE: ${{ job.status == 'success' && 'success' || 'failure' }}
+        run: gh api "repos/$GITHUB_REPOSITORY/statuses/$GITHUB_SHA" -f state="$STATE" -f context="$GITHUB_JOB" -f target_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --silent
+```
+
+The status takes the job's id as its name, so a required job's id is the check name the branch requires.
+Where a status and a check share a name, branch protection requires both, so the status never passes a pull request whose own check failed.
+The call turns the repository setting on:
+
+```sh
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow -F can_approve_pull_request_reviews=true
+```
+
+## Related topics
+
+- [checks-release-report](checks-release-report.md)
+- [checks-release-tag](checks-release-tag.md)
+- [checks-changelog](checks-changelog.md)
+- [checks-release-notes](checks-release-notes.md)

package/docs/gates/checks-release-report.md

@@ -27,7 +27,7 @@ checks-release-report
 ```
 
 It takes no arguments.
-Run it before cutting a tag to decide whether a release is due.
+Run it to see whether a release is due and what it holds.
 
 ## Exit codes
 
@@ -55,10 +55,12 @@ release-report: no unreleased changes since v0.1.0
 
 ## When it runs
 
-Only a person or a scheduler deciding when to cut a release runs it.
+A person runs it to see what the next release holds.
+[checks-release-pr](checks-release-pr.md) reads the same changes before it opens the release pull request.
 A repository with no versioned releases does not need it.
 
 ## Related topics
 
 - [checks-changelog](checks-changelog.md)
 - [checks-release-notes](checks-release-notes.md)
+- [checks-release-pr](checks-release-pr.md)

package/docs/gates/checks-release-tag.md

@@ -0,0 +1,63 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-tag
+
+`checks-release-tag` tags a landed release commit with its version and dispatches the release workflow on the tag.
+
+## What it checks
+
+It reads the subject of `HEAD`, and does nothing unless the subject is `chore: release <version>`, with or without the ` (#N)` a squash merge adds.
+It refuses a release commit whose `package.json` holds another version.
+It tags `HEAD` as `v<version>` and pushes the tag to `origin`.
+A tag the workflow token pushes starts no `push` workflow, so it then dispatches the workflow its argument names on the tag.
+It does nothing when `v<version>` already tags `HEAD`, so a rerun after a release never publishes it twice.
+When the dispatch fails after the push, it names `gh workflow run <workflow> --ref v<version>`.
+A rerun then finds the tag and does nothing, so that command is what dispatches the release workflow by hand.
+It refuses when `v<version>` already tags another commit.
+Before it pushes the tag, it runs `bun run build` and refuses when the build rewrites a committed file.
+That happens when a release pull request merged behind `main`, so its `CHANGELOG.md` lacks the commits `main` gained.
+The refusal says to open a `chore: cancel the unpublished <version>` pull request that returns `package.json` to the last tag's version and commits what `bun run build` then writes to `CHANGELOG.md`.
+The build reads the returned version as a revert, so it drops the unpublished section, and the next `daily-release` run cuts the release again with every change since the last tag.
+
+## What it reads
+
+It reads the subject of `HEAD` and `package.json` from the checkout, and the tag from `origin` with `git ls-remote`.
+The build it runs reads the whole history, so the checkout fetches all of it.
+It pushes the tag with the credentials the checkout holds.
+It calls the GitHub API through `gh api`, which takes the repository from the checkout's remote and the token from `GH_TOKEN`.
+The token needs `contents: write` and `actions: write`.
+
+## Arguments
+
+```sh
+checks-release-tag <workflow>
+```
+
+The argument names the release workflow file under `.github/workflows/`, such as `release.yml`.
+That workflow triggers on `workflow_dispatch` and keeps its own guards, as [checks-release-notes](checks-release-notes.md) shows.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | `HEAD` is no release commit, its tag already tags it, or the tag is pushed and the release workflow dispatched |
+| 2 | the arguments do not parse, `package.json` disagrees with the subject, the tag tags another commit, the build fails or rewrites a committed file, or the push or a GitHub API call fails |
+
+## Sample output
+
+A run that tags the release prints the build's own output, then one line:
+
+```
+release-tag: tagged 3f2a9c81d0b4 as v0.4.0, and dispatched release.yml on it
+```
+
+## When it runs
+
+The `tag` job of the daily release workflow runs it on each push to `main` whose head commit reads as a release, as [checks-release-pr](checks-release-pr.md#running-it-in-ci) shows.
+
+## Related topics
+
+- [checks-release-pr](checks-release-pr.md)
+- [checks-release-notes](checks-release-notes.md)