bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-refine-architecture/SKILL.md

@@ -1,25 +1,26 @@
 ---
 name: skf-refine-architecture
-description: Improve architecture doc using verified skill data and VS feasibility findings. Use when the user requests to "refine skill architecture" or "improve architecture doc."
+description: Refines an architecture document against generated skills and a Verify Stack report. Use when the user requests to "refine the architecture against generated skills" or "refine an architecture doc with a VS report."
 ---
 
 # Refine Architecture
 
 ## Overview
 
-Takes an original architecture document + generated skills + optional VS feasibility report, and produces a refined architecture with gaps filled, issues flagged, and improvements suggested — all backed by specific API evidence from the generated skills. This workflow enhances the original architecture — it never deletes original content, only adds annotations, subsections, and suggestions.
+Produces a refined architecture document: gaps filled, issues flagged and improvements suggested from the generated skills and an optional VS feasibility report. It never deletes original content, only adds annotations, subsections and suggestions between `<!-- RA:BEGIN ... -->` and `<!-- RA:END -->` marker lines; run again on a refined document, it sets its earlier annotations aside and writes one current set.
 
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
-- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
 - `{skill-name}` resolves to the skill directory's basename.
 
 ## Role
 
-You are an architecture refinement analyst operating in Ferris Architect mode. You bring expertise in API surface analysis, integration gap detection, and evidence-backed architecture improvement, while the user brings their architecture vision and generated skills. Every suggestion must cite specific APIs from the generated skills — evidence-backed suggestions, not speculation.
+You are an architecture refinement analyst in Ferris Architect mode; the user brings the architecture vision and the generated skills.
 
 ## Workflow Rules
 
@@ -27,17 +28,18 @@ These rules apply to every step in this workflow:
 
 - Never speculate — every gap, issue, or improvement must cite specific APIs, types, or function signatures from the generated skills
 - Only load one step file at a time — never preload future steps
-- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
 - Always communicate in `{communication_language}`
 - At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action; a gate that picks its default records that decision in the run sink the moment it decides
+- Every HARD HALT names its exit code, `halt_reason` and phase, and in headless mode prints the envelope the Result Contract below describes
+- Run state lives in `{run_dir}`, not in context; step 6 deletes it when the run finishes, a HALT keeps it
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Initialize & Load Inputs | references/init.md | No (confirm) |
-| 2 | Gap Analysis | references/gap-analysis.md | Yes |
+| 1 | Initialize & Load Inputs | references/init.md | No (input gate) |
+| 2 | Gap Analysis | references/gap-analysis.md | Conditional (confirm a derived scope) |
 | 3 | Issue Detection | references/issue-detection.md | Yes |
 | 4 | Improvements | references/improvements.md | Yes |
 | 5 | Compile Refined Architecture | references/compile.md | No (review) |
@@ -49,36 +51,14 @@ These rules apply to every step in this workflow:
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | architecture_doc_path [required], vs_report_path [optional] |
-| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--architecture-doc <path>` (skip step 1 prompt for the required input); `--vs-report-path <path>` (skip step 1 prompt for the optional VS report); `--scope-skills <names>` (comma-separated in-scope skill names; overrides scope derivation in gap analysis) |
-| **Gates** | step 1: Input Gate [use args] | step 5: Review Gate [C] continue / [X] cancel | step 6: Exit menu [R] review / [X] exit |
-| **Outputs** | `refined-architecture-{arch_project_name}.md` at `{outputFolderPath}` (`{arch_project_name}` = the architecture doc's frontmatter `project_name`, else config `project_name` — resolved in init.md), plus `refine-architecture-result-{timestamp}.json` and `refine-architecture-result-latest.json` |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Per-flag args (`--architecture-doc`, `--vs-report-path`) consumed at the gates that would otherwise prompt. |
-| **Exit codes** | See "Exit Codes" below |
-
-## Exit Codes
-
-Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
-
-| Code | Meaning              | Raised by                                                                                    |
-| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
-| 0    | success              | step 7 (terminal)                                                                           |
-| 2    | input-missing / input-invalid | step 1 §1 (headless missing `architecture-doc` arg, or invalid path) → `input-missing`; non-existent file → `input-invalid` |
-| 3    | resolution-failure   | On-Activation §5 (`output_folder` or `forge_data_folder` unconfigured) |
-| 4    | write-failure        | On-Activation §5 pre-flight write probe; step 1 §3c (RA state file write failed); step 5 §6 (refined-architecture write failed); step 6 §3 (result-contract write failed) |
-| 5    | state-conflict       | step 1 §3 (no skills found — refinement requires ≥1 skill) |
-| 6    | user-cancelled       | step 1 §1 prompt cancelled; any prompt that accepted `cancel`/`exit`/`:q`; step 5 review gate `[X]` |
-| 7    | inventory-unreliable | step 1 §2 (>20% skill-inventory warnings exceed budget) |
-| 8    | recovery-failed      | step 5 §1 (durability state insufficient to reconstruct Step 02-04 findings); step 6 §1 (`## Refinement Summary` absent from the compiled document) |
+| **Flags** | `--headless` / `-H`; `--architecture-doc <path>` and `--vs-report-path <path>` answer the step 1 prompts (`--vs-report-path none` refines without a report and skips the search for one); `--scope-skills <names>` (comma-separated skill names that replace the derived scope, so step 2 asks no scope confirmation) |
+| **Gates** | step 1: Input Gate [use args] | step 2: Scope Confirm Gate [C] continue / [X] cancel (only when a derived scope drops skills or keeps an ambiguous one) | step 5: Review Gate [R] review each refinement / [C] approve and replace the refined document / [X] cancel |
+| **Outputs** | `refined-architecture-{arch_project_name}.md` at `{outputFolderPath}` (the document's frontmatter `project_name`, else config's), promoted from a draft once the step 5 review approves it; an earlier one is first renamed to `refined-architecture-{arch_project_name}-{timestamp}.md`. Also `refine-architecture-result-{YYYYMMDD-HHmmss}.json`, its `-latest.json` copy and, once an approved review drops a finding, `.ra-dismissed-{arch_project_name}.json` |
+| **Headless** | Every gate takes its default when `{headless_mode}` is true: `--scope-skills` skips the step 2 scope confirmation, and without `--vs-report-path` step 1 uses the [VS] report it finds. |
 
 ## Result Contract (Headless)
 
-When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
-
-```
-SKF_REFINE_ARCHITECTURE_RESULT_JSON: {"status":"success|error","refined_path":"…|null","gap_count":0,"issue_count":0,"improvement_count":0,"exit_code":0,"halt_reason":null}
-```
-
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"insufficient-skills"`, `"output-folder-unconfigured"`, `"forge-folder-unconfigured"`, `"inventory-unreliable"`, `"write-failed"`, `"recovery-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
+When `{headless_mode}` is true, step 6 prints one `SKF_REFINE_ARCHITECTURE_RESULT_JSON: {...}` line on **stdout**, and every HARD HALT one on **stderr**, built by the shared emitter: `references/exit-codes.md` gives its fields, the `halt_reason` values and the halt command.
 
 ## On Activation
 
@@ -87,40 +67,42 @@ SKF_REFINE_ARCHITECTURE_RESULT_JSON: {"status":"success|error","refined_path":"
    - `skills_output_folder`, `forge_data_folder`, `output_folder`, `sidecar_path`
 
 2. **Compute run-scoped variables:**
-   - `timestamp` ← UTC `YYYYMMDD-HHmmss` captured at activation time. Fixed for the entire workflow run; report.md reuses this when writing the result contract.
+   - `timestamp` ← the output of `date -u +%Y%m%d-%H%M%S`, run once now: it names the run folder and the copy an earlier refined document is renamed to.
+   - `run_dir` ← `{project-root}/_bmad-output/.skf-run/skf-refine-architecture-{timestamp}`, the run folder §5 creates
 
 3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
 4. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-refine-architecture.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` for §5 to record.
 
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+   Bind each path scalar, taking the bundled default when the merged value is empty or absent:
 
-   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+   - `{refinementRulesPath}` ← `workflow.refinement_rules_path` if non-empty, else `references/refinement-rules.md` (house style only: the file's first section names what a copy can change)
+   - `{outputFolderPath}` ← `workflow.output_folder_path` if non-empty, else `{output_folder}`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty
 
-   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
+   Then run `workflow.activation_steps_prepend` now, treat `workflow.persistent_facts` as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off), then run `workflow.activation_steps_append` once §5's pre-flight has passed, before §6 loads the first stage.
 
-   - `{refinementRulesPath}` ← `workflow.refinement_rules_path` if non-empty, else `references/refinement-rules.md`
-   - `{outputFolderPath}` ← `workflow.output_folder_path` if non-empty, else `{output_folder}`
-   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — report.md skips the hook invocation entirely)
+5. **Pre-flight: the emitter, config, write probe and run folder.** In that order, so every halt can print its envelope and an empty path halts as missing config (exit 3), not as a write failure.
 
-   Stash all three as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+   **The emitter.** Resolve `{emitEnvelopeHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py`, else `{project-root}/src/shared/scripts/skf-emit-result-envelope.py` (the first that exists). If neither exists, HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `on-activation:emitter` and display only: "Refine Architecture cannot run without `skf-emit-result-envelope.py`, which is not installed. Re-install SKF."
 
-   Also apply the array surfaces (not silent no-ops): run `workflow.activation_steps_prepend` now, treat `workflow.persistent_facts` as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts), then run `workflow.activation_steps_append` after activation.
+   The halts below come before the run folder, so in headless mode each passes its payload on stdin, with `"customization_resolver_unavailable": "<reason>"` added when step 4 kept one:
 
-5. **Pre-flight config + write probe.** Assert both output paths are configured, then probe writability — order matters: an empty path makes `mkdir -p ""` fail, which would misreport a *missing config* (exit 3) as a *write failure* (exit 4) and collapse the distinction the Result Contract draws.
+   ```bash
+   uv run {emitEnvelopeHelper} emit-halt --workflow skf-refine-architecture --target stderr <<'SKF_RA_HALT'
+   {"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>"}
+   SKF_RA_HALT
+   ```
 
-   **Config-completeness (exit 3).** If `{outputFolderPath}` is empty: HALT (exit code 3, `halt_reason: "output-folder-unconfigured"`) — "`output_folder` is not configured in config.yaml. Add an `output_folder` path and re-run [RA]." If `{forge_data_folder}` is empty: HALT (exit code 3, `halt_reason: "forge-folder-unconfigured"`) — "`forge_data_folder` is not configured in config.yaml. Add a `forge_data_folder` path and re-run [RA]."
+   **Config-completeness (exit 3).** If `{outputFolderPath}` is empty: HALT (exit code 3, `halt_reason: "output-folder-unconfigured"`) at phase `on-activation:config`: "Set `output_folder` in config.yaml, then re-run [RA]." If `{forge_data_folder}` is empty: HALT (exit code 3, `halt_reason: "forge-folder-unconfigured"`) at phase `on-activation:config`: "Set `forge_data_folder` in config.yaml, then re-run [RA]."
 
-   **Write probe (exit 4).** With both paths now non-empty, verify each is writable — a read-only mount, full disk, or permissions-denied path otherwise only surfaces at init.md §3c's RA state file write, by which point the user has already gone through input prompts:
+   **Write probe (exit 4).** Check that both paths are writable before any prompt:
 
    ```bash
    for dir in "{outputFolderPath}" "{forge_data_folder}"; do
@@ -130,6 +112,14 @@ SKF_REFINE_ARCHITECTURE_RESULT_JSON: {"status":"success|error","refined_path":"
    done
    ```
 
-   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, every HALT above emits the error envelope per **Result Contract (Headless)** with `refined_path: null`.
+   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`) at phase `on-activation:write-probe`, with `"path"` set to the folder that failed.
+
+   **Run folder (exit 4).** Create the run folder:
+
+   ```bash
+   mkdir -p "{project-root}/_bmad-output/.skf-run" && mkdir "{run_dir}"
+   ```
+
+   If the command fails, HALT (exit code 4, `halt_reason: "write-failed"`) at phase `on-activation:run-folder`: "Cannot create the run folder `{run_dir}`: {the first stderr line}." Once it exists and `{customization_resolver_unavailable}` is set, record the reason in the run sink: write `customization_resolver_unavailable: {customization_resolver_unavailable}` to `{run_dir}/resolver-warning.txt` with a file write, never `echo`, then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"`.
 
 6. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-refine-architecture/customize.toml

@@ -1,8 +1,11 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-refine-architecture.
-# Team overrides:     _bmad/custom/skf-refine-architecture.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-refine-architecture.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-refine-architecture.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-refine-architecture.user.toml
+# The overrides apply only when BMad core's customization resolver runs;
+# otherwise the run warns `customization_resolver_unavailable` and uses the
+# defaults in this file.
 
 [workflow]
 
@@ -10,27 +13,34 @@
 #   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
 #   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
 
-# Steps to run before the standard activation (uv probe, config load).
-# Overrides append. Use for org-wide pre-flight checks (auth, network,
-# compliance) that must precede architecture refinement work.
+# Steps to run during activation, after the config load and the headless
+# check and before the pre-flight (the emitter, the configured folders, the
+# write probe and the run folder). Overrides append. Use for org-wide checks
+# (auth, network, compliance) that must precede architecture refinement work.
 
 activation_steps_prepend = []
 
-# Steps to run after activation but before the first stage executes.
-# Overrides append. Use for context loads or banner customization that
-# should run once activation completes successfully.
+# Steps to run once the pre-flight has passed, before step 1 loads the
+# inputs. Overrides append. Use for context loads or banner customization
+# that should run once activation completes successfully.
 
 activation_steps_append = []
 
 # Persistent facts the workflow keeps in mind for the whole run
-# (refinement standards, evidence-citation rules, house-style preservation
-# guardrails). Overrides append.
+# (refinement standards, evidence-citation rules). Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "Refinements must cite specific API signatures, never speculate."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/refine-policy.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-refine-architecture.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
@@ -38,21 +48,40 @@ persistent_facts = [
 
 # --- Optional asset overrides ---
 #
-# Lift the canonical refinement-rules path so orgs can substitute house-style
-# rules (e.g. add domain-specific gap categories) without forking the skill.
-# Empty string = use the bundled default.
+# House-style refinement rules. Empty = the bundled
+# references/refinement-rules.md. A copy replaces that whole file, so start
+# it from the bundled one: it can add, rename, drop or redefine the gap,
+# issue and improvement types, name its own severity and value tiers, and
+# decide which tier each [VS] verdict raises. It keeps the six tables the
+# steps read by name, and each tier becomes a {<tier>_count} of the
+# Refinement Summary, so step 1 halts on a copy that lacks a table or whose
+# tiers break these rules: a tier name starts with a letter and holds only
+# the letters A to Z, digits and spaces; no two tiers share a name (ignoring
+# case), severity and value tiers included; none is named gap, issue,
+# improvement, unverified or skill; and each VS Report Integration row
+# raises a tier of Issue Severity, or no issue, not both (bold the one it
+# raises). Fixed whatever the copy says: what each step looks for, which
+# skills and pairs are analyzed (the document scope), how findings are
+# stored for recovery (references/finding-storage.md), and how the refined
+# document is built, marked and checked (headings, callouts, RA markers,
+# preservation).
 
 refinement_rules_path = ""
 
-# Override the destination directory for the refined architecture document.
-# Empty = use {output_folder} from config.yaml. Useful for orgs that want
+# Override the destination directory for the refined architecture document
+# and the files beside it: the earlier refined document a promotion renames,
+# the result files (refine-architecture-result-<YYYYMMDD-HHmmss>.json and its
+# -latest.json copy, the stable path pipelines read) and the record of
+# findings a review dropped (.ra-dismissed-<project>.json). Empty = use
+# {output_folder} from config.yaml. Useful for orgs that want
 # refined-architecture artifacts to land under a curated docs tree.
 
 output_folder_path = ""
 
-# Optional post-completion hook. When non-empty, invoked with
-# `--result-path=<path>` after the refined architecture and result JSON are
-# finalized (step 6). Use to index the refined doc, notify, or chain the next
-# workflow. Failures are logged to workflow_warnings[] but never fail the run.
+# Optional post-completion hook: a shell command. When non-empty, step 6 runs
+# it with `--result-path=<path>` (the per-run result JSON) once the refined
+# architecture is promoted and both result files are written, before the run
+# finishes. Use to index the refined doc, notify, or chain the next workflow.
+# A failure shows as a warning line in step 6's report but never fails the run.
 
 on_complete = ""

package/src/skf-refine-architecture/references/compile.md

@@ -1,7 +1,21 @@
 ---
 nextStepFile: 'report.md'
-# {arch_project_name} resolved in init.md (arch-doc frontmatter project_name, else config project_name).
+refinementRulesData: '{refinementRulesPath}'
 outputFile: '{outputFolderPath}/refined-architecture-{arch_project_name}.md'
+draftFile: '{forge_data_folder}/.skf-ra-draft-{project_name}.md'
+planFile: '{run_dir}/insertion-plan.json'
+applyResult: '{run_dir}/apply.json'
+promoteResult: '{run_dir}/promote.json'
+preservationScript: 'scripts/skf-check-preservation.py'
+# The findings a review dropped (findingStorageData says how §8 records them).
+dismissedFile: '{outputFolderPath}/.ra-dismissed-{arch_project_name}.json'
+findingStorageData: 'references/finding-storage.md'
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+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}. Compile the refined architecture document in {document_output_language}. -->
@@ -10,31 +24,39 @@ outputFile: '{outputFolderPath}/refined-architecture-{arch_project_name}.md'
 
 ## STEP GOAL:
 
-Produce the refined architecture document by starting with the original as a base, adding gap-fill subsections, issue callout blocks, and improvement suggestions. Append a Refinement Summary. Present for user review before finalizing.
+Stage every finding of Steps 02-04 as an entry of an insertion plan, let the preservation script build the refined document from it as a draft, and present the draft for review; only the review's [C] replaces `{outputFile}`.
 
 ## Rules
 
-- Do not discover new gaps, issues, or improvements — use only what Steps 02-04 produced
-- Do not delete, reword, or rearrange original architecture content
-- Present compiled document for user review (gate checkpoint)
+- Do not discover new gaps, issues, or improvements: use only what Steps 02-04 produced
+- Never write the refined document yourself and never retype the original: `{preservationScript}` copies it, places the plan's blocks, checks that every original line survived and writes the draft
 
 ## MANDATORY SEQUENCE
 
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. In headless mode, stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>"}`, adding `"path"` when the halt names one, resolve `{emitEnvelopeHelper}` from `{emitEnvelopeProbeOrder}` if it is not bound (first existing path wins), then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-refine-architecture --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+Display the line it prints, then stop with the halt's exit code (`references/exit-codes.md` describes the envelope). If no candidate exists, or the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
+
 ### 1. Prepare the Original as Base
 
-Load the complete original architecture document.
+The base is `{architecture_doc}` with any earlier Refine Architecture pass set aside, as Step 01 §1b set it aside in `{analysis_doc}`. §6's script reads `{architecture_doc}` itself; read `{analysis_doc}` only to pick each finding's anchor.
 
-This is the base. Every line of the original appears in the refined document unmodified — the workflow only adds annotations and subsections; dropping or rewording original content silently discards the user's architecture.
+**Context recovery check:** read what is no longer in context from the RA state file: `{run_dir}`, `{timestamp}`, `{architecture_doc}` and `{arch_project_name}` from the `<!-- [RA-RUN] -->` block of `{forge_data_folder}/ra-state-{project_name}.md` (`{analysis_doc}` is `{run_dir}/analysis-doc.md`); the findings of Steps 02-04 from its `<!-- [RA-GAPS] -->`, `<!-- [RA-ISSUES] -->` and `<!-- [RA-IMPROVEMENTS] -->` blocks, and from `<!-- [RA-DISMISSED] -->` when there is one; `{unverified_technologies}` (Step 02 §2b), which the plan (§6) needs: the `<!-- [RA-SCOPE] -->` block; `{vs_report}`, which the VS Coverage row (§5) needs: the `<!-- [RA-VS] -->` block (its `path`, `generatedAt`, `coveragePercentage` and `coverageMeasured`, or `none`). When a block is still missing, or a findings block holds only summary counts, HALT (exit code 8, `halt_reason: "recovery-failed"`) at phase `compile:recovery`: "⚠️ Context for the [Gaps|Issues|Improvements|Scope|VS report] analysis was lost and the state file cannot rebuild it. Re-run [RA] from the beginning: step 01 resets the state file and steps 02-04 rebuild every finding."
 
-**Context recovery check:** If gap, issue, or improvement findings from Steps 02-04 are not available in context (e.g., due to context degradation in long runs), attempt to read the durability state from `{forge_data_folder}/ra-state-{project_name}.md`. Parse the `<!-- [RA-GAPS] -->`, `<!-- [RA-ISSUES] -->`, and `<!-- [RA-IMPROVEMENTS] -->` comment blocks to recover the complete formatted findings (each block contains full citation text with evidence, not just counts). If a section is still missing or contains only summary counts after recovery, HALT (exit code 8, `halt_reason: "recovery-failed"`): "⚠️ Context for the [Gaps|Issues|Improvements] analysis was lost and the durability state is insufficient to reconstruct findings. Re-run [RA] from the beginning — step 01 will reset the state file, then steps 02-04 will rebuild all findings." In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `refined_path: null`.
+### 2. Plan the Gap-Fill Subsections
 
-### 2. Insert Gap-Fill Subsections
+The insertion plan is one JSON object, written to `{planFile}` at §6 (the script's module docstring gives every field). Each finding becomes one entry of its `entries` list: an `id` (`gap-1`, `issue-1`, `improvement-1` and so on), its `kind` (`gap`, `issue` or `improvement`), the `anchor` that places it, the `skills` its evidence cites, and the `block` to insert. A finding stored under `[RA-DISMISSED]` gets no entry: §7 lists it, and §8 gives it one only when the user takes it back.
 
-For each gap finding from Step 02:
+**Anchors.** An anchor is text copied exactly from one line of `{analysis_doc}`: a heading line such as `## Data Layer`, or the sentence a finding is about. It must occur on exactly one line (a heading anchor matches only a heading of its level and title); when several lines hold it, add `occurrence` (1-based) to pick one. An anchor of `null` sends the entry to its kind's fallback section at the end of the document.
 
-**Locate the most relevant section** in the original architecture where this integration would logically belong.
+For each gap finding from Step 02:
 
-**Insert a gap-fill subsection** one heading level deeper than the parent section:
+- **anchor:** the heading of the section where this integration logically belongs. The script puts the block at the end of that section, one heading level deeper. `null` when no section fits: the script then collects the gap under `## RA: Additional Integration Paths`.
+- **block** (the script sets the heading's level, so any number of `#` will do):
 
 ```markdown
 #### RA: {Library A} <-> {Library B} Integration Path
@@ -48,15 +70,12 @@ For each gap finding from Step 02:
 {Suggested architecture content describing how the libraries connect}
 ```
 
-If no clear parent section exists, collect orphan gaps into a new section: "## RA: Additional Integration Paths"
+### 3. Plan the Issue Annotations
 
-### 3. Insert Issue Annotations
+For each issue finding from Step 03, with `tier` its severity, a tier of the Issue Severity table of `{refinementRulesData}`:
 
-For each issue finding from Step 03:
-
-**Locate the section** containing the contradicted claim.
-
-**Insert an issue callout block** immediately after the contradicted text:
+- **anchor:** the contradicted claim, exactly as Step 03 recorded it from its line of `{analysis_doc}`. The script puts the callout right after the block (paragraph, list, table, blockquote or code fence) that holds the claim. `null` when the claim cannot be located precisely: the script collects such issues under `## RA: Additional Issues Detected`, the most severe tier first.
+- **block:**
 
 ```markdown
 > [!WARNING] **Issue Detected by Refine Architecture** ({severity})
@@ -67,18 +86,15 @@ For each issue finding from Step 03:
 > **Suggested Correction:** {specific correction with API evidence}
 ```
 
-**Placement priority:** Place each issue callout immediately after the contradicted text in its original location. If the contradicted claim is inside a Markdown list item, code block, or table row where inserting a callout block would break syntax, place the callout immediately after the enclosing block instead. If the contradicted claim cannot be precisely located, collect into "## RA: Additional Issues Detected" at the end of the document, ordered by severity (Critical first, then Major, then Minor).
-
-### 4. Insert Improvement Suggestions
+### 4. Plan the Improvement Suggestions
 
-For each improvement finding from Step 04:
+For each in-scope improvement finding from Step 04 (the `[RA-IMPROVEMENTS]` findings; out-of-scope improvements and synergies stay under `[RA-OUT-OF-SCOPE]` and never enter the refined document), with `tier` its value, a tier of the Improvement Value table of `{refinementRulesData}`:
 
-**Locate the section** where the library is discussed.
-
-**Insert an improvement subsection** one heading level deeper:
+- **anchor:** the heading of the section where the library is discussed, also when it appears there only in a table, code block or Mermaid diagram: the script puts the block at the end of that section, one heading level deeper. `null` when no section discusses the library: the script then collects the improvement under `## RA: Additional Improvements Suggested`, the most valuable tier first.
+- **block:**
 
 ```markdown
-#### RA: Enhancement — {Improvement Title}
+#### RA: Enhancement: {Improvement Title}
 
 > [!TIP] **Improvement Suggested by Refine Architecture** ({value} value)
 > {skill_name} provides `{api}` which is not currently leveraged.
@@ -89,63 +105,90 @@ For each improvement finding from Step 04:
 {Specific suggestion for updating the architecture}
 ```
 
-**Order by value:** High value improvements first, then Medium, then Low.
-
-**Placement fallback:** If the library's only architecture mention is inside a table, code block, or Mermaid diagram where inserting a subsection would break syntax, collect into `## RA: Additional Improvements Suggested` at the end of the document.
-
 ### 5. Add Refinement Summary Section
 
-Append a `## Refinement Summary` section containing:
+The plan's `summary` is the `## Refinement Summary` section, which the script appends last. Leave the count placeholders below as they are: the script fills `{gap_count}`, `{issue_count}`, `{improvement_count}`, a `{<tier>_count}` for each severity and value tier and `{evidence_rows}` from the plan's entries, `{unverified_count}` and `{unverified_technologies}` from its `unverified_technologies`, and `{skill_count}`, and it refuses a summary that types the three totals or holds a placeholder it does not know. Fill the others yourself. The section contains:
 
 - **Header:** "Produced by: Refine Architecture workflow using {skill_count} skills" and date
-- **Changes Made table** with the following rows:
+- **Changes Made table**, whose Issues Flagged and Improvements Suggested breakdowns name each tier of `{rule_tiers}` (its `issue`, then its `improvement` list) in order, each as `<Tier>: {<tier>_count}`; the rows below show the bundled tiers:
 
 | Category | Count | Breakdown |
 |----------|-------|-----------|
-| Gaps Filled | {gap_count} | — |
+| Gaps Filled | {gap_count} | - |
 | Issues Flagged | {issue_count} | Critical: {critical_count}, Major: {major_count}, Minor: {minor_count} |
 | Improvements Suggested | {improvement_count} | High: {high_count}, Medium: {medium_count}, Low: {low_count} |
-| Skills Used as Evidence | {skill_count} | — |
-- **Evidence Sources table:** Each skill name and how many refinements cite it
-- **Next Steps:** Review `[!WARNING]` issues, `[!NOTE]` gaps, `[!TIP]` improvements; then run **[SS] Stack Skill** to compose your individual skills into a unified stack skill, providing this refined architecture doc when prompted
+| Skills Used as Evidence | {skill_count} | - |
+| Not verified (no skill) | {unverified_count} | {unverified_technologies} |
+| VS Coverage | {vs_coverage} | technologies with a skill when [VS] ran, from `{vs_report_name}` |
+
+The Not verified (no skill) row is always written: its Breakdown names the technologies comma-separated, or reads `none`. Write the VS Coverage row only when a VS report was used (`vs_report_available` is true), from the report JSON Step 01 §1 cached (`{vs_report}`), never from the report file: `{vs_coverage}` is its `coveragePercentage` followed by `%` when its `coverageMeasured` is true, and `not recorded` when `coverageMeasured` is false. `{vs_report_name}` is the file name of the JSON's `path`: the refined document is shared, so it names no folder.
+
+- **Evidence Sources table:** a `| Skill | Refinements |` header row and its separator, then `{evidence_rows}` (the script writes one row per cited skill)
+- **Next Steps:** Review `[!WARNING]` issues, `[!NOTE]` gaps, `[!TIP]` improvements; then run **[SS] Stack Skill** to compose your individual skills into a unified stack skill, providing this refined architecture doc when prompted. When `{unverified_technologies}` is not empty, add one line before [SS] that names them: nothing checked what the architecture says about them, so generate their skills with **[CS] Create Skill** or **[QS] Quick Skill** and re-run **[RA]** first.
 
-### 6. Write the Refined Document
+### 6. Build the Draft
+
+Write the plan to `{planFile}`: the `entries` of §2 to §4, the `summary` of §5, `unverified_technologies` (Step 02 §2b's list as written in the document, `[]` when it is empty), `skill_count` (the inventory's `{skill_count}`, Step 01 §2) and `tiers` (`{"issue": [...], "improvement": [...]}`: `{rule_tiers}`, the `tiers` Step 01 §4's `rules` check printed; run that command again if they are no longer in context). Then run:
+
+```bash
+uv run {preservationScript} apply --original "{architecture_doc}" --plan "{planFile}" --draft "{draftFile}" -o "{applyResult}"
+```
 
-Write the complete refined architecture to `{outputFile}`.
+Branch on its exit code:
 
-On any write failure (read-only mount, disk full, permissions denied): HALT (exit code 4, `halt_reason: "write-failed"`) with the captured error. In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `refined_path: null`. The On-Activation §5 write probe should have caught an unwritable output folder earlier — if it surfaces here, the filesystem state changed mid-workflow.
+- **0:** the draft is written and the check passed. `{applyResult}` holds its `counts`, `evidence`, filled `summary`, `unverified_technologies` and `set_aside` (the earlier pass's blocks), where §7 and Step 06 take every number and name.
+- **1 with `status: "problems"`:** nothing was written. Each entry of `problems[]` names the plan entry (`id`), the `reason` and what to change (an anchor's `closest` line or its `matches`, of which `occurrence` can pick one). Fix the plan and run the command again; an anchor still not found after one fix becomes `null`.
+- **1 with `status: "not-preserved"`:** the draft would lose or change a line of the original, so nothing was written (an earlier draft stays as it was), and running the same plan again gives the same result. Show the first entry of `missing[]` and of `altered[]`. In headless, HALT (exit code 4, `halt_reason: "preservation-failed"`) at phase `compile:draft` without a retry, naming that first line; in an interactive run, show the failure at §7 and offer no [C] until a feedback round's `apply` passes.
+- **2** with a JSON (`error` names the file it could not read): for `{planFile}`, write the plan again; for `{architecture_doc}`, HALT (exit code 2, `halt_reason: "input-invalid"`) at phase `compile:draft`, with `"path"` set to it. **2 with no JSON:** a malformed call: fix it and run it again.
+- **3:** the draft could not be written: HALT (exit code 4, `halt_reason: "write-failed"`) at phase `compile:draft`, naming its `error`, with `"path": "{draftFile}"`.
+- If `uv` cannot start the script, here or for §8's `promote`: HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `compile:draft` (`compile:promote` for `promote`).
 
-### 7. Present Compiled Document for Review
+`{outputFile}` is not touched here: an earlier refined document stays as it is until §8's [C].
+
+### 7. Present the Draft for Review
 
 "**Refined architecture compiled. Please review:**
 
 ---
 
-{Display the Refinement Summary section only — not the full document}
+{Display the `summary` of `{applyResult}`: the Refinement Summary as the draft holds it}
 
 ---
 
-**The full refined document has been written to:** `{outputFile}`
+{IF the `[RA-DISMISSED]` block holds findings:}**Left out, as a review dropped them from an earlier refinement of this document.** Ask for one back to insert it:
+{One line per finding: its kind, its skills, its own title and the title of the record it matched}
+
+**The draft is at:** `{draftFile}`. {IF `{outputFile}` exists: `{outputFile}` still holds your earlier refined document; approving renames it with this run's timestamp before the draft takes its place.}{ELSE: Approving writes it to `{outputFile}`.} Ask for changes here rather than editing the draft: each feedback round rebuilds it.
 
-Please review the refinements:
-- {gap_count} gap-fill subsections added
-- {issue_count} issue annotations inserted
-- {improvement_count} improvement suggestions included
-- Original architecture content preserved in full
+- {IF the last `apply` failed the check:}The draft would lose or change line {the first `missing[]` or `altered[]` line} of the original: [C] waits for a draft that passes{ELSE IF its `set_aside` holds a `legacy` entry:}Every original line is preserved except lines {ranges} of `{architecture_doc}` (each `legacy` entry's `start`-`end`), which an earlier pass left without RA markers: they were set aside unchecked, so text of your own there is not in the draft{ELSE:}Original architecture content preserved in full: the preservation script found every line unchanged{END IF}
+{IF previous_pass:}- The earlier Refine Architecture pass in this document was set aside, and these refinements replace it
 
-**Does the refinement look correct?**"
+**Does the refinement look correct?** Choose [R] to walk through each refinement with its evidence, or tell me what to change, such as a finding to drop."
 
 ### 8. Present MENU OPTIONS
 
-Display: **Select:** [C] Continue to Final Report | [X] Cancel
+Display: **Select:** [R] Review each refinement | [C] Approve and replace the refined document | [X] Cancel
 
 #### GATE [default: C]
 
-This is a review gate: halt for the user's decision and do not chain onward until they approve — an unreviewed compile ships un-vetted refinements. Headless auto-selects [C] (log: "headless: auto-approve compiled architecture").
+Wait for the user's choice. Headless auto-selects [C] (log: "headless: auto-approve compiled architecture") and records that decision in the run sink the moment it is taken: stage `{run_dir}/decision.json` as `{"gate": "compile.review", "default_action": "C", "taken_action": "C", "reason": "headless: auto-approve compiled architecture", "evidence": {"draft": "{draftFile}", "output": "{outputFile}"}}`, then run:
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-refine-architecture --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
 
 #### Menu Handling Logic:
 
-- IF C: Load, read entire file, then execute {nextStepFile}
-- IF cancel / exit / [X] / q / :q: HALT (exit code 6, `halt_reason: "user-cancelled"`) — display "Cancelled — refinement not finalized." In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `refined_path: null`. These global cancel tokens pre-empt the feedback branch below.
-- IF Any other: Process as feedback, adjust specific refinements in the document, rewrite {outputFile}, redisplay preview, then [Redisplay Menu Options](#8-present-menu-options)
+- IF R: walk through each refinement with its evidence and its plan `id`, so feedback can name it: the gaps, the issues by severity, the improvements by value, then the findings left out as previously dismissed. It changes nothing; then redisplay this menu.
+- IF C (only while the last `apply` exited 0): promote the draft. The script checks it once more, renames a file already at `{outputFile}` to `refined-architecture-{arch_project_name}-{timestamp}.md` (or a free `-2` name), and moves the draft there:
+
+  ```bash
+  uv run {preservationScript} promote --original "{architecture_doc}" --draft "{draftFile}" --output "{outputFile}" --timestamp "{timestamp}" -o "{promoteResult}"
+  ```
 
+  - **0:** the draft is now `{outputFile}`, and `{promoteResult}` records `previous`, the name the earlier refined document took (null when there was none). When a feedback round staged `{run_dir}/dismissed.json`, only now write it to `{dismissedFile}`, as `{findingStorageData}` says. Then load, read the entire file, and execute `{nextStepFile}`.
+  - **1** (`not-preserved`): nothing was moved. Show the first entry of `missing[]` or `altered[]`, rebuild once with §6's `apply`, and promote again. If it fails the same way, HALT (exit code 4, `halt_reason: "preservation-failed"`) at phase `compile:promote`, naming that line: the draft stays at `{draftFile}` and `{outputFile}` is as it was.
+  - **2** with a JSON (`error` names the file it could not read): for the draft, rebuild it once and promote again, and if it still cannot be read, HALT (exit code 4, `halt_reason: "write-failed"`) at phase `compile:promote`, with `"path": "{draftFile}"`; for `{architecture_doc}`, HALT (exit code 2, `halt_reason: "input-invalid"`) at phase `compile:promote`, with `"path"` set to it. **2 with no JSON:** fix the malformed call and run it again.
+  - **3:** HALT (exit code 4, `halt_reason: "write-failed"`) at phase `compile:promote`, naming its `error`, with `"path": "{outputFile}"`. `{outputFile}` is as it was unless the `error` names a file the script could not put back.
+- IF cancel / exit / [X] / q / :q: delete the draft (`rm -f "{draftFile}"`), display "Cancelled: refinement not finalized. `{outputFile}` is unchanged." and HALT (exit code 6, `halt_reason: "user-cancelled"`) at phase `compile:review`. These global cancel tokens pre-empt the feedback branch below.
+- IF Any other: process it as feedback on the plan: in `{planFile}`, change the anchor, tier or block of the entries it names, drop an entry the user rejects, or add one (as §2 to §4 would) for a dismissed finding the user takes back, and record each drop or take-back in `{run_dir}/dismissed.json` as `{findingStorageData}` says. Then run §6's `apply` again: it rebuilds the draft from the original, so feedback never edits the draft. On exit 0, redisplay §7; on a failure, handle it as §6 says (the previous draft stays), and [C] waits for a round whose `apply` passes. Then [Redisplay Menu Options](#8-present-menu-options)

package/src/skf-refine-architecture/references/exit-codes.md

@@ -0,0 +1,30 @@
+# Exit Codes and Result Envelope
+
+Every hard halt in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text. Each code pairs with a `halt_reason` string carried in the headless result envelope.
+
+| Code | Meaning              | Raised by                                                                                    |
+| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
+| 0    | success              | step 7 (terminal)                                                                           |
+| 2    | input-missing / input-invalid | step 1 §1 (headless with no `--architecture-doc`) → `input-missing`; step 1 §1 (an architecture document that is missing or unreadable, or a [VS] report that breaks the feasibility-report contract (`schemaVersion` not `1.0`, a section missing or out of order, a missing or second verdict table, an unknown verdict token) or cannot be read), step 1 §1b and step 5 §6 and §8 (the architecture document cannot be read as UTF-8 text) → `input-invalid` |
+| 3    | resolution-failure   | On Activation §5 (`output_folder` or `forge_data_folder` unconfigured → `output-folder-unconfigured` / `forge-folder-unconfigured`; the result emitter is not installed → `resolution-failure`); a helper is not installed, cannot start or fails: step 1 §2 (`skf-enumerate-stack-skills.py`, phase `init:inventory`), step 2 §2 (`skf-comention-pairs.py`, phase `gap-analysis:comention`); a helper is not installed or `uv` cannot start it: step 1 §1 (`skf-validate-feasibility-report.py`, phase `init:feasibility-validator`), step 1 §1b, step 3 §4, step 5 §6 and §8 and step 6 §1 (`scripts/skf-check-preservation.py`, or at step 3 §4 the shared feasibility-report reader it runs) → `resolution-failure`; step 1 §4 (the refinement rules cannot be read, lack a table the steps read or name a tier the Refinement Summary cannot count) → `resolution-failure` |
+| 4    | write-failure        | On Activation §5 (the write probe, the run folder); step 1 §1b (the analysis copy); step 1 §3c (the RA state file); step 5 §6 (the draft) and §8 (the promotion, or a draft that still cannot be read after one rebuild); step 6 §1 (the result payload) and §4 (the emitter refuses it twice) → `write-failed`; step 5 §6 (in headless, the draft would lose or change a line of the original) and §8 (it still would after one rebuild) → `preservation-failed` |
+| 5    | state-conflict       | step 1 §3 (no skill SKF generated was found: refinement requires ≥1 skill) → `insufficient-skills` |
+| 6    | user-cancelled       | step 1 §1 prompt cancelled; step 2 §2b scope confirmation `[X]`; any prompt that accepted `cancel`/`exit`/`:q`; step 5 review gate `[X]` (the draft is deleted, `{outputFile}` is unchanged) |
+| 7    | inventory-unreliable | step 1 §2 (skill-inventory warnings exceed the failure budget); skills SKF did not generate are not counted |
+| 8    | recovery-failed      | step 3 §4 (the [VS] report cannot be read again, or [VS] rewrote it during the run, or the refinement rules no longer pass step 1's check); step 5 §1 (the saved state is not enough to rebuild the Step 02-04 findings, the scope or the VS report); step 6 §1 (a record of the draft's build or promotion is missing) |
+
+## Result Envelope
+
+When `{headless_mode}` is true, step 6 prints one `SKF_REFINE_ARCHITECTURE_RESULT_JSON: {...}` line on **stdout** when it writes the result contract, and every HARD HALT prints one on **stderr** with `status: "error"`. The shared emitter builds each line from the payload the stage stages in `{run_dir}`, folds in the decisions and warnings the run recorded there, and checks it against `{project-root}/_bmad/skf/shared/scripts/schemas/skf-refine-architecture-result-envelope.v1.json` (`{project-root}/src/shared/scripts/schemas/skf-refine-architecture-result-envelope.v1.json` in a dev checkout), whose descriptions say what each field holds: `status`, `refined_path`, `previous_refined_path`, `previous_pass`, `gap_count`, `issue_count`, `improvement_count`, `unverified_count`, `exit_code`, `halt_reason`, `run_id`, `result_path`, and `headless_decisions`, `warnings` and `error` when they apply. Never type the line yourself.
+
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"insufficient-skills"`, `"output-folder-unconfigured"`, `"forge-folder-unconfigured"`, `"resolution-failure"`, `"inventory-unreliable"`, `"write-failed"`, `"preservation-failed"`, `"recovery-failed"`, `"user-cancelled"`. `exit_code` matches the table above, and the emitter derives it from `halt_reason`.
+
+## Emitting a Halt
+
+Every HALT names its exit code, `halt_reason` and phase. In headless mode, stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>"}`, adding `"refined_path": "{outputFile}"` once step 5 promoted the draft and `"path"` when the halt names one, then run:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-refine-architecture --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+Each stage that halts shows this command and the probe order that resolves `{emitEnvelopeHelper}`, so a late halt emits the right line even when this file is not in context. Display the line it prints, then stop with the halt's exit code. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing. A HALT before the run folder exists (SKILL.md On Activation §5) passes the payload on stdin instead.