bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-refine-architecture/references/finding-storage.md

@@ -0,0 +1,21 @@
+<!-- Fixed contract for Steps 02-04 (gap-analysis.md, issue-detection.md, improvements.md), and for how Step 05 (compile.md) records a finding its review dropped. No customization replaces it: `workflow.refinement_rules_path` swaps only the house-style references/refinement-rules.md. -->
+
+# Finding Storage (Steps 02-05)
+
+Each analysis step stores its findings two ways: as workflow state for Step 05, and appended to the RA state file `{forge_data_folder}/ra-state-{project_name}.md` as a labeled block, `<!-- [RA-GAPS] ... -->`, `<!-- [RA-ISSUES] ... -->` or `<!-- [RA-IMPROVEMENTS] ... -->`. A block holds the **complete formatted findings**: each finding's full citation as its step formats it, with its type and its tier (a gap has none), the skills it cites, the evidence and the suggestion, never only counts, so Step 05 can rebuild 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.
+
+A finding that involves a skill or a pair outside the document's scope (Step 02 §2b) goes under the shared `<!-- [RA-OUT-OF-SCOPE] ... -->` block instead: it is listed for awareness only, and Step 05 leaves it out of the refined document.
+
+## Findings a Review Dropped
+
+`{dismissed_findings}` (Step 01 §1b) lists the findings a step 5 review dropped from an earlier refinement of this document, each as `{kind, skills, anchor, title, capability}`; it is empty on a first pass. If it is no longer in context, read it again as Step 01 §1b does.
+
+Compare each in-scope finding with that list before storing it. It matches a record when its kind (`gap`, `issue` or `improvement`) is the record's and it cites the same skills (the same pair for a gap or a synergy, in either order). An issue must also contradict the claim the record's `anchor` holds, or have no claim line when that anchor is `null`, and an improvement must name the capability or API the record's `capability` holds, so one dropped finding never hides another about the same skills. Store a matching finding in full under the shared `<!-- [RA-DISMISSED] ... -->` block instead of under its kind's block, with a one-line title of its own and the `title` of the record it matched: Step 05 lists it at the review and inserts it only if the user takes it back. Report it apart from the step's count, as previously dismissed.
+
+**How Step 05 records a drop.** A feedback round of the step 5 review that drops an entry adds its record, `{"kind", "skills", "anchor", "title", "capability"}` (`title` a line naming the finding, such as its heading; `capability` the `{api}` an improvement's block names, `null` for a gap or an issue), to the list of dropped findings, and a finding the user takes back removes the record it matched. Keep that list in `{run_dir}/dismissed.json`, which the first round that changes it starts from `{dismissedFile}` (`[]` when that file does not exist). It reaches `{dismissedFile}` only at [C], once `promote` exits 0, so [X] leaves the record as it was. To write it there, resolve `{atomicWriteHelper}` from Step 05's `{atomicWriteProbeOrder}` (first existing path wins) and run:
+
+```bash
+uv run {atomicWriteHelper} write --target "{dismissedFile}" < "{run_dir}/dismissed.json"
+```
+
+If no candidate exists or the command fails, say "The dropped findings were not recorded ({reason}): a later run may raise them again." and go on.

package/src/skf-refine-architecture/references/gap-analysis.md

@@ -1,6 +1,16 @@
 ---
 nextStepFile: 'issue-detection.md'
 refinementRulesData: '{refinementRulesPath}'
+findingStorageData: 'references/finding-storage.md'
+comentionProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-comention-pairs.py'
+  - '{project-root}/src/shared/scripts/skf-comention-pairs.py'
+enumerateStackSkillsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
+  - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.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}. Append gap-analysis findings to the RA state file in {document_output_language}. -->
@@ -18,90 +28,140 @@ Find undocumented integration paths — library pairs that have compatible APIs
 
 ## 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>"}`, 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: gap classification (Missing Integration Path, Undocumented Data Flow, Absent Bridge Layer) and detection method.
+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 statements describing two or more technologies working together.
+**Run the mentions helper once.** Resolve `{comentionHelper}` from `{comentionProbeOrder}`; first existing path wins. If no candidate exists, `uv` cannot start it, or the command below exits non-zero, HALT (exit code 3, `halt_reason: "resolution-failure"`) at phase `gap-analysis:comention`: "Refine Architecture cannot find the skills the document names: {its first stderr line, or with no candidate: `skf-comention-pairs.py` is not installed. Re-install SKF (`npx bmad-module-skill-forge install`).}" On exit 1 (its stderr names a staged input it refuses), fix that file and run the command once more before halting. No step finds the mentions by hand. Stage its two inputs first:
+
+- `{run_dir}/skill-terms.json`: a JSON array with one object per `skill_inventory.skills[]` entry, `{"name": "<name>", "aliases": [...]}`, where `aliases` holds the entry's `source_repo_basename` and `source_root_basename` that are not null (the repository and folder the skill was built from, so a skill named `oms-cognee` is matched where the document says "Cognee"). Step 03 §4 reads it too.
+- `{run_dir}/technologies.json`: a JSON array of the libraries, frameworks, databases, services and tools the document names, each as the document writes it, in order of first mention. Programming languages, protocols and data formats do not count, and neither does a technology the document marks as deprecated, removed or being replaced, since no skill should exist for it.
+
+The technology list and the helper both read the document as `{analysis_doc}` (`{run_dir}/analysis-doc.md`), the architecture document with any earlier Refine Architecture pass set aside (Step 01 §1b), so RA's own old annotations never count as documented pairs, mentions or technologies:
 
-**Detection method — prose-based co-mention analysis:** From prose text, find sentences or paragraphs where two or more technology names appear in an *integration relationship* — data flowing between them, one wrapping/bridging/extending/consuming another, or a layer boundary connecting them — not mere co-mention in the same document.
+```bash
+uv run {comentionHelper} mentions --doc "{analysis_doc}" --skills "{run_dir}/skill-terms.json" --technologies "{run_dir}/technologies.json"
+```
+
+The helper matches each name and alias case-insensitively at word boundaries, reads each occurrence as its longest term (so `react-dom` never counts as `react`) and skips fenced code; its module docstring gives the contract. Cache its JSON as `{doc_mentions}`: §2b builds the document scope and the technologies with no skill from it too.
 
-**Mermaid limitation:** Detect co-mentions from prose text only, not from Mermaid diagram syntax — an integration drawn only in a diagram would otherwise surface as a false-positive gap. If `` ```mermaid `` blocks are present in the architecture document, inform the user: "Integration paths documented exclusively in Mermaid diagrams are excluded from co-mention analysis and may appear as false-positive gaps. Consider adding prose descriptions for diagram-only integration paths." Display this warning informatively and immediately continue — this does not halt or modify the analysis sequence.
+**Documented pairs.** `{doc_mentions}.candidates[]` holds each pair of skills that a body paragraph names in one unit (a run of prose, a list item, a table row) or through a lead-in (prose that names one skill, with a list item under it that names the other), each with those paragraphs as `evidence[]`. Judge every candidate, a lead-in one included, from its evidence (`unit_excerpt`, with its `header` and `unit_line`): it is a documented pair when an entry describes an *integration relationship* (data flowing between the two, one wrapping, bridging, extending or consuming the other, or a layer boundary connecting them), not mere co-mention in the same text. Record each documented pair as `{library_a, library_b, architectural_context}`, its context the quoted `unit_excerpt` of the entry that shows the relationship. A pair outside `candidates[]` is not documented: no paragraph names both, or they are only ever listed together (`list_only_pair_count` counts those pairs).
 
-**Build documented pairs list:**
-- Each pair: `{library_a, library_b, architectural_context}`
-- `architectural_context`: the quoted text or paraphrased description of their relationship
+**Mermaid limitation:** the helper skips fenced code, so an integration drawn only in a diagram is never a candidate and may surface as a false-positive gap. When an entry of `{doc_mentions}.fenced_blocks[]` has the info string `mermaid`, inform the user: "Integration paths documented exclusively in Mermaid diagrams are excluded from co-mention analysis and may appear as false-positive gaps. Consider adding prose descriptions for diagram-only integration paths." When `{doc_mentions}.fenced_only` is not empty, add: "Named only inside fenced blocks: {fenced_only}." Display this warning informatively and immediately continue: it does not halt or modify the analysis sequence.
 
 ### 2b. Establish Document Scope
 
-The skill inventory (Step 01 §2) can span a wider product surface than the architecture document under refinement. Pairs drawn from a different surface are not actionable gaps for this document — surfacing them injects irrelevant integration recommendations (e.g. wiring real-time A/V libraries into an admin-dashboard architecture).
+The skill inventory (Step 01 §2) can span a wider product surface than the architecture document under refinement, and pairs drawn from a different surface are not actionable gaps for this document (real-time A/V libraries wired into an admin-dashboard architecture, say).
 
 Resolve the in-scope skill set:
 
-- **If `{scope_skills}` was provided** (via `--scope-skills`, resolved in Step 01 §1): use it verbatim as `{in_scope_skills}` — it is authoritative.
-- **Otherwise derive:** `{in_scope_skills}` = every inventory skill whose name or primary technology is referenced anywhere in the architecture document (reuse the technology references parsed in §2; match on skill name and library/technology keywords, case-insensitive, word-boundary). Be conservative — when a skill's relevance is ambiguous, treat it as **in-scope**. Surfacing a borderline gap is safer than burying a real one.
+- **If `{scope_skills}` was provided** (via `--scope-skills`, resolved in Step 01 §1): take it as `{in_scope_skills}`: it is authoritative. §3 checks each name against the inventory and names any that is not an inventory skill, so a mistyped name is reported instead of used.
+- **Otherwise derive:** `{in_scope_skills}` = `{doc_mentions}.mentioned` plus `{doc_mentions}.fenced_only`: every inventory skill whose name or alias a body paragraph or a heading of the architecture document names, and every skill it names only inside fenced blocks, such as a diagram (the document still names it). Add an unmentioned skill only when its relevance is ambiguous (the document describes its technology without naming it, say): be conservative and treat it as **in-scope**. Surfacing a borderline gap is safer than burying a real one. A skill the document names only through a repository or folder alias that is also a common word (its `terms[]` holds only `alias` entries, such as `core`, `ai`, `sdk` or `src`, matched in "core services" or "AI features") is ambiguous too: it stays in scope, but the confirmation below lists it as ambiguous, not as named.
 
 `{out_of_scope_skills}` = inventory skills not in `{in_scope_skills}`. A library pair is **out-of-scope** when either of its libraries is in `{out_of_scope_skills}`.
 
-**Safe default:** If scope cannot be derived (e.g. the architecture references no inventory skill by name) and no `{scope_skills}` was provided, treat all skills as in-scope and note: "Could not derive document scope — analyzing all skill pairs." This keeps borderline gaps visible rather than hiding them.
+**Safe default:** If scope cannot be derived (`mentioned` and `fenced_only` are both empty: the architecture names no inventory skill) and no `{scope_skills}` was provided, treat all skills as in-scope, note: "Could not derive document scope: analyzing all skill pairs.", and record the warning `scope_fallback_all_skills: the document names no inventory skill, so every skill is in scope` with §3's command.
 
-Store `{in_scope_skills}` and `{out_of_scope_skills}` as workflow state — Step 03 (issue detection) reuses them.
+**Confirm a derived scope.** When the scope was derived (no `{scope_skills}`) and `{out_of_scope_skills}` is not empty or an in-scope skill is ambiguous, show the split once, before §4 loads the API surfaces, so the user can correct it without a re-run. A scope from `--scope-skills` is already the user's choice, and the safe default leaves no skill out, so neither shows this gate. In the Why column, `{term}` is the skill's name or the alias that names it in the document, one row of its `{doc_mentions}.skills[].terms[]` with that row's counts, so a surprising match shows.
 
-### 3. Read the Pre-Computed Library Pairs
+"**Document scope** (derived from the architecture document)
 
-Read the pre-computed unique library pairs from `skill_inventory.pairs` (the enumerate helper's `--pairs` output cached in Step 01 §2 — the complete, deterministic pair set). Do not re-derive it in-context: a silently dropped or duplicated pair is a missed integration gap, this workflow's headline output.
+| Skill | Scope | Why |
+|-------|-------|-----|
+| {skill} | In scope | {named as `{term}` in {paragraph_count} paragraph(s) and {heading_count} heading(s), or only in a fenced block; or ambiguous and kept in scope: named only as the common word `{term}`, or not named} |
+| {skill} | Out of scope | not named in the document |
 
-If `skill_inventory.pairs` is absent (the helper was unavailable and the Step 01 §2 fallback path ran), derive the pairs from the inventory as a graceful-degradation fallback only.
+Pairs, VS verdicts and improvement suggestions that involve an out-of-scope skill are listed for awareness only and stay out of the refined document.
 
-### 4. Load Skill API Surfaces for Cross-Reference
+- Type **C** to keep this scope
+- Type skill names to bring them **into** scope
+- Type **-skill_name** to take a skill **out** of scope"
+
+Display: **Select:** [C] Continue with this scope | [X] Cancel
+
+**GATE [default: C]**: present the menu and wait for the user's choice. If `{headless_mode}`: keep the derived sets and auto-proceed with [C], log: "headless: auto-confirm derived document scope (in scope: {in_scope_skills}; out of scope: {out_of_scope_skills})", giving each in-scope skill its Why from the table (the term that named it, or why it is ambiguous). Record that decision in the run sink the moment it is taken: stage `{run_dir}/decision.json` as `{"gate": "gap-analysis.scope", "default_action": "C", "taken_action": "C", "reason": "<the line logged>", "evidence": {"in_scope": [<the in-scope skills>], "out_of_scope": [<the out-of-scope skills>]}}`, then run:
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-refine-architecture --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
+
+- IF C: keep the current sets and go on with the rest of this section.
+- IF cancel / exit / [X] / q / :q: HALT (exit code 6, `halt_reason: "user-cancelled"`) at phase `gap-analysis:scope` and display "Cancelled: no refinement was performed." These global cancel tokens pre-empt the edit branch below.
+- IF the input names skills: each skill name moves that skill into `{in_scope_skills}` and each `-skill_name` moves it out; recompute `{out_of_scope_skills}`. Name any entry that is not an inventory skill, and refuse an edit that would leave `{in_scope_skills}` empty. Then redisplay the table and the menu.
+- IF anything else: answer it (a question about the split, say), then redisplay the menu.
+
+**Technologies with no skill.** `{unverified_technologies}` = `{doc_mentions}.unverified_technologies`: the technologies §2 listed that no inventory skill covers, read in `{analysis_doc}` so an earlier Refine Architecture pass never adds a name. The helper decides what a skill covers (its `technologies[]` names, for each technology, the skill, term and `kind` of each match), so no step compares a technology with a skill by hand. A `covered_by` entry of kind `alias-contained` or `name-contained` (an alias such as `ai` or `core`, or a skill name such as `react`, found only inside a longer name) does not cover the technology, which stays in `{unverified_technologies}` unless the document shows that term is that technology (`next` for Next.js, `vue` for "Vue 3"; React Native and React Query are not `react`), as the derived scope above judges common-word aliases. No step can check what the document says about these technologies: §6 names them, and Step 05 lists them in the Refinement Summary as not verified. The list depends on the inventory, not on the scope, so `--scope-skills` and the edits above leave it unchanged.
 
-<!-- Subagent delegation: read SKILL.md files in parallel, return compact JSON -->
+Store `{in_scope_skills}`, `{out_of_scope_skills}` and `{unverified_technologies}` as workflow state; §3 settles the two sets and splits the pairs by them. Step 03 (issue detection) and Step 04 (improvements) reuse the scope sets and the pair lists §3 builds, and Step 05 (compile) reuses `{unverified_technologies}`; §6 also records them all in the RA state file.
 
-For each library in the skill inventory, delegate reading to a parallel subagent. Launch up to **8 subagents concurrently** (batch larger inventories in rounds of 8).
+### 3. Split the Library Pairs by Scope
 
-**Each subagent receives one skill's SKILL.md path and:**
-1. Reads the SKILL.md file
-2. Extracts the API surface
-3. Returns only this compact JSON — no prose or extra commentary:
+The pair set is `skill_inventory.pairs`, the enumerate helper's `--pairs` output cached in Step 01 §2. Now that §2b fixed the scope, split it once with the same helper (`{enumerateStackSkillsHelper}`, resolved from `{enumerateStackSkillsProbeOrder}`):
+
+```bash
+uv run {enumerateStackSkillsHelper} scope --skills "{inventory_names}" --in-scope "{in_scope_names}"
+```
+
+`{inventory_names}` is the `name` of every `skill_inventory.skills[]` entry and `{in_scope_names}` every name in `{in_scope_skills}`, each comma-separated. The helper builds the pairs exactly as `--pairs` did and splits them:
+
+- Bind `{in_scope_skills}` ← `in_scope`, `{out_of_scope_skills}` ← `out_of_scope`, `{in_scope_pairs}` ← `in_scope_pairs` and `{out_of_scope_pairs}` ← `out_of_scope_pairs`. A pair is in scope when both of its libraries are, and each pair lands in exactly one list.
+- When `unknown` is not empty, name those entries once: "Not an inventory skill, left out of the scope: {unknown}." They come from `--scope-skills`, since a derived scope and the §2b edits hold only inventory skills. Record the warning `unknown_scope_skills: <the unknown names, comma-separated>`.
+- When `--scope-skills` named no inventory skill at all (`in_scope` is empty), apply the §2b safe default: run the command again with `{inventory_names}` as `--in-scope` too, and record the warning `scope_fallback_all_skills: --scope-skills named no inventory skill, so every skill is in scope`.
+- `pair_count` equals `skill_inventory.pair_count`. When it does not, a name was left out of `{inventory_names}`: run the command again with every name.
+- Once these bindings are final, when `{out_of_scope_skills}` is not empty, record the warning `out_of_scope_skills: <n> skills left out of the scope of this run: <the names, comma-separated>`, so every headless envelope names what this run did not check, a scope from `--scope-skills` included.
+
+Each warning goes into the run sink as it is raised, so the envelope and the result file report it (the command single-quotes it, so no warning holds a `'`):
+
+```bash
+uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning '<the warning>'
+```
+
+§5 and Step 04 §4 read these two pair lists instead of checking each pair's scope again; Step 03 §4 passes `{in_scope_skills}` to the `verdicts` join.
+
+### 4. Load Skill API Surfaces for Cross-Reference
+
+For each library in the skill inventory, delegate reading to a parallel subagent. Launch up to **8 subagents concurrently** (batch larger inventories in rounds of 8). Hand each its skill's name. Each reads that skill's `exports[]` from the `skills[]` entry of that name in `{run_dir}/skill-inventory.json` (Step 01 §2), then its SKILL.md, and its `references/*.md` for the signatures SKILL.md lacks (a split-body skill keeps its full API there), and returns only this compact JSON, with no prose:
 
 ```json
 {
   "skill_name": "...",
   "exports": ["functionName(params): ReturnType", "..."],
   "protocols": ["HTTP", "gRPC", "WebSocket", "message queue", "file I/O", "IPC"],
-  "data_formats": ["JSON", "protobuf", "CSV", "binary", "streaming"]
+  "data_formats": ["JSON", "protobuf", "CSV", "binary", "streaming"],
+  "capabilities": ["offline sync", "conflict-free merges", "..."]
 }
 ```
 
 **Extraction rules for subagents:**
-- `exports`: exported functions with signatures, exported types/interfaces/classes
-- `protocols`: any protocol indicators found in the SKILL.md
-- `data_formats`: any data format indicators found in the SKILL.md
+- `exports`: the signature of each name of that `exports[]` that SKILL.md or `references/` shows, and no name the list lacks (Step 03 reads which names exist from the file itself). Only when the list is empty (a stack skill, or `exports_source` `unknown`), extract the exported functions with signatures and the exported types, interfaces and classes from SKILL.md
+- `protocols`: any protocol indicators found in the files read
+- `data_formats`: any data format indicators found in the files read
+- `capabilities`: the capabilities and features the SKILL.md documents beyond its exports, one short phrase each
 - If a field has no matches, return an empty array `[]`
 
-**Parent collects all subagent JSON summaries.** Do not load full SKILL.md content into parent context. Store the collected summaries as `{skill_api_surfaces}` workflow state — Step 03 (issue detection) and Step 04 (improvements) reuse them exactly like `{in_scope_skills}`, rather than re-reading each SKILL.md into the parent. This §4 delegate-the-read (compact-JSON return, no full-file load in parent) is the canonical API-surface read pattern for the workflow.
+**Parent collects all subagent JSON summaries.** Do not load full SKILL.md content into parent context. Store the collected summaries as `{skill_api_surfaces}` workflow state, which Step 03 (issue detection) and Step 04 (improvements) reuse. Append them to the RA state file (`{forge_data_folder}/ra-state-{project_name}.md`) as a `<!-- [RA-SURFACES] ... -->` block too: Steps 03 and 04 read them back from it if context degrades on a long run.
 
-**From metadata.json (read in parent — lightweight), also extract:**
-- `language` — primary programming language
-- `exports` — export count and names
+**From the skill inventory (Step 01 §2), also take** each skill's `language` (the enumerate helper reads it from `metadata.json`: a string, a list of strings for a stack, or null when none is recorded). Do not open `metadata.json` in the parent.
 
 ### 5. Cross-Reference: Identify Gaps
 
-For each library pair in `skill_inventory.pairs` (from §3) not already documented in the architecture:
+For each pair in `{in_scope_pairs}` or `{out_of_scope_pairs}` (from §3) not already documented in the architecture (§2):
 
 **Check API compatibility:**
 - Does Library A export types or data that Library B can consume?
 - Do both libraries share a compatible protocol or data format?
 - Are they in the same language or is there a bridge mechanism available?
 
-**Scope routing (from §2b):** Before classifying, check the pair's scope. If the pair is **out-of-scope** (either library is in `{out_of_scope_skills}`), do not add it to the gap list even when its APIs are compatible — record it in the informational **Out-of-Scope** bucket instead (a compatible pair that belongs to a different product surface than this architecture). Only **in-scope** pairs proceed to gap classification below.
+**Scope routing (from §3):** A pair in `{out_of_scope_pairs}` does not go to the gap list even when its APIs are compatible: record it in the informational **Out-of-Scope** bucket instead. Only pairs in `{in_scope_pairs}` proceed to gap classification below.
 
 **If compatible APIs exist (in-scope pair) but NO architecture mention:**
-- Classify the gap type (Missing Integration Path, Undocumented Data Flow, or Absent Bridge Layer)
+- Type the gap by the Gap Classification of `{refinementRulesData}`
 - Document the connecting APIs from both skills
 - Propose a brief architecture section describing the integration
 
@@ -117,16 +177,19 @@ Evidence:
 Suggestion: {proposed architecture section content}
 ```
 
-**If no compatible APIs:** Skip this pair — not all pairs need to integrate.
+**If no compatible APIs:** skip the pair, since not every pair integrates.
 
 ### 6. Report Gaps & Store Findings
 
-Report the in-scope gap count, then list each gap as a row of **# / Library A / Library B / Gap Type / Connecting APIs** followed by its full §5 citation. Two signals are not inferable from the counts and must survive regardless of format:
+Report the in-scope gap count, then list each gap as a row of **# / Library A / Library B / Gap Type / Connecting APIs** followed by its full §5 citation. Three signals are not inferable from the counts and must survive regardless of format:
 
 - **N == 1 (only one skill loaded):** gap analysis is skipped — pairwise integration analysis needs ≥2 skills, and libraries without a matching skill are invisible to it. Recommend generating skills for all architecture libraries with [CS] or [QS] before re-running [RA], and note issue detection still runs.
 - **Out-of-scope compatible pairs exist (from §2b/§5):** list them separately for awareness only — they were not counted as gaps — and note that re-running with `--scope-skills` (naming the skills to include) pulls any that belong into scope.
+- **The architecture names technologies with no skill (`{unverified_technologies}` from §2b is not empty):** name them. No skill backs what the document says about them, so no step checks it; recommend generating their skills with [CS] or [QS] before re-running [RA].
+
+Store the **in-scope** gap findings under a `<!-- [RA-GAPS] ... -->` block and the out-of-scope pairs under the `<!-- [RA-OUT-OF-SCOPE] ... -->` marker, as `{findingStorageData}` says (a gap that matches one a review dropped goes under `[RA-DISMISSED]` instead).
 
-Store the **in-scope** gap findings per the Finding Storage rule (refinement rules), under a `<!-- [RA-GAPS] ... -->` block. Record out-of-scope pairs under a separate `<!-- [RA-OUT-OF-SCOPE] ... -->` marker so Step 05 leaves them out of the refined document — they are informational only.
+Append the scope under a `<!-- [RA-SCOPE] ... -->` block too: `{in_scope_skills}`, `{out_of_scope_skills}`, how the scope was set (`--scope-skills`, derived, derived then edited at the §2b confirmation, or every skill by the safe default), any name §3 reported as not an inventory skill, `{in_scope_pairs}`, `{out_of_scope_pairs}` and `{unverified_technologies}`. Step 03, Step 04 and Step 05 read the block back if context degrades on a long run.
 
 ### 7. Auto-Proceed to Next Step
 

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

@@ -1,6 +1,7 @@
 ---
 nextStepFile: 'compile.md'
 refinementRulesData: '{refinementRulesPath}'
+findingStorageData: 'references/finding-storage.md'
 ---
 
 <!-- Config: communicate in {communication_language}. Append improvement findings to the RA state file in {document_output_language}. -->
@@ -9,7 +10,7 @@ refinementRulesData: '{refinementRulesPath}'
 
 ## STEP GOAL:
 
-Identify capability expansions — library features documented in the generated skills that the architecture does not leverage. Detect unused capabilities, cross-library synergies visible from skill API surfaces, and alternative patterns that could strengthen the architecture. For each improvement, document the capability and suggest how to incorporate it.
+Identify capability expansions: library features documented in the generated skills that the architecture does not leverage, of the types and value tiers the refinement rules define. For each improvement, document the capability and suggest how to incorporate it.
 
 ## Rules
 
@@ -19,15 +20,9 @@ Identify capability expansions — library features documented in the generated
 
 ## MANDATORY SEQUENCE
 
-### 1. Reference Refinement Rules
-
-Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
-
-Extract: improvement classification (Unused Capability, Cross-Library Synergy, Alternative Pattern) and detection method.
-
 ### 2. Build Architecture Usage Map
 
-For each library referenced in the architecture document, extract how it is used:
+For each library referenced in the architecture document, extract how it is used. Read it as `{analysis_doc}`, the copy Step 01 §1b wrote with any earlier Refine Architecture pass set aside, so an old RA suggestion never reads as a capability the architecture already uses:
 
 - What capabilities are described (e.g., "Loro for real-time data sync")
 - What APIs or features are referenced
@@ -37,15 +32,15 @@ This creates a map of `{library} -> {described_usage[]}` for comparison against
 
 ### 3. Compare Skill API Surfaces Against Architecture Usage
 
-For each skill in the inventory:
+**Scope routing (from Step 02 §2b):** Apply `{in_scope_skills}` and `{out_of_scope_skills}`, and the pair lists `{in_scope_pairs}` and `{out_of_scope_pairs}` that Step 02 §3 split by them; if they are no longer in context, read them from the `[RA-SCOPE]` block of the RA state file (`{forge_data_folder}/ra-state-{project_name}.md`). An improvement or synergy that involves an out-of-scope skill, such as an in-scope capability that pays off only together with an out-of-scope skill, is not an improvement for this document even when it looks worthwhile: set it aside for the informational **Out-of-Scope** bucket (§6).
 
-**Start from the surfaces already collected.** Reuse `{skill_api_surfaces}` (the compact `{exports, protocols, data_formats}` summaries from Step 02 §4) for exports, types, and protocol support — do not re-read SKILL.md in the parent.
+For each skill in `{in_scope_skills}`:
 
-**For the fuller capability read** — documented capabilities and features that go beyond §4's exports/protocols/data_formats extraction — delegate to parallel subagents mirroring Step 02 §4 (the canonical delegate-the-read pattern): each subagent reads one SKILL.md and returns compact JSON listing that skill's documented capabilities/features; the parent collects the summaries without loading full SKILL.md content. Reload a file directly only if its summary is unavailable or context has compacted.
+**Read its surface from `{skill_api_surfaces}`**, the compact `{exports, protocols, data_formats, capabilities}` summaries Step 02 §4 collected: its exports, types and protocol support, and the capabilities and features its SKILL.md documents beyond them. If they are no longer in context, read them from the `<!-- [RA-SURFACES] ... -->` block of the same state file. Never re-read a SKILL.md, in the parent or through new subagents.
 
 **Compare against the architecture usage map:**
-- Which exports does the architecture reference or imply usage of?
-- Which exports are not referenced in the architecture at all?
+- Which exports and capabilities does the architecture reference or imply usage of?
+- Which are not referenced in the architecture at all?
 
 **For each unreferenced capability:**
 - Evaluate relevance: would this capability strengthen the architecture?
@@ -54,7 +49,7 @@ For each skill in the inventory:
 
 ### 4. Detect Cross-Library Synergies
 
-Examine pairs of skills for complementary capabilities not exploited in the architecture:
+Examine the pairs in `{in_scope_pairs}` (Step 02 §3: the pairs whose two skills are both in `{in_scope_skills}`) for complementary capabilities not exploited in the architecture. A pair in `{out_of_scope_pairs}` is out of scope: skip it. For each in-scope pair, ask:
 
 - Does Library A export an event system that Library B could consume?
 - Does Library A produce a data format that Library B has an optimized processor for?
@@ -77,16 +72,15 @@ Evidence:
 Suggestion: {how to incorporate this capability into the architecture}
 ```
 
-**Categorize improvements:**
-- **High:** Capabilities that address known architectural concerns or significantly expand functionality
-- **Medium:** Capabilities that add convenience or efficiency improvements
-- **Low:** Capabilities that are nice-to-have but not impactful
+**Type and value:** type each improvement by the Improvement Classification of `{refinementRulesData}` and give it one tier of its Improvement Value table.
 
 ### 6. Report Improvements & Store Findings
 
-Report the improvement count with its high/medium/low value breakdown, then list each improvement as a row of **# / Library / Improvement Type / Value / Summary** followed by its full §5 citation.
+Report the in-scope improvement count with its count per value tier, then list each improvement as a row of **# / Library / Improvement Type / Value / Summary** followed by its full §5 citation. One signal is not inferable from the counts and must survive regardless of format:
+
+- **Out-of-scope improvements or synergies were set aside (from §3 and §4):** list them separately for awareness only (they were not counted as improvements) and note that re-running with `--scope-skills` pulls any that belong into scope.
 
-Store the improvement findings per the Finding Storage rule (refinement rules), under a `<!-- [RA-IMPROVEMENTS] ... -->` block (its citations carry the evidence, value rating, and suggestion).
+Store the **in-scope** improvement findings under a `<!-- [RA-IMPROVEMENTS] ... -->` block (their citations carry the evidence, value tier and suggestion) and any out-of-scope improvement or synergy under the shared `<!-- [RA-OUT-OF-SCOPE] ... -->` marker, as `{findingStorageData}` says (an improvement that matches one a review dropped goes under `[RA-DISMISSED]` instead).
 
 ### 7. Auto-Proceed to Next Step