bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-brief-skill/references/step-auto-brief.md

@@ -6,9 +6,6 @@ validateBriefSchemaProbeOrder:
 writeSkillBriefProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
   - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
-emitBriefEnvelopeProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
-  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 mergeDocUrlsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-merge-doc-urls.py'
   - '{project-root}/src/shared/scripts/skf-merge-doc-urls.py'
@@ -23,7 +20,7 @@ detectDocsProbeOrder:
 
 ## STEP GOAL:
 
-To enrich an upstream skill brief (produced by AN auto-scope) with documentation URLs discovered via `skf-detect-docs.py`, validate the enriched brief, and write it through the canonical writer. Envelope emission is deferred to step-auto-validate.md, which presents the brief for user approval before continuing. This step replaces the interactive gather-intent → analyze-target → scope-definition → confirm-brief → write-brief chain when `[auto]` mode is active.
+To enrich an upstream skill brief (produced by AN auto-scope) with documentation URLs discovered via `skf-detect-docs.py`, validate the enriched brief, and write it through the canonical writer. Envelope emission is deferred to step-auto-validate.md, which checks the written brief and summarizes it first. This step replaces the interactive gather-intent → analyze-target → scope-definition → confirm-brief → write-brief chain when `[auto]` mode is active.
 
 ## Rules
 
@@ -40,9 +37,7 @@ To enrich an upstream skill brief (produced by AN auto-scope) with documentation
 
 Read the upstream brief path from `{brief_path}` (passed by the forger from AN's `SKF_ANALYZE_RESULT_JSON` `brief_paths[]`).
 
-**IF `{brief_path}` is not set or the file does not exist:**
-- HARD HALT with exit code 2 (`input-missing`): "**Auto-brief requires an upstream brief — `brief_path` is missing or the file does not exist at `{brief_path}`.**"
-- Emit error envelope per §6 with `halt_reason: "input-missing"`.
+**IF `{brief_path}` is not set or the file does not exist:** emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "input-missing"` (SKILL.md Halt Contract), then HARD HALT (exit code 2): "**Auto-brief requires an upstream brief: `brief_path` is missing or the file does not exist at `{brief_path}`.**"
 
 **Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
@@ -54,23 +49,12 @@ uv run {validateBriefSchemaHelper} {brief_path}
 
 The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}`.
 
-- **`valid: false`** — the upstream brief is malformed. HARD HALT with exit code 2 (`input-invalid`): "**Upstream brief at `{brief_path}` is invalid: {first error message}.**" Emit error envelope per §6 with `halt_reason: "input-invalid"`.
-- **`valid: true`** — proceed with the parsed `brief` payload. Surface any non-empty `warnings[]` to the log.
+- **`valid: false`**: the upstream brief is malformed. Emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "input-invalid"` (SKILL.md Halt Contract), then HARD HALT (exit code 2): "**Upstream brief at `{brief_path}` is invalid: {first error message}.**"
+- **`valid: true`**: proceed with the parsed `brief` payload. Log any non-empty `warnings[]` and add each to `workflow_warnings[]` as `<field>: <message>`.
 
-Extract from the parsed brief:
-- `skill_name` ← `brief.name`
-- `version` ← `brief.version`
-- `source_repo` ← `brief.source_repo`
-- `language` ← `brief.language`
-- `scope_type` ← `brief.scope.type`
-- `forge_tier` ← `brief.forge_tier`
-- `description` ← `brief.description`
-- `created` ← `brief.created`
-- `created_by` ← `brief.created_by`
-- All scope fields: `scope.include`, `scope.exclude`, `scope.notes`, `scope.rationale`, `scope.amendments`, `scope.tier_a_include`
-- Optional fields: `source_type`, `source_authority`, `doc_urls`, `target_version`, `target_ref`, `source_ref`, `scripts_intent`, `assets_intent`
+Nothing the upstream brief carries is rebuilt or dropped: §4's writer starts from the upstream brief file itself. That covers the top-level fields (`name`, `version`, `source_type`, `source_repo`, `language`, `description`, `forge_tier`, `created`, `created_by`, `source_authority`, `doc_urls`, `target_version`, `target_ref`, `source_ref`, `scripts_intent`, `assets_intent`) and all scope fields: `scope.type`, `scope.include`, `scope.exclude`, `scope.notes`, `scope.rationale`, `scope.amendments`, `scope.tier_a_include`, `scope.registry_path`, `scope.ui_variants`, `scope.demo_patterns`. The sections below read `skill_name` ← `brief.name`, `source_repo` ← `brief.source_repo`, `scope_type` ← `brief.scope.type` and `source_type` ← `brief.source_type`.
 
-**Docs-only check:** If `source_type` is `docs-only` in the parsed brief, skip §2 (Run Doc Detection) and §3 (Enrich Brief with Detected Docs) — the doc URL is already in the brief's `doc_urls`. Log: "Docs-only brief — skipping repo-based doc detection. Doc URLs provided by upstream." Proceed directly to §4 (Validate Enriched Brief). All brief fields (`source_type`, `source_authority`, `doc_urls`, `scope_type`) must pass through unmodified.
+**Docs-only check:** If `source_type` is `docs-only` in the parsed brief, skip §2 (Run Doc Detection) and §3 (Enrich Brief with Detected Docs): the doc URL is already in the brief's `doc_urls`. Log: "Docs-only brief: skipping repo-based doc detection. Doc URLs provided by upstream." Proceed directly to §4 (Write Enriched Brief). All brief fields (`source_type`, `source_authority`, `doc_urls`, `scope_type`) must pass through unmodified.
 
 ### 2. Run Doc Detection
 
@@ -88,7 +72,7 @@ uv run {detectDocsHelper} --repo-url {source_repo}
 
 - **Exit 0 (found docs):** Parse the JSON output array. Each entry has `{url, detected_via, content_hash, content_type}`. Proceed to §3 with the detected docs.
 - **Exit 1 (none found):** Log: "No external documentation found — brief generated from source analysis only." Proceed to §4 with no doc enrichment.
-- **Exit 2 (error):** Log warning: "Doc detection failed — proceeding without doc enrichment." Do NOT halt — doc enrichment is best-effort. Proceed to §4 with no doc enrichment.
+- **Exit 2 (error):** Log the warning "Doc detection failed: proceeding without doc enrichment." and add it to `workflow_warnings[]`. Do NOT halt: doc enrichment is best-effort. Proceed to §4 with no doc enrichment.
 
 ### 3. Enrich Brief with Detected Docs
 
@@ -106,79 +90,39 @@ For each detected doc entry, create a brief `doc_urls` entry:
     - `"docs_folder"` → `"Docs Folder"`
 - `source` ← coarse provenance derived from `detected_via` (per the `skill-brief.v1.json` `doc_urls[].source` enum): `homepageUrl` → `homepage`, `readme_link` → `readme-detection`, `pages_api` → `pages-api`, `docs_folder` → `docs-folder`. This marks the entry as opportunistically detected, distinct from a registry-guaranteed corpus.
 
-**Merge via the canonical helper.** Resolve `{mergeDocUrlsHelper}` from `{mergeDocUrlsProbeOrder}` (first existing path wins; HALT if neither exists). Pass the upstream brief's `doc_urls` as `existing` and the entries just mapped above as `detected`:
+**Merge via the canonical helper.** Resolve `{mergeDocUrlsHelper}` from `{mergeDocUrlsProbeOrder}` (first existing path wins; HALT if neither exists). Stage its input in the run folder, the upstream brief's `doc_urls` as `existing` and the entries just mapped above as `detected`, then run it on the file:
 
 ```bash
-echo '{"scope_type": "{scope_type}", "existing": {upstream brief doc_urls JSON, [] if none}, "detected": {mapped detected entries JSON}}' \
-  | uv run {mergeDocUrlsHelper}
+cat > "{run_dir}/doc-urls.json" <<'SKF_JSON'
+{"scope_type": "<scope_type>", "existing": <the upstream brief's doc_urls, [] if none>, "detected": <the mapped detected entries>}
+SKF_JSON
+uv run {mergeDocUrlsHelper} < "{run_dir}/doc-urls.json" > "{run_dir}/doc-urls-merged.json"
 ```
 
+The redirect keeps the helper's output in `{run_dir}/doc-urls-merged.json`: §4 hands the writer that file, and the suppressed entries below are read from it.
+
 The helper returns `{"doc_urls": [...], "suppressed": [...]}`. It deduplicates by **normalized** URL (lowercase host, strip a trailing `/index.html` and any trailing `/`), so a seeded `…/book/` and a README's `…/book/index.html` collapse to one entry; existing/corpora-seeded entries always win and keep their `source: language-registry`, so the registry-vs-detected distinction survives the merge. For a **whole-language reference** (`scope_type == "full-library"` AND ≥1 `existing` entry has `source: language-registry`) it additionally suppresses README noise on a corpus host: non-corpus path segments (`/whatsnew/`, `/contribute`, `/wiki/`) and non-primary-locale duplicates of a kept page (`/ja/master/` when `/en/master/` is kept). Ordinary skills (any other `scope_type`, or no registry corpora) pass through with dedup only — no suppression. Use the returned `doc_urls` as the brief's merged list.
 
 **Log suppressed entries.** When `suppressed` is non-empty, log one line per entry — `"info: suppressed {url} ({reason})"` — so the operator can see what the whole-language noise filter dropped (never drop silently). The N==0 DEGRADED case (a whole-language repo whose registry returned no corpora) carries no `language-registry` entry, so suppression stays inactive and its README docs are kept — this is intentional (there is no canonical corpus host to filter against).
 
-### 4. Validate Enriched Brief
-
-Assemble the enriched brief context as a flat JSON object following the write-brief §3 contract:
-
-```json
-{
-  "name":             "{skill_name}",
-  "target_version":   "{target_version or null}",
-  "detected_version": null,
-  "source_type":      "{source_type or 'source'}",
-  "source_repo":      "{source_repo}",
-  "language":         "{language}",
-  "description":      "{description}",
-  "forge_tier":       "{forge_tier}",
-  "created":          "{created}",
-  "created_by":       "{created_by}",
-  "scope_type":       "{scope_type}",
-  "scope_include":    ["{scope.include patterns}"],
-  "scope_exclude":    ["{scope.exclude patterns}"],
-  "scope_notes":      "{scope.notes or ''}",
-  "scope_rationale":  null,
-  "scope_tier_a_include": null,
-  "scope_amendments":     null,
-  "doc_urls":         [{"url": "...", "label": "...", "source": "..."}],
-  "scripts_intent":   "{scripts_intent or null}",
-  "assets_intent":    "{assets_intent or null}",
-  "source_authority": "{source_authority or null}",
-  "target_ref":       "{target_ref or null}",
-  "source_ref":       "{source_ref or null}",
-  "version_resolved": "{version}"
-}
-```
-
-The `version_resolved` key pins the output to the upstream brief's version — without it, the writer's precedence logic falls through to `1.0.0` since `target_version` and `detected_version` are both null on the auto path.
-
-### 5. Write Enriched Brief
+### 4. Write Enriched Brief
 
 **Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
-Write the enriched brief through the canonical writer:
+Write the enriched brief through the canonical writer. It starts from the upstream brief file (`--base-brief`), keeps every field and the version it holds, replaces `doc_urls` with the merged list (`--doc-urls-file`), validates the result and writes it atomically:
 
 ```bash
-echo '<context-json>' | uv run {writeSkillBriefHelper} write --target {forge_data_folder}/{skill_name}/skill-brief.yaml --from-flat
+uv run {writeSkillBriefHelper} write --target {forge_data_folder}/{skill_name}/skill-brief.yaml --base-brief "{brief_path}" --doc-urls-file "{run_dir}/doc-urls-merged.json"
 ```
 
-**On script failure (non-zero exit):**
-- Exit 1 (validation/invariant): Emit error envelope per §6 with `halt_reason: "input-invalid"`, then HARD HALT.
-- Exit 2 (I/O failure): Emit error envelope per §6 with `halt_reason: "write-failed"`, then HARD HALT.
-
-**On success:** Capture `brief_path` and `version` from the response envelope for step-auto-validate's envelope emission.
+Leave `--doc-urls-file` out when §2 and §3 were skipped or found nothing.
 
-### 6. Error Envelope (Canonical)
-
-Every HARD HALT in this step emits the error envelope on stderr:
-
-**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**On script failure (non-zero exit):**
+- Exit 1 (validation/invariant): emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "input-invalid"` (SKILL.md Halt Contract), then HARD HALT (exit code 2).
+- Exit 2 (I/O failure): emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "write-failed"` (SKILL.md Halt Contract), then HARD HALT (exit code 4).
 
-```bash
-echo '{"status":"error","skill_name":"{skill_name or unknown}","halt_reason":"{reason}","mode":"auto"}' | \
-  uv run {emitBriefEnvelopeHelper} emit --target stderr
-```
+**On success:** Capture `brief_path` and `version` from the response envelope for step-auto-validate's envelope emission, and add each entry of its `warnings[]` to `workflow_warnings[]`.
 
-### 7. Chain to Auto-Validate
+### 5. Chain to Auto-Validate
 
-Load, read fully, then execute {nextStepFile} to present the auto-brief validation gate, where the user can approve, edit, or reject the brief before the pipeline continues. Do this only after the enriched brief has been written and validated.
+Load, read fully, then execute {nextStepFile}, which checks and summarizes the written brief, builds the envelope and runs the hook. Do this only after the enriched brief has been written and validated.

package/src/skf-brief-skill/references/step-auto-validate.md

@@ -1,15 +1,9 @@
 ---
 nextStepFile: 'health-check.md'
-rejectTargetFile: 'confirm-brief.md'
+writeBriefFile: 'write-brief.md'
 validateBriefSchemaProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
   - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
-writeSkillBriefProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
-  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
-emitBriefEnvelopeProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
-  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -18,21 +12,20 @@ emitBriefEnvelopeProbeOrder:
 
 ## STEP GOAL:
 
-To present the user with a concise summary of the auto-generated brief and offer three actions — approve, edit, or reject — before the pipeline continues. On approve or edit, the result envelope is emitted and the pipeline chains to the health check. On reject, the pipeline falls back to the interactive brief review cycle with pre-populated fields.
+To check the auto-generated brief against the schema and show a concise summary of it, register it in QMD at Deep tier, then build and bind the result envelope (the health check displays it as the run's last line), run the `on_complete` hook and chain to the health check. `[auto]` is a pipeline stage, which the forger always runs headless, so this step asks nothing.
 
 ## Rules
 
 - This step is conditional — only loaded from step-auto-brief.md when `[auto]` mode is active
-- The brief MUST already exist on disk (written by step-auto-brief §5) before this step runs
+- The brief MUST already exist on disk (written by step-auto-brief §4) before this step runs
 - Do NOT render YAML or JSON envelopes in the LLM — delegate to deterministic scripts
-- Do NOT modify confirm-brief.md or write-brief.md — the [R]eject path reuses them as-is
 - The 10-line summary is always displayed, even in headless mode, for logging transparency
 
 ## MANDATORY SEQUENCE
 
 ### 1. Load Auto-Brief
 
-Read the brief from `{forge_data_folder}/{skill_name}/skill-brief.yaml` (written by step-auto-brief §5).
+Read the brief from `{forge_data_folder}/{skill_name}/skill-brief.yaml` (written by step-auto-brief §4).
 
 **Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
@@ -44,11 +37,10 @@ uv run {validateBriefSchemaHelper} {forge_data_folder}/{skill_name}/skill-brief.
 
 The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}`.
 
-- **`valid: false`** — HARD HALT with exit code 2 (`input-invalid`): "**Auto-brief at `{forge_data_folder}/{skill_name}/skill-brief.yaml` is invalid: {first error message}.**" Emit error envelope per §7 with `halt_reason: "input-invalid"`.
-- **`valid: true`** — proceed with the parsed `brief` payload. Surface any non-empty `warnings[]` to the log.
+- **`valid: false`**: emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "input-invalid"` (SKILL.md Halt Contract), then HARD HALT (exit code 2): "**Auto-brief at `{forge_data_folder}/{skill_name}/skill-brief.yaml` is invalid: {first error message}.**"
+- **`valid: true`**: proceed with the parsed `brief` payload. Log any non-empty `warnings[]` and add each to `workflow_warnings[]` as `<field>: <message>`.
 
-**IF the file does not exist:**
-- HARD HALT with exit code 2 (`input-missing`): "**Auto-brief not found at `{forge_data_folder}/{skill_name}/skill-brief.yaml` — step-auto-brief must write the brief before this step runs.**" Emit error envelope per §7 with `halt_reason: "input-missing"`.
+**IF the file does not exist:** emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "input-missing"` (SKILL.md Halt Contract), then HARD HALT (exit code 2): "**Auto-brief not found at `{forge_data_folder}/{skill_name}/skill-brief.yaml`: step-auto-brief must write the brief before this step runs.**"
 
 Extract from the parsed brief:
 - `skill_name` ← `brief.name`
@@ -81,125 +73,32 @@ Description:  "{description}"
 
 Where `{N}` is the count of `scope_include` patterns and `{M}` is the count of `scope_exclude` patterns. If `doc_urls` is null or empty, display "None detected". The `Pipeline` line names the auto pipeline and the resolved `{forge_tier}` — it carries no numeric quality target, which would be an unverified guarantee an automator might parse as fact.
 
-### 3. Validation Gate
+### 3. Envelope, Hook and Chain
 
-**GATE: [A]pprove** — Present `[A]pprove` / `[E]dit` / `[R]eject` to user.
+**QMD registration.** When the run's forge tier (step 1 §1) is Deep, load `{writeBriefFile}` and run its §3b (QMD Collection Registration) alone, with `{skill-name}` ← `{skill_name}`, then come back here: it indexes the brief when QMD is available, and a warning it raises goes on `workflow_warnings[]` before the envelope below is built. Run nothing else of that file. At any other tier, skip this.
 
-"**Review the auto-generated brief above.**
-
-Select an action:
-  [A] Approve — accept the brief as-is and continue the pipeline
-  [E] Edit — modify specific fields before continuing
-  [R] Reject — fall back to interactive brief review with pre-populated fields"
-
-If `{headless_mode}`: auto-proceed with `[A]pprove`, log: "headless: auto-approve auto-brief".
-
-Wait for user response. Branch on the response:
-
-- `[A]` or `approve` → §4 ([A]pprove path)
-- `[E]` or `edit` → §5 ([E]dit path)
-- `[R]` or `reject` → §6 ([R]eject path)
-- Any other input → answer briefly, re-display the menu
-
-### 4. [A]pprove Path
-
-**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins. HALT if no candidate exists.
-
-Emit the `SKF_BRIEF_RESULT_JSON` envelope with `mode: "auto"`:
-
-```bash
-echo '{"status":"success","brief_path":"{brief_path}","skill_name":"{skill_name}","version":"{version}","language":"{language}","scope_type":"{scope_type}","halt_reason":null,"mode":"auto"}' | \
-  uv run {emitBriefEnvelopeHelper} emit
-```
-
-Where `{brief_path}` is `{forge_data_folder}/{skill_name}/skill-brief.yaml`.
-
-Chain to {nextStepFile} (health-check.md) — load, read fully, then execute.
-
-### 5. [E]dit Path
-
-Present each brief field with its current value and accept natural language modification requests.
-
-"**Editable fields:**
-
-1. **Name:** {skill_name}
-2. **Source:** {source_repo}
-3. **Language:** {language}
-4. **Scope type:** {scope_type}
-5. **Include patterns:** {scope_include}
-6. **Exclude patterns:** {scope_exclude}
-7. **Description:** {description}
-8. **Doc URLs:** {doc_urls or "None"}
-9. **Version:** {version}
-10. **Forge tier:** {forge_tier}
-
-Tell me what to change (e.g. 'change scope type to public-api', 'add doc URL https://...')."
-
-Wait for user response. Apply changes to the brief context.
-
-**Re-write the modified brief** through the canonical writer:
-
-**Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}`; first existing path wins.
-
-Assemble the modified brief context as a flat JSON object (same format as step-auto-brief §4):
+Build the `SKF_BRIEF_RESULT_JSON` envelope with `mode: "auto"`, through the `{emitBriefEnvelopeHelper}` SKILL.md On Activation step 4 resolved (`references/invocation-contract.md` defines each field). Bind `{result_envelope_line}` to the line it prints, and do not display it here: the shared health check displays it verbatim as the run's last line, the final message the pipeline reads:
 
 ```bash
-echo '<modified-flat-json>' | uv run {writeSkillBriefHelper} write --target {forge_data_folder}/{skill_name}/skill-brief.yaml --from-flat
+uv run {emitBriefEnvelopeHelper} emit <<'SKF_BRIEF_RESULT'
+{"status":"success","brief_path":"{brief_path}","skill_name":"{skill_name}","version":"{version}","language":"{language}","scope_type":"{scope_type}","halt_reason":null,"mode":"auto","warnings":[<workflow_warnings[] as JSON strings>]}
+SKF_BRIEF_RESULT
 ```
 
-The canonical writer validates the brief internally — on non-zero exit, surface the error and re-prompt for corrections. The edit loop allows multiple modifications — each write re-validates before accepting.
+Where `{brief_path}` is `{forge_data_folder}/{skill_name}/skill-brief.yaml`. If `{emitBriefEnvelopeHelper}` has no path, or the helper exits non-zero or prints no line, leave `{result_envelope_line}` empty and display its error: the brief is already written, so the run goes on.
 
-**Re-validate the written brief** against the schema to confirm correctness:
-
-**Resolve `{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins.
+**On-complete hook.** Right after the envelope, if `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), run it:
 
 ```bash
-uv run {validateBriefSchemaHelper} {forge_data_folder}/{skill_name}/skill-brief.yaml
+{onCompleteCommand} --result-path={brief_path}
 ```
 
-If validation fails (the writer missed a constraint), surface the error and re-prompt for corrections.
-
-Re-present the 10-line summary (§2 format) with updated values so the user can verify the change.
-
-"Updated brief written. **Select:** [A] Approve and continue · [E] Edit more · [R] Reject"
-
-- `[A]` → emit envelope per §4, chain to {nextStepFile}
-- `[E]` → repeat §5 edit loop
-- `[R]` → §6 ([R]eject path)
-
-### 6. [R]eject Path
+A hook error never fails the run: on a non-zero exit or a process error, display one line, `on_complete hook failed (exit {code}): {first line of its stderr}`, and continue. The envelope is already bound, so it does not carry this line. When `{onCompleteCommand}` is empty, skip the hook.
 
-"**Falling back to interactive brief — fields pre-populated from auto-detection.**"
-
-Hydrate brief context variables from the auto-brief on disk, using the same field mapping as the ratify path in gather-intent §3.1a:
-
-- `name` ← `brief.name`; `version` ← `brief.version`; `target_version` ← `brief.target_version`
-- `target_ref` ← `brief.target_ref`; `source_ref` ← `brief.source_ref` (optional git refs; preserve when present)
-- `source_repo` ← `brief.source_repo`; `source_type` ← `brief.source_type`; `source_authority` ← `brief.source_authority`; `doc_urls` ← `brief.doc_urls`
-- `language` ← `brief.language`; `description` ← `brief.description`; `forge_tier` ← `brief.forge_tier`
-- `created` ← `brief.created`; `created_by` ← `brief.created_by`
-- `scope.type` / `scope.include` / `scope.exclude` / `scope.tier_a_include` / `scope.notes` / `scope.rationale` / `scope.amendments` ← `brief.scope.*` (preserve `tier_a_include` and the `amendments` log verbatim — do not re-derive or drop them)
-- `scripts_intent` ← `brief.scripts_intent`; `assets_intent` ← `brief.assets_intent`
-
-Set `ratify_mode: true` and `ratify_source_path: {forge_data_folder}/{skill_name}/skill-brief.yaml` in workflow context.
-
-Chain to {rejectTargetFile} (confirm-brief.md) — load, read fully, then execute. The user gets the full interactive review experience: view, adjust fields inline, revise scope via [R], or approve via [C] → write-brief.md → health-check.md.
-
-The interactive chain's write-brief.md handles its own envelope emission with `mode: null` (interactive), which is correct since the user explicitly chose to leave auto mode.
-
-### 7. Error Envelope (Canonical)
-
-Every HARD HALT in this step emits the error envelope on stderr:
-
-**Resolve `{emitBriefEnvelopeHelper}`** from `{emitBriefEnvelopeProbeOrder}`; first existing path wins.
+**Remove the run folder.** The brief is written, so the folder step 1 §1 created has done its job; remove it (the guard keeps the command to that folder):
 
 ```bash
-echo '{"status":"error","skill_name":"{skill_name or unknown}","halt_reason":"{reason}","mode":"auto"}' | \
-  uv run {emitBriefEnvelopeHelper} emit --target stderr
+case "{run_dir}" in "{project-root}/_bmad-output/.skf-run/skf-brief-skill-"*) rm -rf "{run_dir}" ;; esac
 ```
 
-### 8. Chain
-
-Load, read fully, then execute the appropriate next step file — only after the user has made their choice and the corresponding action has been taken (envelope emitted or context hydrated):
-- [A]pprove or [E]dit (after final approve): {nextStepFile} (health-check.md)
-- [R]eject: {rejectTargetFile} (confirm-brief.md)
+Chain to {nextStepFile} (health-check.md): load, read fully, then execute. The health check only relays to the shared check: the envelope and the hook of this path run here.

package/src/skf-brief-skill/references/version-resolution.md

@@ -1,6 +1,6 @@
 # Version Resolution
 
-Single source of truth for how brief-skill resolves the `version` field of `skill-brief.yaml`. Loaded by step 2 §4b (auto-detect, fallback path only when the language is not script-supported) and step 5 §3 (resolve & write) so both operate on the same precedence rules and invariant. Step-01 §3b references this file in prose for human-readable rationale but does not load it — that step only collects `target_version` and validates its shape with an inline regex.
+Single source of truth for how brief-skill resolves the `version` field of `skill-brief.yaml`. Loaded by step 2 §4b (auto-detect, fallback path only when the language is not script-supported) and step 5 §3 (resolve & write) so both operate on the same precedence rules and invariant. Step-01 §3b references this file in prose for human-readable rationale but does not load it: that step only collects `target_version` and checks its shape with `skf-validate-brief-inputs.py --only target_version`.
 
 **Aligned with** `assets/skill-brief-schema.md` "Version Detection" section. If you change one, change the other.
 
@@ -13,7 +13,7 @@ For the detected source language, attempt the lookups in order. Stop at the firs
 - **Rust:** `Cargo.toml` `[package] version` (static). If `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`.
 - **Go:** version tag from `go.mod`, or `git describe --tags --abbrev=0`.
 
-For remote GitHub sources, fetch version-bearing files via `gh api repos/{owner}/{repo}/contents/{file}?ref={analysis_ref}` (decode base64) — `{analysis_ref}` is the ref resolved in step 02 §1, defaulting to `HEAD` when no `target_ref`/`target_version` was pinned; reading at the pinned ref keeps the "Detected version" consistent with the version being skilled. For local sources, read the file directly.
+For remote GitHub sources, read version-bearing files from `{run_dir}/files/`, where step 2 stages the files it fetches; fetch one that is not there yet with step 2's fetch helper, naming it: `uv run {githubFetchHelper} --repo "{owner}/{repo}" --ref "{analysis_ref}" --tree-file "{run_dir}/tree.json" --dest "{run_dir}/files" "{file}"`. `{analysis_ref}` is the ref resolved in step 02 §1, defaulting to `HEAD` when no `target_ref`/`target_version` was pinned; reading at the pinned ref keeps the "Detected version" consistent with the version being skilled. For local sources, read the file directly.
 
 If every step fails or returns a non-semver value, the detected version is `null` — the resolver below falls back to `"1.0.0"`.
 
@@ -42,5 +42,6 @@ Step-05 §3 enforces this by setting both fields to the same string when `target
 | Step | Responsibility |
 |------|----------------|
 | 01 §3b | Collect `target_version` (interactive prompt, or headless arg). Do not auto-detect — that is step 02's job. |
+| 02 §1 | Resolve `target_version` to the git tag step 2 reads, through `skf-validate-pins.py`. With no match, analyze `HEAD` and warn. |
 | 02 §4b | Run the detection algorithm regardless of whether `target_version` is set. If `target_version` is set and the detected version differs, surface the disagreement to the user — but the precedence above is unchanged: `target_version` wins. |
 | 05 §3 | Apply the precedence rules and write `version`. If `target_version` is set, also write the `target_version` field with the identical value. Enforce the invariant. |