bmad-module-skill-forge 1.4.1 → 1.5.0

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

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-02-write-config.md'
+nextStepFile: 'write-config.md'
 # Resolve `{mergeCccExclusionsHelper}` by probing `{mergeCccExclusionsProbeOrder}`
 # in order (installed SKF module path first, src/ dev-checkout fallback); first
 # existing path wins. HALT if neither resolves — the script owns config-value
@@ -16,7 +16,7 @@ mergeCccExclusionsProbeOrder:
 
 ## STEP GOAL:
 
-If ccc is available (`{ccc: true}` from step-01), invoke `{mergeCccExclusionsHelper}` to validate config-driven SKF exclusion patterns and merge them into `.cocoindex_code/settings.yml`, then verify the project's ccc index exists and create or refresh it if needed. Store index state and exclusion-merge results in context for step-02 to write into forge-tier.yaml and for step-04 to surface in the JSON envelope.
+If ccc is available (`{ccc: true}` from step 1), invoke `{mergeCccExclusionsHelper}` to validate config-driven SKF exclusion patterns and merge them into `.cocoindex_code/settings.yml`, then verify the project's ccc index exists and create or refresh it if needed. Store index state and exclusion-merge results in context for step 2 to write into forge-tier.yaml and for step 4 to surface in the JSON envelope.
 
 For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
 
@@ -31,49 +31,34 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 ### 1. Check Eligibility
 
-Read `{ccc}` from step-01 context.
+Read `{ccc}` and `{ccc_skip_index}` from context.
 
 **If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: [], ccc_exclusion_warnings: [], settings_yml_written: false, settings_yml_patterns_added: 0}`. Proceed directly to section 4 (Auto-Proceed) — no output, no messaging.
 
-**If `{ccc}` is true:** Continue to section 2.
+**If `{ccc}` is true AND `{ccc_skip_index}` is true:** Run the exclusion-merge (section 3) so settings.yml stays current, then set `{ccc_index_result: "skipped", ccc_indexed_path: null, ccc_last_indexed: null}` and proceed to section 4 — do NOT run `ccc init` or `ccc index`. The envelope's `ccc_index.status` will be `"skipped"` so pipelines that plan an out-of-band re-index can distinguish "the operator opted out" from "indexing failed".
 
-### 2. Check Existing Index State
-
-Read existing forge-tier.yaml at `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml` (if it exists from a previous run).
+**If `{ccc}` is true AND `{ccc_skip_index}` is false:** Continue to section 2.
 
-Read `staleness_threshold_hours` from `ccc_index.staleness_threshold_hours` in the existing forge-tier.yaml (default: 24 if not present or not a number). Use this value for the freshness check below.
-
-Check the `ccc_index` section:
+### 2. Check Existing Index State
 
-- If `ccc_index.indexed_path` matches `{project-root}` AND `ccc_index.status` is `"fresh"` or `"created"`:
-  - Check freshness: if `ccc_index.last_indexed` is within `staleness_threshold_hours` of now → index is fresh
-  - Store `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: {existing timestamp}}`
-  - Set `{needs_reindex: false}` — exclusions still get merged in section 3, which may force a re-index
+Consume prior CCC state from stage 1's detector output (`prior.previous_ccc_*` context flags) — no YAML re-parse here, the detector already read forge-tier.yaml. Use `prior.previous_ccc_staleness_threshold_hours` if set, else default 24 hours.
 
-- If `ccc_index.indexed_path` matches `{project-root}` but timestamp is older than threshold:
-  - Set `{needs_reindex: true}`
+Decide `{needs_reindex}` and `{ccc_index_result}` from those flags:
 
-- If `ccc_index` is missing, has null values, or path doesn't match:
-  - Set `{needs_reindex: true}`
+- If `previous_ccc_indexed_path` matches `{project-root}` AND `previous_ccc_index_status` is `"fresh"` or `"created"` AND `previous_ccc_last_indexed` is within `staleness_threshold_hours` of now → index is fresh. Set `{needs_reindex: false}`, `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: <existing timestamp>}`. Exclusions still merge in section 3 (which may force a re-index).
+- If path matches but the timestamp is older than threshold, or if the path doesn't match, or if any prior CCC field is null → `{needs_reindex: true}`.
 
 ### 3. Merge SKF Exclusion Patterns
 
 SKF infrastructure and output directories must be excluded from the CCC index — they contain workflow instructions, build artifacts, and generated skills that pollute semantic search results with zero extraction value.
 
-**Pre-process the config values before invocation.** `skills_output_folder` and `forge_data_folder` come from `{project-root}/_bmad/skf/config.yaml` as template strings literally containing `{project-root}` (e.g. `'{project-root}/skills'`, `'{project-root}/forge-data'`). The merge helper interpolates each value into a `**/{value}` glob, so passing the raw template produces the malformed pattern `**/{project-root}/skills`. Before invoking the helper:
-
-1. Substitute `{project-root}` in each value with the resolved absolute project root.
-2. Reduce the substituted value to its last path segment (basename) — `**/skills`, `**/forge-data` are the patterns the script is designed to emit. Sub-paths under `{project-root}` (e.g. `_bmad-output/forge-data`) keep the segments below `{project-root}` (`_bmad-output/forge-data`), not the full absolute path.
-
-Concretely: given `skills_output_folder: '{project-root}/skills'`, pass `skills`. Given `forge_data_folder: '{project-root}/_bmad-output/forge-data'`, pass `_bmad-output/forge-data`. The script's PR #248 validator rejects unresolved placeholders (`{`, `}`) and absolute paths (`/abs/...`) as a backstop, but the step is responsible for delivering values the script can interpolate cleanly — surfacing a warning and silently dropping the pattern is worse than getting the pre-processing right here.
-
-Run the merge helper, forwarding the **resolved** config values. Invoke via `uv run` so PEP 723 inline metadata resolves the script's PyYAML dependency automatically (per `docs/getting-started.md`'s prereq list — uv exists for this exact purpose). Bare `python3` will fail on a fresh Python with `ModuleNotFoundError: No module named 'yaml'`.
+Forward `skills_output_folder` and `forge_data_folder` from `{project-root}/_bmad/skf/config.yaml` **verbatim** — the script resolves `{project-root}/...` template strings and rejects absolute paths / placeholders / glob meta-chars internally. The step does no string surgery; that work moved into the helper. Invoke via `uv run` so PEP 723 inline metadata resolves the script's PyYAML dependency automatically (per `docs/getting-started.md`'s prereq list — uv exists for this exact purpose). Bare `python3` will fail on a fresh Python with `ModuleNotFoundError: No module named 'yaml'`.
 
 ```bash
 uv run {mergeCccExclusionsHelper} \
     --project-root "{project-root}" \
-    --skills-output-folder "{resolved_skills_basename}" \
-    --forge-data-folder "{resolved_forge_data_path}"
+    --skills-output-folder "{skills_output_folder}" \
+    --forge-data-folder "{forge_data_folder}"
 ```
 
 The script (see `src/shared/scripts/skf-merge-ccc-exclusions.py` docstring for the full schema) builds the SKF exclusion list (4 always-include hardcoded patterns + 2 conditional from validated config), applies the PR #248 validation rules to reject empty / absolute / glob-meta config values with actionable warnings, and performs an idempotent set-union merge into `{project-root}/.cocoindex_code/settings.yml`. User customizations are preserved. When the file does not exist yet (first-time setup before `ccc init`) the script creates it; when nothing new needs adding the script skips the write entirely (mtime preserved).
@@ -83,8 +68,8 @@ The script (see `src/shared/scripts/skf-merge-ccc-exclusions.py` docstring for t
 - `{settings_yml_existed}` ← `settings_yml_existed`
 - `{settings_yml_written}` ← `written`
 - `{settings_yml_patterns_added}` ← `patterns_added`
-- `{ccc_exclude_patterns}` ← derive from the script's behaviour: it always merges the 4 always-include patterns plus any of the 2 config-driven ones whose value passed validation. Step-02 needs this list to write `ccc_index.exclude_patterns` into forge-tier.yaml — read it from the script's `patterns_added_list` PLUS any already-present matching SKF patterns inferred from the input. Pragmatically: re-derive the list as `["**/_bmad", "**/_bmad-output", "**/.claude", "**/_skf-learn"]` plus `"**/{skills_output_folder}"` if no warning names `skills_output_folder` plus `"**/{forge_data_folder}"` if no warning names `forge_data_folder`.
-- `{ccc_exclusion_warnings}` ← `warnings` (a list — step-04 folds them into the envelope's warnings array)
+- `{ccc_exclude_patterns}` ← `effective_patterns` (the script returns the final, sorted, deduplicated SKF pattern set after validation — consume verbatim; do NOT re-derive in prose).
+- `{ccc_exclusion_warnings}` ← `warnings` (a list — step 4 folds them into the envelope's warnings array)
 
 **If `{settings_yml_written}` is true** (new patterns merged into settings.yml): set `{needs_reindex: true}` — new exclusions require re-indexing for the index to reflect them. Display: "**CCC exclusions configured:** {patterns_added} SKF patterns applied to .cocoindex_code/settings.yml"
 
@@ -127,7 +112,7 @@ ccc index
 
 **If fails:**
 
-- Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null, ccc_indexing_failed_reason: {error}}` (the failed-reason flag flows into step-04's envelope warnings)
+- Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null, ccc_indexing_failed_reason: {error}}` (the failed-reason flag flows into step 4's envelope warnings)
 - Display: "CCC indexing failed: {error}. Extraction will use direct AST scanning — semantic pre-ranking unavailable this session."
 - Continue — this is NOT a workflow error
 

package/src/skf-setup/{steps-c/step-01-detect-and-tier.md → references/detect-and-tier.md}

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-01b-ccc-index.md'
+nextStepFile: 'ccc-index.md'
 # Resolve `{detectToolsHelper}` by probing `{detectToolsProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves — the script is the source of truth for
@@ -27,17 +27,14 @@ Verify availability of the four forge tools (ast-grep, gh, qmd, ccc), read any e
 
 ### 1. Check for Existing Configuration (Re-run Detection)
 
-**Read existing forge-tier.yaml** at `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml`:
-
-- If exists: store the current `tier` value as `{previous_tier}`, `tier_detected_at` as `{previous_detection_date}`, and the `tools` map as `{previous_tools}` (for the tool-set delta detection step-04 needs to surface newly-installed tools on same-tier re-runs).
-- If not found: set `{previous_tier}` to null and `{previous_tools}` to an empty map (first run).
+Prior state lives in two files; the detector helper (§2) reads forge-tier.yaml itself when invoked with `--prior-state-from`, so this section only handles preferences.yaml directly and the first-run preamble.
 
 **Read existing preferences.yaml** at `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml`:
 
 - If exists: check for `tier_override` value
 - If not found: set `{tier_override}` to null
 
-**First-run preamble** — when `{previous_tier}` is null AND `{headless_mode}` is `false`, display this preamble before continuing so the user knows what is about to happen and can abort cleanly with Esc / Ctrl+C before any writes:
+**First-run preamble** — when the prior-state read (§2 below, `prior.previous_tier`) returns null AND `{headless_mode}` is `false`, display this preamble before continuing so the user knows what is about to happen and can abort cleanly with Esc / Ctrl+C before any writes. (When `{headless_mode}` is true, skip the preamble entirely — pipelines never need it.)
 
 "**About to set up the forge.** This workflow will:
 
@@ -53,7 +50,7 @@ Press Esc or Ctrl+C now if this isn't the right project — no files have been w
 
 ### 2. Run Detection Helper
 
-Build the Bash invocation. Start with `uv run {detectToolsHelper}` — `uv run` honors the script's PEP 723 inline-metadata dependency declarations (resolved automatically on first call; cached thereafter), which is why uv is documented as a runtime prerequisite in `docs/getting-started.md`. Do NOT call the script via bare `python3` — `python3` ignores PEP 723 metadata, and on a fresh interpreter without the declared deps installed system-wide the call fails with `ModuleNotFoundError`. If `{tier_override}` is non-null, append `--tier-override "{tier_override}"` (the script handles invalid values by flagging them — do NOT pre-validate). If `{require_tier}` (resolved in On Activation) is non-null, append `--require-tier "{require_tier}"`. Then execute.
+Build the Bash invocation: `uv run {detectToolsHelper} --prior-state-from "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"`. If `{tier_override}` is non-null, append `--tier-override "{tier_override}"`. If `{require_tier}` is non-null, append `--require-tier "{require_tier}"`. Then execute. (The script's PEP 723 metadata is why `uv run` is required — bare `python3` skips dependency resolution.)
 
 The script (see `src/shared/scripts/skf-detect-tools.py` docstring for the full `DETECT_OUTPUT_SCHEMA`) probes ast-grep / gh / qmd / ccc concurrently with two-step verification for qmd and ccc (binary-identity check + daemon-health check, including the `CocoIndex Code` identity-marker substring check that rejects PATH-shadowing aliases). It applies the 4-rule tier table, performs the tier-override sanity check (override is honored but flagged unsafe when underlying tools are missing), and evaluates `--require-tier` using a tool-prerequisite check (Deep does NOT subsume Forge+ — Deep does not require ccc). Output is one JSON document on stdout.
 
@@ -68,7 +65,7 @@ From `tools`:
 - `{gh_cli}` ← `tools.gh_cli.available`
 - `{gh_cli_version}` ← `tools.gh_cli.version`
 - `{qmd}` ← `tools.qmd.available`
-- `{qmd_status}` ← `tools.qmd.status` (`"absent" | "daemon_stopped" | "healthy"` — drives the climb-hint distinction in step-04)
+- `{qmd_status}` ← `tools.qmd.status` (`"absent" | "daemon_stopped" | "healthy"` — drives the climb-hint distinction in step 4)
 - `{qmd_version}` ← `tools.qmd.version`
 - `{ccc}` ← `tools.ccc.available`
 - `{ccc_daemon}` ← `tools.ccc.daemon` (`"healthy" | "stopped" | "error" | null`)
@@ -82,15 +79,31 @@ From `tier`:
 - `{tier_override_active}` ← `tier.override_applied`
 - `{tier_override_invalid}` ← `tier.override_invalid`
 - `{tier_override_invalid_value}` ← `tier.override_invalid_value`
-- `{tier_override_invalid_suggestion}` ← `tier.override_invalid_suggestion` (closest valid tier name from a fuzzy match — `null` when no candidate cleared the cutoff or when override is valid; consumed by step-04's invalid-override note as a "did you mean ...?" hint)
+- `{tier_override_invalid_suggestion}` ← `tier.override_invalid_suggestion` (closest valid tier name from a fuzzy match — `null` when no candidate cleared the cutoff or when override is valid; consumed by step 4's invalid-override note as a "did you mean ...?" hint)
 - `{tier_override_unsafe}` ← `tier.override_unsafe`
-- `{tier_override_unsafe_missing}` ← `tier.override_unsafe_missing` (a list — step-04 joins with `", "` for display)
+- `{tier_override_unsafe_missing}` ← `tier.override_unsafe_missing` (a list — step 4 joins with `", "` for display)
 
 From `require_tier`:
 
 - `{require_tier_satisfied}` ← `require_tier.satisfied` (`true | false | null`; null when `--require-tier` was not set)
 - `{require_tier_failure_missing_tools}` ← `require_tier.missing_tools` (a list)
 
+From `prior` (populated by `--prior-state-from`; all fields null/empty on first run):
+
+- `{previous_tier}` ← `prior.previous_tier`
+- `{previous_detection_date}` ← `prior.previous_detection_date`
+- `{previous_tools}` ← `prior.previous_tools`
+- `{previous_ccc_index_status}` ← `prior.previous_ccc_index_status`
+- `{previous_ccc_indexed_path}` ← `prior.previous_ccc_indexed_path`
+- `{previous_ccc_last_indexed}` ← `prior.previous_ccc_last_indexed`
+- `{previous_ccc_staleness_threshold_hours}` ← `prior.previous_ccc_staleness_threshold_hours`
+
+From `deltas` (computed by the script from current tools + prior; eliminates LLM-side set arithmetic in the report banner):
+
+- `{tools_added}` ← `deltas.tools_added` (the list)
+- `{tools_removed}` ← `deltas.tools_removed` (the list)
+- `{tier_changed}` ← `deltas.tier_changed` (boolean)
+
 **The script is the source of truth.** Every tier-rules edge case (override-honored-but-unsafe, Deep-doesn't-subsume-Forge+, qmd-binary-vs-daemon distinction, ccc-identity-marker rejection of foreign binaries) is locked into the test suite at `test/test-skf-detect-tools.py`. Substituting prose-driven logic for the script's output here will cause subtle re-run regressions that the prompt's prose is no longer detailed enough to catch.
 
 ### 4. Auto-Proceed

package/src/skf-setup/{steps-c/step-05-health-check.md → references/health-check.md}

@@ -15,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-04
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 4
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 

package/src/skf-setup/{steps-c/step-04-report.md → references/report.md}

@@ -1,6 +1,6 @@
 ---
 tierRulesData: 'references/tier-rules.md'
-nextStepFile: './step-05-health-check.md'
+nextStepFile: 'health-check.md'
 # Resolve `{emitEnvelopeHelper}` by probing `{emitEnvelopeProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves when the headless envelope must be emitted
@@ -31,9 +31,9 @@ Display the forge status report with positive capability framing, surface tier c
 
 ## Headless Mode Display Rule
 
-When `{headless_mode}` is `true`, sections 2 (the human-readable banner) and 3 (the REQUIRED TIER NOT MET human prose block) are **skipped entirely**. The single line of stdout in headless mode is the `SKF_SETUP_RESULT_JSON: {…}` envelope from section 4 — every signal the human banner would have surfaced is already in the envelope (`tier`, `previous_tier`, `tier_changed`, `tools`, `tools_added`, `tools_removed`, `files_written`, `tier_override_*`, `require_tier_satisfied`, `warnings`, `error`). Parent skills and CI pipelines consume one parseable line; they should not be forced to scroll past 30 lines of ASCII-art they cannot use.
+When `{headless_mode}` is `true` OR `{quiet_mode}` is `true`, sections 2 (the human-readable banner) and 3 (the REQUIRED TIER NOT MET human prose block) are **skipped entirely**. The single line of stdout in those modes is the `SKF_SETUP_RESULT_JSON: {…}` envelope from section 4 — every signal the human banner would have surfaced is already in the envelope (`tier`, `previous_tier`, `tier_changed`, `tools`, `tools_added`, `tools_removed`, `files_written`, `tier_override_*`, `require_tier_satisfied`, `warnings`, `error`). Parent skills, CI pipelines, and expert re-runners consume the envelope alone; they should not be forced to scroll past 30 lines of ASCII-art they cannot use.
 
-When `{headless_mode}` is `false`, sections 2 and 3 display normally and section 4 is skipped (interactive runs read the human banner; envelope emission would just be log noise).
+When both `{headless_mode}` and `{quiet_mode}` are `false`, sections 2 and 3 display normally and section 4 is skipped (interactive runs read the human banner; envelope emission would just be log noise).
 
 ## MANDATORY SEQUENCE
 
@@ -41,7 +41,7 @@ When `{headless_mode}` is `false`, sections 2 and 3 display normally and section
 
 Load and read {tierRulesData} for the tier capability descriptions and re-run messages. Needed by section 2; safe to load unconditionally — the data load itself is silent.
 
-### 2. Display Forge Status Report (skip when `{headless_mode}` is true)
+### 2. Display Forge Status Report (skip when `{headless_mode}` or `{quiet_mode}` is true)
 
 **Format the report as follows:**
 
@@ -80,7 +80,11 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {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.
+  QMD Registry: empty — collections are created automatically when you run /skf-create-skill.
+  {end if}
+
+  {if hygiene_result is "qmd_unavailable":}
+  QMD Registry: skipped (daemon error — retry after `qmd start`).
   {end if}
 
   {if tools.ccc is true:}
@@ -95,9 +99,7 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {if preferences_yaml_created is true:}
   - preferences.yaml — {project-root}/_bmad/_memory/forger-sidecar/preferences.yaml (first-run defaults)
   {end if}
-  {if forge_data_dir_created is true:}
-  - {forge_data_folder}/ (directory created)
-  {end if}
+  - {forge_data_folder}/ (directory ensured)
   {if settings_yml_written is true:}
   - .cocoindex_code/settings.yml — {project-root}/.cocoindex_code/settings.yml ({settings_yml_patterns_added} SKF exclusion pattern(s) merged)
   {end if}
@@ -119,13 +121,13 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
            rely on the missing tool(s) will fail at runtime. Install the missing tool(s) or remove
            the override from preferences.yaml.
 
-{if re-run with tier change:}
+{if {tier_changed} is true:}
   {appropriate upgrade/downgrade message from tier-rules.md}
 
-{if re-run with same tier and {tools_added} is empty and {tools_removed} is empty:}
+{if {tier_changed} is false and {tools_added} is empty and {tools_removed} is empty and {previous_tier} is non-null:}
   {same-tier message from tier-rules.md}
 
-{if re-run with same tier and ({tools_added} or {tools_removed} is non-empty):}
+{if {tier_changed} is false and ({tools_added} or {tools_removed} is non-empty):}
   Tier unchanged: {calculated_tier}.
   {if {tools_added} non-empty:} Newly detected: {comma-separated tool names from tools_added}{if ccc was added and tier is Deep: " — ccc enhances Deep tier transparently."}
   {if {tools_removed} non-empty:} No longer detected: {comma-separated tool names from tools_removed} — re-install to restore those capabilities.
@@ -135,10 +137,10 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
 ═══════════════════════════════════════
 
 {if {headless_mode} is false:}
-  Next: try [BS] Brief Skill to scope your first compilation target, or [QS] Quick Skill for a fast template-driven path. Already have a skill? [AS] Audit Skill drift-checks an existing skill against current sources.
+  Next: try `/skf-brief-skill` to scope your first compilation target, or `/skf-quick-skill` for a fast template-driven path. Already have a skill? `/skf-audit-skill` drift-checks an existing skill against current sources.
 ```
 
-The same-tier-with-tool-deltas branch reads `{tools_added}` and `{tools_removed}` directly from step-01's context (set from `skf-detect-tools.py` output relative to `{previous_tools}`). No LLM-side recomputation.
+All re-run-delta context flags (`{tools_added}`, `{tools_removed}`, `{tier_changed}`) come from the detector's `deltas` block bound in stage 1 — no LLM-side recomputation, no set arithmetic in prose.
 
 **Tool display rules:**
 
@@ -146,9 +148,9 @@ The same-tier-with-tool-deltas branch reads `{tools_added}` and `{tools_removed}
 - Do NOT list unavailable tools
 - Do NOT show a "missing" column or section
 
-### 3. Display Required-Tier Failure Block (when applicable; skip when `{headless_mode}` is true)
+### 3. Display Required-Tier Failure Block (when applicable; skip when `{headless_mode}` or `{quiet_mode}` is true)
 
-If `{require_tier_satisfied}` is `false` AND `{headless_mode}` is `false`, display this block immediately after the status report. In headless mode the failure surfaces via the envelope's `require_tier_satisfied: false` and the synthesized `warnings` entry — the human prose block would be log noise that pipelines have to scroll past.
+If `{require_tier_satisfied}` is `false` AND both `{headless_mode}` and `{quiet_mode}` are `false`, display this block immediately after the status report. In headless or quiet modes the failure surfaces via the envelope's `require_tier_satisfied: false` and the synthesized `warnings` entry — the human prose block would be log noise.
 
 When the block does fire (interactive run with require-tier failure):
 
@@ -170,7 +172,7 @@ This block exists to make pipeline failures visible without the operator parsing
 
 ### 4. Emit Headless JSON Envelope
 
-When `{headless_mode}` is `true`, build the context payload from this step's accumulated flags and forward it to `{emitEnvelopeHelper}` on stdin. Invoke via `uv run` so the script's PEP 723 dependency declarations are honored (the canonical runtime invocation per `docs/getting-started.md`'s uv prereq — bare `python3` skips the metadata block and breaks on a fresh interpreter). The script computes derived fields (`tools_added`, `tools_removed`, `tier_changed`, `warnings`), validates the assembled envelope against the JSON Schema at `src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`, and emits the single prefixed line `SKF_SETUP_RESULT_JSON: {…}` on stdout.
+When `{headless_mode}` is `true` OR `{quiet_mode}` is `true`, build the context payload from this step's accumulated flags and forward it to `{emitEnvelopeHelper}` on stdin. Invoke via `uv run` so the script's PEP 723 dependency declarations are honored (the canonical runtime invocation per `docs/getting-started.md`'s uv prereq — bare `python3` skips the metadata block and breaks on a fresh interpreter). The script computes derived fields (`tools_added`, `tools_removed`, `tier_changed`, `warnings`), validates the assembled envelope against the JSON Schema at `src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`, and emits the single prefixed line `SKF_SETUP_RESULT_JSON: {…}` on stdout.
 
 ```bash
 echo '{
@@ -205,12 +207,12 @@ echo '{
 }' | uv run {emitEnvelopeHelper} emit
 ```
 
-The script's documented context-payload shape (see `src/shared/scripts/skf-emit-result-envelope.py` docstring) tolerates two `tools` shapes — bare booleans OR `skf-detect-tools.py`'s `{key: {available: bool, ...}}` output — so either step-01's normalized booleans OR the raw detect-tools output forwarded as-is will produce the correct envelope.
+The script's documented context-payload shape (see `src/shared/scripts/skf-emit-result-envelope.py` docstring) tolerates two `tools` shapes — bare booleans OR `skf-detect-tools.py`'s `{key: {available: bool, ...}}` output — so either step 1's normalized booleans OR the raw detect-tools output forwarded as-is will produce the correct envelope.
 
 **If the script exits non-zero:** the assembled envelope failed schema validation, which means a context flag from an earlier step is malformed. Surface the error to stderr and continue (the human-readable banner is already displayed; missing JSON envelope on a headless run is a degraded but non-fatal state — the pipeline observer will see no envelope and treat that as "agent did not complete cleanly").
 
-**When `{headless_mode}` is `false`, do NOT invoke the script** — interactive runs read the human-readable banner.
+**When both `{headless_mode}` and `{quiet_mode}` are `false`, do NOT invoke the script** — interactive runs read the human-readable banner.
 
 ### 5. Chain to Health Check
 
-After the forge status report (and any failure block + JSON envelope) has been displayed, load `{nextStepFile}`, read it fully, and execute it — UNLESS `{require_tier_satisfied}` is `false`, in which case halt the workflow here without chaining to step-05. The health-check step is the true terminal step on success — do not stop after the report on a passing run even though it reads as final. step-05 in turn delegates to `shared/health-check.md`; after that returns, the setup workflow is fully done.
+After the forge status report (and any failure block + JSON envelope) has been displayed, load `{nextStepFile}`, read it fully, and execute it — UNLESS `{require_tier_satisfied}` is `false`, in which case halt the workflow here without chaining to step 5. The health-check step is the true terminal step on success — do not stop after the report on a passing run even though it reads as final. step 5 in turn delegates to `shared/health-check.md`; after that returns, the setup workflow is fully done.

package/src/skf-setup/references/tier-rules.md

@@ -7,7 +7,7 @@
 | ast-grep | `ast-grep --version` | Returns version string without error |
 | gh | `gh --version` | Returns version string without error |
 | qmd | `qmd status` | Returns status indicating initialized and operational |
-| ccc | Step A: `ccc --help` Step B: `ccc doctor` | Step A: exits 0 AND help output identifies the binary as cocoindex-code. Step B: daemon healthy. See `steps-c/step-01-detect-and-tier.md` §7 for the full identity-marker procedure. |
+| ccc | Step A: `ccc --help` Step B: `ccc doctor` | Step A: exits 0 AND help output identifies the binary as cocoindex-code. Step B: daemon healthy. See `references/detect-and-tier.md` §7 for the full identity-marker procedure. |
 
 **Important:** Use verification commands, not existence checks (`which`, `command -v`). A tool must be functional, not just present on PATH. For daemon-based tools (ccc), verify both binary identity and daemon health — a binary with the right name but the wrong implementation is a false positive, not a tool.
 

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

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-03-auto-index.md'
+nextStepFile: 'auto-index.md'
 # Resolve `{forgeTierRwHelper}` by probing `{forgeTierRwProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves — the script owns the canonical
@@ -10,6 +10,12 @@ nextStepFile: './step-03-auto-index.md'
 forgeTierRwProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
   - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
+# Resolve `{emitEnvelopeHelper}` for the headless/quiet blocked-envelope emit
+# on write failures (the regular envelope assembly happens in step 4, but
+# write halts never reach step 4 — see section 1's blocked-emit protocol).
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Halt-on-write-failure messages render in the user's language. -->
@@ -23,7 +29,7 @@ Write the detected tool availability and calculated tier to `forge-tier.yaml` (p
 ## Rules
 
 - Focus only on writing configuration files and creating directories
-- Do not re-detect tools — use results from step-01
+- Do not re-detect tools — use results from step 1
 - Never inline a YAML template for forge-tier.yaml or preferences.yaml — the script owns the canonical format
 - File write failures are errors — report clearly and halt the workflow
 
@@ -31,7 +37,7 @@ Write the detected tool availability and calculated tier to `forge-tier.yaml` (p
 
 ### 1. Write forge-tier.yaml
 
-Build the JSON payload from context flags set by step-01 and step-01b. The payload must include `tools`, `tier`, and `ccc_index`; the script handles `tier_detected_at` defaulting to "now" if absent and preserves `qmd_collections`, `ccc_index_registry`, and a user-customized `ccc_index.staleness_threshold_hours` from any existing file.
+Build the JSON payload from context flags set by step 1 and step 1b. The payload must include `tools`, `tier`, and `ccc_index`; the script handles `tier_detected_at` defaulting to "now" if absent and preserves `qmd_collections`, `ccc_index_registry`, and a user-customized `ccc_index.staleness_threshold_hours` from any existing file.
 
 Invoke via `uv run` so the script's PEP 723 PyYAML dependency resolves automatically (this is what `docs/getting-started.md`'s uv prereq exists for). Bare `python3` would fail on a fresh interpreter with `ModuleNotFoundError`.
 
@@ -59,13 +65,13 @@ echo '{
 
 The script atomically writes the file via temp + fsync + rename (mirrors `skf-atomic-write.py`'s crash-safety contract) and returns a JSON response with `wrote`, `preserved_arrays.qmd_collections` count, `preserved_arrays.ccc_index_registry` count, and the resolved `tier`.
 
-**Parse the response and set context flags for step-04:**
+**Parse the response and set context flags for step 4:**
 
 - `{forge_tier_yaml_path}` ← `wrote`
 - `{forge_tier_qmd_collections_count}` ← `preserved_arrays.qmd_collections`
 - `{forge_tier_ccc_registry_count}` ← `preserved_arrays.ccc_index_registry`
 
-**If the script exits non-zero**: parse the stderr JSON `{"status":"error","message":...}`, set `{error: {phase: "step-02:write-tools", path: "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml", reason: <message>}}` for step-04's envelope, and halt the workflow before chaining to step-03.
+**If the script exits non-zero**: parse the stderr JSON `{"status":"error","message":...}`, set `{error: {phase: "step 2:write-tools", path: "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml", reason: <message>}}`, and halt the workflow before chaining to step 3. When `{headless_mode}` or `{quiet_mode}` is true, first pipe the same `{phase, reason, path}` payload to `python3 {emitEnvelopeHelper} emit-blocked` so the pipeline sees the blocked envelope before the halt (see `references/report.md` frontmatter for the helper probe order; the subcommand declares zero dependencies).
 
 ### 2. Initialize preferences.yaml
 
@@ -76,20 +82,15 @@ uv run {forgeTierRwHelper} init-prefs \
 
 The script creates the file with first-run defaults (matching the prior inline template — `tier_override: ~`, `passive_context: true`, `headless_mode: false`, `compact_greeting: false`, plus reserved-for-future-use commented fields) IF the file does not exist. When the file already exists, the script refuses to overwrite (preserves user customization) and reports `wrote: false`.
 
-**Parse the response and set context flags for step-04:**
+**Parse the response and set context flags for step 4:**
 
 - `{preferences_yaml_created}` ← `wrote` (true on first run, false on re-run when the file pre-existed)
 
-**If the script exits non-zero**: same halt-and-report pattern as section 1, with `phase: "step-02:init-prefs"` and the matching path.
+**If the script exits non-zero**: same halt-and-blocked-envelope-emit pattern as section 1, with `phase: "step 2:init-prefs"` and the matching path.
 
 ### 3. Ensure forge-data/ Directory
 
-Check if `{forge_data_folder}` directory exists:
-
-- If missing: create it. Store `{forge_data_dir_created: true}` in context.
-- If exists: skip silently. Store `{forge_data_dir_created: false}` in context.
-
-If the create fails (parent unwritable, disk full, permission denied), set `{error: {phase: "step-02:forge-data-dir", path: "{forge_data_folder}", reason: <error message>}}` for step-04's envelope and halt the workflow.
+Run `mkdir -p {forge_data_folder}`. The `-p` flag is idempotent (creates parents, exits 0 if the directory already exists), so the prompt does no existence-check reasoning. On non-zero exit, halt with the same blocked-envelope-emit pattern as section 1, using `phase: "step 2:forge-data-dir"` and the matching path.
 
 ### 4. Auto-Proceed
 

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

@@ -9,6 +9,15 @@ description: Cognitive completeness verification — quality gate before export.
 
 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.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+- Step files use `## STEP GOAL:` headings rather than the `## MANDATORY SEQUENCE` + `## CRITICAL STEP COMPLETION NOTE` pattern used by generate-driven SKF workflows — this skill is a validation harness with score-driven step semantics, not a chain that produces new artifacts.
+
 ## 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.
@@ -18,11 +27,8 @@ You are a skill auditor and completeness analyst operating in Ferris's Audit mod
 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
 
@@ -30,23 +36,54 @@ These rules apply to every step in this workflow:
 
 | # | 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 |
+| 1 | Initialize & Load Skill | references/init.md | Yes |
+| 2 | Detect Mode | references/detect-mode.md | Yes |
+| 3 | Coverage Check | references/coverage-check.md | Yes |
+| 4 | Coherence Check | references/coherence-check.md | Yes |
+| 4b | External Validators | references/external-validators.md | Yes |
+| 5 | Score | references/score.md | Yes |
+| 6 | Report | references/report.md | No (confirm) |
+| 7 | Workflow Health Check | references/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) |
+| **Inputs** | skill_name [required]; optional flags: `--allow-workspace-drift`, `--no-discovery` (skip §4b Discovery Testing), `--no-health-check` (skip §7 health-check dispatch), `--tier=<Quick\|Forge\|Forge+\|Deep>` (bypass forge-tier.yaml sidecar requirement), `--threshold=<N>` (override pass threshold; CLI wins over `workflow.default_threshold` scalar) |
+| **Gates** | step 6: Confirm Gate [C] |
+| **Outputs** | test-report-{skill_name}.md with completeness score and result (PASS/FAIL); per-run `skf-test-skill-result-{run_id}.json` and `skf-test-skill-result-latest.json` written atomically under `{forge_version}/` |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every terminal state in this workflow exits with a stable code so headless automators can branch on the verdict (and any HARD HALT) without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                  |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success / PASS       | step 6 §6b — `testResult: 'pass'` (after the result contract is written in §4c)            |
+| 2    | fail / FAIL          | step 6 §6b — `testResult: 'fail'` (after the result contract is written in §4c)            |
+| 3    | inconclusive         | step 6 §6b — `testResult: 'inconclusive'` (distinct from fail so orchestrators can route to manual-review queues) |
+| 4    | pass-with-drift      | step 6 §6b — `testResult: 'pass-with-drift'` (distinct from clean pass — `--allow-workspace-drift` was in effect; orchestrators MUST route to re-test-against-pinned-commit queues and refuse export; never exit 0 under drift override) |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_TEST_RESULT_JSON: {"status":"success|error","skill_name":"…","verdict":"PASS|FAIL|INCONCLUSIVE|pass-with-drift","score":N,"threshold":N,"report_path":"…|null","next_workflow":"export-skill|update-skill|null","exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path (any of PASS / FAIL / INCONCLUSIVE / pass-with-drift — the workflow completed), `"error"` on any HARD HALT before §4c. `verdict` is the canonical result string. `next_workflow` is `"export-skill"` only when `verdict == "PASS"`; `"update-skill"` for `FAIL` or `pass-with-drift`; `null` for `INCONCLUSIVE` (manual review). `halt_reason` is `null` on the terminal path or one of the workflow-defined halt strings (`"forge-tier-missing"`, `"target-inaccessible"`, `"write-failed"`, `"step-completeness-violation"`, `"report-anchor-missing"`, `"health-check-missing"`, `"atomic-writer-missing"`). `exit_code` matches the table above.
+
+The same payload is persisted to disk by step 6 §4c (atomic write) at two locations under `{forge_version}/`:
+
+| Path                                          | Purpose                                                                    |
+| --------------------------------------------- | -------------------------------------------------------------------------- |
+| `skf-test-skill-result-{run_id}.json`         | Per-run record. `{run_id}` carries UTC timestamp + PID + random suffix.    |
+| `skf-test-skill-result-latest.json`           | Latest copy — stable path for pipeline consumers (copy, not symlink).      |
+
+The on-disk payload is the richer form: it adds `outputs[]` (report-path entries), `summary` (`score`, `threshold`, `result`, `testMode`, `activeCategories[]`, `inconclusiveReasons[]` when present), `runId`, and `healthCheckDispatched`. The stdout envelope is the compact subset documented above.
 
 ## On Activation
 
@@ -56,4 +93,29 @@ These rules apply to every step in this workflow:
 
 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.
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the three scalars, if the merged value is empty or absent, use the bundled default:
+
+   - `{testReportTemplatePath}` ← `workflow.test_report_template_path` if non-empty, else `templates/test-report-template.md`
+   - `{outputFormatsPath}` ← `workflow.output_formats_path` if non-empty, else `assets/output-section-formats.md`
+   - `{scoringRulesPath}` ← `workflow.scoring_rules_path` if non-empty, else `references/scoring-rules.md`
+   - `{defaultThreshold}` ← `workflow.default_threshold` if non-empty/non-null, else `80`. CLI `--threshold=<N>` (when present) wins over the scalar at the usage site in `references/score.md`.
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string. When empty, the post-finalization hook in `references/report.md` is a no-op.
+
+   Stash all five as workflow-context variables. Stage files reference `{testReportTemplatePath}` / `{outputFormatsPath}` / `{scoringRulesPath}` / `{defaultThreshold}` / `{onCompleteCommand}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies without forking the skill.
+
+4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

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

@@ -0,0 +1,54 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-test-skill.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   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.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (house style, severity policies, grading guardrails).
+# Overrides append.
+#
+# Each entry is either:
+#   - 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).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical asset paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default.
+
+test_report_template_path = ""
+output_formats_path = ""
+scoring_rules_path = ""
+
+# Pass threshold (percent). CLI `--threshold=<N>` wins over this scalar.
+# Override here to change the org-wide default without forking the skill.
+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 = ""