bmad-module-skill-forge 1.4.1 → 1.5.0

package/src/skf-analyze-source/{steps-c/step-02-scan-project.md → references/scan-project.md}

@@ -1,9 +1,12 @@
 ---
-nextStepFile: './step-03-identify-units.md'
+nextStepFile: 'identify-units.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: 'references/unit-detection-heuristics.md'
+scanManifestsScript: '{project-root}/src/shared/scripts/skf-scan-manifests.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Scan Project
 
 ## STEP GOAL:
@@ -14,13 +17,11 @@ To map the complete project structure by scanning directory trees, detecting ser
 
 - Focus only on structural scanning — do not classify units or map exports yet
 - Do not read source file contents beyond manifest files and entry points
-- Use subprocess Pattern 1 for scanning across many files
+- Delegate per-file scanning to subagents in parallel when many files are involved (main-thread fallback is fine)
 - Tier-aware scanning depth: Quick (file structure), Forge (+ manifest parsing), Deep (+ config analysis)
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Context
 
 Read {outputFile} frontmatter to obtain:
@@ -36,9 +37,9 @@ Load {heuristicsFile} for reference on detection signals.
 
 1. Map the top-level directory tree (2-3 levels deep)
 2. Identify workspace configuration files (pnpm-workspace.yaml, lerna.json, Cargo.toml [workspace], go.work, etc.)
-3. Find all package manifests (package.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml, build.gradle, pom.xml)
+3. Enumerate package manifests deterministically — invoke `uv run {scanManifestsScript} scan {path}` and parse the JSON envelope. The script returns `{manifests[], total_unique, monorepo, warnings?}` covering npm/python/rust/go/maven/gradle/ruby/composer/swift; record each `{path, ecosystem}` for the manifests catalog in §4 and capture `monorepo` for the boundary-signal pass in §3
 4. Locate entry point files (index.ts, main.ts, app.ts, main.go, main.rs, __init__.py, etc.)
-5. Detect service configuration (Dockerfile, docker-compose.yml, kubernetes manifests, serverless.yml)
+5. Detect service configuration (Dockerfile, docker-compose.yml, kubernetes manifests, serverless.yml) — keep this step LLM-driven; file glob + presence check is sufficient, no parsing required
 6. Return structured findings — file paths and types only, not contents
 
 **If subprocess unavailable:** Perform directory scanning in main thread using file I/O tools.
@@ -120,7 +121,7 @@ Wait for user feedback. If user identifies gaps, rescan as directed.
 
 Append the complete "## Project Scan" section to {outputFile}:
 
-Replace the placeholder `[Appended by step-02-scan-project]` with the full scan results including:
+Replace the placeholder `[Appended by scan-project]` with the full scan results including:
 - Structure overview
 - Detected boundaries table
 - Manifests catalog
@@ -130,17 +131,18 @@ Replace the placeholder `[Appended by step-02-scan-project]` with the full scan
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: [append 'step-02-scan-project' to existing array]
-lastStep: 'step-02-scan-project'
+stepsCompleted: [append 'scan-project' to existing array]
+lastStep: 'scan-project'
 ```
 
 ### 7. Present MENU OPTIONS
 
-Display: "**Select:** [C] Continue to Unit Identification"
+Display: "**Select:** [C] Continue to Unit Identification | [X] Cancel and exit"
 
 #### Menu Handling Logic:
 
 - IF C: Save scan results to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, and counts/paths reflecting state at cancellation
 - IF Any other: help user, then [Redisplay Menu Options](#7-present-menu-options)
 
 #### EXECUTION RULES:

package/src/skf-analyze-source/references/unit-detection-heuristics.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Unit Detection Heuristics
 
 ## Purpose

package/src/skf-analyze-source/templates/analysis-report-template.md

@@ -18,24 +18,24 @@ nextWorkflow: ''
 
 ## Project Scan
 
-[Appended by step-02-scan-project]
+[Appended by scan-project]
 
 ## Identified Units
 
-[Appended by step-03-identify-units]
+[Appended by identify-units]
 
 ## Export Map
 
-[Appended by step-04-map-and-detect]
+[Appended by map-and-detect]
 
 ## Integration Points
 
-[Appended by step-04-map-and-detect]
+[Appended by map-and-detect]
 
 ## Recommendations
 
-[Appended by step-05-recommend]
+[Appended by recommend]
 
 ## Generation Results
 
-[Appended by step-06-generate-briefs]
+[Appended by generate-briefs]

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

@@ -9,6 +9,14 @@ description: Drift detection between skill and current source code. Use when the
 
 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.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
 ## 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.
@@ -18,11 +26,8 @@ You are a skill auditor operating in Ferris Audit mode. This is a deterministic
 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
 
@@ -30,22 +35,45 @@ These rules apply to every step in this workflow:
 
 | # | 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 |
+| 1 | Initialize & Baseline | references/init.md | No (confirm) |
+| 2 | Re-Index Source | references/re-index.md | Yes |
+| 3 | Structural Diff | references/structural-diff.md | Yes |
+| 4 | Semantic Diff | references/semantic-diff.md | Yes (skip at non-Deep) |
+| 5 | Severity Classification | references/severity-classify.md | Yes |
+| 6 | Report | references/report.md | Yes |
+| 7 | Workflow Health Check | references/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 |
+| **Inputs** | `skill_name` [required], `skill_path` [optional override — full path to skill directory; bypasses manifest/symlink resolution], `tier_override` [optional: Quick / Forge / Forge+ / Deep — overrides detected tier], `degraded` [optional bool — pre-confirm degraded-mode opt-in when no provenance map exists], `upstream_drift_choice` [optional: C / S / X — pre-supplied answer for the upstream-drift gate at init.md §5b], `dirty_worktree_choice` [optional: T / A / F — pre-supplied answer for the dirty-worktree sub-gate at init.md §5b], `force` [optional bool — when paired with `dirty_worktree_choice=F` or used for any future destructive-action gate, signals consent to skip the confirmation] |
+| **Gates** | step 1: Manifest-vs-Symlink Gate [N] · Upstream-Drift Gate [C/S/X] · Dirty-Worktree Sub-Gate [T/A/F] · Degraded-Mode Gate [D/X] · Baseline Confirm Gate [C] |
+| **Outputs** | `drift-report-{timestamp}.md` at `{forge_version}/` with `drift_score` and `nextWorkflow` frontmatter; per-run result contract at `{forge_version}/audit-skill-result-{timestamp}.json` plus `-latest.json` copy; final `SKF_AUDIT_RESULT_JSON` line on stdout when `{headless_mode}` is true |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true; pre-supplied inputs (`upstream_drift_choice`, `dirty_worktree_choice`, `degraded`, `tier_override`) consumed at the gates that would otherwise prompt |
+| **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 7 (terminal health-check)                                                                                     |
+| 2    | input-missing        | step 1 §1 — no `skill_name` supplied in headless mode (interactive prompt cannot resolve)                          |
+| 3    | resolution-failure   | step 1 §1 (skill not found at resolved path: missing `SKILL.md`); step 1 §2 (`forge-tier.yaml` missing — setup-forge not run); step 1 §5 (source directory from provenance map no longer exists / inaccessible) |
+| 4    | write-failure        | step 1 §6 / step 6 §3 (drift report write failed: read-only mount, disk full, permissions denied)                 |
+| 6    | user-cancelled       | step 1 §1 manifest-vs-symlink gate `[X]` · step 1 §4 degraded-mode gate `[X]` · step 1 §5b upstream-drift gate `[X]` · step 1 §5b dirty-worktree sub-gate `[A]` (and `[A]` headless default) |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_AUDIT_RESULT_JSON: {"status":"success|error","skill_name":"…","drift_score":"CLEAN|MINOR|SIGNIFICANT|CRITICAL|null","report_path":"…|null","next_workflow":"update-skill|null","audit_ref":"…|null","exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `drift_score` is `null` when the workflow halted before severity classification ran. `next_workflow` is `"update-skill"` when CRITICAL or HIGH findings exist, otherwise `null`. `halt_reason` is one of: `null` (success), `"input-missing"`, `"skill-not-found"`, `"forge-tier-missing"`, `"source-dir-missing"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
@@ -56,4 +84,27 @@ These rules apply to every step in this workflow:
 
 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.
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the scalars, if the merged value is empty or absent, use the bundled default:
+
+   - `{driftReportTemplatePath}` ← `workflow.drift_report_template_path` if non-empty, else `assets/drift-report-template.md`
+   - `{severityRulesPath}` ← `workflow.severity_rules_path` if non-empty, else `references/severity-rules.md`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — report.md skips the hook invocation entirely)
+
+   Stash all three as workflow-context variables. Stage files reference `{driftReportTemplatePath}` / `{severityRulesPath}` / `{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 (custom drift-report layout, stricter severity thresholds) or wire in post-audit hooks (Slack notifier, ticket-tracker integration) without forking the skill.
+
+4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-audit-skill/assets/drift-report-template.md

@@ -17,6 +17,7 @@ previousWorkflow: 'create-skill'
 
 ## Audit Summary
 
+**Confidence Mode:** {confidence_mode}
 **Skill:** {skill_name}
 **Source:** {source_path}
 **Tier:** {forge_tier}
@@ -35,28 +36,28 @@ previousWorkflow: 'create-skill'
 
 ## Structural Drift
 
-<!-- Appended by step-03-structural-diff -->
+<!-- Appended by structural-diff -->
 
 ---
 
 ## Semantic Drift
 
-<!-- Appended by step-04-semantic-diff (Deep tier only) -->
+<!-- Appended by semantic-diff (Deep tier only) -->
 
 ---
 
 ## Severity Classification
 
-<!-- Appended by step-05-severity-classify -->
+<!-- Appended by severity-classify -->
 
 ---
 
 ## Remediation Suggestions
 
-<!-- Appended by step-06-report -->
+<!-- Appended by report -->
 
 ---
 
 ## Provenance
 
-<!-- Appended by step-06-report -->
+<!-- Appended by report -->

package/src/skf-audit-skill/customize.toml

@@ -0,0 +1,49 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-audit-skill.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (auth, network,
+# compliance) that must precede any audit work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (house style, severity-threshold policies, audit guardrails).
+# Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Critical drift requires CODEOWNERS notification."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/audit-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical asset paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default.
+
+drift_report_template_path = ""
+severity_rules_path = ""
+
+# Optional post-audit hook. When non-empty, invoked with
+# `--result-path=<path>` after the drift report and result JSON are finalized.
+# Failures are logged to workflow_warnings[] but never fail the workflow.
+
+on_complete = ""

package/src/skf-audit-skill/{steps-c/step-07-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 6
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 

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

@@ -1,9 +1,13 @@
 ---
-nextStepFile: './step-02-re-index.md'
+nextStepFile: 're-index.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 templateFile: 'assets/drift-report-template.md'
+loadProvenanceScript: '{project-root}/src/shared/scripts/skf-load-provenance.py'
+compareFileHashesScript: '{project-root}/src/shared/scripts/skf-compare-file-hashes.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Initialize Audit
 
 ## STEP GOAL:
@@ -19,7 +23,7 @@ Load the existing skill artifacts, provenance map, and forge tier configuration
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+**Initialize workflow context defaults.** Before entering §1, set `confidence_mode = "normal"` as the default. §4 may upgrade this to `"degraded — all findings T1-low"` if the operator opts into degraded mode. Downstream steps (report.md, drift-report-template.md) consume this variable directly — no conditional at the usage site.
 
 ### 1. Get Skill Path
 
@@ -53,7 +57,7 @@ Which skill would you like to audit? Please provide the skill name or path."
 
 3. If not in manifest: check for `active` symlink at `{skills_output_folder}/{skill_name}/active` — resolve to `{skill_group}/active/{skill_name}/`
 4. If neither: fall back to flat path `{skills_output_folder}/{skill_name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
-5. Store the resolved path as `{resolved_skill_package}`. Also store `audit_target_version` = the version that was actually selected (manifest, symlink, or flat) for step-06 Provenance to surface. When the gate above fired, also record the rejected version under `manifest_symlink_drift = {manifest: {active_version}, symlink: {symlink_target}, audited: {audit_target_version}, reason: {fresher-provenance|operator-choice|headless-default}}` so reviewers can audit the choice.
+5. Store the resolved path as `{resolved_skill_package}`. Also store `audit_target_version` = the version that was actually selected (manifest, symlink, or flat) for step 6 Provenance to surface. When the gate above fired, also record the rejected version under `manifest_symlink_drift = {manifest: {active_version}, symlink: {symlink_target}, audited: {audit_target_version}, reason: {fresher-provenance|operator-choice|headless-default}}` so reviewers can audit the choice.
 
 **If user provides full path:**
 - Use as provided
@@ -88,29 +92,38 @@ Load the following from the skill directory:
 - `name`, `version`, `generation_date`, `confidence_tier` used during creation
 - `source_root` — Resolved source code path used during extraction
 
-**Detect split-body state:** If a `references/` directory exists and SKILL.md's `## Full` headings are absent or stubs, this is a split-body skill. Flag `split_body: true` in the baseline so downstream steps (especially semantic diff in step-04) know to also read `references/*.md` for complete content comparison.
+**Detect split-body state:** If a `references/` directory exists and SKILL.md's `## Full` headings are absent or stubs, this is a split-body skill. Flag `split_body: true` in the baseline so downstream steps (especially semantic diff in step 4) know to also read `references/*.md` for complete content comparison.
 
 ### 4. Load Provenance Map
 
 Search for provenance map at `{forge_data_folder}/{skill_name}/{active_version}/provenance-map.json` (i.e., `{forge_version}/provenance-map.json`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/provenance-map.json`:
 
 **If found:**
-- Load and extract: export list, file mappings, extraction timestamps, confidence tiers
-- Record provenance map age (days since last extraction)
+- Record provenance map age (days since last extraction) from file mtime
+- Normalize the map's deterministic projections in one subprocess call:
+
+  ```bash
+  uv run {loadProvenanceScript} normalize {provenanceMap}
+  ```
+
+  Parse the emitted JSON and stash these fields in workflow context (downstream steps read them directly — no re-walk):
+  - `{bounded_scan_files}` — sorted POSIX list, union of `entries[].source_file` and `file_entries[].source_file`. Step 2 `re-index.md` consumes this as the bounded scan list.
+  - `{is_stack_skill}`, `{legacy_stack_provenance}` — stack-skill flags (see Stack Skill Detection below for downstream branching).
+  - `{source_root}`, `{baseline_commit}`, `{baseline_ref}` — used by §5 Resolve Source Path and §5b Detect Upstream Drift.
+  - `{reexport_map}` — `{<internal>: <public>}` mapping consumed by `structural-diff.md` §1 to collapse public-API renames before diffing.
+
+  If the script exits non-zero, surface the stderr as a HARD HALT — the map is structurally invalid and downstream steps cannot proceed.
 
 **If missing at both paths:**
 - "No provenance map found for `{skill_name}`. This skill may not have been created by create-skill."
 - "**Degraded mode available:** I can perform text-based comparison without provenance data. Findings will have T1-low confidence."
 - "**[D]egraded mode** — proceed with text-diff only"
 - "**[X]** — abort audit"
-- Wait for user selection. If D, set `degraded_mode: true`. If X, halt workflow.
+- Wait for user selection. If D, set `degraded_mode: true` and `confidence_mode = "degraded — all findings T1-low"`, then skip the normalize call above (no map to normalize). 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
+`{is_stack_skill}` and `{legacy_stack_provenance}` are already resolved by the normalize call in §4 — no additional walk needed. Apply the post-detection logic:
 
 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
@@ -123,10 +136,9 @@ If `{legacy_stack_provenance}` is true: log a note that this stack uses v1 prove
 ### 5. Resolve Source Path
 
 **If provenance map loaded:**
-- Use `source_root` from provenance map as source code path
+- Use `{source_root}` (already extracted by §4 normalize) as source code path
 - Verify source path still exists and is accessible
-- Extract `baseline_commit` = `provenance-map.source_commit` (fall back to `metadata.source_commit` if absent from the provenance map)
-- Extract `baseline_ref` = `metadata.source_ref` (may be a tag, branch, `HEAD`, or `"local"`)
+- `{baseline_commit}` and `{baseline_ref}` are already populated by §4. If `{baseline_commit}` is null in the projection, fall back to `metadata.source_commit`. `{baseline_ref}` may be a tag, branch, `HEAD`, or `"local"`.
 
 **If degraded mode:**
 - Ask user: "Please provide the path to the current source code."
@@ -144,7 +156,7 @@ Upstream drift detection is the primary use case of this workflow. If the local
 - `baseline_commit` is unavailable
 - Degraded mode is active (no provenance map)
 
-When skipping, log the reason, then set the audit-ref context variables to baseline values so step-06 renders a coherent Provenance row: `audit_ref = baseline_ref or "(unknown)"`, `audit_ref_source = "baseline"` (or `"unavailable"` if both `baseline_ref` and `baseline_commit` are unset), `audit_commit = baseline_commit or "(unknown)"`, `latest_tag = null`, `remote_head = null`. Continue to §6.
+When skipping, log the reason, then set the audit-ref context variables to baseline values so step 6 renders a coherent Provenance row: `audit_ref = baseline_ref or "(unknown)"`, `audit_ref_source = "baseline"` (or `"unavailable"` if both `baseline_ref` and `baseline_commit` are unset), `audit_commit = baseline_commit or "(unknown)"`, `latest_tag = null`, `remote_head = null`. Continue to §6.
 
 **Otherwise:**
 
@@ -198,16 +210,16 @@ When skipping, log the reason, then set the audit-ref context variables to basel
      - **[F] Force checkout** — `git checkout --force` discards uncommitted changes irrecoverably. Only choose this after confirming the changes are safe to lose."
 
      **Gate handling:**
-     - **[T]:** Run `git -C {source_root} stash push -m 'skf-audit-skill: pre-checkout {chosen_ref}' --include-untracked`. Capture the stash ref from the command output (e.g. `stash@{0}`) and store as `pre_checkout_stash_ref` in workflow context for step-06 Provenance to surface. Proceed to the checkout. (After audit completes, the operator restores the stash with `git stash pop` — step-06 puts the literal command in the report as a workflow-level convention rather than per-author ad-hoc prose.)
+     - **[T]:** Run `git -C {source_root} stash push -m 'skf-audit-skill: pre-checkout {chosen_ref}' --include-untracked`. Capture the stash ref from the command output (e.g. `stash@{0}`) and store as `pre_checkout_stash_ref` in workflow context for step 6 Provenance to surface. Proceed to the checkout. (After audit completes, the operator restores the stash with `git stash pop` — step 6 puts the literal command in the report as a workflow-level convention rather than per-author ad-hoc prose.)
      - **[A]:** HALT the workflow. Do not write a drift report — the audit was never started.
-     - **[F]:** Run `git -C {source_root} checkout --force {chosen_ref}` instead of the plain checkout. Record `pre_checkout_force_discard: true` in workflow context for step-06 to surface as a loud warning. Skip the stash path.
+     - **[F]:** Run `git -C {source_root} checkout --force {chosen_ref}` instead of the plain checkout. Record `pre_checkout_force_discard: true` in workflow context for step 6 to surface as a loud warning. Skip the stash path.
      - **Other input:** help user, redisplay the sub-gate.
 
      **Headless default** (when `{headless_mode}`): auto-select **[A] Abort** rather than silently mutating the working tree. Emit a loud log line: `"headless: dirty worktree detected at {source_root}; refusing to checkout {chosen_ref} or stash. Re-run interactively to choose [T]/[A]/[F]."` Stashing under automation could lose work if the operator never returns to pop; force-checkout under automation could destroy uncommitted work outright. Abort is the only safe non-interactive default.
 
      If `git status --porcelain` is empty, skip the sub-gate and proceed directly to the checkout.
 
-     Then `git -C {source_root} checkout {chosen_ref}` (prefer `latest_tag` when present, else `remote_head`). Set `audit_ref = {chosen_ref}`, `audit_ref_source = "checkout-latest"`, `audit_commit = git rev-parse HEAD`. Hold the lock through step-02 re-extraction and release only after the extraction snapshot is complete.
+     Then `git -C {source_root} checkout {chosen_ref}` (prefer `latest_tag` when present, else `remote_head`). Set `audit_ref = {chosen_ref}`, `audit_ref_source = "checkout-latest"`, `audit_commit = git rev-parse HEAD`. Hold the lock through step 2 re-extraction and release only after the extraction snapshot is complete.
    - **[S]:** Keep baseline. Set `audit_ref = baseline_ref`, `audit_ref_source = "baseline"`, `audit_commit = baseline_commit`.
    - **[X]:** HALT workflow — do not create drift report.
    - **Other input:** help user, redisplay gate.
@@ -218,10 +230,36 @@ When skipping, log the reason, then set the audit-ref context variables to basel
 
 ### 6. Create Drift Report
 
+**Re-audit detection (before creating a fresh report).** Glob `{forge_version}/drift-report-*.md`. If one or more matches exist, identify the most recent one by file mtime (or by the `{timestamp}` segment in the filename when mtime is unreliable on the filesystem). If that report's age is `< 7 days` and its frontmatter `audit_ref` matches the current `{audit_ref}` (resolved in §5b), surface a soft gate before creating a fresh report:
+
+  "**Recent audit found:** `{prior_report_path}` (created {prior_timestamp}, audit_ref=`{audit_ref}`).
+  
+  Options:
+  - **[F] Fresh audit** (recommended; default in headless) — start a new drift report at `{outputFile}` and ignore the prior run.
+  - **[D] Diff against prior report** — compute findings delta vs the prior report and emit a `## Diff Against Prior Report` subsection in step 6 (report.md).
+  - **[R] Resume the prior report** — load the prior report's frontmatter (`stepsCompleted`, `drift_score`, intermediate findings) and jump to the next un-completed step instead of starting over.
+  
+  **Select:** [F] / [D] / [R]"
+
+**Gate handling:**
+- **[F]:** Default. Proceed with the fresh-report creation below — ignore the prior report.
+- **[D]:** Read the prior report's findings_list (parse the Structural/Semantic/Severity sections, or the appended findings tables) and stash as `prior_findings` in workflow context. Run the new audit normally. In step 6 (report.md), after the Remediation Suggestions section, emit a `## Diff Against Prior Report` subsection summarizing added / removed / changed findings vs `prior_findings`.
+- **[R]:** Load the prior report's frontmatter (`stepsCompleted`, `drift_score`, any intermediate state). Set `{outputFile}` to the prior report path (do NOT create a new one). Determine the next un-completed step from `stepsCompleted` and skip forward to it; downstream steps append to the existing report.
+
+  > **Note (resumability):** the existing template frontmatter captures `stepsCompleted` and `drift_score` but does not currently persist intermediate findings_list between stages. If [R] is selected and stepsCompleted indicates the prior run halted after structural-diff or semantic-diff, the appended sections in the report body (`## Structural Drift`, `## Semantic Drift`, `## Severity Classification`) serve as the implicit intermediate state — re-parse them on resume rather than re-running completed stages. **TODO:** if resumability proves unreliable in practice, extend the report frontmatter to carry an explicit `intermediate_findings` block (out of scope for this PR).
+
+- **Other input:** help user, redisplay the gate.
+
+**Headless default** (when `{headless_mode}`): auto-select **[F]** and emit a loud log line: `"headless: recent audit found at {prior_report_path}; defaulting to fresh audit. Re-run interactively to choose [D]/[R]."`
+
+**Skip this gate** if no prior report matches the `< 7 days + same audit_ref` filter — proceed directly to creating the fresh report.
+
+**Create the fresh report** (when [F] is selected, headless default fires, or no prior report exists):
+
 Create `{outputFile}` from `{templateFile}`:
 
 - Populate frontmatter: skill_name, skill_path, source_path, forge_tier, date, user_name
-- Set `stepsCompleted: ['step-01-init']`
+- Set `stepsCompleted: ['init']`
 - Fill Audit Summary skeleton with loaded baseline data
 
 ### 7. Present Baseline Summary (User Gate)

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

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-03-structural-diff.md'
+nextStepFile: 'structural-diff.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Re-Index Source
 
 ## STEP GOAL:
@@ -17,8 +19,6 @@ Re-scan the source code using the current forge tier tools to build a fresh extr
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Determine Extraction Strategy
 
 Based on forge tier detected in Step 01:
@@ -47,23 +47,23 @@ Based on forge tier detected in Step 01:
 
 ### 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.
+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 1. 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.
 
-**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.
+**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 3 structural diff as "added" — false-positive drift that obscures real structural changes.
 
-**If a provenance map was loaded in step-01** (normal mode):
+**If a provenance map was loaded in step 1** (normal mode):
 
 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.
+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 3 can classify them as DELETED. Handling missing files is step 3's job, not step 2's.
 4. Record `bounded_scan: true` and `bounded_scan_source: "provenance-map"` in context for the evidence report.
 5. Report:
 
    "**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):
+**If degraded mode** (no provenance map was loaded — user confirmed `[D]egraded mode` at step 1 §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/**`.
@@ -82,7 +82,7 @@ Audit-skill detects drift on files that were in scope during create-skill. The a
 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 a file from the bounded scan list is missing on disk:** record `{file, exports: [], status: "missing"}` and continue — step 3 structural diff will classify exports previously at this path as DELETED.
 
 **If subprocess unavailable:** Perform extraction in main thread, processing each file sequentially.
 
@@ -116,7 +116,7 @@ Read the `qmd_collections` registry from `{sidecar_path}/forge-tier.yaml`.
 
 Find the collection entry matching the current skill: look for an entry where `skill_name` matches the current skill being audited AND `type` is `"extraction"`.
 
-Three collection states must be handled distinctly (same branching as step-04 §2 — keep them in sync):
+Three collection states must be handled distinctly (same branching as step 4 §2 — keep them in sync):
 
 **If a matching extraction collection is found and populated** (pre-query probe via `qmd ls {collection_name}` or equivalent returns one or more files):
 Query qmd_bridge against the `{skill_name}-extraction` collection for temporal context on each extracted export:
@@ -175,7 +175,7 @@ CCC failures: skip rename detection silently, proceed with standard structural d
 ### 6. Update Report and Auto-Proceed
 
 Update {outputFile} frontmatter:
-- Append `'step-02-re-index'` to `stepsCompleted`
+- Append `'re-index'` to `stepsCompleted`
 
 ### 7. Present MENU OPTIONS