@erclx/canon 5.64.0 → 5.66.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [5.66.0](https://github.com/erclx/canon/compare/v5.65.0...v5.66.0) (2026-10-25)
+
+
+### Features
+
+* **labels:** seed a starter label map and create its labels ([#2715](https://github.com/erclx/canon/issues/2715)) ([82a11b1](https://github.com/erclx/canon/commit/82a11b13870960926f0844519a76e039afd0ed5c))
+* **pr:** close a pull request with a required reason ([#2718](https://github.com/erclx/canon/issues/2718)) ([963f784](https://github.com/erclx/canon/commit/963f784e46e25e3c42ea1f6027a7b04860ec544e))
+* **pr:** probe declared health paths before linking the local preview ([#2712](https://github.com/erclx/canon/issues/2712)) ([a16c3f9](https://github.com/erclx/canon/commit/a16c3f966211f5bd9b8af9f82720d42251ac41b9))
+
+
+### Bug Fixes
+
+* **sandbox:** retry the replay checkout copy on a vanished file ([#2720](https://github.com/erclx/canon/issues/2720)) ([64d964b](https://github.com/erclx/canon/commit/64d964bdae0e26f79ab5c0ddc0c1f0e80bc20e6b))
+* **tooling:** install Go for the go stack verify job ([#2717](https://github.com/erclx/canon/issues/2717)) ([e87d433](https://github.com/erclx/canon/commit/e87d433bdbf64945165923d1b6f7294e2d873b7b))
+
+## [5.65.0](https://github.com/erclx/canon/compare/v5.64.0...v5.65.0) (2026-10-25)
+
+
+### Features
+
+* **sandbox:** fail the consumer replay when a snapshot read drifts ([#2709](https://github.com/erclx/canon/issues/2709)) ([68dc0b7](https://github.com/erclx/canon/commit/68dc0b7b55634ac9f7affca6da92cb523ed61754))
+* **sandbox:** replay consumer snapshots through sync in the gate ([#2703](https://github.com/erclx/canon/issues/2703)) ([3fd2934](https://github.com/erclx/canon/commit/3fd2934779b7f242a66ea273b3c53f79802e6494))
+* **skills:** ledger the review and teach craft sources ([#2702](https://github.com/erclx/canon/issues/2702)) ([877b660](https://github.com/erclx/canon/commit/877b66007e7e28c46c6de63d5a891083c19df6c1))
+* **skills:** source every test-craft and codebase-layout bullet ([#2704](https://github.com/erclx/canon/issues/2704)) ([44a23e9](https://github.com/erclx/canon/commit/44a23e936c62cab229a49f82a8775933e540460e))
+
 ## [5.64.0](https://github.com/erclx/canon/compare/v5.63.0...v5.64.0) (2026-10-24)
 
 

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.64.0",
+  "version": "5.66.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/git-pr/references/labels.md

@@ -109,10 +109,14 @@ Labelling runs whenever this skill runs and at no other time, recomputing over t
 Warn and continue rather than creating it, naming the command in the warning:
 
 ```bash
-gh label create <name> --description "<text>"
+canon labels sync
 ```
 
-Creating a label writes to the repository settings from a run invoked to open a pull request, and a label created from a map typo is harder to notice than a warning.
+It creates every label the map names that the remote lacks, and never edits or deletes one.
+
+- An installed `canon` predating the verb takes `gh label create <name>` per label instead
+- Creating a label writes to the repository settings, and a label created from a map typo is harder to notice than a warning
+- So the operator runs the sync on purpose after reading the map, and a run invoked to open a pull request never does
 
 The refusal names the label it rejected and applies none of the set, so an unseen warning leaves the run reading like one that labelled. Surface it beside the result line rather than letting the pull request URL stand alone.
 

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

@@ -0,0 +1,29 @@
+---
+name: git-pr-close
+description: What closing a pull request unmerged is for, the gap it closes, and how it splits from merging and from the verb it calls
+---
+
+# Git PR close requirement
+
+## Gap
+
+Without this skill, a session asked to close a pull request improvises a bare close. Most hand-closed pull requests then carry no reason, so a reader who finds one later cannot tell a rejected idea from a superseded one or a pause. No `git-*` skill covered the act, so the request had nowhere to route.
+
+## Must
+
+- Every close goes through `canon pr close`, which refuses without a reason and posts it before the close
+- The reason follows the shape `references/close.md` fixes, opening on what happened and ending on what replaces it or how to reopen
+- A close of another branch's pull request names that branch through `--head`, so a wrong number refuses rather than closing someone else's work
+
+## Must not
+
+- Merge, mark ready, or reopen a pull request
+- Guess a number from the newest pull request in view
+- Close with no reason, or post the reason any way other than through the verb
+- Exist only to be typed by name. It earns its place when a session routes "close this PR" or a superseded batch here unprompted.
+
+## Out of scope
+
+- Writing the gate on the reason, which the verb owns
+- Merging, which the operator runs through `canon pr merge`
+- Closing an issue, which `git-issue` covers

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

@@ -0,0 +1,55 @@
+---
+name: git-pr-close
+description: Closes an open pull request without merging it, posting a short reason first and deleting its head branch, through `canon pr close`. Use when asked to "close this PR", "close #N", "supersede #N with #M", "abandon this pull request", or "drop this PR". Do NOT use to merge, which the operator does, or to close an issue, which `git-issue` covers.
+metadata:
+  family: after-pr
+---
+
+# Git PR close
+
+Close one pull request unmerged with its reason on the thread, so a later reader finds why without asking.
+
+Read `${CLAUDE_SKILL_DIR}/references/close.md` before writing the reason, for its shape and the two forms it takes.
+
+## Guards
+
+- Take the number the caller named. With none named, "this pull request" means the current branch's, read from the `number` of `canon pr head --json`.
+- Never guess a number from the newest pull request in view, since a wrong number closes another branch's work
+- If the caller gave no reason and none follows from the conversation, stop: `❌ No reason to post. Say why this pull request is closing.`
+
+## Step 1: write the reason
+
+Write the reason to `.canon/tmp/pr/close/close-<number>.md` in its own call, in the shape `close.md` fixes.
+
+## Step 2: close
+
+Run the verb. It refuses unless the pull request's head is the branch `--head` names, defaulting to the current branch, so a wrong number writes nothing.
+
+```bash
+canon pr close <number> --reason-file .canon/tmp/pr/close/close-<number>.md --json
+```
+
+- Pass `--head <branch>` only when closing a branch this checkout is not on, taking the branch from the caller, such as a dispatch naming it or the batch a replacement merged
+- Never read `--head` off the pull request being closed, since a branch read from the same number agrees with any number and the check proves nothing
+- Pass `--keep-branch` only when the caller says the branch stays
+- The verb posts the reason, closes, then deletes the branch, and refuses before any write on a reason it cannot publish
+
+## Step 3: read the record
+
+Branch on `reason` rather than the exit, since a shell function wrapping `canon` can flatten it.
+
+| `reason`               | Route                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `closed`               | Report the comment URL, and name the branch when `branch` is `delete-failed` |
+| `reason-unpublishable` | Rewrite the sentence each finding names, then run Step 2 again               |
+| `head-mismatch`        | Stop and report it, since the number names another branch's pull request     |
+| `close-failed`         | Report that the comment posted and the pull request is still open            |
+| Any other refusal      | Report the `message` and stop                                                |
+
+## Output
+
+One line on a close:
+
+```plaintext
+✅ Closed #<number>: <comment url>
+```

package/claude/skills/git-pr-close/references/close.md

@@ -0,0 +1,54 @@
+---
+title: Closing comment reference
+description: The shape of the comment a pull request carries when it closes unmerged, its two forms, and the limits the verb checks
+---
+
+# Closing comment reference
+
+## Scope
+
+Governs the comment posted when a pull request closes without merging.
+
+Does not govern:
+
+- A pull request body or title: `${CLAUDE_SKILL_DIR}/../git-pr/references/pr.md`
+- A review reply, which `review-address` writes
+
+## Shape
+
+A reader who finds the closed pull request later learns why it closed and where the work went, in two sentences at most.
+
+- Open on what happened: `Superseded by #<number>` when another pull request carries the work, or `Closing unmerged.` otherwise
+- Say why in one sentence, naming the decision rather than retelling the discussion that reached it
+- End on what replaces it, or how to reopen when the close is a pause
+- Keep each paragraph under 350 characters, and two paragraphs at most
+
+### Superseded
+
+Another pull request carries the work, so the comment links it and says nothing is left behind.
+
+```markdown
+Superseded by #<replacement>, which combines this batch with the five other context rebuilds and carries every reviewed change from this branch. Nothing here is left to carry over.
+```
+
+### Closed for a decision
+
+Nothing replaces the work, so the comment names the decision that ended it.
+
+```markdown
+Closing unmerged. Base's starter label map should stay stack-neutral rather than list every stack's configs, so each project adds rows for its own stack.
+```
+
+## What the verb refuses
+
+`canon pr close` checks the reason before it reads the pull request, and refuses `reason-unpublishable` with the findings in its record.
+
+- A banned character, a phase label, a board reference, or a session link, the checks `canon labels scan` runs on a body
+- A paragraph or a run of paragraphs past the density limits, measured on the reason itself
+- The scan measures density only on a post opening on a known heading, so the verb measures it here
+
+## Sources
+
+- [Zephyr pull request lifecycle policy](https://docs.zephyrproject.org/latest/contribute/pr_lifecycle_policy.html)
+  - "Close with explicit rationale and a reopen path."
+  - For a superseded one: "Link the replacement pull request." and "Add a short summary comment preserving context."

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

@@ -43,11 +43,11 @@ Collect only the lines below whose condition holds, and nothing when none does.
 | A checklist posted alone                                  | `📋 Posted the UI checklist to <number>, on its own.`              |
 | The preview step returned an address                      | `🔗 Preview: <url>`                                                |
 | The evidence step posted the local link                   | `🖥️ Local preview: <url>`                                          |
-| The local step refused and evidence or a checklist posted | `🖥️ No local preview: <reason>`                                    |
+| The local step refused and evidence or a checklist posted | `🖥️ No local preview: <reason>: <message>`                         |
 | A git refusal or a preview refusal the reference reports  | `⚠️ <reason>: <message>`                                           |
 
 ### The no-local-preview line
 
-It fires when the local step refused as `no-server` or `no-listener-reader`, since that pull request changes a rendered surface and a reviewer could have used the link. A later run only carries a link forward, so it cannot add one the comment never had.
+It fires when the local step refused under any reason the reference holds, `unhealthy` included, since that pull request changes a rendered surface and a reviewer could have used the link. The `message` names what to fix, such as the failing health path. A later run only carries a link forward, so it cannot add one the comment never had.
 
 To add the link later, start the server and run this skill again, adding `--checklist` to the evidence call when one is still owed.

package/claude/skills/pr-evidence/references/evidence.md

@@ -35,7 +35,9 @@ canon pr local --json
 The verb reports the lowest port serving an HTML page whose process runs inside this worktree, never one in another worktree or the main checkout, which shows a different branch. `canon pr local --help` states the contract. Read `reason` on the record rather than the exit code.
 
 - `ok`: hold the record's `url` for the evidence step below.
-- `no-server` or `no-listener-reader`: hold the reason for the closing report and pass no link. Never start a server here, since the ship chain cannot own one. A worker starts one under `role-worker`.
+- `no-server`, `no-listener-reader`, `unhealthy`, or `invalid-config`: hold the reason and the record's `message` for the closing report, and pass no link.
+- `unhealthy` means a page answered but a health path declared in `canon/config/local.toml` failed. `invalid-config` means that file cannot be read, so nothing was checked.
+- Never start a server here, since the ship chain cannot own one. A worker starts one under `role-worker`.
 - Anything else, including no record or an older binary's unknown-subcommand error: move on silently, as a skip rather than a stop.
 
 ### Where the link lands

package/claude/skills/role-worker/SKILL.md

@@ -46,8 +46,8 @@ Open the task's `## Findings` line for an override with the bold source-and-date
 
 A painted pull request needs a server in this worktree for `canon pr local` to find, and this session is the one with a lifetime to own it. `auto-ship` Step 5 decides whether the diff is painted, so this body restates no file test.
 
-- Run `canon pr local --json` first and start nothing when `reason` reads `ok`
-- Otherwise start the stack's `dev` script as a background command from the worktree root before the pull request step. `dev` follows the worktree, so a `review-address` fix shows on the same link.
+- Run `canon pr local --json` first. Start nothing on `ok`, `unhealthy`, or `invalid-config`, and carry a refusal's `message` in the announcement
+- Otherwise start the stack's `dev` in the background from the worktree root before the pull request step, so a `review-address` fix shows on the same link.
 - Wait up to 60 seconds for the verb to read `ok`, then ship either way. A stack with no `dev` script gets no start, and `pr-evidence` reports `no-server`.
 - Never detach it with `nohup`, `setsid`, or `disown`, since the owning session is the stop. `canon worktrees reclaim` ends any listener left in a worktree it removes.
 

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

@@ -31,7 +31,7 @@ An element counts as stable once it "has maintained the same bounding box for at
 
 - 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 `contextOptions: { reducedMotion: 'reduce' }`, 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
+- From Playwright 1.50 a top-level `use: { reducedMotion: 'reduce' }` works too ([TestOptions](https://playwright.dev/docs/api/class-testoptions)). Before 1.50 it is no test option, so a spec asserting the media query catches it
 
 A site honoring the reduced preference then has nothing to wait out in any test that does not opt back in.
 

package/docs/workflow/skill-map.md

@@ -80,6 +80,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:git-followup`   | A small edit on a branch with an open PR      |
 | `canon:pr-evidence`    | A new head needs its screenshots re-posted    |
 | `canon:git-split`      | A branch carries unrelated commits            |
+| `canon:git-pr-close`   | A pull request closes without merging         |
 | `canon:git-issue`      | Something belongs on the tracker              |
 | `canon:git-worktree`   | After a merge, to reclaim worktrees           |
 

package/governance/ledger/skills/codebase-layout/SKILL.md

@@ -0,0 +1,64 @@
+---
+title: Codebase layout skill ledger
+description: Sources for claude/skills/codebase-layout/SKILL.md, one row per bullet in its concern groups
+---
+
+# Codebase layout skill ledger
+
+The field is source organization. Robert Martin carries cohesion and folder naming, Kent C. Dodds and Robin Wieruch carry colocation and promotion, bulletproof-react carries the import direction, and the Go blog carries file and package naming. The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+No outside source takes a side on when a plan states a path, so the rows for stating a reason, naming a new folder, and reading a reference are house choices naming the misplacement each prevents.
+
+## Read the project's strategy first
+
+| Bullet                                | Source                                                                                                                                                                                                          | Read       |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Name the project's layout first       | [React, File Structure](https://legacy.reactjs.org/docs/faq-structure.html): "React doesn’t have opinions on how you put files into folders", so the project's own layout is the only one a new file can follow | 2026-10-24 |
+| Keep to that strategy                 | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): "choose a strategy that works for you and your team and be consistent across the project"                          | 2026-10-24 |
+| A strategy change is its own decision | House choice: a strategy changed as a side effect of placing one file leaves two strategies in the tree, and every later reader guesses which one a file follows                                                | 2026-10-24 |
+
+## Group what changes together
+
+| Bullet                              | Source                                                                                                                                                                                                                                                     | Read       |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One folder per reason to change     | [Martin, The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html): "Gather together the things that change for the same reasons. Separate those things that change for different reasons." | 2026-10-24 |
+| Name a folder for what it holds     | [Martin, Screaming Architecture](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html): "Your architectures should tell readers about the system, not about the frameworks you used in your system."                               | 2026-10-24 |
+| No bare `utils` or `helpers` bucket | [Gerrand, Package names](https://go.dev/blog/package-names): "Packages named util , common , or misc provide clients with no sense of what the package contains."                                                                                          | 2026-10-24 |
+
+## Name a file for what it covers inside its folder
+
+| Bullet                                 | Source                                                                                                                                                                                                                    | Read       |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The stem never repeats the folder      | [Gerrand, Package names](https://go.dev/blog/package-names): "Since client code uses the package name as a prefix when referring to the package contents, the names for those contents need not repeat the package name." | 2026-10-24 |
+| Drop the prefix and retarget on a move | House choice: a file moved into a subfolder that keeps its old prefix says its folder twice, and a citation left on the old path resolves nowhere                                                                         | 2026-10-24 |
+| The stem runs to the first dot         | House choice: reading the stem past a suffix lets `checkout/checkout.test.ts` pass a check that `checkout/checkout.md` fails, though both repeat their folder                                                             | 2026-10-24 |
+
+## Split before the file lands
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                                                     | Read       |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Split on a second role, before landing | [Martin, The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html): "Separate those things that change for different reasons." Splitting before the file lands is a House choice: the split costs a handful of paths then and 98 later, as the body records | 2026-10-24 |
+| Ten files is a prompt, not a gate      | House choice: no source gives a reliable ceiling, and a count fails a large folder of one role that reads fine flat while passing a small one mixing two                                                                                                                                                                   | 2026-10-24 |
+| A new role gets a named folder         | House choice: a role whose first file lands beside its nearest neighbor leaves the folder holding two roles, and the next file copies the first                                                                                                                                                                            | 2026-10-24 |
+
+## Place a file with its consumer
+
+| Bullet                         | Source                                                                                                                                                                                                                                             | Read       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Colocate with the one consumer | [Dodds, Colocation](https://kentcdodds.com/blog/colocation): "Place code as close to where it's relevant as possible"                                                                                                                              | 2026-10-24 |
+| Promote on the second consumer | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "if exactly one feature uses a util, it lives inside that feature", and "once two or more features need it, it moves up to the shared layer"               | 2026-10-24 |
+| Imports flow one way           | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): "the code should flow in one direction, from shared parts of the code to the application (shared -> features -> app)" | 2026-10-24 |
+
+## State the reason on every new path
+
+| Bullet                                | Source                                                                                                                                                                | Read       |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A one-clause reason per new path      | House choice: a worker copies the path a plan gives it, so a path with no stated reason lands beside its nearest neighbor and the plan's placement call is never made | 2026-10-24 |
+| Name a new folder where it is created | House choice: a folder the plan leaves implied is inferred by the worker, who drops the file in the nearest existing folder instead                                   | 2026-10-24 |
+
+## Read the reference for the category
+
+| Bullet                     | Source                                                                                                                                                                        | Read       |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Interface source reference | House choice: an interface file placed without `frontend.md` lands in the shared `components/` or `lib/` folder whatever its consumer, the flat growth that reference records | 2026-10-24 |
+| Test file reference        | House choice: a test helper placed without `tests.md` lands beside the specs it serves, so the end to end folder stops holding one role                                       | 2026-10-24 |

package/governance/ledger/skills/codebase-layout/frontend.md

@@ -0,0 +1,62 @@
+---
+title: Frontend layout reference ledger
+description: Sources for claude/skills/codebase-layout/references/frontend.md, one row per bullet
+---
+
+# Frontend layout reference ledger
+
+The field is interface source organization. bulletproof-react carries feature folders and the import direction, Robin Wieruch carries the levels and the promotion rule, and the Next.js docs carry routing. Each row cites the bullet's own inline link where the reference carries one.
+
+The worked failure reports what one project's folders did, so its rows are house choices naming the failure the incident shows rather than outside citations.
+
+## Feature folders against shared UI
+
+| Bullet                                  | Source                                                                                                                                                                                                                                                  | Read       |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One feature's code under its folder     | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): "organize most of the code within the features folder", and "Only include the ones that are necessary for the feature."    | 2026-10-24 |
+| Shared `components/` for two features   | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): `components` holds "shared components used across the entire application"                                                  | 2026-10-24 |
+| One feature's component is feature code | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): feature components "are often only used once in a React project", while generic UI components "are used by more than one component"                             | 2026-10-24 |
+| No feature imports another              | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): "It might not be a good idea to import across the features. Instead, compose different features at the application level." | 2026-10-24 |
+| Enforce the flow with an import lint    | [bulletproof-react, Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md): "To forbid cross-feature imports, you can use ESLint", through `import/no-restricted-paths`                                | 2026-10-24 |
+
+## Grow in levels
+
+| Bullet                          | Source                                                                                                                                                                                                                                                    | Read       |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Start flat                      | [React, File Structure](https://legacy.reactjs.org/docs/faq-structure.html): "If you feel completely stuck, start by keeping all files in a single folder. Eventually it will grow large enough that you will want to separate some files from the rest." | 2026-10-24 |
+| The next level on a named event | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "The day the customer feature needs it too, it moves up to the top-level hooks/ folder."                                                                          | 2026-10-24 |
+| One level per change            | House choice: a plan that jumps from flat to a full feature tree rewrites every import in the project in one diff no review can follow                                                                                                                    | 2026-10-24 |
+
+## Routes
+
+| Bullet                                    | Source                                                                                                                                                                                                                                      | Read       |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The router's own conventions first        | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): the page gives "an overview of all the folder and file conventions in Next.js, and recommendations for organizing your project"                | 2026-10-24 |
+| An unopinionated framework leaves it open | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): "Next.js is unopinionated about how you organize and colocate your project files."                                                             | 2026-10-24 |
+| One strategy, kept consistent             | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): "choose a strategy that works for you and your team and be consistent across the project"                                                      | 2026-10-24 |
+| A route's component in a private folder   | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): private folders "colocate non-routable files", as `app/blog/_components/Post.tsx` is marked "Not routable" and a "safe place for UI utilities" | 2026-10-24 |
+| `components` and `lib` are placeholders   | [Next.js, Project structure](https://nextjs.org/docs/app/getting-started/project-structure): "we're using components and lib folders as generalized placeholders, their naming has no special framework significance"                       | 2026-10-24 |
+
+## Hooks and helpers
+
+| Bullet                                  | Source                                                                                                                                                                                             | Read       |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One feature's hook inside it            | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "A hook that only the project feature uses lives inside features/project/hooks/ ."                         | 2026-10-24 |
+| Promote on the second feature           | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "once two or more features need it, it moves up to the shared layer"                                       | 2026-10-24 |
+| Split a shared `lib/` holding two roles | [Martin, The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html): "Separate those things that change for different reasons."      | 2026-10-24 |
+| A helper named for what it does         | [Gerrand, Package names](https://go.dev/blog/package-names): "Avoid meaningless package names. Packages named util , common , or misc provide clients with no sense of what the package contains." | 2026-10-24 |
+
+## Fixtures and sample data
+
+| Bullet                            | Source                                                                                                                                                      | Read       |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Fixtures beside their feature     | [Dodds, Colocation](https://kentcdodds.com/blog/colocation): "Things that change together should be located as close as reasonable."                        | 2026-10-24 |
+| Promote a fixture on two features | House choice: a fixture moved to shared code for one feature's tests drifts from that feature, and the next change to it lands far from the tests it breaks | 2026-10-24 |
+
+## A worked failure
+
+| Bullet                                        | Source                                                                                                                                                               | Read       |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The rules said split, and nobody applied them | House choice: a rule loaded beside a plan that names every file as a sibling of the last loses to the plan, so placement has to be decided where the path is written | 2026-10-24 |
+| The split touched 98 files                    | House choice: a split put off until a folder overflows touches every import of every file in it, and a folder left without a placement rule grows flat again         | 2026-10-24 |
+| A named subfolder at the twelfth file         | House choice: the cost of placement grows with the folder, so the cheapest split is the one a plan names when the second role's first file arrives                   | 2026-10-24 |

package/governance/ledger/skills/codebase-layout/tests.md

@@ -0,0 +1,26 @@
+---
+title: Test layout reference ledger
+description: Sources for claude/skills/codebase-layout/references/tests.md, one row per bullet
+---
+
+# Test layout reference ledger
+
+The field is test file organization. Kent C. Dodds carries colocating a test with its module, and Playwright's fixtures and page object docs carry the split between specs and support. The reference's worked failure is prose rather than bullets, so it takes no table.
+
+## Unit and component tests
+
+| Bullet                                | Source                                                                                                                                                                                                                                      | Read       |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A test beside its module              | [Dodds, Colocation](https://kentcdodds.com/blog/colocation): "we should co-locate our tests files with the file or group of files they are testing"                                                                                         | 2026-10-24 |
+| The test moves with the module        | [Dodds, Colocation](https://kentcdodds.com/blog/colocation): with a mirrored tree, "We'd move or delete a src/ file without updating the corresponding" file beside it, and "All the pitfalls described above apply here as well" for tests | 2026-10-24 |
+| A one-file factory stays in that file | [Wieruch, React Folder Structure](https://www.robinwieruch.de/react-folder-structure/): "if exactly one feature uses a util, it lives inside that feature", and "once two or more features need it, it moves up to the shared layer"        | 2026-10-24 |
+
+## End to end tests
+
+| Bullet                                  | Source                                                                                                                                                                                                                                               | Read       |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Only specs in the runner's folder       | House choice: support code among the specs gives a new spec no single place to find its setup, and the next helper lands beside the others                                                                                                           | 2026-10-24 |
+| One merged fixtures module              | [Playwright, Fixtures](https://playwright.dev/docs/test-fixtures): an extended test "can be used in multiple test files, and each of them will get the fixtures", and `mergeTests` combines "test fixtures from multiple files or modules"           | 2026-10-24 |
+| Each page object its own module         | [Playwright, Fixtures](https://playwright.dev/docs/test-fixtures) imports each page object from its own module, as `TodoPage` from `./todo-page`, and [page object models](https://playwright.dev/docs/pom) capture "element selectors in one place" | 2026-10-24 |
+| Support in its own folder, named by use | House choice: a single `helpers` file every spec imports grows into a bucket naming no role, the fault the body's naming rule forbids for any folder                                                                                                 | 2026-10-24 |
+| Group specs by journey once they mix    | House choice: specs for two journeys in one folder hold two roles, so a reader finds a journey's specs only by opening each file                                                                                                                     | 2026-10-24 |

package/governance/ledger/skills/review-craft/SKILL.md

@@ -0,0 +1,61 @@
+---
+title: Review craft skill ledger
+description: Sources for claude/skills/review-craft/SKILL.md, one row per bullet or ordered step in its concern groups
+---
+
+# Review craft skill ledger
+
+The field is code review. Google's reviewer guide carries the axes, Parnas, Ousterhout, and Beck as Fowler records him carry the design walk, and the skills pinned at `addyosmani/agent-skills@2686b620` carry the bar, performance, and scope checks.
+
+Steps 4, 5, and 8 of the walk have no source in the skill's `adopted.md`, so their rows cite Fowler's FlagArgument with Refactoring Guru's Message Chains, Martin's Single Responsibility Principle post, and Cockburn's Hexagonal Architecture.
+
+The proof ladder and the evidence bar are this toolkit's own, so their rows name the failure each prevents. Closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+Parnas's paper refused a read at its ACM DOI, `10.1145/361598.361623`, so the rows quote an open copy of the same paper.
+
+## Open with the one fact the change's safety rests on
+
+| Bullet         | Source                                                                                                                        | Read       |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Asserted       | House choice: a risky claim taken on the description's word merges unproven, since nothing marks it as the weakest proof      | 2026-10-24 |
+| Pointed at     | House choice: a claim naming its test reads as proven when nobody opened the test, so naming the code is its own lower rung   | 2026-10-24 |
+| Walked through | House choice: reasoning that traces the path still misses the input it never imagined, so it ranks below a test that runs     | 2026-10-24 |
+| Tested         | House choice: a claim with no failing test regresses silently on the next change, so a test in the diff outranks any argument | 2026-10-24 |
+| Reproduced     | House choice: a test can pass on a stubbed path, so a recorded run of the real thing is the one rung above it                 | 2026-10-24 |
+
+## Read the axes in this order
+
+| Bullet                                    | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Read       |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Design and scope                          | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): "The most important thing to cover in a review is the overall design of the CL", and "Reviewers should be especially vigilant about over-engineering"                                                                                                                                                                                                                   | 2026-10-24 |
+| Correctness and edge cases                | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): "you should still be thinking about edge cases, looking for concurrency problems, trying to think like a user"                                                                                                                                                                                                                                                          | 2026-10-24 |
+| What breaks outside the diff              | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): "Sometimes you have to look at the whole file to be sure that the change actually makes sense", and a change that "deletes or deprecates code" asks "whether the documentation should also be deleted"                                                                                                                                                                  | 2026-10-24 |
+| Tests                                     | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): "Will the tests actually fail when the code is broken?"                                                                                                                                                                                                                                                                                                                 | 2026-10-24 |
+| Guard the bar                             | [agent-skills, constraint-driven-development](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/constraint-driven-development/SKILL.md): it watches the diff for a weakened bar, being "new @ts-ignore or eslint-disable suppressions, skipped or deleted tests, assertions stripped out, unimplemented stubs, thresholds edited down"                                                                                                          | 2026-10-24 |
+| Performance                               | [agent-skills, code-review-and-quality](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/code-review-and-quality/SKILL.md): "Any N+1 query patterns?", "Any unbounded loops or unconstrained data fetching?", "Any missing pagination on list endpoints?"                                                                                                                                                                                      | 2026-10-24 |
+| Security                                  | [agent-skills, security-and-hardening](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/security-and-hardening/SKILL.md): "Where does untrusted data cross into your system?", asked before any control is checked                                                                                                                                                                                                                             | 2026-10-24 |
+| Rendered output                           | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): a UI change is when checking behavior matters most, since "It's hard to understand how some changes will impact a user when you're just reading the code"                                                                                                                                                                                                               | 2026-10-24 |
+| Developer experience and operations       | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): "If a CL changes how users build, test, interact with, or release code, check to see that it also updates associated documentation"                                                                                                                                                                                                                                     | 2026-10-24 |
+| Executable prose                          | House choice: a skill body or rule is run by a model with no reviewer in the loop, so a race, an unstated precondition, or a contradiction between two steps ships as a bug that no test of the code catches                                                                                                                                                                                                                                                                                  | 2026-10-24 |
+| Name the next change and count its reach  | [Parnas, On the Criteria To Be Used in Decomposing Systems into Modules](https://www.win.tue.nl/~wstomv/edu/2ip30/references/criteria_for_modularization.pdf): "one begins with a list of difficult design decisions or design decisions which are likely to change"                                                                                                                                                                                                                          | 2026-10-24 |
+| State what each unit hides                | [Ousterhout and Martin, A Philosophy of Software Design vs Clean Code](https://github.com/johnousterhout/aposd-vs-clean-code): "I call these interfaces 'shallow': they don't help much in terms of reducing what the programmer needs to know"                                                                                                                                                                                                                                               | 2026-10-24 |
+| Each rule or constant in one place        | [Fowler, BeckDesignRules](https://martinfowler.com/bliki/BeckDesignRules.html): Beck's rules include "No duplication", and the code "Has no duplicated logic"                                                                                                                                                                                                                                                                                                                                 | 2026-10-24 |
+| Flag parameters, chains, and global state | [Fowler, FlagArgument](https://martinfowler.com/bliki/FlagArgument.html): "A flag argument is a kind of function argument that tells the function to carry out a different operation depending on its value", and [Refactoring Guru, Message Chains](https://refactoring.guru/smells/message-chains): "the client is dependent on navigation along the class structure". House choice for global state: a read or write of it couples every caller to an order nothing in the signature shows | 2026-10-24 |
+| One reason to change per file             | [Martin, The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html): "Gather together the things that change for the same reasons. Separate those things that change for different reasons."                                                                                                                                                                                                                                    | 2026-10-24 |
+| List the hidden inputs                    | House choice: code reading the clock, the environment, the filesystem, or a random source runs differently in a test than in use, so its tests flake or fake the input and its reuse breaks on the next machine                                                                                                                                                                                                                                                                               | 2026-10-24 |
+| Match each pattern to a problem today     | [Fowler, BeckDesignRules](https://martinfowler.com/bliki/BeckDesignRules.html): the last rule, "Fewest elements", so the code "Has the fewest possible classes and methods"                                                                                                                                                                                                                                                                                                                   | 2026-10-24 |
+| Domain rules apart from data in and out   | [Cockburn, Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture/): an application "developed and tested in isolation from its eventual run-time devices and databases"                                                                                                                                                                                                                                                                                                 | 2026-10-24 |
+| Names, literals, dropped errors, effects  | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): "Did the developer pick good names for everything?"                                                                                                                                                                                                                                                                                                                     | 2026-10-24 |
+| Name the split of two concerns            | [Google, Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html): "the right size for a CL is one self-contained change", one that "addresses just one thing"                                                                                                                                                                                                                                                                                                      | 2026-10-24 |
+| Count concepts before and after           | [agent-skills, code-review-and-quality](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/code-review-and-quality/SKILL.md): "Does this refactor reduce complexity or just relocate it? Count the concepts a reader must hold to follow the change."                                                                                                                                                                                            | 2026-10-24 |
+| Say why removed code existed              | [agent-skills, code-simplification](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/code-simplification/SKILL.md): "Before changing or removing anything, understand why it exists", and "Check git blame"                                                                                                                                                                                                                                    | 2026-10-24 |
+
+## Hold every finding to the evidence bar
+
+| Bullet                            | Source                                                                                                                                                                                                                              | Read       |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Confirm against the reviewed head | [Google, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html): "Usually the code review tool will only show you a few lines of code around the parts that are being changed" | 2026-10-24 |
+| Quote the rule cited              | House choice: a finding citing a rule by name alone sends the author to find it first, and a paraphrase drifts from what the rule says                                                                                              | 2026-10-24 |
+| Name the input that breaks        | House choice: a finding with no failing input cannot be reproduced or refuted, so the author either guesses at a fix or dismisses a real bug                                                                                        | 2026-10-24 |
+| Drop what a gate already owns     | House choice: a review restating a linter or a type error reports it with less certainty than the gate, and the noise buries the findings only a reader can make                                                                    | 2026-10-24 |
+| Drop what rests on unread state   | House choice: a finding about state the reviewer never opened is a guess posted as a fact, and the author spends a round disproving it                                                                                              | 2026-10-24 |

package/governance/ledger/skills/review-craft/security.md

@@ -0,0 +1,34 @@
+---
+title: Review craft security ledger
+description: Sources for claude/skills/review-craft/references/security.md, one row per bullet
+---
+
+# Review craft security ledger
+
+The field is application security review. MITRE's CWE entries name each weakness, ShellCheck carries the shell fixes, npm's own docs and Snyk's lockfile write-up carry the supply chain, and Anthropic's security review action pinned at `anthropics/claude-code-security-review@0c6a49f1` carries the exclusions.
+
+The threat model section and the classes stated as prose carry no bullet, so they take no row.
+
+## Classes to check
+
+| Bullet                               | Source                                                                                                                                                                                                                                                                        | Read       |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The paths into a shell               | [CWE-78, OS Command Injection](https://cwe.mitre.org/data/definitions/78.html): "The product constructs all or part of an OS command using externally-influenced input from an upstream component, but it does not neutralize or incorrectly neutralizes special elements"    | 2026-10-24 |
+| Quoting at the call site             | [ShellCheck, SC2086](https://github.com/koalaman/shellcheck/wiki/SC2086): "Double quote to prevent globbing and word splitting."                                                                                                                                              | 2026-10-24 |
+| An empty value collapsing to a root  | [ShellCheck, SC2115](https://github.com/koalaman/shellcheck/wiki/SC2115): "Use `\"${var:?}\"` to ensure this never expands to `/*`", against `rm -rf "$STEAMROOT/"*`                                                                                                          | 2026-10-24 |
+| A glob or symlink carrying it out    | [CWE-59, Link Following](https://cwe.mitre.org/data/definitions/59.html): "does not properly prevent that filename from identifying a link or shortcut that resolves to an unintended resource"                                                                               | 2026-10-24 |
+| No check one level below a root      | [agent-skills, security-and-hardening](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/security-and-hardening/SKILL.md): the resolved target "sits under an allowlisted root", and "it is at least one level below that root" | 2026-10-24 |
+| No read of what is there             | [agent-skills, security-and-hardening](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/security-and-hardening/SKILL.md): the target "carries ownership evidence read before the operation"                                    | 2026-10-24 |
+| Name the class whose fix applies     | House choice: one bug filed under two classes gets two fixes or neither, so the finding names the class whose fix the author applies                                                                                                                                          | 2026-10-24 |
+| Unpinned one-shot package execution  | [npm, npx](https://docs.npmjs.com/cli/v10/commands/npx): a package "not present in the local project dependencies" is installed to the npm cache and run, so an unpinned name runs whatever the registry serves                                                               | 2026-10-24 |
+| A new dependency's install scripts   | [npm, scripts](https://docs.npmjs.com/cli/v10/using-npm/scripts): its life cycle order runs `preinstall`, `install`, and `postinstall` on `npm install`                                                                                                                       | 2026-10-24 |
+| A lockfile changing with no manifest | [Snyk, Why npm lockfiles can be a security blindspot](https://snyk.io/blog/why-npm-lockfiles-can-be-a-security-blindspot-for-injecting-malicious-modules/): an install "will consult the lockfile as the primary source of truth for package versions and their sources"      | 2026-10-24 |
+
+## Excluded
+
+| Bullet                                   | Source                                                                                                                                                                                                                                                                                  | Read       |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Denial of service and exhaustion         | [Anthropic, claude-code-security-review prompts](https://github.com/anthropics/claude-code-security-review/blob/0c6a49f1fa56a1d472575da86a94dbc1edb78eda/claudecode/prompts.py): "Denial of Service (DOS) vulnerabilities or resource exhaustion attacks", and "Rate limiting concerns" | 2026-10-24 |
+| Generic input validation                 | [Anthropic, claude-code-security-review prompts](https://github.com/anthropics/claude-code-security-review/blob/0c6a49f1fa56a1d472575da86a94dbc1edb78eda/claudecode/prompts.py): "If there isn't a proven problem from a lack of input validation, don't report it."                    | 2026-10-24 |
+| Open redirects                           | [Anthropic, claude-code-security-review findings filter](https://github.com/anthropics/claude-code-security-review/blob/0c6a49f1fa56a1d472575da86a94dbc1edb78eda/claudecode/findings_filter.py): drops a finding as "Open redirect vulnerability (not high impact)"                     | 2026-10-24 |
+| A theoretical attack needing access held | [Anthropic, claude-code-security-review prompts](https://github.com/anthropics/claude-code-security-review/blob/0c6a49f1fa56a1d472575da86a94dbc1edb78eda/claudecode/prompts.py): "Skip theoretical issues, style concerns, or low-impact findings"                                      | 2026-10-24 |