bmad-module-skill-forge 1.9.0 → 2.0.1

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,18 +243,26 @@ 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)
-4. Returns structured extraction findings to parent
+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
+   {
+     "file_path": "...",
+     "exports": [
+       {"name": "...", "type": "function|class|type|constant",
+        "signature": "...", "location": "{file}:{start_line}-{end_line}",
+        "confidence": "T1|T1-low|T2",
+        "parameters": [{"name": "...", "type": "..."}],
+        "return_type": "...", "docstring": "...",
+        "qmd_evidence": "<if Deep tier, else omit>"}
+     ]
+   }
+   ```
 
 **For DELETED files:** No extraction needed — deletions handled in merge step.
 
@@ -277,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.
 
@@ -342,16 +350,10 @@ Extraction Results:
 
 **Proceeding to merge with existing skill...**"
 
-### 6. Present MENU OPTIONS
-
-- **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
+### 6. Route to Next Step
 
-ONLY WHEN all changed files have been extracted and results compiled will you load the next file:
+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:
 
-- `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.
 

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

@@ -1,5 +1,13 @@
 ---
 nextStepFile: 'write.md'
+# Resolve `{hashContentHelper}` to the first existing path; HALT if neither
+# candidate exists. Check B uses its `manual-verify` subcommand to verify the
+# merged (on-disk) SKILL.md against the byte-exact [MANUAL] inventory captured
+# in step 1 §5 — the deterministic replacement for the LLM byte-identity
+# eyeball, which could silently pass a subtly truncated block.
+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}. -->
@@ -14,9 +22,9 @@ Validate the merged skill content against the agentskills.io specification, veri
 
 - Focus only on validation — do not fix issues (that's the user's choice)
 - Validation is read-only — do not modify merged content
-- Use parallel validation checks (Pattern 4) when available; if unavailable, check sequentially
+- Run the two live structural checks (B, then C) in order; Checks A, D, E, F are deferred to step 6
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 1. Check Tool Availability and Validation Timing
 
@@ -27,30 +35,40 @@ Run: `npx skill-check -h`
 
 **Important:** Do not assume availability — empirical check required.
 
-**Validation timing note:** Step-04 section 6b has already written SKILL.md (and stack reference files) to disk. External-tool checks against written files (skill-check Checks A, E, F) still run in **step 6 section 7** to co-locate external-tool validation with post-write verification. Structural checks (B, C, D) run here against the merged content — content on disk is byte-identical to the in-context copy.
+**Validation timing note:** Step-04 section 6b has already written SKILL.md to disk. External-tool checks against written files (skill-check Checks A, E, F) still run in **step 6 section 7** to co-locate external-tool validation with post-write verification. Check D (Provenance Completeness) is deterministic but needs both `metadata.json` and `provenance-map.json` on disk — neither exists yet at this step — so it is deferred to **step 6 section 6a**, which runs it via the completeness helper against the freshly-written artifacts. Structural checks (B, C) run here against the merged content — content on disk is byte-identical to the in-context copy.
 
-### 2. Launch Parallel Validation Checks
+### 2. Run Validation Checks
 
-Launch subprocesses in parallel for each validation category, aggregating results when complete:
+Per the §1 timing note, only Check B (a single deterministic `manual-verify` script) and Check C (an in-prompt tier-label consistency check) run live at this step; Checks A, D, E, F are deferred to step 6. Run B then C in order — one script plus one in-prompt comparison have nothing to fan out.
 
 **Check A — Spec Compliance (deferred to post-write):**
 
 Skill-check requires written files on disk. This check is deferred to step 6 section 7. Perform manual structural check only: verify merged SKILL.md has required sections (exports, usage patterns, conventions), verify export entries have name/type/signature/file:line reference, flag missing sections.
 
 **Check B — [MANUAL] Section Integrity:**
-- Compare [MANUAL] inventory from step 01 against merged content
-- Verify every [MANUAL] block exists in merged result, byte-identical (zero modification)
-- Flag any [MANUAL] blocks moved, truncated, or missing
+
+Run the deterministic [MANUAL]-integrity verifier against the step-1 §5 inventory — do not eyeball byte-identity (a subtly truncated block reads as intact to the eye):
+
+```bash
+uv run {hashContentHelper} manual-verify {skill_package}/SKILL.md \
+    --inventory {manual_inventory}
+```
+
+Read the verdict JSON `{"preserved":[...], "modified":[...], "missing":[...], "moved":[...], "ok":bool}` (the on-disk SKILL.md is byte-identical to the merged in-context copy per the timing note above):
+- `ok == true` → status PASS. `preserved` blocks are byte-identical in place; any `moved` blocks are byte-identical but relocated with their logical parent section (report as informational, not a finding).
+- `modified` non-empty → FAIL: these blocks' byte-exact interiors changed (the truncation a marker-count/eyeball check would miss). List each by name.
+- `missing` non-empty → FAIL: these blocks lost their markers entirely. List each by name.
+
+Populate the §3 `manual_integrity` record from this verdict (`sections_verified` = inventory count, `sections_intact` = `len(preserved) + len(moved)`). This check is advisory here (findings inform, do not block); write.md §1 enforces the same `ok` verdict as a HALT gate before any derived artifact is written.
 
 **Check C — Confidence Tier Consistency:**
 - Verify all re-extracted exports have confidence labels (T1/T1-low/T2)
 - Verify tier labels match forge tier: Quick=T1-low only, Forge=T1 (T1-low for degraded), Forge+=T1 (same as Forge, CCC improves coverage not confidence), Deep=T1+T2
 - Flag mismatched or missing tier labels
 
-**Check D — Provenance Completeness:**
-- Verify every export has a provenance map entry with valid file:line references
-- Verify no stale references to old file paths or line numbers
-- Flag orphaned provenance entries (export removed but provenance remains)
+**Check D — Provenance Completeness (deferred to post-write):**
+
+The provenance map does not exist on disk until step 6 §3 writes it, and completeness is a deterministic set-diff (metadata `exports[]` vs provenance `entries[].export_name`) plus file:line citation resolution — not something to eyeball. This check is deferred to **step 6 section 6a**, which runs `skf-verify-provenance-completeness.py` against the just-written `metadata.json` and `provenance-map.json` and reads back `missing[]` / `orphaned[]` / `stale[]` findings. Do not attempt the set comparison here — there is no provenance map to compare against yet. The `Provenance` row in §5's summary is populated from §6a's result.
 
 **Check E — Diff Comparison (via skill-check):**
 
@@ -83,16 +101,6 @@ Validation Results:
   quality_score: [0-100]  # from skill-check, if available
 ```
 
-### 4. For Stack Skills — Validate Reference Files
-
-**ONLY if skill_type == "stack":**
-
-Repeat checks A-D for each reference file:
-- `references/{library}.md` — spec compliance and [MANUAL] integrity
-- `references/integrations/{pair}.md` — spec compliance and [MANUAL] integrity
-
-**If skill_type != "stack":** Skip with notice.
-
 ### 5. Display Validation Summary
 
 "**Validation Results:**
@@ -110,13 +118,7 @@ Repeat checks A-D for each reference file:
 
 **If findings exist:** List each with severity, description, and location. Add: "Validation is advisory. Findings do not block the update."
 
-### 6. Present MENU OPTIONS
-
-Display: "**Proceeding to write updated files...**"
-
-After validation summary is displayed, immediately load, read entire file, then execute {nextStepFile}. This is an auto-proceed step — validation is advisory, not blocking.
-
-## CRITICAL STEP COMPLETION NOTE
+### 6. Route to Next Step
 
-ONLY WHEN all validation checks have completed and findings are displayed will you load {nextStepFile} to write the updated files. Validation does NOT block — it informs.
+This step auto-proceeds — no user choices; validation is advisory and does not block, it only informs. Once all validation checks have completed and findings are displayed, display "**Proceeding to write updated files...**", then load, fully read, and execute `{nextStepFile}` to write the updated files.
 

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

@@ -17,6 +17,31 @@ descriptionGuardProbeOrder:
 updateActiveSymlinkProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-update-active-symlink.py'
   - '{project-root}/src/shared/scripts/skf-update-active-symlink.py'
+# Resolve `{verifyProvenanceCompletenessHelper}` to the first existing path.
+# §6a runs Check D (Provenance Completeness), deferred from step 5 because it
+# needs both metadata.json + provenance-map.json on disk: the export/provenance
+# set-diff (missing + orphaned entries) and file:line citation resolution.
+# Advisory — do not HALT if neither path resolves; fall back to the in-prose
+# set comparison §6a documents (graceful degradation).
+verifyProvenanceCompletenessProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-verify-provenance-completeness.py'
+  - '{project-root}/src/shared/scripts/skf-verify-provenance-completeness.py'
+# Resolve `{hashContentHelper}` to the first existing path; HALT if neither
+# candidate exists. §1 uses its `manual-verify` subcommand to verify the
+# post-merge file against the byte-exact [MANUAL] inventory captured in step 1
+# §5; a marker-count comparison would pass a block whose interior was truncated
+# without changing the marker count.
+hashContentProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
+  - '{project-root}/src/shared/scripts/skf-hash-content.py'
+# Resolve `{renderMetadataStatsHelper}` by probing `{renderMetadataStatsProbeOrder}`
+# in order (installed SKF module path first, src/ dev-checkout fallback); first
+# existing path wins. HALT if neither resolves — §2's `stats` block and
+# `confidence_distribution` are computed values that must not be hand-binned,
+# and this is the same helper sibling create-skill compiles them with.
+renderMetadataStatsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-render-metadata-stats.py'
+  - '{project-root}/src/shared/scripts/skf-render-metadata-stats.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -25,7 +50,7 @@ updateActiveSymlinkProbeOrder:
 
 ## STEP GOAL:
 
-Verify the merged SKILL.md and stack reference files that step 4 section 6b wrote to disk, then write the derived artifacts (metadata.json, provenance-map.json, evidence-report.md, context-snippet.md, and the active symlink).
+Verify the merged SKILL.md that step 4 section 6b wrote to disk, then write the derived artifacts (metadata.json, provenance-map.json, evidence-report.md, context-snippet.md, and the active symlink).
 
 ## Rules
 
@@ -34,7 +59,7 @@ Verify the merged SKILL.md and stack reference files that step 4 section 6b wrot
 - Do not skip provenance map update — critical for future audits
 - HALT immediately on verification failure before writing any derived artifact — a partial-write skill package is worse than an unchanged one
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 0. Description Guard Protocol
 
@@ -48,13 +73,19 @@ Update-skill does not run the optional post-restore frontmatter re-validation to
 
 SKILL.md was written in step 4 section 6b. Verify the write landed intact before proceeding to any derived-artifact writes.
 
-- Read `{skill_package}/SKILL.md` from disk
-- Count `<!-- [MANUAL:*] -->` opening markers and compare against the [MANUAL] inventory captured in step 1
 - Verify the resolved `{skill_package}` path matches the version directory step 4 wrote to (if the version changed, step 4 updated `{skill_package}` in context to point at the new path)
-- If [MANUAL] count matches and path resolves: proceed to section 2
-- **If [MANUAL] count does not match: HALT immediately.** Do not write `metadata.json`, `provenance-map.json`, or any other artifact — further writes would compound the inconsistency. Alert the user:
+- Run the deterministic [MANUAL]-integrity verifier against the byte-exact inventory captured in step 1 §5:
 
-  "**[MANUAL] section count mismatch after write.** Expected {N} from step 1 inventory, found {M} on disk at `{skill_package}/SKILL.md`. The skill package is in an inconsistent state. Manual recovery required — restore the previous version from `{skill_group}/{previous_version}/` or fix the file in place, then re-run update-skill."
+  ```bash
+  uv run {hashContentHelper} manual-verify {skill_package}/SKILL.md \
+      --inventory {manual_inventory}
+  ```
+
+  The verdict JSON is `{"preserved":[...], "modified":[...], "missing":[...], "moved":[...], "ok":bool}`. A `modified` block is one whose byte-exact interior changed (an interior truncation); a `missing` block lost its markers entirely; a `moved` block is byte-identical but relocated with its logical parent section (clean — does not fail the gate). `ok == (modified empty AND missing empty)`.
+- If `ok == true` and the path resolves: proceed to section 2
+- **If `ok == false`: HALT immediately** with status `halted-for-manual-mismatch`. Do not write `metadata.json`, `provenance-map.json`, or any other artifact — further writes would compound the inconsistency. In `{headless_mode}`, emit the halt envelope per SKILL.md §Headless (`error: {phase: "write:verify-manual-integrity", path: "{skill_package}/SKILL.md", reason: "..."}`). Alert the user:
+
+  "**[MANUAL] section integrity failure after write.** Blocks modified (interior changed): {modified}. Blocks missing (markers lost): {missing}. Relocated-but-intact (advisory only): {moved}. Verified against the step-1 inventory `{manual_inventory}`, on disk at `{skill_package}/SKILL.md`. The skill package is in an inconsistent state. Manual recovery required — restore the previous version from `{skill_group}/{previous_version}/` or fix the file in place, then re-run update-skill."
 
 ### 2. Write Updated metadata.json
 
@@ -64,22 +95,28 @@ Update `{skill_package}/metadata.json`:
 - Update `version`: **if `update_mode == "gap-driven"`, do not bump — the skill is being repaired against the same source commit, so leave `version` unchanged and update only `generation_date` / `last_update` below.** This keeps metadata `version` consistent with the on-disk `{skill_package}` path, which step 4 §6b also leaves unchanged in gap-driven mode (see step 4 §6b's "If the source version detected during step 3 differs..." carve-out — in gap-driven mode no source version is detected, so step 4 writes into the existing version directory). Otherwise, if a source version was detected during re-extraction and differs from the current metadata version, use the source version; otherwise increment patch version
 - Update `generation_date` timestamp to current ISO-8601 date
 - Update `exports` array to reflect current export list
-- Update `stats` from re-extraction results:
-  - `exports_documented`: count of exports with documentation in the merged skill
+- **Compute the `stats` block and `confidence_distribution` deterministically** with `{renderMetadataStatsHelper}` (resolve from `{renderMetadataStatsProbeOrder}`; first existing path wins) — the same helper sibling create-skill compiles them with, so create and update emit byte-identical stats for identical inputs. The helper owns all the arithmetic: it bins each provenance `entries[]` row once by its `signature_source` tier into `confidence_distribution.{t1,t1_low,t2,t3}`, sets `exports_documented` = the entry count, and derives `exports_total` = `exports_public_api` + `exports_internal`, `public_api_coverage` = documented / public_api (`null` if public_api is 0), `total_coverage` = documented / total (`null` if total is 0), plus `scripts_count` / `assets_count` from the inventory arrays. Run `uv run {renderMetadataStatsHelper} --help` for the full contract. Do not hand-bin the distribution — binning T2 annotations + T3 doc items on top of the per-export tiers double-counts, which per-entry binning by `signature_source` makes structurally impossible. You supply only the judgment payload:
+
+  **Judgment payload (what you decide — passed as JSON on stdin):**
   - `exports_public_api`: count of exports from public entry points (`__init__.py`, `index.ts`, `lib.rs`, or equivalent)
   - `exports_internal`: count of all other non-underscore-prefixed exports
-  - `exports_total`: `exports_public_api` + `exports_internal`
-  - `public_api_coverage`: `exports_documented / exports_public_api` (`null` if `exports_public_api` is 0)
-  - `total_coverage`: `exports_documented / exports_total` (`null` if `exports_total` is 0)
-- Update `confidence_distribution` from re-extraction results:
-  - `confidence_distribution.t1`, `confidence_distribution.t1_low`, `confidence_distribution.t2`, `confidence_distribution.t3`: update counts from re-extraction results
-  - `scripts_count`, `assets_count`: update from re-extraction results if scripts/assets changed
-- For stack skills: update `library_count`, `integration_count` if changed
+  - `scripts` / `assets`: the scripts / assets inventory arrays (or `[]` when empty) — the helper sets `scripts_count` / `assets_count` from their lengths
+
+  **Invoke** — since the helper reads `entries[]`, stage §3's `provenance-map.json` write first (§3 does not depend on these stats):
+
+  ```bash
+  echo '{"exports_public_api": {N}, "exports_internal": {M}, "scripts": {scripts-inventory-or-[]}, "assets": {assets-inventory-or-[]}}' \
+    | uv run {renderMetadataStatsHelper} {forge_version}/provenance-map.json
+  ```
+
+  Write the returned `stats` and `confidence_distribution` objects into `metadata.json` **verbatim**. If the helper reports `coherence.ok: false`, some provenance entries carry a missing/unrecognized `signature_source` (§3 must write it on every entry) — fix the provenance map, do not hand-edit the stats.
 
 ### 3. Write Updated provenance-map.json
 
 Write to `{forge_version}/provenance-map.json`:
 
+**Every entry this step writes or rewrites carries a `signature_source` (`T1` / `T1-low` / `T2` / `T3`)** — the tier that contributed the structural signature, matching create-skill's entry contract. §2's stats helper bins each entry on this field, so a missing value trips its `coherence.ok: false` check. Preserve it byte-identical on untouched entries; set it from the contributing extraction tier on every re-extracted or new entry.
+
 **If `no_reextraction == true` (gap-driven mode from step 3 section 0):**
 Dispatch per-entry on the verification outcome recorded by step 3 — gap-driven runs produce a mix of `verified`, `moved`, `re-extracted`, and `unknown` outcomes, and each requires a different provenance-map write strategy:
 
@@ -122,6 +159,8 @@ Dispatch per-entry on the verification outcome recorded by step 3 — gap-driven
 }
 ```
 
+`manual_sections_preserved` = `len(preserved) + len(moved)` from the §1 `manual-verify` verdict (blocks that survived byte-identical, whether in place or relocated). Do not re-count markers by hand — the §1 verdict is the deterministic source.
+
 ### 4. Write Updated evidence-report.md
 
 Append update operation section to `{forge_version}/evidence-report.md` (create the file with a standard header if it does not yet exist):
@@ -168,18 +207,9 @@ Append update operation section to `{forge_version}/evidence-report.md` (create
 
 **Context Snippet population** (used by §5 after the staleness check runs): §4 writes the sub-block with placeholders; §5 updates the on-disk evidence report in place after deciding whether to regenerate. Set `Regenerated: true` and populate `Triggers fired` with any combination of `headline-exports`, `version`, `gotchas` when at least one trigger fired. Set `Regenerated: false` and `Triggers fired: —` when none fired (the gap-driven / internals-only outcome). Always fill `Notes` with a one-sentence reason (e.g., `"Gap-driven repair — no snippet surface changed"`, `"Version bumped 0.1.0 → 0.2.0; headline exports re-ranked"`).
 
-### 5. Verify Stack Skill Reference File Writes (Conditional) and Regenerate context-snippet.md
+### 5. Regenerate context-snippet.md
 
-**ONLY if skill_type == "stack":**
-
-Stack reference files were written in step 4 section 6b. Verify each affected reference file that the merge produced:
-
-- Read each `references/{library}.md` back from disk
-- Read each `references/integrations/{pair}.md` back from disk
-- Verify per-file [MANUAL] section counts match the per-file inventory captured in step 1
-- **If any verification fails: HALT** using the same recovery protocol as section 1 — do not regenerate `context-snippet.md` or write any further derived artifact
-
-**For all skills (both single and stack) — regenerate `context-snippet.md` if stale:**
+**Regenerate `context-snippet.md` if stale:**
 
 `context-snippet.md` is a `{skill_package}` deliverable that goes stale whenever **headline exports**, **version**, or **gotchas** change in this run. Regenerate it only when at least one of these triggers fired; otherwise skip — a skip is the correct outcome for gap-driven repairs and other runs that touch internals below the snippet's surface, where regenerating would produce byte-identical content.
 
@@ -193,10 +223,7 @@ Stack reference files were written in step 4 section 6b. Verify each affected re
 
 **If no trigger fired:** skip regeneration — do not touch `context-snippet.md` on disk. The snippet remains valid against the prior run's surface. Continue to §5b.
 
-**If at least one trigger fired:** regenerate the snippet using the format from the matching template file:
-
-- For single skills: `skf-create-skill/assets/skill-sections.md` (pipe-delimited indexed format)
-- For stack skills: `skf-create-stack-skill/assets/stack-skill-template.md`
+**If at least one trigger fired:** regenerate the snippet using the format from `skf-create-skill/assets/skill-sections.md` (pipe-delimited indexed format).
 
 Use the **flat draft form** for the `root:` path in the draft snippet: `root: skills/{skill-name}/`. The per-IDE skill root (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/` — see `skf-export-skill/assets/managed-section-format.md`) is applied later by `export-skill` step 3 when the skill is exported. Do not choose an IDE-specific prefix in update-skill — that is an export-time decision that depends on config.yaml.
 
@@ -204,8 +231,6 @@ Pull values for the regenerated snippet from the updated metadata.json (version,
 
 Write the regenerated snippet to `{skill_package}/context-snippet.md`, preserving file permissions.
 
-**If skill_type == "stack"**, also verify that the reference file updates from the first half of this section have been applied before writing the snippet so the stack snippet reflects the newest integration list.
-
 ### 5b. Update Active Symlink
 
 Flip `{skill_group}/active` to point at the current `{version}` via the helper. The call is **always** run — atomic, idempotent, and verified in one shot. The helper's no-op path handles the "version did not change" case (gap-driven mode, or no source drift) without writing to disk:
@@ -225,9 +250,11 @@ The helper emits a result envelope with `status` ∈ `{ok, flipped, mismatch, mi
 - **`missing-target`** (exit 2): `{skill_group}/{version}/` directory does not exist on disk. HALT — display `halt_message` verbatim. This indicates §4 §6b did not write the version directory before §5b ran (a workflow bug, not a user error).
 - **`mismatch`** (exit 2): re-read after flip showed the symlink still points elsewhere. HALT — display `halt_message`. Should be impossible because the helper uses `os.replace` (atomic rename); a mismatch here indicates filesystem-level interference (concurrent writer, broken FUSE mount).
 
+Both exit-2 halts carry status `halted-for-write-failure`; in `{headless_mode}`, emit the halt envelope per SKILL.md §Headless (`error: {phase: "write:active-symlink", reason: "..."}`).
+
 ### 6. Verify Derived Artifact Writes
 
-SKILL.md was verified in section 1 and stack reference files in section 5 (both written by step 4 section 6b). This section verifies the artifacts this step wrote: `metadata.json`, `provenance-map.json`, `evidence-report.md`, `context-snippet.md`, and the `active` symlink from §5b.
+SKILL.md was verified in section 1 (written by step 4 section 6b). This section verifies the artifacts this step wrote: `metadata.json`, `provenance-map.json`, `evidence-report.md`, `context-snippet.md`, and the `active` symlink from §5b.
 
 For each derived artifact:
 - Read back the file
@@ -246,12 +273,33 @@ For each derived artifact:
 | evidence-report.md | {VERIFIED/FAILED} |
 | context-snippet.md | {VERIFIED/FAILED} |
 | {skill_group}/active symlink | {VERIFIED/FAILED} (readlink → {resolved_version}, expected {version}) |
-| {stack reference files...} | {VERIFIED in section 5} |
 
-**On symlink `mismatch` (helper exit 2):** HALT. Do not proceed to §7 post-write validation or §8 menu. Display the helper's `halt_message` verbatim — it already includes the diverged target, the expected version, and the recovery command. This matches the severity of the other four artifact checks — silent divergence here mis-routes any downstream consumer that uses the symlink fallback.
+**On symlink `mismatch` (helper exit 2):** HALT with status `halted-for-write-failure`. Do not proceed to §7 post-write validation or §8 menu. Display the helper's `halt_message` verbatim — it already includes the diverged target, the expected version, and the recovery command; in `{headless_mode}`, emit the halt envelope per SKILL.md §Headless (`error: {phase: "write:verify-active-symlink", reason: "..."}`). This matches the severity of the other four artifact checks — silent divergence here mis-routes any downstream consumer that uses the symlink fallback.
 
 **All files written and verified.**"
 
+### 6a. Provenance Completeness (Check D — Deferred from Step 05)
+
+`validate.md` Check D (Provenance Completeness) is a deterministic set-diff plus citation resolution, and it needs both `metadata.json` (written in §2) and `provenance-map.json` (written in §3) on disk — neither exists at validate time, so the check is deferred here. Run it against the just-written artifacts via `{verifyProvenanceCompletenessHelper}`:
+
+```bash
+uv run {verifyProvenanceCompletenessHelper} verify \
+    --metadata {skill_package}/metadata.json \
+    --provenance {forge_version}/provenance-map.json \
+    --source-root {source_root}
+```
+
+The helper reads its `--source-root` (falling back to the provenance map's own `source_root` field when the flag is omitted); pass the resolved `{source_root}` so citation resolution runs against the same tree re-extraction read. **Read the emitted JSON — do NOT recompute the set operations by eye; an LLM set-diff can silently pass a dropped or orphaned entry:**
+
+- `missing[]` — documented exports (metadata `exports[]`) with no provenance entry: a coverage gap.
+- `orphaned[]` — provenance `entries[].export_name` whose export was removed but the entry remains.
+- `stale[]` — entries whose `source_file:source_line` no longer resolves; each carries a `reason` of `file-missing`, `line-out-of-bounds`, or `line-invalid`. Internal names are canonicalized through `reexport_map` before the diff, so a barrel-renamed export does not read as missing or orphaned.
+- `summary.stale_check` — `"checked"` when citations were resolved against the source tree, or `"skipped-no-source-root"` when no source root resolved on disk (the completeness + orphan diffs still ran; `stale` is empty by construction, not clean-by-verification).
+
+Map `status` to the `Provenance:` line of the §4 evidence report's Validation Summary: `PASS` when `status == "pass"`, `WARN` when `status == "findings"` (this is the persistent record — step 5 §5's table was rendered before the provenance map existed, so it necessarily showed this row as deferred). Provenance findings are **advisory** — they do not block the update. Surface each `missing` / `orphaned` / `stale` entry in the evidence report's Validation Summary so the user can decide, and note when `stale_check` was `skipped-no-source-root`.
+
+**Graceful degradation:** if neither probe path resolves (no `uv` / script available), fall back to the manual set comparison the script encapsulates — enumerate metadata `exports[]` and provenance `entries[].export_name` (canonicalizing internal names through `reexport_map`), diff the two sets for missing/orphaned entries, and spot-check that each `source_file:source_line` still points at a real line in the source tree. Prefer the script — it does this deterministically.
+
 ### 7. Run Post-Write Validation (Deferred from Step 05)
 
 External tool checks deferred from step 5 now run against the written files.
@@ -284,20 +332,7 @@ Record findings in the evidence report (section 4), including any `description_g
 
 **If skill-check unavailable:** Skip with note — structural checks from step 5 are sufficient.
 
-### 8. Present MENU OPTIONS
-
-Display: "**Proceeding to report...**"
-
-#### Menu Handling Logic:
-
-- After all writes verified and post-write validation complete, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Proceed directly to report after verification
-
-## CRITICAL STEP COMPLETION NOTE
+### 8. Route to Next Step
 
-ONLY WHEN all files have been written and verified will you load {nextStepFile} to display the change report.
+This step auto-proceeds — no user choices. Once all files have been written and verified and post-write validation is complete, display "**Proceeding to report...**", then load, fully read, and execute `{nextStepFile}` to display the change report.