bmad-module-skill-forge 2.0.2 → 2.2.0

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

@@ -3,7 +3,8 @@ nextStepFile: 'step-auto-shard.md'
 # Resolve `{detectDocsHelper}` by probing `{detectDocsProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves — §2 has no prose fallback for doc-source
-# detection (Pages-API walk, docs/ folder scan, content hashing).
+# detection (Pages-API walk, docs/ folder scan, content hashing), and §2a none
+# for docs-only URL hashing.
 detectDocsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
   - '{project-root}/src/shared/scripts/skf-detect-docs.py'
@@ -15,7 +16,7 @@ detectDocsProbeOrder:
 
 ## STEP GOAL:
 
-Record detected documentation pages and README with content hashes in metadata.json so that downstream audit (analyze-skill) can detect when upstream docs have changed since the skill was compiled.
+Record detected documentation pages and README — or, for a docs-only skill, the brief's documentation URLs — with content hashes in metadata.json so that downstream audit (analyze-skill) can detect when upstream docs have changed since the skill was compiled.
 
 ## Rules
 
@@ -35,7 +36,9 @@ Check if `doc_detection_results` is already populated in the workflow context (s
 
 ### 2. Run Doc Detection (if needed)
 
-Check that `{source_repo}` is available from the skill brief.
+**If `source_type` is `"docs-only"`:** skip detection — `source_repo` is the documentation site, not a GitHub repository, so `{detectDocsHelper} --repo-url` would exit 2 with `INVALID_URL` and leave `doc_sources[]` empty. The brief's `doc_urls` are the doc sources; continue to §2a.
+
+Otherwise check that `{source_repo}` is available from the skill brief.
 
 **If `{source_repo}` is not available:**
 - Set `doc_detection_results` to an empty array `[]`
@@ -62,8 +65,30 @@ Pass `--local-path {source_path}` when a local clone exists from the extraction
 - **Exit 1** (none found): set `doc_detection_results` to empty array `[]`
 - **Exit 2** (error): set `doc_detection_results` to empty array `[]`, add evidence note: `"Doc sources: detection partial — skf-detect-docs.py error (exit 2)"`
 
+### 2a. Docs-Only: Hash the Brief's Documentation URLs
+
+Runs only when `source_type` is `"docs-only"` (§2 routed here). Build the URL list: every `doc_urls[].url` from the brief, in brief order, followed by every subpage URL that step 3c (fetch-docs) actually fetched through subpage discovery — the `[EXT:{url}]` provenance set of the doc-fetch inventory. Include a brief URL even if step 3c could not fetch it; the helper fetches independently of the agent's web tools.
+
+**Resolve `{detectDocsHelper}`** from `{detectDocsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Pipe the list to the `hash-urls` subcommand. It fetches each URL and hashes the raw response bytes with the same primitive `skf-audit-skill` step 5a (`compare-hashes`) uses, so a hash recorded here compares byte-for-byte at audit time. Do not hash the markdown a web-fetch tool rendered in step 3c — the audit re-fetches raw bytes, and a rendered-markdown hash would report every page as drifted.
+
+```bash
+printf '%s' '["{url-1}", "{url-2}", "..."]' | uv run {detectDocsHelper} hash-urls -
+```
+
+The input may also be the brief's `doc_urls` block verbatim — an array of `{url, label}` objects, or an object with a `doc_urls` array.
+
+**Handle exit codes:**
+- **Exit 0:** parse the JSON object. Set `doc_detection_results` ← its `doc_sources` array — entries are already in the §4 schema (`url`, `detected_via: "brief_doc_urls"`, `content_hash` — `null` for a URL that could not be fetched — and `recorded_at`). Keep `fetch_failed[]` and `stats` for the §5 evidence note.
+- **Exit 2** (malformed input, unreadable file): set `doc_detection_results` to empty array `[]`, add evidence note: `"Doc sources: detection partial — skf-detect-docs.py hash-urls error (exit 2)"`
+
+Skip §3 — a docs-only brief has no repository README to track. Continue at §4.
+
 ### 3. Ensure README Entry
 
+**If `source_type` is `"docs-only"`:** skip this section — `source_repo` is the documentation site, not a repository, so there is no README to track and `{source_repo}/blob/main/README.md` would be a fabricated URL. Continue at §4.
+
 After obtaining detection results, check if any entry has a URL matching `*/README.md` or `*/readme.md`.
 
 **If a README entry already exists** from detection (e.g., `detected_via: "docs_folder"` found a README): keep it as-is.
@@ -99,6 +124,8 @@ Field mapping from `skf-detect-docs.py` output:
 
 Note: `content_type` from detect-docs output is not carried into `doc_sources`.
 
+For a docs-only skill the `hash-urls` output from §2a is already in this shape (`detected_via: "brief_doc_urls"`, `recorded_at` stamped by the helper) — copy its `doc_sources` entries verbatim.
+
 ### 5. Update metadata.json
 
 Read the staging `_bmad-output/{skill-name}/metadata.json` that compile (step 5) wrote.
@@ -117,6 +144,7 @@ Add evidence note summarizing the result:
 - Success: `"Doc sources: {N} detected, README tracked"`
 - Skip: `"Doc sources: detection skipped — {reason}"`
 - Partial: `"Doc sources: detection partial — {N} found, {errors}"`
+- Docs-only: `"Doc sources: {stats.hashed}/{stats.total} brief doc URL(s) hashed, {stats.fetch_failed} fetch failed"`
 
 ### 6. Auto-Proceed
 

package/src/skf-create-skill/references/sub/fetch-docs.md

@@ -28,6 +28,7 @@ Fetch remote documentation from brief-specified URLs using whatever web fetching
 - Tool-agnostic — use whatever web fetching capability is available
 - Do not halt the workflow if web fetching is unavailable or fails
 - Do not override existing T1, T1-low, or T2 extraction data with T3 content
+- Never delete the staging directory of a `docs-only` skill — the fetched pages are its only source corpus
 
 ## MANDATORY SEQUENCE
 
@@ -173,7 +174,7 @@ This artifact is a **distinct** carrier — it is not merged into the extraction
 
 **If tier is Deep and at least one URL was fetched successfully:**
 
-1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/`
+1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/` — clear any previous contents first, so a corpus retained from an earlier docs-only run (step 5 below) does not mix with this run's pages.
 2. Index into QMD with atomic replace + rollback: if a `{skill-name}-docs` collection already exists, run `qmd collection remove {skill-name}-docs` first, then `qmd collection add {project-root}/_bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`. **If `qmd collection add` fails after a successful `remove`:** remove any matching `{skill-name}-docs` entry from `forge-tier.yaml` → `qmd_collections[]` to keep the registry consistent with QMD's actual state, warn in evidence-report, and skip the embed — docs enrichment degrades gracefully.
 3. Generate embeddings scoped to this collection (only if step 2 `add` succeeded): `qmd embed --collection {skill-name}-docs` (required for semantic `type:'vec'` and HyDE `type:'hyde'` sub-queries within the QMD `query` tool). If the installed `qmd` CLI does not accept `--collection`, gate the embed behind a freshness check: skip re-embedding if the existing `{skill-name}-docs` registry entry is within 24 hours, and log the skip in the evidence report to prevent unbounded batch-mode re-embedding.
 4. Register in forge-tier.yaml `qmd_collections` array — **acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock` for the read-modify-write** (see the locking pattern documented in step 3b §4). Write via `python3 {atomicWriteHelper} write --target {sidecar_path}/forge-tier.yaml`. If `flock` is unavailable, fall back to read-CAS-by-mtime (capture `st_mtime` before, re-check after; refuse to clobber if a concurrent run wrote in between).
@@ -186,7 +187,7 @@ This artifact is a **distinct** carrier — it is not merged into the extraction
   created_at: "{current ISO date}"
 ```
 
-5. Clean up staging directory after indexing: `rm -rf {project-root}/_bmad-output/{skill-name}-docs/`
+5. Clean up the staging directory after indexing — **only when `source_type` is `"source"`**: `rm -rf {project-root}/_bmad-output/{skill-name}-docs/`. Note that this directory is the source path of the `{skill-name}-docs` collection registered in step 4; removing it is accepted for supplemental docs, whose T3 items already live in the extraction inventory. **When `source_type` is `"docs-only"`, keep the directory.** The fetched pages are the skill's only source corpus — there is no code tree — so deleting them would leave the just-registered collection with nothing to refresh from and nothing to verify citations against. Record the retained path in the evidence report.
 
 **If QMD indexing fails:** Warn: "QMD indexing of fetched docs failed. T3 items are still in the extraction inventory — enrichment will proceed without QMD-indexed docs." Continue.
 
@@ -199,6 +200,7 @@ Display:
 **T3 items extracted:** {count}
 **Confidence:** All doc-fetched items are T3 — `[EXT:{url}]` citations applied.
 {If docs-only mode: '**Mode:** Docs-only — all skill content is T3. source_authority: community'}
+{If docs-only mode AND tier is Deep: '**Docs corpus retained:** `_bmad-output/{skill-name}-docs/`{if the `{skill-name}-docs` collection was registered in §5b: ' — source path of QMD collection `{skill-name}-docs`'}'}
 
 Proceeding to enrichment..."
 

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

@@ -62,7 +62,7 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 
 **Used by:** §2 (`skill-check check --fix`), §4 (`split-body`), and any future tool invocation that may modify SKILL.md.
 
-Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — the calling sections (§2 and §4) invoke the helper at the capture and verify-restore points.
+Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — the calling sections (§2 and §4) invoke the helper at the capture and verify-restore points. `verify-restore` refuses an empty `--captured-description` (exit 1, file untouched); when that happens, follow the protocol's empty-snapshot rule instead of re-running with the empty value.
 
 **This skill's post-restore re-validation hook:** after `{descriptionGuardHelper}` reports `restored: true`, resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins), run `uv run {frontmatterValidator} <staging-skill-dir>/SKILL.md` and capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field, flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step 9 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
 
@@ -320,7 +320,7 @@ If the sink, the on-disk rows, and `headless_decisions[]` are all empty, keep th
 - `Original description preserved`: `true` if the restore succeeded (on-disk now matches the pre-tool snapshot), `false` if restoration itself failed (rare — treat as a halt condition in a future version).
 - `Notes`: a one-sentence description of what the tool had changed. Typical values: `"replaced with generic summary"`, `"truncated at N chars"`, `"angle-bracket tokens re-introduced"`, `"field deleted entirely"`. If `Restored: false`, use `—`.
 
-When `Restored: false`, the three follow-up fields are all `—` — this is the clean-run expected state.
+When `Restored: false`, the three follow-up fields are all `—` — this is the clean-run expected state — with one exception: when `description_guard_refused == "empty-capture"` (the protocol's empty-snapshot rule — `verify-restore` exited 1 and no in-context copy allowed a re-run), the guard did fire and must not render as a clean run. Set `Restored: false`, `Triggering tool` to the recorded tool name, `Original description preserved: false`, and `Notes: guard refused — empty captured snapshot (empty-capture)`.
 
 ### 9. Auto-Proceed
 

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

@@ -25,6 +25,7 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 - Do not display skip messages for Quick/Forge tiers
 - Do not fail the workflow if ccc indexing fails
 - The script owns exclusion-pattern validation — do not reimplement it in prose
+- Every branch that leaves this step binds all four of `ccc_index_result`, `ccc_indexed_path`, `ccc_last_indexed`, and `ccc_file_count` — step 2 interpolates each bare into the `write-tools` JSON payload, so an unbound flag would emit its literal placeholder and fail the forge-tier.yaml write
 
 ## MANDATORY SEQUENCE
 
@@ -32,9 +33,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_file_count: 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, ccc_file_count: 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.
 
@@ -44,7 +45,7 @@ Consume prior CCC state from stage 1's detector output (`prior.*` context flags)
 
 Decide `{needs_reindex}` and `{ccc_index_result}` from `{ccc_index_fresh}`:
 
-- If `{ccc_index_fresh}` is true → index is fresh. Set `{needs_reindex: false}`, `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: {previous_ccc_last_indexed}}`. Exclusions still merge in section 3 (which may force a re-index).
+- If `{ccc_index_fresh}` is true → index is fresh. Set `{needs_reindex: false}`, `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: {previous_ccc_last_indexed}, ccc_file_count: {previous_ccc_file_count}}` (the count carried over from the prior forge-tier.yaml by step 1 — nothing re-counts on this path). Exclusions still merge in section 3 (which may force a re-index).
 - If `{ccc_index_fresh}` is false (path mismatch, non-fresh status, stale timestamp, or any required prior CCC field null) → `{needs_reindex: true}`.
 
 ### 3. Merge SKF Exclusion Patterns
@@ -111,7 +112,7 @@ ccc index
 
 **If fails:**
 
-- Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null, ccc_indexing_failed_reason: {error}}` (the failed-reason flag flows into step 4's envelope warnings)
+- Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null, ccc_file_count: null, ccc_indexing_failed_reason: {error}}` (the failed-reason flag flows into step 4's envelope warnings)
 - Display: "CCC indexing failed: {error}. Extraction will use direct AST scanning — semantic pre-ranking unavailable this session."
 - Continue — this is not a workflow error
 

package/src/skf-setup/references/detect-and-tier.md

@@ -100,6 +100,7 @@ From `prior` (populated by `--prior-state-from`; all fields null/empty on first
 - `{previous_ccc_indexed_path}` ← `prior.previous_ccc_indexed_path`
 - `{previous_ccc_last_indexed}` ← `prior.previous_ccc_last_indexed`
 - `{previous_ccc_staleness_threshold_hours}` ← `prior.previous_ccc_staleness_threshold_hours`
+- `{previous_ccc_file_count}` ← `prior.previous_ccc_file_count` (integer or null; step 1b carries it forward on the fresh-index path so `forge-tier.yaml` keeps its `file_count` across re-runs that do not re-index)
 - `{ccc_index_fresh}` ← `prior.ccc_index_fresh` (boolean; the script's deterministic freshness verdict — prior index covers this project AND status was fresh/created AND `last_indexed` is within the staleness threshold of now. Step 1b branches on this directly instead of doing timestamp math.)
 
 From `deltas` (computed by the script from current tools + prior; eliminates LLM-side set arithmetic in the report banner):

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
 

package/src/skf-test-skill/references/score.md

@@ -123,7 +123,13 @@ Use these values for Section 4 (pass/fail/inconclusive) and Section 6 (output fo
 
 #### 3c. Fallback (if script execution fails)
 
-If the script is unavailable or errors, redistribute each skipped category's weight (the `null`-scored categories in the §3a JSON — naive mode already zeroes coherence, and Quick-tier/docsOnly/state2/stackSkill/referenceApp already null out Signature Accuracy + Type Coverage) proportionally across the active categories, then report `total = Σ(weight/100 × category_score)` using the detected mode's weight table in `{scoringRulesFile}`. Report: "**Note:** Scoring script unavailable — calculated manually per scoring-rules.md."
+**First distinguish "the script could not run" from "the script rejected the input" — they take opposite paths.**
+
+A `{"error": ..., "code": "INVALID_INPUT"}` envelope on stdout means the script ran fine and refused what it was given: a field is missing, mistyped, or out of range (exit 2), or the payload was not parseable JSON at all (exit 1). Either way the *input* is wrong, not the script. **Correct the §3a input and re-run.** Do not fall through to the manual redistribution below — it would hand-compute a total from the very numbers the script just refused, so an out-of-range `exportCoverage` would silently become a score. If the input cannot be corrected, report `score: scoring input rejected — {error}` and leave the score unset rather than emitting a computed total.
+
+The fallback below applies only when the script genuinely could not run — missing file, no `uv`, unreadable interpreter — that is, **no envelope on stdout at all**.
+
+If the script is unavailable, redistribute each skipped category's weight (the `null`-scored categories in the §3a JSON — naive mode already zeroes coherence, and Quick-tier/docsOnly/state2/stackSkill/referenceApp already null out Signature Accuracy + Type Coverage) proportionally across the active categories, then report `total = Σ(weight/100 × category_score)` using the detected mode's weight table in `{scoringRulesFile}`. Report: "**Note:** Scoring script unavailable — calculated manually per scoring-rules.md."
 
 ### 3d. Read Post-Score Caps (applied by the script)
 

package/src/skf-test-skill/scripts/aggregate-coherence.py

@@ -62,10 +62,14 @@ CLI usage (mirrors compute-score.py):
   uv run aggregate-coherence.py --json-input '<JSON>'     # explicit flag form
   cat input.json | uv run aggregate-coherence.py --stdin  # piped input
 
-Exit codes:
-  0  — input was parsed; either a result object or a schema-validation error
-       object ({"error": ..., "code": "INVALID_INPUT"}) was emitted as JSON
+Exit codes (same convention as compute-score.py / reconcile-coverage.py):
+  0  — a result object was emitted
   1  — input could not be parsed at all (no input provided, or malformed JSON)
+  2  — input parsed but schema/semantics invalid
+
+Both 1 and 2 emit an {"error": ..., "code": "INVALID_INPUT"} envelope on stdout,
+so the envelope's presence — not the specific code — tells a caller the input was
+refused rather than scored.
 """
 
 from __future__ import annotations
@@ -269,6 +273,12 @@ def main(argv: list[str] | None = None) -> int:
 
     result = aggregate_coherence(data)
     print(json.dumps(result, indent=2))
+    # Same convention as compute-score.py / reconcile-coverage.py. This script
+    # produces the coherence percentage that score.md §3a feeds to
+    # compute-score.py, so a silently-rejected run here would hand a bogus or
+    # absent number to the gate one layer downstream.
+    if isinstance(result, dict) and result.get("code") == "INVALID_INPUT":
+        return 2
     return 0