bmad-module-skill-forge 1.0.0 → 1.2.0

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.

package/src/skf-setup/steps-c/step-03-auto-index.md

@@ -1,73 +1,89 @@
 ---
 nextStepFile: './step-04-report.md'
+# Resolve `{qmdClassifyHelper}` and `{forgeTierRwHelper}` by probing the
+# corresponding `*ProbeOrder` arrays (installed SKF module path first, src/
+# dev-checkout fallback); first existing path wins. HALT if neither resolves
+# for the helper a section actually invokes — both scripts own classification
+# / registry-cleanup contracts that have no prose fallback.
+qmdClassifyProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-qmd-classify-collections.py'
+  - '{project-root}/src/shared/scripts/skf-qmd-classify-collections.py'
+forgeTierRwProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
+  - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
 ---
 
-# Step 3: QMD Collection Hygiene
+<!-- Config: communicate in {communication_language}. The orphan-removal prompt and the headless-resolution log message render in the user's language. -->
+
+# Step 3: QMD + CCC Registry Hygiene
 
 ## STEP GOAL:
 
-If the detected tier is Deep, verify the health of existing QMD collections by cross-referencing them against the `qmd_collections` registry in `forge-tier.yaml`. Identify orphaned collections (in QMD but not in registry) and stale registry entries (in registry but collection missing from QMD). Prompt the user before removing orphaned collections.
+When the detected tier is Deep, classify live QMD collections against the `qmd_collections` registry and prompt the user before removing orphans. Whenever ccc is available (Forge+ or Deep), prune `ccc_index_registry` entries whose source paths no longer exist. All set-arithmetic and YAML mutation goes through scripts (`{qmdClassifyHelper}` and `{forgeTierRwHelper}`); the workflow only orchestrates external CLI calls (`qmd collection list`, `qmd collection remove`) and the user-prompt branch.
 
-For Quick and Forge tiers, skip silently and proceed (QMD is not available at those tiers). For Forge+ tier, skip QMD hygiene but the step routes correctly to the next step.
+For Quick and Forge tiers, skip silently and proceed (QMD is not available; ccc registry cleanup only runs when ccc is available regardless of tier).
 
 ## Rules
 
-- Focus only on verifying and cleaning QMD collections (Deep tier) or graceful skip (other tiers)
-- Do not display negative framing for non-Deep tiers
-- Do not fail the workflow if QMD hygiene encounters errors
-- Do not create new QMD collections — that belongs to create-skill
-- Do not silently delete collections — always prompt user before removal
+- Focus only on registry hygiene — no new collection creation (that belongs to create-skill)
+- Never reimplement the forge-namespace suffix filter in prose — the classifier owns it
+- Never silently delete collections — always prompt before `qmd collection remove`
+- Headless runs must auto-resolve the orphan prompt to the documented default (Keep)
+- Do not fail the workflow if hygiene encounters errors
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
 ### 1. Check Tier
 
-Read `{calculated_tier}` from context.
+Read `{calculated_tier}` and `{ccc}` from context (set by step-01).
 
-**If tier is Quick or Forge:** Set `{ccc_registry_stale_cleaned: 0}`. Proceed directly to section 6 (Auto-Proceed) — no output, no messaging.
+**If `{calculated_tier}` is Quick or Forge AND `{ccc}` is false:** No registry hygiene needed. Set `{hygiene_result: "skipped", hygiene_healthy: 0, hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0, hygiene_stale_cleaned: 0, ccc_registry_stale_cleaned: 0, ccc_registry_stale_removed_paths: []}`. Proceed directly to section 5 (Auto-Proceed) — no output, no messaging.
 
-**If tier is Forge+:** Skip QMD hygiene (qmd is not available at Forge+). Proceed directly to section 5b (CCC Index Registry Hygiene) — no QMD output, no messaging.
+**If `{calculated_tier}` is Quick or Forge AND `{ccc}` is true:** No QMD work, but ccc registry needs pruning. Set QMD-related flags to defaults (`hygiene_result: "skipped"`, all hygiene_* counts = 0). Skip directly to section 4 (Stale Registry Cleanup), running it with the ccc-prune flag only.
 
-**If tier IS Deep:** Continue to section 2.
+**If `{calculated_tier}` is Forge+:** Same as Quick/Forge with ccc — no QMD work (qmd unavailable at Forge+), but ccc registry hygiene runs.
 
-### 2. Load Registry and QMD State
+**If `{calculated_tier}` IS Deep:** Continue to section 2.
 
-Read the `qmd_collections` array from `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml`.
+### 2. Classify Live QMD Collections vs Registry
 
 List live QMD collections:
+
 ```bash
 qmd collection list
 ```
 
-**Store both lists for cross-reference:**
-- `{registry_collections}` — entries from forge-tier.yaml qmd_collections
-- `{live_collections}` — collections currently in QMD
+Parse the output into a comma-separated string of collection names and store as `{live_collections}` (raw — including any foreign collections owned by other tools sharing the QMD daemon; the classifier filters them out).
+
+**Error handling:** If `qmd collection list` fails (daemon down, daemon errors), set `{hygiene_result: "qmd_unavailable", hygiene_healthy: 0, hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0, hygiene_stale_cleaned: 0}`, log the error, and skip directly to section 4 (which will still run the ccc-prune branch if `{ccc}` is true).
 
-**Error handling:** If `qmd collection list` fails, log the error, store `{hygiene_result: "qmd_unavailable"}`, and proceed to section 6.
+Run the classifier. Invoke via `uv run` so the script's PEP 723 PyYAML dependency resolves automatically (`docs/getting-started.md` documents uv as the runtime prereq for exactly this); bare `python3` would `ModuleNotFoundError` on a fresh interpreter.
+
+```bash
+uv run {qmdClassifyHelper} \
+    --live-names "{live_collections}" \
+    --registry-from-yaml "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"
+```
 
-### 3. Cross-Reference and Classify
+The script (see `src/shared/scripts/skf-qmd-classify-collections.py` docstring for the full schema) applies the forge-namespace suffix filter (`-brief | -temporal | -docs | -extraction`) to `{live_collections}` before classifying — collections owned by unrelated tools are silently excluded from the orphan / healthy / stale sets and counted under `foreign_filtered_count` for telemetry only. This is the PR #244 incident protection: collections like Hindsight memory banks that happen to live in the same QMD daemon never enter any classification that could lead to data loss.
 
-Compare the two lists:
+**Parse the JSON output and set context flags:**
 
-**Healthy** — collection exists in both registry AND QMD:
-- Mark as verified
-- No action needed
+- `{hygiene_healthy}` ← `len(healthy)`
+- `{orphaned_collections}` ← `orphaned` (the list — used in section 3)
+- `{stale_collections}` ← `stale` (the list — used in section 4)
+- `{foreign_filtered_count}` ← `foreign_filtered_count`
 
-**Orphaned** — collection exists in QMD but NOT in registry:
-- These may be leftover from prior auto-indexing or manual indexing
-- Flag for user-prompted removal
+Set `{hygiene_result: "completed"}`.
 
-**Stale** — entry exists in registry but collection is missing from QMD:
-- The QMD collection was deleted or lost
-- Remove the stale entry from the registry
+### 3. Handle Orphaned Collections
 
-### 4. Handle Orphaned Collections
+**If `{orphaned_collections}` is empty:** Set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0}` and skip to section 4.
 
-**If orphaned collections found:**
+**Headless gate.** If `{headless_mode}` is true, auto-resolve to the default action **Keep** without prompting: log `"Auto-decision (headless): kept {len(orphaned_collections)} orphaned forge collection(s)"`, set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: len(orphaned_collections)}`, and skip to section 4. This matches the workflow contract (`Headless: All gates auto-resolve with default action when {headless_mode} is true`) declared in the Invocation Contract.
+
+**If `{headless_mode}` is false**, display to the user:
 
-Display to user:
 "**QMD Hygiene: Found {count} orphaned collection(s) not tracked in the forge registry:**
 
 {list orphaned collection names}
@@ -75,77 +91,43 @@ Display to user:
 These collections exist in QMD but are not managed by any skill workflow. They may be from a previous auto-index run or manual creation.
 
 **[R]emove** orphaned collections — clean up QMD
-**[K]eep** orphaned collections — leave them as-is"
+**[K]eep** orphaned collections — leave them as-is (default)"
+
+**If user selects R (Remove):** For each name in `{orphaned_collections}`:
 
-**If user selects R (Remove):**
-For each orphaned collection:
 ```bash
-qmd collection remove {collection_name}
+qmd collection remove <name>
 ```
-Log each removal.
-
-**If user selects K (Keep):**
-Skip removal. Log that orphaned collections were kept.
-
-**If no orphaned collections:** Skip this section silently.
-
-### 5. Handle Stale Registry Entries
-
-**If stale registry entries found:**
 
-Remove stale entries from the `qmd_collections` array in forge-tier.yaml.
+Track the count of successful removals as `{hygiene_orphaned_removed}`. Set `{hygiene_orphaned_kept: 0}`.
 
-Display: "**Cleaned {count} stale registry entry/entries** (collection no longer exists in QMD)."
+**If user selects K (Keep) or no orphans:** Set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: len(orphaned_collections)}`.
 
-Update forge-tier.yaml with the cleaned registry.
+### 4. Stale Registry Cleanup
 
-**If no stale entries:** Skip this section silently.
+This section ALWAYS runs when reachable — it handles both `qmd_collections` stale entries (Deep tier) and `ccc_index_registry` stale entries (whenever ccc is true). The script's flags are mutually independent.
 
-### 5b. CCC Index Registry Hygiene (Forge+ and Deep with ccc)
+Build the invocation. Always include `--target` for the forge-tier.yaml path. Include `--qmd-live-names "{live_collections}"` ONLY when section 2 ran successfully (i.e. `{hygiene_result}` is `"completed"`); omit the flag entirely otherwise so the script skips QMD cleanup. Include `--prune-missing-ccc-paths` ONLY when `{ccc}` is true; omit it otherwise.
 
-**IF `tools.ccc` is true in forge-tier.yaml (regardless of whether QMD hygiene ran):**
-
-Read the `ccc_index_registry` array from forge-tier.yaml.
-
-For each entry, verify the indexed path still exists on disk:
-
-**Healthy** — path exists: no action needed.
-
-**Stale** — path does not exist (source directory removed or moved):
-- Remove the stale entry from `ccc_index_registry`
-- Log: "Removed stale CCC index registry entry: {path} (path no longer exists)"
-
-Update forge-tier.yaml with the cleaned registry.
-
-Store `{ccc_registry_stale_cleaned: count}` in context for step-04 reporting.
-
-**IF `tools.ccc` is false:** Skip this section silently.
-
-### 6. Store Hygiene Results and Auto-Proceed
-
-Store in context for step-04 reporting:
-```
-{hygiene_result: "completed"|"skipped"|"qmd_unavailable"}
-{hygiene_healthy: count}
-{hygiene_orphaned_removed: count}
-{hygiene_orphaned_kept: count}
-{hygiene_stale_cleaned: count}
-{ccc_registry_stale_cleaned: count}
+```bash
+uv run {forgeTierRwHelper} clean-stale \
+    --target "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml" \
+    [--qmd-live-names "{live_collections}"]  \
+    [--prune-missing-ccc-paths]
 ```
 
-"**Proceeding to forge status report...**"
-
-#### Menu Handling Logic:
+The script reads the registry, computes set-difference operations (qmd: registry − live; ccc: filter where `path` does not exist on disk), and atomically rewrites forge-tier.yaml only when something actually changed (mtime preserved on idempotent re-runs). The CI ephemeral-mount caveat for ccc-registry pruning is logged in the script's WARNING message (per PR #248).
 
-- After hygiene completes (or is skipped), immediately load, read entire file, then execute {nextStepFile}
+**Parse the JSON output and set context flags for step-04:**
 
-#### EXECUTION RULES:
+- `{hygiene_stale_cleaned}` ← `len(qmd_removed)`
+- `{ccc_registry_stale_cleaned}` ← `len(ccc_removed)`
+- `{ccc_registry_stale_removed_paths}` ← `ccc_removed` (the list — step-04 folds individual paths into envelope warnings)
 
-- This step has one optional user interaction (orphan removal prompt)
-- If no orphans found, this is an auto-proceed step
-- Proceed directly to next step after hygiene or skip
+If `{hygiene_stale_cleaned}` > 0, display: "**Cleaned {hygiene_stale_cleaned} stale QMD registry entry/entries** (collection no longer exists in QMD)."
 
-## CRITICAL STEP COMPLETION NOTE
+(The script already logs each ccc removal as a WARNING line; no additional display needed.)
 
-ONLY WHEN the hygiene check has been performed (or skipped for non-Deep tiers) will you load and read fully `{nextStepFile}` to execute the report step.
+### 5. Auto-Proceed
 
+After hygiene completes (or is skipped for non-Deep tiers without ccc), display "**Proceeding to forge status report...**", then load `{nextStepFile}`, read it fully, and execute it.