bmad-module-skill-forge 1.9.0 → 2.0.1

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

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

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

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

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

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

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

@@ -22,32 +22,4 @@ Parse document section headers for technology groupings:
 - `## Backend Core` → technologies in backend layer
 - `## AI Layer` → AI-related technologies
 
-**Mermaid Diagram Handling:** Do NOT parse Mermaid diagram syntax (`graph`, `flowchart`, `sequenceDiagram`, etc.) for technology detection. Only use prose text (headings, paragraphs, lists, tables) for detection. If the architecture document appears to list technologies exclusively inside Mermaid diagrams, note this in the coverage results as a detection limitation and recommend the user add prose-based technology listings.
-
-### 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 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 2 §4):**
-
-| Label                                  | Meaning                                                                                                                          |
-|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
-| **Extra (unreferenced)**               | Skill exists with a resolvable `source_repo` / `source_root`, but no architecture tech token matches it                          |
-| **Orphan (source_repo unresolvable)**  | Skill's `source_repo` is empty, malformed, or its basename cannot be extracted — cross-reference against architecture impossible |
-
-## Output Format
-
-When presenting coverage results, use the following structure:
-
-```
-| Technology | Source Section | Skill Match | Verdict |
-|------------|---------------|-------------|---------|
-| {tech_name} | {section_heading} | {skill_name or '—'} | Covered / Missing |
-```
-
-Include a summary line: `Coverage: {covered_count}/{total_count} ({percentage}%)`
+**Mermaid Diagram Handling:** Do not parse Mermaid diagram syntax (`graph`, `flowchart`, `sequenceDiagram`, etc.) for technology detection — use only prose text (headings, paragraphs, lists, tables). If the architecture document appears to list technologies exclusively inside Mermaid diagrams, note this in the coverage results as a detection limitation and recommend the user add prose-based technology listings.

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

@@ -1,6 +1,7 @@
 ---
 nextStepFile: 'integrations.md'
 coveragePatternsData: '{coveragePatternsPath}'
+coverageTallyScript: 'scripts/skf-coverage-tally.py'
 feasibilitySchemaProbeOrder:
   - '{project-root}/_bmad/skf/shared/references/feasibility-report-schema.md'
   - '{project-root}/src/shared/references/feasibility-report-schema.md'
@@ -66,7 +67,7 @@ For each referenced technology in the list:
   4. Compare the resulting basenames/segments against the tech tokens via case-insensitive equality (no substring/fuzzy matching)
   5. A match on either `source_repo` basename or `source_root` last segment counts as a hit
 
-**Detect a deliberate-removal signal (from the architecture document):** Before assigning Covered/Missing, check whether the referenced technology is explicitly marked for removal or replacement in the architecture document itself. Be conservative — recognize a removal signal ONLY when one of these is present, and when in doubt do NOT treat it as removal:
+**Detect a deliberate-removal signal (from the architecture document):** Before assigning Covered/Missing, check whether the referenced technology is explicitly marked for removal or replacement in the architecture document itself. Be conservative — recognize a removal signal only when one of these is present, and when in doubt leave it as a normal reference (a false removal signal silently drops a real coverage gap):
 - The technology is listed under a section whose heading matches (case-insensitive) one of: "deprecated", "removed", "legacy", "migrating away", "being replaced", "to be removed", "sunset", "retiring".
 - The technology's own mention carries an inline removal annotation, e.g. "(deprecated)", "(being replaced by …)", "(removing)", "(to be removed)", "(legacy)".
 
@@ -77,13 +78,19 @@ Record the cited section heading or annotation text as evidence for every techno
 - **Replaced** — no matching skill exists AND a deliberate-removal signal (above) was found; the technology is intentionally being removed/replaced, so no skill should exist for it
 - **Missing** — no matching skill found and no removal signal
 
-**Replaced** technologies are EXCLUDED from the coverage denominator — they are not a gap to close. The denominator (`live_count`) is the count of referenced technologies that are **Covered** or **Missing**; **Replaced** technologies do not count toward it.
-
 Build the coverage matrix as a structured table.
 
+**Tally the matrix deterministically.** Assigning each verdict is judgment; counting the classes and computing the percentage has one correct answer, so delegate it. Serialize the matrix as `{"rows": [{"technology": "…", "verdict": "Covered|Missing|Replaced"}, …]}` and run:
+
+```bash
+echo '<rows JSON>' | uv run {coverageTallyScript} --stdin
+```
+
+The script (run `uv run {coverageTallyScript} --help` for the contract) returns `covered_count`, `missing_count`, `replaced_count`, `live_count` (the denominator — Covered + Missing, with Replaced excluded because a technology being removed is not a gap to close), `total_referenced`, and `coverage_percentage` (Replaced excluded from the denominator, half-up rounding pinned so the same matrix always yields the same integer). Consume these values in §5 and §6 rather than recomputing them. If `uv` is unavailable (e.g. claude.ai web), compute the same values inline per the `--help` contract: `live_count = covered + missing`; `coverage_percentage = round-half-up(covered / live_count * 100)`, or `0` when `live_count` is `0`.
+
 ### 4. Detect Extra Skills
 
-Check if any skills in the inventory are NOT referenced in the architecture document.
+Check if any skills in the inventory are not referenced in the architecture document.
 
 **Subdivide into two categories (both informational — not errors):**
 - **Extra (unreferenced)** — The skill's `source_repo` / `source_root` resolves cleanly (both non-empty and well-formed), but no architecture document tech token matches it.
@@ -103,7 +110,7 @@ Extra and Orphan skills are informational only. They do not affect the coverage
 |------------|---------------|-------------|---------|
 | {tech_name} | {section_heading} | {skill_name or '—'} | {Covered / Missing / Replaced} |
 
-**Coverage: {covered_count}/{live_count} ({percentage}%)** — `live_count` excludes technologies marked **Replaced** (being removed/replaced); they are not a coverage gap.
+**Coverage: {covered_count}/{live_count} ({coverage_percentage}%)** (from the §3 tally; `live_count` excludes **Replaced** technologies)
 
 {IF 100% coverage AND no Extra skills:}
 **All referenced technologies have a matching skill. No extra skills detected.**
@@ -125,7 +132,7 @@ Extra and Orphan skills are informational only. They do not affect the coverage
 
 ### 6. Append to Report
 
-**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists: HALT (exit code 3, `halt_reason: "resolution-failure"`); in headless, emit the error envelope.
 
 **Resolve `{feasibilitySchemaRef}`** from `{feasibilitySchemaProbeOrder}`; first existing path wins (installed SKF module path first, dev-checkout `src/` fallback).
 
@@ -133,9 +140,9 @@ Write the **Coverage Analysis** section to `{outputFile}` (see `{feasibilitySche
 - Include the full coverage table
 - Include coverage percentage
 - Include missing skill recommendations
-- Include the Replaced (being removed/replaced) subdivision from section 3, with the cited removal evidence — these are NOT gaps and carry no [CS]/[QS] recommendation
+- Include the Replaced (being removed/replaced) subdivision from section 3, with the cited removal evidence — these are not gaps and carry no [CS]/[QS] recommendation
 - Include the Extra (unreferenced) and Orphan (source_repo unresolvable) subdivisions from section 4
-- Update frontmatter: append `'coverage'` to `stepsCompleted`; set `coveragePercentage` (integer 0..100) computed as `covered_count / live_count` (Replaced technologies excluded from the denominator; if `live_count` is 0, set `coveragePercentage: 0`)
+- Update frontmatter: append `'coverage'` to `stepsCompleted`; set `coveragePercentage` to the `coverage_percentage` value from the §3 tally (integer 0..100)
 - Pipe the updated full content through `python3 {atomicWriteHelper} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 7. Auto-Proceed to Next Step
@@ -147,7 +154,9 @@ Write the **Coverage Analysis** section to `{outputFile}` (see `{feasibilitySche
 
 **Select:** [X] Halt workflow (recommended) | [C] Continue anyway"
 
-- IF X: "**Workflow halted.** Update the architecture document and re-run [VS] when ready." — END workflow
+**GATE [default: C]** — Interactive-only guard. If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: continuing past all-Replaced coverage gate (nothing live to verify)". Headless never takes [X], so step 6 still emits the result contract — the run resolves to `NOT_FEASIBLE` via the synthesize zero-coverage short-circuit.
+
+- IF X: "**Workflow halted.** Coverage Analysis saved to `{outputFile}`. Update the architecture document and re-run [VS] when ready." HALT (exit code 8, `halt_reason: "analysis-halted"`).
 - IF C: "**Continuing — the analysis covers only technologies marked for removal and will be limited.**" Load, read the full file and then execute `{nextStepFile}`.
 
 {IF coveragePercentage is 0% AND live_count > 0:}
@@ -157,7 +166,9 @@ Write the **Coverage Analysis** section to `{outputFile}` (see `{feasibilitySche
 
 **Select:** [X] Halt workflow (recommended) | [C] Continue anyway"
 
-- IF X: "**Workflow halted.** Generate skills and re-run [VS] when ready." — END workflow
+**GATE [default: C]** — Interactive-only guard. If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: continuing past 0%-coverage gate". Headless never takes [X], so step 6 still emits the result contract — the run resolves to `NOT_FEASIBLE` via the synthesize zero-coverage short-circuit.
+
+- IF X: "**Workflow halted.** Coverage Analysis saved to `{outputFile}`. Generate skills and re-run [VS] when ready." HALT (exit code 8, `halt_reason: "analysis-halted"`).
 - IF C: "**Continuing with 0% coverage — results will be limited.**"
 
   Load, read the full file and then execute `{nextStepFile}`.

package/src/skf-verify-stack/references/exit-codes.md

@@ -0,0 +1,14 @@
+# 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. Each code pairs with a `halt_reason` string carried in the headless result envelope.
+
+| 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 → `skills-folder-missing`); step 1 §3 (forge_data_folder unconfigured → `forge-folder-unconfigured`); any stage that cannot resolve a required shared helper (atomic-write, schema ref, validate-feasibility-report) from its probe order → `resolution-failure` |
+| 4    | write-failure        | On-Activation §5 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 → `insufficient-skills`); step 1 §1 (`previousReport` resolves to same inode as `{outputFile}` → `previous-report-collision`); 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); step 3 §3 (>20% API-surface subagents return malformed JSON) |
+| 8    | analysis-halted      | coverage.md §7 & integrations.md §7 — user picks [X] at an elective vacuous-analysis gate. These gates are interactive-only; in headless they auto-continue, so exit 8 never fires headlessly and `analysis-halted` never appears in the result envelope. |

package/src/skf-verify-stack/references/health-check.md

@@ -24,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 6) 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. This is not an error halt — the health check is an optional self-improvement hook, and the feasibility report (written in step 6) is the authoritative workflow output. Exiting cleanly keeps CI and headless runs from failing on a missing optional hook.

package/src/skf-verify-stack/references/init.md

@@ -6,20 +6,15 @@ feasibilitySchemaProbeOrder:
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
-# {outputFile} and {outputFileLatest} resolve from the activation-stored
-# {project_slug}, {timestamp}, and {outputFolderPath} variables (set in
-# SKILL.md On Activation §2 + §4). The activation-stored values are
-# fixed for the entire run, so every later reference sees the same
-# filename — no order-of-operations bug.
 outputFile: '{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md'
 outputFileLatest: '{outputFolderPath}/feasibility-report-{project_slug}-latest.md'
 # Resolve `{enumerateStackSkillsHelper}` by probing
 # `{enumerateStackSkillsProbeOrder}` in order (installed SKF module path
 # first, src/ dev-checkout fallback); first existing path wins. §2 calls
 # it for the deterministic skills inventory (cascade-resolved exports,
-# metadata-hash for change-detection, confidence-tier mapping). HALT if
-# neither candidate exists — falls through to LLM-driven subagent fan-out
-# only as graceful degradation, see §2.
+# metadata-hash for change-detection, confidence-tier mapping). If neither
+# candidate exists, §2 does NOT halt — it falls through to the LLM-driven
+# subagent fan-out as graceful degradation (see §2).
 enumerateStackSkillsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
   - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
@@ -67,10 +62,16 @@ Wait for user input. **GATE [default: use args]** — If `{headless_mode}` and `
 
 **Validate previous report (if provided):**
 - Confirm the file exists and is readable
-- **Collision check:** Resolve `{outputFile}` from the activation-stored `{outputFolderPath}`, `{project_slug}`, and `{timestamp}` (all three computed in SKILL.md On Activation §2 + §4 — they are fixed for the entire run). Then compare both the provided path and `{outputFile}` via `(st_dev, st_ino)` tuples obtained from `stat(2)` on each path (do not rely on absolute-path string equality — symlinks, bind mounts, and case-insensitive filesystems can defeat string comparison; the `(st_dev, st_ino)` comparison is the canonical kernel-level equivalent of `os.path.realpath`-based equality and is strictly stronger because it also catches hardlinks). If `{outputFile}` does not yet exist, resolve its parent via `realpath`, stat that directory, and combine `(st_dev, parent_ino, basename)` for comparison. If the two paths resolve to the same inode, warn: "The previous report path points to the same inode as the new report. This file will be overwritten during this run. Provide a path to a backup copy, or leave empty to skip delta comparison." HALT (exit code 5, `halt_reason: "previous-report-collision"`) until resolved. In headless, emit the error envelope.
+- **Collision check:** Resolve `{outputFile}` from the activation-stored `{outputFolderPath}`, `{project_slug}`, and `{timestamp}`. Then compare both the provided path and `{outputFile}` via `(st_dev, st_ino)` tuples obtained from `stat(2)` on each path (do not rely on absolute-path string equality — symlinks, bind mounts, and case-insensitive filesystems can defeat string comparison). If `{outputFile}` does not yet exist, resolve its parent via `realpath`, stat that directory, and combine `(st_dev, parent_ino, basename)` for comparison. If the two paths resolve to the same inode, warn: "The previous report path points to the same inode as the new report. This file will be overwritten during this run. Provide a path to a backup copy, or leave empty to skip delta comparison." HALT (exit code 5, `halt_reason: "previous-report-collision"`) until resolved. In headless, emit the error envelope.
 - If missing → "Previous report not found at `{path}`. Proceeding without delta comparison."
 - Store as `previousReport: {path}` (or empty string if not provided)
 
+**Auto-discover a prior report (only when none was provided above):** If neither `--previous-report` nor an interactive previous-report path was given, glob `{outputFolderPath}` for `feasibility-report-{project_slug}-*.md`, excluding this run's `{timestamp}` file and `feasibility-report-{project_slug}-latest.md`. Every run writes a new timestamped report, so a usable prior usually already persists on disk with no manual backup. If one or more matches remain, pick the most recent by the embedded `YYYYMMDD-HHmmss` timestamp:
+- Interactive: offer "Found a prior report from `{date}` — compare against it? **[Y]** use it / paste a different path / **[skip]**". On [Y], set `previousReport` to that path; on a pasted path, use it; on `skip`, leave `previousReport` empty.
+- **GATE [default: Y]** — If `{headless_mode}`: auto-select the most recent match, set `previousReport` to it, log: "headless: delta comparison against `{path}`".
+- Excluding this run's `{timestamp}` and `-latest` files guarantees the auto-selected path is a distinct inode from `{outputFile}`, so it can never trip the collision check above.
+- If no match remains, leave `previousReport` empty — first run, no delta.
+
 ### 2. Scan Skills Folder
 
 **Pre-flight — skills folder existence:**
@@ -82,18 +83,20 @@ Wait for user input. **GATE [default: use args]** — If `{headless_mode}` and `
 **Primary path — deterministic enumeration via shared helper:**
 
 ```bash
-python3 {enumerateStackSkillsHelper} enumerate {skills_output_folder}
+python3 {enumerateStackSkillsHelper} enumerate {skills_output_folder} --reliability
 ```
 
 The helper walks `{skills_output_folder}`, reads each `metadata.json`, applies the exports cascade (metadata → references/ → SKILL.md prose), maps `confidence_tier` (T1/T2/T1-low), captures stack-skill cycles via `composes:`, and emits structured JSON with one entry per skill plus a top-level `warnings[]` array. Cache the result as `skill_inventory` (used by §3, §4, §5, and the integrations + coverage stages).
 
 Each helper-emitted entry includes: `skill_name`, `version`, `language`, `confidence_tier`, `exports` (cascade-resolved), `source_repo`, `source_root`, plus a `metadata_hash` for change-detection across runs. The helper's `warnings[]` carries per-skill skip reasons (missing manifest, malformed JSON, non-symlink `active`, orphan-versions, schema-version violations).
 
-**Failure-budget guard:** If `len(warnings) / len(skill_inventory) + len(warnings) > 0.20` (the same 20% threshold chosen so a single malformed skill in a small 3-5 skill inventory does not trip the halt), HALT (exit code 7, `halt_reason: "inventory-unreliable"`) with: "Inventory scan unreliable — {len(warnings)}/{total} skills returned malformed metadata or skip warnings. Re-run [VS] after skills stabilize." In headless, emit the error envelope.
+`--reliability` additionally attaches the inventory reliability verdict: `inventory_reliable` (bool), `unreliable_ratio` (float), `skill_count`, and `warning_count`.
+
+**Failure-budget guard:** Read `inventory_reliable` from the helper JSON. If it is `false`, HALT (exit code 7, `halt_reason: "inventory-unreliable"`) with: "Inventory scan unreliable — {warning_count}/{skill_count + warning_count} skills returned malformed metadata or skip warnings. Re-run [VS] after skills stabilize." (substitute `warning_count` and `skill_count + warning_count` from the helper JSON). In headless, emit the error envelope. The helper's threshold is chosen so a single malformed skill in a small 3-5 skill inventory does not trip the halt.
 
 **Capture mtime:** For each accepted skill in `skill_inventory`, also record `metadata.json`'s mtime via `stat` into the entry as `metadata_mtime`. Step-03 will re-verify this to detect mid-run modifications.
 
-**Fallback path — graceful degradation when the helper is unavailable:** If `{enumerateStackSkillsHelper}` has no existing candidate (e.g. partial installation), fall through to the LLM-driven subagent fan-out: launch up to **8 subagents concurrently**, each reading one resolved skill package's `metadata.json` and returning the same JSON shape the helper would emit. Apply the same 20% failure-budget guard. This path exists so verify-stack survives a missing helper, but the deterministic helper is preferred — it has a tested cascade resolver, captures the metadata-hash, and surfaces every skip reason in `warnings[]` consistently.
+**Fallback path — graceful degradation when the helper is unavailable:** If `{enumerateStackSkillsHelper}` has no existing candidate (e.g. partial installation), fall through to the LLM-driven subagent fan-out: launch up to **8 subagents concurrently**, each reading one resolved skill package's `metadata.json` and returning the same JSON shape the helper would emit. In this branch `inventory_reliable` is unavailable, so compute the failure-budget guard inline: when `warning_count / (skill_count + warning_count) > 0.20`, HALT (exit code 7, `halt_reason: "inventory-unreliable"`) with the same message as the primary path. In headless, emit the error envelope.
 
 ### 3. Validate Minimum Requirements
 
@@ -107,23 +110,15 @@ Each helper-emitted entry includes: `skill_name`, `version`, `language`, `confid
 - If undefined or empty → "**Cannot proceed.** `forge_data_folder` is not configured in config.yaml. Re-run [SF] Setup Forge to initialize."
 - HALT (exit code 3, `halt_reason: "forge-folder-unconfigured"`). In headless, emit the error envelope.
 
-**Check architecture document:**
-- Confirm it was loaded successfully in section 1
-- If not → HALT with error (should not reach here if section 1 validation passed)
-
 ### 4. Create Feasibility Report
 
-**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists: HALT (exit code 3, `halt_reason: "resolution-failure"`); in headless, emit the error envelope.
 
-**Resolve `{feasibilitySchemaRef}`** from `{feasibilitySchemaProbeOrder}`; first existing path wins (installed SKF module path first, dev-checkout `src/` fallback). HALT if no candidate exists.
+**Resolve `{feasibilitySchemaRef}`** from `{feasibilitySchemaProbeOrder}`; first existing path wins (installed SKF module path first, dev-checkout `src/` fallback). If no candidate exists: HALT (exit code 3, `halt_reason: "resolution-failure"`); in headless, emit the error envelope.
 
-This skill is the PRODUCER of the feasibility report schema defined in `{feasibilitySchemaRef}`. All outputs MUST conform to that schema — in particular: `schemaVersion: "1.0"`, the defined verdict token set (`Verified|Plausible|Risky|Blocked`; overall `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE`), the filename pattern, and the section-heading order.
+This skill produces the feasibility report schema defined in `{feasibilitySchemaRef}`; every output conforms to that schema — `schemaVersion: "1.0"`, the verdict token set (`Verified|Plausible|Risky|Blocked`; overall `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE`), the filename pattern, and the section-heading order.
 
-**Filename variables** (already computed at activation — do not re-derive):
-- `project_slug`: set in SKILL.md On Activation §2 from `project_name`
-- `timestamp`: set in SKILL.md On Activation §2 (UTC `YYYYMMDD-HHmmss`, fixed for the run)
-- `outputFile` resolves to `{outputFolderPath}/feasibility-report-{project_slug}-{timestamp}.md` per the stage frontmatter template
-- `outputFileLatest` resolves to `{outputFolderPath}/feasibility-report-{project_slug}-latest.md` (a copy, not a symlink — per schema)
+**Filename variables:** `project_slug` and `timestamp` were fixed at activation per SKILL.md On Activation §2; reuse them, do not re-derive. `{outputFile}` and `{outputFileLatest}` resolve from them per the stage frontmatter template — the latter a copy, not a symlink (per schema).
 
 **Load** `{reportTemplatePath}` (the customize-aware template path resolved in SKILL.md On Activation §4) and stage the initial content. Substitute the template's `Schema contract:` line `{feasibilitySchemaRef}` placeholder with the resolved schema path so every emitted report cites a path that exists on the running machine.
 
@@ -145,7 +140,7 @@ This skill is the PRODUCER of the feasibility report schema defined in `{feasibi
 - `skillsAnalyzed: {count}`
 - `stepsCompleted: ['init']`
 
-**Atomic write:** Pipe the staged content through `python3 {atomicWriteHelper} write --target {outputFile}` and then again with `--target {outputFileLatest}`. Both writes use the same staged content. Do NOT use `rm`+rewrite; do NOT create a symlink for the `-latest` copy.
+**Atomic write:** Pipe the staged content through `python3 {atomicWriteHelper} write --target {outputFile}` and then again with `--target {outputFileLatest}`. Both writes use the same staged content through the atomic helper — a plain `rm`+rewrite risks a partial write corrupting the report, and the `-latest` file is a copy, not a symlink (per the shared schema).
 
 On any non-zero exit from either write: HALT (exit code 4, `halt_reason: "write-failed"`) and emit the error envelope per SKILL.md "Result Contract (Headless)" with `report_path: null`, `report_latest_path: null`, `overall_verdict: null`.
 

package/src/skf-verify-stack/references/integration-verification-rules.md

@@ -12,9 +12,9 @@ Token set is defined canonically in the SKF shared feasibility report schema (`_
 
 | Verdict       | Meaning                                                                                        | Required Evidence                                                                                                                                                                                                                                                   |
 |---------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Verified**  | APIs demonstrably connect AND docs cross-reference each other                                  | Check 1 (language) passes with declared evidence; Check 3 (types) passes from cited `exports` signatures; **Check 4 (docs cross-reference) MUST pass with a literal substring/name citation** — without Check 4 evidence, cap at `Plausible`. Check 2 is best-effort only and cannot by itself promote to `Verified`. |
+| **Verified**  | APIs demonstrably connect and docs cross-reference each other                                  | Check 1 (language) passes with declared evidence; Check 3 (types) passes from cited `exports` signatures; **Check 4 (docs cross-reference) passes with a literal substring/name citation** — without Check 4 evidence, cap at `Plausible`. Check 2 is best-effort only and cannot by itself promote to `Verified`. |
 | **Plausible** | Checks pass but rely on inferred or indirect evidence                                          | Language + type checks pass; Check 2 uses inferred `protocols_inferred`/`data_formats_inferred` (prose scan); Check 4 is weak or missing (no literal cross-reference). This is the mandatory cap whenever Check 4 does not surface a literal citation.             |
-| **Risky**     | Type mismatch, protocol gap, or language boundary requiring a bridge                           | A clear gap exists (e.g., TypeScript↔Rust FFI needed) but a workaround is architecturally feasible — a named workaround MUST be cited in the recommendation                                                                                                        |
+| **Risky**     | Type mismatch, protocol gap, or language boundary requiring a bridge                           | A clear gap exists (e.g., TypeScript↔Rust FFI needed) but a workaround is architecturally feasible — cite a named workaround in the recommendation                                                                                                                 |
 | **Blocked**   | Fundamental incompatibility — no feasible integration path even with a bridge or adapter layer | The two libraries cannot exchange data in any documented way; requires replacing one of the libraries                                                                                                                                                              |
 
 **Promotion rule:** `Verified` requires Check 4 evidence. If Checks 1 and 3 pass but Check 4 fails (no literal substring/name citation from either skill's SKILL.md), the verdict is capped at `Plausible`. This rule is enforced by step 3 §4 and is the producer obligation declared in the shared schema.
@@ -27,22 +27,13 @@ For each integration pair (Library A ↔ Library B):
 
 ### 1. Language Boundary Check
 
-| A Language          | B Language                             | Assessment                                                                       |
-|---------------------|----------------------------------------|----------------------------------------------------------------------------------|
-| Same language       | Same language                          | No boundary — direct API calls possible                                          |
-| TypeScript ↔ Rust   | Requires FFI, IPC, or WebSocket bridge | Check if a bridge library exists in the stack (e.g., Tauri provides JS↔Rust IPC) |
-| TypeScript ↔ Python | Requires REST/gRPC/WebSocket bridge    | Typically not direct                                                             |
-| Any ↔ C/C++         | FFI available in most languages        | Check for bindings                                                               |
+- Same language on both sides → no boundary, direct API calls. Different languages → the integration needs a bridge (FFI, IPC, or a network protocol; the mechanism follows from the pair — e.g. C/C++ exposes FFI most languages can bind).
+- The load-bearing nudge: **check whether a bridge library already exists in the stack** before assuming one must be built (e.g., Tauri provides JS↔Rust IPC).
 
 ### 2. Protocol Compatibility Check
 
-| A Protocol                | B Protocol        | Assessment                                                  |
-|---------------------------|-------------------|-------------------------------------------------------------|
-| In-process (same runtime) | In-process        | Direct — function calls                                     |
-| HTTP/REST                 | HTTP/REST         | Network bridge — compatible if API endpoints match          |
-| WebSocket                 | WebSocket         | Real-time bridge — check message format compatibility       |
-| Shared filesystem         | Shared filesystem | Async — check format compatibility                          |
-| Embedded database         | Embedded database | May conflict on lock files — check for multi-writer support |
+- Matching transports are compatible modulo format alignment: both in-process → direct calls; both HTTP/REST → compatible if endpoints match; both WebSocket → check message-format compatibility; both shared-filesystem → async, check format.
+- The load-bearing nudge: **two embedded databases may conflict on lock files — check for multi-writer support** before treating them as compatible.
 
 ### 3. Type Compatibility Check
 
@@ -54,15 +45,15 @@ For each integration pair (Library A ↔ Library B):
 
 - Search Skill A's SKILL.md for a literal substring/name citation of Library B
 - Search Skill B's SKILL.md for the reciprocal citation
-- Accept literal names or aliases declared in that skill's metadata; do NOT accept paraphrase or fuzzy matches
-- A pass requires at least one literal citation in at least one direction; the exact substring and location MUST be recorded in the evidence block
-- If neither skill literally cites the other, Check 4 FAILS and the per-pair verdict MUST cap at `Plausible` (not `Verified`)
+- Accept literal names or aliases declared in that skill's metadata; a paraphrase or fuzzy match does not satisfy Check 4
+- A pass requires at least one literal citation in at least one direction; record the exact substring and location in the evidence block
+- If neither skill literally cites the other, Check 4 fails and the per-pair verdict caps at `Plausible` (not `Verified`)
 
 ---
 
 ## Verdict Evidence Format
 
-Each verdict MUST include:
+Each verdict includes:
 
 ```
 **{Library A} ↔ {Library B}: {VERDICT}**