bmad-module-skill-forge 1.1.0 → 1.3.0

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.

package/src/skf-setup/steps-c/step-05-health-check.md

@@ -1,10 +1,12 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. This is a delegation-only step (no user-visible output of its own); shared/health-check.md inherits the language directive on load. -->
+
 # Step 5: Workflow Health Check
 
 ## STEP GOAL:

package/src/skf-test-skill/steps-c/step-01-init.md

@@ -91,10 +91,10 @@ SKF module (`skf init`) or run from a development checkout with src/ present.
 
 Do not proceed. No partial test report is written.
 
-**3b. Run the validator (30s timeout — deterministic validator should finish in <1s; the cap only guards against runaway python):**
+**3b. Run the validator (30s timeout — deterministic validator should finish in <1s; the cap only guards against runaway python).** Invoke via `uv run` so the script's PEP 723 PyYAML dependency resolves automatically; bare `python3` would fail with `ModuleNotFoundError: No module named 'yaml'` on a fresh interpreter (`docs/getting-started.md` documents uv as the runtime prereq for exactly this).
 
 ```bash
-timeout 30s python3 {frontmatterScript} {resolved_skill_package}/SKILL.md --skill-dir-name {skill_name}
+timeout 30s uv run {frontmatterScript} {resolved_skill_package}/SKILL.md --skill-dir-name {skill_name}
 ```
 
 If the command trips the 30s wall-clock (exit code `124`), set
@@ -116,7 +116,7 @@ Parse the JSON output. Per B2, treat each `status` value explicitly:
 This skill will fail `npx skills add` and `npx skill-check check`. {If warn:} Consider fixing frontmatter before proceeding (run `npx skill-check check <skill-dir> --fix` to auto-fix deterministic issues). {If fail:} test-skill cannot proceed — halt and repair frontmatter, then re-run.
 ```
 
-**3c. Python runtime probe.** Before the first invocation, confirm `python3` is on `$PATH` (`command -v python3`). If missing, set `analysis_confidence: degraded` in workflow context and carry a **score cap** into step-05: `capped_score = threshold - 1` → forces auto-FAIL until the runtime is restored. Record the reason in evidence-report and the test report frontmatter (`analysisConfidence: degraded`, `toolingStatus: python3-missing`).
+**3c. Python runtime probe.** Before the first invocation, confirm both `python3` AND `uv` are on `$PATH` (`command -v python3` and `command -v uv`). Both are required: `uv run` shells through to `python3` under the hood AND honors the script's PEP 723 PyYAML dependency declaration that bare `python3` ignores. If either is missing, set `analysis_confidence: degraded` in workflow context and carry a **score cap** into step-05: `capped_score = threshold - 1` → forces auto-FAIL until the runtime is restored. Record the reason in evidence-report and the test report frontmatter (`analysisConfidence: degraded`, `toolingStatus: python3-missing` or `uv-missing` as appropriate). `uv` is a documented runtime prerequisite — see `docs/getting-started.md` for install instructions.
 
 ### 4. Load Forge Tier State
 
@@ -199,7 +199,7 @@ testResult: ''
 score: ''
 threshold: ''
 analysisConfidence: '{full|degraded}'
-toolingStatus: '{ok|python3-missing|frontmatter-validator-missing|frontmatter-validator-timeout}'
+toolingStatus: '{ok|python3-missing|uv-missing|frontmatter-validator-missing|frontmatter-validator-timeout}'
 workspaceDrift: '{not-checked|ok|overridden}'
 testDate: '{run_id timestamp ISO-8601 UTC}'
 stepsCompleted: ['step-01-init']