bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/{workflows/audit-skill → skf-audit-skill}/steps-c/step-02-re-index.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-02-re-index'
-description: 'Re-scan source code with current tier tools to build fresh extraction snapshot'
-
 nextStepFile: './step-03-structural-diff.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
@@ -12,43 +9,11 @@ outputFile: '{forge_version}/drift-report-{timestamp}.md'
 
 Re-scan the source code using the current forge tier tools to build a fresh extraction snapshot. This snapshot will be compared against the original provenance map in Step 03 to detect structural drift.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a skill auditor operating in Ferris Audit mode
-- ✅ Every extraction must be precise — file paths, line numbers, signatures
-- ✅ You enforce zero-hallucination: only extract what actually exists in source
-
-### Step-Specific Rules:
+## Rules
 
-- 🎯 Focus only on extracting current source state — do NOT compare yet
-- 🚫 FORBIDDEN to perform any diff or comparison — that happens in Step 03
-- 🚫 FORBIDDEN to skip files or take shortcuts in extraction
-- 💬 Use subprocess Pattern 2 (per-file deep analysis) when available for AST extraction
-- ⚙️ If subprocess unavailable, perform extraction in main thread file by file
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Extract all public exports from source using tier-appropriate tools
-- 💾 Store current extraction as internal state for Step 03
-- 📖 Update {outputFile} frontmatter stepsCompleted when complete
-- 🚫 Do not append analysis sections to drift report — only update frontmatter
-
-## CONTEXT BOUNDARIES:
-
-- Available: Source path, forge tier, tool availability (from Step 01)
-- Focus: Building a complete current-state extraction snapshot
-- Limits: Extract only — no comparison, no judgment, no severity
-- Dependencies: Step 01 must have loaded skill baseline and validated source path
+- Focus only on extracting current source state — do not compare yet (that's Step 03)
+- Do not skip files or take shortcuts in extraction
+- Use subprocess Pattern 2 (per-file deep analysis) when available for AST extraction; if unavailable, extract in main thread file by file
 
 ## MANDATORY SEQUENCE
 
@@ -78,26 +43,47 @@ Based on forge tier detected in Step 01:
 - Query qmd_bridge for temporal context: when exports were added, modification history, usage frequency
 - Confidence labels: T1 for structural, T2 for temporal context
 
-**Tool resolution:** `gh_bridge` → `gh api` commands or direct file I/O if local. `ast_bridge` → ast-grep MCP tools (`find_code`, `find_code_by_rule`) or `ast-grep` CLI. `qmd_bridge` → QMD MCP tools (`search`, `vector_search`) or `qmd` CLI. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**Tool resolution:** `gh_bridge` → `gh api` commands or direct file I/O if local. `ast_bridge` → ast-grep MCP tools (`find_code`, `find_code_by_rule`) or `ast-grep` CLI. `qmd_bridge` → QMD MCP tools (`search`, `vector_search`) or `qmd` CLI. See `knowledge/tool-resolution.md`.
+
+### 2. Build Bounded Scan List
+
+Audit-skill detects drift on files that were in scope during create-skill. The authoritative record of "what was in scope" is the provenance map loaded in step-01. Scan only those files — **audit-skill does NOT discover new files**. New-file detection is the responsibility of `skf-update-skill`, which maintains its own change manifest. To audit a project that has grown new files since creation, run update-skill first, then audit-skill.
 
-### 2. Scan Source Files
+**Why bounded:** without this constraint, files that were deliberately excluded by the original brief's scope patterns (test fixtures, vendored code, generated artifacts, demo code, unrelated modules) get scanned on every audit and their exports are flagged by step-03 structural diff as "added" — false-positive drift that obscures real structural changes.
 
-Identify all source files in the source directory that contain public exports.
+**If a provenance map was loaded in step-01** (normal mode):
 
-"**Scanning source files...**"
+1. Extract the unique set of file paths from the provenance map:
+   - `entries[].source_file` (one path per extracted export)
+   - `file_entries[].source_file` (one path per tracked script/asset, when present)
+2. Deduplicate the combined list. This is the **bounded scan list**.
+3. Verify each path under `{source_root}`. Files that existed at creation time but are now missing are **not** errors at this stage — keep them in the list so step-03 can classify them as DELETED. Handling missing files is step-03's job, not step-02's.
+4. Record `bounded_scan: true` and `bounded_scan_source: "provenance-map"` in context for the evidence report.
+5. Report:
 
-- List all relevant source files (exclude test files, config files, build artifacts)
-- Count files to process
-- Report: "Found {count} source files to extract."
+   "**Bounded scan:** {count} files from provenance map ({provenance_date})."
+
+**If degraded mode** (no provenance map was loaded — user confirmed `[D]egraded mode` at step-01 §4):
+
+1. Fall back to a source-tree scan: list all source files under `{source_root}` matching the project's primary language extensions (derive from `metadata.json.language` — e.g., `*.ts` / `*.tsx` for typescript, `*.py` for python, `*.rs` for rust, `*.go` for go).
+2. Apply generic exclusions: `**/tests/**`, `**/test/**`, `**/__tests__/**`, `*.test.*`, `*.spec.*`, `node_modules/**`, `dist/**`, `build/**`, `target/**`, `__pycache__/**`, `.venv/**`, `vendor/**`.
+3. Record `bounded_scan: false` and `bounded_scan_source: "source-tree-fallback"` in context.
+4. Report:
+
+   "**Degraded mode scan:** {count} files from source tree (no provenance map — results may include files out of the original brief scope)."
+
+**Count files to process** and proceed to section 3 with the resolved scan list.
 
 ### 3. Extract Current Exports
 
-**DO NOT BE LAZY — For EACH source file, launch a subprocess that:**
+**DO NOT BE LAZY — For EACH file in the bounded scan list from §2, launch a subprocess that:**
 1. Loads the source file
 2. Extracts all public exports using tier-appropriate method
 3. Records: export name, type, signature, file path, line number, confidence tier
 4. Returns structured findings to parent
 
+**If a file from the bounded scan list is missing on disk:** record `{file, exports: [], status: "missing"}` and continue — step-03 structural diff will classify exports previously at this path as DELETED.
+
 **If subprocess unavailable:** Perform extraction in main thread, processing each file sequentially.
 
 **Build extraction snapshot:**
@@ -107,6 +93,8 @@ Identify all source files in the source directory that contain public exports.
   "confidence_tier": "{tier}",
   "source_root": "{source_path}",
   "files_scanned": {count},
+  "bounded_scan": true|false,
+  "bounded_scan_source": "provenance-map|source-tree-fallback",
   "exports": [
     {
       "name": "{export_name}",
@@ -167,6 +155,7 @@ CCC failures: skip rename detection silently, proceed with standard structural d
 
 | Metric | Value |
 |--------|-------|
+| Scan mode | {bounded (provenance-map) / degraded (source-tree)} |
 | Files scanned | {count} |
 | Exports found | {total_exports} |
 | Functions | {function_count} |
@@ -199,27 +188,3 @@ Display: "**Proceeding to structural diff...**"
 
 ONLY WHEN the extraction snapshot is complete with all source files processed will you then load and read fully `{nextStepFile}` to execute and begin structural comparison.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- All source files scanned (none skipped)
-- All public exports extracted with file:line references
-- Confidence tier labels applied to every extraction
-- Tier-appropriate tools used (AST for Forge+, text for Quick)
-- Deep tier temporal context added if applicable
-- Extraction snapshot complete and validated
-- Frontmatter stepsCompleted updated
-
-### ❌ SYSTEM FAILURE:
-
-- Skipping source files or being lazy with extraction
-- Not recording file:line references for each export
-- Performing comparison in this step (comparison is Step 03)
-- Missing confidence tier labels
-- Hardcoded paths instead of frontmatter variables
-- Not using subprocess Pattern 2 when available
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/audit-skill → skf-audit-skill}/steps-c/step-03-structural-diff.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-03-structural-diff'
-description: 'Compare original provenance map extractions against current scan to detect structural drift'
-
 nextStepFile: './step-04-semantic-diff.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
@@ -12,43 +9,11 @@ outputFile: '{forge_version}/drift-report-{timestamp}.md'
 
 Compare the original provenance map extractions from create-skill against the current re-index snapshot from Step 02 to detect structural drift. Identify added, removed, and changed exports with file:line citations and confidence tier labels.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a skill auditor performing structural comparison
-- ✅ Every drift finding must have a file:line citation from either the provenance map or current scan
-- ✅ Zero hallucination — only report drift that is structurally verifiable
-
-### Step-Specific Rules:
+## Rules
 
-- 🎯 Focus only on structural comparison — added/removed/changed exports
-- 🚫 FORBIDDEN to classify severity — that happens in Step 05
-- 🚫 FORBIDDEN to suggest remediation — that happens in Step 06
-- 💬 Use subprocess Pattern 4 (parallel): In Claude Code, use multiple parallel Agent tool calls or `run_in_background: true`. In Cursor, use parallel requests (IDE-dependent). In CLI, use `xargs -P` or background processes. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
-- ⚙️ If subprocess unavailable, compare categories sequentially in main thread
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Compare provenance map exports against current extraction snapshot
-- 💾 Append ## Structural Drift section to {outputFile}
-- 📖 Update {outputFile} frontmatter stepsCompleted when complete
-- 🚫 Only structural findings — no semantic or severity analysis
-
-## CONTEXT BOUNDARIES:
-
-- Available: Provenance map (from Step 01), current extraction snapshot (from Step 02), forge tier
-- Focus: Structural export-level comparison only
-- Limits: Do not classify severity, do not analyze semantics, do not suggest fixes
-- Dependencies: Steps 01 and 02 must be complete
+- Focus only on structural comparison — added/removed/changed exports
+- Do not classify severity (Step 05) or suggest remediation (Step 06)
+- Use subprocess Pattern 4 (parallel) when available; if unavailable, compare sequentially
 
 ## MANDATORY SEQUENCE
 
@@ -122,6 +87,23 @@ For each entry in `file_entries`:
 
 Append results to the Structural Drift section as "### Script/Asset Drift ({count})".
 
+### Stack-Specific Structural Diff
+
+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
+- Report per-library diff results
+
+**For code-mode stacks:** Re-extract from each source repo and compare per-library entries.
+
+**For compose-mode stacks:** Compare current constituent skill exports against the entries recorded at compose time. Use the `source_library` field to match entries to constituents.
+
+**For v1 legacy provenance:** Report library-level summary only (export counts, extraction methods). Note that per-export drift detection requires re-composition with v2 provenance.
+
+**Integration drift:** For each integration in `integrations[]`, verify that co-import files still contain the detected patterns (code-mode) or that constituent skills still document the integration (compose-mode).
+
 ### 5. Compile Structural Drift Section
 
 Append to {outputFile}:
@@ -182,27 +164,3 @@ Display: "**Structural diff complete. {total} drift items found. Proceeding to s
 
 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.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- All three categories compared: added, removed, changed
-- Every finding has file:line citation
-- Confidence tier labels on all findings
-- Moved exports distinguished from removed+added
-- Structured table format in drift report
-- Summary counts accurate
-- Frontmatter stepsCompleted updated
-
-### ❌ SYSTEM FAILURE:
-
-- Missing any comparison category (added/removed/changed)
-- Findings without file:line citations
-- Missing confidence tier labels
-- Classifying severity in this step (severity is Step 05)
-- Not detecting moved exports (false removed + false added)
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/audit-skill → skf-audit-skill}/steps-c/step-04-semantic-diff.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-04-semantic-diff'
-description: 'Compare QMD knowledge context for meaning-level changes (Deep tier only, skip at Quick/Forge/Forge+)'
-
 nextStepFile: './step-05-severity-classify.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
@@ -12,44 +9,12 @@ outputFile: '{forge_version}/drift-report-{timestamp}.md'
 
 Compare QMD knowledge context between the original skill creation and current state to detect meaning-level changes that structural diff cannot catch. This step executes ONLY at Deep tier — at Quick, Forge, and Forge+ tiers, it appends a skip notice and auto-proceeds.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a skill auditor performing semantic analysis
-- ✅ Semantic findings have T2 confidence — evidence-backed but not structurally absolute
-- ✅ Distinguish clearly between structural facts (T1) and semantic observations (T2)
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on semantic/meaning-level changes via QMD context
-- 🚫 FORBIDDEN to classify severity — that happens in Step 05
-- 🚫 FORBIDDEN to repeat structural findings from Step 03
-- 💬 Use subprocess Pattern 3 (data operations — main thread Read + process in Claude Code, script in CLI) when available for QMD queries. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
-- ⚙️ If subprocess unavailable, query QMD in main thread
-- 🔀 CONDITIONAL: Skip entire analysis at Quick/Forge/Forge+ tier — append skip notice only
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Check forge tier FIRST — skip if not Deep
-- 💾 Append ## Semantic Drift section (or skip notice) to {outputFile}
-- 📖 Update {outputFile} frontmatter stepsCompleted when complete
-- 🚫 Only semantic findings — no structural or severity analysis
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Forge tier, structural drift findings (from Step 03), QMD access (Deep tier only)
-- Focus: Meaning-level changes that complement structural diff
-- Limits: Do not re-analyze structural changes, do not classify severity
-- Dependencies: Steps 01-03 must be complete; QMD collection must exist for Deep tier
+- CONDITIONAL: Skip entire analysis at Quick/Forge/Forge+ tier — append 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
 
 ## MANDATORY SEQUENCE
 
@@ -66,7 +31,7 @@ Append to {outputFile}:
 
 **Status:** Skipped — Semantic diff requires Deep tier (current tier: {tier})
 
-Semantic analysis compares QMD knowledge context for meaning-level changes that structural diff cannot detect. To enable semantic diff, run setup-forge with QMD available to unlock Deep tier.
+Semantic analysis compares QMD knowledge context for meaning-level changes that structural diff cannot detect. To enable semantic diff, run setup with QMD available to unlock Deep tier.
 ```
 
 Update frontmatter: append `'step-04-semantic-diff'` to `stepsCompleted`
@@ -173,27 +138,3 @@ Display: "**Semantic diff complete. {total} semantic drift items found. Proceedi
 
 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.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Forge tier checked FIRST — skip gracefully at Quick/Forge/Forge+
-- Deep tier: QMD knowledge context queried and compared
-- All semantic findings have T2 confidence labels
-- Findings clearly distinguished from structural drift (T1)
-- Skip notice includes explanation of what semantic diff provides
-- Structured table format in drift report
-- Frontmatter stepsCompleted updated
-
-### ❌ SYSTEM FAILURE:
-
-- Not checking tier before attempting QMD analysis
-- Repeating structural findings from Step 03
-- Missing confidence tier labels on findings
-- Classifying severity in this step (severity is Step 05)
-- Failing to skip gracefully at non-Deep tiers
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/audit-skill → skf-audit-skill}/steps-c/step-05-severity-classify.md

@@ -1,10 +1,7 @@
 ---
-name: 'step-05-severity-classify'
-description: 'Grade every drift finding by severity using classification rules'
-
 nextStepFile: './step-06-report.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
-severityRulesFile: '../data/severity-rules.md'
+severityRulesFile: 'references/severity-rules.md'
 ---
 
 # Step 5: Severity Classification
@@ -13,43 +10,11 @@ severityRulesFile: '../data/severity-rules.md'
 
 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.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a skill auditor performing severity assessment
-- ✅ Classification must be deterministic — same finding always gets same severity
-- ✅ Apply rules strictly — do not invent new severity categories or soften classifications
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on classifying severity of existing findings
-- 🚫 FORBIDDEN to discover new drift items — only classify what Steps 03-04 found
-- 🚫 FORBIDDEN to suggest remediation — that happens in Step 06
-- 💬 Use subprocess Pattern 3 (data operations — main thread Read + process in Claude Code, script in CLI) to load severity rules and classify. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
-- ⚙️ If subprocess unavailable, load rules and classify in main thread
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Load {severityRulesFile} and apply to every finding
-- 💾 Append ## Severity Classification section to {outputFile}
-- 📖 Update {outputFile} frontmatter stepsCompleted when complete
-- 🚫 Only classification — no new findings, no remediation
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Structural drift findings (Step 03), semantic drift findings (Step 04 if Deep), severity rules
-- Focus: Applying deterministic severity classification to every finding
-- Limits: Do not discover new drift, do not suggest fixes
-- Dependencies: Steps 03 (and optionally 04) must be complete
+- 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
 
 ## MANDATORY SEQUENCE
 
@@ -185,26 +150,3 @@ Display: "**Severity classification complete. Overall drift score: {score}. Proc
 
 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.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Severity rules loaded from {severityRulesFile}
-- Every finding from Steps 03-04 classified (none missed)
-- Classification is deterministic — follows rules strictly
-- Overall drift score calculated correctly
-- Structured tables with severity, source type, and confidence
-- Frontmatter drift_score and stepsCompleted updated
-
-### ❌ SYSTEM FAILURE:
-
-- Inventing new severity categories beyond CRITICAL/HIGH/MEDIUM/LOW
-- Missing any finding from classification (incomplete coverage)
-- Softening classifications that should be CRITICAL
-- Discovering new drift items (classification only, not discovery)
-- Suggesting remediation (that is Step 06)
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/audit-skill → skf-audit-skill}/steps-c/step-06-report.md

@@ -1,8 +1,6 @@
 ---
-name: 'step-06-report'
-description: 'Finalize drift report with audit summary, remediation suggestions, and provenance metadata'
-
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
+nextStepFile: './step-07-health-check.md'
 ---
 
 # Step 6: Generate Report
@@ -11,41 +9,12 @@ outputFile: '{forge_version}/drift-report-{timestamp}.md'
 
 Finalize the drift report by completing the Audit Summary with calculated metrics, generating actionable remediation suggestions for each drift finding, and adding provenance metadata. Present the final report to the user with a next-workflow recommendation.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a skill auditor delivering the final audit report
-- ✅ Remediation suggestions must be specific and actionable
-- ✅ Every suggestion must reference the specific drift finding it addresses
-
-### Step-Specific Rules:
-
-- 🎯 Focus on completing the report — summary, remediation, provenance
-- 🚫 FORBIDDEN to discover new drift items or reclassify severity
-- 💬 Remediation suggestions must be practical: what to change, where, and why
-- 📋 This is the FINAL step — no nextStepFile
+## Rules
 
-## EXECUTION PROTOCOLS:
-
-- 🎯 Complete all remaining sections in {outputFile}
-- 💾 Update {outputFile} frontmatter to mark workflow complete
-- 📖 Present final summary to user
-- 🚫 Do not re-analyze — only synthesize and present
-
-## CONTEXT BOUNDARIES:
-
-- Available: Complete drift report with structural diff, semantic diff, severity classification
-- Focus: Synthesis, remediation guidance, and presentation
-- Limits: Do not add new findings or reclassify — only complete the report
-- Dependencies: Steps 01-05 must be complete
+- Focus on completing the report — summary, remediation, provenance
+- Do not discover new drift items or reclassify severity
+- Remediation suggestions must be practical: what to change, where, and why
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -189,29 +158,11 @@ Update {outputFile} frontmatter:
 
 **Audit workflow complete.**"
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
+### Result Contract
 
-- Audit Summary completed with accurate metrics
-- Remediation suggestion for every CRITICAL and HIGH finding
-- Each remediation is specific: what to change, where, and why
-- Provenance section documents complete audit trail
-- Overall drift score correctly reflects findings
-- Frontmatter updated with completion status and nextWorkflow
-- Final summary presented clearly to user
-- Report saved to correct output path
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_version}/audit-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the drift report path in `outputs`; include `drift_count` and `severity` (CLEAN/MINOR/SIGNIFICANT/CRITICAL) in `summary`.
 
-### ❌ SYSTEM FAILURE:
+### 6. Chain to Health Check
 
-- Missing remediation for any CRITICAL or HIGH finding
-- Vague remediation suggestions (e.g., "update the skill" without specifics)
-- Discovering new findings in this step
-- Reclassifying severity
-- Not presenting final summary to user
-- Missing provenance section
-- Hardcoded paths instead of frontmatter variables
+ONLY WHEN the report has been written, presented, and the result contract saved will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the user-facing summary reads as final.
 
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/skf-audit-skill/steps-c/step-07-health-check.md

@@ -0,0 +1,22 @@
+---
+# `shared/health-check.md` resolves relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+# Step 7: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of audit-skill — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+Load `{nextStepFile}`, read it fully, then execute it.

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

@@ -0,0 +1,53 @@
+---
+name: skf-brief-skill
+description: Design a skill scope through guided discovery. Use when the user requests to "create a skill brief" or "brief a skill."
+---
+
+# Brief Skill
+
+## Overview
+
+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 becomes the input contract for create-skill, which performs the actual compilation.
+
+## Role
+
+You are a skill scoping architect collaborating with a developer who wants to create an agent skill. You bring expertise in source code analysis, API surface identification, and skill boundary design, while the user brings their domain knowledge and specific use case. Work together as equals.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Gather Intent | steps-c/step-01-gather-intent.md | No (interactive) |
+| 2 | Analyze Target | steps-c/step-02-analyze-target.md | Yes |
+| 3 | Scope Definition | steps-c/step-03-scope-definition.md | No (interactive) |
+| 4 | Confirm Brief | steps-c/step-04-confirm-brief.md | No (confirm) |
+| 5 | Write Brief | steps-c/step-05-write-brief.md | Yes |
+| 6 | Workflow Health Check | steps-c/step-06-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | target_repo [required], skill_name [required], scope_hint [optional], language_hint [optional] |
+| **Gates** | step-01: Input Gate [use args] | step-03: Confirm Gate [C] | step-04: Confirm Gate [C] |
+| **Outputs** | skill-brief.yaml |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `forge_data_folder`, `sidecar_path`
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-gather-intent.md` to begin the workflow.

package/src/{workflows/brief-skill/data → skf-brief-skill/assets}/scope-templates.md

@@ -22,6 +22,12 @@ Present these options to the user for selection:
 - Auto-exclude demo/example/story files (with user confirmation)
 - Variant consolidation across design systems
 
+**[R] Reference App** — Whole-app pattern-reference skill. Use when the source is a working example app and the skill's value is **wiring patterns** (lifecycle, IPC, build-config, distribution) rather than a public library API.
+- Pattern surface as primary API slot (not individual exports)
+- Adoption Steps as primary workflow format (not API-call chains)
+- Tier 2 organized as `references/pattern-*.md` groupings (not per-function)
+- Export-count stats are pattern-surface proxies, not library exports
+
 ## Boundary Definitions by Scope Type
 
 ### Full Library Boundaries
@@ -65,6 +71,23 @@ Prompt: "Which of these would you like to include? (Enter numbers, or 'all'):"
 Exclusions will include all internal implementation files, tests, and utilities.
 Prompt: "Any additional items you'd like to include or exclude?"
 
+### Reference App Boundaries
+
+**Phase 1 — Pattern surface intent:**
+
+Ask: "What is the authored pattern surface for this skill? List the files (or directories) the user must touch to adopt the pattern — entry points, config files, lifecycle hooks, build scripts."
+
+- Record the user's list as `scope.tier_a_include` when narrower than a broad `scope.include`. Reference-app briefs benefit strongly from `tier_a_include` because the denominator is small and precise.
+- Prompt follow-up: "Any files outside that list that should still be in scope for completeness (tests, fixtures, supporting configs)?"
+
+**Phase 2 — Scope.include and exclusions:**
+
+Set `scope.include` to the pattern-surface file list (or broader union when the author flagged supporting files). Default exclusions mirror the Full Library defaults (tests, build artifacts, docs source). Record `scope.notes` with a one-sentence description of the pattern (e.g., "Embedded Python sidecar pattern for Electron apps — lifecycle orchestration, RPC proxy, build-copy wiring").
+
+**Phase 3 — Confirmation:**
+
+Summary showing: pattern surface count, `tier_a_include` vs `include` distinction, notes. Prompt: "Does this reference-app scope look right? Adjust before continuing."
+
 ### Docs-Only Boundaries
 
 **No source code access.** Scope is defined by the `doc_urls` collected during intent gathering.