bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/skf-test-skill/scripts/validate-inventory.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Deterministic schema validation of the §1 subagent inventory JSON.
+
+Structural validator for the SKF test-skill coverage step (coverage-check.md
+§1a "Schema validation" block). test-skill is a quality gate, so it must not
+trust subagent output blindly: before any downstream step consumes the
+documented inventory, the shape is validated. That validation is pure
+structural checking — strip wrapping fences, parse JSON, assert required keys
+and types, assert each export entry is a dict with a non-empty `name` and a
+`kind` drawn from a fixed enum, and assert each cross-check mismatch carries its
+five fields — with exactly one correct pass/fail per input and no
+interpretation of meaning. It is therefore script work, not prompt work; the
+prompt reads this verdict and owns the HALT decision plus the separate
+grep ground-truth spot-check.
+
+Distinct from reconcile-coverage.py (coverage numerator arithmetic) and
+compute-score.py (weight tables): this script only validates the *shape* of the
+subagent inventory and, on success, echoes the fence-stripped parsed inventory
+back so the prompt consumes it directly instead of re-parsing the raw response.
+
+CLI usage (mirrors reconcile-coverage.py):
+  uv run validate-inventory.py '<raw response>'                 # positional
+  uv run validate-inventory.py --json-input '<raw response>'    # explicit flag
+  echo '<raw response>' | uv run validate-inventory.py --stdin  # piped input
+
+Input: the subagent's RAW response text (JSON, optionally wrapped in a markdown
+code fence — a leading line of three backticks with an optional language tag and
+a trailing line of three backticks are stripped before parsing).
+
+Output (stdout, one object):
+  {
+    "valid": <bool>,             # true only when parse + every schema check pass
+    "violations": [<str>, ...],  # human-readable failures; empty when valid
+    "rejectedCount": <int>,      # count of malformed exports[] entries
+    "exportsCount": <int>,       # len(exports) when parsed; 0 otherwise
+    "inventory": {...} | null    # fence-stripped parsed inventory when valid; null otherwise
+  }
+
+Exit codes:
+  0  — inventory valid
+  1  — no input provided (usage error)
+  2  — inventory invalid (parse failure or schema violation; result JSON emitted)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+
+# Fixed enum for exports[].kind — the constructs SKF documents across languages
+# and skill types: JS/TS (function/class/type/constant/hook/interface/method),
+# Rust public-API items (struct/enum/trait/macro, alongside the shared
+# type/constant/function), and stack-composition scaffolds (adapter). Mirrors the
+# enum documented in coverage-check.md §1a.
+VALID_KINDS = (
+    "function",
+    "class",
+    "type",
+    "constant",
+    "hook",
+    "interface",
+    "method",
+    "struct",
+    "enum",
+    "trait",
+    "macro",
+    "adapter",
+)
+
+REQUIRED_MISMATCH_FIELDS = (
+    "export",
+    "skill_md_line",
+    "reference_file",
+    "reference_line",
+    "issue",
+)
+
+_FENCE_OPEN = re.compile(r"^```[A-Za-z0-9_-]*$")
+_FENCE_CLOSE = re.compile(r"^```$")
+
+
+def strip_fences(text):
+    """Remove a wrapping markdown code fence, matching coverage-check.md §1a step 1.
+
+    When the first non-empty line is three backticks (optionally with a language
+    tag) and the last non-empty line is three backticks, drop those two lines.
+    Otherwise return the text unchanged.
+    """
+    lines = text.split("\n")
+    non_empty_idx = [i for i, ln in enumerate(lines) if ln.strip()]
+    if len(non_empty_idx) < 2:
+        return text
+    first, last = non_empty_idx[0], non_empty_idx[-1]
+    if _FENCE_OPEN.match(lines[first].strip()) and _FENCE_CLOSE.match(lines[last].strip()):
+        kept = [ln for i, ln in enumerate(lines) if i != first and i != last]
+        return "\n".join(kept)
+    return text
+
+
+def validate_inventory(raw):
+    """Pure structural validation of the subagent inventory response.
+
+    `raw` is the raw response text. Returns the result dict documented in the
+    module docstring. Deterministic: identical input yields an identical verdict.
+    """
+    violations = []
+    inner = strip_fences(raw)
+    try:
+        data = json.loads(inner)
+    except json.JSONDecodeError as exc:
+        return {
+            "valid": False,
+            "violations": [f"subagent response not valid JSON: {exc.msg}"],
+            "rejectedCount": 0,
+            "exportsCount": 0,
+            "inventory": None,
+        }
+
+    if not isinstance(data, dict):
+        return {
+            "valid": False,
+            "violations": ["subagent response is not a JSON object"],
+            "rejectedCount": 0,
+            "exportsCount": 0,
+            "inventory": None,
+        }
+
+    exports = data.get("exports")
+    if not isinstance(exports, list):
+        violations.append(
+            "missing/typo: `exports` must be present and a list"
+        )
+        exports = []
+
+    cross = data.get("cross_check_mismatches")
+    if not isinstance(cross, list):
+        violations.append(
+            "missing/typo: `cross_check_mismatches` must be present and a list (may be empty)"
+        )
+        cross = []
+
+    # Per-entry export validation — count rejections.
+    rejected = 0
+    for idx, entry in enumerate(exports):
+        if not isinstance(entry, dict):
+            rejected += 1
+            continue
+        name = entry.get("name")
+        kind = entry.get("kind")
+        if not (isinstance(name, str) and name):
+            rejected += 1
+            continue
+        if kind not in VALID_KINDS:
+            rejected += 1
+            continue
+    if rejected > 0:
+        subject = "entry does" if rejected == 1 else "entries do"
+        violations.append(
+            f"{rejected} exports[] {subject} not match schema "
+            f"(each needs a non-empty string `name` and a `kind` in "
+            f"{{{', '.join(VALID_KINDS)}}})"
+        )
+
+    # Non-empty cross-check mismatch entries must carry all five fields.
+    for idx, entry in enumerate(cross):
+        if not isinstance(entry, dict):
+            violations.append(f"cross_check_mismatches[{idx}] is not an object")
+            continue
+        missing = [f for f in REQUIRED_MISMATCH_FIELDS if f not in entry]
+        if missing:
+            violations.append(
+                f"cross_check_mismatches[{idx}] missing field(s): {', '.join(missing)}"
+            )
+
+    valid = not violations
+    return {
+        "valid": valid,
+        "violations": violations,
+        "rejectedCount": rejected,
+        "exportsCount": len(exports),
+        "inventory": data if valid else None,
+    }
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="validate-inventory",
+        description=(
+            "Deterministic schema validation of the §1 subagent inventory JSON "
+            "(coverage-check.md §1a). Strips wrapping fences, parses, and asserts "
+            "the required-keys/types/enum/mismatch-field contract, returning "
+            "{valid, violations, rejectedCount, exportsCount, inventory}."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "raw_input",
+        nargs="?",
+        help="Raw subagent response as a positional argument.",
+    )
+    src.add_argument(
+        "--json-input",
+        dest="raw_input_flag",
+        help="Raw subagent response passed via flag (overrides positional).",
+    )
+    src.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read the raw subagent response from stdin.",
+    )
+    return parser
+
+
+def _resolve_input(args):
+    if args.stdin:
+        return sys.stdin.read()
+    if args.raw_input_flag is not None:
+        return args.raw_input_flag
+    if args.raw_input is not None:
+        return args.raw_input
+    return ""
+
+
+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
+
+    result = validate_inventory(raw)
+    print(json.dumps(result, indent=2))
+    return 0 if result["valid"] else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# 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.
+
+Input schema (one JSON object):
+  {
+    "declaredNames": ["foo", "Bar::baz", ...],  # metadata.exports[] / provenance declared set
+    "skillPackagePath": "/path/to/skill"        # SKILL.md ∪ references/*.md
+  }
+
+Output (stdout, one object):
+  {
+    "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
+    "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).
+
+CLI usage (mirrors reconcile-coverage.py):
+  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)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+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)
+
+
+def _validate(inp):
+    if inp is None or not isinstance(inp, dict):
+        return "Input must be a JSON object"
+    names = inp.get("declaredNames")
+    if not isinstance(names, list) or not names:
+        return "declaredNames must be a non-empty list of strings"
+    if not inp.get("skillPackagePath"):
+        return "skillPackagePath is required to grep SKILL.md ∪ references"
+    return None
+
+
+def verify(inp, doc_text=None):
+    """Pure verification. `doc_text` may be injected (tests); else loaded from disk."""
+    err = _validate(inp)
+    if err:
+        return make_error(err)
+
+    declared_set = sorted({n for n in inp["declaredNames"] if isinstance(n, str) and n})
+    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)
+
+    return {
+        "declared": len(declared_set),
+        "verified": len(present),
+        "present": present,
+        "absent": absent,
+        "inflated": len(present) < len(declared_set),
+    }
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="verify-declared-numerator",
+        description=(
+            "Deterministic numerator ground-truth verifier (coverage-check.md "
+            "§4b). 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."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Example:\n"
+            "  uv run verify-declared-numerator.py "
+            "'{\"declaredNames\":[\"foo\",\"bar\"],"
+            "\"skillPackagePath\":\"/path/to/skill\"}'"
+        ),
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "json_input",
+        nargs="?",
+        help="JSON object as a positional argument (single-quote it on the shell).",
+    )
+    src.add_argument(
+        "--json-input",
+        dest="json_input_flag",
+        help="JSON object passed via flag (overrides positional).",
+    )
+    src.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read the JSON object from stdin.",
+    )
+    return parser
+
+
+def _resolve_input(args):
+    if args.stdin:
+        return sys.stdin.read()
+    if args.json_input_flag is not None:
+        return args.json_input_flag
+    if args.json_input is not None:
+        return args.json_input
+    return ""
+
+
+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)
+    print(json.dumps(result, indent=2))
+    if isinstance(result, dict) and result.get("code") == "INVALID_INPUT":
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -12,6 +12,7 @@ Surgically updates existing skills when source code changes, preserving all [MAN
 ## 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.
 - `{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.
@@ -50,11 +51,11 @@ These rules apply to every step in this workflow:
 | 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); `--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. |
+| **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, updated 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) and by every documented halt path. 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. Pipeline branches on the envelope's top-level `status` field (`success`, `no-changes`, `detect-only`, `dry-run`, or one of the documented `halted-for-*` codes). The first four are successful exits — pipelines treating non-success as failure must include them in the success set. Schema: `src/shared/scripts/schemas/skf-update-result-envelope.v1.json`. |
+| **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`. |
 
 ## On Activation
 
@@ -64,4 +65,15 @@ These rules apply to every step in this workflow:
 
 2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
 
-3. Load, read the full file, and then execute `references/init.md` to begin the workflow.
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   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.
+
+   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.
+
+4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

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

@@ -1,6 +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})
 
 [workflow]
 
@@ -33,3 +35,15 @@ activation_steps_append = []
 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
+# command is called as:
+#   <on_complete> --result-path=<{forge_version}/update-skill-result-latest.json>
+# 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.
+#
+# Empty string = no-op (default).
+
+on_complete = ""

package/src/skf-update-skill/references/detect-changes.md

@@ -36,6 +36,10 @@ provenanceGapDispatchProbeOrder:
 detectScriptsAssetsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-scripts-assets.py'
   - '{project-root}/src/shared/scripts/skf-detect-scripts-assets.py'
+# `{newFileDiffHelper}` derives NEW_FILE (inventory source_files not in the
+# provenance map, minus [MANUAL] paths) — the set-difference §Category D would
+# otherwise ask the model to compute by hand. Per-skill helper, always bundled.
+newFileDiffHelper: 'scripts/skf-new-file-diff.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -51,7 +55,7 @@ Compare current source code state against the provenance map to produce a comple
 - Focus only on detecting and classifying changes — do not extract or merge
 - Use subprocess Pattern 4 (parallel) when available; if unavailable, compare sequentially
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 0. Check for Test Report Input (Gap-Driven Mode)
 
@@ -105,7 +109,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
 ### 1b. Discovered Authoritative Files Protocol (Mirror)
 
-**Purpose:** mirror `skf-create-skill` §2a into update-skill. `skf-create-skill` §2a catches authoritative AI documentation files (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.) during **creation**. But a project may add these files *after* the skill was created — for example, an upstream project adopts an `llms.txt` convention six months into development. Without this mirror, update-skill would either miss the new file entirely (if it doesn't match the provenance map's file patterns) or classify it as a generic ADDED file in §2 Category A with no authoritative-file treatment. The mirror surfaces the discovery with the same P/S/U prompt create-skill uses, honoring any prior amendments.
+**Purpose:** mirror `skf-create-skill` §2a into update-skill. `skf-create-skill` §2a catches authoritative AI documentation files (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.) during **creation**, but a project may add these files *after* the skill was created. Without this mirror, update-skill would either miss the new file entirely (if it doesn't match the provenance map's file patterns) or classify it as a generic ADDED file in §2 Category A with no authoritative-file treatment. The mirror surfaces the discovery with the same P/S/U prompt create-skill uses, honoring any prior amendments.
 
 **Skip this section entirely if:**
 
@@ -177,11 +181,11 @@ Read the source directory at `{source_root}` and build a current file inventory:
 
 **Record for evidence report:** the update-skill evidence report appends `authoritative_files_mirror: {candidates: N, promoted: P, skipped: S, pre_decided: A, already_tracked: T, decisions: [{path, action, heuristic, reason}]}`.
 
-**Interaction with §2 change detection:** promoted docs live in `promoted_docs_new[]`, NOT in the change manifest. But §2 Category A ("files in source but not in provenance map → ADDED") would still find the promoted doc files on disk and classify them as ADDED if nothing prevents it. The coordination mechanism is an explicit pre-filter exclusion set built in §2.0 (below) that every Category A subprocess worker receives as an input before it starts scanning. See §2.0 for the exact contract. The exclusion set is the only mechanism guaranteeing that parallel subprocesses cannot double-count `promoted_docs_new[]` paths — prose-level "skip any path" instructions cannot cross subprocess boundaries.
+**Interaction with §2 change detection:** promoted docs live in `promoted_docs_new[]`, not in the change manifest. §2.0's `change_detection_excludes` set (built below) is what stops §2 Category A from re-classifying them as ADDED — it is the only coordination that survives across the parallel Category A subprocesses.
 
 ### 1c. Major-Version Scope Reconciliation (Pre-Detection)
 
-**Purpose:** When upstream undergoes a paradigm shift (rebrand, package restructure, major-version rewrite), the brief's `scope.include` no longer reflects the real public API. §1b handles new authoritative-doc files; §1c handles new **code globs** that fall outside the original scope. Without it, update-skill silently misses the new surface and pays the gap cost on every future update — the cocoindex `0.3.37 → 1.0.0` and cognee `0.5.8 → 1.0.0` runs are existence proofs that this case is real and recurring.
+**Purpose:** §1b handles new authoritative-doc files; §1c handles new **code globs** that fall outside the original scope when upstream restructures (rebrand, package restructure, major-version rewrite) so the brief's `scope.include` no longer reflects the real public API. Without it, update-skill silently misses the new public surface and pays the gap cost on every future update.
 
 **Skip this section entirely if:**
 
@@ -233,7 +237,7 @@ Read the source directory at `{source_root}` and build a current file inventory:
      - `status: "pre-decided-demoted"` → record as `pre_decided`; do not re-prompt (`prior_action` ∈ `demoted-include`, `demoted-exclude`).
      - `status: "unresolved"` → continue to step 4 (user prompt).
 
-   **Note:** the Out-of-Scope section is an optional audit-skill output. `skf-audit-skill` does not currently discover new files (per `src/skf-audit-skill/references/re-index.md` — new-file detection is the responsibility of update-skill). The section is a forward-looking integration point: manual additions or a future audit-skill enhancement populate it.
+   **Note:** the Out-of-Scope section is an optional audit-skill output and is often absent or empty — new-file detection is update-skill's job (§1b/§2.2), not audit-skill's — so the `no-report` / `no-candidates` paths above are the common case.
 
 3. **Prompt for each unresolved candidate.** Present the same menu shape as §1b:
 
@@ -358,15 +362,14 @@ Translate the helper's output into the change manifest:
 - `DELETED_FILE` rows → add to manifest as DELETED_FILE
 - `UNCHANGED` rows → omit from the manifest (no action needed)
 
-The helper does NOT detect NEW_FILE — its job is provenance comparison only. Detect new files by running the same deterministic detector create-skill step 3 §4c uses (resolved via `detectScriptsAssetsProbeOrder`) against the current source tree:
+The compare helper reports only tracked files; NEW_FILE detection (a file present in source but absent from the provenance map) is a set-difference, so it runs through a script rather than the prompt. Pipe the same deterministic detector create-skill step 3 §4c uses (resolved via `detectScriptsAssetsProbeOrder`) into `{newFileDiffHelper}`, which subtracts the provenance map's `file_entries[].source_file` and sets aside user-authored `[MANUAL]` paths:
 
 ```bash
-uv run {detectScriptsAssetsHelper} detect <source-root>
+uv run {detectScriptsAssetsHelper} detect <source-root> \
+    | uv run {newFileDiffHelper} {forge_version}/provenance-map.json
 ```
 
-It emits `scripts_inventory[]` and `assets_inventory[]` (each entry carries `source_file`). Take every `source_file` across both inventories, then subtract the paths already present in `provenance.file_entries[].source_file`. Of the remaining files, those matching detection patterns (`scripts/`, `bin/`, `assets/`, `templates/`) and NOT under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are NEW_FILE.
-
-Files in `scripts/[MANUAL]/` or `assets/[MANUAL]/` → SKIP (user-authored, preserved).
+It emits `{"new_files":[{source_file, kind}], "skipped_manual":[...], "already_tracked":[...], "stats":{...}}`. Add each `new_files[]` entry to the manifest as NEW_FILE — `kind` (`script`/`asset`) selects the target array. `skipped_manual[]` are user-authored files under `scripts/[MANUAL]/` or `assets/[MANUAL]/`, preserved and not touched; `already_tracked[]` were handled by the compare above.
 
 Aggregate all subprocess results into a unified change manifest.
 
@@ -429,8 +432,6 @@ The upstream surface appears to have been substantially replaced. The brief's
 - **[B] Brief:** halt with status `halted-for-brief-refinement`. Display: `"Halting update-skill. Re-run skf-brief-skill to refine scope for {skill_name}, then re-run skf-update-skill."` Change manifest discarded — no partial writes.
 - **[A] Audit:** halt with status `halted-for-audit`. Display: `"Halting update-skill. Run skf-audit-skill against {skill_name} to map the new surface — its drift report will feed §1c on the next update-skill run."` Change manifest discarded.
 
-**Why both §1c and §2.2:** §1c is precise (per-path P/S/U) but requires upstream signal from audit-skill. §2.2 is coarse (single halt/continue) but self-contained — it fires even when the user runs update-skill directly without audit. Together they cover the major-version case across the two real workflows.
-
 ### 3. Build Change Manifest
 
 Hand the assembled Category A/B/C/D JSON to the helper:
@@ -490,7 +491,7 @@ The skill `{skill_name}` is current — no update needed.
 
 → Skip steps 03-06, immediately load {noChangeReportFile} with "no changes" status.
 
-### 5. Display Change Summary and Auto-Proceed
+### 5. Display Change Summary and Route
 
 "**Change Detection Complete:**
 
@@ -500,30 +501,11 @@ The skill `{skill_name}` is current — no update needed.
 | Files added | {count} |
 | Files deleted | {count} |
 | Files moved/renamed | {count} |
-| Exports affected | {total_export_changes} |
-
-**Proceeding to re-extraction of {affected_file_count if normal mode, or gap_count if gap-driven mode} changes...**"
-
-### 6. Present MENU OPTIONS
-
-Display: "**Proceeding to re-extraction...**"
-
-#### Menu Handling Logic:
-
-- **If `detect_only_mode` is true:** display "**Detect-only mode — skipping re-extract/merge/validate/write.** Loading report..." and load `{noChangeReportFile}` (report.md). The report handles the detect-only envelope. Do NOT load `{nextStepFile}`.
-- Else, after change manifest is built, immediately load, read entire file, then execute `{nextStepFile}`.
-- **EXCEPTION:** If no changes detected (section 4), load `{noChangeReportFile}` instead.
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after change detection completes (or to report when `detect_only_mode` is true)
-
-## CRITICAL STEP COMPLETION NOTE
+| Exports affected | {total_export_changes} |"
 
-ONLY WHEN the change manifest is fully built will you load the next file:
+This step auto-proceeds — no user choices. Once the change manifest is fully built, load and fully read the next file, then execute it, per the branch that applies:
 
-- `detect_only_mode == true` → load `{noChangeReportFile}` (report.md). Report emits status `detect-only`.
-- No changes detected → load `{noChangeReportFile}` (report.md). Report emits status `no-changes`.
-- Otherwise → load `{nextStepFile}` (re-extract.md) to begin re-extraction.
+- **`detect_only_mode == true`** → display "**Detect-only mode — skipping re-extract/merge/validate/write.** Loading report..." and load `{noChangeReportFile}` (report.md), which emits status `detect-only`. Do not load `{nextStepFile}`.
+- **No changes detected** (section 4) → load `{noChangeReportFile}` (report.md), which emits status `no-changes`.
+- **Otherwise** → display "**Proceeding to re-extraction of {affected_file_count if normal mode, or gap_count if gap-driven mode} changes...**" and load `{nextStepFile}` (re-extract.md) to begin re-extraction.