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

package/src/{workflows/analyze-source → skf-analyze-source}/steps-c/step-04-map-and-detect.md

@@ -1,10 +1,7 @@
 ---
-name: 'step-04-map-and-detect'
-description: 'Map exports per unit and detect cross-unit integration points, flag stack skill candidates'
-
 nextStepFile: './step-05-recommend.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-heuristicsFile: '../data/unit-detection-heuristics.md'
+heuristicsFile: 'references/unit-detection-heuristics.md'
 ---
 
 # Step 4: Map Exports and Detect Integrations
@@ -13,46 +10,12 @@ heuristicsFile: '../data/unit-detection-heuristics.md'
 
 To analyze each qualifying unit's export surface and import graph, detect cross-unit integration points, and flag potential stack skill candidates — completing the analysis foundation needed for recommendations.
 
-## 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
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ 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
-
-### Role Reinforcement:
-
-- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Prescriptive precision — zero-hallucination, only report what is found
-- ✅ File:line citation tracing — cite specific files and line numbers for all claims
-
-### Step-Specific Rules:
-
-- 🎯 Use subprocess optimization (Pattern 2 — per-unit deep analysis): In Claude Code, use Agent tool for each unit sequentially. In CLI, use a per-unit script. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md)
-- 💬 DO NOT BE LAZY — For EACH qualifying unit, perform thorough export surface analysis
-- 🚫 FORBIDDEN to make recommendations in this step (that's step 05)
-- 📋 Tier-aware depth: Quick (file-level exports), Forge (AST export analysis), Deep (AST + semantic relationships)
-
-**AST Degradation Fallback:** If the AST tool (ast-grep) is unavailable at Forge or Deep tier, degrade to Quick-tier behavior for this step and emit a warning: "AST tool unavailable — falling back to file-level export mapping for this step."
-
-## EXECUTION PROTOCOLS:
+## Rules
 
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Append "## Export Map" and "## Integration Points" sections to {outputFile}
-- 📖 Update stepsCompleted in {outputFile} frontmatter
-- 🚫 FORBIDDEN to proceed without presenting findings to user
-
-## CONTEXT BOUNDARIES:
-
-- Available: Identified Units section from report (qualifying units with paths, types, scope types, languages)
-- Focus: Export surfaces, import graphs, and cross-unit integration patterns
-- Limits: Do not recommend or filter units — present all findings objectively
-- Dependencies: step-03-identify-units must have populated the Identified Units section
+- Use subprocess Pattern 2 (per-unit deep analysis) when available
+- For each qualifying unit, perform thorough export surface analysis — do not shortcut
+- Do not make recommendations (Step 05)
+- Tier-aware depth: Quick (file-level), Forge (AST), Deep (AST + semantic)
 
 ## MANDATORY SEQUENCE
 
@@ -82,7 +45,7 @@ DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in
    - **Quick tier:** Count files by type, identify index/barrel files, list directory structure
    - **Forge tier:** Parse export statements, identify public API surface, count exported functions/classes/types
    - **Forge+ tier:** All Forge analysis plus:
-     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search` CLI; see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) — to discover semantically relevant files beyond directory scan
+     - If `tools.ccc` is true: run `ccc_bridge.search("{unit_name} exports public API", top_k=15)` — **Tool resolution:** `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search` CLI; see `knowledge/tool-resolution.md` — to discover semantically relevant files beyond directory scan
      - Merge CCC-discovered files with scoped file list — files from CCC that are within the unit's directory are added to the analysis queue
      - Record CCC signals in per-unit findings: top 3 CCC-ranked file names (or "—" if no ccc results)
    - **Deep tier:** All Forge analysis plus:
@@ -216,27 +179,3 @@ Display: "**Select:** [C] Continue to Recommendations | [D] Discover Additional
 
 ONLY WHEN both the Export Map and Integration Points sections have been appended to {outputFile} with complete findings, and frontmatter stepsCompleted and stack_skill_candidates have been updated, will you load and read fully {nextStepFile} to begin recommendations.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Every qualifying unit's export surface mapped with tier-appropriate depth
-- Import graph built showing cross-unit dependencies
-- Integration points documented with coupling strength
-- Stack skill candidates flagged with evidence
-- Findings presented to user for confirmation
-- Report updated with both Export Map and Integration Points sections
-- stepsCompleted and stack_skill_candidates updated in frontmatter
-
-### ❌ SYSTEM FAILURE:
-
-- Skipping units during export analysis (DO NOT BE LAZY)
-- Not building the cross-reference matrix
-- Missing stack skill candidate detection
-- Making recommendations in this step (that's step 05)
-- Not citing specific files for integration points
-- Not presenting findings for user confirmation
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/analyze-source → skf-analyze-source}/steps-c/step-05-recommend.md

@@ -1,10 +1,7 @@
 ---
-name: 'step-05-recommend'
-description: 'Present unit recommendations with rationale for user confirmation or rejection'
-
 nextStepFile: './step-06-generate-briefs.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-schemaFile: '../data/skill-brief-schema.md'
+schemaFile: 'assets/skill-brief-schema.md'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
@@ -15,44 +12,11 @@ partyModeSkill: '/bmad-party-mode'
 
 To present each qualifying unit as a recommendation with evidence-based rationale, allow the user to confirm, reject, or modify each recommendation, and build the confirmed units list that drives brief generation.
 
-## 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
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ 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
-
-### Role Reinforcement:
-
-- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Prescriptive precision — zero-hallucination, every recommendation backed by evidence
-- ✅ This is the COLLABORATIVE GATE — user must explicitly confirm each unit
-
-### Step-Specific Rules:
-
-- 🎯 This is the primary user decision point — do NOT rush through it
-- 🚫 FORBIDDEN to proceed without explicit confirmation for each unit
-- 💬 Present evidence for each recommendation, invite questions and pushback
-- 📋 User can ask "why?" for any recommendation — explain with specific file citations
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Append "## Recommendations" section to {outputFile}
-- 📖 Update stepsCompleted and confirmed_units in {outputFile} frontmatter
-- 🚫 FORBIDDEN to generate briefs in this step (that's step 06)
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Full report — Project Scan, Identified Units, Export Map, Integration Points
-- Focus: Presenting evidence-based recommendations and capturing user decisions
-- Limits: Do not generate skill-brief.yaml files — only confirm which units to brief
-- Dependencies: steps 02-04 must have populated scan, units, exports, and integrations
+- This is the primary user decision point — do not rush through it
+- Do not proceed without explicit confirmation for each unit
+- Present evidence for each recommendation, invite questions and pushback
 
 ## MANDATORY SEQUENCE
 
@@ -202,6 +166,7 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Disc
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: accept all recommendations and auto-proceed, log: "headless: auto-accept all recommendations"
 - ONLY proceed to next step when user selects 'C'
 - After other menu items execution, return to this menu
 - User can chat or ask questions — always respond and then redisplay menu
@@ -210,28 +175,3 @@ Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [D] Disc
 
 ONLY WHEN all units have explicit user decisions (Y/N/M), the confirmed_units list is finalized in frontmatter, and the user has given final confirmation, will you load and read fully {nextStepFile} to begin brief generation.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Every qualifying unit presented with evidence-based recommendation
-- User explicitly decided on each unit (Y/N/M)
-- Modifications captured and confirmed
-- Stack skill candidates addressed
-- Already-skilled units directed to update-skill
-- Final confirmation obtained before proceeding
-- Report updated with complete Recommendations section
-- confirmed_units populated in frontmatter
-
-### ❌ SYSTEM FAILURE:
-
-- Auto-confirming units without user decision
-- Not presenting evidence/rationale for recommendations
-- Skipping the final confirmation
-- Generating skill-brief.yaml files in this step (that's step 06)
-- Not documenting rejection reasons
-- Proceeding with empty confirmed_units list without user acknowledgment
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/analyze-source → skf-analyze-source}/steps-c/step-06-generate-briefs.md

@@ -1,9 +1,7 @@
 ---
-name: 'step-06-generate-briefs'
-description: 'Generate skill-brief.yaml per confirmed unit, write analysis summary, recommend next workflow'
-
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-schemaFile: '../data/skill-brief-schema.md'
+schemaFile: 'assets/skill-brief-schema.md'
+nextStepFile: './step-07-health-check.md'
 ---
 
 # Step 6: Generate Briefs
@@ -12,44 +10,12 @@ schemaFile: '../data/skill-brief-schema.md'
 
 To generate a valid skill-brief.yaml file for each confirmed unit using the schema, write the files to the forge data folder, append generation results to the analysis report, and recommend the appropriate next workflow for each unit — completing the analyze-source workflow.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ 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
-
-### Role Reinforcement:
-
-- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Prescriptive precision — zero-hallucination, every brief field backed by evidence from prior steps
-- ✅ This is the GENERATION step — produce files that are immediately consumable by downstream workflows
-
-### Step-Specific Rules:
-
-- 🎯 Generate ONLY for units in confirmed_units — no extras, no omissions
-- 🚫 FORBIDDEN to modify recommendations or re-ask for confirmations (that was step 05)
-- 💬 Every generated field must trace back to data collected in steps 02-05
-- 📋 Validate each brief against the schema before writing
+## Rules
 
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Write skill-brief.yaml files to `{forge_data_folder}/{unit-name}/`
-- 💾 Append "## Generation Results" section to {outputFile}
-- 📖 Update stepsCompleted and mark workflow COMPLETE in {outputFile} frontmatter
-- 🚫 FORBIDDEN to skip validation of generated briefs
-
-## CONTEXT BOUNDARIES:
-
-- Available: Full report — all sections from steps 02-05, confirmed_units list, stack_skill_candidates
-- Focus: YAML generation, file writing, downstream workflow recommendation
-- Limits: Do not re-analyze source code — use only data already captured in the report
-- Dependencies: step-05-recommend must have populated confirmed_units with at least one entry
+- Generate only for units in confirmed_units — no extras, no omissions
+- Do not modify recommendations or re-ask for confirmations
+- Every generated field must trace back to data collected in steps 02-05
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -185,9 +151,9 @@ lastStep: 'step-06-generate-briefs'
 nextWorkflow: '{primary recommendation}'
 ```
 
-### 8. Present Completion Summary
+### 8. Present Summary
 
-"**Analyze-Source Workflow Complete**
+"**Analyze-Source Summary**
 
 **Project:** {project_name}
 **Forge Tier:** {forge_tier}
@@ -210,31 +176,13 @@ nextWorkflow: '{primary recommendation}'
 **Stack Skill Candidates:**
 {List candidates with recommendation to run create-stack-skill after individual skills are created}
 
-**This analysis is complete.** To refine any brief, run the recommended next workflow. To re-analyze with different scope, run analyze-source again."
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+To refine any brief, run the recommended next workflow. To re-analyze with different scope, run analyze-source again."
 
-### ✅ SUCCESS:
+### 9. Result Contract
 
-- Every confirmed unit has a skill-brief.yaml generated and validated
-- All required schema fields present and all 8 validation rules passed in each brief
-- Files written to correct paths in forge_data_folder
-- User confirmed before files were written
-- Next workflow recommended per unit
-- Generation Results section appended to report
-- stepsCompleted fully populated and workflow marked complete
-- Completion summary presented with clear next steps
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_data_folder}/analyze-source-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all generated `skill-brief.yaml` paths in `outputs` and brief counts in `summary`.
 
-### ❌ SYSTEM FAILURE:
+### 10. Chain to Health Check
 
-- Generating briefs for units NOT in confirmed_units
-- Writing files without user confirmation
-- Missing required schema fields in generated YAML
-- Not validating briefs against schema before writing
-- Re-analyzing source code instead of using report data
-- Not recommending next workflow per unit
-- Not marking workflow as complete in frontmatter
+ONLY WHEN the briefs have been written (or skipped per user abort), the report updated, the summary 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 summary reads as final.
 
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/skf-analyze-source/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 analyze-source — 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-audit-skill/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: skf-audit-skill
+description: Drift detection between skill and current source code. Use when the user requests to "audit a skill" or "audit skill" for drift.
+---
+
+# Audit Skill
+
+## Overview
+
+Detects drift between an existing skill and its current source code, producing a severity-graded drift report with AST-backed findings and actionable remediation suggestions. Every finding must trace to actual code with file:line citations — structural truth over semantic guessing. Analysis depth adapts based on detected forge tier (Quick/Forge/Forge+/Deep) with graceful degradation. Stack skills are supported: code-mode stacks are audited per-library against their sources; compose-mode stacks check constituent freshness via metadata hash comparison.
+
+## Role
+
+You are a skill auditor operating in Ferris Audit mode. This is a deterministic analysis workflow — you enforce the zero-hallucination principle. You bring AST analysis expertise and drift detection methodology, while the source code provides the ground truth.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Never fabricate findings — all data must trace to source code with file:line citations
+- 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
+- Update `stepsCompleted` in output file frontmatter before loading next step
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- 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 | Initialize & Baseline | steps-c/step-01-init.md | No (confirm) |
+| 2 | Re-Index Source | steps-c/step-02-re-index.md | Yes |
+| 3 | Structural Diff | steps-c/step-03-structural-diff.md | Yes |
+| 4 | Semantic Diff | steps-c/step-04-semantic-diff.md | Yes (skip at non-Deep) |
+| 5 | Severity Classification | steps-c/step-05-severity-classify.md | Yes |
+| 6 | Report | steps-c/step-06-report.md | Yes |
+| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | skill_name [required] |
+| **Gates** | step-01: Confirm Gate [C] |
+| **Outputs** | drift-report-{timestamp}.md with drift_score and nextWorkflow |
+| **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`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+   - Generate and store `timestamp` as `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run.
+
+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-init.md` to begin the workflow.

package/src/{workflows/audit-skill/data → skf-audit-skill/assets}/drift-report-template.md

@@ -23,13 +23,13 @@ previousWorkflow: 'create-skill'
 **Date:** {date}
 **Overall Drift Score:** {drift_score}
 
-| Category | Count |
-|----------|-------|
-| CRITICAL | |
-| HIGH | |
-| MEDIUM | |
-| LOW | |
-| **Total** | |
+| Category  | Count |
+|-----------|-------|
+| CRITICAL  |       |
+| HIGH      |       |
+| MEDIUM    |       |
+| LOW       |       |
+| **Total** |       |
 
 ---
 

package/src/{workflows/audit-skill/data → skf-audit-skill/references}/severity-rules.md

@@ -35,18 +35,18 @@
 
 ## Overall Drift Score
 
-| Score | Criteria |
-|-------|----------|
-| CLEAN | 0 findings at any level |
-| MINOR | LOW findings only, no MEDIUM+ |
+| 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 |
+| CRITICAL    | Any CRITICAL findings present            |
 
 ## Confidence Tier Labels
 
-| Label | Source | Reliability |
-|-------|--------|-------------|
-| T1 | AST extraction (ast-grep) | High — structural truth |
-| T1-low | Text pattern matching (no AST) | Moderate — pattern-based |
-| T2 | QMD semantic context | High — evidence-backed temporal context |
-| T3 | External documentation reference | Variable — secondary source |
+| Label  | Source                           | Reliability                             |
+|--------|----------------------------------|-----------------------------------------|
+| T1     | AST extraction (ast-grep)        | High — structural truth                 |
+| T1-low | Text pattern matching (no AST)   | Moderate — pattern-based                |
+| T2     | QMD semantic context             | High — evidence-backed temporal context |
+| T3     | External documentation reference | Variable — secondary source             |

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

@@ -1,10 +1,7 @@
 ---
-name: 'step-01-init'
-description: 'Load existing skill, provenance map, and detect forge tier for drift analysis'
-
 nextStepFile: './step-02-re-index.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
-templateFile: '../data/drift-report-template.md'
+templateFile: 'assets/drift-report-template.md'
 ---
 
 # Step 1: Initialize Audit
@@ -13,45 +10,12 @@ templateFile: '../data/drift-report-template.md'
 
 Load the existing skill artifacts, provenance map, and forge tier configuration to establish the baseline for drift detection. Create the drift report document and present a baseline summary for user confirmation before proceeding with analysis.
 
-## 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
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ⚙️ 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 finding must trace to actual code with file:line citations
-- ✅ You enforce the zero-hallucination principle: structural truth over semantic guessing
-- ✅ You bring AST analysis expertise, the source code provides ground truth
-
-### Step-Specific Rules:
+## Rules
 
-- 🎯 Focus only on loading skill artifacts and establishing the baseline
-- 🚫 FORBIDDEN to perform any diff or analysis — that happens in later steps
-- 🚫 FORBIDDEN to proceed if skill path is invalid or SKILL.md not found
-- 💬 Present baseline summary clearly so user can confirm before analysis begins
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Discover and load all required input artifacts
-- 💾 Create drift report from {templateFile} with populated frontmatter
-- 📖 Track loaded artifacts in report frontmatter
-- 🚫 Do not proceed to analysis without user confirmation at the gate
-
-## CONTEXT BOUNDARIES:
-
-- Available: User-provided skill path, SKF module config variables
-- Focus: Loading and validating all inputs needed for drift analysis
-- Limits: Do not analyze or compare — only load and baseline
-- Dependencies: setup-forge must be completed (forge-tier.yaml exists), skill must have been created by create-skill (provenance-map.json exists for source-based skills)
-- Docs-only limitation: If `metadata.json` indicates `source_type: "docs-only"` or `confidence_tier: "Quick"` with all T3 citations, inform user: "**This is a docs-only skill.** Drift detection compares against upstream documentation, not source code. Re-run `@Ferris US` to re-fetch documentation URLs and detect content changes." Audit-skill's structural diff is not applicable to docs-only skills — recommend update-skill instead.
+- Focus only on loading skill artifacts and establishing the baseline — do not perform any diff or analysis
+- Do not proceed if skill path is invalid or SKILL.md not found
+- Present baseline summary clearly so user can confirm before analysis begins
+- Docs-only limitation: If `metadata.json` indicates `source_type: "docs-only"` or `confidence_tier: "Quick"` with all T3 citations, inform user: "**This is a docs-only skill.** Drift detection compares against upstream documentation, not source code. Re-run `@Ferris US` to re-fetch documentation URLs and detect content changes." Recommend update-skill instead.
 
 ## MANDATORY SEQUENCE
 
@@ -63,7 +27,7 @@ Load the existing skill artifacts, provenance map, and forge tier configuration
 
 Which skill would you like to audit? Please provide the skill name or path."
 
-**If user provides skill name (not full path) — version-aware path resolution (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)):**
+**If user provides skill name (not full path) — version-aware path resolution (see `knowledge/version-paths.md`):**
 1. Read `{skills_output_folder}/.export-manifest.json` and look up the skill name in `exports` to get `active_version`
 2. If found: resolve to `{skill_package}` = `{skills_output_folder}/{skill_name}/{active_version}/{skill_name}/`
 3. If not in manifest: check for `active` symlink at `{skills_output_folder}/{skill_name}/active` — resolve to `{skill_group}/active/{skill_name}/`
@@ -87,7 +51,7 @@ Load `{sidecar_path}/forge-tier.yaml` to detect available tools.
 
 **If found:**
 - Extract tier level: Quick / Forge / Forge+ / Deep
-- Extract available tools: gh_bridge, ast_bridge, qmd_bridge — see [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for concrete tool resolution per IDE
+- Extract available tools: gh_bridge, ast_bridge, qmd_bridge — see `knowledge/tool-resolution.md` for concrete tool resolution per IDE
 
 **Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
@@ -120,6 +84,21 @@ Search for provenance map at `{forge_data_folder}/{skill_name}/{active_version}/
 - "**[X]** — abort audit"
 - Wait for user selection. If D, set `degraded_mode: true`. If X, halt workflow.
 
+### Stack Skill Detection
+
+After loading provenance-map.json, detect skill type:
+- If `provenance_version` is `"2.0"` and `skill_type` is `"stack"`: set `{is_stack_skill}` = true
+- If provenance-map has top-level `libraries` key (v1 stack format): set `{is_stack_skill}` = true, `{legacy_stack_provenance}` = true
+- Otherwise: `{is_stack_skill}` = false
+
+If `{is_stack_skill}` is true and `constituents` array is present (compose-mode stack):
+- For each constituent, compute the current metadata hash: read `{constituent.skill_path}/active/{constituent.skill_name}/metadata.json` and compute SHA-256
+- Compare against `constituent.metadata_hash`
+- Flag any mismatches as **constituent drift** with severity HIGH
+- Record constituent freshness results for the report
+
+If `{legacy_stack_provenance}` is true: log a note that this stack uses v1 provenance format with reduced audit depth (library-level only, no per-export verification).
+
 ### 5. Resolve Source Path
 
 **If provenance map loaded:**
@@ -173,33 +152,10 @@ Display: "**Select:** [C] Continue to Analysis"
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past baseline confirmation"
 - ONLY proceed to next step when user selects 'C'
 
 ## CRITICAL STEP COMPLETION NOTE
 
 ONLY WHEN C is selected and the drift report has been created with baseline data populated, will you then load and read fully `{nextStepFile}` to execute and begin source re-indexing.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Skill artifacts loaded (SKILL.md, metadata.json)
-- Forge tier detected from sidecar (and override applied if set in preferences.yaml)
-- Provenance map loaded (or degraded mode confirmed)
-- Source path resolved and validated
-- Drift report created from template with populated frontmatter
-- Baseline summary presented to user
-- User confirmed via [C] Continue
-
-### ❌ SYSTEM FAILURE:
-
-- Proceeding without valid skill path
-- Not loading provenance map or offering degraded mode
-- Not detecting forge tier
-- Performing analysis in this step (analysis is Steps 02-05)
-- Proceeding without user confirmation at the gate
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.