@erclx/canon 4.95.0 → 4.97.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.95.0",
+  "version": "4.97.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/codebase-layout/REQUIREMENT.md

@@ -0,0 +1,46 @@
+---
+name: codebase-layout
+description: Why the session writing a new path into a plan needs placement guidance at that moment, and where that guidance stops short of test layers and module interfaces
+---
+
+# Codebase layout requirement
+
+## Gap
+
+Without this skill, the session that decides where a new file goes has nothing about layout in front of it when it decides. The planner writes each new path into the plan, the worker copies it, and the planner's only instruction on the tree is to measure against it, which for a new path reads as copying the flat folder beside it.
+
+The failure is measured on a real target. Two source folders grew from 11 files to 46 and 36 flat files in six days, with the constitution's directory line and a stack rule mandating feature folders both installed throughout. The split that followed touched 98 files, and the end to end folder is flat again, four specs beside five helpers. Archived plans from the same project name every new file as a literal flat path.
+
+Sharpening the rules does not reach the decision. Both were loaded and neither was applied, since an always-loaded line competes with everything else a session holds and a path-scoped rule fires on a read of an existing file rather than on a path written into a plan.
+
+## Must
+
+- Be loaded by `plan-feature` whenever a plan names a path that does not exist yet, so the guidance is in front of the planner at the moment it writes the path
+- Tell the session to name and keep to the project's existing layout strategy before placing a file, since two strategies in one tree cost every reader a guess
+- State the split trigger as a second role entering a folder, with a file count only as a prompt to look
+- State colocation with the one consumer and promotion on the second, and imports flowing from shared toward features toward the app entry
+- Require a one-clause placement reason on every new path the plan names
+- Hold the stack-neutral core in the body and defer category specifics to a reference loaded only when a new path falls in that category
+- Record the external layouts adopted and declined with the reason for each, so a later session extends the position instead of re-deriving it
+- Fire on a direct question about placement as well, such as where a file goes or whether a flat folder should split, since a session outside any plan still places files
+
+## Must not
+
+- Name a framework or runner in the body. Stack specifics live in the references.
+- Carry a hard file-count threshold. A command folder holding sixty files of one role reads fine flat, and a number would fail it.
+- Restate the layer rule, the layer table, or the final filter `test-craft` owns
+- Mandate one layout across projects, such as a `features/` tree, over the project's own strategy
+- Restate the constitution's directory line. The rule points here and this body carries the depth.
+
+## Guards
+
+- A plan that only edits existing files does not load the skill, so the cost lands only where a placement is decided
+- A strategy change is proposed as its own decision rather than made while placing one file
+
+## Out of scope
+
+- Which layer a test belongs at: `test-craft`
+- Interface depth, seams, and where a module boundary sits in code, which govern a module's shape rather than its path on disk
+- Per-language placement conventions such as test suffixes and the top-level test folder: the language testing rules
+- Backend, asset, and script layouts, which wait for a driving project before a reference is written
+- Whether a plan that loaded the skill actually places files differently, which needs a measured run on a target rather than a rule here

package/claude/skills/codebase-layout/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: codebase-layout
+description: Carries the rules that decide where a new file goes, when a folder splits, and when a file moves from its one consumer to shared code, so a plan places each new path by role and feature with a one-clause reason rather than beside its nearest neighbor. Use when a plan names a file or folder that does not exist yet, when `plan-feature` reaches its placement step, or when asked "where should this file go", "this folder is flat", "restructure this folder", or "should this be its own folder". Do NOT use to choose which layer a test belongs at, which is `test-craft`, or to shape a module's interface and seams.
+---
+
+# Codebase layout
+
+A session placing a new file copies the folder next to it, so a flat folder stays flat until a refactor pays to split it. In one target, two source folders grew to 46 and 36 flat files under installed rules against it, and the split cost a pull request touching 98 files. This skill carries the placement call to the moment the path is written, which is the one moment it is cheap.
+
+Load it before writing a new path into a plan, not after. A worker copies the path the plan gives it, so the placement is settled once the plan is.
+
+Skip it when every path the work names already exists.
+
+## Read the project's strategy first
+
+- Name the layout the project already uses before placing anything: by feature, by route, by role, or flat. Look at the folders a new file would sit beside and at any stated rule on layout.
+- Keep to that strategy. A second strategy beside the first costs every later reader a guess about which one a file follows.
+- Propose a strategy change as its own decision, never as a side effect of placing one file.
+
+## Group what changes together
+
+- Put files that change for the same reason in one folder, and separate files that change for different reasons.
+- Name a folder for what it holds for a reader, being a feature, a route, or a role, over its technical kind alone. `checkout/` tells a reader what is inside where `helpers/` does not.
+- Never create a bucket named `misc`, `common`, `utils`, or `helpers` on its own. Qualify it by what it serves, or place the file with its consumer.
+
+## Split before the file lands
+
+- Split a folder when the new file brings a second role into it, before the file lands rather than in a later refactor. The split that touched 98 files would have touched a handful when the folder held eleven.
+- Treat roughly ten files as a prompt to look, not a gate. A folder holding one role can stay flat at any size, and a folder mixing two roles is worth splitting at six.
+- Give a new role a named folder in the plan, rather than dropping its first file beside the nearest neighbor.
+
+## Place a file with its consumer
+
+- Colocate a new file with the one module that uses it.
+- Promote it to shared code when a second consumer arrives, and move it in the change that adds that consumer.
+- Keep imports flowing one way, from shared code toward features toward the app entry. A shared module importing from a feature, or one feature importing another, names a file in the wrong place.
+
+## State the reason on every new path
+
+- Give each new path in a plan a one-clause reason for where it sits: the role it holds, the consumer it serves, or the strategy it follows.
+- Name a new folder in the plan entry that creates it, so the worker creates the folder rather than inferring it.
+
+## Read the reference for the category
+
+Read the reference matching what the new paths hold, and skip the rest.
+
+- Application source for an interface: `${CLAUDE_SKILL_DIR}/references/frontend.md`
+- Test files of any layer: `${CLAUDE_SKILL_DIR}/references/tests.md`
+
+Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which external layouts were adopted, which were declined, and why.
+
+## What this delegates
+
+- Which layer a test belongs at: `test-craft`. This skill decides where the test file sits once its layer is chosen.
+- Where a new path gets written into a plan, and the plan's shape: `plan-feature` and the plan standard
+- The directory principle every session loads: `000-constitution`
+- Runner, suffix, and top-level test folder conventions per language: `300-testing-ts` and `330-testing-py`

package/claude/skills/codebase-layout/references/adopted.md

@@ -0,0 +1,34 @@
+---
+title: Adopted and declined
+description: Which external layout patterns this skill adopted, which it declined, and why, so a later session extends the position instead of re-deriving it
+---
+
+# Adopted and declined
+
+External sources were read and filtered rather than imported. This file is the record. A later session extending the skill adds to it rather than re-arguing an item already settled here.
+
+## Adopted
+
+**Group what changes together.** Robert Martin's restatement of the single responsibility principle: "Gather together the things that change for the same reasons. Separate those things that change for different reasons" ([The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html)). It gives "split by role" a test a planner can apply to a folder: would these files change together?
+
+**Name folders for the domain rather than the framework.** Martin's Screaming Architecture argues the top level should tell readers "about the system, not about the frameworks you used in your system" ([Screaming Architecture](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html)). It is the root of naming a folder for what it holds rather than its technical kind.
+
+**Feature folders, no cross-feature imports, one-way flow.** bulletproof-react puts most code under per-feature folders holding only the subfolders each needs, forbids one feature importing another, and enforces a shared, then features, then app direction with an import-path lint rule ([project structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)). Adopted as the direction rule in the body and the feature-folder guidance in `frontend.md`, without the mandate.
+
+**Grow in levels and promote on the second consumer.** Robin Wieruch grows a project from one file to feature folders, each level triggered by a named event rather than a count, and moves a helper to the shared layer once two or more features need it ([React folder structure](https://www.robinwieruch.de/react-folder-structure/)). Adopted as the promotion rule in the body and the levels in `frontend.md`.
+
+**Consistency over any one strategy.** The Next.js docs call the framework unopinionated about organization, list three strategies, and ask a project to "choose a strategy that works for you and your team and be consistent across the project" ([project structure](https://nextjs.org/docs/app/getting-started/project-structure)). Adopted as the body's first section, reading and keeping the project's own strategy.
+
+**Fixtures in modules, page objects on their own.** Playwright defines fixtures in dedicated modules that extend the base test, merges them into one module the specs import, and keeps page objects as their own modules ([fixtures](https://playwright.dev/docs/test-fixtures)). Adopted in `tests.md` as the split between specs and support.
+
+## Declined
+
+**Deep modules and seams.** Matt Pocock's codebase-design skill covers a lot of behavior behind a small interface placed at a clean seam ([codebase-design](https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/SKILL.md)). It answers where a boundary goes in code, not where a file goes on disk, and absorbing it doubles the skill's scope before the placement problem is shown solved. It becomes a reference only when a plan places files well and still draws a boundary badly.
+
+**A mandated `features/` tree.** bulletproof-react's layout, and a stack rule some projects install, put domain code under `src/features/`. Declined as a mandate because it conflicts with keeping the project's own strategy, and a project that never adopted feature folders gains a second strategy rather than a better one. A stack rule mandating the tree still loads beside this skill in a project that installs it, and the two give different answers there until that rule is softened on its own.
+
+**A numeric file ceiling.** None of the sources gives a reliable number, and a count fails a folder holding sixty files of one role that reads fine flat. The body triggers on a second role and treats roughly ten files as a prompt to look.
+
+**A required placement field in the plan format.** It would touch every plan, including the ones that create nothing. The body asks for a one-clause reason on each new path instead, and the field is worth revisiting only if plans load the skill and still list flat paths.
+
+**Loading the skill in the worker.** The worker copies the path the plan gives it, so placement is already decided by the time a worker would read this.

package/claude/skills/codebase-layout/references/frontend.md

@@ -0,0 +1,43 @@
+---
+title: Frontend layout
+description: Where interface source goes, being feature folders against shared UI, routes and their private folders, hooks and helpers split by consumer, fixtures by feature, and the promotion rule, with one worked failure
+---
+
+# Frontend layout
+
+Read this before placing a new component, hook, helper, route, or fixture in an interface project. The body's rules hold here unchanged, and this file says how they land on the folders an interface project grows.
+
+## Feature folders against shared UI
+
+- Put code that serves one feature under that feature's folder, holding only the subfolders it needs: its components, its hooks, its data access, its types ([bulletproof-react](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)).
+- Keep the shared `components/` folder for pieces two or more features render, such as a button, a dialog, or a layout shell. A component only one feature renders is feature code, even when it looks generic.
+- Never import one feature from another. Lift the piece both need to shared code, or compose the two features at the app or route level ([bulletproof-react](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)).
+- Enforce the flow from shared toward features toward the app where the project already lints imports. An import-path restriction turns the direction into a check rather than a habit.
+
+## Grow in levels
+
+- Start flat. A small project with one screen needs no feature folders, and adding them early is structure nobody reads.
+- Move to the next level on a named event rather than a count: a second feature, a second role in `components/`, a helper only one feature uses ([Robin Wieruch](https://www.robinwieruch.de/react-folder-structure/)).
+- Take one level per change. A plan that jumps from flat to a full feature tree rewrites every import in the project.
+
+## Routes
+
+- Follow the router's own conventions where the framework ships file-based routing, and treat everything outside them as project strategy.
+- A framework calling itself unopinionated about organization leaves the strategy to the project. Pick one of keeping code outside the routes folder, top-level folders inside it, or splitting by feature or route, and "be consistent across the project" ([Next.js project structure](https://nextjs.org/docs/app/getting-started/project-structure)).
+- Colocate a component only one route renders beside that route, in a folder the router excludes from routing, such as a private `_components` folder in a router that supports one.
+- Treat `components` and `lib` as placeholder names with no framework meaning. Their contents still follow the body's rules.
+
+## Hooks and helpers
+
+- Put a hook or helper one feature uses inside that feature. Promote it to a shared `hooks/` or `lib/` folder when a second feature needs it, and move it in the change that adds the second consumer ([Robin Wieruch](https://www.robinwieruch.de/react-folder-structure/)).
+- Split a shared `lib/` by what each file serves once it holds two roles, such as data access beside formatting beside browser APIs. A flat `lib/` is the second folder to overflow after `components/`.
+- Name a helper file for what it does rather than `utils` or `helpers`, so the folder listing reads as an index.
+
+## Fixtures and sample data
+
+- Keep fixtures and sample data beside the feature they describe, and name the file for that feature.
+- Promote a fixture to a shared folder only when two features' tests build from it.
+
+## A worked failure
+
+An interface project's `components/` folder held 11 files when its first plan landed and 46 six days later, with its `lib/` at 36, all flat. Every plan in between named each new file as a sibling of the last, since the folder it was measured against was flat. The installed rules said to split by role and to keep domain logic in feature folders, and neither was applied. The split, when it came, touched 98 files, and the project's end to end folder has since grown flat again, four specs beside five helpers. Placing the twelfth component in a named subfolder would have cost that plan one folder.

package/claude/skills/codebase-layout/references/tests.md

@@ -0,0 +1,28 @@
+---
+title: Test layout
+description: Where test files live once their layer is chosen, being unit tests beside their module and an end to end folder split into specs, a fixtures module, page objects, and support, with one worked failure
+---
+
+# Test layout
+
+Read this before placing a new test file or a file a test imports. Which layer the test belongs at is settled first, by `test-craft`. This file starts from that answer and says where the file goes.
+
+## Unit and component tests
+
+- Put a unit or component test beside the module it tests, named after it, so a reader opening the module finds its test in the same listing.
+- Move the test with the module. A test left behind in a folder its module has left is the first sign the folder no longer holds one role.
+- Keep a factory or builder one test file uses inside that file. Move it beside the tests that share it once a second file needs it, and name it for what it builds.
+
+## End to end tests
+
+A browser suite starts as a folder of specs, and every helper written after the first lands beside them unless something says otherwise. Split the folder by role before the first support file lands.
+
+- Keep specs in the folder the runner reads, and nothing there but specs once support code exists.
+- Put fixtures in a dedicated module that extends the runner's base test, and merge several into one fixtures module the specs import ([Playwright fixtures](https://playwright.dev/docs/test-fixtures)). A spec importing its setup from one place is how a new spec finds what exists.
+- Give each page object its own module, named for the page or region it drives ([Playwright fixtures](https://playwright.dev/docs/test-fixtures)).
+- Put helpers, stubs, and seed data in a support folder beside the specs rather than among them. Name each file for what it serves, never a single `helpers` file every spec imports.
+- Group specs by journey once they mix, such as checkout specs in one folder and account specs in another. A folder of a handful of specs covering one journey stays flat.
+
+## A worked failure
+
+An interface project's end to end folder held four specs beside five helper files, all flat, after an earlier refactor had split its source folders by role. The project's plans named every new file as a literal flat path, so each helper landed as a sibling of the specs it served. A new spec then had no single place to find its setup, and the next helper went beside the others. One plan naming a support folder when the first helper arrived would have kept the specs as the folder's only role.

package/claude/skills/git-pr/REQUIREMENT.md

@@ -26,6 +26,8 @@ A lookup that resolves by head branch alone carries its own failure. A branch na
 - Label from the paths the branch changed, against a map the project declares, so the label set belongs to the project rather than to the skill
 - Apply labels after the pull request exists, so a label the remote does not carry costs a warning rather than the pull request
 - Report a refused label, since a warning nothing surfaces leaves the run indistinguishable from one that labelled
+- Put a preview address on a pull request that changes a rendered surface when the project's deploy can mint one, since screenshots and a checklist leave a reviewer nothing to click into before merging
+- Bound the wait on that preview and finish the chain without the link on a timeout, since a slow deploy must not hold the ship
 
 ## Must not
 
@@ -35,6 +37,7 @@ A lookup that resolves by head branch alone carries its own failure. A branch na
 - Edit a pull request that is not open, or record its number on a task
 - Name a domain of any one project in the skill body or its references
 - Create a label the map names and the remote lacks
+- Dispatch a deploy whose command names no branch, since Cloudflare Pages publishes such a deploy to production
 - Emit anything after the result line
 
 ## Guards

package/claude/skills/git-pr/SKILL.md

@@ -197,6 +197,27 @@ Clean up the tmp file the way the UI-checklist step does, only after the call re
 
 Any other `reason` is one of the mirrored git refusals (`gh-missing`, `gh-failed`, `no-base`, `unreadable-tree`, `unreadable-changes`). Report it and move on without stopping the chain: a branch that carries no evidence images most of the time should not fail here on a transient git or `gh` read.
 
+### Post the preview address
+
+Run this step only when the evidence step above returned `ok` or the UI checklist step posted a comment. Either one means the pull request changes a rendered surface, and a reviewer holding a checklist with no screenshots needs the live page most. Otherwise skip it silently.
+
+The evidence comment is already posted, so the reviewer has the screenshots while the deploy runs. Mint the preview against the same `<number>`:
+
+```bash
+canon pr preview <number> --json
+```
+
+The verb dispatches the project's Pages deploy on the pull request's branch and waits on the run for up to 15 minutes. It refuses before dispatching anything when the deploy command passes no `--branch`, since that deploy would publish the branch to production. `canon docs pr-preview` states the contract. Read `reason` on the record rather than the exit code.
+
+- `ok`: re-render the evidence body with the address on its first line, then post or update it exactly as the evidence step does, through the same tmp file and the `commentId` the record carries:
+
+```bash
+canon pr evidence <number> --preview <url> --json
+```
+
+- `no-deploy`: the project deploys nothing a dispatch can start. Say nothing and move on.
+- Any other `reason`, being `unfenced`, `no-alias`, `run-failed`, `timeout`, or a mirrored `gh` refusal: report it with the record's `message` and move on without stopping the chain. A missing link costs the reviewer a click, and a held ship costs the whole chain.
+
 ### Record the number on the task
 
 Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. `${CLAUDE_SKILL_DIR}/REQUIREMENT.md` states why: a lookup that resolves by branch alone can return a closed pull request sharing that head, so the number is resolved once and reused rather than re-derived.
@@ -233,4 +254,8 @@ Add a line when the UI checklist step posted a comment, naming the pull request
 
 `📋 Posted the UI checklist to <number>.`
 
+Add a line when the preview step returned an address:
+
+`🔗 Preview: <url>`
+
 Do not add any other text.

package/claude/skills/plan-feature/REQUIREMENT.md

@@ -13,6 +13,7 @@ Without this skill, implementation starts before anyone knows what it touches. A
 
 - Read the project's own Claude setup before scanning source, so the plan inherits decisions already made instead of reopening them
 - Name every file the work touches with the reason it is touched
+- Place each new path against the layout guidance with a one-clause reason, loading that guidance only when the plan creates a file or folder, since the planner decides placement and the worker copies whatever path it is given
 - Surface each unresolved ambiguity as a numbered question carrying a suggested answer and an empty answer slot, so the plan is decision-ready in one pass
 - State which act a constraint forbids when it names a surface to leave alone, since conforming that surface and retargeting a pointer into it are different acts and only one is out of scope
 - Scale the output to the work. A two-file change with nothing to decide should not produce a plan file.

package/claude/skills/plan-feature/SKILL.md

@@ -33,7 +33,7 @@ Coding standards live in `.claude/rules/`. Claude Code loads them automatically.
 
 Based on the feature description, identify and read source files that are directly relevant. Do not read entire directories speculatively. Where a folder carries an `index.md`, read it first and load only the files it points at.
 
-Measure against the tree rather than recall. Grep for each construct the plan will name and count the sites, so the plan carries the count the tree holds today. Confirm any work the plan sequences behind is still open, so it does not lead with an item that already shipped.
+Measure against the tree rather than recall. Grep for each construct the plan will name and count the sites, so the plan carries the count the tree holds today. The tree tells a new path what exists beside it, not where it belongs, so a flat folder is a reading to place against rather than a pattern to copy. Confirm any work the plan sequences behind is still open, so it does not lead with an item that already shipped.
 
 Open each file before describing what is in it. A count or a claim carried from an earlier session, a summary, or another document is the most common way a plan ships the wrong scope.
 
@@ -45,6 +45,7 @@ What this skill adds on top of the standard:
 
 - Apply senior judgment to every `- Suggested:` line. Pick the best option and state it in one line with its reason or main tradeoff. No padding, no alternatives unless they change the pick.
 - Suggest a real default when best practice, the codebase, or prior context points to one.
+- Load the `canon:codebase-layout` skill before writing the `**Files to touch:**` entries when any of them names a file or folder that does not exist yet, and give each new path its placement reason in its entry. Skip the load when every entry edits an existing file. Report it rather than proceeding silently when the skill does not resolve.
 - Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one.
 - When three or more questions remain, keep chat output to the file pointer plus a short summary. Inline chat is fine when two or fewer remain.
 

package/claude/skills/test-craft/REQUIREMENT.md

@@ -52,3 +52,12 @@ Moving the guidance into a path-scoped rule does not reach the session that need
 - Writing a UI change's tests and its visual checklist after implementation: `ui-test`
 - Grading the tests a pull request adds: `review-pr`
 - Whether the guidance moves where a session puts a test, which needs a measured with-and-without run rather than a rule here
+
+## Measured
+
+2026-09-19, one Sonnet run per arm over the `pull` arm of the toolkit's own sandbox scenario for this skill, a page with an end to end spec already beside it and a prompt adding a loading state.
+
+- With the skill: the loading state landed in a new component test and the existing end to end spec stayed unchanged.
+- Without it, on a plugin dir lacking the skill: no `Skill` call fired, and the run made the same placement, one component test with three cases and the spec unchanged.
+
+The arm did not discriminate, so the run shows no movement from the skill. It also shows that the pull toward extending an existing spec is too weak to move an unaided session, which is a fixture finding and not evidence about the body. A stronger pull, such as a prompt naming the spec, is the next arm to try before reading this as a rework signal on the skill. One run per arm on one model cannot separate a difference of one test from noise.

package/claude/skills/test-craft/references/e2e.md

@@ -28,7 +28,7 @@ Suites dominated by end to end tests inflate both runtime and flake ([Google Tes
 ## Motion off by default
 
 - Run with motion reduced unless the test asserts motion, and opt back in per test with `page.emulateMedia({ reducedMotion: 'no-preference' })`.
-- Set it once in the config's `use` block as `reducedMotion: 'reduce'` rather than per test, since the option defaults to `'no-preference'` ([TestOptions](https://playwright.dev/docs/api/class-testoptions)). A site honoring the reduced preference then has nothing to wait out in any test that does not opt back in.
+- Set it once in the config's `use` block as `contextOptions: { reducedMotion: 'reduce' }` rather than per test, since the option defaults to `'no-preference'` ([BrowserContext options](https://playwright.dev/docs/api/class-browser#browser-new-context)). A top-level `use.reducedMotion` reaches no page and type-checks nowhere, so a spec asserting the media query is what catches it. A site honoring the reduced preference then has nothing to wait out in any test that does not opt back in.
 
 ## Isolation and speed
 

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.95.0",
+  "version": "4.97.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

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',