bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/shared/scripts/skf-detect-docs.py

@@ -38,6 +38,42 @@ Exit codes:
   0  found >=1 documentation source
   1  no documentation sources found (empty array)
   2  error (invalid args, gh not found, etc.)
+
+---------------------------------------------------------------------------
+Subcommand: compare-hashes
+---------------------------------------------------------------------------
+
+Doc-drift detection for audit-skill.  Given a set of tracked doc sources
+(each `{url, content_hash}`), re-fetch every URL, hash the response bytes with
+the SAME fetch+sha256 primitive the compile side used, and classify each entry
+as changed / unchanged / fetch_failed / skipped_null_hash.  This replaces the
+per-URL fetch/hash/compare/count prose at
+`src/skf-audit-skill/references/step-doc-drift.md` §2-3 — the model no longer
+orchestrates HTTP GETs or computes sha256 by hand, and correctness no longer
+depends on whether a WebFetch tool is wired.
+
+  uv run src/shared/scripts/skf-detect-docs.py compare-hashes <source>
+
+Input `<source>`:
+  - a path to a JSON file that is EITHER an array of `{url, content_hash}`
+    entries OR an object with a `doc_sources` array (e.g. a skill's
+    metadata.json), OR
+  - `-` to read that JSON from stdin.
+
+Output (JSON object on stdout):
+  {
+    "changed":           [{"url","old_hash","new_hash"}],
+    "unchanged":         [{"url"}],
+    "fetch_failed":      [{"url","old_hash","reason"}],
+    "skipped_null_hash": [{"url"}],
+    "stats": {"total_tracked","changed","unchanged",
+              "fetch_failed","skipped_null_hash"}
+  }
+
+Each list is stably sorted by url.  Stored hashes are normalized (leading
+`algo:` prefix stripped) before comparison so a bare-hex writer form still
+matches.  Exit 0 on any well-formed input (never blocks the informational
+audit); exit 2 on malformed args or JSON.
 """
 
 from __future__ import annotations
@@ -47,12 +83,13 @@ import base64
 import hashlib
 import json
 import re
+import socket
 import subprocess
 import sys
 import urllib.error
 import urllib.request
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 _GITHUB_URL_RE = re.compile(
     r"https?://(?:www\.)?github\.com/([^/\s]+)/([^/\s.]+?)(?:\.git)?/?$",
@@ -224,6 +261,57 @@ def _fetch_and_hash(url: str) -> Optional[str]:
         return None
 
 
+# Leading algorithm-name prefix on a stored hash (`sha256:`, `sha1:`, ...) so a
+# bare-hex writer form and the prefixed form compare equal.
+_HASH_PREFIX_RE = re.compile(r"^[a-z0-9]+:")
+
+
+def _normalize_hash(value: Optional[str]) -> Optional[str]:
+    """Strip a leading `algo:` prefix from a hash so bare-hex and prefixed
+    forms compare equal. Returns None for non-string input. Idempotent."""
+    if not isinstance(value, str):
+        return None
+    return _HASH_PREFIX_RE.sub("", value, count=1)
+
+
+def _fetch_and_hash_reason(url: str) -> Tuple[Optional[str], Optional[str]]:
+    """Byte-symmetric sibling of `_fetch_and_hash` that surfaces WHY a fetch
+    failed for drift reporting.
+
+    Uses the identical fetch+sha256 primitive as the compile side — same
+    `USER_AGENT`, same `_FETCH_TIMEOUT`, sha256 of the raw response bytes with
+    the `sha256:` prefix — so a hash produced here compares byte-for-byte
+    against a `content_hash` written by `_fetch_and_hash` at compile time.
+
+    Returns `(content_hash, None)` on success or `(None, reason)` on failure.
+    Never raises: the doc-drift audit must never abort on a bad URL.
+    """
+    if url.startswith("file://"):
+        local_path = url[7:]
+        try:
+            with open(local_path, "rb") as fh:
+                content = fh.read()
+        except OSError as exc:
+            return None, f"local read failed: {exc}"
+        return "sha256:" + hashlib.sha256(content).hexdigest(), None
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    try:
+        with urllib.request.urlopen(req, timeout=_FETCH_TIMEOUT) as resp:
+            content = resp.read()
+    except urllib.error.HTTPError as exc:
+        return None, f"HTTP {exc.code}"
+    except (socket.timeout, TimeoutError):
+        return None, f"timeout after {_FETCH_TIMEOUT}s"
+    except urllib.error.URLError as exc:
+        reason = getattr(exc, "reason", exc)
+        if isinstance(reason, (socket.timeout, TimeoutError)):
+            return None, f"timeout after {_FETCH_TIMEOUT}s"
+        return None, f"URL error: {reason}"
+    except Exception as exc:  # never let a malformed URL crash the audit
+        return None, f"fetch failed: {exc}"
+    return "sha256:" + hashlib.sha256(content).hexdigest(), None
+
+
 # ---------------------------------------------------------------------------
 # Detection method 1 — homepageUrl
 # ---------------------------------------------------------------------------
@@ -376,11 +464,154 @@ def detect(
     return deduped
 
 
+# ---------------------------------------------------------------------------
+# compare-hashes subcommand — doc-drift detection for audit-skill
+# ---------------------------------------------------------------------------
+
+def _load_doc_sources(raw_text: str, source_label: str) -> List[Any]:
+    """Parse a compare-hashes input blob into a list of doc-source entries.
+
+    Accepts either a top-level JSON array of `{url, content_hash}` entries or a
+    top-level object with a `doc_sources` array (e.g. a skill's metadata.json).
+    An object without `doc_sources` yields an empty list (nothing tracked).
+
+    Raises ValueError on malformed JSON or an unexpected top-level shape.
+    """
+    try:
+        data = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"malformed JSON in {source_label}: {exc}") from exc
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        entries = data.get("doc_sources")
+        if entries is None:
+            return []
+        if not isinstance(entries, list):
+            raise ValueError(f"`doc_sources` in {source_label} is not an array")
+        return entries
+    raise ValueError(
+        f"{source_label} must be a JSON array or an object with a "
+        f"`doc_sources` array; got {type(data).__name__}"
+    )
+
+
+def compare_doc_hashes(doc_sources: List[Any]) -> Dict[str, Any]:
+    """Fetch/hash/compare each tracked doc source and categorize it.
+
+    Deterministic: the same entries served the same upstream bytes always
+    yield the same categorization. Every entry lands in exactly one bucket, so
+    `stats.total_tracked` == the sum of the four category counts.
+    """
+    changed: List[Dict[str, Any]] = []
+    unchanged: List[Dict[str, Any]] = []
+    fetch_failed: List[Dict[str, Any]] = []
+    skipped_null_hash: List[Dict[str, Any]] = []
+
+    for entry in doc_sources:
+        if not isinstance(entry, dict):
+            fetch_failed.append(
+                {"url": "", "old_hash": None, "reason": "invalid entry: not an object"}
+            )
+            continue
+        url = entry.get("url")
+        if not isinstance(url, str) or not url:
+            fetch_failed.append({
+                "url": url if isinstance(url, str) else "",
+                "old_hash": entry.get("content_hash"),
+                "reason": "invalid entry: missing url",
+            })
+            continue
+        stored = entry.get("content_hash")
+        if stored is None:
+            # No baseline hash was recorded at compile time — nothing to
+            # compare against, so skip the fetch entirely.
+            skipped_null_hash.append({"url": url})
+            continue
+        new_hash, reason = _fetch_and_hash_reason(url)
+        if new_hash is None:
+            fetch_failed.append({"url": url, "old_hash": stored, "reason": reason})
+        elif _normalize_hash(new_hash) == _normalize_hash(stored):
+            unchanged.append({"url": url})
+        else:
+            changed.append({"url": url, "old_hash": stored, "new_hash": new_hash})
+
+    changed.sort(key=lambda e: e["url"])
+    unchanged.sort(key=lambda e: e["url"])
+    fetch_failed.sort(key=lambda e: e["url"])
+    skipped_null_hash.sort(key=lambda e: e["url"])
+
+    total = len(changed) + len(unchanged) + len(fetch_failed) + len(skipped_null_hash)
+    return {
+        "changed": changed,
+        "unchanged": unchanged,
+        "fetch_failed": fetch_failed,
+        "skipped_null_hash": skipped_null_hash,
+        "stats": {
+            "total_tracked": total,
+            "changed": len(changed),
+            "unchanged": len(unchanged),
+            "fetch_failed": len(fetch_failed),
+            "skipped_null_hash": len(skipped_null_hash),
+        },
+    }
+
+
+def _cmd_compare_hashes(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-detect-docs.py compare-hashes",
+        description=(
+            "Re-fetch each tracked doc URL, hash the response bytes, and "
+            "compare against the stored content_hash to detect doc drift."
+        ),
+    )
+    parser.add_argument(
+        "source",
+        help=(
+            "path to a JSON file (array of {url, content_hash} entries, or an "
+            "object with a doc_sources array such as metadata.json), or - to "
+            "read that JSON from stdin"
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    if args.source == "-":
+        raw = sys.stdin.read()
+        label = "<stdin>"
+    else:
+        path = Path(args.source)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            json.dump({"error": f"cannot read {path}: {exc}", "code": "READ_ERROR"}, sys.stderr)
+            sys.stderr.write("\n")
+            return 2
+        label = str(path)
+
+    try:
+        doc_sources = _load_doc_sources(raw, label)
+    except ValueError as exc:
+        json.dump({"error": str(exc), "code": "INVALID_JSON"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    result = compare_doc_hashes(doc_sources)
+    json.dump(result, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # CLI entry point
 # ---------------------------------------------------------------------------
 
 def main() -> int:
+    # Additive subcommand: route `compare-hashes ...` to the doc-drift path
+    # before the existing detect parser runs. The default (no subcommand)
+    # invocation `--repo-url <url> ...` is unchanged.
+    if len(sys.argv) > 1 and sys.argv[1] == "compare-hashes":
+        return _cmd_compare_hashes(sys.argv[2:])
+
     parser = argparse.ArgumentParser(
         description="Detect documentation URLs for a GitHub repository.",
     )

package/src/shared/scripts/skf-detect-language.py

@@ -58,6 +58,16 @@ Output (JSON on stdout):
   detection_source  — human-readable string naming what fired (manifest
                        basename, extension share, etc.)
   fallback_to_extension_frequency — bool (true when rule 10 fired)
+  detected_languages — ordered, deduplicated list of EVERY manifest-level
+                       match in the same priority order the winner walk uses.
+                       language == detected_languages[0] whenever the manifest
+                       table fired, so a caller can auto-pick detected_languages[0]
+                       and gate multi-language disambiguation on
+                       len(detected_languages) > 1. Special cases: a
+                       workspace_signal override (rule 0) is decisive and returns
+                       a single-element [language]; the extension-frequency
+                       fallback (rule 10) contributes [language] for a best guess
+                       or [] when language is "unknown".
 
 Exit codes:
   0 — recommendation produced (even when language is "unknown")
@@ -201,7 +211,74 @@ def _frequency_fallback(tree: list[str]) -> dict[str, Any]:
     }
 
 
+def _detected_languages(payload: dict[str, Any], winner: dict[str, Any]) -> list[str]:
+    """Accumulate every manifest-level match into an ordered, deduplicated list.
+
+    The walk mirrors the winner-selection priority order exactly, so
+    winner["language"] == detected_languages[0] whenever the manifest table
+    fired. Two decisive short-circuits diverge from a full walk on purpose:
+
+      * A workspace_signal override (rule 0) is authoritative — the workspace
+        root language wins over any nested package.json, so this returns a
+        single-element [winner_language] and never surfaces a spurious
+        multi-language gate for what workspace detection already resolved.
+      * When no manifest matched (rule 10 fired), the list carries the
+        extension-frequency best guess as a single element, or [] when the
+        guess was "unknown".
+    """
+    tree: list[str] = payload["tree"]  # validated non-empty by _winner()
+
+    workspace_signal = payload.get("workspace_signal")
+    if isinstance(workspace_signal, str) and workspace_signal in _WORKSPACE_SIGNAL_LANGUAGE:
+        return [winner["language"]]
+
+    langs: list[str] = []
+
+    def add(lang: str) -> None:
+        if lang not in langs:
+            langs.append(lang)
+
+    # Rule 1 — package.json (tsconfig.json disambiguation)
+    if _has_basename(tree, "package.json"):
+        add("typescript" if _has_basename(tree, "tsconfig.json") else "javascript")
+
+    # Rules 2-6 / 8 / 10 — single-basename manifests (same order as _MANIFEST_RULES)
+    for basename, language, _source in _MANIFEST_RULES:
+        if _has_basename(tree, basename):
+            add(language)
+
+    # Rule 7b — build.gradle (Groovy) Java/Kotlin disambiguation
+    if _has_basename(tree, "build.gradle"):
+        add("kotlin" if _has_path_segment(tree, "src/main/kotlin/") else "java")
+
+    # Rules 8-9 — suffix-based (csproj, sln)
+    for suffix, language, _source in _SUFFIX_RULES:
+        if _has_suffix(tree, suffix):
+            add(language)
+
+    if langs:
+        return langs
+
+    # No manifest matched — the winner came from the extension-frequency
+    # fallback (rule 10). Carry its best guess, or [] when it was "unknown".
+    fallback_language = winner["language"]
+    return [] if fallback_language == "unknown" else [fallback_language]
+
+
 def detect(payload: dict[str, Any]) -> dict[str, Any]:
+    """Apply the documented rule walk and annotate the full manifest match set.
+
+    Returns the single-winner envelope (language/confidence/detection_source/
+    fallback_to_extension_frequency) unchanged, plus detected_languages[] — the
+    ordered, deduplicated set of every manifest-level match — so a caller can
+    both auto-pick and gate multi-language disambiguation off one JSON shape.
+    """
+    winner = _winner(payload)
+    winner["detected_languages"] = _detected_languages(payload, winner)
+    return winner
+
+
+def _winner(payload: dict[str, Any]) -> dict[str, Any]:
     """Apply the documented rule walk. Always returns a recommendation."""
     tree = payload.get("tree")
     if not isinstance(tree, list):

package/src/shared/scripts/skf-detect-tools.py

@@ -79,6 +79,25 @@ DETECT_OUTPUT_SCHEMA (v1):
       "requested":     "Quick"|"Forge"|"Forge+"|"Deep"|null,
       "satisfied":     bool|null,
       "missing_tools": [str]
+    },
+    "prior": {
+      # Populated from --prior-state-from's forge-tier.yaml (first run: all null/empty).
+      "previous_tier":                          "Quick"|"Forge"|"Forge+"|"Deep"|null,
+      "previous_detection_date":                str|null,
+      "previous_tools":                         {tool: bool, ...},
+      "previous_ccc_index_status":              str|null,
+      "previous_ccc_indexed_path":              str|null,
+      "previous_ccc_last_indexed":              str|null,
+      "previous_ccc_staleness_threshold_hours": int|null,
+      # Deterministic CCC-index freshness verdict — computed against
+      # --project-root and datetime.now(UTC) captured at detect time, so the
+      # ccc-index.md step branches on a boolean instead of doing timestamp math.
+      "ccc_index_fresh":                        bool
+    },
+    "deltas": {
+      "tools_added":   [str],
+      "tools_removed": [str],
+      "tier_changed":  bool
     }
   }
 """
@@ -93,6 +112,7 @@ import subprocess
 import sys
 import tempfile
 from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
 
 
 VALID_TIERS = ("Quick", "Forge", "Forge+", "Deep")
@@ -219,8 +239,13 @@ def probe_ccc() -> dict:
         # `ccc` resolved to a foreign binary (e.g. code2prompt alias). Refuse.
         return {"available": False, "daemon": None, "version": None}
 
-    rc_doctor, doctor_stdout, _ = _run(["ccc", "doctor"])
-    version = _first_line(doctor_stdout) or _first_line(stdout)
+    rc_doctor, _, _ = _run(["ccc", "doctor"])
+    # ccc exposes no version CLI: `ccc --version` prints a usage banner, and
+    # `ccc doctor` / `ccc --help` lead with a settings header ("Global
+    # Settings") or usage line — never a version string. Capturing that first
+    # line mislabels a header as a version, so report daemon health (below)
+    # as ccc's identifier instead of a misparse.
+    version = None
     if rc_doctor == 0:
         return {"available": True, "daemon": "healthy", "version": version}
     # Distinguishing "stopped" from "error" requires parsing doctor output;
@@ -337,6 +362,73 @@ def read_prior_state(prior_state_path) -> dict:
     }
 
 
+def _parse_iso_timestamp(value) -> datetime | None:
+    """Parse an ISO 8601 timestamp into a timezone-aware datetime, or None.
+
+    Normalizes a trailing 'Z' (UTC designator) to '+00:00' because
+    `datetime.fromisoformat` does not accept 'Z' on Python < 3.11 and
+    requires-python here is >=3.10. A naive result (no tzinfo) is assumed to be
+    UTC so it can be compared against a tz-aware `now` without raising. Returns
+    None on any parse failure (non-string, empty, malformed).
+    """
+    if not isinstance(value, str):
+        return None
+    text = value.strip()
+    if not text:
+        return None
+    if text[-1] in ("Z", "z"):
+        text = text[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(text)
+    except (ValueError, TypeError):
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def compute_ccc_index_fresh(prior: dict, project_root, now: datetime) -> bool:
+    """Deterministic freshness verdict for a prior CCC index.
+
+    Replaces the ISO-8601 datetime arithmetic that ccc-index.md §2 used to ask
+    the model to perform (parse a timestamp, subtract from now, convert to
+    hours, compare against a threshold). Same inputs → same boolean.
+
+    Returns True only when ALL hold:
+      - the prior index covered this same project (indexed_path == project_root)
+      - the prior index status is "fresh" or "created"
+      - last_indexed parses AND (now - last_indexed) <= staleness threshold
+
+    The staleness threshold defaults to 24 hours when the prior field is null
+    (matching the ccc-index.md §2 default). Any null/unparseable required field
+    (indexed_path, status, last_indexed), path mismatch, non-fresh status,
+    unparseable threshold, or over-threshold delta yields False.
+    """
+    if not project_root:
+        return False
+    if prior.get("previous_ccc_indexed_path") != project_root:
+        return False
+    if prior.get("previous_ccc_index_status") not in ("fresh", "created"):
+        return False
+
+    last_indexed = _parse_iso_timestamp(prior.get("previous_ccc_last_indexed"))
+    if last_indexed is None:
+        return False
+
+    threshold = prior.get("previous_ccc_staleness_threshold_hours")
+    if threshold is None:
+        threshold = 24
+    try:
+        threshold_hours = float(threshold)
+    except (ValueError, TypeError):
+        return False
+
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+    delta_hours = (now - last_indexed).total_seconds() / 3600.0
+    return delta_hours <= threshold_hours
+
+
 def detect(args: argparse.Namespace) -> dict:
     tools: dict = {}
     with ThreadPoolExecutor(max_workers=4) as ex:
@@ -389,6 +481,9 @@ def detect(args: argparse.Namespace) -> dict:
         require_satisfied = None
 
     prior = read_prior_state(getattr(args, "prior_state_from", None))
+    prior["ccc_index_fresh"] = compute_ccc_index_fresh(
+        prior, getattr(args, "project_root", None), datetime.now(timezone.utc)
+    )
     deltas = compute_deltas(tools, prior, calculated)
 
     return {
@@ -470,6 +565,14 @@ def main() -> None:
         help="Environment variable name to check for security-scan availability"
              " (informational only — does NOT affect tier). Default: SNYK_TOKEN.",
     )
+    parser.add_argument(
+        "--project-root",
+        default=None,
+        help="Absolute project root of the current run. Used only to compute"
+             " prior.ccc_index_fresh: the prior CCC index counts as fresh only"
+             " when its indexed_path equals this value (and its status/timestamp"
+             " still qualify). Omitted → ccc_index_fresh is always false.",
+    )
     parser.add_argument(
         "--prior-state-from",
         default=None,

package/src/shared/scripts/skf-enumerate-stack-skills.py

@@ -22,7 +22,7 @@ SKILL.md, then extract usage patterns per skill (the part that does
 benefit from LLM judgment).
 
 Subcommand:
-  enumerate <skills-root>
+  enumerate <skills-root> [--pairs] [--reliability]
       Emit JSON {"skills": [...], "cycles": [...], "warnings": [...]}
       describing every subdirectory of <skills-root> that resolves to a
       skill package. Both layouts from knowledge/version-paths.md are
@@ -84,18 +84,47 @@ Symlink handling:
 Per-skill errors (malformed metadata.json, OSError, etc.) are captured
 as warnings on the top-level result; they do not exit the process.
 
+Optional derived output (additive flags — off by default, so existing
+consumers that read only skills/cycles/warnings are unaffected):
+
+  --pairs
+      Attach the complete set of unique library pairs derived from the
+      inventory: `pairs = [{"library_a": a, "library_b": b}, ...]` over
+      `itertools.combinations` of the sorted, deduplicated skill names,
+      plus `pair_count == N*(N-1)/2`. This is the deterministic
+      combinatorics the refine-architecture gap-analysis prompt used to
+      do in-context (where a dropped pair is a silently missed
+      integration gap). Sorting the names first makes ordering
+      independent of directory-scan order and byte-stable across runs.
+
+  --reliability
+      Attach the inventory reliability verdict computed from the counts
+      the script already owns:
+        skill_count       — len(skills)
+        warning_count     — len(warnings)
+        unreliable_ratio  — warning_count / (skill_count + warning_count),
+                            or 0.0 when the inventory is empty
+        inventory_reliable — unreliable_ratio <= 0.20 (the RELIABILITY
+                            THRESHOLD lives here, in one unit-tested place,
+                            so consuming prompts read a boolean instead of
+                            re-deriving a ratio + threshold comparison).
+      The raw counts are emitted alongside the boolean so a caller's halt
+      message can still render "{warning_count}/{skill_count+warning_count}
+      skills returned malformed metadata".
+
 Exit codes:
   0  enumeration succeeded (including zero skills found)
   1  user error (bad skills-root path)
 
 CLI:
-  uv run skf-enumerate-stack-skills.py enumerate <skills-root>
+  uv run skf-enumerate-stack-skills.py enumerate <skills-root> [--pairs] [--reliability]
 """
 
 from __future__ import annotations
 
 import argparse
 import hashlib
+import itertools
 import json
 import re
 import sys
@@ -112,6 +141,13 @@ SOURCE_REFERENCES = "references"
 SOURCE_SKILL_MD = "skill-md"
 SOURCE_UNKNOWN = "unknown"
 
+# Inventory reliability policy (single source of truth). If the fraction of
+# skip/malformed warnings exceeds this threshold, the inventory is deemed
+# unreliable. The gate is `ratio <= THRESHOLD` (i.e. a ratio of exactly 0.20
+# is still reliable) so a single malformed skill in a small 3-5 skill
+# inventory does not trip the halt.
+RELIABILITY_THRESHOLD = 0.20
+
 _CONFIDENCE_BY_SOURCE = {
     SOURCE_METADATA: "T1",
     SOURCE_REFERENCES: "T2",
@@ -552,6 +588,53 @@ def enumerate_stack_skills(skills_root: Path) -> dict:
     return result
 
 
+# --------------------------------------------------------------------------
+# Derived output: unique library pairs (--pairs)
+# --------------------------------------------------------------------------
+
+
+def compute_pairs(skills: list[dict]) -> list[dict]:
+    """Deterministic unique library pairs from an inventory's skills[].
+
+    Returns `[{"library_a": a, "library_b": b}, ...]` over every
+    combination of the sorted, deduplicated skill names — exactly
+    N*(N-1)/2 entries for N distinct names. Sorting first makes the order
+    independent of directory-scan order and byte-stable across runs; the
+    dedup guards against a pathological repeated name yielding a duplicate
+    pair. Never drops or duplicates a pair, unlike in-context enumeration
+    at larger N.
+    """
+    names = sorted({e["name"] for e in skills})
+    return [
+        {"library_a": a, "library_b": b}
+        for a, b in itertools.combinations(names, 2)
+    ]
+
+
+# --------------------------------------------------------------------------
+# Derived output: inventory reliability verdict (--reliability)
+# --------------------------------------------------------------------------
+
+
+def compute_reliability(skill_count: int, warning_count: int) -> dict:
+    """Reliability verdict from the inventory's own counts.
+
+    `unreliable_ratio` = warning_count / (skill_count + warning_count),
+    or 0.0 for an empty inventory (no ZeroDivisionError). The inventory is
+    reliable when that ratio is <= RELIABILITY_THRESHOLD (boundary
+    inclusive). Emits the raw counts too so a caller's halt message can
+    render "{warning_count}/{skill_count+warning_count}".
+    """
+    total = skill_count + warning_count
+    unreliable_ratio = (warning_count / total) if total else 0.0
+    return {
+        "inventory_reliable": unreliable_ratio <= RELIABILITY_THRESHOLD,
+        "unreliable_ratio": unreliable_ratio,
+        "skill_count": skill_count,
+        "warning_count": warning_count,
+    }
+
+
 # --------------------------------------------------------------------------
 # CLI
 # --------------------------------------------------------------------------
@@ -566,6 +649,15 @@ def _cmd_enumerate(args: argparse.Namespace) -> int:
         )
         return 1
     result = enumerate_stack_skills(skills_root)
+    # Additive derived output — attached only when the flag is set, so the
+    # default shape stays {skills, cycles, warnings} for existing consumers.
+    if args.pairs:
+        result["pairs"] = compute_pairs(result["skills"])
+        result["pair_count"] = len(result["pairs"])
+    if args.reliability:
+        result.update(
+            compute_reliability(len(result["skills"]), len(result["warnings"]))
+        )
     json.dump(result, sys.stdout, indent=2)
     sys.stdout.write("\n")
     return 0
@@ -590,6 +682,23 @@ def _build_parser() -> argparse.ArgumentParser:
         "skills_root",
         help="directory containing skill packages (each subdir has SKILL.md)",
     )
+    p_enum.add_argument(
+        "--pairs",
+        action="store_true",
+        help=(
+            "additionally emit `pairs[]` (unique {library_a, library_b} "
+            "combinations over the sorted skill names) and `pair_count`"
+        ),
+    )
+    p_enum.add_argument(
+        "--reliability",
+        action="store_true",
+        help=(
+            "additionally emit the reliability verdict "
+            "(`inventory_reliable`, `unreliable_ratio`, `skill_count`, "
+            f"`warning_count`; threshold {RELIABILITY_THRESHOLD})"
+        ),
+    )
     p_enum.set_defaults(func=_cmd_enumerate)
 
     return parser