bmad-module-skill-forge 1.8.0 → 2.0.0

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

@@ -5,7 +5,7 @@
   "description": "Single-line JSON document emitted by skf-brief-skill step 5 §4b when {headless_mode} is true, prefixed with the literal 'SKF_BRIEF_RESULT_JSON: '. Pipelines grep one line out of the workflow log to branch on the brief outcome without parsing prose. Schema mirrors the contract in src/skf-brief-skill/SKILL.md Result Contract section.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["status", "brief_path", "skill_name", "version", "language", "scope_type", "exit_code", "halt_reason"],
+  "required": ["status", "brief_path", "skill_name", "version", "language", "scope_type", "exit_code", "halt_reason", "mode"],
   "properties": {
     "status": {
       "type": "string",
@@ -53,6 +53,11 @@
         "user-cancelled"
       ],
       "description": "Null on success. One of the documented HALT classes on error. Pipelines branch on this to surface the right operator message without grepping the prose error."
+    },
+    "mode": {
+      "type": ["string", "null"],
+      "enum": ["auto", null],
+      "description": "'auto' when BS was invoked with the [auto] bracket modifier (pipeline auto-brief generation). Null otherwise (interactive or headless-without-auto)."
     }
   }
 }

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

@@ -51,7 +51,12 @@
         "required": ["url"],
         "properties": {
           "url": { "type": "string", "minLength": 1 },
-          "label": { "type": "string" }
+          "label": { "type": "string" },
+          "source": {
+            "type": "string",
+            "enum": ["language-registry", "readme-detection", "homepage", "pages-api", "docs-folder"],
+            "description": "Optional per-corpus provenance. `language-registry` marks a registry-guaranteed companion corpus (skf-language-corpora.py); the others mark opportunistically-detected docs by detection method. Absent on legacy/hand-authored entries."
+          }
         }
       },
       "minItems": 1,

package/src/shared/scripts/skf-derive-assembly-shape.py

@@ -0,0 +1,107 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pyyaml"]
+# ///
+"""SKF Derive Assembly Shape — decide whether a brief is a whole-language reference.
+
+create-skill's SKILL.md assembly is mostly LLM-driven prose, but the BRANCH
+SELECTION — does this skill get the whole-language "Language Guide" treatment
+(prose foregrounded, compiler internals demoted) or the standard
+library-export layout? — must be deterministic. This helper computes that one
+decision from the brief so the assembler (and the doc-fetch step) branch on a
+machine value instead of grepping free-text `scope.notes`.
+
+The gate is a single, structured, schema-validated condition: the brief's
+`doc_urls` contains at least one entry with `source: "language-registry"`
+(issue #432). Registry-sourced corpora are stamped ONLY by
+skf-language-corpora.py, which is invoked ONLY for a whole-language reference
+(a grammar_file:/tree_triad: signal) in step-auto-scope.md §6b. So the gate
+fires exactly when there is registry-guaranteed prose to foreground, and never
+for an ordinary library, a parser library (pest), a component-library, a
+reference-app, or a docs-only brief — none of which carry a language-registry
+entry. A registry-miss (N==0) whole-language reference carries no such entry
+and is intentionally NOT gated: there is no canonical prose to foreground, so
+it keeps the standard layout (and its scope.notes DEGRADED caveat stands).
+
+Gating on the structured `source` field — not the operator-editable
+`scope.notes` substring — means a hand-edited or interactive brief cannot
+silently disable (or misfire) the override.
+
+CLI:
+  uv run skf-derive-assembly-shape.py <path/to/skill-brief.yaml>
+  cat brief.yaml | uv run skf-derive-assembly-shape.py -
+
+Output (JSON on stdout):
+  {
+    "assembly_shape": "whole-language-reference" | "standard",
+    "gate_signal":    "language-registry" | null
+  }
+
+Exit codes:
+  0  success (shape emitted)
+  2  error (missing/unreadable/invalid brief)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def derive_assembly_shape(brief: dict[str, Any]) -> dict[str, Any]:
+    """Return the assembly-shape decision for a parsed brief."""
+    doc_urls = brief.get("doc_urls")
+    if isinstance(doc_urls, list):
+        for entry in doc_urls:
+            if isinstance(entry, dict) and entry.get("source") == "language-registry":
+                return {
+                    "assembly_shape": "whole-language-reference",
+                    "gate_signal": "language-registry",
+                }
+    return {"assembly_shape": "standard", "gate_signal": None}
+
+
+def _die(message: str) -> None:
+    json.dump({"error": message}, sys.stderr)
+    sys.stderr.write("\n")
+    sys.exit(2)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-derive-assembly-shape",
+        description="Decide whether a skill brief is a whole-language reference.",
+    )
+    parser.add_argument(
+        "path",
+        help="path to skill-brief.yaml; pass `-` to read YAML from stdin",
+    )
+    args = parser.parse_args(argv)
+
+    if args.path == "-":
+        text = sys.stdin.read()
+    else:
+        p = Path(args.path)
+        if not p.is_file():
+            _die(f"Brief not found at {p.as_posix()}")
+        text = p.read_text(encoding="utf-8")
+
+    try:
+        brief = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        _die(f"Brief is not valid YAML: {exc}")
+    if not isinstance(brief, dict):
+        _die("Brief must be a YAML mapping")
+
+    json.dump(derive_assembly_shape(brief), sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,417 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Detect Docs — discover documentation URLs for a GitHub repository.
+
+Standalone doc-detection script that discovers documentation URLs through
+multiple methods.  BS, CS, AS, and campaign workflows all locate a repo's
+docs through this shared entry point, eliminating duplicate detection logic.
+
+Detection chain (all four methods attempted, results aggregated):
+
+  1. homepageUrl    — GitHub repo metadata homepage field
+  2. readme_link    — links parsed from the repo README
+  3. pages_api      — GitHub Pages site URL
+  4. docs_folder    — markdown files in the repo's docs/ directory
+
+CLI:
+  uv run src/shared/scripts/skf-detect-docs.py \\
+      --repo-url <url> [--local-path <path>] [--skip-pages-api]
+
+Input:
+  --repo-url        GitHub repository URL (required)
+  --local-path      local clone path for docs/ folder scan (optional)
+  --skip-pages-api  skip GitHub Pages API detection (optional flag)
+
+Output (JSON array on stdout):
+  [
+    {
+      "url":          "https://docs.example.com",
+      "detected_via": "homepageUrl",
+      "content_hash": "sha256:a1b2c3...",
+      "content_type": "api-docs"
+    }
+  ]
+
+Exit codes:
+  0  found >=1 documentation source
+  1  no documentation sources found (empty array)
+  2  error (invalid args, gh not found, etc.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import json
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+_GITHUB_URL_RE = re.compile(
+    r"https?://(?:www\.)?github\.com/([^/\s]+)/([^/\s.]+?)(?:\.git)?/?$",
+    re.IGNORECASE,
+)
+
+USER_AGENT = "skf-detect-docs/1.0 (+https://github.com/armelhbobdad/bmad-module-skill-forge)"
+
+_FETCH_TIMEOUT = 15
+
+# ---------------------------------------------------------------------------
+# URL exclusion patterns (AC #5)
+# ---------------------------------------------------------------------------
+
+_EXCLUSION_PATTERNS = re.compile(
+    r"(?:^|/)(?:"
+    r"CHANGELOG|CHANGES|HISTORY"
+    r"|MIGRATION|MIGRATING|UPGRADE"
+    r"|RELEASE|release-notes|releases"
+    r"|CONTRIBUTING|CODE_OF_CONDUCT"
+    r"|LICENSE|SECURITY"
+    r")(?:\.|/|$)",
+    re.IGNORECASE,
+)
+
+# ---------------------------------------------------------------------------
+# README link scanning patterns
+# ---------------------------------------------------------------------------
+
+_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\.)",
+    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"|/book/|/std/|/library/|/tutorial/)",
+    re.IGNORECASE,
+)
+
+_DOC_TEXT_RE = re.compile(
+    r"(?:documentation|docs|api\s+reference|guide|wiki)",
+    re.IGNORECASE,
+)
+
+_REJECT_URL_RE = re.compile(
+    r"(?:"
+    r"github\.com/[^/]+/[^/]+/(?:issues|pull|actions)"
+    r"|img\.shields\.io"
+    r"|badge"
+    r"|\.(?:svg|png|gif|jpg|jpeg)(?:\?|$)"
+    r"|travis-ci\."
+    r"|circleci\."
+    r"|npmjs\.com"
+    r"|pypi\.org"
+    r"|crates\.io"
+    r"|twitter\.com|x\.com"
+    r"|discord\.(?:gg|com)"
+    r"|slack\.com"
+    r")",
+    re.IGNORECASE,
+)
+
+
+# ---------------------------------------------------------------------------
+# Content type classification
+# ---------------------------------------------------------------------------
+
+_API_DOCS_RE = re.compile(r"(?:/api/|/reference/|/sdk/|api-docs|api\.)", re.IGNORECASE)
+_GUIDE_RE = re.compile(
+    r"(?:/guide/|/tutorial/|/getting-started|/quickstart|/howto)",
+    re.IGNORECASE,
+)
+
+
+def _classify_content_type(url: str) -> str:
+    if _API_DOCS_RE.search(url):
+        return "api-docs"
+    if _GUIDE_RE.search(url):
+        return "guide"
+    return "reference"
+
+
+# ---------------------------------------------------------------------------
+# URL helpers
+# ---------------------------------------------------------------------------
+
+def _is_excluded(url: str) -> bool:
+    return bool(_EXCLUSION_PATTERNS.search(url))
+
+
+def _is_github_self_url(url: str, owner: str, repo: str) -> bool:
+    return bool(re.match(
+        rf"https?://(?:www\.)?github\.com/{re.escape(owner)}/{re.escape(repo)}/?$",
+        url,
+        re.IGNORECASE,
+    ))
+
+
+def _is_doc_url(url: str, link_text: str = "") -> bool:
+    if _REJECT_URL_RE.search(url):
+        return False
+    if _DOC_DOMAIN_RE.search(url):
+        return True
+    if _DOC_PATH_RE.search(url):
+        return True
+    if link_text and _DOC_TEXT_RE.search(link_text):
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# gh CLI helper
+# ---------------------------------------------------------------------------
+
+def _run_gh(args: List[str]) -> Optional[str]:
+    try:
+        result = subprocess.run(
+            ["gh"] + args,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+        return None
+    except FileNotFoundError:
+        return None
+
+
+def _check_gh_available() -> bool:
+    try:
+        subprocess.run(
+            ["gh", "--version"],
+            capture_output=True,
+            text=True,
+        )
+        return True
+    except FileNotFoundError:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Content hashing
+# ---------------------------------------------------------------------------
+
+def _fetch_and_hash(url: str) -> Optional[str]:
+    if url.startswith("file://"):
+        try:
+            local_path = url[7:]
+            with open(local_path, "rb") as fh:
+                content = fh.read()
+            return "sha256:" + hashlib.sha256(content).hexdigest()
+        except (OSError, IOError):
+            return 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()
+        return "sha256:" + hashlib.sha256(content).hexdigest()
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Detection method 1 — homepageUrl
+# ---------------------------------------------------------------------------
+
+def _detect_homepage_url(owner: str, repo: str) -> List[Dict[str, Any]]:
+    raw = _run_gh(["api", f"repos/{owner}/{repo}", "--jq", ".homepage"])
+    if not raw or raw == "null":
+        return []
+    url = raw.strip()
+    if not url:
+        return []
+    if _is_github_self_url(url, owner, repo):
+        return []
+    return [{"url": url, "detected_via": "homepageUrl", "content_type": _classify_content_type(url)}]
+
+
+# ---------------------------------------------------------------------------
+# Detection method 2 — README link scanning
+# ---------------------------------------------------------------------------
+
+def _detect_readme_links(owner: str, repo: str) -> List[Dict[str, Any]]:
+    raw = _run_gh(["api", f"repos/{owner}/{repo}/readme"])
+    if not raw:
+        return []
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return []
+    encoded = data.get("content", "")
+    if not encoded:
+        return []
+    try:
+        readme_text = base64.b64decode(encoded).decode("utf-8", errors="replace")
+    except Exception:
+        return []
+
+    urls_with_text: List[tuple] = []
+    for text, url in _MD_LINK_RE.findall(readme_text):
+        urls_with_text.append((url.strip(), text.strip()))
+    for url in _HTML_LINK_RE.findall(readme_text):
+        urls_with_text.append((url.strip(), ""))
+    for url in _BARE_URL_RE.findall(readme_text):
+        urls_with_text.append((url.strip(), ""))
+
+    results: List[Dict[str, Any]] = []
+    seen: set = set()
+    for url, text in urls_with_text:
+        if not url.startswith("http"):
+            continue
+        if url in seen:
+            continue
+        if _is_doc_url(url, text):
+            seen.add(url)
+            results.append({
+                "url": url,
+                "detected_via": "readme_link",
+                "content_type": _classify_content_type(url),
+            })
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Detection method 3 — Pages API
+# ---------------------------------------------------------------------------
+
+def _detect_pages_api(owner: str, repo: str) -> List[Dict[str, Any]]:
+    raw = _run_gh(["api", f"repos/{owner}/{repo}/pages", "--jq", ".html_url"])
+    if not raw or raw == "null":
+        return []
+    url = raw.strip()
+    if not url:
+        return []
+    return [{"url": url, "detected_via": "pages_api", "content_type": _classify_content_type(url)}]
+
+
+# ---------------------------------------------------------------------------
+# Detection method 4 — docs/ folder
+# ---------------------------------------------------------------------------
+
+def _detect_docs_folder(owner: str, repo: str, local_path: Optional[str] = None) -> List[Dict[str, Any]]:
+    results: List[Dict[str, Any]] = []
+    if local_path:
+        docs_dir = Path(local_path) / "docs"
+        if docs_dir.is_dir():
+            for md_file in sorted(docs_dir.rglob("*.md")):
+                file_url = "file://" + md_file.as_posix()
+                results.append({
+                    "url": file_url,
+                    "detected_via": "docs_folder",
+                    "content_type": _classify_content_type(md_file.as_posix()),
+                })
+    else:
+        raw = _run_gh(["api", f"repos/{owner}/{repo}/contents/docs"])
+        if not raw:
+            return []
+        try:
+            entries = json.loads(raw)
+        except json.JSONDecodeError:
+            return []
+        if not isinstance(entries, list):
+            return []
+        for entry in entries:
+            name = entry.get("name", "")
+            if not name.lower().endswith(".md"):
+                continue
+            download_url = entry.get("download_url", "")
+            if download_url:
+                results.append({
+                    "url": download_url,
+                    "detected_via": "docs_folder",
+                    "content_type": _classify_content_type(download_url),
+                })
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Main detection orchestrator
+# ---------------------------------------------------------------------------
+
+def detect(
+    repo_url: str,
+    local_path: Optional[str] = None,
+    skip_pages_api: bool = False,
+) -> List[Dict[str, Any]]:
+    m = _GITHUB_URL_RE.match(repo_url.strip())
+    if not m:
+        return []
+
+    owner, repo = m.group(1), m.group(2)
+
+    all_results: List[Dict[str, Any]] = []
+    all_results.extend(_detect_homepage_url(owner, repo))
+    all_results.extend(_detect_readme_links(owner, repo))
+    if not skip_pages_api:
+        all_results.extend(_detect_pages_api(owner, repo))
+    all_results.extend(_detect_docs_folder(owner, repo, local_path))
+
+    filtered = [r for r in all_results if not _is_excluded(r["url"])]
+
+    seen: set = set()
+    deduped: List[Dict[str, Any]] = []
+    for r in filtered:
+        if r["url"] not in seen:
+            seen.add(r["url"])
+            deduped.append(r)
+
+    for entry in deduped:
+        entry["content_hash"] = _fetch_and_hash(entry["url"])
+
+    return deduped
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Detect documentation URLs for a GitHub repository.",
+    )
+    parser.add_argument("--repo-url", required=True, help="GitHub repository URL")
+    parser.add_argument("--local-path", default=None, help="Local clone path for docs/ folder scan")
+    parser.add_argument("--skip-pages-api", action="store_true", help="Skip GitHub Pages API detection")
+    args = parser.parse_args()
+
+    if not _check_gh_available():
+        json.dump({"error": "gh CLI not found", "code": "GH_NOT_FOUND"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    m = _GITHUB_URL_RE.match(args.repo_url.strip())
+    if not m:
+        json.dump({"error": f"Not a GitHub URL: {args.repo_url}", "code": "INVALID_URL"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    try:
+        results = detect(args.repo_url, args.local_path, args.skip_pages_api)
+    except Exception as exc:
+        json.dump({"error": str(exc), "code": "DETECTION_ERROR"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    json.dump(results, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+
+    return 0 if results else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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)
 
@@ -94,6 +95,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"),
 ]
 

package/src/shared/scripts/skf-emit-brief-result-envelope.py

@@ -44,7 +44,8 @@ Context payload shape (consumed by `emit`):
     "halt_reason": null | "input-missing" | "input-invalid" |
                    "forge-tier-missing" | "target-inaccessible" |
                    "gh-auth-failed" | "write-failed" |
-                   "overwrite-cancelled" | "user-cancelled"
+                   "overwrite-cancelled" | "user-cancelled",
+    "mode":        null | "auto"
   }
 
 The caller does NOT supply exit_code — the script derives it from
@@ -105,6 +106,8 @@ HALT_TO_EXIT = {
     "user-cancelled": 6,
 }
 
+VALID_MODES = {None, "auto"}
+
 # Envelope key order — fixed so byte-stable diffs are possible.
 KEY_ORDER = [
     "status",
@@ -115,6 +118,7 @@ KEY_ORDER = [
     "scope_type",
     "exit_code",
     "halt_reason",
+    "mode",
 ]
 
 
@@ -152,6 +156,10 @@ def assemble(ctx: dict[str, Any]) -> dict[str, Any]:
     if not skill_name or not isinstance(skill_name, str):
         _die(f"skill_name is required and must be a non-empty string; got {skill_name!r}")
 
+    mode = ctx.get("mode")
+    if mode not in VALID_MODES:
+        _die(f"mode must be one of {sorted(m for m in VALID_MODES if m is not None)} or null; got {mode!r}")
+
     envelope = {
         "status": status,
         "brief_path": ctx.get("brief_path"),
@@ -161,6 +169,7 @@ def assemble(ctx: dict[str, Any]) -> dict[str, Any]:
         "scope_type": scope_type,
         "exit_code": HALT_TO_EXIT[halt_reason],
         "halt_reason": halt_reason,
+        "mode": mode,
     }
     # Re-emit in canonical key order
     return {k: envelope[k] for k in KEY_ORDER}
@@ -181,6 +190,8 @@ def validate(envelope: dict[str, Any]) -> None:
         _die(f"halt_reason invalid: {envelope.get('halt_reason')!r}")
     if envelope.get("scope_type") not in VALID_SCOPE_TYPES:
         _die(f"scope_type invalid: {envelope.get('scope_type')!r}")
+    if envelope.get("mode") not in VALID_MODES:
+        _die(f"mode invalid: {envelope.get('mode')!r}")
     if envelope.get("exit_code") not in {0, 2, 3, 4, 5, 6}:
         _die(f"exit_code invalid: {envelope.get('exit_code')!r}")
     expected_exit = HALT_TO_EXIT[envelope.get("halt_reason")]

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