@erclx/canon 5.44.0 → 5.46.0

package/claude/skills/code-craft/REQUIREMENT.md

@@ -7,42 +7,28 @@ description: Why a session writing code needs stated rules on the shape of a fun
 
 ## Gap
 
-Without this skill, nothing in the toolkit shapes code at the moment it is written. `test-first` runs the loop around the code, `codebase-layout` places the file, `api-design` shapes what a caller sees, and the core code rule holds placement, error, and naming floors. The shape of a function, a class, or a module's internals is left to whatever the neighboring code suggests.
+Nothing shapes code at the moment it is written. The loop, the file's placement, and the caller's contract each have an owner, and the shape of a function, a class, or a module's internals is left to whatever the neighboring code suggests.
 
-Agents fail there in recorded ways. Birgitta Böckeler's two articles on agentic coding name them: code that is copied rather than reused, a lack of modularity that spreads one change across files, features and business logic nobody asked for, assumptions filled in where the requirement was silent, and brute-force fixes that silence a symptom rather than its cause. Each reads fine in its own diff and costs the next change.
-
-Before this skill, two shipped pointers left interface depth unowned. `api-design` declined depth and the internals behind a boundary, and `codebase-layout` named depth as having no owner, so a session routed away from either on that question landed nowhere. Both now point here.
+Agents fail there in recorded ways. They copy where reuse belonged, spread one change across files, build features nobody asked for, fill in assumptions, and patch a symptom by brute force. Each reads fine in its own diff and costs the next change.
 
 ## Must
 
-- Open with the change test: name the change most likely to come next and count what it would touch before choosing a shape
-- State depth as rules a session can act on: a unit earns its place when its interface is simpler than what it does, a pass-through is inlined, and a module splits by the decision it hides rather than by processing step
-- State each tension as when one side wins: one piece of knowledge in one place against coupling two things that only look alike, building only what is asked against seams that ease change, and one reason to change against over-decomposition
-- List patterns by their wrong case, short enough to stay in the body, with a plain function named as the usual replacement for the class
-- State hidden inputs: pass in the clock, the environment, randomness, and globals, keep business rules free of transport and storage code, and skip ports and adapters for a thin read-and-write application
-- Close the concern groups with the agent failure modes as checks on the session's own diff: a copy where a refactor belonged, one responsibility scattered across files, a feature nobody asked for, an assumption filled in rather than asked, and a brute-force fix
-- Record the external sources adopted and declined with the reason for each, so a later session extends the position instead of re-deriving it
-- Close with a table of the excuses a session gives for a shape that costs the next change, each with its rebuttal, the red flags a session can see in its own work mid-task, and a checklist each line of which answers yes or no against the code the change produced
+- Open with the change test, naming the change most likely to come next and counting what it would touch before choosing a shape
+- State depth as rules a session can act on, covering a unit's interface being simpler than its work, inlined pass-throughs, and splitting by the decision hidden
+- State each tension as when one side wins, such as one place for knowledge against coupling two things that only look alike
+- State hidden inputs: pass in the clock, environment, and randomness, and keep business rules free of transport and storage code
+- Close with the agent failure modes as checks on the session's own diff, with excuses, red flags, a checklist, and the external sources adopted and declined with the reason for each
 
 ## Must not
 
-- Restate a definition a model already holds, such as what coupling or a design pattern is
-- State a tension as one side only, such as "never duplicate"
+- Restate a definition a model already holds, state a tension as one side only, or shape code for a change nobody can name
 - Name a language, a framework, or a type system feature in the body
-- Restate the red, green, refactor loop `test-first` runs, or the design review procedure `review-craft` carries for a finished diff
-- Restate error or naming bullets. The core code rule retired them on purpose, and the error shape lives in `api-design`.
-
-## Guards
-
-- A change filling in a body whose shape is already fixed skips the skill
-- A shape is never chosen for a change nobody can name, since that shape is a guess
+- Restate error or naming bullets, which the core code rule and `api-design` carry
 
 ## Out of scope
 
-- Where a new file sits on disk: `codebase-layout`
-- The red, green, refactor loop: `test-first`
-- Which layer a test belongs at: `test-craft`
-- The contract a caller depends on, being its exports, flags, output, errors, and versioning: `api-design`
-- Judging a finished diff, including a design review of it: `review-craft`
-- Service architecture and layering beyond the one hidden-inputs bullet kept here
-- Whether the guidance changes what a session ships, which needs a measured with-and-without run rather than a rule here
+- Where a new file sits on disk, which `codebase-layout` owns
+- The red, green, refactor loop, which `test-first` owns
+- Which layer a test belongs at, which `test-craft` owns
+- The contract a caller depends on, which `api-design` owns
+- Judging a finished diff, which `review-craft` owns

package/claude/skills/codebase-layout/REQUIREMENT.md

@@ -7,44 +7,27 @@ description: Why the session writing a new path into a plan needs placement guid
 
 ## Gap
 
-Without this skill, the session that decides where a new file goes has nothing about layout in front of it when it decides. The planner writes each new path into the plan, the worker copies it, and the planner's only instruction on the tree is to measure against it, which for a new path reads as copying the flat folder beside it.
+The session that decides where a new file goes has nothing about layout in front of it. The planner writes each new path into the plan and the worker copies it, so a new path copies the flat folder beside it and a source folder grows flat until a split touches dozens of files.
 
-The failure is measured on a real target. Two source folders grew from 11 files to 46 and 36 flat files in six days, with the constitution's directory line and a stack rule mandating feature folders both installed throughout. The split that followed touched 98 files, and the end to end folder is flat again, four specs beside five helpers. Archived plans from the same project name every new file as a literal flat path.
-
-Sharpening the rules does not reach the decision. Both were loaded and neither was applied, since an always-loaded line competes with everything else a session holds and a path-scoped rule fires on a read of an existing file rather than on a path written into a plan.
-
-A placement rule in front of the session is also one it can argue past. Each flat file in that target landed for a reason that sounded fine in the moment, such as the neighbors already being flat or a split reading as scope creep, and nothing answered the reason before the path was written.
+Sharpening the rules does not reach the decision. An always-loaded line competes with everything else a session holds, and a path-scoped rule fires on a read of an existing file rather than on a path written into a plan. Each flat file also lands for a reason that sounds fine, such as the neighbors already being flat.
 
 ## Must
 
-- Be loaded by `plan-feature` whenever a plan names a path that does not exist yet, so the guidance is in front of the planner at the moment it writes the path
-- Tell the session to name and keep to the project's existing layout strategy before placing a file, since two strategies in one tree cost every reader a guess
-- State the split trigger as a second role entering a folder, with a file count only as a prompt to look
-- State colocation with the one consumer and promotion on the second, and imports flowing from shared toward features toward the app entry
-- Require a one-clause placement reason on every new path the plan names
-- State that a file is named for what it covers inside its folder, never repeating the folder's name as its stem or its prefix, since a name placed beside its neighbor copies the neighbor's prefix along with its folder
-- Hold the stack-neutral core in the body and defer category specifics to a reference loaded only when a new path falls in that category
-- Record the external layouts adopted and declined with the reason for each, so a later session extends the position instead of re-deriving it
-- Close with a table of the excuses a session gives for placing a file beside its neighbor, each with its rebuttal, the red flags a session can see while writing a path, and a checklist each new path passes before the plan is handed over
-- Fire on a direct question about placement as well, such as where a file goes or whether a flat folder should split, since a session outside any plan still places files
+- Load whenever a plan names a path that does not exist yet, and on a direct question about placement
+- Keep to the project's existing layout strategy, naming it before placing a file, and propose a strategy change as its own decision
+- Split a folder when a second role enters it, with a file count only as a prompt to look, and colocate with the one consumer until a second promotes the file
+- Give every new path a one-clause placement reason, and name a file for what it covers rather than repeating its folder
+- Hold the stack-neutral core in the body, with category specifics in a reference, then close with excuses, red flags, a checklist, and the external sources adopted and declined with the reason for each
 
 ## Must not
 
-- Name a framework or runner in the body. Stack specifics live in the references.
-- Carry a hard file-count threshold. A command folder holding sixty files of one role reads fine flat, and a number would fail it.
-- Restate the layer rule, the layer table, or the final filter `test-craft` owns
-- Mandate one layout across projects, such as a `features/` tree, over the project's own strategy
-- Restate the pointer in `routing`, which loads in code stacks only. The rule points here and this body carries the depth.
-
-## Guards
-
-- A plan that only edits existing files does not load the skill, so the cost lands only where a placement is decided
-- A strategy change is proposed as its own decision rather than made while placing one file
+- Name a framework or runner in the body, or carry a hard file-count threshold
+- Mandate one layout across projects over the project's own strategy
+- Restate the layer rule that `test-craft` owns, or the pointer the routing rule carries
 
 ## Out of scope
 
-- Which layer a test belongs at: `test-craft`
-- Interface depth, seams, and where a module boundary sits in code, which govern a module's shape rather than its path on disk. What crosses that boundary is `api-design`, and depth is `code-craft`.
-- Per-language placement conventions such as test suffixes and the top-level test folder: the language testing rules
-- Backend, asset, and script layouts, which wait for a driving project before a reference is written
-- Whether a plan that loaded the skill actually places files differently, which needs a measured run on a target rather than a rule here
+- Which layer a test belongs at, which `test-craft` owns
+- What crosses a module boundary, which `api-design` owns
+- Interface depth and seams inside a module, which `code-craft` owns
+- Per-language placement conventions, which the language testing rules own

package/claude/skills/context-fold/REQUIREMENT.md

@@ -7,53 +7,29 @@ description: What the context-entry fold is for, the gaps it closes, and why it
 
 ## Gap
 
-Without this skill, the context entries describe the repository the session opened with. An entry keeps listing a folder the diff moved and a trap the diff fixed, so it states what the repository used to be.
+The context entries describe the repository the session opened with. An entry keeps listing a folder the diff moved and a trap the diff fixed. A fold doing everything at ship time buries the one step a caller asked for under board marking, receipt sweeps, and the design record.
 
-The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the context folder the request was about goes untouched.
-
-The opposite gap opened from the same write. A fold allowed to touch the requirements record on every ship rewrote it one reasonable edit at a time, and nothing read it for whether it still stated the project's identity. Each ship looked correct and the sum drifted.
-
-A fold that did everything at ship time hid its own job. It marked board outcomes, swept receipts, wrote the design record, and landed promoted pages, so a session invoking it to refresh the context entries ran ten steps and could not tell which one it had asked for.
-
-This skill writes canonical docs at the end of a long build. An appended figure, a branch-narrated re-measurement, or an entry pushed past its length lands unchecked the same way a session's own edits do, so what the fold produces carries the exact defect the standards it cites already ban.
+"Sync the docs" names either corpus, so a description leaving its corpus to the opening clause loses the request to its sibling. A fold rewriting the requirements record each ship drifts its identity. Appended figures and over-length entries land unchecked at the end of a long build.
 
 ## Must
 
-- Name the context entries in a trigger phrase rather than in the opening clause alone, so a bare request to sync the docs separates this skill from `docs-sync` on something both descriptions state
-- Take the refresh scope from the diff, and from the session only the requirements or direction change the report names
-- Write tracked docs at the current worktree root, since only that copy commits with the branch
-- Write an entry only when the diff adds, moves, or removes a folder, makes a folder's bullet untrue, or changes a trap, and never write a decision, which the pull request records
-- Report a requirements or direction change in one line naming `document-health`, rather than writing it, so the identity record changes only when the operator reviews it
-- Close on an audit of what the fold touched, running `canon context audit` and reporting the findings on files this run wrote or the diff carries
-- Classify the fold's whole diff baseline through `canon context classify diff`, calling the verb rather than reimplementing its pattern or its prompt in the skill body, since an earlier commit on the branch carries a doc edit the fold is equally responsible for
-- Apply a `REPLACE` or `HISTORY` finding against the quote it names, report a `MOVE` finding naming the surface it belongs on rather than cutting it, or keep a finding with a one-line reason, rather than leaving a finding unanswered
-- Rewrite a restated or superseded statement in place rather than appending the replacement beside it
-- Report a refusal or a missing `context audit` or `context classify` subcommand as one line and continue the fold either way, since a check that cannot run is not a reason to leave the fold's own output unshipped
+- Name the context entries in a trigger phrase, so a bare request to sync the docs separates this skill from `docs-sync`
+- Take the refresh scope from the diff and write tracked docs at the current worktree root, only when the diff adds, moves, or removes a folder, falsifies a bullet, or changes a trap
+- Report a requirements or direction change in one line naming `document-health` rather than writing it
+- Close on `canon context audit` and `canon context classify diff` over the fold's whole baseline, reporting findings on files this run wrote or the diff carries
+- Apply a `REPLACE` or `HISTORY` finding against its quote, report a `MOVE` with its surface rather than cutting it, and continue the fold when a check cannot run
 
 ## Must not
 
-- Write the task board, the design record, `CLAUDE.md`, or a page from a promotion handoff. Each has its own owner, and a fold that writes them hides its job behind theirs.
-- Widen what the refresh reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
-- Write the requirements record. It states identity, and a fold reads one session where a review reads the whole project.
-- Create a context entry for a domain the catalog does not list
-- Report an audit finding on an entry this run never touched, which belongs to whoever next edits it
-- Add a path flag to the audit verb from this skill. It takes a project root, so the skill filters the record.
-- Pick or configure a classifier backend. The project setting decides it, and this skill reports the resolved `modelLayer` as returned.
-- Stop the fold on an audit or classify finding, a refusal, or a missing subcommand. All of them report and continue.
-- Apply a finding against a quote found more than once or not found at all. Report that it could not be located instead of guessing.
-- Re-run the classifier after applying a finding, which loops it over its own edit
-- Cut a `MOVE` finding. The verdict means correct content sitting on the wrong surface rather than a deletion candidate, so cutting one can discard content that belongs elsewhere rather than removing detail that never belonged at all.
-- Scope the classifier to the files Step 3 wrote this run. An earlier commit on the branch carries a doc edit the fold is equally responsible for, and the verb's own extraction already answers whether anything in range qualifies.
-
-## Guards
-
-- Neither a `canon/` nor a `.claude/` directory: stop and name the command that sets one up
-- No direction change in the session and no diff a context entry could describe: stop with a pass, since both conditions have to hold
+- Write the task board, the design record, `CLAUDE.md`, the requirements record, or a promoted page
+- Create an entry for a domain the catalog does not list, or report a finding on an entry this run never touched
+- Pick a classifier backend, re-run the classifier after a fix, or apply a finding whose quote is not found exactly once
+- Stop the fold on a finding, a refusal, or a missing subcommand
 
 ## Out of scope
 
-- Marking a shipped task's outcomes, sweeping review receipts, and archiving a task, which `task-complete` owns
-- Landing a page a teach promotion handoff carries, which `teach-workspace` owns in its fold mode
+- Marking outcomes, sweeping receipts, and archiving a task, which `task-complete` owns
+- Landing a teach promotion page, which `teach-workspace` owns
 - Creating or declining a task file, which `task-board` owns
-- Public-facing docs, which `docs-sync` owns. Both descriptions name their corpus in the trigger so a request saying only "sync the docs" lands on one of the pair rather than on either.
-- Regenerating the context catalog, which a commit hook runs
+- Public-facing docs, which `docs-sync` owns
+- Regenerating the context catalog, which a commit hook owns

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

@@ -71,13 +71,13 @@ An entry carries three H2 sections and no other, being `Overview`, `Layout`, and
 
 Layout gives each folder doing real work its own H3, titled with the folder path in a code span, such as ``### `src/design/` ``.
 
-- Open the H3 with a lead of one short paragraph stating what the folder does
-- Follow it with at most five bullets on what the folder does now
+- Open the H3 with a one-paragraph lead stating what the folder does, then at most five bullets on what it does now
 - Put every trivial folder under `### Other folders` as a one-line bullet in owns-X form
 - Name folders only, never files, and write no decisions and no history under any H3
+- Give each folder under the code roots one H3 or `Other folders` line, since a second entry may cite it but never claims it
 - Write no heading below H3 under `## Layout`
 
-The audit reports a Layout H3 titled neither a path nor `Other folders`, a folder H3 holding a second paragraph or a sixth bullet, and any H4 under Layout. Bullets count at any indent and across any paragraph, so a list split by a bold label still counts as one list.
+The audit reports a Layout H3 titled neither a path nor `Other folders`, a folder H3 holding a second paragraph or a sixth bullet, and any H4 under Layout. Under `--gate` it also fails a code folder no Layout names. Bullets count at any indent and across any paragraph, so a list split by a bold label still counts as one list.
 
 ### Ordering and headings
 

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

@@ -7,25 +7,17 @@ description: Why a project-local rule needs a subdir, a slug free in it, and a s
 
 ## Gap
 
-Without this skill, a project rule is written straight into the rules folder under a name already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a name free in the target today could be the name a shipped rule landed on tomorrow, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that collision whatever the name, since the sync engine orphans the file by location before it ever compares names, and leaves only a slug taken in the same project subdir to check.
+Without this skill, a project rule is written into the rules folder under a name already taken, or one a shipped rule claims later and overwrites. Writing under `.claude/rules/project/` closes that by location, leaving only a slug taken in the same subdir to check.
 
-The subdir gets picked by feel, so a UI copy rule lands in the always-on folder and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
+The subdir gets picked by feel, so a UI copy rule loads on every session. The scope key fails both ways, and a body written from memory drifts from the rule standard's shape. A rule restating what canon ships duplicates it, and one committed unseen lands before the operator read it.
 
 ## Must
 
-- Resolve what the rule enforces and where it applies, asking only for what the request leaves missing
-- Pick the subdir from the topic and take the folder from that choice
-- Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
-- Take a slug no rule in the chosen project subdir uses and that equals no subdir name
-- Read the rule standard before writing the body
-- Hold the body to the rule standard's shape limits on words, bullets, sections, and bullet length
-- Apply the content test, leaving out what Claude already knows, what the toolchain enforces, and what changes often
-- Check the installed skills for one already covering the topic and point the rule at it, skipping the check when none are listed
-- Run every written bullet through the checklist and fix what fails before reporting
-- Tell the user to cite a source in the commit that adds a rule claiming outside practice
-- Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
-- Preview the resolved path, subdir, slug, and frontmatter, then write without pausing
-- Say when the rule loads, since path-scoped and always-on rules behave differently
+- Resolve what the rule enforces and where it applies, asking only for what the request leaves missing, and stop when it names no behavior
+- Write under `.claude/rules/project/` in a subdir picked from the topic, with a slug no rule in that subdir uses, and propose a narrower slug when it is taken
+- Read the rule standard before writing, then hold the body to its shape limits and content test and run every bullet through its checklist before reporting
+- Emit the path scope for a path-scoped rule and omit the key for an always-on one, say when the rule loads, then write and show the diff, leaving the commit to the operator's OK
+- Check what canon ships and the installed skills for one already covering the topic and point the rule at it, and tell the user to cite a source in the commit when the rule claims outside practice
 
 ## Must not
 
@@ -34,14 +26,8 @@ The subdir gets picked by feel, so a UI copy rule lands in the always-on folder
 - Overwrite a project rule already holding the slug
 - Write more than one topic into a single rule
 
-## Guards
-
-- No project Claude directory: stop, since there is nowhere for the rule to live
-- The request names no behavior to enforce: stop rather than inventing one
-- The topic's slug is taken in the chosen subdir: stop and propose a narrower one
-
 ## Out of scope
 
-- Editing a rule that already exists
-- Toolkit source rules, which are authored in the toolkit rather than in a target
-- Installing the rules the toolkit ships, which the governance setup path owns
+- Editing a rule that already exists, which the rule standard governs
+- Toolkit source rules, which the toolkit authors rather than a target
+- Installing the rules the toolkit ships, which `target-setup` owns

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

@@ -22,6 +22,7 @@ Resolve both from the request, and ask only for what is missing. Attach a propos
 
 - What the rule enforces: one topic, phrased as a standard (`<topic> conventions`).
 - Scope: a path glob relative to the project root (`<dir>/**/*.<ext>`) for a path-scoped rule, or always-on when the rule states a global principle with no file scope.
+- Whether canon already ships a rule for the topic, read from `canon gov list --rules --json`. When one does, point the user at it and at `canon gov install --add` rather than authoring a copy.
 - An installed skill already covering the topic, found per `### Checking the installed skills` in `${CLAUDE_SKILL_DIR}/references/rule.md`. Point the rule at it rather than restating it.
 
 ## Step 2: resolve the subdir
@@ -86,3 +87,5 @@ Read `${CLAUDE_SKILL_DIR}/references/checklist.md` and run every bullet of the w
 ## After writing
 
 Emit the full path on its own line: `.claude/rules/project/<subdir>/<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session. When a bullet claims outside practice, tell them to cite its source in the commit that adds the rule.
+
+Show the new rule as a diff in chat and commit nothing until the operator says OK.

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

@@ -7,37 +7,26 @@ description: What skill creation is for, the gaps it closes, and why it confirms
 
 ## Gap
 
-Without this skill, a new skill lands in the wrong shape and the wrong place. A session writes `SKILL.md` from its own idea of the format, writes malformed frontmatter that Claude Code routes on, and never opens the authoring standard that already answers every question it guessed at.
+Without this skill, a new skill lands in the wrong shape and place. A session writes `SKILL.md` and its frontmatter from its own idea of the format and never opens the authoring standard. With no requirement beside it, a later sweep must reconstruct what the skill was for.
 
-A skill born without its requirement is the second failure, and it surfaces much later. Coverage of the corpus is what the operator reads to decide whether a skill should exist, so every skill created without the sibling decays that reading, and the sweep that closes the gap has to reconstruct what the skill was for from the body it already shipped.
-
-A third failure is a folder created for a moment a rule, a verb, or an existing skill already reaches, or for a procedure no session would get wrong from first principles. Nothing caught that before the folder existed, so the corpus grew by a skill an inward audit later had to argue for removing, with only a commit body recording the argument.
-
-A fourth failure is dated provenance in the body. A target asked for an edit citing a measurement taken that day, and the draft carried "measured on" and the date inline, with the authoring standard, the markdown audit, and this skill all passing it. A body collecting those notes reads as history rather than as the rule a session follows.
-
-A fifth failure is the confirmation itself. A worker running a plan that adds a skill reached Step 4, asked a person nobody had dispatched, and the chain parked on a question nobody read. The same description named only the `.claude/skills/` root, which is where a target authors and where a toolkit checkout keeps its `internal-*` skills, but not where its plugin skills live.
+Nothing checks the folder before it exists, so a skill appears for a moment a rule, a verb, or a sibling already reaches. Bodies collect dated provenance. The confirm step stalls an unattended run, and a checkout keeps internal and plugin skills in different roots.
 
 ## Must
 
-- Read the authoring standard and the prose standard before drafting, so the draft starts conformant rather than getting corrected into shape
-- Answer, in writing, whether a rule, a verb, or an existing skill already reaches this moment, and whether the body carries a procedure a session would get wrong from first principles. A folder that fails either belongs to the surface that already covers it, not to a new skill.
-- Draft the sibling `REQUIREMENT.md` beside the body, from what the skill is for rather than from the drafted body
-- Confirm the name and both files with the user before writing, where a person is present to answer. The name is the routing key and a folder that disagrees with its frontmatter fails silently. Where nobody is present, record the three answers and both paths in the output and write.
-- Write to the conventional skills path, so discovery finds it without configuration. That is `.claude/skills/` in a target project. In the toolkit's own checkout, which the project root's `claude/.claude-plugin/plugin.json` marks, an `internal-*` skill goes under `.claude/skills/` and a plugin skill under `claude/skills/`
-- Leave the skills audit's dated-provenance check clean for the new folder before reporting it, with each incident cut and left to git
+- Read the authoring standard and the prose standard before drafting
+- Answer in writing whether a rule, a verb, or a skill already reaches this moment, and whether a session would get the procedure wrong unaided, since a folder failing either belongs elsewhere
+- Draft the sibling `REQUIREMENT.md` beside the body from what the skill is for, never from the drafted body
+- Confirm the name and both files before writing where a person is present, and where nobody is, record the three answers and both paths in the output and write
+- Write to the conventional skills path for the project, and leave the skills audit's dated-provenance check clean for the new folder before reporting
 
 ## Must not
 
-- Auto-trigger. Creation is a deliberate act and a skill invented from an ambiguous request is worse than none.
+- Auto-trigger, since creation is a deliberate act and a skill invented from an ambiguous request is worse than none
 - Write either file before the user has seen it, where a user is present
 - Derive the requirement from the drafted body, which records the draft's overfitting as the requirement
-- Gate creation on whether anything will invoke the new skill beyond the author typing its name. That question has no answer yet.
-
-## Guards
-
-- The authoring standard is not installed: stop and name the command that installs it
+- Gate creation on whether anything will invoke the new skill beyond the author typing its name
 
 ## Out of scope
 
 - Editing an existing skill, which the authoring standard and the skill's own requirement govern
-- Whether anything ends up invoking the new skill: the usage census the toolkit's own context entry tracks, read once the skill has run
+- Whether anything ends up invoking the new skill, which the toolkit's usage census owns

package/claude/skills/decision-escalate/REQUIREMENT.md

@@ -7,38 +7,26 @@ description: Scope boundary for handing a decision back to the operator, and the
 
 ## Gap
 
-Without this skill, a session facing a decision that belongs to the operator asks about it one question at a time across several turns, so the operator answers each without knowing how many are open and cannot trade one against another. It asks in prose with no options attached, so the operator has to invent the alternatives before picking one. It names an option and omits what the other one buys, so the pick is made blind. It escalates a call it could have settled from the repository or from its own judgment, which spends the operator's attention on work the session owed.
+A session facing a decision that belongs to the operator asks one question per turn, so the operator cannot see how many are open or trade one against another. It asks in prose with no options, omits what the other option buys, or escalates a call the repository could settle.
 
-It also empties a long backlog into one turn, so the questions past the first few arrive in no order and the operator cannot tell which ones the work is actually stalled on. It carries on with work the unanswered questions govern, so an answer arrives against output already built the other way. It takes the answer, acts, and leaves the plan, task, or record that posed the question reading as open, so the next session re-asks a decision the operator already made.
-
-A body written around a named tool fails a third way. A session on a surface carrying no structured question tool reads an instruction it cannot execute and falls back to whatever it would have done unaided, which is the per-decision ask this file exists against.
-
-The opposite failure is the one that ships silently. A session that takes a preference decision itself produces work the operator did not ask for and never learns a choice was made, because nothing in the output says a fork was passed.
-
-`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The second branch now states how a question is shaped and where it is put, so this skill inherits both and adds only what a batch needs on top of one question.
+It carries on with work the open questions govern, or acts on an answer and leaves the record that posed it reading open, so the next session re-asks. Where the named tool is absent it falls back to the per-decision ask. Taking a preference decision itself ships silently.
 
 ## Must
 
-- Collect every open decision before asking any of them, so the operator sees the set rather than the first one
-- Put the whole batch in one turn, since a batch split across turns is the per-decision ask this skill exists to replace
-- Give each question a short axis header and two to four options, taking the shape of an option from `CLAUDE.md` rather than restating it
-- Test the surface rather than the project's instruction file when choosing where the batch goes, so a target whose `CLAUDE.md` predates the rule still reaches the tool and loses only the shape
-- Cap a batch at four questions and say how many are held, since a structured question tool takes four and an uncapped batch hides the overflow
-- Hold every escalated decision until it is answered, and continue only the work depending on none of them
-- Route a pick that changes a written artifact into that artifact under the standard owning it, rather than leaving it in the session
+- Collect every open decision before asking, and put the whole batch in one turn
+- Give each question a short axis header and two to four options shaped as `CLAUDE.md` states, capped at four questions with the held count said
+- Test the surface rather than the project's instruction file when choosing where the batch goes
+- Hold every escalated decision until answered, and continue only work depending on none of them
+- Route a pick that changes a written artifact into that artifact under the standard owning it
 
 ## Must not
 
 - Answer on the operator's behalf, or treat the recommendation as the answer because no reply arrived
-- Escalate a decision the session can settle from its own judgment or from reading the repository, which is the first branch of the rule and belongs to the session
-- Escalate a decision already taken, which goes to the record that holds it rather than back to the operator
-
-## Guards
-
-- Nothing open, stop rather than manufacturing a question to justify the invocation
+- Escalate a decision settled by the repository or by the session's own judgment, or one already recorded
+- Manufacture a question when nothing is open
 
 ## Out of scope
 
-- Making the ordinary judgment call, which is a pick plus a one-sentence tradeoff and needs no surface
-- Writing the decision into a plan, task, or context entry, which each owning standard governs and this skill only routes to
-- Deciding when to fire. The description states `Do NOT auto-trigger`, so escalating is the operator's call rather than a description match.
+- The ordinary judgment call, which `CLAUDE.md` owns as a pick plus a one-sentence tradeoff
+- Writing the decision into a plan, task, or context entry, which each owning standard governs
+- Deciding when to fire, which the operator owns since the skill never auto-triggers

package/claude/skills/deploy-app/REQUIREMENT.md

@@ -7,38 +7,28 @@ description: What the deploy setup gap is on each host, which of the manual step
 
 ## Gap
 
-Without this skill, a deploy setup is a sequence performed from memory. Most of its repeated acts touch a service rather than the tree, so no workflow file can absorb them. One of those acts has already cost a broken deploy: the account ID displayed in the Cloudflare dashboard is truncated, and a value copied from there is wrong in a way that only shows up at deploy time. That is the Cloudflare instance of the general rule, that an ID comes from the host CLI's own session or files and never from a page a person copies out of.
+Without this skill, a deploy setup is a sequence performed from memory. Most of its acts touch a service rather than the tree, so no workflow file absorbs them, and an account ID copied from a host's dashboard can be truncated in a way that shows only at deploy time.
 
-The same sequence repeats on Vercel with different calls, so a skill per host would duplicate every guard and stop. Picking the wrong host is its own failure: a project mid-migration carries both hosts' files, and a silent pick creates a project on the account the operator was leaving.
+The sequence repeats on Cloudflare and Vercel with different calls, so a skill per host duplicates every stop. A project mid-migration carries both hosts' files, and a silent pick creates a project on the account the operator was leaving.
 
 ## Must
 
-- Pick the host from the signals the project already carries, and ask the operator when it carries none or both
-- Create the host's project through its own CLI: `wrangler pages project create` or `vercel project add` and `vercel link`
-- Fetch every account, org, or project ID from the host CLI's own session or files rather than have it typed or pasted
-- Stop for the operator to issue the API token and run `gh secret set` for it themselves
-- Verify every secret the host needs is present with `gh secret list` before continuing
-- Stop for the operator at the custom domain step, since DNS sits outside the tree
-- Call `wrangler`, `vercel`, and `gh` directly for every step those tools already cover
+- The host comes from the signals the project carries, and the operator is asked when it carries none or both
+- The host's project is created and every account, org, or project ID fetched through the host CLI's own session or files
+- The operator issues the API token and runs `gh secret set` themselves, and every secret the host needs is confirmed with `gh secret list` before continuing
+- The run stops for the operator at the custom domain step
+- `wrangler`, `vercel`, and `gh` are called directly for every step they cover, each confirmed authenticated first
 
 ## Must not
 
-- Accept an API token as input in any form. The toolkit verifies a secret exists, never what it contains.
-- Take an ID from the operator rather than from the host CLI's own session or files
+- Accept an API token as input in any form
+- Take an ID from the operator
 - Default to a host when the signals are absent or disagree
-- Reimplement a host CLI call or `gh secret set` as a hand-built API call
 - Seed a deploy workflow for Vercel, whose git integration already deploys on push
 - Open a pull request or merge
 
-## Guards
-
-- `wrangler` or `vercel` not authenticated: stop and name the login command
-- `gh` not authenticated: stop and name the login command
-- A secret missing after the token stop: stop and name which one
-
 ## Out of scope
 
-- Attaching a custom domain through the Cloudflare REST API instead of the dashboard. Measured absent from `wrangler pages` at plan time and the REST API was not read, so the dashboard stop stays for this pass.
-- Running the deploy itself once secrets and the domain are set. On Cloudflare that is the seeded `deploy.yml` workflow, triggered by a push to main. On Vercel it is the git integration.
-- A Vercel `tooling/` stack or a CI-gated Vercel deploy workflow.
-- Reconfiguring an existing project's build settings on either host.
+- Running the deploy once secrets and the domain are set, which the seeded workflow or the host's git integration owns
+- The workflow structure around a deploy job, which `ci-workflow` owns
+- A Vercel tooling stack, a domain attached through the REST API, or reconfiguring an existing project's build settings, which no skill owns yet

package/claude/skills/deprecation-migration/REQUIREMENT.md

@@ -7,56 +7,28 @@ description: Why a session retiring code needs stated rules for deciding to depr
 
 ## Gap
 
-Without this skill, nothing in the toolkit tells a session how to retire a function, a flag, a file, or a command. No skill folder carries the topic, and the terms strangler and expand-then-contract appear in no skill, rule, or standard. The persistence rule covers only the destructive half of a schema change, and `api-design` stops at adding a new name beside an old one and removing the old one once no caller reads it, without saying how a session proves that or who moves the callers.
+Nothing tells a session how to retire a function, a flag, a file, or a command. The persistence rule covers only the destructive half of a schema change, and `api-design` stops at adding a new name beside an old one, without saying how a session proves the old one unused or who moves the callers.
 
-The toolkit retires its own surfaces often, and three observed cases show the failure the gap allows:
-
-- A record folder moved from a flat sibling to a nested layout while one known consumer still sat on the old layout with no checkout reachable to migrate it. The expand step shipped and the contract step had no owner or date.
-- A skill kept a fallback beside a new command "until a release retires it", a compatibility path with no stated removal condition.
-- A sync engine reported entries a source had stopped shipping as retired, leaving each consumer to decide what to do with them, which is a deprecation announced without the owner migrating anyone.
-
-Each excuse row in the body traces to one of these cases or to a source in the ledger:
-
-- Fallback row: the second case
-- Migrate-later and one-machine rows: the first and third cases
-- Notice row: the deprecation chapter of Software Engineering at Google
-- No-owner row: the upstream skill's zombie-code section
-- Search row: the upstream skill's red flag against removing code without verifying zero consumers
-- Add-and-drop row: the upstream skill's rationalization for adding a column and dropping the old one in one migration
+The result is an expand step with no contract step behind it, a fallback kept "until a release retires it" with no removal condition, and a deprecation announced while every consumer is left to migrate alone.
 
 ## Must
 
-- State the decision to deprecate as four questions, being what keeping it costs, who calls it, what replaces it, and who migrates the callers, and keep the surface when they do not add up
-- Separate advisory from compulsory, and allow compulsory only once a replacement has shipped and a removal date is stated where a caller looks
-- State the Churn Rule: the owner of a surface migrates its callers rather than announcing and waiting
-- Require a zero-consumers check across every caller kind before removal, being imports, string references, configuration, documentation, and copies outside the repository, and require the report to name the kinds the search could not reach rather than reporting zero
-- Name the adapter and the strangler as the two bridges, with when each fits
-- State expand, migrate, and contract as three separate changes, never letting the contract step share a change with the expand step
-- Treat zombie code as a decision between removal and ownership, settled by the same zero-consumers check
-- Record the external sources adopted and declined with the reason for each
-- Close with a table of the excuses a session gives for removing early or leaving a deprecation open, the red flags it can see mid-task, and a checklist each line of which answers yes or no against the change
+- Decide to deprecate by four questions, being what keeping it costs, who calls it, what replaces it, and who migrates the callers
+- Separate advisory from compulsory deprecation, allowing compulsory only once a replacement has shipped and a removal date sits where a caller looks
+- Make the owner of a surface migrate its callers rather than announce and wait
+- Prove zero consumers across imports, string references, configuration, documentation, and outside copies before removal, naming any kind the search could not reach
+- Run expand, migrate, and contract as three changes, then close with excuses, red flags, a checklist, and the external sources adopted and declined with the reason for each
 
 ## Must not
 
-- Name a toolkit command, a toolkit-local path, or a project from the evidence, since the body ships to targets
-- State a numeric deprecation window, since a number fits one project's release cadence and not another's
-- Restate additive change or the One-Version Rule, which `api-design` owns
-- Restate the persistence rule's schema bullets
-
-## Guards
-
-- Code introduced on the same branch that nothing has shipped against skips the skill
-- A removal whose zero-consumers check left a caller kind unreached is reported with that kind named, never as clean
+- Name a toolkit command, a toolkit-local path, or a project, since the body ships to targets
+- State a numeric deprecation window
+- Restate additive change or the One-Version Rule, or the persistence rule's schema bullets
+- Report a removal as clean while a caller kind went unsearched
 
 ## Out of scope
 
-- Database schema migrations and their down paths: the project's persistence rule
+- Database schema migrations and their down paths, which the project's persistence rule owns
 - Release versioning and changelog format, which a release process owns
-- Whether a tooling sync removes a path a stack stopped shipping, which needs measuring before any rule is written
-- Moving or renaming a file with no caller change: `codebase-layout`
-- Adding a field, flag, or parameter beside an old one: `api-design`
-- Whether the guidance changes what a session ships, which needs a measured with-and-without run rather than a rule here
-
-## Measured
-
-Not yet run. The seeded arm holds a deprecated helper with one caller by import and one by string reference, and asserts the session finds both before deleting and leaves the helper while either remains. The with-and-without run waits on the operator authorizing the spend.
+- Moving or renaming a file with no caller change, which `codebase-layout` owns
+- Adding a field, flag, or parameter beside an old one, which `api-design` owns