@erclx/canon 5.41.0 → 5.43.0

package/claude/skills/ci-workflow/SKILL.md

@@ -17,7 +17,8 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 
 ## Workflow setup
 
-- Include `workflow_dispatch` on every workflow alongside the primary trigger.
+- Include `workflow_dispatch` alongside the primary trigger, except on a commit-back workflow, where a manual run has no branch to commit onto and would pass while doing nothing.
+- Set `permissions: contents: read` at the top level, and grant a write scope only on the job that needs it.
 - Pin all actions to major version tags (`@v4`, never `@latest` or `@main`).
 - Use `runs-on: ubuntu-latest` for all jobs.
 
@@ -50,6 +51,14 @@ Generate GitHub Actions workflow files for CI pipelines. Enforce parallel job ex
 - Install with `bun install --frozen-lockfile`.
 - Cache Playwright browsers keyed on the Playwright version string, never a static key.
 
+## Commit-back
+
+A workflow that pushes a regenerated file onto the pull request branch takes these on top of the setup above.
+
+- Set the concurrency group on the ref so a newer push cancels the run committing onto a stale head.
+- Set `HUSKY: 0` on the commit step when the runner lacks a tool a hook shells out to.
+- Fail a template's first step while a path list still holds its placeholder, so an unfinished install fails loudly rather than never firing.
+
 ## Template
 
 Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow template. Adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed. The template already carries the folded shape, and the split beside it applies once the granularity rule above calls for it.
@@ -58,7 +67,8 @@ Load `${CLAUDE_SKILL_DIR}/references/workflows.md` for the base workflow templat
 
 Before responding, verify:
 
-- `workflow_dispatch` is present alongside the primary trigger.
+- `workflow_dispatch` is present alongside the primary trigger, and absent from a commit-back workflow.
+- The top-level `permissions` reads `contents: read`, and every write scope sits on a job.
 - All actions pinned to major version tags, no `@latest` or `@main`.
 - A new pipeline folds static, unit, and build into one job, and a gate a run log put past two minutes gives them no `needs` so they run in parallel.
 - Every name in a `needs` matches a job declared in the same file. E2E names the artifact producer, release and deploy name E2E.

package/claude/skills/ci-workflow/references/workflows.md

@@ -12,12 +12,15 @@ on:
     branches: [main]
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   checks:
     name: '🛡️ Checks'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
@@ -25,7 +28,7 @@ jobs:
       - run: bun run check
       - run: bun run test
       - run: bun run build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: build-output
           path: dist/
@@ -35,17 +38,17 @@ jobs:
     needs: checks
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
       - run: bun install --frozen-lockfile
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: build-output
           path: dist/
       - run: bun run test:e2e
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         if: failure()
         with:
           name: e2e-results
@@ -63,7 +66,7 @@ jobs:
     name: '🛡️ Static Checks'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
@@ -74,7 +77,7 @@ jobs:
     name: '🧪 Unit Tests'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
@@ -85,13 +88,13 @@ jobs:
     name: '📦 Build Check'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
       - run: bun install --frozen-lockfile
       - run: bun run build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: build-output
           path: dist/

package/claude/skills/code-craft/references/adopted.md

@@ -5,48 +5,86 @@ description: Which external software design sources this skill adopted, which 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.
+External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
-## Adopted
+## Adopted from the default shelf
 
-### From the default shelf
+### What to look for in a code review
 
-**What to look for in a code review.** [Google's engineering practices](https://google.github.io/eng-practices/review/reviewer/looking-for.html): solve the problem known to need solving now rather than one speculated about, and read "too complex" as "cannot be understood quickly by a reader". Adopted as the writing-time half of the same judgment, behind the change test and the ban on building for an unnamed case. The review procedure itself stays with `review-craft`.
+[Google's engineering practices](https://google.github.io/eng-practices/review/reviewer/looking-for.html) say to solve the problem known to need solving now rather than one speculated about, and to read "too complex" as "cannot be understood quickly by a reader".
 
-### Depth and decomposition
+Adopted as the writing-time half of the same judgment, behind the change test and the ban on building for an unnamed case. The review procedure itself stays with `review-craft`.
 
-**Information hiding.** David Parnas, [On the Criteria To Be Used in Decomposing Systems into Modules](https://dl.acm.org/doi/10.1145/361598.361623), 1972: split a system by the design decision each module hides, not by the steps of processing. Adopted as the module-split rule under depth.
+## Adopted for depth and decomposition
 
-**Deep modules.** John Ousterhout, [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php): complexity is what makes a system hard to change, and a module is worth having when its interface is much simpler than its implementation. Adopted as the opening of the depth group and the pass-through flag. `api-design` declined depth as behind its boundary, so it lands here.
+### Information hiding
 
-**The APoSD and Clean Code exchange.** [John Ousterhout and Robert Martin's discussion](https://github.com/johnousterhout/aposd-vs-clean-code): Martin argues for very small methods and Ousterhout for fewer, deeper ones a reader need not stitch together. Adopted as the third tension, stated as when each side wins rather than as a verdict, plus the depth bullet preferring one function a reader follows top to bottom.
+David Parnas, [On the Criteria To Be Used in Decomposing Systems into Modules](https://dl.acm.org/doi/10.1145/361598.361623), 1972, splits a system by the design decision each module hides, not by the steps of processing. Adopted as the module-split rule under depth.
 
-**Reducing coupling.** Martin Fowler, [Reducing Coupling](https://martinfowler.com/ieeeSoftware/coupling.pdf), IEEE Software, 2001: a change in one module should not ripple into others. Adopted behind the rule that a decision stays in one unit and the red flag on a third file opened to adjust one rule.
+### Deep modules
 
-### Tensions
+John Ousterhout, [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php), holds that complexity is what makes a system hard to change, and a module is worth having when its interface is much simpler than its implementation.
 
-**DRY as knowledge.** Andy Hunt and Dave Thomas, [Orthogonality and the DRY Principle](https://www.artima.com/articles/orthogonality-and-the-dry-principle): every piece of knowledge has one authoritative representation, which is broader than and different from avoiding repeated text. Adopted as the first tension, with its other side stated: two blocks that only look alike and change for different reasons stay apart.
+Adopted as the opening of the depth group and the pass-through flag. `api-design` declined depth as behind its boundary, so it lands here.
 
-**Yagni and its carve-out.** Ron Jeffries, [You're NOT Gonna Need It](https://ronjeffries.com/xprog/articles/practices/pracnotneed/), and Martin Fowler, [Yagni](https://martinfowler.com/bliki/Yagni.html): build no capability for a presumptive feature, though Yagni "does not apply to effort to make the software easier to modify". Adopted as the second tension, with Fowler's carve-out as the side that wins for a refactor, a test, or a parameter serving the asked-for code.
+### The design book exchange
 
-**Beck's design rules.** Martin Fowler, [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRules.html): passes the tests, reveals intention, no duplication, fewest elements, in that priority. Adopted for the ordering behind the closing checklist, where fewest elements stops the pattern table's indirection once the rules above it are met.
+In [John Ousterhout and Robert Martin's discussion](https://github.com/johnousterhout/aposd-vs-clean-code), Martin argues for very small methods and Ousterhout for fewer, deeper ones a reader need not stitch together.
 
-### Patterns and inputs
+Adopted as the third tension, stated as when each side wins rather than as a verdict, plus the depth bullet preferring one function a reader follows top to bottom.
 
-**Smells and patterns.** [Refactoring Guru's code smells](https://refactoring.guru/refactoring/smells) and [design patterns](https://refactoring.guru/design-patterns) catalogs. Adopted only for the wrong case of six common patterns and the smells a red flag can see, such as speculative generality and a lazy class. Each pattern's definition is left to the model.
+### Reducing coupling
 
-**Injection.** Martin Fowler, [Inversion of Control Containers and the Dependency Injection pattern](https://martinfowler.com/articles/injection.html): hand a component what it depends on rather than letting it find it. Adopted as the hidden-inputs rule for the clock, the environment, randomness, and globals, without any container.
+Martin Fowler, [Reducing Coupling](https://martinfowler.com/ieeeSoftware/coupling.pdf), IEEE Software, 2001, holds that a change in one module should not ripple into others. Adopted behind the rule that a decision stays in one unit and the red flag on a third file opened to adjust one rule.
 
-### Agent failure modes
+## Adopted for the tensions
 
-Birgitta Böckeler, [The role of developer skills in agentic coding](https://martinfowler.com/articles/exploring-gen-ai/13-role-of-developer-skills.html), 2025, and [How far can we push AI autonomy in code generation?](https://martinfowler.com/articles/pushing-ai-autonomy.html), 2025. Together they record a lack of reuse and modularity, overeagerness that builds unrequested features, assumptions filled in for silent requirements, and brute-force fixes. Adopted as the closing concern group, worded as checks on the session's own diff, and as the source each excuse row and red flag traces to.
+### DRY as knowledge
+
+Andy Hunt and Dave Thomas, [Orthogonality and the DRY Principle](https://www.artima.com/articles/orthogonality-and-the-dry-principle), give every piece of knowledge one authoritative representation, which is broader than and different from avoiding repeated text.
+
+Adopted as the first tension, with its other side stated. Two blocks that only look alike and change for different reasons stay apart.
+
+### Yagni and its carve-out
+
+Ron Jeffries, [You're NOT Gonna Need It](https://ronjeffries.com/xprog/articles/practices/pracnotneed/), and Martin Fowler, [Yagni](https://martinfowler.com/bliki/Yagni.html), build no capability for a presumptive feature, though Yagni "does not apply to effort to make the software easier to modify".
+
+Adopted as the second tension, with Fowler's carve-out as the side that wins for a refactor, a test, or a parameter serving the asked-for code.
+
+### Beck's design rules
+
+Martin Fowler, [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRules.html), orders the rules as passes the tests, reveals intention, no duplication, fewest elements. Adopted for the ordering behind the closing checklist, where fewest elements stops the pattern table's indirection once the rules above it are met.
+
+## Adopted for patterns and inputs
+
+### Smells and patterns
+
+[Refactoring Guru's code smells](https://refactoring.guru/refactoring/smells) and [design patterns](https://refactoring.guru/design-patterns) catalogs. Adopted only for the wrong case of six common patterns and the smells a red flag can see, such as speculative generality and a lazy class. Each pattern's definition is left to the model.
+
+### Injection
+
+Martin Fowler, [Inversion of Control Containers and the Dependency Injection pattern](https://martinfowler.com/articles/injection.html), hands a component what it depends on rather than letting it find it. Adopted as the hidden-inputs rule for the clock, the environment, randomness, and globals, without any container.
+
+## Adopted for agent failure modes
+
+Birgitta Böckeler, [The role of developer skills in agentic coding](https://martinfowler.com/articles/exploring-gen-ai/13-role-of-developer-skills.html), 2025, and [How far can we push AI autonomy in code generation?](https://martinfowler.com/articles/pushing-ai-autonomy.html), 2025.
+
+- Together they record a lack of reuse and modularity, overeagerness that builds unrequested features, assumptions filled in for silent requirements, and brute-force fixes
+- Adopted as the closing concern group, worded as checks on the session's own diff
+- They are the source each excuse row and red flag traces to
 
 ## Declined
 
+Each item below was read and left out, with the reason it changes nothing a session does.
+
+### Definitions and language pages
+
 **Definitions a model already holds.** What coupling, cohesion, or a given pattern is. Declined because a definition changes no behavior a session would otherwise get wrong.
 
-**Language-specific pages.** Every page tied to one language, its type system, or its runtime. Declined because the body has to hold on every code stack, and the one language note the pattern table carried became "a plain function often replaces the class".
+**Language-specific pages.** Every page tied to one language, its type system, or its runtime. Declined because the body holds on every code stack, so the one language note the pattern table carried became "a plain function often replaces the class".
+
+### Architecture and books
 
 **Layering and hexagonal architecture.** Beyond the one bullet kept, keeping business rules free of transport and storage and skipping ports and adapters for a thin application. Declined because where layers sit is a structure call made once, not a writing-time one.
 
-**The Gang of Four and The Pragmatic Programmer as books.** Gamma, Helm, Johnson, and Vlissides, Design Patterns, 1994, and Hunt and Thomas, The Pragmatic Programmer, 1999. Declined as cited sources because neither is open to read at a link, so a reader could not check the passage a rule rests on. The articles above carry the same positions where a reader can open them.
+**The Gang of Four and The Pragmatic Programmer as books.** Gamma, Helm, Johnson, and Vlissides, Design Patterns, 1994, and Hunt and Thomas, The Pragmatic Programmer, 1999, are declined as cited sources because neither is open to read at a link. The articles above carry the same positions where a reader can open them.

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

@@ -5,36 +5,69 @@ description: Which external layout patterns this skill adopted, which it decline
 
 # 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.
+External sources were read and filtered rather than imported. This file is the record, and a later session extending the skill adds to it rather than re-arguing an item settled here.
 
-## Adopted
+## Adopted for placing files
 
-### Placing files
+### Group what changes together
 
-**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?
+Robert Martin's restatement of the single responsibility principle reads "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)).
 
-**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.
+It gives "split by role" a test a planner can apply to a folder, which is whether these files would change together.
 
-**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.
+### Name folders for the domain rather than the framework
 
-**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`.
+Martin's [Screaming Architecture](https://blog.cleancoder.com/uncle-bob/2011/09/30/Screaming-Architecture.html) argues the top level should tell readers "about the system, not about the frameworks you used in your system". It is the root of naming a folder for what it holds rather than its technical kind.
 
-**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.
+### Feature folders, no cross-feature imports, one-way flow
 
-**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.
+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)).
 
-### Closing the body
+Adopted as the direction rule in the body and the feature-folder guidance in `frontend.md`, without the mandate.
 
-**Excuses, red flags, and a closing checklist.** From `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md): Common Rationalizations, Red Flags, and Verification. Adopted as the three closing sections every practice skill carries. Each excuse row rebuts a reason a flat folder stayed flat in the target this skill's requirement measures, rather than an objection nobody raised.
+### 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.
+
+## Adopted for closing the body
+
+From `addyosmani/agent-skills@2686b620`, [`docs/skill-anatomy.md`](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/docs/skill-anatomy.md), the Common Rationalizations, Red Flags, and Verification sections.
+
+- Adopted as the three closing sections every practice skill carries
+- Each excuse row rebuts a reason a flat folder stayed flat in the target this skill's requirement measures, rather than an objection nobody raised
 
 ## 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.
+Each item below was read and left out, with the condition that would reopen it where one exists.
+
+### Deep modules and seams
+
+Matt Pocock's [codebase-design](https://github.com/mattpocock/skills/blob/main/skills/engineering/codebase-design/SKILL.md) skill covers a lot of behavior behind a small interface placed at a clean seam. It answers where a boundary goes in code, not where a file goes on disk.
+
+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 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 stack rule mandating the tree still loads beside this skill in a project that installs it. 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.
+### Numbers, fields, and the worker
 
-**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.
+Three smaller items were declined for the reason each states.
 
-**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.
+- **A numeric file ceiling.** No source gives a reliable number, and a count fails sixty files of one role that read fine flat. The body triggers on a second role, with about ten files a prompt to look.
+- **A required placement field in the plan format.** It would touch every plan, even ones creating nothing, so the body asks a reason per new path. Revisit only if plans 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

@@ -10,7 +10,8 @@ Read this before placing a new component, hook, helper, route, or fixture in an
 ## 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.
+- 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.
 
@@ -23,13 +24,15 @@ Read this before placing a new component, hook, helper, route, or fixture in an
 ## 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)).
+- A framework calling itself unopinionated about organization leaves the strategy to the project ([Next.js project structure](https://nextjs.org/docs/app/getting-started/project-structure))
+- Pick one of code outside the routes folder, top-level folders inside it, or a split by feature or route, and "be consistent across the project"
 - 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/)).
+- Put a hook or helper one feature uses inside that feature ([Robin Wieruch](https://www.robinwieruch.de/react-folder-structure/))
+- Promote it to a shared `hooks/` or `lib/` folder when a second feature needs it, in the change that adds the second consumer
 - 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.
 
@@ -40,4 +43,8 @@ Read this before placing a new component, hook, helper, route, or fixture in an
 
 ## 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.
+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 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

@@ -18,11 +18,13 @@ Read this before placing a new test file or a file a test imports. Which layer t
 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.
+- Put fixtures in a module extending the runner's base test, merged into one fixtures module the specs import, so a new spec finds its setup in one place ([Playwright fixtures](https://playwright.dev/docs/test-fixtures))
 - 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.
+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/context-fold/references/classify.md

@@ -30,7 +30,9 @@ Each finding carries `file`, a `verdict` of `KEEP`, `REPLACE`, `HISTORY`, or `MO
 
 ## Scope
 
-Answer every non-`KEEP` finding the verb returns, not only the files Step 3 wrote this run. A branch carrying earlier commits from a prior session has doc edits the fold is equally responsible for, and the verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none, so there is no narrower check to add here.
+Answer every non-`KEEP` finding the verb returns, not only the files Step 3 wrote this run, since a branch carrying a prior session's commits has doc edits the fold is equally responsible for.
+
+The verb's own extraction already scopes to canonical doc types and reports nothing when the range carries none, so there is no narrower check to add here.
 
 ## Applying a finding
 
@@ -40,7 +42,7 @@ Locate the finding by its `quote` in the file's current content. The quote is of
   - `REPLACE`: rewrite the sentence or bullet carrying the quote in place with the fact that now stands, per Step 3's rewrite-in-place rule. State what is current and drop what the quote restated, in the one edit.
   - `HISTORY`: rewrite the sentence or bullet carrying the quote to drop the narration and keep any current fact the same clause states. The quote narrates how the fact arrived rather than stating the fact, which a canonical doc excludes regardless of what wrote it, and a literal cut of the fragment alone would leave the rest of the clause grammatically stranded.
   - `MOVE`: do not cut. The verdict means correct content sitting on the wrong surface, such as a rule written into a context entry that belongs in a path-scoped rule, and only the model layer returns it. Cutting would delete content a fold with no model configured would never have flagged at all. Report the finding instead, naming the surface the `reason` names as where the content belongs, and leave the file unedited.
-- **Found more than once, or not found at all.** Report that the finding could not be located rather than guessing which occurrence or rewriting nothing silently. A model verdict paraphrasing the quote it read is the ordinary way this happens.
+- **Found more than once, or not found at all.** Report it as not located rather than guessing an occurrence or silently rewriting nothing. A model paraphrasing its quote is the usual cause.
 
 Run the classifier once per fold. Do not re-run it after applying a finding to check the edit, since a second pass over what this step wrote is the loop the verb's own reference already warns against.
 
@@ -50,25 +52,18 @@ Keep a non-`KEEP` finding without applying it only when the quote is itself the
 
 ## When the verb is absent or refused
 
-The verb ships with the CLI and this skill ships with the plugin, so a target holding an older installed binary carries no `context classify` subcommand. Report:
-
-`⚠ Classify: canon context classify not available on the installed binary. Skipped.`
-
-and continue. Never read a missing subcommand as a clean pass, which would report a run that never checked anything as one that found nothing.
+The verb ships with the CLI and this skill ships with the plugin, so a target holding an older installed binary carries no `context classify` subcommand. Never read a missing subcommand as a clean pass, which would report a run that never checked anything as one that found nothing.
 
-A refused range reports the same way, naming the verb's own message:
-
-`⚠ Classify: <message>`
+| Case               | Report, then continue                                                                |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| Subcommand missing | `⚠ Classify: canon context classify not available on the installed binary. Skipped.` |
+| Range refused      | `⚠ Classify: <message>`, naming the verb's own message                               |
 
 Neither case stops the fold. This step checks what the fold wrote, and a check that cannot run is not a reason to leave the fold's own output unshipped.
 
 ## Report
 
-One line naming what ran:
-
-`✅ Classify: <n> findings, regex ran, model <modelLayer>`
-
-Then one line per non-`KEEP` finding:
+Print one line naming what ran, `✅ Classify: <n> findings, regex ran, model <modelLayer>`, then one line per non-`KEEP` finding:
 
 - `✏ Rewrote: <file>, "<quote>" (<reason>)`
 - `✂ Cut: <file>, "<quote>" (<reason>)`

package/claude/skills/context-fold/references/completion-report.md

@@ -7,16 +7,18 @@ description: The lines context-fold prints once every step has run, being one pe
 
 The close of `context-fold`. The session reads this file once every step has run, before printing anything.
 
-Output one line per file updated:
+## Lines
 
-`✅ Updated: <path written>`
+| When                                                 | Line                                                                                        |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Per file updated                                     | `✅ Updated: <path written>`                                                                |
+| Step 2 noted a requirements change                   | `↪ Direction changed this session: run document-health on canon/REQUIREMENTS.md`            |
+| Per audit finding Step 4 reported                    | `⚠ Audit:` in the shape the body gives                                                      |
+| Step 4's classify half applied or reported a finding | The exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives under its Report section |
+| No file updated and Step 4 reported nothing          | `✅ No changes needed.`                                                                     |
 
-When Step 2 noted a requirements change: `↪ Direction changed this session: run document-health on canon/REQUIREMENTS.md`
+Do not shorten or paraphrase the audit and classify lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
 
-Step 4 adds one `⚠ Audit:` line per audit finding it reported, in the shape the body gives. Its classify half adds its own lines when it applied or reported a finding, in the exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives them under its own Report section. Do not shorten or paraphrase those lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
+## Suppressing the closing line
 
-If no files were updated and Step 4 reported nothing, output:
-
-`✅ No changes needed.`
-
-Suppress that line when Step 2 already reported no context updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.
+Suppress `✅ No changes needed.` when Step 2 already reported no context updates. That report closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.

package/claude/skills/context-fold/references/context-refresh.md

@@ -5,19 +5,26 @@ description: How context-fold Step 3 folds diff-scoped rewrites into canon/conte
 
 # Refresh context entries
 
-Step 3 of `context-fold`, reached in order once `canon/context/index.md` lists at least one entry.
-
-The diff carries what the repository changed, and this step rewrites against it.
+Step 3 of `context-fold`, reached in order once `canon/context/index.md` lists at least one entry. The diff carries what the repository changed, and this step rewrites against it.
 
 When the baseline is unusable, scope this step to the working tree and untracked files, and skip it only when that set is empty, reporting `⚠ No diff to scope against. Skipped the context refresh.`
 
-Reuse the diff from the baseline above, names and content both. For each domain listed in `canon/context/index.md`, read its own entry: a flat `canon/context/<domain>.md`, or, for a domain split into a folder, its `canon/context/<domain>/index.md` and every sibling file that index links. Follow the index rather than globbing the folder, since a folder can hold a file the index does not list yet.
+## Reading each entry
+
+Reuse the diff from the baseline above, names and content both. For each domain listed in `canon/context/index.md`, read its own entry, following the index rather than globbing the folder, since a folder can hold a file the index does not list yet.
+
+- A flat domain reads `canon/context/<domain>.md`
+- A domain split into a folder reads its `canon/context/<domain>/index.md` and every sibling file that index links
+
+### What to rewrite
+
+An entry is relevant only when the diff touches what it states, and the rewrite stays inside the part the trigger names.
 
 - Treat an entry as relevant only when the diff adds, moves, or removes a folder its Layout lists, makes a folder's bullet untrue, or changes a trap it names
 - For each relevant entry, rewrite only the H3 or the gotcha the trigger names, and leave unrelated sections alone
 - Never rewrite a split domain's own `index.md`, which a regen overwrites, and rewrite the sibling file the section lives in instead
 - Edit the bullet that went untrue in place and never append one beside it, the same rule the body states.
-- Write a reference to another entry as the path that entry sits at, rather than as its bare filename. `${CLAUDE_SKILL_DIR}/references/context.md` states the form, and a bare name strands the reference once a domain splits into subfolders.
+- Write a reference to another entry as the path that entry sits at, per `${CLAUDE_SKILL_DIR}/references/context.md`, since a bare filename strands it once a domain splits into subfolders
 
 ## When the diff removes a capability
 
@@ -25,15 +32,25 @@ The mapping above is scoped by file, and a removal invalidates claims that mappi
 
 Grep the tree for the name that went, rather than for the paths the diff carries. A capability removed by name is cited by that name, which reaches a file the diff never touched.
 
-- An entry this run already rewrote is read whole before it is left. A refresh that updates the top and leaves a contradicting claim below reads worse than an untouched entry, because the current opening lends authority to the stale remainder. This is the one case that overrides "do not touch unrelated sections", and it overrides it only inside an entry the run edited anyway.
-- A claim comparing two surfaces is checked even where its file is outside the diff. Such a claim holds only while both surfaces do, so moving one inverts it with nobody editing the file it sits in.
+- Read an entry this run rewrote whole before leaving it. An updated top over a contradicting claim below reads worse than an untouched entry, since the opening lends authority to the stale rest.
+- That is the one case overriding "do not touch unrelated sections", and only inside an entry the run edited anyway
+- Check a claim comparing two surfaces even where its file is outside the diff. It holds only while both surfaces do, so moving one inverts it with nobody editing its file.
 
 Report each hit as an ordinary rewrite.
 
-Create a new entry only for a domain `canon/context/index.md` already lists but carries no file for, following `${CLAUDE_SKILL_DIR}/references/context.md` for its shape. Before treating a domain as carrying no file, confirm it holds no entry under either spelling, `canon/context/<domain>.md` or `canon/context/<domain>/index.md`, since a domain already split into a folder still passes a check that only looked for the flat file. A row in the catalog is the deliberate decision, taken by whoever added it. This step only fills in what that decision left open, and only until the next `canon indexes regen` pass, which rebuilds the catalog from each entry's own frontmatter plus every sibling's and drops a row whose file still does not exist. Create the file before that regen runs, or the row this bar exists to fill in is gone. A domain the catalog does not list at all is a different case: report it and stop, rather than creating an entry or a catalog row for it.
+## Creating an entry
+
+Create a new entry only for a domain `canon/context/index.md` already lists but carries no file for, following `${CLAUDE_SKILL_DIR}/references/context.md` for its shape. A row in the catalog is the deliberate decision, taken by whoever added it, and this step only fills in what that decision left open.
+
+- Confirm the domain holds no entry under either spelling, `canon/context/<domain>.md` or `canon/context/<domain>/index.md`, since a split domain passes a check for the flat file alone
+- The next `canon indexes regen` rebuilds the catalog from each entry's frontmatter plus every sibling's, dropping a row whose file does not exist. Create the file before it runs.
+- A domain the catalog does not list at all is a different case. Report it and stop, rather than creating an entry or a catalog row for it.
+
+## Writing and reporting
 
 Write each updated entry immediately. Output one line per file, naming the path this run actually wrote rather than always the flat template:
 
-`✅ Context: canon/context/<domain>.md` for a flat entry, or `✅ Context: canon/context/<domain>/<sub-area>.md` for the sibling file a nested edit landed in
+- `✅ Context: canon/context/<domain>.md` for a flat entry
+- `✅ Context: canon/context/<domain>/<sub-area>.md` for the sibling file a nested edit landed in
 
 The base lint-staged config runs `canon indexes regen` on every committed `*.md`, so `canon/context/index.md` refreshes automatically on commit. No manual step needed.

package/claude/skills/context-fold/references/unusable-baseline.md

@@ -14,8 +14,10 @@ The baseline is unusable in two cases:
 
 An unusable baseline costs only the committed half. `git diff <base> HEAD` is empty by definition once the base equals HEAD, while `git diff HEAD` and `git ls-files --others --exclude-standard` still report uncommitted and untracked work at correct scope.
 
-**Step 3 keeps the scoped set.** Run it on the working tree and untracked files alone, and skip only when that set comes out empty, reporting the warning its own reference names.
+## Step 3 keeps the scoped set
 
-Never substitute the whole tree for a missing baseline, and do not widen to `git log -p -1` for coverage. On a fresh `git init` project the last commit is the scaffold commit, so that read is the whole tree by another route, and Step 3 writes, so the same set rewrites every context entry that tree touches. `task-complete` takes the widened read for its marking step, which only reads and matches conservatively against outcomes already on the board.
+Run Step 3 on the working tree and untracked files alone, and skip only when that set comes out empty, reporting the warning its own reference names. Widening what a step reads is safe, and widening what a step writes is not.
 
-Widening what a step reads is safe. Widening what a step writes is not.
+- Never substitute the whole tree for a missing baseline, and do not widen to `git log -p -1` for coverage
+- On a fresh `git init` project the last commit is the scaffold, so that read is the whole tree by another route. Step 3 writes, so it would rewrite every context entry that tree touches.
+- `task-complete` takes the widened read for its marking step, which only reads and matches conservatively against outcomes already on the board

package/claude/skills/create-rule/REQUIREMENT.md

@@ -18,6 +18,11 @@ The subdir gets picked by feel, so a UI copy rule lands in the always-on folder
 - Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
 - Take a slug no rule in the chosen project subdir uses and that equals no subdir name
 - Read the rule standard before writing the body
+- Hold the body to the rule standard's shape limits on words, bullets, sections, and bullet length
+- Apply the content test, leaving out what Claude already knows, what the toolchain enforces, and what changes often
+- Check the installed skills for one already covering the topic and point the rule at it, skipping the check when none are listed
+- Run every written bullet through the checklist and fix what fails before reporting
+- Tell the user to cite a source in the commit that adds a rule claiming outside practice
 - Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
 - Preview the resolved path, subdir, slug, and frontmatter, then write without pausing
 - Say when the rule loads, since path-scoped and always-on rules behave differently

package/claude/skills/create-rule/SKILL.md

@@ -22,6 +22,7 @@ Resolve both from the request, and ask only for what is missing. Attach a propos
 
 - What the rule enforces: one topic, phrased as a standard (`<topic> conventions`).
 - Scope: a path glob relative to the project root (`<dir>/**/*.<ext>`) for a path-scoped rule, or always-on when the rule states a global principle with no file scope.
+- An installed skill already covering the topic, found per `### Checking the installed skills` in `${CLAUDE_SKILL_DIR}/references/rule.md`. Point the rule at it rather than restating it.
 
 ## Step 2: resolve the subdir
 
@@ -74,6 +75,14 @@ paths:
 
 Title casing is sentence case, with proper nouns keeping their own casing (`# TypeScript standards`). `${CLAUDE_SKILL_DIR}/references/rule.md` owns the rest of the body shape.
 
+## Step 5: check each bullet
+
+Read `${CLAUDE_SKILL_DIR}/references/checklist.md` and run every bullet of the written rule through it, along with the shape limits and the content test in `rule.md`.
+
+- Rewrite a bullet marked revise and cut one marked drop, then run the checklist again over what changed
+- Run `canon gov audit .claude/rules/project/<subdir>/<slug>.md` and fix every finding it reports, since the shape limits are counts the verb takes rather than a judgment
+- Report the verdict counts with the path, and name any bullet kept against a criterion with the reason
+
 ## After writing
 
-Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session.
+Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session. When a bullet claims outside practice, tell them to cite its source in the commit that adds the rule.