bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/{workflows/setup-forge → skf-setup}/steps-c/step-01b-ccc-index.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-01b-ccc-index'
-description: 'Ensure ccc project index exists — Forge+ and Deep tiers when ccc is available'
-
 nextStepFile: './step-02-write-config.md'
 ---
 
@@ -13,40 +10,12 @@ If ccc is available (`{ccc: true}` from step-01), configure CCC exclusion patter
 
 For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step, ensure entire file is read
-- 🎯 Execute all operations autonomously — no user interaction
-
-### Role Reinforcement:
-
-- ✅ You are a system executor verifying the ccc index state
-- ✅ ccc indexing failure is never a workflow error — degrade gracefully
-- ✅ No negative messaging for tiers that skip this step
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on ccc index verification and creation
-- 🚫 FORBIDDEN to display skip messages for Quick/Forge tiers
-- 🚫 FORBIDDEN to fail the workflow if ccc indexing fails
-- 🚫 FORBIDDEN to re-index if ccc index already exists and is fresh (< staleness threshold) UNLESS new exclusion patterns were applied to settings.yml
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Store ccc index state in context for step-02
-- 🚫 FORBIDDEN to write forge-tier.yaml — that is step-02's job
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: {ccc} boolean and {ccc_daemon} status from step-01
-- Available: {calculated_tier} from step-01
-- Available: existing forge-tier.yaml may contain prior `ccc_index` state
-- Focus: ccc index state verification and creation only
-- Dependencies: step-01 must have completed with tool detection results
+- Focus only on ccc index verification and creation
+- Do not display skip messages for Quick/Forge tiers
+- Do not fail the workflow if ccc indexing fails
+- Do not re-index if ccc index already exists and is fresh, unless new exclusion patterns were applied
 
 ## MANDATORY SEQUENCE
 
@@ -84,17 +53,15 @@ SKF infrastructure and output directories must be excluded from the CCC index
 
 **Build the SKF exclusion list:**
 
-1. Read `{project-root}/_bmad/_config/skf-manifest.yaml` to resolve configurable paths:
-   - `skills_output_folder` (default: `skills` if manifest is missing or field is absent)
-   - `forge_data_folder` (default: `forge-data` if manifest is missing or field is absent)
+1. Use `{skills_output_folder}` and `{forge_data_folder}` from the workflow activation context (resolved in On Activation from `{project-root}/_bmad/skf/config.yaml`).
 
 2. Assemble the exclusion patterns using `**/` prefix format (matching `.cocoindex_code/settings.yml` convention — e.g., `**/node_modules`):
    - `**/_bmad` — SKF framework module (workflows, agents, knowledge files)
    - `**/_bmad-output` — Build output artifacts
    - `**/.claude` — Claude Code configuration
    - `**/_skf-learn` — SKF learning materials
-   - `**/{skills_output_folder}` — Generated skill files (resolved from manifest)
-   - `**/{forge_data_folder}` — Compilation workspace (resolved from manifest)
+   - `**/{skills_output_folder}` — Generated skill files (from activation context)
+   - `**/{forge_data_folder}` — Compilation workspace (from activation context)
 
 3. Store `{ccc_exclude_patterns}` in context for step-02 to write into forge-tier.yaml.
 
@@ -119,7 +86,7 @@ If `{settings_yml_existed}` is false: the exclusions will be applied after `ccc
 
 ### 3. Create or Refresh CCC Index
 
-**If `{ccc_daemon}` is `"stopped"` or undefined (healthy daemon where no explicit state was recorded):**
+**If `{ccc_daemon}` is `"stopped"` or `"healthy"`:**
 
 The `ccc index` command auto-starts the daemon when needed. Proceed with indexing below.
 
@@ -177,26 +144,3 @@ ccc index
 
 ONLY WHEN ccc index verification is complete (or step is skipped for ccc unavailable) will you load and read fully `{nextStepFile}` to execute the configuration write step.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- ccc unavailable: skipped silently with no output, context variables set to null/none
-- ccc available with fresh index: verified freshness, exclusions configured, skipped re-index, context variables set
-- ccc available with stale/missing index: exclusions configured, index created, context variables set with fresh timestamp
-- ccc indexing fails: logged gracefully, workflow continues, context variables set to failed/null
-- Auto-proceeded to step-02
-
-### ❌ SYSTEM FAILURE:
-
-- Displaying skip messages when ccc is unavailable
-- Halting the workflow on ccc index failure
-- Re-indexing when index is already fresh and path matches (unless exclusion patterns changed)
-- Writing forge-tier.yaml (that is step-02's responsibility)
-- Not storing ccc index context variables for step-02
-- Indexing without configuring SKF exclusion patterns in `.cocoindex_code/settings.yml`
-- Overwriting user customizations in `.cocoindex_code/settings.yml` instead of appending
-
-**Master Rule:** CCC indexing is always best-effort. Failures degrade gracefully. The workflow never halts over ccc issues.

package/src/{workflows/setup-forge → skf-setup}/steps-c/step-02-write-config.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-02-write-config'
-description: 'Write forge-tier.yaml, create preferences.yaml defaults, ensure forge-data/ exists'
-
 nextStepFile: './step-03-auto-index.md'
 ---
 
@@ -11,40 +8,12 @@ nextStepFile: './step-03-auto-index.md'
 
 Write the detected tool availability and calculated tier to forge-tier.yaml, create preferences.yaml with defaults if it does not exist, and ensure the forge-data/ directory is present.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step, ensure entire file is read
-- 🎯 Execute all operations autonomously — no user interaction
-
-### Role Reinforcement:
-
-- ✅ You are a system executor writing configuration files
-- ✅ File operations must be precise — correct paths, correct YAML structure
-- ✅ Preserve user data (preferences.yaml) — never overwrite existing
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on writing configuration files and creating directories
-- 🚫 FORBIDDEN to re-detect tools — use results from step-01
-- 🚫 FORBIDDEN to overwrite existing preferences.yaml
-- 💬 File write failures ARE errors — report clearly if they occur
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Write files to the forger-sidecar directory
-- 📖 Use context from step-01 (detected_tools, calculated_tier)
-- 🚫 FORBIDDEN to proceed if forge-tier.yaml write fails
-
-## CONTEXT BOUNDARIES:
+## Rules
 
-- Available: {detected_tools}, {calculated_tier}, {previous_tier} from step-01; {ccc_index_result}, {ccc_indexed_path}, {ccc_last_indexed}, {ccc_file_count}, {ccc_exclude_patterns} from step-01b
-- Focus: file I/O operations only
-- Limits: do not modify preferences.yaml if it exists
-- Dependencies: step-01 and step-01b must have completed with tool detection and CCC index results
+- Focus only on writing configuration files and creating directories
+- Do not re-detect tools — use results from step-01
+- Do not overwrite existing preferences.yaml
+- File write failures are errors — report clearly
 
 ## MANDATORY SEQUENCE
 
@@ -56,7 +25,7 @@ Write to `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml`:
 
 ```yaml
 # Ferris Sidecar: Forge Tier State
-# Written by setup-forge workflow
+# Written by setup workflow
 
 # Tool availability (detected during [SF] Setup Forge)
 tools:
@@ -72,7 +41,7 @@ tools:
 tier: {calculated_tier}
 tier_detected_at: {current ISO timestamp}
 
-# CCC semantic index state (managed by setup-forge step-01b and extraction workflows)
+# CCC semantic index state (managed by setup step-01b and extraction workflows)
 ccc_index:
   indexed_path: {ccc_indexed_path from step-01b, or ~}
   last_indexed: {ccc_last_indexed from step-01b, or ~}
@@ -104,7 +73,7 @@ Check if `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml` exists:
 
 ```yaml
 # Ferris Sidecar: User Preferences
-# Created by setup-forge workflow on first run
+# Created by setup workflow on first run
 # Edit this file to customize Ferris behavior
 
 # Override detected tier (set to Quick, Forge, Forge+, or Deep to force a tier)
@@ -113,6 +82,12 @@ tier_override: ~
 # Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)
 passive_context: true
 
+# Headless mode (set to true to skip confirmation gates in all workflows)
+headless_mode: false
+
+# Compact greeting (set to true to skip the full capabilities table on session start)
+compact_greeting: false
+
 # Reserved for future use — these fields are not yet consumed by any workflow step
 # output_language: ~
 # skill_format_version: ~
@@ -144,25 +119,5 @@ Check if `{forge_data_folder}` directory exists:
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN forge-tier.yaml has been written successfully and preferences.yaml exists (created or pre-existing) will you load and read fully `{nextStepFile}` to execute the auto-index step.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- forge-tier.yaml written with accurate tool booleans (including ccc), tier, timestamp, ccc_index state (including exclude_patterns), and preserved qmd_collections/ccc_index_registry arrays
-- preferences.yaml exists (created with defaults on first run, preserved on re-run)
-- forge-data/ directory exists (created or pre-existing)
-- Auto-proceeded to step-03
-
-### ❌ SYSTEM FAILURE:
-
-- forge-tier.yaml write fails and workflow continues
-- preferences.yaml overwritten when it already existed
-- Incorrect tool values written (not matching step-01 detection)
-- Missing tier_detected_at timestamp
-- Re-detecting tools instead of using step-01 results
+ONLY WHEN forge-tier.yaml has been written successfully and preferences.yaml exists (created or pre-existing) will you load and read fully `{nextStepFile}` to execute the QMD hygiene step.
 
-**Master Rule:** forge-tier.yaml must be written accurately. preferences.yaml must never be overwritten. These are the foundation for all downstream workflows.

package/src/{workflows/setup-forge → skf-setup}/steps-c/step-03-auto-index.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-03-auto-index'
-description: 'Verify and clean QMD collections against the forge-tier.yaml registry (Deep tier only) and CCC index registry hygiene (Forge+/Deep)'
-
 nextStepFile: './step-04-report.md'
 ---
 
@@ -11,45 +8,15 @@ nextStepFile: './step-04-report.md'
 
 If the detected tier is Deep, verify the health of existing QMD collections by cross-referencing them against the `qmd_collections` registry in `forge-tier.yaml`. Identify orphaned collections (in QMD but not in registry) and stale registry entries (in registry but collection missing from QMD). Prompt the user before removing orphaned collections.
 
-For Quick and Forge tiers (without ccc), skip silently and proceed. For Forge+ tier, skip QMD hygiene but the step routes correctly to the next step.
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step, ensure entire file is read
-- 🎯 Execute all operations autonomously — minimal user interaction (only prompt before deletion)
-
-### Role Reinforcement:
-
-- ✅ You are a system executor performing QMD collection maintenance
-- ✅ Graceful degradation is paramount — never fail the workflow over hygiene checks
-- ✅ No negative messaging — do not mention what non-Deep tiers are missing
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on verifying and cleaning QMD collections (Deep tier) or graceful skip (other tiers)
-- 🚫 FORBIDDEN to display "missing" or "skipped" messages for non-Deep tiers
-- 🚫 FORBIDDEN to fail the workflow if QMD hygiene encounters errors
-- 🚫 FORBIDDEN to create new QMD collections — that responsibility belongs to create-skill
-- 🚫 FORBIDDEN to silently delete collections — always prompt user before removal
-- 💬 If hygiene fails: log the issue, note that it can be retried, continue
-
-## EXECUTION PROTOCOLS:
+For Quick and Forge tiers, skip silently and proceed (QMD is not available at those tiers). For Forge+ tier, skip QMD hygiene but the step routes correctly to the next step.
 
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 QMD hygiene only verifies and cleans — it does NOT index new content
-- 📖 Use {calculated_tier} from step-01 context
-- 🚫 FORBIDDEN to attempt QMD hygiene for Quick, Forge, or Forge+ tiers (Forge+ has no qmd)
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: {calculated_tier} from step-01, forge-tier.yaml written in step-02
-- Available: {project_name} from workflow config
-- Focus: QMD collection verification and cleanup only
-- Limits: only run if Deep tier
-- Dependencies: step-02 must have completed (forge-tier.yaml exists with qmd_collections registry)
+- Focus only on verifying and cleaning QMD collections (Deep tier) or graceful skip (other tiers)
+- Do not display negative framing for non-Deep tiers
+- Do not fail the workflow if QMD hygiene encounters errors
+- Do not create new QMD collections — that belongs to create-skill
+- Do not silently delete collections — always prompt user before removal
 
 ## MANDATORY SEQUENCE
 
@@ -182,29 +149,3 @@ Store in context for step-04 reporting:
 
 ONLY WHEN the hygiene check has been performed (or skipped for non-Deep tiers) will you load and read fully `{nextStepFile}` to execute the report step.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Deep tier: forge-tier.yaml registry cross-referenced with live QMD collections
-- Healthy collections identified and verified
-- Orphaned collections flagged and user prompted before removal
-- Stale registry entries cleaned from forge-tier.yaml
-- Hygiene results stored for step-04 reporting
-- Quick/Forge/Forge+ tier: skipped silently with no negative messaging
-- Workflow continues regardless of hygiene outcome
-- Auto-proceeded to step-04
-
-### ❌ SYSTEM FAILURE:
-
-- Creating new QMD collections (that's create-skill's responsibility)
-- Silently deleting collections without user prompt
-- Attempting QMD hygiene for Quick, Forge, or Forge+ tiers
-- Displaying "skipped" or "missing" messages for non-Deep tiers
-- Halting the workflow due to QMD hygiene failure
-- Indexing project directories (old auto-index behavior — removed)
-- Not proceeding to step-04 after this step
-
-**Master Rule:** This step ONLY verifies and cleans. It never indexes new content. QMD collection creation is the responsibility of create-skill. Non-Deep tiers skip silently. Always prompt before removing orphaned collections.

package/src/skf-setup/steps-c/step-04-report.md

@@ -0,0 +1,92 @@
+---
+tierRulesData: 'references/tier-rules.md'
+nextStepFile: './step-05-health-check.md'
+---
+
+# Step 4: Forge Status Report
+
+## STEP GOAL:
+
+Display the forge status report with positive capability framing and report tier changes on re-run.
+
+## Rules
+
+- Focus only on displaying the status report
+- Do not use negative framing ("missing", "lacking", "unavailable")
+- Do not list tools that are not available
+- Use tier capability descriptions from tier-rules.md
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing status report is NOT the terminal step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Capability Descriptions
+
+Load and read {tierRulesData} for the tier capability descriptions and re-run messages.
+
+### 2. Display Forge Status Report
+
+**Format the report as follows:**
+
+```
+═══════════════════════════════════════
+  FORGE STATUS
+═══════════════════════════════════════
+
+  Tier:  {calculated_tier}
+  {tier capability description from tier-rules.md}
+
+  Tools Detected:
+  {for each tool that is available, show: tool name — version}
+
+  {if hygiene_result is "completed":}
+  QMD Registry:
+  {hygiene_healthy} collection(s) healthy
+  {if hygiene_orphaned_removed > 0: {hygiene_orphaned_removed} orphaned collection(s) removed}
+  {if hygiene_orphaned_kept > 0: {hygiene_orphaned_kept} orphaned collection(s) kept}
+  {if hygiene_stale_cleaned > 0: {hygiene_stale_cleaned} stale QMD registry entry/entries cleaned}
+  {end if}
+
+  {if ccc_registry_stale_cleaned > 0:}
+  CCC Registry: {ccc_registry_stale_cleaned} stale entry/entries cleaned
+  {end if}
+
+  {if hygiene_result is "completed" and hygiene_healthy is 0:}
+  QMD Registry: empty — collections are created automatically when you run [CS] Create Skill.
+  {end if}
+
+  {if tools.ccc is true:}
+  CCC Index:
+  {if ccc_index_result is "fresh": up to date — semantic discovery ready}
+  {if ccc_index_result is "created": indexed this run — semantic discovery ready}
+  {if ccc_index_result is "failed": indexing failed — semantic discovery unavailable this session}
+  {end if}
+
+{if tier_override is active:}
+  Note: Tier override active (set in preferences.yaml)
+
+{if re-run with tier change:}
+  {appropriate upgrade/downgrade message from tier-rules.md}
+
+{if re-run with same tier:}
+  {same-tier message from tier-rules.md}
+
+═══════════════════════════════════════
+  Forge ready. {calculated_tier} tier active.
+═══════════════════════════════════════
+```
+
+**Tool display rules:**
+- Only show tools that ARE available with their version strings
+- Do NOT list unavailable tools
+- Do NOT show a "missing" column or section
+
+### 3. Chain to Health Check
+
+ONLY WHEN the forge status report has been displayed will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+
+## CRITICAL STEP COMPLETION NOTE
+
+This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the setup workflow is fully done.
+

package/src/skf-setup/steps-c/step-05-health-check.md

@@ -0,0 +1,22 @@
+---
+# `shared/health-check.md` resolves relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+# Step 5: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of setup — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-04
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-test-skill/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: skf-test-skill
+description: Cognitive completeness verification — quality gate before export. Use when the user requests to "test a skill" or "verify skill completeness."
+---
+
+# Test Skill
+
+## Overview
+
+Verifies that a skill is complete enough to be useful to an AI agent by checking coverage of the public API surface (naive mode) or validating SKILL.md + references coherence (contextual mode). Produces a completeness score and gap report as a quality gate before export. Every finding must trace to actual code with file:line citations.
+
+## Role
+
+You are a skill auditor and completeness analyst operating in Ferris's Audit mode. This is a deterministic quality gate — you bring AST-backed analysis expertise and zero-hallucination verification, while the skill artifacts provide the evidence.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Zero hallucination — every finding must trace to actual code with file:line citations
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- Update `stepsCompleted` in output file frontmatter before loading next step
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Initialize & Load Skill | steps-c/step-01-init.md | Yes |
+| 2 | Detect Mode | steps-c/step-02-detect-mode.md | Yes |
+| 3 | Coverage Check | steps-c/step-03-coverage-check.md | Yes |
+| 4 | Coherence Check | steps-c/step-04-coherence-check.md | Yes |
+| 4b | External Validators | steps-c/step-04b-external-validators.md | Yes |
+| 5 | Score | steps-c/step-05-score.md | Yes |
+| 6 | Report | steps-c/step-06-report.md | No (confirm) |
+| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | skill_name [required] |
+| **Gates** | step-06: Confirm Gate [C] |
+| **Outputs** | test-report-{skill_name}.md with completeness score and result (PASS/FAIL) |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `user_name`, `communication_language`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.

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

@@ -0,0 +1,114 @@
+# Migration & Deprecation Section Rules (§2b / §5b)
+
+> **Single source of truth.** Both `step-04-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.
+
+## Gate Check
+
+Execute this check ONLY IF both conditions are met:
+
+1. Forge tier is **Deep** (tool-gated)
+2. `{forge_data_folder}/{skill_name}/evidence-report.md` exists (data-gated)
+
+If either condition fails, skip silently and proceed to the next section.
+
+The check runs regardless of naive/contextual mode. T2-future annotations are a
+property of the source code and enrichment data, not the skill type.
+
+## Scope of Section 4b (Authoring Rule This Gate Enforces)
+
+Section 4b (SKILL.md "Migration & Deprecation Warnings") is scoped to
+*forward-looking* breaking changes only — what T2-future annotations capture.
+Current-state signature gotchas (e.g. "this function is sync not async") belong
+alongside the function in Full API Reference, **not here**.
+
+This scoping is authoritative per `skf-create-skill/assets/skill-sections.md`
+("Section 4b (Migration & Deprecation Warnings) is conditional: only emitted
+for Deep tier when T2-future annotations exist").
+
+Two legitimate exceptions for the `T2-future = 0 AND Section 4b present` case
+are formalized in the rules below:
+
+- **(a) historical migration** content — past, shipped package renames or
+  consolidated import paths that remain load-bearing for correcting model
+  training-data drift → Info severity, no justification required.
+- **(b) other non-migration content** — reviewer may downgrade to Low with
+  inline justification.
+
+Do not relax the gate otherwise — that would desync the test workflow from the
+authoring rule.
+
+## Case Rules
+
+Check whether SKILL.md contains a "Migration & Deprecation Warnings" section
+(Section 4b). Then parse `evidence-report.md`'s **YAML frontmatter** for the
+pinned `t2_future_count` field — this is the authoritative count, not the
+narrative body.
+
+**Detection contract (MANDATORY).** Read the frontmatter deterministically:
+
+```bash
+# Extract t2_future_count from frontmatter. Requires a `---` delimiter pair.
+awk '/^---$/{c++;next} c==1 && /^t2_future_count:/{print $2; exit}' \
+    {forge_data_folder}/{skill_name}/evidence-report.md
+```
+
+- **Frontmatter missing OR `t2_future_count` absent** → treat as Case 4 (see
+  below) and skip silently. Do NOT fall back to grepping prose (`grep "T2-future"`) —
+  prose drift (heading renames, alt phrasings like "forward-looking
+  annotations", capitalization variance) silently breaks detection and can
+  invert Case-1 vs Case-2/3 severity.
+- **`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`
+§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.
+
+### Case 1 — T2-future > 0 AND Section 4b absent
+
+Flag as **Medium** severity gap:
+
+> "Migration section missing — T2-future annotations exist but Section 4b is
+> not present in SKILL.md Tier 1."
+
+### Case 2 — T2-future = 0 AND Section 4b present AND content is historical migration
+
+Flag as **Info** severity (not Medium). Historical migration content covers
+completed package renames (e.g. `@oldscope/*` → `@newscope/*`), consolidated
+import paths, and shipped API cutovers that still surface in training-data
+drift — load-bearing for correcting model knowledge even though no
+forward-looking change is pending.
+
+Recognizable patterns: old-name → new-name rewrites, citations to
+already-shipped PRs/issues, "migrated in version N" or "consolidated from X to
+Y" language.
+
+Recommend in the gap report that a future skill revision rename Section 4b to
+"Import Corrections" or "Ecosystem Notes" to free the Migration & Deprecation
+heading for its forward-looking contract. No inline justification required —
+the historical-migration classification is itself the rationale.
+
+### Case 3 — T2-future = 0 AND Section 4b present AND content is non-migration
+
+Flag as **Medium** severity gap:
+
+> "Migration section unexpected — Section 4b contains non-migration content and
+> no T2-future annotations were produced."
+
+Reviewer may downgrade to Low with inline justification on a case-by-case
+basis.
+
+### Case 4 — evidence-report.md unavailable
+
+Skip silently. Record the note:
+
+> "Section 4b verification skipped — evidence-report.md not found."
+
+## Output
+
+Append any resulting finding(s) to the coherence analysis results. Both the
+naive path (§2b) and the contextual path (§5b) funnel findings into the same
+Coherence Analysis section of `{outputFile}`.