bmad-module-skill-forge 1.4.1 → 1.5.0

package/src/skf-rename-skill/references/rebuild-context.md

@@ -0,0 +1,110 @@
+---
+# Static reference loaded by execute.md §7. The carve removes ~70
+# lines of context-rebuild loop logic from the main execute.md so
+# the §1–§6 + §8–§10 critical-path stays tight; §7 itself is always
+# reached on the success path so this file loads on every successful
+# rename, but the rollback paths (§4–§6 failure jumps) skip §7
+# entirely and never load this reference.
+---
+
+<!-- Config: communicate in {communication_language}. Render the rebuilt-files report in {document_output_language}. -->
+
+# Rename: Rebuild Context Files (per-IDE managed-section sweep)
+
+## Purpose
+
+After §6 re-keys the manifest from `{old_name}` to `{new_name}`, every IDE's context file (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, etc.) still contains the old name in its managed-section snippet rows. This step rewrites each one in-place via the surgical between-marker swap so the on-disk managed sections reflect the new name.
+
+Loaded by `execute.md` §7 once `manifest_updated == true` (§6 succeeded) and the rollback paths in §4–§6 were not taken.
+
+## Resolve target_context_files
+
+Load the `ides` list from `config.yaml`. The installer writes IDE identifiers — these must be mapped to context files and skill roots using the "IDE → Context File Mapping" table in `{managedSectionLogic}`:
+
+1. For each entry in `config.yaml.ides`, look up its `context_file` and `skill_root` from the mapping table.
+2. For any entry not found in the table, default to AGENTS.md / `.agents/skills/` and emit a warning: `Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md`.
+3. Deduplicate by `context_file` — when multiple IDEs map to the same context file, use the first configured IDE's `skill_root`.
+4. If `config.yaml.ides` is absent or the mapping yields an empty list, fall back to `[{context_file: "AGENTS.md", skill_root: ".agents/skills/"}]` and emit a note: `No IDEs configured in config.yaml — defaulting to AGENTS.md`.
+
+Store the result as `target_context_files`.
+
+## Per-file loop
+
+For each entry in `target_context_files`:
+
+### 1. Resolve target file
+
+Resolve the absolute path at `{context_file}`.
+
+### 2. Read the current file
+
+- If the file does not exist, skip this context file (nothing to rebuild — the file will be re-created the next time export-skill runs).
+- If the file exists but contains no `<!-- SKF:BEGIN -->` marker, skip this context file (no managed section to rewrite).
+- If the file contains `<!-- SKF:BEGIN -->` but no matching `<!-- SKF:END -->`, record the error against that context file and continue to the next entry — do not halt the entire rename on a malformed context file.
+
+### 3. Build the exported skill set (version-aware, deprecated-excluded)
+
+Use the same logic as `skf-export-skill/references/update-context.md` §4b and the snippet resolution from §4c:
+
+- Read the manifest's `exports` object (already updated in §6, so `{new_name}` is present and `{old_name}` is absent).
+- For each skill, resolve its `active_version`.
+- If `versions.{active_version}.status == "deprecated"`, skip that skill entirely.
+- For each remaining `{skill-name, active_version}` pair, read `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`.
+- If missing, fall back to the `active` symlink path; if still missing, skip with a warning.
+
+### 4. Rewrite root paths for the current context file
+
+Use the generic rewrite algorithm from `skf-export-skill/references/update-context.md` §4d:
+
+For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the **effective target prefix** if different. The effective target prefix is `snippet_skill_root_override` when that key is set in `config.yaml` — applied uniformly to every snippet so the managed section references the real on-disk location and never mixes override and per-IDE paths — otherwise the current entry's `skill_root`. See `skf-export-skill/references/update-context.md` §4d for full semantics.
+
+### 5. Sort and count
+
+Sort skills alphabetically by name. Count totals (skills, stack skills).
+
+### 6. Assemble the new managed section
+
+Use the format from `{managedSectionLogic}`:
+
+```markdown
+<!-- SKF:BEGIN updated:{current-date} -->
+[SKF Skills]|{n} skills|{m} stack
+|IMPORTANT: Prefer documented APIs over training data.
+|When using a listed library, read its SKILL.md before writing code.
+|
+|{skill-snippet-1}
+|
+|{skill-snippet-2}
+|
+|{skill-snippet-N}
+<!-- SKF:END -->
+```
+
+### 7. Surgical replacement — atomic, deterministic
+
+Invoke `{rebuildManagedSectionsHelper}` (resolved from `{rebuildManagedSectionsProbeOrder}` in `execute.md` frontmatter) for the surgical between-marker swap:
+
+```bash
+python3 {rebuildManagedSectionsHelper} {context_file} replace --content "{new_managed_section_text}"
+```
+
+The helper handles marker location, between-marker swap, atomic temp-file + rename, and post-write verification (markers preserved, content outside markers byte-identical). It exits non-zero on any failure with a clear `stderr` reason.
+
+### 8. Verify (deferred to helper)
+
+The `replace` action above performs verification internally. Treat any non-zero exit code as a per-file failure (next bullet).
+
+### 9. On per-file failure
+
+Record the error against that context file and continue to the next entry. Do not halt the rename on a recoverable per-context-file error — the manifest and filesystem are already consistent; context files can be re-rebuilt later via `[EX] Export Skill`.
+
+## After the loop
+
+- Record `context_files_updated` as the list of files that were successfully rewritten.
+- Record `context_files_failed` as the list of any that failed.
+
+Report: `**Rebuilt managed sections in:** {list of updated files}. {if any failed: 'Failed: {list} — re-run [EX] Export Skill to retry.'}`
+
+## Rollback semantics
+
+§7 failures **do not** trigger a rollback. The manifest and filesystem are the canonical state — context files are derived artifacts that can be regenerated at any time via `[EX] Export Skill`. The rename is considered successful as soon as §6 lands, even if §7 partially or fully fails to rewrite context files.

package/src/skf-rename-skill/{steps-c/step-03-report.md → references/report.md}

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-04-health-check.md'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the report block in {document_output_language}. -->
+
 # Step 3: Report Rename Results
 
 ## STEP GOAL:
@@ -10,15 +12,13 @@ Present a clear, final summary of what the rename workflow changed — old and n
 
 ## Rules
 
-- Focus only on reporting results stored in context by step-02 — do not re-execute any part of the rename
+- Focus only on reporting results stored in context by step 2 — do not re-execute any part of the rename
 - Do not hide verification warnings, context file rebuild failures, or deletion errors
 - Present next-steps guidance so the user knows which downstream workflows to run
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is NOT the terminal step
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly.
-
 ### 1. Render the Report
 
 Display the following block, filling in values from context:
@@ -71,7 +71,15 @@ Informational: the old name still appears in SKILL.md body text (prose only, non
 
 ### Result Contract
 
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/{new_name}/rename-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/{new_name}/rename-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all updated file paths (SKILL.md, metadata.json, context-snippet.md, provenance-map.json) in `outputs`; include `old_name`, `new_name`, and `versions_renamed` in `summary`.
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/{new_name}/rename-skill-result-{timestamp}.json` (reuse the activation-stored `{timestamp}`, resolution to seconds) and a copy at `{skills_output_folder}/{new_name}/rename-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all updated file paths (SKILL.md, metadata.json, context-snippet.md, provenance-map.json) in `outputs`; include `old_name`, `new_name`, and `versions_renamed` in `summary`.
+
+When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 4 (matches the SKILL.md "Result Contract (Headless)" shape):
+
+```
+SKF_RENAME_SKILL_RESULT_JSON: {"status":"success","old_name":"{old_name}","new_name":"{new_name}","versions_renamed":{affected_versions},"manifest_rekeyed":{manifest_rekeyed},"context_files_updated":{context_files_updated},"exit_code":0,"halt_reason":null}
+```
+
+Substitute `{affected_versions}` and `{context_files_updated}` as JSON arrays; `manifest_rekeyed` is the boolean from step 2's context.
 
 ### 2. Chain to Health Check
 

package/src/skf-rename-skill/{steps-c/step-01-select.md → references/select.md}

@@ -1,13 +1,15 @@
 ---
-nextStepFile: './step-02-execute.md'
+nextStepFile: 'execute.md'
 versionPathsKnowledge: 'knowledge/version-paths.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Select Rename Target
 
 ## STEP GOAL:
 
-Identify the skill the user wants to rename, validate the new name against the agentskills.io spec (kebab-case, length, uniqueness), warn about source authority implications, enumerate every version that will be touched, and obtain explicit user confirmation before any filesystem operation is scheduled. Every selection decision is stored in context so step-02 can execute the rename transactionally.
+Identify the skill the user wants to rename, validate the new name against the agentskills.io spec (kebab-case, length, uniqueness), warn about source authority implications, enumerate every version that will be touched, and obtain explicit user confirmation before any filesystem operation is scheduled. Every selection decision is stored in context so step 2 can execute the rename transactionally.
 
 ## Rules
 
@@ -18,8 +20,6 @@ Identify the skill the user wants to rename, validate the new name against the a
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Knowledge
 
 Read `{versionPathsKnowledge}` completely and extract:
@@ -28,19 +28,19 @@ Read `{versionPathsKnowledge}` completely and extract:
 - Export manifest v2 schema (`schema_version`, `exports`, `active_version`, `versions` map, `status` field values)
 - The Rename section under "Skill Management Operations" — the complete list of 9 locations that must be updated coherently
 
-You will use these templates and rules to build directory paths, enumerate affected versions, and plan the transactional rename in step-02.
+You will use these templates and rules to build directory paths, enumerate affected versions, and plan the transactional rename in step 2.
 
 ### 2. Read Export Manifest
 
 Load `{skills_output_folder}/.export-manifest.json` if it exists.
 
-**If the file is missing or empty:** Treat as an empty manifest — proceed to section 3 and rely entirely on the on-disk directory scan. Drafted or never-exported skills can still be renamed. Store `manifest_exists = false` for later use in step-02 (section 6 will not attempt to update a manifest that does not exist).
+**If the file is missing or empty:** Treat as an empty manifest — proceed to section 3 and rely entirely on the on-disk directory scan. Drafted or never-exported skills can still be renamed. Store `manifest_exists = false` for later use in step 2 (section 6 will not attempt to update a manifest that does not exist).
 
-**If the file exists but contains no `exports` entries:** Same handling — proceed to section 3 with the directory scan. Store `manifest_exists = true` so step-02 still touches the (empty) manifest on write.
+**If the file exists but contains no `exports` entries:** Same handling — proceed to section 3 with the directory scan. Store `manifest_exists = true` so step 2 still touches the (empty) manifest on write.
 
 **If the file exists with entries:** Parse JSON and verify `schema_version` is `"2"`. If the manifest is v1 (no `schema_version` field), note this but continue — treat every entry as having a single active version derived from its current state. Store `manifest_exists = true`.
 
-**Hard halt condition:** If the file exists but is malformed (not valid JSON), halt with: "**Export manifest is corrupt** at `{skills_output_folder}/.export-manifest.json` — fix or remove the file before renaming."
+**Hard halt condition:** If the file exists but is malformed (not valid JSON), halt with: "**Export manifest is corrupt** at `{skills_output_folder}/.export-manifest.json` — fix or remove the file before renaming." HALT (exit code 3, `halt_reason: "manifest-corrupt"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `old_name: null`, `new_name: null`.
 
 ### 3. List Available Skills
 
@@ -54,7 +54,7 @@ For each skill in the manifest's `exports` (if `manifest_exists` and entries exi
 
 Also scan `{skills_output_folder}/` for any top-level directories that are NOT present in the manifest's `exports` object. Record these as "(not in manifest)" — they represent draft or orphaned skills that the rename workflow can also handle. When the manifest is missing or empty, every on-disk skill appears in this category.
 
-**If the combined list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Rename Skill — nothing to rename.** No skills found in `{skills_output_folder}/`. Run `[CS] Create Skill` first."
+**If the combined list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Rename Skill — nothing to rename.** No skills found in `{skills_output_folder}/`. Run `[CS] Create Skill` first." HALT (exit code 3, `halt_reason: "nothing-to-rename"`). In headless mode, emit the error envelope with `old_name: null`, `new_name: null`.
 
 Display the combined list:
 
@@ -70,20 +70,55 @@ Available skills:
 ### 4. Ask Which Skill
 
 "**Which skill would you like to rename?**
-Enter the skill name or its number from the list above."
+Enter the skill name or its number from the list above, or `cancel` / `exit` / `:q` to abort."
 
-Wait for user input. Accept either the numeric index or the skill name (exact match). **GATE [default: use args]** — If `{headless_mode}` and old skill name was provided as argument: select that skill and auto-proceed. If not provided, HALT: "headless mode requires old_name argument."
+Wait for user input. Accept either the numeric index or the skill name (exact match). **GATE [default: use args]** — If `{headless_mode}` and old skill name was provided as argument: select that skill and auto-proceed. If not provided, HALT (exit code 2, `halt_reason: "input-missing"`): "headless mode requires old_name argument." In headless, emit the error envelope.
 
-**If the user's input does not match any listed skill:** Re-display the list and ask again.
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: Display "Cancelled — no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+- **If the user's input does not match any listed skill:** Re-display the list and ask again.
 
 Store the selection as `old_name`.
 
+### 4b. Concurrency Guard
+
+Two concurrent rename runs against the same `old_name` would corrupt state mid-copy: one would `rm -rf` the other's freshly-staged new directories, or both would race on the manifest re-key. The lock below catches the common accidental-double-invoke case. It is a **best-effort PID-file guard**, not a held flock — the LLM-driven workflow spans many turn boundaries and no single bash invocation can hold flock across them.
+
+**Mirror this exactly so the guard works the same way every run:**
+
+```bash
+LOCK={forge_data_folder}/{old_name}/.skf-rename.lock
+mkdir -p "$(dirname "$LOCK")"
+
+if [ -f "$LOCK" ]; then
+  HELD_PID=$(head -n1 "$LOCK" 2>/dev/null | awk '{print $1}')
+  if [ -n "$HELD_PID" ] && kill -0 "$HELD_PID" 2>/dev/null; then
+    echo "skf-rename-skill: another rename is in progress (pid=$HELD_PID, started $(awk 'NR==2' "$LOCK" 2>/dev/null))"
+    exit 1
+  fi
+  echo "skf-rename-skill: clearing stale lock from pid=$HELD_PID"
+fi
+
+printf '%s\n%s\n' "$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$LOCK"
+```
+
+**Halt protocol on live-PID collision:**
+
+- Display: `"**Another rename is in progress.** The skill {old_name} is locked by pid={HELD_PID} (started {timestamp from line 2 of the lock file}). Wait for that run to finish, or — if you know that pid is no longer running — delete {LOCK} manually and re-run."`
+- HALT (exit code 5, `halt_reason: "halted-for-concurrent-run"`). In `{headless_mode}`, emit the error envelope per SKILL.md "Result Contract (Headless)" with `old_name: "{old_name}"`, `new_name: null`. **No `headless_decisions[]` entry** — this is a hard halt before any gate fires.
+
+**Release contract:**
+
+- The terminal health-check step (step 4) deletes the lock as its final action.
+- **Every halted-for-\* path in this workflow must delete the lock before exiting** — otherwise the next attempt would see a stale lock from this run. The lock-release is a single `rm -f "$LOCK"` per halt site.
+
 ### 5. Ask for New Name
 
 "**What is the new name for this skill?**
-The new name must be kebab-case: lowercase alphanumeric with hyphens, 1-64 characters, matching the regex `^[a-z][a-z0-9-]*[a-z0-9]$` (single-character names may be a single lowercase letter or digit)."
+The new name must be kebab-case: lowercase alphanumeric with hyphens, 1-64 characters, matching the regex `^[a-z][a-z0-9-]*[a-z0-9]$` (single-character names may be a single lowercase letter or digit). Or type `cancel` / `exit` / `:q` to abort."
 
-Wait for user input. Trim whitespace. **GATE [default: use args]** — If `{headless_mode}` and new_name was provided as argument: use it and auto-proceed through validation. If not provided, HALT: "headless mode requires new_name argument."
+Wait for user input. Trim whitespace. **GATE [default: use args]** — If `{headless_mode}` and new_name was provided as argument: use it and auto-proceed through validation. If not provided, release the lock and HALT (exit code 2, `halt_reason: "input-missing"`): "headless mode requires new_name argument." In headless, emit the error envelope.
+
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), display "Cancelled — no changes were made.", and HALT (exit code 6, `halt_reason: "user-cancelled"`).
 
 Apply the following validations in order:
 
@@ -106,7 +141,7 @@ Apply the following validations in order:
 
    If any collision is detected:
    "**Name collision.** `{new-name}` already exists at: {list the colliding locations}. Pick a different name."
-   Re-ask.
+   Re-ask. In headless mode, instead of re-asking, release the lock and HALT (exit code 5, `halt_reason: "name-collision"`) and emit the error envelope.
 
 Only after all four validations pass, store the input as `new_name`.
 
@@ -129,11 +164,13 @@ registry will still get the original name. Rename is a LOCAL operation only —
 does not rename anything at the registry.
 ```
 
-Ask: "**Continue anyway?** [Y/N]"
+Ask: "**Continue anyway?** [Y/N] (or `cancel` / `exit` / `:q` to abort)"
 
 Wait for response.
-- **If `N`** or anything other than `Y` → "**Cancelled.** No changes were made." HALT the workflow.
-- **If `Y`** → proceed.
+- **If `N`** (or `cancel` / `exit` / `[X]` / `:q`) → release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), display "**Cancelled.** No changes were made.", HALT (exit code 6, `halt_reason: "user-cancelled"`).
+- **If `Y`** → proceed. Set `source_authority_override = true`.
+
+**Headless behavior:** If `{headless_mode}` is true AND `{forceSourceAuthorityInHeadless}` is `"true"`, auto-proceed and record `{gate: "source-authority", default_action: "halt", taken_action: "proceed", reason: "force_source_authority_in_headless override"}` in `headless_decisions[]`. Otherwise, release the lock and HALT (exit code 5, `halt_reason: "source-authority-blocked"`) and emit the error envelope — the safe default protects against silent registry-divergence on `published`-tagged skills.
 
 **If `source_authority` is absent, or any value other than `"official"`:** skip the warning and proceed.
 
@@ -192,13 +229,15 @@ Proceed? [Y/N]
 
 Wait for explicit user response.
 
+**If `--dry-run` was passed**: skip the Y/N prompt entirely. Release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), display "**[DRY RUN] No changes were made — preview above shows what would be renamed.**", and emit the success envelope per SKILL.md "Result Contract (Headless)" with `status: "dry-run"`, the resolved `old_name`, `new_name`, and `versions_renamed: {affected_versions}`, then HALT (exit code 0). No copy, no manifest re-key, no delete.
+
 - **If `Y`** → proceed to section 9
-- **If `N`** → "**Cancelled.** No changes were made." HALT the workflow
+- **If `N`** (or `cancel` / `exit` / `[X]` / `:q`) → release the lock (`rm -f {forge_data_folder}/{old_name}/.skf-rename.lock`), display "**Cancelled.** No changes were made.", HALT (exit code 6, `halt_reason: "user-cancelled"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with the resolved `old_name` and `new_name`.
 - **Any other input** → re-display the confirmation and ask again
 
 ### 9. Store Decisions in Context
 
-Store the following decisions in workflow context for step-02:
+Store the following decisions in workflow context for step 2:
 
 - `old_name` — the current skill name
 - `new_name` — the validated new name

package/src/skf-setup/SKILL.md

@@ -1,13 +1,21 @@
 ---
 name: skf-setup
-description: Initialize forge environment, detect tools, and set capability tier (Quick/Forge/Forge+/Deep). Use when the user requests to "set up" or "initialize the forge."
+description: Initialize forge environment, detect tools, and set capability tier (Quick/Forge/Forge+/Deep). Use when the user requests to "set up" or "initialize the forge".
 ---
 
 # Setup Forge
 
 ## Overview
 
-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.
+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 non-interactively when `{headless_mode}` is true or when `--orphan-action=<keep|remove>` is passed.
+
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
 
 ## Role
 
@@ -15,56 +23,48 @@ You are a system executor performing environment resolution. Run each step in se
 
 ## Workflow Rules
 
-These rules apply to every step in this workflow:
-
-- 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
-- Always communicate in `{communication_language}`
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- One optional gate (step 3 orphan-removal prompt; default: Keep). Every other step auto-proceeds.
+- Only load one step file at a time — never preload future steps.
+- Communicate in `{communication_language}`.
+- If `{headless_mode}` is true, or if `{orphan_action}` is non-null, auto-resolve the gate non-interactively and log the decision.
 
 ## Stages
 
-| # | Step | File | Auto-proceed |
-|---|------|------|--------------|
-| 1 | Detect Tools & Set Tier | steps-c/step-01-detect-and-tier.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 + 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 |
+All stages auto-proceed except the optional orphan-removal gate in step 3.
+
+| # | Step | File |
+|---|------|------|
+| 1 | Detect Tools & Set Tier | references/detect-and-tier.md |
+| 1b | CCC Index (only when ccc is available) | references/ccc-index.md |
+| 2 | Write Config | references/write-config.md |
+| 3 | QMD + CCC Registry Hygiene | references/auto-index.md |
+| 4 | Report | references/report.md |
+| 5 | Workflow Health Check | references/health-check.md |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **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) |
+| **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); `--orphan-action=<keep\|remove>` (resolve the orphan-removal gate non-interactively, even outside `--headless`); `--ccc-skip-index` (skip CCC indexing; envelope `ccc_index.status` becomes `"skipped"`); `--quiet` (suppress the human-readable FORGE STATUS banner — pipelines and expert re-runners get the envelope only) |
+| **Gates** | One optional: orphaned QMD collection removal (step 3, Deep tier only; default: Keep, or whatever `--orphan-action` set) |
 | **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. |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Under `--headless` or `--quiet`, step 4 emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope as the only stdout line — the FORGE STATUS banner is suppressed. Branch on the envelope's top-level `status` field (one of `success`, `tier_failure`, `write_failure`, `blocked`) — `skf-emit-result-envelope.py` derives it from the payload, so pipelines never compose it from `require_tier_satisfied` + `error`. Schema in `references/report.md` §4. |
+| **Failure modes** | `--require-tier` not satisfied → status becomes `tier_failure`, the envelope sets `"require_tier_satisfied": false`, and the workflow halts before step 5 (interactive runs also print a "REQUIRED TIER NOT MET" block). |
 | **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. **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`
+> **Halt contract for headless/quiet runs.** Any halt below MUST first emit a blocked envelope when `{headless_mode}` or `{quiet_mode}` is true, before printing the human diagnostic. Pipe `{"phase":"<phase>","reason":"<reason>","path":"<path>"}` to `python3 <helper> emit-blocked` where `<helper>` is the first existing path of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` then `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`. The `emit-blocked` subcommand declares zero dependencies (no `uv`, no `pyyaml`), so it works even when `uv` itself is the thing that's missing.
 
-   **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:
+1. **Parse invocation flags FIRST** (so every halt below knows whether to emit an envelope): `{headless_mode}` (true on `--headless` / `-H`), `{require_tier}` (`--require-tier=<Quick|Forge|Forge+|Deep>`, case-sensitive; null if absent or unparseable), `{orphan_action}` (`--orphan-action=<keep|remove>`; null if absent), `{ccc_skip_index}` (true on `--ccc-skip-index`), `{quiet_mode}` (true on `--quiet`).
 
-   "**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."
+2. **Probe `uv` runtime.** Run `uv --version`. Every step invokes shared Python helpers via `uv run` (PEP 723 inline metadata auto-resolves `pyyaml`). If `uv` is missing, halt with phase `on-activation:uv-missing` and the human diagnostic:
 
-   **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."
+   "**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`."
 
-3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+3. **Load config** from `{project-root}/_bmad/skf/config.yaml` and resolve `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`. Halt with phase `on-activation:config-missing` if the file does not exist, or `on-activation:config-malformed` if the YAML is invalid, with the matching human diagnostic.
 
-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).
+4. **Reconcile `{headless_mode}`** with `preferences.yaml`: OR the parsed flag with `headless_mode: true` from the YAML.
 
-5. Load, read the full file, and then execute `./steps-c/step-01-detect-and-tier.md` to begin the workflow.
+5. Execute `references/detect-and-tier.md`.

package/src/skf-setup/customize.toml

@@ -0,0 +1,33 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-setup.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (auth, network,
+# compliance) that must precede any forge setup work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (standards, compliance constraints, stylistic guardrails). Overrides
+# append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Forge writes must be reproducible in CI."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/forge-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = []

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

@@ -1,5 +1,5 @@
 ---
-nextStepFile: './step-04-report.md'
+nextStepFile: '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
@@ -35,7 +35,7 @@ For Quick and Forge tiers, skip silently and proceed (QMD is not available; ccc
 
 ### 1. Check Tier
 
-Read `{calculated_tier}` and `{ccc}` from context (set by step-01).
+Read `{calculated_tier}` and `{ccc}` from context (set by step 1).
 
 **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.
 
@@ -47,31 +47,23 @@ Read `{calculated_tier}` and `{ccc}` from context (set by step-01).
 
 ### 2. Classify Live QMD Collections vs Registry
 
-List live QMD collections:
-
-```bash
-qmd collection list
-```
-
-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).
-
-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.
+Run the classifier — it owns the `qmd collection list` invocation and stdout parsing. Invoke via `uv run`:
 
 ```bash
 uv run {qmdClassifyHelper} \
-    --live-names "{live_collections}" \
     --registry-from-yaml "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"
 ```
 
-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.
+The script (see `src/shared/scripts/skf-qmd-classify-collections.py` docstring for the full schema) invokes `qmd collection list` itself, applies the forge-namespace suffix filter (`-brief | -temporal | -docs | -extraction`) before classifying, and exits non-zero with an error message on stderr if the daemon is down. 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: foreign collections never enter any classification that could lead to data loss.
+
+**Error handling:** If the script exits non-zero, set `{hygiene_result: "qmd_unavailable", hygiene_healthy: 0, hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0, hygiene_stale_cleaned: 0}` and skip directly to section 4 (which will still run the ccc-prune branch if `{ccc}` is true).
 
 **Parse the JSON output and set context flags:**
 
 - `{hygiene_healthy}` ← `len(healthy)`
 - `{orphaned_collections}` ← `orphaned` (the list — used in section 3)
 - `{stale_collections}` ← `stale` (the list — used in section 4)
+- `{live_collections}` ← comma-join of `live_names` (used in §4's clean-stale invocation; the script owns the raw set, the prompt only forwards it)
 - `{foreign_filtered_count}` ← `foreign_filtered_count`
 
 Set `{hygiene_result: "completed"}`.
@@ -80,7 +72,7 @@ Set `{hygiene_result: "completed"}`.
 
 **If `{orphaned_collections}` is empty:** Set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0}` and skip to section 4.
 
-**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.
+**Non-interactive resolution.** If `{orphan_action}` is non-null, resolve the gate without prompting using that value: log `"Auto-decision (--orphan-action={value}): kept|removed {len(orphaned_collections)} orphaned forge collection(s)"`. If `{orphan_action}` is `"keep"`, set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: len(orphaned_collections)}` and skip to section 4. If `"remove"`, fall through to the removal block below (still no user prompt). Independently, if `{headless_mode}` is true and `{orphan_action}` is null, auto-resolve to the default **Keep** with the equivalent log line and skip to section 4. The two paths compose: `--orphan-action` overrides the headless default; `--headless` without `--orphan-action` keeps backward-compatible behavior.
 
 **If `{headless_mode}` is false**, display to the user:
 
@@ -118,11 +110,11 @@ uv run {forgeTierRwHelper} clean-stale \
 
 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).
 
-**Parse the JSON output and set context flags for step-04:**
+**Parse the JSON output and set context flags for step 4:**
 
 - `{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)
+- `{ccc_registry_stale_removed_paths}` ← `ccc_removed` (the list — step 4 folds individual paths into envelope warnings)
 
 If `{hygiene_stale_cleaned}` > 0, display: "**Cleaned {hygiene_stale_cleaned} stale QMD registry entry/entries** (collection no longer exists in QMD)."