bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-setup/references/report.md

@@ -1,11 +1,10 @@
 ---
-tierRulesData: 'references/tier-rules.md'
 nextStepFile: 'health-check.md'
 # `{emitEnvelopeHelper}` = first existing path in `{emitEnvelopeProbeOrder}`;
-# halt if neither exists when the headless envelope must be emitted. The script
-# is the source of truth for the SKF_SETUP_RESULT_JSON contract — do not
-# inline-render the envelope from prose (LLM schema drift is the bug this
-# script exists to prevent).
+# halt if neither exists when section 4 emits the envelope. The script is the
+# source of truth for the SKF_SETUP_RESULT_JSON contract: do not 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'
@@ -17,196 +16,74 @@ emitEnvelopeProbeOrder:
 
 ## STEP GOAL:
 
-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}`.
+Stage the run's report payload, display the FORGE STATUS banner that `{emitEnvelopeHelper}` renders from it (tier, tools, an upgrade for each tool below its minimum version, tier changes and tool-set deltas on re-runs, and a REQUIRED TIER NOT MET block on a required-tier miss), and (when headless or quiet) emit the schema-locked `SKF_SETUP_RESULT_JSON` envelope from the same payload.
 
 ## Rules
 
 - 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
+- The FORGE STATUS lines come from `render-report`: display them (translated when needed), and never compose, add or drop a line yourself
 - 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
+- Display messages only when `{quiet_mode}` is false; the one exception is the envelope line section 4 builds, which section 5 displays on a tier miss and the shared health check displays last otherwise
+- When `{quiet_mode}` is true, write no assistant text at all between tool calls: no status, progress or step-transition notes, however brief
+- If section 4 finds no existing path in `emitEnvelopeProbeOrder`, halt with phase `step 4:helper-missing`, `path` set to its first entry, and reason `Setup cannot proceed: skf-emit-result-envelope.py was not found. Reinstall SKF, then re-run /skf-setup.` With no envelope helper to call, display that reason alone as the run's one line (the SKILL.md halt contract)
 
 ## MANDATORY SEQUENCE
 
-### 1. Load Capability Descriptions
+### 1. Stage the Report Payload
 
-Load and read {tierRulesData} for the tier capability descriptions and re-run messages. Needed by section 2.
+Sections 2 and 4 read the helper outputs the run folder holds (`detect-tools.json`, `ccc-exclusions.json`, `qmd-classify.json`, `qmd-remove.json` and `clean-stale.json`, each when its step ran the helper), take the run's paths from `--project-root`, `--sidecar-path` and `--forge-data-folder` (the folders On Activation bound from preflight), and read one payload file with what neither gives, staged here on every run through a quoted heredoc:
 
-### 2. Display Forge Status Report (skip when `{headless_mode}` or `{quiet_mode}` is true)
-
-**Format the report as follows:**
-
-```
-═══════════════════════════════════════
-  FORGE STATUS
-═══════════════════════════════════════
-
-  Tier:  {calculated_tier}
-  {tier capability description from tier-rules.md}
-
-  Tools Detected:
-  {for each tool that is available, show: tool name — version. ccc exposes no version string, so for ccc show its daemon health instead: ccc — daemon {ccc_daemon} (e.g. "ccc — daemon healthy")}
-  {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}
-  {end if}
-
-  {if hygiene_result is "completed":}
-  QMD Registry:
-  {hygiene_healthy} collection(s) healthy
-  {if hygiene_orphaned_removed > 0: {hygiene_orphaned_removed} orphaned collection(s) removed}
-  {if hygiene_orphaned_kept > 0: {hygiene_orphaned_kept} orphaned collection(s) kept}
-  {if hygiene_stale_cleaned > 0: {hygiene_stale_cleaned} stale QMD registry entry/entries cleaned}
-  {end if}
-
-  {if ccc_registry_stale_cleaned > 0:}
-  CCC Registry: {ccc_registry_stale_cleaned} stale entry/entries cleaned
-  {end if}
-
-  {if hygiene_result is "completed" and hygiene_healthy is 0:}
-  QMD Registry: empty — collections are created automatically when you run /skf-create-skill.
-  {end if}
-
-  {if hygiene_result is "qmd_unavailable":}
-  QMD Registry: skipped (qmd unavailable — if the daemon is stopped, `qmd start` restores it).
-  {end if}
-
-  {if tools.ccc is true:}
-  CCC Index:
-  {if ccc_index_result is "fresh": up to date — semantic discovery ready}
-  {if ccc_index_result is "created": indexed this run — semantic discovery ready}
-  {if ccc_index_result is "skipped": skipped (--ccc-skip-index) — run `/skf-setup` without --ccc-skip-index to build the index when you're ready}
-  {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}
-  - {forge_data_folder}/ (directory ensured)
-  {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 {previous_tier} is null:}
-  Initial detection — {calculated_tier} tier established.
-
-{if {tier_changed} is true:}
-  {appropriate upgrade/downgrade message from tier-rules.md}
-
-{if {tier_changed} is false and {tools_added} is empty and {tools_removed} is empty and {previous_tier} is non-null:}
-  {same-tier message from tier-rules.md}
-  {if preferences_yaml_created is false and (ccc_index_result is "fresh" or ccc_index_result is "none" or ccc_index_result is "skipped"): Nothing changed — your preferences were left untouched and the index was already current. You're good.}
-
-{if {tier_changed} is false and ({tools_added} or {tools_removed} is non-empty) and {previous_tier} is non-null:}
-  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: the fastest start is `@Ferris forge-auto <repo-or-doc-url>` — one command auto-scopes, briefs, compiles, tests at a 90% quality gate, and exports a verified skill with zero configuration. Prefer to scope by hand? `/skf-brief-skill` scopes your first compilation target, or `/skf-quick-skill` is a fast template-driven path. Already have a skill? `/skf-audit-skill` drift-checks an existing skill against current sources.
+```bash
+cat > "{run_dir}/report-context.json" <<'SKF_JSON'
+{
+  "orphan_auto_resolution": {orphan_auto_resolution_or_null},
+  "customization_resolver_unavailable": {customization_resolver_unavailable},
+  "error": null
+}
+SKF_JSON
 ```
 
-All re-run-delta context flags (`{tools_added}`, `{tools_removed}`, `{tier_changed}`) come from the detector's `deltas` block bound in stage 1 — no LLM-side recomputation, no set arithmetic in prose.
-
-### 3. Display Required-Tier Failure Block (when applicable; skip when `{headless_mode}` or `{quiet_mode}` is true)
+Write `{orphan_auto_resolution}` as the JSON object step 3 set (`{"action": "...", "source": "..."}`), or `null` when step 3 set none. `{customization_resolver_unavailable}` is JSON `null` unless SKILL.md On Activation bound it to the resolver's one-line failure reason; it is then that reason as a JSON string, its `"` and `\` escaped, and the envelope warns that the `{project-root}/_bmad/custom/` overrides were not applied. `error` stays `null`: a halt that names a phase never reaches this step, because it displays its own blocked envelope.
 
-If `{require_tier_satisfied}` is `false`, display this block immediately after the status report (the heading gate already handles the headless/quiet skip).
+### 2. Display Forge Status Report (skip when `{quiet_mode}` is true)
 
-When the block does fire (interactive run with require-tier failure):
+Render the banner from the payload and the run folder:
 
+```bash
+uv run {emitEnvelopeHelper} render-report --run-dir "{run_dir}" --project-root "{project-root}" \
+    --sidecar-path "{sidecar_path}" --forge-data-folder "{forge_data_folder}" \
+    --tier-rules "{skill-root}/references/tier-rules.md" < "{run_dir}/report-context.json"
 ```
-═══════════════════════════════════════
-  REQUIRED TIER NOT MET
-═══════════════════════════════════════
 
-  Required:  {require_tier}
-  Detected:  {calculated_tier}
-  Missing:   {require_tier_failure_missing_tools}
+Display its stdout as one code block, so its alignment holds, keeping every line in its order. When `{document_output_language}` is not English, translate the prose and keep paths, commands, flags, tool names and tier names as they are. If the script exits non-zero, or no path in `emitEnvelopeProbeOrder` exists, display one line instead, `FORGE STATUS could not be rendered: <message>`, where `<message>` is the `message` of its stderr JSON, or `skf-emit-result-envelope.py was not found`, and continue: the forge is configured either way.
 
-  Install the missing tool(s) and re-run, or relax `--require-tier`.
-  See "Climb to next tier" above for install URLs.
-═══════════════════════════════════════
-```
+### 3. Required-Tier Failure Block (skip when `{quiet_mode}` is true)
+
+If section 2 displayed `FORGE STATUS could not be rendered` and `{require_tier_satisfied}` is `false`, display one line: `REQUIRED TIER NOT MET: --require-tier {require_tier}, detected {calculated_tier}, missing <tools>`, where `<tools>` is `{require_tier_failure_missing_tools}` joined with `, `, so the section 5 halt shows its cause. A banner that rendered already ends with the REQUIRED TIER NOT MET block: display nothing more.
 
 ### 4. Emit Headless JSON Envelope
 
-When `{headless_mode}` is `true` OR `{quiet_mode}` is `true`, build the context payload from this step's accumulated flags and forward it to `{emitEnvelopeHelper}` on stdin. Invoke via `uv run`. 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.
+When `{quiet_mode}` is `true`, run `{emitEnvelopeHelper}` on the payload section 1 staged; `--run-dir` makes it read the staged helper outputs too, and the three path options give it the run's paths. It emits the single prefixed line `SKF_SETUP_RESULT_JSON: {…}` on stdout. Bind `{setup_envelope_line}` ← that stdout line, and do not display it here. It is the only line a headless or quiet run displays, and in a standalone run it must be the run's final message: `claude -p` prints only the final message, and the health check still runs after this step. Section 5 displays it on a tier miss; otherwise the shared health check displays it when it stops (its §0). Either way it is displayed verbatim as its own line (no code fence, no preface, no commentary), with nothing of setup's after it. When `{pipeline_mode}` is true, control then returns to the forger, which keeps chaining.
 
 ```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},
-  "orphan_auto_resolution": {orphan_auto_resolution_or_null},
-  "error": {error_object_or_null}
-}' | uv run {emitEnvelopeHelper} emit
+uv run {emitEnvelopeHelper} emit --run-dir "{run_dir}" --project-root "{project-root}" \
+    --sidecar-path "{sidecar_path}" --forge-data-folder "{forge_data_folder}" < "{run_dir}/report-context.json"
 ```
 
-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 1's normalized booleans OR the raw detect-tools output forwarded as-is will produce the correct envelope.
-
-**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 (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").
+**If the script exits non-zero:** a value in the payload or in a staged helper output is malformed: set `{setup_envelope_line}` to the empty string. Display nothing and continue (a missing JSON envelope on a headless or quiet run is a degraded but non-fatal state: the pipeline observer sees no envelope and treats the run as not completed cleanly).
 
 ### 5. Chain to Health Check
 
-After the forge status report (and any failure block + JSON envelope) has been displayed:
+After the forge status report and any failure block have been displayed (under headless or quiet, once `{setup_envelope_line}` is bound), delete the run folder:
+
+```bash
+rm -f "{run_dir}/detect-tools.json" "{run_dir}/detect-tools.err" "{run_dir}/ccc-exclusions.json" "{run_dir}/write-tools.err" "{run_dir}/forge-data-dir.err" "{run_dir}/qmd-classify.json" "{run_dir}/qmd-remove.json" "{run_dir}/clean-stale.json" "{run_dir}/report-context.json" && rmdir "{run_dir}"
+```
+
+Then:
 
-- If `{require_tier_satisfied}` is `false`, halt the workflow here without chaining to step 5. The tier miss is terminal; `{onCompleteCommand}` does not fire on a failed run.
-- Otherwise the forge is fully configured. If `{onCompleteCommand}` (resolved from `workflow.on_complete` at activation) is non-empty, execute it now — this is the workflow's terminal skill-specific action (e.g. trigger the first index build or notify an onboarding channel); in headless, log the action. Then load `{nextStepFile}`, read it fully, and execute it.
+- If `{require_tier_satisfied}` is `false`, halt the workflow here without chaining to step 5. When `{quiet_mode}` is true, display `{setup_envelope_line}` verbatim as the run's final message in a standalone run (nothing when it is empty); when `{pipeline_mode}` is true, control then returns to the forger, which reads the envelope's `tier_failure` status. This halt emits no blocked envelope: the `tier_failure` envelope is its one line. The tier miss is terminal; `{onCompleteCommand}` does not fire on a failed run.
+- Otherwise the forge is fully configured. If `{onCompleteCommand}` (resolved from `workflow.on_complete` at activation) is non-empty, carry out that instruction now: this is the workflow's terminal skill-specific action (for example, notify an onboarding channel); when `{quiet_mode}` is true, display nothing about it. Then load `{nextStepFile}`, read it fully, and execute it; under headless or quiet, the shared health check it chains to ends setup's output with `{setup_envelope_line}`.
 
 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 5 in turn delegates to `shared/health-check.md`; after that returns, the setup workflow is fully done.

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

@@ -1,10 +1,10 @@
 # Tier Report Copy
 
-The user-facing report strings the Step 4 report (`report.md`) consumes. Tool-detection probes and tier-calculation rules are owned by `skf-detect-tools.py` (see `references/detect-and-tier.md` §2) — this file holds only display copy, never detection or tier logic.
+The strings the step 4 FORGE STATUS banner shows. `render-report` (`skf-emit-result-envelope.py`) reads the first line under each `###` heading below, without its surrounding double quotes, so keep each string on one line. Tool-detection probes and tier-calculation rules are owned by `skf-detect-tools.py`; this file holds only display copy, never detection or tier logic.
 
 ## Tier Capability Descriptions
 
-Use these for positive-framing in the report step. Describe what the tier GIVES, never what it lacks.
+Describe what each tier gives, never what it lacks.
 
 ### Quick Tier
 "Quick tier active. You have fast, template-driven skill generation with package-name resolution. Perfect for getting started quickly."
@@ -13,15 +13,15 @@ Use these for positive-framing in the report step. Describe what the tier GIVES,
 "Forge tier active. You have AST-backed structural code analysis with line-level citations, plus template-driven generation. Every skill instruction traces to verified source code."
 
 ### Forge+ Tier
-"Forge+ tier active. Semantic-guided precision compilation — cocoindex-code maps the codebase semantically before AST extraction runs. Every skill begins with a ranked discovery pass that surfaces the most relevant source regions, then AST-backed verification gives each export its line-level citation."
+"Forge+ tier active. Semantic-guided precision compilation: cocoindex-code maps the codebase semantically before AST extraction runs. Every skill begins with a ranked discovery pass that surfaces the most relevant source regions, then AST-backed verification gives each export its line-level citation."
 
 ### Deep Tier
-"Deep tier active. Full capability unlocked — AST-backed code analysis, GitHub repository exploration, and QMD knowledge search with cross-repository synthesis. Maximum provenance and intelligence."
+"Deep tier active. Full capability unlocked: AST-backed code analysis, GitHub repository exploration, and QMD knowledge search with cross-repository synthesis. Maximum provenance and intelligence."
 
 ## Re-run Tier Change Messages
 
 ### Upgrade
-"Tier upgraded from {previous} to {current}. {newly available tool(s)} now detected — expanded capabilities unlocked."
+"Tier upgraded from {previous} to {current}. {newly available tool(s)} now detected: expanded capabilities unlocked."
 
 ### Downgrade
 "Tier changed from {previous} to {current}. {tool} no longer detected. Run the tool's installation to restore capabilities."

package/src/skf-setup/references/write-config.md

@@ -1,17 +1,13 @@
 ---
 nextStepFile: 'auto-index.md'
 # `{forgeTierRwHelper}` = first existing path in `{forgeTierRwProbeOrder}`;
-# halt if neither exists. 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.
-# Do not fall back to inline YAML emission — a prose-rendered template drifts
-# from the script and silently corrupts downstream skills.
+# halt if neither exists. The script owns the canonical forge-tier.yaml
+# format and keeps the registries a rewrite must not lose.
 forgeTierRwProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
   - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
-# Resolve `{emitEnvelopeHelper}` for the headless/quiet blocked-envelope emit
-# on write failures (the regular envelope assembly happens in step 4, but
-# write halts never reach step 4 — see section 1's blocked-emit protocol).
+# `{emitEnvelopeHelper}` = first existing path in `{emitEnvelopeProbeOrder}`,
+# for the blocked envelope a halt in this step emits under headless or quiet.
 emitEnvelopeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
   - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
@@ -23,74 +19,55 @@ emitEnvelopeProbeOrder:
 
 ## STEP GOAL:
 
-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.
+Write the detected tools, the tier and the ccc index state to `{sidecar_path}/forge-tier.yaml` through `{forgeTierRwHelper}`, which reads them from the run folder and keeps the registries and the SKF exclusion record of an existing file, and make sure `{forge_data_folder}/` exists.
 
 ## Rules
 
-- Focus only on writing configuration files and creating directories
-- Do not re-detect tools — use results from step 1
-- 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
+- Never inline a YAML template for forge-tier.yaml: the script owns the canonical format
+- Never create or edit `{sidecar_path}/preferences.yaml`: the installer writes it, and activation only reads it
+- File write failures are errors: halt the workflow; under `{quiet_mode}` the blocked envelope is the only output, otherwise report the failure clearly
+- Display messages only when `{quiet_mode}` is false; the one exception is the envelope line a halt displays
+- When `{quiet_mode}` is true, write no assistant text at all between tool calls: no status, progress or step-transition notes, however brief
+- If no path in `forgeTierRwProbeOrder` exists, halt with phase `step 2:helper-missing`, `path` set to its first entry, and reason `Setup cannot proceed: skf-forge-tier-rw.py was not found. Reinstall SKF, then re-run /skf-setup.`
+- Every halt follows the SKILL.md halt contract: when `{quiet_mode}` is true, run `uv run {emitEnvelopeHelper} emit-blocked --phase '<phase>' --reason '<reason>' --path "<path>"`, which builds the payload itself (no `--path` for a halt without one, `--stderr-from` where the halt names it, and `--customization-resolver-unavailable "<reason>"` once SKILL.md On Activation item 6 bound `{customization_resolver_unavailable}` to a reason, escaped as the halt contract says), and display its stdout line verbatim and nothing else (the reason alone if `{emitEnvelopeHelper}` resolves to no path, or the helper exits non-zero or prints no line); otherwise display the reason
 
 ## MANDATORY SEQUENCE
 
 ### 1. Write forge-tier.yaml
 
-Build the JSON payload from context flags set by step 1 and step 1b. 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`.
-
 ```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"
+uv run {forgeTierRwHelper} write-tools \
+    --target "{sidecar_path}/forge-tier.yaml" \
+    --detect-from "{run_dir}/detect-tools.json" \
+    --ccc-from "{run_dir}/ccc-exclusions.json" 2> "{run_dir}/write-tools.err"
 ```
 
-The script atomically writes the file via temp + fsync + rename (crash-safe) and returns a JSON response with `wrote`, `preserved_arrays.qmd_collections` count, `preserved_arrays.ccc_index_registry` count, and the resolved `tier`.
-
-**Parse the response and set context flags for step 4:**
-
-- `{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 the script exits non-zero**: parse the stderr JSON `{"status":"error","message":...}`, set `{error: {phase: "step 2:write-tools", path: "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml", reason: <message>}}`, and halt the workflow before chaining to step 3. When `{headless_mode}` or `{quiet_mode}` is true, first pipe the same `{phase, reason, path}` payload to `python3 {emitEnvelopeHelper} emit-blocked` so the pipeline sees the blocked envelope before the halt (see `references/report.md` frontmatter for the helper probe order; the subcommand declares zero dependencies).
+The script takes the tools and the tier from step 1's `detect-tools.json`, and the index state and the SKF exclusion record from step 1b's `ccc-exclusions.json`.
 
-### 2. Initialize preferences.yaml
+**If the script exits non-zero**: halt the workflow before chaining to step 3, with phase `step 2:write-tools`, path `{sidecar_path}/forge-tier.yaml` and as the reason the diagnostic in `{run_dir}/write-tools.err`. When `{quiet_mode}` is true, run the emitter, which reads that diagnostic itself, display its stdout line verbatim, and display nothing else: the envelope's `error` carries the path and reason. If the helper exits non-zero or prints no line, display the reason alone. Otherwise read that file and display the failure with its path and, as the reason, the `message` of its JSON error, else its first line.
 
 ```bash
-uv run {forgeTierRwHelper} init-prefs \
-    --target "{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml"
+uv run {emitEnvelopeHelper} emit-blocked --phase "step 2:write-tools" --path "{sidecar_path}/forge-tier.yaml" \
+    --reason "<message>" --stderr-from "{run_dir}/write-tools.err" \
+    [--customization-resolver-unavailable "{customization_resolver_unavailable}"]
 ```
 
-The script creates the file with first-run defaults (`tier_override: ~`, `passive_context: true`, `headless_mode: false`, `compact_greeting: false`) if the file does not exist. When the file already exists, the script refuses to overwrite (preserves user customization) and reports `wrote: false`.
+In each `emit-blocked` call of this step, keep the bracketed `--customization-resolver-unavailable` only when On Activation item 6 bound `{customization_resolver_unavailable}` to a reason, escaped as the halt contract says; otherwise leave it out.
 
-**Parse the response and set context flags for step 4:**
+### 2. Ensure the Forge Data Folder
 
-- `{preferences_yaml_created}` ← `wrote` (true on first run, false on re-run when the file pre-existed)
-
-**If the script exits non-zero**: same halt-and-blocked-envelope-emit pattern as section 1, with `phase: "step 2:init-prefs"` and the matching path.
+```bash
+mkdir -p "{forge_data_folder}" 2> "{run_dir}/forge-data-dir.err"
+```
 
-### 3. Ensure forge-data/ Directory
+On non-zero exit, halt as section 1 does, with phase `step 2:forge-data-dir`, path `{forge_data_folder}` and the diagnostic in `{run_dir}/forge-data-dir.err` as the reason (an interactive run reads that file); under `{quiet_mode}`:
 
-Run `mkdir -p {forge_data_folder}`. The `-p` flag is idempotent (creates parents, exits 0 if the directory already exists), so the prompt does no existence-check reasoning. On non-zero exit, halt with the same blocked-envelope-emit pattern as section 1, using `phase: "step 2:forge-data-dir"` and the matching path.
+```bash
+uv run {emitEnvelopeHelper} emit-blocked --phase "step 2:forge-data-dir" --path "{forge_data_folder}" \
+    --reason "<message>" --stderr-from "{run_dir}/forge-data-dir.err" \
+    [--customization-resolver-unavailable "{customization_resolver_unavailable}"]
+```
 
-### 4. Auto-Proceed
+### 3. 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.
+Once forge-tier.yaml is written, load `{nextStepFile}`, read it fully, and execute it.

package/src/skf-test-skill/SKILL.md

@@ -12,7 +12,9 @@ Verifies that a skill is complete enough to be useful to an AI agent by checking
 ## 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.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; e.g. `shared/references/output-contract-schema.md` and `shared/health-check.md`.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one. The coherence and migration rules cite `skf-create-skill/assets/skill-sections.md` and `skf-create-stack-skill/references/compose-mode-rules.md`.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` holds deterministic helpers, `assets/` the output section formats and `templates/` the test report template.
 - `{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.
@@ -29,7 +31,11 @@ These rules apply to every step in this workflow:
 - Only load one step file at a time — never preload future steps
 - Update `stepsCompleted` in output file frontmatter before loading next step
 - Always communicate in `{communication_language}`
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- No stage waits for an answer in headless mode: the one question, the skill name, halts `input-missing` there
+- Every HARD HALT names its `halt_reason` and phase and carries exit code 1 (`exit_code` in its envelope); in headless mode it prints its envelope through the shared emitter, as each stage's **Halt envelope** paragraph shows
+- Once `references/init.md` §6a has taken the run lock, every HALT after it first releases the lock, whatever the release prints (it never removes another run's lock): from `{project-root}`, run `uv run {runLockHelper} release --lock "{forge_version}/.test-skill.lock" --owner "{run_owner}"`.
+- The report is `{report_file}`: init.md §6c creates it as `.skf-test-report-{skill_name}-{run_id}.md`, and it takes its public name `test-report-{skill_name}-{run_id}.md` only once report.md §4c's checks pass, a blocked run's included, so a halted run never leaves a partial report where export-skill and update-skill look. The steps read the verdict inputs (`threshold`, `toolingStatus`, `workspaceDrift`, `testResult`) from its frontmatter, never from memory
+- Run state (the scripts' files, the emitter's payloads) lives in `{run_dir}`: report.md §7 deletes it, a HALT keeps it
 
 ## Stages
 
@@ -42,49 +48,12 @@ These rules apply to every step in this workflow:
 | 4b | External Validators | references/external-validators.md | Yes |
 | 4c | Hard Gate | references/step-hard-gate.md | Yes |
 | 5 | Score | references/score.md | Yes |
-| 6 | Report | references/report.md | No (confirm) |
+| 6 | Report | references/report.md | Yes |
 | 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
-| Aspect | Detail |
-|--------|--------|
-| **Inputs** | skill_name [required]; optional flags: `--allow-workspace-drift`, `--no-discovery` (skip the report step's Discovery Testing block), `--no-health-check` (skip §7 health-check dispatch), `--tier=<Quick\|Forge\|Forge+\|Deep>` (bypass forge-tier.yaml sidecar requirement), `--threshold=<N>` (override pass threshold; CLI wins over per-pipeline defaults and `workflow.default_threshold` scalar) |
-| **Gates** | step 6: Confirm Gate [C] |
-| **Outputs** | per-run `test-report-{skill_name}-{run_id}.md` with completeness score and result (PASS/FAIL); per-run `skf-test-skill-result-{run_id}.json` and `skf-test-skill-result-latest.json` written atomically under `{forge_version}/`; `evidence-report-fallback.md` written under `{forge_version}/` when threshold fallback occurs (score between 80% and target threshold) — downstream consumers (export-skill, update-skill `--from-test-report`) glob `test-report-{skill_name}-*.md` and pick newest by parsed ISO timestamp |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
-| **Exit codes** | See "Exit Codes" below |
-
-## Exit Codes
-
-Every terminal state in this workflow exits with a stable code so headless automators can branch on the verdict (and any HARD HALT) without grepping message text:
-
-| Code | Meaning              | Raised by                                                                                  |
-| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
-| 0    | success / PASS       | step 6 §6b — `testResult: 'pass'` (after the result contract is written in §4c)            |
-| 1    | error (HARD HALT)    | infrastructure / precondition HALT in step 1 or step 6 before a verdict exists — see the "Result Contract" `halt_reason` set (the hard gate uses code 2) |
-| 2    | fail / FAIL          | step 4c §3 — hard gate blocked (`halt_reason: "hard-gate-blocked"`); step 6 §6b — `testResult: 'fail'` (after the result contract is written in §4c) |
-| 3    | inconclusive         | step 6 §6b — `testResult: 'inconclusive'` (distinct from fail so orchestrators can route to manual-review queues) |
-| 4    | pass-with-drift      | step 6 §6b — `testResult: 'pass-with-drift'` (distinct from clean pass — `--allow-workspace-drift` was in effect; re-test against the pinned commit and refuse export — exit 0 would wrongly signal a clean pass) |
-
-## Result Contract (Headless)
-
-When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HALT the Exit Codes table above marks with a non-zero code emits the same envelope shape on **stderr** with `status: "error"` and the `halt_reason` naming the failure, so a headless orchestrator branches on the reason without grepping prose:
-
-```
-SKF_TEST_RESULT_JSON: {"status":"success|error","skill_name":"…","verdict":"PASS|FAIL|INCONCLUSIVE|pass-with-drift","score":N,"threshold":N,"report_path":"…|null","next_workflow":"export-skill|update-skill|null","exit_code":0,"halt_reason":null,"threshold_fallback":true,"original_threshold":90}
-```
-
-`status` is `"success"` on the terminal happy path (PASS / FAIL / INCONCLUSIVE / pass-with-drift — the workflow completed), `"error"` on an emitted HARD HALT. `verdict` is the canonical result string (`null` on an infrastructure error halt). `next_workflow` is `"export-skill"` only when `verdict == "PASS"`; `"update-skill"` for `FAIL` or `pass-with-drift`; `null` for `INCONCLUSIVE` and error halts. `halt_reason` is `null` on the terminal path or one of the emitted strings: `"target-inaccessible"`, `"forge-tier-missing"`, `"workspace-drift"`, `"another-run-active"`, `"frontmatter-invalid"` (init HALTs), `"atomic-writer-missing"`, `"step-completeness-violation"`, `"report-anchor-missing"`, `"health-check-missing"` (report HALTs), or `"hard-gate-blocked"` (step 4c). `exit_code` is the code the Exit Codes table above assigns to the reached terminal state or HALT. Step 1 §3 frontmatter-validation now emits the `"frontmatter-invalid"` stderr envelope (see init.md §3c) and is branchable. Only the coverage/coherence analysis aborts print a diagnostic and exit non-zero **without** this envelope — they are the sole remaining outcomes outside the branchable set. When threshold fallback occurred, the envelope includes `"threshold_fallback":true` and `"original_threshold":N`; these fields are omitted when no fallback occurred.
-
-The same payload is persisted to disk by step 6 §4c (atomic write) at two locations under `{forge_version}/`:
-
-| Path                                          | Purpose                                                                    |
-| --------------------------------------------- | -------------------------------------------------------------------------- |
-| `skf-test-skill-result-{run_id}.json`         | Per-run record. `{run_id}` carries UTC timestamp + PID + random suffix.    |
-| `skf-test-skill-result-latest.json`           | Latest copy — stable path for pipeline consumers (copy, not symlink).      |
-
-The on-disk payload is the richer form: it adds `outputs[]` (report-path entries), `summary` (`score`, `threshold`, `result`, `testMode`, `activeCategories[]`, `inconclusiveReasons[]` when present, `threshold_fallback`, `original_threshold`, `evidence_report_path` when threshold fallback occurred), `runId`, and `healthCheckDispatched`. The stdout envelope is the compact subset documented above.
+Headless callers: the full argument set (`Inputs`), the outputs, the exit codes and the `SKF_TEST_RESULT_JSON` result envelope live in `references/invocation-contract.md`. Interactive runs do not need it.
 
 ## On Activation
 
@@ -92,33 +61,24 @@ The on-disk payload is the richer form: it adds `outputs[]` (report-path entries
    - `project_name`, `user_name`, `communication_language`, `document_output_language`
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
 3. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
-
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
-
-   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-test-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}`: report.md §4c hands it to the result as a warning.
 
-   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the three scalars, if the merged value is empty or absent, use the bundled default:
+   Apply the scalar fallbacks now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
 
    - `{testReportTemplatePath}` ← `workflow.test_report_template_path` if non-empty, else `templates/test-report-template.md`
-   - `{outputFormatsPath}` ← `workflow.output_formats_path` if non-empty, else `assets/output-section-formats.md`
-   - `{scoringRulesPath}` ← `workflow.scoring_rules_path` if non-empty, else `references/scoring-rules.md`
-   - `{defaultThreshold}` ← `workflow.default_threshold` if non-empty/non-null, else `80`. CLI `--threshold=<N>` wins over per-pipeline defaults (from init.md §1b) which win over this scalar at the usage site in `references/score.md`.
+   - `{defaultThreshold}` ← `workflow.default_threshold` if non-empty/non-null, else `80`. init.md §1b resolves the precedence (CLI, then per-pipeline default, then this scalar) once and writes `threshold` and `thresholdSource` into the report frontmatter, which score.md §1 reads.
    - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (the post-finalization hook in `references/report.md` is then a no-op).
 
-   Stash all five as workflow-context variables that stage files reference directly — no conditional at the usage site.
+   Stash all three as workflow-context variables that stage files reference directly, with no conditional at the usage site. The scoring rules, the Gap Severity table and the output formats are not overridable: scripts own the scoring and the hard gate reads the table, so a house-style copy could change what blocks export.
 
-   **Apply the array surfaces** (not silent no-ops): run `workflow.activation_steps_prepend` in order now; treat each `workflow.persistent_facts` entry as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts — the bundled default globs any `project-context.md`); then run `workflow.activation_steps_append` after activation.
+   **Apply the array surfaces** (not silent no-ops): run `workflow.activation_steps_prepend` in order now; treat each `workflow.persistent_facts` entry as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off); then run `workflow.activation_steps_append` after activation.
 
 4. Load, read the full file, and then execute `references/init.md` to begin the workflow.