bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-test-skill/assets/output-section-formats.md

@@ -10,8 +10,8 @@
 
 ### Structural Findings
 
-| # | Type | Detail | Line |
-|---|------|--------|------|
+| # | Type | Severity | Detail | Line |
+|---|------|----------|--------|------|
 | {per-issue rows} |
 
 **Structural Issues:** {count}
@@ -44,8 +44,8 @@ Only rendered when `references/` directory exists alongside SKILL.md.
 
 ### Reference Validation
 
-| Reference | Type | Line | Target Exists | Accurate | Issues |
-|-----------|------|------|--------------|----------|--------|
+| Reference | Type | Line | Target Exists | Accurate | Severity | Issues |
+|-----------|------|------|--------------|----------|----------|--------|
 | {per-reference rows} |
 
 ### Integration Pattern Completeness
@@ -61,39 +61,45 @@ Only rendered when `references/` directory exists alongside SKILL.md.
 - **Combined Coherence:** {percentage}%
 ```
 
-## Gap Report Section
+## Ledger Record Format
 
-```markdown
-## Gap Report
+Every gap a stage finds is one JSON record in the run's gap ledger, `{forge_version}/test-findings-{run_id}.json`, appended through `scripts/gap-ledger.py append`; no stage writes gap entries into the report by hand:
 
-**Total Gaps:** {N}
-**Blocking (Critical + High):** {N}
-**Non-blocking (Medium + Low + Info):** {N}
+```json
+{
+  "severity": "Critical | High | Medium | Low | Info",
+  "category": "the category of its Gap Severity table row, such as missing-export",
+  "title": "one line",
+  "source": "file:line, or a section reference when no line applies",
+  "remediation": "the exact action that fixes the gap",
+  "issue": "what is wrong (optional)",
+  "export": "the export the gap is about (optional; set it whenever the gap is about one export)"
+}
+```
 
-### Remediation Summary
+- `severity` and `category` come from one row of the Gap Severity table in `references/scoring-rules.md`. The script refuses a category outside its vocabulary, which `uv run scripts/gap-ledger.py categories` lists.
+- `source` is a `file:line` pair whenever a line applies, with nothing after it: update-skill reads the pair as the gap's citation. A gap inside the skill package cites `SKILL.md:{line}` or `references/{file}.md:{line}`.
+- `remediation` follows the Remediation Quality Rules below and names each file it touches.
+- Leave out `id`, `group` and `stage`: the script assigns them (`GAP-{NNN}` in the order the gaps were recorded, the group from the category, the stage from `--stage`).
 
-| Severity | Count | Estimated Effort |
-|----------|-------|-----------------|
-| Critical | {N} | {description} |
-| High | {N} | {description} |
-| Medium | {N} | {description} |
-| Low | {N} | {description} |
-| Info | {N} | {description} |
-| **Total** | **{N}** | |
-```
+## Gap Report
 
-## Gap Entry Format
+`uv run scripts/gap-ledger.py render --ledger <ledger> --heading` prints the Gap Report, its effort column included, and report.md §4c writes it unchanged: it is never written by hand.
+
+## Discovery Quality Subsection
+
+Written under the Gap Report by report.md §4c:
 
 ```markdown
-### GAP-{NNN}: {Brief title}
+### Discovery Quality
 
-**Severity:** {Critical|High|Medium|Low|Info}
-**Category:** {Coverage|Coherence|Structural}
-**Source:** {file:line or section reference}
+**Discovery Test:** {PASS (3/3) | WARN (2/3) | FAIL ({N}/3 misrouted) | skipped: {reason} | not run: the hard gate blocked the run}
 
-**Issue:** {Precise description of what is wrong or missing}
+| # | Prompt | Selected Skill | Result |
+|---|--------|----------------|--------|
+| {per-prompt rows, when the test ran} |
 
-**Remediation:** {Exact action to fix this gap}
+{description optimization hints from report.md §4b.4, when any}
 ```
 
 ## Remediation Quality Rules
@@ -102,10 +108,3 @@ Only rendered when `references/` directory exists alongside SKILL.md.
 - **Bad:** "Document the missing function."
 - **Good:** "Update signature in SKILL.md line 78 from `(date: Date) => string` to `(date: Date, format?: string) => string` to match source at `src/utils.ts:42`."
 - **Bad:** "Fix the signature mismatch."
-
-## Effort Estimation Guidelines
-
-- Critical/High gaps: typically require reading source code and writing documentation
-- Medium gaps: typically require adding type definitions or interface docs
-- Low gaps: typically require adding examples or metadata
-- Info: optional improvements, no action required

package/src/skf-test-skill/customize.toml

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-test-skill.
-# Team overrides:     _bmad/custom/skf-test-skill.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-test-skill.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-test-skill.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-test-skill.user.toml
 
 [workflow]
 
@@ -10,9 +10,10 @@
 #   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 any quality-test work.
+# Steps SKILL.md On Activation step 3 runs right after the customization
+# resolve: config.yaml is loaded and headless mode resolved by then, and no
+# stage has run. Overrides append. Use for org-wide pre-flight checks (auth,
+# network, compliance) that must precede any quality-test work.
 
 activation_steps_prepend = []
 
@@ -26,11 +27,18 @@ activation_steps_append = []
 # (house style, severity policies, grading guardrails).
 # Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "Test failures of CRITICAL severity block release."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/test-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-test-skill.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
@@ -42,16 +50,22 @@ persistent_facts = [
 # without forking the skill. Empty string = use the bundled default.
 
 test_report_template_path = ""
-output_formats_path = ""
-scoring_rules_path = ""
+
+# The scoring rules and the output formats are not overridable: scripts own
+# the weights and the verdict rules, and the hard gate reads the Gap Severity
+# table, so a house-style copy could change what blocks export.
 
 # Pass threshold (percent). Precedence: CLI `--threshold=<N>` > per-pipeline
-# defaults (from init.md §1b lookup table) > this scalar > bundled fallback 80.
-# Override here to change the org-wide default without forking the skill.
+# defaults (the init.md §1b lookup table, which outranks this scalar in
+# forge-auto, forge, forge-quick and campaign runs) > this scalar > bundled
+# fallback 80. Override here to change the org-wide default without forking
+# the skill. A value above 80 is a target: a run scoring 80 or more still
+# passes through the threshold fallback (with an evidence report), while a
+# run a cap forced to FAIL stays FAIL at any threshold.
 default_threshold = 80
 
 # Optional post-finalization hook. When non-empty, the workflow invokes:
-#   <on_complete> --result-path=<path-to-skf-test-skill-result-{run_id}.json>
-# after the result JSON is finalized. Failures are recorded to
-# workflow_warnings[] but never fail the workflow. Empty = no-op.
+#   <on_complete> --result-path=<the per-run skf-test-skill-result-<YYYYMMDD-HHmmss>.json>
+# after the result JSON is finalized. A failure is shown to the user but
+# never fails the workflow. Empty = no-op.
 on_complete = ""

package/src/skf-test-skill/references/coherence-check.md

@@ -1,10 +1,18 @@
 ---
 nextStepFile: 'external-validators.md'
-outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
-outputFormatsFile: '{outputFormatsPath}'
-scoringRulesFile: '{scoringRulesPath}'
+outputFile: '{report_file}'
+outputFormatsFile: 'assets/output-section-formats.md'
+scoringRulesFile: 'references/scoring-rules.md'
 coherenceAggregationScript: 'scripts/aggregate-coherence.py'
+locateExportSegmentsScript: 'scripts/locate-export-segments.py'
 migrationSectionRules: 'references/migration-section-rules.md'
+# §6 records every gap this step finds in the run's gap ledger, which the
+# hard gate (step 4c) reads and the Gap Report is rendered from.
+ledgerFile: '{forge_version}/test-findings-{run_id}.json'
+gapLedgerScript: 'scripts/gap-ledger.py'
+# Resolve `{scanSkillMdStructureHelper}` to the first existing path (§1): both
+# modes take their structural facts, export usage counts and reference
+# checks from it, so no step greps SKILL.md by hand.
 scanSkillMdStructureProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-scan-skill-md-structure.py'
   - '{project-root}/src/shared/scripts/skf-scan-skill-md-structure.py'
@@ -18,10 +26,20 @@ scanSkillMdStructureProbeOrder:
 
 Validate internal consistency of the skill documentation. In contextual mode (stack skills): verify that all cross-references in SKILL.md point to real files, types match their declarations, and integration patterns are complete. In naive mode (individual skills): perform basic structural validation only.
 
+**Halt envelope.** Every HALT in this step names its `halt_reason` and phase and carries exit code 1. It releases the run lock first, whatever the release prints: from `{project-root}`, run `uv run {runLockHelper} release --lock "{forge_version}/.test-skill.lock" --owner "{run_owner}"` (SKILL.md Workflow Rules). In headless mode it then writes `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "skill_name": "{skill_name}", "report_path": "{report_file}"}`, adding `"path"` when the halt names one, to `{run_dir}/halt.json` and runs:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-test-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+Display the line it prints, as the run's last line, then stop. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
+
 ### 1. Check Test Mode
 
 Read `testMode` from `{outputFile}` frontmatter.
 
+**Resolve `{scanSkillMdStructureHelper}`** from `{scanSkillMdStructureProbeOrder}`; first existing path wins. Both modes run it. If no candidate exists, HALT (`halt_reason: "helper-missing"`, phase `coherence-check:scan`). Any command of it below that exits non-zero: HALT with its stderr (`halt_reason: "helper-failed"`, phase `coherence-check:scan`).
+
 **IF naive mode → Execute Naive Coherence (Section 2)**
 **IF contextual mode → Execute Contextual Coherence (Sections 3-5)**
 
@@ -29,46 +47,60 @@ Read `testMode` from `{outputFile}` frontmatter.
 
 Perform the following explicit checks (no hand-waving — most use a single deterministic script; severity assignments are binding; do not relax them).
 
-**Resolve `{scanSkillMdStructureHelper}`** from `{scanSkillMdStructureProbeOrder}`; first existing path wins. HALT if no candidate exists.
-
-**2.0 Run the structural scan.** Invoke `{scanSkillMdStructureHelper}` twice and parse the JSON outputs. These results back §§2.1, 2.2, 2.3, and 2.6 — do not re-implement those checks with grep/sed/awk loops.
+**2.0 Run the structural scan.** Invoke `{scanSkillMdStructureHelper}` (§1) twice, saving each output to the run folder. These results back §§2.1, 2.2, 2.3, 2.6 and 2.7: do not re-implement those checks with grep/sed/awk loops.
 
 ```bash
-uv run {scanSkillMdStructureHelper} scan {skill-md} --required-sections
-uv run {scanSkillMdStructureHelper} scan {skill-md}
+uv run {scanSkillMdStructureHelper} scan "{resolved_skill_package}/SKILL.md" --required-sections > "{run_dir}/required-sections.json"
+uv run {scanSkillMdStructureHelper} scan "{resolved_skill_package}/SKILL.md" > "{run_dir}/structure.json"
 ```
 
-The first call returns `{ description: {satisfied, matched_synonym, tried[]}, usage: {...}, api_surface: {...} }`. The second returns `{ unbalanced_fences, fence_count, bare_opening_fences[{line,text}], table_drift[{line,section,expected_cols,actual_cols,row}] }`. Hold both JSON blobs for the checks below.
+The first call returns `{ description: {satisfied, matched_synonym, tried[]}, usage: {...}, api_surface: {...}, frontmatter_description, outline[{line,level,text}] }`. The second returns `{ unbalanced_fences, fence_count, bare_opening_fences[{line,text}], table_drift[{line,section,expected_cols,actual_cols,row}], scripts_assets{folders[],section,missing} }`. Hold both JSON blobs, which the files keep, for the checks below.
 
 **2.1 Required sections present.** Read the first JSON blob from §2.0. For each of the three families (`description`, `usage`, `api_surface`):
 
 - `satisfied: true` → no finding.
-- `satisfied: false` AND family is `description` AND the SKILL.md frontmatter has a non-empty `description` field → no finding (the frontmatter alternative satisfies the family per the original rule).
-- Otherwise → **High severity** finding: `naive-coherence — missing required section: {family}` (the `tried[]` list from the JSON identifies which synonyms were checked: `Description`/`Overview`/`Purpose`/`Summary` for description; `Usage`/`Usage Patterns`/`Examples`/`How to use`/`Quickstart`/`Quick Start`/`Getting Started`/`Common Workflows`/`Adoption Steps` for usage; `API`/`API Surface`/`Exports`/`Key Exports`/`Public API`/`Interface`/`Reference`/`Key API Summary`/`Pattern Surface` for api_surface).
+- `satisfied: false`, family `description` and `frontmatter_description: true` (a non-empty frontmatter `description` satisfies the family) → no finding.
+- `satisfied: false` otherwise: read `outline`, each heading of the body with its line. When one heading's section serves the family (it shows how to call the library, for `usage`; it lists the library's exports, for `api_surface`; it says what the library is for, for `description`), there is no finding: name that heading and its line in the Coherence Analysis, and pass the family to §6 as `--served`. Otherwise → **High severity** finding: `naive-coherence: missing required section: {family}`.
 
-The script matches case-insensitively and tolerates `##`/`###` heading levels. SKF-template skills' headings are first-class synonyms baked into the script — the Deep/create-skill `## Quick Start`, `## Common Workflows`, and `## Key API Summary`, the quick-skill `## Usage Patterns` and `## Key Exports`, and the reference-app overrides `## Adoption Steps` (usage) and `## Pattern Surface` (api_surface) — so they all surface with `satisfied: true` and the corresponding `matched_synonym` field.
+The script matches the full heading text, case-insensitively, at any heading level, outside the frontmatter and fenced code. Its synonyms, `tried[]`, include every SKF template and override heading, so a skill built from a template reports `satisfied: true` and the `matched_synonym`.
 
-**2.2 Code fence balance.** Read `unbalanced_fences` from the second JSON blob. **`true` → High severity** finding: `naive-coherence — unbalanced code fence (unclosed block)` (the JSON's `fence_count` may be cited in the detail).
+**2.2 Code fence balance.** Read `unbalanced_fences` from the second JSON blob. **`true` → High severity** finding: `naive-coherence: unbalanced code fence (unclosed block)` (the JSON's `fence_count` may be cited in the detail).
 
-**2.3 Language tags on opening fences.** Read `bare_opening_fences[]` from the second JSON blob. The script already runs the stateful open/close scan — closing fences are never reported. For each entry, emit a **Medium severity** finding: `naive-coherence — opening code fence at line {entry.line} missing language tag`.
+**2.3 Language tags on opening fences.** Read `bare_opening_fences[]` from the second JSON blob. The script already runs the stateful open/close scan, so closing fences are never reported. For each entry, emit a **Medium severity** finding: `naive-coherence: opening code fence at line {entry.line} missing language tag`.
 
-**2.4 Exports cross-used in a usage-family section.** For each function name reported in the step 3 subagent inventory (`exports[].name` where `kind == "function"` or `kind == "method"`):
-- Determine the usage-family search scope:
-  - **Single-body skill** (no `references/` directory, or `## Full*` sections carry real content): the span from §2.1's `matched_synonym` anchor to the next `^## ` anchor.
-  - **Split-body skill** (a `references/` directory exists alongside SKILL.md AND the SKILL.md `## Full*` sections are stubs/pointers): the union of EVERY usage-family heading present in SKILL.md (`Usage`/`Usage Patterns`/`Examples`/`How to use`/`Quickstart`/`Quick Start`/`Getting Started`/`Common Workflows`/`Adoption Steps`/`Key API Summary`/`Pattern Surface`/`Key Exports`), each from its anchor to the next `^## ` anchor, PLUS the full text of every file under `references/`.
-- `grep -c "{export.name}"` across that scope and sum the counts.
-- **Zero occurrences across the entire scope → High severity** finding: `naive-coherence — exported {kind} \`{name}\` is not referenced in any usage-family section or reference file`. This catches the "documented but unused" failure mode that trivially fails discovery testing. A method referenced in any usage-family section OR any `references/` file satisfies the check.
+**2.4 Exports cross-used in a usage-family section.** The scanner counts how often each function and method export of the validated inventory (the file step 3 wrote) is used in the usage-family scope, so no name is grepped by hand:
 
-**2.5 Async/sync consistency.** For every export with `async` in its description prose (grep for `\basync\b` in the description segment), check the corresponding code example segment for `await` / `async` keywords:
-- Description says async + example shows no `await` → **High severity** finding: `naive-coherence — \`{name}\` described as async but example lacks \`await\``
-- Description says sync + example uses `await {name}` → **High severity** finding: `naive-coherence — \`{name}\` described as sync but example awaits it`
+```bash
+uv run {scanSkillMdStructureHelper} usage-scope "{resolved_skill_package}/SKILL.md" --exports "{run_dir}/inventory.json" --kinds function,method [--body single] > "{run_dir}/usage-scope.json"
+```
 
-**2.6 Table syntax.** Read `table_drift[]` from the second JSON blob (§2.0). The script normalizes escaped pipes (`\|`, used inside TypeScript union types such as `string \| undefined`) before splitting and compares each row against its header's column count, so a plain `split on |` false-positive cannot occur here. For each entry, emit a **Medium severity** finding: `naive-coherence — table row at line {entry.line} has {entry.actual_cols} columns; header has {entry.expected_cols}` (the `entry.section` and `entry.row` fields populate the detail when present).
+The script decides split-body from the `references/` folder alone; whether the `## Full*` sections are stubs is your judgment, so pass `--body single` when a `references/` directory exists but those sections carry real content. Read `zero_usage[]` from the output:
+- **Zero occurrences across the entire scope → Medium severity** finding, one per `zero_usage[]` entry: `naive-coherence: exported {kind} \`{name}\` is not referenced in any usage-family section or reference file`. This catches the "documented but unused" failure mode that trivially fails discovery testing. Like a missing export, it is a completeness gap, so it does not block the hard gate.
 
-**2.7 Scripts & Assets section.** If `{skillDir}/scripts/` or `{skillDir}/assets/` exists, `grep -n '^## Scripts' SKILL.md`:
-- Directory exists AND no `## Scripts` section → **Medium severity** finding: `naive-coherence — scripts/assets directory exists but Scripts & Assets section missing` (per `{scoringRulesFile}`)
+**2.5 Async/sync consistency.** `{locateExportSegmentsScript}` reports the facts: for each export the step 3 inventory lists with `kind` `function` or `method`, where the skill describes it (`descriptions[]`: the heading sections, table rows, list items and paragraphs that name it in code, and the signature lines that declare it) and each call to it in fenced code, with whether the call awaits it. It reads the names from the validated inventory file itself, keeping the `function` and `method` entries, so no name is copied by hand. Skip this check when the inventory has no such export; otherwise run the script (it resolves relative to the skill root):
 
-**Hard rule:** 0 findings across §§2.1–2.7 = naive coherence PASS. ≥1 finding = rerank per the severity rubric above; the count and severity list are appended to the Coherence Analysis output in §6.
+```bash
+uv run {locateExportSegmentsScript} --inventory "{run_dir}/inventory.json" --skill-dir "{resolved_skill_package}"
+```
+
+The script judges no meaning. For each `exports[]` entry, read its `descriptions[]` and decide what they assert about **this** export. The word `async` in a description decides nothing:
+
+- **async**: the caller must await what it returns (a promise, a coroutine or a future), as its signature or its description says. A Kotlin `suspend` function needs no `await`, so it makes no async claim here.
+- **sync**: it returns its result directly, for example as the blocking counterpart of an async export.
+- **no claim**: nothing says how it returns. A description that names a paired sync or async variant (`readFileSync` as "the sync counterpart of the async `readFile`"), or says async about another API, asserts nothing about this export.
+
+Then, for each export:
+
+- **async**, no call is awaited (`awaitedCount` is 0) and no unawaited call hands its result on → **High severity** finding: `naive-coherence: \`{name}\` described as async but example lacks \`await\`` (cite the first call's `file` and `line`). A call hands its result on when its `chainedMember` waits for it (`then`, `catch`, `join`, `get`), the example returns it (`return fetchData(x)` in an async function) or stores it and awaits it later: read the call lines before raising the finding.
+- **sync** and `awaitedCount` is above 0 → **High severity** finding: `naive-coherence: \`{name}\` described as sync but example awaits it` (cite the first awaited call).
+- Otherwise no finding. The names in `notCalled[]` appear in no example, so they raise none.
+
+**2.6 Table syntax.** Read `table_drift[]` from the second JSON blob (§2.0). The script normalizes escaped pipes (`\|`, used inside TypeScript union types such as `string \| undefined`) before splitting and compares each row against its header's column count, so a plain `split on |` false-positive cannot occur here. For each entry, emit a **Medium severity** finding: `naive-coherence: table row at line {entry.line} has {entry.actual_cols} columns; header has {entry.expected_cols}` (the `entry.section` and `entry.row` fields populate the detail when present).
+
+**2.7 Scripts & Assets section.** Read `scripts_assets` from the second JSON blob (§2.0): `folders` names the `scripts/` and `assets/` folders beside SKILL.md, and `section` the first heading that starts with `Scripts` (null when there is none).
+- `missing` is true (a folder exists AND no Scripts heading) → **Medium severity** finding: `naive-coherence: scripts/assets directory exists but Scripts & Assets section missing` (per `{scoringRulesFile}`)
+
+**Hard rule:** 0 findings across §§2.1–2.7 = naive coherence PASS. ≥1 finding = rerank per the severity rubric above; the count and severity list go into the Coherence Analysis section §6 writes.
 
 Build the findings list:
 
@@ -77,14 +109,14 @@ Build the findings list:
   "structural_issues": [
     {"type": "missing_section", "severity": "High", "detail": "No 'Usage' section found", "line": null},
     {"type": "unbalanced_fence", "severity": "High", "detail": "3 opening fences, 2 closing", "line": null},
-    {"type": "export_not_in_usage", "severity": "High", "detail": "exported function `formatDate` never referenced in Usage section", "line": 42},
+    {"type": "export_not_in_usage", "severity": "Medium", "detail": "exported function `formatDate` never referenced in Usage section", "line": 42},
     {"type": "async_mismatch", "severity": "High", "detail": "`fetchData` described async but example lacks await", "line": 67}
   ],
   "issues_found": 4
 }
 ```
 
-**After naive coherence → Execute Section 2b if gate conditions met, then skip to Section 6 (Append Results)**
+**After naive coherence → Execute Section 2b if gate conditions met, then skip to Section 6 (Write Results)**
 
 ### 2b. Migration/Deprecation Verification (Mode-Independent)
 
@@ -92,50 +124,57 @@ Apply rules from `{migrationSectionRules}`. That file is the single source of
 truth for the gate, scope, and case rules; §5b below applies the same rules on
 the contextual path.
 
-**After Section 2b (naive path) → Skip to Section 6 (Append Results)**
+**After Section 2b (naive path) → Skip to Section 6 (Write Results)**
 
 ### 3. Contextual Mode: Extract References
 
-Scan SKILL.md for all cross-references:
+SKILL.md's cross-references come in two kinds, and each has one owner:
+
+- **File-path and script/asset references**: every markdown link to a file (`[types](src/types.ts)`, `[guide](references/guide.md)`) and every `references/`, `scripts/` or `assets/` path mentioned in prose or inline code (`references/{file}.md`, `scripts/{file}`, `assets/{file}`), by the scanner's Reference extraction rules. Whether the target exists, and where it really lives, has one right answer, so the scanner extracts them and checks them. Any other path written outside a link (`../shared/types.ts` in inline code, an import specifier) is not checked: it usually names a file in the reader's project or a module, not one the skill ships:
 
-**Reference types to extract:**
-- File path references (`./path/to/file.ts`, `../shared/types.ts`)
-- Skill references (`See SKILL.md for {other-skill}`, `Integrates with {package}`)
-- Type imports (`import { Type } from './module'`)
-- Integration pattern references (middleware chains, plugin hooks, shared state)
-- Script/asset references (`scripts/{file}`, `assets/{file}`) in SKILL.md body
+  ```bash
+  uv run {scanSkillMdStructureHelper} reference-check "{resolved_skill_package}/SKILL.md" [--source-root "{source_path}"] [--skills-root "{skills_output_folder}"] > "{run_dir}/references.json"
+  ```
 
-Delegate to a subagent that grep/regexes SKILL.md for reference patterns and returns only this JSON shape — no prose, no commentary, no markdown fences: `{"references_found": [{"line": N, "type": "file-path|skill|type-import|integration-pattern|script-asset", "target": "..."}]}`. Parent strips wrapping markdown fences (if present) before parsing. If subagent unavailable, scan in main thread.
+  Pass `--source-root` when metadata.json records the extraction tree (`{source_path}`), and `--skills-root` for a stack skill: a stack's constituent cross-references legitimately resolve to `skills/{name}/active` under `{skills_output_folder}`, which lies outside `{skillDir}`, and a stack's metadata.json records no single `source_path` to anchor them. The scanner resolves each target against the SKILL.md folder through every symlink (`os.path.realpath`) before the root check, so a symlink that points outside every root is still caught, and gives it a `status`: `ok` (inside a root, present), `missing` (inside a root, nothing there) or `escapes` (outside every root: `../../../etc/passwd`, an absolute path to an unrelated folder, a symlink redirection outside the skill, its source or a stack's skills tree). Do not check these targets again by hand or through subagents, and do not validate an escaping target's contents: the escape itself is the finding.
+- **Skill references, type imports and integration-pattern references** (`See SKILL.md for {other-skill}`, `Integrates with {package}`, `import { Type } from './module'`, middleware chains, plugin hooks, shared state): whether one is accurate takes judgment. Delegate to a subagent that reads SKILL.md and returns only this JSON shape (no prose, no commentary, no markdown fences): `{"references_found": [{"line": N, "type": "skill|type-import|integration-pattern", "target": "..."}]}`. Parent strips wrapping markdown fences (if present) before parsing. If subagent unavailable, scan in main thread.
 
 ### 4. Contextual Mode: Validate Each Reference
 
-For EACH reference found, delegate to a subagent that:
+The scanned references need no further check: `{run_dir}/references.json` holds their statuses.
 
-1. Checks if the target exists (file exists, skill exists, type is declared)
-2. If target exists, validates the reference is accurate:
-   - File path references: file exists at specified path
+Delegate the references §3's subagent found, in one batch, to a subagent that, for each one:
+
+1. Checks if the target exists (the skill exists in the skills output folder, the type is declared, the integration point is in the code)
+2. If the target exists, validates the reference is accurate:
    - Type imports: type is actually exported from the referenced module
    - Skill references: referenced skill exists in skills output folder
    - Integration patterns: documented pattern matches actual implementation
-   - Script/asset references: verify the referenced file exists in the skill's `scripts/` or `assets/` directory
-3. Returns only this JSON shape per reference — no prose, no commentary, no markdown fences: `{"reference": "...", "line": N, "target_exists": <bool>, "type_match": <bool>, "signature_match": <bool>, "issues": ["..."]}`
-
-Parent strips wrapping markdown fences (if present) before parsing. If subagent unavailable, validate each reference in main thread.
+3. Returns only a JSON array, one object per reference, with no prose, no commentary and no markdown fences: `{"reference": "...", "line": N, "target_exists": <bool>, "type_match": <bool>, "signature_match": <bool>, "issues": ["..."]}`
 
-4. **Scripts/assets directory check:** If a `scripts/` or `assets/` directory exists alongside SKILL.md, verify that a "Scripts & Assets" section (Section 7b) is present in SKILL.md. This directory-level check applies in both modes (naive mode performs it in Section 2; contextual mode performs it here alongside per-reference validation). Flag absence as Medium severity gap per `{scoringRulesFile}`.
+Save its response, as it came back, to `{run_dir}/judged-references.json` with the Write tool (no file when §3 found no such reference). If subagent unavailable, validate each reference in main thread and save the same array. §5c counts the valid references from both files, and classifies the invalid ones.
 
-5. **Path containment:** for every resolved reference target, compute its canonical path (`os.path.realpath`) and require that it lives inside `{skillDir}`, inside `{source_path}` (the extraction tree recorded in metadata.json), OR — for stack skills — inside `{skills_output_folder}`. The third root applies only here in contextual mode: a stack's constituent cross-references legitimately resolve to `skills/{name}/active` under `{skills_output_folder}`, which lies outside `{skillDir}`, and a stack's metadata.json records no single `source_path` to anchor them. References whose canonical path escapes all applicable roots (e.g. `../../../etc/passwd`, absolute paths to unrelated dirs, symlink redirections outside the skill, its source, or — for a stack — the skills output tree) are **High severity** findings: `coherence — reference escapes skill/source sandbox: {raw_ref} → {canonical_path}`. Canonicalization happens before the root check, so a symlink that points outside every applicable root is still caught. Do not validate the target's contents for escaping references — the escape itself is the finding.
+When `scripts_assets.missing` in `{run_dir}/references.json` is true (a `scripts/` or `assets/` folder beside SKILL.md, and no Scripts & Assets section), it is a Medium `scripts-assets` gap, as in naive mode §2.7; §6 records it from that file.
 
 ### 5. Contextual Mode: Check Integration Pattern Completeness
 
 For stack skills, verify integration patterns are complete:
 
-- **All documented integration points have corresponding code examples**
+- **All documented integration points carry the wiring evidence of the stack's mode** (defined below; a fenced code example is not required)
 - **Shared types are consistently used across referenced components**
 - **Middleware/plugin chains show complete flow, not fragments**
 - **Event handlers reference valid event types**
 
-Build integration completeness findings:
+**Integration points.** Each Cross-Cutting Patterns entry and each Library Pair Integrations entry in the stack's Integration Patterns section is one integration point, and `patterns_documented` counts them. The Hub Library Connections list that create-stack-skill adds after them only summarizes each hub library's partners, so its bullets are not integration points: this section does not score them and `patterns_documented` does not count them.
+
+**Wiring evidence (first criterion).** create-stack-skill gives an integration entry no slot for a code example: the entry records a type, the wiring evidence of the stack's mode and a confidence label, so the first criterion reads that evidence. Take the stack's mode from the Confidence labels of its integration entries: the stack is compose-mode when any of them carries the `[composed]` marker (alone or extended, as in `[composed, +T2 annotations]`) or `[inferred from shared domain]`, the markers create-stack-skill puts on every compose-mode integration; otherwise it is code-mode. An integration point meets the first criterion when its entry carries the evidence of its stack's mode:
+
+- **Code mode:** at least one `file:line` citation (a source file path with a line number) where the libraries connect in the codebase, and, for a library-pair entry, a `**Key files:**` line that names at least one file.
+- **Compose mode:** one `[from skill: {skill name}]` line for each constituent skill the entry joins, citing something that skill exports. For a skill that exports functions, that is an exported function signature, the `[from skill: {skill name}] {exported_function_signature}` line of the Integration Evidence Format in `skf-create-stack-skill/references/compose-mode-rules.md`. For any other constituent (a skill whose `scope_type` is `reference-app` or `docs-only`, or whose exports are not functions), it is the export, pattern surface or documented contract the line quotes. A `[from skill: …]` line that cites nothing the skill exports does not count.
+
+A fenced code block is not required in either mode: an entry that carries its mode's evidence meets the criterion without one, and a code block does not stand in for missing evidence. When an entry fails the first criterion, name the missing evidence in its `incomplete_patterns` issue, for example `no file:line citation` or `no [from skill: …] line for {skill name}`.
+
+Build integration completeness findings, and save them to `{run_dir}/integration.json` with the Write tool (§5c reads the file):
 
 ```json
 {
@@ -151,7 +190,9 @@ Build integration completeness findings:
 }
 ```
 
-**Zero integration patterns:** If no integration patterns are documented in SKILL.md (e.g., a contextual-mode skill that uses shared types but has no middleware chains, plugin hooks, or event flows): record `patterns_documented: 0`, `patterns_complete: 0`. The coherence score will use reference validity alone — see `{scoringRulesFile}` Coherence Score Aggregation: "If no integration patterns exist, combined coherence equals reference validity."
+Each `incomplete_patterns` entry is an incomplete integration pattern, a Medium `integration-pattern` gap, with its Source at `SKILL.md:{line}` and the missing evidence as its Issue; §6 records it.
+
+**Zero integration patterns:** If no integration patterns are documented in SKILL.md (e.g., a contextual-mode skill that uses shared types but has no middleware chains, plugin hooks, or event flows): record `patterns_documented: 0`, `patterns_complete: 0`. The coherence score then uses reference validity alone: with no integration patterns, §5c's script makes combined coherence equal reference validity.
 
 ### 5b. Migration/Deprecation Verification (Contextual Path)
 
@@ -161,24 +202,55 @@ results.
 
 ### 5c. Calculate Coherence Scores
 
-**Contextual mode only.** The reference-validity ratio, the integration-completeness ratio, and their fixed 0.6 / 0.4 weighted mean are pure arithmetic — the judgment (which references are valid in §4, which patterns are complete in §5) has already happened. Do not compute these percentages by hand; they are aggregated by `{coherenceAggregationScript}` (the formulas it encodes are documented in `{scoringRulesFile}` — Coherence Score Aggregation).
+**Contextual mode only.** The reference-validity ratio, the integration-completeness ratio, and their weighted mean are pure arithmetic: the judgment (which references are valid in §4, which patterns are complete in §5) has already happened. Do not compute these percentages by hand; `{coherenceAggregationScript}` aggregates them and is the one home of the formula and its weights.
 
-Tally the counts from the §4 per-reference JSON (`valid_references` = references with `target_exists && type_match && signature_match && no issues`; `total_references` = references extracted in §3) and the §5 integration JSON (`patterns_documented`, `patterns_complete`), then invoke:
+The script counts the references itself, from the per-reference files of §3 and §4, and reads the pattern counts from the §5 file:
 
 ```bash
-echo '{"valid_references": <V>, "total_references": <T>, "patterns_documented": <PD>, "patterns_complete": <PC>}' | uv run {coherenceAggregationScript} --stdin
+uv run {coherenceAggregationScript} --references "{run_dir}/references.json" [--judged "{run_dir}/judged-references.json"] --integration "{run_dir}/integration.json" --output "{run_dir}/coherence.json"
 ```
 
-The script also accepts the JSON as a positional argument or via `--json-input`. Parse its output and read:
-- `referenceValidity` — reference-validity percentage
-- `integrationCompleteness` — integration-completeness percentage (`null` when no patterns are documented)
-- `combinedCoherence` — the combined coherence percentage passed to score.md §3a as the `coherence` input
+Exit 2 (`INVALID_INPUT`): a file does not hold the shape §3 to §5 describe; correct it (re-dispatch the §4 subagent once for its file) and run the command again. Exit 1: a file is missing or is not JSON; write it again. A second failure: HALT with its `error` (`halt_reason: "helper-failed"`, phase `coherence-check:aggregate`).
+
+`--output` also writes the result to the run folder, where step 5 hands it to the scoring script. Parse its output and read:
+- `referenceValidity`: reference-validity percentage
+- `integrationCompleteness`: integration-completeness percentage (`null` when no patterns are documented)
+- `combinedCoherence`: the combined coherence percentage, the `coherence` score step 5 reads from `{run_dir}/coherence.json`
+
+The script handles both edge cases the formula requires: `patterns_documented == 0` → `combinedCoherence` equals `referenceValidity` (no divide-by-zero); `total_references == 0` → `referenceValidity` is 100.0 (no references means no broken references). These values fill the `{percentage}%` placeholders in the output template loaded in Section 6. Its `invalidReferences[]` lists each invalid reference with its `status`, which §6 records.
+
+### 6. Write the Coherence Analysis Section
 
-The script handles both edge cases the formula requires: `patterns_documented == 0` → `combinedCoherence` equals `referenceValidity` (no divide-by-zero); `total_references == 0` → `referenceValidity` is 100.0 (no references means no broken references). These values fill the `{percentage}%` placeholders in the output template loaded in Section 6.
+Load `{outputFormatsFile}` and use the appropriate Coherence Analysis section format (naive or contextual) to write the findings in place of the template's `## Coherence Analysis` heading and the placeholder comment under it, in `{outputFile}`.
+
+Then record every coherence gap in the gap ledger `{ledgerFile}`: the hard gate (step 4c) decides from it, and the report step renders the Gap Report from it. `{gapLedgerScript}` (it resolves relative to the skill root) writes the record of each gap a script found from that script's file, with the severity and category the Gap Severity table gives it and a fixed title, Source and Remediation. Run the commands of this run's mode:
+
+- **Naive mode:** the §2.1, §2.2 and §2.5 findings are High `structural` gaps and the §2.3, §2.4 and §2.6 findings Medium `structural` gaps; the §2.7 finding is a Medium `scripts-assets` gap. The scan files give all but §2.5's, with one `--served` for each family §2.1 found served by another heading:
+
+  ```bash
+  uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coherence-check --from structure --input "{run_dir}/required-sections.json" --input "{run_dir}/structure.json" --input "{run_dir}/usage-scope.json" [--served <family>]...
+  ```
+
+- **Contextual mode:** each §5c `invalidReferences[]` entry by its `status` (`missing` is a Critical `broken-reference` gap, a missing `scripts/` or `assets/` file included; `inaccurate` a High `inaccurate-reference` gap; `escapes` a High `reference-escape` gap) and the §4 scripts/assets gap:
+
+  ```bash
+  uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coherence-check --from coherence --input "{run_dir}/coherence.json"
+  uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coherence-check --from structure --input "{run_dir}/references.json"
+  ```
+
+Then write the records no script wrote, each in the Ledger Record Format of `{outputFormatsFile}`: the §2.5 findings, titled with their `naive-coherence:` text and with their Source at `SKILL.md:{line}`; each §5 incomplete integration pattern; and in both modes a §2b / §5b migration section finding (Case 1 and Case 3 are Medium `migration-section` gaps, a Low `migration-section` gap when the reviewer downgraded Case 3 with an inline justification, and Case 2 is an Info `migration-section` gap). The split-body rows of the Reference Consistency table are not recorded here: coverage-check §1b recorded them. Write them as one JSON array on the lines between the two markers, exactly as they are: the quoted marker hands them to the script unchanged, quotes, apostrophes and `$` included. Run the command even when the array is empty (`[]`): the hard gate refuses to decide until every stage before it has recorded, with gaps or without.
+
+```bash
+uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage coherence-check <<'SKF_GAPS'
+<the records, one JSON array>
+SKF_GAPS
+```
 
-### 6. Append Coherence Analysis to Output
+Rely on the JSON of each command:
 
-Load `{outputFormatsFile}` and use the appropriate Coherence Analysis section format (naive or contextual) to append findings to `{outputFile}`.
+- Exit 0: the records are in the ledger. `appended` names the id each new record received, and `duplicates` the ones a rerun of this step had already recorded.
+- Exit 2 (`INVALID_RECORD` or `INVALID_INPUT`): nothing was written. Correct each record `errors[]` names (its `index` counts from 0), or the file or flag the `error` names, and run the command again.
+- Exit 1: HALT with the script's `error` (`halt_reason: "helper-failed"`, phase `coherence-check:ledger`).
 
 ### 7. Report Coherence Results
 
@@ -187,5 +259,5 @@ Report the coherence result to the user, then proceed to external validation:
 - **Naive mode:** the count of structural issues found (the coherence category is not scored — its weight redistributes to coverage).
 - **Contextual mode:** the reference-validity ratio, the integration-completeness ratio, the combined coherence percentage, and the issue count — full details are in the Coherence Analysis section.
 
-Update stepsCompleted, then load and execute {nextStepFile}.
+Append `'coherence-check'` to `stepsCompleted` in the `{outputFile}` frontmatter, then load and execute {nextStepFile}.
 

package/src/skf-test-skill/references/coverage-check-tiers.md

@@ -0,0 +1,35 @@
+# Coverage Check: Tier Branches
+
+Load this file only from coverage-check.md §2, and follow the one section §2 names: **Quick Tier** at Quick tier, **Fallback Per-File Scan** when the Forge-tier recipe runner cannot be used. coverage-check.md's frontmatter bindings, its run files, its per-file results and its §2 **Exits** apply here unchanged. When the section is done, continue in coverage-check.md §2 after the tier that loaded it (at Deep tier, its extra checks; otherwise States 2 to 4 and then §2b).
+
+## Quick Tier
+
+- **A skill quick-skill built** (`metadata.json` `generated_by` is `quick-skill`), **from local source** (State 1): quick-skill built its export list with `{extractPublicApiHelper}` `--mode quick`, so parse the entry points with the same parser and both sides count one surface. Resolve it ← first existing path in `{extractPublicApiProbeOrder}` and run it once per package in scope, with its manifest and one `--entry-file` for each entry-point file the Source API Surface Definition makes its surface, each path relative to `{source_path}` (`<n>` counts the packages from 1):
+
+  ```bash
+  uv run {extractPublicApiHelper} --mode quick --language <language> --source-root "{source_path}" --manifest-file <manifest path> --entry-file <entry path> > "{run_dir}/quick-<n>.json"
+  ```
+
+  Its `warnings` name each statement whose names the entry file alone cannot give. Read by eye only the statements its warnings name, save the names they give as a per-file result for the entry file that holds the statement, `{"file": "<entry path>", "exports_found": [<each name>], "signature_mismatches": []}`, and list those names in the Coverage Analysis section as read by eye. Give `surface` one `--quick` per package, one `--per-file` per saved result, the brief when the skill has one (its globs give the `scope.include` and `tier_a_include` sets), the metadata and, when init.md §2 bound one, the provenance map (the baselines of the §2b candidates and guards; they add no name):
+
+  ```bash
+  uv run {coverageInputsScript} surface --quick "{run_dir}/quick-<n>.json" [--per-file "{run_dir}/per-file-<n>.json"] [--brief "{forge_data_folder}/{skill_name}/skill-brief.yaml"] --metadata "{resolved_skill_package}/metadata.json" [--provenance "{forge_provenance_map}"] --output "{run_dir}/surface.json"
+  ```
+
+- **Any other skill** (create-skill's Quick tier reads the entry points as source text), a source that is not local, or a helper that does not resolve or exits non-zero (it exits 1 on a language it does not parse): identify the exports by reading the entry points per the Source API Surface Definition, save one per-file result per entry file, run the `surface` command above with no `--quick`, and note in the Coverage Analysis section that the Quick-tier scan read them by eye.
+
+## Fallback Per-File Scan
+
+The recipe runner cannot be used, so subagents read the files in scope one at a time. List every documented signature first: `plan` without `--surface` writes the map as `documentedSignatures`:
+
+```bash
+uv run {scoreSignaturesScript} plan --inventory "{run_dir}/inventory.json" --output "{run_dir}/signature-plan.json"
+```
+
+For each source file that defines public API exports, delegate a subagent that gets that map with the file. It extracts the file's exported symbols with their full signatures with ast-grep (or reads the file when `extraction.fallback.reason` says no ast-grep can run; list those files in the Coverage Analysis section as read by eye), compares each with the map's entry (params, return type), gives each mismatch the `line` that defines the export, and returns only `{"file", "exports_found": [...], "types_found": [<the exported interfaces, type aliases, enums and classes>], "signature_mismatches": [...]}`, each mismatch in the shape §2's signature comparison returns. Save each response to `{run_dir}/per-file-<n>.txt` with the Write tool and build the surface from them, one `--per-file` each, with the same baselines as at Quick tier:
+
+```bash
+uv run {coverageInputsScript} surface --per-file "{run_dir}/per-file-<n>.txt" [--brief "{forge_data_folder}/{skill_name}/skill-brief.yaml"] --metadata "{resolved_skill_package}/metadata.json" [--provenance "{forge_provenance_map}"] --output "{run_dir}/surface.json"
+```
+
+coverage-check.md §2b scores these responses once it has picked the denominator set.