bmad-module-skill-forge 1.1.0 → 1.3.0

package/src/skf-setup/steps-c/step-01-detect-and-tier.md

@@ -1,111 +1,98 @@
 ---
 nextStepFile: './step-01b-ccc-index.md'
-tierRulesData: 'references/tier-rules.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
+# tool detection and tier calculation; no fallback to prose-driven probes.
+detectToolsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-tools.py'
+  - '{project-root}/src/shared/scripts/skf-detect-tools.py'
 ---
 
+<!-- Config: communicate in {communication_language}. The first-run preamble below is user-visible — render it in the user's language. -->
+
 # Step 1: Detect Tools and Determine Tier
 
 ## STEP GOAL:
 
-Verify availability of the four forge tools (ast-grep, gh, qmd, ccc), read any existing configuration for re-run comparison, check for tier override, and calculate the capability tier.
+Verify availability of the four forge tools (ast-grep, gh, qmd, ccc), read any existing configuration for re-run comparison, check for tier override, and calculate the capability tier — all via `{detectToolsHelper}` so the deterministic work is done once, by a tested script, never by the LLM.
 
 ## Rules
 
 - Focus only on tool detection and tier calculation — do not write any files (Step 02)
-- Do not skip any tool check — all 4 must be verified
-- Tool command failures are not errors — they indicate unavailability
+- Never reimplement tool probes or the tier rules in prose — the script is authoritative
+- Tool command failures are not errors — they indicate unavailability (the script swallows them)
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
-### 1. Load Tier Rules
-
-Load and read {tierRulesData} for the tool detection commands and tier calculation logic.
-
-### 2. Check for Existing Configuration (Re-run Detection)
+### 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}` and `tier_detected_at` as `{previous_detection_date}`
-- If not found: set `{previous_tier}` to null (first run)
+
+- 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).
 
 **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
 
-### 3. Verify Tool: ast-grep
-
-Run: `ast-grep --version`
-
-- If succeeds: record `{ast_grep: true}` and store version string
-- If fails (command not found or error): record `{ast_grep: false}`
-
-### 4. Verify Tool: gh
-
-Run: `gh --version`
-
-- If succeeds: record `{gh_cli: true}` and store version string
-- If fails: record `{gh_cli: false}`
-
-### 5. Verify Tool: qmd
-
-Run: `qmd status`
-
-- If succeeds and indicates operational: record `{qmd: true}`
-- If fails or indicates not initialized: record `{qmd: false}`
-
-### 6. Check Optional: Security Scan (SNYK_TOKEN)
-
-Check if the `SNYK_TOKEN` environment variable is set:
-
-- If `SNYK_TOKEN` is non-empty: record `{security_scan: true}`
-- If `SNYK_TOKEN` is empty or unset: record `{security_scan: false}`
-
-This is informational only — security scan availability does NOT affect the tier level. It is recorded in forge-tier.yaml so that create-skill's validation step can report actionable guidance when security scanning is unavailable.
-
-### 7. Verify Tool: ccc (cocoindex-code)
+**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:
 
-**Step A — Binary existence:** Run `ccc --help`
+"**About to set up the forge.** This workflow will:
 
-- If exits 0: binary confirmed. Continue to Step B.
-- If fails (command not found or error): record `{ccc: false}`. Skip Step B.
+- Detect available tools (ast-grep, gh, qmd, ccc) — read-only probes only
+- Write `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml` (capability tier + tool state)
+- Write `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml` (first-run defaults)
+- Create `{forge_data_folder}/` if missing
+- When ccc is available: augment `{project-root}/.cocoindex_code/settings.yml` with SKF exclusion patterns, then create or refresh the project ccc index
 
-**Step B — Daemon health:** Run `ccc doctor`
+**About tiers:** SKF picks one of four tiers (Quick / Forge / Forge+ / Deep) based on which tools are installed. **All four are fully usable** — higher tiers add power, they don't fix gaps. If you're new and only have a base Python install, Quick tier is the right starting point and the report at the end will show you exactly which tools to install if you want to climb later.
 
-- If daemon is running and model check OK: record `{ccc: true, ccc_daemon: "healthy"}` and store version string from output
-- If daemon is not running: record `{ccc: true, ccc_daemon: "stopped"}` — binary available, daemon needs starting. Step-01b will handle this.
-- If error or timeout: record `{ccc: true, ccc_daemon: "error"}` — binary works but daemon has issues.
+Press Esc or Ctrl+C now if this isn't the right project — no files have been written yet."
 
-ccc availability gates the Forge+ tier and enhances Deep tier when present.
+### 2. Run Detection Helper
 
-### 8. Calculate Tier
+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.
 
-**If `{tier_override}` is set and valid (Quick, Forge, Forge+, or Deep):**
-- Use `{tier_override}` as `{calculated_tier}`
-- Note that override is active for the report step
+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.
 
-**If no override, apply tier rules from {tierRulesData} in order — the first matching rule wins. Do not continue checking once a match is found:**
-- `{ast_grep}` AND `{gh_cli}` AND `{qmd}` all true → **Deep**
-- `{ast_grep}` AND `{ccc}` both true, but NOT (`{gh_cli}` AND `{qmd}`) → **Forge+**
-- `{ast_grep}` true (regardless of ccc/gh/qmd) → **Forge**
-- Otherwise → **Quick**
+### 3. Parse Output and Set Context Flags
 
-**If `{tier_override}` is set but invalid:** ignore it, use detected tier, flag for warning in report.
+From the JSON, set these context flags. Field paths are relative to the script's top-level object.
 
-### 9. Auto-Proceed
+From `tools`:
 
-"**Proceeding to CCC index check...**"
+- `{ast_grep}` ← `tools.ast_grep.available`
+- `{ast_grep_version}` ← `tools.ast_grep.version`
+- `{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_version}` ← `tools.qmd.version`
+- `{ccc}` ← `tools.ccc.available`
+- `{ccc_daemon}` ← `tools.ccc.daemon` (`"healthy" | "stopped" | "error" | null`)
+- `{ccc_version}` ← `tools.ccc.version`
+- `{security_scan}` ← `tools.security_scan.available` (informational only — never affects tier)
 
-#### Menu Handling Logic:
+From `tier`:
 
-- After tier calculation is complete, immediately load, read entire file, then execute {nextStepFile}
+- `{calculated_tier}` ← `tier.calculated` — the tier downstream steps act on
+- `{detected_tier}` ← `tier.detected` — what would have been chosen without override
+- `{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_unsafe}` ← `tier.override_unsafe`
+- `{tier_override_unsafe_missing}` ← `tier.override_unsafe_missing` (a list — step-04 joins with `", "` for display)
 
-#### EXECUTION RULES:
+From `require_tier`:
 
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after detection and calculation
+- `{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)
 
-## CRITICAL STEP COMPLETION NOTE
+**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.
 
-ONLY WHEN all 4 core tools have been verified, optional security scan checked, and the tier calculated will you load and read fully `{nextStepFile}` to execute the CCC index check step.
+### 4. Auto-Proceed
 
+After context flags are populated, display "**Proceeding to CCC index check...**", then load `{nextStepFile}`, read it fully, and execute it.

package/src/skf-setup/steps-c/step-01b-ccc-index.md

@@ -1,31 +1,39 @@
 ---
 nextStepFile: './step-02-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
+# validation and the set-union merge into .cocoindex_code/settings.yml; no
+# fallback to prose-driven validation.
+mergeCccExclusionsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-merge-ccc-exclusions.py'
+  - '{project-root}/src/shared/scripts/skf-merge-ccc-exclusions.py'
 ---
 
+<!-- Config: communicate in {communication_language}. User-visible status messages (CCC exclusion summary, indexing progress message) render in the user's language. -->
+
 # Step 1b: CCC Index Verification
 
 ## STEP GOAL:
 
-If ccc is available (`{ccc: true}` from step-01), configure CCC exclusion patterns for SKF infrastructure directories, verify that the ccc index exists for the project root, and create or refresh it if needed. Store index state and exclusion patterns in context for step-02 to write into forge-tier.yaml.
+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.
 
 For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
 
 ## Rules
 
-- Focus only on ccc index verification and creation
+- Focus only on ccc index verification, exclusion-pattern merge, and (re-)indexing
 - 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
+- Never reimplement the exclusion-pattern validation in prose — the script owns the PR #248 rules
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Eligibility
 
 Read `{ccc}` from step-01 context.
 
-**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: []}`. Proceed directly to section 4 (Auto-Proceed) — no output, no messaging.
+**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.
 
@@ -36,81 +44,68 @@ Read existing forge-tier.yaml at `{project-root}/_bmad/_memory/forger-sidecar/fo
 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:
+
 - 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}` — proceed to section 2b (exclusions must still be configured)
+  - Set `{needs_reindex: false}` — exclusions still get merged in section 3, which may force a re-index
 
 - If `ccc_index.indexed_path` matches `{project-root}` but timestamp is older than threshold:
-  - Set `{needs_reindex: true}` — proceed to section 2b then section 3
+  - Set `{needs_reindex: true}`
 
 - If `ccc_index` is missing, has null values, or path doesn't match:
-  - Set `{needs_reindex: true}` — proceed to section 2b then section 3
+  - Set `{needs_reindex: true}`
 
-### 2b. Configure CCC Exclusions
+### 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.
 
-**Build the SKF exclusion list:**
-
-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 (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.
+Run the merge helper, forwarding the resolved config values from the workflow activation context. 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'`.
 
-**Apply exclusions to settings.yml:**
+```bash
+uv run {mergeCccExclusionsHelper} \
+    --project-root "{project-root}" \
+    --skills-output-folder "{skills_output_folder}" \
+    --forge-data-folder "{forge_data_folder}"
+```
 
-Check if `{project-root}/.cocoindex_code/settings.yml` exists. Set `{settings_yml_existed: true}` if it does, `{settings_yml_existed: false}` if not.
+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).
 
-If `{settings_yml_existed}` is true (from a previous `ccc init` run):
+**Parse the JSON output and set context flags:**
 
-1. Read `settings.yml`
-2. For each pattern in `{ccc_exclude_patterns}`: if the pattern is NOT already present in `exclude_patterns`, append it and set `{exclusions_changed: true}`
-3. If `{exclusions_changed}`: write the updated `settings.yml` back, set `{needs_reindex: true}` (new exclusions require re-indexing), display: "**CCC exclusions configured:** {count} SKF patterns applied to .cocoindex_code/settings.yml"
-4. If no new patterns needed: display nothing (exclusions already configured)
+- `{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)
 
-This preserves any existing user customizations and default exclusions while ensuring SKF directories are filtered out.
+**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"
 
-If `{settings_yml_existed}` is false: the exclusions will be applied after `ccc init` in section 3.
+**If `{settings_yml_written}` is false** (idempotent re-run, all patterns already present): display nothing (exclusions already configured). Do NOT change `{needs_reindex}` — it stays at whatever section 2 set it to.
 
 **Flow decision:**
-- If `{needs_reindex}` is true: proceed to section 3
-- If `{needs_reindex}` is false: proceed to section 4 (Auto-Proceed)
-
-### 3. Create or Refresh CCC Index
 
-**If `{ccc_daemon}` is `"stopped"` or `"healthy"`:**
+- If `{needs_reindex}` is true: proceed to section 4
+- If `{needs_reindex}` is false: proceed to section 5 (Auto-Proceed)
 
-The `ccc index` command auto-starts the daemon when needed. Proceed with indexing below.
+### 4. Create or Refresh CCC Index
 
-**If `{ccc_daemon}` is `"error"`:**
+**If `{ccc_daemon}` is `"stopped"` or `"healthy"`:** the `ccc index` command auto-starts the daemon when needed.
 
-Attempt indexing anyway — errors will be caught below.
+**If `{ccc_daemon}` is `"error"`:** attempt indexing anyway — errors will be caught below.
 
 Run (CWD must be `{project-root}`):
+
 ```bash
 ccc init
 ```
 
-**If init fails** (project may already be initialized): continue — this is not an error.
-
-**Apply SKF exclusion patterns (if not already applied in section 2b):**
+**If init fails** (project may already be initialized): continue — this is not an error. Note: when `{settings_yml_existed}` was false and `ccc init` just created the settings.yml, the merge in section 3 ran BEFORE ccc init. The script handles "no settings.yml exists" by creating one with just the SKF exclusions, which `ccc init` will then either preserve (if it merges) or overwrite (in which case the next workflow run re-merges). Either way the SKF exclusions end up in the file by the time `ccc index` runs the second time.
 
-If `{settings_yml_existed}` is false (first-time setup — `ccc init` just created it), apply exclusions now:
-
-1. Read `{project-root}/.cocoindex_code/settings.yml` (created by `ccc init`)
-2. For each pattern in `{ccc_exclude_patterns}`: if the pattern is NOT already present in `exclude_patterns`, append it
-3. Write the updated `settings.yml` back
-4. Display: "**CCC exclusions configured:** {count} SKF patterns applied to .cocoindex_code/settings.yml"
+Before invoking `ccc index`, display: "**Building semantic index — this can take several minutes on large codebases (1000+ files). Run `ccc status` in another terminal to monitor progress.**" so the user does not assume the workflow has hung during the long-running call.
 
 Then run:
+
 ```bash
 ccc index
 ```
@@ -118,29 +113,17 @@ ccc index
 **Note:** `ccc index` can take several minutes on large codebases (1000+ files). Run with an extended timeout or in background mode. Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero.
 
 **If succeeds:**
+
 - Run `ccc status` to get file count
 - Store `{ccc_index_result: "created", ccc_indexed_path: {project-root}, ccc_last_indexed: {current ISO timestamp}, ccc_file_count: {count from ccc status}}`
 - Display: "**CCC index created.** {ccc_file_count} files indexed for semantic discovery."
 
 **If fails:**
-- Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null}`
+
+- 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)
 - Display: "CCC indexing failed: {error}. Extraction will use direct AST scanning — semantic pre-ranking unavailable this session."
 - Continue — this is NOT a workflow error
 
-### 4. Auto-Proceed
-
-"**Proceeding to write configuration...**"
-
-#### Menu Handling Logic:
-
-- After ccc index check completes (or is skipped), immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after ccc index verification
-
-## CRITICAL STEP COMPLETION NOTE
-
-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.
+### 5. Auto-Proceed
 
+After ccc index verification is complete (or skipped because ccc is unavailable), display "**Proceeding to write configuration...**", then load `{nextStepFile}`, read it fully, and execute it.

package/src/skf-setup/steps-c/step-02-write-config.md

@@ -1,123 +1,96 @@
 ---
 nextStepFile: './step-03-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
+# forge-tier.yaml format AND the array-preservation contract that protects
+# qmd_collections / ccc_index_registry / staleness_threshold_hours from being
+# lost on rewrite. NEVER fall back to inline YAML emission — drift between the
+# script and a prose-rendered template will silently corrupt downstream skills.
+forgeTierRwProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
+  - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
 ---
 
+<!-- Config: communicate in {communication_language}. Halt-on-write-failure messages render in the user's language. -->
+
 # Step 2: Write Configuration
 
 ## STEP GOAL:
 
-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.
+Write the detected tool availability and calculated tier to `forge-tier.yaml` (preserving registry arrays from any existing file), create `preferences.yaml` with first-run defaults if it does not exist, and ensure the `forge-data/` directory is present. All file mutations go through `{forgeTierRwHelper}` so the format is locked, atomic, and array-preservation is guaranteed.
 
 ## Rules
 
 - 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
+- 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
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Write forge-tier.yaml
 
-Write to `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml`:
-
-```yaml
-# Ferris Sidecar: Forge Tier State
-# Written by setup workflow
-
-# Tool availability (detected during [SF] Setup Forge)
-tools:
-  ast_grep: {true/false from detection}
-  gh_cli: {true/false from detection}
-  qmd: {true/false from detection}
-  ccc: {true/false from detection}
-  ccc_daemon: {ccc_daemon from step-01 if available: "healthy"|"stopped"|"error", or ~}
-  security_scan: {true/false — true when SNYK_TOKEN is set}
-
-# Capability tier (derived from tool availability)
-# Quick = no tools | Forge = + ast-grep | Forge+ = + ast-grep + ccc | Deep = + ast-grep + gh + QMD
-tier: {calculated_tier}
-tier_detected_at: {current ISO timestamp}
-
-# 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 ~}
-  status: {ccc_index_result from step-01b: "fresh"|"created"|"none"|"failed"}
-  staleness_threshold_hours: 24
-  file_count: {ccc_file_count from step-01b, or ~}
-  exclude_patterns: {ccc_exclude_patterns from step-01b, or []}
-
-# CCC index registry (tracks which source paths have been indexed for skill workflows)
-# PRESERVE existing entries on re-runs — see Note below
-ccc_index_registry: {preserved from existing forge-tier.yaml, or [] if first run}
-
-# QMD collection registry (populated by create-skill, consumed by audit/update-skill)
-# PRESERVE existing entries on re-runs — see Note below
-qmd_collections: {preserved from existing forge-tier.yaml, or [] if first run}
+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.
+
+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`.
+
+```bash
+echo '{
+  "tools": {
+    "ast_grep": {ast_grep},
+    "gh_cli": {gh_cli},
+    "qmd": {qmd},
+    "ccc": {ccc},
+    "ccc_daemon": {ccc_daemon},
+    "security_scan": {security_scan}
+  },
+  "tier": "{calculated_tier}",
+  "ccc_index": {
+    "indexed_path": {ccc_indexed_path},
+    "last_indexed": {ccc_last_indexed},
+    "status": "{ccc_index_result}",
+    "file_count": {ccc_file_count},
+    "exclude_patterns": {ccc_exclude_patterns}
+  }
+}' | uv run {forgeTierRwHelper} write-tools \
+       --target "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"
 ```
 
-**Note on re-runs:** The `qmd_collections`, `ccc_index_registry` arrays, and `staleness_threshold_hours` value must be preserved across re-runs. Before overwriting forge-tier.yaml, read these existing values and re-inject them into the new write. These values are populated by create-skill workflows or customized by users and must not be reset. Note: `exclude_patterns` is NOT preserved — it is always written fresh from `{ccc_exclude_patterns}` computed by step-01b.
-
-**This file is ALWAYS overwritten** on every run — it reflects current tool state.
-
-If the write fails, report the error and halt the workflow.
+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`.
 
-### 2. Handle preferences.yaml
+**Parse the response and set context flags for step-04:**
 
-Check if `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml` exists:
+- `{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 it does NOT exist (first run):** Create with defaults:
+**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.
 
-```yaml
-# Ferris Sidecar: User Preferences
-# Created by setup workflow on first run
-# Edit this file to customize Ferris behavior
+### 2. Initialize preferences.yaml
 
-# Override detected tier (set to Quick, Forge, Forge+, or Deep to force a tier)
-tier_override: ~
-
-# Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)
-passive_context: true
+```bash
+uv run {forgeTierRwHelper} init-prefs \
+    --target "{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml"
+```
 
-# Headless mode (set to true to skip confirmation gates in all workflows)
-headless_mode: false
+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`.
 
-# Compact greeting (set to true to skip the full capabilities table on session start)
-compact_greeting: false
+**Parse the response and set context flags for step-04:**
 
-# Reserved for future use — these fields are not yet consumed by any workflow step
-# output_language: ~
-# skill_format_version: ~
-# citation_style: ~
-# confidence_display: ~
-```
+- `{preferences_yaml_created}` ← `wrote` (true on first run, false on re-run when the file pre-existed)
 
-**If it DOES exist:** Do not modify. Preserve entirely.
+**If the script exits non-zero**: same halt-and-report pattern as section 1, with `phase: "step-02:init-prefs"` and the matching path.
 
 ### 3. Ensure forge-data/ Directory
 
 Check if `{forge_data_folder}` directory exists:
 
-- If missing: create it
-- If exists: skip silently
+- If missing: create it. Store `{forge_data_dir_created: true}` in context.
+- If exists: skip silently. Store `{forge_data_dir_created: false}` in context.
 
-### 4. Auto-Proceed
+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.
 
-"**Proceeding to QMD collection hygiene...**"
-
-#### Menu Handling Logic:
-
-- After all file operations complete successfully, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Proceed directly to next step after configuration is written
-
-## 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 QMD hygiene step.
+### 4. Auto-Proceed
 
+After forge-tier.yaml has been written successfully and preferences.yaml exists (created or pre-existing), display "**Proceeding to QMD collection hygiene...**", then load `{nextStepFile}`, read it fully, and execute it.