bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-update-skill/references/detect-changes.md

@@ -25,6 +25,21 @@ buildChangeManifestProbeOrder:
 provenanceGapDispatchProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-provenance-gap-dispatch.py'
   - '{project-root}/src/shared/scripts/skf-provenance-gap-dispatch.py'
+# Resolve `{detectScriptsAssetsHelper}` to the first existing path; HALT if
+# neither candidate exists. §Category D uses `detect` to walk the current
+# source tree for scripts/assets (directory conventions, shebang signals,
+# `package.json` `bin` entry-points, asset filename patterns) so NEW_FILE
+# detection mirrors create-skill §4c exactly. Falling back to prose-driven
+# file walking would let the LLM drift on the heuristic list and miss new
+# scripts/assets at deeper directory depths — and on installed modules
+# (no `src/` tree) the LLM would otherwise guess a non-existent path.
+detectScriptsAssetsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-scripts-assets.py'
+  - '{project-root}/src/shared/scripts/skf-detect-scripts-assets.py'
+# `{newFileDiffHelper}` derives NEW_FILE (inventory source_files not in the
+# provenance map, minus [MANUAL] paths) — the set-difference §Category D would
+# otherwise ask the model to compute by hand. Per-skill helper, always bundled.
+newFileDiffHelper: 'scripts/skf-new-file-diff.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -40,7 +55,7 @@ Compare current source code state against the provenance map to produce a comple
 - Focus only on detecting and classifying changes — do not extract or merge
 - Use subprocess Pattern 4 (parallel) when available; if unavailable, compare sequentially
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 0. Check for Test Report Input (Gap-Driven Mode)
 
@@ -94,7 +109,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
 ### 1b. Discovered Authoritative Files Protocol (Mirror)
 
-**Purpose:** mirror `skf-create-skill` §2a into update-skill. `skf-create-skill` §2a catches authoritative AI documentation files (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.) during **creation**. But a project may add these files *after* the skill was created — for example, an upstream project adopts an `llms.txt` convention six months into development. Without this mirror, update-skill would either miss the new file entirely (if it doesn't match the provenance map's file patterns) or classify it as a generic ADDED file in §2 Category A with no authoritative-file treatment. The mirror surfaces the discovery with the same P/S/U prompt create-skill uses, honoring any prior amendments.
+**Purpose:** mirror `skf-create-skill` §2a into update-skill. `skf-create-skill` §2a catches authoritative AI documentation files (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.) during **creation**, but a project may add these files *after* the skill was created. Without this mirror, update-skill would either miss the new file entirely (if it doesn't match the provenance map's file patterns) or classify it as a generic ADDED file in §2 Category A with no authoritative-file treatment. The mirror surfaces the discovery with the same P/S/U prompt create-skill uses, honoring any prior amendments.
 
 **Skip this section entirely if:**
 
@@ -166,11 +181,11 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
 **Record for evidence report:** the update-skill evidence report appends `authoritative_files_mirror: {candidates: N, promoted: P, skipped: S, pre_decided: A, already_tracked: T, decisions: [{path, action, heuristic, reason}]}`.
 
-**Interaction with §2 change detection:** promoted docs live in `promoted_docs_new[]`, NOT in the change manifest. But §2 Category A ("files in source but not in provenance map → ADDED") would still find the promoted doc files on disk and classify them as ADDED if nothing prevents it. The coordination mechanism is an explicit pre-filter exclusion set built in §2.0 (below) that every Category A subprocess worker receives as an input before it starts scanning. See §2.0 for the exact contract. The exclusion set is the only mechanism guaranteeing that parallel subprocesses cannot double-count `promoted_docs_new[]` paths — prose-level "skip any path" instructions cannot cross subprocess boundaries.
+**Interaction with §2 change detection:** promoted docs live in `promoted_docs_new[]`, not in the change manifest. §2.0's `change_detection_excludes` set (built below) is what stops §2 Category A from re-classifying them as ADDED — it is the only coordination that survives across the parallel Category A subprocesses.
 
 ### 1c. Major-Version Scope Reconciliation (Pre-Detection)
 
-**Purpose:** When upstream undergoes a paradigm shift (rebrand, package restructure, major-version rewrite), the brief's `scope.include` no longer reflects the real public API. §1b handles new authoritative-doc files; §1c handles new **code globs** that fall outside the original scope. Without it, update-skill silently misses the new surface and pays the gap cost on every future update — the cocoindex `0.3.37 → 1.0.0` and cognee `0.5.8 → 1.0.0` runs are existence proofs that this case is real and recurring.
+**Purpose:** §1b handles new authoritative-doc files; §1c handles new **code globs** that fall outside the original scope when upstream restructures (rebrand, package restructure, major-version rewrite) so the brief's `scope.include` no longer reflects the real public API. Without it, update-skill silently misses the new public surface and pays the gap cost on every future update.
 
 **Skip this section entirely if:**
 
@@ -222,7 +237,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
      - `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).
 
-   **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.
+   **Note:** the Out-of-Scope section is an optional audit-skill output and is often absent or empty — new-file detection is update-skill's job (§1b/§2.2), not audit-skill's — so the `no-report` / `no-candidates` paths above are the common case.
 
 3. **Prompt for each unresolved candidate.** Present the same menu shape as §1b:
 
@@ -305,7 +320,20 @@ Launch subprocesses in parallel that compare source state against provenance map
 
 **Category C — Rename detection:**
 - Cross-reference deleted files/exports with added files/exports
-- 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
+- If content similarity > 80% (fixed bundled threshold — not configurable): 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
+
+**Subprocess return contract.** Hand each Category worker its exact output slice so it returns parse-ready JSON, not prose the parent must re-read. Each worker returns ONLY its own object — no prose, no commentary, no markdown fences (parent strips wrapping fences before parsing). The slice each worker fills is exactly the key §3's `build` helper consumes (the `category_a/b/c` shape below; Category D is helper-driven, not a worker):
+
+```json
+// Category A worker returns ONLY:
+{"category_a": {"modified": [...], "added": [...], "deleted": [...]}}
+// Category B worker returns ONLY:
+{"category_b": {"modified_exports": [...], "new_exports": [...], "deleted_exports": [...], "moved_exports": [...]}}
+// Category C worker returns ONLY:
+{"category_c": {"renamed_files": [...], "renamed_exports": [...]}}
+```
+
+The parent merges the three slices (plus Category D and the `degraded_mode`/`update_mode` flags) into the single category-JSON object §3 pipes to the `build` helper.
 
 **Category D — Script/asset file changes:**
 
@@ -334,9 +362,14 @@ Translate the helper's output into the change manifest:
 - `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.
+The compare helper reports only tracked files; NEW_FILE detection (a file present in source but absent from the provenance map) is a set-difference, so it runs through a script rather than the prompt. Pipe the same deterministic detector create-skill step 3 §4c uses (resolved via `detectScriptsAssetsProbeOrder`) into `{newFileDiffHelper}`, which subtracts the provenance map's `file_entries[].source_file` and sets aside user-authored `[MANUAL]` paths:
 
-Files in `scripts/[MANUAL]/` or `assets/[MANUAL]/` → SKIP (user-authored, preserved).
+```bash
+uv run {detectScriptsAssetsHelper} detect <source-root> \
+    | uv run {newFileDiffHelper} {forge_version}/provenance-map.json
+```
+
+It emits `{"new_files":[{source_file, kind}], "skipped_manual":[...], "already_tracked":[...], "stats":{...}}`. Add each `new_files[]` entry to the manifest as NEW_FILE — `kind` (`script`/`asset`) selects the target array. `skipped_manual[]` are user-authored files under `scripts/[MANUAL]/` or `assets/[MANUAL]/`, preserved and not touched; `already_tracked[]` were handled by the compare above.
 
 Aggregate all subprocess results into a unified change manifest.
 
@@ -356,7 +389,7 @@ echo "{category JSON}" | uv run {buildChangeManifestHelper} deletion-ratio \
     --provenance-map {forge_version}/provenance-map.json
 ```
 
-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:
+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`. `should_trigger` fires when the deletion ratio reaches the fixed bundled threshold of 50% (`ratio >= 0.50`, baked into the helper — not configurable). The output envelope:
 
 ```json
 {
@@ -399,8 +432,6 @@ The upstream surface appears to have been substantially replaced. The brief's
 - **[B] Brief:** halt with status `halted-for-brief-refinement`. Display: `"Halting update-skill. Re-run skf-brief-skill to refine scope for {skill_name}, then re-run skf-update-skill."` Change manifest discarded — no partial writes.
 - **[A] Audit:** halt with status `halted-for-audit`. Display: `"Halting update-skill. Run skf-audit-skill against {skill_name} to map the new surface — its drift report will feed §1c on the next update-skill run."` Change manifest discarded.
 
-**Why both §1c and §2.2:** §1c is precise (per-path P/S/U) but requires upstream signal from audit-skill. §2.2 is coarse (single halt/continue) but self-contained — it fires even when the user runs update-skill directly without audit. Together they cover the major-version case across the two real workflows.
-
 ### 3. Build Change Manifest
 
 Hand the assembled Category A/B/C/D JSON to the helper:
@@ -460,7 +491,7 @@ The skill `{skill_name}` is current — no update needed.
 
 → Skip steps 03-06, immediately load {noChangeReportFile} with "no changes" status.
 
-### 5. Display Change Summary and Auto-Proceed
+### 5. Display Change Summary and Route
 
 "**Change Detection Complete:**
 
@@ -470,30 +501,11 @@ The skill `{skill_name}` is current — no update needed.
 | Files added | {count} |
 | Files deleted | {count} |
 | Files moved/renamed | {count} |
-| Exports affected | {total_export_changes} |
-
-**Proceeding to re-extraction of {affected_file_count if normal mode, or gap_count if gap-driven mode} changes...**"
-
-### 6. Present MENU OPTIONS
-
-Display: "**Proceeding to re-extraction...**"
-
-#### Menu Handling Logic:
-
-- **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 (or to report when `detect_only_mode` is true)
-
-## CRITICAL STEP COMPLETION NOTE
+| Exports affected | {total_export_changes} |"
 
-ONLY WHEN the change manifest is fully built will you load the next file:
+This step auto-proceeds — no user choices. Once the change manifest is fully built, load and fully read the next file, then execute it, per the branch that applies:
 
-- `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.
+- **`detect_only_mode == true`** → display "**Detect-only mode — skipping re-extract/merge/validate/write.** Loading report..." and load `{noChangeReportFile}` (report.md), which emits status `detect-only`. Do not load `{nextStepFile}`.
+- **No changes detected** (section 4) → load `{noChangeReportFile}` (report.md), which emits status `no-changes`.
+- **Otherwise** → display "**Proceeding to re-extraction of {affected_file_count if normal mode, or gap_count if gap-driven mode} changes...**" and load `{nextStepFile}` (re-extract.md) to begin re-extraction.
 

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

@@ -1,7 +1,7 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
@@ -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
 
@@ -38,6 +48,7 @@ Provide either:
 3. If not in manifest: check for `active` symlink at `{skills_output_folder}/{skill-name}/active` — resolve to `{skill_group}/active/{skill-name}/`
 4. If neither: fall back to flat path `{skills_output_folder}/{skill-name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
 5. Store the resolved path as `{resolved_skill_package}` for all subsequent artifact loading
+6. Bind `{baseline_version}` to the pre-update version — for an update this is the version being updated, i.e. the `{active_version}` resolved in step 1 above (the flat-path fallback in step 4 has no version, so use the package version read from metadata.json in §2). Step 2 §1c passes `{baseline_version}` to `skf-provenance-gap-dispatch.py` as a required argument; leaving it unbound makes the helper search a wrong/empty directory and silently return `no-report`, dropping the major-version off-ramp.
 
 Resolve the path to an absolute skill folder location.
 
@@ -53,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.
@@ -80,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)
@@ -95,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
 
@@ -112,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
 
@@ -125,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`:**
@@ -159,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
 
@@ -185,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:**
@@ -192,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} |
@@ -209,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.