bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-audit-skill/references/semantic-diff.md

@@ -13,7 +13,7 @@ Compare QMD knowledge context between the original skill creation and current st
 
 ## Rules
 
-- CONDITIONAL: Skip entire analysis at Quick/Forge/Forge+ tier — append skip notice only
+- At Quick/Forge/Forge+ tier, skip the entire analysis — append the skip notice only
 - Focus only on semantic/meaning-level changes via QMD context — do not repeat structural findings from Step 03
 - Do not classify severity (Step 05)
 - Use subprocess Pattern 3 when available for QMD queries; if unavailable, query in main thread
@@ -22,7 +22,7 @@ Compare QMD knowledge context between the original skill creation and current st
 
 ### 1. Check Forge Tier
 
-**IF forge tier is Quick, Forge, or Forge+:**
+**If forge tier is Quick, Forge, or Forge+:**
 
 Append to {outputFile}:
 
@@ -40,7 +40,7 @@ Update frontmatter: append `'semantic-diff'` to `stepsCompleted`
 
 → Auto-proceed to {nextStepFile}
 
-**IF forge tier is Deep:**
+**If forge tier is Deep:**
 
 Continue to section 2.
 
@@ -127,23 +127,5 @@ Append to {outputFile}:
 
 ### 5. Update Report and Auto-Proceed
 
-Update {outputFile} frontmatter:
-- Append `'semantic-diff'` to `stepsCompleted`
-
-### 6. Present MENU OPTIONS
-
-Display: "**Semantic diff complete. {total} semantic drift items found. Proceeding to severity classification...**"
-
-#### Menu Handling Logic:
-
-- After semantic diff section is appended and frontmatter updated, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed analysis step with no user choices
-- Proceed directly to next step after completion
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the ## Semantic Drift section (or skip notice) has been appended to {outputFile} will you then load and read fully `{nextStepFile}` to execute and begin severity classification.
+Update {outputFile} frontmatter — append `'semantic-diff'` to `stepsCompleted`. Once the ## Semantic Drift section (or skip notice) has been appended, load, read fully, and execute `{nextStepFile}` (severity classification).
 

package/src/skf-audit-skill/references/severity-classify.md

@@ -1,7 +1,10 @@
 ---
 nextStepFile: 'step-doc-drift.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
-severityRulesFile: 'references/severity-rules.md'
+severityRulesFile: '{severityRulesPath}'
+severityClassifyProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-severity-classify.py'
+  - '{project-root}/src/shared/scripts/skf-severity-classify.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -10,82 +13,61 @@ severityRulesFile: 'references/severity-rules.md'
 
 ## STEP GOAL:
 
-Grade every drift finding from Steps 03 and 04 by severity level (CRITICAL/HIGH/MEDIUM/LOW) using the classification rules. Calculate the overall drift score and produce a categorized findings table with confidence tier labels.
+Grade every drift finding from Steps 03 and 04 by severity (CRITICAL/HIGH/MEDIUM/LOW), derive the overall drift score, and produce a categorized findings table with confidence-tier labels.
 
 ## Rules
 
-- Only classify severity of existing findings — do not discover new drift items or suggest remediation
-- Classification must be deterministic — apply {severityRulesFile} rules strictly
-- Use subprocess Pattern 3 when available; if unavailable, load rules and classify in main thread
+- Only classify existing findings — do not discover new drift items or suggest remediation
+- Reading each change and assigning its `type` / `category` is judgment; mapping those to a severity, reducing the set to the drift score, and counting per level are deterministic and delegated to the shared helper so the classification cannot drift from {severityRulesFile} between runs
+- The confidence tier (T1 / T1-low / T2) travels with each finding from Steps 03/04 — the helper never touches it
 
 ## MANDATORY SEQUENCE
 
-### 1. Load Severity Rules
+### 1. Collect and Categorize Findings
 
-Launch a subprocess (Pattern 3 — data operations) that:
-1. Loads {severityRulesFile}
-2. Extracts classification criteria for each severity level
-3. Returns structured rules to parent
+Gather every drift item already recorded in the report:
 
-**If subprocess unavailable:** Load {severityRulesFile} directly in main thread.
+**From ## Structural Drift (Step 03):** added, removed, changed, and moved exports (plus any Script/Asset Drift rows).
+**From ## Semantic Drift (Step 04, Deep tier only):** new patterns, changed conventions, dependency shifts, deprecated patterns.
 
-**Rules summary:**
-- **CRITICAL:** Removed/renamed exports, changed signatures (breaking changes)
-- **HIGH:** New public API not in skill (>3), removed helpers used in patterns, deprecated APIs
-- **MEDIUM:** Implementation changes behind stable API, 1-3 new exports, moved functions
-- **LOW:** Style/convention changes, comments, whitespace, internal functions
+For each finding, read {severityRulesFile} and assign the two interpretive fields the rules key on — this is the judgment step, where the nuance of the change lives:
 
-### 2. Collect All Findings
+- `type`: `removed` / `added` / `changed` / `moved` / `renamed` / `deprecated` / `semantic`
+- `category`: what the change is about — e.g. `export`, `module`, `class`, `interface`, `signature`, `parameter_count`, `return_type`, `inheritance`, `internal_helper`, `default_value`, `required_parameter`, `implementation`, `optional_parameter`, `function` (for a move), or a LOW bucket (`style`, `convention`, `comment`, `documentation`, `whitespace`, `test`, `private`, `internal`). The category carries the interpretation: a removed helper referenced in a documented pattern is `internal_helper` (→ HIGH); a new private function is `private` (→ LOW).
 
-Gather all drift items from the report:
+Build one JSON array of `{type, category, detail, confidence, file, line}` objects — carry each finding's `confidence`, `file`, `line`, and human `detail` through untouched.
 
-**From ## Structural Drift (Step 03):**
-- Added exports
-- Removed exports
-- Changed exports
+### 2. Classify, Score, and Count (deterministic)
 
-**From ## Semantic Drift (Step 04, if Deep tier):**
-- New patterns
-- Changed conventions
-- Dependency shifts
-- Deprecated patterns
+Mapping type/category to a severity, reducing the severities to an overall drift score, and counting per level each have exactly one correct answer for a given finding set — delegate them to the shared helper, which encodes {severityRulesFile} directly.
 
-Count total findings to classify.
+**Resolve `{severityClassifyHelper}`** from `{severityClassifyProbeOrder}`; first existing path wins.
 
-### 3. Apply Severity Classification
+Pipe the findings array from §1 to the helper on stdin:
 
-For EACH finding, apply the severity rules:
-
-**Structural findings classification:**
-- Removed export → CRITICAL (breaking: skill references something that no longer exists)
-- Changed signature → CRITICAL (breaking: skill documents wrong parameters/return type)
-- Renamed export → CRITICAL (breaking: skill references old name)
-- Moved export (same signature) → MEDIUM (non-breaking but location in skill is wrong)
-- Added export (>3 total) → HIGH (significant API surface not documented)
-- Added export (1-3 total) → MEDIUM (minor gap in coverage)
-
-**Semantic findings classification:**
-- Deprecated pattern still in skill → HIGH (skill teaches outdated approach)
-- Changed convention → MEDIUM (skill may use old style)
-- New pattern detected → MEDIUM (skill doesn't cover new approach)
-- Dependency shift → MEDIUM (skill may reference wrong dependencies)
+```bash
+echo '{findings_json}' | uv run {severityClassifyHelper} -
+```
 
-Record for each finding: original finding + assigned severity level.
+Parse the emitted JSON:
 
-### 4. Calculate Overall Drift Score
+```json
+{
+  "status": "ok",
+  "drift_score": "CLEAN|MINOR|SIGNIFICANT|CRITICAL",
+  "total_findings": N,
+  "by_severity": {"CRITICAL": N, "HIGH": N, "MEDIUM": N, "LOW": N},
+  "findings": [ {"type": "...", "category": "...", "detail": "...", "confidence": "...", "severity": "CRITICAL|HIGH|MEDIUM|LOW"} ]
+}
+```
 
-Apply scoring rules from {severityRulesFile}:
+Consume `by_severity`, `drift_score`, and each finding's assigned `severity` directly — do not recount or recompute the score in prose.
 
-| Score | Criteria |
-|-------|----------|
-| **CLEAN** | 0 findings at any level |
-| **MINOR** | LOW findings only, no MEDIUM+ |
-| **SIGNIFICANT** | Any MEDIUM or HIGH findings, no CRITICAL |
-| **CRITICAL** | Any CRITICAL findings present |
+**If `uv`/the helper cannot execute** (e.g. claude.ai web): fall back to classifying in the main thread — apply {severityRulesFile}'s severity levels to each finding's type/category, then reduce with its Overall Drift Score table (CLEAN = no findings; MINOR = LOW only; SIGNIFICANT = any MEDIUM/HIGH, no CRITICAL; CRITICAL = any CRITICAL present).
 
-### 5. Compile Severity Classification Section
+### 3. Compile Severity Classification Section
 
-**Rollup inherits from step 3.** If step 3 §5 collapsed ≥ 10 same-kind findings into a single rollup row (deleted source file, renamed module, entire package tree removed), carry that rollup through to the matching severity table as one row — do not re-expand it here. Keep the existing 6-column severity table shape; the rollup encodes root cause, count, and representative symbols **inline in the `Finding` cell** rather than adding new columns, so rollup and per-item rows render cleanly in one table. Changed-signature and cross-file findings remain per-row; they were not eligible for rollup in step 3 and are not eligible here.
+**Rollup inherits from step 3.** If step 3 §5 collapsed ≥ 10 same-kind findings into a single rollup row (deleted source file, renamed module, entire package tree removed), carry that rollup through to the matching severity table as one row — do not re-expand it here. Keep the 6-column severity table shape; the rollup encodes root cause, count, and representative symbols **inline in the `Finding` cell** rather than adding columns, so rollup and per-item rows render cleanly in one table. Changed-signature and cross-file findings remain per-row; they were not eligible for rollup in step 3 and are not eligible here.
 
 **Rollup row form (any severity table):**
 
@@ -93,32 +75,32 @@ Apply scoring rules from {severityRulesFile}:
 |---|---------|------|--------|----------|------------|
 | N | {root cause} (×{Count}; rep: `{sym1}`, `{sym2}`, `{sym3}`, …) | {structural/semantic} | {shared detail} | {root-cause path} | {T1/T2} |
 
-Append to {outputFile}:
+Append to {outputFile}, filling the counts from `by_severity` and each finding's assigned `severity`:
 
 ```markdown
 ## Severity Classification
 
-**Overall Drift Score: {CLEAN / MINOR / SIGNIFICANT / CRITICAL}**
+**Overall Drift Score: {drift_score}**
 
-### CRITICAL ({count})
+### CRITICAL ({by_severity.CRITICAL})
 
 | # | Finding | Type | Detail | Location | Confidence |
 |---|---------|------|--------|----------|------------|
 | 1 | {finding} | {structural/semantic} | {detail} | {file}:{line} | {T1/T2} |
 
-### HIGH ({count})
+### HIGH ({by_severity.HIGH})
 
 | # | Finding | Type | Detail | Location | Confidence |
 |---|---------|------|--------|----------|------------|
 | 1 | {finding} | {structural/semantic} | {detail} | {file}:{line} | {T1/T2} |
 
-### MEDIUM ({count})
+### MEDIUM ({by_severity.MEDIUM})
 
 | # | Finding | Type | Detail | Location | Confidence |
 |---|---------|------|--------|----------|------------|
 | 1 | {finding} | {structural/semantic} | {detail} | {file}:{line} | {T1/T2} |
 
-### LOW ({count})
+### LOW ({by_severity.LOW})
 
 | # | Finding | Type | Detail | Location | Confidence |
 |---|---------|------|--------|----------|------------|
@@ -126,35 +108,19 @@ Append to {outputFile}:
 
 ### Classification Summary
 
-| Severity | Count | Source |
-|----------|-------|--------|
-| CRITICAL | {count} | {structural: N, semantic: N} |
-| HIGH | {count} | {structural: N, semantic: N} |
-| MEDIUM | {count} | {structural: N, semantic: N} |
-| LOW | {count} | {structural: N, semantic: N} |
-| **Total** | {total} | |
+| Severity | Count |
+|----------|-------|
+| CRITICAL | {by_severity.CRITICAL} |
+| HIGH | {by_severity.HIGH} |
+| MEDIUM | {by_severity.MEDIUM} |
+| LOW | {by_severity.LOW} |
+| **Total** | {total_findings} |
 ```
 
-### 6. Update Report and Auto-Proceed
+### 4. Update Report and Auto-Proceed
 
 Update {outputFile} frontmatter:
 - Append `'severity-classify'` to `stepsCompleted`
-- Set `drift_score` to calculated overall score
-
-### 7. Present MENU OPTIONS
-
-Display: "**Severity classification complete. Overall drift score: {score}. Proceeding to report generation...**"
-
-#### Menu Handling Logic:
-
-- After severity classification section is appended and frontmatter updated, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed analysis step with no user choices
-- Proceed directly to next step after completion
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the ## Severity Classification section has been appended to {outputFile} with all findings classified will you then load and read fully `{nextStepFile}` to execute and begin final report generation.
+- Set `drift_score` to `{drift_score}` from the helper
 
+Once the ## Severity Classification section has been appended with all findings classified, load, read fully, and execute `{nextStepFile}` (documentation drift).

package/src/skf-audit-skill/references/step-doc-drift.md

@@ -1,6 +1,13 @@
 ---
 nextStepFile: 'report.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
+# Resolve `{compareDocHashesHelper}` by probing `{compareDocHashesProbeOrder}`
+# in order (installed SKF module path first, src/ dev-checkout fallback); first
+# existing path wins. When neither resolves (uv/python absent), §2 falls back to
+# skipping the doc-drift check with a notice — see the graceful-failure rule.
+compareDocHashesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
+  - '{project-root}/src/shared/scripts/skf-detect-docs.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -53,15 +60,38 @@ Set `doc_drift_summary = { total_tracked: 0, skipped_entirely: false }` in workf
 
 ### 2. Fetch and Hash Each Tracked Doc
 
-For each entry in `doc_sources`:
+Fetching each URL, hashing the response bytes, comparing against the stored `content_hash`, and categorizing the outcome is deterministic work — and the model cannot compute a `sha256:{hexdigest}` of fetched bytes natively (it must shell out). Delegate the whole fetch/hash/compare pass to the shared script, which hashes byte-symmetrically with how `doc_sources` hashes were written at compile time and fetches independently of whether a WebFetch tool is wired.
 
-1. Read `url` and `content_hash` from the entry
-2. **If `content_hash` is `null`:** Skip this entry — there is no baseline to compare against. Record it for the report as a null-hash entry. Do not attempt to fetch the URL.
-3. **If `content_hash` is non-null:** Attempt HTTP GET of the URL with a reasonable timeout (10s)
-   - **On success:** Compute `sha256:{hexdigest}` of the response body bytes (UTF-8 encoding). Compare against the stored `content_hash`. If they differ, record as drifted. If they match, record as unchanged.
-   - **On failure (network error, timeout, non-200 status):** Record the entry as `status: "fetch_failed"` with the failure reason. Do not report as drift.
+**Resolve `{compareDocHashesHelper}`** from `{compareDocHashesProbeOrder}`; first existing path wins.
 
-If URL fetching is unavailable in the current environment, skip doc drift check entirely with:
+Run one deterministic comparison subprocess over the skill's `doc_sources`. The script reads the `doc_sources` array straight out of the skill's `metadata.json` (or accepts a bare `doc_sources` array, or `-` for stdin):
+
+```bash
+uv run {compareDocHashesHelper} compare-hashes {skill_path}/metadata.json
+```
+
+For each entry, the script:
+- **`content_hash` is `null`** → records it under `skipped_null_hash` and does **not** fetch the URL (there is no baseline to compare against).
+- **`content_hash` is non-null** → HTTP GETs the URL (15s timeout, same User-Agent as the compile side), computes `sha256:{hexdigest}` of the response body bytes, and compares against the stored `content_hash` (prefix-normalized so a bare-hex writer form still matches).
+  - Hashes match → `unchanged`.
+  - Hashes differ → `changed`, carrying `old_hash` and `new_hash`.
+  - Network error, timeout, or non-200 status → `fetch_failed`, carrying the failure `reason`. Not reported as drift.
+
+Parse the emitted JSON:
+
+```json
+{
+  "changed":           [{"url": "...", "old_hash": "sha256:...", "new_hash": "sha256:..."}],
+  "unchanged":         [{"url": "..."}],
+  "fetch_failed":      [{"url": "...", "old_hash": "sha256:...", "reason": "..."}],
+  "skipped_null_hash": [{"url": "..."}],
+  "stats": {"total_tracked": N, "changed": N, "unchanged": N, "fetch_failed": N, "skipped_null_hash": N}
+}
+```
+
+The script exits 0 on any well-formed input (even when everything drifted) and exits 2 only on malformed args/JSON — it never blocks this informational audit.
+
+If `uv`/`python` is unavailable or the script cannot be resolved — i.e. URL fetching is unavailable in the current environment — skip the doc drift check entirely with:
 
 ```markdown
 ## Documentation Drift
@@ -73,18 +103,18 @@ Set `doc_drift_summary = { skipped_entirely: true }` and auto-proceed.
 
 ### 3. Build Drift Findings
 
-Categorize results:
-- **changed:** entries where `content_hash` differs from newly computed hash
-- **unchanged:** entries where hashes match
-- **fetch_failed:** entries where the URL could not be reached
-- **skipped_null_hash:** entries where `content_hash` was `null`
+Read the categories and totals directly from the script's JSON — no manual counting. The four buckets are already computed:
+- **changed:** entries where the stored `content_hash` differs from the newly computed hash (`changed[]`)
+- **unchanged:** entries where the hashes match (`unchanged[]`)
+- **fetch_failed:** entries where the URL could not be reached (`fetch_failed[]`)
+- **skipped_null_hash:** entries where `content_hash` was `null` (`skipped_null_hash[]`)
 
-Compute totals:
-- `total_tracked` = length of `doc_sources`
-- `changed` = count of drifted entries
-- `unchanged` = count of matching entries
-- `fetch_failed` = count of fetch failures
-- `skipped_null_hash` = count of null-hash entries
+Take the totals straight from `stats` (do not recount):
+- `total_tracked` = `stats.total_tracked`
+- `changed` = `stats.changed`
+- `unchanged` = `stats.unchanged`
+- `fetch_failed` = `stats.fetch_failed`
+- `skipped_null_hash` = `stats.skipped_null_hash`
 
 ### 4. Append to Drift Report
 
@@ -144,4 +174,4 @@ Load, read the full file, then execute {nextStepFile}.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN the ## Documentation Drift section has been appended to {outputFile} and workflow context updated will you then load and read fully `{nextStepFile}` to begin final report generation.
+Only when the ## Documentation Drift section has been appended to {outputFile} and workflow context updated do you then load and read fully `{nextStepFile}` to begin final report generation.

package/src/skf-audit-skill/references/structural-diff.md

@@ -7,6 +7,9 @@ loadProvenanceProbeOrder:
 compareFileHashesProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-compare-file-hashes.py'
   - '{project-root}/src/shared/scripts/skf-compare-file-hashes.py'
+structuralDiffProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-structural-diff.py'
+  - '{project-root}/src/shared/scripts/skf-structural-diff.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -25,69 +28,57 @@ Compare the original provenance map extractions from create-skill against the cu
 
 ## MANDATORY SEQUENCE
 
-### 1. Prepare Comparison Sets
+### 1. Run the Deterministic Export Diff
 
-Load both datasets:
+The export comparison — canonicalization, set arithmetic (added/removed/moved), and field-level change detection — is fully deterministic and runs in one subprocess. Do **not** diff the two export lists by hand: an LLM comparing dozens or hundreds of exports can silently drop or mis-match entries, which violates this skill's zero-hallucination contract.
 
-**Baseline (from provenance map):**
-- Export list with names, types, signatures, file paths, line numbers
+**Resolve `{structuralDiffHelper}`** from `{structuralDiffProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
-**Current (from Step 02 extraction):**
-- Export list with names, types, signatures, file paths, line numbers
+Run one comparison over the baseline provenance map (from step 1) and the current extraction snapshot (`{extractionSnapshot}`, written to disk by step 2 §3):
 
-**Canonicalize extractor methodology differences before matching.** The extractor used by `skf-create-skill` at baseline time and the re-extractor used by step 2 can differ in cosmetic detail (quote style, module qualification, re-export resolution). Without normalization, those cosmetic differences surface as false-positive "Changed" and "Removed" entries even when the source commit has not moved. Apply these transforms to both sets symmetrically:
-
-- **Quote style on string defaults.** Normalize string-literal defaults in signatures to a single style — e.g., `kind: str = "Hnsw"` ↔ `kind: str = 'Hnsw'`. Pick one canonical form and apply to both sides.
-- **Module qualification of stdlib helpers.** Strip module prefixes on well-known stdlib helpers when the unqualified form is importable at the call site: `dataclasses.field(...)` → `field(...)`, `typing.Optional[...]` → `Optional[...]`, `typing.List[...]` → `List[...]`. Do not collapse user-defined namespaces.
-- **Public-API re-export resolution.** When `{source_root}/**/__init__.py` re-exports an internal symbol under a different public name (`from .internal import _Impl as Public`, or via `__all__`), resolve both sides to the public name before key-matching — otherwise a renamed re-export in the current scan shows up as "Removed `_Impl`" + "Added `Public`" instead of matching the baseline entry. The re-export map is already in workflow context as `{reexport_map}` (produced by `skf-load-provenance.py normalize` in step 1 §4). Apply it directly without re-walking `__init__.py` files.
-
-Record the set of transforms actually applied in workflow context — step 6 surfaces them in the Provenance section so a reviewer can tell which differences the diff collapsed and which were real.
-
-Normalize both sets for comparison:
-- Match by canonicalized export name (primary key)
-- Group by file for location-aware comparison
-
-> **Longer-term fix.** The principled remedy is to persist `skf-create-skill`'s ast-grep ruleset to `{forge_version}/extraction-rules.yaml` at create time and have step 2 replay that exact ruleset. When the file is present, step 2 extraction becomes reproducible against the baseline and the canonicalization pass above becomes a no-op. Until then, normalization is the salvage remediation for provenance maps that predate extractor pinning.
+```bash
+uv run {structuralDiffHelper} {provenanceMap} {extractionSnapshot}
+```
 
-### 2. Detect Added Exports
+The helper reads both shapes directly — the provenance map's `entries[]` (with `export_name`/`export_type`/`source_file`/`source_line`) and the snapshot's `exports[]` — and aliases the field names, so no manual projection is needed.
 
-**Launch subprocess (Pattern 4 — parallel execution):** In Claude Code, use multiple parallel Agent tool calls. In CLI, use `xargs -P` or equivalent.
+**Canonicalization is applied inside the helper, symmetrically to both sides**, before name-keyed matching — so cosmetic extractor differences do not surface as false-positive "Changed"/"Removed"/"Added" entries:
 
-Find exports that exist in current scan but NOT in provenance map.
+- **Quote style on string defaults** — `kind: str = "Hnsw"` ↔ `kind: str = 'Hnsw'`.
+- **Stdlib module qualification** — `typing.Optional[...]` → `Optional[...]`, `dataclasses.field(...)` → `field(...)` (user-defined namespaces are never collapsed).
+- **Public-API re-export resolution** — a renamed public re-export (`_Impl` → `Public`) matches the baseline entry instead of splitting into "Removed `_Impl`" + "Added `Public`". The re-export map is **auto-derived from the provenance map** (identical to the `{reexport_map}` projection `skf-load-provenance.py normalize` produced in step 1 §4). Pass `--reexport-map {file}` only to override with a custom map.
 
-For each added export, record:
-- Export name, type, signature
-- File path and line number (from current scan)
-- Confidence tier (T1 if AST-backed, T1-low if text-based)
+Parse the emitted JSON:
 
-**If subprocess unavailable:** Iterate current exports, check against provenance map set.
+```
+{
+  "summary": {"added": N, "removed": N, "changed": N, "moved": N, "unchanged": N},
+  "added":   [ <entry>, ... ],   // in current snapshot, NOT in provenance map
+  "removed": [ <entry>, ... ],   // in provenance map, NOT in current snapshot
+  "changed": [ {"name", "field", "baseline_value", "current_value"}, ... ],
+  "moved":   [ {"name", "previous_file", "current_file"}, ... ],
+  "unchanged_count": N,
+  "applied_transforms": [ {"transform": "quote-style|stdlib-prefix|reexport-resolution", "count": N}, ... ]
+}
+```
 
-### 3. Detect Removed Exports
+Stash `applied_transforms` in workflow context — step 6 surfaces it in the Provenance section so a reviewer can tell which cosmetic differences the diff collapsed and which changes were real.
 
-Find exports that exist in provenance map but NOT in current scan.
+**If `uv` / the helper cannot execute** (e.g. claude.ai web): fall back to comparing the two lists by hand — match by canonicalized export name (apply the three transforms above to both sides), then read off added (current-only), removed (baseline-only), moved (same name, different `file`), and changed (matched name, differing type/signature/line). Compare a field only when it is present on both sides.
 
-For each removed export, record:
-- Export name, type, signature (from provenance map)
-- Original file path and line number
-- Confidence tier (T1 if AST-backed, T1-low if text-based)
+### 2. Read Added / Removed / Moved from the Diff
 
-**Special check:** If export name exists but in a different file, classify as MOVED (not removed).
+These sets come straight from the helper's JSON — no further set arithmetic:
 
-### 4. Detect Changed Exports
+- **Added** — `added[]`: exports in the current snapshot but not the provenance map. Each carries name, type, signature, file, line, confidence.
+- **Removed** — `removed[]`: exports in the provenance map but not the current snapshot. Same fields (in provenance-map field names).
+- **Moved** — `moved[]`: matched exports whose file path changed (`previous_file` → `current_file`). A move is **not** a removal.
 
-Find exports that exist in BOTH sets but have differences.
+Confidence tier for each entry is the `confidence` field the extractor recorded (T1 if AST-backed, T1-low if text-based).
 
-Compare:
-- **Signature changes:** Parameter count, parameter types, return type
-- **Type changes:** Function became class, const became function, etc.
-- **Location changes:** Same name/signature but different file or line number (MOVED)
+### 3. Read Changed Exports from the Diff
 
-For each changed export, record:
-- Export name
-- Original signature → Current signature
-- Original location → Current location
-- What changed (signature / type / location)
-- Confidence tier
+`changed[]` lists per-field differences for exports present in BOTH sets. Each item names the export, the `field` that changed (type / signature / line / confidence), and its `baseline_value` → `current_value`. Group items by export name when compiling the report, and pair with the export's `moved[]` entry (if any) to describe location changes.
 
 ### 4b. Detect Script/Asset Drift
 
@@ -114,7 +105,9 @@ Parse the emitted JSON:
 
 Hash-prefix normalization (writer-vs-reader compatibility — `skf-create-skill` writes `content_hash` with a `"sha256:"` prefix, a bare-hex hash from `hashlib` would otherwise never match) is handled inside the script. Downstream consumers read `added`/`removed`/`changed` directly with no further normalization.
 
-Append the three lists into the Structural Drift section as "### Script/Asset Drift ({stats.added + stats.removed + stats.changed})".
+Append the three lists into the Structural Drift section under a `### Script/Asset Drift (added {stats.added}, removed {stats.removed}, changed {stats.changed})` heading — take each count straight from `stats`, no recount.
+
+**If `uv`/the helper cannot execute** (e.g. claude.ai web): skip the script/asset drift check with a `### Script/Asset Drift — skipped (hashing helper unavailable)` note rather than blocking the audit. This check is supplementary to the export diff, which has its own by-hand fallback in §1.
 
 ### Stack-Specific Structural Diff
 
@@ -122,7 +115,7 @@ If `{is_stack_skill}` is true:
 
 **For v2 provenance (per-export entries with `source_library`):**
 - Group entries by `source_library`
-- For each library, perform the standard structural diff (same as single-skill) against current source
+- For each library, run the same deterministic diff as the single-skill path (§1) — pass the per-library baseline slice and the matching current snapshot to `{structuralDiffHelper}`
 - Report per-library diff results
 
 **For code-mode stacks:** Re-extract from each source repo and compare per-library entries.
@@ -135,7 +128,7 @@ If `{is_stack_skill}` is true:
 
 ### 5. Compile Structural Drift Section
 
-**Rollup for high-volume uniform findings.** When ≥ 10 findings in the same table share one root cause (deleted source file, renamed module, entire package tree removed), you MAY collapse them into one row per root cause. Rollup rows replace the per-symbol `Export`/`Signature` columns with `Count` and `Representative symbols` (up to 3 names, `…` if more). Rollup applies to **Added Exports**, **Removed Exports**, and **Script/Asset Drift** tables — **not** to Changed Exports, which are heterogeneous by construction (signature changes and cross-file changes are inspected per-finding). Record which groupings were collapsed in workflow context for reviewer traceability.
+**Rollup for high-volume uniform findings.** When ≥ 10 findings in the same table share one root cause (deleted source file, renamed module, entire package tree removed), you may collapse them into one row per root cause. Rollup rows replace the per-symbol `Export`/`Signature` columns with `Count` and `Representative symbols` (up to 3 names, `…` if more). Rollup applies to **Added Exports**, **Removed Exports**, and **Script/Asset Drift** tables — **not** to Changed Exports, which are heterogeneous by construction (signature changes and cross-file changes are inspected per-finding). Record which groupings were collapsed in workflow context for reviewer traceability.
 
 **Rollup row form (Added / Removed Exports):**
 
@@ -181,23 +174,5 @@ Append to {outputFile}:
 
 ### 6. Update Report and Auto-Proceed
 
-Update {outputFile} frontmatter:
-- Append `'structural-diff'` to `stepsCompleted`
-
-### 7. Present MENU OPTIONS
-
-Display: "**Structural diff complete. {total} drift items found. Proceeding to semantic diff...**"
-
-#### Menu Handling Logic:
-
-- After structural diff section is appended and frontmatter updated, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed analysis step with no user choices
-- Proceed directly to next step after completion
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the ## Structural Drift section has been appended to {outputFile} with all findings documented will you then load and read fully `{nextStepFile}` to execute and begin semantic diff analysis.
+Update {outputFile} frontmatter — append `'structural-diff'` to `stepsCompleted`. Once the ## Structural Drift section has been appended, load, read fully, and execute `{nextStepFile}` (semantic diff).
 

package/src/skf-brief-skill/SKILL.md

@@ -9,11 +9,9 @@ description: Design a skill scope through guided discovery. Use when the user re
 
 Helps the user define what to skill — target repo, scope, language, inclusion/exclusion patterns — and produces a `skill-brief.yaml` that drives create-skill. This is the first step in the skill creation pipeline; the brief is the input contract for create-skill, which performs the actual compilation.
 
-A good skill brief sets a tight, cohesive boundary: one capability with 3-8 primary functions, an unambiguous public API surface, and a description short enough to fit in a registry row. Briefs that try to cover several unrelated concerns (e.g. authentication *and* data visualization) compile into skills that no agent can route to confidently — a brief covering too much is a worse failure mode than a brief covering too little, and this workflow steers toward the smaller, sharper version when scope is unclear.
+A good skill brief sets a tight, cohesive boundary: one capability with 3-8 primary functions, an unambiguous public API surface, and a description short enough to fit in a registry row. Briefs that try to cover several unrelated concerns (e.g. authentication *and* data visualization) compile into skills that no agent can route to confidently — a brief covering too much is a worse failure mode than a brief covering too little, and this workflow steers toward the smaller, sharper version when scope is unclear. Scope on cheap signals — manifests, top-level exports, intent — not full AST extraction.
 
-Brief-skill is split from create-skill so the scoping conversation runs *once*, on cheap signals (manifests, top-level exports, intent), without paying for AST extraction. Compilation is expensive; scoping decisions are cheap to revise. Keeping them in separate workflows lets a user iterate on the brief, share it for review, and re-run create-skill against the same brief whenever the upstream version moves.
-
-**Ratify path.** When the user already has a `skill-brief.yaml` produced by another workflow — typically `skf-analyze-source`'s `generate-briefs` step, where one analyze pass emits several recommended briefs — the brief can be *ratified* (reviewed and rewritten without re-deriving its fields) instead of authored from scratch. **Interactively:** invoke `/skf-brief-skill` with a path to that brief at the first prompt — gather-intent §3.1a loads the YAML, hydrates the brief context, and jumps straight to step 4 (confirm-brief) where the standard review/edit cycle still applies before step 5 writes. **Headlessly:** pass `from_brief <path>` — the step 1 §8 GATE runs the same schema validation and hydration and writes through the canonical writer (overwriting in place), enabling a fully headless analyze → brief → create pipeline that preserves the upstream-authored scope. Either path skips re-deriving fields the upstream draft already supplies and saves the 5-10 minutes a full re-run of intent + analyze + scope would cost.
+**Ratify path.** A pre-authored `skill-brief.yaml` (typically from `skf-analyze-source`'s `generate-briefs` step) can be *ratified* — reviewed and rewritten in place — instead of re-derived from scratch. Interactively, pass its path at the first prompt; headlessly, pass `from_brief <path>`. See the `from_brief` Inputs cell in `references/invocation-contract.md` for the full ratify contract.
 
 ## Conventions
 
@@ -63,8 +61,11 @@ These rules apply to every step in this workflow:
    - `{descriptionVoiceExamplesPath}` ← `workflow.description_voice_examples_path` if non-empty, else `assets/description-voice-examples.md`
    - `{scopeTemplatesPath}` ← `workflow.scope_templates_path` if non-empty, else `assets/scope-templates.md`
    - `{briefSchemaPath}` ← `workflow.brief_schema_path` if non-empty, else `assets/skill-brief-schema.md`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — write-brief.md skips the hook invocation entirely)
+
+   Stash all four as workflow-context variables. Stage files reference `{descriptionVoiceExamplesPath}` / `{scopeTemplatesPath}` / `{briefSchemaPath}` / `{onCompleteCommand}` 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 (or wire in a pipeline hook) without forking the skill.
 
-   Stash all three as workflow-context variables. Stage files reference `{descriptionVoiceExamplesPath}` / `{scopeTemplatesPath}` / `{briefSchemaPath}` 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 apply the array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries are paths or globs whose contents load as facts — the bundled default loads any `project-context.md` under `{project-root}`); then, after activation completes and before step 4 loads the first stage, execute each entry in `workflow.activation_steps_append` in order.
 
 4. Load, read the full file, and execute `references/gather-intent.md`.
 
@@ -85,34 +86,4 @@ Stages 1a-1b are conditional — they replace stages 2-5 when BS is invoked with
 
 ## Invocation Contract
 
-| Aspect | Detail |
-|--------|--------|
-| **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting], `from_brief` [optional: path to a pre-authored `skill-brief.yaml` to *ratify* — when supplied it is the source of truth, `target_repo`/`skill_name` become optional/derived-from-brief, and the run mirrors the interactive §3.1a ratify path: schema-validate, skip analyze-target/scope-definition, write through the canonical writer in place], `[auto]` [optional: bracket modifier passed via pipeline context — when present, BS loads the upstream brief from `brief_path` in pipeline data, enriches it with doc detection, and writes through the canonical writer; requires `brief_path` from AN's `SKF_ANALYZE_RESULT_JSON`] |
-| **Gates** | step 1: Input Gate [use args] | step 3: Confirm Gate [C] | step 4: Confirm Gate [C] |
-| **Outputs** | `skill-brief.yaml` at `{forge_data_folder}/{skill-name}/skill-brief.yaml`; final `SKF_BRIEF_RESULT_JSON` line on stdout when `{headless_mode}` is true |
-| **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; pre-supplied inputs consumed at the gates that would otherwise prompt; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise); supplying `from_brief <path>` instead routes the step 1 GATE to a ratify path that schema-validates the pre-authored brief, skips analyze-target/scope-definition, and writes through the canonical writer (overwriting in place, no `--force` needed) rather than deriving a new brief |
-| **Transient-failure retry** | This workflow does **not** auto-retry network or subprocess failures. A failed `gh` fetch (analyze-target.md §1, portfolio-similarity-check.md), QMD probe, or extraction script is logged and surfaced in the final result envelope as a warning, but the workflow continues with whatever signal it has. Headless pipelines that want retry semantics should wrap the invocation at their orchestrator level (e.g. CI re-runner on non-zero exit). Rationale: brief-skill is read-mostly with one terminal write (the YAML at step 5); a partial-signal retry has more failure modes than just re-running the whole workflow, which is cheap. |
-| **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                                                                                  |
-| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
-| 0    | success              | step 6 (terminal)                                                                         |
-| 2    | input-missing / input-invalid | step 1 GATE — required headless arg absent (`target_repo`, `skill_name`, or `doc_urls` when `source_type=docs-only`) → `input-missing`; enum violation, malformed semver, non-kebab `skill_name`, or step 5 brief-context schema validation failure → `input-invalid` |
-| 3    | resolution-failure   | step 1 §1 (`forge-tier.yaml` missing); step 2 §1 (target inaccessible / `gh auth` fails) |
-| 4    | write-failure        | step 1 §1 pre-flight write probe (data folder unwritable: read-only mount, disk full, permissions denied); step 5 §4 (write to `{forge_data_folder}/{skill-name}/skill-brief.yaml` failed) |
-| 5    | overwrite-cancelled  | step 5 §2 (existing brief, `force` not supplied)                                          |
-| 6    | user-cancelled       | any interactive menu in step 1/03/04 (user selected `[X]` Cancel and exit)                |
-
-## Result Contract (Headless)
-
-When `{headless_mode}` is true, step 5 emits a single-line JSON envelope on **stdout** before chaining to step 6, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
-
-```
-SKF_BRIEF_RESULT_JSON: {"status":"success|error","brief_path":"…|null","skill_name":"…","version":"…|null","language":"…|null","scope_type":"…|null","exit_code":0,"halt_reason":null,"mode":"auto|null"}
-```
-
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"target-inaccessible"`, `"gh-auth-failed"`, `"write-failed"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above. `mode` is `"auto"` when BS was invoked with the `[auto]` flag (pipeline auto-brief generation), `null` otherwise (interactive or headless-without-auto).
+Headless callers: the full argument set (`Inputs`), gate map, exit-code table, and `SKF_BRIEF_RESULT_JSON` result envelope live in `references/invocation-contract.md`. Interactive runs do not need it.

package/src/skf-brief-skill/assets/scope-templates.md

@@ -121,7 +121,7 @@ Auto-detect demo directories and file patterns:
 - Directories: `demo/`, `demos/`, `stories/`, `examples/`, `__stories__/`, `storybook/`
 - Files: `*.stories.*`, `*.story.*`, `*.example.*`, `*.demo.*`
 
-Present detected patterns to user before applying (do NOT exclude silently).
+Show detected patterns to the user for confirmation before applying them, rather than excluding files silently.
 Prompt: "**Auto-detected {N} demo/example files** in {M} directories. Confirm exclusion? [Y/n] Or adjust patterns:"
 
 **Phase 3 — Variant Selection (if applicable):**