bmad-module-skill-forge 2.2.0 → 4.0.0

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

@@ -1,46 +1,80 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
+# dependencies = ["pyyaml"]
 # ///
 """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.
+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.
+`file_entries[].source_file`, and set aside any user-authored `[MANUAL]` path,
+any path the map's `entries[]` cite (code Category A and B track) and, with
+--brief, any path the skill brief leaves out. 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>
+  skf-detect-scripts-assets.py detect <source-root> \\
+    | skf-new-file-diff.py <provenance-map-path> [--brief <brief-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).
+map at the path argument (canonical `{file_entries: [...], entries: [...]}`
+object, or a bare array of file entries). A map with no `file_entries`, or a
+null one, tracks no file (a skill with no script, asset or promoted document,
+or a map written before the field existed); a `file_entries` or `entries`
+that is neither null nor an array is bad input.
+
+--brief <brief-path> (the skill's skill-brief.yaml) keeps a detected path
+only when the brief takes it, by update-skill Category A's in-scope test
+(skf-classify-changed-files.py load_scope, loaded from the shared
+scripts folder, the one brief-scope test the script and asset detector's
+and audit-skill's --brief use too, with the glob rules of
+skf-resolve-authoritative-files.py): each `scope.include` and
+`scope.exclude` pattern normalized (forward slashes, no leading `./`),
+and a path in scope when an include
+matches it and no exclude does. With an empty `scope.include`, a path is in
+scope when no exclude matches it and its extension is one a file the map's
+`entries[]` cite has, or one the brief's `language` uses. The brief's
+`scripts_intent` and `assets_intent` are honoured too: `none` drops every
+detected path of that kind, and an absent or free-text intent detects.
+An empty --brief (an unbound brief path) is a usage error, never an
+unscoped run. Every path, the map's and the detector's, is compared
+stripped, with forward slashes and no leading `./`.
 
 Output JSON (stdout):
   {
     "new_files":       [ {"source_file": "...", "kind": "script|asset"}, ... ],
     "skipped_manual":  [ "...", ... ],   # under scripts/[MANUAL]/ or assets/[MANUAL]/
     "already_tracked": [ "...", ... ],   # present in file_entries
+    "tracked_code":    [ "...", ... ],   # cited by entries[]: code, not a new file
+    "out_of_scope":    [ "...", ... ],   # --brief: outside the brief's scope
+    "intent_none":     [ "...", ... ],   # --brief: a kind whose intent is none
     "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".
+Each detected path lands in exactly one list, tested in this order:
+already_tracked, skipped_manual, tracked_code, out_of_scope, intent_none,
+and new_files for the rest. All 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". The three set-aside lists (tracked_code,
+out_of_scope, intent_none) are never counted in `stats`, whose
+inventory_total still counts every detected path.
 
 Exit codes:
-  0  success
-  2  bad input (unreadable/invalid stdin JSON, missing/invalid provenance map)
+  0  success (and --help)
+  2  bad input (a usage error, unreadable/invalid stdin JSON, missing/invalid
+     provenance map, a missing or unreadable brief, or a shared helper that
+     cannot be loaded)
 """
 
+import argparse
+import importlib.util
 import json
 import re
 import sys
@@ -49,6 +83,13 @@ from pathlib import Path
 # scripts/[MANUAL]/... or assets/[MANUAL]/... anywhere in the (posix) path
 _MANUAL_RE = re.compile(r"(?:^|/)(?:scripts|assets)/\[MANUAL\]/")
 
+# The shared helper that holds the scope test, installed beside this skill's
+# folder: it loads skf-resolve-authoritative-files.py beside it.
+SHARED_SCRIPTS = Path(__file__).resolve().parent.parent.parent / "shared" / "scripts"
+CLASSIFIER = "skf-classify-changed-files.py"
+
+_SHARED: dict[str, object] = {}
+
 
 def _fail(msg: str) -> "NoReturn":  # type: ignore[valid-type]
     print(json.dumps({"error": msg}), file=sys.stderr)
@@ -56,37 +97,88 @@ def _fail(msg: str) -> "NoReturn":  # type: ignore[valid-type]
 
 
 def _posix(p: str) -> str:
-    return p.replace("\\", "/")
+    """A path as skf-resolve-authoritative-files.py's normalize_rel_path
+    writes it: stripped, forward slashes, no leading `./`."""
+    p = p.strip().replace("\\", "/")
+    while p.startswith("./"):
+        p = p[2:]
+    return p
 
 
-def load_tracked_source_files(provenance_path: Path) -> set[str]:
-    """Return the set of file_entries[].source_file already in the provenance map."""
+def _shared(filename: str):
+    """A script of SHARED_SCRIPTS, loaded once; a failure to load it is bad input (exit 2)."""
+    module = _SHARED.get(filename)
+    if module is None:
+        path = SHARED_SCRIPTS / filename
+        try:
+            spec = importlib.util.spec_from_file_location("skf_" + filename[:-3].replace("-", "_"), path)
+            if spec is None or spec.loader is None or not path.is_file():
+                raise ImportError(f"{filename} not found in {SHARED_SCRIPTS}")
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+        except Exception as exc:  # whatever the script raises, the run reports it
+            _fail(f"cannot load {filename} from {SHARED_SCRIPTS}: {exc}; re-install SKF")
+        _SHARED[filename] = module
+    return module
+
+
+def _source_files(rows: list) -> set[str]:
+    found: set[str] = set()
+    for entry in rows:
+        if isinstance(entry, dict):
+            sf = entry.get("source_file")
+            if isinstance(sf, str) and _posix(sf):
+                found.add(_posix(sf))
+    return found
+
+
+def load_map_paths(provenance_path: Path) -> tuple[set[str], set[str]]:
+    """(file_entries[].source_file, entries[].source_file) of the provenance map.
+
+    A missing or null `file_entries` (or `entries`) is an empty list; one
+    that is neither null nor an array is bad input. A bare array is the
+    file entries themselves.
+    """
     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:
+        return _source_files(data), set()
+    if not isinstance(data, dict):
         _fail(
             f"provenance map {provenance_path} must be an object or array; "
             f"got {type(data).__name__}"
         )
+    rows = {}
+    for key in ("file_entries", "entries"):
+        value = data.get(key)
+        if value is None:
+            value = []  # a map that tracks no such row
+        if not isinstance(value, list):
+            _fail(f"`{key}` in {provenance_path} is not an array")
+        rows[key] = value
+    return _source_files(rows["file_entries"]), _source_files(rows["entries"])
 
-    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 load_tracked_source_files(provenance_path: Path) -> set[str]:
+    """Return the set of file_entries[].source_file already in the provenance map."""
+    return load_map_paths(provenance_path)[0]
+
+
+def load_scope(brief_path: Path, cited: set[str]):
+    """The brief's Scope (skf-classify-changed-files.py load_scope): its
+    takes(path) is Category A's in-scope test and its wants(kind) the
+    brief's intent. A brief it cannot find or read, or a shared helper it
+    cannot load, is bad input (exit 2)."""
+    classifier = _shared(CLASSIFIER)
+    try:
+        return classifier.load_scope(brief_path, cited)
+    except ValueError as exc:  # a brief it cannot find or read
+        _fail(str(exc))
+    except Exception as exc:  # an out-of-date classifier, or a resolver beside it that cannot load
+        _fail(f"cannot load the brief's scope test from {SHARED_SCRIPTS}: {exc}; re-install SKF")
 
 
 def collect_inventory(detect: dict) -> list[tuple[str, str]]:
@@ -112,38 +204,82 @@ def collect_inventory(detect: dict) -> list[tuple[str, str]]:
     return sorted(seen.items())
 
 
-def diff(detect: dict, tracked: set[str]) -> dict:
+def diff(detect: dict, tracked: set[str], cited: set[str] | frozenset = frozenset(),
+         scope=None) -> dict:
+    """Sort the detected paths into the output lists; `scope` is load_scope's
+    Scope (--brief) or None."""
     new_files: list[dict] = []
-    skipped_manual: list[str] = []
-    already_tracked: list[str] = []
+    lists: dict[str, list[str]] = {name: [] for name in (
+        "skipped_manual", "already_tracked", "tracked_code", "out_of_scope", "intent_none")}
 
     inventory = collect_inventory(detect)
     for sf, kind in inventory:
         if sf in tracked:
-            already_tracked.append(sf)
+            lists["already_tracked"].append(sf)
         elif _MANUAL_RE.search(sf):
-            skipped_manual.append(sf)
+            lists["skipped_manual"].append(sf)
+        elif sf in cited:
+            lists["tracked_code"].append(sf)
+        elif scope is not None and not scope.takes(sf):
+            lists["out_of_scope"].append(sf)
+        elif scope is not None and not scope.wants(kind):
+            lists["intent_none"].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),
+        "skipped_manual": sorted(lists["skipped_manual"]),
+        "already_tracked": sorted(lists["already_tracked"]),
+        "tracked_code": sorted(lists["tracked_code"]),
+        "out_of_scope": sorted(lists["out_of_scope"]),
+        "intent_none": sorted(lists["intent_none"]),
         "stats": {
             "inventory_total": len(inventory),
             "new": len(new_files),
-            "skipped_manual": len(skipped_manual),
-            "already_tracked": len(already_tracked),
+            "skipped_manual": len(lists["skipped_manual"]),
+            "already_tracked": len(lists["already_tracked"]),
         },
     }
 
 
+USAGE = "usage: skf-new-file-diff.py <provenance-map-path> [--brief <brief-path>]  (detect JSON on stdin)"
+
+
+class _JsonErrorParser(argparse.ArgumentParser):
+    """Report a usage error as the JSON error and exit 2 every other bad input gets."""
+
+    def error(self, message: str) -> "NoReturn":  # type: ignore[valid-type]
+        _fail(f"{USAGE}: {message}")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _JsonErrorParser(
+        prog="skf-new-file-diff.py",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "provenance_map",
+        metavar="provenance-map-path",
+        help="the skill's provenance-map.json (the detect JSON is read on stdin)",
+    )
+    parser.add_argument(
+        "--brief",
+        metavar="brief-path",
+        help="the skill brief: keep only the paths its scope takes and its intents want",
+    )
+    return parser
+
+
 def main(argv: list[str]) -> int:
-    if len(argv) != 2:
-        _fail("usage: skf-new-file-diff.py <provenance-map-path>  (detect JSON on stdin)")
+    parser = _build_parser()
+    args = parser.parse_args(argv[1:])
+    if args.brief is not None and not args.brief.strip():
+        parser.error("--brief is empty (an unbound brief path?): pass the brief, or leave --brief out")
 
-    provenance_path = Path(argv[1])
+    provenance_path = Path(args.provenance_map)
     if not provenance_path.exists():
         _fail(f"provenance map not found: {provenance_path}")
 
@@ -157,8 +293,9 @@ def main(argv: list[str]) -> int:
     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)
+    tracked, cited = load_map_paths(provenance_path)
+    scope = load_scope(Path(args.brief), cited) if args.brief is not None else None
+    result = diff(detect, tracked, cited, scope)
     print(json.dumps(result, indent=2))
     return 0
 

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

@@ -7,7 +7,7 @@ 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. Read-only: it reads skills and input documents and writes only the feasibility report (see Workflow Rules).
+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, its result files and a scratch run folder (see Workflow Rules).
 
 **Schema contract:** This skill is the producer of the SKF shared feasibility report schema — every report conforms to it.
 
@@ -18,6 +18,8 @@ Cross-references generated skills against architecture and PRD documents to prod
 - `{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.
+- **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; e.g. `shared/references/output-contract-schema.md` and `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.
 
 ## Role
 
@@ -33,7 +35,11 @@ These rules apply to every step in this workflow:
 - 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
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision; a gate that picks its default for the user (step 1's offer of the newest earlier report) also records that decision in the run sink the moment it decides
+- Every helper a stage runs (a `scripts/` file, or a shared helper from the stage's probe order) is required: if the probe order resolves to no path, or the helper cannot start, HALT (exit code 3, `halt_reason: "resolution-failure"`) at the stage's phase, through the stage's halt envelope. Never recompute a helper's result by hand: the main-thread rule above covers subagent work, not helpers.
+- Every HARD HALT names its exit code, `halt_reason` and phase, and in headless mode prints its envelope through the shared emitter, with the command each stage file shows (`references/exit-codes.md` describes the envelope).
+- Stages 1 to 5 write only the timestamped report `{outputFile}`, and each write that fails halts (exit code 4, `halt_reason: "write-failed"`). Step 6 copies the report to `{outputFileLatest}` only after it passes the feasibility-report check, so a run that halts before then leaves the previous finished copy, the one consumers read, in place.
+- Run state lives in `{run_dir}`, not in context; step 6 deletes it, a HALT keeps it.
 
 ## Stages
 
@@ -44,7 +50,7 @@ These rules apply to every step in this workflow:
 | 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) |
+| 6 | Report | references/report.md | Yes |
 | 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
@@ -53,20 +59,14 @@ 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 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` |
+| **Gates** | step 1 Input Gate (use args), including the offer to compare against the newest earlier report (headless default: use it). No later stage waits for input: a run with 0% coverage or only Blocked pairs prints one warning and continues, so its report still carries the recommendations. |
+| **Outputs** | `feasibility-report-{project_slug}-{timestamp}.md` and its `feasibility-report-{project_slug}-latest.md` copy (not a symlink), written by step 6 once the finished report passes the feasibility-report check, both per the SKF shared feasibility report schema (`{project-root}/_bmad/skf/shared/references/feasibility-report-schema.md`; `{project-root}/src/shared/references/feasibility-report-schema.md` in a dev checkout), with integration verdicts, coverage analysis, recommendations, and evidence sources; plus `verify-stack-result-{YYYYMMDD-HHmmss}.json` and `verify-stack-result-latest.json` in `{forge_data_folder}` |
 | **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 `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 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"`, `"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`).
+When `{headless_mode}` is true, step 6 prints one `SKF_VERIFY_STACK_RESULT_JSON: {...}` line on **stdout** and every HARD HALT one on **stderr**, built by the shared emitter: `references/exit-codes.md` gives its fields, the `halt_reason` values and the halt command.
 
 ## On Activation
 
@@ -74,49 +74,30 @@ SKF_VERIFY_STACK_RESULT_JSON: {"status":"success|error","report_path":"…|null"
    - `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)
+2. **Fix the run-scoped variables** so no stage derives them again:
    - `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.
+   - `project_slug` is bound by init.md before its §1, from the shared feasibility-report helper, which holds the one slug rule the consumers of this report also apply; never slugify `project_name` by hand
+   - The two combine in init.md §4 into `{outputFile}` and `{outputFileLatest}` per the stage frontmatter template, and stay fixed for the whole run, so every later reference to either file resolves to the same path.
+   - `run_dir` ← `{project-root}/_bmad-output/.skf-run/skf-verify-stack-{timestamp}`, the run folder init.md creates first
 
 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.
 
+   **Bind the inputs** in every mode: `{architecture_doc_path}` ← the `--architecture-doc` value, `{prd_path}` ← `--prd` and `{previous_report_path}` ← `--previous-report`, each null when its flag is absent. init.md §1 asks only for those still null.
+
 4. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-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:
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-verify-stack.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. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for init.md to record once it has created `{run_dir}`.
 
-   - `{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.
+   Apply the path-scalar fallback now so stage files don't repeat it: `{reportTemplatePath}` ← `workflow.report_template_path` if non-empty, else `assets/feasibility-report-template.md`. An empty or absent value falls through to that default, and init.md §4 loads the variable as it is. Bind `{outputFolderPath}` ← `{forge_data_folder}`, always (no setting moves it): the report and its `-latest` copy go where create-stack-skill and refine-architecture look for them, and step 1 finds the earlier reports there.
 
    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
-   mkdir -p "{outputFolderPath}" && \
-     printf 'probe' > "{outputFolderPath}/.skf-write-probe" && \
-     rm "{outputFolderPath}/.skf-write-probe"
-   ```
+   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 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); then execute each entry in `workflow.activation_steps_append` after activation completes.
 
-   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`.
+5. **Pre-flight: the emitter.** Before the first prompt, resolve `{emitEnvelopeHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py`, else `{project-root}/src/shared/scripts/skf-emit-result-envelope.py` (the first that exists). If neither exists, HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `on-activation:emitter` and display only: "Verify Stack cannot run without `skf-emit-result-envelope.py`, which is not installed. Re-install SKF."
 
 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

@@ -19,6 +19,9 @@ architectureDoc: ''
 prdDoc: ''
 previousReport: ''
 skillsAnalyzed: 0
+coverageCovered: null
+coverageMissing: null
+coverageReplaced: null
 stepsCompleted: []
 requirementsPass: ''
 requirementsFulfilled: null
@@ -55,9 +58,8 @@ deltaUnchanged: null
 
 ## Integration Verdicts
 
-<!-- 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: -->
+<!-- Filled in place by integrations: one row per pair goes under this header.
+The report holds this table once: consumers read it and reject a second copy. -->
 
 | lib_a | lib_b | verdict | rationale |
 |-------|-------|---------|-----------|
@@ -72,5 +74,9 @@ The table header is fixed and MUST be emitted exactly as shown below: -->
 
 ## Evidence Sources
 
-<!-- Appended by synthesize — cite each skill's SKILL.md path, metadata_schema_version,
-     confidence_tier, stack manifest (if any), and architecture/PRD doc paths -->
+<!-- Filled in place by synthesize: one row per skill goes under this header (the
+next run's delta reads its evidence_tier column), then the architecture and PRD
+document paths. -->
+
+| skill | evidence_tier | confidence_tier | metadata_schema_version | skill_md |
+|-------|---------------|-----------------|-------------------------|----------|

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

@@ -1,8 +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}
+# Team overrides:     {project-root}/_bmad/custom/skf-verify-stack.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-verify-stack.user.toml
 
 [workflow]
 
@@ -10,27 +10,41 @@
 #   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.
+# Steps SKILL.md On Activation step 4 runs once this file resolves: after
+# config.yaml is loaded and {headless_mode} is resolved, before the emitter
+# pre-flight (step 5) and before any stage. 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.
+# Steps to run once activation completes (the emitter resolved), before
+# references/init.md (the first stage) loads. Overrides append. Use for
+# context loads or banner customization.
 
 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.
+# language, the other names a technology goes by). Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - 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).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# Extra aliases go here: a fact such as "Our documents call the postgresql
+# skill Postgres or PG." makes step 2 (coverage) pass both names to the
+# mentions helper as aliases of that skill, so the architecture document's
+# "PG" covers it and pairs it for step 3.
+#
+# 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-verify-stack.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
@@ -42,18 +56,37 @@ persistent_facts = [
 
 on_complete = ""
 
-# --- 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.
+# --- Optional override. An empty string means the default named below. ---
 
-report_template_path = ""
-integration_rules_path = ""
-coverage_patterns_path = ""
+# The template step 1 (references/init.md section 4) creates the feasibility
+# report from: a path from the skill root, or a {project-root}/... path.
+# Default: assets/feasibility-report-template.md. A house-style copy may
+# reword the prose and add sections of its own, and must keep what the shared
+# feasibility report schema (feasibility-report-schema.md under
+# shared/references/) fixes, since the next run, create-stack-skill and
+# refine-architecture read the report through it:
+#   - the frontmatter keys with their starting values, `schemaVersion: "1.0"`
+#     included;
+#   - the `## Executive Summary`, `## Coverage Analysis`,
+#     `## Integration Verdicts`, `## Recommendations` and `## Evidence Sources`
+#     headings, once each and in that order;
+#   - one empty `| lib_a | lib_b | verdict | rationale |` table under
+#     `## Integration Verdicts`, and the empty
+#     `| skill | evidence_tier | confidence_tier | metadata_schema_version | skill_md |`
+#     table under `## Evidence Sources`: the stages fill both in place.
+# Step 6 checks the finished report against the schema and halts
+# (`schema-violation`) on a copy that breaks it.
 
-# 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.
+report_template_path = ""
 
-output_folder_path = ""
+# Not overridable:
+#   - the integration verification rules: they hold the obligations the shared
+#     schema puts on this report's producer (Check 4's literal citation and the
+#     Plausible cap), which the report's readers rely on;
+#   - the coverage patterns: the shared mentions helper finds the skills the
+#     architecture document names, and a fact (see persistent_facts) adds the
+#     other names a skill goes by;
+#   - the report folder: the report always lands in {forge_data_folder}, where
+#     create-stack-skill and refine-architecture look for it. Change
+#     forge_data_folder in config.yaml to move the report and its readers
+#     together.