bmad-module-skill-forge 1.4.0 → 1.5.0

package/src/skf-test-skill/{steps-c/step-04-coherence-check.md → references/coherence-check.md}

@@ -1,27 +1,20 @@
 ---
-nextStepFile: './step-04b-external-validators.md'
+nextStepFile: 'external-validators.md'
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 outputFormatsFile: 'assets/output-section-formats.md'
 scoringRulesFile: 'references/scoring-rules.md'
 migrationSectionRules: 'references/migration-section-rules.md'
+scanSkillMdStructureScript: '{project-root}/src/shared/scripts/skf-scan-skill-md-structure.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 4: Coherence Check
 
 ## STEP GOAL:
 
 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.
 
-## Rules
-
-- Use subprocess optimization: grep for references, then per-reference deep validation
-- For each reference in contextual mode, launch a subprocess to validate the target — do not shortcut
-- Analysis depth is conditional on testMode (naive vs contextual)
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Check Test Mode
 
 Read `testMode` from `{outputFile}` frontmatter.
@@ -29,40 +22,32 @@ Read `testMode` from `{outputFile}` frontmatter.
 **IF naive mode → Execute Naive Coherence (Section 2)**
 **IF contextual mode → Execute Contextual Coherence (Sections 3-5)**
 
-### 2. Naive Mode: Concrete Structural Validation (H1)
+### 2. Naive Mode: Concrete Structural Validation
 
-Perform the following explicit checks (no hand-waving — each recipe is a shell recipe or a literal pattern). Severity assignments are binding; do not relax them.
+Perform the following explicit checks (no hand-waving — most use a single deterministic script; severity assignments are binding; do not relax them).
 
-**2.1 Required sections present.** For each required top-level H2, run `grep -n "^## {section}" SKILL.md`. A required section is satisfied if **any** synonym in its set matches:
-- Description: `## Description` OR frontmatter `description` field — either satisfies
-- Usage: `## Usage` OR `## Examples` OR `## Quick Start` OR `## Common Workflows`
-- API surface: `## Exports` OR `## Key API Summary` OR `## API`
-- **Zero matches across an entire synonym set → High severity** finding: `naive-coherence — missing required section: {section-set-name}`
+**2.0 Run the structural scan.** Invoke `{scanSkillMdStructureScript}` 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.
 
-Note: SKF-template skills ship with `## Quick Start`, `## Common Workflows`, and `## Key API Summary`. These are first-class synonyms — do not downgrade to Low on literal-name miss; accept them.
+```bash
+uv run {scanSkillMdStructureScript} scan {skill-md} --required-sections
+uv run {scanSkillMdStructureScript} scan {skill-md}
+```
 
-**2.2 Code fence balance.** Count triple-backtick fences with `grep -c '^```' SKILL.md`. **Odd count → High severity** finding: `naive-coherence — unbalanced code fence (unclosed block)`.
+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.
 
-**2.3 Language tags on opening fences.** Only **opening** fences are required to carry a language tag; closing fences are bare by markdown convention and must NOT be flagged. Do not use a plain `grep -n '^```$' SKILL.md` — that flags every closing fence and produces one false positive per well-formed code block.
+**2.1 Required sections present.** Read the first JSON blob from §2.0. For each of the three families (`description`, `usage`, `api_surface`):
 
-Use a stateful open/close scan (toggle `in_code` on each `^```` line; flag only the line where `in_code` transitions 0→1 with no trailing language tag):
+- `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`/`Examples`/`How to use`/`Quickstart`/`Quick Start`/`Getting Started`/`Common Workflows` for usage; `API`/`API Surface`/`Exports`/`Public API`/`Interface`/`Reference`/`Key API Summary` for api_surface).
 
-```python
-in_code = False
-for i, line in enumerate(open('SKILL.md'), 1):
-    s = line.rstrip('\n')
-    if s.startswith('```'):
-        if not in_code:
-            if s == '```':
-                print(f'{i}: bare opening fence')
-            in_code = True
-        else:
-            in_code = False
-```
+The script matches case-insensitively and tolerates `##`/`###` heading levels. SKF-template skills' `## Quick Start`, `## Common Workflows`, and `## Key API Summary` are first-class synonyms baked into the script — they will surface with `satisfied: true` and the corresponding `matched_synonym` field.
+
+**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).
 
-**Each flagged opening fence → Medium severity** finding: `naive-coherence — opening code fence at line {N} 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 — 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 Usage section.** For each function name reported in the step-03 subagent inventory (`exports[].name` where `kind == "function"` or `kind == "method"`):
+**2.4 Exports cross-used in Usage section.** For each function name reported in the step 3 subagent inventory (`exports[].name` where `kind == "function"` or `kind == "method"`):
 - `grep -c "{export.name}" SKILL.md` restricted to the Usage section (find the `## Usage` anchor from §2.1 and the next `^## ` anchor; count within that span).
 - **Zero occurrences → High severity** finding: `naive-coherence — exported {kind} \`{name}\` is not referenced in the Usage section`. This catches the "documented but unused" failure mode that trivially fails discovery testing.
 
@@ -70,20 +55,7 @@ for i, line in enumerate(open('SKILL.md'), 1):
 - 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`
 
-**2.6 Table syntax.** `grep -nE '^\|.*\|$' SKILL.md | head` — for each table row, normalize escaped pipes (`\|`) before splitting, then verify adjacent rows have the same column count. **Escaped pipes appear inside TypeScript union types and discriminated payloads** (e.g. `string \| undefined`) and must not inflate the count.
-
-Recipe:
-
-```bash
-# Normalize `\|` to a placeholder, split on |, count, restore.
-grep -nE '^\|.*\|$' SKILL.md \
-  | sed 's/\\|/\x00/g' \
-  | awk -F'|' '{print NR, NF-2}'   # -2 drops the empty leading/trailing fields
-```
-
-Or equivalent: hand off to a proper markdown-table parser. A plain `split on |` WILL produce false "column drift" findings on any table whose cells contain union types.
-
-**Column-count drift → Medium severity** finding: `naive-coherence — table row at line {N} has {X} columns; neighboring rows have {Y}`.
+**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.** 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}`)
@@ -125,11 +97,11 @@ Scan SKILL.md for all cross-references:
 - Integration pattern references (middleware chains, plugin hooks, shared state)
 - Script/asset references (`scripts/{file}`, `assets/{file}`) in SKILL.md body
 
-Launch a subprocess to grep/regex SKILL.md for reference patterns and return all found references with line numbers as structured JSON (`references_found[]` with line, type, target fields). If subprocess unavailable, scan in main thread.
+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.
 
 ### 4. Contextual Mode: Validate Each Reference
 
-DO NOT BE LAZY — For EACH reference found, launch a subprocess that:
+For EACH reference found, delegate to a subagent that:
 
 1. Checks if the target exists (file exists, skill exists, type is declared)
 2. If target exists, validates the reference is accurate:
@@ -138,13 +110,13 @@ DO NOT BE LAZY — For EACH reference found, launch a subprocess that:
    - 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 structured validation JSON per reference (reference, line, target_exists, type_match, signature_match, issues[])
+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": ["..."]}`
 
-If subprocess unavailable, validate each reference in main thread.
+Parent strips wrapping markdown fences (if present) before parsing. If subagent unavailable, validate each reference in main thread.
 
 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}`.
 
-5. **Path containment (S8):** for every resolved reference target, compute its canonical path (`os.path.realpath`) and require that it lives inside `{skillDir}` OR inside `{source_path}` (the extraction tree recorded in metadata.json). References whose canonical path escapes both roots (e.g. `../../../etc/passwd`, absolute paths to unrelated dirs, symlink redirections outside the skill or its source) are **High severity** findings: `coherence — reference escapes skill/source sandbox: {raw_ref} → {canonical_path}`. Do NOT validate the target's contents for escaping references — the escape itself is the finding.
+5. **Path containment:** for every resolved reference target, compute its canonical path (`os.path.realpath`) and require that it lives inside `{skillDir}` OR inside `{source_path}` (the extraction tree recorded in metadata.json). References whose canonical path escapes both roots (e.g. `../../../etc/passwd`, absolute paths to unrelated dirs, symlink redirections outside the skill or its source) are **High severity** findings: `coherence — reference escapes skill/source sandbox: {raw_ref} → {canonical_path}`. Do NOT validate the target's contents for escaping references — the escape itself is the finding.
 
 ### 5. Contextual Mode: Check Integration Pattern Completeness
 
@@ -220,20 +192,5 @@ Reference validation of **{skill_name}**:
 
 **Proceeding to external validation...**"
 
-### 8. Auto-Proceed
-
-Display: "**Proceeding to external validation...**"
-
-#### Menu Handling Logic:
-
-- After coherence analysis is complete, update {outputFile} frontmatter stepsCompleted, then immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed validation step with no user choices
-- Proceed directly to next step after coherence is analyzed
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN coherence analysis is complete (naive structural or contextual full validation), the Coherence Analysis section has been appended to {outputFile}, and coherence scores (if contextual) have been calculated, will you then load and read fully `{nextStepFile}` to execute external validation.
+Update stepsCompleted, then load and execute {nextStepFile}.
 

package/src/skf-test-skill/{steps-c/step-03-coverage-check.md → references/coverage-check.md}

@@ -1,31 +1,23 @@
 ---
-nextStepFile: './step-04-coherence-check.md'
+nextStepFile: 'coherence-check.md'
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 scoringRulesFile: 'references/scoring-rules.md'
 sourceAccessProtocol: 'references/source-access-protocol.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3: Coverage Check
 
 ## STEP GOAL:
 
 Compare the exports, functions, classes, types, and interfaces documented in SKILL.md against the actual source code API surface. Identify missing documentation, undocumented exports, and signature mismatches. Analysis depth scales with forge tier.
 
-## Rules
-
-- Use subprocess optimization for per-file AST analysis when available; if unavailable, analyze sequentially
-- For each source file, launch a subprocess for deep analysis — do not shortcut
-- Coverage depth must match the detected forge tier
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 0. Check for Docs-Only Mode
 
 **If all SKILL.md citations are `[EXT:...]` format (no local source citations):**
 
-Set `docs_only_mode: true` in context for step-05 scoring. Coverage scoring adapts: instead of comparing SKILL.md against source code exports, compare SKILL.md documented items against themselves for internal completeness (every documented function has a description, parameters, and return type). Score based on documentation completeness rather than source coverage.
+Set `docs_only_mode: true` in context for step 5 scoring. Coverage scoring adapts: instead of comparing SKILL.md against source code exports, compare SKILL.md documented items against themselves for internal completeness (every documented function has a description, parameters, and return type). Score based on documentation completeness rather than source coverage.
 
 **Quick-tier weight adjustment:** If `confidence_tier` is also `"Quick"`, apply Quick-tier weight redistribution (zeroing Signature Accuracy and Type Coverage) as an additional step per `{scoringRulesFile}`.
 
@@ -80,13 +72,13 @@ test-skill is a quality gate — it MUST NOT trust subagent output blindly. Befo
 **Schema validation (required keys + types):**
 
 1. Strip wrapping markdown fences before parsing. Subagents frequently return JSON wrapped in a code fence — a line of three backticks (optionally followed by a language tag like `json`) preceding the JSON and a closing line of three backticks after it — despite prompt instructions to return raw JSON. When the first non-empty line of the response is three backticks (optionally with a language tag) and the last non-empty line is three backticks, remove those two fence lines before parsing. Then parse the remaining content as JSON. On parse failure of the inner content → HALT "coverage-check: subagent response not valid JSON".
-2. Required keys present: `exports` (list), `cross_check_mismatches` (list — may be empty). Missing key or wrong type → HALT "coverage-check: subagent JSON schema invalid — missing/typo: {key}". Note: the parent already knows the skill name from workflow context (`{resolved_skill_package}` from step-01) — the subagent is not required to echo it back, and doing so introduces a contract-drift surface without improving verification.
+2. Required keys present: `exports` (list), `cross_check_mismatches` (list — may be empty). Missing key or wrong type → HALT "coverage-check: subagent JSON schema invalid — missing/typo: {key}". Note: the parent already knows the skill name from workflow context (`{resolved_skill_package}` from step 1) — the subagent is not required to echo it back, and doing so introduces a contract-drift surface without improving verification.
 3. Each `exports[]` entry must be a dict with at minimum `name` (non-empty string) and `kind` (one of `function|class|type|constant|hook|interface|method`). Reject entries violating this; if >0 rejections, HALT "coverage-check: subagent returned malformed export entries — {count} entries do not match schema".
 4. `cross_check_mismatches[]` entries (when non-empty) must carry `export`, `skill_md_line`, `reference_file`, `reference_line`, `issue`. Missing fields → HALT.
 
 **Spot-check (ground-truth verification, zero-hallucination guard):**
 
-1. If `len(exports) == 0`: skip the spot-check (no names to verify). Zero-exports policy is handled in section 3 (B1 zero-exports guard).
+1. If `len(exports) == 0`: skip the spot-check (no names to verify). Zero-exports policy is handled in the §2b zero-exports guard.
 2. Otherwise, sample `min(3, len(exports))` exports deterministically — by default take indices `[0, len//2, len-1]` (first, middle, last) from the `exports` array after a stable sort by `name`.
 3. For each sampled export, run: `grep -n "{export.name}" {resolved_skill_package}/SKILL.md` in the parent context. The name MUST appear at least once.
 4. If ANY sampled name returns zero matches, HALT "coverage-check: subagent inventory failed ground-truth spot-check — `{name}` claimed as export but absent from SKILL.md".
@@ -125,7 +117,7 @@ Parent reads `cross_check_mismatches` from the subagent JSON summary. Build the
 }
 ```
 
-Flag each mismatch as **High severity** — signature inconsistency between SKILL.md body and reference files undermines agent trust. These findings feed into the gap report (step-06).
+Flag each mismatch as **High severity** — signature inconsistency between SKILL.md body and reference files undermines agent trust. These findings feed into the gap report (step 6).
 
 ### 2. Analyze Source Code (Tier-Dependent)
 
@@ -138,10 +130,10 @@ Start from the package entry point (see 0b) and identify the public API surface.
 - Cannot verify signatures — note as "unverified" in report
 
 **Forge Tier (ast-grep available):**
-DO NOT BE LAZY — For EACH source file that defines public API exports, launch a subprocess that:
+For EACH source file that defines public API exports, delegate to a subagent that:
 1. Uses ast-grep to extract all exported symbols with their full signatures
 2. Matches each export against the documented inventory
-3. Returns structured findings:
+3. Returns ONLY the JSON object below — no prose, no commentary, no markdown fences:
 
 ```json
 {
@@ -160,7 +152,7 @@ DO NOT BE LAZY — For EACH source file that defines public API exports, launch
 }
 ```
 
-If subprocess unavailable, perform ast-grep analysis in main thread per file.
+Parent strips wrapping markdown fences (if present) before parsing, same as §1a. If subagent unavailable, perform ast-grep analysis in main thread per file.
 
 **Deep Tier (ast-grep + gh + QMD):**
 - All Forge tier checks, plus:
@@ -168,7 +160,7 @@ If subprocess unavailable, perform ast-grep analysis in main thread per file.
 - Cross-check type definitions against their source declarations
 - Verify re-exported symbols trace to their original source
 
-### 2b. Zero-Exports Guard (B1)
+### 2b. Zero-Exports Guard
 
 After the source-code analysis (§2) completes, compute `total_exports` — the count of exports discovered in the source / provenance-map / metadata.json, per the stratified-scope and State 2 rules resolved in §4.
 
@@ -225,7 +217,7 @@ Load `{scoringRulesFile}` to determine category scores:
 
 Record the denominator source in the Coverage Analysis section as `Denominator: stratified ({effective_denominator | tier_a_include union | scope.include union}, {N} files matched)`. When stratified scope does not apply, use the standard barrel-based denominator and omit the stratified annotation.
 
-**M2 — Record the two non-chosen candidate values alongside the chosen one.**
+**Record the two non-chosen candidate values alongside the chosen one.**
 Stratified-scope resolution picks ONE of three denominator candidates
 (`stats.effective_denominator`, `tier_a_include` union, `scope.include` union)
 per the priority above. To make the choice auditable, append a
@@ -234,7 +226,7 @@ all three values — the chosen one explicitly marked and the other two recorded
 as-observed (or `absent` when the candidate was not present for this skill):
 
 ```markdown
-**Denominator Candidates** (M2 — stratified-scope audit trail):
+**Denominator Candidates** (stratified-scope audit trail):
 - `stats.effective_denominator`: {N | absent}  {← chosen if priority (1) applied}
 - `scope.tier_a_include` union: {N | absent}    {← chosen if priority (2) applied}
 - `scope.include` union: {N | absent}           {← chosen if priority (3) applied}
@@ -262,7 +254,7 @@ After the denominator has been resolved (standard, stratified, or State 2), cros
 3. `metadata.json.stats.exports_documented` — the declared documented count
 4. Provenance-map entry count (if `{forge_data_folder}/{skill_name}/provenance-map.json` exists)
 
-Cluster assignment is canonical: `skf-create-skill` step-05 derives `exports_public_api` from entry-point validation and writes the `exports[]` array from the same barrel surface (see `skf-create-skill/steps-c/step-05-compile.md:105`), while `exports_documented` tracks the broader documented surface that the provenance-map also enumerates.
+Cluster assignment is canonical: `skf-create-skill` step 5 derives `exports_public_api` from entry-point validation and writes the `exports[]` array from the same barrel surface (see `skf-create-skill/references/compile.md:105`), while `exports_documented` tracks the broader documented surface that the provenance-map also enumerates.
 
 **Intra-cluster divergence (Medium):** For each cluster, if two counts are present and disagree by more than 10% of the larger, emit a **Medium**-severity gap titled `metadata drift — {cluster} export counts diverge` (substitute `barrel` for Cluster A, `documented-surface` for Cluster B). Enumerate the offending counts in the gap body (e.g., `stats.exports_public_api=55, exports[].length=48` → 13% drift). This is the real drift signal — the two sources should mirror the same surface and they don't, so upstream extraction or compilation produced inconsistent output that a re-compile should reconcile. Classify under structural/metadata coherence regardless of naive/contextual mode.
 
@@ -311,7 +303,7 @@ Append the **Coverage Analysis** section to `{outputFile}`:
 | Signature Accuracy | {N}% or N/A |
 | Type Coverage | {N}% or N/A |
 
-Note: Weight application is deferred to step-05 where all category weights are calculated after external validation availability is known.
+Note: Weight application is deferred to step 5 where all category weights are calculated after external validation availability is known.
 ```
 
 ### 6. Report Coverage Results
@@ -328,20 +320,5 @@ Note: Weight application is deferred to step-05 where all category weights are c
 
 **Proceeding to coherence check...**"
 
-### 7. Auto-Proceed
-
-Display: "**Proceeding to coherence check...**"
-
-#### Menu Handling Logic:
-
-- After coverage analysis is complete, update {outputFile} frontmatter stepsCompleted, then immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed validation step with no user choices
-- Proceed directly to next step after coverage is analyzed
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN all source files have been analyzed, the Coverage Analysis section has been appended to {outputFile}, and category scores have been calculated, will you then load and read fully `{nextStepFile}` to execute coherence check.
+Update stepsCompleted, then load and execute {nextStepFile}.
 

package/src/skf-test-skill/{steps-c/step-02-detect-mode.md → references/detect-mode.md}

@@ -1,23 +1,16 @@
 ---
-nextStepFile: './step-03-coverage-check.md'
+nextStepFile: 'coverage-check.md'
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Detect Mode
 
 ## STEP GOAL:
 
 Examine the skill metadata to determine whether this is an individual skill (naive mode — API surface coverage only) or a stack skill (contextual mode — full coherence validation including cross-references and integration patterns).
 
-## Rules
-
-- Focus only on mode detection — do not begin coverage or coherence analysis
-- Set testMode in output frontmatter before proceeding
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Examine Skill Type
 
 Read the skill metadata (loaded in step 01) and check:
@@ -86,20 +79,5 @@ Append the **Test Summary** section to `{outputFile}`:
 
 **Proceeding to coverage check...**"
 
-### 5. Auto-Proceed
-
-Display: "**Proceeding to coverage check...**"
-
-#### Menu Handling Logic:
-
-- After mode detection is complete, update {outputFile} frontmatter stepsCompleted, then immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed detection step with no user choices
-- Proceed directly to next step after mode is set
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN testMode is set in the output frontmatter and the Test Summary section is appended to the output document, will you then load and read fully `{nextStepFile}` to execute coverage check.
+Update stepsCompleted, then load and execute {nextStepFile}.
 

package/src/skf-test-skill/{steps-c/step-04b-external-validators.md → references/external-validators.md}

@@ -1,24 +1,16 @@
 ---
-nextStepFile: './step-05-score.md'
+nextStepFile: 'score.md'
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 4b: External Validators
 
 ## STEP GOAL:
 
 Run external validation tools (`skill-check` and `tessl`) against the skill directory, capture their scores and findings, and append results to the test report. These tools catch complementary issues that internal coverage and coherence checks miss: `skill-check` validates spec compliance while `tessl` evaluates content quality and actionability.
 
-## Rules
-
-- Run each tool independently — one tool's failure does not affect the other
-- Do not halt the workflow if either tool is unavailable or fails
-- Read-only — do not modify skill content
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Resolve Skill Directory
 
 Read {outputFile} frontmatter to get the skill directory path (`skillDir`).
@@ -65,7 +57,7 @@ on the actual validator run below. If the probe exits non-zero OR the 15s
 timeout trips (exit code `124`), record `skill_check_score: N/A` and skip to
 section 3.
 
-**Run validation (S2 — 120s timeout):**
+**Run validation (120s timeout):**
 
 ```bash
 timeout 120s npx skill-check check {skillDir} --format json --no-security-scan
@@ -97,7 +89,7 @@ prevent a cold-cache fetch from stalling the workflow. If the probe exits
 non-zero OR the 15s timeout trips (exit code `124`), record
 `tessl_score: N/A` and skip to section 4.
 
-**Run review (S2 — 120s timeout):**
+**Run review (120s timeout):**
 
 The §2 probe (`npx --no-install -y tessl --version`) already resolved tessl via the caller's npm cache or a locally-installed binary on `$PATH`. Invoke the same binary for the review — do not re-pin to a registry-published version.
 
@@ -185,19 +177,5 @@ Append to `{outputFile}`:
 
 **Proceeding to scoring...**"
 
-### 7. Auto-Proceed
-
-#### Menu Handling Logic:
-
-- After external validation is complete, update {outputFile} frontmatter stepsCompleted, then immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed validation step with no user choices
-- Tool unavailability is a skip, not a halt
-- Proceed directly to next step after external validation
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN external validation results are appended to {outputFile} and scores are stored in context will you proceed to load `{nextStepFile}` for scoring.
+Update stepsCompleted, then load and execute {nextStepFile}.
 

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

@@ -0,0 +1,14 @@
+---
+# `{nextStepFile}` is resolved by probing both candidate roots in order.
+# HALT if neither exists — step 6 §7 should have caught this already, but
+# this step re-asserts the invariant at dispatch time.
+nextStepFileProbeOrder:
+  - '{project-root}/_bmad/skf/shared/health-check.md'
+  - '{project-root}/src/shared/health-check.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 7: Workflow Health Check
+
+Probe `{nextStepFileProbeOrder}` in order; load and execute the first path that exists as `{nextStepFile}`, else HALT with a diagnostic naming both candidate paths. This is the terminal step of test-skill.

package/src/skf-test-skill/{steps-c/step-01-init.md → references/init.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-02-detect-mode.md'
+nextStepFile: 'detect-mode.md'
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 templateFile: 'templates/test-report-template.md'
 sidecarFile: '{sidecar_path}/forge-tier.yaml'
@@ -13,27 +13,24 @@ frontmatterScriptProbeOrder:
 versionPathsKnowledge: 'knowledge/version-paths.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Initialize Test
 
 ## STEP GOAL:
 
 Discover and validate the target skill, load forge tier state to determine analysis depth, and create the test report document from template.
 
-## Rules
-
-- Focus only on input discovery and validation — do not begin analysis
-- Validate all required files exist before proceeding
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Receive Skill Path
 
 If skill path was provided as workflow argument, use it directly.
 
 **Recognized flags on the invocation:**
 - `--allow-workspace-drift` — bypass the section 5b pre-flight guard that halts when local workspace HEAD does not match `metadata.source_commit`. Store `allow_workspace_drift: true` in workflow context when present. No effect when `source_commit` is unpinned or the source is not a git working tree.
+- `--no-discovery` — skip the §4b Discovery Testing block in step 6 (report). Store `no_discovery: true` in workflow context when present.
+- `--no-health-check` — skip the §7 health-check dispatch in step 6 (report). Store `no_health_check: true` in workflow context when present.
+- `--tier=<Quick|Forge|Forge+|Deep>` — bypass the §4 forge-tier.yaml sidecar HALT. Store `tier_flag: '<value>'` in workflow context when present; §4 will set `detected_tier` directly from this value and skip the sidecar probe.
+- `--threshold=<N>` — override the pass threshold for this run. Consumed by `references/score.md` §1; CLI wins over the `workflow.default_threshold` scalar.
 
 If no path provided, ask:
 
@@ -99,10 +96,10 @@ timeout 30s uv run {frontmatterScript} {resolved_skill_package}/SKILL.md --skill
 
 If the command trips the 30s wall-clock (exit code `124`), set
 `analysis_confidence: degraded` and `toolingStatus: frontmatter-validator-timeout`
-in workflow context, apply the step-05 tooling-degraded cap (score capped at
+in workflow context, apply the step 5 tooling-degraded cap (score capped at
 `threshold - 1` → auto-FAIL), and record the reason in evidence-report.
 
-Parse the JSON output. Per B2, treat each `status` value explicitly:
+Parse the JSON output. Treat each `status` value explicitly:
 
 - `status: "pass"` — continue silently.
 - `status: "warn"` — display the warning below, log each issue as a pre-check finding, and continue with testing. Frontmatter issues surface in the gap report alongside coverage/coherence findings.
@@ -116,18 +113,20 @@ Parse the JSON output. Per B2, treat each `status` value explicitly:
 This skill will fail `npx skills add` and `npx skill-check check`. {If warn:} Consider fixing frontmatter before proceeding (run `npx skill-check check <skill-dir> --fix` to auto-fix deterministic issues). {If fail:} test-skill cannot proceed — halt and repair frontmatter, then re-run.
 ```
 
-**3c. Python runtime probe.** Before the first invocation, confirm both `python3` AND `uv` are on `$PATH` (`command -v python3` and `command -v uv`). Both are required: `uv run` shells through to `python3` under the hood AND honors the script's PEP 723 PyYAML dependency declaration that bare `python3` ignores. If either is missing, set `analysis_confidence: degraded` in workflow context and carry a **score cap** into step-05: `capped_score = threshold - 1` → forces auto-FAIL until the runtime is restored. Record the reason in evidence-report and the test report frontmatter (`analysisConfidence: degraded`, `toolingStatus: python3-missing` or `uv-missing` as appropriate). `uv` is a documented runtime prerequisite — see `docs/getting-started.md` for install instructions.
+**3c. Python runtime probe.** Before the first invocation, confirm both `python3` AND `uv` are on `$PATH` (`command -v python3` and `command -v uv`). Both are required: `uv run` shells through to `python3` under the hood AND honors the script's PEP 723 PyYAML dependency declaration that bare `python3` ignores. If either is missing, set `analysis_confidence: degraded` in workflow context and carry a **score cap** into step 5: `capped_score = threshold - 1` → forces auto-FAIL until the runtime is restored. Record the reason in evidence-report and the test report frontmatter (`analysisConfidence: degraded`, `toolingStatus: python3-missing` or `uv-missing` as appropriate). `uv` is a documented runtime prerequisite — see `docs/getting-started.md` for install instructions.
 
 ### 4. Load Forge Tier State
 
-Read `{sidecarFile}` to determine available analysis depth.
+**`--tier=<...>` flag bypass (precedes the sidecar probe).** If `tier_flag` is set in workflow context (from §1's `--tier=<Quick|Forge|Forge+|Deep>` flag), validate the value against the allowed set. On valid match: set `detected_tier` directly to the flag's value, leave `ast_grep`/`gh_cli`/`qmd` availability flags unset (downstream steps treat unset as "unknown" — analysis proceeds without tool-specific enrichment), log Info note "tier — supplied via --tier flag, sidecar bypassed", and SKIP the sidecar probe and HALT below (jump straight to §4b "Apply Tier Override"). On invalid value (not one of the four), HALT with "Error: --tier=<value> is not one of Quick, Forge, Forge+, Deep".
+
+**Otherwise (no `--tier` flag):** Read `{sidecarFile}` to determine available analysis depth.
 
 **If forge-tier.yaml exists:**
 - Read `tier` value (Quick, Forge, Forge+, or Deep)
 - Read tool availability flags (ast_grep, gh_cli, qmd)
 
 **If forge-tier.yaml missing:**
-"**Cannot proceed.** forge-tier.yaml not found at `{sidecarFile}`. Please run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+"**Cannot proceed.** forge-tier.yaml not found at `{sidecarFile}`. Please run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep), or re-run with `--tier=<Quick|Forge|Forge+|Deep>` to bypass the sidecar."
 
 HALT — do not proceed.
 
@@ -154,7 +153,7 @@ Test-skill reads `source_path` during coverage and coherence analysis. If the lo
 
 - Resolve `pinned_commit` from `metadata.source_commit`.
 - **If `pinned_commit` is null, empty, or `"local"`:** skip the guard; log `workspace_drift_check: skipped (no pinned commit)` and continue to section 6.
-- **If `pinned_commit` is a per-repo map (stack skills):** iterate each `{repo_path: commit}` entry — for each repo run `git -C "{repo_path}" rev-parse HEAD` and compare to its pinned commit (accept full-SHA or short-SHA-prefix match). If ANY repo diverges and the user did not pass `--allow-workspace-drift`, HALT with exit status `halted-for-workspace-drift` listing every mismatched repo. On all-match: log `workspace_drift_check: ok (stack, {N} repos verified)` and continue to section 6. Per B6, this guard MUST iterate every repo — do not skip stack skills.
+- **If `pinned_commit` is a per-repo map (stack skills):** iterate each `{repo_path: commit}` entry — for each repo run `git -C "{repo_path}" rev-parse HEAD` and compare to its pinned commit (accept full-SHA or short-SHA-prefix match). If ANY repo diverges and the user did not pass `--allow-workspace-drift`, HALT with exit status `halted-for-workspace-drift` listing every mismatched repo. On all-match: log `workspace_drift_check: ok (stack, {N} repos verified)` and continue to section 6. This guard MUST iterate every repo — do not skip stack skills.
 - **If `source_path` is not a git working tree** (bare checkout, tarball extract, docs-only source) — detect by `git -C "{source_path}" rev-parse --is-inside-work-tree`, non-zero exit means skip: log `workspace_drift_check: skipped (not a git working tree)` and continue to section 6.
 - **Otherwise** run `git -C "{source_path}" rev-parse HEAD` and compare to `pinned_commit`. Accept full-SHA or short-SHA-prefix match (stored pins are often 8-char short hashes — see `src/knowledge/provenance-tracking.md`).
   - **On match:** log `workspace_drift_check: ok ({short_sha})` and continue.
@@ -177,15 +176,15 @@ Test-skill reads `source_path` during coverage and coherence analysis. If the lo
     ```
 
     Do not proceed. The test report has not been created; no partial writes.
-  - **On mismatch WITH `--allow-workspace-drift`:** log `workspace_drift_check: overridden (pinned={pinned_commit}, head={head_sha})`, carry the warning into the final report frontmatter (`workspaceDrift: overridden`), and set `allow_workspace_drift: true` in workflow context (consumed by step-05 §5 M5 — a PASS under drift is demoted to `pass-with-drift` and `nextWorkflow` is forced to `update-skill`, never `export-skill`). Continue.
+  - **On mismatch WITH `--allow-workspace-drift`:** log `workspace_drift_check: overridden (pinned={pinned_commit}, head={head_sha})`, carry the warning into the final report frontmatter (`workspaceDrift: overridden`), and set `allow_workspace_drift: true` in workflow context (consumed by step 5 §5 drift override — a PASS under drift is demoted to `pass-with-drift` and `nextWorkflow` is forced to `update-skill`, never `export-skill`). Continue.
 
 ### 6. Create Output Document
 
-**6a. Generate `{run_id}`** per B5: a per-run identifier of the form `{YYYYMMDDTHHmmssZ}-{pid}-{rand4}` (UTC timestamp + process PID + 4-char random hex). Store in workflow context. All per-run artifacts in this and subsequent steps MUST carry this suffix; step-06 verifies `testDate` in the resulting report matches the run's stamp and fail-fast otherwise.
+**6a. Generate `{run_id}`**: a per-run identifier of the form `{YYYYMMDDTHHmmssZ}-{pid}-{rand4}` (UTC timestamp + process PID + 4-char random hex). Store in workflow context. All per-run artifacts in this and subsequent steps MUST carry this suffix; step 6 verifies `testDate` in the resulting report matches the run's stamp and fail-fast otherwise.
 
-**6b. Acquire the per-skill test lock** (B4): `flock {forge_version}/.test-skill.lock` for the duration of this run to serialize concurrent `skf-test-skill` invocations against the same skill. If the lock is already held by another run, HALT with "another test-skill run is active for {skill_name}".
+**6b. Acquire the per-skill test lock**: `flock {forge_version}/.test-skill.lock` for the duration of this run to serialize concurrent `skf-test-skill` invocations against the same skill. If the lock is already held by another run, HALT with "another test-skill run is active for {skill_name}".
 
-**6c. Create `{outputFile}` from `{templateFile}`** — use `{forge_version}/test-report-{skill_name}-{run_id}.md` per B5. Initial frontmatter:
+**6c. Create `{outputFile}` from `{templateFile}`** — use `{forge_version}/test-report-{skill_name}-{run_id}.md` Initial frontmatter:
 
 ```yaml
 ---
@@ -202,7 +201,7 @@ analysisConfidence: '{full|degraded}'
 toolingStatus: '{ok|python3-missing|uv-missing|frontmatter-validator-missing|frontmatter-validator-timeout}'
 workspaceDrift: '{not-checked|ok|overridden}'
 testDate: '{run_id timestamp ISO-8601 UTC}'
-stepsCompleted: ['step-01-init']
+stepsCompleted: ['init']
 nextWorkflow: ''
 ---
 ```
@@ -219,20 +218,5 @@ nextWorkflow: ''
 
 **Proceeding to mode detection...**"
 
-### 8. Auto-Proceed
-
-Display: "**Proceeding to mode detection...**"
-
-#### Menu Handling Logic:
-
-- After initialization is complete, update {outputFile} frontmatter stepsCompleted, then immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed initialization step with no user choices
-- Proceed directly to next step after setup
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN all required files are validated, forge tier is loaded, output document is created, and initialization status is reported, will you then load and read fully `{nextStepFile}` to execute mode detection.
+Update stepsCompleted, then load and execute {nextStepFile}.
 

package/src/skf-test-skill/references/migration-section-rules.md

@@ -1,6 +1,8 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Migration & Deprecation Section Rules (§2b / §5b)
 
-> **Single source of truth.** Both `step-04-coherence-check.md` §2b (naive path)
+> **Single source of truth.** Both `coherence-check.md` §2b (naive path)
 > and §5b (contextual path) apply the rules in this file verbatim. Update this
 > file — not the step file sections — when the rule set changes.
 
@@ -62,7 +64,7 @@ awk '/^---$/{c++;next} c==1 && /^t2_future_count:/{print $2; exit}' \
 - **`t2_future_count` parsed** → use its integer value for the Case Rules
   below.
 
-The pinned field is emitted by `skf-create-skill/steps-c/step-05-compile.md`
+The pinned field is emitted by `skf-create-skill/references/compile.md`
 §7 (frontmatter-pinned fields), which ALWAYS writes `t2_future_count: N`
 (including 0). Legacy skills whose `evidence-report.md` predates the pinned
 field land in Case 4.