@erclx/canon 5.50.0 → 5.52.0

package/governance/ledger/tooling/ci-workflow.md

@@ -22,6 +22,12 @@ The field is continuous integration on GitHub Actions, and the authority is GitH
 | Skip a fork's pull request             | [Workflow syntax, permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax): "if the workflow was triggered by a pull request event other than `pull_request_target` from a forked repository, and the Send write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read only" | 2026-10-18 |
 | Never commit back to the trunk         | House choice: a workflow pushing onto the trunk lands a change no pull request carried and no reviewer read                                                                                                                                                                                                                                                                                         | 2026-10-18 |
 
+## Steps
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Long steps call a script, 5 max | House choice, from [issue 2531](https://github.com/erclx/canon/issues/2531): a 33-line publish check copied out of a workflow carried a program no laptop or shellcheck could run. [Workflow syntax, run](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax) documents `run` as a command run in the shell, with no limit on its size. One guard stays inline, since a placeholder or secrets guard of three lines gains nothing from a script | 2026-10-21 |
+
 ## Token scopes
 
 | Bullet                      | Source                                                                                                                                                                                                                                                                                                                                       | Read       |

package/governance/ledger/ui/design-reference.md

@@ -9,13 +9,14 @@ The rule states canon's own design handoff, generalized from Frameboard's projec
 
 ## Where the design lives
 
-| Bullet                         | Source                                                                                                                                                              | Read       |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| Build against the tracked copy | House choice: a canvas changes under the build with no history, so a reviewer cannot tell which version a surface was built against                                 | 2026-10-18 |
-| Load the keeper skill          | House choice: the rule governs an edit and carries no procedure, so a session without the skill copies frames in by hand or skips the index row                     | 2026-10-21 |
-| Land a design first            | House choice: a design landing inside a feature pull request is reviewed as code, and a second feature building against it meanwhile reads a design nobody accepted | 2026-10-18 |
-| No hand edits                  | House choice: a reference edited by hand drifts from its canvas source, and the next sync overwrites the edit or reports it as a change nobody made                 | 2026-10-18 |
-| Index row before the sync      | House choice: the sync writes only the surfaces the index names, so a missing row drops the new surface's reference, and a stale row keeps a removed surface's      | 2026-10-18 |
+| Bullet                         | Source                                                                                                                                                            | Read       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Build against the tracked copy | House choice: a canvas changes under the build with no history, so a reviewer cannot tell which version a surface was built against                               | 2026-10-18 |
+| Load the keeper skill          | House choice: the rule governs an edit and carries no procedure, so a session without the skill copies frames in by hand or skips the index row                   | 2026-10-21 |
+| Land a design with its build   | House choice: a design merged as its own pull request waits on a review that reads a picture with no build beside it, and the pick drifts before anything uses it | 2026-10-21 |
+| No hand edits                  | House choice: a reference edited by hand drifts from its canvas source, and the next sync overwrites the edit or reports it as a change nobody made               | 2026-10-18 |
+| Index row before the sync      | House choice: the sync writes only the surfaces the index names, so a missing row drops the new surface's reference                                               | 2026-10-21 |
+| Reference lifetime             | House choice: a reference kept past its surface misleads the next build, and one redrawn without a design change hides a departure the review should see          | 2026-10-21 |
 
 ## Building against a reference
 
@@ -32,12 +33,6 @@ The rule states canon's own design handoff, generalized from Frameboard's projec
 | Name each departure                | House choice: an unnamed departure reads as an accident, and the next build against the same reference repeats or reverts it | 2026-10-18 |
 | Unexplained departure is a finding | House choice: without the finding, an unexplained departure merges as the new design with no one having chosen it            | 2026-10-18 |
 
-## Naming
-
-| Bullet                  | Source                                                                                                                                 | Read       |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| One folder per app part | House choice: a fixed folder and theme suffix let the sync and a reviewer find a surface's pair of references without reading an index | 2026-10-18 |
-
 ## Declined
 
 The rewrite kept every bullet. Each was already under 200 characters and states a step a reviewer can check against the pull request.

package/governance/rules/tooling/ci-workflow.md

@@ -17,6 +17,10 @@ paths:
 - Skip a pull request from a fork with `github.event.pull_request.head.repo.full_name == github.repository`, since the default token cannot push to a fork's branch.
 - Never commit back to the trunk. A commit with no pull request and no reviewer needs an operator's decision, not a workflow's.
 
+## Steps
+
+- Keep an inline `run:` step to five lines at most with one guard allowed and no other branching, loop, trap, or function, and call a script for anything longer, per the `canon:ci-workflow` skill.
+
 ## Token scopes
 
 - In a workflow with more than one job, add a write scope to the job that needs it, never to the workflow-level block, so every other job keeps the read-only token.

package/governance/rules/ui/design-reference.md

@@ -18,9 +18,10 @@ paths:
 
 - Build UI against `canon/design/`, never against the canvas directly.
 - Load the `canon:design-record` skill before adding, redrawing, or removing a reference under `canon/design/`, and report it rather than proceeding silently when it does not resolve.
-- Land a picked or changed canvas design in `canon/design/` through the project's design sync, as its own pull request, before any feature builds against it.
+- Land a picked or changed design in `canon/design/` through the project's design sync, in the first commit of the branch that builds against it or with its design round, never as its own pull request.
 - Never copy, edit, or delete a reference file under `canon/design/` by hand.
-- Add a new surface's row to the index in `canon/design/` before running the sync, and remove it only in the change that removes the surface.
+- Add a new surface's row to the index in `canon/design/` before running the sync.
+- Keep a reference while its surface exists, redraw it only on an intentional design change, and remove it with its index row in the change that removes the surface.
 
 ## Building against a reference
 
@@ -32,7 +33,3 @@ paths:
 - Put each changed surface's reference image beside its built capture, light and dark, in the pull request description.
 - Name each place the build departs from its reference, with its reason, in the pull request description.
 - Report an unexplained departure from a reference as a review finding.
-
-## Naming
-
-- Give each app part one plain kebab-case folder under `canon/design/`, and name each file `<name>-dark` or `<name>-light`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.50.0",
+  "version": "5.52.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -14,6 +14,7 @@
     "tooling",
     "claude",
     "docs",
+    "CHANGELOG.md",
     "tsconfig.json",
     "assets/brand/mark.svg",
     "!scripts/eval",

package/scripts/ci/check-browsers.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Fails when a Playwright browser named in the arguments is missing from the
+# cache, called after the cache restore in pr-visual-checks.yml. A cache hit
+# skips the install step, so a restore that came back empty would otherwise
+# surface later as a launch error.
+set -e
+
+for browser in "$@"; do
+  if ! compgen -G "$HOME/.cache/ms-playwright/${browser}-*" >/dev/null; then
+    echo "Missing Playwright browser: ${browser}" >&2
+    exit 1
+  fi
+done

package/scripts/ci/delete-previews.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Deletes the Cloudflare Pages preview deployments minted for one branch, called
+# by the cleanup-preview job in deploy-site.yml with the Pages project name and
+# the branch. CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID come from the step
+# env.
+#
+# Deployments are listed through the REST API rather than wrangler, whose
+# listing carries no branch filter. `force=true` is what lets a deployment
+# still holding its branch alias be deleted.
+#
+# tooling/cloudflare/configs/scripts/delete-previews.sh is the seeded copy,
+# which adds a skip for an absent secret. Keep the two otherwise the same.
+set -e
+
+PROJECT_NAME=$1
+BRANCH=$2
+
+api="https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/pages/projects/$PROJECT_NAME/deployments"
+auth="Authorization: Bearer $CLOUDFLARE_API_TOKEN"
+page=1
+ids=""
+while :; do
+  listing=$(curl -fsS -H "$auth" "$api?env=preview&per_page=25&page=$page")
+  [ "$(echo "$listing" | jq '.result | length')" -eq 0 ] && break
+  ids="$ids $(echo "$listing" | jq -r --arg branch "$BRANCH" '.result[] | select(.deployment_trigger.metadata.branch == $branch) | .id')"
+  page=$((page + 1))
+done
+deleted=0
+for id in $ids; do
+  curl -fsS -X DELETE -H "$auth" "$api/$id?force=true" >/dev/null
+  echo "Deleted $id"
+  deleted=$((deleted + 1))
+done
+echo "Deleted $deleted preview deployments for $BRANCH."

package/scripts/ci/publish-check.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Reports whether the newest GitHub release reached npm, called by the
+# publish-check job in release-please.yml. The step passes GH_TOKEN and GH_REPO
+# for gh. A release inside the publish job's 15-minute window passes, since its
+# publish may still be running.
+set -e
+
+package=@erclx/canon
+
+if ! release=$(gh release view --json tagName,publishedAt --jq '"\(.tagName) \(.publishedAt)"') || [ -z "$release" ]; then
+  echo "::error::Could not read the newest GitHub release, so whether it reached npm is unknown."
+  exit 1
+fi
+read -r tag published <<<"$release"
+age=$(($(date +%s) - $(date -d "$published" +%s)))
+if [ "$age" -lt 900 ]; then
+  echo "$tag is ${age}s old, inside the 15-minute window its publish job runs in."
+  exit 0
+fi
+# A missing version is an E404, so read the whole list to tell it from an outage
+if ! versions=$(npm view "$package" versions --json); then
+  echo "::error::Could not read $package from npm, so whether $tag reached it is unknown."
+  exit 1
+fi
+if ! jq -e --arg v "${tag#v}" '[.] | flatten | index($v) != null' <<<"$versions" >/dev/null; then
+  echo "::error::$tag has a GitHub release but npm does not serve it. Publish it with: gh workflow run release-please.yml -f tag=$tag"
+  exit 1
+fi
+echo "$tag is on npm."

package/scripts/ci/refresh-frames-pr.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Commits the regenerated capture frames onto the refresh branch and opens or
+# updates its pull request, called by refresh-capture-frames.yml after the
+# capture steps. The step holds GH_TOKEN and HUSKY, since the token scope is
+# read off the workflow.
+#
+# Hooks stay off, since pre-push runs a check whose format step needs shfmt,
+# which the runner lacks. verify.yml checks the pull request.
+#
+# The frames commit where they rendered, then only the files that commit wrote
+# or dropped carry onto main fetched now, so a merge landing mid-run neither
+# leaves the branch on an older base nor loses a frame it moved. The pull
+# request resolves by number, since every merged refresh leaves a closed one on
+# the same head.
+set -e
+
+branch=chore/refresh-capture-frames
+title="chore(web): refresh capture frames"
+
+if [ -z "$(git status --porcelain assets/captures assets/frames assets/evidence)" ]; then
+  echo "Frames are current, nothing to refresh."
+  exit 0
+fi
+git config user.name "github-actions[bot]"
+git config user.email "41898282+github-actions[bot]@users.noreply.github.com" # canon-allow-reference: the bot account id, not a commit
+git add assets/captures assets/frames assets/evidence
+git commit -m "$title"
+rendered=$(git rev-parse HEAD)
+written=$(git diff --name-only --no-renames --diff-filter=d HEAD~1 HEAD)
+dropped=$(git diff --name-only --no-renames --diff-filter=D HEAD~1 HEAD)
+git fetch --depth=1 origin +refs/heads/main:refs/remotes/origin/main
+git checkout -B "$branch" origin/main
+if [ -n "$written" ]; then
+  printf '%s\n' "$written" | xargs -d '\n' git checkout "$rendered" --
+fi
+if [ -n "$dropped" ]; then
+  printf '%s\n' "$dropped" | xargs -d '\n' git rm -q --ignore-unmatch --
+fi
+if git diff --cached --quiet -- assets/captures assets/frames assets/evidence; then
+  echo "Main already carries these frames, nothing to refresh."
+  exit 0
+fi
+git commit -m "$title"
+git push --force origin "$branch"
+number=$(gh pr list --head "$branch" --state open --json number --jq '.[0].number')
+if [ -z "$number" ]; then
+  gh pr create \
+    --base main \
+    --head "$branch" \
+    --title "$title" \
+    --body "## Summary
+
+- Refreshes the capture frames from main so their counts and tokens stay current.
+
+## Key changes
+
+- Regenerates the count and token bearing frames, their images, and their stamps from main.
+- Recaptures the home page baseline under assets/evidence/home.
+- Merges itself by squash once its required check passes."
+  number=$(gh pr list --head "$branch" --state open --json number --jq '.[0].number')
+fi
+# Every run, so a force-push from a later run leaves it queued either way
+gh pr merge "$number" --auto --squash

package/scripts/ci/report-baseline.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Writes the step summary saying whether the captured landing page frames match
+# the committed baseline, called by the capture job in pr-visual-checks.yml. A
+# moved capture is expected when a catalog the page counts has moved, so it
+# reports and never fails.
+set -e
+
+if git diff --quiet -- assets/evidence/home; then
+  echo "The captured frames match the committed baseline." >>"$GITHUB_STEP_SUMMARY"
+  exit 0
+fi
+{
+  echo "### The landing page capture moved"
+  echo
+  echo "These frames differ from the committed baseline. That is expected"
+  echo "when a catalog this page counts has moved, and it is not a failure."
+  echo
+  echo '```'
+  git diff --stat -- assets/evidence/home
+  echo '```'
+  echo
+  echo "Download the \`landing-page-capture\` artifact to view them."
+} >>"$GITHUB_STEP_SUMMARY"

package/scripts/ci/stack-issues.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Opens, updates, or closes one issue per stack from the outcomes stack-verify.yml
+# recorded under results/<stack>, called by its report job. Takes the stacks as
+# arguments and reads GH_TOKEN, GH_REPO, and RUN_URL from the step env.
+set -euo pipefail
+
+for stack in "$@"; do
+  title="stack-verify: $stack"
+  # A job that died before recording counts as a failure
+  outcome=failure
+  [ -f "results/$stack" ] && outcome=$(cat "results/$stack")
+  number=$(gh issue list --state open --search "\"$title\" in:title" --json number,title \
+    --jq "[.[] | select(.title == \"$title\")][0].number // empty")
+  if [ "$outcome" = success ]; then
+    if [ -n "$number" ]; then
+      gh issue close "$number" --comment "Passing again in $RUN_URL"
+    fi
+  elif [ -n "$number" ]; then
+    gh issue comment "$number" --body "Still failing in $RUN_URL"
+  else
+    gh issue create --title "$title" \
+      --body "\`canon tooling verify $stack\` failed in $RUN_URL. The issue closes itself when a later run passes."
+  fi
+done

package/scripts/ci/verify-npm-token.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Checks that the npm publish credential is set and authenticates, so a release
+# is never cut it cannot publish. release-please.yml passes NPM_TOKEN from the
+# step env, which keeps the secret named in the workflow.
+set -e
+
+if [ -z "$NPM_TOKEN" ]; then
+  echo "::error::NPM_TOKEN is not set. Add the secret before a release can be cut."
+  exit 1
+fi
+if ! curl -sf -H "Authorization: Bearer $NPM_TOKEN" https://registry.npmjs.org/-/whoami >/dev/null; then
+  echo "::error::NPM_TOKEN did not authenticate. It is likely expired or revoked."
+  exit 1
+fi

package/src/claude/cases/setup.ts

@@ -66,6 +66,13 @@ export const SETUP_CASES: readonly SkillCase[] = [
       'Report what this project has fallen behind the toolkit on, domain by domain, and fix nothing.',
     expect: 'target-check',
   },
+  // The applying half of the same moment. It previews what the check would
+  // report and then writes, which is the line between the two.
+  {
+    prompt:
+      'A new toolkit release is out, bring this project up to it and run whatever migrations it needs.',
+    expect: 'target-update',
+  },
   {
     prompt:
       "This project needs its own coding rule that the toolkit doesn't ship.",

package/src/cli/help.ts

@@ -20,6 +20,7 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['sync [path]', 'Sync all installed domains in a project'],
       ['upgrade', 'Reinstall the CLI with the manager that installed it'],
       ['migrate [cmd]', 'Move a project off a retired name or layout'],
+      ['changelog', 'Read the releases between a stamp and this binary'],
       ['targets [cmd]', 'Projects this toolkit installed into'],
     ],
   },

package/src/cli.ts

@@ -40,6 +40,7 @@ import { register as census } from '@/commands/census'
 import { register as upstream } from '@/commands/upstream'
 import { register as targets } from '@/commands/targets'
 import { register as upgrade } from '@/commands/upgrade'
+import { register as changelog } from '@/commands/changelog'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { renderHelp } from '@/cli/help'
 import { renderAll, routeHelp } from '@/cli/help-all'
@@ -100,6 +101,7 @@ upstream(program)
 audits(program)
 gate(program)
 upgrade(program)
+changelog(program)
 
 const route = routeHelp(program, process.argv.slice(2))
 if (route.kind === 'top') showHelp()

package/src/commands/changelog.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { PROJECT_ROOT } from '@/roots/project'
+import { readStamp } from '@/sync/stamp'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/cli/ui'
+import { type ChangelogReport, resolveChangelog } from '@/version/changelog'
+import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
+
+interface ChangelogOptions {
+  readonly since?: string
+  readonly root?: string
+  readonly json?: boolean
+}
+
+const REFUSALS = {
+  'no-stamp':
+    'the target carries no stamped version and --since named none, so there is no start to range from',
+  'no-changelog':
+    'the installed package carries no CHANGELOG.md with release entries to read',
+  'unknown-version':
+    'the changelog lists no such release, so the range would be a guess',
+} as const
+
+const HELP = [
+  '',
+  'Prints the release entries after a version, up to the running one, from the',
+  'CHANGELOG.md the installed package ships. It reads no registry and needs no',
+  '`gh`, so it answers offline.',
+  '',
+  'The start defaults to the oldest `version` across the target stamp domains,',
+  'since the oldest domain is the one furthest behind. --since overrides it.',
+  '',
+  'Exit codes:',
+  '  0  the range was read, empty when the target is already current',
+  '  1  refused, with the reason on stderr',
+  '',
+  'A refusal names a "reason" rather than printing an empty range. no-stamp',
+  'means no start was recorded or given, no-changelog means the file or its',
+  'release headings are missing, and unknown-version means the start or the',
+  'running version is absent from the file, which covers a pre-release and a',
+  'start newer than the binary.',
+  '',
+  'The JSON carries "since", "running", and "entries", each an object with the',
+  'release "version" and its raw "markdown". Read the record rather than the',
+  'exit when a skill consumes this, since a shell function wrapping the binary',
+  'may flatten the status.',
+  '',
+  'Examples:',
+  '  canon changelog',
+  '  canon changelog --since 5.47.0 --json',
+  '  canon changelog --root ../frameboard',
+  '',
+].join('\n')
+
+export function register(program: Command): void {
+  program
+    .command('changelog')
+    .description(
+      'Print the release entries after a version up to the running one',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--since <version>',
+      'Start after this version instead of the stamp',
+    )
+    .option('--root <path>', 'Target whose stamp sets the start', '.')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText('after', HELP)
+    .action((opts: ChangelogOptions) => {
+      process.exitCode = runChangelog(opts)
+    })
+}
+
+function readChangelogText(): string | undefined {
+  const path = join(PROJECT_ROOT, 'CHANGELOG.md')
+
+  return existsSync(path) ? readFileSync(path, 'utf8') : undefined
+}
+
+function stampedVersions(root: string): string[] {
+  const stamp = readStamp(root)
+  if (stamp === undefined) return []
+
+  return Object.values(stamp.domains)
+    .map((domain) => domain?.version)
+    .filter((version): version is string => version !== undefined)
+}
+
+function runChangelog(opts: ChangelogOptions): number {
+  intro('canon changelog')
+
+  const root = resolve(opts.root ?? '.')
+  const report = resolveChangelog({
+    text: readChangelogText(),
+    running: readInstalled().version ?? UNKNOWN_LABEL,
+    since: opts.since,
+    stamped: stampedVersions(root),
+  })
+
+  if (report.kind === 'range') {
+    reportRange(report)
+  } else {
+    reportRefusal(report)
+  }
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(report)}\n`)
+  }
+
+  return report.kind === 'range' ? 0 : 1
+}
+
+function reportRange(
+  report: Extract<ChangelogReport, { kind: 'range' }>,
+): void {
+  logStep('Range')
+  logInfo(`${report.since} to ${report.running}`)
+
+  if (report.entries.length === 0) {
+    logInfo('No release after the start, so nothing is pending')
+    return
+  }
+
+  logStep(plural(report.entries.length, 'release'))
+  for (const entry of report.entries) {
+    pipeOutput(entry.markdown)
+  }
+}
+
+function reportRefusal(
+  report: Extract<ChangelogReport, { kind: 'refused' }>,
+): void {
+  logStep('Refused')
+  const version = report.version === undefined ? '' : ` (${report.version})`
+  logWarn(`${report.reason}${version}: ${REFUSALS[report.reason]}`)
+}

package/src/commands/hooks.ts

@@ -39,14 +39,16 @@ export function register(program: Command): void {
         'Runs these steps in order, each a child call reading its --json record:',
         ...Object.values(STEP_VERBS).map((verb) => `  canon ${verb.join(' ')}`),
         '',
-        'The archive runs once per pull request number the merge brought in.',
-        'Lines go to stderr, and an ordinary merge prints nothing.',
+        'The archive and the member retirement run once per pull request',
+        'number the merge brought in. Lines go to stderr, and an ordinary merge',
+        'prints nothing.',
         '',
-        'The reclaim runs from the working directory with no root, so a pull',
-        'inside a linked worktree never removes the worktree it stands in.',
+        'The member retirement and the reclaim run from the working directory',
+        'with no root, so a pull inside a linked worktree never removes the',
+        'worktree it stands in.',
         '',
         'Environment:',
-        '  CANON_SKIP_RECLAIM=1        skip the worktree reclaim',
+        '  CANON_SKIP_RECLAIM=1        skip the member retirement and the reclaim',
         '  CANON_SKIP_UPGRADE=1        skip the CLI reinstall',
         '  CANON_SKIP_PLUGIN_UPDATE=1  skip the plugin update',
         '',

package/src/commands/labels.ts

@@ -249,8 +249,8 @@ export function register(program: Command): void {
         '## Summary or ## Key changes, fails. A review, a release-please body,',
         'and a scan carrying no title skip this check.',
         '',
-        'It reports the density of that same body per section under `density`,',
-        'without failing on it: a bullet past 200 characters, more than 5 plain',
+        'It fails the density of that same body, reported per section under',
+        '`density`: a bullet past 200 characters, more than 5 plain',
         'bullets or 2 paragraphs in a row, a paragraph past 350 characters, any',
         'H3 or deeper heading, and Technical context mixing bullets with',
         'paragraphs. A bold label alone on a line splits a Key changes run, a',
@@ -279,11 +279,12 @@ export function register(program: Command): void {
         'not read, as GitHub does not read it.',
         '',
         'Exit codes:',
-        '  0  none of the eight found',
+        '  0  none of the nine found',
         '  1  refused, with the reason on stderr or in the JSON record',
         '  2  the title or body carries a phase label, a board identifier, a',
         '     session link, a banned character, a heading outside the closed',
-        '     list or a required one missing, a missing or stray closing line',
+        '     list or a required one missing, a density finding in the body, a',
+        '     missing or stray closing line',
         '     under --closes, or a title',
         "     breaking claude/skills/git-pr/references/pr.md's format, casing, or length",
         '',
@@ -718,9 +719,9 @@ async function runScan(opts: ScanOptions): Promise<number> {
     }
   }
 
-  // Reported and never gated yet. New bodies come back clean under the
-  // shape in pr.md first, so an older open pull request fails no edit event.
-  // A post is never gated, since CI reads one only after it is published.
+  // A body's density fails the scan. A post's never does, since the review
+  // post hook denies on exit 2 and scans with no title, so a post-density
+  // fail would block every dense review or reply post.
   const post = !sectionsChecked && isPost(resolved.body)
   const density = sectionsChecked
     ? bodyDensity(resolved.body)
@@ -859,6 +860,7 @@ async function runScan(opts: ScanOptions): Promise<number> {
     titleFormatIssues.length === 0 &&
     sections.outside.length === 0 &&
     sections.missing.length === 0 &&
+    !(sectionsChecked && density.length > 0) &&
     banFindings.length === 0 &&
     closing.missing.length === 0 &&
     closing.stray.length === 0