@erclx/canon 5.73.0 → 5.75.0

package/claude/skills/ui-film/references/handoff.md

@@ -33,13 +33,8 @@ The track is final. It already carries the easing, the spring, and the hold, so
 
 ## Where the composition lives
 
-The HyperFrames project sits in the same workspace as the takes, so one folder holds everything a video is made from.
+The HyperFrames project sits in the same workspace as the takes, so one folder holds everything a video is made from. Create it at `.canon/video/<slug>/composition` with the new-project command the `hyperframes` skill names, run the way that skill says for its install, since a plugin install routes the CLI through its own launcher.
 
-```bash
-bunx -y hyperframes init .canon/video/<slug>/composition
-```
-
-- Use `bunx` when bun is available, falling back to `npx -y hyperframes init ...` otherwise
 - Prefix the path with the main worktree root when running from a linked worktree, as `ui-film`'s write scope states
 - Read each clip from `../takes/<dir>/clip.mp4`, relative to the project, rather than copying it in
 - Leave renders in the project's `renders/` folder, which `canon records push` skips along with `takes/`, `scratch/`, `snapshots/`, `node_modules/`, and any video file
@@ -68,7 +63,7 @@ Where composing from the main root is not possible, write each file whole throug
 
 ## Applying it in a composition
 
-Load `hyperframes-core` for placing the clip and `hyperframes-keyframes` for the wrapper's transform before writing the composition.
+Read the `hyperframes` skill's `references/format.md` for placing the clip and `references/motion.md` for the wrapper's transform before writing the composition.
 
 1. Size a stage at 1920x1080 and place the clip inside a non-timed wrapper that fills it, with `transform-origin: 0 0`. Time the video, never the wrapper too.
 2. Drive the wrapper from the track on the composition's registered timeline, setting `scale(s) translate(-x px, -y px)` at each frame's time from the clip's start.

package/claude/skills/write-human/references/adopted.md

@@ -12,6 +12,8 @@ Two external writing skills were read as source material for this one.
 
 Neither was imported wholesale, and one measurement settles why. Read this before adding a rule from outside this corpus, and extend the position below rather than deriving a second one.
 
+A source a bullet rests on is linked once, in that bullet's row of the toolkit's per-bullet ledger at `governance/ledger/skills/write-human/`, which ships outside the plugin. This file names those sources without the link and keeps the catalog-level adopted and declined record, linking only a source no row cites.
+
 ## What was adopted
 
 Roughly half the pattern catalog had no counterpart in this corpus. Six of those patterns are now in `machine-tells.md`, each a shape rather than a token, which kept it out of a ban list that matches words.
@@ -49,8 +51,11 @@ The source material treats repetition of a noun as a defect. This skill treats i
 
 The source material also prefers shorter sentences without bound. This skill measures the spread instead, since a passage of uniformly short sentences is the reported failure rather than the fix for it.
 
-## The industry-guide record
+## Where the rows sit
 
-The cadence rules and the bans they pair with trace to three industry style guides, being Google's developer documentation style guide, Microsoft's writing style guide, and Apple's style guide.
+Each bullet and ordered step in the skill body and in `density.md` has its own source row in a ledger outside the plugin, one ledger per file and one row per bullet under the H2 the bullet sits under.
 
-The authoring toolkit keeps the per-rule attributions and the dates each guide was read. No install carries that record, so this file is the position a target reads.
+- The toolkit's skill audit fails a ledgered file whose bullets and rows disagree in count under any heading, and a target never carries the rows
+- The rows cite plain-language guidance, the Google and Microsoft style guides, Nielsen Norman Group, Purdue OWL, and Signs of AI writing, and mark the rest as house choices
+- `machine-tells.md` holds its tells as prose, so its ledger sources each tell in a list rather than a table
+- This record keeps the adopted and declined position above, which no row restates

package/docs/agents/audits.md

@@ -63,30 +63,30 @@ An audit that finds no corpus reports `absent`, which moves neither the verdict
 
 `canon audits list` reports the first 18 rows. The rows marked `outside` run by hand or from a skill and sit beside the aggregate.
 
-| Id                   | Verb                                | Measures                                                                           | Finding        |
-| -------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- | -------------- |
-| `context`            | `canon context audit`               | Context folder structure, citations, and the requirements record's word cap        | Gates          |
-| `markdown`           | `canon markdown audit`              | Bans, dead links, density, and reference shape                                     | Gates          |
-| `skills`             | `canon claude skills audit`         | Both skill corpora against the skill standards                                     | Gates          |
-| `skills-reach`       | `canon claude skills reach`         | Skill bodies citing a path no target receives                                      | Reports        |
-| `skills-rank`        | `canon claude skills rank`          | Whether skill descriptions separate against a routing case corpus                  | Reports        |
-| `tasks`              | `canon tasks validate`              | Board rows nothing resolves                                                        | Reports        |
-| `records-plans`      | `canon records validate plans`      | Plan records against their shape                                                   | Reports        |
-| `records-groundwork` | `canon records validate groundwork` | Groundwork folders against their shape                                             | Reports        |
-| `records-intake`     | `canon records validate intake`     | Intake folders against their shape                                                 | Reports        |
-| `comments`           | `canon comments scan`               | Comment density by language and kind, and `TODO`, `FIXME`, `HACK`, `XXX`           | Reports        |
-| `test-order`         | `canon gov test-order`              | Implementations that reached branch history before their test                      | Reports        |
-| `secrets`            | `canon secrets scan`                | Credential-shaped values in the shipped tree                                       | Gates          |
-| `labels`             | `canon labels audit`                | Changed paths no row of the label map reaches                                      | Reports        |
-| `restated`           | `canon gov restated`                | Instructions `CLAUDE.md` states that a second surface states too                   | Reports        |
-| `rules`              | `canon gov audit`                   | Rules past a shape limit, and here rules short of a ledger or out of step with one | Reports        |
-| `counts`             | `canon gov counts`                  | Sentences stating a closed catalog's size that disagree with the tree              | Reports        |
-| `census`             | `canon census`                      | File count, extension breakdown, and line total                                    | Reports        |
-| `deps`               | `canon deps audit`                  | Advisories against the resolved dependencies                                       | Reports        |
-| `outside`            | `canon gov citations`               | Rule citations and internal frontmatter globs reaching nothing                     | Gates in check |
-| `outside`            | `canon gov superseded <old> <new>`  | Where the tree still asserts a value a changed convention no longer produces       | Reports        |
-| `outside`            | `canon claude skills drift <ref>`   | Shipped skill bodies rewritten since a ref                                         | Reports        |
-| `outside`            | `canon claude routing`              | Per `CLAUDE.md` section, how many bullets name a path and whether a rule covers it | Reports        |
+| Id                   | Verb                                | Measures                                                                                    | Finding        |
+| -------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------- | -------------- |
+| `context`            | `canon context audit`               | Context folder structure, citations, and the requirements record's word cap                 | Gates          |
+| `markdown`           | `canon markdown audit`              | Bans, dead links, density, and reference shape                                              | Gates          |
+| `skills`             | `canon claude skills audit`         | Both skill corpora against the skill standards, and any ledger under `canon/ledger/skills/` | Gates          |
+| `skills-reach`       | `canon claude skills reach`         | Skill bodies citing a path no target receives                                               | Reports        |
+| `skills-rank`        | `canon claude skills rank`          | Whether skill descriptions separate against a routing case corpus                           | Reports        |
+| `tasks`              | `canon tasks validate`              | Board rows nothing resolves                                                                 | Reports        |
+| `records-plans`      | `canon records validate plans`      | Plan records against their shape                                                            | Reports        |
+| `records-groundwork` | `canon records validate groundwork` | Groundwork folders against their shape                                                      | Reports        |
+| `records-intake`     | `canon records validate intake`     | Intake folders against their shape                                                          | Reports        |
+| `comments`           | `canon comments scan`               | Comment density by language and kind, and `TODO`, `FIXME`, `HACK`, `XXX`                    | Reports        |
+| `test-order`         | `canon gov test-order`              | Implementations that reached branch history before their test                               | Reports        |
+| `secrets`            | `canon secrets scan`                | Credential-shaped values in the shipped tree                                                | Gates          |
+| `labels`             | `canon labels audit`                | Changed paths no row of the label map reaches                                               | Reports        |
+| `restated`           | `canon gov restated`                | Instructions `CLAUDE.md` states that a second surface states too                            | Reports        |
+| `rules`              | `canon gov audit`                   | Rules past a shape limit or out of step with a ledger, and here rules short of one          | Reports        |
+| `counts`             | `canon gov counts`                  | Sentences stating a closed catalog's size that disagree with the tree                       | Reports        |
+| `census`             | `canon census`                      | File count, extension breakdown, and line total                                             | Reports        |
+| `deps`               | `canon deps audit`                  | Advisories against the resolved dependencies                                                | Reports        |
+| `outside`            | `canon gov citations`               | Rule citations and internal frontmatter globs reaching nothing                              | Gates in check |
+| `outside`            | `canon gov superseded <old> <new>`  | Where the tree still asserts a value a changed convention no longer produces                | Reports        |
+| `outside`            | `canon claude skills drift <ref>`   | Shipped skill bodies rewritten since a ref                                                  | Reports        |
+| `outside`            | `canon claude routing`              | Per `CLAUDE.md` section, how many bullets name a path and whether a rule covers it          | Reports        |
 
 A deliberate secret takes a `canon-allow-secret: <reason>` marker. A deliberate citation takes `canon-allow-citation: <reason>` and a deliberate superseded value takes `canon-allow-superseded: <reason>`, each on its own line or the one above. Run any verb with `--help` for its flags and refusal reasons.
 

package/docs/agents/migrate.md

@@ -21,7 +21,7 @@ kind: reference
 | `record-layout`    | Review receipts, memory archives, feedback, renders, picks, evidence, and the design board into their current folders |
 | `session-defaults` | The seeded session defaults into an existing `.claude/settings.json`, listed below the table                          |
 
-`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies `Agent`, `Task`, and both merge commands, and turns auto memory off. The bullets below add detail per verb.
+`record-tree` follows citations in `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`. `session-defaults` denies `Agent`, `Task`, and both merge commands, turns auto memory off, and wires an installed `plan-guard.sh` into the PreToolUse hooks. The bullets below add detail per verb.
 
 - `skill-names` takes no `--scope`, and skips the changelog, eval transcripts, replay fixtures, and the pointer each renamed `draft-` skill leaves at its old name
 - `surface-roots` moves `context/`, `wireframes/`, `ARCHITECTURE.md`, `REQUIREMENTS.md`, `DESIGN.md`, and the stamp folder, and leaves `rules/`, `skills/`, `hooks/`, and `settings.json` in place
@@ -56,15 +56,15 @@ Three markers keep an old spelling on a line. Each also covers the nearest non-b
 
 ## Refusals
 
-| Verb               | Refuses when                                                                          |
-| ------------------ | ------------------------------------------------------------------------------------- |
-| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.        |
-| `records`          | A record folder already exists at the destination                                     |
-| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan                |
-| `scratch-evidence` | A destination is occupied                                                             |
-| `record-layout`    | A destination already exists, each move refused on its own                            |
-| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply.   |
-| `session-defaults` | The settings file is not valid JSON, or `permissions` or its `deny` has another shape |
+| Verb               | Refuses when                                                                                              |
+| ------------------ | --------------------------------------------------------------------------------------------------------- |
+| `records`          | The project does not ignore `.canon/`. Run `canon tooling sync --write` first.                            |
+| `records`          | A record folder already exists at the destination                                                         |
+| `surface-roots`    | Any destination already exists under `canon/`, refusing the whole plan                                    |
+| `scratch-evidence` | A destination is occupied                                                                                 |
+| `record-layout`    | A destination already exists, each move refused on its own                                                |
+| `rule-layout`      | A destination holds different bytes. Neither file is touched and other moves apply.                       |
+| `session-defaults` | The settings file is not valid JSON, or `permissions`, `deny`, `hooks`, or `PreToolUse` has another shape |
 
 A `rule-layout` destination holding the same bytes marks a duplicate, which `--write` deletes.
 

package/docs/migrations/by-verb.md

@@ -108,6 +108,8 @@ It moves each surface with `git mv` and repoints every tracked citation. No othe
 
 The seeded `.claude/settings.json` now denies the `Agent` and `Task` tools and both merge commands, and sets `autoMemoryEnabled` to `false`. `canon claude sync` never rewrites a settings file you hold, so it warns while the file holds no default or lacks a merge entry. Removing `Agent` and `Task` later draws no warning.
 
+The plan guard takes two steps. `canon claude init` adds the absent `.claude/hooks/plan-guard.sh`, and the verb below then wires it into `hooks.PreToolUse` for `Bash` and `Write|Edit`. It skips a tool whose matcher already runs the guard, and wires nothing while the script is absent.
+
 ```bash
 canon migrate session-defaults --json
 canon migrate session-defaults --write --json

package/docs/target/index.md

@@ -10,6 +10,7 @@ Scaffold, sync, and migrate a toolkit-managed project, with worked setups for th
 
 ## Agent surface
 
+- [Outside tools](outside-tools.md): The two tools canon's media skills reach but do not own, which skill uses each, how to install both through the canon-media bundle, and what keeps them current
 - [Target projects](projects.md): Scaffold, add domains later, and sync upstream drift in a toolkit-managed project
 - [Target scenarios](scenarios.md): Worked setups for a markdown-heavy project, a web application, and a monorepo
 - [Target sync](sync.md): Check what drifted in a toolkit-managed project and pull it in, per domain or all at once, and update canon itself

package/docs/target/outside-tools.md

@@ -0,0 +1,39 @@
+---
+title: Outside tools
+description: The two tools canon's media skills reach but do not own, which skill uses each, how to install both through the canon-media bundle, and what keeps them current
+category: Agent surface
+---
+
+# Outside tools
+
+Two canon skills hand work to a tool canon does not ship. Plain `canon` installs neither, so a machine that never films the app or picks a design never pulls them in.
+
+| Tool        | Used by       | What it does there                                         |
+| ----------- | ------------- | ---------------------------------------------------------- |
+| HyperFrames | `ui-film`     | Composes, captions, and renders the takes `ui-film` films  |
+| Frameboard  | `design-pick` | Serves the board the design arms are drawn on and selected |
+
+A skill checks that its tool is present and names the install when it is missing. It never installs or updates a tool itself. `ui-film` films the takes either way and stops at the handoff when HyperFrames is absent.
+
+## Install both
+
+The `canon-media` plugin carries no skills of its own. It depends on `canon`, `hyperframes`, and `frameboard`, so installing it installs all three. Add the three marketplaces first, since Claude Code resolves a dependency only from a marketplace you have added:
+
+```bash
+claude plugin marketplace add https://github.com/erclx/canon
+claude plugin marketplace add heygen-com/hyperframes
+claude plugin marketplace add erclx/frameboard
+claude plugin install canon-media@canon
+```
+
+Inside a session, `/plugin install canon-media@canon` does the same once the marketplaces are added. Restart Claude Code, or run `/reload-plugins`, to load the skills.
+
+To take one tool alone, install `hyperframes@hyperframes` or `frameboard@frameboard` from its own marketplace instead of the bundle.
+
+## Keep them current
+
+Neither tool is pinned. Claude Code's plugin manager owns each plugin's updates, and ships auto-update off for a third-party marketplace, so turn it on once per marketplace under `/plugin` in the Marketplaces tab. Updating by hand runs the same two steps per plugin that [target sync](sync.md) gives for canon.
+
+- HyperFrames runs its CLI through the plugin's own launcher at the plugin's version, so updating the plugin moves the CLI with it
+- `design-pick` uses a `frameboard` binary on your PATH when one is there, and otherwise runs `bunx -y frameboard` at the latest published release
+- A standalone copy of the HyperFrames skills under `~/.claude/skills/` updates apart from the plugin and can lag its layout, so remove it once the plugin is installed

package/docs/workflow/skill-map.md

@@ -24,6 +24,7 @@ Groups run in the order a project meets them. Every name `canon claude skills li
 | `canon:backlog-triage`     | The backlog needs pruning                          |
 | `canon:plan-groundwork`    | The state is unmeasured and approaches compete     |
 | `canon:decision-escalate`  | Open decisions turn on your preference             |
+| `canon:proposal-critique`  | A proposal needs questioning before it is built    |
 | `canon:design-pick`        | The call is taste, wanting candidates side by side |
 | `canon:task-board`         | A decided item needs a file on the board           |
 | `canon:plan-feature`       | The approach is settled and needs a plan           |

package/governance/detect.toml

@@ -20,6 +20,10 @@
 deps = []
 files = [".claude/skills", "claude/skills"]
 
+["rule"]
+deps = []
+files = [".claude/rules/project"]
+
 ["ci-workflow"]
 deps = []
 files = [".github/workflows"]

package/governance/ledger/claude/rule.md

@@ -0,0 +1,16 @@
+---
+title: Rule rule ledger
+description: Decisions behind governance/rules/claude/rule.md, one row per bullet
+---
+
+# Rule rule ledger
+
+The rule is a core rule, so every row is a house choice rather than a citation. Each names what goes wrong without its bullet and the option the bullet beat, with the date it was decided.
+
+## Rule files
+
+| Bullet                          | Source                                                                                                                                                                                          | Read       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load create-rule before an edit | House choice: a session hand-editing rules without the skill shipped defects `canon gov audit` passed (issue 2842). It beat relying on the audit alone                                          | 2026-10-29 |
+| Report an unresolved skill      | House choice: a project that installed governance without the plugin has no `create-rule`, and a silent skip hides that. It beat omitting the line                                              | 2026-10-29 |
+| Audit each touched rule         | House choice: the audit catches the shape and ledger defects the skill's checklist names, so running it before the commit closes the loop. It beat leaving the audit to the pre-push gate alone | 2026-10-29 |

package/governance/ledger/skills/build-in-slices/SKILL.md

@@ -0,0 +1,55 @@
+---
+title: Build in slices skill ledger
+description: Sources for claude/skills/build-in-slices/SKILL.md, one row per bullet in its concern groups
+---
+
+# Build in slices skill ledger
+
+The field is software delivery practice. Google's engineering practices carry small changes, Fowler's continuous integration article carries reverting to a good build, and Addy Osmani's `incremental-implementation` skill carries the cycle and the slicing order.
+
+The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+The house rows route a rule through this toolkit's own surfaces, being `git-commit`, the task's findings, and a ship chain's verify gate, where no outside source takes a side. `references/adopted.md` stays the record of what was adopted and declined at the source level.
+
+## Run the cycle per slice
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Implement through `test-first`  | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Implement the smallest complete piece of functionality", then "write a test if none exists". [Google, Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html): "A CL that adds or changes logic should be accompanied by new or updated tests for the new behavior." | 2026-10-28 |
+| Run every check it could affect | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Run each verification command after a change that could affect it."                                                                                                                                                                                                                             | 2026-10-28 |
+| Commit through `git-commit`     | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "save your progress with a descriptive message". Routing it through `git-commit` and staging only the slice's files is a House choice: a whole-tree commit sweeps a second slice's edits into the first, which no later revert can split                                                         | 2026-10-28 |
+| Carry forward from the commit   | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Move to the next slice", then "carry forward, don't restart"                                                                                                                                                                                                                                    | 2026-10-28 |
+
+## Choose the next slice
+
+| Bullet                         | Source                                                                                                                                                                                                                                                                                                                                                       | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| One path through every layer   | [Google, Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html): "you can instead break down your code into smaller, full-stack, vertical features." [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Build one complete path through the stack" | 2026-10-28 |
+| Riskiest piece first           | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Tackle the riskiest or most uncertain piece first", since "If Slice 1 fails, you discover it before investing in Slices 2 and 3."                                                               | 2026-10-28 |
+| Contract first, then each side | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Slice 0: Define the API contract (types, interfaces, OpenAPI spec)", with the backend and frontend built against it as slices 1a and 1b                                                         | 2026-10-28 |
+| File list as scope, not order  | House choice: a plan lists its files by path, and building them in that order builds one layer at a time, the order the slicing rules above exist to replace                                                                                                                                                                                                 | 2026-10-28 |
+
+## Keep each commit safe to revert on its own
+
+| Bullet                         | Source                                                                                                                                                                                                                                                                                                                                                                                                                | Read       |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One logical change per commit  | [Google, Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html): "The CL makes a minimal change that addresses just one thing." [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Each increment changes one logical thing."                                                                               | 2026-10-28 |
+| Test with or ahead of its code | [Google, Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html): "CLs should include related test code."                                                                                                                                                                                                                                                                                  | 2026-10-28 |
+| No delete and replace in one   | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Avoid deleting something in one commit and replacing it in the same commit", then "separate them"                                                                                                                                                        | 2026-10-28 |
+| Narrow edits to existing code  | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Modifications to existing code should be minimal and focused". [Fowler, Continuous Integration](https://martinfowler.com/articles/continuousIntegration.html): "Usually the best way to fix the build is to revert the latest commit from the mainline," | 2026-10-28 |
+
+## Note what you notice, and leave it
+
+| Bullet                             | Source                                                                                                                                                                                                                                                                                                                                                                                   | Read       |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One line under the task's findings | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "If you notice something worth improving outside your task scope, note it". The task's `## Findings` as the place is a House choice: a note left in the session's output dies with the session                               | 2026-10-28 |
+| The handover when no task exists   | House choice: a file created to hold a finding is a task with no row on the board, so nobody schedules it. It beat the source's offer to "create tasks for these", which a worker may not do                                                                                                                                                                                             | 2026-10-28 |
+| Leave the file, even for one line  | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "Touch only what the task requires." [Google, Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html): "It's usually best to do refactorings in a separate CL from feature changes or bug fixes." | 2026-10-28 |
+| Fix it only when the plan needs it | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "After each increment, the project must build and existing tests must pass." Saying so in the commit is a House choice: an unexplained out-of-scope hunk reads to review as scope creep                                      | 2026-10-28 |
+
+## Run a check when the code under it changed
+
+| Bullet                           | Source                                                                                                                                                                                                                                                                                                           | Read       |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Re-run after an edit it can see  | [addyosmani/agent-skills, Incremental Implementation](https://github.com/addyosmani/agent-skills/blob/2686b620/skills/incremental-implementation/SKILL.md): "After a successful run, don't repeat the same command unless the code has changed since", since "re-running on unchanged code adds no information." | 2026-10-28 |
+| A chain's verify step still runs | House choice: read unscoped, the source's note lets a session skip a ship gate's verify on a resumed run, where the gate is the only check reading the tree as it now stands. It beat applying the note to every run                                                                                             | 2026-10-28 |

package/governance/ledger/skills/proposal-critique/SKILL.md

@@ -0,0 +1,66 @@
+---
+title: Proposal critique skill ledger
+description: Sources for claude/skills/proposal-critique/SKILL.md, one row per bullet in its steps
+---
+
+# Proposal critique skill ledger
+
+The field is judgment and decision-making, plus red teaming doctrine. Kahneman, Lovallo, and Sibony carry the question set and independence, Klein the premortem, Bezos the scaling, and the UK Ministry of Defence handbook the devil's advocate.
+
+A row opening `House choice` states a rule no source makes. `## Output` and `## What this delegates` restate the steps or route, so they take no table.
+
+## Guards
+
+| Bullet                          | Source                                                                                                                                                                                     | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Stop when no proposal is named  | House choice: a critique of a guessed proposal answers questions nobody asked                                                                                                              | 2026-10-28 |
+| Critique only what is not built | [Klein, 2007](https://hbr.org/2007/09/performing-a-project-premortem): those with reservations "may speak freely at the outset, so that the project can be improved rather than autopsied" | 2026-10-28 |
+| Write nothing into the record   | House choice: a plan's sections belong to its validator, and the operator decides what moves into a record                                                                                 | 2026-10-28 |
+
+## Step 1: read the proposal
+
+| Bullet                                | Source                                                                                                                                                                                                                                                           | Read       |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Say it was read from the conversation | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): "What you see is all there is", so the reader names what it saw                                                        | 2026-10-28 |
+| Say when this session wrote it        | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): "the individuals using this quality screen should be completely independent from the teams making the recommendations" | 2026-10-28 |
+| Read the requirements record          | House choice: the goal and non-goal questions need the record that states them                                                                                                                                                                                   | 2026-10-28 |
+
+## Step 2: size the critique
+
+| Bullet        | Source                                                                                                                                                                                                                                   | Read       |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Reversibility | [Bezos, 2016 letter](https://www.aboutamazon.com/news/company-news/2016-letter-to-shareholders): "Many decisions are reversible, two-way doors. Those decisions can use a light-weight process"                                          | 2026-10-28 |
+| Reach         | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): "This approach is not designed for routine decisions that an executive formally rubber-stamps" | 2026-10-28 |
+
+## Step 3: ask in both directions
+
+| Bullet                          | Source                                                                                                                                                                                                                                                                                 | Read       |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| What does it solve, who hits it | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): the third group of questions is "aimed at evaluating the proposal"                                                                           | 2026-10-28 |
+| Which goal, which non-goal      | House choice: a requirements record states goals and non-goals, and a proposal crossing one is decided there                                                                                                                                                                           | 2026-10-28 |
+| Is the cause ours               | House choice: a fix for an upstream fault ships as ours unless the evidence separating the two is named first                                                                                                                                                                          | 2026-10-28 |
+| The strongest rival explanation | [UK MoD Red Teaming Handbook, 2021](https://assets.publishing.service.gov.uk/media/61702155e90e07197867eb93/20210625-Red_Teaming_Handbook.pdf): "Team members should adopt the role of devil's advocate"                                                                               | 2026-10-28 |
+| Where the numbers came from     | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): "Do you know where the numbers came from?" and "Which numbers in this plan are facts and which are estimates?"                               | 2026-10-28 |
+| What doing nothing costs        | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): "Is the base case overly optimistic?"                                                                                                        | 2026-10-28 |
+| Around the cause or into it     | House choice: a retry into an upstream failure repeats it, which only a question about the mechanism catches                                                                                                                                                                           | 2026-10-28 |
+| Has its mechanism worked once   | House choice: a mechanism never seen working, such as a cache that never saved, is a guess the fix rests on                                                                                                                                                                            | 2026-10-28 |
+| Is it too cautious              | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): "Is the recommending team overly cautious?", since "excessive conservatism is a source of less visible but serious chronic underperformance" | 2026-10-28 |
+| Assume it shipped and failed    | [Klein, 2007](https://hbr.org/2007/09/performing-a-project-premortem): "the premortem operates on the assumption that the 'patient' has died, and so asks what did go wrong"                                                                                                           | 2026-10-28 |
+| The cheapest reversible probe   | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): "what information would you want, and can you get more of it now?"                                                                           | 2026-10-28 |
+| When to stop mitigating         | House choice: a mitigation chain with no end point set in advance keeps adding fixes after each one fails                                                                                                                                                                              | 2026-10-28 |
+
+## Step 4: route what evidence cannot answer
+
+| Bullet                                   | Source                                                                                                                                                                                                  | Read       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One batch through the question surface   | House choice: `decision-escalate` owns the batch shape, so a preference question takes its form rather than a second one                                                                                | 2026-10-28 |
+| Hold the verdict when an answer moves it | [Bezos, 2016 letter](https://www.aboutamazon.com/news/company-news/2016-letter-to-shareholders): "most decisions should probably be made with somewhere around 70% of the information you wish you had" | 2026-10-28 |
+
+## Step 5: give one verdict
+
+| Bullet      | Source                                                                                                                                                                                | Read       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Go          | [Bezos, 2016 letter](https://www.aboutamazon.com/news/company-news/2016-letter-to-shareholders): "If you're good at course correcting, being wrong may be less costly than you think" | 2026-10-28 |
+| Probe first | [Kahneman, Lovallo, and Sibony, 2011](https://thecne.org/wp-content/uploads/2016/04/The-Big-Idea_-Before-You-Make-That-Big-Decision.pdf): "can you get more of it now?"               | 2026-10-28 |
+| Absorb      | House choice: a fix costing more than the problem it removes is declined with its reason recorded                                                                                     | 2026-10-28 |
+| Stop        | House choice: a problem not shown or a cause not ours leaves the fix nothing to act on                                                                                                | 2026-10-28 |

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

@@ -0,0 +1,54 @@
+---
+title: Search craft skill ledger
+description: Sources for claude/skills/search-craft/SKILL.md, one row per bullet in its concern groups
+---
+
+# Search craft skill ledger
+
+The field is information literacy and research methods. ACRL's framework carries how a searcher picks producers and judges authority, and Wineburg and McGrew's study of fact checkers carries reading past the ranking. Caulfield's SIFT carries tracing a claim to its origin, while Anthropic's tool docs carry the domain filter.
+
+The closing sections and `## What this delegates` restate these rules or route, so they take no table.
+
+The access note's Reddit and X rows record refusals, so they are measurements re-run on the date in `Read` rather than citations. Its last row cites a source like any other.
+
+## Name the field
+
+| Bullet                        | Source                                                                                                                                                                                                                               | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Name the field before a query | [ACRL Framework, Searching as Strategic Exploration](https://www.ala.org/acrl/standards/ilframework): learners "match information needs to appropriate search tools and information producers"                                       | 2026-10-28 |
+| At a practitioner's level     | [ACRL Framework, Searching as Strategic Exploration](https://www.ala.org/acrl/standards/ilframework): learners "distinguish between different types of searching language (e.g., controlled vocabulary, keywords, natural language)" | 2026-10-28 |
+| Say the field in the output   | House choice: an answer from a search run in the wrong field reads the same as a wrong fact unless the output names where it looked. It beat reporting the sources alone                                                             | 2026-10-28 |
+
+## Derive who the field trusts
+
+| Bullet                                  | Source                                                                                                                                                                                                                                                                                | Read       |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Ask what kind of body settles it        | [ACRL Framework, Authority Is Constructed and Contextual](https://www.ala.org/acrl/standards/ilframework): "authority is a type of influence recognized or exerted within a community", and learners "identify different types of authority"                                          | 2026-10-28 |
+| Derive the names, never a list          | House choice: a remembered list of sites per category rots with nobody noticing, and reading one skips the test of what kind of body the field trusts. It beat a per-category directory, declined in `references/adopted.md`                                                          | 2026-10-28 |
+| Search for the authorities first        | [Wineburg and McGrew, Lateral Reading and the Nature of Expertise](https://stacks.stanford.edu/file/druid:yk133ht8603/Wineburg%20McGrew_Lateral%20Reading%20and%20the%20Nature%20of%20Expertise.pdf): "before diving deeply into unfamiliar content, chart a plan for moving forward" | 2026-10-28 |
+| Each new question derives its own names | [ACRL Framework, Authority Is Constructed and Contextual](https://www.ala.org/acrl/standards/ilframework): "the information need of the individual or community may help to determine the form of authority required"                                                                 | 2026-10-28 |
+
+## Search twice
+
+| Bullet                                  | Source                                                                                                                                                                                                                                                                                                                                                      | Read       |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The same query scoped and open          | [Wineburg and McGrew, Lateral Reading and the Nature of Expertise](https://stacks.stanford.edu/file/druid:yk133ht8603/Wineburg%20McGrew_Lateral%20Reading%20and%20the%20Nature%20of%20Expertise.pdf): fact checkers "knew that the first result was not necessarily the most authoritative", since optimizers push "more authoritative sites to the bottom" | 2026-10-28 |
+| Prefer the scoped side, and say so      | House choice: a silent pick hides which source a fact rests on, so a reader cannot re-check the disagreement. It beat keeping whichever result ranked higher                                                                                                                                                                                                | 2026-10-28 |
+| The open result for what is unpublished | [Wineburg and McGrew, Lateral Reading and the Nature of Expertise](https://stacks.stanford.edu/file/druid:yk133ht8603/Wineburg%20McGrew_Lateral%20Reading%20and%20the%20Nature%20of%20Expertise.pdf): reading laterally means "drawing on the resources of the Internet to learn more about a site and its claims"                                          | 2026-10-28 |
+| Check every scoped result's domain      | [Anthropic, Server tools, Domain filtering](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools): "Subdomains are automatically included (`example.com` covers `docs.example.com`)", and Unicode names "can bypass domain filters through homograph attacks"                                                                         | 2026-10-28 |
+| Fetch the page where summaries differ   | [Caulfield, SIFT (The Four Moves)](https://hapgood.us/2019/06/19/sift-the-four-moves/): "we'll have you trace the claim, quote, or media back to the source"                                                                                                                                                                                                | 2026-10-28 |
+
+## Prefer a structured source
+
+| Bullet                                | Source                                                                                                                                                                                                           | Read       |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A public API over a summarized page   | [Crossref REST API](https://www.crossref.org/documentation/retrieve-metadata/rest-api/): "Our publicly available REST API exposes the scholarly metadata that members and trusted sources deposit with Crossref" | 2026-10-28 |
+| A plain request rather than a wrapper | [claude-research-stack](https://github.com/aghori3004/claude-research-stack): "The skill talks to the CLIs and MCPs directly, on purpose", listing "No wrapper scripts" among what it leaves out                 | 2026-10-28 |
+
+## Access note
+
+| Bullet                          | Source                                                                                                                                                                                                       | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Reddit refuses keyless routes   | House choice, measured: `curl` on `/r/programming/.rss` and on `/search.json` both returned 403, and `WebFetch` answered that it is "unable to fetch from www.reddit.com"                                    | 2026-10-28 |
+| X answers nothing without login | House choice, measured: `curl` on `/search` returned 307 to `/i/jf/onboarding/web` with `mode=login`, and `WebFetch` returned "HTTP 402 Payment Required"                                                    | 2026-10-28 |
+| Ask before a route that pays    | [x-research-skill](https://github.com/rohunvora/x-research-skill): "Each search page returns up to 100 posts = ~$0.50/page", a spend that is the operator's to authorize rather than one a session discovers | 2026-10-28 |

package/governance/ledger/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,64 @@
+---
+title: Systematic debugging skill ledger
+description: Sources for claude/skills/systematic-debugging/SKILL.md, one row per step and bullet in its concern groups
+---
+
+# Systematic debugging skill ledger
+
+The field is software debugging, with reliability engineering for a cause outside the code. Most rows cite the `obra/superpowers` skill this one was ported from, and `addyosmani/agent-skills` adds the non-reproducible tree. Git's docs, Zeller's Debugging Book, and the SRE book cover bisect, reduction, and retry.
+
+The closing sections restate these rules, so they take no table. `references/adopted.md` stays the record of what was adopted and declined at the source level.
+
+## Phase 1: investigate
+
+| Bullet                                     | Source                                                                                                                                                                                                                                                         | Read       |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Read every line of the output              | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Read stack traces completely", noting "line numbers, file paths, error codes"                    | 2026-10-28 |
+| Reproduce, by the likely cause             | [agent-skills](https://github.com/addyosmani/agent-skills/blob/2686b620fc1fed2e8f60c704839c766b8594c6b6/skills/debugging-and-error-recovery/SKILL.md): its non-reproducible tree splits on "Timing-dependent?", "Environment-dependent?", "State-dependent?"   | 2026-10-28 |
+| Check what changed, bisecting a regression | [git-bisect](https://git-scm.com/docs/git-bisect): "uses a binary search algorithm to find which commit in your project's history introduced a bug"                                                                                                            | 2026-10-28 |
+| Instrument each component boundary         | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Run once to gather evidence showing WHERE it breaks", then "investigate that specific component" | 2026-10-28 |
+| Trace a bad value to its source            | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Keep tracing up until you find the source" and "Fix at source, not at symptom"                   | 2026-10-28 |
+
+## Phase 2: reduce and find the pattern
+
+| Bullet                              | Source                                                                                                                                                                                                                                      | Read       |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Reduce to the smallest failing case | [The Debugging Book, Reducing Failure-Inducing Inputs](https://www.debuggingbook.org/html/DeltaDebugger.html): a minimum "not only eases debugging" but explains "why and when the program fails"                                           | 2026-10-28 |
+| Compare against working code        | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Locate similar working code in same codebase"                                 | 2026-10-28 |
+| Read a reference completely         | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "read reference implementation COMPLETELY", and "Don't skim - read every line" | 2026-10-28 |
+| List every difference               | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "List every difference, however small", and "Don't assume "that can't matter"" | 2026-10-28 |
+
+## Phase 3: hypothesize and test
+
+| Bullet                              | Source                                                                                                                                                                                                                                          | Read       |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| State one specific hypothesis       | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "State clearly: "I think X is the root cause because Y"", "Be specific, not vague" | 2026-10-28 |
+| The smallest change, one variable   | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Make the SMALLEST possible change to test hypothesis", "One variable at a time"   | 2026-10-28 |
+| A new hypothesis, not a stacked fix | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Didn't work? Form NEW hypothesis" and "DON'T add more fixes on top"               | 2026-10-28 |
+| Say what you do not understand      | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Say "I don't understand X"" and "Don't pretend to know"                           | 2026-10-28 |
+
+## Phase 4: fix
+
+| Bullet                             | Source                                                                                                                                                                                                                                            | Read       |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A failing test before the fix      | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): the failing test case is one you "MUST have before fixing"                           | 2026-10-28 |
+| One change at the root cause       | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "ONE change at a time", "No "while I'm here" improvements", "No bundled refactoring" | 2026-10-28 |
+| The test passes and nothing breaks | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Test passes now?" and "No other tests broken?"                                      | 2026-10-28 |
+
+## Three-fix circuit breaker
+
+| Bullet                               | Source                                                                                                                                                                                                                               | Read       |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Each fix reveals a new problem       | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Each fix reveals new shared state/coupling/problem in different place" | 2026-10-28 |
+| Each fix needs refactoring elsewhere | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Fixes require "massive refactoring" to implement"                      | 2026-10-28 |
+| Symptoms keep moving                 | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Each fix creates new symptoms elsewhere"                               | 2026-10-28 |
+
+## When the cause is external or not found
+
+| Bullet                              | Source                                                                                                                                                                                                                                                                  | Read       |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Document what was ruled out         | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): for a cause that is "truly environmental, timing-dependent, or external", "Document what you investigated" | 2026-10-28 |
+| Log for the next occurrence         | [superpowers, Systematic Debugging](https://github.com/obra/superpowers/blob/8ca22dba9a94f28898bbce59f2537ff4d87c747d/skills/systematic-debugging/SKILL.md): "Add monitoring/logging for future investigation"                                                          | 2026-10-28 |
+| Ask whether handling routes around  | House choice: CI retried a degraded package mirror when the fix that fit was routing around it. It beat naming retry first                                                                                                                                              | 2026-10-28 |
+| Ask whether a retry meets the fault | [SRE book, Addressing Cascading Failures](https://sre.google/sre-book/addressing-cascading-failures/): "the retries themselves may be keeping the backend in an overloaded mode"                                                                                        | 2026-10-28 |
+| Count what absorbing costs          | House choice: a retry kept a degraded package mirror on CI's path, and each rerun paid its time and spend. It beat retry by default                                                                                                                                     | 2026-10-28 |

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

@@ -0,0 +1,28 @@
+---
+title: Test first skill ledger
+description: Sources for claude/skills/test-first/SKILL.md, one row per step and bullet in its concern groups
+---
+
+# Test first skill ledger
+
+The field is test-driven development. Kent Beck states the loop, Martin Fowler makes its refactor step mandatory, and `obra/superpowers` carries the failure check the loop runs before writing code. `## What this delegates` routes, so it takes no table.
+
+`references/adopted.md` stays the record of what was adopted and declined at the source level.
+
+## The loop
+
+| Bullet                                  | Source                                                                                                                                                                                                                                                            | Read       |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| The test before the code it covers      | [Fowler, TestDrivenDevelopment](https://martinfowler.com/bliki/TestDrivenDevelopment.html): "Write a test for the next bit of functionality you want to add", ahead of "Write the functional code until the test passes"                                          | 2026-10-28 |
+| The behavior to come, named as proved   | [obra/superpowers, Test-Driven Development](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/SKILL.md): a good test "Demonstrates desired API", and its "Name describes behavior" where `test('test1')` does not                   | 2026-10-28 |
+| A failure for the missing behavior      | [obra/superpowers, Test-Driven Development](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/SKILL.md): confirm the test "Fails because feature missing (not typos)", and on an error "Fix error, re-run until it fails correctly" | 2026-10-28 |
+| The smallest change that passes         | [obra/superpowers, Test-Driven Development](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/SKILL.md): "Write simplest code to pass the test", and "Don't add features, refactor other code, or "improve" beyond the test"        | 2026-10-28 |
+| The pass it was written for, then suite | [Beck, Canon TDD](https://newsletter.kentbeck.com/p/canon-tdd): "Change the code to make the test (& all previous tests) pass", where "delete assertions so the test pretends to pass" is a mistake                                                               | 2026-10-28 |
+| Refactor with the suite green           | [Fowler, TestDrivenDevelopment](https://martinfowler.com/bliki/TestDrivenDevelopment.html): "Refactor both new and old code to make it well structured", since "The most common way that I hear to screw up TDD is neglecting the third step"                     | 2026-10-28 |
+
+## Extending existing behavior
+
+| Bullet                              | Source                                                                                                                                                                                                                                                                       | Read       |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| A changed assertion fails first     | [obra/superpowers, Test-Driven Development](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/SKILL.md) applies the loop "Always" to "Behavior changes", under "If you didn't watch the test fail, you don't know if it tests the right thing" | 2026-10-28 |
+| A pass before any change is no test | [obra/superpowers, Test-Driven Development](https://github.com/obra/superpowers/blob/5bf4e78/skills/test-driven-development/SKILL.md): "Test passes? You're testing existing behavior. Fix test."                                                                            | 2026-10-28 |