bmad-module-skill-forge 2.0.0 → 2.0.1

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

@@ -24,6 +24,20 @@ descriptionGuardProbeOrder:
 frontmatterValidatorProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-frontmatter.py'
   - '{project-root}/src/shared/scripts/skf-validate-frontmatter.py'
+# Resolve `{shardBodyHelper}` by probing `{shardBodyProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. §4 uses it as the deterministic selective splitter and reads its
+# `tier1_preserved` field instead of counting Tier-1 headings pre/post by hand.
+shardBodyProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-shard-body.py'
+  - '{project-root}/src/shared/scripts/skf-shard-body.py'
+# Resolve `{renderMetadataStatsHelper}` by probing `{renderMetadataStatsProbeOrder}`
+# in order (installed SKF module path first, src/ dev-checkout fallback); first
+# existing path wins. §7 uses it in --check mode to re-derive the metadata
+# `stats` / `confidence_distribution` instead of re-doing the arithmetic by hand.
+renderMetadataStatsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-render-metadata-stats.py'
+  - '{project-root}/src/shared/scripts/skf-render-metadata-stats.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -111,14 +125,14 @@ If `restored: true` in the verify-restore output, apply §0's post-restore re-va
 
 **If skill-check was available:** Skip — already validated in step 2.
 
-**If skill-check NOT available (fallback):** Perform manual frontmatter compliance check:
+**If skill-check not available (fallback):** Perform manual frontmatter compliance check:
 
 - [ ] Frontmatter present — file starts with `---` and has closing `---`
 - [ ] `name` field — present, non-empty, lowercase alphanumeric + hyphens only, 1-64 chars
 - [ ] `name` matches skill output directory name
 - [ ] `description` field — present, non-empty, 1-1024 characters
 - [ ] No unknown fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` permitted
-- [ ] `version` and `author` are NOT in frontmatter (they belong in metadata.json)
+- [ ] `version` and `author` are not in frontmatter (they belong in metadata.json)
 
 If fails: auto-fix (deterministic), re-validate once, record result. If passes: record "Frontmatter: PASS".
 
@@ -144,13 +158,21 @@ If `restored: true` in the verify-restore output, apply §0's post-restore re-va
 
 **Mandatory approach — selective split:** Identify Tier 2 sections by their `## Full` heading prefix (e.g., `## Full API Reference`, `## Full Type Definitions`, `## Full Integration Patterns`). Extract ONLY those sections to `references/`, starting with the largest. Keep ALL Tier 1 content and any smaller sections inline. Inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval (per Vercel research).
 
-**FORBIDDEN:** Running `npx skill-check split-body --write` without prior selective extraction. The `split-body --write` command extracts ALL `##` sections top-to-bottom, destroying Tier 1 inline content that the two-tier design depends on. This command is a LAST RESORT only after selective split has been attempted and proven insufficient.
+This selective split is deterministic — run `{shardBodyHelper}` (the same splitter step 5b auto-shard uses) rather than counting and extracting by hand. **Resolve `{shardBodyHelper}`** from `{shardBodyProbeOrder}`; first existing path wins.
+
+```bash
+uv run {shardBodyHelper} <staging-skill-dir>/SKILL.md --budget 400
+```
+
+It extracts the largest `## Full` sections to `references/` until the body fits, rewrites each as a cross-reference blockquote through the atomic-write helper, and reports `sections_extracted`, `body_lines_after`, `tier1_preserved`, `xref_ok`, and `under_budget`.
 
-**If selective split alone does not bring body under the limit** (rare — typically only occurs when Tier 1 itself exceeds 300 lines): reduce Tier 1 Key API Summary and Architecture at a Glance sections to fit within limits. Do NOT fall back to automated `split-body --write` to solve a Tier 1 sizing problem.
+**Do not run `npx skill-check split-body --write` before selective extraction.** It extracts every `##` section top-to-bottom, destroying the Tier 1 inline content the two-tier design depends on — a last resort used only after selective split has been attempted and proven insufficient.
 
-**Tier 1 preservation check:** After ANY split operation, verify that ALL of the following sections remain inline in SKILL.md (not moved to references/): Overview, Quick Start, Common Workflows, Key API Summary, Migration & Deprecation Warnings (if present), Key Types, Architecture at a Glance, CLI (if present), Scripts & Assets (if present), Manual Sections. If any Tier 1 section was moved to references/, restore it immediately and re-split targeting only Tier 2 sections.
+**If selective split alone does not bring body under the limit** (the splitter reports `under_budget: false` — rare, typically only when Tier 1 itself exceeds 300 lines): reduce Tier 1 Key API Summary and Architecture at a Glance sections to fit within limits. Do not fall back to automated `split-body --write` to solve a Tier 1 sizing problem.
 
-**Post-split Tier-1 count check (mandatory):** before invoking the splitter, count the Tier-1 `##`-level section headings present in SKILL.md (any heading whose title matches one of the Tier-1 names listed above) and store as `tier1_count_pre`. After the split completes, recount as `tier1_count_post`. **HALT** if `tier1_count_post < tier1_count_pre` with: "Split reduced Tier-1 section count from {pre} to {post}. Tier-1 sections must remain inline. Restoring from staging backup and aborting body split — manual review required." Do not proceed past §4 — Tier-1 preservation is a hard invariant and a count drop indicates the splitter pulled an inline section into references/ regardless of the section-list check above (e.g., heading-text variation, capitalization, or the splitter's own heuristics).
+**Tier 1 preservation check:** After any split operation, verify that all of the following Tier 1 sections remain inline in SKILL.md (not moved to references/): Overview, Quick Start, Common Workflows, Key API Summary, Migration & Deprecation Warnings (if present), Key Types, Architecture at a Glance, CLI (if present), Scripts & Assets (if present), Manual Sections. If any was moved to references/, restore it immediately and re-split targeting only Tier 2 sections.
+
+**Post-split Tier-1 count check (mandatory):** do not recount Tier-1 headings by hand — consume the splitter's `tier1_preserved` field. `{shardBodyHelper}` compares the Tier-1 headings inline before extraction against those inline afterward and reports `tier1_preserved` (with any pulled headings in `tier1_missing`). Read it from the invocation above, or re-check any split's result with `uv run {shardBodyHelper} <staging-skill-dir>/SKILL.md --dry-run`. **HALT** if `tier1_preserved` is false with: "Split reduced Tier-1 section count (missing {tier1_missing}). Tier-1 sections must remain inline. Restoring from staging backup and aborting body split — manual review required." Do not proceed past §4 — Tier-1 preservation is a hard invariant and a `tier1_preserved: false` result means the splitter pulled an inline section into references/ regardless of the section-list check above (e.g., heading-text variation, capitalization, or the splitter's own heuristics).
 
 **Anchor validation and remediation:** After any split, verify that context-snippet section anchors (`#quick-start`, `#key-types`) still resolve to headings in SKILL.md. If an anchor no longer resolves (section was split out), restore that section to SKILL.md inline content — the context-snippet must always reference sections that exist in the main file.
 
@@ -189,8 +211,8 @@ Parse output for: `description_score`, `content_score`, `review_score`, `validat
 **Apply dismissal rules** in this order:
 
 1. **Check score thresholds** against the "Score Thresholds" table in `{tesslDismissalData}`. Most importantly:
-   - If tessl's output contains a `findings[]` entry with rule ID `description_field` (the deterministic angle-bracket / XML-tag validator): follow the **recover-then-halt** path defined by the `description-xml-tags-guarded-upstream` rule in `{tesslDismissalData}`. Re-apply step 5 §2a's `<`/`>` → `{`/`}` substitution in place on the staging SKILL.md frontmatter `description`, re-sync the in-context copy, and re-run `npx -y tessl skill review <staging-skill-dir>` once. **Re-run gate:** treat the `description_field` finding being **absent** from the re-run as the only successful recovery outcome. If the finding persists on the re-run — whether the re-substitution improved the description or not — that counts as recovery failure: halt with the original `description-xml-tags-guarded-upstream` failure message from `{tesslDismissalData}`, do NOT proceed to §6b, and do NOT downgrade the recovery to a warning. On successful recovery (finding cleared), log `description-recovery: applied ({count} substitutions)` in the evidence report under "Dismissed tessl suggestions" and continue suggestion iteration against the rerun's `judge_suggestions[]`.
-   - If the LLM-judge `description_score` is below 100 **but no `description_field` finding is present** (the deterministic validator PASSED): this is a soft discoverability signal (jargon density, trigger-term phrasing) from the judge's sub-scores, not a sanitizer bypass. Record `description_judge_score: {n}% (deterministic description_field validator PASSED)` as a warning in the evidence report and continue — do NOT trigger the recover-then-halt path and do NOT halt.
+   - If tessl's output contains a `findings[]` entry with rule ID `description_field` (the deterministic angle-bracket / XML-tag validator): follow the **recover-then-halt** path defined by the `description-xml-tags-guarded-upstream` rule in `{tesslDismissalData}`. Re-apply step 5 §2a's `<`/`>` → `{`/`}` substitution in place on the staging SKILL.md frontmatter `description`, re-sync the in-context copy, and re-run `npx -y tessl skill review <staging-skill-dir>` once. **Re-run gate:** treat the `description_field` finding being **absent** from the re-run as the only successful recovery outcome. If the finding persists on the re-run — whether the re-substitution improved the description or not — that counts as recovery failure: halt with the original `description-xml-tags-guarded-upstream` failure message from `{tesslDismissalData}`, do not proceed to §6b, and do not downgrade the recovery to a warning. On successful recovery (finding cleared), log `description-recovery: applied ({count} substitutions)` in the evidence report under "Dismissed tessl suggestions" and continue suggestion iteration against the rerun's `judge_suggestions[]`.
+   - If the LLM-judge `description_score` is below 100 **but no `description_field` finding is present** (the deterministic validator PASSED): this is a soft discoverability signal (jargon density, trigger-term phrasing) from the judge's sub-scores, not a sanitizer bypass. Record `description_judge_score: {n}% (deterministic description_field validator PASSED)` as a warning in the evidence report and continue — do not trigger the recover-then-halt path and do not halt.
    - If `review_score < 60` or `content_score < 60`: record warnings in the evidence report, continue.
 2. **Iterate `judge_suggestions[]`.** For each suggestion:
    - Cross-reference against the rules in `{tesslDismissalData}` in order.
@@ -206,7 +228,7 @@ tessl installs automatically via `npx`. A missing tool is not an error — grace
 
 **If §6 produced no novel suggestions (all dismissed via `{tesslDismissalData}`) OR tessl was unavailable:** Skip this gate — auto-proceed.
 
-**GATE [default: S]** — If `{headless_mode}` is true AND §6 produced novel suggestions: auto-select [S] Skip (a headless run has no human to triage novel suggestions), record `"tessl suggestions: {N} novel suggestion(s) auto-skipped (headless)"` in the evidence report under "Dismissed tessl suggestions", log `"headless: auto-skip {N} novel tessl suggestion(s)"`, and append `{step: "validate", gate: "tessl-suggestions", decision: "S", value: "{N} novel auto-skipped", rationale: "headless mode — no human to triage novel tessl suggestions", timestamp: {ISO}}` to the in-context `headless_decisions[]` list (step 5 §7 reads it into the evidence-report `## Auto-Decisions` table). This is the one consequential auto-decision that drops human-relevant feedback, so it must leave an audit row rather than vanishing. Then auto-proceed to §7 — do NOT present the menu below.
+**GATE [default: S]** — If `{headless_mode}` is true AND §6 produced novel suggestions: auto-select [S] Skip (a headless run has no human to triage novel suggestions), record `"tessl suggestions: {N} novel suggestion(s) auto-skipped (headless)"` in the evidence report under "Dismissed tessl suggestions", log `"headless: auto-skip {N} novel tessl suggestion(s)"`, and append `{step: "validate", gate: "tessl-suggestions", decision: "S", value: "{N} novel auto-skipped", rationale: "headless mode — no human to triage novel tessl suggestions", timestamp: {ISO}}` to the in-context `headless_decisions[]` list and, the moment it lands, append the same object as a JSON line to the durable audit sink `{sidecar_path}/auto-decisions.jsonl` (the on-landing append established at step 1 §3). §8 below reconciles the sink into the evidence-report `## Auto-Decisions` table — this is the last gate to fire; the earlier gates' rows are already in the sink and were rendered into the staged report at step 5 §7. This is the one consequential auto-decision that drops human-relevant feedback, so it must leave an audit row rather than vanishing. Then auto-proceed to §7 — do not present the menu below.
 
 **If §6 produced novel suggestions** (ones not matched by any dismissal rule) AND `{headless_mode}` is false, present them to the user:
 
@@ -234,14 +256,21 @@ tessl suggestions (novel — not matched by `{tesslDismissalData}`):
 
 ### 7. Validate metadata.json
 
-Cross-check metadata.json against extraction inventory:
-- `stats.exports_documented` / `stats.exports_public_api` / `stats.exports_internal` / `stats.exports_total` are accurate
-- `stats.public_api_coverage` and `stats.total_coverage` are correctly computed (null when denominator is 0)
-- `confidence_distribution.{t1, t1_low, t2, t3}` bin **per-export signature tiers** — each documented export lands in exactly one tier, so the four bins must **sum to `stats.exports_documented`**. Do NOT fold T2 annotation counts or T3 doc-item counts into the bins (a common error: binning ~8 annotations + ~80 doc items on top of 59 exports → sum 147 ≠ 59). `skf-test-skill` coverage-check §4b enforces this sum as an internal-consistency defect. Carve-outs mirror that consumer: for a **stack** skill the distribution bins constituents (sums to the constituent count, not `exports_documented`); for a **reference-app** it bins per-citation provenance entries (sums to the citation count, not `pattern_surfaces_documented`)
-- `spec_version` is "1.3"
-- If `scripts[]` or `assets[]` arrays present: verify `stats.scripts_count`/`stats.assets_count` match array lengths; verify `file_entries` count in provenance-map.json matches
+**Re-derive the computed fields with `{renderMetadataStatsHelper}` in check mode** rather than re-doing the arithmetic by hand. Resolve `{renderMetadataStatsHelper}` from `{renderMetadataStatsProbeOrder}` (first existing path wins; HALT if neither resolves), then run it against the staged provenance-map and metadata.json:
+
+```bash
+uv run {renderMetadataStatsHelper} <staging-skill-dir>/provenance-map.json \
+    --check <staging-skill-dir>/metadata.json
+```
+
+The helper re-bins `entries[]` by `signature_source`, recomputes `exports_documented`, `exports_total`, and `public_api_coverage` / `total_coverage` (null when the denominator is 0), and cross-checks `stats.scripts_count` / `stats.assets_count` against the `scripts[]` / `assets[]` array lengths and the provenance-map `file_entries` counts. It takes the judgment values (`exports_public_api`, `exports_internal`, `effective_denominator`) from `metadata.json` itself and infers the shape from `scope_type` / `skill_type` (pass `--shape` to override). Parse the emitted JSON (rely on the JSON, not the exit code):
 
-Auto-fix any discrepancies (these are computed values).
+- **`coherence.ok: true`** — the computed fields are internally consistent; record "Metadata: PASS".
+- **`coherence.ok: false`** — each `violations[]` entry is `{field, expected, actual}` where `expected` is the correct value. **Auto-fix each computed-value violation** (`field` starting `stats.` or `confidence_distribution.`) by setting that field in `metadata.json` to `expected` (write via `python3 {atomicWriteHelper} write --target <staging-skill-dir>/metadata.json`), leaving every other stats field — e.g. `stats.notes` on a reference app — untouched. Record "Metadata: auto-fixed {N} computed-value discrepanc(y|ies)" listing the fields. These are computed values, so the helper is authoritative — a `confidence_distribution` violation is the per-entry mis-binning compile.md §4 describes (T2 annotations + T3 doc items counted on top of the per-export tiers); the helper's per-entry counts replace them. Carve-outs are handled by `--shape`: a **stack** distribution sums to the constituent count and a **reference-app** distribution to the per-citation count, so those are consistent states, not violations. A `provenance.file_entries.*` violation is not a computed metadata field — it means the provenance-map `file_entries` and metadata counts disagree; record it as a warning for manual reconciliation rather than auto-editing the count.
+
+Then verify the two fields the helper does not own (genuine constants/contract):
+- `spec_version` is `"1.3"`.
+- `scope_type` is present and equals the brief's `scope.type` verbatim.
 
 ### 8. Update Evidence Report
 
@@ -272,6 +301,18 @@ Add validation results to evidence-report content in context:
 - {warnings, security results, tessl scores and suggestions — or "skipped"}
 ```
 
+**Auto-Decisions table (reconcile from the durable sink — idempotent):** all gates have now fired — every one appended its row to the on-disk sink `{sidecar_path}/auto-decisions.jsonl` as it landed (including §6b's tessl-suggestions row), step 5 §7 rendered the step 1–3d rows into the staged `<staging-skill-dir>/evidence-report.md`, and steps 7–9 add none. Reconcile: read the sink's JSON lines (the authoritative durable record — it survives any compaction of the in-context buffer), union them with both the `## Auto-Decisions` rows already in `<staging-skill-dir>/evidence-report.md` and the in-context `headless_decisions[]` buffer, keyed on `step`+`gate` so no decision is duplicated or dropped, and re-render the section from that union. Because the rows are recovered from the sink rather than from the possibly-compacted buffer, the audit table stays complete on a long headless run. Emit one row per entry:
+
+```
+## Auto-Decisions
+
+| Step | Gate | Decision | Rationale | Timestamp |
+|------|------|----------|-----------|-----------|
+| {step} | {gate} | {decision}{value?} | {rationale} | {timestamp} |
+```
+
+If the sink, the on-disk rows, and `headless_decisions[]` are all empty, keep the single line step 5 §7 emitted: `No auto-decisions — workflow ran interactively (or all gates had no match to auto-resolve).` This keeps the section always present so reviewers can tell "zero auto-decisions" apart from "section missing", and keeps the row count equal to `summary.auto_decision_count`.
+
 **Description Guard population:** if the §0 protocol fired during §2 (`skill-check --fix`) or §4 (`split-body`), fill the four Description Guard fields from context:
 
 - `Restored: true` when `description_guard_restored == true`, otherwise `false`.
@@ -281,17 +322,7 @@ Add validation results to evidence-report content in context:
 
 When `Restored: false`, the three follow-up fields are all `—` — this is the clean-run expected state.
 
-### 9. Menu Handling Logic
-
-**Conditional interaction step.** If tessl produced suggestions, section 6b halts for user input. Otherwise, auto-proceed.
-
-After validation completes (including any user decisions from section 6b), immediately load, read entire file, then execute `{nextStepFile}`.
-
-- Tool unavailability is a skip, not a halt
-- Validation failures are warnings — proceed to artifact generation
-- tessl gate only triggers when suggestions exist — no gate for clean reviews or unavailable tools
-
-## CRITICAL STEP COMPLETION NOTE
+### 9. Auto-Proceed
 
-ONLY WHEN validation is complete (or skipped) and evidence-report content is updated will you proceed to load `{nextStepFile}` for artifact generation.
+Conditional interaction: §6b halts for user input only when tessl produced novel suggestions; otherwise the step auto-proceeds. After validation completes (including any §6b decisions), load `{nextStepFile}`, read it fully, then execute it. Tool unavailability and validation failures are skips and warnings, never halts.
 

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

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Deterministic doc-rot correction-indicator scan (step-doc-rot.md §2).
+
+step 5c self-declares its correction scan "grep-based and deterministic — no AI
+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.
+
+The genuine judgment the step keeps in-prompt is untouched by this script:
+enriching each match's `affected` symbol from surrounding context (§2) and
+choosing where the `## CORRECTION` block goes (§3). The script emits every
+deterministic field (`source`, `pattern`, `category`, `context_line`,
+`line_number`); the prompt adds `affected`.
+
+The pattern table and category labels are the contract in step-doc-rot.md §2 —
+keep the two in lockstep.
+
+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.
+
+  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."
+
+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>},
+      ...
+    ],
+    "match_count": <int>,
+    "excluded_count": <int>             # SKILL.md matches dropped by the §4b filter
+  }
+
+Exit codes:
+  0  — scan emitted successfully (including the zero-match case)
+  1  — invalid arguments (no feeders supplied)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# Fixed correction-pattern table — mirrors step-doc-rot.md §2. (pattern, category)
+# Order is the table order; scanning is per-pattern so overlapping patterns
+# (e.g. "deprecated" ⊂ "@deprecated") each record their own hit, exactly as the
+# 13-row table enumerates them.
+PATTERN_TABLE: list[tuple[str, str]] = [
+    ("deprecated", "Deprecation"),
+    ("@deprecated", "Deprecation"),
+    ("breaking change", "Breaking change"),
+    ("BREAKING", "Breaking change"),
+    ("removed in", "Removal"),
+    ("was removed", "Removal"),
+    ("renamed to", "Rename"),
+    ("renamed from", "Rename"),
+    ("superseded by", "Supersession"),
+    ("replaced by", "Supersession"),
+    ("no longer supported", "End of life"),
+    ("migration required", "Migration"),
+    ("signature changed", "Signature change"),
+]
+
+_MIGRATION_HEADING = re.compile(r"^\s*##\s+Migration\s*&\s*Deprecation Warnings", re.IGNORECASE)
+
+
+def scan_text(text: str, source: str) -> list[dict]:
+    """Case-insensitive substring scan of `text` against PATTERN_TABLE.
+
+    Returns one record per (line, pattern) hit, in file order then table order.
+    line_number is 1-indexed. Pure — no I/O.
+    """
+    matches: list[dict] = []
+    for idx, line in enumerate(text.splitlines(), start=1):
+        lowered = line.lower()
+        for pattern, category in PATTERN_TABLE:
+            if pattern.lower() in lowered:
+                matches.append(
+                    {
+                        "source": source,
+                        "pattern": pattern,
+                        "category": category,
+                        "context_line": line.strip(),
+                        "line_number": idx,
+                    }
+                )
+    return matches
+
+
+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.
+
+    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".
+    """
+    lines = skill_md_text.splitlines()
+    start = None
+    for idx, line in enumerate(lines, start=1):
+        if _MIGRATION_HEADING.match(line):
+            start = idx
+            break
+    if start is None:
+        return None
+    end = len(lines) + 1
+    for idx in range(start + 1, len(lines) + 1):
+        if lines[idx - 1].lstrip().startswith("## "):
+            end = idx
+            break
+    return (start, end)
+
+
+def apply_migration_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 Migration & Deprecation Warnings section. Returns (kept, dropped)."""
+    if skill_md_source is None or skill_md_text is None:
+        return matches, 0
+    window = migration_section_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 _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."""
+    p = Path(path)
+    if not p.is_file():
+        return None
+    text = p.read_text(encoding="utf-8")
+    if not text.strip():
+        return 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."""
+    scanned: list[str] = []
+    matches: list[dict] = []
+    skill_md_text = None
+
+    ordered = list(feeders)
+    if skill_md is not None:
+        ordered.append(skill_md)
+
+    for path in ordered:
+        text = _load(path)
+        if text is None:
+            continue
+        scanned.append(path)
+        if path == skill_md:
+            skill_md_text = text
+        matches.extend(scan_text(text, path))
+
+    matches, excluded = apply_migration_exclusion(matches, skill_md, skill_md_text)
+    return {
+        "scanned": scanned,
+        "matches": matches,
+        "match_count": len(matches),
+        "excluded_count": excluded,
+    }
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="scan-doc-rot",
+        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."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "positional_feeders",
+        nargs="*",
+        metavar="FEEDER",
+        help="Feeder artifact paths (evidence-report.md, provenance-map.json, temporal files).",
+    )
+    parser.add_argument(
+        "--feeder",
+        action="append",
+        default=[],
+        dest="feeders",
+        help="Feeder artifact path (repeatable). Equivalent to a positional FEEDER.",
+    )
+    parser.add_argument(
+        "--skill-md",
+        dest="skill_md",
+        default=None,
+        help="Compiled/staged SKILL.md feeder; its Migration & Deprecation Warnings "
+        "section is excluded from matches.",
+    )
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    feeders = list(args.positional_feeders) + list(args.feeders)
+    if not feeders and args.skill_md is None:
+        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)
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-create-stack-skill/SKILL.md

@@ -12,6 +12,7 @@ Produces a consolidated stack skill documenting how libraries connect. **Code-mo
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- The `knowledge/` and `shared/` prefixes are the exception: they resolve from the **SKF module root** (`{project-root}/_bmad/skf/` when installed, `src/` during development), not the skill root — they point at module-shared reference docs (`knowledge/tool-resolution.md`, `knowledge/version-paths.md`) and scripts/schemas (`shared/references/…`) that live once at the module root, mirroring the resolution note `references/health-check.md` carries for `shared/health-check.md`.
 - `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
@@ -34,7 +35,9 @@ These rules apply to every step in this workflow:
 
 ## Workflow state contract
 
-Every step that emits a warning ("log a warning", "record in workflow state for the evidence report", "Warning: ...", etc.) appends a structured entry to a single in-memory list named `workflow_warnings[]`. Each entry has the shape `{step: "step-NN", severity: "info|warn|error", code: "<short-slug>", message: "<human text>", context: {<optional fields>}}`. Step 7 surfaces these in `evidence-report.md`; step 8 may add validation findings; step 9 §5 reads the accumulated list and renders the user-facing "Warnings" section. There is exactly one accumulator for the whole workflow — do not invent per-step channels.
+Every step that emits a warning appends a structured entry to a single in-memory list named `workflow_warnings[]` (the one accumulator for the whole workflow). Each entry has the shape `{step: "step-NN", severity: "info|warn|error", code: "<short-slug>", message: "<human text>", context: {<optional fields>}}`. Step 7 surfaces these in `evidence-report.md`; step 8 may add validation findings; step 9 §5 reads the accumulated list and renders the user-facing "Warnings" section.
+
+**Single-pass — no mid-run checkpoint.** State lives in memory until step 7 commits `provenance-map.json`/`evidence-report.md`; the workflow keeps no resumable checkpoint and On Activation does not probe for a prior run — the analysis is deterministic and cheap to redo, and the two gates are trivially re-confirmed. If interrupted before that commit, restart from step 1.
 
 ## Stages
 
@@ -65,14 +68,13 @@ Every step that emits a warning ("log a warning", "record in workflow state for
 
 Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
 
-| Code | Meaning              | Raised by                                                                                  |
+| Code | Meaning              | Raised by (halt_reason)                                                                     |
 | ---- | -------------------- | ------------------------------------------------------------------------------------------ |
 | 0    | success              | step 10 (terminal handoff to shared health-check)                                          |
-| 2    | input-missing / input-invalid | step 1 §0 (`config.yaml` missing or malformed); step 2 §2 headless cannot proceed without manifests (S2); step 4 §3 all extractions failed (B7); step 5 §2 feasibility-report `schemaVersion` mismatch; compose-mode-rules `schemaVersion` mismatch |
-| 3    | resolution-failure   | step 1 §1 (`forge-tier.yaml` missing); step 2 §0 compose-mode skill resolution corruption (manifest + symlink both fail); step 2 §0 compose-mode zero qualifying skills (S1/S3) |
-| 4    | write-failure        | step 7 §1 stage-dir / commit-dir failure; step 7 §1 group-dir collision when an existing non-stack skill occupies the target path |
-| 5    | overwrite-cancelled  | step 7 collision when the user declines to replace an existing stack package |
-| 6    | user-cancelled       | any interactive menu in step 3 / step 6 (user selected `[X]` Cancel and exit) |
+| 2    | input / precondition invalid | step 1 §0 `config.yaml` missing/malformed (`config-missing`); step 2 §2 headless with no manifests (`no-manifests`, S2); step 4 §3 all extractions failed (`all-extractions-failed`, B7); step 5 §2 feasibility-report `schemaVersion` mismatch (`schema-version-mismatch`) |
+| 3    | resolution-failure   | step 1 §1 `forge-tier.yaml` missing (`forge-tier-missing`); step 2 §0 compose-mode skill-resolution corruption (manifest + symlink both fail); step 2 §0 compose-mode zero qualifying skills (S1/B4); step 4 §0 compose-cycle — all `resolution-failure` |
+| 4    | write-failure        | step 7 §1 stage-dir / commit-dir failure; step 7 §1 group-dir collision when an existing non-stack skill occupies the target path — both `write-failure` |
+| 6    | user-cancelled       | any interactive menu in step 3 / step 6 when the user selects `[X]` Cancel and exit (`user-cancelled`) |
 
 ## Result Contract (Headless)
 
@@ -82,7 +84,7 @@ When `{headless_mode}` is true, step 9 emits a single-line JSON envelope on **st
 SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"…|null","skill_name":"…","stack_libraries":["…"],"mode":"code|compose","exit_code":0,"halt_reason":null}
 ```
 
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `skill_package` is the absolute path to the committed stack-skill directory (or `null` on error before commit). `skill_name` is the stack skill's published name (e.g. `{project_name}-stack`). `stack_libraries` is the array of library names included in the stack (constituent skill names in compose-mode, dependency names in code-mode). `mode` is `"code"` or `"compose"` per the run's resolved mode. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"config-missing"`, `"no-manifests"`, `"all-extractions-failed"`, `"schema-version-mismatch"`, `"resolution-failure"`, `"write-failure"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above.
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `skill_package` is the absolute path to the committed stack-skill directory (or `null` on error before commit). `skill_name` is the stack skill's published name (e.g. `{project_name}-stack`). `stack_libraries` is the array of library names included in the stack (constituent skill names in compose-mode, dependency names in code-mode). `mode` is `"code"` or `"compose"` per the run's resolved mode (`null` if the run halts before mode resolution). `halt_reason` is one of: `null` (success), `"config-missing"`, `"forge-tier-missing"`, `"no-manifests"`, `"all-extractions-failed"`, `"schema-version-mismatch"`, `"resolution-failure"`, `"write-failure"`, `"user-cancelled"`. `exit_code` matches the table above. Fields unknown at the halt point are `null` (`skill_name`) or `[]` (`stack_libraries`) — e.g. a `config-missing` halt precedes `project_name` resolution.
 
 ## On Activation
 
@@ -118,6 +120,10 @@ SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"…|null","ski
    - `{composeModeRulesPath}` ← `workflow.compose_mode_rules_path` if non-empty, else `references/compose-mode-rules.md`
    - `{provenanceMapSchemaPath}` ← `workflow.provenance_map_schema_path` if non-empty, else `assets/provenance-map-schema.md`
 
-   Stash all five as workflow-context variables. Stage files reference `{stackSkillTemplatePath}` / `{integrationPatternsPath}` / `{manifestPatternsPath}` / `{composeModeRulesPath}` / `{provenanceMapSchemaPath}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies without forking the skill.
+   Also resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — `references/report.md` §6c skips the hook invocation entirely).
+
+   Stash all five paths plus `{onCompleteCommand}` as workflow-context variables. Stage files reference `{stackSkillTemplatePath}` / `{integrationPatternsPath}` / `{manifestPatternsPath}` / `{composeModeRulesPath}` / `{provenanceMapSchemaPath}` directly; empty-string overrides fall through to the bundled default.
+
+   Also apply the array surfaces: run `workflow.activation_steps_prepend` now, keep `workflow.persistent_facts` as standing context (`file:` entries load their contents), then run `workflow.activation_steps_append` after.
 
 4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-create-stack-skill/assets/provenance-map-schema.md

@@ -53,7 +53,7 @@ Used when the workflow ran in code-mode against an actual codebase. `source_repo
 
 ## Compose-mode variant
 
-Used when the workflow ran in compose-mode against pre-generated constituent skills. Source-anchor fields (`source_repo`, `source_commit`, `source_ref`) are `null` because there is no codebase to anchor against — provenance traces back to the constituent skills instead, captured in the `constituents[]` array. Each entry's `extraction_method` is `"compose-from-skill"`; integrations have `detection_method` of `"architecture_co_mention"` (named in the architecture doc), `"constituent_documented_contract"` (a cross-library contract documented in a constituent skill's integration docs but not co-mentioned in the architecture document — e.g. a grep-verified upstream seam cited from a source skill), or `"inferred_from_shared_domain"` (synthesized inference from shared language/domain, no cited contract). `detection_method` records *how* an edge was discovered; it is orthogonal to `confidence`, which is inherited from the constituent skills per the Confidence Tier Inheritance matrix in `references/compose-mode-rules.md` (the integration tier is the weaker of the pair — never forced to a fixed band by detection method).
+Used when the workflow ran in compose-mode against pre-generated constituent skills. Source-anchor fields (`source_repo`, `source_commit`, `source_ref`) are `null` because there is no codebase to anchor against — provenance traces back to the constituent skills instead, captured in the `constituents[]` array. Each entry's `extraction_method` is `"compose-from-skill"`; integrations have `detection_method` of `"architecture_co_mention"` (named in the architecture doc), `"constituent_documented_contract"` (a cross-library contract documented in a constituent skill's integration docs but not co-mentioned in the architecture document — e.g. a grep-verified upstream seam cited from a source skill), or `"inferred_from_shared_domain"` (synthesized inference from shared language/domain, no cited contract). `detection_method` records *how* an edge was discovered; it is orthogonal to `confidence`, which is inherited from the constituent skills per the Confidence Tier Inheritance matrix in `{composeModeRulesPath}` (the integration tier is the weaker of the pair — never forced to a fixed band by detection method).
 
 ```json
 {

package/src/skf-create-stack-skill/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-create-stack-skill.
+# Team overrides:     _bmad/custom/skf-create-stack-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-create-stack-skill.user.toml (under {project-root})
 
 [workflow]
 
@@ -34,6 +36,14 @@ persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
+# Command invoked once the workflow reaches its terminal stage — after the
+# stack package is committed and the result contract is written (step 9,
+# report.md §6c), before the health-check chain. Override wins. Use for a
+# terminal action such as catalog registration or notifying a downstream
+# pipeline. Empty string = no terminal action. The hook never fails the run.
+
+on_complete = ""
+
 # --- Optional asset overrides ---
 #
 # Lift the canonical asset paths so orgs can substitute house-style copies

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

@@ -1,6 +1,5 @@
 ---
 nextStepFile: 'generate-output.md'
-stackSkillTemplate: 'assets/stack-skill-template.md'
 ---
 
 <!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
@@ -13,7 +12,7 @@ Assemble the main SKILL.md by combining per-library extractions with the integra
 
 ## Rules
 
-- Compile SKILL.md following the stack-skill-template structure — integration patterns go first (primary value)
+- Compile SKILL.md following the stack-skill-template structure — integration patterns go first
 - Do not write output files (Step 07)
 - Present compiled content for user review
 
@@ -21,7 +20,7 @@ Assemble the main SKILL.md by combining per-library extractions with the integra
 
 ### 1. Load Template Structure
 
-Load `{stackSkillTemplate}` and prepare SKILL.md section structure.
+Load `{stackSkillTemplatePath}` and prepare SKILL.md section structure.
 
 ### 2. Generate Frontmatter
 
@@ -41,12 +40,12 @@ description: >
 **Frontmatter rules:**
 
 - `name`: lowercase alphanumeric + hyphens only, must match skill output directory name. **Stack skills MUST end in `-stack`** (e.g., `{project_name}-stack`) — this is how consumers (skf-verify-stack, skf-test-skill) detect stack vs individual skills.
-- `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can..."). **Do NOT enumerate every library by name** — a 12+ library stack overruns 1024 chars. Keep the generic "{lib_count} libraries with {integration_count} integration patterns" form; if a per-library parenthetical is used, cap it to the top libraries by import/export count with a `+{N} more` suffix (full list lives in `metadata.json` `libraries[]`). See "Sizing Guidance for Large Stacks" in `{stackSkillTemplate}`.
+- `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can..."). **Do NOT enumerate every library by name** — a 12+ library stack overruns 1024 chars. Keep the generic "{lib_count} libraries with {integration_count} integration patterns" form; if a per-library parenthetical is used, cap it to the top libraries by import/export count with a `+{N} more` suffix (full list lives in `metadata.json` `libraries[]`). See "Sizing Guidance for Large Stacks" in `{stackSkillTemplatePath}`.
 - No other frontmatter fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec
 
 ### 3. Compile Integration Layer
 
-**This is the core value of the stack skill.** Compile in order:
+Compile in order:
 
 **Zero-integration guard:** If the integration graph from step 05 has zero edges (no detected integration pairs), skip the integration layer compilation and note: "No integration patterns detected — stack skill will contain library summaries without an integration layer." Proceed directly to section 4 (Per-Library Sections).
 
@@ -72,7 +71,7 @@ description: >
 `Per-Library Summaries` and `Library Reference Index` are the largest sections
 and grow with the stack. For a **large stack** (heuristic: **> 6 libraries OR
 > 6 integration patterns**), author both into `references/stack-catalog.md`
-(structure in `{stackSkillTemplate}`) and place only the inline pointer from the
+(structure in `{stackSkillTemplatePath}`) and place only the inline pointer from the
 template's "Sizing Guidance" in SKILL.md — this keeps the body under the 500-line
 `body.max_lines` budget that step 08 enforces. For a **small stack**, keep both
 inline (inline passive context yields higher task accuracy). Either way, step 08's
@@ -132,9 +131,9 @@ Display: **Select:** [C] Continue to Output Generation | [X] Cancel and exit
 
 #### EXECUTION RULES:
 
-- ALWAYS halt and wait for user input after presenting compilation
+- This is a review gate — advancing without the user's `C` would write output files from a compilation they never reviewed. Halt and wait for input after presenting the compiled SKILL.md.
 - **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve stack compilation"
-- ONLY proceed to next step when user approves and selects 'C'
+- Proceed to the next step only once the user approves by selecting `C`.
 
 #### Menu Handling Logic:
 

package/src/skf-create-stack-skill/references/compose-mode-rules.md

@@ -6,18 +6,7 @@ Rules for synthesizing a stack skill from pre-generated individual skills and an
 
 ## Skill Loading
 
-Skills use version-nested directories — see `knowledge/version-paths.md` for the full path templates and resolution rules.
-
-**Version-aware skill enumeration:**
-
-1. **Primary: Export manifest** — Read `{skills_output_folder}/.export-manifest.json`. For each entry in `exports`, resolve the active version path: `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/` — this directory must contain both `SKILL.md` and `metadata.json`.
-2. **Fallback: `active` symlinks** — If the manifest does not exist, is empty, or a manifest entry lacks an `active_version`, scan for `{skills_output_folder}/*/active/*/SKILL.md`. Each match resolves to a skill package at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template).
-3. **Filter:** Skip any skill named `{project_name}-stack` or any skill where `metadata.json` has `"skill_type": "stack"` — stack skills must not be loaded as source dependencies to avoid self-referencing loops
-4. Skip any resolved skill package missing either `SKILL.md` or `metadata.json` — log a warning and skip
-5. Load each `metadata.json` from the resolved version-aware path and extract: `name`, `language`, `confidence_tier`, `source_repo`, `exports` (count), `version`
-6. Store the skill group directory name as `skill_dir` (the top-level name under `{skills_output_folder}`, distinct from `name` — the directory may differ from the metadata name)
-7. Store the resolved package path as `skill_package_path` for use in later steps (extraction, integration detection)
-8. Store loaded skills as `raw_dependencies` with `source: "existing_skill"`
+The version-aware skill-enumeration protocol (export-manifest primary → active-symlink fallback → stack-skill filter → load metadata fields → store as `raw_dependencies`) is specified operationally in `detect-manifests.md` §0. That step runs at step 2 and has already enumerated and loaded every constituent skill into workflow state before this file is consulted at step 5, so the loading is not re-performed here — this file covers only the compose-mode composition rules below.
 
 ## Compose-mode Co-mention Precision
 
@@ -86,4 +75,4 @@ When no architecture document is available:
 - Mark all inferred integrations: `[inferred from shared domain]`
 - Inferred integrations default to lowest confidence of the pair with `[inferred from shared domain]` suffix (use this instead of `[composed]` for inferred integrations)
 
-**Constituent-documented contracts (distinct from shared-domain inference):** When a constituent skill's own integration docs cite a verifiable cross-library contract (e.g. a grep-verified upstream seam) that the architecture document does not co-mention, record it with `detection_method: constituent_documented_contract` (see `assets/provenance-map-schema.md`) — NOT `inferred_from_shared_domain`. It is a cited contract, not a synthesized guess. Its confidence still inherits the weaker tier of the pair per the matrix above — detection method is orthogonal to tier and never forces a fixed band.
+**Constituent-documented contracts (distinct from shared-domain inference):** When a constituent skill's own integration docs cite a verifiable cross-library contract (e.g. a grep-verified upstream seam) that the architecture document does not co-mention, record it with `detection_method: constituent_documented_contract` (see `{provenanceMapSchemaPath}`) — NOT `inferred_from_shared_domain`. It is a cited contract, not a synthesized guess. Its confidence still inherits the weaker tier of the pair per the matrix above — detection method is orthogonal to tier and never forces a fixed band.