bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -1,55 +1,74 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # ///
-"""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 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
-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.
+"""Doc-rot correction-candidate scan (step-doc-rot.md §2).
+
+Step 5c writes a `## CORRECTION` block for each live upstream correction to an
+export the compiled skill documents. This helper finds the candidates: it
+walks the resolved feeder artifacts, matches every line against the fixed
+13-row keyword table with case-insensitive substring containment (no regex,
+no semantics), and emits each hit with the kind of change its keyword
+suggests (`candidate_category`), a ranking hint. A keyword is not a
+correction: "No breaking changes in this release" holds one, and so do a pull
+request template checkbox and a bug fix that mentions a deprecation warning.
+Nor is every correction worded with one: a Keep a Changelog "### Removed"
+bullet that names `Client.close_all`, or "Renamed `load` to `read`", holds
+none. So with --provenance (the staged provenance map), a line of the
+project's own announcements (the temporal feeder's changelog.md,
+releases.md and prs.md) that names an export the map lists is a candidate
+too. Every candidate carries the nearest headings above it: `release`, the
+nearest one naming a version (`## [2.3.0] - 2024-05-01`, `## v2.3.0`), and
+`section`, the nearest one under that (`### Removed`). The step's judgment
+pass decides which candidates are live corrections, then caps the blocks at
+10. Running the scan here (instead of in-prompt) keeps the candidate list
+identical for identical feeders: the model never hand-greps multi-KB
+artifacts.
+
+Before it returns, the script drops 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.
+
+Bounding matters because the temporal feeder is a verbatim upstream dump
+(changelog, release notes, issue and pull request bodies), so an unbounded
+run can hand the judgment pass hundreds of "breaking" and "deprecated" lines.
+Two deterministic bounds run after the exclusions: duplicate collapse (same
+candidate category + same normalized line text) and a cap on the candidate
+pool. Keyword hits, and export mentions under a change section, come first;
+a plain export mention (an "### Added" bullet) gets only the places left. A
+change section is a heading whose whole text is a change name (Keep a
+Changelog's `### Deprecated`, `### Removed` and `### Changed`, `## Breaking
+Changes`, `## Migration Guide`), never one with such a word inside it:
+GitHub's generated `## What's Changed` and a pull request template's
+`## Type of change` head every line of their feeder. Within each of those two
+ranks the feeders share the cap in turns, so a years-deep changelog cannot
+crowd out the release notes, and the compiled SKILL.md's own lines of a rank
+come after every other feeder's lines of that rank, so the skill's own text
+never outranks an upstream line of the same rank.
+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.
 
 CLI usage:
-  uv run scan-doc-rot.py --skill-md <staged SKILL.md> [FEEDER ...]
+  uv run scan-doc-rot.py --skill-md <staged SKILL.md> [--provenance <map>] [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 YAML frontmatter or its `## Migration &
-                     Deprecation Warnings` section are excluded. It is also
+                     Deprecation Warnings` section are excluded, and its other
+                     candidates come last when the pool is capped. 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.
+  --provenance       the staged provenance-map.json: its entries[].export_name
+                     values are the exports a changelog.md, releases.md or
+                     prs.md line may name (`default` aside). Missing, empty or
+                     unreadable: no export is known, as without the flag.
+  --max-candidates   cap on emitted candidates (default 50). 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."
@@ -57,9 +76,13 @@ CLI usage:
 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",
+    "matches": [                        # the candidates step 5c's judgment pass reviews
+      {"source": "<path>", "pattern": "deprecated" | null,  # null: an export mention
+       "candidate_category": "Deprecation" | null,
        "context_line": "<line text>", "line_number": <1-indexed int>,
+       "exports": ["<export_name>", ...],  # the known exports the line names
+       "release": "<heading>" | null,     # nearest heading above naming a version
+       "section": "<heading>" | null,     # nearest heading below that one
        "occurrences": <int>,            # 1 unless duplicates collapsed into this record
        "duplicate_of": [{"source": "<path>", "line_number": <int>}, ...]},
       ...
@@ -67,8 +90,9 @@ Output (stdout, one object):
     "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)
+    "capped_count": <int>,              # candidates dropped because the cap was reached
+    "cap": <int>,                       # effective cap (0 = unlimited)
+    "exports_known": <int>              # export names --provenance gave
   }
 
 Exit codes:
@@ -79,12 +103,14 @@ Exit codes:
 from __future__ import annotations
 
 import argparse
+import itertools
 import json
 import re
 import sys
 from pathlib import Path
 
-# Fixed correction-pattern table — mirrors step-doc-rot.md §2. (pattern, category)
+# Fixed keyword table: (pattern, candidate_category). A hit makes the line a
+# candidate for step-doc-rot.md §2's judgment pass, never a correction by itself.
 # 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.
@@ -106,32 +132,83 @@ 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]:
+# The temporal feeder files that carry the project's own announcements: a line
+# of one that names a known export is a candidate (issues.md and
+# targeted-issues.md hold reports anyone can open, which §2 drops anyway).
+EXPORT_FEEDERS = frozenset({"changelog.md", "releases.md", "prs.md"})
+# An export name too common to mean the export when a line says it.
+IGNORED_EXPORT_NAMES = frozenset({"default"})
+_HEADING = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
+_FENCE = re.compile(r"^\s*(```|~~~)")
+# A heading that names a release: a version (`[2.3.0]`, `v2.3.0`, `2.3`) or Unreleased.
+_RELEASE_HEADING = re.compile(r"\bv?\d+\.\d+|\bunreleased\b", re.IGNORECASE)
+# A change section: a heading whose whole text, its marks stripped, is one of
+# these names. Its export mentions rank with the keyword hits.
+_CHANGE_SECTION = re.compile(
+    r"deprecated|deprecations?|removed|removals?|changed|breaking(?: changes?)?|migrations?(?: guide)?",
+    re.IGNORECASE,
+)
+# The marks around a heading's words: `[Removed]`, `Removed:`, `⚠ BREAKING CHANGES`.
+_HEADING_MARKS = re.compile(r"^[\W_]+|[\W_]+$")
+_IDENTIFIER = re.compile(r"[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*")
+
+# Cap on the candidate pool one run hands the judgment pass (step-doc-rot.md §2).
+# The pass keeps at most 10 corrections (step 5b budgets the compiled body at 400
+# lines and each block is ~7 lines), so 50 candidates leaves room for the many
+# keyword lines that are no correction at all.
+DEFAULT_MAX_CANDIDATES = 50
+
+
+def named_exports(line: str, exports: frozenset[str]) -> list[str]:
+    """The known export names `line` names: each dotted identifier on it
+    (`Client.close_all`) and each of its parts (`close_all`), checked
+    against the set. Sorted, each once."""
+    found: set[str] = set()
+    for token in _IDENTIFIER.findall(line):
+        for name in (token, *token.split(".")):
+            if name in exports:
+                found.add(name)
+    return sorted(found)
+
+
+def scan_text(
+    text: str, source: str, exports: frozenset[str] = frozenset(), export_feeder: bool = False
+) -> 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.
+    Returns one record per (line, pattern) hit, in file order then table
+    order, and, when `export_feeder`, one record for a line with no hit that
+    names an export of `exports` (pattern and candidate_category null).
+    Every record carries the line's `exports` and the nearest `release` and
+    `section` headings above it (headings inside a code fence do not count).
+    line_number is 1-indexed. Pure: no I/O.
     """
     matches: list[dict] = []
+    release: str | None = None
+    section: str | None = None
+    fenced = False
     for idx, line in enumerate(text.splitlines(), start=1):
+        if _FENCE.match(line):
+            fenced = not fenced
+        heading = None if fenced else _HEADING.match(line)
+        if heading:
+            title = line.strip()
+            if _RELEASE_HEADING.search(heading.group(2)):
+                release, section = title, None
+            else:
+                section = title
+        named = named_exports(line, exports) if exports else []
         lowered = line.lower()
-        for pattern, category in PATTERN_TABLE:
+        context = {"context_line": line.strip(), "line_number": idx, "exports": named,
+                   "release": release, "section": None if heading else section}
+        hit = False
+        for pattern, candidate_category in PATTERN_TABLE:
             if pattern.lower() in lowered:
-                matches.append(
-                    {
-                        "source": source,
-                        "pattern": pattern,
-                        "category": category,
-                        "context_line": line.strip(),
-                        "line_number": idx,
-                    }
-                )
+                hit = True
+                matches.append({"source": source, "pattern": pattern,
+                                "candidate_category": candidate_category, **context})
+        if not hit and export_feeder and named:
+            matches.append({"source": source, "pattern": None, "candidate_category": None, **context})
     return matches
 
 
@@ -240,23 +317,25 @@ def apply_migration_exclusion(
 
 
 def collapse_duplicates(matches: list[dict]) -> tuple[list[dict], int]:
-    """Collapse matches that repeat the same text under the same category.
+    """Collapse matches that repeat the same text under the same candidate 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.
+    `(candidate_category, whitespace-normalized lowercased context_line)`: a
+    temporal changelog restates the same deprecation across many releases, and
+    a pull request template repeats the same checkbox in every pull request, so
+    each restatement would otherwise be its own candidate 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.
+    `occurrences` (how many keyword hits collapsed into it, itself included)
+    and `duplicate_of` (the `{source, line_number}` of every later hit), so
+    nothing is silently destroyed. Two keywords of one candidate category on
+    one line count twice, and the second hit points back at the same line.
+    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())
+        key = (m["candidate_category"], " ".join(m["context_line"].split()).lower())
         survivor = seen.get(key)
         if survivor is not None:
             survivor["occurrences"] += 1
@@ -270,24 +349,50 @@ def collapse_duplicates(matches: list[dict]) -> tuple[list[dict], int]:
     return kept, len(matches) - len(kept)
 
 
+def change_section(section: str | None) -> bool:
+    """True when `section` (a heading line) is a change section: its text,
+    without its `#`s and the marks around its words, is a change name as a
+    whole. `### Removed` and `## Breaking Changes` are; `## What's Changed`
+    and `## Type of change` are not."""
+    title = _HEADING_MARKS.sub("", (section or "").strip().lstrip("#"))
+    return bool(_CHANGE_SECTION.fullmatch(title))
+
+
+def rank(match: dict) -> int:
+    """0 for a keyword hit or a line under a change section, 1 for a plain
+    export mention (an "### Added" bullet)."""
+    if match.get("pattern") is not None:
+        return 0
+    return 0 if change_section(match.get("section")) else 1
+
+
 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.
+    """Keep at most `cap` candidates. Returns (kept, dropped).
+
+    A cap of 0 or less means unlimited. Rank 0 (keyword hits, and export
+    mentions under a change section) fills the cap before rank 1 (plain
+    export mentions). Within a rank the feeders share the cap in turns: each
+    turn takes the next candidate of every feeder, in scan order, so one long
+    feeder (a years-deep changelog) cannot crowd out the rest. The compiled
+    SKILL.md's own candidates take only the places of their rank left after
+    every other feeder's, because its body restates what compile wrote: the
+    skill's own text never outranks an upstream line of its rank. The kept records are
+    returned in scan order, so a run that does not hit the cap is ordered
+    exactly as the scan.
     """
     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])
+    order: list[int] = []
+    for level in (0, 1):
+        by_feeder: dict[str, list[int]] = {}
+        for i, m in enumerate(matches):
+            if m["source"] != skill_md_source and rank(m) == level:
+                by_feeder.setdefault(m["source"], []).append(i)
+        order += [i for turn in itertools.zip_longest(*by_feeder.values()) for i in turn if i is not None]
+        order += [i for i, m in enumerate(matches) if m["source"] == skill_md_source and rank(m) == level]
+    keep = sorted(order[:cap])
     return [matches[i] for i in keep], len(matches) - cap
 
 
@@ -303,18 +408,35 @@ def _load(path: str) -> str | None:
     return text
 
 
+def load_exports(path: str | None) -> frozenset[str]:
+    """The entries[].export_name values of a provenance map; empty when the
+    path is None, missing, empty or not a provenance map."""
+    text = _load(path) if path else None
+    if text is None:
+        return frozenset()
+    try:
+        data = json.loads(text)
+    except ValueError:
+        return frozenset()
+    entries = data.get("entries") if isinstance(data, dict) else None
+    names = {e.get("export_name") for e in entries or [] if isinstance(e, dict)}
+    return frozenset(n for n in names if isinstance(n, str) and n and n not in IGNORED_EXPORT_NAMES)
+
+
 def scan_files(
     feeders: list[str],
     skill_md: str | None,
     *,
-    max_corrections: int = DEFAULT_MAX_CORRECTIONS,
+    max_candidates: int = DEFAULT_MAX_CANDIDATES,
+    provenance: str | None = None,
 ) -> 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."""
+    exclusions, collapse duplicates, cap the candidate pool, and return the
+    result object. Deterministic: feeders scanned in the given order."""
     scanned: list[str] = []
     matches: list[dict] = []
     skill_md_text = None
+    exports = load_exports(provenance)
 
     ordered = list(feeders)
     if skill_md is not None:
@@ -327,7 +449,8 @@ def scan_files(
         scanned.append(path)
         if path == skill_md:
             skill_md_text = text
-        matches.extend(scan_text(text, path))
+        export_feeder = path != skill_md and Path(path).name in EXPORT_FEEDERS
+        matches.extend(scan_text(text, path, exports, export_feeder))
 
     # 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
@@ -335,7 +458,7 @@ def scan_files(
     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)
+    matches, capped = apply_cap(matches, max_candidates, skill_md)
     return {
         "scanned": scanned,
         "matches": matches,
@@ -343,7 +466,8 @@ def scan_files(
         "excluded_count": front_excluded + section_excluded,
         "deduped_count": deduped,
         "capped_count": capped,
-        "cap": max(max_corrections, 0),
+        "cap": max(max_candidates, 0),
+        "exports_known": len(exports),
     }
 
 
@@ -351,11 +475,12 @@ def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="scan-doc-rot",
         description=(
-            "Deterministic doc-rot correction-indicator scan (step-doc-rot.md §2): "
+            "Doc-rot correction-candidate 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 frontmatter and "
+            "keyword table, with the compiled SKILL.md's frontmatter and "
             "Migration & Deprecation Warnings section excluded, duplicates collapsed, "
-            "and the survivors capped."
+            "and the candidate pool capped. The step's judgment pass decides which "
+            "candidates are corrections."
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
@@ -377,15 +502,23 @@ def _build_parser() -> argparse.ArgumentParser:
         dest="skill_md",
         default=None,
         help="Compiled/staged SKILL.md feeder; its frontmatter and its Migration & "
-        "Deprecation Warnings section are excluded from matches.",
+        "Deprecation Warnings section are excluded from matches, and its other "
+        "candidates come last when the pool is capped.",
+    )
+    parser.add_argument(
+        "--provenance",
+        dest="provenance",
+        default=None,
+        help="The staged provenance-map.json: a changelog.md, releases.md or prs.md line "
+        "that names one of its entries[].export_name values is a candidate too.",
     )
     parser.add_argument(
-        "--max-corrections",
-        dest="max_corrections",
+        "--max-candidates",
+        dest="max_candidates",
         type=int,
-        default=DEFAULT_MAX_CORRECTIONS,
+        default=DEFAULT_MAX_CANDIDATES,
         help=(
-            f"Maximum matches to emit (default {DEFAULT_MAX_CORRECTIONS}). "
+            f"Maximum candidates to emit (default {DEFAULT_MAX_CANDIDATES}). "
             "0 or negative means unlimited."
         ),
     )
@@ -400,7 +533,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, max_corrections=args.max_corrections)
+    result = scan_files(feeders, args.skill_md, max_candidates=args.max_candidates, provenance=args.provenance)
     print(json.dumps(result, indent=2))
     return 0
 

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

@@ -11,9 +11,10 @@ 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.
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root, inside a `references/` file too: only a stage's frontmatter `nextStepFile` names a file beside it.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; e.g. `knowledge/tool-resolution.md`, `knowledge/version-paths.md` and `shared/references/feasibility-report-schema.md`.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `assets/` holds the stack skill template, the metadata contract and the provenance map schema.
 - `{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.
 - `{skill-name}` resolves to the skill directory's basename.
@@ -28,23 +29,33 @@ These rules apply to every step in this workflow:
 
 - Zero hallucination — all extracted content must trace to actual source code (compose-mode inferences must be labeled)
 - Only load one step file at a time — never preload future steps
-- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread, with two exceptions: never decide by hand whether SKF generated a folder (the ownership check), and never work out by hand what a shared helper computes where its step names a `helper-missing` HALT: that helper resolving to no path stops the run with exit 3 `helper-missing` (`references/invocation-contract.md` lists every such halt). Where a step says what to do without its helper (an advisory check, a default value), do as it says
+- Never write into a skill folder SKF did not generate — generate-output §1 runs the inventory's write check before any prior metadata is read and again before staging
 - Always communicate in `{communication_language}`
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
-- Warnings use a single accumulator — see `## Workflow state contract` below for shape and surfacing.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action, and record each auto-decision in the run sink the moment the gate takes it, with the `record --decision` command the gate shows
+- Every HARD HALT names its exit code, `halt_reason` and phase, and prints its envelope through the shared emitter with the command its step file shows (the `init:emitter` halt, with no emitter, only displays its message); never type an `SKF_STACK_RESULT_JSON` line
+- Warnings use a single accumulator: see `## Workflow state contract` below for shape and surfacing.
 
 ## Workflow state contract
 
-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.
+Every step that emits a warning appends a structured entry to a single 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>}}`. Appending one means recording it in the run sink at once, the `context` fields folded into the message. Write its `[{step}/{severity}] {code}: {message}` line to `{run_dir}/warning.txt` with a file write, never an `echo`: a message can quote backticks or `$( )`, which a shell runs. Then run:
 
-**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.
+```bash
+uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/warning.txt")"
+```
+
+The shell does not expand what the substitution prints, so the message reaches the sink as text.
+
+The sink, `{run_dir}/warnings.jsonl`, is the list: step 7 §8b lists it in `evidence-report.md`, step 9 §1 renders it, and the result envelope carries it.
+
+**Single-pass, no resume:** the run's state lives in `{run_dir}`, the run folder step 1 creates under `{project-root}/_bmad-output/.skf-run/` (the warnings and auto-decisions, step 3's import counts, step 4's extraction bundle and step 6's draft), and an interrupted run starts again from step 1.
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Initialize & Mode Detection | references/init.md | No (confirm) |
-| 2 | Detect Manifests | references/detect-manifests.md | Yes |
+| 1 | Initialize & Mode Detection | references/init.md | Conditional |
+| 2 | Detect Manifests | references/detect-manifests.md | Conditional (no manifest found) |
 | 3 | Rank & Confirm Libraries | references/rank-and-confirm.md | No (confirm) |
 | 4 | Parallel Extract | references/parallel-extract.md | Yes |
 | 5 | Detect Integrations | references/detect-integrations.md | Yes |
@@ -56,35 +67,7 @@ Every step that emits a warning appends a structured entry to a single in-memory
 
 ## Invocation Contract
 
-| Aspect | Detail |
-|--------|--------|
-| **Inputs** | project_path [required], mode (code/compose) [auto-detected] |
-| **Gates** | step 3: Confirm Gate [C] | step 6: Review Gate [C] |
-| **Outputs** | SKILL.md (stack), context-snippet.md, metadata.json |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
-| **Exit codes** | See "Exit Codes" below |
-
-## Exit Codes
-
-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 (halt_reason)                                                                     |
-| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
-| 0    | success              | step 10 (terminal handoff to shared health-check)                                          |
-| 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)
-
-When `{headless_mode}` is true, step 9 emits a single-line JSON envelope on **stdout** before chaining to step 10, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
-
-```
-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 (`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.
+`references/invocation-contract.md` holds the inputs, gates and outputs, the exit code and `halt_reason` of every HARD HALT, and the `SKF_STACK_RESULT_JSON` result envelope.
 
 ## On Activation
 
@@ -100,30 +83,20 @@ SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"…|null","ski
 3. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
-
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
-
-   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-create-stack-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran): `references/init.md` records it as the run's first warning once its pre-flight has created `{run_dir}`.
 
-   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the five scalars, if the merged value is empty or absent, use the bundled default:
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the two scalars, if the merged value is empty or absent, use the bundled default:
 
-   - `{stackSkillTemplatePath}` ← `workflow.stack_skill_template_path` if non-empty, else `assets/stack-skill-template.md`
+   - `{stackSkillTemplatePath}` ← `workflow.stack_skill_template_path` if non-empty, else `assets/stack-skill-template.md` (the SKILL.md, snippet and reference-file structures; `assets/metadata-contract.md` holds the `metadata.json` contract, which no override replaces)
    - `{integrationPatternsPath}` ← `workflow.integration_patterns_path` if non-empty, else `references/integration-patterns.md`
-   - `{manifestPatternsPath}` ← `workflow.manifest_patterns_path` if non-empty, else `references/manifest-patterns.md`
-   - `{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`
 
-   Also resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — `references/report.md` §6c skips the hook invocation entirely).
+   Also resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op: `references/report.md` §2c then skips the hook).
 
-   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.
+   Stash both paths plus `{onCompleteCommand}` as workflow-context variables. Stage files reference `{stackSkillTemplatePath}` and `{integrationPatternsPath}` 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.
+   Also apply the array surfaces: run `workflow.activation_steps_prepend` now, keep `workflow.persistent_facts` as standing context (`file:` entries load their contents: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off), then run `workflow.activation_steps_append` after.
 
 4. Load, read the full file, and then execute `references/init.md` to begin the workflow.