bmad-module-skill-forge 2.1.0 → 3.0.0

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

@@ -11,11 +11,10 @@ The fastest path to a skill — accept a GitHub URL or package name, resolve to
 
 ## Conventions
 
-- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
-- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
-- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root, `{skill-root}`: this skill's installed directory, where `customize.toml` lives.
 - `{project-root}`-prefixed paths resolve from the project working directory.
-- `{skill-name}` resolves to the skill directory's basename.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; e.g. `shared/health-check.md`, which the terminal step chains to.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
 
 ## Role
 
@@ -26,26 +25,22 @@ You are a rapid skill compiler collaborating with a developer. You bring source
 These rules apply to every step in this workflow:
 
 - Never fabricate content — all data must come from source extraction or user input
+- Never write into a skill folder SKF did not generate
 - Only load one step file at a time — never preload future steps
 - Always communicate in `{communication_language}`
-- **Universal cancel-line affordance** — at any interactive prompt the user may type `cancel`, `exit`, `:q`, or select the `[X] Cancel and exit` menu option (where surfaced) to leave cleanly. HARD HALT with **exit code 6 (user-cancelled)** and emit the error result contract per `references/halt-contract.md` with `error.code: "user-cancelled"`. In step 4 §6 the equivalent affordance is `[Q] Quit without writing` — same exit code, same envelope contract.
-- 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 and `<slug>` is the kebab portion of the filename (see the Stages table below for the canonical list). One line per event; do not pretty-print.
+- **Universal cancel-line affordance**: at any interactive prompt the user may type `cancel`, `exit`, `:q`, or select the `[X] Cancel and exit` menu option (where surfaced) to leave cleanly. HARD HALT with **exit code 6 (user-cancelled)**: stage `{"phase": "<the step's slug>", "halt_reason": "user-cancelled", "reason": "Cancelled. No files were written.", "skill_package": null}` as `{run_dir}/halt.json` and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"` (`references/halt-contract.md`). In step 4 §6 the equivalent affordance is `[Q] Quit without writing`, with the same exit code and envelope.
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action, and record each auto-decision in the run folder the moment its gate decides, so the envelope's `headless_decisions` carries it: stage `{"gate": "<the gate's name>", "default_action": "<X>", "taken_action": "<X>", "reason": "headless: <why>"}` as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-quick-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`. Each gate names its gate and default where it decides.
+- If `{headless_mode}` is true, print the one-line JSON progress events on stderr that `references/halt-contract.md` (Headless Events) defines: when each step starts, just before it chains on, and at a HARD HALT.
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Resolve Target | references/resolve-target.md | Yes |
-| 2 | Ecosystem Check | references/ecosystem-check.md | Yes |
-| 3 | Quick Extract | references/quick-extract.md | Yes |
+| 1 | Resolve Target | references/resolve-target.md | Conditional (no target, or an ambiguous one) |
+| 2 | Ecosystem Check | references/ecosystem-check.md | Conditional (an official skill matches) |
+| 3 | Quick Extract | references/quick-extract.md | Conditional (an unusual repo shape, zero exports) |
 | 4 | Compile | references/compile.md | No (review) |
-| 5 | Write & Validate | references/write-and-validate.md | Yes |
+| 5 | Write & Validate | references/write-and-validate.md | Conditional (the skill folder exists) |
 | 6 | Finalize | references/finalize.md | Yes |
 | 7 | Workflow Health Check | references/health-check.md | Yes |
 
@@ -53,62 +48,68 @@ These rules apply to every step in this workflow:
 
 | Aspect | Detail |
 |--------|--------|
-| **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 4 |
-| **Gates** | step 1: target input, multi-language disambiguation [C/A]; step 2: ecosystem match [P/I/A] (if match); step 3: repo-shape [C/A] + zero-exports rescue [R/P/A]; step 4: review [C/E/S/Q]; step 5: overwrite [Y/N] |
-| **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 `references/halt-contract.md` |
+| **Inputs** | target (GitHub URL, package name or npm, PyPI or crates.io page URL) [required for single-target mode], language_hint [optional, `--language-hint`], scope_hint [optional, `--scope-hint`] |
+| **Overrides** | `--language-hint`, `--scope-hint`, `--description`, `--exports`, `--skip-snippet`, `--no-active-pointer`, `--batch <file>`, `--fail-fast`: see On Activation step 4 |
+| **Gates** | step 1: target input, ambiguous package name [C/n/U/X] (if another registry also holds the name; headless keeps the first registry's pick), multi-language disambiguation [C/n/A] (pick any detected language); step 2: ecosystem match [P/I/A] (none until agentskills.io has a registry API); step 3: repo-shape [C/A] + zero-exports rescue [R/P/A]; step 4: review [C/E/S/Q]; step 5: overwrite [Y/N] |
+| **Outputs** | SKILL.md, context-snippet.md, metadata.json, active pointer, result contract (timestamped + `-latest` copy), one `SKF_QUICK_SKILL_RESULT_JSON` line (stdout when the run finishes, stderr at a HARD HALT), and under `--batch` the batch summary. Snippet and active pointer can be skipped per overrides. |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true; each auto-decision is recorded in the envelope's `headless_decisions` |
+| **Exit codes** | See `references/halt-contract.md`: the exit-code map and the envelope every HARD HALT emits, except On Activation step 1's check for `python3` and `uv`, which prints none |
 
-## Exit Codes & HARD HALT Contract
+## On Activation
 
-See `references/halt-contract.md` for the exit-code map and the error-result envelope every HARD HALT emits (the `SKF_QUICK_SKILL_RESULT_JSON:` stderr line, the on-disk `-latest.json` write once `{skill_package}` is known, and the schema). Steps load it on their failure path so the wire format survives compaction.
+1. Read `{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` and `sidecar_path`.
 
-## On Activation
+   Then check the runtime: every helper this workflow runs, the envelope emitter included, runs through `uv run`, so confirm that `python3` and `uv` are both on `$PATH` (`command -v python3` and `command -v uv`). If either is missing, HARD HALT with **exit code 3 (resolution-failure)**: display "**Quick Skill needs `{the missing tool}`, which is not on your PATH.** Install it (`uv` from <https://docs.astral.sh/uv/getting-started/installation/>, `python3` from <https://www.python.org/downloads/>), then re-run." No envelope is printed: the emitter needs `uv` too.
 
-1. Read `{project-root}/_bmad/skf/config.yaml` and `{sidecar_path}/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`, `sidecar_path`
-   - From preferences: `headless_mode` (default false)
+   Then resolve `{emitEnvelopeHelper}` ← the first existing path of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` and `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`, the shared emitter every envelope and auto-decision goes through, and create the run folder:
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `preferences.yaml`. Default: false.
+   ```bash
+   mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-quick-skill-XXXXXXXX"
+   ```
 
-3. **Resolve workflow customization.** Run:
+   Bind `{run_dir}` ← the path it prints (a finished run deletes it; a halted one keeps it). If it cannot be created, HARD HALT with **exit code 4 (write-failure)**: display "**Quick Skill cannot start: the run folder could not be created.** {the first stderr line}" and emit with nothing to stage in:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --target stderr <<'SKF_JSON'
+   {"phase": "on-activation", "halt_reason": "write-failure", "reason": "<that message, one line>", "skill_package": null}
+   SKF_JSON
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+   With no emitter path (an incomplete install), each halt displays its message alone and step 6 §3 writes no result contract.
 
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `{sidecar_path}/preferences.yaml` sets `headless_mode: true`. Default: false.
 
-   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+3. **Resolve workflow customization.** Run:
 
-   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the three scalars, if the merged value is empty or absent, use the bundled default:
+   ```bash
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
+   ```
 
-   - `{skillTemplatePath}` ← `workflow.skill_template_path` if non-empty, else `assets/skill-template.md`
-   - `{registryResolutionPath}` ← `workflow.registry_resolution_path` if non-empty, else `references/registry-resolution.md`
-   - `{batchOutputPath}` ← `workflow.batch_output_path` if non-empty, else `{skills_output_folder}/_batch/`
-   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — step 6 §3 skips the hook invocation entirely)
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-quick-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) and, when `{emitEnvelopeHelper}` has a path, record it in the run sink: write `customization_resolver_unavailable: {customization_resolver_unavailable}` to `{run_dir}/resolver-warning.txt` with a file write, never `echo` (the reason can hold quotes or `$( )`), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"`. Under `--batch`, `references/batch-mode.md` §2 records that file in each target's run folder.
 
-   Stash all four as workflow-context variables. Stage files reference `{skillTemplatePath}` / `{registryResolutionPath}` / `{batchOutputPath}` / `{onCompleteCommand}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies (custom template, registry chain, batch output dir) or wire in a post-completion hook (git-add, register, notify) without forking the skill.
+   Bind these three as workflow-context variables, taking the default when the merged value is empty or absent:
 
-   **Apply the array surfaces** so the declared overrides are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries are paths or globs whose contents load as facts — the bundled default loads any `project-context.md`); then, after activation completes and before the first stage runs, execute each entry in `workflow.activation_steps_append` in order.
+   - `{skillTemplatePath}` ← `workflow.skill_template_path`, else `assets/skill-template.md`
+   - `{batchOutputPath}` ← `workflow.batch_output_path`, else `{skills_output_folder}/_batch/`
+   - `{onCompleteCommand}` ← `workflow.on_complete`, else empty (step 6 §3 then runs no hook)
 
-4. **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.
+   Run each `workflow.activation_steps_prepend` entry now, in order. Hold every `workflow.persistent_facts` entry as standing context for the whole run; a `file:` entry loads the contents of the paths or globs it names: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off. Once step 4 has parsed the flags, before step 5 or 6 starts the run, run each `workflow.activation_steps_append` entry in order.
+
+4. **Parse CLI overrides** into the workflow context as `{overrides}`:
 
    | Flag | Effect |
    | --- | --- |
-   | `--description "<string>"` | Override the LLM-derived description in step 4 §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 4 §2 Key Exports and the count-derived metadata stats. |
-   | `--skip-snippet` | Skip context-snippet.md generation in step 4 §3 and its write in step 5 §2. Artifact omitted from `outputs`; step 5 §5 advisory snippet validation reports a "skipped" entry. |
-   | `--no-active-pointer` | Skip the active-pointer flip in step 6 §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 `references/batch-mode.md` 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. |
+   | `--language-hint <lang>` | Sets `language_hint`: step 1 §4 takes it as the language, with no detection and no multi-language gate, and step 1 §3 asks only that language's registry. |
+   | `--scope-hint <path>` | Sets `scope_hint`: the folder step 3 reads the entry points and skill folders from. |
+   | `--description "<string>"` | Replaces the extracted description in step 4 §2, which checks its length and voice as it checks an extracted one. |
+   | `--exports "<name1,name2,...>"` | Replaces the extracted export list in step 4 §2: comma-separated, each name trimmed, empty items skipped. |
+   | `--skip-snippet` | No context-snippet.md: step 4 §3 and step 5 §2 skip it. |
+   | `--no-active-pointer` | Step 6 §1 leaves `{skill_group}/active` as it is. |
+   | `--batch <file>` | Compiles every target the file lists, headless (On Activation step 5); `--skip-snippet` and `--no-active-pointer` apply to every target in the batch. |
+   | `--fail-fast` | With `--batch`: the batch stops at the first failed target. |
+
+   `--language-hint`, `--scope-hint`, `--description` and `--exports` are single-target flags: batch mode refuses them.
 
-5. **If `--batch` is set**, force `{headless_mode} = true` (log "headless: coerced by --batch" if it was false), then load and read `references/batch-mode.md` in full before proceeding. Follow its protocol to read the batch file, parse the target list, and drive the batch loop that wraps the step 1 → step 7 pipeline that follows.
+5. **If `--batch` is set**, load and read `references/batch-mode.md` in full before anything else and follow it.
 
-6. Load, read the full file, and then execute `references/resolve-target.md` to begin the workflow. (In batch mode, control returns here for each subsequent target after step 7 completes; see `references/batch-mode.md`.)
+6. Load, read the full file, and then execute `references/resolve-target.md` to begin the workflow; when `{headless_mode}` is true, print step 1's `start` event first (`references/halt-contract.md`). In batch mode, `references/batch-mode.md` loads it for each target instead.

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

@@ -28,10 +28,10 @@ description: >
 {README-derived description of what the package does}
 
 ## Key Exports
-{List of public exports with brief descriptions}
+{List of public exports with brief descriptions. For a skills module: each skill with its description, then each menu code with its description, display name and the skill it runs}
 
 ## Usage Patterns
-{Common usage patterns extracted from README examples}
+{Common usage patterns extracted from README examples. For a skills module with module-help.csv: one entry per row, giving the menu code, display name and description, the skill and action it runs, its args, and the skills it follows or precedes}
 ```
 
 ### Optional Sections (include when data available)
@@ -108,3 +108,5 @@ Indexed format targeting ~80-120 tokens per skill:
   }
 }
 ```
+
+For a skills module (`repo_shape: skills-module`), `exports` lists the skill names, then the menu codes, and the export counts in `stats` and `confidence_distribution.t1_low` count both.

package/src/skf-quick-skill/customize.toml

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-quick-skill.
-# Team overrides:     _bmad/custom/skf-quick-skill.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-quick-skill.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-quick-skill.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-quick-skill.user.toml
 
 [workflow]
 
@@ -10,15 +10,17 @@
 #   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
 #   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
 
-# Steps to run before the standard activation (uv probe, config load).
-# Overrides append. Use for org-wide pre-flight checks (auth, network,
-# compliance) that must precede any compilation work.
+# Steps to run in SKILL.md On Activation step 3: after config.yaml is read,
+# the run folder created and headless mode resolved, before the CLI flags are
+# parsed and before any stage runs. Overrides append. Use for org-wide
+# pre-flight checks (auth, network, compliance) that must precede any
+# compilation work.
 
 activation_steps_prepend = []
 
-# Steps to run after activation but before the first stage executes.
-# Overrides append. Use for context loads or banner customization that
-# should run once activation completes successfully.
+# Steps to run once activation completes (step 4 has parsed the CLI flags),
+# before step 1 or a --batch run starts; a batch runs them once, not per
+# target. Overrides append. Use for context loads or banner customization.
 
 activation_steps_append = []
 
@@ -26,28 +28,57 @@ activation_steps_append = []
 # (house style, naming conventions, compilation guardrails).
 # Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "All skills must cite their upstream source."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/skill-style.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-quick-skill.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
-# --- Optional asset overrides ---
-#
-# Lift the canonical asset paths so orgs can substitute house-style copies
-# without forking the skill. Empty string = use the bundled default.
+# --- Optional overrides. An empty string means the default named below. ---
+
+# The template step 4 assembles SKILL.md and context-snippet.md from, a path
+# from the skill root. Default: assets/skill-template.md. A house-style copy
+# may reword it and add optional sections, and must keep:
+#   - its `## SKILL.md Section Structure` and `## context-snippet.md Format`
+#     headings, which step 4 reads;
+#   - the `## Overview`, `## Description`, `## Key Exports` and
+#     `## Usage Patterns` headings: step 5's output validator requires all
+#     four, and the snippet's `#key-exports` and `#usage-patterns` anchors
+#     point at the last two.
+# metadata.json is read from a copy only when skf-render-quick-metadata.py
+# is missing or fails twice, so leave the copy's `## metadata.json Format`
+# section as bundled.
+
+skill_template_path = "assets/skill-template.md"
+
+# The folder a --batch run writes its summary to
+# (quick-skill-batch-<timestamp>.json and quick-skill-batch-latest.json),
+# ending in a slash. Default: {skills_output_folder}/_batch/.
 
-skill_template_path = ""
-registry_resolution_path = ""
-batch_output_path = ""
+batch_output_path = "{skills_output_folder}/_batch/"
 
-# Optional post-completion hook. When non-empty, invoked with
-# `--skill-package=<path>` after the result contract is finalized in step 6.
-# Failures are logged but never fail the workflow. Use for git-add,
-# skill-registry registration, or a notifier on the freshly compiled skill.
+# Optional post-completion hook: a shell command, not an instruction. Step 6
+# runs it once the success envelope is printed and the result contract
+# written, as:
+#   <on_complete> --result-path=<skill package>/quick-skill-result-latest.json
+# The result file sits in the skill package, which then holds SKILL.md,
+# metadata.json and context-snippet.md (unless --skip-snippet); its
+# `outputs` list those paths. It is skipped when the emitter wrote no result
+# file, or not that -latest copy. Under --batch it runs once per target
+# that finishes; a HARD HALT never runs it. A failure is logged and never
+# fails the workflow, and the envelope, already printed, does not carry it.
+# Use for git-add, skill-registry registration, or a notifier on the
+# freshly compiled skill. Empty string = no hook (default).
 
 on_complete = ""

package/src/skf-quick-skill/references/batch-mode.md

@@ -1,12 +1,22 @@
 ---
 nextStepFile: 'resolve-target.md'
+healthCheckStepFile: 'health-check.md'
+quickBatchProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-quick-batch.py'
+  - '{project-root}/src/shared/scripts/skf-quick-batch.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
 
 # 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, and batch meta-workflows.
+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, and batch meta-workflows. The batch's place in the file and every target's outcome live in the batch run folder, kept by `skf-quick-batch.py`, never only in context, so a context compaction mid-batch loses neither, and the helper computes the counts, the status and the exit code.
+
+## Before the Batch Starts
+
+SKILL.md On Activation step 5 loads this file before anything else. `--skip-snippet` and `--no-active-pointer` apply to every target. `--description` and `--exports` are single-target overrides: one description or export list cannot fit every target. `--language-hint` and `--scope-hint` are single-target flags too: a batch line gives its own target a hint with `language=` and `scope=` (Input format below). When any of the four was passed, HARD HALT with **exit code 2 (input-invalid)** before any target runs: "**`{the flags passed}` do not combine with `--batch`.** They would apply the same description, export list or hint to every skill in the batch. Run each target that needs its own description or export list on its own, give a batch line its own `language=` or `scope=`, or drop the flag and let each target's extraction supply it." Stage `{"phase": "on-activation", "halt_reason": "input-invalid", "reason": "<the message's first sentence>", "skill_package": null, "details": {"flags": [<the flags passed>], "batch_file": "<file>"}}` as `{run_dir}/halt.json` and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`; no batch summary is written.
+
+Otherwise `--batch` implies `--headless`: set `{headless_mode}` to true (log "headless: coerced by --batch" if it was false) and go on to Execution.
 
 ## Input format
 
@@ -20,7 +30,7 @@ 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:
+# Per-line modifiers: overrides for THIS target only
 lodash language=javascript scope=src/
 cognee@0.5.0 language=python scope=cognee/api/
 ```
@@ -29,32 +39,70 @@ 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. |
+| `language=<lang>` | Sets `language_hint` for this target: the same effect as `--language-hint` on a single-target run. |
+| `scope=<path>` | Sets `scope_hint` for this target: the same effect as `--scope-hint` 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.
+The target stays whole, its version included (`cognee@0.5.0`, `requests==2.31.0`): step 1 §1b reads the version as it reads a single target's. A modifier key may be in any letter case; its value must not be empty, and each modifier may appear once. A line with any other word after its target is taken whole as the target, so step 1 cannot parse it and that target fails while the rest of the batch runs.
 
 ## Execution
 
-`--batch` implies `--headless`. The batch loop runs the full quick-skill pipeline (steps 1–7) for each target in file order:
+Resolve `{quickBatchHelper}` from `{quickBatchProbeOrder}`; first existing path wins. `{batch_dir}` is the run folder SKILL.md On Activation step 1 created (`{run_dir}` until the first target), and `{batch_file}` the file given to `--batch`. After a compaction, `{batch_dir}` is the parent folder of the target's `{run_dir}`: the `{project-root}/_bmad-output/.skf-run/skf-quick-skill-*` folder that holds `batch.jsonl`.
+
+### 1. Start the Batch
+
+```bash
+uv run {quickBatchHelper} start "{batch_file}" --run-dir "{batch_dir}" [--fail-fast]
+```
 
-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 7 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.
+Pass `--fail-fast` when it was given. The helper parses the file and writes the batch file `{batch_dir}/batch.jsonl`, status running and every target pending; run again on the same file, after a compaction for example, it changes nothing. If it exits non-zero, the `halt_reason` of its stderr JSON names the halt; no target runs and no batch summary is written (`references/halt-contract.md`):
+
+- **`input-invalid`** (a batch file it cannot read, or a run folder that holds another batch), or no path in `{quickBatchProbeOrder}` exists (an incomplete install): HARD HALT with **exit code 2 (input-invalid)**: display "**The batch cannot start:** {its `message`, or: skf-quick-batch.py is missing, re-install SKF}", stage `{"phase": "batch-mode", "halt_reason": "input-invalid", "reason": "The batch cannot start: <that message>", "skill_package": null, "details": {"batch_file": "{batch_file}"}}` as `{batch_dir}/halt.json` and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --run-dir "{batch_dir}" --target stderr < "{batch_dir}/halt.json"`.
+- **`write-failure`** (the batch run folder cannot be written, so it cannot hold `halt.json` either): HARD HALT with **exit code 4 (write-failure)**: display "**The batch cannot start:** {its `message`}" and emit with nothing to stage in:
+
+  ```bash
+  uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --target stderr <<'SKF_JSON'
+  {"phase": "batch-mode", "halt_reason": "write-failure", "reason": "The batch cannot start: <its message, one line>", "skill_package": null}
+  SKF_JSON
+  ```
+
+### 2. Take the Next Target
+
+```bash
+uv run {quickBatchHelper} next --run-dir "{batch_dir}"
+```
 
-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 `references/halt-contract.md`).
+- **`"status": "next"`**: the helper printed the target's `start` event on stderr: display it verbatim, then print step 1's `start` event (Headless events below). Bind `{run_dir}` ← its `run_dir` (the target's own run folder, created empty), and set `target`, `language_hint` and `scope_hint` from it. When `{batch_dir}/resolver-warning.txt` exists (SKILL.md On Activation step 3 wrote it, so the customization resolver could not run), record it in the target's sink: `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{batch_dir}/resolver-warning.txt")"`. Nothing else carries over from the previous target: its version, repository, extraction, compiled output, `{skill_package}` and summary values all start empty. Then load, read in full and execute `{nextStepFile}`: steps 1 to 6 run for this target.
+- **`"status": "record"`**: target `batch` ended, its payload staged, before §3 recorded it (a compaction came between its envelope and §3): go to §3 with that `batch`, never running it again.
+- **`"status": "done"`**: no target is pending, or `--fail-fast` ended the batch after a failed target. Go to §4.
+
+### 3. Record the Target
+
+Every target ends here: step 6 §4 returns here when the target finishes, and every HARD HALT of steps 1 to 6 returns here after its envelope (`references/halt-contract.md`, In `--batch`), the step 5 ownership halt included. Control returns here even when the step that ended the target reads as the end of the run. Record it:
+
+```bash
+uv run {quickBatchHelper} record --run-dir "{batch_dir}" --batch {batch} --target stderr
+```
+
+`{batch}` is the number §2's `next` printed. The helper reads how the target ended from what its run folder staged for the emitter (`halt.json`, or step 6's `result-context.json`), appends the outcome to the batch file, removes the run folder of a target that succeeded, and prints the target's `done` or `fail` event on stderr: display it verbatim. Then go back to §2. If it exits non-zero, its `message` names what is missing: stage the payload the target ended with, record again, then go back to §2.
+
+### 4. Batch Summary
+
+```bash
+uv run {quickBatchHelper} summarize --run-dir "{batch_dir}" --output-dir "{batchOutputPath}" --target stderr
+```
+
+The helper counts the targets, sets the batch status and exit code, writes the summary files below, appends the final status to the batch file (and removes the batch run folder when no target failed), and prints the `batch_summary` event on stderr: display it verbatim. Then print step 7's `start` event and load, read in full and execute `{healthCheckStepFile}`: the health check runs once per batch, here. The batch ends with the event's `exit_code`.
 
 ## Batch summary contract
 
-After the last target completes (or `--fail-fast` triggers an early exit), write the batch summary at:
+`summarize` writes the batch summary at:
 
 ```
 {batchOutputPath}quick-skill-batch-{YYYYMMDD-HHmmss}.json
 {batchOutputPath}quick-skill-batch-latest.json   (copy, not symlink)
 ```
 
-`{batchOutputPath}` is resolved at SKILL.md On Activation §3 from `workflow.batch_output_path` (bundled default `{skills_output_folder}/_batch/`, trailing slash included).
+`{batchOutputPath}` is resolved at SKILL.md On Activation §3 from `workflow.batch_output_path` (bundled default `{skills_output_folder}/_batch/`, trailing slash included). The per-batch name gains `-2`, `-3` and so on when another batch ended in the same second.
 
 Schema:
 
@@ -64,41 +112,46 @@ Schema:
   "mode": "batch",
   "status": "success | partial | failed",
   "timestamp": "<ISO 8601 UTC>",
-  "input_file": "<path passed to --batch>",
+  "input_file": "<absolute path of the file passed to --batch>",
   "targets_total": 0,
   "succeeded": 0,
   "failed": 0,
   "fail_fast_triggered": false,
+  "exit_code": 0,
   "results": [
     {
+      "batch": 1,
       "target": "<line from batch file>",
       "status": "success | error",
       "exit_code": 0,
       "skill_package": "<absolute path or null>",
-      "error_code": null
+      "error_code": null,
+      "quality_score": 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.
+`status` resolves as: `"success"` when `failed == 0`, a batch file with no target included (it ends at once, `targets_total` 0 and exit code `0`); `"partial"` when `failed > 0 && succeeded > 0`; `"failed"` when `failed > 0 && 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. Each `results[]` entry is one target in file order: its `batch` number, its `exit_code` and `error_code` (the `halt_reason` of its halt envelope, null on success), and its `quality_score`, the skill-check score of its success envelope (null when it failed or skill-check did not run).
 
 ## Headless events
 
-Batch mode emits per-target boundary events on stderr in addition to the per-step events documented in Workflow Rules:
+Batch mode emits per-target boundary events on stderr in addition to the per-step events of `references/halt-contract.md` (Headless Events):
 
 ```
 {"batch":<n>,"target":"<target>","status":"start"}
-{"batch":<n>,"target":"<target>","status":"done","exit":<code>}
+{"batch":<n>,"target":"<target>","status":"done","exit":0}
 {"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:
+`<n>` is the 1-based index of the target in the parsed list. `next` prints the `start` event; `record` prints `done` or `fail`. After the loop ends, `summarize` prints one final batch-summary event:
 
 ```
-{"batch_summary":true,"targets_total":N,"succeeded":K,"failed":M,"status":"<...>","fail_fast_triggered":<bool>}
+{"batch_summary":true,"targets_total":N,"succeeded":K,"failed":M,"status":"<...>","fail_fast_triggered":<bool>,"exit_code":<code>,"summary_path":"<path>"}
 ```
 
 ## Exit code
 
-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.
+Without `--fail-fast`, the batch runs every target, whatever an earlier target's outcome, and exits with the batch summary's `exit_code`: `0` when `failed == 0`, otherwise the highest exit code among the failed targets. Automators that branch on the single-target exit-code map read each target's own code in `results[]`. With `--fail-fast`, the batch stops at the first failed target and exits with that target's code.
+
+A batch refused before its first target writes no batch summary. It exits with code `2` when `--description` or `--exports` was passed with `--batch` (or `--language-hint` or `--scope-hint`), §1 cannot read the batch file or `skf-quick-batch.py` is missing, and with code `4` when §1 cannot write the batch run folder.