bmad-module-skill-forge 1.4.1 → 1.5.0

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

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-06-write.md'
+nextStepFile: 'write.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 5: Validate
 
 ## STEP GOAL:
@@ -16,8 +18,6 @@ Validate the merged skill content against the agentskills.io specification, veri
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Check Tool Availability and Validation Timing
 
 Run: `npx skill-check -h`
@@ -27,7 +27,7 @@ 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-06 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 (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.
 
 ### 2. Launch Parallel Validation Checks
 
@@ -35,7 +35,7 @@ Launch subprocesses in parallel for each validation category, aggregating result
 
 **Check A — Spec Compliance (deferred to post-write):**
 
-Skill-check requires written files on disk. This check is deferred to step-06 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.
+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

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

@@ -1,64 +1,65 @@
 ---
-nextStepFile: './step-07-report.md'
+nextStepFile: 'report.md'
+descriptionGuardProtocol: '{project-root}/src/shared/references/description-guard-protocol.md'
+# Resolve `{descriptionGuardHelper}` by probing `{descriptionGuardProbeOrder}`
+# in order (installed SKF module path first, src/ dev-checkout fallback);
+# first existing path wins. HALT if neither resolves — letting an external
+# tool's rewrite of the merged description field stand would silently
+# regress discovery quality and re-introduce angle-bracket tokens.
+descriptionGuardProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-description-guard.py'
+  - '{project-root}/src/shared/scripts/skf-description-guard.py'
+# Resolve `{updateActiveSymlinkHelper}` to the first existing path; HALT if
+# neither candidate exists. §5b uses it to atomically flip the active
+# symlink; §6 uses it (verify mode) to confirm the post-state. Without
+# the helper, §5b's "rm and recreate" pattern leaves a brief window where
+# concurrent readers see a missing symlink.
+updateActiveSymlinkProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-update-active-symlink.py'
+  - '{project-root}/src/shared/scripts/skf-update-active-symlink.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 6: Write Updated Files
 
 ## STEP GOAL:
 
-Verify the merged SKILL.md and stack reference files that step-04 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 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).
 
 ## Rules
 
-- Focus only on verifying merged files and writing derived artifacts — merge content was already written in step-04
+- Focus only on verifying merged files and writing derived artifacts — merge content was already written in step 4
 - Do not modify merged SKILL.md content — any mismatch detected during verification triggers HALT, not repair
 - 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
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 0. Description Guard Protocol
 
 **Used by:** §7 (`skill-check check --fix` and `skill-check split-body --write`), and any future tool invocation that may modify SKILL.md's frontmatter on disk.
 
-External validators occasionally rewrite the frontmatter `description` field — `skill-check --fix` may replace it with a generic or truncated version, and `split-body` may touch it during mechanical restructuring. The merged description written to disk in step-04 is **authoritative**: it reflects the final merge of the prior skill's description (with any author edits preserved) and fresh re-extraction results. Losing it to a tool's well-meaning rewrite breaks discovery quality and — if the prior skill was compiled from a sanitized description (step-05 §2a) — can re-introduce angle-bracket tokens that then fail tessl on the next run.
-
-To prevent this, any tool invocation in §7 that may touch SKILL.md must run inside the following four-phase guard:
-
-1. **Capture.** Before invoking the tool, read `{skill_package}/SKILL.md` frontmatter and snapshot the exact `description` value into a local variable (e.g., `guarded_description`). Capture the in-context copy as well.
-2. **Execute.** Run the tool as specified in its section.
-3. **Verify.** After the tool completes, re-read the on-disk SKILL.md and compare its frontmatter `description` against `guarded_description`. Normalize whitespace for comparison (trim leading/trailing whitespace, collapse internal runs) but do not ignore content differences.
-4. **Restore on divergence.** If the post-tool description differs from `guarded_description` in any way other than whitespace normalization, write `guarded_description` back to the on-disk SKILL.md frontmatter and update the in-context copy to match. Record `description_guard_restored: true` with the tool name in context for the evidence report.
+Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — §7 invokes the helper at the capture and verify-restore points around every `skill-check` call.
 
-**What counts as divergence:**
-
-- The description was replaced (different content).
-- The description was truncated (suffix missing).
-- Angle-bracket tokens were re-introduced (should never happen if the prior skill was correctly sanitized, but protect anyway).
-- The field was deleted entirely (extreme tool behavior).
-
-**What does NOT count as divergence:** whitespace-only differences (trailing newline, trimmed spaces) — treat as equivalent.
-
-**Why this lives in update-skill too:** the guard protocol was first introduced in `skf-create-skill/step-06-validate.md §0` to defend the freshly-compiled description. Update-skill runs the identical `skill-check check --fix` command against the merged skill package in §7, so it faces the same risk and needs the same defense. Keep the two §0 protocols functionally identical — if external tool behavior changes, update both workflows.
+Update-skill does not run the optional post-restore frontmatter re-validation today — the post-write checks in §1 catch downstream issues, and a `restored: true` outcome is already surfaced through the evidence report (§4).
 
 ### 1. Verify SKILL.md Write
 
-SKILL.md was written in step-04 section 6b. Verify the write landed intact before proceeding to any derived-artifact writes.
+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-01
-- Verify the resolved `{skill_package}` path matches the version directory step-04 wrote to (if the version changed, step-04 updated `{skill_package}` in context to point at the new path)
+- 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:
 
-  "**[MANUAL] section count mismatch after write.** Expected {N} from step-01 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."
+  "**[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."
 
 ### 2. Write Updated metadata.json
 
 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-04 §6b also leaves unchanged in gap-driven mode (see step-04 §6b's "If the source version detected during step-03 differs..." carve-out — in gap-driven mode no source version is detected, so step-04 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 `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:
@@ -77,13 +78,13 @@ Update `{skill_package}/metadata.json`:
 
 Write to `{forge_version}/provenance-map.json`:
 
-**If `no_reextraction == true` (gap-driven mode from step-03 section 0):**
-Dispatch per-entry on the verification outcome recorded by step-03 — gap-driven runs produce a mix of `verified`, `moved`, `re-extracted`, and `unknown` outcomes, and each requires a different provenance-map write strategy:
+**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:
 
 - **`verified` exports**: no fresh extraction data exists — do NOT overwrite `confidence`, `extraction_method`, `ast_node_type`, `params[]`, `return_type`, `source_file`, or `source_line`. The provenance entry stays byte-identical.
 - **`moved` exports**: update `source_line` (and `source_file` if different) to the new location recorded by the spot-check. Do not touch other fields.
-- **`re-extracted` exports** (resolved via step-03 §0a's Targeted Re-Extraction Branch from `remediation_paths[]`): write a full entry — `source_file`, `source_line`, `confidence`, `extraction_method`, `ast_node_type`, `params[]`, `return_type` — from §0a's fresh AST extraction record. This is the only gap-driven outcome that produces normal-mode-quality provenance; do NOT fall through to the byte-identical preservation above.
-- **`unknown` exports** (not in provenance map; no `source_citation`; `severity` is `Medium`, `Low`, or `Info`, OR `remediation_paths[]` was empty and §0a did not halt): add new entries with fields populated from step-04 merge output. `source_file`/`source_line` may be `null` here — leave these fields unset rather than writing stale values. **This path is only acceptable for `severity` in `Medium`, `Low`, or `Info`.** A Critical/High `unknown` reaching this branch indicates step-03 §0a was skipped or bypassed and is a workflow bug — step-03 §0a should have halted with status `halted-for-remediation-path` before step-06 ran. If you encounter one, halt with a pointer to §0a rather than writing null citations for a blocking gap.
+- **`re-extracted` exports** (resolved via step 3 §0a's Targeted Re-Extraction Branch from `remediation_paths[]`): write a full entry — `source_file`, `source_line`, `confidence`, `extraction_method`, `ast_node_type`, `params[]`, `return_type` — from §0a's fresh AST extraction record. This is the only gap-driven outcome that produces normal-mode-quality provenance; do NOT fall through to the byte-identical preservation above.
+- **`unknown` exports** (not in provenance map; no `source_citation`; `severity` is `Medium`, `Low`, or `Info`, OR `remediation_paths[]` was empty and §0a did not halt): add new entries with fields populated from step 4 merge output. `source_file`/`source_line` may be `null` here — leave these fields unset rather than writing stale values. **This path is only acceptable for `severity` in `Medium`, `Low`, or `Info`.** A Critical/High `unknown` reaching this branch indicates step 3 §0a was skipped or bypassed and is a workflow bug — step 3 §0a should have halted with status `halted-for-remediation-path` before step 6 ran. If you encounter one, halt with a pointer to §0a rather than writing null citations for a blocking gap.
 - Skip the "For each export in the updated skill" bullets below — they apply only to normal re-extraction mode.
 
 **For each export in the updated skill (normal mode only):**
@@ -160,7 +161,7 @@ Append update operation section to `{forge_version}/evidence-report.md` (create
 - Notes: {one-sentence detail or —}
 ```
 
-**Description Guard population** (used by §7 Post-Write Validation when the §0 protocol fires): fill all four fields from context when `description_guard_restored == true` (triggering tool, whether restore succeeded, what changed). When `Restored: false`, the other three fields are `—` — this is the clean-run expected state. Same field semantics and populator logic as create-skill step-06 §8.
+**Description Guard population** (used by §7 Post-Write Validation when the §0 protocol fires): fill all four fields from context when `description_guard_restored == true` (triggering tool, whether restore succeeded, what changed). When `Restored: false`, the other three fields are `—` — this is the clean-run expected state. Same field semantics and populator logic as create-skill step 6 §8.
 
 **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"`).
 
@@ -168,11 +169,11 @@ Append update operation section to `{forge_version}/evidence-report.md` (create
 
 **ONLY if skill_type == "stack":**
 
-Stack reference files were written in step-04 section 6b. Verify each affected reference file that the merge produced:
+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-01
+- 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:**
@@ -194,36 +195,43 @@ Stack reference files were written in step-04 section 6b. Verify each affected r
 - 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`
 
-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-03 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.
+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.
 
-Pull values for the regenerated snippet from the updated metadata.json (version, top exports), the merged SKILL.md (section anchors, inline summaries), and the evidence report (new gotchas). If gotchas cannot be derived from the updated evidence but the prior snippet has a `|gotchas:` line, carry forward the prior line with the `[CARRIED]` marker — see `skf-export-skill/steps-c/step-03-generate-snippet.md` for the carry-forward protocol (one-cycle limit).
+Pull values for the regenerated snippet from the updated metadata.json (version, top exports), the merged SKILL.md (section anchors, inline summaries), and the evidence report (new gotchas). If gotchas cannot be derived from the updated evidence but the prior snippet has a `|gotchas:` line, carry forward the prior line with the `[CARRIED]` marker — see `skf-export-skill/references/generate-snippet.md` for the carry-forward protocol (one-cycle limit).
 
 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 (If Version Changed)
+### 5b. Update Active Symlink
 
-If the version was incremented or changed in section 2 (metadata.json update):
-- Create or update the `active` symlink at `{skill_group}/active` pointing to the new `{version}`
-- If the symlink already exists, remove it first and recreate
+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:
 
-```
-{skill_group}/active -> {version}
+```bash
+uv run {updateActiveSymlinkHelper} update \
+    --skill-group {skill_group} \
+    --version {version}
 ```
 
-If the version did not change, the existing symlink already points to the correct version -- no action needed.
+The helper emits a result envelope with `status` ∈ `{ok, flipped, mismatch, missing-target}` and a pre-formatted `log_message`. Log the message to the evidence report.
+
+**Dispatch on `status`:**
+
+- **`ok`** (exit 0): symlink already points at `{version}` — no disk write. Continue to §6.
+- **`flipped`** (exit 0): symlink was atomically updated (temp-and-replace). Continue to §6.
+- **`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).
 
 ### 6. Verify Derived Artifact Writes
 
-SKILL.md was verified in section 1 and stack reference files in section 5 (both written by step-04 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 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.
 
 For each derived artifact:
 - Read back the file
 - Confirm content matches expected output
 - Report verification status
 
-**Active symlink verification:** resolve `readlink({skill_group}/active)` and assert it equals the `version` just written to `metadata.json` in §2. This closes the §5b gap where a silent skip would otherwise leave the manifest and symlink divergent — the symlink is the fallback resolver for consumers that don't read the manifest (see `knowledge/version-paths.md` §Reading Workflows step 5), so a mismatch must fail the step, not warn. Applies in every mode — gap-driven runs do not bump `version`, but the symlink must still point to the current `version`, otherwise a prior partial run left it pointing elsewhere.
+**Active symlink verification:** run `{updateActiveSymlinkHelper} verify --skill-group {skill_group} --version {version}` — read-only check that the symlink resolves to the version just written to `metadata.json` in §2. This closes the §5b gap where a silent skip would otherwise leave the manifest and symlink divergent — the symlink is the fallback resolver for consumers that don't read the manifest (see `knowledge/version-paths.md` §Reading Workflows step 5), so a `mismatch` must fail the step, not warn. Applies in every mode — gap-driven runs do not bump `version`, but the symlink must still point to the current `version`, otherwise a prior partial run left it pointing elsewhere.
 
 "**Write Verification:**
 
@@ -237,27 +245,41 @@ For each derived artifact:
 | {skill_group}/active symlink | {VERIFIED/FAILED} (readlink → {resolved_version}, expected {version}) |
 | {stack reference files...} | {VERIFIED in section 5} |
 
-**On symlink FAILED:** HALT. Do not proceed to §7 post-write validation or §8 menu. Alert the user: "**Active symlink divergence.** `{skill_group}/active` resolves to `{resolved_version}` but `metadata.json` reports `version: {version}`. §5b did not apply. Re-point the symlink manually (`ln -sfn {version} {skill_group}/active`) or re-run update-skill, then re-verify." 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. 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.
 
 **All files written and verified.**"
 
 ### 7. Run Post-Write Validation (Deferred from Step 05)
 
-External tool checks deferred from step-05 now run against the written files.
+External tool checks deferred from step 5 now run against the written files.
+
+**Description Guard Protocol:** every invocation below that may modify SKILL.md (`skill-check check --fix` and any `split-body` write) must run inside the four-phase guard defined in §0. Invoke `{descriptionGuardHelper}` at the capture and verify-restore points around each call:
+
+```bash
+# Phase 1 — capture before any frontmatter-touching tool call
+uv run {descriptionGuardHelper} capture {skill_package}/SKILL.md
+# stash returned `description` as `guarded_description`
+
+# Phase 2 — run the tool (skill-check --fix, split-body --write, etc.)
+
+# Phases 3+4 — verify and restore after the tool call
+uv run {descriptionGuardHelper} verify-restore {skill_package}/SKILL.md \
+    --captured-description "{guarded_description}"
+```
 
-**Description Guard Protocol:** every invocation below that may modify SKILL.md (`skill-check check --fix` and any `split-body` write) must run inside the four-phase guard defined in §0. Capture `guarded_description` before each call, execute, verify against the post-tool description, and restore on divergence. Do not rely on per-call ad-hoc preservation logic — use the §0 protocol.
+Do not rely on per-call ad-hoc preservation logic — use the helper.
 
 **If skill-check available:**
 
 - Run: `npx skill-check check {skill_package} --fix --format json --no-security-scan` **inside the §0 guard**.
-- **Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. This prevents silent divergence between the in-context SKILL.md and the on-disk version that step-07-report will reference. The §0 guard has already restored `description` if divergent; the re-read picks up any other fix-corrected content.
+- **Context sync after --fix:** If `fixed[]` is non-empty (i.e., `--fix` modified files on disk), re-read the modified SKILL.md to update the in-context copy. This prevents silent divergence between the in-context SKILL.md and the on-disk version that report will reference. The §0 guard has already restored `description` if divergent; the re-read picks up any other fix-corrected content.
 - If `body.max_lines` reported, prefer selective split — extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). **If falling back to `npx skill-check split-body {skill_package} --write`, run it inside the §0 guard** — split-body can also touch frontmatter. Verify anchors resolve after split.
 - Run: `npx skill-check diff` if original version was preserved.
 - Run: `npx skill-check check {skill_package} --format json` for security scan. (Read-only; guard not required.)
 
 Record findings in the evidence report (section 4), including any `description_guard_restored` events recorded by the §0 protocol. These are advisory — do not block on warnings.
 
-**If skill-check unavailable:** Skip with note — structural checks from step-05 are sufficient.
+**If skill-check unavailable:** Skip with note — structural checks from step 5 are sufficient.
 
 ### 8. Present MENU OPTIONS
 

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

@@ -11,6 +11,14 @@ Cross-references generated skills against architecture and PRD documents to prod
 
 **Schema contract:** This skill is the PRODUCER of the feasibility report schema defined in `src/shared/references/feasibility-report-schema.md`. 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.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
 ## Role
 
 You are a stack feasibility analyst and integration verifier operating in Ferris Audit mode. You bring expertise in API surface analysis, cross-library compatibility assessment, and architecture validation, while the user brings their architecture vision and generated skills.
@@ -21,40 +29,104 @@ These rules apply to every step in this workflow:
 
 - Read-only — never modify skills, architecture docs, or PRD files
 - Every verdict must cite evidence from the generated skills
-- Read each step file completely before taking any action
-- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
 - If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
 - Always communicate in `{communication_language}`
+- At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Initialize & Load Inputs | steps-c/step-01-init.md | No (confirm) |
-| 2 | Coverage Analysis | steps-c/step-02-coverage.md | Yes |
-| 3 | Integration Verification | steps-c/step-03-integrations.md | Yes |
-| 4 | Requirements Mapping | steps-c/step-04-requirements.md | Yes |
-| 5 | Synthesize Verdict | steps-c/step-05-synthesize.md | Yes |
-| 6 | Report | steps-c/step-06-report.md | No (confirm) |
-| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+| 1 | Initialize & Load Inputs | references/init.md | No (confirm) |
+| 2 | Coverage Analysis | references/coverage.md | Yes |
+| 3 | Integration Verification | references/integrations.md | Yes |
+| 4 | Requirements Mapping | references/requirements.md | Yes |
+| 5 | Synthesize Verdict | references/synthesize.md | Yes |
+| 6 | Report | references/report.md | No (confirm) |
+| 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | architecture_doc_path [required], prd_path [optional] |
-| **Gates** | step-01: Input Gate [use args] | step-06: Confirm Gate [C] |
-| **Outputs** | `feasibility-report-{projectSlug}-{timestamp}.md` and `feasibility-report-{projectSlug}-latest.md` (copy, not symlink) per `src/shared/references/feasibility-report-schema.md` — with integration verdicts, coverage analysis, recommendations, and evidence sources |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **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] |
+| **Outputs** | `feasibility-report-{projectSlug}-{timestamp}.md` and `feasibility-report-{projectSlug}-latest.md` (copy, not symlink) per `src/shared/references/feasibility-report-schema.md` — 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) |
+
+## 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"`:
+
+```
+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`).
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
-   - `project_name`, `user_name`, `communication_language`
-   - `skills_output_folder`, `forge_data_folder`, `document_output_language`
+   - `project_name`, `user_name`, `communication_language`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+
+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.)
+
+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.
+
+4. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the four scalars, if the merged value is empty or absent, use the bundled default:
+
+   - `{reportTemplatePath}` ← `workflow.report_template_path` if non-empty, else `assets/feasibility-report-template.md`
+   - `{integrationRulesPath}` ← `workflow.integration_rules_path` if non-empty, else `references/integration-verification-rules.md`
+   - `{coveragePatternsPath}` ← `workflow.coverage_patterns_path` if non-empty, else `references/coverage-patterns.md`
+   - `{outputFolderPath}` ← `workflow.output_folder_path` if non-empty, else `{forge_data_folder}`
+
+   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.
+
+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
+   mkdir -p "{outputFolderPath}" && \
+     printf 'probe' > "{outputFolderPath}/.skf-write-probe" && \
+     rm "{outputFolderPath}/.skf-write-probe"
+   ```
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, emit the error envelope per **Result Contract (Headless)** with `report_path: null`, `report_latest_path: null`, `overall_verdict: null`.
 
-3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.
+6. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-verify-stack/assets/feasibility-report-template.md

@@ -49,13 +49,13 @@ deltaUnchanged: null
 
 ## Coverage Analysis
 
-<!-- Appended by step-02-coverage -->
+<!-- Appended by coverage -->
 
 ---
 
 ## Integration Verdicts
 
-<!-- Appended by step-03-integrations.
+<!-- Appended by integrations.
 Consumers grep for the `## Integration Verdicts` heading to locate the pair table.
 The table header is fixed and MUST be emitted exactly as shown below: -->
 
@@ -66,11 +66,11 @@ The table header is fixed and MUST be emitted exactly as shown below: -->
 
 ## Recommendations
 
-<!-- Appended by step-05-synthesize -->
+<!-- Appended by synthesize -->
 
 ---
 
 ## Evidence Sources
 
-<!-- Appended by step-05-synthesize — cite each skill's SKILL.md path, metadata_schema_version,
+<!-- Appended by synthesize — cite each skill's SKILL.md path, metadata_schema_version,
      confidence_tier, stack manifest (if any), and architecture/PRD doc paths -->

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

@@ -0,0 +1,50 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-verify-stack.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (auth, network,
+# compliance) that must precede any verification work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (verification standards, evidence-citation rules, house-style verdict
+# language). Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Verdict citations must include file:line spans."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/verify-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical asset paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default.
+
+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.
+
+output_folder_path = ""

package/src/skf-verify-stack/references/coverage-patterns.md

@@ -26,14 +26,14 @@ Parse document section headers for technology groupings:
 
 ### Coverage Verdict
 
-The coverage matrix renders two verdict tokens per referenced technology: **Covered** and **Missing**. Extra skills (skills present in the inventory but NOT referenced by the architecture document) are tracked in a separate informational subdivision — they are not coverage verdicts and do not appear in the primary `Technology → Skill Match → Verdict` column. See step-02 §4 for the Extra-skill subdivision output.
+The coverage matrix renders two verdict tokens per referenced technology: **Covered** and **Missing**. Extra skills (skills present in the inventory but NOT referenced by the architecture document) are tracked in a separate informational subdivision — they are not coverage verdicts and do not appear in the primary `Technology → Skill Match → Verdict` column. See step 2 §4 for the Extra-skill subdivision output.
 
 | Verdict     | Meaning                                                          |
 |-------------|------------------------------------------------------------------|
 | **Covered** | A generated skill exists in `skills/` for this technology        |
 | **Missing** | Technology is referenced in architecture doc but no skill exists |
 
-**Informational — Extra skills subdivision (not a verdict; rendered in a separate section per step-02 §4):**
+**Informational — Extra skills subdivision (not a verdict; rendered in a separate section per step 2 §4):**
 
 | Label                                  | Meaning                                                                                                                          |
 |----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|

package/src/skf-verify-stack/{steps-c/step-02-coverage.md → references/coverage.md}

@@ -1,12 +1,14 @@
 ---
-nextStepFile: './step-03-integrations.md'
-coveragePatternsData: 'references/coverage-patterns.md'
+nextStepFile: 'integrations.md'
+coveragePatternsData: '{coveragePatternsPath}'
 feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
 atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
-outputFile: '{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md'
-outputFileLatest: '{forge_data_folder}/feasibility-report-{project_slug}-latest.md'
+outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Append the Coverage Analysis section to the report in {document_output_language}. -->
+
 # Step 2: Technology Coverage Analysis
 
 ## STEP GOAL:
@@ -20,8 +22,6 @@ Verify that a generated skill exists for every technology, library, or framework
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Load Coverage Patterns
 
 Load `{coveragePatternsData}` for detection rules.
@@ -112,7 +112,7 @@ Write the **Coverage Analysis** section to `{outputFile}` (see `{feasibilitySche
 - Include coverage percentage
 - Include missing skill recommendations
 - Include the Extra (unreferenced) and Orphan (source_repo unresolvable) subdivisions from section 4
-- Update frontmatter: append `'step-02-coverage'` to `stepsCompleted`; set `coveragePercentage` (integer 0..100)
+- Update frontmatter: append `'coverage'` to `stepsCompleted`; set `coveragePercentage` (integer 0..100)
 - Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 7. Auto-Proceed to Next Step

package/src/skf-verify-stack/{steps-c/step-07-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
-# `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# Note: `shared/health-check.md` resolves relative to the SKF module root
+# ({project-root}/_bmad/skf/ when installed, {project-root}/src/ during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 6
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 
@@ -22,4 +24,4 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 Attempt to load `{nextStepFile}`.
 
 - **If `{nextStepFile}` loads successfully:** Read it fully, then execute it.
-- **If `{nextStepFile}` cannot be resolved or loaded** (e.g., running against a partial installation, module root not resolvable, or the file has been removed): log exactly `health-check unavailable at {path}` (substitute the attempted resolved path) to the user-visible output and exit the workflow cleanly. Do NOT HALT with an error — the health check is an optional self-improvement hook, and the feasibility report (written in step-06) is the authoritative workflow output. Exit cleanly so CI and headless runs do not fail on a missing optional hook.
+- **If `{nextStepFile}` cannot be resolved or loaded** (e.g., running against a partial installation, module root not resolvable, or the file has been removed): log exactly `health-check unavailable at {path}` (substitute the attempted resolved path) to the user-visible output and exit the workflow cleanly. Do NOT HALT with an error — the health check is an optional self-improvement hook, and the feasibility report (written in step 6) is the authoritative workflow output. Exit cleanly so CI and headless runs do not fail on a missing optional hook.