bmad-module-skill-forge 1.1.0 → 1.2.0

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.

package/src/skf-setup/steps-c/step-04-report.md

@@ -1,31 +1,47 @@
 ---
 tierRulesData: 'references/tier-rules.md'
 nextStepFile: './step-05-health-check.md'
+# Resolve `{emitEnvelopeHelper}` by probing `{emitEnvelopeProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves when the headless envelope must be emitted
+# — the script is the source of truth for the SKF_SETUP_RESULT_JSON contract;
+# never inline-render the envelope from prose (LLM schema drift is the bug
+# this script exists to prevent).
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
 ---
 
+<!-- Config: communicate in {communication_language}; emit user-visible report text (FORGE STATUS banner, climb hint, REQUIRED TIER NOT MET block, breadcrumb) in {document_output_language}. The JSON envelope from section 4 is a machine contract — its keys and enum values stay English regardless. -->
+
 # Step 4: Forge Status Report
 
 ## STEP GOAL:
 
-Display the forge status report with positive capability framing and report tier changes on re-run.
+Display the forge status report with positive capability framing, surface tier changes and tool-set deltas on re-runs, prominently flag a required-tier miss, and (when headless) emit the schema-locked `SKF_SETUP_RESULT_JSON` envelope via `{emitEnvelopeHelper}`.
 
 ## Rules
 
-- Focus only on displaying the status report
+- Focus only on display + envelope emission
 - Do not use negative framing ("missing", "lacking", "unavailable")
 - Do not list tools that are not available
 - Use tier capability descriptions from tier-rules.md
+- Never inline-render the envelope JSON — the script owns the schema; drift breaks pipelines
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing status report is NOT the terminal step
 
-## MANDATORY SEQUENCE
+## Headless Mode Display Rule
+
+When `{headless_mode}` is `true`, sections 2 (the human-readable banner) and 3 (the REQUIRED TIER NOT MET human prose block) are **skipped entirely**. The single line of stdout in headless mode is the `SKF_SETUP_RESULT_JSON: {…}` envelope from section 4 — every signal the human banner would have surfaced is already in the envelope (`tier`, `previous_tier`, `tier_changed`, `tools`, `tools_added`, `tools_removed`, `files_written`, `tier_override_*`, `require_tier_satisfied`, `warnings`, `error`). Parent skills and CI pipelines consume one parseable line; they should not be forced to scroll past 30 lines of ASCII-art they cannot use.
+
+When `{headless_mode}` is `false`, sections 2 and 3 display normally and section 4 is skipped (interactive runs read the human banner; envelope emission would just be log noise).
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+## MANDATORY SEQUENCE
 
 ### 1. Load Capability Descriptions
 
-Load and read {tierRulesData} for the tier capability descriptions and re-run messages.
+Load and read {tierRulesData} for the tier capability descriptions and re-run messages. Needed by section 2; safe to load unconditionally — the data load itself is silent.
 
-### 2. Display Forge Status Report
+### 2. Display Forge Status Report (skip when `{headless_mode}` is true)
 
 **Format the report as follows:**
 
@@ -39,6 +55,17 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
 
   Tools Detected:
   {for each tool that is available, show: tool name — version}
+  {if no tools are available: (none yet — see "Climb to next tier" below)}
+
+  {if calculated_tier is not Deep:}
+  Climb to next tier:
+  {if not tools.ast_grep: - Install ast-grep (https://ast-grep.github.io) — unlocks AST-backed code analysis (Forge tier)}
+  {if tools.ast_grep and not tools.ccc: - Install cocoindex-code (https://github.com/cocoindex-io/cocoindex-code) — adds semantic-guided precision compilation (Forge+ tier)}
+  {if tools.ast_grep and not tools.gh_cli: - Install GitHub CLI (https://cli.github.com) — required for Deep tier (cross-repository synthesis)}
+  {if tools.ast_grep and not tools.qmd and qmd_status is "absent": - Install qmd (https://github.com/tobi/qmd) — required for Deep tier (knowledge search)}
+  {if tools.ast_grep and not tools.qmd and qmd_status is "daemon_stopped": - Start the qmd daemon (already installed) — run `qmd start` (or your distribution's qmd service command) to unlock Deep tier (knowledge search)}
+  {if tools.ccc and ccc_daemon is "error": - The ccc daemon is reporting errors — run `ccc doctor` to diagnose. CCC index will fail until resolved (mirrors the qmd daemon-stopped pattern above for parity)}
+  {end if}
 
   {if hygiene_result is "completed":}
   QMD Registry:
@@ -63,30 +90,127 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {if ccc_index_result is "failed": indexing failed — semantic discovery unavailable this session}
   {end if}
 
+  Files written this run:
+  - forge-tier.yaml — {project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml
+  {if preferences_yaml_created is true:}
+  - preferences.yaml — {project-root}/_bmad/_memory/forger-sidecar/preferences.yaml (first-run defaults)
+  {end if}
+  {if forge_data_dir_created is true:}
+  - {forge_data_folder}/ (directory created)
+  {end if}
+  {if settings_yml_written is true:}
+  - .cocoindex_code/settings.yml — {project-root}/.cocoindex_code/settings.yml ({settings_yml_patterns_added} SKF exclusion pattern(s) merged)
+  {end if}
+  {if ccc_index_result is "created":}
+  - .cocoindex_code/ ccc index — {ccc_file_count} files indexed
+  {end if}
+
 {if tier_override is active:}
   Note: Tier override active (set in preferences.yaml)
 
+{if tier_override_invalid is true:}
+  Note: tier_override value "{tier_override_invalid_value}" in preferences.yaml is not valid.
+        {if tier_override_invalid_suggestion is non-null: Did you mean "{tier_override_invalid_suggestion}"?}
+        Valid values are case-sensitive: Quick, Forge, Forge+, Deep. Using detected tier {calculated_tier}.
+
+{if tier_override_unsafe is true:}
+  Warning: tier_override is forcing {calculated_tier} but the underlying tool prerequisites are not satisfied.
+           Missing: {tier_override_unsafe_missing}. The override is honored, but downstream skills that
+           rely on the missing tool(s) will fail at runtime. Install the missing tool(s) or remove
+           the override from preferences.yaml.
+
 {if re-run with tier change:}
   {appropriate upgrade/downgrade message from tier-rules.md}
 
-{if re-run with same tier:}
+{if re-run with same tier and {tools_added} is empty and {tools_removed} is empty:}
   {same-tier message from tier-rules.md}
 
+{if re-run with same tier and ({tools_added} or {tools_removed} is non-empty):}
+  Tier unchanged: {calculated_tier}.
+  {if {tools_added} non-empty:} Newly detected: {comma-separated tool names from tools_added}{if ccc was added and tier is Deep: " — ccc enhances Deep tier transparently."}
+  {if {tools_removed} non-empty:} No longer detected: {comma-separated tool names from tools_removed} — re-install to restore those capabilities.
+
 ═══════════════════════════════════════
   Forge ready. {calculated_tier} tier active.
 ═══════════════════════════════════════
+
+{if {headless_mode} is false:}
+  Next: try [BS] Brief Skill to scope your first compilation target, or [QS] Quick Skill for a fast template-driven path. Already have a skill? [AS] Audit Skill drift-checks an existing skill against current sources.
 ```
 
+The same-tier-with-tool-deltas branch reads `{tools_added}` and `{tools_removed}` directly from step-01's context (set from `skf-detect-tools.py` output relative to `{previous_tools}`). No LLM-side recomputation.
+
 **Tool display rules:**
+
 - Only show tools that ARE available with their version strings
 - Do NOT list unavailable tools
 - Do NOT show a "missing" column or section
 
-### 3. Chain to Health Check
+### 3. Display Required-Tier Failure Block (when applicable; skip when `{headless_mode}` is true)
+
+If `{require_tier_satisfied}` is `false` AND `{headless_mode}` is `false`, display this block immediately after the status report. In headless mode the failure surfaces via the envelope's `require_tier_satisfied: false` and the synthesized `warnings` entry — the human prose block would be log noise that pipelines have to scroll past.
+
+When the block does fire (interactive run with require-tier failure):
+
+```
+═══════════════════════════════════════
+  REQUIRED TIER NOT MET
+═══════════════════════════════════════
+
+  Required:  {require_tier}
+  Detected:  {calculated_tier}
+  Missing:   {require_tier_failure_missing_tools}
+
+  Install the missing tool(s) and re-run, or relax `--require-tier`.
+  See "Climb to next tier" above for install URLs.
+═══════════════════════════════════════
+```
+
+This block exists to make pipeline failures visible without the operator parsing the JSON envelope.
+
+### 4. Emit Headless JSON Envelope
+
+When `{headless_mode}` is `true`, build the context payload from this step's accumulated flags and forward it to `{emitEnvelopeHelper}` on stdin. Invoke via `uv run` so the script's PEP 723 dependency declarations are honored (the canonical runtime invocation per `docs/getting-started.md`'s uv prereq — bare `python3` skips the metadata block and breaks on a fresh interpreter). The script computes derived fields (`tools_added`, `tools_removed`, `tier_changed`, `warnings`), validates the assembled envelope against the JSON Schema at `src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`, and emits the single prefixed line `SKF_SETUP_RESULT_JSON: {…}` on stdout.
+
+```bash
+echo '{
+  "tier": "{calculated_tier}",
+  "previous_tier": {previous_tier_or_null},
+  "tools": {tools_dict_from_step_01_or_skf_detect_tools_output},
+  "previous_tools": {previous_tools_or_null},
+  "config_path": "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml",
+  "ccc_index": {
+    "status": "{ccc_index_result}",
+    "indexed_path": {ccc_indexed_path_or_null},
+    "file_count": {ccc_file_count_or_null}
+  },
+  "files_written": {
+    "forge-tier.yaml": true,
+    "preferences.yaml": {preferences_yaml_created},
+    "settings.yml": {settings_yml_written},
+    "ccc_index": {ccc_index_result_was_created}
+  },
+  "tier_override_active": {tier_override_active},
+  "tier_override_invalid": {tier_override_invalid},
+  "tier_override_invalid_value": {tier_override_invalid_value_or_null},
+  "tier_override_unsafe": {tier_override_unsafe},
+  "tier_override_unsafe_missing": {tier_override_unsafe_missing_list},
+  "require_tier_satisfied": {require_tier_satisfied_or_null},
+  "require_tier_failure_missing": {require_tier_failure_missing_tools_list},
+  "qmd_status": "{qmd_status}",
+  "ccc_exclusion_warnings": {ccc_exclusion_warnings_list},
+  "ccc_registry_stale_removed": {ccc_registry_stale_removed_paths_list},
+  "ccc_indexing_failed_reason": {ccc_indexing_failed_reason_or_null},
+  "error": {error_object_or_null}
+}' | uv run {emitEnvelopeHelper} emit
+```
+
+The script's documented context-payload shape (see `src/shared/scripts/skf-emit-result-envelope.py` docstring) tolerates two `tools` shapes — bare booleans OR `skf-detect-tools.py`'s `{key: {available: bool, ...}}` output — so either step-01's normalized booleans OR the raw detect-tools output forwarded as-is will produce the correct envelope.
 
-ONLY WHEN the forge status report has been displayed will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+**If the script exits non-zero:** the assembled envelope failed schema validation, which means a context flag from an earlier step is malformed. Surface the error to stderr and continue (the human-readable banner is already displayed; missing JSON envelope on a headless run is a degraded but non-fatal state — the pipeline observer will see no envelope and treat that as "agent did not complete cleanly").
 
-## CRITICAL STEP COMPLETION NOTE
+**When `{headless_mode}` is `false`, do NOT invoke the script** — interactive runs read the human-readable banner.
 
-This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the setup workflow is fully done.
+### 5. Chain to Health Check
 
+After the forge status report (and any failure block + JSON envelope) has been displayed, load `{nextStepFile}`, read it fully, and execute it — UNLESS `{require_tier_satisfied}` is `false`, in which case halt the workflow here without chaining to step-05. The health-check step is the true terminal step on success — do not stop after the report on a passing run even though it reads as final. step-05 in turn delegates to `shared/health-check.md`; after that returns, the setup workflow is fully done.