bmad-module-skill-forge 1.2.0 → 1.3.0

package/src/shared/scripts/skf-resolve-package.py

@@ -0,0 +1,264 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""SKF Resolve Package — resolve a package name to a GitHub repository URL.
+
+Walks the canonical fallback chain documented in
+`src/skf-quick-skill/references/registry-resolution.md`:
+
+  1. npm registry        (JavaScript/TypeScript)
+  2. PyPI registry       (Python)
+  3. crates.io registry  (Rust)
+
+Per-call timeout (default 10s); a timeout is treated as a soft failure
+and the resolver falls through to the next entry. Web-search fallback
+is intentionally NOT in this helper — registries are deterministic;
+web search is judgment, and stays in the LLM step.
+
+CLI:
+
+  python3 skf-resolve-package.py <package_name> [--timeout 10]
+
+Output JSON (stdout):
+
+  status:           "ok" | "fallthrough"
+  package_name:     "<input>"
+  resolved_url:     "https://github.com/<owner>/<repo>"  (when status == "ok")
+  repo_owner:       "<owner>"                            (when status == "ok")
+  repo_name:        "<repo>"                             (when status == "ok")
+  registry_used:    "npm" | "pypi" | "crates"            (when status == "ok")
+  registries_tried: ["npm", ...]
+  registry_outcomes: {"npm": "ok|404|timeout|error|no-github-link", ...}
+
+Exit codes:
+
+  0  status == "ok"
+  1  status == "fallthrough" — every registry replied without a GitHub
+     URL; the LLM step should fall back to web search.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import socket
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Optional
+
+REGISTRY_TIMEOUT_SECONDS = 10.0
+USER_AGENT = "skf-resolve-package/1.0 (+https://github.com/armelhbobdad/bmad-module-skill-forge)"
+
+_GITHUB_URL_RE = re.compile(
+    r"https?://(?:www\.)?github\.com/([^/\s]+)/([^/\s.]+?)(?:\.git)?/?$",
+    re.IGNORECASE,
+)
+
+
+def parse_github_url(url: str) -> Optional[tuple[str, str, str]]:
+    """Parse a GitHub URL/string into (canonical_url, owner, repo).
+
+    Handles the variants registries actually emit:
+      - https://github.com/owner/repo
+      - http://github.com/owner/repo
+      - github.com/owner/repo
+      - git+https://github.com/owner/repo.git
+      - git@github.com:owner/repo.git
+      - github:owner/repo (npm shortcut)
+    """
+    if not url or not isinstance(url, str):
+        return None
+
+    s = url.strip()
+
+    if s.startswith("github:"):
+        rest = s[len("github:") :]
+        if "/" in rest:
+            owner, _, repo = rest.partition("/")
+            repo = repo.removesuffix(".git").rstrip("/")
+            if owner and repo:
+                return f"https://github.com/{owner}/{repo}", owner, repo
+        return None
+
+    if s.startswith("git+"):
+        s = s[len("git+") :]
+
+    if s.startswith("git@github.com:"):
+        rest = s[len("git@github.com:") :]
+        rest = rest.removesuffix(".git").rstrip("/")
+        if "/" in rest:
+            owner, _, repo = rest.partition("/")
+            if owner and repo:
+                return f"https://github.com/{owner}/{repo}", owner, repo
+        return None
+
+    if s.startswith("github.com/"):
+        s = "https://" + s
+
+    m = _GITHUB_URL_RE.match(s)
+    if m:
+        owner, repo = m.group(1), m.group(2)
+        return f"https://github.com/{owner}/{repo}", owner, repo
+
+    return None
+
+
+def _http_get_json(url: str, timeout: float) -> tuple[Optional[dict], str]:
+    """Fetch JSON. Returns (payload_or_None, outcome).
+
+    Outcome values:
+      "ok"       — valid JSON object returned
+      "404"      — HTTP 404 (package does not exist on this registry)
+      "timeout"  — socket / urlopen timed out
+      "error"    — any other transport / parse error
+    """
+    req = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": USER_AGENT})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            payload = json.loads(resp.read().decode("utf-8"))
+            if isinstance(payload, dict):
+                return payload, "ok"
+            return None, "error"
+    except urllib.error.HTTPError as e:
+        return None, "404" if e.code == 404 else "error"
+    except urllib.error.URLError as e:
+        if isinstance(getattr(e, "reason", None), (socket.timeout, TimeoutError)):
+            return None, "timeout"
+        return None, "error"
+    except (TimeoutError, socket.timeout):
+        return None, "timeout"
+    except (ValueError, json.JSONDecodeError):
+        return None, "error"
+
+
+def try_npm(package_name: str, timeout: float) -> tuple[Optional[tuple[str, str, str]], str]:
+    """Try the npm registry. Returns (parsed_or_None, outcome)."""
+    encoded = urllib.parse.quote(package_name, safe="@")
+    url = f"https://registry.npmjs.org/{encoded}"
+    payload, outcome = _http_get_json(url, timeout)
+    if payload is None:
+        return None, outcome
+    candidates: list[str] = []
+    repo = payload.get("repository")
+    if isinstance(repo, dict) and isinstance(repo.get("url"), str):
+        candidates.append(repo["url"])
+    elif isinstance(repo, str):
+        candidates.append(repo)
+    homepage = payload.get("homepage")
+    if isinstance(homepage, str):
+        candidates.append(homepage)
+    for c in candidates:
+        parsed = parse_github_url(c)
+        if parsed:
+            return parsed, "ok"
+    return None, "no-github-link"
+
+
+def try_pypi(package_name: str, timeout: float) -> tuple[Optional[tuple[str, str, str]], str]:
+    """Try the PyPI registry. Returns (parsed_or_None, outcome)."""
+    encoded = urllib.parse.quote(package_name, safe="")
+    url = f"https://pypi.org/pypi/{encoded}/json"
+    payload, outcome = _http_get_json(url, timeout)
+    if payload is None:
+        return None, outcome
+    info = payload.get("info") or {}
+    candidates: list[str] = []
+    project_urls = info.get("project_urls") or {}
+    if isinstance(project_urls, dict):
+        for key in ("Source", "Source Code", "Repository", "Homepage"):
+            v = project_urls.get(key)
+            if isinstance(v, str):
+                candidates.append(v)
+    home_page = info.get("home_page")
+    if isinstance(home_page, str):
+        candidates.append(home_page)
+    for c in candidates:
+        parsed = parse_github_url(c)
+        if parsed:
+            return parsed, "ok"
+    return None, "no-github-link"
+
+
+def try_crates(package_name: str, timeout: float) -> tuple[Optional[tuple[str, str, str]], str]:
+    """Try the crates.io registry. Returns (parsed_or_None, outcome)."""
+    encoded = urllib.parse.quote(package_name, safe="")
+    url = f"https://crates.io/api/v1/crates/{encoded}"
+    payload, outcome = _http_get_json(url, timeout)
+    if payload is None:
+        return None, outcome
+    crate = payload.get("crate") or {}
+    for key in ("repository", "homepage"):
+        v = crate.get(key)
+        if isinstance(v, str):
+            parsed = parse_github_url(v)
+            if parsed:
+                return parsed, "ok"
+    return None, "no-github-link"
+
+
+_RESOLVER_NAMES: tuple[tuple[str, str], ...] = (
+    ("npm", "try_npm"),
+    ("pypi", "try_pypi"),
+    ("crates", "try_crates"),
+)
+
+
+def resolve_package(package_name: str, timeout: float = REGISTRY_TIMEOUT_SECONDS) -> dict:
+    registries_tried: list[str] = []
+    outcomes: dict[str, str] = {}
+
+    # Dynamic lookup so test code can monkeypatch try_npm / try_pypi / try_crates
+    # without re-binding entries in a module-level tuple of function refs.
+    for name, fn_name in _RESOLVER_NAMES:
+        registries_tried.append(name)
+        fn = globals()[fn_name]
+        result, outcome = fn(package_name, timeout)
+        outcomes[name] = outcome
+        if result is not None:
+            url, owner, repo = result
+            return {
+                "status": "ok",
+                "package_name": package_name,
+                "resolved_url": url,
+                "repo_owner": owner,
+                "repo_name": repo,
+                "registry_used": name,
+                "registries_tried": registries_tried,
+                "registry_outcomes": outcomes,
+            }
+
+    return {
+        "status": "fallthrough",
+        "package_name": package_name,
+        "registries_tried": registries_tried,
+        "registry_outcomes": outcomes,
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Resolve a package name to a GitHub repository URL via npm/PyPI/crates.io.",
+    )
+    parser.add_argument(
+        "package_name",
+        help="Package name to resolve (e.g., lodash, @tanstack/query, requests, serde).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=float,
+        default=REGISTRY_TIMEOUT_SECONDS,
+        help=f"Per-registry timeout in seconds (default: {REGISTRY_TIMEOUT_SECONDS}).",
+    )
+    args = parser.parse_args(argv)
+
+    result = resolve_package(args.package_name, timeout=args.timeout)
+    print(json.dumps(result, indent=2))
+    return 0 if result["status"] == "ok" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/src/shared/scripts/skf-validate-output.py

@@ -9,6 +9,7 @@ schema against agentskills.io specification. Outputs JSON validation results.
 
 CLI: python3 skf-validate-output.py <skill-package-dir>
      python3 skf-validate-output.py <skill-package-dir> --generated-by quick-skill
+     python3 skf-validate-output.py <skill-package-dir> --skip-frontmatter
 """
 
 from __future__ import annotations
@@ -73,7 +74,7 @@ def validate_body_structure(content):
     issues = []
     body = content.split("---", 2)[-1] if content.startswith("---") else content
 
-    required_sections = ["Overview", "Key Exports", "Usage"]
+    required_sections = ["Overview", "Description", "Key Exports", "Usage"]
     for section in required_sections:
         pattern = rf"^##\s+.*{re.escape(section)}"
         if not re.search(pattern, body, re.MULTILINE | re.IGNORECASE):
@@ -155,8 +156,13 @@ def validate_metadata_json(data, generated_by=None):
     return issues
 
 
-def validate_skill_package(skill_dir, generated_by=None):
-    """Validate a complete skill package directory."""
+def validate_skill_package(skill_dir, generated_by=None, skip_frontmatter=False):
+    """Validate a complete skill package directory.
+
+    When `skip_frontmatter` is True, the SKILL.md frontmatter pass is omitted —
+    intended for callers that already validated frontmatter via skill-check or
+    skf-validate-frontmatter.py and only want body / snippet / metadata checks.
+    """
     skill_dir = Path(skill_dir)
     skill_name = skill_dir.name
 
@@ -183,9 +189,14 @@ def validate_skill_package(skill_dir, generated_by=None):
     skill_md_path = files["SKILL.md"]
     if skill_md_path.exists():
         content = skill_md_path.read_text(encoding="utf-8")
-        fm_issues = validate_frontmatter(content, skill_name)
+        if skip_frontmatter:
+            fm_section = {"skipped": "frontmatter validation skipped (--skip-frontmatter)"}
+            fm_issues = []
+        else:
+            fm_issues = validate_frontmatter(content, skill_name)
+            fm_section = fm_issues
         body_issues = validate_body_structure(content)
-        result["validation"]["skill_md"] = {"frontmatter": fm_issues, "body": body_issues}
+        result["validation"]["skill_md"] = {"frontmatter": fm_section, "body": body_issues}
         for issue in fm_issues + body_issues:
             result["summary"]["total_issues"] += 1
             result["summary"]["by_severity"][issue["severity"]] += 1
@@ -232,7 +243,11 @@ def validate_skill_package(skill_dir, generated_by=None):
 
 if __name__ == "__main__":
     if len(sys.argv) < 2:
-        print("Usage: python3 skf-validate-output.py <skill-package-dir> [--generated-by <generator>]", file=sys.stderr)
+        print(
+            "Usage: python3 skf-validate-output.py <skill-package-dir> "
+            "[--generated-by <generator>] [--skip-frontmatter]",
+            file=sys.stderr,
+        )
         sys.exit(1)
 
     pkg_dir = sys.argv[1]
@@ -242,6 +257,8 @@ if __name__ == "__main__":
         if idx + 1 < len(sys.argv):
             gen_by = sys.argv[idx + 1]
 
-    result = validate_skill_package(pkg_dir, generated_by=gen_by)
+    skip_fm = "--skip-frontmatter" in sys.argv
+
+    result = validate_skill_package(pkg_dir, generated_by=gen_by, skip_frontmatter=skip_fm)
     print(json.dumps(result, indent=2))
     sys.exit(0 if result["result"] == "PASS" else 1)

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

@@ -23,6 +23,12 @@ These rules apply to every step in this workflow:
 - Only load one step file at a time — never preload future steps
 - Always communicate in `{communication_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- If `{headless_mode}` is true, emit a single-line JSON progress event to **stderr** at each step's entry and exit so pipeline schedulers can stream live progress instead of post-mortem-parsing the result contract:
+  - entry: `{"step":N,"name":"<slug>","status":"start"}`
+  - exit (just before chaining to nextStepFile): `{"step":N,"name":"<slug>","status":"done"}`
+  - on HARD HALT: `{"step":N,"name":"<slug>","status":"halt","exit":<code>}` instead of "done"
+
+  `N` is the step number (1–7) and `<slug>` is the kebab portion of the filename after the number — `resolve-target`, `ecosystem-check`, `quick-extract`, `compile`, `write-and-validate`, `finalize`, `health-check`. One line per event; do not pretty-print.
 
 ## Stages
 
@@ -32,25 +38,187 @@ These rules apply to every step in this workflow:
 | 2 | Ecosystem Check | steps-c/step-02-ecosystem-check.md | Yes |
 | 3 | Quick Extract | steps-c/step-03-quick-extract.md | Yes |
 | 4 | Compile | steps-c/step-04-compile.md | No (review) |
-| 5 | Write & Validate | steps-c/step-05-validate.md | Yes |
-| 6 | Finalize | steps-c/step-06-write.md | Yes |
+| 5 | Write & Validate | steps-c/step-05-write-and-validate.md | Yes |
+| 6 | Finalize | steps-c/step-06-finalize.md | Yes |
 | 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | target (GitHub URL or package name) [required], language_hint [optional], scope_hint [optional] |
-| **Gates** | step-01: Input Gate [use args] | step-02: Choice Gate [P] (if match) | step-04: Review Gate [C] |
-| **Outputs** | SKILL.md, context-snippet.md, metadata.json, active symlink |
+| **Inputs** | target (GitHub URL or package name) [required for single-target mode], language_hint [optional], scope_hint [optional] |
+| **Overrides** | `--description`, `--exports`, `--skip-snippet`, `--no-active-pointer`, `--batch <file>`, `--fail-fast` — see On Activation step 3 |
+| **Gates** | step-01: Input Gate [use args]; step-02: Choice Gate [P] (if match); step-04: Review Gate [C/E/S/Q] |
+| **Outputs** | SKILL.md, context-snippet.md, metadata.json, active pointer, result contract (timestamped + `-latest` copy). Snippet and active pointer can be skipped per overrides. |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable, documented code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning                | Raised by                                                   |
+| ---- | ---------------------- | ----------------------------------------------------------- |
+| 0    | success                | step-07 (terminal)                                          |
+| 3    | resolution-failure     | step-01 §2c (prose input), step-01 §3 (registry chain failed) |
+| 4    | write-failure          | step-05 §2 (deliverable write failed)                       |
+| 5    | overwrite-cancelled    | step-05 §1 (user selected [N])                              |
+| 6    | compile-cancelled      | step-04 §6 (user selected [Q])                              |
+| 7    | finalize-blocked       | step-06 §1 (active-pointer flip refused — non-link in place) |
+
+Reserved: `validator-missing` may be promoted from advisory log to fatal exit code in a future revision; consumers should not assume code 8+ is unused.
+
+## Result Contract on HARD HALT
+
+In addition to the success-variant result contract written by step-06 §3, every HARD HALT must surface an **error variant** so headless automators don't silently break when `quick-skill-result-latest.json` is missing on failed runs.
+
+**Always (every HARD HALT, regardless of phase)** — emit a single line on **stderr**:
+
+```
+SKF_QUICK_SKILL_RESULT_JSON: {"status":"error","exit_code":<N>,"phase":"<slug>","error":{"code":"<class>","message":"<short>"},"outputs":{},"summary":{},"skill_package":"<path-or-null>"}
+```
+
+One line, no pretty-print. Matches the prefix-and-envelope convention used by `skf-emit-result-envelope.py`.
+
+**Additionally, when `{skill_package}` is known** (HALT at step-05 §1 onward) — write the same JSON object (without the `SKF_QUICK_SKILL_RESULT_JSON: ` prefix) to disk:
+
+```
+{skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json
+{skill_package}/quick-skill-result-latest.json   (copy, not symlink)
+```
+
+so consumers that hardcode the `-latest.json` path see a deterministic file even on failed runs. HALTs at step-01/02/03/04 cannot write to disk because `{skill_package}` is computed only in step-05 §1; for those, the stderr envelope plus exit code is the contract.
+
+**Schema:**
+
+| Field           | Type           | Notes                                                                                                       |
+| --------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
+| `status`        | string         | always `"error"` for HARD HALTs                                                                             |
+| `exit_code`     | integer        | matches the Exit Codes table                                                                                |
+| `phase`         | string         | step slug where the HALT occurred (e.g. `resolve-target`, `compile`)                                        |
+| `error.code`    | string         | one of: `resolution-failure`, `write-failure`, `overwrite-cancelled`, `compile-cancelled`, `finalize-blocked` |
+| `error.message` | string         | the user-facing message that was displayed                                                                  |
+| `error.details` | any            | optional — phase-specific context (e.g. the failed file path)                                               |
+| `outputs`       | object         | empty `{}` on early HALTs; partial when files were already written                                          |
+| `summary`       | object         | empty `{}` on early HALTs                                                                                   |
+| `skill_package` | string \| null | absolute path when known, `null` when HALT preceded step-05 §1                                              |
 
 ## On Activation
 
-1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
-   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
-   - `skills_output_folder`, `forge_data_folder`
+1. Read `{project-root}/_bmad/skf/config.yaml` and `{forger_root}/preferences.yaml` in parallel (one batched tool-call message — they are independent files), then resolve:
+   - From config: `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`
+   - From preferences: `headless_mode` (default false)
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `preferences.yaml`. Default: false.
+
+3. **Parse CLI overrides** — capture optional override flags into the workflow context as `{overrides}`. Each override is opt-in; when omitted, the workflow runs as today.
+
+   | Flag | Effect |
+   | --- | --- |
+   | `--description "<string>"` | Override the LLM-derived description in step-04 §2 (used in SKILL.md frontmatter and metadata.json). Subject to the same agentskills.io length (1–1024 chars) and voice (third-person) checks as extracted descriptions. |
+   | `--exports "<name1,name2,...>"` | Override the extracted export list. Parse as comma-separated; trim whitespace per item; skip empty items. Used in step-04 §2 Key Exports and the count-derived metadata stats. |
+   | `--skip-snippet` | Skip context-snippet.md generation in step-04 §3 and its write in step-05 §2. Artifact omitted from `outputs`; step-05 §5 advisory snippet validation reports a "skipped" entry. |
+   | `--no-active-pointer` | Skip the active-pointer flip in step-06 §1. Deliverables still land in `{skill_package}` but `{skill_group}/active` is not updated. Useful for batch automators that flip pointers in a separate stage. |
+   | `--batch <file>` | Run the workflow against a list of targets from a text file rather than a single argument. Implies `--headless` (gates cannot be human-driven across N targets). See "Batch Mode" below for input format and summary contract. Single-target overrides above apply globally to every target in the batch. |
+   | `--fail-fast` | Only meaningful with `--batch`. Abort the whole batch on the first per-target failure instead of recording the failure in the summary and proceeding to the next target. |
+
+4. **If `--batch` is set**, force `{headless_mode} = true` (log "headless: coerced by --batch" if it was false), read the batch file, and parse the target list per "Batch Mode" below. Continue at step 5; the batch loop documented in "Batch Mode" wraps the step-01 → step-07 pipeline that follows.
+
+5. Load, read the full file, and then execute `./steps-c/step-01-resolve-target.md` to begin the workflow. (In batch mode, control returns here for each subsequent target after step-07 completes; see "Batch Mode" below.)
+
+## Batch Mode
+
+When `--batch <file>` is supplied, quick-skill processes a list of targets from a text file in sequence rather than a single target from arguments. Designed for unattended bulk runs (CI pipelines, mass-rebuilds, the skf-batch-skills meta-workflow when it lands).
+
+### Input format
+
+One target per line. Empty lines and lines starting with `#` (after optional leading whitespace) are ignored. Each non-empty line has the same shape as the single-target `target` argument, with optional space-separated per-line modifiers:
+
+```
+# A batch input file.
+lodash
+@vercel/og
+cognee@0.5.0
+https://github.com/foo/bar
+https://github.com/foo/bar@2.1.0-beta
+
+# Per-line modifiers — overrides for THIS target only:
+lodash language=javascript scope=src/
+cognee@0.5.0 language=python scope=cognee/api/
+```
+
+Recognised per-line modifiers:
+
+| Modifier | Effect (this target only) |
+| --- | --- |
+| `language=<lang>` | Sets `language_hint` for this target — same effect as the optional `language_hint` input on a single-target run. |
+| `scope=<path>` | Sets `scope_hint` for this target — same effect as the optional `scope_hint` input on a single-target run. |
+
+Per-line modifiers shadow the global `--description` / `--exports` / `--skip-snippet` / `--no-active-pointer` overrides only when those override fields are not set. Global overrides apply to every target unless a future modifier extends per-line override syntax.
+
+### Execution
+
+`--batch` implies `--headless`. The batch loop runs the full quick-skill pipeline (steps 1–7) for each target in file order:
+
+1. Set `target`, `target_version`, `language_hint`, `scope_hint` from the batch line into the workflow context.
+2. Execute steps 1–7 per the normal pipeline.
+3. After step-07 completes (success or HARD HALT), record the per-target outcome (target, status, exit_code, skill_package, error.code) into the batch result list.
+4. If `--fail-fast` is set and the target failed, exit the batch loop immediately. Otherwise continue with the next target.
+
+Per-target output lands in `{skill_package}/` as today, with the per-target result contract at `{skill_package}/quick-skill-result-latest.json` (success or error variant per "Result Contract on HARD HALT" above).
+
+### Batch summary contract
+
+After the last target completes (or `--fail-fast` triggers an early exit), write the batch summary at:
+
+```
+{skills_output_folder}/_batch/quick-skill-batch-{YYYYMMDD-HHmmss}.json
+{skills_output_folder}/_batch/quick-skill-batch-latest.json   (copy, not symlink)
+```
+
+Schema:
+
+```json
+{
+  "skill": "skf-quick-skill",
+  "mode": "batch",
+  "status": "success | partial | failed",
+  "timestamp": "<ISO 8601 UTC>",
+  "input_file": "<path passed to --batch>",
+  "targets_total": 0,
+  "succeeded": 0,
+  "failed": 0,
+  "fail_fast_triggered": false,
+  "results": [
+    {
+      "target": "<line from batch file>",
+      "status": "success | error",
+      "exit_code": 0,
+      "skill_package": "<absolute path or null>",
+      "error_code": null
+    }
+  ]
+}
+```
+
+`status` resolves as: `"success"` when `failed == 0`; `"partial"` when `failed > 0 && succeeded > 0`; `"failed"` when `succeeded == 0`. `fail_fast_triggered` is `true` only when `--fail-fast` aborted the loop early — `targets_total` then reflects the count actually attempted, not the file's line count.
+
+### Headless events
+
+Batch mode emits per-target boundary events on stderr in addition to the per-step events documented in Workflow Rules:
+
+```
+{"batch":<n>,"target":"<target>","status":"start"}
+{"batch":<n>,"target":"<target>","status":"done","exit":<code>}
+{"batch":<n>,"target":"<target>","status":"fail","exit":<code>,"error_code":"<class>"}
+```
+
+`<n>` is the 1-based index of the target in the parsed list. After the loop ends, emit one final batch-summary event:
+
+```
+{"batch_summary":true,"targets_total":N,"succeeded":K,"failed":M,"status":"<...>","fail_fast_triggered":<bool>}
+```
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+### Exit code
 
-3. Load, read the full file, and then execute `./steps-c/step-01-resolve-target.md` to begin the workflow.
+The batch process exits with code `0` when `failed == 0`, otherwise with the exit code of the first failed target (so automators that already branch on the single-target exit-code map continue to work without batch-specific handling). When `--fail-fast` triggers, the exit code is the failing target's code.

package/src/skf-quick-skill/assets/skill-template.md

@@ -101,6 +101,10 @@ Indexed format targeting ~80-120 tokens per skill:
     "assets_count": 0
   },
   "dependencies": [],
-  "compatibility": "{semver-range}"
+  "compatibility": "{semver-range}",
+  "provenance": {
+    "language_hint": "{language_hint or null}",
+    "scope_hint": "{scope_hint or null}"
+  }
 }
 ```

package/src/skf-quick-skill/references/registry-resolution.md

@@ -13,6 +13,8 @@ When the user provides a package name instead of a GitHub URL, use this fallback
 
 Try each registry in order. Stop at first success.
 
+**Per-call timeout:** apply a 10s timeout to each registry HTTP call (15s for the web-search fallback) so a single hung registry cannot stall the workflow under hostile network conditions. Treat a timeout as a soft failure and fall through to the next entry in the chain.
+
 #### 1. npm Registry (JavaScript/TypeScript)
 
 ```