bmad-module-skill-forge 2.0.2 → 2.1.0

package/src/skf-create-skill/assets/compile-assembly-rules.md

@@ -15,7 +15,7 @@ description: >
 **Frontmatter rules:**
 
 - `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity.
-- `description`: non-empty, max 1024 chars, optimized for agent discovery. Use third-person voice ("Processes Excel files..." not "I can help you..." or "You can use this to...") and include a trigger phrase so agents know when to match — one of `Use when …`, `Triggers on …`, or `Reach for this when …`. When using `Use when `, follow with a **gerund** (`Use when building/processing/analyzing X…`) or a noun-phrase clause (`Use when the user requests to "X"`); never a bare indicative verb like `builds`/`processes`, because `skill-check --fix` will prepend a literal `Use when ` to a description missing the trigger phrase, producing ungrammatical output (`Use when builds X…`). Inconsistent point-of-view or a missing trigger phrase causes discovery problems since the description is injected into the system prompt. See `skf-brief-skill/assets/description-voice-examples.md` for the canonical voice palette.
+- `description`: non-empty, max 1024 chars, optimized for agent discovery. Use third-person voice ("Processes Excel files..." not "I can help you..." or "You can use this to...") and include a trigger phrase so agents know when to match. **The description must contain a literal `Use when` clause somewhere** — `skill-check`'s `description.use_when_phrase` rule tests for that exact phrase anywhere in the string, so `Triggers on …` or `Reach for this when …` on their own score below 100 with a `description should contain "Use when" phrasing` warning. The lead is still free: a descriptive opener followed by a `Use when …` clause (`Charts and visualizations powered by D3.js. Use when plotting data …`) passes cleanly, and the other two phrases are fine as *additional* text. When using `Use when `, follow with a **gerund** (`Use when building/processing/analyzing X…`) or a noun-phrase clause (`Use when the user requests to "X"`); never a bare indicative verb like `builds`/`processes`, because `skill-check --fix` will prepend a literal `Use when ` to a description missing the trigger phrase, producing ungrammatical output (`Use when builds X…`). Inconsistent point-of-view or a missing trigger phrase causes discovery problems since the description is injected into the system prompt. See `skf-brief-skill/assets/description-voice-examples.md` for the canonical voice palette.
 - **The `description` cannot contain angle brackets** — neither standalone placeholders like `<name>`, `<component>`, `<path>`, nor inline generics like `` `Array<T>` `` or `` `Meta<typeof X>` ``. Both `skill-check`'s `description_field` validator and `tessl`'s deterministic description check parse the frontmatter description as a raw string and reject any `<` or `>`, regardless of markdown context (backticks do not protect content here). A rejected description fails the review with 0% score. When the natural phrasing would use angle brackets:
   - Prefer the curly-brace form in prose: `{name}`, `{component-id}`, `{path}` — readable and tessl-safe.
   - Uppercase placeholders are also acceptable: `NAME`, `COMPONENT_ID`.
@@ -62,6 +62,7 @@ These sections form the essential standalone body. Target: **under 300 lines tot
 - Provenance citation per function
 
 **Section 4b — Migration & Deprecation Warnings (~10 lines, Deep tier only):**
+- Emit the heading verbatim as `## Migration & Deprecation Warnings`. Downstream gates match that exact text, so a naturally-retitled section (`## Deprecations & pre-1.0 hazards`, `## v2 → v3 breaking changes`) is reported as *missing* while its bullets are re-emitted as duplicate `## CORRECTION` blocks.
 - Only populated when step 4 enrichment produced **T2-future** annotations (deprecation warnings, breaking changes, planned renames)
 - List each warning as a single-line bullet: function name, what changed or will change, source citation
 - Max 10 lines — just the actionable warnings, not full context
@@ -268,7 +269,7 @@ Replace per-function subsections with `references/pattern-*.md` groupings: one r
 - `stats.exports_documented` MAY be set to the Pattern Surface row count as a proxy, but its semantics change: it counts authored pattern surfaces, not public exports. Emit an adjacent `stats.pattern_surfaces_documented` with the same integer so downstream consumers (test-skill, feasibility, discovery) can discriminate.
 - `exports_public_api` / `exports_internal` / `exports_total` are not meaningful for a reference app — omit them, or set all three to the Pattern Surface count with a note in `stats.notes`: `"reference-app: export counts are pattern-surface proxies, not library exports"`.
 - Do not fabricate signature / type-coverage data from pattern surfaces. skf-test-skill will skip those categories when metadata flags a reference-app (same skip path as `stackSkill` once that flag is wired — see scoring-rules.md).
-- Do not emit `effective_denominator` for reference-app scope, even when the source is a monorepo. `effective_denominator` counts public exports from the authoring-surface barrel — a library concept that `pattern_surfaces_documented` already replaces here. A reference-app-in-monorepo literally satisfies `compile.md` §4's emit-conditions (monorepo + non-`full-library` + stratified `scope.notes`), so this carve-out takes precedence: pattern-surface coverage is the reference-app basis, and skf-test-skill skips library-export coverage for it.
+- Do not emit `effective_denominator` for reference-app scope, even when the source is a monorepo. `effective_denominator` counts public exports from the authoring-surface barrel — a library concept that `pattern_surfaces_documented` already replaces here. A reference-app-in-monorepo literally satisfies `compile.md` §4's emit-conditions (condition 1 arm (a) + non-`full-library` + stratified `scope.notes`), so this carve-out takes precedence: pattern-surface coverage is the reference-app basis, and skf-test-skill skips library-export coverage for it.
 
 **Language / spec-reference sub-shape:** A reference app that documents an engine- or spec-versioned **language** — a query language, grammar, or DSL (e.g. SurrealQL @ SurrealDB) whose value is construct idioms rather than wiring or exports — is a recognized reference-app sub-shape. Keep `scope.type: "reference-app"` (there is no separate enum value), so every carve-out above applies unchanged (`pattern_surfaces_documented` proxy, no `effective_denominator`, test-skill signature/type skip). Adapt the three overrides to the language's surface instead of app wiring:
 

package/src/skf-create-skill/assets/skill-sections.md

@@ -134,7 +134,7 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "total_coverage": 0.0,
     "scripts_count": 0,
     "assets_count": 0
-    // "effective_denominator": 0  // optional — emitted for stratified-scope monorepo packages; test-skill uses this as the coverage denominator when present. See compile.md §4 emit rules.
+    // "effective_denominator": 0  // optional — emitted for the curated-subset shapes in compile.md §4 condition 1; test-skill uses this as the coverage denominator when present. See compile.md §4 emit rules.
   },
   // scripts[] and assets[] — include ONLY when inventories are non-empty; omit entirely otherwise
   // "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],

package/src/skf-create-skill/references/compile.md

@@ -111,12 +111,21 @@ Following the structure from the skill-sections data file:
   - `exports_public_api`: count of exports from public entry points (`__init__.py`, `index.ts`, `lib.rs`, or equivalent) — derive this from step 3's entry-point validation (section 4b), not from the provenance-map entry count (which may be incomplete if extraction patterns missed some export types)
   - `exports_internal`: count of all other non-underscore-prefixed exports (internal modules, helpers, adapters)
   - `scripts` / `assets`: the `scripts_inventory` / `assets_inventory` arrays (or `[]` when empty) — the helper sets `stats.scripts_count` / `stats.assets_count` from their lengths
-  - `effective_denominator` (**optional** — include in the helper's judgment payload only for stratified-scope monorepo packages): the count of public exports from files matched by the brief's authoring-surface globs, filtered by `scope.exclude`, resolved against `source_path`. **Prefer `scope.tier_a_include` when the brief supplies it** — that narrow list represents the authoring surface the brief intends to document; resolve its globs across `source_path` and count the union of **named exports** — items reachable from the language's public entry-point barrel (`lib.rs` `pub use`, `index.ts` / `index.js` re-exports, `__init__.py` exports), where a type counts **once** with its methods and impl-block members rolling up under it (count a `pub fn` only when it is a free function reachable from the barrel, never a method on an already-counted type). **Otherwise use `scope.include`** — the coarse list. This counting unit matches what `skf-test-skill` re-derives on the consumer side (`coverage-check.md` §2c excludes `kind: "method"` from `documented_set`), so the producer- and test-side denominators stay aligned; without it, a type-heavy API (a few handle types carrying hundreds of methods) inflates the denominator by an order of magnitude and auto-fails the coverage gate. This is the coverage denominator `skf-test-skill` uses when the package is a curated subset of a multi-package repository, so it must match the brief's authoring intent. Compute when ALL of the following hold:
-    1. The source is a monorepo (detected via `packages/` layout, `workspaces` field in root `package.json`, `lerna.json`, `rush.json`, `nx.json`, or Cargo `[workspace]`).
+  - `effective_denominator` (**optional** — include in the helper's judgment payload only for the curated-subset shapes enumerated in condition 1 below): the count of public exports from files matched by the brief's authoring-surface globs, filtered by `scope.exclude`, resolved against `source_path`. **Prefer `scope.tier_a_include` when the brief supplies it** — that narrow list represents the authoring surface the brief intends to document; resolve its globs across `source_path` and count the union of **named exports** — items reachable from the language's public entry-point barrel (`lib.rs` `pub use`, `index.ts` / `index.js` re-exports, `__init__.py` exports), where a type counts **once** with its methods and impl-block members rolling up under it (count a `pub fn` only when it is a free function reachable from the barrel, never a method on an already-counted type). **Otherwise use `scope.include`** — the coarse list. This counting unit matches what `skf-test-skill` re-derives on the consumer side (`coverage-check.md` §2c excludes `kind: "method"` from `documented_set`), so the producer- and test-side denominators stay aligned; without it, a type-heavy API (a few handle types carrying hundreds of methods) inflates the denominator by an order of magnitude and auto-fails the coverage gate. This is the coverage denominator `skf-test-skill` uses when the brief documents a curated subset rather than a package's whole barrel, so it must match the brief's authoring intent. Compute when ALL of the following hold:
+    1. The skill's coverage denominator is resolved by a `skf-test-skill` `references/source-access-protocol.md` §Source API Surface Definition clause that actually consumes `effective_denominator` — **any one** of:
+       - **(a) stratified-scope:** the source is a monorepo (detected via `packages/` layout, `workspaces` field in root `package.json`, `lerna.json`, `rush.json`, `nx.json`, or Cargo `[workspace]`);
+       - **(b) single-crate curated subset:** `scope.type` is `specific-modules` on a non-monorepo repo;
+       - **(c) multi-entry (exports-map):** the in-scope `package.json` declares an `exports` map with more than one non-root subpath, and the repo carries no monorepo markers.
+
+       Arms (b) and (c) are not a widening for its own sake — both consumer clauses already say "prefer `metadata.json.stats.effective_denominator`", and a monorepo-only emit condition makes those two rungs unreachable, so a non-monorepo curated scope has no way to lock its denominator.
     2. `scope.type` is not `full-library` (and not `reference-app` — see carve-out below), AND the resolved include list (`tier_a_include` if present, else `scope.include`) lists a curated file/directory subset rather than the full workspace.
     3. `scope.notes` is present and documents the stratification strategy (e.g., a tiered A/B/C plan) — this serves as the intent marker confirming the subset is by design.
 
-    Otherwise omit it from the payload entirely — when absent, `skf-test-skill` falls back to `exports_public_api`. See `skf-test-skill` `references/source-access-protocol.md` §Source API Surface Definition ("Stratified-scope monorepo packages") for the test-side consumption rules.
+    Otherwise omit it from the payload entirely — when absent, `skf-test-skill` falls back to `exports_public_api`. See `skf-test-skill` `references/source-access-protocol.md` §Source API Surface Definition ("Stratified-scope monorepo packages", "Single-crate curated subset", "Multi-entry (exports-map) packages") for the test-side consumption rules.
+
+    **A `public-api` scope on a single-package repo with no multi-subpath `exports` map matches none of the three arms** — that shape falls to the standard root-barrel rule, which honors neither `effective_denominator` nor `tier_a_include`. Emitting the field there has no effect on the test-side denominator, so omit it.
+
+    **That shape has no brief-side denominator lever, and `scope.exclude` is not one.** The root-barrel rule counts the named exports of a single entry-point file (`index.ts` / `__init__.py` / `lib.rs`), so excluding *files* cannot remove exports from the barrel's own export list — the denominator is unchanged. When the brief genuinely documents a curated subset of a single package's surface (citation-only files alongside a narrow `tier_a_include`), express that with `scope.type: "specific-modules"` rather than `public-api`: the single-crate curated-subset clause in `skf-test-skill` `references/source-access-protocol.md` filters the barrel by `scope.include` / `scope.exclude` **and** honors `effective_denominator`, so condition 1 arm (b) applies and the denominator matches the authoring intent. Reserve `public-api` for the case where the whole root barrel is the intended surface.
 
     **Reference-app carve-out:** never emit `effective_denominator` for `scope.type: "reference-app"`, even when the three conditions above are literally satisfied (a reference-app-in-monorepo matches all of them). A reference app's coverage basis is `pattern_surfaces_documented`, not library exports — see the Reference-App stats semantics in `assets/compile-assembly-rules.md`.
 - **Shape:** pass `--shape reference-app` or `--shape stack` when the matching assembly-rules override applies (default `library`). For a reference app, also put `pattern_surfaces_documented` (the Pattern Surface row count) in the payload — the helper uses it as `exports_documented`, emits `stats.pattern_surfaces_documented`, and refuses to emit `effective_denominator`; the distribution then sums to the per-citation count, not to `exports_documented`. For a stack, put the own-barrel `exports_documented` (usually `0`) in the payload; the distribution sums to the cited-constituent count.

package/src/skf-create-skill/references/extract.md

@@ -101,7 +101,7 @@ Then run CCC indexing and discovery on the resolved clone (workspace or ephemera
    node_modules/, dist/, build/, .git/, vendor/, __pycache__/, .cache/, .next/, .nuxt/, target/, out/, .venv/, .tox/
    ```
 
-   Read `settings.yml`, append any patterns not already present to the `exclude_patterns` array, write back. **Reuse check:** if an existing `.cocoindex_code/settings.yml` was already present (workspace hit), read its `exclude_patterns` first and diff against the standard-exclusion list above. If ANY standard entry is missing from the existing list, append only the missing entries (preserving any user-added patterns) AND force a re-index by running `ccc index --force` (or the equivalent rebuild flag). If every standard entry is already present, skip the write and skip the forced re-index — the existing index is valid. Record `ccc_exclusions_augmented: {count}` in context for the evidence report.
+   Read `settings.yml`, append any patterns not already present to the `exclude_patterns` array, write back. **Reuse check:** if an existing `.cocoindex_code/settings.yml` was already present (workspace hit), read its `exclude_patterns` first and diff against the standard-exclusion list above. If ANY standard entry is missing from the existing list, append only the missing entries (preserving any user-added patterns) AND force a re-index by running `ccc reset --force` (discards the stale databases) followed by `ccc index` — `ccc index` itself takes no rebuild flag, so re-running it alone would reuse the existing index. If every standard entry is already present, skip the write and skip the forced re-index — the existing index is valid. Record `ccc_exclusions_augmented: {count}` in context for the evidence report.
 
    **Note:** Brief-specific `include_patterns` and `exclude_patterns` are not written to `settings.yml`. The CCC index is general-purpose — it indexes everything (minus standard artifacts). Brief-specific filtering happens at search result time, not index time. This allows a single workspace CCC index to serve multiple briefs with different scope filters.
 

package/src/skf-create-skill/references/generate-artifacts.md

@@ -194,11 +194,13 @@ Ensure the source path used for extraction is indexed by ccc and registered in t
 
 **Index verification:**
 
-`ccc index` requires the directory to be initialized first. Run `ccc init {source_root}` (idempotent — a no-op once initialized) before `ccc index {source_root}`, or use the ccc MCP tool. `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. Indexing is a no-op if the source was already indexed during setup or step 2b.
+**Working-directory contract:** `ccc init`, `ccc index`, and `ccc status` take **no positional path argument** — each operates on the current working directory, and passing a path makes them exit non-zero with `Got unexpected extra argument`. Run them from `{source_root}` (`cd {source_root} && ccc …`, the same form `extract.md` step 2b and `knowledge/ccc-bridge.md` use), then return to `{project-root}` before the registry update below, which resolves `{forgeTierConfig}` relative to the project.
 
-**Nested project marker:** when `{source_root}` is a subtree of a repo that already carries a project marker (e.g. a cloned source tree under `.forge-sources/`, or a `.cocoindex_code` / VCS marker in a parent), `ccc init {source_root}` exits non-zero with `A parent directory has a project marker`. This is expected — re-run as `ccc init -f {source_root}` to initialize at the subtree anyway, then `ccc index`. Do not treat the parent-marker warning as fatal.
+`ccc index` requires the directory to be initialized first. Run `cd {source_root} && ccc init` (idempotent — a no-op once initialized) before `cd {source_root} && ccc index`, or use the ccc MCP tool. `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. Indexing is a no-op if the source was already indexed during setup or step 2b.
 
-**Verify the index is not degraded:** after `ccc index`, run `ccc status {source_root}` and read the `Languages:` breakdown — a non-zero `Chunks`/`Files` total is not sufficient. Confirm the source's primary language (`{brief.language}`) reports a non-trivial chunk count. An index dominated by `markdown`/config chunks with the source language absent or near-zero means `ccc index` ran against degraded settings (a stale `.cocoindex_code/` inherited from a parent project, or a no-op `ccc init` over a prior partial index that returned `Project already initialized.`) — the source code was never indexed, which silently cripples later `skf-audit-skill` / `skf-update-skill` searches with no error surfaced. When the source language is absent, rebuild from a clean init (`ccc init -f {source_root}` then `ccc index {source_root}`) and re-check the breakdown. If the source language is still missing after a forced re-init, log it and continue per the error handling below — a degraded index is not workflow-fatal, but it must be recorded so the gap is visible.
+**Nested project marker:** when `{source_root}` is a subtree of a repo that already carries a project marker (e.g. a cloned source tree under `.forge-sources/`, or a `.cocoindex_code` / VCS marker in a parent), `ccc init` exits non-zero with `A parent directory has a project marker`. This is expected — re-run as `cd {source_root} && ccc init -f` to initialize at the subtree anyway, then `ccc index`. Do not treat the parent-marker warning as fatal.
+
+**Verify the index is not degraded:** after `ccc index`, run `cd {source_root} && ccc status` and read the `Languages:` breakdown — a non-zero `Chunks`/`Files` total is not sufficient. Confirm the source's primary language (`{brief.language}`) reports a non-trivial chunk count. An index dominated by `markdown`/config chunks with the source language absent or near-zero means `ccc index` ran against degraded settings (a stale `.cocoindex_code/` inherited from a parent project, or a no-op `ccc init` over a prior partial index that returned `Project already initialized.`) — the source code was never indexed, which silently cripples later `skf-audit-skill` / `skf-update-skill` searches with no error surfaced. When the source language is absent, rebuild from a clean init (`cd {source_root} && ccc init -f` then `ccc index`) and re-check the breakdown. Note that `-f` only skips the parent-marker warning — it does not clear a stale `.cocoindex_code/`; when the degraded settings survive the forced re-init, `ccc reset` (run from `{source_root}`) is what discards the existing databases. If the source language is still missing after a forced re-init, log it and continue per the error handling below — a degraded index is not workflow-fatal, but it must be recorded so the gap is visible.
 
 **Registry update:**
 

package/src/skf-create-skill/references/step-doc-rot.md

@@ -29,7 +29,7 @@ Identify the feeder artifacts in the **staging directory** for the current skill
 1. **Evidence report:** `_bmad-output/{skill-name}/evidence-report.md`
 2. **Provenance map:** `_bmad-output/{skill-name}/provenance-map.json` — focus on T2/T3 entries with temporal annotations
 3. **Temporal context:** changelogs, migration guides, and issue/PR data fetched by step 3b and enriched by step 4 (available in workflow context)
-4. **Compiled SKILL.md:** the staged `_bmad-output/{skill-name}/SKILL.md` itself — check for `[QMD:...]` or `[DOC:...]` annotations referencing corrections. **Do not treat its own `## Migration & Deprecation Warnings` section (§4b) as a correction source:** compile (step 5 §4b) already authored that section from the same T2-future annotations, so its bullets are already-surfaced corrections — §2 discards matches that land inside it.
+4. **Compiled SKILL.md:** the staged `_bmad-output/{skill-name}/SKILL.md` itself — check for `[QMD:...]` or `[DOC:...]` annotations referencing corrections. **Do not treat its own self-authored regions as correction sources:** compile already wrote the `## Migration & Deprecation Warnings` section (step 5 §4b) and the frontmatter `description` (step 5 §2) from the same T2-future annotations, so both restate already-surfaced corrections — §2 discards matches that land in either.
 
 For each artifact, attempt to load its content. If an artifact does not exist or is empty, skip it — this is not an error.
 
@@ -42,6 +42,7 @@ The scan is deterministic plumbing — a fixed-table substring grep with one cor
 ```bash
 uv run {scanDocRotHelper} \
   --skill-md _bmad-output/{skill-name}/SKILL.md \
+  --max-corrections 10 \
   _bmad-output/{skill-name}/evidence-report.md \
   _bmad-output/{skill-name}/provenance-map.json \
   _bmad-output/{skill-name}-temporal/*.md
@@ -49,13 +50,15 @@ uv run {scanDocRotHelper} \
 
 (Pass whichever of the §1 feeder paths actually exist — the script skips any that are missing or empty, and reports the loaded set in `scanned`.)
 
-The script emits `{scanned: [...], matches: [...], match_count, excluded_count}` on stdout. Each entry in `matches` is a match record with the deterministic fields the script owns:
+The script emits `{scanned: [...], matches: [...], match_count, excluded_count, deduped_count, capped_count, cap}` on stdout. Each entry in `matches` is a match record with the deterministic fields the script owns:
 
 - `source`: the feeder artifact path where the match was found
 - `pattern`: the specific pattern string that matched
 - `category`: the category label
 - `context_line`: the line containing the match
-- `line_number`: the 1-indexed line the match sits on
+- `line_number`: the 1-indexed line the match sits on — a representative occurrence when duplicates were collapsed
+- `occurrences`: how many feeder lines collapsed into this record (1 when it is unique)
+- `duplicate_of`: the `{source, line_number}` of every collapsed occurrence (empty when it is unique)
 
 Read `matches` into `correction_matches: [{match records}]`. Then add the one judgment field the script cannot infer:
 
@@ -79,7 +82,19 @@ Read `matches` into `correction_matches: [{match records}]`. Then add the one ju
 | `migration required` | Migration |
 | `signature changed` | Signature change |
 
-**Exclusion — drop already-surfaced §4b corrections (deterministic, no AI judgment, applied inside the script before it emits):** the script discards any match whose `source` is the compiled SKILL.md (feeder #4) **and** whose `context_line` sits inside that file's own `## Migration & Deprecation Warnings` section — i.e. on a line at or after the `## Migration & Deprecation Warnings` heading and before the next `##` heading (`excluded_count` reports how many it dropped). Compile (step 5 §4b) authored that section from the same T2-future annotations, so re-emitting its bullets as `## CORRECTION` blocks in §3 would duplicate already-surfaced content verbatim. This is a positional heading-boundary check on text already loaded, not a semantic assessment. Set `feeder_artifacts_scanned` from the script's `scanned` list.
+**Exclusion — drop the compiled SKILL.md's self-authored content (deterministic, no AI judgment, applied inside the script before it emits):** the script discards any match whose `source` is the compiled SKILL.md (feeder #4) **and** whose `line_number` sits in either of two positional windows. `excluded_count` reports the combined total.
+
+1. **Its own `## Migration & Deprecation Warnings` section** — a line at or after the heading and before the next `##` heading. Compile (step 5 §4b) authored that section from the same T2-future annotations, so re-emitting its bullets as `## CORRECTION` blocks in §3 would duplicate already-surfaced content verbatim.
+2. **Its own YAML frontmatter** — a line at or inside the leading `---` … `---` fences. Compile (step 5 §2) writes the frontmatter `description` from the same annotations, and it routinely restates the release's headline breaking change, so a match there is already-surfaced too. The frontmatter is a closed key set of pipeline scalars, so it can never carry an upstream correction the body has missed — and §3 forbids annotating it in any case, which would leave such a match with nowhere legitimate to go.
+
+Both are positional boundary checks on text already loaded, not semantic assessments. The heading search starts after the frontmatter, so an indented restatement of the heading inside a folded `description:` cannot anchor the window in the wrong place. Set `feeder_artifacts_scanned` from the script's `scanned` list.
+
+**Bounding — collapse duplicates, then cap (deterministic, applied inside the script after the exclusions):** the temporal feeder above is a verbatim upstream changelog, so a single run can match hundreds of "breaking"/"deprecated" lines drawn from years of release history. Two bounds keep §3's output proportionate:
+
+- **Duplicate collapse.** Matches sharing a `category` and the same whitespace-normalized, lowercased `context_line` collapse into their first occurrence, which carries `occurrences` and `duplicate_of`. `deduped_count` reports how many collapsed. A changelog that restates one deprecation across many releases yields one block, not one per release.
+- **Cap.** At most `--max-corrections` matches survive (default 10; pass `0` for unlimited). `capped_count` reports how many were dropped and `cap` the limit in force. Selection prefers the compiled SKILL.md's own annotations over other feeders, then scan order. Ten blocks at ~7 lines each fits step 5b's 400-line body budget with headroom.
+
+Neither bound is a judgment call, and neither is silent — §4 logs both counts.
 
 **IF `correction_matches` is empty** (the script returned `match_count: 0`, or the run had no feeder files to pass)**:**
 - Log: `"doc-rot: skipped (no correction indicators found in feeder artifacts)"`
@@ -90,7 +105,7 @@ Read `matches` into `correction_matches: [{match records}]`. Then add the one ju
 
 ### §3. Annotate SKILL.md with Correction Blocks
 
-For each entry in `correction_matches`, insert a `## CORRECTION` block into the compiled SKILL.md.
+For each entry in `correction_matches`, insert a `## CORRECTION` block into the compiled SKILL.md. The list is already collapsed and capped by §2's bounding, so this loop is bounded by construction — do not re-expand it from `duplicate_of`, and do not write the drop counts into the artifact (they belong in the §4 log, not in a third-party skill).
 
 **Block format:**
 
@@ -114,11 +129,13 @@ Store: `corrections_added: {count of blocks inserted}`
 
 ### §4. Log Results
 
-Log: `"doc-rot: {corrections_added} correction blocks added from {feeder_artifacts_scanned_count} feeder artifacts"`
+Log: `"doc-rot: {corrections_added} correction blocks added from {feeder_artifacts_scanned_count} feeder artifacts ({deduped_count} duplicates collapsed, {capped_count} dropped over cap {cap})"`
 
 Set context:
 - `doc_rot_triggered: true`
 - `corrections_added: {count}`
+- `corrections_deduped: {deduped_count}`
+- `corrections_capped: {capped_count}`
 - `feeder_artifacts_scanned: [{list}]`
 - `correction_matches: [{match records}]`
 

package/src/skf-create-skill/scripts/scan-doc-rot.py

@@ -8,13 +8,25 @@ step 5c self-declares its correction scan "grep-based and deterministic — no A
 judgment is used for detection." This helper *is* that grep: it walks the
 resolved feeder artifacts, matches every line against the fixed 13-row
 correction-pattern table with case-insensitive substring containment (no regex,
-no semantics), and emits the matches as JSON. It applies the one positional
-filter the step documents — dropping matches that land inside the compiled
-SKILL.md's own `## Migration & Deprecation Warnings` section (compile §4b
-already authored those, so re-emitting them would be circular) — before it
-returns. Running the scan here (instead of in-prompt) makes the "deterministic,
-identical input → identical output" promise actually hold: the model no longer
-hand-greps multi-KB artifacts.
+no semantics), and emits the matches as JSON. It applies the positional filters
+the step documents — dropping matches that land inside the compiled SKILL.md's
+own YAML frontmatter or its own `## Migration & Deprecation Warnings` section
+(both are self-authored: compile §2 wrote the frontmatter `description` and
+compile §4b wrote the migration bullets, so re-emitting either would be
+circular) — and then bounds what survives, before it returns. Running the scan
+here (instead of in-prompt) makes the "deterministic, identical input →
+identical output" promise actually hold: the model no longer hand-greps
+multi-KB artifacts.
+
+Bounding matters because §2's own example command passes the raw temporal
+changelog as a feeder. That artifact is a verbatim upstream dump (thousands of
+lines of release history), so an unbounded run turns years of "breaking" /
+"deprecated" lines into hundreds of `## CORRECTION` blocks and blows the
+compiled body's line budget. Two deterministic bounds run after the exclusions:
+duplicate collapse (same category + same normalized line text) and a hard cap
+on how many blocks a single run may propose. Nothing is silently destroyed —
+a collapsed record carries `occurrences` and `duplicate_of`, and the counts of
+what was collapsed and capped are reported so the step can log them.
 
 The genuine judgment the step keeps in-prompt is untouched by this script:
 enriching each match's `affected` symbol from surrounding context (§2) and
@@ -29,11 +41,15 @@ CLI usage:
   uv run scan-doc-rot.py --skill-md <staged SKILL.md> [FEEDER ...]
   uv run scan-doc-rot.py --feeder evidence-report.md --feeder provenance-map.json
 
-  --skill-md  the compiled/staged SKILL.md feeder (feeder #4); matches inside its
-              `## Migration & Deprecation Warnings` section are excluded. It is
-              also scanned like any other feeder.
-  FEEDER      any other feeder artifact (evidence-report.md, provenance-map.json,
-              temporal-context files). Repeatable positionally or via --feeder.
+  --skill-md         the compiled/staged SKILL.md feeder (feeder #4); matches
+                     inside its YAML frontmatter or its `## Migration &
+                     Deprecation Warnings` section are excluded. It is also
+                     scanned like any other feeder.
+  FEEDER             any other feeder artifact (evidence-report.md,
+                     provenance-map.json, temporal-context files). Repeatable
+                     positionally or via --feeder.
+  --max-corrections  cap on emitted matches (default 10). 0 or negative means
+                     unlimited.
 
   Missing or empty files are skipped silently (not an error), matching §1's
   "attempt to load; if it does not exist or is empty, skip it."
@@ -43,11 +59,16 @@ Output (stdout, one object):
     "scanned": ["<path>", ...],        # feeders that existed and were non-empty
     "matches": [                        # correction_matches[] (affected added in-prompt)
       {"source": "<path>", "pattern": "deprecated", "category": "Deprecation",
-       "context_line": "<line text>", "line_number": <1-indexed int>},
+       "context_line": "<line text>", "line_number": <1-indexed int>,
+       "occurrences": <int>,            # 1 unless duplicates collapsed into this record
+       "duplicate_of": [{"source": "<path>", "line_number": <int>}, ...]},
       ...
     ],
-    "match_count": <int>,
-    "excluded_count": <int>             # SKILL.md matches dropped by the §4b filter
+    "match_count": <int>,               # len(matches), after exclusions/collapse/cap
+    "excluded_count": <int>,            # SKILL.md matches dropped (frontmatter + §4b)
+    "deduped_count": <int>,             # matches collapsed into a surviving record
+    "capped_count": <int>,              # matches dropped because the cap was reached
+    "cap": <int>                        # effective cap (0 = unlimited)
   }
 
 Exit codes:
@@ -85,6 +106,11 @@ PATTERN_TABLE: list[tuple[str, str]] = [
 
 _MIGRATION_HEADING = re.compile(r"^\s*##\s+Migration\s*&\s*Deprecation Warnings", re.IGNORECASE)
 
+# Cap on how many `## CORRECTION` blocks one run may propose (step-doc-rot.md §3).
+# Step 5b budgets the compiled body at 400 lines and each block is ~7 lines, so
+# 10 blocks stays inside the budget with headroom.
+DEFAULT_MAX_CORRECTIONS = 10
+
 
 def scan_text(text: str, source: str) -> list[dict]:
     """Case-insensitive substring scan of `text` against PATTERN_TABLE.
@@ -109,6 +135,27 @@ def scan_text(text: str, source: str) -> list[dict]:
     return matches
 
 
+def frontmatter_range(text: str) -> tuple[int, int] | None:
+    """1-indexed [start, end] inclusive window of the leading YAML frontmatter
+    block (both `---` fences included), or None when the file has no frontmatter.
+
+    Delimiter handling mirrors the established SKF convention (see
+    `skf-shard-body.py` `split_frontmatter` and
+    `skf-validate-feasibility-report.py` `split_frontmatter`): the opening fence
+    must be the FIRST line and the closing fence is the next line that is
+    exactly `---` once surrounding whitespace is stripped. A `---` horizontal
+    rule further down the body therefore cannot open a block, and an unterminated
+    opening fence yields None rather than swallowing the file.
+    """
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return None
+    for idx in range(2, len(lines) + 1):
+        if lines[idx - 1].strip() == "---":
+            return (1, idx)
+    return None
+
+
 def migration_section_range(skill_md_text: str) -> tuple[int, int] | None:
     """1-indexed [start, end) line window of the `## Migration & Deprecation
     Warnings` section, or None if the section is absent.
@@ -116,11 +163,18 @@ def migration_section_range(skill_md_text: str) -> tuple[int, int] | None:
     start = the heading line; end = the next level-2 (`## `) heading, or EOF.
     A `### ` subsection inside the section does NOT close it (only a sibling
     `## ` heading does), matching §2's "before the next `##` heading".
+
+    The search starts after any YAML frontmatter. `_MIGRATION_HEADING` tolerates
+    leading whitespace, so an indented restatement of the heading inside a folded
+    `description:` would otherwise anchor the window in the frontmatter and leave
+    the real body section unexcluded.
     """
     lines = skill_md_text.splitlines()
+    front = frontmatter_range(skill_md_text)
+    first_body_line = front[1] + 1 if front else 1
     start = None
-    for idx, line in enumerate(lines, start=1):
-        if _MIGRATION_HEADING.match(line):
+    for idx in range(first_body_line, len(lines) + 1):
+        if _MIGRATION_HEADING.match(lines[idx - 1]):
             start = idx
             break
     if start is None:
@@ -133,6 +187,38 @@ def migration_section_range(skill_md_text: str) -> tuple[int, int] | None:
     return (start, end)
 
 
+def apply_frontmatter_exclusion(
+    matches: list[dict], skill_md_source: str | None, skill_md_text: str | None
+) -> tuple[list[dict], int]:
+    """Drop matches whose source is the compiled SKILL.md and whose line sits
+    inside its YAML frontmatter. Returns (kept, dropped).
+
+    Same circularity argument as the §4b exclusion below: compile (step 5 §2)
+    authors the frontmatter `description` from the very annotations this scan
+    looks for, so a `breaking change` / `deprecated` phrase there is already
+    surfaced, not a new correction. The frontmatter is also a closed key set of
+    pipeline scalars (`name`, `description`), so a match in it can never be an
+    upstream correction the body has missed.
+
+    Scoped to the compiled SKILL.md deliberately. evidence-report.md also carries
+    frontmatter, but its frontmatter holds pinned counts rather than authored
+    prose, so it cannot restate an upstream correction and is left in scope.
+    """
+    if skill_md_source is None or skill_md_text is None:
+        return matches, 0
+    window = frontmatter_range(skill_md_text)
+    if window is None:
+        return matches, 0
+    start, end = window
+    kept, dropped = [], 0
+    for m in matches:
+        if m["source"] == skill_md_source and start <= m["line_number"] <= end:
+            dropped += 1
+            continue
+        kept.append(m)
+    return kept, dropped
+
+
 def apply_migration_exclusion(
     matches: list[dict], skill_md_source: str | None, skill_md_text: str | None
 ) -> tuple[list[dict], int]:
@@ -153,6 +239,58 @@ def apply_migration_exclusion(
     return kept, dropped
 
 
+def collapse_duplicates(matches: list[dict]) -> tuple[list[dict], int]:
+    """Collapse matches that repeat the same text under the same category.
+
+    Returns (kept, collapsed). The dedup key is
+    `(category, whitespace-normalized lowercased context_line)` — a temporal
+    changelog restates the same deprecation across many releases, and each
+    restatement would otherwise become its own `## CORRECTION` block saying the
+    same thing.
+
+    The first occurrence in scan order survives and gains two fields:
+    `occurrences` (how many lines collapsed into it, including itself) and
+    `duplicate_of` (the `{source, line_number}` of every later occurrence), so
+    nothing is silently destroyed. Records are copies — the inputs are untouched.
+    """
+    seen: dict[tuple[str, str], dict] = {}
+    kept: list[dict] = []
+    for m in matches:
+        key = (m["category"], " ".join(m["context_line"].split()).lower())
+        survivor = seen.get(key)
+        if survivor is not None:
+            survivor["occurrences"] += 1
+            survivor["duplicate_of"].append(
+                {"source": m["source"], "line_number": m["line_number"]}
+            )
+            continue
+        record = dict(m, occurrences=1, duplicate_of=[])
+        seen[key] = record
+        kept.append(record)
+    return kept, len(matches) - len(kept)
+
+
+def apply_cap(
+    matches: list[dict], cap: int, skill_md_source: str | None
+) -> tuple[list[dict], int]:
+    """Keep at most `cap` matches. Returns (kept, dropped).
+
+    A cap of 0 or less means unlimited. Selection prefers the compiled SKILL.md's
+    own annotations over other feeders — a naive head-slice would drop them first,
+    because scan order puts the skill-md feeder last — and falls back to scan
+    order within each group. The kept records are returned in scan order, so a
+    run that does not hit the cap is ordered exactly as it is today.
+    """
+    if cap <= 0 or len(matches) <= cap:
+        return matches, 0
+    priority = sorted(
+        range(len(matches)),
+        key=lambda i: (0 if matches[i]["source"] == skill_md_source else 1, i),
+    )
+    keep = sorted(priority[:cap])
+    return [matches[i] for i in keep], len(matches) - cap
+
+
 def _load(path: str) -> str | None:
     """Read a feeder file as UTF-8. Returns None for missing/empty (skip, not
     an error). UTF-8 avoids cp1252 mojibake on Windows."""
@@ -165,9 +303,15 @@ def _load(path: str) -> str | None:
     return text
 
 
-def scan_files(feeders: list[str], skill_md: str | None) -> dict:
-    """Scan every feeder + the skill-md feeder, apply the §4b exclusion, return
-    the result object. Deterministic: feeders scanned in the given order."""
+def scan_files(
+    feeders: list[str],
+    skill_md: str | None,
+    *,
+    max_corrections: int = DEFAULT_MAX_CORRECTIONS,
+) -> dict:
+    """Scan every feeder + the skill-md feeder, apply the self-authorship
+    exclusions, collapse duplicates, cap the survivors, and return the result
+    object. Deterministic: feeders scanned in the given order."""
     scanned: list[str] = []
     matches: list[dict] = []
     skill_md_text = None
@@ -185,12 +329,21 @@ def scan_files(feeders: list[str], skill_md: str | None) -> dict:
             skill_md_text = text
         matches.extend(scan_text(text, path))
 
-    matches, excluded = apply_migration_exclusion(matches, skill_md, skill_md_text)
+    # Frontmatter first, then the §4b section — the two windows are disjoint, so
+    # the total is order-independent, but running them in file order keeps the
+    # attribution obvious when debugging a run.
+    matches, front_excluded = apply_frontmatter_exclusion(matches, skill_md, skill_md_text)
+    matches, section_excluded = apply_migration_exclusion(matches, skill_md, skill_md_text)
+    matches, deduped = collapse_duplicates(matches)
+    matches, capped = apply_cap(matches, max_corrections, skill_md)
     return {
         "scanned": scanned,
         "matches": matches,
         "match_count": len(matches),
-        "excluded_count": excluded,
+        "excluded_count": front_excluded + section_excluded,
+        "deduped_count": deduped,
+        "capped_count": capped,
+        "cap": max(max_corrections, 0),
     }
 
 
@@ -200,8 +353,9 @@ def _build_parser() -> argparse.ArgumentParser:
         description=(
             "Deterministic doc-rot correction-indicator scan (step-doc-rot.md §2): "
             "case-insensitive substring match of feeder artifacts against the fixed "
-            "correction-pattern table, with the compiled SKILL.md's Migration & "
-            "Deprecation Warnings section excluded."
+            "correction-pattern table, with the compiled SKILL.md's frontmatter and "
+            "Migration & Deprecation Warnings section excluded, duplicates collapsed, "
+            "and the survivors capped."
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
@@ -222,8 +376,18 @@ def _build_parser() -> argparse.ArgumentParser:
         "--skill-md",
         dest="skill_md",
         default=None,
-        help="Compiled/staged SKILL.md feeder; its Migration & Deprecation Warnings "
-        "section is excluded from matches.",
+        help="Compiled/staged SKILL.md feeder; its frontmatter and its Migration & "
+        "Deprecation Warnings section are excluded from matches.",
+    )
+    parser.add_argument(
+        "--max-corrections",
+        dest="max_corrections",
+        type=int,
+        default=DEFAULT_MAX_CORRECTIONS,
+        help=(
+            f"Maximum matches to emit (default {DEFAULT_MAX_CORRECTIONS}). "
+            "0 or negative means unlimited."
+        ),
     )
     return parser
 
@@ -236,7 +400,7 @@ def main(argv=None) -> int:
         parser.print_usage(file=sys.stderr)
         print("error: supply at least one feeder path or --skill-md", file=sys.stderr)
         return 1
-    result = scan_files(feeders, args.skill_md)
+    result = scan_files(feeders, args.skill_md, max_corrections=args.max_corrections)
     print(json.dumps(result, indent=2))
     return 0
 

package/src/skf-create-stack-skill/references/detect-integrations.md

@@ -145,7 +145,7 @@ For each library pair with **0 or 1 co-import files** (below the 2-file threshol
 
 **CCC precision guard for 1-file pairs (H3):** When a CCC hit would elevate a 1-file pair to qualifying status, run a post-hoc verification on that file: re-grep the file and confirm it contains explicit import statements for **both** libraries (per the ecosystem import patterns from `{manifestPatternsPath}`). If either import is missing (e.g., one library is only name-dropped in a comment or string), drop the CCC-added file from the candidate list. Only pairs with ≥2 files that each contain explicit imports for both libraries qualify. Log rejected CCC candidates in workflow state for the evidence report.
 
-**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{libA} {libB}" --path {source_root} --top 10` (CLI). See `knowledge/tool-resolution.md`.
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc search --limit 10 "{libA} {libB}"` (CLI). `ccc search` reads the index in the current working directory and has no project-selector flag (`--path` is a file-path glob filter *within* the index, and the result cap is `--limit`, not `--top`). See `knowledge/tool-resolution.md`.
 
 For pairs that already qualify (2+ files), CCC is not needed for detection — but the CCC results may surface additional integration files for richer classification in section 3.
 

package/src/skf-setup/references/ccc-index.md

@@ -32,9 +32,9 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 Read `{ccc}` and `{ccc_skip_index}` from context.
 
-**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: [], ccc_exclusion_warnings: [], settings_yml_written: false, settings_yml_patterns_added: 0}`. Proceed directly to section 4 (Auto-Proceed) — no output, no messaging.
+**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: [], ccc_exclusion_warnings: [], settings_yml_written: false, settings_yml_patterns_added: 0}`. Proceed directly to section 5 (Auto-Proceed) — no output, no messaging.
 
-**If `{ccc}` is true AND `{ccc_skip_index}` is true:** Run the exclusion-merge (section 3) so settings.yml stays current, then set `{ccc_index_result: "skipped", ccc_indexed_path: null, ccc_last_indexed: null}` and proceed to section 4 — do not run `ccc init` or `ccc index`. The envelope's `ccc_index.status` will be `"skipped"` so pipelines that plan an out-of-band re-index can distinguish "the operator opted out" from "indexing failed".
+**If `{ccc}` is true AND `{ccc_skip_index}` is true:** Run the exclusion-merge (section 3) so settings.yml stays current, then set `{ccc_index_result: "skipped", ccc_indexed_path: null, ccc_last_indexed: null}` and proceed to section 5 (Auto-Proceed) — do not run `ccc init` or `ccc index`. The envelope's `ccc_index.status` will be `"skipped"` so pipelines that plan an out-of-band re-index can distinguish "the operator opted out" from "indexing failed".
 
 **If `{ccc}` is true AND `{ccc_skip_index}` is false:** Continue to section 2.
 

package/src/skf-setup/references/report.md

@@ -77,7 +77,7 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {end if}
 
   {if hygiene_result is "qmd_unavailable":}
-  QMD Registry: skipped (daemon error — retry after `qmd start`).
+  QMD Registry: skipped (qmd unavailable — if the daemon is stopped, `qmd start` restores it).
   {end if}
 
   {if tools.ccc is true:}

package/src/skf-test-skill/references/coverage-check.md

@@ -216,9 +216,9 @@ On a split-body skill the §1 inventory (documented surface) and the §2 AST out
 
 1. **Enumerated path (`denominatorSource: "barrel"`)** — the common split-body case. `barrel_set` is the union of `exports_found[]` across every §2 per-file result. **When a stratified-scope or State-2 denominator applies (see §4) and it resolves to an enumerated name set** — the priority-2/3 re-derivation from `scope.tier_a_include` / `scope.include` globs — pass that resolved name set as `barrelSet` so the script intersects against it instead of the raw per-file union. The script computes `Documented := |documented_set ∩ barrel_set|`, `Missing := barrel_set − documented_set` (in source, not documented), `Stale := documented_set − barrel_set` (documented, not in source), and `Export Coverage = |Documented| / |barrel_set| * 100`.
 
-2. **Scalar-denominator branch (`denominatorSource: "scalar"`)** — §4 priority 1, when the resolved denominator is the scalar `metadata.json.stats.effective_denominator` (a count with **no enumerated name set**). There is no `barrel_set` to intersect, so the script instead greps each `documented_set` name across `SKILL.md ∪ references/*.md` and counts appearances. Pass `denominatorValue: effective_denominator` and `skillPackagePath: {resolved_skill_package}`; the script sets `Missing := effective_denominator − Documented` and returns an empty `Stale` (not enumerable without a barrel name set). If §4b's numerator-ground-truth arm fires (it triggers only when `exports_documented == effective_denominator`), its verified count is authoritative and **overrides** this numerator — do not apply both.
+2. **Scalar-denominator branch (`denominatorSource: "scalar"`)** — §4 priority 1, when the resolved denominator is the scalar `metadata.json.stats.effective_denominator` (a count with **no enumerated name set**). There is no `barrel_set` to intersect, so the script instead greps each `documented_set` name across `SKILL.md ∪ references/*.md` and counts appearances. Pass `denominatorValue: effective_denominator` and `skillPackagePath: {resolved_skill_package}`; the script sets `Missing := max(0, effective_denominator − Documented)` and returns an empty `Stale` (not enumerable without a barrel name set). When the grep count overshoots the denominator the script reports the surplus instead of a negative residual — see the surplus note under the returns list. If §4b's numerator-ground-truth arm fires (it triggers only when `exports_documented == effective_denominator`), its verified count is authoritative and **overrides** this numerator — do not apply both.
 
-3. **Stack-skill branch (`denominatorSource: "stack"`, `metadata.json.skill_type == "stack"`)** — a stack's source barrel is empty by design, so intersecting against it would divide by zero. Pass `denominatorValue: stack_denominator` (the §2b composition-surface denominator) and `compositionNames`: the provenance-map cited-contract names (`::`-excluded) when the map exists and is non-empty, else the `libraries` and `integration_pairs` names. The script greps each composition name across `SKILL.md ∪ references/*.md` for the numerator, sets `Missing := stack_denominator − Documented`, and omits `Stale` (no source barrel to enumerate against).
+3. **Stack-skill branch (`denominatorSource: "stack"`, `metadata.json.skill_type == "stack"`)** — a stack's source barrel is empty by design, so intersecting against it would divide by zero. Pass `denominatorValue: stack_denominator` (the §2b composition-surface denominator) and `compositionNames`: the provenance-map cited-contract names (`::`-excluded) when the map exists and is non-empty, else the `libraries` and `integration_pairs` names. The script greps each composition name across `SKILL.md ∪ references/*.md` for the numerator, sets `Missing := max(0, stack_denominator − Documented)`, and omits `Stale` (no source barrel to enumerate against). The same surplus reporting as the scalar branch applies.
 
 **Build the reconciliation input and run the script:**
 
@@ -242,11 +242,14 @@ Input JSON (one object — supply only the fields the chosen branch needs; `{rec
 
 The script returns (read these — **do not re-derive them by hand**):
 
-- `documented` — the numerator (`|documented_set ∩ barrel_set|` for barrel; grep-verified count for scalar/stack)
-- `missing` / `missingCount` — source names not documented (barrel enumerates the names; scalar/stack give only the residual count)
+- `documented` — the numerator (`|documented_set ∩ barrel_set|` for barrel; grep-verified count for scalar/stack). This is always the true count, never capped.
+- `missing` / `missingCount` — source names not documented (barrel enumerates the names; scalar/stack give only the residual count). Never negative.
 - `stale` / `staleCount` — documented names not in source (barrel only; empty with `staleApplicable: false` for scalar/stack)
 - `denominator` — `|barrel_set|` (barrel) or the resolved scalar/stack denominator
-- `exportCoverage` — `documented / denominator * 100`, already rounded
+- `exportCoverage` — `documented / denominator * 100`, already rounded; capped at 100 on the scalar/stack branches
+- `numeratorSurplus` / `coverageUncapped` / `coverageCapped` — scalar/stack only; see the surplus note below
+
+**Surplus on the grep branches.** The scalar and stack branches grep a name set against the skill body, so their numerator and denominator measure independent sets and `documented` can exceed `denominator` — a consumer-surface denominator counts one surface while the documented body may also name migration aliases or re-exported sibling symbols. When that happens the script reports `numeratorSurplus > 0` and `coverageCapped: true`, holds `exportCoverage` at 100, floors `missingCount` at 0, and preserves the raw ratio in `coverageUncapped`. **A surplus is a signal, not a pass:** it means the two sets disagree, so state it in the Coverage Analysis section (§5) alongside both counts. A large surplus on a skill whose brief carries no `scope.tier_a_include` is the deflated-denominator signature the `source-access-protocol.md` deflation guard describes — check that guard before accepting the 100.
 
 Carry these into §3's table/summary and §4's Export Coverage, and record the counts in the Coverage Analysis section (§5) so the numerator is auditable. The `exportCoverage` recorded here is the value step 5 feeds to `compute-score.py` — it is the script's value, not a parent estimate.
 
@@ -267,6 +270,8 @@ Aggregate findings across all source files:
 - Signature mismatches: {N}
 - Undocumented in SKILL.md but not in source (stale docs): `staleCount`
 
+When the script reports `coverageCapped: true`, add the surplus to the summary — `Documented (surplus over denominator): {numeratorSurplus}` and `Uncapped coverage: {coverageUncapped}%` — so the reader can see that `Missing documentation: 0` is a floored residual rather than a verified-complete surface.
+
 ### 4. Load Scoring Rules
 
 Load `{scoringRulesFile}` to determine category scores:
@@ -390,6 +395,7 @@ Append the **Coverage Analysis** section to `{outputFile}`:
 - **Missing Documentation:** {N}
 - **Signature Mismatches:** {N}
 - **Stale Documentation:** {N}
+- **Numerator Surplus:** {N} — omit this row unless `coverageCapped: true`; when present, also give the uncapped percentage
 
 ### Category Scores