bmad-module-skill-forge 1.2.0 → 1.4.0

package/src/skf-brief-skill/steps-c/step-05-write-brief.md

@@ -1,6 +1,12 @@
 ---
 briefSchemaFile: 'assets/skill-brief-schema.md'
+versionResolutionFile: 'references/version-resolution.md'
+qmdRegistrationFile: 'references/qmd-collection-registration.md'
 nextStepFile: './step-06-health-check.md'
+writeSkillBriefScript: '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+emitBriefEnvelopeScript: '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+forgeTierRwScript: '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
+forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
 
 # Step 5: Write Brief
@@ -15,145 +21,136 @@ To generate the complete skill-brief.yaml from the approved brief data and write
 - Do not change any field values without user request — the brief was already approved
 - Create the output directory if it doesn't exist
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing success summary is NOT the terminal step
+- All user-facing output in `{communication_language}`; written artifact (`description`, `notes`) in `{document_output_language}`
+- **Determinism delegation:** YAML rendering, version-precedence, atomic write, the headless result envelope, and the QMD-collection registry mutation are all delegated to shared SKF scripts. The LLM's job in this step is to assemble inputs, branch on script results, and surface user-facing prose — not to render YAML, JSON envelopes, or YAML-mutation diffs in the model.
 
 ## MANDATORY SEQUENCE
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
-### 1. Load Schema Template
+### 1. Reference the Schema (LLM context only)
 
-Load `{briefSchemaFile}` to reference the YAML template structure.
+`{briefSchemaFile}` and `{versionResolutionFile}` document the brief contract for human readers. The deterministic enforcement of that contract lives in `{writeSkillBriefScript}` and its JSON Schema artifact at `src/shared/scripts/schemas/skill-brief.v1.json`. Load `{briefSchemaFile}` only if you need to explain a specific field to the user during inline adjustments — otherwise skip the read; the script is the source of truth.
 
-### 2. Create Output Directory
+### 2. Resolve Output Path
 
-Create the directory `{forge_data_folder}/{skill-name}/` if it doesn't already exist.
+Resolve the target write path:
+- Primary: `{forge_data_folder}/{skill-name}/skill-brief.yaml`
+- Fallback (when `{forge_data_folder}` is not set or doesn't exist): `{output_folder}/forge-data/{skill-name}/skill-brief.yaml` and inform user "**Note:** forge_data_folder not configured. Writing to {output_folder}/forge-data/{skill-name}/ instead."
 
-If `{forge_data_folder}` is not set or doesn't exist:
-- Fall back to `{output_folder}/forge-data/{skill-name}/`
-- Inform user: "**Note:** forge_data_folder not configured. Writing to {output_folder}/forge-data/{skill-name}/ instead."
+The script's atomic-write helper creates parent directories as needed (`mkdir -p`) — no separate mkdir call required.
 
-### 3. Generate skill-brief.yaml
+### 2b. Existing Brief — Overwrite Policy
 
-**Resolve the `version` field before generating the YAML:**
+Before writing, check whether the resolved target path already exists.
 
-- If `target_version` was set in step 01 (the user explicitly asked for a specific version), use `target_version` as the value of the `version` field. This is the authoritative version for create-skill.
-- Otherwise, use the auto-detected source version from step 02, or `1.0.0` if none was detected.
+**Interactive (`{headless_mode}` is false):**
 
-`target_version` and `version` must never carry different values in the written brief. When the user provided a `target_version`, also include it as a separate `target_version` field so downstream tooling can distinguish "user-requested" from "auto-detected" without re-deriving the provenance — but its value must be identical to `version`.
+If the file exists, present:
 
-Generate the YAML file using the approved field values and the schema template:
+"**An existing brief was found at `{path}`.**
+Overwrite it with the brief you just approved? [Y/N]"
 
-```yaml
----
-name: "{approved skill name}"
-version: "{resolved version — target_version if set, else detected source version, else 1.0.0}"
-source_type: "{source or docs-only}"
-source_repo: "{approved source repo or doc site URL}"
-language: "{approved language}"
-description: "{approved description}"
-forge_tier: "{approved forge tier}"
-created: "{current date}"
-created_by: "{user_name}"
-scope:
-  type: "{approved scope type}"
-  include:
-    - "{approved include patterns}"
-  exclude:
-    - "{approved exclude patterns}"
-  notes: "{approved scope notes or empty string}"
----
-```
+- **[Y]** Overwrite — proceed to §3.
+- **[N]** Cancel — emit a single-line stderr log `brief-skill: overwrite-cancelled at {path}` and HALT with exit code 5 (do not chain to step-06; the run produced no new artifact).
 
-**Conditional optional field inclusion:**
+**Headless (`{headless_mode}` is true):**
 
-**If `target_version` was set in step 01:**
-Include the `target_version` field in the generated YAML — its value MUST be identical to the `version` field above:
-```yaml
-target_version: "{target_version — same value as version}"
-```
+If the file exists:
 
-**If `source_type: "docs-only"` OR supplemental `doc_urls` were collected:**
-Include the `doc_urls` array (uncommented) in the generated YAML:
-```yaml
-doc_urls:
-  - url: "{documentation URL}"
-    label: "{page label}"
-```
-When `source_type: "docs-only"`: `doc_urls` is required (at least one entry), `source_repo` may be set to the doc site URL for reference or omitted.
+- If `force` was supplied as a headless argument: log `"headless: force-overwriting existing brief at {path}"` and proceed to §3.
+- Otherwise: emit the error envelope per §4b with `halt_reason: "overwrite-cancelled"`, then HALT with exit code 5.
 
-**If `scripts_intent` was collected and is not the default `"detect"`:**
-Include the `scripts_intent` field (uncommented):
-```yaml
-scripts_intent: "{none or description}"
-```
+If the file does not exist, proceed normally.
+
+### 3. Write the Brief
 
-**If `assets_intent` was collected and is not the default `"detect"`:**
-Include the `assets_intent` field (uncommented):
-```yaml
-assets_intent: "{none or description}"
+Assemble the brief context as a **flat** JSON object — every approved value is a top-level key, scope is split across four `scope_*` keys instead of nested, and every optional field is passed as `null` when not set rather than conditionally omitted. This eliminates the "decide what to omit" cognitive load that previously made this the most expensive HALT-typo site in the workflow:
+
+```json
+{
+  "name":             "{approved skill name}",
+  "target_version":   "{target_version from step 01, or null}",
+  "detected_version": "{auto-detected version from step 02, or null}",
+  "source_type":      "{source or docs-only}",
+  "source_repo":      "{approved source repo or doc site URL}",
+  "language":         "{approved language}",
+  "description":      "{approved description}",
+  "forge_tier":       "{Quick|Forge|Forge+|Deep}",
+  "created":          "{current ISO date YYYY-MM-DD}",
+  "created_by":       "{user_name}",
+  "scope_type":       "{approved scope type}",
+  "scope_include":    ["{approved include patterns}"],
+  "scope_exclude":    ["{approved exclude patterns}"],
+  "scope_notes":      "{approved scope notes or empty string}",
+  "doc_urls":         null | [{"url": "...", "label": "..."}],
+  "scripts_intent":   null | "{detect|none|free-text}",
+  "assets_intent":    null | "{detect|none|free-text}",
+  "source_authority": null | "{official|community|internal}"
+}
 ```
 
-**Always include** `source_authority` (default: `"community"`, forced to `"community"` when `source_type: "docs-only"`):
-```yaml
-source_authority: "{official|community|internal}"
+Pipe it into the writer script with the `--from-flat` flag:
+
+```bash
+echo '<context-json>' | uv run {writeSkillBriefScript} write --target {resolved-target-path} --from-flat
 ```
 
-### 4. Write the File
+The script translates flat → nested internally, drops the null optional fields, and runs the same schema validation and atomic write as before — pass every key always, the writer decides what reaches the YAML.
 
-Write the generated YAML to `{forge_data_folder}/{skill-name}/skill-brief.yaml`.
+The script:
+- Validates the context against `src/shared/scripts/schemas/skill-brief.v1.json`
+- Applies the version-precedence rule from `{versionResolutionFile}`
+- Enforces the `target_version == version` invariant (refuses to write a brief that violates it)
+- Renders YAML in canonical key order (byte-stable across runs)
+- Atomically writes the file via temp + fsync + rename (no half-written file ever visible)
+- Emits a JSON success envelope on stdout: `{"status":"ok","brief_path":"…","version":"…","bytes":…,"warnings":[…]}`
 
-If write fails: **HALT** — "**Error:** Failed to write skill-brief.yaml. Please check that the directory is writable and try again."
+**On script failure (non-zero exit):**
+- Exit 1 (validation/invariant): The error JSON on stderr names the offending field. This indicates a context-assembly bug, not a user error — surface the message to the user, log it, then HALT.
+  - Interactive: **HALT** — display the error JSON's `message` field.
+  - Headless: emit the error envelope per §4b with `halt_reason: "input-invalid"`, then `exit 2`.
+- Exit 2 (I/O failure): The atomic write failed (target unwritable, disk full, etc.).
+  - Interactive: **HALT** — "**Error:** Failed to write skill-brief.yaml. Check that the directory is writable and try again."
+  - Headless: emit the error envelope per §4b with `halt_reason: "write-failed"`, then `exit 4`.
 
-### 5. QMD Collection Registration (Deep Tier Only)
+**On success:** capture `brief_path` and `version` from the response envelope — both are needed for §4b and §6.
 
-**IF forge tier is Deep AND QMD tool is available:**
+**Draft cleanup.** After a successful write, remove `{forge_data_folder}/{skill-name}/.brief-draft.json` if it exists (`rm -f` — silent on absent). The draft was a step-01 §7 checkpoint covering the in-flight workflow window; once the brief is written it is no longer meaningful. In headless mode this rm is a no-op (drafts are only written interactively).
 
-Index the skill brief into a QMD collection so that portfolio-level searches can find existing briefs and avoid duplicate skill creation across large monorepos.
+### 4b. Headless Result Envelope (Canonical)
 
-**Collection creation:**
+This section is the canonical envelope-emission reference for the workflow. Every headless emission — the success terminal here and every HARD HALT in step-01/02/05 — uses this contract. Remote sites point here instead of restating it.
+
+**Success (this call site only — emitted from §3 directly):**
 
-Create a QMD collection targeting only the brief file:
 ```bash
-qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --mask "skill-brief.yaml"
-qmd embed
+echo '{"status":"success","brief_path":"<from §3 response>","skill_name":"<name>","version":"<from §3 response>","language":"<language>","scope_type":"<scope.type>","halt_reason":null}' | \
+  uv run {emitBriefEnvelopeScript} emit
 ```
 
-If collection already exists (re-briefing): remove and recreate for atomic replace:
+**Error (used by every HARD HALT site):**
+
 ```bash
-qmd collection remove {skill-name}-brief
-qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --mask "skill-brief.yaml"
-qmd embed
+echo '{"status":"error","skill_name":"<name>","halt_reason":"<reason>"}' | \
+  uv run {emitBriefEnvelopeScript} emit --target stderr
 ```
 
-**Embed verification:**
+When the HALT fires before `skill_name` has been resolved (step-01 §1 pre-flight write probe, step-01 §8 input-missing on a malformed args bundle), pass the partially-gathered value or the literal `"unknown"` — the script accepts any non-empty string at this position.
 
-After `qmd embed` completes, verify the collection was embedded:
-- Run `qmd status` or `qmd collection list` and confirm `{skill-name}-brief` shows document count > 0
-- If verification succeeds: proceed to registry update normally
-- If verification fails: log warning "QMD embed verification failed for {skill-name}-brief — collection may not be searchable yet", still proceed to registry update but add `status: "pending"` field to the registry entry
+The script derives `exit_code` deterministically from `halt_reason` (null→0, input-missing/input-invalid→2, forge-tier-missing/target-inaccessible/gh-auth-failed→3, write-failed→4, overwrite-cancelled→5, user-cancelled→6 [interactive-only — headless never raises this]), validates against `src/shared/scripts/schemas/skf-brief-result-envelope.v1.json`, and prints the prefixed `SKF_BRIEF_RESULT_JSON: {…}` line.
 
-**Registry update:**
+The script enforces the success/error halt_reason invariant (success requires null halt_reason; error requires non-null). The `user-cancelled` halt_reason is accepted for completeness (interactive `[X]` Cancel sites in step-01/03/04) but never appears on the headless code path.
 
-Read `{sidecar_path}/forge-tier.yaml` and update the `qmd_collections` array.
+Invocation sites (each pointed at this block, not duplicated): step-01 §1 (write-failed pre-resolution), step-01 §8 (input-missing/input-invalid GATE), step-05 §2b (overwrite-cancelled), step-05 §3 (input-invalid/write-failed from script). Step-01 §1 forge-tier-missing and step-02 §1 (target-inaccessible/gh-auth-failed) currently HALT without emitting an envelope — pre-existing gaps tracked separately, not addressed by this canonicalization.
 
-If an entry with `name: "{skill-name}-brief"` already exists, replace it. Otherwise, append:
+When `{headless_mode}` is false, skip this section silently — no envelope is emitted.
 
-```yaml
-  - name: "{skill-name}-brief"
-    type: "brief"
-    source_workflow: "brief-skill"
-    skill_name: "{skill-name}"
-    created_at: "{current ISO date}"
-    # status: "pending"    # Added only when embed verification fails
-```
-
-Write the updated forge-tier.yaml.
+### 5. QMD Collection Registration (Deep Tier Only)
 
-**Error handling:**
-- If QMD collection creation fails: log the error. Do NOT fail the workflow — the brief file was already written successfully.
-- If forge-tier.yaml update fails: log the error, continue.
+**IF forge tier is Deep AND QMD tool is available:** load `{qmdRegistrationFile}` and follow the procedure there to index the brief into a QMD collection and update the forge-tier registry.
 
-**IF forge tier is NOT Deep:** Skip this section silently. No messaging.
+**IF forge tier is NOT Deep OR QMD is not available:** skip this section silently — do not load `{qmdRegistrationFile}`. No messaging.
 
 ### 6. Display Success Summary
 
@@ -161,7 +158,7 @@ Write the updated forge-tier.yaml.
 
 ---
 
-**File:** `{forge_data_folder}/{skill-name}/skill-brief.yaml`
+**File:** `{brief_path from §3 response}`
 **Skill:** {name}
 **Language:** {language}
 **Scope:** {scope type}
@@ -190,4 +187,3 @@ ONLY WHEN the brief file has been written and the success summary displayed will
 ## CRITICAL STEP COMPLETION NOTE
 
 This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the brief-skill workflow is fully done.
-

package/src/skf-brief-skill/steps-c/step-06-health-check.md

@@ -1,7 +1,7 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/`
+# during development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
@@ -16,7 +16,16 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 - No user-facing reports, file writes, or result contracts in this step — those belong in step-05
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
+- All user-facing output in `{communication_language}`
 
 ## MANDATORY SEQUENCE
 
 Load `{nextStepFile}`, read it fully, then execute it.
+
+## Completion criteria
+
+This is the terminal step of brief-skill. The workflow is complete when `{nextStepFile}` returns control — do not transition to any further step.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Step 06 is the terminal stage of brief-skill. After `{nextStepFile}` returns control, the brief-skill workflow is fully complete — do not re-enter step-05 or step-06, do not load any further step file, and do not loop back into the workflow.

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)
 
 ```