bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-quick-skill/references/resolve-target.md

@@ -1,12 +1,18 @@
 ---
 nextStepFile: 'ecosystem-check.md'
-registryResolutionData: '{registryResolutionPath}'
+registryResolutionData: 'references/registry-resolution.md'
 packageResolverProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-resolve-package.py'
   - '{project-root}/src/shared/scripts/skf-resolve-package.py'
+githubProbeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-github-probe.py'
+  - '{project-root}/src/shared/scripts/skf-github-probe.py'
 detectLanguageProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
   - '{project-root}/src/shared/scripts/skf-detect-language.py'
+skillsModuleProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skills-module.py'
+  - '{project-root}/src/shared/scripts/skf-skills-module.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -21,22 +27,23 @@ To accept a GitHub URL or package name from the user, resolve it to a GitHub rep
 
 - Focus only on resolving the target to a GitHub repository — do not begin extraction or compilation
 - If resolution fails, hard halt with actionable guidance
+- 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. Accept User Input
 
-**Batch mode:** if `--batch` is active (see SKILL.md "Batch Mode"), the current target was already resolved by On Activation step 5 from the next batch line and placed into the workflow context as `target`, with optional `language_hint` and `scope_hint` per-line modifiers. Skip the prompt below — emit `{"batch":<n>,"target":"<target>","status":"start"}` to stderr and proceed directly to §1b with the batch-supplied values.
+**Batch mode:** under `--batch`, `references/batch-mode.md` §2 set `target`, `language_hint` and `scope_hint` from the next pending batch line and printed its `start` event. Skip the prompt below and proceed directly to §1b with those values.
 
-**Single-target mode** (default):
+**Single-target mode** (default): when the invocation carried a target, take it, with `--language-hint` as `language_hint` and `--scope-hint` as `scope_hint` when they were passed (SKILL.md On Activation step 4), and go on to §1b without the prompt below, in either mode. Otherwise ask:
 
 "**Quick Skill — fastest path to a skill.**
 
-Provide a **GitHub URL** or **package name** and I'll resolve it to source and compile a best-effort SKILL.md.
+Provide a **GitHub URL**, a **package name** or its **npm, PyPI or crates.io page** and I'll resolve it to source and compile a best-effort SKILL.md.
 
-**Target:** (GitHub URL or package name)
+**Target:** (GitHub URL, package name or registry page URL)
 
-Examples: `cocoindex`, `@tanstack/query`, `https://github.com/tursodatabase/limbo`, `cognee@0.5.0`
+Examples: `cocoindex`, `@tanstack/react-query`, `requests==2.31.0`, `https://github.com/tursodatabase/limbo`, `cognee@0.5.0`
 
 **Optional:**
 - **Language hint:** (if the repo is multi-language)
@@ -44,60 +51,75 @@ Examples: `cocoindex`, `@tanstack/query`, `https://github.com/tursodatabase/limb
 
 Or type `cancel` / `exit` / `:q` / `[X]` to leave without writing anything."
 
-Wait for user input. **Cancel branch** — if the user types `cancel`, `exit`, `:q`, `[X]`, or selects `[X] Cancel and exit`, display `"Cancelled — no files were written."` and HARD HALT with **exit code 6 (user-cancelled)** per the exit-code map in `references/halt-contract.md`. Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "user-cancelled"`, `skill_package: null`). Cancellation here is non-destructive — no files have been written yet.
+Wait for user input. **Cancel branch**: if the user types `cancel`, `exit`, `:q`, `[X]`, or selects `[X] Cancel and exit`, display "Cancelled. No files were written." and HARD HALT with **exit code 6 (user-cancelled)**: stage `{"phase": "resolve-target", "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`). Cancellation here is non-destructive: no files have been written yet.
 
-**GATE [default: use args]** — If `{headless_mode}` and a target (URL or package name) was provided as argument: use it as the target input and auto-proceed, log: "headless: using provided target". If no target provided in headless mode, HALT with: "headless mode requires a target argument."
+**GATE [default: use args]**: if `{headless_mode}` and a target (URL or package name) was provided as argument, use it as the target input, with the hint flags, and auto-proceed, log: "headless: using provided target". If no target was provided in headless mode, HARD HALT with **exit code 2 (input-invalid)**: "Headless mode requires a target argument." Stage `{"phase": "resolve-target", "halt_reason": "input-invalid", "reason": "Headless mode requires a target argument.", "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"`.
 
-### 1b. Parse Version Targeting
+### 1b. Parse the Target
 
-**Version targeting:** If the user input contains `@` followed by a semver-like string (e.g., `cognee@0.5.0`, `https://github.com/org/repo@2.1.0-beta`), parse it as:
-- **Package/URL:** everything before the last `@`
-- **Target version:** everything after the last `@`
+**Resolve `{packageResolver}`** from `{packageResolverProbeOrder}`; first existing path wins. If no candidate exists, or a call to it prints no JSON on stdout, HARD HALT with **exit code 3 (resolution-failure)**, in interactive mode too: "**The package resolver could not run.** {the call's first stderr line, or with no candidate: SKF's package resolver (`skf-resolve-package.py`) is missing from `{project-root}/_bmad/skf/shared/scripts/`, so re-install SKF.}" Stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "The package resolver could not run.", "skill_package": null, "details": {"cause": "<package-resolver-missing, or package-resolver-error after a call that printed no JSON>"}}` 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"`.
 
-Store the target version as `target_version` in the extraction context. When present, this version overrides auto-detection (same behavior as `target_version` in the skill-brief schema).
+Parse the target. Write it exactly as given on the line between the two markers: the quoted marker hands it to the parser unchanged, quotes, backticks and `$` included.
 
-If no `@version` suffix is present, proceed as today — version will be auto-detected.
-
-### 2. Classify Input Type
+```bash
+uv run {packageResolver} parse-target <<'SKF_TARGET'
+{target}
+SKF_TARGET
+```
 
-**If input starts with `https://github.com/` or `github.com/`:**
-- Extract org/repo from URL
-- Set `resolved_url` to the GitHub URL
-- Set `repo_name` to the repo name (last path segment)
-- Skip to step 3a (Verify Target Version Tag), then step 4 (Detect Language)
+When the parser's `target_version` is not `null`, store it as `target_version` in the extraction context. A `target_version` overrides auto-detection. A `dist_tag` (an npm dist-tag such as `latest` or `canary`) pins no version: log "`{dist_tag}` pins no version; auto-detecting it". Without a `target_version`, the version is auto-detected.
 
-**If input is a package-name-like token** (no whitespace, matches `[@a-zA-Z0-9._/-]+(@<semver>)?`, e.g. `lodash`, `@scope/name`, `requests==2.31`, `cognee@0.5.0`):
-- Proceed to step 3 (Registry Resolution)
+### 2. Route by Kind
 
-**Otherwise — input looks like free-form prose, not a target:**
+- **`github`**: set `resolved_url` ← `url`, `owner` ← `owner`, `repo` ← `repo` and `repo_name` ← `skill_name`, the name the skill is written under. A `/tree/<ref>/<folder>` URL also gives `ref` and `subdir`: set `source_ref` ← `ref`, and `scope_hint` ← `subdir` when no scope hint was given. Skip to §3a (Verify Target Version Tag), then §4 (Detect Language).
+- **`package`** or **`registry-page`**: proceed to §3 (Registry Resolution) with `package_name`, and with `registry` when it is set.
+- **`other-host`**, **`local-path`** or **`unparsed`**: quick-skill cannot resolve the input to a GitHub repository. Instead of a registry lookup that can only fail, show the redirect for its kind, then, in interactive mode, wait for new input and go back to §1b. Two such inputs still name a package that a web search can place, so they try it first: an `other-host` input written with no scheme, such as the Go module path `go.uber.org/zap` (a Go module proxy serves it, not a registry quick-skill asks), and an `unparsed` Maven coordinate `<group>:<artifact>`, such as `com.google.guava:guava`. Take the input as `package_name` and run the web-search step of §3's `fallthrough` branch; show the redirect only when it finds no GitHub URL.
 
-The user typed something like "I want a skill that helps with onboarding" or "build me a brainstorming workflow" — quick-skill cannot resolve that to a GitHub repository. Instead of falling through to a registry-failure HARD HALT, redirect with a sibling-skill suggestion:
+  - **`other-host`**: "**Quick Skill reads GitHub repositories only.** `{url}` is on `{host}`. Paste the project's GitHub URL if it has one, or clone it and run `/skf-brief-skill` on the local clone, then `/skf-create-skill`."
+  - **`local-path`**: "**Quick Skill reads GitHub repositories, not local folders.** To make a skill from `{path}`, run `/skf-brief-skill` with that path, then `/skf-create-skill`. Or paste the GitHub URL of its repository."
+  - **`unparsed`**: the user typed something like "I want a skill that helps with onboarding" or "build me a brainstorming workflow", or text that is no package name or URL. Redirect with a sibling-skill suggestion:
 
-"**This input looks like a description, not a package or URL.** Quick Skill needs a package name (e.g. `lodash`, `@vercel/og`, `requests`) or a GitHub URL (e.g. `https://github.com/lodash/lodash`).
+    "**This input looks like a description, not a package or URL.** Quick Skill needs a package name (e.g. `lodash`, `@vercel/og`, `requests==2.31.0`) or a GitHub URL (e.g. `https://github.com/lodash/lodash`).
 
-If you are describing a skill you want to **create from scratch** rather than compile from existing source:
+    If you are describing a skill you want to **create from scratch** rather than compile from existing source:
 
-- Run `/skf-create-skill` with a skill brief — full pipeline with provenance tracking and AST-verified exports
-- Or use `bmad-agent-builder` for an interactive skill design session
+    - Run `/skf-create-skill` with a skill brief: the full pipeline, with provenance tracking and AST-verified exports
+    - Or use `bmad-workflow-builder` (a workflow or utility skill) or `bmad-agent-builder` (an agent) for an interactive skill design session
 
-Otherwise, paste the package name or GitHub URL of the library you want to wrap, and quick-skill will resolve it."
+    Otherwise, paste the package name or GitHub URL of the library you want to wrap, and quick-skill will resolve it."
 
-**GATE [default: HALT]** — In headless mode, emit the same redirect message and HALT with **exit code 3 (resolution-failure)** per the exit-code map in `references/halt-contract.md`. Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`). Do not attempt registry lookups against prose input; that wastes ~3-4 round trips and produces a less actionable error message than the redirect above.
+**GATE [default: HALT]**: in headless mode, after the web search above when the input qualifies for it, emit the redirect for the kind and HARD HALT with **exit code 3 (resolution-failure)**: stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "<the redirect's first sentence>", "skill_package": null, "details": {"kind": "<kind>"}}` 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"`.
 
 ### 3. Registry Resolution
 
-Run the shared resolver against the deterministic registries (npm → PyPI → crates.io). The resolver does the HTTP+JSON+GitHub-URL-extraction work; the LLM only handles the web-search fallback below when needed.
-
-**Resolve `{packageResolver}`** from `{packageResolverProbeOrder}`; first existing path wins. If no candidate exists, fall back to the LLM walk of {registryResolutionData} for the full chain.
+Run the shared resolver (resolved in §1b), which asks every deterministic registry (npm, PyPI, crates.io):
 
 ```bash
-python3 {packageResolver} {package_name} --timeout 10
+uv run {packageResolver} resolve {package_name} --timeout 10 [--registry {registry}] [--language "{language_hint}"]
 ```
 
-The resolver emits JSON with `status` (`"ok"` or `"fallthrough"`), `resolved_url`, `repo_owner`, `repo_name`, `registry_used`, `registries_tried`, and a per-registry `registry_outcomes` map. Exit 0 means ok; exit 1 means fallthrough.
+Pass `--registry` when §2 set `registry`, and `--language` when a language hint was given: a JavaScript, TypeScript, Python or Rust hint makes the resolver ask that language's registry alone. It prints JSON whose `status` is `ok`, `ambiguous` or `fallthrough` (exit 0, 3 or 1).
+
+- **On `status: "ok"`**: set, from the JSON, `resolved_url`, `owner` ← `repo_owner`, `repo` ← `repo_name`, `repo_name` ← `skill_name` and `registry_used`; when `source_subdir` is set and no scope hint was given, set `scope_hint` ← `source_subdir`. Proceed to §3a.
+- **On `status: "ambiguous"`**: another registry answered for the name too, so it may belong to two projects. `resolved_url`, from `registry_used`, is the chain's pick (the first registry, in the order npm, PyPI, crates.io, that gives a GitHub repository), and `also_found_in` lists every other registry that answered. Run the ambiguous-name gate below.
+- **On `status: "fallthrough"`**: no registry gave a GitHub URL. Load {registryResolutionData} and run its web search for `{package_name}`. If found, take that URL as the target and go back to §1b. If web search also returns nothing, HARD HALT below.
+
+**Ambiguous-name gate** (on `status: "ambiguous"` only). Offer every candidate: the pick first, then each `also_found_in` entry that has a `resolved_url`, numbered on from 2. `{others}` names each entry without one: `no-github-link` knows the name but gives no GitHub repository, `error` could not be read.
 
-- **On `status: "ok"`** — capture `resolved_url`, `repo_name`, and `registry_used` from the JSON. Proceed to §3a.
-- **On `status: "fallthrough"`** — the deterministic chain returned no GitHub URL (every registry replied with 404 / no-github-link / timeout). Fall back to the web-search step from {registryResolutionData} §4: search `"{package_name} github repository"` with a 15s timeout and look for a GitHub URL in the top results. If found, set `resolved_url` and proceed. If web search also returns nothing, HARD HALT below.
+"**`{package_name}` may name more than one project.**
+
+1. {resolved_url}, from `{registry_used}` (the registry chain's pick)
+2. {the next candidate's `resolved_url`}, from `{its registry}`
+
+{others}
+
+Select: [C] Continue with 1 · [2] to [n] Use that candidate · [U] Use another GitHub URL · [X] Cancel and exit"
+
+- **IF C**: log "user accepted the `{registry_used}` resolution of `{package_name}`" and continue as on `status: "ok"`.
+- **IF 2 to n**: continue as on `status: "ok"` with that candidate's entry: its `resolved_url`, `owner` ← its `repo_owner`, `repo` ← its `repo_name`, `registry_used` ← its `registry`, and `scope_hint` ← its `source_subdir` when set and no scope hint was given (`repo_name` stays the package's `skill_name`).
+- **IF U**: ask for the GitHub URL of the project the user means, take it as the target and go back to §1b.
+- **IF X**: display "Cancelled. No files were written." and HARD HALT with **exit code 6 (user-cancelled)**: stage `{"phase": "resolve-target", "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"`.
+- **GATE [default: C]**: in headless mode, keep the chain's pick and never halt. Record the resolver's `warning` (`also_found_in: ...`) with `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "{warning}"`, and the decision: stage `{"gate": "resolve-target.ambiguous-package", "default_action": "C", "taken_action": "C", "reason": "headless: kept the {registry_used} pick"}` 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 continue as on `status: "ok"`. To build another candidate headlessly, pass its GitHub URL or a language hint for its registry (`language=` on a batch line).
 
 **If all methods fail — HARD HALT (exit code 3, resolution-failure):**
 
@@ -110,65 +132,91 @@ Check:
 
 **Provide the GitHub URL directly to continue.**"
 
-In interactive mode, wait for corrected input and loop back to step 2. In headless mode, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`) and exit 3.
+In interactive mode, wait for corrected input and loop back to §1b. In headless mode, stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "Resolution failed. Could not resolve {package_name} to a GitHub repository.", "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"`.
 
 ### 3a. Verify Target Version Tag (when applicable)
 
-Skip this section if `target_version` is null (auto-detect path — version comes from manifest read in step 3).
+Skip this section if `target_version` is null (auto-detect path: the version comes from the manifest read in step 3).
+
+When the target carried a version (§1b), verify the tag exists in the resolved repo before extraction. Otherwise step 3 silently reads from the default branch while metadata records the requested version: a quiet provenance bug where the SKILL.md claims version 0.5.0 but the exports actually came from main.
 
-When the user explicitly supplied `@version` in §1b, verify the tag exists in the resolved repo before extraction. Otherwise step 3 silently reads from the default branch while metadata records the requested version — a quiet provenance bug where the SKILL.md claims version 0.5.0 but the exports actually came from main.
+**Resolve `{githubProbe}`** from `{githubProbeProbeOrder}`; first existing path wins. If no candidate exists, halt as when no probe could read the tags (below).
 
-Probe both with-and-without v-prefix (the v-prefix is conventional but not universal across ecosystems):
+List the repository's tags once, looking for every form a tag gives the version: `0.5.0`, `v0.5.0`, or a monorepo package's `<name>@0.5.0`:
 
 ```bash
-gh api repos/{owner}/{repo}/git/ref/tags/{target_version} --silent \
-  || gh api repos/{owner}/{repo}/git/ref/tags/v{target_version} --silent
+uv run {githubProbe} tags --repo {owner}/{repo} --version {target_version} --name {package_name or repo_name} --limit 5
 ```
 
-**If a matching tag is found** — set `source_ref` to the matching ref (with v-prefix when that variant matched). Step-03's ref-aware source reading uses this value to fetch from the tagged commit. Proceed to §4.
+- **`status: "ok"` with `match` set**: set `source_ref` ← `match`, which replaces a `/tree/` URL's ref. Step 3's ref-aware source reading uses this value to fetch from the tagged commit. Proceed to §4.
+- **`status: "ok"` with `match` null**: the listing lacks the tag. HARD HALT with **exit code 3 (resolution-failure)**:
 
-**If no tag matches** — HARD HALT with **exit code 3 (resolution-failure)**:
+  "**Tag `{target_version}` not found in `{owner}/{repo}`.**
 
-"**Tag `{target_version}` not found in `{owner}/{repo}`.**
+  The version was parsed from your target but no tag of the resolved repository names it. Quick-skill cannot extract from a version with no commit pointer: the result would be sourced from the default branch but labelled `{target_version}` in metadata.
 
-The version was parsed from your `@version` suffix but does not exist as a tag in the resolved repository. Quick-skill cannot extract from a version with no commit pointer — the result would be sourced from the default branch but labelled `{target_version}` in metadata.
+  Tags near this version:
+  {the probe's `nearest`, else its `tags`, or "(none: the repo has no tags)"}
 
-Recent tags in this repo:
-{list top 5 from `gh api repos/{owner}/{repo}/tags --paginate=false`, or "(none — repo has no tags; omit @version to auto-detect from default branch)"}
+  Re-run with one of these tags, or omit the version to auto-detect from the default branch."
 
-Re-run with one of these tags, or omit the `@version` suffix to auto-detect from the default branch."
+  Stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "Tag {target_version} not found in {owner}/{repo}.", "skill_package": null, "details": {"requested_version": "{target_version}", "available_tags": [<the tags shown>]}}` 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"`.
+- **`status: "unavailable"`, any other exit, or no `{githubProbe}` candidate**: nothing could read the repository's tags, so the tag may exist. Do not report it missing. HARD HALT with **exit code 3 (resolution-failure)**: "**Could not check tag `{target_version}` in `{owner}/{repo}`.** {the probe's `message` (on stderr after another exit), or with no candidate: SKF's GitHub probe (`skf-github-probe.py`) is missing from `{project-root}/_bmad/skf/shared/scripts/`, so re-install SKF.} Re-run once GitHub can be read, or omit the version to auto-detect from the default branch." Stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "Could not check tag {target_version} in {owner}/{repo}.", "skill_package": null, "details": {"requested_version": "{target_version}", "cause": "<the probe's cause, probe-error after another exit, or github-probe-missing>"}}` 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"`.
 
-Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {requested_version: "{target_version}", available_tags: [...top 5]}`, `skill_package: null`). In headless mode, exit immediately; do not loop.
+In headless mode, halt at once on either; do not re-prompt.
 
 ### 4. Detect Language
 
-**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins. If no candidate exists (e.g. Python/`uv` unavailable), fall back to the manifest-priority walk documented in the helper's `--help` — `package.json` → JavaScript/TypeScript (TypeScript when a `tsconfig.json` is also present), `Cargo.toml` → Rust, `pyproject.toml`/`setup.py`/`setup.cfg` → Python, `go.mod` → Go, `pom.xml` → Java, `build.gradle.kts` → Kotlin, `build.gradle` → Kotlin when `src/main/kotlin/` exists else Java, `*.csproj`/`*.sln` → C#, `Gemfile` → Ruby, then extension frequency — applied by hand.
+**List the repository's files once**, at the ref step 3 reads. Resolve `{githubProbe}` from `{githubProbeProbeOrder}` (§3a may have resolved it already); first existing path wins. Write the listing into the run folder, where the language helper below and step 3 read it, so no step lists the tree again and no path list passes through the model:
+
+```bash
+uv run {githubProbe} tree --repo {owner}/{repo} --ref {source_ref or HEAD} > "{run_dir}/tree.json"
+```
+
+The probe reads the tree through gh, and through GitHub's unauthenticated API when gh is missing or logged out, so a public repository needs no login. A `truncated` listing (GitHub cut a very large tree short) is still read.
+
+- **`status: "unavailable"`, any other exit, or no `{githubProbe}` candidate**: nothing could list the repository. HARD HALT with **exit code 3 (resolution-failure)**: "**Could not list the files of `{owner}/{repo}`.** {the probe's `message` (on stderr after another exit), or with no candidate: SKF's GitHub probe (`skf-github-probe.py`) is missing from `{project-root}/_bmad/skf/shared/scripts/`, so re-install SKF.}" Stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "Could not list the files of {owner}/{repo}.", "skill_package": null, "details": {"ref": "{source_ref or HEAD}", "cause": "<the probe's cause, probe-error after another exit, or github-probe-missing>"}}` 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"`.
 
 Determine primary language:
 
-1. **User-provided language hint** (overrides detection) — set `language` to the hint and skip straight to §5. The disambiguation gate below does not run.
+1. **User-provided language hint** (overrides detection): set `language` to the hint and `language_resolution` to `hint`, and skip straight to §5. The disambiguation gate below does not run.
 
-2. **Delegate the rule walk to `{detectLanguageHelper}`** — it is the single source of truth for the manifest → language rule table (including the `package.json` JS-vs-TS disambiguation); do not restate or re-derive it here. Fetch the repo file listing once (`gh api repos/{owner}/{repo}/git/trees/{source_ref or default branch}?recursive=1`, reading the `path` values), then hand the flat list to the script:
+2. **Delegate the rule walk to `{detectLanguageHelper}`**, resolved from `{detectLanguageProbeOrder}` (first existing path wins). If no candidate exists, or its call below prints no JSON on stdout, HARD HALT with **exit code 3 (resolution-failure)**: "**Could not detect the language of `{repo_name}`.** {the call's first stderr line, or with no candidate: SKF's language detector (`skf-detect-language.py`) is missing from `{project-root}/_bmad/skf/shared/scripts/`, so re-install SKF.} Re-run with `--language-hint <lang>` (a batch line's `language=`) to skip detection." Stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "Could not detect the language of {repo_name}.", "skill_package": null, "details": {"cause": "<detect-language-missing, or detect-language-error after a call that printed no JSON>"}}` 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"`. The helper reads the listing from the file:
 
    ```bash
-   echo '{"tree": [<flat list of repo-relative file paths>]}' | uv run {detectLanguageHelper}
+   uv run {detectLanguageHelper} --tree-file "{run_dir}/tree.json"
    ```
 
-   The script returns `{language, confidence, detection_source, detected_languages}` after walking the deterministic rule table (manifest presence first, then extension-frequency fallback). `detected_languages` is the ordered, deduplicated set of every manifest-level match in priority order, with `detected_languages[0]` equal to the winning `language`.
+   The script returns `{language, confidence, detection_source, source_language, detected_languages}`: the manifests nearest the tree's root decide (folder depth, then rule order), never one in a non-core or hidden folder while another exists, and with no manifest at the root the nearest one decides at `medium` confidence. `detected_languages` lists the deciding manifests' languages in that ranking, then the languages of the manifests that never decide, then `source_language` (the language most source files are in) when no manifest sits at the root, with `detected_languages[0]` equal to the winning `language`.
+
+3. **Auto-pick**: set `language` to the returned `language`. If `detected_languages` is empty (the script recognized no manifest and no source extensions: `language` is `"unknown"`), the repository may still ship agent skills written in Markdown alone, which step 3 documents as a skills module. Resolve `{skillsModuleHelper}` from `{skillsModuleProbeOrder}` and ask it:
+
+   ```bash
+   uv run {skillsModuleHelper} sniff --tree-file "{run_dir}/tree.json" [--scope-hint "{scope_hint}"]
+   ```
+
+   Pass `--scope-hint` when `scope_hint` is set, as step 3 does, so both steps classify the same folder.
+
+   - **`skills_module` is true**: set `language` to `markdown` and `language_resolution` to `detected`, keep `detected_languages` empty, and go on to §5.
+   - **Otherwise** (or no `{skillsModuleHelper}` candidate): treat it as a zero-match resolution: show the §3 resolution-failure guidance so the user can supply a language hint or a different target, and in headless mode HARD HALT with **exit code 3 (resolution-failure)**: stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "No language found in {repo_name}.", "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"`.
+
+4. **Multi-language gate** (`len(detected_languages) > 1`): the helper named more than one language (another manifest's, or the source files' language when no manifest sits at the root). Offer every detected language, the helper's pick first:
 
-3. **Auto-pick** — set `language` to the returned `language`. If `detected_languages` is empty (the script recognized no manifest and no source extensions — `language` is `"unknown"`), treat it as a zero-match resolution and HALT with the step 1 §3 resolution-failure guidance so the user can supply a language hint or a different target.
+   "**`{repo_name}` has manifests for multiple languages.**
 
-4. **Multi-language gate** (`len(detected_languages) > 1`) — the script found manifests for more than one language. Surface the choice rather than silently keeping the first match. Multi-language repos (Python + JS bindings, or monorepos with mixed manifests) otherwise produce a skill for whichever manifest sorts first in priority order, with no signal that the user might have wanted the other one.
+   1. **{language}** (`detected_languages[0]`, the helper's pick)
+   2. {detected_languages[1]}
 
-   "**`{repo_name}` has manifests for multiple languages:** {detected_languages}.
+   {and so on, one numbered line per entry of `detected_languages`}
 
-   Primary guess: **{language}** (`detected_languages[0]`, manifest-priority order). If you wanted a different language, abort and re-run with `--language-hint <lang>` or with the optional language hint at step 1 §1.
+   Select: [C] Continue with 1 · [2] to [n] Use that language · [A] Abort"
 
-   Select: [C] Continue with `{language}` · [A] Abort"
+   - **IF C**: log "user accepted multi-manifest pick: `{language}`", keep `language` and set `language_resolution: "user-confirmed"`.
+   - **IF 2 to n**: set `language` to that entry of `detected_languages`, set `language_resolution: "user-confirmed"` and log "user picked `{language}` of {detected_languages}". `detected_languages` keeps its order.
+   - **IF A**: HARD HALT with **exit code 3 (resolution-failure)**: "Aborted to disambiguate language. Re-run with `--language-hint <lang>`." Stage `{"phase": "resolve-target", "halt_reason": "resolution-failure", "reason": "Aborted to disambiguate language.", "skill_package": null, "details": {"detected_languages": [<detected_languages>], "auto_pick": "{language}"}}` 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"`.
+   - **GATE [default: C]**: headless mode auto-proceeds with the helper's pick, sets `language_resolution: "auto-picked-first"`, and records the decision: stage `{"gate": "resolve-target.multi-language", "default_action": "C", "taken_action": "C", "reason": "headless: kept the helper's pick", "evidence": {"detected_languages": [<detected_languages>]}}` as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-quick-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`. To build another of the languages headlessly, pass `--language-hint` (a batch line's `language=`).
 
-   - **IF C** — log "user accepted multi-manifest pick: `{language}`" and keep `language`.
-   - **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted to disambiguate language. Re-run with a `language_hint`." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {detected_languages: [...], auto_pick: "{language}"}`, `skill_package: null`).
-   - **GATE [default: C]** — Headless mode auto-proceeds with the manifest-priority pick; record `detected_languages` and `language_resolution: "auto-picked-first"` in the extraction context so the result contract surfaces the ambiguity downstream.
+Keep `language_resolution` and `detected_languages` (the helper's list, empty when a hint set the language) for step 6 §3's summary: `language_resolution` is `hint` when a language hint set the language, `detected` when the helper found no second manifest language (or the listing is a skills module with no code), and the gate's `user-confirmed` or `auto-picked-first` otherwise.
 
 ### 5. Confirm Resolution
 
@@ -176,6 +224,8 @@ Determine primary language:
 
 - **Repository:** {resolved_url}
 - **Name:** {repo_name}
+- **Registry:** {registry_used} (omit this line when no registry resolved the target)
+- **Ref:** {source_ref} (omit this line when `source_ref` is not set)
 - **Language:** {language}
 - **Scope:** {scope_hint or 'entire repo'}
 
@@ -183,5 +233,5 @@ Determine primary language:
 
 ### 6. Proceed to Next Step
 
-Once the target is resolved to a GitHub repository with confirmed URL, name, and detected language, load and execute {nextStepFile} for the ecosystem check.
+Once the target is resolved to a GitHub repository with confirmed URL, name, and detected language, load and execute {nextStepFile} for the ecosystem check; when `{headless_mode}` is true, print this step's `done` event and step 2's `start` event first (`references/halt-contract.md`).
 

package/src/skf-quick-skill/references/write-and-validate.md

@@ -6,6 +6,15 @@ frontmatterValidatorProbeOrder:
 outputValidatorProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-output.py'
   - '{project-root}/src/shared/scripts/skf-validate-output.py'
+descriptionGuardProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-description-guard.py'
+  - '{project-root}/src/shared/scripts/skf-description-guard.py'
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Generated SKILL.md text in {document_output_language}. -->
@@ -14,44 +23,80 @@ outputValidatorProbeOrder:
 
 ## STEP GOAL:
 
-To write the compiled SKILL.md, context-snippet.md, and metadata.json to the versioned skill package, then validate them on disk against the agentskills.io specification at community tier. Writing happens here (before step 6 finalization) because `skill-check` is a file-based CLI — it reads artifacts from disk — so the files must exist before validation runs. Report any gaps or issues. Validation is advisory — issues are reported but do not block the workflow.
+To write the compiled SKILL.md, context-snippet.md, and metadata.json to the versioned skill package, then validate them on disk against the agentskills.io specification at community tier. Validation is advisory: issues are reported but do not block the workflow.
 
 ## Rules
 
 - Write exactly what was compiled — do not modify content during writing or after validation
 - Community-tier validation (lighter than official requirements)
+- 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 Output Directory
+### 1. Check Ownership, Then Create Output Directory
 
-Resolve `{version}` from the extraction inventory's detected version, defaulting to `1.0.0` if not detected. Create the skill output directories:
+Resolve `{version}` ← the `version` of `{run_dir}/metadata.json`, which step 4 §4 rendered: the version the target pinned, else the manifest's, else `1.0.0`. The version folder and the file's `version` are then one value.
+
+**Ownership check.** Run it before creating any directory and before the overwrite prompt below. Resolve `{skillInventoryHelper}` ← first existing path in `{skillInventoryProbeOrder}` and run:
+
+```bash
+uv run {skillInventoryHelper} {skills_output_folder} --skill {repo_name} --write-check --write-version {version} --forge-data-folder {forge_data_folder}
+```
+
+`--forge-data-folder` only tells the helper whether both settings name one folder.
+
+Bind `{write_verdict}` ← `write_check.verdict`, `{write_folder}` ← `write_check.folder`, `{write_detail}` ← `write_check.detail`, and `{existing_generator}` ← `write_check.version_generated_by` and `{existing_tier}` ← `write_check.version_confidence_tier` (the build already at `{version}`, each null when none names it). Continue only when the status is `ok` and `{write_verdict}` is `"ok"`: nothing is at the skill folder yet, it holds only what an interrupted run leaves, or SKF generated it and the version is new or SKF's own. Otherwise create nothing and refuse with the first case that applies:
+
+- `{write_verdict}` is `"flat-layout"` → `halt_reason: "flat-layout"`: "**`{repo_name}` still uses the flat layout — nothing was written.** A version written beside its root `SKILL.md` would leave a skill SKF can no longer migrate or rename. Run `@Ferris TS {repo_name}` (or US, AS or EX) once to move it into the versioned layout, then re-run."
+- `{write_verdict}` is `"not-skf-output"` → `halt_reason: "not-skf-output"`: "**`{repo_name}` is not SKF output — nothing was written.** `{write_folder}` {write_detail}, so SKF will not write a version there. A shared `{skills_output_folder}` is supported: SKF leaves the skills it did not generate alone, so manage `{repo_name}` yourself, and Quick Skill names a skill after its target, so to create it under another name, brief it with `@Ferris BS` and compile it with `@Ferris CS`. Only if `{skills_output_folder}` holds a module's own source rather than skills, set `skills_output_folder` in `{project-root}/_bmad/skf/config.yaml` to a folder of its own, move your SKF skills there and re-run `/skf-setup`. A version folder with no `metadata.json` can also be one that an interrupted quick-skill run left behind; delete it yourself in that case."
+- The status is not `ok`, or the output has no `write_check` (an older helper: it has no `--write-check` and reports a new skill as `SKILL_NOT_FOUND`) → `halt_reason: "not-skf-output"`: the same message with "SKF could not check it ({the helper's `error`, if any}; re-install SKF if the installed `skf-skill-inventory.py` is out of date)" in place of "`{write_folder}` {write_detail}".
+- When no helper candidate resolves, continue only when nothing exists at `{skill_group}` (no folder, no file, not even a broken link). Otherwise refuse with `halt_reason: "not-skf-output"` and the same message, giving "SKF cannot check who generated `{skill_group}`: `skf-skill-inventory.py` is missing; re-install SKF" in place of "`{write_folder}` {write_detail}".
+
+Each refusal is a HARD HALT with **exit code 9 (state-conflict)**: stage `{"phase": "write-and-validate", "halt_reason": "<the halt reason>", "reason": "<the message's first sentence>", "skill_package": null, "details": {"folder": "<the folder the message names>"}}` 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"`, with no `--result-dir` (`references/halt-contract.md`). This halt writes no result file on disk: `{skill_package}` would sit in a folder SKF did not generate. It is a HALT, not a gate, so it has no headless default.
+
+Then create the skill output directories:
 
 ```
 {skill_group}                          # {skills_output_folder}/{repo_name}/
 {skill_package}                        # {skills_output_folder}/{repo_name}/{version}/{repo_name}/
 ```
 
-If `{skill_package}` already exists, confirm with user before overwriting:
+If `{skill_package}/metadata.json` exists, confirm with user before overwriting:
+
+"**Directory `{skill_package}` already exists.** It holds a `{existing_generator}` build ({existing_tier}); overwriting replaces it whole with a community quick skill, and validation results, result contracts, and any manual tweaks from the previous run will not be preserved. Overwrite existing files? [Y/N]" (say "an SKF build" in place of "a `{existing_generator}` build ({existing_tier})" when `{existing_generator}` is null, and leave out " ({existing_tier})" when only `{existing_tier}` is null).
 
-"**Directory `{skill_package}` already exists.** Overwrite will replace the prior compiled output; validation results, result contracts, and any manual tweaks from the previous run will not be preserved. Overwrite existing files? [Y/N]"
+- **If user selects Y:** when `{existing_generator}` is neither `quick-skill` nor null, remove the old package first, so none of its files (create-skill's `references/` and `extraction-rules.yaml`, for example) stays beside the quick skill, and set `{replaced_build}` ← `{existing_generator}` for step 6's summary. The `case` guard removes nothing unless the path is this skill's version package:
 
-- **If user selects Y:** Proceed to section 2.
-- **If user selects N:** HARD HALT with **exit code 5 (overwrite-cancelled)** per the exit-code map in `references/halt-contract.md`: "Overwrite cancelled. Existing skill preserved. Run [QS] with a different skill name or remove the existing directory manually." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "write-and-validate"`, `error.code: "overwrite-cancelled"`, `skill_package` set to the existing path that was preserved). Write the `-latest.json` envelope to disk here — `{skill_package}` is known, so consumers that hardcode that path see a deterministic file even on this cancelled run.
+  ```bash
+  case "{skill_package}" in */{repo_name}/{version}/{repo_name}) rm -rf "{skill_package}" && mkdir -p "{skill_package}" ;; esac
+  ```
 
-**GATE [default: Y]** — If `{headless_mode}` is true, auto-proceed with Y and log: "headless: overwriting existing `{skill_package}`".
+  Proceed to section 2.
+- **If user selects N:** HARD HALT with **exit code 5 (overwrite-cancelled)**: "Overwrite cancelled. Existing skill preserved. Quick Skill names a skill after its target, so to create it under another name, brief it with `@Ferris BS` and compile it with `@Ferris CS`; or remove the existing directory yourself and re-run." Stage `{"phase": "write-and-validate", "halt_reason": "overwrite-cancelled", "reason": "Overwrite cancelled. Existing skill preserved.", "skill_package": "{skill_package}", "details": {"existing_generator": "{existing_generator}"}}` as `{run_dir}/halt.json` (`existing_generator` null when none names it) 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"`: `{skill_package}` holds `metadata.json`, so the emitter also writes the `-latest.json` envelope there, and consumers that hardcode that path see a deterministic file even on this cancelled run.
+
+**GATE [default: Y]** when `{existing_generator}` is `quick-skill` or null: if `{headless_mode}` is true, auto-proceed with Y, log "headless: overwriting existing `{skill_package}`", and record the decision: stage `{"gate": "write-and-validate.overwrite", "default_action": "Y", "taken_action": "Y", "reason": "headless: overwrote the existing package", "evidence": {"skill_package": "{skill_package}"}}` as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-quick-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`.
+
+**GATE [default: N]** for any other `{existing_generator}`, so no headless run or batch replaces another workflow's build with a quick skill: if `{headless_mode}` is true, record the decision: stage `{"gate": "write-and-validate.overwrite", "default_action": "N", "taken_action": "N", "reason": "headless: kept the {existing_generator} build", "evidence": {"skill_package": "{skill_package}", "existing_generator": "{existing_generator}"}}` 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 halt as **If user selects N** does, with the message "**Kept the `{existing_generator}` build at `{skill_package}`.** A headless run never replaces another workflow's build with a quick skill. To replace it, run Quick Skill interactively and answer Y; to keep it, give the quick skill another version (`@Ferris QS <package>@<version>`)." and the `reason` "Kept the {existing_generator} build: a headless run never replaces another workflow's build".
+
+A `{skill_package}` without `metadata.json` holds only what an interrupted run leaves (the ownership check refuses anything else), so it is written without asking.
 
 ### 2. Write Deliverables
 
-Write the three compiled artifacts to the skill package so that validation in sections 3–7 has files on disk to read:
+Write the three compiled artifacts to the skill package in this order, `metadata.json` first, so a run interrupted mid-write leaves a package that carries the SKF marker, which the next run's ownership check accepts:
+
+1. `{skill_package}/metadata.json`: installed from the file step 4 §4 rendered, never typed again. Resolve `{atomicWriteHelper}` ← first existing path in `{atomicWriteProbeOrder}` and run:
+
+   ```bash
+   uv run {atomicWriteHelper} write --target "{skill_package}/metadata.json" < "{run_dir}/metadata.json"
+   ```
 
-**File 1:** `{skill_package}/SKILL.md` — the compiled skill document
-**File 2:** `{skill_package}/context-snippet.md` — the compressed context snippet. **Skip this write** if `{overrides.skip_snippet}` was set; the artifact is omitted from `outputs`.
-**File 3:** `{skill_package}/metadata.json` — the machine-readable metadata
+   It writes the file in place atomically, so an interrupted run never leaves half a `metadata.json`. If no candidate exists, write nothing and HARD HALT with **exit code 3 (resolution-failure)**, in interactive mode too: "**Nothing was written to `{skill_package}`.** SKF's atomic writer (`skf-atomic-write.py`) is missing from `{project-root}/_bmad/skf/shared/scripts/`, so re-install SKF." Stage `{"phase": "write-and-validate", "halt_reason": "resolution-failure", "reason": "Nothing was written: the atomic writer is missing.", "skill_package": "{skill_package}", "details": {"cause": "atomic-writer-missing"}}` as `{run_dir}/halt.json` 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"`, without `--result-dir "{skill_package}"` when no earlier run's `metadata.json` is there (`references/halt-contract.md`).
+2. `{skill_package}/SKILL.md`: the compiled skill document.
+3. `{skill_package}/context-snippet.md`: the compressed context snippet. **Skip this write** if `{overrides.skip_snippet}` was set; the artifact is omitted from `outputs`.
 
-Confirm after each write: "Written: SKILL.md" / "Written: context-snippet.md" / "Written: metadata.json". When `--skip-snippet` is active, log "Skipped: context-snippet.md (--skip-snippet)" instead of the snippet write confirmation.
+Confirm after each write: "Written: metadata.json" / "Written: SKILL.md" / "Written: context-snippet.md". When `--skip-snippet` is active, log "Skipped: context-snippet.md (--skip-snippet)" instead of the snippet write confirmation.
 
-**If any write fails — HARD HALT (exit code 4, write-failure):** Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "write-and-validate"`, `error.code: "write-failure"`, `error.details: {failed_path: <path>, error: <details>}`, `skill_package` set, `outputs` listing any files that did write successfully before the failure).
+**If any write fails, HARD HALT (exit code 4, write-failure):** stage `{"phase": "write-and-validate", "halt_reason": "write-failure", "reason": "Write failed: could not write <path>.", "skill_package": "{skill_package}", "outputs": {<each file that did write before the failure, as "metadata", "skill_md" or "context_snippet" with its path>}, "details": {"failed_path": "<path>", "error": "<details>"}}` as `{run_dir}/halt.json` 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"`. When `metadata.json` itself failed to write, run it without `--result-dir "{skill_package}"`: the contract writes no result file on disk, because a package holding only result files would read as not SKF output to the next run's ownership check.
 
 "**Write failed:** Could not write to `{file_path}`.
 
@@ -67,17 +112,21 @@ Check:
 Run: `npx skill-check -h`
 
 - If succeeds (returns usage information): Continue to automated validation (section 4)
-- If fails (command not found or error): Skip to manual fallback in section 4
+- If fails (command not found or error): skip to the frontmatter validator in section 4, and log "security scan skipped: skill-check unavailable" in the validation results
 
 ### 4. Validate SKILL.md via skill-check (if available)
 
-**If `npx skill-check` is available**, run automated validation + security scan in one invocation against the skill package written in section 2 (security scan is enabled by default when `--no-security-scan` is omitted, so the same call covers §6 and avoids paying the npx startup cost twice):
+**If `npx skill-check` is available**, run validation and its security scan in one call against the skill package written in section 2. `--fix` can also rewrite the frontmatter `description` the user approved in step 4, which would leave SKILL.md out of step with `metadata.json`, so the call runs inside the description guard. Resolve `{descriptionGuardHelper}` ← first existing path in `{descriptionGuardProbeOrder}`, then run the three commands in order:
 
 ```bash
-npx skill-check check {skill_package} --fix --format json
+uv run {descriptionGuardHelper} capture "{skill_package}/SKILL.md" > "{run_dir}/description-guard.json"
+npx skill-check check "{skill_package}" --fix --format json
+uv run {descriptionGuardHelper} verify-restore "{skill_package}/SKILL.md" --captured-file "{run_dir}/description-guard.json"
 ```
 
-This validates frontmatter, description, body limits, links, and formatting; runs the security scan; and auto-fixes deterministic issues (field ordering, slug format, required fields, trailing newlines).
+**Guard outputs.** `capture` stages the approved description in `{run_dir}/description-guard.json` and `verify-restore` reads it there, so it never passes through a shell string. Bind `{guard_restored}` ← `restored` and `{guard_diff_kind}` ← `diff_kind` from `verify-restore`. When `{guard_restored}` is true, the approved description is back in SKILL.md, matching `metadata.json`: record the validation note "description restored after `skill-check --fix` ({guard_diff_kind})", which §6 lists with the auto-fixed issues. `verify-restore` refuses an empty or whitespace-only captured description, and a file it cannot read (exit 1, SKILL.md untouched): re-run it with `--captured-file "{skill_package}/metadata.json"`, whose `description` step 4 rendered, never with an empty value, and if that exits 1 too, record a high-severity issue: the guard could not check the description. When it exits 2 with JSON on stdout (the JSON carries `restore_error`), the restore could not be written, so record a high-severity issue: SKILL.md's description no longer matches `metadata.json`.
+
+**If no `{descriptionGuardProbeOrder}` path exists**, never run `--fix` unguarded. Run `npx skill-check check "{skill_package}" --format json` instead, which validates and scans without fixing, and log the validation issue "description guard unavailable (`skf-description-guard.py` missing): skill-check ran without `--fix`".
 
 **Parse JSON output** to extract:
 - `scores[].score` — overall score (0-100); match the entry by `relativePath`/`skillId`
@@ -85,45 +134,35 @@ This validates frontmatter, description, body limits, links, and formatting; run
 - `fixed[]` — issues automatically corrected
 - `security[]` (when present) — security findings, recorded as advisory warnings (security issues do not block output)
 
-Record quality score, remaining diagnostics, and security findings as validation issues.
+Bind `{quality_score}` ← that score, and record the remaining diagnostics and security findings as validation issues. `{quality_score}` is null when skill-check did not run.
 
-**If skill-check is not available**, run the shared frontmatter validator. Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}`; first existing path wins. If no candidate exists, log a high-severity issue ("frontmatter validator unavailable — both `npx skill-check` and `skf-validate-frontmatter.py` missing") and skip frontmatter validation.
+**If skill-check is not available**, run the shared frontmatter validator. Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}`; first existing path wins. If no candidate exists, nothing can check the frontmatter: HARD HALT with **exit code 3 (resolution-failure)**, in interactive mode too: "**`{skill_package}` was written but not validated.** skill-check is unavailable and SKF's frontmatter validator (`skf-validate-frontmatter.py`) is missing from `{project-root}/_bmad/skf/shared/scripts/`, so re-install SKF, then re-run." Stage `{"phase": "write-and-validate", "halt_reason": "resolution-failure", "reason": "The skill was written but not validated: the frontmatter validator is missing.", "skill_package": "{skill_package}", "outputs": {<each deliverable §2 wrote, as "metadata", "skill_md" or "context_snippet" with its path>}, "details": {"cause": "frontmatter-validator-missing"}}` as `{run_dir}/halt.json` 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"`.
 
 ```bash
-uv run {frontmatterValidator} {skill_package}/SKILL.md --skill-dir-name {repo_name}
+uv run {frontmatterValidator} "{skill_package}/SKILL.md" --skill-dir-name {repo_name}
 ```
 
-The validator emits JSON with `status` (`pass`/`fail`), `issues[]` (each with `severity`, `code`, `message`), and `frontmatter` (the parsed name/description). It checks frontmatter delimiters, name format (Unicode letters + digits + hyphens, no consecutive/trailing hyphens), name-directory match, description presence and length, and unknown fields against the agentskills.io spec. Record each `issues[]` entry as a validation issue with its reported severity. Missing frontmatter or missing required fields are high-severity — skills without valid frontmatter will fail `npx skills add` and `npx skill-check check`.
+The validator emits JSON with `status` (`pass`/`fail`), `issues[]` (each with `severity`, `code`, `message`), and `frontmatter` (the parsed name/description). Record each `issues[]` entry as a validation issue with its reported severity.
 
 ### 5. Validate Body, Snippet, and Metadata via skf-validate-output.py
 
 Run the shared output validator against the on-disk skill package — it performs the body-structure, snippet-format, and metadata-shape checks. Pass `--skip-frontmatter` since §4 has already covered frontmatter.
 
-**Resolve `{outputValidator}`:** probe `{outputValidatorProbeOrder}` (installed first, dev fallback); first existing path wins. If neither candidate exists, log a high-severity issue ("output validator unavailable — `skf-validate-output.py` missing") and skip body/snippet/metadata validation.
+**Resolve `{outputValidator}`** from `{outputValidatorProbeOrder}`; first existing path wins. If no candidate exists, HARD HALT with **exit code 3 (resolution-failure)**, in interactive mode too: "**`{skill_package}` was written but not validated.** SKF's output validator (`skf-validate-output.py`) is missing from `{project-root}/_bmad/skf/shared/scripts/`, so re-install SKF, then re-run." Stage `{"phase": "write-and-validate", "halt_reason": "resolution-failure", "reason": "The skill was written but not validated: the output validator is missing.", "skill_package": "{skill_package}", "outputs": {<each deliverable §2 wrote, as "metadata", "skill_md" or "context_snippet" with its path>}, "details": {"cause": "output-validator-missing"}}` as `{run_dir}/halt.json` 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"`. Otherwise run:
 
 ```bash
-python3 {outputValidator} {skill_package} --generated-by quick-skill --skip-frontmatter
+uv run {outputValidator} "{skill_package}" --generated-by quick-skill --skip-frontmatter
 ```
 
 The validator emits JSON with `result` (PASS/FAIL), `validation.skill_md.body[]`, `validation.context_snippet.issues[]`, `validation.metadata.issues[]`, and a severity-bucketed `summary`. Record each issue as a validation issue at its reported severity.
 
-The validator covers:
-
-- **Body structure** — Overview, Description, Key Exports, Usage sections present (medium when missing)
-- **Context snippet** — `[{name} v{version}]|root: ...` first line, `|IMPORTANT:` second line, ~80–120-token length
-- **Metadata** — required string fields (`name`, `version`, `source_authority`, `language`, `generation_date`), `source_repo`, `generated_by`, `confidence_tier`, and `stats` numerics (`exports_documented`, `exports_public_api`, `exports_total`, `public_api_coverage`, `total_coverage`)
-
-### 6. Security Scan (covered by §4)
-
-Security findings are already collected from the §4 invocation (no separate `npx` round trip needed — `skill-check check ... --fix --format json` runs the security scan by default). If skill-check was unavailable in §3, log "security scan skipped — skill-check unavailable" in validation results.
-
-### 7. Report Validation Results
+### 6. Report Validation Results
 
 "**Validation complete:**
 
 **SKILL.md:** {pass/issues found} (quality score: {score}/100 if skill-check was available)
 {list any issues}
-{list any auto-fixed issues}
+{list any auto-fixed issues, and the §4 description-guard note when the guard restored the description}
 
 **context-snippet.md:** {pass/issues found}
 {list any issues}
@@ -137,13 +176,13 @@ Security findings are already collected from the §4 invocation (no separate `np
 **Overall:** {pass / N issues found}
 
 {If issues found:}
-These issues are advisory for community-tier skills. You can proceed to finalize or go back to adjust.
+These issues are advisory for community-tier skills: fix them in the written files, or re-run Quick Skill once the source or the hints change.
 
 **Proceeding to finalize...**"
 
-Set `validation_result` with pass/fail status, quality score, and issues list.
+Set `validation_result` with pass/fail status, quality score, and issues list, and `{validation_issues}` ← `{"skill_md": <n>, "context_snippet": <n>, "metadata": <n>, "security": <n>}`, each `<n>` the number of entries the validators returned for that heading: `skill_md` counts skill-check's `diagnostics[]` (without skill-check, the frontmatter validator's `issues[]`) plus `validation.skill_md.body[]`; `context_snippet` counts `validation.context_snippet.issues[]`; `metadata` counts `validation.metadata.issues[]`; `security` counts skill-check's `security[]`. A check that did not run counts 0, and `fixed[]` and the guard note count nothing. Step 6 §3's summary carries `{quality_score}` and `{validation_issues}`.
 
-### 8. Auto-Proceed to Finalize
+### 7. Auto-Proceed to Finalize
 
-Once deliverables are written to `{skill_package}` and validation is reported (advisory), load and execute {nextStepFile} to finalize.
+Once deliverables are written to `{skill_package}` and validation is reported (advisory), load and execute {nextStepFile} to finalize; when `{headless_mode}` is true, print this step's `done` event and step 6's `start` event first (`references/halt-contract.md`).