@erclx/canon 5.40.0 → 5.42.0

package/claude/skills/build-in-slices/references/adopted.md

@@ -5,40 +5,54 @@ description: Which external sources on incremental building this skill adopted,
 
 # 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
+### Small changes
 
-**Small changes.** [Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html), from Google's engineering practices: a change should be self-contained and address one thing, a refactor goes in a change apart from the feature that needs it, and a test goes in the same change as the code it covers. Adopted as the rule that each commit carries one logical change, the refactor excuse row, and the rule that a slice's test never lands after its code.
+[Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html), from Google's engineering practices, keeps a change self-contained and about one thing, puts a refactor in a change apart from the feature needing it, and puts a test in the same change as its code.
 
-### The increment cycle
+Adopted as the rule that each commit carries one logical change, the refactor excuse row, and the rule that a slice's test never lands after its code.
 
-**Incremental implementation.** Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, [`skills/incremental-implementation/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md). Adopted from it:
+## Adopted for the increment cycle
 
-- The increment cycle of implement, test, verify, commit, and next slice, with the commit routed through `git-commit` rather than a message format of its own.
-- Vertical, risk-first, and contract-first slicing, stated as rules for choosing the next slice rather than as worked examples tied to one stack.
-- Rule 1, one thing at a time, as one logical change per commit.
-- Rule 2, keep it compilable, as a build left passing at every commit.
+Addy Osmani's `agent-skills`, pinned at addyosmani/agent-skills@2686b620, [`skills/incremental-implementation/SKILL.md`](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md), supplies the cycle and most of the rules.
 
-#### Rollback and the notes
+### The cycle and its rules
 
-- Rule 5, rollback-friendly, as the group on keeping each commit safe to revert and the rule against deleting and replacing in one commit.
-- The "noticed but not touching" list from its scope section, routed to the open task's findings or the handover rather than offered as new tasks, since a worker may not add a row to the board.
-- The note against re-running a command on unchanged code, scoped to a session's own repeats so it never reads as permission to skip a chain's verify step.
-- The rationalizations and red flags that carry across stacks, reworded as reasons this toolkit's sessions give, with one row added for the ship step committing everything anyway.
+The increment cycle of implement, test, verify, commit, and next slice is adopted with the commit routed through `git-commit` rather than a message format of its own.
+
+- Vertical, risk-first, and contract-first slicing, stated as rules for choosing the next slice rather than as worked examples tied to one stack
+- Rule 1, one thing at a time, as one logical change per commit
+- Rule 2, keep it compilable, as a build left passing at every commit
+
+### Rollback and the notes
+
+Rule 5, rollback-friendly, is the group on keeping each commit safe to revert and the rule against deleting and replacing in one commit.
+
+- The "noticed but not touching" list from its scope section, routed to the open task's findings or the handover, since a worker may not add a row to the board
+- The note against re-running a command on unchanged code, scoped to a session's own repeats so it never reads as permission to skip a chain's verify step
+- The rationalizations and red flags that carry across stacks, reworded as this toolkit's sessions give them, plus one row for the ship step committing everything anyway
 
 ## Declined
 
-**Rule 0, simplicity first, and the abstraction red flags.** Declined because `code-craft` owns when an abstraction earns its place and when to write the plainest code that passes. Restating it here would put two owners on one rule.
+Each item below was read and left out, with the reason it changes nothing a session does here.
+
+### Rules another skill owns
+
+**Rule 0, simplicity first, and the abstraction red flags.** `code-craft` owns when an abstraction earns its place and when to write the plainest code that passes, and restating it here would put two owners on one rule.
+
+**Rule 4, safe defaults.** A conservative default is a concern of the interface a caller sees, which belongs to the skill shaping that interface rather than to how the work is sequenced.
+
+### Rules this skill already covers
 
-**The rest of its scope section.** Declined as a scope call this skill makes: its slices already keep to the plan, and minimal edits, no unrequested features, and edits limited to what the user named restate that in different words. Only the noticed list was new.
+**The rest of its scope section.** Its slices already keep to the plan, and minimal edits, no unrequested features, and edits limited to what the user named restate that in different words. Only the noticed list was new.
 
-**Rule 3, feature flags for incomplete features.** Declined because the slices of one branch merge together as one pull request rather than reaching trunk one at a time, so nothing incomplete is exposed between them.
+**Rule 3, feature flags for incomplete features.** The slices of one branch merge together as one pull request rather than reaching trunk one at a time, so nothing incomplete is exposed between them.
 
-**Rule 4, safe defaults.** Declined because a conservative default is a concern of the interface a caller sees, which belongs to the skill shaping that interface rather than to how the work is sequenced.
+### Numbers and commands tied to one stack
 
-**The 100-line threshold.** Its red flag of more than 100 lines written without running tests. Declined because a line count means something different on every stack and a session cannot carry it from one to the next. The red flag is stated as a check instead: a slice implemented whose tests have not run.
+**The 100-line threshold.** Its red flag of more than 100 lines written without running tests means something different on every stack. The red flag is stated as a check instead, being a slice implemented whose tests have not run.
 
-**Its per-stack command lists and its definition-of-done pointer.** Declined because the project's own `CLAUDE.md` names its verify commands, and a body naming runners stops holding on the next stack.
+**Its per-stack command lists and its definition-of-done pointer.** The project's own `CLAUDE.md` names its verify commands, and a body naming runners stops holding on the next stack.

package/claude/skills/canvas-board/references/canvas.md

@@ -25,7 +25,8 @@ The folder is gitignored, so nothing in a repository checks its shape and nothin
 
 Governs the canvas content under `.canon/canvas/`: page folder names, frame files, the `layout.json` shape, how tokens reach a frame, and what a frame must not assume about where it renders.
 
-Also governs the house style of an explanation frame, being a diagram, a board of notes, or a comparison. A mockup of the project's own interface is not an explanation frame, and it follows the project's design document for type, color, and layout.
+- Also governs the house style of an explanation frame, being a diagram, a board of notes, or a comparison
+- A mockup of the project's own interface is not an explanation frame, and follows the project's design document for type, color, and layout
 
 Does not govern:
 
@@ -61,6 +62,8 @@ A canvas failing these is non-conforming even when it satisfies every shape rule
 
 ### Content and edits
 
+A frame is the only copy of its markup, so it carries everything it needs.
+
 - Keep a frame self-contained. Inline its own styles and scripts, or link a file inside the same page folder, since a frame is served from its page and nothing outside the canvas resolves.
 - Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
 - Edit a frame by rewriting its file. The file is the frame, and nothing else holds a copy of its markup.
@@ -76,9 +79,12 @@ Applies to an explanation frame only. A mockup of the project's interface render
 
 ### Colors, faces, and fit
 
-- Take colors from the project's custom properties. A frame that defines colors of its own sets the dark values on `:root` and the light ones under `[data-theme="light"]`, since the shell sets `data-theme` on each frame's root.
-- Name only the faces the canvas serves into every frame: `Geist Variable` for text, `Noto Sans Mono` for code, and `Excalifont` for a hand-drawn look. They render the same in a capture and in any browser, so a height fitted against them holds.
-- Make each box tall enough to show all its content, with no scrollbar and no clipped line. Run `canon canvas fit <page>/<frame>` rather than estimating, since it measures the content in the capture browser and sets the height.
+Take colors from the project's custom properties. A frame defining colors of its own sets the dark values on `:root` and the light ones under `[data-theme="light"]`, since the shell sets `data-theme` on each frame's root.
+
+- Name only the faces the canvas serves into every frame, being `Geist Variable` for text, `Noto Sans Mono` for code, and `Excalifont` for a hand-drawn look
+- Those render the same in a capture and in any browser, so a height fitted against them holds
+- Make each box tall enough to show all its content, with no scrollbar and no clipped line
+- Run `canon canvas fit <page>/<frame>` rather than estimating, since it measures the content in the capture browser and sets the height
 - Read frames left to right in reading order. Let `frame add` place each frame after the last with the standard gap, and move one only when the operator asks for a position.
 
 ## Layout
@@ -89,6 +95,8 @@ Applies to an explanation frame only. A mockup of the project's interface render
 
 ### Missing boxes and writes
 
+The layout file is shared state, so a write never discards a box another writer or reader holds.
+
 - Leave a frame out of the layout only when its position does not matter yet. A reader places an unnamed frame in a row after the others, at the default size of 1440 by 900.
 - Never write the file while a writer holds its lock, which is the same name with `.lock` appended. Two writers each replacing the whole file lose one of the two edits.
 - Treat a layout that does not parse as a defect to repair, never as an empty one to overwrite. Writing over it erases every box it held.
@@ -107,7 +115,8 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 ## Tokens
 
 - Expect the token stylesheet first in every frame's `head` when it is served, ahead of anything the frame links. A stylesheet the frame links itself still wins the cascade.
-- Read where the tokens come from in this order: the canvas tool's own module inside its own checkout, else the project's installed base stylesheet plus anything in its project override folder, else none. A canvas with no token source renders unstyled and says so.
+- Read the tokens from the canvas tool's own module inside its own checkout, else the project's installed base stylesheet plus its project override folder, else none
+- A canvas with no token source renders unstyled and says so
 - Never paste the token stylesheet into a frame. The injected copy follows the project, and a pasted one stops following it the moment it is written.
 
 ## What a frame must not assume
@@ -118,7 +127,9 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 
 ### Font, source, and checkout
 
-- Do not assume a default font. Set `font-family` with a served face first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines. A frame naming a machine family such as `DejaVu Sans` renders at another height in another browser, which `canon canvas fit` reports.
+Do not assume a default font. Set `font-family` with a served face first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines.
+
+- A frame naming a machine family such as `DejaVu Sans` renders at another height in another browser, which `canon canvas fit` reports
 - Do not assume the frame is the source. A picked direction is carried into the project's design document or a plan, and the operator clears the frame once it has been carried.
 - Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
 

package/claude/skills/canvas-board/references/design.md

@@ -30,8 +30,8 @@ Does not govern:
 
 ## Two shapes
 
-- **An intent record** is the shape a project writes by hand. It carries rules, omissions, and each role's intent, and its lead names the stylesheet the values live in. It carries no value, since a hand-typed copy of the stylesheet drifts from it.
-- **A values record** is generated from a token source and carries the value tables beside the rules. It is never edited by hand, and its lead names the module it is rendered from. The toolkit's own record is one.
+- **An intent record** is the shape a project writes by hand, carrying rules, omissions, and each role's intent, with a lead naming the stylesheet. It carries no value, since a hand-typed copy drifts.
+- **A values record** is generated from a token source and carries value tables beside the rules. Never hand-edited, its lead names the module it renders from. The toolkit's own record is one.
 
 Everything below applies to both shapes unless it names one.
 
@@ -68,24 +68,43 @@ Headings and table rows are never counted, and a section holding a table and no
 
 ## Sections
 
-Use `## Overview`, `## Colors`, `## Typography`, `## Spacing`, `## Shapes`, `## Motion`, and `## Iconography`, in that order, which follows Google's DESIGN.md for the sections the two share. An optional `## Layout` sits between Spacing and Shapes. The parser still reads a record written under the earlier names, `## Personality`, `## Color`, and `## Borders`, as the sections they became.
+Use `## Overview`, `## Colors`, `## Typography`, `## Spacing`, `## Shapes`, `## Motion`, and `## Iconography`, in that order, which follows Google's DESIGN.md for the sections the two share.
+
+- An optional `## Layout` sits between Spacing and Shapes
+- The parser still reads the earlier names `## Personality`, `## Color`, and `## Borders` as the sections they became
 
 In an intent record, `## Colors` carries a `Role | Property | Intent` table and `## Shapes` a `Role | Property | When used` table. Each row names the custom property the stylesheet declares for that role, such as `--color-accent`. Typography and Spacing carry rules alone.
 
 Add either optional section when the project has content for it:
 
-- `## Layout`: page width, breakpoints, and grid rules, as current constraints. The surface-capture rule reads the breakpoints from here, so a project with none declared here is captured at the 320 reflow floor alone.
+- `## Layout`: page width, breakpoints, and grid rules as current constraints. The surface-capture rule reads breakpoints here, so a project declaring none is captured at the 320 reflow floor alone.
 - `## Mark`: the logo's construction rules and the files that carry it
 
 ## The uncertainty tag
 
 Applies to a values record alone. An intent record carries no value to tag, and a guessed value is marked where it is written, in the stylesheet.
 
-A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
+### Writing the tag
+
+A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``, and both spellings parse.
+
+- The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it
+- The preview reports anchored cells against tagged ones, which is where a reviewer reads the record's overall confidence
+
+### Which columns count
+
+The table fixes which columns the ratio reads, not the record. The first column names its row, and `Multiplier` and `When used` restate what the row carries, so no source could anchor them and none is counted.
+
+| Section    | Counted columns                           |
+| ---------- | ----------------------------------------- |
+| Colors     | `Intent`, `Value`                         |
+| Typography | `Family`, `Weight`, `Size`, `Line height` |
+| Spacing    | `Value`                                   |
+| Shapes     | `Radius`, `Width`                         |
 
-The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it. The preview also reports how many cells are anchored against how many are tagged, which is the reading a reviewer takes the record's overall confidence from.
+A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
 
-Which columns that ratio reads is fixed by the table rather than by the record. The first column of each table names its row, and `Multiplier` and `When used` restate what the row already carries, so none of them is something a source could anchor and none is counted. That leaves `Intent` and `Value` in Colors, `Family`, `Weight`, `Size`, and `Line height` in Typography, `Value` in Spacing, and `Radius` and `Width` in Shapes. A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
+### Prose sections
 
 A prose section takes its uncertainty inline instead, in a sentence saying what is proposed and what has yet to confirm it. A tag appended to a paragraph renders verbatim.
 

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.