bmad-module-skill-forge 2.0.0 → 2.0.1

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

@@ -11,15 +11,9 @@ nextStepFile: 'shared/health-check.md'
 
 ## 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.
+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. This step only releases the concurrency lock and delegates: no user-facing reports, file writes, or result contracts here (those belong in step 7).
 
-## 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
+## Steps
 
 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):
 
@@ -27,6 +21,6 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
    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.
+   Release the lock before delegating to the shared health-check: the health-check is the terminal step, so once it returns the workflow is done and any still-held lock is orphaned until the next run clears it. Releasing here keeps the lock lifecycle tight against the workflow's actual span.
 
 2. Load `{nextStepFile}`, read it fully, then execute it.

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

@@ -1,6 +1,15 @@
 ---
 nextStepFile: 'detect-changes.md'
 manualSectionRulesFile: 'references/manual-section-rules.md'
+# Resolve `{hashContentHelper}` to the first existing path; HALT if neither
+# candidate exists. §5 uses its `manual-inventory` subcommand to capture the
+# exact pre-write [MANUAL] inventory (per-block byte-exact interior hashes),
+# which write.md §1 (HALT gate) and validate.md Check B later verify against.
+# An LLM marker-count would miss an interior truncation that leaves the marker
+# count unchanged.
+hashContentProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
+  - '{project-root}/src/shared/scripts/skf-hash-content.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -16,7 +25,7 @@ Load the existing skill and all its provenance data, detect whether this is an i
 - Focus only on loading existing artifacts and establishing the baseline — read-only operations
 - Do not begin change detection (Step 02)
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 1. Request Skill Path
 
@@ -27,6 +36,7 @@ Provide either:
 - 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 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
+- `--allow-degraded` (headless mode only) to pre-authorize the lossy degraded full re-extraction if §4 finds no provenance map — without it, a headless run halts `blocked` there rather than silently rebuilding
 - `--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
 
@@ -54,6 +64,8 @@ If a report is located, set `test_report_path` in context to the resolved absolu
 
 **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 `--allow-degraded` was provided:** set `allow_degraded: true` in workflow context. This flag is consumed by §4 below when no provenance map is found under `{headless_mode}`; it has no effect interactively (the [D]/[X] prompt is shown) or when a provenance map is present.
+
 **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.
@@ -81,8 +93,8 @@ if [ -f "$LOCK" ]; then
     # (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"
+  # Dead PID — lock left by a prior halted or crashed run; clear + overwrite
+  echo "skf-update-skill: clearing lock from a prior halted/crashed run (pid=$HELD_PID)"
 fi
 
 # Acquire: write our PID + start timestamp (one per line)
@@ -96,9 +108,9 @@ printf '%s\n%s\n' "$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$LOCK"
 
 **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.
+- The terminal health-check step (step 8) deletes the lock as its final action — the normal end of every non-inspection run. The two init-stage headless halts below (§4 no-provenance-map, §6 invalid-source-path) also delete it explicitly, since they fire right after acquisition, before the terminal step runs.
+- Mid-workflow halts (detect-changes, re-extract, merge, write) do **not** delete the lock themselves — they rely on the self-heal below. This is deliberate: several of those halt sites are also reachable under `--detect-only`/`--dry-run`, which never acquired this lock, so a blind `rm -f` there could clobber a concurrent real update's lock.
+- The lock is best-effort and self-healing: whatever a halt or crash (process kill, host reboot) leaves behind is cleared by the next run's live-PID check above, since the stored PID is a short-lived bash PID that is already dead. No manual cleanup needed in the common case.
 
 ### 2. Validate Required Artifacts
 
@@ -113,7 +125,7 @@ printf '%s\n%s\n' "$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$LOCK"
 
 **Detect skill type from metadata:**
 - If `skill_type == "single"` or absent: flag as single skill
-- If `skill_type == "stack"`: flag as stack skill (multi-file update mode)
+- If `skill_type == "stack"`: flag as stack skill — the guard below redirects it
 
 ### Stack Skill Guard
 
@@ -126,6 +138,8 @@ After loading metadata.json, check `skill_type`:
   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 2)
 
+**This guard is the single gate for stack skills** — every stack is redirected to `skf-create-stack-skill` here, before step 2, and no flag (`--detect-only`, `--dry-run`, `--from-test-report`, `--allow-workspace-drift`) bypasses it. Every later stage therefore runs against a single skill only and carries no stack-merge branch.
+
 ### 3. Load Forge Tier Configuration
 
 **Load `{sidecar_path}/forge-tier.yaml`:**
@@ -160,18 +174,22 @@ Select: [D] Degraded / [X] Abort"
 - If D: set `degraded_mode = true`, proceed with full extraction scope
 - If X: **ABORT**
 
+**In `{headless_mode}` without `--allow-degraded` (default):** do not auto-select [D]. Degraded mode is a full, lossy T1-low re-extraction — choosing it unattended would silently swap surgical update for a create-skill-equivalent rebuild, a policy call that belongs to an operator. Halt instead: release the lock (`rm -f "$LOCK"`), emit `SKF_UPDATE_RESULT_JSON` with `status: "blocked"`, `error: {phase: "init:load-provenance-map", path: "{forge_version}/provenance-map.json", reason: "no provenance map at versioned or flat path; degraded full re-extraction needs a human decision"}`, and exit. No `headless_decisions[]` entry — this is a hard halt, not an auto-resolved gate.
+
+**In `{headless_mode}` with `--allow-degraded` (`allow_degraded: true`):** the operator pre-authorized the lossy rebuild for this run, so treat it as an auto-resolved [D] rather than a halt. Set `degraded_mode = true`, proceed with full extraction scope, and append to in-context `headless_decisions[]`: `{gate: "init.degraded-rebuild", default_action: "X", taken_action: "D", reason: "headless: --allow-degraded pre-authorized degraded full re-extraction", evidence: "no provenance map at {forge_version}/provenance-map.json or flat fallback"}`. Continue to step 2.
+
 ### 5. Load [MANUAL] Section Inventory
 
-Load {manualSectionRulesFile} to understand [MANUAL] detection patterns.
+Load {manualSectionRulesFile} to understand [MANUAL] detection patterns (the human-readable rules for markers, parent-section mapping, and orphan/nesting handling).
 
-**Scan SKILL.md for [MANUAL] sections:**
-- Count all `<!-- [MANUAL:*] -->` markers
-- Map each [MANUAL] block to its parent section (by heading hierarchy)
-- Record section names and approximate line positions
+**Capture the [MANUAL] inventory deterministically.** The workflow's headline rule is "[MANUAL] sections survive regeneration with zero content loss" — the pre-write inventory captured here is the exact baseline that write.md §1 and validate.md Check B verify against, so it must be a per-block byte-exact hash, not an eyeballed marker count. Run the `manual-inventory` subcommand of `{hashContentHelper}` and persist its JSON:
+
+```bash
+uv run {hashContentHelper} manual-inventory {resolved_skill_package}/SKILL.md \
+    > {forge_version}/.manual-inventory.json
+```
 
-**For stack skills, also scan:**
-- All `references/*.md` files for [MANUAL] markers
-- All `references/integrations/*.md` files for [MANUAL] markers
+The emitted JSON is `{"blocks":[{name, content_hash, byte_offset, parent_heading}...], "count":N}` — each `content_hash` covers the block's byte-exact interior, so a later interior truncation that leaves the marker count unchanged is still caught. Bind the persisted path as `{manual_inventory}` in context; write.md §1 and validate.md Check B pass it to `manual-verify`. Surface the block `count` in the baseline summary (§7 `{manual_count}`).
 
 ### 6. Resolve Source Code Path
 
@@ -186,6 +204,8 @@ Load {manualSectionRulesFile} to understand [MANUAL] detection patterns.
 Provide the current source code path:
 **Path:** {user provides path}"
 
+**In `{headless_mode}`:** there is no operator to supply a path. Halt: release the lock (`rm -f "$LOCK"`), emit `SKF_UPDATE_RESULT_JSON` with `status: "blocked"`, `error: {phase: "init:resolve-source-path", path: "{source_root}", reason: "source_root from provenance map is invalid or inaccessible and no interactive path can be supplied"}`, and exit. No `headless_decisions[]` entry — this is a hard halt, not an auto-resolved gate.
+
 ### 7. Present Baseline Summary
 
 "**Update Skill Baseline:**
@@ -193,7 +213,7 @@ Provide the current source code path:
 | Property | Value |
 |----------|-------|
 | **Skill** | {skill_name} |
-| **Type** | {single/stack} |
+| **Type** | single |
 | **Version** | {version} |
 | **Created** | {created date} |
 | **Source** | {source_root} |
@@ -210,22 +230,9 @@ Provide the current source code path:
 
 **Ready to detect changes and update this skill?**"
 
-### 8. Present MENU OPTIONS
-
-Display: "**Select:** [C] Continue to Change Detection"
-
-#### Menu Handling Logic:
-
-- IF C: Load, read entire file, then execute {nextStepFile}
-- IF Any other: help user respond, then [Redisplay Menu Options](#8-present-menu-options)
-
-#### 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". **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'
+### 8. Confirmation Gate
 
-## CRITICAL STEP COMPLETION NOTE
+Present "**Select:** [C] Continue to Change Detection" and wait for the user to confirm; on [C], load, read the full file, then execute {nextStepFile}.
 
-ONLY WHEN [C] is selected and baseline has been established with all required artifacts loaded, will you then load and read fully `{nextStepFile}` to execute change detection.
+**Headless (`{headless_mode}` true):** auto-continue and append to in-context `headless_decisions[]` (step 7 surfaces it in `SKF_UPDATE_RESULT_JSON`): `{gate: "init.update-confirmation", default_action: "C", taken_action: "C", reason: "headless: no user to prompt"}`. Entry shape: `src/shared/scripts/schemas/skf-update-result-envelope.v1.json`.
 

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

@@ -26,8 +26,7 @@ It must be preserved during any update operation.
 2. **Preserve marker positions** — if the surrounding generated content moves, the [MANUAL] block moves with its logical parent section
 3. **Orphan detection** — if the parent section is deleted (export removed), flag as WARNING and present to user
 4. **Multiple [MANUAL] blocks** — a single SKILL.md may have multiple [MANUAL] sections; preserve all
-5. **Stack skill [MANUAL] blocks** — [MANUAL] markers can appear in any output file (SKILL.md, references/*.md, integrations/*.md); preserve across all files
-6. **Nested [MANUAL] forbidden** — [MANUAL] blocks cannot be nested; if detected, flag as ERROR
+5. **Nested [MANUAL] forbidden** — [MANUAL] blocks cannot be nested; if detected, flag as ERROR
 
 ### Conflict Types
 

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

@@ -4,58 +4,7 @@ type: static-reference
 
 # Merge Conflict Rules
 
-## Change Categories
-
-### Category 1: Modified Exports (signature/type change)
-
-- **Action:** Re-extract affected export with fresh AST analysis
-- **Merge:** Replace generated content for that export; preserve adjacent [MANUAL] blocks
-- **Confidence:** Same tier as original (T1/T1-low/T2)
-
-### Category 2: New Exports (added since last generation)
-
-- **Action:** Extract new export with full AST analysis
-- **Merge:** Append to appropriate section based on export type (function, type, class, constant)
-- **Confidence:** Label with extraction tier confidence
-- **[MANUAL] impact:** None — new content, no existing [MANUAL] blocks
-
-### Category 3: Deleted Exports (removed from source)
-
-- **Action:** Remove generated content for that export
-- **Merge:** Check for attached [MANUAL] blocks before deletion
-- **If [MANUAL] attached:** Flag as orphan, present to user for decision
-- **If no [MANUAL]:** Auto-remove generated content
-
-### Category 4: Moved Exports (file relocated)
-
-- **Action:** Update provenance map file references
-- **Merge:** Update file:line citations in generated content
-- **Confidence:** Retain original tier if AST structure unchanged; downgrade to T1-low if structure changed
-- **[MANUAL] impact:** Preserve — content unchanged, only provenance metadata updates
-
-### Category 5: Renamed Exports (identifier changed)
-
-- **Action:** Re-extract with new identifier
-- **Merge:** Replace old identifier references in generated content
-- **[MANUAL] impact:** Flag if [MANUAL] blocks reference old identifier name
-
-## Merge Priority Order
-
-1. Process deleted exports first (remove generated content, flag [MANUAL] orphans)
-2. Process moved exports second (update references only)
-3. Process renamed exports third (update identifiers)
-4. Process modified exports fourth (re-extract and replace)
-5. Process new exports last (append to sections)
-
-## Stack Skill Merge Rules
-
-For stack skills with multi-file outputs:
-
-1. **SKILL.md:** Apply standard merge rules above
-2. **references/{library}.md:** Merge per-library, preserving [MANUAL] blocks within each
-3. **references/integrations/{pair}.md:** Merge per-integration-pair
-4. **metadata.json:** Regenerate completely (no [MANUAL] support in JSON)
-5. **context-snippet.md:** Regenerate completely (no [MANUAL] support — too concise)
+> Change-category actions and the merge priority order (deleted → moved → renamed → modified → new, plus the gap-driven priorities) are specified authoritatively in `merge.md` §3. This reference carries only the one thing §3 does not: the conflict-resolution strategy table below.
 
 ## Conflict Resolution Strategies
 

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

@@ -10,21 +10,21 @@ mergeConflictRulesFile: 'references/merge-conflict-rules.md'
 
 ## STEP GOAL:
 
-Merge freshly extracted export data into the existing SKILL.md content while preserving all [MANUAL] sections. Detect and resolve conflicts where regenerated content overlaps developer-authored content. For stack skills, merge across all output files.
+Merge freshly extracted export data into the existing SKILL.md content while preserving all [MANUAL] sections. Detect and resolve conflicts where regenerated content overlaps developer-authored content.
 
 ## Rules
 
 - Focus only on merging extractions into existing skill content
 - Never delete or modify [MANUAL] section content
-- Write merged SKILL.md (and stack reference files) directly to disk at section 6b — Claude Code's Edit/Write tools commit on call, so there is no held-in-memory "edit plan" primitive; subsequent steps validate and verify against the on-disk files
+- Write merged SKILL.md directly to disk at section 6b — Claude Code's Edit/Write tools commit on call, so there is no held-in-memory "edit plan" primitive; subsequent steps validate and verify against the on-disk files
 - If [MANUAL] conflicts detected: halt and present to user. If clean merge: auto-proceed
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 1. Load Merge Rules
 
 Load {manualSectionRulesFile} for [MANUAL] detection and preservation patterns.
-Load {mergeConflictRulesFile} for change category merge strategies and priority order.
+Load {mergeConflictRulesFile} for the conflict-resolution strategy table (the change-category actions and priority order live in §3 below).
 
 ### 2. Extract [MANUAL] Blocks
 
@@ -35,7 +35,7 @@ From the [MANUAL] inventory captured in step 01:
 
 ### 3. Apply Merge by Priority Order
 
-Follow the merge priority order from {mergeConflictRulesFile}:
+Apply merge in the following priority order:
 
 **Priority 1 — Process DELETED exports:**
 - Remove generated content for deleted exports
@@ -146,20 +146,6 @@ Select: [K] Keep / [R] Remove / [E] Edit"
 
 Process each conflict with user's decision.
 
-### 5. Stack Skill Merge (Conditional)
-
-**ONLY if skill_type == "stack":**
-
-Apply the same merge process to each stack output file:
-- `references/{library}.md` — merge per-library changes, preserve [MANUAL] blocks
-- `references/integrations/{pair}.md` — merge per-integration-pair
-- `metadata.json` — regenerate completely (no [MANUAL] support)
-- `context-snippet.md` — regenerate completely (no [MANUAL] support)
-
-Report stack file merge status for each file.
-
-**If skill_type != "stack":** Skip with notice: "Individual skill — single file merge."
-
 ### 6. Compile Merge Results
 
 Build merge result summary:
@@ -176,30 +162,22 @@ Merge Results:
   manual_conflicts_resolved: [count]
   manual_orphans_kept: [count]
   manual_orphans_removed: [count]
-
-  stack_files_merged: [count] (if stack skill)
 ```
 
 ### 6b. Write Merged Files to Disk
 
-Write the merged content produced by sections 3–5 directly to disk now. Later steps read from these files for validation and verification. The write must happen exactly once, here.
+Write the merged content produced by sections 3–4 directly to disk now. Later steps read from these files for validation and verification. The write must happen exactly once, here.
 
 **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 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:
-  - `references/{library}.md` with merged per-library content
-  - `references/integrations/{pair}.md` with merged per-integration content
-- 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 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 5 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 with status `halted-for-write-failure` 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. In `{headless_mode}`, emit the halt envelope per SKILL.md §Headless (`error: {phase: "merge:write-skill-md", path: "{skill_package}/SKILL.md", reason: "..."}`).
 
 ### 7. Display Merge Summary
 
@@ -213,36 +191,14 @@ Write the merged content produced by sections 3–5 directly to disk now. Later
 | [MANUAL] sections preserved | {count} |
 | Conflicts resolved | {count} |"
 
-### 8. Present MENU OPTIONS
-
-**If conflicts were resolved (user interaction occurred):**
-
-Display: "**Merge complete with conflict resolution. Select:** [C] Continue to Validation"
-
-#### Menu Handling Logic:
-
-- IF C: Load, read entire file, then execute {nextStepFile}
-- IF Any other: help user respond, then [Redisplay Menu Options](#8-present-menu-options)
-
-#### 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". **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):**
-
-Display: "**Clean merge — proceeding to validation...**"
-
-#### Clean Merge Menu Handling Logic:
-
-- Immediately load, read entire file, then execute {nextStepFile}
+### 8. Gate to Validation
 
-#### Clean Merge EXECUTION RULES:
+**Clean merge (no conflicts):** display "**Clean merge — proceeding to validation...**", then load, read the full file, and execute {nextStepFile} (auto-proceed).
 
-- This is an auto-proceed path when no conflicts exist
+**Conflicts were resolved (user interaction occurred):** present "**Merge complete with conflict resolution. Select:** [C] Continue to Validation" and wait for the user to confirm before loading {nextStepFile}.
 
-## CRITICAL STEP COMPLETION NOTE
+**Headless (`{headless_mode}` true):**
 
-ONLY WHEN all merge operations are complete and any [MANUAL] conflicts have been resolved by the user will you load {nextStepFile} to begin validation.
+- Clean merge → auto-continue and 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"}`.
+- Conflicts present → halt even in headless mode (conflicts require human judgment): status `halted-for-manual-mismatch`, emitting the halt envelope per SKILL.md §Headless (`error: {phase: "merge:conflict-resolution", reason: "..."}`); no `headless_decisions[]` entry is added.
 

package/src/skf-update-skill/references/re-extract.md

@@ -28,7 +28,7 @@ Perform tier-aware extraction on only the changed files identified in step 02, p
 - Only extract files in the change manifest — do not touch unchanged files. **Exception (gap-driven mode):** §0a's Targeted Re-Extraction Branch also scans files listed in each manifest entry's `remediation_paths[]` to resolve citation-less Critical/High gaps.
 - For each changed file, launch a subprocess for deep AST analysis (Pattern 2); if unavailable, extract sequentially
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 0. Check for Gap-Driven Mode
 
@@ -45,7 +45,7 @@ uv run {checkWorkspaceDriftHelper} <source-root> \
     [--allow-drift]
 ```
 
-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.
+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.).
 
 The helper emits a result envelope:
 
@@ -63,7 +63,7 @@ The helper emits a result envelope:
 
 - **`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.
+- **`mismatch`** (helper exit 2): HALT immediately with 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. In `{headless_mode}`, emit the halt envelope per SKILL.md §Headless (`error: {phase: "re-extract:workspace-drift", path: "{source_root}", reason: "..."}`).
 
 1. Use the provenance map already loaded in step 1 (at `{forge_version}/provenance-map.json`) — do not re-read
 2. **Partition by change category, then iterate the export-bearing entries.** Entries that do not name an export skip the per-export verification below — they have no symbol to resolve against source:
@@ -173,7 +173,7 @@ The helper emits a result envelope:
      c) Downgrade the gap(s) to Medium/Low/Info (accepts the degraded documentation outcome).
    ```
 
-   Exit with status `halted-for-remediation-path`. Step-04 merge has not run; no partial writes.
+   Exit with status `halted-for-remediation-path`. Step-04 merge has not run; no partial writes. In `{headless_mode}`, emit the halt envelope per SKILL.md §Headless (`error: {phase: "re-extract:targeted-reextraction", reason: "..."}`).
 
 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.
 
@@ -223,7 +223,7 @@ The helper emits a result envelope:
 
 **Forge tier (AST structural extraction):**
 
-⚠️ **CRITICAL:** Load and follow the **AST Extraction Protocol** from `{extractionPatternsData}`. Use the decision tree based on the number of changed files: prefer MCP `find_code()` for small sets, `find_code_by_rule()` with scoped YAML rules for medium sets, and CLI `--json=stream` with line-by-line streaming for large sets. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases.
+Load and follow the **AST Extraction Protocol** from `{extractionPatternsData}`. Use the decision tree based on the number of changed files: prefer MCP `find_code()` for small sets, `find_code_by_rule()` with scoped YAML rules for medium sets, and CLI `--json=stream` with line-by-line streaming for large sets. Never use `ast-grep --json` (without `=stream`) — it loads the entire result set into memory and will fail on large codebases.
 
 - Extract: function signatures, type definitions, class members, exported constants
 - Extract: parameter types, return types, JSDoc/docstring comments
@@ -243,17 +243,11 @@ The helper emits a result envelope:
 
 **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:
+For each remaining file in the change manifest with status MODIFIED, ADDED, or RENAMED, launch a subprocess that:
 
 1. Loads the source file
 2. Performs tier-appropriate extraction (Quick/Forge/Forge+/Deep)
-3. For each export found:
-   - Record: export name, type (function/class/type/constant), signature
-   - Record: file path, start line, end line
-   - Record: parameters with types (if function/method)
-   - Record: return type (if function/method)
-   - Record: JSDoc/docstring summary (if present)
-   - Label: confidence tier (T1/T1-low/T2)
+3. Extract each export into the per-file return contract shown in bullet 4.
 4. **Return contract.** Each extraction worker returns ONLY this per-file block — no prose, no commentary, no markdown fences (the parent strips wrapping fences before parsing). The shape is exactly the per-file record §4 aggregates (the `Per-file extractions` block, lines below), so the parent appends it verbatim rather than re-parsing free text:
 
    ```json
@@ -291,7 +285,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 3 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 returns empty results, so semantic ranking is skipped and all changes are treated equally.
 
 **IF `tools.ccc` is false:** Skip this section silently.
 
@@ -356,16 +350,10 @@ Extraction Results:
 
 **Proceeding to merge with existing skill...**"
 
-### 6. Present MENU OPTIONS
+### 6. Route to Next Step
 
-- **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.
+This step auto-proceeds — no user choices. Once all changed files are extracted and results compiled, load and fully read the next file, then execute it, per the branch that applies:
 
-## CRITICAL STEP COMPLETION NOTE
-
-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.
+- **`dry_run_mode == true`** → display "**Dry-run mode — skipping merge/validate/write.** Loading report..." and load `report.md` (NOT `{nextStepFile}`); it emits status `dry-run` describing what merge+write would have done. No artifact is modified on disk by this run.
+- **Otherwise** → display "**Proceeding to merge...**" and load `{nextStepFile}` (merge.md) to begin the merge operation.
 

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

@@ -16,7 +16,7 @@ Present a comprehensive change summary showing what was updated, [MANUAL] sectio
 - 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
+## Steps
 
 ### 1. Handle No-Change Shortcut
 
@@ -89,7 +89,7 @@ The headless envelope carries `status: "dry-run"`, `files_written: []`, the `hea
 
 | Metric | Value |
 |--------|-------|
-| **Skill** | {skill_name} ({single/stack}) |
+| **Skill** | {skill_name} |
 | **Forge Tier** | {tier} |
 | **Mode** | {update_mode}{mode_fallback_note} |
 | **Duration** | {step count} steps |
@@ -169,7 +169,6 @@ These signals also appear in `warnings[]` on the headless envelope; the Mode row
 | `{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`."
 
@@ -199,16 +198,24 @@ Write the result contract per `shared/references/output-contract-schema.md`: the
 **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|{...}}}
+SKF_UPDATE_RESULT_JSON: {"skf_update":{"status":"success|no-changes|detect-only|dry-run|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.
+- `headless_decisions[]` — verbatim from the in-context array populated by gates (init.md §confirmation and §4 degraded-rebuild, 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; `"detect-only"` / `"dry-run"` for the §1a/§1b read-only exits; one of the documented `halted-for-*` codes when a halt fired; `"blocked"` as the catch-all. The full enum lives in the schema (this step emits the value already resolved in context).
 - `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.
 
+**Post-finalization hook.** If `{onCompleteCommand}` (resolved in SKILL.md On Activation §3 from `workflow.on_complete`) is non-empty, invoke it after both result-JSON writes complete:
+
+```bash
+{onCompleteCommand} --result-path={forge_version}/update-skill-result-latest.json
+```
+
+Run it with a bounded timeout (default 60s). On success, log an Info note and continue; on non-zero exit, timeout, or any failure, append the reason to `warnings[]` (surfaced on the headless envelope) and continue. The hook must never fail the workflow — it is integration glue (notify a CI router, chain audit/export/test) orthogonal to the update outcome. Empty `{onCompleteCommand}` = no-op, no log entry.
+
 ### 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.
+Once the change summary has been presented, the files-written list displayed, and the result contract saved, load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop at the report even though it reads as final.