bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-quick-skill/references/compile.md

@@ -16,9 +16,10 @@ To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-alig
 
 ## Rules
 
-- Focus only on assembling the three output documents — do not write files to disk (that's step 6)
+- Focus only on assembling the three output documents: do not write files to disk (step 5 writes them)
 - Follow template structure exactly from {skillTemplateData}
 - Mark any sections with insufficient data as best-effort
+- A HARD HALT prints, after its envelope, this step's `halt` event when `{headless_mode}` is true. Under `--batch` it ends only this target: then return to `references/batch-mode.md` §3, even when the halt reads as the end of the run (`references/halt-contract.md`).
 
 ## Steps
 
@@ -34,7 +35,7 @@ Load {skillTemplateData} to understand:
 Populate the SKILL.md section structure from `{skillTemplateData}` § "SKILL.md Section Structure" (the frontmatter skeleton and the Required/Optional section list live there) using extraction_inventory. The rules below are the deltas the template does not encode:
 
 **Frontmatter rules (agentskills.io compliance):**
-- `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`) for clarity.
+- `name` is `{repo_name}`: step 5 writes that folder and validates the name against it.
 - `description`: non-empty, max 1024 chars, optimized for agent discovery. Use third-person voice ("Processes..." not "I can..." / "You can...") so it reads correctly in the agent's skill index.
 - No other frontmatter fields — only `name` and `description` for community skills
 
@@ -42,48 +43,52 @@ Populate the SKILL.md section structure from `{skillTemplateData}` § "SKILL.md
 - **Description:** From `{overrides.description}` if set (subject to the same length/voice checks as extracted descriptions); otherwise from extraction_inventory.description (README-derived)
 - **Key Exports:** From `{overrides.exports}` if set (comma-separated names parsed and trimmed; empty items skipped); otherwise from extraction_inventory.exports — list each with name, type, brief description
 
-**Scripts & Assets Note** (add as an optional section if source contains `scripts/`, `bin/`, `assets/`, `templates/`, or `schemas/` directories): "This package may include scripts and assets. Run create-skill for full extraction with provenance tracking."
+**Skills module** (`repo_shape: skills-module`): Unless `{overrides.exports}` is set, Key Exports lists the skills first, each with its description, then the menu codes, each with its description, display name and the skill it runs, in the inventory's order. Usage Patterns gives one entry per `module-help.csv` usage pattern in the inventory; with no `module-help.csv`, it comes from the README as for a library.
+
+**Scripts & Assets Note** (add as an optional section when step 3's `{run_dir}/sniff.json` lists a `scripts/`, `bin/`, `assets/`, `templates/` or `schemas/` folder: its `asset_dir_count` is above 0): "This package may include scripts and assets. Run create-skill for full extraction with provenance tracking."
 
 **If confidence is low** — include a note: "This skill was generated with limited source data. Consider running create-skill for a more thorough compilation."
 
 ### 3. Generate Context Snippet
 
-**If `{overrides.skip_snippet}` is true** — skip generation and note in the §5 preview: "context-snippet.md skipped per `--skip-snippet` override." Step-05 §2 will skip the corresponding write; step 5 §5 advisory snippet validation will report a "skipped" entry.
+**If `{overrides.skip_snippet}` is true**, skip generation and note in the §5 preview: "context-snippet.md skipped per `--skip-snippet` override."
 
 Otherwise, produce context-snippet.md in the Vercel-aligned indexed format from `{skillTemplateData}` § "context-snippet.md Format" (~80-120 tokens).
 
-The snippet anchors point to the QS template's actual headings — `#usage-patterns` (Usage Patterns) and `#key-exports` (Key Exports). The QS template has no `## Quick Start` / `## Key Types` headings (those are Deep-tier sections), so the Deep-tier anchors `#quick-start` / `#key-types` would dangle. If the assembled SKILL.md is missing the referenced heading, omit that line rather than emit a dangling anchor.
+Its `{version}` is the version §4 gives `metadata.json`, which names the version folder: `{target_version}` when step 1 parsed one from the target, else the first `version` set in step 3's extraction files (`{run_dir}/extract.json` first), else `1.0.0`.
+
+If the assembled SKILL.md lacks a heading a snippet line anchors to, omit that line.
 
-**If fewer than 5 exports:** Use all available exports.
 **If no exports:** Omit the api line.
 **If no gotchas known:** Omit the gotchas line.
+**If `repo_shape` is `skills-module`:** the api line names up to five skills, without `()`, and the key-types summary lists the menu codes when there are any.
 
 ### 4. Generate Metadata JSON
 
-Run the shared renderer against the assembled state. The helper applies the constants, echoes input-derived fields, computes export counts and the ISO 8601 UTC timestamp, and emits the canonical envelope per `{skillTemplateData}` § "metadata.json Format".
-
-**Resolve `{quickMetadataRenderer}`** from `{quickMetadataRendererProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt rendering of the canonical envelope per `{skillTemplateData}` § "metadata.json Format".
-
-**Probe `tool_versions.skf` first** (the helper expects it as input — the filesystem walk stays here because the helper does no I/O):
+Run the shared renderer. It applies the constants, takes the export list, the dependencies and the manifest's version from step 3's extraction files, probes the installed SKF's version for `tool_versions.skf`, computes export counts and the ISO 8601 UTC timestamp, and writes the canonical envelope (it does not read the template).
 
-1. Read `{project-root}/_bmad/skf/package.json` → take `version`
-2. If absent, read `{project-root}/_bmad/skf/VERSION`
-3. If absent, set to `"unknown"`
+**Resolve `{quickMetadataRenderer}`** from `{quickMetadataRendererProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt rendering of the canonical envelope per `{skillTemplateData}` § "metadata.json Format", and write it to `{run_dir}/metadata.json`.
 
-Build the input payload from the extraction inventory + step 1 resolution + the probed `tool_versions.skf` and pipe it to the renderer:
+Stage the fields this step and step 1 decide through a quoted heredoc, so a description holding an apostrophe, a quote or a `$` reaches the file as written, then run the renderer:
 
 ```bash
-echo '{"name":"<name>","version":"<v>","description":"<desc>","language":"<lang>","source_repo":"<url>","source_root":"<path or empty>","source_commit":"<source_ref or empty>","source_package":"<package or name>","exports":[{"name":"...","type":"..."}],"dependencies":["..."],"compatibility":"<semver-range or empty>","language_hint":<hint or null>,"scope_hint":<hint or null>,"skf_version":"<probed>"}' \
-  | python3 {quickMetadataRenderer}
+cat > "{run_dir}/metadata-input.json" <<'SKF_JSON'
+{"name": "{repo_name}", "description": "<the SKILL.md frontmatter description>", "version": <"{target_version}" or null>, "language": "{language}", "source_repo": "{resolved_url}", "source_root": "<path or empty>", "source_commit": "<source_ref or empty>", "source_package": "<package name or empty>", "compatibility": "<semver-range or empty>", "language_hint": <"{language_hint}" or null>, "scope_hint": <"{scope_hint}" or null>, "exports": <the --exports names as a JSON list, or null>}
+SKF_JSON
+uv run {quickMetadataRenderer} --input "{run_dir}/metadata-input.json" --extraction "{run_dir}/extract.json" --skf-root "{project-root}/_bmad/skf" --output "{run_dir}/metadata.json"
 ```
 
-The renderer emits the rendered metadata.json on stdout. Capture the output as `metadata` for the §5 preview and step 5 §2's deliverable write.
+Write each value as JSON: a string in double quotes with any `"` or `\` escaped, and `null` where the line says so. `version` is the version step 1 parsed from the target, else `null`, which takes the manifest's version (else `1.0.0`); `exports` is `{overrides.exports}` when set, else `null`, which takes the extraction's exports; an empty `source_package` takes the manifest's package name. Pass one `--extraction` per file step 3 wrote, the parent first: `{run_dir}/extract.json`, then each `{run_dir}/extract-module-<n>.json` of a multi-module build in `<n>` order and `{run_dir}/extract-added.json` when §3 staged it. Do not type the export list or the dependencies: the renderer reads them from those files.
+
+The renderer writes `{run_dir}/metadata.json` and prints it on stdout. Read it as `metadata` for the §5 preview; step 5 §2 installs that file.
+
+If the renderer exits non-zero, its error line names the file or the field at fault: fix that file once (stage `metadata-input.json` again with the missing field, or stage an empty extraction file as quick-extract §3's empty envelope) and run the command again. If it fails a second time, render the envelope in-prompt as the no-candidate fallback above does.
 
 ### 5. Present Compiled Output for Review
 
 **If `{headless_mode}` is true** — skip the inline preview (no human reviewer reads it) and emit a one-line summary instead:
 
-"Compiled: SKILL.md ({section_count} sections, {export_count} exports), context-snippet.md (~{snippet_token_count} tokens), metadata.json (version {version}, confidence {confidence}). Auto-approving [C]."
+"Compiled: SKILL.md ({section_count} sections, {export_count} exports), context-snippet.md (~{snippet_token_count} tokens), metadata.json (version {metadata.version}, confidence {confidence}). Auto-approving [C]."
 
 Then proceed directly to §6 — the GATE default action takes over.
 
@@ -105,16 +110,11 @@ Then proceed directly to §6 — the GATE default action takes over.
 
 ---
 
-**metadata.json:**
-
-{Display the JSON}
+**metadata.json:** version {metadata.version}, confidence tier {metadata.confidence_tier}, {metadata.stats.exports_documented} exports documented (step 5 writes the full file)
 
 ---
 
-**Extraction confidence:** {confidence}
-**Exports documented:** {count}
-
-Review the output above, then choose: [C] continue to validation, [E] edit the description, [S] adjust scope and re-extract, or [Q] quit without writing."
+**Extraction confidence:** {confidence}"
 
 ### 6. Present MENU OPTIONS
 
@@ -123,14 +123,13 @@ Display: **Select:** [C] Continue to Validation · [E] Edit description · [S] A
 #### Menu Handling Logic:
 
 - **IF C** — Load, read entire file, then execute {nextStepFile}.
-- **IF E** — Ask the user for a replacement description ("New description (1–1024 chars):"). Update SKILL.md frontmatter `description` and `metadata.json.description` in the in-memory compiled output, then re-render the §5 preview and redisplay this menu. Do not re-run extraction.
-- **IF S** — Ask the user for an adjusted `scope_hint` ("New scope (e.g. `src/server/`, `packages/core/`):") and optionally a `language_hint`. Update the extraction context with the new hints, then load `quick-extract.md` to re-extract. The new extraction returns to §1 of this step on completion. Discards the prior compiled output.
-- **IF Q** — HARD HALT with **exit code 6 (user-cancelled)** per the exit-code map in `references/halt-contract.md`: "Compilation cancelled. No files written." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "compile"`, `error.code: "user-cancelled"`, `skill_package: null`). Do not proceed to validation; do not write any artifacts.
+- **IF E**: Ask the user for a replacement description ("New description (1–1024 chars):"). Update SKILL.md frontmatter `description` in the compiled output, stage `{run_dir}/metadata-input.json` again with the new description and run §4's renderer command again, so `{run_dir}/metadata.json` carries it, then re-render the §5 preview and redisplay this menu. Do not edit `metadata.json` by hand, and do not re-run extraction.
+- **IF S**: Ask the user for an adjusted `scope_hint` ("New scope (e.g. `src/server/`, `packages/core/`):") and optionally a `language_hint`. A non-empty new language hint sets `language` to it, `language_resolution` to `hint` and `detected_languages` to `[]`, as step 1 §4 does for a hint. Update the extraction context with the new hints, then load `quick-extract.md` to re-extract. The new extraction returns to §1 of this step on completion. Discards the prior compiled output.
+- **IF Q**: HARD HALT with **exit code 6 (user-cancelled)**: "Compilation cancelled. No files written." Stage `{"phase": "compile", "halt_reason": "user-cancelled", "reason": "Compilation cancelled. No files 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`). Do not proceed to validation; do not write any artifacts.
 - **IF Any other** — Help the user adjust the compiled output (treated as a free-form revision request), then redisplay the menu.
 
 #### Gate:
 
 - Halt and wait for user input after presenting the compiled output; only [C] (or a headless auto-approve) chains to `{nextStepFile}` for validation.
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve compiled output"
-- [E] re-renders the preview without re-running extraction; [S] discards the compiled output and re-runs step 3 with new hints.
+- **GATE [default: C]**: if `{headless_mode}`, auto-proceed with [C] Continue, log "headless: auto-approve compiled output", record the decision (stage `{"gate": "compile.review", "default_action": "C", "taken_action": "C", "reason": "headless: auto-approved the compiled output"}` as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-quick-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`), and print this step's `done` event and step 5's `start` event (`references/halt-contract.md`) before loading `{nextStepFile}`.
 

package/src/skf-quick-skill/references/ecosystem-check.md

@@ -6,67 +6,17 @@ nextStepFile: 'quick-extract.md'
 
 # Step 2: Ecosystem Check
 
-## STEP GOAL:
-
-To query the agentskills.io ecosystem for an existing official skill matching the resolved target, preventing unnecessary duplication. This is an advisory gate — it never blocks the workflow on failure.
-
 ## Rules
 
-- 5-second timeout on ecosystem queries; tool unavailability is a silent skip, not an error
-- Do not begin extraction or compilation
+- A HARD HALT prints, after its envelope, this step's `halt` event when `{headless_mode}` is true. Under `--batch` it ends only this target: then return to `references/batch-mode.md` §3, even when the halt reads as the end of the run (`references/halt-contract.md`).
 
 ## Steps
 
-### 1. Query Ecosystem
-
-Search for an existing official skill matching `{repo_name}` in the agentskills.io ecosystem.
-
-**Query methods (try in order):**
-1. Search agentskills.io registry for `{repo_name}`
-2. Web search: `"agentskills.io" "{repo_name}" skill`
-
-**Apply 5-second timeout.** If query takes longer, treat as no-match.
-
-### 2. Evaluate Result
-
-**If tool unavailable or timeout:**
-- Set `ecosystem_status: skip`
-- Proceed silently to step 3 (auto-proceed, no message to user)
-
-**If no match found:**
-- Set `ecosystem_status: no-match`
-- Auto-proceed silently to step 3. Do not display any message — absence of a match is the expected case.
-
-**If match found:**
-- Set `ecosystem_status: match`
-- Display match details and present conditional menu:
-
-"**Existing official skill found for {repo_name}.**
-
-**Skill:** {matched_skill_name}
-**Source:** agentskills.io
-**Authority:** official
-
-An official skill already exists. You can:
-
-**[P] Proceed** — Compile a custom community skill anyway (different scope or customization)
-**[I] Install** — Install the existing official skill instead (exits this workflow)
-**[A] Abort** — Cancel compilation"
-
-### 3. Handle Match Menu (only when a match was found)
-
-#### Menu Handling Logic:
-
-- IF P: Set `ecosystem_status: match-proceed`, then load, read entire file, then execute {nextStepFile}
-- IF I: Display install instructions for the official skill, emit the HARD HALT envelope per `references/halt-contract.md` (`phase: "ecosystem-check"`, `error.code: "ecosystem-redirect"`, `error.message: "User opted to install existing official skill instead of compiling a custom community skill."`, `skill_package: null`), exit with code 8 (ecosystem-redirect). Skill package is unknown at this phase — no on-disk result file is written.
-- IF A: Display "Compilation cancelled.", emit the HARD HALT envelope (`phase: "ecosystem-check"`, `error.code: "user-cancelled"`, `error.message: "User aborted at ecosystem-match gate."`, `skill_package: null`), exit with code 6 (user-cancelled). Skill package is unknown at this phase — no on-disk result file is written.
-- IF Any other: help user, then redisplay the match menu
-
-#### Gate:
-
-- **GATE [default: P]** — If `{headless_mode}` and match found: auto-proceed with [P] Proceed (compile custom skill anyway), log: "headless: ecosystem match found, auto-proceeding with custom compilation"
-
-### 4. Auto-Proceed (No Match or Skip)
+agentskills.io has no registry API to ask whether an official skill already covers `{repo_name}`, so make no query and no web search (a search hit cannot show that a skill is official), say nothing, and go on as IF P does.
 
-For no-match and skip, load and execute {nextStepFile} to proceed to source extraction.
+Once a registry API lists an official skill for `{repo_name}`, name it and offer: [P] Proceed, compiling a custom community skill anyway · [I] Install the official skill instead, which ends this workflow · [A] Abort. Answer anything else by helping, then offer again.
 
+- IF P: when `{headless_mode}` is true, print this step's `done` event and step 3's `start` event (`references/halt-contract.md`); then load, read entire file, then execute {nextStepFile}
+- IF I: Display install instructions for the official skill, then HARD HALT with **exit code 8 (ecosystem-redirect)**: stage `{"phase": "ecosystem-check", "halt_reason": "ecosystem-redirect", "reason": "User opted to install existing official skill instead of compiling a custom community skill.", "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`). The skill package is unknown at this phase, so no result file is written.
+- IF A: Display "Compilation cancelled.", then HARD HALT with **exit code 6 (user-cancelled)**: stage `{"phase": "ecosystem-check", "halt_reason": "user-cancelled", "reason": "User aborted at ecosystem-match gate.", "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"`. No result file is written.
+- **GATE [default: P]**: if `{headless_mode}` and match found, auto-proceed with [P] Proceed (compile custom skill anyway), log "headless: ecosystem match found, auto-proceeding with custom compilation", and record the decision: stage `{"gate": "ecosystem-check.ecosystem-match", "default_action": "P", "taken_action": "P", "reason": "headless: compiled a custom skill beside the official one"}` as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-quick-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`, then go on as IF P does, its events included.

package/src/skf-quick-skill/references/finalize.md

@@ -11,35 +11,35 @@ atomicWriteProbeOrder:
 
 ## STEP GOAL:
 
-To finalize the skill by creating the active-version pointer, displaying the completion summary, and writing the result contract. Deliverables (SKILL.md, context-snippet.md, metadata.json) were already written in step 5 so that validation could run against files on disk; this step only performs the post-write finalization.
+To finalize the skill by creating the active-version pointer, displaying the completion summary, and emitting the result envelope and result contract.
 
 ## Rules
 
 - Do not rewrite deliverables — they were written and validated in step 5
-- Create the active pointer via the shared helper — never `rm` + `ln -s` manually
-- Result contract writing is mandatory (pipeline consumers depend on it)
+- Emit the result envelope and contract through the shared emitter, never by hand; when it is missing or fails twice, say the contract was not written and go on (§3)
+- A HARD HALT prints, after its envelope, this step's `halt` event when `{headless_mode}` is true. Under `--batch` it ends only this target: then return to `references/batch-mode.md` §3, even when the halt reads as the end of the run (`references/halt-contract.md`).
 
 ## Steps
 
 ### 1. Create Active Pointer (atomic flip, Windows-safe)
 
-**If `{overrides.no_active_pointer}` is true** — skip the helper invocation entirely. Log: "Active pointer: skipped per `--no-active-pointer` override." Do not update `{skill_group}/active`. Proceed to §2 with the active-pointer line omitted from the completion summary and the outputs payload.
+**If `{overrides.no_active_pointer}` is true**, skip the helper invocation entirely. Log: "Active pointer: skipped per `--no-active-pointer` override." Do not update `{skill_group}/active`, and set `{active_pointer}` to `skipped-no-active-pointer`. Proceed to §2 with the active-pointer line omitted from the completion summary and the outputs payload.
 
-`{skill_group}` and `{skill_package}` were computed in step 5 §1 from `{skills_output_folder}`, `{repo_name}`, and `{version}`; `{version}` was resolved from the extraction inventory. Reuse the same values here — do not recompute.
+`{skill_group}` and `{skill_package}` were computed in step 5 §1 from `{skills_output_folder}`, `{repo_name}`, and `{version}`; `{version}` is the `version` of the `metadata.json` step 5 installed.
 
-Create or update the `active` pointer at `{skill_group}/active` pointing to `{version}` using the shared atomic-flip helper. The helper acquires an `flock` on `{skill_group}/active.skf-lock`, refuses to replace a non-link at `{skill_group}/active` (protecting against accidental `rm -rf` of a real directory), and uses a rename-over-symlink pattern so the update is atomic from a concurrent reader's perspective. On Windows the helper automatically falls back to a directory junction (`mklink /J`) when `os.symlink` fails with `PRIVILEGE_NOT_HELD` / `ACCESS_DENIED` — junctions require no admin elevation and resolve identically for `skf-skill-inventory`'s consumers:
+Point `{skill_group}/active` at `{version}` with the shared helper.
 
-**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists, skip the flip the same way `--no-active-pointer` does: log "Active pointer: skipped — atomic-write helper unavailable", omit the active-pointer line from the completion summary and outputs, and record `active_pointer: "skipped-helper-missing"` in the result-contract summary (§3) so consumers see why the pointer is absent. The deliverables are already on disk, so a missing helper degrades to "no pointer" rather than a failed run. There is no manual fallback: a hand-rolled `rm` + `ln -s` loses the helper's atomicity and non-link guard, risking a half-flipped pointer or an `rm -rf` into a real directory.
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists, skip the flip the same way `--no-active-pointer` does: log "Active pointer: skipped, atomic-write helper unavailable", omit the active-pointer line from the completion summary and outputs, and set `{active_pointer}` to `skipped-helper-missing`, which the result-contract summary (§3) carries so consumers see why the pointer is absent. This branch is reached only when `skf-atomic-write.py` disappeared after step 5, whose metadata.json install halts without it. There is no manual fallback: a hand-rolled `rm` + `ln -s` loses the helper's atomicity and non-link guard, risking a half-flipped pointer or an `rm -rf` into a real directory.
 
 ```bash
-python3 {atomicWriteHelper} flip-link \
-  --link {skill_group}/active \
-  --target {version}
+uv run {atomicWriteHelper} flip-link \
+  --link "{skill_group}/active" \
+  --target "{version}"
 ```
 
-The helper returns non-zero (helper exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a link — in that case, HARD HALT the workflow with **exit code 7 (finalize-blocked)** per the exit-code map in `references/halt-contract.md`: "Refusing to flip `{skill_group}/active` — existing path is not a symlink or junction. Investigate manually; expected a link pointing at a version directory." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "finalize"`, `error.code: "finalize-blocked"`, `skill_package` set, `outputs` listing the deliverables already on disk from step 5). A common cause on Windows is a prior run that executed `ln -s` under git-bash without Developer Mode enabled, which silently wrote a full directory copy; remove that copy and retry.
+On exit 0 the helper prints `{"link": …, "points_to": …, "kind": …, "status": "ok"}` on stdout. On any other exit, HARD HALT the workflow with **exit code 7 (finalize-blocked)**: "Refusing to flip `{skill_group}/active`: {the `message` of the helper's `{"status": "error", "message": …}` stderr line (something that is not a link is at `{skill_group}/active`, or another process holds its lock), else its stderr}." Stage `{"phase": "finalize", "halt_reason": "finalize-blocked", "reason": "Refusing to flip {skill_group}/active: <the helper's message>", "skill_package": "{skill_package}", "outputs": {"skill_md": "{skill_package}/SKILL.md", "context_snippet": "{skill_package}/context-snippet.md", "metadata": "{skill_package}/metadata.json"}}` as `{run_dir}/halt.json` (`context_snippet` left out under `--skip-snippet`) and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --run-dir "{run_dir}" --result-dir "{skill_package}" --target stderr < "{run_dir}/halt.json"` (`references/halt-contract.md`). When a real folder is at `{skill_group}/active`, a common cause on Windows is a prior run that executed `ln -s` under git-bash without Developer Mode enabled, which silently wrote a full directory copy: remove that copy and retry.
 
-Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{kind}` is `symlink` or `junction` as returned by the helper.
+Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{kind}` is `symlink` or `junction` as returned by the helper, and set `{active_pointer}` to that `{kind}`.
 
 ### 2. Display Completion Summary
 
@@ -51,6 +51,8 @@ Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{ki
 **Authority:** community
 **Confidence:** {extraction confidence}
 {If `scope_hint` is non-empty, add:} **Scope:** {scope_hint}
+{If step 3 recorded a `repo_shape`, add:} **Repo shape:** {repo_shape}
+{If it is `skills-module`, add:} **Skills:** {skill count} skills and {menu code count} menu codes, documented as the exports below
 
 **Files written:**
 - `{skill_package}/SKILL.md`
@@ -58,6 +60,8 @@ Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{ki
 - `{skill_package}/metadata.json`
 - `{skill_group}/active` -> `{version}` (omit this line when `--no-active-pointer` was set)
 
+{If step 5 §1 set `{replaced_build}`, add:} **Replaced:** the `{replaced_build}` build of v{version}. Its forge data, `{forge_data_folder}/{repo_name}/{version}/`, is left in place: remove it yourself once you no longer need it.
+
 **Exports documented:** {count}
 **Validation:** {pass / N issues (advisory)}
 
@@ -70,18 +74,65 @@ Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{ki
 
 **Note:** This is a best-effort community skill. For deeper analysis with AST-verified exports and provenance tracking, use the full **create-skill** workflow with a skill brief."
 
-### 3. Result Contract
+### 3. Result Envelope and Result Contract
+
+Stage the run's result payload through a quoted heredoc, then run the shared emitter, which prints the success envelope and writes the result contract:
+
+```bash
+cat > "{run_dir}/result-context.json" <<'SKF_JSON'
+{
+  "status": "success",
+  "skill_package": "{skill_package}",
+  "outputs": {"skill_md": "{skill_package}/SKILL.md", "context_snippet": "{skill_package}/context-snippet.md", "metadata": "{skill_package}/metadata.json", "active_pointer": "{skill_group}/active"},
+  "summary": {
+    "skill_name": "{repo_name}",
+    "version": "{version}",
+    "language": "{language}",
+    "exports_documented": {export count},
+    "quality_score": {quality_score},
+    "confidence": "{extraction confidence}",
+    "repo_shape": {repo_shape},
+    "language_resolution": {language_resolution},
+    "detected_languages": {detected_languages},
+    "zero_exports_rescue": {zero_exports_rescue},
+    "active_pointer": "{active_pointer}",
+    "validation_issues": {validation_issues}
+  },
+  "result_contract": {
+    "skill": "skf-quick-skill",
+    "outputs": [
+      {"type": "skill", "path": "{skill_package}/SKILL.md"},
+      {"type": "skill", "path": "{skill_package}/context-snippet.md"},
+      {"type": "skill", "path": "{skill_package}/metadata.json"}
+    ]
+  }
+}
+SKF_JSON
+uv run {emitEnvelopeHelper} emit --workflow skf-quick-skill --run-dir "{run_dir}" --result-dir "{skill_package}" < "{run_dir}/result-context.json"
+```
+
+This list is the summary, once: `skill_name`, `version`, `language`, `exports_documented` (the export count), `quality_score` and `validation_issues` (step 5, the object `{"skill_md": <n>, "context_snippet": <n>, "metadata": <n>, "security": <n>}`), `confidence` and `repo_shape` (step 3, the shape null when it recorded none), `language_resolution` and `detected_languages` (step 1), `zero_exports_rescue` (step 3 §4.5, else null) and `active_pointer` (§1). Write each value as JSON: a string in double quotes with any `"` or `\` escaped, every path absolute with `/`, and `null` for a value the run did not record. Leave the snippet out of both `outputs` under `--skip-snippet`, and `outputs.active_pointer` out when §1 flipped no pointer.
 
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skill_package}/quick-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include `SKILL.md`, `context-snippet.md`, and `metadata.json` paths in `outputs` and export count in `summary`.
+The emitter writes the result contract from `result_contract`, with the payload's own `status` and `summary`, so neither is typed twice (the per-run record `{skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json` and its copy `quick-skill-result-latest.json`, the stable path for pipeline consumers) and prints one line on stdout, `SKF_QUICK_SKILL_RESULT_JSON: {...}`. In a headless single-target run, bind `{result_envelope_line}` ← that line and do not display it here: the shared health check displays it verbatim as the run's last line, so a `claude -p` caller reads the envelope as the final message. Otherwise (an interactive run, or a `--batch` target) display it verbatim as its own line. If it exits non-zero, fix `result-context.json` once (its `message` names the problem) and run it again; if it still fails, or no path resolved for `{emitEnvelopeHelper}`, leave `{result_envelope_line}` empty, say that the result contract was not written and why, and go on.
 
-**Post-completion hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it after the result contract is finalized:
+**Post-completion hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`) and the emitter wrote the result contract (the line it printed has a non-null `result_path` and no `result_file_write_failed` warning naming `quick-skill-result-latest.json`), invoke it after the result contract is finalized:
 
 ```bash
-{onCompleteCommand} --skill-package={skill_package}
+{onCompleteCommand} --result-path={skill_package}/quick-skill-result-latest.json
 ```
 
-Log success/failure but never fail the workflow on a hook error — the skill is already written. The hook runs last so a git-add, registry registration, or notifier sees a complete package. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
+When the emitter failed twice, no path resolved for `{emitEnvelopeHelper}`, `result_path` is null, or a `result_file_write_failed` warning names `quick-skill-result-latest.json` (the copy alone failed), skip the hook and say so: "Post-completion hook skipped: `quick-skill-result-latest.json` was not written." The hook never gets a missing file or an earlier run's `-latest` copy. Log success/failure but never fail the workflow on a hook error: the skill is already written. The hook runs last so a git-add, registry registration, or notifier sees a complete package. Under `--batch` it runs once per target that reaches this section.
+
+In a single-target run, then delete the run folder, which a finished run no longer needs: the files step 3 fetched into it, and the files the steps staged (if `rmdir` reports it is not empty, leave it). The `case` guard deletes nothing unless the path is a quick-skill run folder:
+
+```bash
+case "{run_dir}" in */.skf-run/skf-quick-skill-*) rm -rf "{run_dir}/src" && rm -f "{run_dir}"/*.json "{run_dir}"/*.jsonl "{run_dir}"/*.txt && rmdir "{run_dir}" ;; esac
+```
+
+Under `--batch`, leave it: batch mode §3 records the target from it, then removes it.
 
 ### 4. Chain to Health Check
 
-Once the active pointer, completion summary, result contract, and any post-completion hook are done, load and execute {nextStepFile}. Do not stop here — health-check is the true terminal step even though the summary reads as final.
+**Single target.** Once the active pointer, completion summary, result envelope, any post-completion hook and the run folder's removal are done, print this step's `done` event and step 7's `start` event when `{headless_mode}` is true (`references/halt-contract.md`), then load and execute {nextStepFile}. Do not stop here: health-check is the true terminal step even though the summary reads as final.
+
+**Under `--batch`.** Print this step's `done` event, then return to `references/batch-mode.md` §3 instead of {nextStepFile}: control returns there even though this step reads as the end of the run. The health check runs once, after the batch summary.

package/src/skf-quick-skill/references/halt-contract.md

@@ -2,7 +2,7 @@
 
 # HARD HALT Contract
 
-The exit-code map and error-result envelope every step emits on a HARD HALT. Any step loads this file on its failure path, so the wire format is available even if SKILL.md has been compacted mid-run.
+The exit-code map, the envelope every HARD HALT emits, the headless progress events and the `--batch` rule. Each HARD HALT in the stage files names its phase, `halt_reason`, exit code and emit command, and each stage's Rules carry its `halt` event and the `--batch` return, so a halt keeps its wire format even when SKILL.md or this file was compacted away.
 
 ## Exit Codes
 
@@ -11,44 +11,56 @@ Every HARD HALT in this workflow exits with a stable, documented code so headles
 | Code | Meaning                | Raised by                                                   |
 | ---- | ---------------------- | ----------------------------------------------------------- |
 | 0    | success                | step 7 (terminal)                                          |
-| 3    | resolution-failure     | step 1 (prose input §2, registry chain §3, version-tag miss §3a, language abort §4); step 3 (non-library shape §1.5, zero-exports §4.5) |
-| 4    | write-failure          | step 5 §2 (deliverable write failed)                       |
-| 5    | overwrite-cancelled    | step 5 §1 (user selected [N])                              |
-| 6    | user-cancelled         | step 1 §1 ([X] Cancel and exit, or cancel-line affordance); step 2 §3 ([A] Abort at ecosystem-match gate); step 4 §6 (user selected [Q]) |
-| 7    | finalize-blocked       | step 6 §1 (active-pointer flip refused — non-link in place) |
-| 8    | ecosystem-redirect     | step 2 §3 ([I] Install at ecosystem-match gate — user opted to install the existing official skill instead of compiling a custom community skill) |
+| 2    | input-invalid          | batch mode, before any target runs (`--description`, `--exports`, `--language-hint` or `--scope-hint` passed with `--batch`; §1: a batch file it cannot read, or `skf-quick-batch.py` missing); step 1 §1 (a headless run with no target) |
+| 3    | resolution-failure     | SKILL.md On Activation step 1 (`python3` or `uv` missing); a shipped helper missing, named in the message and in `details.cause` (step 3: `skf-github-fetch.py`, `skf-skills-module.py` §1, `skf-extract-public-api.py` §2; step 5: `skf-atomic-write.py` §2, `skf-validate-frontmatter.py` §4 when skill-check is unavailable, `skf-validate-output.py` §5); step 1 (package resolver missing or failing §1b, a target that is no GitHub repository or package §2, registry chain §3, version tag missing or not checkable §3a, file listing unreadable, language detector missing or failing, language abort or no language found §4); step 3 (non-library shape §1.5, zero-exports §4.5) |
+| 4    | write-failure          | SKILL.md On Activation step 1 (the run folder cannot be created); batch mode §1 (the batch run folder cannot be written); step 5 §2 (deliverable write failed) |
+| 5    | overwrite-cancelled    | step 5 §1 (user selected [N], or a headless run reached a version another SKF workflow built; `details.existing_generator` names its generator) |
+| 6    | user-cancelled         | step 1 §1 ([X] Cancel and exit, or cancel-line affordance) and §3 ([X] at the ambiguous-name gate); step 2 ([A] Abort at ecosystem-match gate); step 4 §6 (user selected [Q]) |
+| 7    | finalize-blocked       | step 6 §1 (the flip helper refused or failed: something that is not a link is at `{skill_group}/active`, or another process holds its lock) |
+| 8    | ecosystem-redirect     | step 2 ([I] Install at ecosystem-match gate: user opted to install the existing official skill instead of compiling a custom community skill) |
+| 9    | state-conflict         | step 5 §1 (ownership check: the skill folder or the version folder it writes is not SKF output, or SKF cannot check it → error.code `not-skf-output`; an SKF skill still in the flat layout → `flat-layout`) |
 
 ## Result Contract on HARD HALT
 
-In addition to the success-variant result contract written by step 6 §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.
+Every HARD HALT emits an **error envelope** through the shared emitter, `{emitEnvelopeHelper}`, so headless automators never meet a failed run with no result, except SKILL.md On Activation's halt for a missing `python3` or `uv`, which the emitter needs: that halt displays its message alone. SKILL.md On Activation step 1 resolved the emitter; when a compaction lost it, it is 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`. Stage the halt payload as `{run_dir}/halt.json` through a quoted heredoc, then run the emitter:
 
-**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>"}
+```bash
+cat > "{run_dir}/halt.json" <<'SKF_JSON'
+{"phase": "<step slug>", "halt_reason": "<code>", "reason": "<the halt message, one line>", "skill_package": null}
+SKF_JSON
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-quick-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
 ```
 
-One line, no pretty-print. Matches the prefix-and-envelope convention used by `skf-emit-result-envelope.py`.
+- `phase`: the step's slug (`resolve-target`, `ecosystem-check`, `quick-extract`, `compile`, `write-and-validate`, `finalize`), `on-activation` for a halt before the run starts (SKILL.md On Activation, and batch mode's refusal of `--description` and `--exports` and of the hint flags), or `batch-mode` for batch mode §1.
+- `halt_reason`: the failure class the halt names: the Meaning of its exit code in the table above, or `not-skf-output` or `flat-layout` for exit 9. The emitter derives `exit_code` from it.
+- `reason`: the message the step displayed, as one line (its first sentence when it runs longer); it becomes `error.message`. Escape `"` and `\` in it as JSON requires.
+- `skill_package`: the absolute `{skill_package}` once step 5 §1 computed it, else `null`.
+- `outputs` (optional): the files already on disk, as `{"skill_md": ..., "context_snippet": ..., "metadata": ...}` paths.
+- `details` (only when the halt names them): the halt's context as an object, such as the folder a refusal names or the file a failed write named. The emitter puts it in the envelope's `error.details`, beside the `code` and `message` it builds from `halt_reason` and `reason`, so no halt types an `error` object.
+
+The emitter prints one line on stderr, `SKF_QUICK_SKILL_RESULT_JSON: {...}`: display it verbatim. If it exits non-zero, fix `halt.json` once (its `message` names the problem) and run it again; if it still fails, or no path resolved for `{emitEnvelopeHelper}`, display the halt message alone.
 
-**Additionally, when `{skill_package}` is known** (HALT at step 5 §1 onward) — write the same JSON object (without the `SKF_QUICK_SKILL_RESULT_JSON: ` prefix) to disk:
+**Additionally, when `{skill_package}/metadata.json` exists** (HALT at step 5 §1 onward, except the step 5 §1 ownership halt, which writes nothing on disk: `{skill_package}` would sit in a folder SKF did not generate), the command adds `--result-dir "{skill_package}"`, and the emitter also writes the envelope (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 1/02/03/04 cannot write to disk because `{skill_package}` is computed only in step 5 §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 above                                                                          |
-| `phase`         | string         | step slug where the HALT occurred (e.g. `resolve-target`, `compile`)                                        |
-| `error.code`    | string         | one of: `resolution-failure`, `write-failure`, `overwrite-cancelled`, `user-cancelled`, `finalize-blocked`, `ecosystem-redirect` |
-| `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 5 §1                                              |
+so consumers that hardcode the `-latest.json` path see a deterministic file even on failed runs. Before step 5 §1 computes `{skill_package}`, the stderr line and the exit code are the whole contract. A HALT while `{skill_package}` has no `metadata.json` (a failed first write in step 5 §2, for example) writes nothing on disk either: a package holding only result files is not SKF output, so the next run's ownership check would refuse it.
+
+**Schema:** `shared/scripts/schemas/skf-quick-skill-result-envelope.v1.json` (installed under `{project-root}/_bmad/skf/`).
+
+## Headless Events
+
+When `{headless_mode}` is true, each step prints one-line JSON progress events on stderr (one line each, never pretty-printed), so a pipeline can follow a run live:
+
+- when the step starts: `{"step":N,"name":"<slug>","status":"start"}`
+- just before it chains to its `nextStepFile`: `{"step":N,"name":"<slug>","status":"done"}`
+- at a HARD HALT, in place of `done`: `{"step":N,"name":"<slug>","status":"halt","exit":<code>}`
+
+`N` and `<slug>`: 1 `resolve-target`, 2 `ecosystem-check`, 3 `quick-extract`, 4 `compile`, 5 `write-and-validate`, 6 `finalize`, 7 `health-check`. A `--batch` run adds the per-target events of `references/batch-mode.md`.
+
+## In `--batch`
+
+A HARD HALT in steps 1 to 6 ends the current target, not the batch. After its envelope line and `halt` event, return to `references/batch-mode.md` §3, which records the target and prints its `fail` event: control returns there even when the halt message reads as the end of the run, so a target's halt never exits the process. The batch then takes its next target, or, under `--fail-fast`, writes its summary. A halt before the first target (SKILL.md On Activation, batch mode's refusal of `--description` and `--exports`, or batch mode §1) ends the run itself, with no batch summary.

package/src/skf-quick-skill/references/health-check.md

@@ -11,13 +11,15 @@ nextStepFile: 'shared/health-check.md'
 
 ## STEP GOAL:
 
-Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of quick-skill — after the shared health check completes, the workflow is fully done.
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of quick-skill: after the shared health check completes, the workflow is fully done. Under `--batch` it runs once per batch, after `references/batch-mode.md` §4 wrote the batch summary, never after a single target.
+
+In a headless single-target run step 6 §3 bound `{result_envelope_line}` to the `SKF_QUICK_SKILL_RESULT_JSON` line without displaying it: the shared health check displays that line verbatim as the run's last line wherever it stops, so a `claude -p` caller reads the envelope as the final message.
 
 ## Rules
 
 - No user-facing reports, file writes, or result contracts in this step — those belong in step 6
-- Delegate directly to `{nextStepFile}` with no additional commentary or intervening action
+- Delegate directly to `{nextStepFile}` with no additional commentary or other action, except the headless `done` event below
 
 ## Steps
 
-Load `{nextStepFile}`, read it fully, then proceed to execute it.
+When `{headless_mode}` is true, print this step's `done` event (`references/halt-contract.md`). Load `{nextStepFile}`, read it fully, then proceed to execute it.