bmad-module-skill-forge 1.4.0 → 1.5.0

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

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-02-detect-changes.md'
+nextStepFile: 'detect-changes.md'
 manualSectionRulesFile: 'references/manual-section-rules.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Initialize Update
 
 ## STEP GOAL:
@@ -16,8 +18,6 @@ Load the existing skill and all its provenance data, detect whether this is an i
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Request Skill Path
 
 "**Which skill would you like to update?**
@@ -26,7 +26,9 @@ Provide either:
 - A skill name (resolves via version-aware path resolution — see `knowledge/version-paths.md`)
 - A full path to the skill folder
 - A skill name with `--from-test-report` to use the test report's gap findings instead of source drift detection
-- `--allow-workspace-drift` (gap-driven mode only) to intentionally bypass the step-03 §0.a guard that halts when the local workspace HEAD does not match `metadata.source_commit`. Only use this if you know the spot-checks should read the current workspace instead of the pinned tree — step-06 will NOT automatically re-pin
+- `--allow-workspace-drift` (gap-driven mode only) to intentionally bypass the step 3 §0.a guard that halts when the local workspace HEAD does not match `metadata.source_commit`. Only use this if you know the spot-checks should read the current workspace instead of the pinned tree — step 6 will NOT automatically re-pin
+- `--detect-only` to run detect-changes only and exit; emits the change manifest with no further work and no writes
+- `--dry-run` to run detect-changes + re-extract and exit before merge/write; emits what WOULD change without modifying any artifact
 
 **Skill:** {user provides path or name}"
 
@@ -42,7 +44,53 @@ Resolve the path to an absolute skill folder location.
 **If `--from-test-report` was provided (or user references a test report):**
 Search for the test report at `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}.md` (i.e., `{forge_version}/test-report-{skill_name}.md`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`. If found, set `test_report_path` in context and `update_mode: gap-driven`. If not found at either path, warn and continue with normal source drift mode.
 
-**If `--allow-workspace-drift` was provided:** set `allow_workspace_drift: true` in workflow context. This flag is consumed by step-03 §0.a's pre-flight drift guard (gap-driven mode only) and has no effect in normal source-drift mode.
+**If `--allow-workspace-drift` was provided:** set `allow_workspace_drift: true` in workflow context. This flag is consumed by step 3 §0.a's pre-flight drift guard (gap-driven mode only) and has no effect in normal source-drift mode.
+
+**If `--detect-only` was provided:** set `detect_only_mode: true` in workflow context. After step 2 (detect-changes) completes, jump directly to step 7 (report) — skip re-extract, merge, validate, and write. The report emits the change manifest and a `SKF_UPDATE_RESULT_JSON` envelope with `status: "detect-only"`. **Compatibility:** `--detect-only` short-circuits before §0.a runs, so `--allow-workspace-drift` is silently ignored in detect-only mode (warn the user once at flag-parse time: "`--allow-workspace-drift` has no effect with `--detect-only` — workspace drift guard runs in step 3 §0.a, which is skipped").
+
+**If `--dry-run` was provided:** set `dry_run_mode: true` in workflow context. After step 3 (re-extract) completes, jump directly to step 7 (report) — skip merge, validate, and write. The report emits what would change with `status: "dry-run"` in the envelope. No artifact on disk is modified — `--dry-run` is the "show me what an update would do without committing" mode.
+
+**If BOTH `--detect-only` AND `--dry-run` were provided:** `--detect-only` wins (it's the more restrictive). Warn the user once: "`--detect-only` supersedes `--dry-run`; re-extract is skipped." Set `detect_only_mode: true`, ignore `dry_run_mode`.
+
+### 1b. Concurrency Guard
+
+**Skip this section entirely if `detect_only_mode` OR `dry_run_mode` is true.** Both inspection modes are read-only — they do not modify any artifact and are safe to run alongside a concurrent real update.
+
+Two concurrent `skf-update-skill` runs against the same `{forge_data_folder}/{skill_name}/` can corrupt provenance: one would write metadata.json mid-way through the other's extraction. The lock below catches the common accidental-double-invoke case (user re-runs in another shell before the first finishes). It is a **best-effort PID-file guard**, not a held flock — the LLM-driven workflow spans many turn boundaries and no single bash invocation can hold flock across them. Use the pattern from `skf-create-skill/references/source-resolution-protocols.md:87` (workspace concurrency guard) as the conceptual model.
+
+**Mirror this exactly so the guard works the same way every run:**
+
+```bash
+# Lock file path — one per skill, lives next to skill-brief.yaml
+LOCK={forge_data_folder}/{skill_name}/.skf-update.lock
+mkdir -p "$(dirname "$LOCK")"
+
+if [ -f "$LOCK" ]; then
+  HELD_PID=$(head -n1 "$LOCK" 2>/dev/null | awk '{print $1}')
+  if [ -n "$HELD_PID" ] && kill -0 "$HELD_PID" 2>/dev/null; then
+    # Live PID — another update is running. HALT.
+    echo "skf-update-skill: another update is in progress (pid=$HELD_PID, started $(awk 'NR==2' "$LOCK" 2>/dev/null))"
+    # (LLM emits SKF_UPDATE_RESULT_JSON status=halted-for-concurrent-run, see below)
+    exit 1
+  fi
+  # Stale lock (PID is dead) — log + overwrite
+  echo "skf-update-skill: clearing stale lock from pid=$HELD_PID"
+fi
+
+# Acquire: write our PID + start timestamp (one per line)
+printf '%s\n%s\n' "$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$LOCK"
+```
+
+**Halt protocol on live-PID collision:**
+
+- Display: `"**Another update is in progress.** The skill {skill_name} is locked by pid={HELD_PID} (started {timestamp from line 2 of the lock file}). Wait for that run to finish, or — if you know that pid is no longer running — delete {LOCK} manually and re-run."`
+- In `{headless_mode}`, emit `SKF_UPDATE_RESULT_JSON` with `status: "halted-for-concurrent-run"`, `error: {phase: "init:concurrency-guard", path: "{LOCK}", reason: "another update in progress (pid={HELD_PID})"}`, and exit immediately. **No `headless_decisions[]` entry** — this is a hard halt before any gate fires.
+
+**Release contract:**
+
+- The terminal health-check step (step 8) deletes the lock file as its final action.
+- **Every halted-for-\* path in this workflow must delete the lock before exiting** — otherwise the next attempt would see a stale lock from this run. The lock-release is a single `rm -f "$LOCK"` per halt site; do not skip it.
+- The lock is best-effort: a crash mid-workflow (process kill, host reboot) leaves a stale lock that the next run will clear via the live-PID check above. No manual cleanup needed in the common case.
 
 ### 2. Validate Required Artifacts
 
@@ -68,7 +116,7 @@ After loading metadata.json, check `skill_type`:
   **To update this stack skill**, run `skf-create-stack-skill` with the same project path. It will re-analyze manifests (code-mode) or re-read constituent skills (compose-mode) and produce an updated stack.
   
   If you came here from an audit report, the drift report identifies which constituent libraries changed — use that to decide whether re-composition is needed."
-- Exit the workflow (do not proceed to step-02)
+- Exit the workflow (do not proceed to step 2)
 
 ### 3. Load Forge Tier Configuration
 
@@ -127,7 +175,7 @@ Load {manualSectionRulesFile} to understand [MANUAL] detection patterns.
 
 "**Source path from provenance map is invalid:** `{source_root}`
 
-Please provide the current source code path:
+Provide the current source code path:
 **Path:** {user provides path}"
 
 ### 7. Present Baseline Summary
@@ -166,7 +214,7 @@ Display: "**Select:** [C] Continue to Change Detection"
 #### 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 update confirmation"
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past update confirmation". **Also append to in-context `headless_decisions[]`** (step 7 surfaces this list in `SKF_UPDATE_RESULT_JSON`): `{gate: "init.update-confirmation", default_action: "C", taken_action: "C", reason: "headless: no user to prompt"}`. The headless_decisions[] array is the structured audit trail for non-interactive runs — see `src/shared/scripts/schemas/skf-update-result-envelope.v1.json` for the entry shape.
 - ONLY proceed to next step when user selects 'C'
 
 ## CRITICAL STEP COMPLETION NOTE

package/src/skf-update-skill/references/manual-section-rules.md

@@ -1,3 +1,7 @@
+---
+type: static-reference
+---
+
 # [MANUAL] Section Rules
 
 ## Detection Pattern

package/src/skf-update-skill/references/merge-conflict-rules.md

@@ -1,3 +1,7 @@
+---
+type: static-reference
+---
+
 # Merge Conflict Rules
 
 ## Change Categories

package/src/skf-update-skill/{steps-c/step-04-merge.md → references/merge.md}

@@ -1,9 +1,11 @@
 ---
-nextStepFile: './step-05-validate.md'
+nextStepFile: 'validate.md'
 manualSectionRulesFile: 'references/manual-section-rules.md'
 mergeConflictRulesFile: 'references/merge-conflict-rules.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 4: Merge
 
 ## STEP GOAL:
@@ -19,8 +21,6 @@ Merge freshly extracted export data into the existing SKILL.md content while pre
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Merge Rules
 
 Load {manualSectionRulesFile} for [MANUAL] detection and preservation patterns.
@@ -165,7 +165,7 @@ Write the merged content produced by sections 3–5 directly to disk now. Later
 **Write SKILL.md:**
 - Use the `Edit` or `Write` tool to write merged SKILL.md content to `{skill_package}/SKILL.md`
 - Preserve UTF-8 encoding
-- If the source version detected during step-03 differs from the previous metadata version, create the new `{skill_package}` directory (`{skill_group}/{new_version}/`) first and write there — the previous version's directory is preserved on disk. Update `{skill_package}` in context to point at the new path.
+- If the source version detected during step 3 differs from the previous metadata version, create the new `{skill_package}` directory (`{skill_group}/{new_version}/`) first and write there — the previous version's directory is preserved on disk. Update `{skill_package}` in context to point at the new path.
 
 **Write stack reference files (if `skill_type == "stack"`):**
 - For each affected file from section 5, use `Edit` or `Write` to write:
@@ -174,10 +174,10 @@ Write the merged content produced by sections 3–5 directly to disk now. Later
 - Preserve [MANUAL] blocks exactly as captured in section 2.
 
 **Do NOT write here:**
-- `metadata.json`, `provenance-map.json`, `evidence-report.md` — derived from merge + validation output, written by step-06 sections 2–4
-- `context-snippet.md` — regenerated from the on-disk SKILL.md + metadata.json by step-06 section 5
+- `metadata.json`, `provenance-map.json`, `evidence-report.md` — derived from merge + validation output, written by step 6 sections 2–4
+- `context-snippet.md` — regenerated from the on-disk SKILL.md + metadata.json by step 6 section 5
 
-**Halt-on-tool-failure:** If any `Edit`/`Write` call errors (permission denied, disk full, path invalid, etc.), halt and report the failure — do not proceed to step-05 validation. The skill package may be in a partial state and will need manual recovery before re-running update-skill.
+**Halt-on-tool-failure:** If any `Edit`/`Write` call errors (permission denied, disk full, path invalid, etc.), halt and report the failure — do not proceed to step 5 validation. The skill package may be in a partial state and will need manual recovery before re-running update-skill.
 
 ### 7. Display Merge Summary
 
@@ -205,7 +205,7 @@ Display: "**Merge complete with conflict resolution. Select:** [C] Continue to V
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after conflict resolution
-- **GATE [default: C if clean merge]** — If `{headless_mode}` and merge is clean (no [MANUAL] conflicts): auto-proceed with [C] Continue, log: "headless: clean merge, auto-continue". If conflicts exist, HALT even in headless mode — conflicts require human judgment.
+- **GATE [default: C if clean merge]** — If `{headless_mode}` and merge is clean (no [MANUAL] conflicts): auto-proceed with [C] Continue, log: "headless: clean merge, auto-continue". **Also append to in-context `headless_decisions[]`** (surfaced via `SKF_UPDATE_RESULT_JSON` by step 7): `{gate: "merge.clean-merge-gate", default_action: "C", taken_action: "C", reason: "headless: clean merge, no conflicts to resolve"}`. If conflicts exist, HALT even in headless mode — conflicts require human judgment, and the headless_decisions[] array does NOT get a continue-on-conflict entry (the workflow status becomes `halted-for-manual-mismatch` instead).
 - ONLY proceed when user selects 'C'
 
 **If clean merge (no conflicts):**

package/src/skf-update-skill/{steps-c/step-03-re-extract.md → references/re-extract.md}

@@ -1,11 +1,21 @@
 ---
-nextStepFile: './step-04-merge.md'
+nextStepFile: 'merge.md'
 extractionPatternsData: 'skf-create-skill/references/extraction-patterns.md'
 extractionPatternsTracingData: 'skf-create-skill/references/extraction-patterns-tracing.md'
 remoteSourceResolutionData: 'references/remote-source-resolution.md'
 tierDegradationRulesData: 'skf-create-skill/references/tier-degradation-rules.md'
+# Resolve `{checkWorkspaceDriftHelper}` to the first existing path; HALT if
+# neither candidate exists. §0.a relies on the helper for the deterministic
+# workspace-pinning guard (git rev-parse + short-SHA prefix match + halt
+# message rendering). Falling back to prose-driven git invocation would
+# lose the four-state dispatch (ok / skipped / mismatch / overridden).
+checkWorkspaceDriftProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-check-workspace-drift.py'
+  - '{project-root}/src/shared/scripts/skf-check-workspace-drift.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3: Re-Extract Changed Exports
 
 ## STEP GOAL:
@@ -20,51 +30,48 @@ Perform tier-aware extraction on only the changed files identified in step 02, p
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 0. Check for Gap-Driven Mode
 
-**If `update_mode == "gap-driven"` (set in step-01 via `--from-test-report`, confirmed in step-02 section 0):**
+**If `update_mode == "gap-driven"` (set in step 1 via `--from-test-report`, confirmed in step 2 section 0):**
 
-Source code has not drifted — the gap-derived manifest from step-02 contains export-level findings translated from the test report, not file-level changes. Perform citation spot-checks instead of full re-extraction to verify each gap-affected export is still at its recorded location.
+Source code has not drifted — the gap-derived manifest from step 2 contains export-level findings translated from the test report, not file-level changes. Perform citation spot-checks instead of full re-extraction to verify each gap-affected export is still at its recorded location.
 
-**0.a Pre-flight: verify workspace HEAD matches pinned commit.** Gap-driven spot-checks read source at recorded `source_line` positions and must see the exact bytes the skill was pinned against. A drifted workspace silently verifies against the wrong tree — moved/renamed symbols appear "verified" because the recorded line now points at different code. Before reading any source, run this guard:
+**0.a Pre-flight: verify workspace HEAD matches pinned commit.** Gap-driven spot-checks read source at recorded `source_line` positions and must see the exact bytes the skill was pinned against. A drifted workspace silently verifies against the wrong tree — moved/renamed symbols appear "verified" because the recorded line now points at different code. Before reading any source, run the guard via `{checkWorkspaceDriftHelper}`:
 
-- Resolve `pinned_commit` from `metadata.source_commit` (loaded in step-01).
-- **If `pinned_commit` is null, empty, `"local"`, or a per-repo map (stack skills) with no single commit:** skip the guard and log `workspace_drift_check: skipped (no pinned commit)`. Continue to bullet 1.
-- **If `source_root` is not a git working tree** (e.g., bare checkout, tarball extract) — detect by running `git -C "{source_root}" rev-parse --is-inside-work-tree`; non-zero exit means skip: log `workspace_drift_check: skipped (not a git working tree)`. Continue to bullet 1.
-- **Otherwise** run `git -C "{source_root}" rev-parse HEAD` and compare to `pinned_commit`. Accept either a full SHA match or a short-SHA prefix match (the pinned commit is often stored as an 8-char short hash — see `src/knowledge/provenance-tracking.md`).
-  - **On match:** log `workspace_drift_check: ok ({short_sha})` and continue.
-  - **On mismatch, AND the user did not pass `--allow-workspace-drift`:** HALT immediately with exit status `halted-for-workspace-drift`. Display:
-
-    ```
-    Workspace HEAD does not match the commit this skill was pinned against.
+```bash
+uv run {checkWorkspaceDriftHelper} <source-root> \
+    --pinned-commit "<metadata.source_commit>" \
+    [--source-ref "<metadata.source_ref>"] \
+    [--allow-drift]
+```
 
-      pinned (metadata.source_commit): {pinned_commit}
-      pinned ref (metadata.source_ref): {source_ref or "unset"}
-      workspace HEAD ({source_root}):  {head_sha}
+Pass `--allow-drift` only when the user provided `--allow-workspace-drift` to update-skill. The helper accepts `""` and `"local"` as the "no pinned commit" sentinels; it also auto-skips when `source_root` is not a git working tree (bare checkout, tarball extract, etc.). **For per-repo pinned-commit maps (stack skills with no single commit):** the caller must skip the helper entirely — pass nothing and log `workspace_drift_check: skipped (no pinned commit)` directly.
 
-    Gap-driven spot-checks read source at pinned line numbers — verifying
-    against a drifted tree silently produces wrong results (symbols appear at
-    unintended locations). Re-sync the workspace before re-running:
+The helper emits a result envelope:
 
-      git -C "{source_root}" checkout {source_ref or pinned_commit}
+```json
+{
+  "status": "ok" | "skipped" | "mismatch" | "overridden",
+  "skip_reason": "no-pinned-commit" | "not-a-git-tree" | null,
+  "head_sha": "...", "head_short_sha": "...", "match_kind": "full" | "short-prefix" | null,
+  "log_message": "workspace_drift_check: ...",
+  "halt_message": "<multi-line user-facing message>" | null
+}
+```
 
-    Or, to intentionally proceed against the current workspace HEAD (accepting
-    that spot-checks will read bytes that differ from the pinned commit),
-    re-run update-skill with `--allow-workspace-drift`.
-    ```
+**Dispatch on `status`:**
 
-    Do not proceed to bullet 1. Step-04 merge has not run; no partial writes.
-  - **On mismatch WITH `--allow-workspace-drift`:** log `workspace_drift_check: overridden (pinned={pinned_commit}, head={head_sha})` and surface a visible warning in the final report ("**Workspace drift accepted via --allow-workspace-drift** — spot-checks read HEAD {head_sha}, not pinned {pinned_commit}"). Continue to bullet 1. The override does not automatically re-pin `metadata.source_commit`; re-pinning is explicit user work (run the normal-mode update-skill flow against the same HEAD, or re-create the skill).
+- **`ok` or `skipped`** (helper exit 0): log `log_message` and continue to bullet 1.
+- **`overridden`** (helper exit 0): log `log_message`, surface a visible warning in the final report ("**Workspace drift accepted via --allow-workspace-drift** — spot-checks read HEAD {head_short_sha}, not pinned {pinned_commit}"), and continue to bullet 1. The override does not automatically re-pin `metadata.source_commit`; re-pinning is explicit user work (run the normal-mode update-skill flow against the same HEAD, or re-create the skill).
+- **`mismatch`** (helper exit 2): HALT immediately with exit status `halted-for-workspace-drift`. Display the helper's `halt_message` verbatim — it already substitutes `{pinned_commit}`, `{source_ref or "unset"}`, `{source_root}`, `{head_sha}`, and the suggested `git checkout` command. Do not proceed to bullet 1. Step-04 merge has not run; no partial writes.
 
-1. Use the provenance map already loaded in step-01 (at `{forge_version}/provenance-map.json`) — do not re-read
-2. For each entry in the gap-derived change manifest from step-02:
+1. Use the provenance map already loaded in step 1 (at `{forge_version}/provenance-map.json`) — do not re-read
+2. For each entry in the gap-derived change manifest from step 2:
    - Look up the export by `name` in `provenance_map.exports` — read `source_file` and `source_line`
    - **If export not found in provenance map:**
-     - **If the manifest entry has a `source_citation` (propagated from the test report by step-02 §0 bullet 4):** read the file at that citation's `file:line ± 5` lines and verify the symbol name still appears within that window. Record a full `verified` / `moved` / `missing` entry using the citation as the starting location — same spot-check logic as the "export found" branch below, keyed on the manifest-supplied citation instead of the provenance map. The export is still flagged `NEW_EXPORT` for the merge step; this branch only upgrades the provenance entry from `unknown` to a live spot-check result so step-06 writes `source_file` / `source_line` instead of `null`.
+     - **If the manifest entry has a `source_citation` (propagated from the test report by step 2 §0 bullet 4):** read the file at that citation's `file:line ± 5` lines and verify the symbol name still appears within that window. Record a full `verified` / `moved` / `missing` entry using the citation as the starting location — same spot-check logic as the "export found" branch below, keyed on the manifest-supplied citation instead of the provenance map. The export is still flagged `NEW_EXPORT` for the merge step; this branch only upgrades the provenance entry from `unknown` to a live spot-check result so step 6 writes `source_file` / `source_line` instead of `null`.
      - **If the manifest entry has no `source_citation` but has a non-empty `remediation_paths[]` AND `severity` is `Critical` or `High`:** route this entry to §0a (Targeted Re-Extraction Branch). §0a scans the remediation paths with the tier-appropriate extractor and, on success, records a full verification record with `verification: re-extracted`, a live `provenance_citation`, and full signature/params/return-type fields for the merge step to consume as a NEW_EXPORT. On failure, §0a halts the workflow — Critical/High gaps are not allowed to degrade to `unknown`. See §0a for the procedure, the consolidated halt protocol, and the output record shape.
-     - **If the manifest entry has no `source_citation` AND (`remediation_paths[]` is empty OR `severity` is `Medium`, `Low`, or `Info`):** record as new (`provenance_citation: unknown`) — no spot-check possible; flag for merge step to handle as `NEW_EXPORT`. Step-06 §3 only accepts null `source_file` / `source_line` for these lower-severity unknowns; a Critical/High unknown reaching step-06 indicates §0a was skipped or bypassed and is a workflow bug.
+     - **If the manifest entry has no `source_citation` AND (`remediation_paths[]` is empty OR `severity` is `Medium`, `Low`, or `Info`):** record as new (`provenance_citation: unknown`) — no spot-check possible; flag for merge step to handle as `NEW_EXPORT`. Step-06 §3 only accepts null `source_file` / `source_line` for these lower-severity unknowns; a Critical/High unknown reaching step 6 indicates §0a was skipped or bypassed and is a workflow bug.
    - **If export found:** read the source file at `source_line ± 5` lines and verify the symbol name still appears within that window
    - Record verification outcome: `verified` (symbol at recorded line), `moved` (symbol found elsewhere in same file — record new line), `missing` (symbol not found in file), `re-extracted` (resolved via §0a from `remediation_paths[]`), or `unknown` (no usable provenance data)
 3. Build a minimal extraction results block matching section 4's shape, with `mode: gap-driven` and per-export verification records:
@@ -100,8 +107,8 @@ Source code has not drifted — the gap-derived manifest from step-02 contains e
              docstring: {summary}
    ```
 
-4. Set `no_reextraction: true` in workflow context — step-06 will use this flag to skip stale `source_file`/`source_line`/`confidence` field updates for `verified` exports. `moved` exports get updated citations; `re-extracted` exports get full fresh provenance from §0a's extraction records (see step-06 §3). The flag is a global gap-driven marker, not a per-entry one — step-06 dispatches on each verification outcome independently.
-5. **Skip all remaining sections of step-03** — sections 1–5 are source-drift extraction paths that do not apply. Display the summary below and load `{nextStepFile}` to proceed directly to the merge step.
+4. Set `no_reextraction: true` in workflow context — step 6 will use this flag to skip stale `source_file`/`source_line`/`confidence` field updates for `verified` exports. `moved` exports get updated citations; `re-extracted` exports get full fresh provenance from §0a's extraction records (see step 6 §3). The flag is a global gap-driven marker, not a per-entry one — step 6 dispatches on each verification outcome independently.
+5. **Skip all remaining sections of step 3** — sections 1–5 are source-drift extraction paths that do not apply. Display the summary below and load `{nextStepFile}` to proceed directly to the merge step.
 
 "**Gap-driven re-extraction.** Verified {verified_count}/{gap_count} citations against live source. Moved: {moved_count}. Missing: {missing_count}. Re-extracted (via remediation paths, §0a): {re_extracted_count}. Unknown (not in provenance map): {unknown_count}. Proceeding to merge."
 
@@ -113,7 +120,7 @@ Source code has not drifted — the gap-derived manifest from step-02 contains e
 
 **Used by:** §0 bullet 2, when a manifest entry has no `source_citation`, has non-empty `remediation_paths[]`, and `severity` is `Critical` or `High`.
 
-**Purpose:** produce AST-backed provenance for citation-less Critical/High gaps so step-06 §3 never writes `source_file: null` for blocking findings. Honors the workflow-level rule **Never hallucinate — every statement must have AST provenance** against the most common gap-driven trigger — a failing test report whose Gap Report `Source:` field is a region reference (e.g., `@storybook/addon-docs control primitives`) rather than a `file:line` pair. Gap-driven mode skips §1 through §5, so §0a is also the only place §1b's source-access and extraction machinery is invoked during gap-driven runs.
+**Purpose:** produce AST-backed provenance for citation-less Critical/High gaps so step 6 §3 never writes `source_file: null` for blocking findings. Honors the workflow-level rule **Never hallucinate — every statement must have AST provenance** against the most common gap-driven trigger — a failing test report whose Gap Report `Source:` field is a region reference (e.g., `@storybook/addon-docs control primitives`) rather than a `file:line` pair. Gap-driven mode skips §1 through §5, so §0a is also the only place §1b's source-access and extraction machinery is invoked during gap-driven runs.
 
 **Procedure:**
 
@@ -130,7 +137,7 @@ Source code has not drifted — the gap-derived manifest from step-02 contains e
    - `new_location: {file}:{start_line}` (same value — satisfies the existing consumer contract)
    - `resolution_source: remediation-paths`
    - `confidence: T1` (AST-extracted) or `T1-low` (pattern-matched fallback)
-   - the full extraction signature (type, params, return_type, docstring) — mirror the shape of §4's per-file extraction record so step-04 Priority 5 can merge it with the same code path used in normal mode.
+   - the full extraction signature (type, params, return_type, docstring) — mirror the shape of §4's per-file extraction record so step 4 Priority 5 can merge it with the same code path used in normal mode.
 5. **Track failures across all qualifying entries.** Collect every entry whose symbol was not found in any scanned remediation path into an `unresolved[]` list. After processing every qualifying entry, if `unresolved[]` is non-empty: HALT with a consolidated report listing every unresolved entry (`name`, `severity`, `remediation_paths`, `files_scanned`, `exports_found_in_scan`). Template:
 
    ```
@@ -156,7 +163,7 @@ Source code has not drifted — the gap-derived manifest from step-02 contains e
 
    Exit with status `halted-for-remediation-path`. Step-04 merge has not run; no partial writes.
 
-6. **Success summary** — record `targeted_reextraction: {resolved_count, files_scanned, exports_matched, tier}` in workflow context. The evidence report (step-06 §4) surfaces this alongside the verified / moved / missing tally.
+6. **Success summary** — record `targeted_reextraction: {resolved_count, files_scanned, exports_matched, tier}` in workflow context. The evidence report (step 6 §4) surfaces this alongside the verified / moved / missing tally.
 
 **Why halt instead of degrading to `unknown`:** a Critical or High gap by definition blocks skill usefulness — it is either missing documentation for a public API or a wrong signature. Silently writing `source_file: null` for a blocking gap produces a skill that passes re-test but still hides the broken behavior behind a placeholder. The halt forces the test report to carry usable remediation information — a one-time fix-up that is far cheaper than a downstream audit trying to track why the "repaired" skill still fails.
 
@@ -222,7 +229,7 @@ Source code has not drifted — the gap-derived manifest from step-02 contains e
 
 ### 2. Extract Changed Files
 
-**Skip authoritative doc paths.** Before iterating the change manifest, build a skip set from `promoted_docs_new[]` (populated by step-02 §1b) and any existing `file_entries[]` entries with `file_type: "doc"` from the provenance map. These are documentation files tracked for drift detection only — they must not reach AST extraction, which would produce ghost entries on non-code content. If a change manifest entry matches the skip set, skip it silently and continue; doc-type drift is handled by step-02 Category D and step-04 Priority 6/7.
+**Skip authoritative doc paths.** Before iterating the change manifest, build a skip set from `promoted_docs_new[]` (populated by step 2 §1b) and any existing `file_entries[]` entries with `file_type: "doc"` from the provenance map. These are documentation files tracked for drift detection only — they must not reach AST extraction, which would produce ghost entries on non-code content. If a change manifest entry matches the skip set, skip it silently and continue; doc-type drift is handled by step 2 Category D and step 4 Priority 6/7.
 
 DO NOT BE LAZY — For EACH remaining file in the change manifest with status MODIFIED, ADDED, or RENAMED, launch a subprocess that:
 
@@ -258,7 +265,7 @@ This helps the merge step (section 4) prioritize which changes are most likely t
 
 CCC failures: skip ranking silently, all changes treated equally.
 
-**Note on remote sources:** If `source_root` is a workspace clone, the CCC index may already exist from a prior forge and can be reused via `ccc search --refresh`. If the source is an ephemeral fallback clone, the clone path is not indexed by CCC — the search will return empty results and semantic ranking will be skipped. Deferred CCC indexing is implemented in create-skill step-03 but not in update-skill. All changes are treated equally for ephemeral remote sources.
+**Note on remote sources:** If `source_root` is a workspace clone, the CCC index may already exist from a prior forge and can be reused via `ccc search --refresh`. If the source is an ephemeral fallback clone, the clone path is not indexed by CCC — the search will return empty results and semantic ranking will be skipped. Deferred CCC indexing is implemented in create-skill step 3 but not in update-skill. All changes are treated equally for ephemeral remote sources.
 
 **IF `tools.ccc` is false:** Skip this section silently.
 
@@ -325,12 +332,14 @@ Extraction Results:
 
 ### 6. Present MENU OPTIONS
 
-Display: "**Proceeding to merge...**"
-
-- After extraction results are compiled, immediately load, read entire file, then execute {nextStepFile}
-- This is an auto-proceed step with no user choices
+- **If `dry_run_mode` is true:** display "**Dry-run mode — skipping merge/validate/write.** Loading report..." and load `report.md` (NOT `{nextStepFile}`). The report emits the dry-run envelope describing what merge+write WOULD have done.
+- Else, display "**Proceeding to merge...**" and after extraction results are compiled, immediately load, read entire file, then execute `{nextStepFile}`.
+- This is an auto-proceed step with no user choices.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN all changed files have been extracted and results compiled will you load {nextStepFile} to begin the merge operation.
+ONLY WHEN all changed files have been extracted and results compiled will you load the next file:
+
+- `dry_run_mode == true` → load `report.md`. Report emits status `dry-run`. No artifact is modified on disk by this run.
+- Otherwise → load `{nextStepFile}` (merge.md) to begin the merge operation.
 

package/src/skf-update-skill/references/remote-source-resolution.md

@@ -1,3 +1,7 @@
+---
+type: static-reference
+---
+
 # Remote Source Resolution (Forge/Deep Tier)
 
 If `source_root` is a local path: proceed with the tier-appropriate strategy as normal.
@@ -83,7 +87,7 @@ After extraction is complete for all files in scope (whether successful or parti
 
 ## Version Reconciliation
 
-After the source path is accessible, check whether the source version has changed since the original skill was created. Look for the version file matching the detected language (e.g., `pyproject.toml`, `package.json`, `Cargo.toml`). If the source version differs from the current `metadata.json` version, record `source_version_detected` in context for step-06 to use when updating `metadata.json`. No warning needed here — step-06 handles the version update.
+After the source path is accessible, check whether the source version has changed since the original skill was created. Look for the version file matching the detected language (e.g., `pyproject.toml`, `package.json`, `Cargo.toml`). If the source version differs from the current `metadata.json` version, record `source_version_detected` in context for step 6 to use when updating `metadata.json`. No warning needed here — step 6 handles the version update.
 
 ## AST Tool Unavailability (Local Source)
 

package/src/skf-update-skill/references/report.md

@@ -0,0 +1,214 @@
+---
+nextStepFile: 'health-check.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 7: Report
+
+## STEP GOAL:
+
+Present a comprehensive change summary showing what was updated, [MANUAL] sections preserved, confidence tier breakdown, and recommend next workflow actions in the SKF chain.
+
+## Rules
+
+- Focus only on reporting — all operations are complete; do not modify any files
+- Present clear, actionable summary with next step recommendations
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
+
+## MANDATORY SEQUENCE
+
+### 1. Handle No-Change Shortcut
+
+**If routed here from step 02 with no changes detected:**
+
+"**Update Skill Report: {skill_name}**
+
+**Status:** No changes detected
+
+Source code matches provenance map exactly. The skill `{skill_name}` is current — no update was needed.
+
+**Provenance age:** {days} days since last extraction
+**Forge tier:** {tier}
+
+**Recommendation:** No action required. Run audit-skill periodically to monitor for drift."
+
+→ Load, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
+
+### 1a. Handle Detect-Only Mode
+
+**If `detect_only_mode` is true (routed here from detect-changes.md §6):**
+
+"**Update Skill Report: {skill_name} — Detect-Only Mode**
+
+**Status:** Detect-only (no writes)
+
+The change manifest below describes what would be updated. No artifact was modified — re-run without `--detect-only` to apply.
+
+{render the change manifest summary table from detect-changes.md §5, plus the per-file detail section}
+
+**Recommendation:** Review the manifest; if it matches expectations, re-run `skf-update-skill` without `--detect-only` to perform the actual update."
+
+The headless envelope (`SKF_UPDATE_RESULT_JSON`) carries `status: "detect-only"`, `files_written: []`, and any `headless_decisions[]` recorded by detect-changes' §1b / §1c / §2.2 gates. `version` and `previous_version` are both equal to the on-disk version (detect-only does not bump). `update_mode` reflects the run's mode (`normal` or `gap-driven` or `degraded`) so consumers know which detection path produced the manifest.
+
+→ Load, read the full file, and execute `{nextStepFile}` (health-check) — even detect-only runs through the terminal health-check step.
+
+### 1b. Handle Dry-Run Mode
+
+**If `dry_run_mode` is true (routed here from re-extract.md §6):**
+
+"**Update Skill Report: {skill_name} — Dry-Run Mode**
+
+**Status:** Dry-run (no writes)
+
+The change manifest below shows what was detected; re-extraction ran to compute the planned merge but neither merge nor write executed. No artifact was modified.
+
+{render the change manifest summary AND the re-extraction summary — what merge+validate+write WOULD have done}
+
+**Planned writes (skipped):**
+- SKILL.md re-merge with re-extracted exports
+- metadata.json version bump (or hold for gap-driven)
+- provenance-map.json update with re-extraction results
+- evidence-report.md
+- context-snippet.md (only if a staleness trigger fired)
+- active-symlink flip (only if version changed)
+
+**Recommendation:** Review the manifest and re-extraction summary; if both match expectations, re-run `skf-update-skill` without `--dry-run` to perform the actual update."
+
+The headless envelope carries `status: "dry-run"`, `files_written: []`, the `headless_decisions[]` recorded so far (everything before merge), and `update_mode` from the run.
+
+→ Load, read the full file, and execute `{nextStepFile}` (health-check).
+
+### 2. Present Change Summary
+
+"**Update Skill Report: {skill_name}**
+
+---
+
+### Operation Summary
+
+| Metric | Value |
+|--------|-------|
+| **Skill** | {skill_name} ({single/stack}) |
+| **Forge Tier** | {tier} |
+| **Mode** | {update_mode}{mode_fallback_note} |
+| **Duration** | {step count} steps |
+
+**`{update_mode}`** is one of `normal`, `gap-driven`, or `degraded` (mirrors the `update_mode` field of `SKF_UPDATE_RESULT_JSON`).
+
+**`{mode_fallback_note}`** surfaces weak-signal fallbacks the workflow took silently and would otherwise be buried in the evidence report. Render it inline after the mode value when any of these conditions fire; render the empty string when none did:
+
+- `--from-test-report` was passed but the test report was missing at the expected path, so step 1 fell back to `normal` mode → ` (gap-driven requested; test report missing — fell back to normal)`
+- `re-extract.md §0.a` skipped the workspace-drift guard because `source_root` is not a git working tree (or HEAD was unreadable) → ` (workspace-drift check skipped: {skip_reason})` where `{skip_reason}` is the helper's `skip_reason` field (`not-a-git-tree` or `HEAD unreadable`)
+- Both fallbacks fired: concatenate both parenthetical notes with `; ` between them
+
+These signals also appear in `warnings[]` on the headless envelope; the Mode row makes them visible to interactive users who scan the report without parsing the envelope.
+
+### Changes Applied
+
+| Category | Count |
+|----------|-------|
+| Files modified | {count} |
+| Files added | {count} |
+| Files deleted | {count} |
+| Files moved/renamed | {count} |
+| **Total exports affected** | {count} |
+
+### Export Changes
+
+| Change Type | Count |
+|-------------|-------|
+| Updated (signature/type change) | {count} |
+| Added (new exports) | {count} |
+| Removed (deleted exports) | {count} |
+| Moved (file relocated) | {count} |
+| Renamed (identifier changed) | {count} |
+
+### Confidence Tier Breakdown
+
+| Tier | Count | Description |
+|------|-------|-------------|
+| T1 | {count} | AST-verified structural extraction |
+| T1-low | {count} | Pattern-matched (Quick tier or degraded) |
+| T2 | {count} | QMD-enriched semantic context |
+
+### [MANUAL] Section Preservation
+
+| Metric | Count |
+|--------|-------|
+| Sections preserved | {count} |
+| Conflicts resolved | {count} |
+| Orphans kept | {count} |
+| Orphans removed | {count} |
+| **Integrity** | {VERIFIED / count issues} |"
+
+### 3. Present Validation Findings (If Any)
+
+**If validation findings exist from step 05:**
+
+"### Validation Findings
+
+| Check | Status | Issues |
+|-------|--------|--------|
+| Spec compliance | {PASS/WARN/FAIL} | {count} |
+| [MANUAL] integrity | {PASS/WARN/FAIL} | {count} |
+| Confidence tiers | {PASS/WARN/FAIL} | {count} |
+| Provenance | {PASS/WARN/FAIL} | {count} |
+
+{List specific findings if WARN or FAIL}"
+
+**If all validations passed:** "### Validation: All checks passed."
+
+### 4. Show Files Updated
+
+"### Files Written
+
+| File | Status |
+|------|--------|
+| `{resolved_skill_package}/SKILL.md` | Updated |
+| `{resolved_skill_package}/metadata.json` | Updated |
+| `{forge_version}/provenance-map.json` | Updated |
+| `{forge_version}/evidence-report.md` | Appended |
+| {stack reference files if applicable} | Updated |
+
+Where `{resolved_skill_package}` = `{skills_output_folder}/{skill_name}/{version}/{skill_name}/` and `{forge_version}` = `{forge_data_folder}/{skill_name}/{version}/` — see `knowledge/version-paths.md`."
+
+### 5. Workflow Chaining Recommendations
+
+"### Next Steps
+
+Based on the update results:"
+
+**If all validations passed:**
+"- **audit-skill** — Run to verify the update resolved known drift
+- **export-skill** — Package the updated skill for distribution
+- **test-skill** — Run test suite against the updated skill"
+
+**If validation warnings/failures exist:**
+"- **audit-skill** — Run to identify remaining issues
+- Review validation findings above before exporting"
+
+**If triggered by audit-skill chain:**
+"- **audit-skill** — Re-run to verify CRITICAL/HIGH drift resolved
+- **export-skill** — Package once audit confirms clean state"
+
+### 5b. Result Contract
+
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_version}/update-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_version}/update-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all modified file paths in `outputs`; include `exports_affected`, `files_modified`, and `validation_status` (passed/warnings/failures) in `summary`.
+
+**Headless envelope (`SKF_UPDATE_RESULT_JSON`):** when `{headless_mode}` is true, ALSO emit a single-line JSON envelope to stdout prefixed with the literal `SKF_UPDATE_RESULT_JSON: `. Schema: `src/shared/scripts/schemas/skf-update-result-envelope.v1.json`. Construct the envelope from in-context state:
+
+```json
+SKF_UPDATE_RESULT_JSON: {"skf_update":{"status":"success|no-changes|halted-for-*|blocked","skill_name":"<name>","version":"<v>","previous_version":"<v>","update_mode":"normal|gap-driven|degraded","files_written":[...],"headless_decisions":[...],"warnings":[...],"error":null|{...}}}
+```
+
+- `headless_decisions[]` — verbatim from the in-context array populated by gates (init.md §confirmation, detect-changes.md §1b/§1c/§2.2, merge.md §gate). Each entry `{gate, default_action, taken_action, reason, evidence?}`. Empty when no gates auto-resolved (e.g. no-changes path skipped detect-changes' gates).
+- `status` — single-field outcome for pipeline branching. `"success"` when the run wrote artifacts and produced no halts; `"no-changes"` when §1 short-circuited; one of the documented `halted-for-*` codes when a halt fired; `"blocked"` as the catch-all.
+- `error` — null on success or no-changes. Object `{phase, path?, reason}` describing the failure when a halt or write error fired. Pipelines branch on `error !== null` for non-zero exit semantics.
+
+The headless envelope is the structured channel; the per-run JSON written above is the audit trail. Both coexist — the envelope is one line on stdout for grep-friendly consumption, the per-run JSON is the full record on disk.
+
+### 6. Chain to Health Check
+
+ONLY WHEN the change summary has been presented, files-written list displayed, and 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 report reads as final.
+