@erclx/canon 5.49.0 → 5.51.0

package/tooling/base/configs/.husky/post-merge

@@ -1,16 +1,17 @@
 #!/usr/bin/env sh
 
 # Runs the post-merge steps through `canon hooks post-merge`: archive the task a
-# merged pull request closed, push the records, reclaim merged worktrees,
-# reinstall the CLI, and update the plugin cache. The verb owns the order and
-# each line it prints.
+# merged pull request closed, push the records, retire the fan-in members a
+# merged integrator named, reclaim merged worktrees, reinstall the CLI, and
+# update the plugin cache. The verb owns the order and each line it prints.
 #
-# CANON_SKIP_RECLAIM=1 turns off the worktree reclaim.
+# CANON_SKIP_RECLAIM=1 turns off the member retirement and the worktree
+# reclaim, since both remove worktrees.
 # CANON_SKIP_UPGRADE=1 turns off the CLI reinstall.
 # CANON_SKIP_PLUGIN_UPDATE=1 turns off the plugin cache update.
 #
-# The reclaim reads merge state through `gh`, so a machine without it on PATH
-# reclaims nothing and says nothing. Install `gh` to turn it on.
+# Both read merge state through `gh`, so a machine without it on PATH retires
+# and reclaims nothing and says nothing. Install `gh` to turn them on.
 #
 # Husky runs this as `sh -e`, and `post-rewrite` sources it on a rebase, so
 # every test sits inside an `if` or an `||` and nothing here exits non-zero.

package/tooling/claude/reference.md

@@ -57,6 +57,7 @@ A project installed before the board became a folder still holds `.claude/TASKS.
 
 - Fill in the seed's placeholder project name, description, and key paths after init
 - Keep its sections `Context`, `Commands`, and `Key paths`, since skills detect, extend, or skip by heading
+- Group `Key paths` under H3s, each opening on a lead sentence, before it runs past 5 bullets. `canon markdown audit` and `canon claude sync` both report a longer run.
 - Keep the `Context` section to one line pointing at the state docs, since `plan-feature` does the parallel read when invoked
 
 ## Seed docs

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -81,6 +81,11 @@ colons=$(printf '%s' "$record" |
 density=$(printf '%s' "$record" |
   jq -r '.entries[]?.density[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "opens with neither a paragraph nor a table" else "\(.value) past \(.limit)" end) + (if .gating then "  gating" else "" end)' 2>/dev/null)
 
+# Table findings report and never gate, so each kind is handed back with the
+# fix its shape takes rather than the seam a density finding splits at.
+tables=$(printf '%s' "$record" |
+  jq -r '.entries[]?.tables[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "a list follows the table with no lead sentence" else "\(.value) past \(.limit)" end)' 2>/dev/null)
+
 # A page marked `kind: reference` carries reference shape findings, handed back
 # whole the same way, since a gated one fails the push like a density finding.
 shape=$(printf '%s' "$record" |
@@ -92,7 +97,7 @@ shape=$(printf '%s' "$record" |
 empty=$(printf '%s' "$record" |
   jq -r '[.bans.emptySets[]?] | join(", ")' 2>/dev/null)
 
-[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$density" ] && [ -z "$shape" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
+[ -z "$hits" ] && [ -z "$headings" ] && [ -z "$colons" ] && [ -z "$density" ] && [ -z "$tables" ] && [ -z "$shape" ] && [ -z "$unread" ] && [ -z "$empty" ] && exit 0
 
 nl=$'\n'
 msg=""
@@ -125,6 +130,11 @@ if [ -n "$density" ]; then
   msg="${msg:+$msg$nl}$found"
 fi
 
+if [ -n "$tables" ]; then
+  found=$(printf 'Standards-audit: %s breaks the markdown table limits, being a 120-character cell, 8 body rows, a list directly after a table, and a code span holding a run past 30 characters. These report and never fail a push. Move a long cell into a bullet under the table'"'"'s lead, split a long table into groups each under a lead sentence, give a trailing list its own lead sentence, and move a wide token out of the table.\n%s' "$file" "$tables")
+  msg="${msg:+$msg$nl}$found"
+fi
+
 if [ -n "$shape" ]; then
   found=$(printf 'Standards-audit: %s is marked kind: reference and breaks its shape, being an opening, then Output, Refusals, and See also, each at most once and in that order, no H3, and no flag table. Point at the command'"'"'s own --help for flags. A finding marked gating fails the push.\n%s' "$file" "$shape")
   msg="${msg:+$msg$nl}$found"

package/tooling/claude/seeds/CLAUDE.md

@@ -15,5 +15,14 @@
 
 ## Key paths
 
+### Code
+
+[One sentence on what the code paths below hold]
+
 - `src/`: [description]
+
+### Content
+
+[One sentence on what the content paths below hold]
+
 - `canon/DESIGN.md`: visual intent, pointing at the stylesheet that holds the values

package/tooling/cloudflare/configs/.github/workflows/deploy.yml

@@ -130,36 +130,18 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      # 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. An absent secret skips the
-      # job the way the deploy's own guard does.
+      # The default branch, since a closed pull request may have no merge ref to
+      # check out, and the script that holds the Cloudflare token should not
+      # come from the branch being closed.
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
       - name: Delete preview deployments
         env:
           CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          # Fill in the same Pages project name the Publish step deploys to.
-          PROJECT_NAME: REPLACE_WITH_PROJECT_NAME
           BRANCH: ${{ github.head_ref }}
-        run: |
-          if [ -z "$CLOUDFLARE_API_TOKEN" ] || [ -z "$CLOUDFLARE_ACCOUNT_ID" ]; then
-            echo "::notice::CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID is not set, skipping preview cleanup."
-            exit 0
-          fi
-          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."
+        # Fill in the same Pages project name the Publish step deploys to.
+        run: bash scripts/delete-previews.sh REPLACE_WITH_PROJECT_NAME "$BRANCH"

package/tooling/cloudflare/configs/scripts/delete-previews.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Deletes the Cloudflare Pages preview deployments minted for one branch, called
+# by the cleanup-preview job in .github/workflows/deploy.yml with the Pages
+# project name and the branch. CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID
+# come from the step env, and an absent secret skips the job the way the
+# deploy's own guard does.
+#
+# 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.
+set -e
+
+PROJECT_NAME=$1
+BRANCH=$2
+
+if [ -z "$CLOUDFLARE_API_TOKEN" ] || [ -z "$CLOUDFLARE_ACCOUNT_ID" ]; then
+  echo "::notice::CLOUDFLARE_API_TOKEN or CLOUDFLARE_ACCOUNT_ID is not set, skipping preview cleanup."
+  exit 0
+fi
+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/tooling/cloudflare/reference.md

@@ -2,7 +2,9 @@
 
 ## Overview
 
-The cloudflare stack ships one parameterized GitHub Actions workflow that deploys a static build to Cloudflare Pages. It is keyed on host rather than on framework and carries no dependencies, seeds, or scripts of its own, so it syncs onto a project already carrying `astro`, `vite-react`, or any other stack without colliding.
+The cloudflare stack ships one parameterized GitHub Actions workflow that deploys a static build to Cloudflare Pages. It is keyed on host rather than on framework and carries no dependencies or seeds of its own, so it syncs onto a project already carrying `astro`, `vite-react`, or any other stack without colliding.
+
+It ships one script, `scripts/delete-previews.sh`, which the cleanup job calls and which overwrites a project's own file of that name on every sync.
 
 ## Deploy workflow
 
@@ -28,7 +30,8 @@ Every branch gets a preview URL rather than only `main`.
 
 A `pull_request` trigger on `closed` runs only the `cleanup-preview` job, which deletes every preview deployment Cloudflare holds for that branch.
 
-- It lists them through the Pages REST API, because the wrangler listing has no branch filter.
+- It checks out the default branch and runs `scripts/delete-previews.sh` with the Pages project name and the closing branch as arguments.
+- The script lists them through the Pages REST API, because the wrangler listing has no branch filter.
 - It deletes each with `force=true`, so a deployment still holding the branch alias goes too.
 - It skips with a notice when the secrets are absent, the same as the deploy job.
 
@@ -38,9 +41,9 @@ Three values in the seeded file have no generic default, and a project sets them
 
 - The `paths:` filter under the `push` trigger ships as a single `src/**` glob. Widen it to every path the build reads when the build draws on catalogs or generated content outside `src/`.
 - The `concurrency.group` name ships as `deploy-${{ github.ref_name }}`, enough for one deploy. Rename the `deploy` prefix only for a second deploy workflow, and keep the ref suffix.
-- The Pages project name appears twice as `REPLACE_WITH_PROJECT_NAME`, in the `--project-name` flag and as `PROJECT_NAME` in the cleanup job.
+- The Pages project name appears twice as `REPLACE_WITH_PROJECT_NAME`, in the `--project-name` flag and as the first argument to `scripts/delete-previews.sh` in the cleanup job.
 - Set both to the name the `deploy-app` skill creates the project under.
 
 ## Re-sync
 
-`configs/` is golden and always overwrites. Re-running `canon tooling sync cloudflare . --write` after hand-editing any of the three parameters above discards that edit and restores the shipped defaults. Re-fill the parameters after any re-sync rather than expecting the file to preserve them.
+`configs/` is golden and always overwrites, `scripts/delete-previews.sh` included. Re-running `canon tooling sync cloudflare . --write` after hand-editing any of the three parameters above discards that edit and restores the shipped defaults. Re-fill the parameters after any re-sync rather than expecting the file to preserve them.

package/tooling/web/reference.md

@@ -86,6 +86,11 @@ The web layer covers the tooling shared across Vite + React, Astro, and Next.js.
 - `.github/workflows/verify.yml` runs `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests`. `unit-tests` installs Chromium and runs `test:browser` only when the project defines that script.
 - Read `governance/rules/tooling/ci-workflow.md` for when a workflow's commit-back is right and when a report is
 
+## Design references
+
+- Expect a seeded `canon/design/index.md` stub carrying `auto: false`, copied only when missing, so a project's own index is never replaced
+- Expect `governance/rules/ui/design-reference.md` to install once a group folder sits under `canon/design/`, since the stub alone is no reference
+
 ## Ports
 
 - Derive every served port from `scripts/worktree-port.sh`, never a port literal in a script string, since two worktrees of one repository otherwise attach to one server

package/tooling/web/seeds/canon/design/index.md

@@ -0,0 +1,23 @@
+---
+title: Design references
+description: The accepted design frames a build matches, grouped by app part, with the code each group governs
+auto: false
+---
+
+# Design references
+
+Each group holds accepted frames a build matches, light and dark. The `design-record` skill carries the folder standard, so load it before adding, redrawing, or removing a reference.
+
+## Layout
+
+- Give each app part one plain kebab-case folder, such as `home` or `inspector`
+- Put tokens, colors, and the logo under `foundations/`
+- Name each file `<name>-dark` or `<name>-light`, a PNG beside its frame HTML
+- Put what every frame loads under `kit/`
+
+## Groups
+
+One row per group, `foundations` included. List no files, since the tree answers what exists.
+
+| Group | What the user sees | Code | States |
+| ----- | ------------------ | ---- | ------ |