bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/shared/scripts/schemas/skf-update-result-envelope.v1.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-update-result-envelope.v1.json",
+  "title": "SKF_UPDATE_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document emitted by skf-update-skill step 7 (report) when {headless_mode} is true, prefixed with the literal 'SKF_UPDATE_RESULT_JSON: '. Pipelines branch on the envelope's top-level fields without parsing the human-readable report. The `headless_decisions[]` array surfaces every auto-resolved gate so non-interactive runs can be audited post-hoc — previously these were buried in the evidence report as free-form log lines. Schema added in PR #319.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skf_update"],
+  "properties": {
+    "skf_update": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "skill_name",
+        "version",
+        "previous_version",
+        "update_mode",
+        "files_written",
+        "headless_decisions",
+        "warnings",
+        "error"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "success",
+            "no-changes",
+            "detect-only",
+            "dry-run",
+            "halted-for-workspace-drift",
+            "halted-for-brief-refinement",
+            "halted-for-audit",
+            "halted-for-remediation-path",
+            "halted-for-manual-mismatch",
+            "halted-for-write-failure",
+            "halted-for-concurrent-run",
+            "blocked"
+          ],
+          "description": "Single-field outcome for pipeline branching. 'success' when the run completed and wrote the updated artifacts. 'no-changes' when detect-changes found nothing to update. 'detect-only' when the workflow was invoked with --detect-only and exited after step 2 without modifying any artifact. 'dry-run' when the workflow was invoked with --dry-run and exited after step 3 (re-extract) without merging or writing — the envelope describes what merge+write WOULD have done. Each 'halted-for-*' value corresponds to a documented halt in the stage prose (workspace-drift from re-extract.md §0.a, brief-refinement from detect-changes.md §1c [U] / §2.2 [B], audit from §2.2 [A], remediation-path from re-extract.md §0a, manual-mismatch from write.md §1, write-failure for any §5b/§6 failure, concurrent-run from init.md §1b's PID-file collision check). 'blocked' is the catch-all for halts that don't map to a documented status code. NOTE: detect-only and dry-run are successful exits — pipelines treating non-success as failure must include them in the success set."
+        },
+        "skill_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Name of the skill being updated, read from metadata.json at workflow start."
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Version written this run. In gap-driven mode this equals previous_version (gap-driven runs do not bump). In normal mode this is either the detected source version or an incremented patch."
+        },
+        "previous_version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Version read from metadata.json at workflow start, before any write."
+        },
+        "update_mode": {
+          "type": "string",
+          "enum": ["normal", "gap-driven", "degraded"],
+          "description": "Which detect-changes path ran. 'normal' = provenance map present and source-drift detection ran. 'gap-driven' = --from-test-report path. 'degraded' = no provenance baseline (every export looks modified)."
+        },
+        "files_written": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["SKILL.md", "metadata.json", "provenance-map.json", "evidence-report.md", "context-snippet.md", "active-symlink"]
+          },
+          "uniqueItems": true,
+          "description": "Artifacts actually written or updated this run. Empty array when a halt fired before any write completed."
+        },
+        "headless_decisions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["gate", "default_action", "taken_action", "reason"],
+            "properties": {
+              "gate": {
+                "type": "string",
+                "enum": [
+                  "init.update-confirmation",
+                  "detect-changes.promoted-doc-prompt",
+                  "detect-changes.scope-expansion",
+                  "detect-changes.deletion-ratio",
+                  "merge.clean-merge-gate"
+                ],
+                "description": "Identifier for the gate. Matches the labels in stage prose so post-hoc audits can grep both directions."
+              },
+              "default_action": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The action documented as the default for this gate (e.g. 'C' for [C] Continue, 'S' for [S] Skip)."
+              },
+              "taken_action": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The action actually taken. In headless mode this almost always equals default_action — the field exists so future user-overrides via flags (e.g. --orphan-action style) can differ from defaults."
+              },
+              "reason": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Human-readable rationale (e.g. 'headless: no user to prompt')."
+              },
+              "evidence": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "Optional gate-specific data — for deletion-ratio, the ratio value and counts; for promoted-doc, the candidate path; etc. Pipelines that want the audit trail richer than reason can read this."
+              }
+            }
+          },
+          "description": "One entry per gate that auto-resolved during this run. Empty when no gates fired (no-changes path, or interactive run where the user resolved gates manually). The merge.clean-merge-gate entry never appears with taken_action=continue when the gate halted on conflicts — conflict halts produce a halted-for-* status instead."
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Non-fatal anomalies surfaced during the run. May include workspace_drift_overridden, scope_reconciliation_post entries, qmd indexing failures, etc. Empty when none."
+        },
+        "error": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["phase", "reason"],
+              "properties": {
+                "phase": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Step or operation that failed (e.g. 'write:active-symlink', 'init:provenance-load')."
+                },
+                "path": {
+                  "type": "string",
+                  "description": "Optional path the failed operation targeted (when applicable)."
+                },
+                "reason": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Human-readable error message."
+                }
+              }
+            }
+          ],
+          "description": "Null on success or no-changes. Object describing the failure when a halt or write error fired. Pipelines branch on error !== null for non-zero exit semantics."
+        }
+      }
+    }
+  }
+}

package/src/shared/scripts/schemas/skill-brief.v1.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skill-brief.v1.json",
   "title": "skill-brief.yaml (v1)",
-  "description": "Canonical schema for the skill-brief.yaml artifact written by skf-brief-skill step-05 and consumed by skf-create-skill, skf-update-skill, skf-audit-skill. Mirrors src/skf-brief-skill/assets/skill-brief-schema.md.",
+  "description": "Canonical schema for the skill-brief.yaml artifact written by skf-brief-skill step 5 and consumed by skf-create-skill, skf-update-skill, skf-audit-skill. Mirrors src/skf-brief-skill/assets/skill-brief-schema.md.",
   "type": "object",
   "required": ["name", "version", "source_repo", "language", "description", "forge_tier", "created", "created_by", "scope"],
   "properties": {
@@ -70,7 +70,27 @@
         },
         "include": { "type": "array", "items": { "type": "string" } },
         "exclude": { "type": "array", "items": { "type": "string" } },
-        "notes": { "type": "string" }
+        "notes": { "type": "string" },
+        "rationale": {
+          "type": "object",
+          "description": "Optional authoring-time scope-type decision record written once by skf-brief-skill step 03. Absent on legacy briefs.",
+          "required": ["recommended", "chosen", "accepted_recommendation", "heuristic", "reason", "recorded"],
+          "additionalProperties": false,
+          "properties": {
+            "recommended": {
+              "type": "string",
+              "enum": ["full-library", "specific-modules", "public-api", "component-library", "reference-app", "docs-only"]
+            },
+            "chosen": {
+              "type": "string",
+              "enum": ["full-library", "specific-modules", "public-api", "component-library", "reference-app", "docs-only"]
+            },
+            "accepted_recommendation": { "type": "boolean" },
+            "heuristic": { "type": "string", "minLength": 1 },
+            "reason": { "type": "string", "minLength": 1 },
+            "recorded": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }
+          }
+        }
       }
     }
   }

package/src/shared/scripts/skf-build-change-manifest.py

@@ -0,0 +1,420 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Build Change Manifest — aggregate category A/B/C/D detection results.
+
+`skf-update-skill/references/detect-changes.md §3` assembles the final
+change manifest from four category result streams the LLM (or its
+subprocess workers) produces upstream:
+
+  - Category A — file-level changes (modified/added/deleted)
+  - Category B — export-level changes (for MODIFIED files)
+  - Category C — rename detection (cross-files and cross-exports)
+  - Category D — script/asset file changes
+
+The aggregation itself is purely deterministic: count rollups, grouping
+exports under their owning file, deduplicating across categories, and
+emitting the canonical manifest shape that downstream stages consume.
+The §3 prose previously asked the LLM to count entries across four
+streams every run — the helper makes it one bash call with stable
+shape.
+
+The same script also implements §2.2's Major-Version Scope
+Reconciliation trigger (the deletion-ratio formula) — same input
+schema, plus the provenance map for the denominator.
+
+Subcommands:
+
+  build [--input <file>] [--no-changes-on-empty]
+      Reads category JSON from stdin or `--input <file>`, emits the
+      unified manifest envelope.
+
+  deletion-ratio --provenance-map <file> [--input <file>]
+      Same category JSON input. Reads provenance entries[] from
+      <file>, computes the §2.2 trigger envelope. Auto-skips when
+      degraded_mode or update_mode==gap-driven is set in the input.
+
+Input JSON shape (object on stdin or in --input file):
+
+  {
+    "category_a": {
+      "modified": ["path1", ...],
+      "added":    ["path2", ...],
+      "deleted":  ["path3", ...]
+    },
+    "category_b": {
+      "modified_exports": [{name, file, old_line, new_line}, ...],
+      "new_exports":      [{name, file, line}, ...],
+      "deleted_exports":  [{name, file, old_line}, ...],
+      "moved_exports":    [{name, file, old_line, new_line}, ...]
+    },
+    "category_c": {
+      "renamed_files":   [{old_path, new_path}, ...],
+      "renamed_exports": [{old_name, new_name, file}, ...]
+    },
+    "category_d": {
+      "scripts_modified": ["path", ...], "scripts_added": [...], "scripts_deleted": [...],
+      "assets_modified": [...],          "assets_added": [...],  "assets_deleted":  [...]
+    },
+    "degraded_mode": false,
+    "update_mode": "normal" | "gap-driven"  // optional; influences deletion-ratio only
+  }
+
+Every category and sub-key is optional — missing keys default to
+empty lists. This lets gap-driven runs (which produce no Category D
+results) and degraded runs (which skip Category B) feed the same
+script without sentinel values.
+
+Exit codes:
+  0  — operation succeeded
+  1  — user error (malformed JSON, bad path, malformed provenance file)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+# --------------------------------------------------------------------------
+# Input normalization
+# --------------------------------------------------------------------------
+
+
+def _get_list(d: dict, *path: str) -> list:
+    """Pluck a list out of a nested dict, defaulting to []."""
+    cur = d
+    for key in path:
+        if not isinstance(cur, dict):
+            return []
+        cur = cur.get(key)
+        if cur is None:
+            return []
+    return cur if isinstance(cur, list) else []
+
+
+def _load_input(input_path: Path | None) -> dict:
+    """Read JSON either from --input path or from stdin."""
+    if input_path is not None:
+        text = input_path.read_text(encoding="utf-8")
+    else:
+        text = sys.stdin.read()
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"input is not valid JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"input must be a JSON object, got {type(data).__name__}")
+    return data
+
+
+# --------------------------------------------------------------------------
+# Build manifest
+# --------------------------------------------------------------------------
+
+
+def build_manifest(payload: dict) -> dict:
+    """Aggregate category A/B/C/D into the unified manifest envelope."""
+    cat_a = payload.get("category_a", {}) or {}
+    cat_b = payload.get("category_b", {}) or {}
+    cat_c = payload.get("category_c", {}) or {}
+    cat_d = payload.get("category_d", {}) or {}
+
+    a_modified = _get_list(cat_a, "modified")
+    a_added = _get_list(cat_a, "added")
+    a_deleted = _get_list(cat_a, "deleted")
+
+    b_modified = _get_list(cat_b, "modified_exports")
+    b_new = _get_list(cat_b, "new_exports")
+    b_deleted = _get_list(cat_b, "deleted_exports")
+    b_moved = _get_list(cat_b, "moved_exports")
+
+    c_renamed_files = _get_list(cat_c, "renamed_files")
+    c_renamed_exports = _get_list(cat_c, "renamed_exports")
+
+    d = {
+        "scripts_modified": len(_get_list(cat_d, "scripts_modified")),
+        "scripts_added": len(_get_list(cat_d, "scripts_added")),
+        "scripts_deleted": len(_get_list(cat_d, "scripts_deleted")),
+        "assets_modified": len(_get_list(cat_d, "assets_modified")),
+        "assets_added": len(_get_list(cat_d, "assets_added")),
+        "assets_deleted": len(_get_list(cat_d, "assets_deleted")),
+    }
+
+    counts = {
+        "files_changed": len(a_modified),
+        "files_added": len(a_added),
+        "files_deleted": len(a_deleted),
+        "files_moved": len(c_renamed_files),
+        "exports_modified": len(b_modified),
+        "exports_new": len(b_new),
+        "exports_deleted": len(b_deleted),
+        "exports_renamed": len(c_renamed_exports),
+        "exports_moved": len(b_moved),
+        **d,
+    }
+
+    per_file = _build_per_file(
+        a_modified=a_modified,
+        a_added=a_added,
+        a_deleted=a_deleted,
+        c_renamed_files=c_renamed_files,
+        b_modified=b_modified,
+        b_new=b_new,
+        b_deleted=b_deleted,
+        b_moved=b_moved,
+    )
+
+    total_export_changes = (
+        counts["exports_modified"]
+        + counts["exports_new"]
+        + counts["exports_deleted"]
+        + counts["exports_renamed"]
+        + counts["exports_moved"]
+    )
+
+    no_changes = (
+        sum(counts.values()) == 0  # every count is zero
+    )
+
+    return {
+        "no_changes": no_changes,
+        "degraded_mode": bool(payload.get("degraded_mode")),
+        "counts": counts,
+        "total_export_changes": total_export_changes,
+        "per_file": per_file,
+    }
+
+
+def _build_per_file(
+    *,
+    a_modified: list,
+    a_added: list,
+    a_deleted: list,
+    c_renamed_files: list,
+    b_modified: list,
+    b_new: list,
+    b_deleted: list,
+    b_moved: list,
+) -> list[dict]:
+    """Group exports under their owning file path. Preserves stable ordering:
+    MODIFIED files first, then ADDED, then DELETED, then MOVED. Files within
+    each status sorted alphabetically by path."""
+    exports_by_file: dict[str, list[dict]] = {}
+
+    def _record(entry: dict, change_type: str) -> None:
+        path = entry.get("file")
+        if not path:
+            return
+        exports_by_file.setdefault(path, []).append({
+            "name": entry.get("name"),
+            "change_type": change_type,
+            "old_line": entry.get("old_line"),
+            "new_line": entry.get("new_line") or entry.get("line"),
+        })
+
+    for e in b_modified:
+        _record(e, "MODIFIED_EXPORT")
+    for e in b_new:
+        _record(e, "NEW_EXPORT")
+    for e in b_deleted:
+        _record(e, "DELETED_EXPORT")
+    for e in b_moved:
+        _record(e, "MOVED_EXPORT")
+
+    out: list[dict] = []
+
+    for path in sorted(a_modified):
+        out.append({
+            "file_path": path,
+            "status": "MODIFIED",
+            "exports_affected": exports_by_file.get(path, []),
+        })
+
+    for path in sorted(a_added):
+        out.append({
+            "file_path": path,
+            "status": "ADDED",
+            "exports_affected": exports_by_file.get(path, []),
+        })
+
+    for path in sorted(a_deleted):
+        out.append({
+            "file_path": path,
+            "status": "DELETED",
+            "exports_affected": exports_by_file.get(path, []),
+        })
+
+    # MOVED entries from Category C — emit one record per move with the new path
+    for move in sorted(c_renamed_files, key=lambda m: m.get("new_path") or ""):
+        new_path = move.get("new_path")
+        if new_path is None:
+            continue
+        out.append({
+            "file_path": new_path,
+            "status": "MOVED",
+            "old_path": move.get("old_path"),
+            "exports_affected": exports_by_file.get(new_path, []),
+        })
+
+    return out
+
+
+# --------------------------------------------------------------------------
+# Deletion ratio (§2.2)
+# --------------------------------------------------------------------------
+
+
+def compute_deletion_ratio(payload: dict, provenance: dict) -> dict:
+    """Compute the §2.2 deletion-ratio trigger envelope.
+
+    Skip conditions (per the §2.2 prose):
+      - update_mode == "gap-driven"
+      - degraded_mode is True
+      - provenance has zero entries (denominator would be zero)
+    """
+    if payload.get("update_mode") == "gap-driven":
+        return _ratio_skip(skip_reason="gap-driven")
+    if payload.get("degraded_mode"):
+        return _ratio_skip(skip_reason="degraded-mode")
+
+    entries = provenance.get("entries", [])
+    if not isinstance(entries, list):
+        raise ValueError("provenance `entries` must be an array")
+    total = len(entries)
+    if total == 0:
+        return _ratio_skip(skip_reason="zero-provenance-exports")
+
+    # Count exports under category A deleted files (via provenance lookup)
+    by_source: dict[str, int] = {}
+    for entry in entries:
+        sf = entry.get("source_file")
+        if isinstance(sf, str):
+            by_source[sf] = by_source.get(sf, 0) + 1
+
+    cat_a = payload.get("category_a", {}) or {}
+    deleted_files = _get_list(cat_a, "deleted")
+    deleted_in_files = sum(by_source.get(p, 0) for p in deleted_files)
+
+    cat_b = payload.get("category_b", {}) or {}
+    deleted_exports = len(_get_list(cat_b, "deleted_exports"))
+
+    deleted_export_count = deleted_in_files + deleted_exports
+    ratio = deleted_export_count / total
+
+    cat_c = payload.get("category_c", {}) or {}
+    renamed_or_moved = (
+        len(_get_list(cat_c, "renamed_files"))
+        + len(_get_list(cat_b, "moved_exports"))
+        + len(_get_list(cat_c, "renamed_exports"))
+    )
+
+    return {
+        "skip_reason": None,
+        "deleted_export_count": deleted_export_count,
+        "total_provenance_exports": total,
+        "deletion_ratio": ratio,
+        "deleted_file_count": len(deleted_files),
+        "added_in_scope_count": len(_get_list(cat_a, "added")),
+        "renamed_or_moved_count": renamed_or_moved,
+        "should_trigger": ratio >= 0.50,
+    }
+
+
+def _ratio_skip(*, skip_reason: str) -> dict:
+    return {
+        "skip_reason": skip_reason,
+        "deleted_export_count": 0,
+        "total_provenance_exports": 0,
+        "deletion_ratio": 0.0,
+        "deleted_file_count": 0,
+        "added_in_scope_count": 0,
+        "renamed_or_moved_count": 0,
+        "should_trigger": False,
+    }
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _cmd_build(args: argparse.Namespace) -> int:
+    try:
+        payload = _load_input(Path(args.input) if args.input else None)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    manifest = build_manifest(payload)
+    json.dump(manifest, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _cmd_deletion_ratio(args: argparse.Namespace) -> int:
+    try:
+        payload = _load_input(Path(args.input) if args.input else None)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    prov_path = Path(args.provenance_map)
+    if not prov_path.is_file():
+        print(f"error: provenance-map not found: {prov_path}", file=sys.stderr)
+        return 1
+    try:
+        provenance = json.loads(prov_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"error: provenance-map is not valid JSON: {exc}", file=sys.stderr)
+        return 1
+    try:
+        result = compute_deletion_ratio(payload, provenance)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    json.dump(result, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skf-build-change-manifest",
+        description=(
+            "Aggregate category A/B/C/D detection results into the unified "
+            "change manifest, OR compute the §2.2 deletion-ratio trigger."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_build = sub.add_parser("build", help="aggregate categories into manifest")
+    p_build.add_argument(
+        "--input", default=None, help="path to JSON input (default: stdin)"
+    )
+    p_build.set_defaults(func=_cmd_build)
+
+    p_ratio = sub.add_parser(
+        "deletion-ratio",
+        help="compute §2.2 trigger; requires --provenance-map",
+    )
+    p_ratio.add_argument(
+        "--input", default=None, help="path to JSON input (default: stdin)"
+    )
+    p_ratio.add_argument(
+        "--provenance-map", required=True, help="path to provenance-map.json"
+    )
+    p_ratio.set_defaults(func=_cmd_deletion_ratio)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())