bmad-module-skill-forge 1.4.0 → 1.5.0

package/src/skf-test-skill/templates/test-report-template.md

@@ -20,39 +20,39 @@ nextWorkflow: ''
 # Test Report: {{skillName}}
 
 <!--
-Section order is LOAD-BEARING: step-05 §5 enforces it, step-06 §5 verifies
+Section order is LOAD-BEARING: step 5 §5 enforces it, step 6 §5 verifies
 stepsCompleted against the canonical chain. Do not reorder or delete anchors.
 
 Anchor / Step mapping:
-  Test Summary       → step-02-detect-mode
-  Coverage Analysis  → step-03-coverage-check
-  Coherence Analysis → step-04-coherence-check
-  External Validation→ step-04b-external-validators
-  Completeness Score → step-05-score
-  Gap Report         → step-06-report (includes Discovery Quality subsection)
+  Test Summary       → detect-mode
+  Coverage Analysis  → coverage-check
+  Coherence Analysis → coherence-check
+  External Validation→ external-validators
+  Completeness Score → score
+  Gap Report         → report (includes Discovery Quality subsection)
 -->
 
 ## Test Summary
 
-<!-- Populated by step-02-detect-mode §3 -->
+<!-- Populated by detect-mode §3 -->
 
 ## Coverage Analysis
 
-<!-- Populated by step-03-coverage-check §5 -->
+<!-- Populated by coverage-check §5 -->
 
 ## Coherence Analysis
 
-<!-- Populated by step-04-coherence-check §6 (naive or contextual variant) -->
+<!-- Populated by coherence-check §6 (naive or contextual variant) -->
 
 ## External Validation
 
-<!-- Populated by step-04b-external-validators §5 -->
+<!-- Populated by external-validators §5 -->
 
 ## Completeness Score
 
-<!-- Populated by step-05-score §6 -->
+<!-- Populated by score §6 -->
 
 ## Gap Report
 
-<!-- Populated by step-06-report §3-§4b (includes Discovery Quality subsection) -->
+<!-- Populated by report §3-§4b (includes Discovery Quality subsection) -->
 

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

@@ -9,6 +9,15 @@ description: Smart regeneration preserving [MANUAL] sections after source change
 
 Surgically updates existing skills when source code changes, preserving all [MANUAL] developer content while re-extracting only affected exports with full provenance tracking. Only changed exports are re-extracted — unchanged content is never touched. Every regenerated instruction must trace to code with file:line citations. Stack skills (`skill_type: "stack"` in metadata.json) are not supported by surgical update — use `skf-create-stack-skill` to re-compose from updated constituents. If a stack skill is provided, this workflow exits with a redirect message.
 
+## 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.
+- **Cross-skill data coupling:** stages in this workflow load four shared assets from `skf-create-skill` to keep extraction semantics aligned between create and update — `re-extract.md` pulls `extraction-patterns.md`, `extraction-patterns-tracing.md`, and `tier-degradation-rules.md` from `skf-create-skill/references/`; `remote-source-resolution.md` references `source-resolution-protocols.md`; `write.md` reads `skill-sections.md` from `skf-create-skill/assets/`. Update-skill assumes these files are present at install time and that their semantics are stable across the two skills' versions.
+
 ## Role
 
 You are a precision code analyst operating in Ferris Surgeon mode. This is a surgical operation, not an exploratory session. You bring AST-backed structural analysis and provenance-driven change detection expertise, while the source code provides the ground truth.
@@ -19,8 +28,6 @@ These rules apply to every step in this workflow:
 
 - Never hallucinate — every statement must have AST provenance
 - [MANUAL] sections survive regeneration with zero content loss
-- 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
@@ -29,23 +36,25 @@ These rules apply to every step in this workflow:
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Initialize & Load | steps-c/step-01-init.md | No (confirm) |
-| 2 | Detect Changes | steps-c/step-02-detect-changes.md | Yes |
-| 3 | Re-Extract | steps-c/step-03-re-extract.md | Yes |
-| 4 | Merge | steps-c/step-04-merge.md | Yes |
-| 5 | Validate | steps-c/step-05-validate.md | Yes |
-| 6 | Write | steps-c/step-06-write.md | Yes |
-| 7 | Report | steps-c/step-07-report.md | Yes |
-| 8 | Workflow Health Check | steps-c/step-08-health-check.md | Yes |
+| 1 | Initialize & Load | references/init.md | No (confirm) |
+| 2 | Detect Changes | references/detect-changes.md | Yes |
+| 3 | Re-Extract | references/re-extract.md | Yes |
+| 4 | Merge | references/merge.md | Yes |
+| 5 | Validate | references/validate.md | Yes |
+| 6 | Write | references/write.md | Yes |
+| 7 | Report | references/report.md | Yes |
+| 8 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | skill_name [required] |
-| **Gates** | step-01: Confirm Gate [C] | step-04: Confirm Gate [C if clean merge, HALT if conflicts] |
-| **Outputs** | Updated SKILL.md, updated provenance-map.json, evidence-report.md |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--from-test-report` (gap-driven mode); `--allow-workspace-drift` (gap-driven only — bypass §0.a pinning guard); `--detect-only` (run detect-changes only, exit before re-extract; envelope `status="detect-only"`); `--dry-run` (run detect-changes + re-extract, exit before merge/write; envelope `status="dry-run"` describes what would change). If both `--detect-only` and `--dry-run` are passed, `--detect-only` wins. |
+| **Gates** | step 1: Confirm Gate [C] | step 4: Confirm Gate [C if clean merge, HALT if conflicts] |
+| **Outputs** | Updated SKILL.md, updated provenance-map.json, evidence-report.md (none when `--detect-only` or `--dry-run` is set — those modes are read-only inspection paths) |
+| **Concurrency** | Two simultaneous real-update runs against the same skill would corrupt provenance. init.md §1b acquires a PID-file lock at `{forge_data_folder}/{skill_name}/.skf-update.lock` before any artifact read; live-PID collisions halt with `status: "halted-for-concurrent-run"`. Stale locks (dead PID) are cleared silently with a warning. The lock is released by the terminal health-check step (step 8) and by every documented halt path. Read-only modes (`--detect-only`, `--dry-run`) skip the lock entirely — they're safe alongside a concurrent real update. |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Each auto-resolved gate appends a `{gate, default_action, taken_action, reason, evidence?}` entry to `headless_decisions[]`, surfaced in step 7's `SKF_UPDATE_RESULT_JSON` envelope so non-interactive runs can be audited post-hoc. Pipeline branches on the envelope's top-level `status` field (`success`, `no-changes`, `detect-only`, `dry-run`, or one of the documented `halted-for-*` codes). The first four are successful exits — pipelines treating non-success as failure must include them in the success set. Schema: `src/shared/scripts/schemas/skf-update-result-envelope.v1.json`. |
 
 ## On Activation
 
@@ -55,4 +64,4 @@ 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. Load, read the full file, and then execute `references/init.md` to begin the workflow.

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

@@ -0,0 +1,44 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-update-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 skill update 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
+# (drift policies, manual-section preservation rules, compliance
+# guardrails). Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Updates must preserve [MANUAL] sections verbatim."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/update-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional gate thresholds ---
+#
+# Override the default thresholds used by detect-changes and merge. Empty
+# string or commented = use the bundled default (50% deletion ratio,
+# 80% rename similarity).
+
+deletion_ratio_threshold = ""
+rename_similarity_threshold = ""

package/src/skf-update-skill/{steps-c/step-02-detect-changes.md → references/detect-changes.md}

@@ -1,8 +1,34 @@
 ---
-nextStepFile: './step-03-re-extract.md'
-noChangeReportFile: './step-07-report.md'
+nextStepFile: 're-extract.md'
+noChangeReportFile: 'report.md'
+# Resolve `{hashContentHelper}` to the first existing path; HALT if neither
+# candidate exists — §1b and §Category D rely on the helper for deterministic
+# SHA-256 hashing (file-read + size + line-count) and provenance comparison
+# (UNCHANGED / MODIFIED_FILE / DELETED_FILE classification). Falling back to
+# prose-driven hashing would lose hash stability across runs.
+hashContentProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
+  - '{project-root}/src/shared/scripts/skf-hash-content.py'
+# Resolve `{buildChangeManifestHelper}` to the first existing path; HALT if
+# neither candidate exists. §3 uses `build` to aggregate Category A/B/C/D
+# results into the unified manifest; §2.2 uses `deletion-ratio` to compute
+# the major-version trigger. Falling back to prose-driven count rollups
+# would let the LLM drift on manifest shape across runs.
+buildChangeManifestProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-build-change-manifest.py'
+  - '{project-root}/src/shared/scripts/skf-build-change-manifest.py'
+# Resolve `{provenanceGapDispatchHelper}` to the first existing path; HALT
+# if neither exists. §1c uses it to discover the latest drift report, parse
+# Out-of-Scope candidates, and classify them against brief.scope.amendments[]
+# in one call. Falling back to prose-driven markdown parsing would let
+# report-format drift produce silent skips of out-of-scope candidates.
+provenanceGapDispatchProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-provenance-gap-dispatch.py'
+  - '{project-root}/src/shared/scripts/skf-provenance-gap-dispatch.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Detect Changes
 
 ## STEP GOAL:
@@ -16,11 +42,9 @@ Compare current source code state against the provenance map to produce a comple
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 0. Check for Test Report Input (Gap-Driven Mode)
 
-**If `update_mode == "gap-driven"` (set in step-01 via `--from-test-report`):**
+**If `update_mode == "gap-driven"` (set in step 1 via `--from-test-report`):**
 
 Load the test report at `{test_report_path}` and extract findings:
 
@@ -36,9 +60,9 @@ Load the test report at `{test_report_path}` and extract findings:
 | Medium | Stale documentation | MODIFIED_EXPORT (docs reference removed export) |
 | Low | Missing metadata/examples | metadata update |
 
-4. Build the change manifest from translated gaps — no file-level timestamp comparison needed since source hasn't changed. For each manifest entry, propagate these fields from the test report finding so step-03 can resolve the export against live source:
+4. Build the change manifest from translated gaps — no file-level timestamp comparison needed since source hasn't changed. For each manifest entry, propagate these fields from the test report finding so step 3 can resolve the export against live source:
 
-   - **`severity`** — the Gap Report severity (`Critical`, `High`, `Medium`, `Low`, `Info`). Step-03 §0 and step-06 §3 gate the null-citation fallback on severity: Critical/High gaps must produce AST provenance, Medium/Low/Info gaps may degrade to `unknown`.
+   - **`severity`** — the Gap Report severity (`Critical`, `High`, `Medium`, `Low`, `Info`). Step-03 §0 and step 6 §3 gate the null-citation fallback on severity: Critical/High gaps must produce AST provenance, Medium/Low/Info gaps may degrade to `unknown`.
    - **`source_citation: {file, line}`** — populated only when the finding's `Source:` field is a `file:line` pair (e.g., a Gap Report row that cites `packages/utils/src/builder-utils.ts:33`). Step-03 §0 uses this field to perform a live spot-check against source rather than flagging the export as `unknown`. Omit when the `Source:` field is a region reference (e.g., `@storybook/addon-docs control primitives`) or missing.
    - **`remediation_paths: [path, ...]`** — path-like tokens extracted from the finding's `Remediation:` text: any substring matching a recognized source file extension (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.py`, `.rs`, `.go`, `.java`, `.rb`, `.c`, `.h`, `.cpp`), or a directory/glob fragment under the project's source root. Include every matching path verbatim. Step-03 §0a uses this list as the source set for its Targeted Re-Extraction Branch when `source_citation` is absent and severity is Critical/High. Omit the field when the Remediation text names no paths — the entry then falls through to `unknown` or to §0a's halt, depending on severity.
 5. Set `gap_count` from the total number of translated entries
@@ -100,7 +124,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
    [U] Update  — halt this run and return to skf-brief-skill to refine scope
    ```
 
-5. **Headless mode (`{headless_mode}` is true):** auto-select `[S] Skip` for every candidate — record `action: "skipped"`, `reason: "headless: no user to prompt"`, `workflow: "skf-update-skill"`. A non-interactive update run must never silently add files to scope.
+5. **Headless mode (`{headless_mode}` is true):** auto-select `[S] Skip` for every candidate — record `action: "skipped"`, `reason: "headless: no user to prompt"`, `workflow: "skf-update-skill"`. A non-interactive update run must never silently add files to scope. **Also append one entry per candidate to in-context `headless_decisions[]`** (surfaced via `SKF_UPDATE_RESULT_JSON` by step 7): `{gate: "detect-changes.promoted-doc-prompt", default_action: "S", taken_action: "S", reason: "headless: no user to prompt", evidence: {path: "<candidate.path>"}}`.
 
 6. **Apply decision:**
 
@@ -108,7 +132,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
      1. Append `candidate.path` to `brief.scope.include` as a literal glob.
      2. Append a `brief.scope.amendments[]` entry: `action: "promoted"`, `path: candidate.path`, `reason: {user-provided or auto: "discovered post-creation — matched heuristic {basename}"}`, `heuristic: {basename}`, `date: {today ISO}`, `workflow: "skf-update-skill"`.
      3. **Write the amended brief back to disk immediately** at `{forge_data_folder}/{skill_name}/skill-brief.yaml`. Preserve all other fields.
-     4. **Compute SHA-256 content hash** of `candidate.path` and add an entry to the in-context `promoted_docs_new[]` list: `{path, heuristic, size_bytes, line_count, content_hash}`. This list is consumed by §4 merge Priority 7 to write new `file_entries[]` rows — promoted docs do NOT go through §3 code re-extraction, which would produce ghost entries on non-code files.
+     4. **Hash the candidate** via `uv run {hashContentHelper} hash {candidate.path}` — emits `{content_hash, size_bytes, line_count}` as JSON. Combine with the existing context fields and append to the in-context `promoted_docs_new[]` list: `{path, heuristic, size_bytes, line_count, content_hash}`. This list is consumed by §4 merge Priority 7 to write new `file_entries[]` rows — promoted docs do NOT go through §3 code re-extraction, which would produce ghost entries on non-code files.
      5. Display: `"Promoted {path} — brief amended, scheduled as new file_entries row for file_type doc."`
 
    - **[S] Skip:**
@@ -143,23 +167,51 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
 **Procedure:**
 
-1. **Locate the most recent audit drift report.** Search `{forge_data_folder}/{skill_name}/{baseline_version}/drift-report-*.md`, sorted by timestamp descending. Pick the latest. If none found, **skip §1c entirely** — the post-detection deletion-ratio trigger in §2.2 still catches major restructures even without an audit pass.
+1. **Discover, parse, and reconcile in one call.** The helper handles drift-report discovery (glob, timestamp-DESC sort, latest wins), Out-of-Scope section extraction (both `## Out-of-Scope Observations` and `### Out-of-Scope New Public API` under `## Remediation Suggestions` heading shapes), candidate parsing (bullet and table markdown formats), and amendment reconciliation against `brief.scope.amendments[]`:
 
-2. **Parse the report for an "Out-of-Scope Observations" section.** Look for either a top-level `## Out-of-Scope Observations` heading or a `### Out-of-Scope New Public API` subsection under `## Remediation Suggestions`. Each entry must expose:
+   ```bash
+   uv run {provenanceGapDispatchHelper} dispatch \
+       --skill-name {skill_name} \
+       --baseline-version {baseline_version} \
+       --forge-data-folder {forge_data_folder} \
+       --brief {forge_data_folder}/{skill_name}/skill-brief.yaml
+   ```
 
-   - `path` — literal file path or directory glob (e.g., `python/cocoindex/_internal/api.py` or `python/cocoindex/resources/**`)
-   - `evidence` — short one-liner from the report (export count, rationale)
+   Output envelope:
+
+   ```json
+   {
+     "status": "no-report" | "no-candidates" | "candidates-found",
+     "report_path": "<abs path>" | null,
+     "candidates_total": N,
+     "classified": [
+       {
+         "path": "<glob or file path>",
+         "evidence": "<one-liner>",
+         "status": "already-in-scope" | "pre-decided-skipped"
+                 | "pre-decided-demoted" | "unresolved",
+         "prior_action": "promoted" | "skipped"
+                       | "demoted-include" | "demoted-exclude"
+                       | null
+       }, ...
+     ],
+     "summary": {"pre_decided_count": N, "unresolved_count": N}
+   }
+   ```
 
-   **Note:** This section is an optional audit-skill output. `skf-audit-skill` does not currently discover new files (per `src/skf-audit-skill/steps-c/step-02-re-index.md` — new-file detection is the responsibility of update-skill). The section is a forward-looking integration point: manual additions to the drift report or a future audit-skill enhancement populate it. If absent, no candidates from this trigger — proceed to step 6.
+2. **Dispatch on `status`:**
 
-3. **Reconcile against existing amendments.** For each candidate, consult `brief.scope.amendments[]`:
+   - **`no-report`** — no drift report under `{forge_data_folder}/{skill_name}/{baseline_version}/`. **Skip §1c entirely** — proceed to step 6's summary line (omit). §2.2's post-detection deletion-ratio trigger still catches major restructures.
+   - **`no-candidates`** — report exists but the Out-of-Scope section is absent or empty. Proceed to step 6's summary line with `"no out-of-scope observations in drift report."`
+   - **`candidates-found`** — iterate `classified[]`:
+     - `status: "already-in-scope"` → skip silently (`prior_action: "promoted"`).
+     - `status: "pre-decided-skipped"` → honor silently (`prior_action: "skipped"`).
+     - `status: "pre-decided-demoted"` → record as `pre_decided`; do not re-prompt (`prior_action` ∈ `demoted-include`, `demoted-exclude`).
+     - `status: "unresolved"` → continue to step 4 (user prompt).
 
-   - `action: "promoted"` AND `path` matches → already in scope, skip silently.
-   - `action: "skipped"` AND `path` matches → user previously declined, honor silently.
-   - `action: "demoted-include"` or `action: "demoted-exclude"` AND `path` matches → user previously narrowed scope on this path, do not re-prompt; record as `pre_decided`.
-   - No matching amendment → continue to user prompt.
+   **Note:** the Out-of-Scope section is an optional audit-skill output. `skf-audit-skill` does not currently discover new files (per `src/skf-audit-skill/references/re-index.md` — new-file detection is the responsibility of update-skill). The section is a forward-looking integration point: manual additions or a future audit-skill enhancement populate it.
 
-4. **Prompt for each unresolved candidate.** Present the same menu shape as §1b:
+3. **Prompt for each unresolved candidate.** Present the same menu shape as §1b:
 
    ```
    **Out-of-scope new public API discovered**
@@ -175,9 +227,9 @@ Read the source directory at `{source_root}` and build a current file inventory:
    [U] Update  — halt this run and return to skf-brief-skill to refine scope
    ```
 
-5. **Headless mode (`{headless_mode}` is true):** auto-select `[S] Skip` for every candidate — record `action: "skipped"`, `category: "scope-expansion"`, `reason: "headless: no user to prompt"`, `workflow: "skf-update-skill"`. A non-interactive update run must never silently expand scope.
+4. **Headless mode (`{headless_mode}` is true):** auto-select `[S] Skip` for every candidate — record `action: "skipped"`, `category: "scope-expansion"`, `reason: "headless: no user to prompt"`, `workflow: "skf-update-skill"`. A non-interactive update run must never silently expand scope. **Also append one entry per candidate to in-context `headless_decisions[]`** (surfaced via `SKF_UPDATE_RESULT_JSON` by step 7): `{gate: "detect-changes.scope-expansion", default_action: "S", taken_action: "S", reason: "headless: no user to prompt", evidence: {path: "<candidate.path>"}}`.
 
-6. **Apply decision:**
+5. **Apply decision:**
 
    - **[P] Promote:**
      1. Append `candidate.path` to `brief.scope.include` as a literal glob (preserve any wildcards from the drift report).
@@ -197,7 +249,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
      2. Display: `"Halting update-skill. Re-run skf-brief-skill to refine scope for {skill_name}, then re-run skf-update-skill."`
      3. Exit with status `halted-for-brief-refinement`. Change manifest is not yet built — no partial writes to provenance.
 
-7. **Summary:** After all candidates are resolved (or none were found):
+6. **Summary:** After all candidates are resolved (or none were found):
 
    - `"Scope reconciliation: {N} candidates, {P} promoted, {S} skipped, {A} pre-decided from amendments."`
    - If N = 0 (section absent or empty): `"Scope reconciliation: no out-of-scope observations in drift report."`
@@ -215,7 +267,7 @@ Before launching parallel subprocesses, build a `change_detection_excludes` set
 
 The exclusion set includes:
 
-- Every path in `promoted_docs_new[]` (populated by §1b). These files are tracked as `file_entries[]` via step-04 Priority 7, not through Category A code extraction. Without this exclusion, Category A would classify them as ADDED (because they're in source but not yet in the provenance map) and §3 re-extract would send them to AST extraction, producing ghost entries.
+- Every path in `promoted_docs_new[]` (populated by §1b). These files are tracked as `file_entries[]` via step 4 Priority 7, not through Category A code extraction. Without this exclusion, Category A would classify them as ADDED (because they're in source but not yet in the provenance map) and §3 re-extract would send them to AST extraction, producing ghost entries.
 - Every source path in `file_entries[].source_file` where `file_type == "doc"` in the existing provenance map. These are already-tracked authoritative docs; any drift in them is handled by Category D (script/asset file changes), not Category A.
 
 Record the set size: "**Change-detection excludes:** {count} paths ({promoted_docs_new count} new promotions + {existing doc file_entries count} already tracked)."
@@ -227,7 +279,7 @@ Launch subprocesses in parallel that compare source state against provenance map
 **Category A — File-level changes:**
 - Files in provenance map but missing from source → DELETED
 - Files in source but not in provenance map AND not in `change_detection_excludes` → ADDED
-- Files in `change_detection_excludes`: skip entirely (routed to file_entries via §1b → step-04 Priority 7, never through Category A)
+- Files in `change_detection_excludes`: skip entirely (routed to file_entries via §1b → step 4 Priority 7, never through Category A)
 - Files in both but with different timestamps/sizes → MODIFIED
 - Files with same content at different paths → MOVED
 
@@ -243,12 +295,35 @@ Launch subprocesses in parallel that compare source state against provenance map
 - If content similarity > 80%: classify as RENAMED instead of deleted+added. **Similarity mechanism by tier:** Quick: compare file size ratio (within 20%) and export name overlap (>70% of exports match by name). Forge and above: use ast-grep to compare export signatures between the deleted and added files. Forge+/Deep: use CCC semantic similarity when available
 
 **Category D — Script/asset file changes:**
-- Compare `file_entries` from provenance-map.json against current source files
-- For each file_entry: compute current SHA-256 content hash, compare against stored hash
-- Files with changed hashes → MODIFIED_FILE
-- Files in provenance but missing from source → DELETED_FILE
-- Files in source matching detection patterns (scripts/, bin/, assets/, templates/) but not in provenance → NEW_FILE
-- Files in `scripts/[MANUAL]/` or `assets/[MANUAL]/` → SKIP (user-authored, preserved)
+
+Run the bulk comparison once via:
+
+```bash
+uv run {hashContentHelper} compare <source-root> \
+    --provenance-map <provenance-map-path>
+```
+
+The helper emits:
+
+```json
+{
+  "comparisons": [
+    {"source_file": "...", "classification": "UNCHANGED|MODIFIED_FILE|DELETED_FILE",
+     "stored_hash": "sha256:...", "current_hash": "sha256:..."|null,
+     "current_size_bytes": N|null}, ...
+  ],
+  "stats": {"total": N, "unchanged": U, "modified": M, "deleted": D}
+}
+```
+
+Translate the helper's output into the change manifest:
+- `MODIFIED_FILE` rows → add to manifest as MODIFIED_FILE
+- `DELETED_FILE` rows → add to manifest as DELETED_FILE
+- `UNCHANGED` rows → omit from the manifest (no action needed)
+
+The helper does NOT detect NEW_FILE — its job is provenance comparison only. Detect new files via `skf-detect-scripts-assets.py` from create-skill step 3 §4c against the current source tree, then subtract the paths already present in `provenance.file_entries[].source_file`. Remaining files matching detection patterns (`scripts/`, `bin/`, `assets/`, `templates/`) and NOT under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are NEW_FILE.
+
+Files in `scripts/[MANUAL]/` or `assets/[MANUAL]/` → SKIP (user-authored, preserved).
 
 Aggregate all subprocess results into a unified change manifest.
 
@@ -261,22 +336,29 @@ Aggregate all subprocess results into a unified change manifest.
 
 **Purpose:** §1c catches the major-version case when an audit drift report supplies explicit candidates. §2.2 is the safety net that fires when no audit was run (or audit emitted no out-of-scope section): it inspects the just-built Category A/B results for the deletion-ratio signature of a major-version restructure and gives the user an off-ramp before §3 commits the change manifest.
 
-**Skip this section entirely if:**
-
-- `update_mode == "gap-driven"` (test-report mode), OR
-- `degraded_mode == true` (no provenance baseline to compare against — every export looks "modified", deletion ratio is meaningless), OR
-- Provenance map's tracked export count is zero.
-
-**Trigger:** Compute
+**Trigger computation:** invoke the helper with the same Category A/B/C/D JSON used for §3, plus the provenance map:
 
+```bash
+echo "{category JSON}" | uv run {buildChangeManifestHelper} deletion-ratio \
+    --provenance-map {forge_version}/provenance-map.json
 ```
-deleted_export_count = (sum of exports across Category A DELETED files)
-                     + (DELETED_EXPORT count from Category B)
-total_provenance_exports = provenance_map.entries.length
-deletion_ratio = deleted_export_count / total_provenance_exports
+
+The helper handles the three skip conditions internally — when the input has `update_mode: "gap-driven"`, `degraded_mode: true`, or the provenance has zero entries, it returns `skip_reason` set and `should_trigger: false`. The output envelope:
+
+```json
+{
+  "skip_reason": "gap-driven" | "degraded-mode" | "zero-provenance-exports" | null,
+  "deleted_export_count": N,
+  "total_provenance_exports": N,
+  "deletion_ratio": 0.X,
+  "deleted_file_count": N,
+  "added_in_scope_count": N,
+  "renamed_or_moved_count": N,
+  "should_trigger": <bool>
+}
 ```
 
-If `deletion_ratio >= 0.50`, present the prompt below. Otherwise skip §2.2 silently and continue to §3.
+If `skip_reason` is non-null OR `should_trigger` is false, skip the prompt and continue to §3. If `should_trigger` is true, present the prompt below.
 
 **Prompt:**
 
@@ -296,7 +378,7 @@ The upstream surface appears to have been substantially replaced. The brief's
 [A] Audit    — halt and run skf-audit-skill to map the new surface, then re-run update-skill
 ```
 
-**Headless mode (`{headless_mode}` is true):** auto-select `[C] Continue`, log a WARN-level entry to the evidence report (`scope_reconciliation_post: {trigger: "deletion-ratio", ratio: X, decision: "headless-continue"}`), and surface the warning in step-07's report. A non-interactive run must not silently halt, but the user must be able to see the signal post-hoc.
+**Headless mode (`{headless_mode}` is true):** auto-select `[C] Continue`, log a WARN-level entry to the evidence report (`scope_reconciliation_post: {trigger: "deletion-ratio", ratio: X, decision: "headless-continue"}`), and surface the warning in step 7's report. A non-interactive run must not silently halt, but the user must be able to see the signal post-hoc. **Also append to in-context `headless_decisions[]`** (surfaced via `SKF_UPDATE_RESULT_JSON` by step 7): `{gate: "detect-changes.deletion-ratio", default_action: "C", taken_action: "C", reason: "headless: deletion-ratio threshold exceeded but no user to halt", evidence: {deletion_ratio: <ratio>, deleted_export_count: <N>, total_provenance_exports: <T>}}`.
 
 **Apply decision:**
 
@@ -308,30 +390,51 @@ The upstream surface appears to have been substantially replaced. The brief's
 
 ### 3. Build Change Manifest
 
-Compile the change manifest with structured entries:
+Hand the assembled Category A/B/C/D JSON to the helper:
 
+```bash
+echo "{category JSON}" | uv run {buildChangeManifestHelper} build
 ```
-Change Manifest:
-  files_changed: [count]
-  files_added: [count]
-  files_deleted: [count]
-  files_moved: [count]
-
-  exports_modified: [count]
-  exports_new: [count]
-  exports_deleted: [count]
-  exports_renamed: [count]
-  exports_moved: [count]
-
-  scripts_modified, scripts_added, scripts_deleted: {counts}
-  assets_modified, assets_added, assets_deleted: {counts}
-
-  Per-file detail:
-    {file_path}:
-      status: MODIFIED|ADDED|DELETED|MOVED
-      exports_affected: [{export_name, change_type, old_line, new_line}]
+
+The category JSON shape is:
+
+```json
+{
+  "category_a": {"modified": [...], "added": [...], "deleted": [...]},
+  "category_b": {"modified_exports": [...], "new_exports": [...],
+                 "deleted_exports": [...], "moved_exports": [...]},
+  "category_c": {"renamed_files": [...], "renamed_exports": [...]},
+  "category_d": {"scripts_modified": [...], "scripts_added": [...],
+                 "scripts_deleted": [...], "assets_modified": [...],
+                 "assets_added": [...], "assets_deleted": [...]},
+  "degraded_mode": <bool>,
+  "update_mode": "normal" | "gap-driven"
+}
+```
+
+The helper emits the unified manifest envelope:
+
+```json
+{
+  "no_changes": <bool>,
+  "degraded_mode": <bool>,
+  "counts": {
+    "files_changed": N, "files_added": N, "files_deleted": N, "files_moved": N,
+    "exports_modified": N, "exports_new": N, "exports_deleted": N,
+    "exports_renamed": N, "exports_moved": N,
+    "scripts_modified": N, "scripts_added": N, "scripts_deleted": N,
+    "assets_modified": N, "assets_added": N, "assets_deleted": N
+  },
+  "total_export_changes": N,
+  "per_file": [
+    {"file_path": "...", "status": "MODIFIED|ADDED|DELETED|MOVED",
+     "exports_affected": [{name, change_type, old_line, new_line}, ...]}
+  ]
+}
 ```
 
+`per_file` entries are sorted MODIFIED → ADDED → DELETED → MOVED, then alphabetically within each status group, so downstream stages can rely on stable ordering. MOVED entries include an extra `old_path` field. Stash the envelope as the change manifest in workflow context.
+
 ### 4. Check for No-Change Shortcut
 
 **If zero changes detected across all categories:**
@@ -364,15 +467,20 @@ Display: "**Proceeding to re-extraction...**"
 
 #### Menu Handling Logic:
 
-- After change manifest is built, immediately load, read entire file, then execute {nextStepFile}
-- **EXCEPTION:** If no changes detected (section 4), load {noChangeReportFile} instead
+- **If `detect_only_mode` is true:** display "**Detect-only mode — skipping re-extract/merge/validate/write.** Loading report..." and load `{noChangeReportFile}` (report.md). The report handles the detect-only envelope. Do NOT load `{nextStepFile}`.
+- Else, after change manifest is built, immediately load, read entire file, then execute `{nextStepFile}`.
+- **EXCEPTION:** If no changes detected (section 4), load `{noChangeReportFile}` instead.
 
 #### EXECUTION RULES:
 
 - This is an auto-proceed step with no user choices
-- Proceed directly to next step after change detection completes
+- Proceed directly to next step after change detection completes (or to report when `detect_only_mode` is true)
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN the change manifest is fully built will you load {nextStepFile} to begin re-extraction. If no changes detected, skip to {noChangeReportFile}.
+ONLY WHEN the change manifest is fully built will you load the next file:
+
+- `detect_only_mode == true` → load `{noChangeReportFile}` (report.md). Report emits status `detect-only`.
+- No changes detected → load `{noChangeReportFile}` (report.md). Report emits status `no-changes`.
+- Otherwise → load `{nextStepFile}` (re-extract.md) to begin re-extraction.
 

package/src/skf-update-skill/references/health-check.md

@@ -0,0 +1,32 @@
+---
+# `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'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 8: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of update-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 7
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}` (other than the lock release below)
+
+## MANDATORY SEQUENCE
+
+1. **Release the concurrency lock** acquired by init.md §1b (skip when `detect_only_mode` or `dry_run_mode` is true — those modes never acquired one):
+
+   ```bash
+   rm -f "{forge_data_folder}/{skill_name}/.skf-update.lock"
+   ```
+
+   The lock release MUST run before delegating to the shared health-check, since the health-check is the terminal step — once it returns, the workflow is done and any held lock becomes orphaned for the next run to clean up. Releasing here keeps the lock lifecycle tight against the workflow's actual span.
+
+2. Load `{nextStepFile}`, read it fully, then execute it.