bmad-module-skill-forge 2.0.0 → 2.0.1

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.
 

package/src/skf-update-skill/scripts/skf-new-file-diff.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Deterministic NEW_FILE detection for skf-update-skill (detect-changes Category D).
+
+`skf-hash-content compare` classifies files already tracked in the provenance
+map (UNCHANGED / MODIFIED_FILE / DELETED_FILE) but by design cannot report a
+file that is present in source yet absent from the provenance map — a NEW_FILE.
+Deriving that set is a set-difference plus a filter with exactly one correct
+answer per input: take every `source_file` in the scripts/assets inventory
+(emitted by `skf-detect-scripts-assets detect`), subtract the paths already in
+`file_entries[].source_file`, and set aside any user-authored `[MANUAL]` path.
+Doing that subtraction in the prompt drifts across runs; doing it here is
+byte-stable.
+
+Usage:
+  skf-detect-scripts-assets.py detect <source-root> \
+    | skf-new-file-diff.py <provenance-map-path>
+
+Reads the detect JSON on stdin (needs `scripts_inventory[]` and
+`assets_inventory[]`, each row carrying `source_file`). Reads the provenance
+map at the path argument (canonical `{file_entries: [...]}` object, or a bare
+array of entries).
+
+Output JSON (stdout):
+  {
+    "new_files":       [ {"source_file": "...", "kind": "script|asset"}, ... ],
+    "skipped_manual":  [ "...", ... ],   # under scripts/[MANUAL]/ or assets/[MANUAL]/
+    "already_tracked": [ "...", ... ],   # present in file_entries
+    "stats": {"inventory_total": N, "new": N,
+              "skipped_manual": N, "already_tracked": N}
+  }
+
+All three arrays are sorted by source_file; new_files carries the kind of the
+inventory it came from (scripts -> "script", assets -> "asset"). A path found
+in both inventories is counted once, resolved as "script".
+
+Exit codes:
+  0  success
+  2  bad input (unreadable/invalid stdin JSON, missing/invalid provenance map)
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+# scripts/[MANUAL]/... or assets/[MANUAL]/... anywhere in the (posix) path
+_MANUAL_RE = re.compile(r"(?:^|/)(?:scripts|assets)/\[MANUAL\]/")
+
+
+def _fail(msg: str) -> "NoReturn":  # type: ignore[valid-type]
+    print(json.dumps({"error": msg}), file=sys.stderr)
+    sys.exit(2)
+
+
+def _posix(p: str) -> str:
+    return p.replace("\\", "/")
+
+
+def load_tracked_source_files(provenance_path: Path) -> set[str]:
+    """Return the set of file_entries[].source_file already in the provenance map."""
+    try:
+        data = json.loads(provenance_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        _fail(f"failed to read provenance map {provenance_path}: {exc}")
+
+    if isinstance(data, list):
+        entries = data
+    elif isinstance(data, dict):
+        entries = data.get("file_entries")
+        if entries is None:
+            _fail(f"provenance map {provenance_path} has no `file_entries` field")
+        if not isinstance(entries, list):
+            _fail(f"`file_entries` in {provenance_path} is not an array")
+    else:
+        _fail(
+            f"provenance map {provenance_path} must be an object or array; "
+            f"got {type(data).__name__}"
+        )
+
+    tracked: set[str] = set()
+    for entry in entries:
+        if isinstance(entry, dict):
+            sf = entry.get("source_file")
+            if isinstance(sf, str) and sf:
+                tracked.add(_posix(sf))
+    return tracked
+
+
+def collect_inventory(detect: dict) -> list[tuple[str, str]]:
+    """Return [(source_file, kind), ...] from the detect JSON, de-duplicated.
+
+    Scripts win over assets when a path appears in both, so kind is stable.
+    """
+    seen: dict[str, str] = {}
+    for key, kind in (("scripts_inventory", "script"), ("assets_inventory", "asset")):
+        rows = detect.get(key)
+        if rows is None:
+            continue
+        if not isinstance(rows, list):
+            _fail(f"`{key}` in detect JSON is not an array")
+        for row in rows:
+            if not isinstance(row, dict):
+                _fail(f"`{key}` entry is not an object: {row!r}")
+            sf = row.get("source_file")
+            if not isinstance(sf, str) or not sf:
+                _fail(f"`{key}` entry missing string `source_file`: {row!r}")
+            sf = _posix(sf)
+            seen.setdefault(sf, kind)  # first inventory wins the kind
+    return sorted(seen.items())
+
+
+def diff(detect: dict, tracked: set[str]) -> dict:
+    new_files: list[dict] = []
+    skipped_manual: list[str] = []
+    already_tracked: list[str] = []
+
+    inventory = collect_inventory(detect)
+    for sf, kind in inventory:
+        if sf in tracked:
+            already_tracked.append(sf)
+        elif _MANUAL_RE.search(sf):
+            skipped_manual.append(sf)
+        else:
+            new_files.append({"source_file": sf, "kind": kind})
+
+    return {
+        "new_files": new_files,
+        "skipped_manual": sorted(skipped_manual),
+        "already_tracked": sorted(already_tracked),
+        "stats": {
+            "inventory_total": len(inventory),
+            "new": len(new_files),
+            "skipped_manual": len(skipped_manual),
+            "already_tracked": len(already_tracked),
+        },
+    }
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        _fail("usage: skf-new-file-diff.py <provenance-map-path>  (detect JSON on stdin)")
+
+    provenance_path = Path(argv[1])
+    if not provenance_path.exists():
+        _fail(f"provenance map not found: {provenance_path}")
+
+    raw = sys.stdin.read()
+    if not raw.strip():
+        _fail("no detect JSON on stdin")
+    try:
+        detect = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        _fail(f"invalid detect JSON on stdin: {exc}")
+    if not isinstance(detect, dict):
+        _fail(f"detect JSON must be an object; got {type(detect).__name__}")
+
+    tracked = load_tracked_source_files(provenance_path)
+    result = diff(detect, tracked)
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/src/skf-verify-stack/SKILL.md

@@ -7,9 +7,9 @@ description: Pre-code stack feasibility verification against architecture and PR
 
 ## Overview
 
-Cross-references generated skills against architecture and PRD documents to produce a feasibility report with evidence-backed integration verdicts, coverage analysis, and requirements mapping. This is a read-only workflow — it never modifies skills or input documents, only reads and produces a feasibility report. Every verdict must cite specific APIs, types, or function signatures from the generated skills.
+Cross-references generated skills against architecture and PRD documents to produce a feasibility report with evidence-backed integration verdicts, coverage analysis, and requirements mapping. Read-only: it reads skills and input documents and writes only the feasibility report (see Workflow Rules).
 
-**Schema contract:** This skill is the PRODUCER of the feasibility report schema defined under the SKF shared references (`_bmad/skf/shared/references/feasibility-report-schema.md` in installed mode; `src/shared/references/feasibility-report-schema.md` in a dev checkout). All report outputs emit `schemaVersion: "1.0"` in frontmatter, use only the defined verdict tokens (`Verified|Plausible|Risky|Blocked` per pair; `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE` overall), follow the fixed section-heading order, and are written through `src/shared/scripts/skf-atomic-write.py write` to both the timestamped file and the stable `-latest.md` copy.
+**Schema contract:** This skill is the producer of the SKF shared feasibility report schema — every report conforms to it.
 
 ## Conventions
 
@@ -53,34 +53,20 @@ These rules apply to every step in this workflow:
 |--------|--------|
 | **Inputs** | architecture_doc_path [required], prd_path [optional], previous_report_path [optional] |
 | **Flags** | `--headless` / `-H` (auto-resolve all gates); `--architecture-doc <path>` (skip step 1 prompt for the required input); `--prd <path>` (skip step 1 prompt for the optional PRD); `--previous-report <path>` (skip step 1 prompt for delta comparison) |
-| **Gates** | step 1: Input Gate [use args] | step 6: Confirm Gate [C] |
+| **Gates** | step 1 Input Gate (use args); step 6 Report Menu ([R] review / [X] exit, headless default X). Steps 2-3 also hold elective vacuous-analysis guards (0% coverage, all-Blocked) that only fire in degenerate cases; every guard auto-resolves to Continue in headless. |
 | **Outputs** | `feasibility-report-{projectSlug}-{timestamp}.md` and `feasibility-report-{projectSlug}-latest.md` (copy, not symlink) per the SKF shared feasibility report schema (`_bmad/skf/shared/references/feasibility-report-schema.md`; `src/shared/references/…` in a dev checkout) — with integration verdicts, coverage analysis, recommendations, and evidence sources; plus `verify-stack-result-{timestamp}.json` and `verify-stack-result-latest.json` |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Per-flag args (`--architecture-doc`, `--prd`, `--previous-report`) consumed at the gates that would otherwise prompt. |
-| **Exit codes** | See "Exit Codes" below |
-
-## Exit Codes
-
-Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
-
-| Code | Meaning              | Raised by                                                                                    |
-| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
-| 0    | success              | step 7 (terminal)                                                                           |
-| 2    | input-missing / input-invalid | step 1 §1 (headless missing `architecture-doc` arg, or invalid path) → `input-missing`; non-existent file → `input-invalid` |
-| 3    | resolution-failure   | step 1 §2 (`{skills_output_folder}` does not exist or is empty); step 1 §3 (forge_data_folder unconfigured) |
-| 4    | write-failure        | On-Activation §3 pre-flight write probe; step 1 §4 (atomic write of report skeleton failed); step 6 §4b (result-contract write failed) |
-| 5    | state-conflict       | step 1 §3 (fewer than 2 valid skills found — stack requires ≥2); step 1 §1 (`previousReport` resolves to same inode as `{outputFile}`); step 6 §1 (report section order or schemaVersion mismatch — schema-violation) |
-| 6    | user-cancelled       | step 1 §1 prompt cancelled; any prompt that accepted `cancel`/`exit`/`:q`; step 6 menu cancelled |
-| 7    | inventory-unreliable | step 1 §2 (>20% subagent failures or enumerate-stack-skills warnings exceed budget) |
+| **Exit codes** | See `references/exit-codes.md` |
 
 ## Result Contract (Headless)
 
-When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every headless hard halt emits the same envelope shape on **stderr** with `status: "error"`:
 
 ```
 SKF_VERIFY_STACK_RESULT_JSON: {"status":"success|error","report_path":"…|null","report_latest_path":"…|null","overall_verdict":"…|null","coverage_percentage":0,"recommendation_count":0,"exit_code":0,"halt_reason":null}
 ```
 
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"skills-folder-missing"`, `"insufficient-skills"`, `"forge-folder-unconfigured"`, `"previous-report-collision"`, `"inventory-unreliable"`, `"schema-violation"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above. `overall_verdict` uses the schema tokens (`FEASIBLE`/`CONDITIONALLY_FEASIBLE`/`NOT_FEASIBLE`).
+`status` is `"success"` on the terminal happy path, `"error"` on any halt. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"skills-folder-missing"`, `"insufficient-skills"`, `"forge-folder-unconfigured"`, `"resolution-failure"`, `"previous-report-collision"`, `"inventory-unreliable"`, `"schema-violation"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches `references/exit-codes.md` (the `analysis-halted` / exit-8 gates are interactive-only, so they never reach this envelope). `overall_verdict` uses the schema tokens (`FEASIBLE`/`CONDITIONALLY_FEASIBLE`/`NOT_FEASIBLE`).
 
 ## On Activation
 
@@ -91,7 +77,7 @@ SKF_VERIFY_STACK_RESULT_JSON: {"status":"success|error","report_path":"…|null"
 2. **Compute run-scoped variables** (same place as config so every stage can reference them without re-derivation):
    - `project_slug` ← slugify `project_name` (lowercase, hyphens only, no unicode, no whitespace)
    - `timestamp` ← UTC `YYYYMMDD-HHmmss` captured at activation time
-   - These two combine in init.md §4 into `{outputFile}` per the stage frontmatter template, but the values themselves are fixed for the entire workflow run — every later reference to `{outputFile}` resolves consistently. (Computing them here resolves an order-of-operations bug where the §1 §3 inode-collision check referenced `{outputFile}` before `{project_slug}` and `{timestamp}` were defined.)
+   - These two combine in init.md §4 into `{outputFile}` per the stage frontmatter template, but the values themselves are fixed for the entire workflow run — every later reference to `{outputFile}` resolves consistently.
 
 3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
@@ -119,6 +105,10 @@ SKF_VERIFY_STACK_RESULT_JSON: {"status":"success|error","report_path":"…|null"
 
    Stash all four as workflow-context variables. Stage files reference them directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default.
 
+   The same merge resolves `workflow.on_complete` (default empty = no-op); report.md §5 executes it, if non-empty, at the terminal stage.
+
+   Also apply the array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries load their file/glob contents as facts — the bundled default glob is `{project-root}/**/project-context.md`); then execute each entry in `workflow.activation_steps_append` after activation completes.
+
 5. **Pre-flight write probe.** Verify `{outputFolderPath}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at init.md §4 atomic write — by then the user has already gone through the input prompts:
 
    ```bash

package/src/skf-verify-stack/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-verify-stack.
+# Team overrides:     _bmad/custom/skf-verify-stack.toml under {project-root}
+# Personal overrides: _bmad/custom/skf-verify-stack.user.toml under {project-root}
 
 [workflow]
 
@@ -34,6 +36,12 @@ persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
+# Instruction executed when the workflow reaches its terminal stage (after the
+# feasibility report + result JSON are written). Empty = no-op. Use to route
+# the verdict onward or trigger a downstream step without forking the skill.
+
+on_complete = ""
+
 # --- Optional asset overrides ---
 #
 # Lift the canonical asset paths so orgs can substitute house-style copies
@@ -43,8 +51,9 @@ report_template_path = ""
 integration_rules_path = ""
 coverage_patterns_path = ""
 
-# Override the destination directory for the feasibility report. Empty =
-# use {forge_data_folder} from config.yaml. Useful for orgs that want
-# verification artifacts to land outside the per-skill forge tree.
+# Override the destination directory for the feasibility report only. Empty =
+# use {forge_data_folder} from config.yaml. The result-contract JSON
+# (verify-stack-result-*.json) always stays in {forge_data_folder} as a stable
+# path for pipeline consumers, so redirecting this does not relocate it.
 
 output_folder_path = ""