@erclx/canon 5.63.0 → 5.65.0

package/governance/ledger/skills/design-taste/systems.md

@@ -0,0 +1,42 @@
+---
+title: Systems reference ledger
+description: Sources for claude/skills/design-taste/references/systems.md, one row per bullet
+---
+
+# Systems reference ledger
+
+The field is visual design systems. The authorities are the Nielsen Norman Group for proximity, Practical Typography for the type scale, Apple's Human Interface Guidelines for dark mode, and W3C for text contrast.
+
+A catalog row records what a community prompt skill observed models drawing, never an authority. A House choice row carries a count the toolkit set so a tell can be counted, and names the failure it prevents.
+
+## Space
+
+| Bullet                      | Source                                                                                                                                                                                                                                                                        | Read       |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Every gap from one scale    | Catalog observation, [Impeccable layout](https://github.com/pbakaus/impeccable/blob/main/skill/reference/layout.md): "Use a documented spacing scale rather than one-off values." The figure of about eight is a House choice: past it, a count tells a scale from arithmetic | 2026-10-24 |
+| Steps grow rather than add  | House choice: a scale stepping by a fixed amount spends its large steps on gaps a reader cannot tell apart, and has too few steps where small gaps need them                                                                                                                  | 2026-10-24 |
+| Between groups beats within | [NN/g, Proximity](https://www.nngroup.com/articles/gestalt-proximity/): "Items close together are likely to be perceived as part of the same group"                                                                                                                           | 2026-10-24 |
+| One gap everywhere          | [NN/g, Proximity](https://www.nngroup.com/articles/gestalt-proximity/): a tight label reads as one group "compared to a larger margin before the next label-field pair"                                                                                                       | 2026-10-24 |
+| Two or three section tiers  | House choice: enough tiers for rhythm, few enough that each section takes one, since a value per section leaves no rhythm to read                                                                                                                                             | 2026-10-24 |
+| Space follows the viewport  | House choice: a layout scaling every value with the viewport arrives at a phone with body type too small to read, while space shrinks without harm                                                                                                                            | 2026-10-24 |
+
+## Type
+
+| Bullet                       | Source                                                                                                                                                                                                                        | Read       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Fewer steps than feel enough | [Practical Typography, Headings](https://practicaltypography.com/headings.html): "Limit yourself to three levels of headings. Two is better." The five to seven figure is a House choice: more holds steps nobody tells apart | 2026-10-24 |
+| Adjacent steps differ        | [Practical Typography, Headings](https://practicaltypography.com/headings.html): "Use the smallest increment necessary to make a visible difference."                                                                         | 2026-10-24 |
+| Body size anchors            | House choice: a scale worked down from a display size leaves body text at whatever size was left, and body text is most of what a reader reads                                                                                | 2026-10-24 |
+| Line height against size     | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): headlines "reduce line-height", and for body text "Increase line-height for readability"    | 2026-10-24 |
+| Weights beside sizes         | [Practical Typography, Headings](https://practicaltypography.com/headings.html): "If you're using bold in your heading, you can also try reducing the point size"                                                             | 2026-10-24 |
+
+## Palette
+
+| Bullet                        | Source                                                                                                                                                                                                                                                                                                                                                                               | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| An accent is rare             | Catalog observation, [Minimalist skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/minimalist-skill/SKILL.md): "Color is a scarce resource, utilized only for semantic meaning or subtle accents."                                                                                                                                                            | 2026-10-24 |
+| One neutral temperature       | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Mixing warm and cool grays. Stick to one gray family."                                                                                                                                                                                            | 2026-10-24 |
+| Surfaces near, content far    | [WCAG 2.2, Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) backs the content half: text needs "a contrast ratio of at least 4.5:1". The surface half is a catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "Opaque surfaces one tone step from the ground" | 2026-10-24 |
+| A semantic color is no accent | House choice: an accent borrowed for an error makes every accent read as an error, and leaves the surface no color free for emphasis                                                                                                                                                                                                                                                 | 2026-10-24 |
+| Dark mode re-derived          | [Apple HIG, Dark Mode](https://developer.apple.com/design/human-interface-guidelines/dark-mode): dark colors "aren't necessarily inversions of their light counterparts"                                                                                                                                                                                                             | 2026-10-24 |
+| Saturation has a budget       | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Desaturate accents so they blend with neutrals instead of screaming."                                                                                                                                                                             | 2026-10-24 |

package/governance/ledger/skills/design-taste/tells.md

@@ -0,0 +1,103 @@
+---
+title: Machine tells ledger
+description: Sources for claude/skills/design-taste/references/tells.md, one row per bullet
+---
+
+# Machine tells ledger
+
+The field is what language models draw when nothing states a direction, which no design authority studies. Nearly every row is therefore a catalog observation from a community prompt skill, recording model output and never cited as an authority. The few authority rows quote MDN, Practical Typography, or Wikipedia.
+
+The main catalog is Taste-Skill's v2 experimental skill, which its author moved to the classics repository on 2026-10-19. Each count in the countable limits is a House choice even where a catalog states the same number, since the toolkit adopted it so the tell can be counted.
+
+## Where current AI design clusters
+
+| Bullet                  | Source                                                                                                                                                                                                                                                                   | Read       |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| The warm paper page     | Catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "a warm cream background (near #F4F1EA) with a high-contrast serif display and a terracotta or warm-clay accent"                                 | 2026-10-24 |
+| Black with one accent   | Catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "a near-black background with a single bright acid-green or vermilion accent"                                                                    | 2026-10-24 |
+| The newspaper imitation | Catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "a broadsheet-style layout with hairline rules, zero border-radius, and dense newspaper-like columns"                                            | 2026-10-24 |
+| The card kit            | Catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "content chopped into identical rounded cards", under "the same soft grey shadow", with "gradient washes as decoration"                          | 2026-10-24 |
+| Template chrome         | Catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "a tracked-out ALL-CAPS eyebrow label above every heading", "meta strings joined with middle dots", and "a monospace face for small data labels" | 2026-10-24 |
+
+## Composition
+
+| Bullet                     | Source                                                                                                                                                                                                                                                                 | Read       |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The three equal cards      | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Three equal card columns as feature row. This is the most generic AI layout."                                                       | 2026-10-24 |
+| One section shape repeated | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "Every section the same layout family" is a structural tell, reached past with "Different composition per section"                 | 2026-10-24 |
+| The centered hero          | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "Centred headline, subtitle, two buttons, screenshot below"                                                                        | 2026-10-24 |
+| Decoration as structure    | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "NO crosshair / hairline grid lines as decoration", kept "only when they organize real content"            | 2026-10-24 |
+| The corner floater         | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "a small explainer paragraph floating with no clear alignment to anything else. That floater is the Tell." | 2026-10-24 |
+
+## Content and labels
+
+| Bullet                     | Source                                                                                                                                                                                                                                                                               | Read       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Enumerated eyebrows        | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): generic step labels are banned, since "The actual step content is the label"                                             | 2026-10-24 |
+| Poetic section labels      | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Field notes" and "On our desks" style labels read "as performative-craftsman. Use plain functional labels"              | 2026-10-24 |
+| Atmospheric strips         | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "NO weather / locale strips" and "NO version footers on marketing pages"                                                 | 2026-10-24 |
+| Scroll cues                | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Scroll cues are banned." Readers "know what scroll is."                                                                 | 2026-10-24 |
+| Decorative status dots     | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): a dot is "Only acceptable when conveying real semantic state" and "limited to one per page section"                      | 2026-10-24 |
+| Filler verbs               | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Never use 'Elevate', 'Seamless', 'Unleash', 'Next-Gen'", and "Write plain, specific language."                                                    | 2026-10-24 |
+| Placeholder as placeholder | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Generic names like 'John Doe'" and "Placeholder company names like 'Acme Corp'"                                                                   | 2026-10-24 |
+| Invented precision         | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Fake-precise numbers are flagged", passing only when they "Come from real data" or "Are explicitly labeled as mock"     | 2026-10-24 |
+| The fake screenshot        | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "NO div-based fake product UI in the hero", which it ranks first among the tells                                         | 2026-10-24 |
+| Copy nobody re-read        | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "re-read every visible string on the page", since "AI-generated cute copy is worse than boring copy"                     | 2026-10-24 |
+| What the re-read rewrites  | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): the re-read flags a string that is "Grammatically broken", "Has unclear referents", or carries "cute-but-wrong wordplay" | 2026-10-24 |
+
+## Surface and palette
+
+| Bullet                       | Source                                                                                                                                                                                                                                                                                                                                                   | Read       |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Glow as depth                | Catalog observation, [Impeccable craft floor](https://github.com/pbakaus/impeccable/blob/main/skill/reference/craft-floor.md): "shadows carry an offset and a soft blur. A zero-offset colored halo is decoration."                                                                                                                                      | 2026-10-24 |
+| Pure black and pure white    | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md), for the black half: a pure black background is a tell, to "Replace with off-black, dark charcoal, or tinted dark". The white half is a House choice: a full-brightness ground glares beside every tinted neutral on it | 2026-10-24 |
+| Saturation everywhere        | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Oversaturated accent colors. Keep saturation below 80%."                                                                                                                                                              | 2026-10-24 |
+| The gradient as a substitute | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "Gradient-filled headline text" and a "Glowing or gradient" button are banned, reached past with "Solid ink" and a "Flat button"                                                                                     | 2026-10-24 |
+| Uniform radius and elevation | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "One medium border radius (12–16px) on everything" and a "Soft grey drop shadow under every card"                                                                                                                    | 2026-10-24 |
+
+## Platform surfaces
+
+| Bullet                       | Source                                                                                                                                                                | Read       |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| An unstyled platform control | [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme): it adapts "The default colors of form controls"                   | 2026-10-24 |
+| No checkerboard              | [Wikipedia, Transparency](https://en.wikipedia.org/wiki/Transparency_%28graphic%29): an editor "shows transparency by a special pattern, e.g. a checkerboard pattern" | 2026-10-24 |
+
+## Typography
+
+| Bullet                       | Source                                                                                                                                                                                                                                         | Read       |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Scale as the only hierarchy  | [Practical Typography, Headings](https://practicaltypography.com/headings.html): "It's fine to make the point size bigger, but just a little."                                                                                                 | 2026-10-24 |
+| One family doing every job   | Catalog observation, [Redesign skill](https://github.com/nxpatterns/claude-taste-skill/blob/main/skills/redesign-skill/SKILL.md): "Browser default fonts or Inter everywhere", reached past by pairing "a serif header with a sans-serif body" | 2026-10-24 |
+| Unbounded measure            | [Practical Typography, Line length](https://practicaltypography.com/line-length.html): "Aim for an average line length of 45–90 characters, including spaces."                                                                                 | 2026-10-24 |
+| Caps and tracking as texture | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "Tiny uppercase letter-spaced captions scattered around the viewport"                                      | 2026-10-24 |
+
+## Motion
+
+| Bullet                             | Source                                                                                                                                                                                                                                                              | Read       |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Motion nobody can justify          | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Before adding any animation, ask: 'what does this animation communicate?'"                             | 2026-10-24 |
+| The permanent loop                 | Catalog observation, [Taste-Skill tells](https://github.com/leonxlnx/taste-skill/blob/main/skills/taste-skill/references/tells.md): "infinite loops that mean nothing" are a motion tell                                                                            | 2026-10-24 |
+| Motion on arrival                  | Catalog observation, [frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md): "fade-and-slide-up entrances on each section and hover transitions on every card are the generic default and read as AI-generated"          | 2026-10-24 |
+| Motion claimed but absent          | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Motion claimed, motion shown." A static page claiming motion "is broken"                               | 2026-10-24 |
+| Motion that ignores the preference | [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion): it detects a setting "to minimize the amount of non-essential motion", the source the `ui-craft` motion ledger records for the rule this bullet points at | 2026-10-24 |
+
+## The countable limits
+
+| Bullet                 | Source                                                                                                                                                                                                                                                                                                                  | Read       |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A layout family once   | House choice: a repeated shape becomes a count a reviewer can check. The catalog states the cap, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "A landing page with 8 sections must use at least 4 different layout families." | 2026-10-24 |
+| Two consecutive splits | House choice: a third alternation is where the pattern reads as filler. The catalog states the cap, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Max 2 sections in a row with this image+text-split pattern."                | 2026-10-24 |
+| One label per three    | House choice, recorded in the `ui-craft` copy ledger. The catalog states the cap, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Maximum 1 eyebrow per 3 sections."                                                            | 2026-10-24 |
+| One marquee            | House choice: a second sliding strip is where the device reads as filler. The catalog states the cap, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Two or more marquees on the same page reads as lazy filler."              | 2026-10-24 |
+| Cells equal items      | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "A bento grid has EXACTLY as many cells as you have content for."                                                                                           | 2026-10-24 |
+| Over five items        | House choice: a long run becomes a count a reviewer can check. The catalog states the cap, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "If you have > 5 items, reach for one of these instead"                               | 2026-10-24 |
+
+## The first screen
+
+| Bullet                       | Source                                                                                                                                                                                                                                                                                   | Read       |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| It fits                      | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "Hero MUST fit in the initial viewport", with "CTAs visible without scroll"                                                  | 2026-10-24 |
+| At most four text elements   | House choice: a label, a headline, a supporting line, and the actions, so a fifth is countable. The catalog states the cap, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "max 4 text elements" | 2026-10-24 |
+| Everything else moves down   | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): the tagline, trust strip, pricing teaser, feature list, and avatar row "move to dedicated sections directly below the hero"  | 2026-10-24 |
+| Scale planned with the asset | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): "A 4-line hero headline is always a font-size error, never a copy-length error."                                             | 2026-10-24 |
+| Logos go under it            | Catalog observation, [Taste-Skill v2 experimental](https://github.com/Leonxlnx/taste-skill-classics/blob/main/skills/taste-skill-v2-experimental/SKILL.md): the logo wall "belongs UNDER the hero, never inside it"                                                                      | 2026-10-24 |

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

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

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

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

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

@@ -0,0 +1,33 @@
+---
+title: Teach craft skill ledger
+description: Sources for claude/skills/teach-craft/SKILL.md, one row per bullet in its concern groups
+---
+
+# Teach craft skill ledger
+
+The field is learning science, and the papers are the ones `adopted.md` opened through PubMed. Each row links the abstract page and quotes only what that abstract carries. The house choices stand where `adopted.md` lists a rule as house judgment, and each row names the failure the rule prevents.
+
+The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+## References
+
+| Bullet            | Source                                                                                                                         | Read       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| `pedagogy.md`     | House choice: a session picking the next topic from the body alone skips the spacing ladder and the placement rules it carries | 2026-10-24 |
+| `lesson-craft.md` | House choice: a quiz written without the construction rules leaks its answer through option length or slot                     | 2026-10-24 |
+
+## Before teaching
+
+| Bullet                                | Source                                                                                                                                                                  | Read       |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Ask what the learner already knows    | House choice: a lesson pitched from an assumed floor either repeats what the learner holds or skips what they lack                                                      | 2026-10-24 |
+| Read the subject from sources         | House choice: a claim taught from recall is confident where it is wrong, and a learner has no way to audit it                                                           | 2026-10-24 |
+| Open a returning learner on retrieval | [Roediger and Karpicke 2006, Test-enhanced learning](https://pubmed.ncbi.nlm.nih.gov/16507066/): "prior testing produced substantially greater retention than studying" | 2026-10-24 |
+
+## While teaching
+
+| Bullet                            | Source                                                                                                                                                                                                                                                                                                                                                                                                                      | Read       |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Place each step just past unaided | House choice: a step inside what the learner can already do is review, and one far past it leaves the support doing the whole task                                                                                                                                                                                                                                                                                          | 2026-10-24 |
+| Carry a quiz and a teach-back     | [Pashler et al. 2007, IES practice guide](https://ies.ed.gov/ncee/wwc/Docs/PracticeGuide/20072004.pdf): "Use quizzing with active retrieval of information at all phases of the learning process", and [Nestojko et al. 2014, Expecting to teach](https://pubmed.ncbi.nlm.nih.gov/24845756/) backs the teach-back: "Participants expecting to teach produced more complete and better organized free recall of the passage" | 2026-10-24 |
+| Record the wrong answer itself    | House choice: a score tells the next session that the learner missed and not what they believe, so it places them from a count rather than the misconception                                                                                                                                                                                                                                                                | 2026-10-24 |

package/governance/ledger/skills/teach-craft/lesson-craft.md

@@ -0,0 +1,47 @@
+---
+title: Teach craft lesson craft ledger
+description: Sources for claude/skills/teach-craft/references/lesson-craft.md, one row per bullet
+---
+
+# Teach craft lesson craft ledger
+
+The reference names Butler and Roediger 2008 for feedback, Kornell, Hays and Bjork 2009 for its timing, and Nestojko et al. 2014 for the teach-back. Each row links the PubMed abstract `adopted.md` opened and quotes only that abstract.
+
+Restraint and what makes a lesson worth returning to are editorial calls about a page, so their rows are house choices naming the failure each prevents. `## Contents` takes no table.
+
+## Restraint
+
+| Bullet                                   | Source                                                                                                                       | Read       |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Cut decoration carrying nothing          | House choice: an ornament competes with the material for the learner's attention and teaches nothing in return               | 2026-10-24 |
+| One accent color, for the action         | House choice: a second accent splits what the eye goes to first, so the thing the learner acts on stops standing out         | 2026-10-24 |
+| No animation the learner did not trigger | House choice: motion the learner did not start pulls the eye off the line they are reading                                   | 2026-10-24 |
+| Whitespace over rules and boxes          | House choice: rules and boxes add marks the reader has to skip, and stacked boxes read as nesting the material does not have | 2026-10-24 |
+
+## Quiz design
+
+| Bullet                                 | Source                                                                                                                                                                                                                                  | Read       |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Every option the same length           | House choice: a longer option reads as the considered one, so a learner picks it by length and the quiz measures test-taking                                                                                                            | 2026-10-24 |
+| Rotate the correct slot by number      | House choice: an author varying the slot by judgment settles on the first one, and a learner who notices answers by position                                                                                                            | 2026-10-24 |
+| Each wrong option a held misconception | House choice: an option nobody believes removes itself, so a four-option question shrinks to fewer and passes a guess                                                                                                                   | 2026-10-24 |
+| One feedback block per question        | [Butler and Roediger 2008, Feedback and multiple-choice testing](https://pubmed.ncbi.nlm.nih.gov/18491500/): "The selection of lures can lead students to acquire false knowledge", and feedback "reduced the proportion of intrusions" | 2026-10-24 |
+| Feedback after the attempt             | [Kornell, Hays and Bjork 2009, Unsuccessful retrieval attempts enhance subsequent learning](https://pubmed.ncbi.nlm.nih.gov/19586265/): "participants attempted to answer the question before being shown the answer"                   | 2026-10-24 |
+
+## Teach back
+
+| Bullet                                  | Source                                                                                                                                                                                          | Read       |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Explain to a named audience             | [Nestojko et al. 2014, Expecting to teach](https://pubmed.ncbi.nlm.nih.gov/24845756/): "Participants expecting to teach produced more complete and better organized free recall of the passage" | 2026-10-24 |
+| Ask about what the lesson was for       | House choice: a teach-back on a detail beside the point tests attention, so the learner passes it without holding the material                                                                  | 2026-10-24 |
+| A hidden self-check of what to cover    | House choice: a learner alone cannot grade their own explanation, and a check shown beside the ask leaks what to say                                                                            | 2026-10-24 |
+| The self-check as coverage, not a model | House choice: a model answer is read instead of produced, which turns the teach-back back into reading                                                                                          | 2026-10-24 |
+
+## What makes a lesson worth returning to
+
+| Bullet                            | Source                                                                                                                            | Read       |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The worked example is complete    | House choice: a fragment forces a returning reader to rebuild the rest from memory, which is the work they came back to avoid     | 2026-10-24 |
+| The lesson states what it assumes | House choice: a reader who cannot tell whether they hold the prerequisites reads on and fails at a step they were never ready for | 2026-10-24 |
+| The hard part is named as hard    | House choice: material flattened to one difficulty gives a returning reader nothing to navigate by, so they reread all of it      | 2026-10-24 |
+| Nothing depends on the session    | House choice: a lesson pointing at what was discussed loses its meaning once that conversation is gone, often within a week       | 2026-10-24 |

package/governance/ledger/skills/teach-craft/pedagogy.md

@@ -0,0 +1,77 @@
+---
+title: Teach craft pedagogy ledger
+description: Sources for claude/skills/teach-craft/references/pedagogy.md, one row per bullet or ordered step
+---
+
+# Teach craft pedagogy ledger
+
+The field is learning science. Each paper row links the PubMed abstract `adopted.md` opened and quotes only that abstract, and the IES practice guide rows quote the guide's PDF.
+
+The reference labels the rest as house judgment, being the ladder, production over selection, the zone of proximal development, and the sourcing rules, so those rows name the failure each prevents. `## Contents` takes no table.
+
+## Fluency is not storage strength
+
+| Bullet                                  | Source                                                                                                                                                                                                                | Read       |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Confidence is evidence about the lesson | [Roediger and Karpicke 2006, Test-enhanced learning](https://pubmed.ncbi.nlm.nih.gov/16507066/): testing won "even though repeated studying increased students' confidence in their ability to remember the material" | 2026-10-24 |
+| Advance on an unaided retrieval         | [Roediger and Karpicke 2006, Test-enhanced learning](https://pubmed.ncbi.nlm.nih.gov/16507066/): "When the final test was given after 5 min, repeated studying improved recall relative to repeated testing"          | 2026-10-24 |
+
+## Retrieval practice
+
+| Bullet                                      | Source                                                                                                                                                                                                     | Read       |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Ask before telling                          | [Kornell, Hays and Bjork 2009, Unsuccessful retrieval attempts](https://pubmed.ncbi.nlm.nih.gov/19586265/): "participants attempted to answer the question before being shown the answer"                  | 2026-10-24 |
+| Production over selection                   | House choice: a learner picking from four options can pass on recognition alone, so the lesson reports a retrieval the learner cannot do unprompted                                                        | 2026-10-24 |
+| Let the attempt fail before correcting      | [Kornell, Hays and Bjork 2009, Unsuccessful retrieval attempts](https://pubmed.ncbi.nlm.nih.gov/19586265/): "Unsuccessful retrieval attempts enhanced learning with both types of materials"               | 2026-10-24 |
+| No cue in the question                      | House choice: a question restating the material can be answered by reading it, so it measures reading and reports memory                                                                                   | 2026-10-24 |
+| Which rules rest on Kornell, Hays and Bjork | [Kornell, Hays and Bjork 2009, Unsuccessful retrieval attempts](https://pubmed.ncbi.nlm.nih.gov/19586265/): the read-only condition it beat is one where "the question and answer were presented together" | 2026-10-24 |
+| A teach-back block in every lesson          | [Nestojko et al. 2014, Expecting to teach](https://pubmed.ncbi.nlm.nih.gov/24845756/): "Participants expecting to teach produced more complete and better organized free recall of the passage"            | 2026-10-24 |
+| Name the explanation's audience             | [Nestojko et al. 2014, Expecting to teach](https://pubmed.ncbi.nlm.nih.gov/24845756/): the gain came to "Participants expecting to teach", against "participants expecting a test"                         | 2026-10-24 |
+| Record what the explanation left out        | House choice: a missed production filed apart from a missed selection splits one placement input, so the next session places the learner from half of it                                                   | 2026-10-24 |
+
+## Spacing
+
+| Bullet                                    | Source                                                                                                                                                                                               | Read       |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Revisit once forgetting has begun         | [Pashler et al. 2007, IES practice guide](https://ies.ed.gov/ncee/wwc/Docs/PracticeGuide/20072004.pdf): key content seen on two occasions "separated by a period of several weeks to several months" | 2026-10-24 |
+| Widen the gap on a hit, shorten on a miss | House choice: a fixed gap keeps reviewing what the learner holds and leaves what they keep missing to fade between sessions                                                                          | 2026-10-24 |
+| Name the revisit in the record            | House choice: a next session with no schedule in the record picks its revisit by guess, and the spacing the ladder sets is lost                                                                      | 2026-10-24 |
+| Apply the ladder as written               | House choice: an author told to widen a gap by judgment settles on whatever feels right, so two sessions space one topic differently                                                                 | 2026-10-24 |
+
+## Interleaving
+
+| Bullet                                      | Source                                                                                                                                                                                                                     | Read       |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Mix topics once each has a foothold         | House choice, extending Kornell and Bjork's exemplars to topics: a session finishing one topic before the next never makes the learner work out which approach a problem calls for                                         | 2026-10-24 |
+| Keep a mixed set close enough to tell apart | [Kornell and Bjork 2008, Learning concepts and categories](https://pubmed.ncbi.nlm.nih.gov/18578849/): a given artist's paintings "presented consecutively (massed) or interleaved with other artists' paintings (spaced)" | 2026-10-24 |
+| Never interleave an unseen topic            | House choice: telling two things apart needs something on each side, so mixing in a topic never taught leaves the learner guessing rather than discriminating                                                              | 2026-10-24 |
+
+## The zone of proximal development
+
+| Bullet                                            | Source                                                                                                                                                            | Read       |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Compute the band from the records                 | House choice: a band taken from the subject's own order teaches the next chapter whatever the learner got wrong last time                                         | 2026-10-24 |
+| Target the first thing not done unaided           | House choice: a target picked past the first miss builds on a step the learner cannot yet do, so the support carries the task                                     | 2026-10-24 |
+| Withdraw support on success, restore it on a miss | House choice: support left in place after a success carries a task the learner can now do alone, and repeating the lesson on a miss restarts what was nearly held | 2026-10-24 |
+| Ask where the records show nothing                | House choice: a guessed starting point misses in both directions, either reviewing what is held or skipping what is not                                           | 2026-10-24 |
+
+## Where difficulty helps and where it hurts
+
+| Bullet                                   | Source                                                                                                                                                                                                                                           | Read       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| New material in its clearest form        | [Pashler et al. 2007, IES practice guide](https://ies.ed.gov/ncee/wwc/Docs/PracticeGuide/20072004.pdf): students "learn more by alternating between studying examples of worked-out problem solutions and solving similar problems on their own" | 2026-10-24 |
+| Add difficulty once practicing           | [Kornell, Hays and Bjork 2009, Unsuccessful retrieval attempts](https://pubmed.ncbi.nlm.nih.gov/19586265/): "Unsuccessful retrieval attempts enhanced learning with both types of materials"                                                     | 2026-10-24 |
+| A hard explanation is not a hard problem | House choice: a confusing explanation adds load the learner spends decoding the teacher, so the difficulty teaches nothing about the material                                                                                                    | 2026-10-24 |
+
+## Sourcing
+
+| Bullet                                   | Source                                                                                                                                                  | Read       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Read the subject from sources first      | House choice: parametric recall is confident where it is wrong, and a learner cannot audit a claim nobody read                                          | 2026-10-24 |
+| Mark a claim resting on recall           | House choice: an unmarked recalled claim reads with the authority of a sourced one, so the learner trusts the part most likely to be wrong              | 2026-10-24 |
+| A source not opened is a lead            | House choice: a citation to a page nobody read can say the opposite of the claim, and the link makes the claim look checked                             | 2026-10-24 |
+| The highest rung covering the claim      | House choice: a claim resting on a tutorial when the owner's docs cover it inherits the tutorial's errors and its age                                   | 2026-10-24 |
+| No personal or employer proof            | House choice: one project or one employer's practice stands for a general rule only by accident, so a lesson built on it teaches a local habit as a law | 2026-10-24 |
+| Owner documentation or specification     | House choice: the owner's own docs track the current version, so a claim read anywhere lower drifts the first time the subject changes                  | 2026-10-24 |
+| A canonical work                         | House choice: a subject nobody owns has no docs to rank first, so the standard text or primary paper is the most checked source left                    | 2026-10-24 |
+| Other material, recorded with its reason | House choice: a third-rung source recorded without why no higher rung covers the claim cannot be rechecked when a better source appears                 | 2026-10-24 |

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

@@ -0,0 +1,67 @@
+---
+title: Test craft skill ledger
+description: Sources for claude/skills/test-craft/SKILL.md, one row per bullet in its concern groups
+---
+
+# Test craft skill ledger
+
+The field is software testing practice. Software Engineering at Google carries test sizes, clarity, and doubles, Fowler and Ham Vocke carry the pyramid, and `obra/superpowers` carries the opening question the body asks of every test. The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+`references/adopted.md` stays the record of what was adopted and declined at the source level.
+
+## Open every test with one question
+
+| Bullet                             | Source                                                                                                                                                                                                                                                                            | Read       |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A bug is what the test is for      | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): "what production change should make this test fail", then whether "that change [is] a bug or a decision"                           | 2026-10-24 |
+| A decision makes a change detector | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): when "only intentional decisions can fail a test", such as "exact message wording", "it fires on redesign and sleeps through bugs" | 2026-10-24 |
+| No answer proves nothing yet       | [obra/superpowers, Writing Good Tests](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/writing-good-tests.md): "Cannot name one → redesign around an observable behavior"                                                                         | 2026-10-24 |
+| Cover the edges as their own cases | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): unit tests "should ensure that all your non-trivial code paths are tested (including happy path and edge cases)"                                                              | 2026-10-24 |
+
+## Put the test at the smallest layer that can catch the break
+
+| Bullet                                     | Source                                                                                                                                                                                                                                                              | Read       |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The row read off the behavior              | [Software Engineering at Google, ch. 11](https://abseil.io/resources/swe-book/html/ch11.html): "small tests run in a single process, medium tests run on a single machine, and large tests run wherever they want", a size set by what the test touches             | 2026-10-24 |
+| Split a behavior that spans rows           | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "Push your tests as far down the test pyramid as you can"                                                                                                       | 2026-10-24 |
+| A red higher run names a missing lower one | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "If a higher-level test spots an error and there's no lower-level test failing, you need to write a lower-level test"                                           | 2026-10-24 |
+| Real-browser component before end to end   | [Vitest, Component Testing](https://vitest.dev/guide/browser/component-testing): component tests run "in real browser environments", which "provides the most accurate testing environment as your components run in real browsers with actual DOM implementations" | 2026-10-24 |
+
+## Spend end to end on journeys
+
+| Bullet                                | Source                                                                                                                                                                                                                                                                            | Read       |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Journeys the product cannot lose      | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "Try to come up with user journeys that define the core value of your product and translate the most important steps of these user journeys into automated end-to-end tests." | 2026-10-24 |
+| No end to end for a component's state | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "UI tests don't have to be on the highest level of your pyramid - you're perfectly able to unit test your UI in all of these frameworks"                                      | 2026-10-24 |
+| Every later run pays for a new one    | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "Due to their high maintenance cost you should aim to reduce the number of end-to-end tests to a bare minimum."                                                               | 2026-10-24 |
+| No numeric mix                        | [web.dev, Pyramid or Crab?](https://web.dev/articles/ta-strategies): the strategy "should fir your architecture, your requirements, and last but not least, your users and their requirements", typo as published                                                                 | 2026-10-24 |
+
+## Keep test code readable over clever
+
+| Bullet                                  | Source                                                                                                                                                                                                                                               | Read       |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A repeated arrange over a shared helper | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): "A little bit of duplication is OK in tests so long as that duplication makes the test simpler and clearer."                                          | 2026-10-24 |
+| Test data through a factory or builder  | [Pryce, Test Data Builders](http://www.natpryce.com/articles/000714.html): "For each class you want to use in a test, create a Builder for that class", one that "Initialises its instance variables to commonly used or safe values"                | 2026-10-24 |
+| Assert through the public surface       | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): tests should "make calls against its public API rather than its implementation details"                                                               | 2026-10-24 |
+| Real, then fake, then stub, mock last   | [addyosmani/agent-skills, Test-Driven Development](https://github.com/addyosmani/agent-skills/blob/c004a74/skills/test-driven-development/SKILL.md): "Preference order (most to least preferred): 1. Real implementation", then fake, stub, and mock | 2026-10-24 |
+
+## Hold the structure floors
+
+| Bullet                              | Source                                                                                                                                                                                                                                                                                                                                                                                                          | Read       |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Arrange, act, assert                | [Vocke, The Practical Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html): "There's a nice mnemonic to remember this structure: “Arrange, Act, Assert”"                                                                                                                                                                                                                                | 2026-10-24 |
+| One behavior per test               | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): "Each test should cover only a single behavior"                                                                                                                                                                                                                                                                  | 2026-10-24 |
+| No branches or loops in a test body | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html): "in test code, stick to straight-line code over clever logic"                                                                                                                                                                                                                                                    | 2026-10-24 |
+| No coverage percentage as a target  | [Fowler, Test Coverage](https://martinfowler.com/bliki/TestCoverage.html): "If you make a certain level of coverage a target, people will try to attain it. The trouble is that high coverage numbers are too easy to reach with low quality testing."                                                                                                                                                          | 2026-10-24 |
+| Nesting kept to two levels          | [Software Engineering at Google, ch. 12](https://abseil.io/resources/swe-book/html/ch12.html) groups tests "nested within one another and named using strings". The two-level cap is a House choice: deeper nesting spreads a test's setup across hooks, which [Dodds](https://kentcdodds.com/blog/avoid-nesting-when-youre-testing) names as "the number one reason I strongly recommend against nested tests" | 2026-10-24 |
+| Independent tests, state restored   | [Beck, Test Desiderata](https://testdesiderata.com/): Isolated tests "should return the same results regardless of the order in which they are run."                                                                                                                                                                                                                                                            | 2026-10-24 |
+| Await every async operation         | [Jest, Testing Asynchronous Code](https://jestjs.io/docs/asynchronous): "if you omit the return / await statement, your test will complete before the promise returned from fetchData resolves or rejects"                                                                                                                                                                                                      | 2026-10-24 |
+| Assertions, never a snapshot        | [Dodds, Effective Snapshot Testing](https://kentcdodds.com/blog/effective-snapshot-testing), quoting Justin Searls: "Snapshot tests lack (or at least, fail to encourage) expressing the author's intent as to what the code does (much less why)"                                                                                                                                                              | 2026-10-24 |
+
+## Read the reference for the layer
+
+| Bullet                         | Source                                                                                                                                                                | Read       |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Unit and integration reference | House choice: a unit test written without `unit.md` reaches for a mock before a real collaborator or a fake, and skips the mutation check that finds its missing case | 2026-10-24 |
+| Component reference            | House choice: a component test written without `component.md` queries by test id and fires synthetic events, so it passes on markup a user cannot reach               | 2026-10-24 |
+| End to end reference           | House choice: a first spec written without `e2e.md` pauses for a fixed time and runs with motion on, the two causes of the flakes its worked failures record          | 2026-10-24 |