bmad-module-skill-forge 2.1.0 → 3.0.0

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

@@ -1,14 +1,19 @@
 ---
 nextStepFile: 'gap-analysis.md'
 refinementRulesData: '{refinementRulesPath}'
-# Resolve `{enumerateStackSkillsHelper}` by probing
-# `{enumerateStackSkillsProbeOrder}` in order (installed SKF module path
-# first, src/ dev-checkout fallback); first existing path wins. §2 calls
-# it for the deterministic skill inventory (cascade-resolved exports,
-# metadata-hash, confidence-tier mapping).
+# The findings a step 5 review dropped from an earlier refinement (compile.md §8).
+dismissedFile: '{outputFolderPath}/.ra-dismissed-{arch_project_name}.json'
+# Each probe order resolves to its first existing path.
 enumerateStackSkillsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
   - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
+validateFeasibilityReportProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-feasibility-report.py'
+  - '{project-root}/src/shared/scripts/skf-validate-feasibility-report.py'
+preservationScript: 'scripts/skf-check-preservation.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}. -->
@@ -22,80 +27,108 @@ Load the architecture document (required), scan the skills folder to build a ski
 ## Rules
 
 - Focus only on loading inputs, scanning skills, and validating prerequisites — do not perform analysis
-- Present a clear initialization summary so downstream steps have validated inputs
 
 ## 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.
+
+**Recording a decision or a warning.** A gate below that picks its default for a headless run records that decision in the run sink the moment it decides: stage the decision it shows as `{run_dir}/decision.json`, then run the first command. A warning goes in with the second:
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-refine-architecture --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning '<the warning>'
+```
+
 ### 1. Accept Input Documents
 
-"**Refine Architecture — Evidence-Backed Refinement** (additive — never deletes original content).
+`--architecture-doc <path>` and `--vs-report-path <path>` apply in every mode, as the SKILL.md Invocation Contract says: each one answers its question below, which is then not asked, in an interactive run as in headless.
+
+**Refine without a report.** `--vs-report-path none` answers the report question as typing `none` at the prompt does, in every mode: skip the probe and the path mode below, use no report, and say "VS report skipped (--vs-report-path none)." (in headless, log it).
+
+**Find the [VS] report first.** Unless `--vs-report-path none` was passed, resolve `{validateFeasibilityReportHelper}` from `{validateFeasibilityReportProbeOrder}`; first existing path wins. If no candidate exists, or `uv` cannot start it, HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `init:feasibility-validator`: "Refine Architecture cannot read a [VS] report: `skf-validate-feasibility-report.py` is not installed. Re-install SKF (`npx bmad-module-skill-forge install`), or refine without a report with `--vs-report-path none`."
+
+Unless `--vs-report-path` was passed, run the probe (the first command) before asking anything: it reads the `-latest` report [VS] wrote for `{project_name}`, whose file name the helper builds. A path from `--vs-report-path`, or one typed at the prompt, goes through the path mode (the second), which checks and reads that file exactly as `--locate` does and prints the same JSON:
+
+```bash
+uv run {validateFeasibilityReportHelper} --locate "{forge_data_folder}" --project-name "{project_name}"
+uv run {validateFeasibilityReportHelper} "{vs_report_path}"
+```
+
+Each checks the report against the shared feasibility-report schema and prints one JSON (its module docstring lists every key). Branch on its exit code:
+
+- **0 with `status: "ok"`:** the report to use. The probe's becomes the report question's default below.
+- **0 with `status: "not-found"`** (the probe only): there is no [VS] report for this project, so the question has no default.
+- **1** (the report breaks the contract), or **2** with a JSON from the probe (the report exists but could not be read): HALT as **Unusable VS report** says below.
+- **2** with a JSON from the path mode (the file is missing or could not be read; its `error` says which): in an interactive run, show `error`, run the probe above if it has not run, and ask the report question again. In headless, log "headless: VS report not read at {vs_report_path} ({error}); probing for the [VS] report instead", record the decision `{"gate": "init.vs-report-unreadable", "default_action": "probe", "taken_action": "probe", "reason": "<the line logged>", "evidence": {"given": "<vs_report_path>", "error": "<error>"}}`, then run the probe above and take its outcome as if `--vs-report-path` had not been passed.
+- **2 with no JSON** on stdout: argparse refused the call itself (its usage error is on stderr). It says nothing about the report: fix the call and run it again.
+
+**Unusable VS report.** A report that breaks the contract is never interpreted: HALT (exit code 2, `halt_reason: "input-invalid"`) at phase `init:vs-report`, with `"path"` set to the report's `path`. Name the report's `path` and each problem its JSON shows: a `schemaVersion` other than `1.0` (`schemaVersionOk` is false), sections missing or out of order (`missingHeadings`, `orderViolations`), no verdict table (`verdictTableFound` is false), a second verdict table (at line `duplicateVerdictTableLine`), each entry of `unknownTokens`, or the `error` of a report that could not be read. End with: "Re-run [VS] to write a current report, pass another one with `--vs-report-path <path>`, or refine without one with `--vs-report-path none`."
+
+**Ask for the inputs.** Ask only for what no flag answered:
+
+"**Refine Architecture: Evidence-Backed Refinement** (additive: never deletes original content).
 
 If you wanted to *verify* the stack first, type `cancel` and run `[VS] Verify Stack`; if no skills exist yet, run `[CS] Create Skill`. Otherwise, please provide the following:
-1. **Architecture document path** (REQUIRED) — your project's architecture doc to refine
-2. **VS feasibility report path** (OPTIONAL) — from a previous [VS] Verify Stack run, for additional context
+1. **Architecture document path** (REQUIRED): your project's architecture doc to refine
+2. **VS feasibility report path** (OPTIONAL): {IF the probe found a report:}Found the [VS] report from {vs_report_date}: press Enter to use it, or give another path.{ELSE:}From a previous [VS] Verify Stack run, for additional context.{END IF} Type `none` to refine without a report.
 
 Or type `cancel` / `exit` / `:q` at any prompt to abort cleanly."
 
-Wait for user input. Store the validated architecture document path as `architecture_doc`. **GATE [default: use args]** — If `{headless_mode}` and `--architecture-doc` was provided: use that path and auto-proceed, log: "headless: using provided architecture path". If `--vs-report-path` was provided, consume it at the VS validation below. If `--architecture-doc` is absent in headless: HALT (exit code 2, `halt_reason: "input-missing"`) and emit the error envelope.
+`{vs_report_date}` is the date in the probe's `generatedAt`, or the file name of its `path` when `generatedAt` is null.
 
-- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q` at any sub-prompt: Display "Cancelled — no refinement was performed." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+Wait for user input. Store the validated architecture document path as `architecture_doc`. **GATE [default: use args]:** a question a flag answered is not asked, and headless answers the rest with their defaults. If `{headless_mode}` and `--architecture-doc` was provided: use that path and auto-proceed, log: "headless: using provided architecture path". If `--architecture-doc` is absent in headless: HALT (exit code 2, `halt_reason: "input-missing"`) at phase `init:inputs`. The report question's default is the probe's report when its `status` is `ok`: with no `--vs-report-path`, headless takes it and logs "headless: using the [VS] report found at {path}", or logs "headless: no [VS] report for {project_name}; issue detection will use skill data only" when the probe found none.
 
-**Validate architecture document:**
-- Confirm the file exists and is readable
-- If missing or unreadable: "Architecture document not found at `{path}`. Provide a valid path."
-- HALT (exit code 2, `halt_reason: "input-invalid"`) if the user cannot provide a valid path. In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" immediately.
+A headless run that answered the report question this way (no `--vs-report-path`, or one it could not read) records the decision: `{"gate": "init.vs-report", "default_action": "use-found-report", "taken_action": "use-found-report", "reason": "<the line logged>", "evidence": {"vs_report_path": "<path>"}}` when the probe found a report, or `{"gate": "init.vs-report", "default_action": "no-report", "taken_action": "no-report", "reason": "<the line logged>"}` when it found none.
 
-**Resolve `{arch_project_name}` (names the refined output file):** Read the architecture document's YAML frontmatter. If it declares a `project_name`, store that value as `{arch_project_name}`; otherwise fall back to the config `{project_name}` resolved at activation. Stash `{arch_project_name}` as a workflow-context variable — `compile.md` and `report.md` resolve `{outputFile}` from it. This makes a producer-side refine of a consumer's architecture doc (the producer/consumer forge split) name the proposal after the doc's own project rather than the forge workspace config. Producer-side working state (`ra-state-{project_name}.md`) and the VS report auto-probe stay keyed on the config `{project_name}`.
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q` at any sub-prompt: Display "Cancelled: no refinement was performed." and HALT (exit code 6, `halt_reason: "user-cancelled"`) at phase `init:inputs`.
 
-**Validate VS report (if provided via `--vs-report-path` or interactive input):**
-- Confirm the file exists and is readable
-- If missing at user-provided path: attempt auto-probe (below) before giving up
-- Store VS report availability as `vs_report_available: true|false` and `vs_report_path`
+**Validate the architecture document:** when the file is missing or unreadable, say "Architecture document not found at `{path}`. Provide a valid path." and HALT (exit code 2, `halt_reason: "input-invalid"`) at phase `init:architecture-doc`, with `"path"` set to the path given, if the user cannot provide one (a headless run, at once).
 
-**Scope hint (optional, `--scope-skills`):** If `--scope-skills <names>` was provided, store the parsed comma-separated list as `{scope_skills}` — gap analysis (Step 02 §2b) uses it as the authoritative in-scope skill set. If absent, leave `{scope_skills}` empty; Step 02 derives scope from the architecture document instead.
+**Resolve `{arch_project_name}`**, which names the refined output file: the `project_name` the architecture document's YAML frontmatter declares, else the config `{project_name}`. The RA state file and the VS report probe stay keyed on the config `{project_name}`.
 
-### 2. Scan Skills Folder
+**Record the VS report.** Cache the JSON of the report this run uses as `{vs_report}`: no step reads the report file by hand. Set `vs_report_available` to true when there is one (its `status` is `ok`), and to false when the probe found none or `none` was typed or passed with `--vs-report-path`; set `vs_report_path` to its `path`.
+
+**Scope hint (optional, `--scope-skills`):** If `--scope-skills <names>` was provided, store the comma-separated names as `{scope_skills}`, as given: Step 02 §2b takes them as the in-scope skill set, and Step 02 §3 checks each against the inventory. If absent, leave `{scope_skills}` empty.
 
-**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins.
+### 1b. Set Aside an Earlier Refinement Pass
 
-**Primary path — deterministic enumeration via shared helper:**
+Before §3c resets the state file, set aside any earlier Refine Architecture pass, whose annotations are not the user's text:
 
 ```bash
-python3 {enumerateStackSkillsHelper} enumerate {skills_output_folder} --pairs --reliability
+uv run {preservationScript} inspect --doc "{architecture_doc}" --stripped "{run_dir}/analysis-doc.md" -o "{run_dir}/inspect.json"
 ```
 
-The helper walks `{skills_output_folder}`, reads each `metadata.json`, applies the version-aware resolution (export-manifest → `active` symlink → flat fallback), captures the exports cascade (metadata → references → SKILL.md), maps `confidence_tier`, and emits structured JSON with one entry per skill plus a top-level `warnings[]` array. Cache the result as `skill_inventory`.
+Bind `{analysis_doc}` ← `{run_dir}/analysis-doc.md`, the document with any earlier pass set aside: Steps 02 to 04 read the architecture document only through it, while Step 05 builds from `{architecture_doc}` itself. Bind `{previous_pass}` ← `previous_pass`. Then act on the script's exit code:
 
-`--pairs` additionally attaches `skill_inventory.pairs` — the complete, deterministic set of unique `{library_a, library_b}` combinations over the skill names (`itertools.combinations`, sorted-name order, `pair_count == N*(N-1)/2`) — plus `skill_inventory.pair_count`. Cache both alongside the inventory. This is the exact pair set Step 02 (gap analysis) iterates; the helper owns the combinatorics, so a pair can never be silently dropped or duplicated at larger N and downstream steps read the set rather than re-deriving it.
+- **0** with `previous_pass` true: say "This document holds an earlier Refine Architecture pass ({signals}): its RA blocks ({marked_blocks} marked, {legacy_blocks} unmarked) are set aside, and this run writes one current set in their place. Refinements you moved into your own prose stay as they are." (in headless, log it). An unmarked block runs to the next heading, so it can hold text of yours: when `set_aside` holds a `legacy` entry, list each one's `start`-`end` lines and `first_line`, say "Text of your own in these lines is neither analyzed nor kept in the refined document: move it above the RA heading and re-run [RA] to keep it.", and record the warning `legacy_blocks_set_aside: lines <each start-end, comma-separated>`. When `malformed_markers` is not empty (an RA marker without its pair, kept with the text around it as the user's), name those lines and record the warning `malformed_ra_markers: lines <the lines, comma-separated>`.
+- **0** with `previous_pass` false: nothing to set aside; the analysis copy equals the document.
+- **2** with a JSON: the document cannot be read as UTF-8 text: HALT (exit code 2, `halt_reason: "input-invalid"`) at phase `init:previous-pass`, naming its `error`, with `"path"` set to `{architecture_doc}`. **2 with no JSON:** a malformed call: fix it and run it again.
+- **3:** the analysis copy could not be written: HALT (exit code 4, `halt_reason: "write-failed"`) at phase `init:previous-pass`, naming its `error`.
+- If `uv` cannot start the script: HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `init:previous-pass`.
 
-Each helper-emitted entry includes: `skill_name`, `version`, `language`, `confidence_tier`, `exports_documented`, `source_repo`, `source_root`, and a `metadata_hash` for change-detection across runs. The helper's `warnings[]` carries per-skill skip reasons (missing SKILL.md/metadata.json, non-symlink `active`, orphan-versions, schema-version violations).
+**Findings an earlier review dropped.** When `{previous_pass}` is true and `{dismissedFile}` exists, read it as `{dismissed_findings}`: the list of `{kind, skills, anchor, title, capability}` records Step 05 writes when its review drops a finding, which Steps 02 to 04 match as `references/finding-storage.md` says. Otherwise `{dismissed_findings}` is empty. A file that is not such a JSON list leaves it empty too: say "The record of findings dropped at an earlier review cannot be read ({reason}): they may come back in this run." (in headless, log it).
 
-**Failure-budget guard:** `--reliability` attaches the helper-computed verdict — `inventory_reliable` (boolean), `unreliable_ratio`, `skill_count`, `warning_count` — so the reliability threshold lives in one unit-tested place and this step reads a boolean rather than re-deriving a ratio. If `inventory_reliable` is false, HALT (exit code 7, `halt_reason: "inventory-unreliable"`) with: "Inventory scan unreliable — {warning_count}/{skill_count + warning_count} skills returned skip warnings. Re-run [RA] after skills stabilize." In headless, emit the error envelope.
-
-**Fallback path — graceful degradation when the helper is unavailable:** If `{enumerateStackSkillsHelper}` has no existing candidate, fall through to the LLM-driven inventory: walk `{skills_output_folder}` and for each `{skill_package}` read `metadata.json` and extract `name`, `language`, `confidence_tier`, `stats.exports_documented`, `source_repo`/`source_root`. Skip packages missing SKILL.md or metadata.json with a logged warning. On this degraded path only — with no helper to consult — treat the run as unreliable and HALT the same way if skip warnings exceed one in five of the scanned packages.
+### 2. Scan Skills Folder
 
-### 3. Validate Minimum Requirements
+**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins. If no candidate exists, `uv` cannot start it, or the command below exits non-zero (a `{skills_output_folder}` that does not exist, say), HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `init:inventory`: "Refine Architecture cannot list the skills: {its first stderr line, or with no candidate: `skf-enumerate-stack-skills.py` is not installed. Re-install SKF (`npx bmad-module-skill-forge install`).}" No step walks `{skills_output_folder}` by hand.
 
-**Check skill count:**
-- At least 1 valid skill must exist
-- If no skills found: "**Cannot proceed.** No skills found in `{skills_output_folder}`. Generate skills with [CS] Create Skill or [QS] Quick Skill, then re-run [RA]."
-- HALT (exit code 5, `halt_reason: "insufficient-skills"`). In headless, emit the error envelope.
-- If exactly 1 valid skill found: "⚠️ Proceeding with 1 skill. Note: gap analysis will find no gaps — pairwise analysis requires at least 2 skills. Step 02 will still execute and issue an appropriate notice. Issue detection and improvement detection will proceed normally."
+```bash
+uv run {enumerateStackSkillsHelper} enumerate "{skills_output_folder}" --pairs --reliability > "{run_dir}/skill-inventory.json"
+```
 
-**Output paths (`{outputFolderPath}`, `forge_data_folder`):** both were asserted non-empty (config-completeness → exit 3, `output-folder-unconfigured` / `forge-folder-unconfigured`) and then probed for writability (→ exit 4, `write-failed`) at On-Activation §5. If either was unconfigured or unwritable the run already halted there, so both are guaranteed present and writable here — no re-check needed.
+The helper reads only the skills SKF generated. Each `skills[]` entry has `name`, `path`, `exports`, `exports_source`, `confidence` (from the exports source, not metadata's `confidence_tier`), and the `language`, `source_repo_basename` and `source_root_basename` Step 02 reads, so no step opens `metadata.json`; `warnings[]` names per-skill problems, each starting `<name>: `. `--pairs` adds `pairs`, every unique `{library_a, library_b}` pair of the skills SKF generated, which Step 02 never re-derives, and `--reliability` adds `inventory_reliable` with the counts behind it. Read the JSON it writes to `{run_dir}/skill-inventory.json` as `skill_inventory` (Step 02 §4 and Step 03 §3 read each skill's `exports[]` from that file), and bind `{not_skf_output}` ← `not_skf_output`, `{inventory_reliable}` ← `inventory_reliable`, `{warning_count}` ← `warning_count`, `{skill_count}` ← `skill_count`, `{inventory_warnings}` ← `warnings`, `{pairs}` ← `pairs` and `{pair_count}` ← `pair_count`. When `{not_skf_output}` is non-empty, display it once: "Skipped (not SKF output): {not_skf_output}". Those folders count toward neither `{skill_count}` nor `{warning_count}`.
 
-**Check architecture document:**
-- Confirm it was loaded successfully in section 1
-- If not: HALT with error (should not reach here if section 1 validation passed)
+**Failure-budget guard:** If `{inventory_reliable}` is false, HALT (exit code 7, `halt_reason: "inventory-unreliable"`) at phase `init:inventory` with: "Inventory scan unreliable: {warning_count} warning(s) across {skill_count} skill(s) SKF generated: {inventory_warnings}. Fix the skills named there (re-save an unreadable `metadata.json` as plain UTF-8 JSON or restore it from version control, and regenerate a skill whose exports are missing), then re-run [RA]."
 
-### 3b. Auto-Probe VS Report
+### 3. Validate Minimum Requirements
 
-**Auto-probe VS report (if not provided by user in section 1, OR if user-provided path was invalid):**
-- Only attempt if `forge_data_folder` is non-empty and the directory exists (validated above); otherwise skip probe and set `vs_report_available: false`
-- Check for `{forge_data_folder}/feasibility-report-{project_name}.md`
-- If found: "Auto-discovered VS report at `{path}`. Loading for additional context."
-- Store `vs_report_available: true` and `vs_report_path`
-- If not found: `vs_report_available: false` — "Proceeding without VS report — issue detection will rely on skill data only."
+When `{skill_count}` is 0, say "**Cannot proceed.** No skill SKF generated was found in `{skills_output_folder}`. Generate skills with [CS] Create Skill or [QS] Quick Skill, then re-run [RA]." (appending "Skipped (not SKF output): {not_skf_output}." when `{not_skf_output}` is non-empty) and HALT (exit code 5, `halt_reason: "insufficient-skills"`) at phase `init:skills`. When it is 1, say "⚠️ Proceeding with 1 skill: gap analysis needs at least 2 and will find no gaps; issue and improvement detection run normally."
 
 ### 3c. Reset RA State File
 
@@ -105,15 +138,22 @@ Create (or overwrite) `{forge_data_folder}/ra-state-{project_name}.md` with a fr
 <!-- RA state for {project_name} — generated {current_date} -->
 ```
 
-This ensures steps 02-04 append to a clean slate and context recovery in step 5 never loads stale findings from a prior run.
+Then append a `<!-- [RA-VS] ... -->` block: the `path`, `generatedAt`, `coveragePercentage` and `coverageMeasured` of `{vs_report}` when `vs_report_available` is true, or `none`. Step 03 reads the report again from that `path` and checks its `generatedAt`, and Step 05 reads the block back if context degrades on a long run.
 
-On any write failure (read-only mount, disk full, permissions denied): HALT (exit code 4, `halt_reason: "write-failed"`) with the captured error and emit the error envelope. The On-Activation §5 probe should have caught this earlier — if it surfaces here, the filesystem state changed mid-workflow.
+Then append `<!-- [RA-RUN] run_dir={run_dir} timestamp={timestamp} architecture_doc={architecture_doc} arch_project_name={arch_project_name} -->`: Steps 05 and 06 read these bindings back when context degrades, since the run's records live in `{run_dir}`.
 
-### 4. Load Refinement Rules
+On a write failure: HALT (exit code 4, `halt_reason: "write-failed"`) at phase `init:state-file`, with `"path"` set to the state file, naming the captured error.
 
-Load `{refinementRulesData}` for reference by downstream steps.
+### 4. Check the Refinement Rules
+
+`{refinementRulesData}` holds the house-style rules Steps 02 to 05 classify with: the bundled `references/refinement-rules.md`, or the copy `workflow.refinement_rules_path` names. The preservation script checks that it holds the six tables the steps read and that its tiers follow the rules the file's first section states, so the Refinement Summary can count each tier:
+
+```bash
+uv run {preservationScript} rules --rules "{refinementRulesData}"
+```
 
-Extract: gap detection rules, issue detection rules, improvement detection rules, citation format, and preservation rules.
+- **0:** bind `{rule_tiers}` ← `tiers`, the tiers of the Issue Severity and Improvement Value tables in their order, which Step 05 writes into its plan.
+- **1** (`status: "violations"`: it lacks a table or breaks a tier rule), or **2** with a JSON (`error` says why the file cannot be read): HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `init:rules`, with `"path"` set to it: "The refinement rules at `{refinementRulesData}` {cannot be read: {error} | break these rules: {the `detail` of each of its `violations`}}. Fix the copy `refinement_rules_path` names, starting again from the bundled `references/refinement-rules.md`, or remove that override." **2 with no JSON:** a malformed call: fix it and run it again.
 
 ### 5. Display Initialization Summary
 
@@ -122,14 +162,15 @@ Extract: gap detection rules, issue detection rules, improvement detection rules
 | Field | Value |
 |-------|-------|
 | **Architecture Doc** | {architecture_doc} |
-| **VS Report** | {vs_report_path or 'Not provided — issue detection will use skill data only'} |
+| **VS Report** | {vs_report_path, or 'None: issue detection will use skill data only'} |
+| **Earlier RA pass** | {IF previous_pass: set aside ({signals}), replaced by this run ELSE: none} |
 | **Skills Loaded** | {skill_count} |
 
 **Skill Inventory:**
 
-| Skill | Language | Tier | Exports |
-|-------|----------|------|---------|
-| {skill_name} | {language} | {confidence_tier} | {exports_documented} |
+| Skill | Exports | Exports source | Confidence |
+|-------|---------|----------------|------------|
+| {name} | {number of exports} | {exports_source} | {confidence} |
 
 **Proceeding to gap analysis...**"
 

package/src/skf-refine-architecture/references/issue-detection.md

@@ -1,6 +1,13 @@
 ---
 nextStepFile: 'improvements.md'
 refinementRulesData: '{refinementRulesPath}'
+findingStorageData: 'references/finding-storage.md'
+# §4 joins the [VS] verdicts to the inventory and the scope with it.
+preservationScript: 'scripts/skf-check-preservation.py'
+# The shared emitter: §4's halts print their envelope with it.
+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}. Append issue-detection findings to the RA state file in {document_output_language}. -->
@@ -9,7 +16,7 @@ refinementRulesData: '{refinementRulesPath}'
 
 ## STEP GOAL:
 
-Find contradictions between what the architecture document claims and what the generated skills reveal about actual API surfaces. Detect language boundary issues not addressed, protocol mismatches assumed away, and missing bridge layers. If a VS feasibility report is available, incorporate RISKY and BLOCKED verdicts as confirmed issues.
+Find contradictions between what the architecture document claims and what the generated skills reveal about actual API surfaces. Each issue takes a type and a severity tier the refinement rules define. If a VS feasibility report is available, raise its in-scope verdicts as issues, as the refinement rules map their tokens.
 
 ## Rules
 
@@ -19,15 +26,17 @@ Find contradictions between what the architecture document claims and what the g
 
 ## MANDATORY SEQUENCE
 
-### 1. Reference Refinement Rules
+**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:
 
-Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-refine-architecture --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
 
-Extract: issue classification (API Mismatch, Protocol Contradiction, Language Boundary Ignored, Type Incompatibility) and VS report integration rules.
+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.
 
 ### 2. Extract Integration Claims from Architecture
 
-Parse the architecture document for specific claims about how technologies interact.
+Parse the architecture document for specific claims about how technologies interact. Read it as `{analysis_doc}`, the copy Step 01 §1b wrote with any earlier Refine Architecture pass set aside, so a claim is always the user's, never an old RA annotation.
 
 **Claim types to extract:**
 - **API claims:** "Library X provides/exposes/exports {function/endpoint}"
@@ -37,48 +46,35 @@ Parse the architecture document for specific claims about how technologies inter
 - **Capability claims:** "Library X handles {capability}"
 
 For each claim, record:
-- The exact text or paraphrase from the architecture
+- The claim's exact text as one line of `{analysis_doc}` holds it, copied character for character (Step 05 anchors the issue's callout on it), then a paraphrase if one helps
 - The section where it appears
 - The libraries referenced
 
 ### 3. Verify Claims Against Skill API Surfaces
 
-For each extracted claim, verify against the compact API surfaces already collected in Step 02 §4 — the per-skill `{skill_api_surfaces}` summaries (`{exports, protocols, data_formats}`), carried forward as workflow state exactly like `{in_scope_skills}`. Reload a skill's SKILL.md directly only if its summary is unavailable or context has compacted (see Step 02 §4 for the canonical delegate-the-read pattern). Then check:
-
-**API Mismatch check:**
-- Does the claimed API actually exist in the skill's export list?
-- Does the function signature match what the architecture describes?
-- If the architecture describes an API that does not appear in the skill: flag as issue
+Check each claim against the compact API surfaces Step 02 §4 collected, the per-skill `{skill_api_surfaces}` summaries (`{exports, protocols, data_formats, capabilities}`), and against each skill's `language` in `skill_inventory`. If the summaries are no longer in context, read them from the `<!-- [RA-SURFACES] ... -->` block of the RA state file (`{forge_data_folder}/ra-state-{project_name}.md`), never from the SKILL.md files. Look at what the claim says about an API and its signature, a protocol or data format, a call across languages, and the types passed between libraries. Whether a named export exists is a membership lookup in the skill's `exports[]` in `{run_dir}/skill-inventory.json` (Step 01 §2), never in the surface: a claim fails on existence only when that list lacks the name, and for a name it holds, judge only the signature, protocol or types the claim states. When that list is empty (a stack skill, or `exports_source` `unknown`), the surface's `exports` were extracted from the files read and may be partial: judge existence from them, never taking a missing name as proof. A claim the skill evidence contradicts is an issue: type it by the Issue Classification of `{refinementRulesData}`.
 
-**Protocol Contradiction check:**
-- Does the skill document the protocol the architecture assumes?
-- If the architecture claims gRPC but the skill shows HTTP-only: flag as issue
+### 4. Incorporate VS Report (If Available)
 
-**Language Boundary check:**
-- If two libraries are in different languages, does the architecture describe a bridge mechanism?
-- If the architecture assumes direct calls across language boundaries without FFI/IPC: flag as issue
+If `vs_report_available` is false, skip this section: issue detection proceeds with skill data only.
 
-**Type Incompatibility check:**
-- Does the architecture assume type compatibility that the skills contradict?
-- If Library A exports Type X but the architecture claims Library B consumes it, and Library B expects Type Y: flag as issue
+**Join the verdicts to the scope.** The report's verdicts span the whole skill set, which may exceed this architecture's surface. One call reads its verdict rows (`pairVerdicts`) again through the shared feasibility-report reader and joins them to the skill names and aliases in `{run_dir}/skill-terms.json` (Step 02 §2), the scope Step 02 §3 settled and the VS Report Integration table of `{refinementRulesData}`:
 
-### 4. Incorporate VS Report (If Available)
-
-If `vs_report_available` is true:
+```bash
+uv run {preservationScript} verdicts --report "{vs_report_path}" --generated-at "{vs_generated_at}" --skills "{run_dir}/skill-terms.json" --in-scope "{in_scope_names}" --rules "{refinementRulesData}"
+```
 
-**Scope filter (reuse `{out_of_scope_skills}` from Step 02 §2b):** The VS report carries verdicts across the entire skill set, which may exceed this architecture's surface. Before promoting any verdict, check the pair's scope — if a verdict is for an **out-of-scope** pair (either library in `{out_of_scope_skills}`), do not promote it to an issue for this architecture; record it under the informational Out-of-Scope bucket instead. Only **in-scope** pairs' verdicts are promoted by the rules below.
+`{vs_report_path}` and `{vs_generated_at}` are the `path` and `generatedAt` of `{vs_report}` (an empty string when `generatedAt` is null), and `{in_scope_names}` every name in `{in_scope_skills}`, comma-separated. If they are no longer in context, read them from the `[RA-VS]` and `[RA-SCOPE]` blocks of the RA state file (`{forge_data_folder}/ra-state-{project_name}.md`). Branch on its exit code:
 
-**Load the VS feasibility report and extract verdicts:**
-- **Risky verdicts** (match case-insensitively): Promote to confirmed issues with the VS evidence as additional citation
-- **Blocked verdicts** (match case-insensitively): Promote to critical issues requiring architecture redesign
-- **Plausible verdicts:** Note informatively — Plausible is not an issue by itself. Only flag as a potential issue if the VS rationale text explicitly states "no direct API evidence" or "weak evidence"
+- **0:** each `in_scope` row (both libraries in-scope skills, in report order) whose `raises` names a tier is an issue of that tier; one whose `raises` is null raises none. The token alone decides, never phrases in the rationale text. Record every `out_of_scope` row, with its `reason`, under the informational Out-of-Scope bucket instead of promoting it to an issue for this architecture.
+- **1** (`status: "stale"`): the report this run started from is gone ([VS] rewrote it during this run, or it cannot be read again), or the refinement rules no longer pass step 1's check: HALT (exit code 8, `halt_reason: "recovery-failed"`) at phase `issue-detection:vs-report`, naming the `detail` of each of its `problems`, with `"path"` set to `{vs_report_path}`.
+- **2** with a JSON (`error` names the file it could not read): stage `{run_dir}/skill-terms.json` again as Step 02 §2 does and run the command again. **2 with no JSON:** a malformed call: fix it and run it again.
+- **3**, or `uv` cannot start the script: HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `issue-detection:vs-report`, naming its `error` (the shared feasibility-report reader is not installed).
 
 **For each VS-sourced issue, include dual citations:**
 - Evidence from the skill content
 - Verdict and rationale from the VS report
 
-If `vs_report_available` is false: Skip this section. Issue detection proceeds with skill data only.
-
 ### 5. Document Each Issue
 
 For each detected issue, cite it in this format:
@@ -86,25 +82,22 @@ For each detected issue, cite it in this format:
 ```
 **[ISSUE]**: {description}
 
-Architecture states: "{quoted claim from original document}" (Section: {section_name})
+Architecture states: "{the claim's exact text from §2}" (Section: {section_name})
 Skill reality: {skill_name} exports: `{actual_api}` — {explanation of contradiction}
-{IF VS report}: VS verdict: {Risky|Blocked} for {pair} — {VS rationale}
+{IF VS report}: VS verdict: {verdict} for {pair}: {VS rationale}
 
 Suggestion: {specific correction with API evidence}
 ```
 
-**Severity classification:**
-- **Critical:** Blocked VS verdicts, fundamental language barriers with no bridge
-- **Major:** Risky VS verdicts, protocol mismatches, missing bridge layers
-- **Minor:** Plausible VS verdicts where the VS rationale explicitly states "no direct API evidence" or "weak evidence", minor type differences with easy conversion
+**Severity:** give each issue one tier of the Issue Severity table of `{refinementRulesData}`; a VS-sourced issue takes the tier its verdict's row raises.
 
 ### 6. Report Issues & Store Findings
 
-Report the in-scope issue count with its critical/major/minor breakdown, then list each issue as a row of **# / Libraries / Issue Type / Severity / Summary** followed by its full §5 citation. One signal is not inferable from the counts and must survive regardless of format:
+Report the in-scope issue count with its count per severity tier, then list each issue as a row of **# / Libraries / Issue Type / Severity / Summary** followed by its full §5 citation. One signal is not inferable from the counts and must survive regardless of format:
 
 - **Out-of-scope VS verdicts were set aside (from §4):** list them separately for awareness only — they were not counted as issues — and note that re-running with `--scope-skills` pulls any that belong into scope.
 
-Store the **in-scope** issue findings per the Finding Storage rule (refinement rules), under a `<!-- [RA-ISSUES] ... -->` block (its citations carry the architecture claim, skill evidence, VS verdict, severity, and suggestion). Record any out-of-scope VS verdicts under the shared `<!-- [RA-OUT-OF-SCOPE] ... -->` marker so Step 05 leaves them out — informational only.
+Store the **in-scope** issue findings under a `<!-- [RA-ISSUES] ... -->` block (their citations carry the architecture claim, skill evidence, VS verdict, severity and suggestion) and any out-of-scope VS verdicts under the shared `<!-- [RA-OUT-OF-SCOPE] ... -->` marker, as `{findingStorageData}` says (an issue that matches one a review dropped goes under `[RA-DISMISSED]` instead).
 
 ### 7. Auto-Proceed to Next Step
 

package/src/skf-refine-architecture/references/refinement-rules.md

@@ -1,25 +1,22 @@
-<!-- Static reference loaded by gap-analysis.md, issue-detection.md, and improvements.md. -->
+<!-- House style: the finding types and tiers Steps 02-05 classify with. Step 01 checks it, and `workflow.refinement_rules_path` can swap it for a team's copy. -->
 
 # Architecture Refinement Rules
 
-## Purpose
+## What a Copy Can Change
 
-Rules for detecting gaps, issues, and improvements in an architecture document using generated skill data as the evidence source.
+`workflow.refinement_rules_path` replaces this whole file with a team's copy, so a copy starts from this file. It can add, rename, drop or redefine the gap, issue and improvement types, name its own severity and value tiers and say when each applies, and decide which tier each [VS] verdict raises. It keeps the six tables below under their headings, since the steps read them by name: Step 01 halts on a copy that lacks one.
 
----
+What each step looks for is fixed: the types label what a step finds, so a type a copy drops does not stop the step finding it, and a finding no type fits takes the closest type.
 
-## Gap Detection Rules
+Each tier becomes a count of the Refinement Summary, `{<tier>_count}` (the name in lower case, spaces as `_`), so Step 01 also halts on a copy 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, in one table or across the two (so High, Medium and Low cannot name both severity and value); no tier is named Gap, Issue, Improvement, Unverified or Skill, whose counts the summary already holds; and each VS Report Integration row raises a tier of the Issue Severity table, or no issue.
 
-Gaps are undocumented integration paths — library pairs that have compatible APIs but no architecture description.
+Everything else is fixed, whatever a copy says. The step files decide which skills and pairs are analyzed (the document scope of Step 02 §2b), `references/finding-storage.md` decides how Steps 02-04 store their findings, and the refined document's headings, callouts, RA markers, placement and preservation check are set by Step 05: compile.md and `scripts/skf-check-preservation.py` own them, so an override of this file cannot change them.
 
-### Detection Method
+---
 
-1. Read the pre-computed unique library pairs from `skill_inventory.pairs` (emitted by the enumerate helper's `--pairs` flag) — do not re-derive them in-context
-2. For each pair, check if both skills export APIs that could connect (compatible types, shared protocols, complementary producer/consumer patterns)
-3. Cross-reference against the architecture document: does the document describe how these two libraries interact?
-4. If compatible APIs exist but NO architecture description exists, this is a **gap**
+## Gap Classification
 
-### Gap Classification
+A gap is an undocumented integration path: two in-scope skills whose APIs could connect while the architecture never describes how they interact.
 
 | Gap Type                     | Description                                                            | Example                                                                              |
 |------------------------------|------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
@@ -29,17 +26,9 @@ Gaps are undocumented integration paths — library pairs that have compatible A
 
 ---
 
-## Issue Detection Rules
-
-Issues are contradictions between architecture claims and verified API reality from the skills.
-
-### Detection Method
+## Issue Classification
 
-1. Extract every integration claim from the architecture document (prose co-mention analysis)
-2. For each claim, verify against the actual API surfaces in the skills
-3. Flag contradictions: claimed APIs that do not exist, assumed compatibility that breaks, missing bridge layers
-
-### Issue Classification
+An issue is a contradiction between an architecture claim and the API evidence of the skills: an API that does not exist, an assumed compatibility that breaks, a bridge layer that is missing.
 
 | Issue Type                    | Description                                                    | Example                                                                      |
 |-------------------------------|----------------------------------------------------------------|------------------------------------------------------------------------------|
@@ -48,26 +37,32 @@ Issues are contradictions between architecture claims and verified API reality f
 | **Language Boundary Ignored** | Architecture assumes direct calls across language boundaries   | "Calls Rust functions from TypeScript" with no FFI/IPC mechanism described   |
 | **Type Incompatibility**      | Architecture assumes type compatibility that does not hold     | "Passes CRDT documents directly" but types are incompatible across libraries |
 
-### VS Report Integration
+## Issue Severity
 
-When a VS feasibility report is available:
-- RISKY verdicts become **confirmed issues** with the VS evidence as additional citation
-- BLOCKED verdicts become **critical issues** requiring architecture redesign
-- Plausible verdicts become potential issues **only if** the VS rationale text explicitly states "no direct API evidence" or "weak evidence" — otherwise they are informational only
+Each issue takes one severity tier. The tiers are listed most severe first: Step 05 orders issues by them and counts each one in the Refinement Summary.
 
----
+| Severity     | When                                                                             |
+|--------------|----------------------------------------------------------------------------------|
+| **Critical** | The architecture needs a redesign: a fundamental language barrier with no bridge |
+| **Major**    | A protocol mismatch or a missing bridge layer                                    |
+| **Minor**    | A minor type difference with an easy conversion                                  |
 
-## Improvement Detection Rules
+## VS Report Integration
 
-Improvements are capability expansions — library features documented in skills but not leveraged in the architecture.
+When the run uses a [VS] feasibility report, each in-scope pair verdict raises the issue this table maps its token to, citing the verdict and its rationale as additional evidence. The tokens are the feasibility-report schema's and are case-sensitive, and each rule keys on the token alone, never on phrases in the rationale text. A copy maps all four tokens, each to a severity tier of the table above or to no issue. A Raises cell raises what it bolds (a tier, or No issue or None), else what its text names; when that is more than one tier, or a tier and also No issue or None, Step 01 halts: bold only the one it raises.
 
-### Detection Method
+| Verdict     | Raises                                                                                                     |
+|-------------|------------------------------------------------------------------------------------------------------------|
+| `Blocked`   | A **Critical** issue: the architecture needs a redesign                                                    |
+| `Risky`     | A **Major** issue, confirmed by the VS evidence                                                            |
+| `Plausible` | A **Minor**, potential issue: every compatibility check passed but neither skill cites the other literally |
+| `Verified`  | No issue                                                                                                   |
 
-1. For each skill, enumerate its full API surface (all exports, types, protocols)
-2. Compare against how the architecture uses that library
-3. Identify capabilities present in the skill but absent from the architecture
+---
 
-### Improvement Classification
+## Improvement Classification
+
+An improvement is a capability expansion, looked for in each in-scope skill (Step 02 §2b): a feature the skill documents that the architecture does not use, or two in-scope skills whose features combine in a way the architecture does not.
 
 | Improvement Type          | Description                                                             | Example                                                                        |
 |---------------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------|
@@ -75,18 +70,12 @@ Improvements are capability expansions — library features documented in skills
 | **Cross-Library Synergy** | Two libraries have complementary features not combined in architecture  | "Library A's event system could feed Library B's stream processor"             |
 | **Alternative Pattern**   | Skill documents a better pattern than the one described in architecture | "Skill shows batch API is more efficient than the per-item approach described" |
 
----
-
-## Finding Storage (Steps 02-04)
-
-Each analysis step stores its findings two ways: as workflow state for Step 05, and appended to `{forge_data_folder}/ra-state-{project_name}.md` as a labeled `<!-- [RA-...] ... -->` block holding the **complete formatted findings** — full citation blocks with evidence and suggestions, not just counts — so Step 05 can recover them if context degrades on a long run. The refined document itself is written once, in Step 05; Steps 02-04 never write to it.
-
----
+## Improvement Value
 
-## Preservation Rules
+Each improvement takes one value tier. The tiers are listed most valuable first: Step 05 orders improvements by them and counts each one in the Refinement Summary.
 
-1. **Never delete original content** — only add annotations and subsections
-2. **Follow original section layout** — add refinement subsections within existing sections
-3. **Use callout blocks** for issues: `> [!WARNING]` or `> [!NOTE]` format
-4. **Mark additions clearly** — prefix added subsections with "RA:" or use a refinement marker
-5. **Maintain original heading hierarchy** — refinement subsections are one level deeper than the parent
+| Value      | When                                                                                 |
+|------------|--------------------------------------------------------------------------------------|
+| **High**   | Addresses a known architectural concern or significantly expands functionality       |
+| **Medium** | Adds convenience or efficiency                                                       |
+| **Low**    | Nice to have, not impactful                                                          |