bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-create-skill/references/load-brief.md

@@ -1,15 +1,19 @@
 ---
-nextStepFile: 'ecosystem-check.md'
+nextStepFile: 'sub/ccc-discover.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 preferencesFile: '{sidecar_path}/preferences.yaml'
-# Resolve `{validateBriefSchemaHelper}` to the first existing path; HALT if
-# neither candidate exists. §3 relies on the helper for deterministic
-# schema-conformance checks (required fields, regex patterns, enum
-# membership, docs-only conditional rules) so this stage does not re-run
-# those checks in prose.
+# Resolve `{validateBriefSchemaHelper}` to the first existing path; HALT
+# (exit code 3, helper-missing) if neither exists. §3 relies on the helper
+# for deterministic schema-conformance checks (required fields, regex
+# patterns, enum membership, docs-only conditional rules) so this stage
+# does not re-run those checks in prose.
 validateBriefSchemaProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
   - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
+# HARD HALT helper (Rules).
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -23,16 +27,35 @@ To load and validate the skill-brief.yaml compilation config, resolve the source
 ## Rules
 
 - Focus only on loading brief, resolving source, and determining tier — do not begin extraction or compilation
-- Do not write any output files — this step only loads and validates
+- Write nothing but the brief's run folder (§0) and the decisions recorded in it: this step loads and validates
+- A HARD HALT emits through `{emitEnvelopeHelper}`, resolved from `{emitEnvelopeProbeOrder}` when it is not bound. After its envelope, under `--batch` it ends only this brief: return to `references/batch-mode.md` §3, even when the halt reads as the end of the run.
 
 ## MANDATORY SEQUENCE
 
+### 0. Start the Run Folder
+
+Every brief gets a run folder of its own: the decisions recorded in it and the staged envelope payloads belong to this brief. Under `--batch`, `references/batch-mode.md` §2 created it and bound `{run_dir}`: go on to the resolver warning below. Otherwise create it:
+
+```bash
+mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-create-skill-XXXXXXXX"
+```
+
+Bind `{run_dir}` ← the path it prints. Step 8 deletes it once the brief finishes; a halted brief keeps it. If it cannot be created, **HARD HALT** (exit code 4, `write-failed`, phase `load-brief`): display "**Create Skill cannot start: the run folder could not be created.** {the first stderr line}" and emit with nothing to stage in, adding `"customization_resolver_unavailable": "<reason>"` to the payload when On Activation step 3 kept one:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --target stderr <<'SKF_JSON'
+{"phase": "load-brief", "halt_reason": "write-failed", "reason": "<that message, one line>", "summary": {"halt_reason": "write-failed", "evidence_report": null}}
+SKF_JSON
+```
+
+**Resolver warning.** Record the reason On Activation step 3 kept, if any, in this brief's sink. Under `--batch`, when `{batch_dir}/resolver-warning.txt` exists (batch-mode.md §1 wrote it), run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{batch_dir}/resolver-warning.txt")"`. Otherwise, when `{customization_resolver_unavailable}` is set, write `customization_resolver_unavailable: {customization_resolver_unavailable}` to `{run_dir}/resolver-warning.txt` with a file write, never `echo` (the reason can hold quotes or `$( )`), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"`.
+
 ### 1. Load Forge Tier
 
 Load `{forgeTierFile}` completely.
 
 **If file does not exist:**
-Halt with: "Forge halted: No forge configuration found. Run [SF] Setup Forge first to detect tools and set your tier."
+**HARD HALT** (exit code 3, `forge-tier-missing`, phase `load-brief`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Forge halted: No forge configuration found. Run [SF] Setup Forge first to detect tools and set your tier."
 
 **If file exists:**
 Extract and report:
@@ -42,12 +65,12 @@ Extract and report:
 
 **Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is one of the exact valid tier values (`Quick`, `Forge`, `Forge+`, `Deep`), use it instead of the detected tier. **If `tier_override` is set but is not one of those four values:** log a warning — "Unknown tier_override `{value}` in preferences.yaml; falling back to detected tier `{detected_tier}`. Valid values: Quick, Forge, Forge+, Deep." — and use the detected tier. Never silently apply an unknown override value, and never map it heuristically to a tier.
 
-**Record the decision:** append an entry to the in-context `headless_decisions[]` buffer (initialize to `[]` at the start of this step if absent) whenever a non-interactive choice is made automatically — both the valid-override path AND the rejected-override path:
+**Record the decision** in the run sink per the Workflow Rules, in every mode, on the valid-override path and on the rejected-override path alike: stage the object as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-create-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`.
 
-- Valid override applied: `{step: "load-brief", gate: "tier-override", decision: "apply", value: "{tier_override}", rationale: "explicit preferences.yaml tier_override", timestamp: {ISO}}`
-- Invalid override rejected: `{step: "load-brief", gate: "tier-override", decision: "reject-invalid", value: "{tier_override}", fallback: "{detected_tier}", rationale: "tier_override not in {Quick,Forge,Forge+,Deep}", timestamp: {ISO}}`
+- Valid override applied: `{"step": "load-brief", "gate": "tier-override", "decision": "apply", "value": "{tier_override}", "rationale": "explicit preferences.yaml tier_override", "timestamp": "{ISO}"}`
+- Invalid override rejected: `{"step": "load-brief", "gate": "tier-override", "decision": "reject-invalid", "value": "{tier_override}", "fallback": "{detected_tier}", "rationale": "tier_override not in Quick, Forge, Forge+, Deep", "timestamp": "{ISO}"}`
 
-These entries stay in the in-context buffer until §3 establishes the on-disk auto-decision sink and seeds it with the buffer-so-far; from then on every later gate's decision is appended to the sink as it lands (per the headless Workflow Rule). Step 5 §7 renders the sink into the evidence-report `## Auto-Decisions` table and step 6 §8 reconciles it, so reviewers can audit every silent choice even on a run long enough to compact the in-context buffer before step 5.
+Step 5 §7 renders the sink into the evidence report's `## Auto-Decisions` table, so reviewers can audit every silent choice.
 
 ### 2. Discover Skill Brief
 
@@ -56,23 +79,26 @@ These entries stay in the in-context buffer until §3 establishes the on-disk au
 - Otherwise, treat it as a skill name and search `{forge_data_folder}/{skill-name}/skill-brief.yaml`
 - If found, load it completely
 
-**If user invoked with --batch flag:**
-- Check `{sidecar_path}/batch-state.yaml` for an active batch checkpoint:
-  - If `batch_active: true`: validate the checkpoint before trusting it — both conditions below must hold:
-    1. `0 <= current_index < len(brief_list)` — the index points inside the recorded list.
-    2. `os.path.exists(brief_list[current_index])` — the brief file is still on disk.
-    If both hold, load the brief at `brief_list[current_index]` (resuming a batch loop from step 8). If **either** check fails, the checkpoint is stale (briefs renamed, moved, or deleted between runs; index off the end after a partial failure). Log a warning — "Stale batch checkpoint — current_index={i}, brief_list length={n}, brief_exists={bool}. Resetting and re-discovering." — then set `batch_active: false` in `batch-state.yaml` and fall through to the no-checkpoint branch below.
-  - If no checkpoint exists or `batch_active` is false: search specified directory for all `skill-brief.yaml` files, list discovered briefs with skill names, store list for batch loop processing, and load the FIRST brief
+**Under `--batch`:** `references/batch-mode.md` §2 handed out this brief as `{brief_path}`, after the validator checked every brief of the batch: load it.
+
+**If no brief path, skill name or `--batch` was given:** list the files that match `{forge_data_folder}/*/skill-brief.yaml`, the brief in each skill's forge folder.
+- **One brief:** load it, and record the pick in the run sink per the Workflow Rules, in every mode: `{"step": "load-brief", "gate": "brief-selection", "decision": "only-brief", "value": "<its path>", "rationale": "no brief named; the only brief in forge_data_folder", "timestamp": "{ISO}"}`. §5's banner names it.
+- **Several briefs:** interactive, list each one by its skill name (its folder's name) and ask "Which brief should I compile?", then load the one the user names. **GATE [default: HALT]**: headless, ask nothing: **HARD HALT** (exit code 2, `brief-missing`, phase `load-brief`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "No brief named, and {N} briefs are in `{forge_data_folder}`: {their skill names}. Pass the brief's path or skill name, or `--batch` to compile them all."
+- **None:** the halt below.
+
+**Bind `{brief_path}`** ← the path of the `skill-brief.yaml` this section loaded: the path given, `{forge_data_folder}/{skill-name}/skill-brief.yaml` for a skill name, the brief the list above gave, or under `--batch` the brief batch-mode.md handed out, never a folder. Later steps hand it to their helpers (`--brief`, `amend --target`).
 
 **If no brief found:**
-Halt with: "No skill brief found. Run [BS] Brief Skill to create one, or use [QS] Quick Skill for brief-less generation."
+**HARD HALT** (exit code 2, `brief-missing`, phase `load-brief`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "No skill brief found. Run [BS] Brief Skill to create one, or use [QS] Quick Skill for brief-less generation."
 
 ### 3. Validate Brief Structure
 
+Resolve `{validateBriefSchemaHelper}` ← first existing path in `{validateBriefSchemaProbeOrder}`. If neither exists, **HARD HALT** (exit code 3, `helper-missing`, phase `load-brief`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Cannot validate the brief: skf-validate-brief-schema.py is missing. Re-install SKF, then re-run create-skill."
+
 Run the deterministic schema validator — it checks required fields, regex patterns (`name`, `version`), enum membership (`source_type`, `source_authority`, `forge_tier`, `scope.type`), type correctness, the docs-only conditional rule (`doc_urls` ≥ 1 when `source_type == "docs-only"`), and the version-non-empty-or-whitespace rule:
 
 ```bash
-uv run {validateBriefSchemaHelper} <path-to-skill-brief.yaml>
+uv run {validateBriefSchemaHelper} "{brief_path}"
 ```
 
 The helper emits:
@@ -87,7 +113,7 @@ The helper emits:
 }
 ```
 
-**If `valid` is false:** HALT and display the first error's `message` field verbatim — the helper already formats messages in the "Brief validation failed: ..." form the user expects. For halt-reasons:
+**If `valid` is false:** **HARD HALT** (exit code 2, `{halt_reason}`, phase `load-brief`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`), with the helper's `halt_reason` and the first error's `message` as the halt message, and display that `message` verbatim: the helper already formats messages in the "Brief validation failed: ..." form the user expects. For halt-reasons:
 
 - `brief-missing` — the brief path doesn't exist. Display the helper's message (it includes the `Run [BS] Brief Skill` redirect).
 - `brief-malformed` — the YAML failed to parse. Display the helper's message.
@@ -95,16 +121,6 @@ The helper emits:
 
 **If `valid` is true:** continue with `brief` (the parsed object) for downstream sections. Surface any `warnings[]` to the user but do not halt.
 
-**Establish the auto-decision sink (durable headless audit).** The brief is now confirmed, so create the on-disk audit sink at `{sidecar_path}/auto-decisions.jsonl` — one compact JSON object per line — and seed it with whatever is already in the in-context `headless_decisions[]` buffer (the §1 tier-override row, or nothing if none fired). This truncates any stale sink a prior brief left behind:
-
-```bash
-: > {sidecar_path}/auto-decisions.jsonl          # truncate / create empty
-# then, for each entry already in headless_decisions[], append its compact JSON:
-printf '%s\n' '{decision-json}' >> {sidecar_path}/auto-decisions.jsonl
-```
-
-From here on, **every time a later gate appends an auto-decision to `headless_decisions[]`, append that same object as a line to this sink the moment it lands** (the on-landing append the headless Workflow Rule mandates). The array is tiny, so the append costs nothing and keeps a complete on-disk copy across the token-heavy step 3→5 extraction window — the point where a long component-library run can compact the in-context buffer. Step 5 §7 renders this sink into the evidence-report `## Auto-Decisions` table and step 6 §8 reconciles it, so the audit table and `auto_decision_count` stay complete even when the buffer is lost.
-
 **Field reference (for human readers):**
 
 The complete contract — required fields, optional fields, types, and rules — lives in `src/shared/scripts/schemas/skill-brief.v1.json` and the prose mirror at `src/skf-brief-skill/assets/skill-brief-schema.md`. Read those if you need to explain a specific field; do not restate the rules here.
@@ -116,7 +132,7 @@ The complete contract — required fields, optional fields, types, and rules —
 **If source_repo is a GitHub URL or owner/repo format:**
 - Verify repository exists via `gh_bridge.list_tree(owner, repo, branch)` — **Tool resolution:** `gh api repos/{owner}/{repo}/git/trees/{branch}?recursive=1` or direct file listing if local; see `knowledge/tool-resolution.md`
 - If branch not specified, detect default branch
-- Store resolved: owner, repo, branch, file tree — note: `source_root` for remote repos is initially set to the remote URL (for detection and API access purposes) and then updated to the local workspace/clone path during step 3 source resolution
+- Store resolved: owner, repo, branch, file tree. Note: `source_root` for remote repos is initially set to the remote URL (for detection and API access purposes), and step 3 source resolution then sets it to the private tree it reads the source into, at Forge tier and above
 - **Version-to-tag pinning intent:** If `brief.target_version` is absent but `brief.version` is present, record the intent to apply **implicit tag resolution** from `brief.version` when step 3 resolves the source. Do not resolve the tag here — tag resolution runs in step 3 alongside the clone. This step only notes the pinning intent so step 3 knows to attempt it. See `references/source-resolution-protocols.md` → "Implicit Tag Resolution".
 
 **If source_repo is a local path:**
@@ -124,7 +140,7 @@ The complete contract — required fields, optional fields, types, and rules —
 - Store resolved: local path as `source_root`, file listing
 
 **If source cannot be resolved:**
-Halt with: "Source not found: `{source_repo}`. Verify the repository exists and is accessible."
+**HARD HALT** (exit code 3, `source-not-found`, phase `load-brief`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Source not found: `{source_repo}`. Verify the repository exists and is accessible."
 
 ### 5. Report Initialization
 
@@ -132,6 +148,7 @@ Display initialization summary:
 
 "**Forge initialized.**
 
+**Brief:** `{brief_path}`
 **Skill:** {name} v{version}
 **Source:** {source_repo} @ {branch}
 **Language:** {language}
@@ -139,12 +156,12 @@ Display initialization summary:
 **Tier:** {tier} — {tier_description}
 **Tools:** {available_tools_list}
 
-Proceeding to ecosystem check..."
+Proceeding to extraction..."
 
 Where tier_description follows positive capability framing:
 - Quick: "Source reading and spec validation"
 - Forge: "AST-backed structural extraction"
-- Forge+: "Semantic-guided precision — ccc pre-ranks files before AST extraction"
+- Forge+: "AST-backed structural extraction plus ccc semantic discovery"
 - Deep: "Full intelligence — structural + contextual + QMD knowledge synthesis"
 
 ### 6. Auto-Proceed

package/src/skf-create-skill/references/relabel-rule.md

@@ -0,0 +1,12 @@
+# Relabel Rule
+
+A provenance entry's labels follow its `extraction_method`, never the reverse. compile.md §4 and validate.md §7 load this file as `{relabelRuleData}` and apply the rule to each `provenance.entries[<i>].*` violation `skf-render-metadata-stats.py` reports, and validate.md §7a takes a node kind from its second part; the one-line Relabel Rule section of `extraction-patterns.md` points any other reader here.
+
+1. **Labels.** Set the entry's `confidence`, `signature_source` and `ast_node_type` to the violation's `expected` value, and where `expected` is `non-null`, record the node kind part 2 gives. Leave a known `extraction_method` as it is. When the violation is on `extraction_method` itself (unknown or missing), set it to the method of the tool that produced the entry, `ast-grep` or `source-read` (so `direct-read` becomes `source-read`), and relabel what the next check reports. When the run cannot tell which tool produced the entry, set `source-read`: T1 needs evidence that an ast-grep rule matched.
+2. **Node kind.** Take the `kind` that the recipe this run's extraction record names for the export (`ast_recipe`) declares in `{extractionPatternsData}` (the ast-grep Patterns table in `extraction-patterns-by-hand.md`, beside it, gives the kind of a `find_code` pattern). When the record names no recipe, or for an entry this run did not extract (one carried over from an earlier map), look the kind up at the entry's `source_file` and `source_line` (the values below are the entry's): from `{project-root}`, run
+
+   ```bash
+   uv run {verifyProvenanceCompletenessHelper} kind-at --source-root "{source_root}" --file "{source_file}" --line {source_line} --name "{export_name}" --recipes "{extractionPatternsData}"
+   ```
+
+   and record the `kind` it prints when `status` is `found`. On any other status (`ambiguous`, `no-match`, `incomplete` or a `skipped-` one), an exit 2, no resolved verifier or no local source tree, never invent a kind: leave that finding in place and list it as a WARN with the reason.

package/src/skf-create-skill/references/report.md

@@ -2,7 +2,8 @@
 nextStepFile: 'health-check.md'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves.
+# path wins. §5 rewrites metadata.json through it only when the emitter is
+# missing; if neither resolves, that write is skipped.
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
@@ -14,13 +15,13 @@ atomicWriteProbeOrder:
 
 ## STEP GOAL:
 
-To display the final compilation summary — skill name, version, source, export count, confidence distribution, tier used, file list, and any warnings — and suggest next steps for the user.
+To display the final compilation summary (skill name, version, source, export count, confidence distribution, tier used, file list and any warnings), suggest next steps, then end the brief: its result contract and `on_complete` call, every brief of a `--batch` run included, and the health check once the run's last brief is done.
 
 ## Rules
 
-- Focus only on reporting compilation results — do not modify any files
+- Write only the brief's result files (through the emitter, §5) and, outside `--batch`, the removal of the brief's run folder. Change no skill artifact, except in §5's fallback when `{emitEnvelopeHelper}` resolved no path: `validation_status` in `{skill_package}/metadata.json` and one warning appended to `{forge_version}/evidence-report.md`
 - Deliver structured report with confidence breakdown
-- Chains to the local health-check step via `{nextStepFile}` after completion (non-batch mode, or after the final batch brief) — the user-facing report is not the terminal step
+- The user-facing report is not the end of the run: §5 and §6 follow it in order, and §6 chains to the health check via `{nextStepFile}`, or under `--batch` back to `references/batch-mode.md`, which runs it once the last brief is recorded
 
 ## MANDATORY SEQUENCE
 
@@ -28,7 +29,7 @@ To display the final compilation summary — skill name, version, source, export
 
 "**Skill forged: {name} v{version} — {export_count} functions, {primary_confidence} confidence.**"
 
-Where `{primary_confidence}` is the predominant confidence tier (T1 if Forge/Deep, T1-low if Quick).
+Where `{primary_confidence}` is the `confidence` label most provenance-map entries carry, counted from the entries' own labels. Never infer it from the forge tier: a Forge or Deep run whose exports were read by eye is T1-low. On a tie, report the weaker label (T1-low over T1), so the headline never overstates confidence.
 
 ### 2. Display Compilation Summary
 
@@ -70,6 +71,8 @@ If there were warnings from extraction, validation, or enrichment, display them:
 - {warning_2}
 - ..."
 
+When step 7's `{promotion}` carried hand-written content (its `manual.blocks` or `manual.files` is not empty), list it first: "Replaced the earlier {existing_generator, or SKF} build of v{version}; kept its [MANUAL] blocks {`manual.blocks`, or none} and files {`manual.files`, or none}." When `manual.missing_blocks` is not empty, add: "[MANUAL] blocks {`manual.missing_blocks`} are not in the new SKILL.md: restore them from `{manual.backup}`." These lines are warnings: show the section when either applies, even with no other warning.
+
 If no warnings, omit this section entirely.
 
 ### 4. Suggest Next Steps
@@ -84,75 +87,41 @@ To use this skill immediately, add the context snippet to your CLAUDE.md:
 {context_snippet_content}
 ```"
 
-### 5. Batch Mode Status (If Applicable)
-
-**If running in --batch mode:**
-
-"**Batch progress:** {completed_count} of {total_count} skills compiled.
+### 5. Result Contract and Post-Completion Hook
 
-{If more remaining:} Proceeding to next brief: {next_skill_name}..."
+Every brief that reaches this step gets its own result contract and `on_complete` call, each brief of a `--batch` run included. A HARD HALT in steps 1 to 7 never reaches this step: it emits its envelope where it fires, as its HALT line says, and writes its result file there once step 7 has created `{forge_version}`.
 
-Update the batch checkpoint in `{sidecar_path}/batch-state.yaml` with:
+**Write the result contract through the emitter.** `{emitEnvelopeHelper}` (SKILL.md On Activation) writes `{forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` and its `create-skill-result-latest.json` copy (a stable path for pipeline consumers; a copy, not a symlink), stamps the timestamp, the run id and the run sink's decisions and warnings into them, checks the brief's `SKF_CREATE_SKILL_RESULT_JSON` line against `skf-create-skill-result-envelope.v1.json` and prints it. First read the run sink, from `{project-root}`:
 
-```yaml
-batch_active: true
-brief_list: [{full list of brief paths}]
-current_index: {index of next brief to process, 0-based}
-completed: [{list of completed skill names}]
-last_updated: {ISO timestamp}
+```bash
+grep -c . "{run_dir}/headless-decisions.jsonl" 2>/dev/null; grep -c '"gate":"zero-exports"' "{run_dir}/headless-decisions.jsonl" 2>/dev/null
 ```
 
-**Before writing:** validate the same two invariants that step 1 re-checks on resume — `0 <= current_index < len(brief_list)` AND `os.path.exists(brief_list[current_index])`. If either fails (e.g., the next brief file was deleted mid-batch, or arithmetic pushed the index off the end), set `batch_active: false` and write `batch_halt_reason: "invalid checkpoint at write time — index or file missing"` instead of the active record. The next run will re-discover rather than resume a broken index.
-
-Then load and execute `references/load-brief.md` for the next brief. Step-01 detects an active batch via `batch-state.yaml` and loads the brief at `current_index` only after re-validating the same invariants (belt and braces — the checkpoint may have been edited between runs).
-
-**If all batch briefs complete:**
-
-Set `batch_active: false` in `{sidecar_path}/batch-state.yaml` to prevent stale state. Display: "Batch complete. {completed_count} skills compiled."
-
-**If not batch mode:**
-
-End workflow. No further steps.
-
-### Result Contract
-
-**If not batch mode (or all batch briefs complete):**
-
-**Resolve the schema reference:** before writing, verify that `{project-root}/src/shared/references/output-contract-schema.md` exists and is readable. Try in order: `{project-root}/src/shared/references/output-contract-schema.md`, then `{project-root}/_bmad/skf/shared/references/output-contract-schema.md` (installed-forge path).
-
-- **If resolved:** write the result contract per the schema — the per-run record at `{forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_version}/create-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include `SKILL.md`, `context-snippet.md`, `metadata.json`, **and `{forge_version}/evidence-report.md`** paths in `outputs` (the evidence report carries the `## Auto-Decisions` audit table where every silent auto-decision is recorded — pipeline consumers follow this path to audit the run) and confidence distribution in `summary`. Also set `summary.auto_decision_count` to the number of decision rows in the reconciled evidence-report `## Auto-Decisions` table (0 when the run was interactive and the section holds only the no-auto-decisions line) so a consumer can tell from the result JSON alone whether any gate auto-resolved. Count the persisted rows — the durable audit record step 6 §8 reconciled from disk — rather than the in-context `headless_decisions[]` length, so the count matches the table even if a long headless run compacted the buffer. Use `python3 {atomicWriteHelper} write --target {forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` (stdin-piped JSON) for the per-run record, then the same helper for the `-latest.json` copy.
-
-- **If neither candidate path resolves:** skip the result-contract write entirely. Append a warning to `evidence-report.md`: "Result contract skipped — `shared/references/output-contract-schema.md` could not be resolved at either candidate path." Then set `validation_status: 'schema-unavailable'` in `metadata.json` (and re-write metadata.json via `skf-atomic-write.py write`). Pipeline consumers will observe the missing `-latest.json` and the metadata flag.
-
-**Post-completion hook (optional).** After the result JSON and `metadata.json` are finalized, if `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it:
+Bind `{auto_decision_count}` ← the first count (0 when the file is missing), the rows of the evidence report's `## Auto-Decisions` table, so a consumer can tell from the result alone whether any gate auto-resolved. Bind `{run_status}` ← `partial` when the second count is above 0 (a headless run went on past zero exports at step 3), else `success`. Take `exports_documented` (`stats.exports_documented`) and `confidence_distribution` from the promoted `metadata.json`. Stage the payload with these values and `{auto_decision_count}` in place of the template's zeros, in both `summary` objects, adding `"warning": "zero-exports"` to both when `{run_status}` is `partial`, and run the emitter:
 
 ```bash
-{onCompleteCommand} --result-path={forge_version}/create-skill-result-latest.json
+cat > "{run_dir}/result-context.json" <<'SKF_JSON'
+{"status": "{run_status}", "phase": null, "halt_reason": null, "error": null, "skill_package": "{skill_package}", "outputs": {"skill_md": "{skill_package}/SKILL.md", "context_snippet": "{skill_package}/context-snippet.md", "metadata": "{skill_package}/metadata.json", "references": "{skill_package}/references", "provenance_map": "{forge_version}/provenance-map.json", "evidence_report": "{forge_version}/evidence-report.md", "extraction_rules": "{forge_version}/extraction-rules.yaml"}, "summary": {"skill_name": "{name}", "version": "{version}", "forge_tier": "{tier}", "exports_documented": 0, "confidence_distribution": {"t1": 0, "t1_low": 0, "t2": 0, "t3": 0}, "auto_decision_count": 0}, "result_contract": {"skill": "skf-create-skill", "status": "{run_status}", "outputs": [{"type": "skill", "path": "{skill_package}/SKILL.md"}, {"type": "skill", "path": "{skill_package}/context-snippet.md"}, {"type": "skill", "path": "{skill_package}/metadata.json"}, {"type": "report", "path": "{forge_version}/evidence-report.md"}], "summary": {"skill_name": "{name}", "version": "{version}", "exports_documented": 0, "confidence_distribution": {"t1": 0, "t1_low": 0, "t2": 0, "t3": 0}, "auto_decision_count": 0}}}
+SKF_JSON
+uv run {emitEnvelopeHelper} emit --workflow skf-create-skill --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
 ```
 
-Log success or failure to `workflow_warnings[]` but never fail the workflow on a hook error — the skill is already written and the result contract is final. The hook runs last so a git-add, registry registration, notifier, or downstream-skill chain sees a complete package. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
-
-### Result Contract on HARD HALT
+The evidence report in `outputs` carries the `## Auto-Decisions` audit table: a pipeline consumer follows its path to audit the run. Display the line the emitter prints. If it exits non-zero, fix `result-context.json` once (its `message` names the problem) and run it again. When it fails again, display its `message`: this brief has no result contract.
 
-The success-variant contract above is only reached at step 8. The ~10 HARD HALT conditions in steps 1–7 (forge-config missing, no brief, brief invalid, source not found, prerequisite failure in load-brief; atomic/detect/auth helper unresolved and the Tier-1 split-count drop in extract/validate; the non-symlink active-link refusal in generate-artifacts) otherwise print a human string and exit with **no machine-readable outcome** — a pipeline polling `create-skill-result-latest.json` cannot distinguish "halted at brief-invalid" from "still running" from "crashed". Mirror skf-quick-skill: **whenever `{headless_mode}` is true, every HARD HALT must surface an error-variant result before exiting.**
+**If `{emitEnvelopeHelper}` resolved no path** (an incomplete install), write no result contract: append "Result contract skipped: skf-emit-result-envelope.py is missing." under `{forge_version}/evidence-report.md`'s `## Remaining Warnings`, and set `validation_status: 'schema-unavailable'` in `{skill_package}/metadata.json`, rewritten through `python3 {atomicWriteHelper} write --target {skill_package}/metadata.json` when `{atomicWriteHelper}` resolves. Pipeline consumers observe the missing `-latest.json` and the metadata flag.
 
-**For every HARD HALT under `{headless_mode}` (regardless of phase)** — emit a single line on **stderr** (one line, no pretty-print; matches the prefix-and-envelope convention used by `skf-emit-result-envelope.py`):
+**Post-completion hook.** When `{onCompleteCommand}` is non-empty (SKILL.md On Activation §3 resolved it from `workflow.on_complete`) and the emitter wrote this brief's result contract (its `emit` exited 0), run it as a shell command from `{project-root}`, for this brief:
 
+```bash
+{onCompleteCommand} --result-path={forge_version}/create-skill-result-latest.json
 ```
-SKF_CREATE_SKILL_RESULT_JSON: {"status":"failed","phase":"<step-slug>","outputs":{},"summary":{"halt_reason":"<short class>","evidence_report":"<path-or-null>"},"skill_package":"<path-or-null>"}
-```
-
-Use `status: "partial"` instead of `"failed"` when artifacts were already staged or promoted before the HALT (i.e. the HALT fired at step 7 generate-artifacts after some files were written); use `"failed"` for HALTs before any artifact exists on disk (steps 1–6).
-
-**Additionally, when `{forge_version}` is resolved** (HALT at step 7 onward, where the staging tree has been promoted) — write the same JSON object (without the `SKF_CREATE_SKILL_RESULT_JSON: ` prefix) to disk at `{forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` and a copy at `{forge_version}/create-skill-result-latest.json` (copy, not symlink) via `python3 {atomicWriteHelper} write`, so consumers that hardcode the `-latest.json` path see a deterministic file even on failed runs. Set `summary.evidence_report` to `{forge_version}/evidence-report.md` whenever that file exists, so the consumer can still reach the `## Auto-Decisions` audit on a failed run. HALTs before step 7 cannot write to disk because `{forge_version}` is only created at step 7 §1; for those, the stderr envelope is the contract and `summary.evidence_report` is `null`.
-
-When `{headless_mode}` is false, HARD HALTs display their human message only — no envelope is emitted.
 
-### 6. Chain to Health Check
+The hook runs after the contract, so a git-add, registry registration or notifier sees a complete package. A hook failure never fails the brief, since the skill is written and its result contract is final: display "on_complete failed for `{name}`: {its exit code and first stderr line}" and go on. When the emitter wrote no result contract for this brief (no `{emitEnvelopeHelper}`, or `emit` failed twice), `--result-path` would name a missing file or an earlier compile's: skip the hook and display "on_complete skipped for `{name}`: no result contract was written ({the reason})". When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
 
-**If not batch mode (or all batch briefs complete):**
+**Remove the run folder.** The brief finished, so outside `--batch` delete `{run_dir}` (`rm -rf "{run_dir}"`); under `--batch`, batch-mode.md §3 reads the staged `result-context.json` there and removes the folder itself. A halted brief keeps its folder, with the decisions it recorded and its staged payloads.
 
-Only after the compilation report, warnings (if any), recommended next steps, and result contract have been handled do you load `{nextStepFile}`, read it fully, and execute it. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+### 6. Chain to the Next Step
 
-**If batch mode with remaining briefs:** Skip the health-check chain — load and execute `references/load-brief.md` for the next brief instead. The health check runs only after the final brief in the batch.
+**Under `--batch`:** go to `references/batch-mode.md` §3, which records this brief from the `result-context.json` §5 staged and hands out the next one. The health check waits for the batch summary.
 
+**Otherwise:** load `{nextStepFile}`, read it fully, and execute it. The health check runs once per run, after the brief's result contract and hook.