bmad-module-skill-forge 1.9.0 → 2.0.1

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

@@ -16,7 +16,7 @@ Detection chain (all four methods attempted, results aggregated):
   4. docs_folder    — markdown files in the repo's docs/ directory
 
 CLI:
-  uv run python src/shared/scripts/skf-detect-docs.py \\
+  uv run src/shared/scripts/skf-detect-docs.py \\
       --repo-url <url> [--local-path <path>] [--skip-pages-api]
 
 Input:
@@ -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)?/?$",
@@ -86,13 +123,18 @@ _MD_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
 _HTML_LINK_RE = re.compile(r'<a\s[^>]*href=["\']([^"\']+)["\']', re.IGNORECASE)
 _BARE_URL_RE = re.compile(r"^(https?://\S+)$", re.MULTILINE)
 
+# `docs?\.` (not `docs\.`) so a `doc.` subdomain matches too — language doc
+# sites use the singular form (doc.rust-lang.org, doc.qt.io).
 _DOC_DOMAIN_RE = re.compile(
-    r"(?:docs\.|\.readthedocs\.|wiki\.|documentation\.)",
+    r"(?:docs?\.|\.readthedocs\.|wiki\.|documentation\.)",
     re.IGNORECASE,
 )
 
+# Language reference/guide path segments (a Book, a std/library API, a tutorial)
+# are doc URLs even on a bare domain (doc.rust-lang.org/book/, .../std/).
 _DOC_PATH_RE = re.compile(
-    r"(?:/docs/|/documentation/|/api/|/reference/|/guide/|/wiki/)",
+    r"(?:/docs/|/documentation/|/api/|/reference/|/guide/|/wiki/"
+    r"|/book/|/std/|/library/|/tutorial/)",
     re.IGNORECASE,
 )
 
@@ -219,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
 # ---------------------------------------------------------------------------
@@ -371,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

@@ -32,9 +32,10 @@ Detection rules (apply in order, first match wins):
   7. build.gradle (Groovy) — check tree:
        src/main/kotlin/  → kotlin (medium)
        else              → java (medium)
-  8. *.csproj | *.sln    → csharp (high)
-  9. Gemfile             → ruby (high)
- 10. Extension-frequency fallback over the full tree.
+  8. Package.swift       → swift (high)
+  9. *.csproj | *.sln    → csharp (high)
+ 10. Gemfile             → ruby (high)
+ 11. Extension-frequency fallback over the full tree.
        dominant extension >= 50% of code files → that language (medium)
        no clear winner                        → unknown (low)
 
@@ -57,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")
@@ -94,6 +105,7 @@ _MANIFEST_RULES: list[tuple[str, str, str]] = [
     ("go.mod", "go", "go.mod present"),
     ("pom.xml", "java", "pom.xml present"),
     ("build.gradle.kts", "kotlin", "build.gradle.kts present"),
+    ("Package.swift", "swift", "Package.swift present"),
     ("Gemfile", "ruby", "Gemfile present"),
 ]
 
@@ -199,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-emit-result-envelope.py

@@ -54,9 +54,17 @@ Context payload shape (consumed by `emit`):
     "ccc_exclusion_warnings":        ["string", ...],
     "ccc_registry_stale_removed":    ["/path", ...],
     "ccc_indexing_failed_reason":    "string|null",
+    "orphan_auto_resolution":        null|{"action": "keep|remove", "count": int, "source": "headless-default|orphan-action-flag"},
     "error":                         null|{"phase","path","reason"}
   }
 
+  When the step-3 orphan-removal gate is resolved non-interactively
+  (headless default Keep, or an explicit --orphan-action), pass
+  `orphan_auto_resolution` so the audit trail lands in `warnings` —
+  most importantly when the destructive `remove` ran headlessly, which a
+  pipeline otherwise could not distinguish from a no-op by reading the
+  envelope alone.
+
 Caller does NOT need to compute warnings, tools_added/removed, or
 tier_changed — the script derives them from the inputs above.
 
@@ -176,6 +184,15 @@ def _assemble_warnings(payload: dict) -> list[str]:
         warnings.append(
             f"require_tier_failed: missing {', '.join(missing) if missing else '<none>'}"
         )
+    orphan = payload.get("orphan_auto_resolution")
+    if isinstance(orphan, dict) and orphan.get("action"):
+        action = str(orphan.get("action"))
+        count = orphan.get("count", 0)
+        source = str(orphan.get("source", "headless-default"))
+        warnings.append(
+            f"orphan_auto_resolution: {action} {count} orphaned collection(s) "
+            f"(non-interactive, {source})"
+        )
     return warnings