bmad-module-skill-forge 1.1.0 → 1.2.0

package/src/skf-setup/SKILL.md

@@ -7,7 +7,7 @@ description: Initialize forge environment, detect tools, and set capability tier
 
 ## Overview
 
-Initializes the forge environment by detecting available tools, determining the capability tier (Quick/Forge/Forge+/Deep), writing persistent configuration, and optionally indexing the project for deep search. This is a fully autonomous workflow — no user interaction is required during execution.
+Initializes the forge environment by detecting available tools, determining the capability tier (Quick/Forge/Forge+/Deep), and writing persistent configuration to `{project-root}/_bmad/_memory/forger-sidecar/`. When `ccc` (cocoindex-code) is available, also augments `.cocoindex_code/settings.yml` with SKF exclusion patterns and creates or refreshes the project's semantic-search index. On Deep tier, reconciles the QMD collection registry; whenever ccc is available, reconciles the CCC index registry as well. The workflow is autonomous with one optional gate — orphaned QMD collection removal in step 3 (Deep tier only; default action: Keep) — which auto-resolves to the default when `{headless_mode}` is true.
 
 ## Role
 
@@ -17,7 +17,7 @@ You are a system executor performing environment resolution. Run each step in se
 
 These rules apply to every step in this workflow:
 
-- Fully autonomous — all steps auto-proceed with no user interaction until the final report
+- Autonomous with one optional gate (step 3 orphan-removal prompt; default: Keep) — all other steps auto-proceed with no user interaction until the final report
 - 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
@@ -29,9 +29,9 @@ These rules apply to every step in this workflow:
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
 | 1 | Detect Tools & Set Tier | steps-c/step-01-detect-and-tier.md | Yes |
-| 1b | CCC Index | steps-c/step-01b-ccc-index.md | Yes |
+| 1b | CCC Index (only when ccc is available) | steps-c/step-01b-ccc-index.md | Yes |
 | 2 | Write Config | steps-c/step-02-write-config.md | Yes |
-| 3 | QMD Hygiene | steps-c/step-03-auto-index.md | Yes |
+| 3 | QMD + CCC Registry Hygiene | steps-c/step-03-auto-index.md | Yes |
 | 4 | Report | steps-c/step-04-report.md | Yes |
 | 5 | Workflow Health Check | steps-c/step-05-health-check.md | Yes |
 
@@ -39,17 +39,32 @@ These rules apply to every step in this workflow:
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | (none — fully autonomous) |
+| **Inputs** | (none) |
+| **Flags** | `--headless` / `-H` (skip prompts, auto-resolve gates to defaults); `--require-tier=<Quick\|Forge\|Forge+\|Deep>` (halt with failure if calculated tier does not satisfy the requirement) |
 | **Gates** | One optional: orphaned QMD collection removal (step 3, Deep tier only; default: Keep) |
-| **Outputs** | forge-tier.yaml, preferences.yaml, forge-data directories |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Outputs** | `forger-sidecar/forge-tier.yaml`, `forger-sidecar/preferences.yaml`, `{forge_data_folder}/`; when ccc is available, `.cocoindex_code/settings.yml` (exclusion patterns merged) and the project ccc index |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. step-04 emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope after the human-readable banner so pipelines can parse the outcome without reading forge-tier.yaml. Schema documented in `steps-c/step-04-report.md` §4. |
+| **Failure modes** | `--require-tier` not satisfied → step-04 prints a "REQUIRED TIER NOT MET" block, the JSON envelope sets `"require_tier_satisfied": false`, and the workflow halts before step-05. |
+| **Exit codes** | The workflow runs as an LLM-driven sequence rather than a CLI process, so "exit code" describes the agent's terminal state for a calling pipeline that reads `SKF_SETUP_RESULT_JSON`. **0 — success** (no JSON `error` field, all writes completed, `require_tier_satisfied` is `true` or `null`). **1 — required-tier failure** (`require_tier_satisfied` is `false`; envelope still emitted with full state for diagnosis). **2 — write failure** (forge-tier.yaml or preferences.yaml could not be written; envelope `error` field names the path and reason). Pipelines should branch on the JSON `require_tier_satisfied` and `error` fields rather than process exit codes. |
 
 ## On Activation
 
-1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+1. **Probe `uv` runtime.** Run `uv --version`. Every step in this workflow invokes shared Python helpers via `uv run` (PEP 723 inline metadata is what auto-resolves `pyyaml` for the helpers that need it — see `docs/getting-started.md`). If `uv` is missing, halt now with a single cohesive diagnostic rather than letting five separate steps each fail with `uv: command not found`:
+
+   "**Setup cannot proceed: `uv` is not installed.** SKF helpers depend on `uv` to auto-resolve their Python dependencies. Install it from <https://docs.astral.sh/uv/getting-started/installation/> and re-run `/skf-setup`. (See the Prerequisites section in <https://docs.astral.sh/uv/getting-started/installation/> or the SKF docs at `docs/getting-started.md` for details.)"
+
+2. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name` (from installer-generated config.yaml, not module.yaml), `output_folder`, `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.
+   **If the file does not exist**, halt with a single cohesive "wrong directory" diagnostic rather than failing later with a generic file-read error from a downstream step:
+
+   "**Setup cannot proceed: `{project-root}/_bmad/skf/config.yaml` was not found.** This directory does not appear to be an SKF-initialised project. From the project root, run `npx bmad-module-skill-forge install` (or `npx bmad-method install` and add SKF as a custom module — see `docs/getting-started.md`), then re-run `/skf-setup`. If you ARE in the right project but the file was deleted, restore it from version control or re-run the SKF installer."
+
+   **If the file exists but is malformed YAML**, halt and surface the parser error along with the file path so the user can fix it directly: "**Setup cannot proceed: `{project-root}/_bmad/skf/config.yaml` is not valid YAML.** Parser error: {error_message}. Open the file and repair the YAML, or restore from version control."
+
+3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+4. **Resolve `{require_tier}`**: parse `--require-tier=<value>` from the invocation arguments. Accept exactly `Quick`, `Forge`, `Forge+`, or `Deep` (case-sensitive). If absent or unparseable, leave as null (no tier requirement).
 
-3. Load, read the full file, and then execute `./steps-c/step-01-detect-and-tier.md` to begin the workflow.
+5. Load, read the full file, and then execute `./steps-c/step-01-detect-and-tier.md` to begin the workflow.

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

@@ -7,9 +7,9 @@
 | 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 (binary exists). Step B: daemon running, version string, model check OK |
+| 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. |
 
-**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 existence and daemon health.
+**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.
 
 ## Tier Calculation
 

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.