@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/rule-consolidation.md

@@ -0,0 +1,118 @@
+# Rule consolidation & retirement
+
+Mechanics for the Core Rule *"Consolidate and retire rules; a skill's rule set must not grow monotonically."* A skill's rule TEXT (`SKILL.md` / references) is living — merged, tightened, retired in place — so a corrections-graveyard (every miss appends a parallel bullet, none ever removed) does not regrow. This file makes that safe and actionable; it does NOT loosen any gate.
+
+## At-add-time consolidation check (replaces a "periodic" cue)
+
+A "periodically run a pass" cue is dead-letter — nobody owns the calendar. Instead the check fires **when you add a rule**, and is recorded so the dual-track review can see it ran:
+
+- Before appending a new top-level rule to a `SKILL.md`/reference section, **grep that section for the new rule's mother-theme** (a distinctive phrase, e.g. `target-output map`, `dual-track`, `interim`).
+- Record exactly one outcome in the commit body / source-register row:
+  - `consolidation: merged into <surviving anchor>` — an existing rule owned the theme; you merged/tightened it or added a sub-bullet under it instead of a parallel bullet.
+  - `consolidation: no candidate (new theme)` — genuinely new failure-class; a new bullet is justified.
+- A new top-level bullet with no recorded outcome is the defect; the dual-track review treats a missing line the same as a missing review row.
+- A separate full-section consolidation pass is still worth running at each deep self-audit, but it is opportunistic; the at-add-time check is the load-bearing gate.
+
+- **A rule written for a temporary condition carries its own retirement trigger.** When guidance is only right while some state holds — a pre-release stance ("no external consumers yet, so rename freely"), a migration window, a workaround for a tool version — write the condition and the removal action into the rule itself ("remove this section at the first tagged release" / "delete once <gate> lands"), so the next reader can retire it mechanically instead of rediscovering that it went stale; a temporary rule with no exit clause is monotonic growth by another name.
+- **Condensing an inline rule that already points at a reference must keep the load-bearing invariants inline.** A bounded diff reviewer (dual-track lanes see only the packet, never the referenced file) reads "see the checklist" as the invariants having vanished; keep the one-line list of the obligations that make the rule bite (what is forbidden, what must be human-authorized, what fails closed) and move only the procedure and examples.
+
+- **Entrypoint capacity is an INPUT to the target-output map, not an obstacle discovered afterwards.** Before the map assigns a landing, check each candidate owner's entrypoint budget (`scripts/check-size-budget.sh`; a `severe_debt` entrypoint blocks any net growth). A candidate at or over budget does not silently become "wrong owner" — the map records `capacity` explicitly and picks the landing form: merge into an existing canonical rule at zero/negative net words, land in a `references/` file the entrypoint **already** points at (no new pointer = no net growth), or route to a different owner whose scope genuinely covers the lesson. Skipping this makes the gate the decider: you draft into the natural owner, get blocked, and relocate under pressure — the relocation then reads as a judgment when it was a constraint, and the map's rationale column silently becomes false. Failure shape: a routing-condition rule drafted into a `severe_debt` router entrypoint, rejected by the size gate, then moved to a downstream skill and reported as the better owner — until a reviewer asked whether that owner was actually right. Record the capacity check as part of the map row, and when capacity forced the form, say so in the row rather than in the rationale.
+
+## Form-by-failure (choose the guidance form at drafting time)
+
+The at-add-time check above decides *where* a rule lands (merge vs new bullet); this section decides *what form* the text takes. Matching form to the baseline failure type is load-bearing: external head-to-head wording tests (superpowers `writing-skills` v6, micro-tested arms vs a no-guidance control) measured the prohibition form backfiring on output-shaping problems — clearly worse than the recipe arm (fully separated distributions), and trending worse than even the no-guidance control. This table is the ccl-layer distillation, kept so the rule stands alone on hosts without that pack; when `superpowers:writing-skills` is installed, it owns the fuller method (its form table + wording micro-test recipe) — re-check it on version bumps rather than growing this section.
+
+| Baseline failure | Right form | Wrong form |
+|---|---|---|
+| Agent knows the gate and walks past it under pressure (discipline slip — our merge-authorization / R0 / done-claim class) | Prohibition + rationalization-vs-reality pairs + red-flag self-check | Soft guidance ("prefer…", "consider…") |
+| Agent complies but the artifact's SHAPE is wrong (bloated review packet, buried verdict, register row restating the source) | Positive recipe/contract: state what the artifact IS — its parts, in order | A "don't"-list about the shape — the measured backfire above |
+| Agent omits a required element from an artifact it already produces (missing status/evidence cell, absent map row) | A REQUIRED slot in the template/validator it must fill (our closeout rows and register gate are this form) | Prose reminders near the template |
+| Behavior should differ by situation | Conditional keyed to an observable predicate ("fan-out → name the tier") | Unconditional rule + exemption clauses |
+
+The rows are not mutually exclusive — a real failure often carries several axes (e.g. a required field omitted only under pressure). Give each axis its own form **on its own target**: the discipline axis keeps a prohibition aimed at the *act of skipping/violating*; the shape axis gets the recipe/slot describing *what the output is*. Do NOT re-express the shape requirement as a prohibition merely because a discipline axis is also present — a "don't restate X"-style prohibition riding along with a recipe is exactly the measured backfire. (This combination guidance is an inference beyond the source's separately-tested arms; like any load-bearing form choice it is subject to the behavioral-evidence row below.)
+
+Two wording rules for whichever form wins:
+
+- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation — appending a single nuance clause to a winning recipe degraded it from consistent to noisy in the same tests. Write a real exception as its own conditional on an observable predicate.
+- **Exemption clauses don't scope.** "This limit doesn't apply to code blocks" still suppresses code blocks; if part of the output must be exempt, restructure the rule so it cannot reach that part.
+
+Boundary vs the owning Core Rule's salience mechanism: that rule governs how JOINT requirements are structured (walked enumeration at the firing point; merge-over-append); this table governs the form of a SINGLE rule's text once its landing spot is chosen. Provenance is external — adopt the principle, but transferred evidence does NOT exempt the change from the dual-track gate's mandatory behavioral-evidence row: for a behavior-shaping rule, the `RED-baseline` (recorded incident, or a constructed scenario run against BOTH the unchanged baseline and the changed rule — `dual-track-review-gate.md`) is exactly where the form choice gets tested on YOUR case, with the instrument scaled per `harness-patterns-and-eval.md` §3 (before-after / golden-trace for a single skill edit; the system-wide `skill-behavior-eval` fixture battery is ONLY for always-on layer changes, not routine rule edits). A prohibition chosen for an output-shaping failure, or a recipe replacing a prohibition, is a form choice the source measured as capable of backfiring — it must not land on transferred deltas alone.
+
+## Obligation-preservation table (required for any rewrite / retire)
+
+Any change that **rewrites or deletes** existing rule text, **or leaves any pre-existing obligation under a different governing chain** (see the row-set predicate below), must carry this table in the behavioral-evidence (`semantic-control`) row — durable, not chat-only. That second trigger is why "it's a pure append" is not by itself an exemption: appending a rule at the end of a section re-parents nothing and stays exempt, but *interposing* one between an existing host and the obligations beneath it silently re-parents them while deleting and rewriting nothing — so the exemption is decided by the governing-chain comparison below, not by whether the diff happens to be addition-only:
+
+| before obligation | old anchor (rule phrase/label) | after anchor | status | proof |
+|---|---|---|---|---|
+| <the gate/trigger/consequence the old rule imposed> | <distinctive phrase of the removed/edited rule> | <where it now lives — file AND the governing chain it now hangs under: immediate bullet through enclosing section> | `merged` / `subsumed` / `rehosted` / `retired-dead` | merged/subsumed: where it survives. `rehosted`: the obligation deliberately changed governing chain — record what the NEW host gains and what the OLD host loses, both sides separately. `retired-dead`: proof the trigger/source surface no longer exists, or the obligation is now impossible/invalid — not "we think it no longer matters" |
+
+Every obligation **selected by the row-set predicate below** gets a row. Keep the two sets distinct: the **comparison domain** is everything you must LOOK at (every pre-existing obligation in every changed file, plus every relocation destination), while the **row set** is the subset that survives the predicate — those whose governing chain differs or whose own text left a rewritten line. Untouched obligations in the domain are walked and found unchanged; they do not each owe a row. The challenge inspects this table for a silently-dropped guard; an unmapped obligation *from the row set* blocks landing.
+
+**The `after anchor` / "where it survives" cell must be a *verifiable pointer*, not an asserted location.** The agent that performed the merge is exactly the one whose "I preserved it at X" claim is least trustworthy, and a sibling challenge can wave through a confident-but-false one — so do not let "survives at X" rest on a reviewer happening to notice the lie. For a `merged`/`subsumed`/`rehosted` row, name a destination that mechanically exists and carries the obligation: either the surviving anchor's distinctive phrase is greppable at the named file/section (grep it and cite the hit in the `proof` cell), or — when the merge rephrased so no literal phrase survives — the row quotes the semantic carrier sentence verbatim from the after-text. **A `merged`/`subsumed`/`rehosted` row whose named destination does not exist, or exists but does not carry the obligation, is not a safe merge — it is silent data loss, and is reclassified as a dropped guard that blocks landing** (the same downgrade an autonomous skill-curator applies when a "consolidated into umbrella Y" claim is contradicted by Y being absent on disk: claimed-preserved-but-actually-gone counts as a prune, not a merge). The challenge **re-runs this existence check**, not just a read-through of the table.
+
+**Count the carriers, not just the destination — a `merged`/`subsumed`/`rehosted` row asserts exactly ONE afterwards.** The existence check above is satisfied by *at least one* carrier at the destination, so it passes in both directions of the wrong answer and cannot tell a real move from a copy: (a) the destination **already carried** the obligation before the change, so the "merge" appended a second statement of it — two copies now drift independently, which is the disease consolidation exists to cure; and (b) the origin text was **never actually deleted**, so the row says `subsumed` while the old prose sits where it always was, and the entrypoint never slims. Both read GREEN under a destination-only check. So each `merged`/`subsumed`/`rehosted` row's `proof` cell must record the carrier count **after** the change plus the survivor's governing chain, established by walking these four checks in order — they have to hold jointly, so walk them one at a time rather than eyeballing the destination once:
+
+1. Grep the obligation's distinctive phrase (**and** its rephrased carrier, when the merge reworded it) across the WHOLE package — not only at the named destination — and write the resulting hit count into the `proof` cell. **One phrase per row is sentence-granular while a sentence often carries two obligations — a base obligation plus a *strength-bearing qualifier* (a modality, recency, threshold, scope, actor, or consequence modifier: "**MUST**/never/required" vs "may/should", "dated *at or after the change under review*", "within N days", "by the resource owner", "before first release", "and the check must FAIL"). Modality is first in that list because it is the one a base-phrase grep never sees: `MUST be signed` → `may be signed` leaves base, actor, scope, and consequence all intact. When the before-obligation carries one, the row must grep that qualifier as its own phrase and record its own count, because the base phrase surviving at the destination is not evidence about the qualifier: a rewrite that keeps the obligation and silently drops its modifier reads GREEN on the base-phrase grep while the rule's strength falls (a "cite dated evidence" survivor no longer says *how recent*, so any old dated baseline now passes). Three bounds keep this from becoming a decompose-every-sentence tax that authors route around — the trigger, the set, and the unit are all fixed, not author-chosen: it fires only on a row whose after-text does **not** carry the before-sentence verbatim (a verbatim survivor already carries its own modifiers); the qualifier set is the closed six above, not "whatever reads important"; and the count is over the **base and qualifier co-occurring under one immediate host** — the same governing-chain unit check 4 uses, so a rewording that splits them across adjacent sentences beneath that host still counts — never the qualifier alone — bare `before first release` legitimately appears in unrelated rules and would fail check 2 on hits that are not carriers. So a reworded row costs one extra co-occurrence grep per modifier actually present (typically none to two), and a row with none records `no qualifier in the closed set` and moves on. **Each qualifier count enters check 2 as its own count — a base count of 1 does not discharge a qualifier count of 0, which is a dropped guard, not a green row.** And read the co-occurrence, don't just count it: a grep proves the qualifier is still *present*, never that it still *governs the base* — `MUST be dated at or after the change` weakened to `may be old, but the proof must state whether it is dated at or after the change` keeps every phrase and loses the guard. So count 0 is a mechanical RED, while count ≥1 is only a necessary condition that hands the row to the challenge's read of whether the modifier still binds what it used to bind. When a before-sentence's parts legitimately come to rest under **different hosts**, that is not one row with two proofs: split it, one row per destination, each then walked through checks 2-4 on its own.**
+2. Require that count to be exactly **1**, and cite the surviving hit. A count of 2+ is not a successful merge but a duplication to collapse before landing.
+3. Separately confirm the single carrier is **where the row says it is**. Checks 1-2 prove exactly one carrier exists; this one proves its location matches the disposition claimed. A row claiming the obligation MOVED must find it at the destination and **not** at the origin (a count of 1 still at the origin is a no-op mislabelled as a move). A row claiming it stayed and was rewritten, tightened, or extended in place must find it at the origin — the surviving text being a rewrite of the old wording, or the old wording plus more, is what that claim predicts, not a violation of it. Do **not** test this as "the old phrase must be gone": that holds only for the moved case, and applied to an in-place change it rejects every legitimate tightening and leaves it with no valid status. The invariant is agreement between claim and location; the same count means opposite things under different claims.
+4. Bind the survivor to its GOVERNING CHAIN, not merely to its file. Checks 1–3 are predicated on the sentence *alone*, so a survivor that came to rest under a **different obligation than the one it qualified** passes them whenever the count lands on 1. The invariant is the pair **`(governing chain, sentence)`**: the `proof` cell records the survivor's chain (immediate bullet through enclosing section) and requires it to be the obligation it qualified before. A clause that qualified rule A and now trails rule B has simultaneously **added an escape hatch to B and removed one from A** — two defects a single "it's still in the package" reading sails past.
+   - A deliberate chain change takes `rehosted`, which is exempt from **this check's same-chain equality assertion only**: checks 1-3 still bind it (two copies under the new host is the same duplication `merged` would be, wearing a different label), and it still owes a positive record of the chain it now hangs under. `merged`/`subsumed` assert the chain held and must fail here; `retired-dead` is false while the obligation lives.
+   - Only one of the two ways a chain can change has two sides. `rehosted` is for an obligation that **came to rest under a different host**, and owes the old-host-loss / new-host-gain pair. When instead the host was **rewritten underneath an obligation that did not move**, the obligation still owes a row — that is the nesting-closure case, and skipping it is how a widened parent silently widens its children — but its proof is the single question *does the rewritten host still support this qualifier*. Demanding the two-sided form there would charge a paragraph-opener edit one declaration per sentence beneath it, which the failure never justified.
+
+**The row set is derived from the DIFF, not from your move list — this is the check that fails first.** The four checks are only as good as the set you walk them over, and the recurring failure is a **missing row**, not a weak predicate: a table built from what the author *set out to relocate* has no row for a clause that changed host as a side effect of a neighbouring rewrite, and an unwalked obligation is unchecked however strong the predicate.
+
+So derive the row set from **each obligation's GOVERNING CHAIN, compared before against after** — the complete ordered set of normative ancestors it hangs under (immediate bullet, every enclosing bullet, the section), each taken by **normative content, not label, heading text, or position**. An obligation owes a row if its chain differs, or if its own text left a rewritten line. Two closure properties are why this replaces enumerating edit shapes rather than joining them: **closed under nesting depth** (rewriting a *grandparent*'s trigger/scope/strength earns rows for everything beneath it — effective strength is set by the whole chain), and **closed under edit shape** (an ancestor deleted, re-scoped, interposed, relabelled-but-rewritten, or a block moved between sections — several of which leave the obligation byte-identical, so no diff-of-removed-text scan can see them). An unchanged label is never evidence of an unchanged chain.
+
+Run it, don't eyeball it: `../scripts/governing-chain-diff.py` (this skill's `scripts/`, resolved from the skill root) computes the derived row set for a markdown file across two revisions, so the predicate is reproducible and the challenge's independent recomputation has something to run; `../scripts/test_governing_chain_diff.sh` pins its behaviour per edit shape and is registered in the repo regression lane. Its **comparison domain** is mechanical — **every pre-existing obligation in every changed file, plus every relocation destination** — never a window drawn around the edited lines, because a hand-drawn region is author-chosen and excludes exactly the descendant whose ancestry moved just outside it.
+
+Failure shape: an entrypoint-slimming batch carried a 45-row table, grepped each row to `count == 1`, and confirmed each origin no longer matched — green through eleven review and four challenge rounds — while a clause (`a case that cannot be exercised safely is recorded as a safe-unavailable gap…`) migrated off the enforcement-matrix rule it qualified onto an adjacent precision rule that never had it. Its post-change carrier count was **2**, so check 2 would have caught it on sight; nobody ran check 2 on it, because a sentence the author was not moving never became a row.
+
+**This applies to a relocation with no rewrite** ("moved detail X to a reference, entrypoint keeps a pointer") exactly as it does to a rewrite — a move is a merge whose destination happened to be empty, and it fails all the same ways. Its STATUS, though, follows the chain rather than the file: a relocation whose governing chain changes takes `rehosted` — moving a detail out to a reference normally does change it — and only a relocation whose chain stays normatively identical may take `merged`, since check 4 rejects `merged` the moment the chain moves. Failure shape: an entrypoint-slimming change declared two sections "merged into the reference, deduped" and "subsumed into the schema"; the reference already stated the same contract ~30 lines below the insertion point, and the section declared subsumed was still sitting in the entrypoint under a freshly-added pointer telling the reader to go read the copy.
+
+**A rewrite/slim owes a *preservation list* of externally-pinned anchors, owed by ANY draft that may touch pinned text — independent of whether the obligation-table trigger fires.** The row set above is derived from the changed files' own diff and cannot see text that machinery OUTSIDE those files pins verbatim — a phrase a script greps for, or a register anchor that must keep resolving. Build the list before drafting from at least these three walked sources; walk all three and mark each `walked: N anchors` / `walked: none` — an unwalked source is the defect, and `none` must be a grep result, not an assumption. Then, before finalizing, search each phrase you intend to reword across the whole **tracked** tree — `git grep -F '<phrase>'`, never a bare filesystem `grep -r … .` — covering register cells beyond `firing-path:`, regression-test fixtures, and templates; any hit outside the changed files pins the phrase verbatim even when all three sources missed it. Tracked-only is a sanitization constraint, not a convenience: a filesystem walk descends into ignored per-host scratch, private evidence archives, and sibling worktrees, and this rule then requires you to record what it printed — so a bare walk feeds private paths straight into a shared surface (measured on one checkout: the tracked search returned 4 files, the same search through the real `grep` binary returned 10, the extra 6 being scratch review results, plans, and draft MR bodies). The marks are author-declared, so the walked marks AND their search outputs are recorded in the closeout evidence row — the commit body or the change's `source-register.md` row, i.e. a surface the review packet carries; marks left in per-host scratch or chat cannot be reconciled and count as absent. The adversarial challenge reconciles the declared marks against those recorded outputs — a declared `none` contradicted by a recorded grep hit, or marks with no recorded output, is a blocking finding:
+
+- `source-register.md` `firing-path:` anchors that resolve into the changed files;
+- the repo's check/validator scripts' pin lists — run `git grep -n 'required_phrase' -- '*.sh' '*.rb' '*.py'` from the REPO ROOT, never scoped to a top-level `scripts/`: validator scripts also live under `skills/*/scripts/`, `hooks/`, and `eval/`, so a directory-scoped grep returns nothing and manufactures the false `walked: none` this rule exists to prevent. But that grep is one gate's variable name, not the pin mechanism, so it can only find the pinners that happen to share it — run a second, idiom-level pass over the tracked tree, `git grep -nE "grep -[a-zA-Z]*F|rg -[a-zA-Z]*F|has_marker" -- '*.sh' '*.rb' '*.py'`, and inspect the literal each hit pins (on this repo the two passes differ by an order of magnitude: 1 script vs 20). Both passes are `walked: none` only when you have read the pinned literals and none names text in the changed files. **Neither pass — nor the phrase check below — sees a pin whose phrase is assembled at runtime or matched by regex**: a literal `git grep -F` of the phrase finds only files that contain it verbatim, and a constructed or regex pin by definition does not, so that class is genuinely uncovered by this list. Do not record it as covered; when the changed text plausibly sits behind such a pin, read the candidate scripts' matching code before concluding, and if you cannot rule it out, say so on the closeout row rather than writing `walked: none`;
+- named couplings that quote or name text in the changed files from anywhere else in the repo: same-package carriers (the host `SKILL.md` or a sibling reference), other skills, the always-on bootstrap layer, and hooks.
+
+The three are not equally exposed, and the asymmetry is the reason to walk them BEFORE drafting rather than after: a reworded source-(a) or source-(b) anchor does eventually turn `check-ccl-skills.sh` RED (`register_firing_path_resolution_ok` re-resolves the whole ledger; a pinning script prints its own `*_gate_missing` line), so walking those two early converts a late RED into no RED at all — but source (c) has no phrase-level gate anywhere in the repo (the cross-package check verifies pointers resolve, never that quoted text survives), so for it this list is the only control.
+
+What the list obliges on the resulting text:
+
+- **The closeout record is itself shared-tree content, so it carries locators rather than payloads**: repo-relative *tracked* paths, hit counts, and the anchor phrases — never a raw line or path from an untracked, ignored, or out-of-tree file. And tracked is not the same as sanitized: a pinned phrase can be pre-existing shared-tree provenance carried as `known_debt`, and quoting it into a commit body or ledger row mints a fresh occurrence of it. So every phrase you are about to record still passes the normal sanitization audit; one that does not is recorded as its tracked locator plus count, or a stable alias, and never quoted.
+- A phrase on this list must survive **verbatim** — it may move, never be reworded — and when it does move, the obligation-table row it already owes under the row-set predicate above names the external anchor in its `proof` cell (a listed phrase left untouched owes no row, exactly like any other unchanged obligation in the comparison domain); a genuinely needed rewording goes through the anchor's owner in the same commit, never silently. Failure shape: an entrypoint-slim batch built its preservation list from the register source alone, reworded five script-pinned phrases, and turned five anchor gates RED in one round — the phrases were never on the list, so nothing told the author they could not be touched.
+
+## "Subsumed" is strict (the anti-loophole)
+
+`subsumed` (delete the earlier rule because a later one covers it) is valid **only** when the after-text preserves ALL of: the same **trigger** (fires in the same situations), the same **gate strength** (blocks/`interim`s exactly what the old one did), the same **owner**, and the same **closeout consequence**.
+
+- A broader-but-vaguer rule does **not** subsume a narrow mechanical gate. Example: a general *"use extraction for reusable lessons"* bullet does NOT subsume the mechanical *"a committed skill-change with no visible in-session `skill-extraction-workflow` invocation is `interim`"* gate — the latter has a precise, machine-adjacent trigger the former lacks.
+- When in doubt, keep the narrow gate. Losing a specific gate to a generality is the exact regression this rule prevents.
+
+## Package / support-file integrity (the file axis)
+
+The obligation table above governs rule TEXT. Consolidating or retiring a whole **skill or reference package** has a second, independent loss axis: its support files and the links into them. Before merging/retiring a unit that owns `references/`, `templates/`, `scripts/`, or `assets/` files, or whose text contains relative links (`references/...`, `templates/...`, `scripts/...`, `assets/...`), treat it as a **complete directory package**, not just its entry file. Do NOT flatten only the entry file into another unit's `references/` and leave its support files behind. Choose one safe path:
+
+- keep it standalone, OR
+- fully re-home every needed support file into the destination's canonical `references/`/`templates/`/`scripts/`/`assets/` directory **AND** rewrite every instruction/link to the new paths, OR
+- retire the whole package unchanged.
+
+Two failure shapes, both silent and distinct:
+
+- **dangling link** — text references a relative path that no longer exists. `validate-skill.sh` catches only a **subset** of these: backticked `.md` references under `references/` (or `../`). Links to `templates/`, `scripts/`, `assets/`, or any non-`.md` / non-backticked path are **not** validated — do not rely on the validator for them.
+- **orphan** — a support file nobody links to anymore: it survives on disk but is unreachable, and the validator checks reachable references, not abandoned files, so it does **NOT** catch this at all. A flatten-merge that copies only the entry file produces orphans by construction.
+
+Because the validator covers only part of one shape, closeout must run its own sweep and confirm, for the changed unit: every relative-link target (all of `references/`/`templates/`/`scripts/`/`assets/`, backticked or not) resolves (no dangling) **and** every support file under the retired/merged unit was re-homed or intentionally retired (no orphan). Record one line in the `semantic-control` row; the adversarial challenge hunts both shapes.
+
+## Artifact boundary (vs the append-only register)
+
+- Consolidation rewrites/retires rule TEXT in `SKILL.md` and `references/*` — these are living.
+- It **never** edits or deletes a `source-register.md` row — that ledger is append-only with forward supersede pointers per its "Row lifecycle" convention. Record the consolidation as a **new** register row that names the deleted/merged rule anchors and the surviving anchor.
+
+## Audit recovery
+
+Deleted rule text is recoverable from git history; the index back to it is (a) the consolidation register row naming the deleted anchors + the round/commit label, and (b) the commit itself. So the register row MUST name the removed anchors, not just "consolidated some rules" — otherwise a reviewer asking "where did guard X go?" has no pointer.
+
+## Dual-track
+
+A consolidation is a non-wording shared-skill change → full dual-track. The behavioral-evidence row is `semantic-control` carrying the obligation table above; the fact/consistency review confirms the at-add-time check line is present; the adversarial challenge **first independently recomputes the row set** — deriving each obligation's before/after governing chain across the full comparison domain defined above — every pre-existing obligation in every changed file plus every relocation destination, not a window around the diff — and reconciling that derived set against the submitted table, because every other check in this section runs only over rows the author declared, so an obligation the author never enrolled is invisible to all of them and an omitted row is precisely the failure this section exists to catch (a table can be perfectly verified row-by-row and still be missing the row that mattered) — then hunts the table for a dropped, falsely-`subsumed`, or falsely-`retired-dead` guard (a `retired-dead` row whose trigger/source surface actually still exists is a dropped guard), **independently re-runs the destination-existence check and carrier checks 1-3** for every `merged`/`subsumed`/`rehosted` row — `rehosted` is exempt from the same-chain equality assertion alone, never from existence or counting, so a rehost that leaves two copies under the new host must fail the challenge exactly as a duplicating `merged` would (a named-but-absent or named-but-doesn't-carry destination is silent data loss) **and the governing-chain binding check** (a survivor that came to rest under a different obligation than it qualified is an undeclared strength change, and no carrier count can see it; for a `rehosted` row the challenge verifies BOTH declared sides — that the new host really gains the obligation and the old host really loses it — since a one-sided rehost is the same silent escape wearing a status label), and — when a whole skill/reference package was merged or retired — **hunts for dangling links and orphaned support files** per the file-axis section above. Route wording-level compression (define-once, cross-reference instead of restate, kill near-synonym restatement) to `tighten-doc`; this file owns *when/whether* to consolidate and *how to prove no obligation was lost*.

package/dist/assets/marketplace/plugins/ccl-skills/skills/skill-extraction-workflow/references/skill-listing-budget.md

@@ -0,0 +1,19 @@
+# Claude Code skill-listing budget — mechanism, cold-start trap, levers
+
+Companion to the **budget-dropped** Core Rule in `SKILL.md` (under *Triggers, routing surfaces & isolation*). The Core Rule carries the gate (before fixing a routing miss with a trigger-word edit, check whether the description was even in the host listing; the evidence bar; the two host corollaries). This file carries the **mechanism detail and the remediation levers**. It adds no new gate.
+
+## Mechanism
+
+Claude Code always loads every skill *name*, but when many skills are installed it collapses the *descriptions* of the **least-invoked** skills to bare name-only to fit a skill-listing budget (default ~1% of the context window via `skillListingBudgetFraction`). `/doctor` shows the overflow and which skills lost their description.
+
+While an entry is name-only, **trigger-word edits are invisible to description-based routing** — the skill is still reachable by explicit `/skill-name` or by name semantics, just not by the new keywords.
+
+## The cold-start trap
+
+A rarely-used gate skill can spiral: never invoked → description dropped → never auto-routed → never invoked. The trigger-word edit that was supposed to fix routing has no effect because the description it edits is not in the listing.
+
+## Levers (once confirmed name-only)
+
+- **Raise `skillListingBudgetFraction`** — applies to ALL skills incl. plugins, but it is a global per-turn context/cost tradeoff, not a default fix.
+- **Disable unused plugins** via `/plugin` — note `skillOverrides: name-only` does NOT apply to plugin skills (personal/project only).
+- **Invoke the skill once** — a single invocation lifts it out of the least-invoked set.