bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-test-skill/scripts/verify-declared-numerator.py

@@ -1,24 +1,29 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # dependencies = []
 # ///
 """Deterministic numerator ground-truth verifier.
 
-Grep-and-count helper for the SKF test-skill workflow (coverage-check.md §4b
-"Numerator ground-truth"). It fires only on the inflation signature
-(`stats.exports_documented == effective_denominator` exactly): the numerator
-equals the denominator, the tell of a documented count padded to force 100%
-coverage. On that signature the declared count is not trusted — every declared
-export name is greped against the skill's documentation surface and only the
-names that actually appear count toward coverage.
-
-Distinct from reconcile-coverage.py (whose scalar/stack branches grep the §1
-inventory names and return only a residual missing *count*): this script greps
-the full declared metadata/provenance set and enumerates the *absent* names so
-§4b can list them in a High-severity gap. Both scripts share the same grep
-semantics (SKILL.md ∪ sorted references/*.md, UTF-8, case-sensitive substring
-containment — mirroring `grep "{name}"`) so their numerators agree.
+Lookup-and-count helper for the SKF test-skill workflow (coverage-check.md
+§2b, its "Numerator ground truth" paragraph; §4b records the gap). It fires
+only on the inflation signature
+(`stats.exports_documented == effective_denominator` exactly, or, for a
+provenance map with no `::` entry, its distinct entry names number
+`effective_denominator`): the numerator equals the denominator, the tell of a
+documented count padded to force 100% coverage. On that signature the declared
+count is not trusted: every declared export name is looked up in the skill's
+documentation surface and only the names that actually appear count toward
+coverage.
+
+Distinct from reconcile-coverage.py (whose scalar/stack branches look up the §1
+inventory names and return only a residual missing *count*): this script looks
+up the full declared metadata/provenance set and enumerates the *absent* names so
+§4b can list them in a High-severity gap. Both scripts read the same text and
+match names the same way, through validate-inventory.py beside them (SKILL.md ∪
+sorted references/*.md, UTF-8; the name as a fixed string, case-sensitive, never
+inside a longer identifier, so `get` is not found in `target` or `getAll`), so
+their numerators agree.
 
 Input schema (one JSON object):
   {
@@ -26,59 +31,71 @@ Input schema (one JSON object):
     "skillPackagePath": "/path/to/skill"        # SKILL.md ∪ references/*.md
   }
 
+or the files: --inputs <coverage-inputs.json> --skill-dir <skill package>.
+--inputs reads load-coverage-inputs.py metadata's output: its `declaredNames`
+and `inflationSignature`. Without the signature there is nothing to verify,
+so the result is `skipped` and `inflated` is false; a caller can run the
+command on every skill.
+
 Output (stdout, one object):
   {
+    "skipped":   <bool>,          # --inputs only: true when there is no inflation signature
     "declared":  <int>,           # de-duplicated declared name count
     "verified":  <int>,           # declared names present in the doc surface
     "present":   [names],         # sorted
-    "absent":    [names],         # sorted (declared − verified) — the gap list
+    "absent":    [names],         # sorted (declared − verified): the gap list
     "inflated":  <bool>           # verified < declared (numerator was padded)
   }
   or {"error": ..., "code": "INVALID_INPUT"} on a schema violation.
 
-`verified` is the numerator §4b uses for Export Coverage (it overrides the
-declared count when `inflated` is true).
+`verified` is the numerator §2c's reconcile-coverage.py call uses (it
+overrides the declared count when `inflated` is true): reconcile-coverage.py
+--verified reads this result. --output also writes it to a file.
 
 CLI usage (mirrors reconcile-coverage.py):
+  uv run verify-declared-numerator.py --inputs <file> --skill-dir <dir> [--output <file>]
   uv run verify-declared-numerator.py '<JSON>'                  # positional
   uv run verify-declared-numerator.py --json-input '<JSON>'     # explicit flag
   cat input.json | uv run verify-declared-numerator.py --stdin  # piped input
 
 Exit codes:
-  0  — verification emitted successfully
-  1  — no input / input could not be parsed as JSON
-  2  — input parsed but schema/semantics invalid (error object emitted as JSON)
+  0  verification emitted successfully
+  1  no input, input that does not parse as JSON, or an --inputs file that cannot be read
+  2  input parsed but schema/semantics invalid (error object emitted as JSON)
 """
 
 from __future__ import annotations
 
 import argparse
+import importlib.util
 import json
 import sys
 from pathlib import Path
 
+_INVENTORY_MODULE = None
+
+
+def _inventory():
+    """validate-inventory.py beside this script: the name match lives there."""
+    global _INVENTORY_MODULE
+    if _INVENTORY_MODULE is None:
+        sibling = Path(__file__).resolve().parent / "validate-inventory.py"
+        spec = importlib.util.spec_from_file_location("skf_validate_inventory", sibling)
+        if spec is None or spec.loader is None or not sibling.is_file():
+            raise ImportError(f"validate-inventory.py not found beside {Path(__file__).name}")
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        _INVENTORY_MODULE = module
+    return _INVENTORY_MODULE
+
 
 def make_error(message):
     return {"error": message, "code": "INVALID_INPUT"}
 
 
 def load_doc_text(skill_package_path):
-    """Concatenate SKILL.md ∪ references/*.md text for name-presence grepping.
-
-    Deterministic: references are read in sorted order. Reads as UTF-8 so
-    non-ASCII exports do not mojibake on Windows (cp1252 default). Mirrors
-    reconcile-coverage.py.load_doc_text so the two numerators agree.
-    """
-    root = Path(skill_package_path)
-    parts = []
-    skill_md = root / "SKILL.md"
-    if skill_md.is_file():
-        parts.append(skill_md.read_text(encoding="utf-8"))
-    refs_dir = root / "references"
-    if refs_dir.is_dir():
-        for ref in sorted(refs_dir.glob("*.md")):
-            parts.append(ref.read_text(encoding="utf-8"))
-    return "\n".join(parts)
+    """SKILL.md ∪ references/*.md text, as validate-inventory.py reads it."""
+    return _inventory().load_doc_text(skill_package_path)
 
 
 def _validate(inp):
@@ -102,8 +119,8 @@ def verify(inp, doc_text=None):
     if doc_text is None:
         doc_text = load_doc_text(inp["skillPackagePath"])
 
-    present = sorted(n for n in declared_set if n in doc_text)
-    absent = sorted(n for n in declared_set if n not in doc_text)
+    present = _inventory().names_present(declared_set, doc_text)
+    absent = sorted(set(declared_set) - set(present))
 
     return {
         "declared": len(declared_set),
@@ -122,7 +139,7 @@ def _build_parser():
         prog="verify-declared-numerator",
         description=(
             "Deterministic numerator ground-truth verifier (coverage-check.md "
-            "§4b). Greps the full declared export set against SKILL.md ∪ "
+            "§2b). Greps the full declared export set against SKILL.md ∪ "
             "references/*.md and enumerates the present/absent names so a padded "
             "numerator is caught and the verified count replaces it."
         ),
@@ -150,9 +167,32 @@ def _build_parser():
         action="store_true",
         help="Read the JSON object from stdin.",
     )
+    src.add_argument(
+        "--inputs",
+        metavar="PATH",
+        help="load-coverage-inputs.py metadata output: declaredNames and inflationSignature.",
+    )
+    parser.add_argument("--skill-dir", metavar="DIR",
+                        help="the skill package (with --inputs): SKILL.md and references/")
+    parser.add_argument("--output", metavar="PATH", help="also write the result to this file")
     return parser
 
 
+def verify_from_inputs(inputs, skill_dir, doc_text=None):
+    """Verify the declared set of a load-coverage-inputs.py metadata result."""
+    if not isinstance(inputs, dict):
+        return make_error("--inputs must hold a JSON object")
+    names = inputs.get("declaredNames")
+    if inputs.get("inflationSignature") is not True:
+        declared = len({n for n in names if isinstance(n, str) and n}) if isinstance(names, list) else 0
+        return {"skipped": True, "declared": declared, "verified": None, "present": [], "absent": [],
+                "inflated": False}
+    result = verify({"declaredNames": names, "skillPackagePath": skill_dir}, doc_text=doc_text)
+    if result.get("code") != "INVALID_INPUT":
+        result = {"skipped": False, **result}
+    return result
+
+
 def _resolve_input(args):
     if args.stdin:
         return sys.stdin.read()
@@ -163,30 +203,67 @@ def _resolve_input(args):
     return ""
 
 
+def _write_output(path, result):
+    target = Path(path)
+    if result.get("code") == "INVALID_INPUT":
+        target.unlink(missing_ok=True)
+        return
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes((json.dumps(result, indent=2, ensure_ascii=False) + "\n").encode("utf-8"))
+
+
 def main(argv=None):
     parser = _build_parser()
     args = parser.parse_args(argv)
-    raw = _resolve_input(args)
-    if not raw.strip():
-        parser.print_usage(file=sys.stderr)
-        print(
-            "error: no input provided (positional arg, --json-input, or --stdin)",
-            file=sys.stderr,
-        )
-        return 1
-
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError as exc:
-        print(json.dumps(make_error(f"Invalid JSON: {exc.msg}"), indent=2))
-        return 1
-
-    result = verify(data)
+    if args.inputs is not None:
+        if not args.skill_dir:
+            parser.error("--inputs needs --skill-dir")
+        try:
+            inputs = json.loads(Path(args.inputs).read_bytes().decode("utf-8-sig"))
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+            print(f"error: cannot read --inputs {args.inputs}: {exc}", file=sys.stderr)
+            return 1
+        result = verify_from_inputs(inputs, args.skill_dir)
+    else:
+        raw = _resolve_input(args)
+        if not raw.strip():
+            parser.print_usage(file=sys.stderr)
+            print(
+                "error: no input provided (positional arg, --json-input, --stdin or --inputs)",
+                file=sys.stderr,
+            )
+            return 1
+
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            print(json.dumps(make_error(f"Invalid JSON: {exc.msg}"), indent=2))
+            return 1
+
+        result = verify(data)
+    if args.output:
+        _write_output(args.output, result)
     print(json.dumps(result, indent=2))
     if isinstance(result, dict) and result.get("code") == "INVALID_INPUT":
         return 2
     return 0
 
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure stdout and stderr to UTF-8, keeping each stream's error handler.
+
+    A Windows console pipes them as cp1252, which cannot print every character
+    of the --help text, so --help would stop with UnicodeEncodeError.
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 if __name__ == "__main__":
+    _force_utf8(sys.stdout, sys.stderr)
     raise SystemExit(main())

package/src/skf-test-skill/templates/test-report-template.md

@@ -5,6 +5,7 @@ skillDir: ''
 runId: ''
 testMode: ''
 forgeTier: ''
+hardGate: ''
 testResult: ''
 score: ''
 threshold: ''
@@ -20,22 +21,28 @@ nextWorkflow: ''
 # Test Report: {{skillName}}
 
 <!--
-Section order is LOAD-BEARING: step 5 §5 enforces it, step 6 §5 verifies
-stepsCompleted against the canonical chain. Do not reorder or delete anchors.
-
-Anchor / Step mapping:
-  Test Summary       → detect-mode
-  Coverage Analysis  → coverage-check
-  Coherence Analysis → coherence-check
-  External Validation→ external-validators
-  (hard gate)        → step-hard-gate (reads findings, blocks or passes; no report section)
-  Completeness Score → score
-  Gap Report         → report (includes Discovery Quality subsection)
+Each stage writes its section in place of the heading below that it owns and
+the placeholder comment under that heading, so every heading occurs once.
+Before the result files are written, report.md §4c checks that each heading
+occurs exactly once and that no placeholder comment is left: a stage that
+skipped its section stops the run there. Do not reorder or delete the
+headings or their placeholder comments.
+
+Heading / owning step:
+  Test Summary        → detect-mode §2
+  Coverage Analysis   → coverage-check §5
+  Coherence Analysis  → coherence-check §6
+  External Validation → external-validators §5
+  (hard gate)         → step-hard-gate reads the gap ledger; it writes the
+                        Completeness Score section only when it blocks the run
+  Completeness Score  → score §6, or step-hard-gate §3 on a blocked run
+  Gap Report          → report §4c, rendered from the gap ledger (with the
+                        Discovery Quality subsection)
 -->
 
 ## Test Summary
 
-<!-- Populated by detect-mode §3 -->
+<!-- Populated by detect-mode §2 -->
 
 ## Coverage Analysis
 
@@ -51,9 +58,8 @@ Anchor / Step mapping:
 
 ## Completeness Score
 
-<!-- Populated by score §6 -->
+<!-- Populated by score §6, or by step-hard-gate §3 when the hard gate blocks the run -->
 
 ## Gap Report
 
-<!-- Populated by report §3-§4b (includes Discovery Quality subsection) -->
-
+<!-- Populated by report §4c from the gap ledger (includes the Discovery Quality subsection) -->

package/src/skf-update-skill/SKILL.md

@@ -7,17 +7,18 @@ description: Smart regeneration preserving [MANUAL] sections after source change
 
 ## Overview
 
-Surgically updates existing skills when source code changes, preserving all [MANUAL] developer content while re-extracting only affected exports with full provenance tracking. Only changed exports are re-extracted — unchanged content is never touched. Every regenerated instruction must trace to code with file:line citations. Stack skills (`skill_type: "stack"` in metadata.json) are not supported by surgical update — use `skf-create-stack-skill` to re-compose from updated constituents. If a stack skill is provided, this workflow exits with a redirect message.
+Surgically updates existing skills when source code changes, preserving all [MANUAL] developer content while re-extracting only affected exports with full provenance tracking; unchanged content is never touched, and each regenerated instruction cites code by file:line. Stack skills (`skill_type: "stack"` in metadata.json) are not updated here: this workflow redirects them to `skf-create-stack-skill`, which re-composes them from updated constituents.
 
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
-- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root — stage files reference `knowledge/version-paths.md` and `knowledge/tool-resolution.md`, and the terminal step chains to `shared/health-check.md`.
-- `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.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; stage files reference `knowledge/version-paths.md` and `knowledge/tool-resolution.md`, and the terminal step chains to `shared/health-check.md`.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
+- `references/` holds the workflow stages, chained by each file's frontmatter `nextStepFile` (init.md §8 loads `gap-driven.md` through `gapDrivenStepFile` instead when `update_mode` is `gap-driven`), the [MANUAL] rules file merge.md loads, and the invocation contract; `scripts/` holds this skill's own helper.
 - `{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.
-- **Cross-skill data coupling:** stages in this workflow load four shared assets from `skf-create-skill` to keep extraction semantics aligned between create and update — `re-extract.md` pulls `extraction-patterns.md`, `extraction-patterns-tracing.md`, and `tier-degradation-rules.md` from `skf-create-skill/references/`; `remote-source-resolution.md` references `source-resolution-protocols.md`; `write.md` reads `skill-sections.md` from `skf-create-skill/assets/`. Update-skill assumes these files are present at install time and that their semantics are stable across the two skills' versions.
+- **Cross-skill data coupling:** stages load shared assets from `skf-create-skill`, so create and update extract alike: `re-extract.md` pulls `extraction-patterns.md`, `extraction-patterns-tracing.md` and `tier-degradation-rules.md` from `skf-create-skill/references/`, `detect-changes.md` pulls `extraction-patterns.md`, and `gap-driven.md` pulls `extraction-patterns.md` and `tier-degradation-rules.md`; `init.md` §6c reads the version files the Version Reconciliation section of `skf-create-skill/references/source-resolution-protocols.md` lists, and `skf-source-tree.py` (init.md §6b) computes a remote skill's clone path with its workspace rule; `write.md` reads `skill-sections.md` from `skf-create-skill/assets/`, and `extraction-patterns.md` and, for §2's by-hand public API count, `entry-points-by-hand.md` from `skf-create-skill/references/`.
 
 ## Role
 
@@ -32,30 +33,26 @@ These rules apply to every step in this workflow:
 - Only load one step file at a time — never preload future steps
 - Always communicate in `{communication_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- Every HALT, ABORT or other exit before step 7 runs the **Halt procedure** of the step file it fires in: one `{runStateHelper}` `halt` call that undoes this run's writes, removes the private source tree, releases the run lock and, headless, prints the halt's line. A halt never falls through to step 6.
+- While `{source_tree}` is bound, a step that finds `{source_root}` missing HALTs with status `blocked` (`error.phase` `<step>:source-tree-missing`) instead of reading its files as deleted.
+- **Run log.** Warnings and gate decisions live in the run folder, never only in context: a step records each warning the moment it raises it, and each gate its decision, with the `record` call that step names.
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
 | 1 | Initialize & Load | references/init.md | No (confirm) |
-| 2 | Detect Changes | references/detect-changes.md | Yes |
+| 2 | Detect Changes | references/detect-changes.md | Conditional (§1b, §1c and §2.2 ask when triggered) |
+| 2g | Gap-Driven Repair (only when `update_mode` is gap-driven: in place of steps 2 and 3) | references/gap-driven.md | Conditional (§1 rule R1 asks [D]/[R] when a gap's remediation names removal) |
 | 3 | Re-Extract | references/re-extract.md | Yes |
-| 4 | Merge | references/merge.md | Yes |
-| 5 | Validate | references/validate.md | Yes |
-| 6 | Write | references/write.md | Yes |
-| 7 | Report | references/report.md | Yes |
-| 8 | Workflow Health Check | references/health-check.md | Yes |
+| 4 | Merge | references/merge.md | Conditional ([C] after resolved [MANUAL] conflicts) |
+| 5 | Write | references/write.md | Yes |
+| 6 | Report | references/report.md | Yes |
+| 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
-| Aspect | Detail |
-|--------|--------|
-| **Inputs** | skill_name [required] |
-| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--from-test-report` (gap-driven mode); `--allow-workspace-drift` (gap-driven only — bypass §0.a pinning guard); `--allow-degraded` (headless only — pre-authorize the lossy degraded full re-extraction when the provenance map is missing, instead of halting `blocked`; init.md §4); `--detect-only` (run detect-changes only, exit before re-extract; envelope `status="detect-only"`); `--dry-run` (run detect-changes + re-extract, exit before merge/write; envelope `status="dry-run"` describes what would change). If both `--detect-only` and `--dry-run` are passed, `--detect-only` wins. |
-| **Gates** | step 1: Confirm Gate [C] | step 4: Confirm Gate [C if clean merge, HALT if conflicts] |
-| **Outputs** | Updated SKILL.md, metadata.json, provenance-map.json, evidence-report.md (none when `--detect-only` or `--dry-run` is set — those modes are read-only inspection paths) |
-| **Concurrency** | Two simultaneous real-update runs against the same skill would corrupt provenance. init.md §1b acquires a PID-file lock at `{forge_data_folder}/{skill_name}/.skf-update.lock` before any artifact read; live-PID collisions halt with `status: "halted-for-concurrent-run"`. Stale locks (dead PID) are cleared silently with a warning. The lock is released by the terminal health-check step (step 8) on the normal path and by the two init-stage headless halts (§4/§6); mid-workflow halts leave it for the next run's stale-lock self-heal (see init.md §1b Release contract). Read-only modes (`--detect-only`, `--dry-run`) skip the lock entirely — they're safe alongside a concurrent real update. |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Each auto-resolved gate appends a `{gate, default_action, taken_action, reason, evidence?}` entry to `headless_decisions[]`, surfaced in step 7's `SKF_UPDATE_RESULT_JSON` envelope so non-interactive runs can be audited post-hoc. A HALT reached in headless mode emits its own `SKF_UPDATE_RESULT_JSON` at the halt site (the site's `status` code plus an `error: {phase, path?, reason}` object) and exits — halts do not fall through to step 7. Pipeline branches on the envelope's top-level `status` field (`success`, `no-changes`, `detect-only`, `dry-run`, or one of the documented `halted-for-*`/`blocked` codes). The first four are successful exits — pipelines treating non-success as failure must include them in the success set. The status enum is defined once in `src/shared/scripts/schemas/skf-update-result-envelope.v1.json`. |
+Headless callers: the inputs, flags, gate map, outputs and the `SKF_UPDATE_RESULT_JSON` line live in `references/invocation-contract.md`. Interactive runs do not need it.
 
 ## On Activation
 
@@ -63,17 +60,33 @@ These rules apply to every step in this workflow:
    - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+2. **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. Bind `{requested_skill}` ← the skill name or folder path the invocation passes (its argument that is neither a flag nor a flag's value), else empty: `references/init.md` §1 takes it as the skill without asking.
 
-3. **Resolve workflow customization.** Run:
+3. **Resolve the shared helpers and create the run folder**, before anything can halt. Resolve `{emitEnvelopeHelper}` ← the first that exists of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` and `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`.
+   Resolve `{runStateHelper}` ← the first that exists of `{project-root}/_bmad/skf/shared/scripts/skf-update-run-state.py` and `{project-root}/src/shared/scripts/skf-update-run-state.py`. Then, from `{project-root}`, run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-update-skill-XXXXXXXX"
    ```
 
-   This merges the three layers per `bmad-customize` rules (scalars override, arrays append): `{skill-root}/customize.toml` (bundled defaults), `_bmad/custom/<skill-name>.toml` under `{project-root}` (team overrides), and `_bmad/custom/<skill-name>.user.toml` under `{project-root}` (personal overrides). If the script is missing or fails, read `{skill-root}/customize.toml` directly.
+   Bind `{run_dir}` ← the path it prints and `{run_id}` ← its folder name less `skf-update-skill-`.
 
-   Apply the resolved values so no surface is a silent no-op: 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 (entries prefixed `file:` are paths or globs whose contents load as facts — the bundled default loads any `project-context.md` under `{project-root}`); resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string, and stash it in workflow context (`references/report.md` §5b invokes it after the result contract is written; empty string = the hook is a no-op). After activation completes, execute each entry in `workflow.activation_steps_append` in order before `init.md` runs.
+   If a helper is missing or the folder cannot be created, HALT: display "**SKF cannot start this update:** {the missing helper (re-install SKF), or the command's first stderr line}. Nothing was changed." Headless, when the emitter resolved, print the halt's line with no run folder, from `{project-root}`:
 
-4. Load, read the full file, and then execute `references/init.md` to begin the workflow.
+   ```bash
+   uv run {emitEnvelopeHelper} emit-halt --workflow skf-update-skill <<'SKF_JSON'
+   {"status": "blocked", "phase": "on-activation:run-folder", "path": "{project-root}/_bmad-output/.skf-run", "reason": "<which helper is missing, or that stderr line>", "skill_name": "unknown", "version": "unknown", "previous_version": "unknown", "update_mode": "normal"}
+   SKF_JSON
+   ```
+
+4. **Resolve workflow customization.** Run:
+
+   ```bash
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
+   ```
+
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-update-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. Record the warning in the run log at once: write `customization_resolver_unavailable: <reason>` to `{run_dir}/resolver-warning.txt` with a file write (a resolver error can hold quotes or `$( )`, so never echo it or type it into an argument), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"` from `{project-root}`.
+
+   Apply the resolved values so no surface is a silent no-op: 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 (entries prefixed `file:` are paths or globs whose contents load as facts: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off); resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string, and stash it in workflow context (`references/report.md` §5b runs it after a finished run's result files, never in `--detect-only`, `--dry-run` or a halt; empty = no-op). After activation completes, execute each entry in `workflow.activation_steps_append` in order before `init.md` runs.
+
+5. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-update-skill/customize.toml

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-update-skill.
-# Team overrides:     _bmad/custom/skf-update-skill.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-update-skill.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-update-skill.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-update-skill.user.toml
 
 [workflow]
 
@@ -10,15 +10,17 @@
 #   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 skill update work.
+# Steps SKILL.md On Activation step 4 runs once this file resolves: after
+# the config load, the headless flag and the run folder, before
+# activation_steps_append and references/init.md. Overrides append. Use for
+# org-wide pre-flight checks (auth, network, compliance) that must precede
+# any skill update 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.
+# Steps to run after activation, before references/init.md (the first
+# stage) runs. Overrides append. Use for context loads or banner
+# customization that should run once activation completes successfully.
 
 activation_steps_append = []
 
@@ -26,23 +28,36 @@ activation_steps_append = []
 # (drift policies, manual-section preservation rules, compliance
 # guardrails). Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "Updates must preserve [MANUAL] sections verbatim."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/update-policy.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-update-skill.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
 # Pipeline-integration hook invoked after report.md §5b writes the result
-# contract (the per-run record plus update-skill-result-latest.json). The
+# contract (the per-run record plus update-skill-result-latest.json) of a
+# finished run: an update that wrote a version, or a run that found no
+# change (its result files go in the current version's forge folder). The
 # command is called as:
 #   <on_complete> --result-path=<{forge_version}/update-skill-result-latest.json>
+# It is not called for --detect-only or --dry-run, which write no result
+# file, nor when a run halts.
 # Useful for Slack notifications, dashboard ingest, CI hooks, or chaining a
-# downstream skill (audit, export, test). Failures are logged to the run's
-# warnings[] but never fail the workflow.
+# downstream skill (audit, export, test). A failure is reported to the user
+# in one line and never fails the workflow; it does not reach the result
+# files or the SKF_UPDATE_RESULT_JSON line, which are written before the
+# hook runs.
 #
 # Empty string = no-op (default).