@erclx/canon 4.96.0 → 4.98.0

package/docs/agents/capture.md

@@ -18,9 +18,9 @@ canon capture https://example.com --selector .window --out preview.png
 
 ## What this repository captures
 
-A capture set here spans two folders. `assets/captures/` holds five sources and the template each is written from, and `assets/evidence/` holds the five images a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the five is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
+A capture set here spans two folders. `assets/captures/` holds three sources and the template each is written from, and `assets/evidence/` holds their images and the built-page capture a document points at with the stamp answering for each, under the segment `canon pr evidence` compares. One run over the source folder rebuilds every image, and it takes `--out assets/evidence` to put each PNG where its document points rather than beside the markup it rendered. None of the three sources is edited by hand. `scripts/core/regen-hero.sh` writes each `.html` from the template beside it, filling one shared value map into all of them, and `bun run check` regenerates them and fails on the difference.
 
-Three of the five take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` and `task-board.html` are the two exceptions: the first holds terminal text from a real run and the second holds a hand-frozen snapshot of a gitignored board, each in its template rather than derived from a live catalog at build time.
+Two of the three take catalog data, so a stack gaining a rule moves the frame on the next run. `install.html` is the exception, since it holds terminal text from a real run in its template rather than derived from a live catalog at build time. `assets/evidence/arrival.png` is the one image with no source here: it is the built page's `.fold` element captured in dark mode against a local `web/` preview, since `canon capture` takes no color scheme and the page follows the browser's default of light, so it is retaken by hand when the page's first screen changes.
 
 `assets/captures/` is read flat and never descends, by the regeneration script, by this command, and by the drift stage alike. A source nested a further folder down is skipped by all three with nothing reported, so a new frame is a template dropped directly in rather than a folder of its own. The split is what retired the name prefix the flat layout used to need: a frame is named for itself now, since `assets/captures/` no longer mixes markup in with the images.
 

package/docs/agents/commands.md

@@ -94,7 +94,8 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon pr head`                  | Compare the head a pull request object reports against the branch tip the remote carries, naming both shas (`--root`, `--json`)                                                                                                                                                                                              |
 | `canon pr checks`                | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean (`--root`, `--json`)                                                                                                                                                                                            |
 | `canon pr review-state`          | Report the commit and instant the last review pass covered, off the pass's own marker rather than the fields GitHub stamps at submission (`--root`, `--json`)                                                                                                                                                                |
-| `canon pr evidence`              | Render a before-and-after comment comparing changed `evidence/` images against the merge base, editing its own prior comment in place rather than posting a second (`--root`, `--json`)                                                                                                                                      |
+| `canon pr evidence`              | Render a before-and-after comment comparing changed `evidence/` images against the merge base, editing its own prior comment in place rather than posting a second (`--root`, `--json`, `--preview`)                                                                                                                         |
+| `canon pr preview`               | Dispatch the Pages deploy on a pull request's branch and report the preview address the run prints, refusing a deploy that passes no `--branch` (`--root`, `--json`, `--timeout`)                                                                                                                                            |
 | `canon repo metadata propose`    | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`)                                                                                                                                                             |
 | `canon repo metadata apply`      | Write an explicitly supplied description, homepage, or topic set to the remote through `gh repo edit` (`--description`, `--homepage`, `--topics`, `--root`, `--json`)                                                                                                                                                        |
 | `canon census [path]`            | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                                                                                                                                                                         |

package/docs/agents/index.md

@@ -31,6 +31,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
 - [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
+- [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
 - [Records](records.md): The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, claiming the ordinal intake and groundwork share, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates

package/docs/agents/pr-evidence.md

@@ -51,7 +51,7 @@ image or marks the case new.
 | `ok`                 | A body was rendered. `commentId` is set when a marked comment already exists. |
 | `no-evidence`        | Nothing in the diff carries an `evidence/` segment. An ordinary silent no-op. |
 | `gh-missing`         | `gh` is not on the path, so no pull request could be resolved.                |
-| `gh-failed`          | `gh` could not answer for this repository or branch.                          |
+| `gh-failed`          | `gh` could not answer for this repository or branch, or read its comments.    |
 | `no-branch`          | The pull request carries no head branch name.                                 |
 | `no-object-head`     | The pull request object reported no head commit.                              |
 | `no-base`            | No base resolves against the trunk.                                           |
@@ -99,6 +99,14 @@ also why this verb renders the whole comment body rather than handing each
 skill a record to format on its own: a fix to the table shape or the
 collapsed-details wrapper lands once, not twice.
 
+## The preview line
+
+`--preview <url>` opens the body with the branch's preview address, and a run
+without it carries forward the address the marked comment already holds. With
+no evidence in the diff and an address in hand, the body is the address and the
+marker alone, reported as `ok`. `canon docs pr-preview` covers where the
+address comes from.
+
 ## What a collapsed comment still leaves to GitHub
 
 GitHub already draws its own before-and-after comparison on the Files Changed

package/docs/agents/pr-preview.md

@@ -0,0 +1,103 @@
+---
+title: The pull request preview deploy
+description: How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
+---
+
+# The pull request preview deploy
+
+`canon pr preview` publishes a pull request's branch to a Cloudflare Pages
+preview and reports the address. `git-pr` calls it after the evidence
+comparison, then re-renders that comment through `canon pr evidence --preview`
+so the link opens it. A reviewer gets a page to click into before merging
+rather than screenshots and a checklist alone.
+
+```bash
+canon pr preview --json
+canon pr preview 1341 --json --timeout 20
+```
+
+## Which workflow it dispatches
+
+The verb reads `.github/workflows/*.yml` and `*.yaml` in the checkout and picks
+the first file, in path order, that meets four tests:
+
+- It runs `pages deploy`.
+- It carries a `workflow_dispatch` trigger, since nothing else lets a caller
+  start it on a branch.
+- Its deploy passes `--branch=${{ github.ref_name }}`.
+- It prints a `canon-preview-alias:` line.
+
+The workflow is read before the pull request, so a project with no fenced
+deploy is refused without a network call.
+
+## Why an unfenced deploy is refused
+
+Cloudflare Pages publishes a deploy that names no branch to production. A
+dispatch from an unmerged branch through such a workflow ships that branch to
+the live site, so the verb refuses as `unfenced` and dispatches nothing. The
+fix is one flag on the deploy command, and the cloudflare stack's
+`deploy.yml` already carries it.
+
+## Where the address comes from
+
+The workflow prints the alias Cloudflare returned for the deploy, read from
+`wrangler-action`'s `pages-deployment-alias-url` output, on a fixed line:
+
+```plaintext
+canon-preview-alias: https://<alias>.<project>.pages.dev
+```
+
+The verb reads that line out of the finished run's log rather than computing
+the address from the branch name. Cloudflare flattens a branch into its alias
+and may truncate it, and a computed address that is wrong is worse than none.
+The output needs wrangler 3.78 or later, so the workflow pins
+`wranglerVersion`.
+
+`gh workflow run` reports no run id. The verb lists the branch's dispatched
+runs before dispatching and takes the one id that appears afterwards, which
+keeps the match independent of the local clock.
+
+## What the record carries
+
+`reason` on the record is what a caller branches on, not the exit code:
+
+| Reason        | What it means                                                              |
+| ------------- | -------------------------------------------------------------------------- |
+| `ok`          | The preview was published. `url` carries the address and `runId` the run.  |
+| `no-deploy`   | No dispatchable workflow runs `pages deploy`.                              |
+| `unfenced`    | The deploy passes no `--branch`, so nothing was dispatched.                |
+| `no-alias`    | The workflow prints no alias line, or the finished run's log carried none. |
+| `run-failed`  | The deploy run finished without succeeding. `runId` names it.              |
+| `timeout`     | The run did not finish inside `--timeout` minutes, 15 by default.          |
+| `bad-timeout` | `--timeout` was not a positive number.                                     |
+| `gh-missing`  | `gh` is not on the path.                                                   |
+| `gh-failed`   | `gh` could not read the pull request, or list or dispatch the workflow.    |
+| `no-branch`   | The pull request carries no head branch name.                              |
+
+The exit is 0 on `ok` and 1 on every refusal. A `timeout` leaves the run
+going, so the preview may still land after the verb has given up on it.
+
+## How the address reaches the pull request
+
+`canon pr evidence --preview <url>` puts `**Preview:** <url>` on the first line
+of the evidence body. With no evidence image in the diff, the body is that line
+and the trailing marker alone, so a pull request with a checklist and no
+screenshots still gets one comment a later call can find and edit.
+
+A later `canon pr evidence` run without `--preview` reads the address off the
+marked comment and carries it into the new body. `git-followup` re-renders the
+comment after every push, and without that carry the first push would delete
+the link.
+
+## Removing a preview
+
+A `pull_request` trigger on `closed` in the same workflow runs a cleanup job
+that deletes every preview deployment Cloudflare holds for the branch. The
+deploy job carries `if: github.event_name != 'pull_request'`, so a closed pull
+request never deploys.
+
+## What this does not cover
+
+The verb builds only the deployed-and-public case. A private repository whose
+previews need access protection, and a project with no deploy at all where a
+local server would stand in, both wait for a project that needs them.

package/docs/workflow/ai-workflow.md

@@ -223,6 +223,7 @@ This section is the corpus the coverage claim is measured against: every name `c
 | `canon:draft-and-pick`     | When the call is taste and wants several candidates rendered side by side       |
 | `canon:task-board`         | When a decided item needs a file on the board, or a shipped one needs archiving |
 | `canon:plan-feature`       | When the approach is settled and the next step is a plan                        |
+| `canon:codebase-layout`    | When a plan or change adds a file and you need to decide which folder holds it  |
 
 ### Build the feature
 

package/governance/rules/core/000-constitution.md

@@ -19,7 +19,7 @@ Your primary directive is to maintain long-term system health over short-term co
 - Implement only the functionality required for the immediate task (YAGNI).
 - Extract shared logic into single-purpose utilities. Never duplicate behavior across modules (DRY).
 - Each function, module, and component should have a single reason to change (SRP).
-- Apply SRP to directories: once a folder mixes distinct roles and grows past a handful of files, split it into subfolders by role.
+- Apply SRP to directories: once a folder mixes distinct roles and grows past a handful of files, split it into subfolders by role. Load the `canon:codebase-layout` skill before placing a new file, and report it rather than proceeding silently when it does not resolve.
 - Favor composition over inheritance.
 - Prioritize native platform capabilities over third-party libraries.
 

package/governance/rules/lib/300-testing-ts.md

@@ -27,6 +27,7 @@ paths:
 - Place all Playwright tests within the `e2e/` directory.
 - Never place Playwright tests inside `src/`.
 - Scope the three rules above to tests the Playwright runner executes. A Vitest test importing a browser driver to exercise project code stays beside its module, where Vitest looks for it.
+- Keep specs apart from their fixtures, page objects, and helpers inside `e2e/`. Load the `canon:codebase-layout` skill for the folder shape.
 
 ## Timers and async
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.96.0",
+  "version": "4.98.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -77,8 +77,11 @@ GOV_JSON="$(catalog gov list)"
 STANDARDS_JSON="$(catalog standards list)"
 SNIPPETS_JSON="$(catalog snippets list)"
 TOOLING_JSON="$(catalog tooling list)"
+# The catalog ledger names three commands, and the registered set is only
+# readable from the root help, which lists one per line under `Commands:`.
+COMMANDS_HELP="$(cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts --help 2>/dev/null)"
 
-for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON"; do
+for payload in "$COUNTS_JSON" "$SKILLS_JSON" "$GOV_JSON" "$STANDARDS_JSON" "$SNIPPETS_JSON" "$TOOLING_JSON" "$COMMANDS_HELP"; do
   if [ -z "$payload" ]; then
     echo "regen-hero: a catalog returned nothing, refusing to write a zeroed hero" >&2
     exit 1
@@ -98,6 +101,7 @@ printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
 printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
 printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
 printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
+printf '%s' "$COMMANDS_HELP" >"$PAYLOAD_DIR/commands-help.txt"
 printf '%s' "$TOKEN_CSS" >"$PAYLOAD_DIR/tokens.css"
 
 export PAYLOAD_DIR
@@ -326,8 +330,36 @@ for (const [label, rows] of [
   }
 }
 
+// The ledger names a few real entries per domain. Chosen by hand for the same
+// reason FEATURED_SKILLS is, and asserted against the catalog so a rename fails
+// the run rather than leaving a name the repository no longer ships.
+const commandNames = readFileSync(PAYLOAD_DIR + "/commands-help.txt", "utf8")
+  .split("\n")
+  .map((line) => line.match(/^[│\s]{2,}(?<name>[a-z][a-z-]*)\s/)?.groups?.name)
+  .filter(Boolean)
+const LEDGER = [
+  ["skills", skills.length, ["plan-feature", "role-orchestrator", "review-pr"], skills],
+  ["rules", rules.length, ["behavior", "memory", "testing"], rules],
+  ["standards", standards.length, ["markdown", "plan", "teach"], standards],
+  ["commands", commandCount, ["gov", "tasks", "design"], commandNames],
+  ["stacks", toolingStacks.length, ["astro", "python", "web"], toolingStacks.map((stack) => stack.name)],
+]
+for (const [domain, , chosen, names] of LEDGER) {
+  const known = new Set(names)
+  const missing = chosen.filter((name) => !known.has(name))
+  if (missing.length > 0) {
+    console.error(`regen-hero: ledger ${domain} names missing from the catalog: ${missing.join(", ")}`)
+    process.exit(1)
+  }
+}
+const ledgerRows = LEDGER.map(
+  ([domain, count, chosen]) =>
+    `      <div class="row"><span class="count">${count}</span><span class="domain">${domain}</span><span class="names">${escape(chosen.join(", "))}</span></div>`,
+).join("\n")
+
 const values = {
   TOKENS: tokenCss,
+  LEDGER_ROWS: ledgerRows,
   GOV_STACK_ROWS: govStackRows,
   GOV_RULE_ROWS: govRuleRows,
   STANDARD_ROWS: standardRows,

package/src/claude/cases/misc.ts

@@ -59,6 +59,11 @@ export const MISC_CASES: readonly SkillCase[] = [
       'The loading state already shipped. Should its test be an e2e test or a component one, and is the one I wrote any good?',
     expect: 'test-craft',
   },
+  {
+    prompt:
+      "The e2e folder has specs and helpers mixed together and I'm adding two more, where should they go?",
+    expect: 'codebase-layout',
+  },
   {
     prompt: 'Does our github about text still match what the readme says?',
     expect: 'repo-metadata',