bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-setup/references/ccc-index.md

@@ -1,120 +1,60 @@
 ---
 nextStepFile: 'write-config.md'
 # `{mergeCccExclusionsHelper}` = first existing path in
-# `{mergeCccExclusionsProbeOrder}`; halt if neither exists. The script owns
-# config-value validation and the set-union merge into
-# .cocoindex_code/settings.yml — no prose fallback.
+# `{mergeCccExclusionsProbeOrder}`; halt if neither exists.
 mergeCccExclusionsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-merge-ccc-exclusions.py'
   - '{project-root}/src/shared/scripts/skf-merge-ccc-exclusions.py'
+# `{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'
 ---
 
-<!-- Config: communicate in {communication_language}. User-visible status messages (CCC exclusion summary, indexing progress message) render in the user's language. -->
+<!-- Config: communicate in {communication_language}. User-visible status messages (indexing progress message) render in the user's language. -->
 
-# Step 1b: CCC Index Verification
+# Step 1b: CCC Index
 
 ## STEP GOAL:
 
-If ccc is available (`{ccc: true}` from step 1), invoke `{mergeCccExclusionsHelper}` to validate config-driven SKF exclusion patterns and merge them into `.cocoindex_code/settings.yml`, then verify the project's ccc index exists and create or refresh it if needed. Store index state and exclusion-merge results in context for step 2 to write into forge-tier.yaml and for step 4 to surface in the JSON envelope.
-
-For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
+When ccc is available, run `{mergeCccExclusionsHelper}` once: it prepares `.cocoindex_code/settings.yml` (running `ccc init` when needed), keeps its SKF exclusion patterns current, builds or refreshes the project index when it needs it, and writes its result to `{run_dir}/ccc-exclusions.json`, where step 2 and step 4 read it.
 
 ## Rules
 
-- Focus only on ccc index verification, exclusion-pattern merge, and (re-)indexing
-- Do not display skip messages for Quick/Forge tiers
-- Do not fail the workflow if ccc indexing fails
-- The script owns exclusion-pattern validation — do not reimplement it in prose
+- The script owns `ccc init`, every `settings.yml` edit, the index decision, `ccc index` and `ccc status`: run none of them yourself, and bind nothing from its output (steps 2 and 4 read the result file)
+- Do not fail the workflow if settings preparation or ccc indexing fails: the result file records the failure, and the report shows it
+- 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 `mergeCccExclusionsProbeOrder` exists when section 2 runs (an install fault, not a settings failure), halt with phase `step 1b:helper-missing`, `path` set to its first entry, and reason `Setup cannot proceed: skf-merge-ccc-exclusions.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. Check Eligibility
 
-Read `{ccc}` and `{ccc_skip_index}` from context.
-
-**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: [], ccc_exclusion_warnings: [], settings_yml_written: false, settings_yml_patterns_added: 0}`. Proceed directly to section 5 (Auto-Proceed) — no output, no messaging.
-
-**If `{ccc}` is true AND `{ccc_skip_index}` is true:** Run the exclusion-merge (section 3) so settings.yml stays current, then set `{ccc_index_result: "skipped", ccc_indexed_path: null, ccc_last_indexed: null}` and proceed to section 5 (Auto-Proceed) — do not run `ccc init` or `ccc index`. The envelope's `ccc_index.status` will be `"skipped"` so pipelines that plan an out-of-band re-index can distinguish "the operator opted out" from "indexing failed".
-
-**If `{ccc}` is true AND `{ccc_skip_index}` is false:** Continue to section 2.
-
-### 2. Check Existing Index State
-
-Consume prior CCC state from stage 1's detector output (`prior.*` context flags) — no YAML re-parse and no timestamp math here. The detector already read forge-tier.yaml and computed the freshness verdict `{ccc_index_fresh}` against `{project-root}` and the current time (same-project path match AND `"fresh"`/`"created"` status AND `last_indexed` within the staleness threshold, defaulting to 24 hours).
-
-Decide `{needs_reindex}` and `{ccc_index_result}` from `{ccc_index_fresh}`:
-
-- If `{ccc_index_fresh}` is true → index is fresh. Set `{needs_reindex: false}`, `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: {previous_ccc_last_indexed}}`. Exclusions still merge in section 3 (which may force a re-index).
-- If `{ccc_index_fresh}` is false (path mismatch, non-fresh status, stale timestamp, or any required prior CCC field null) → `{needs_reindex: true}`.
+If `{ccc}` (from step 1) is false, go to section 3 with no output. Otherwise continue to section 2, with or without `--ccc-skip-index`: the skip lane still prepares settings.yml, and only the index build is skipped.
 
-### 3. Merge SKF Exclusion Patterns
+### 2. Prepare the Settings and the Index
 
-SKF infrastructure and output directories must be excluded from the CCC index — they contain workflow instructions, build artifacts, and generated skills that pollute semantic search results with zero extraction value.
+Unless `{quiet_mode}` is true, display: "**Preparing the ccc settings, then the semantic index if it needs building: a first index can take several minutes on large codebases (1000+ files). Run `ccc status` in another terminal to monitor progress.**"
 
-Forward `skills_output_folder` and `forge_data_folder` from `{project-root}/_bmad/skf/config.yaml` **verbatim** — the script resolves `{project-root}/...` template strings and rejects absolute paths / placeholders / glob meta-chars internally. The step does no string surgery; that work moved into the helper. Invoke via `uv run`.
+Pass `{ccc_index_fresh}` (from step 1) and `{ccc_skip_index}` as `true` or `false`, and add `--defer-index` only when `{require_tier_satisfied}` (from step 1) is `false`: a run that ends `tier_failure` then builds no index that is due, while a fresh index record still carries forward. Give the call an extended timeout (or run it in the background and wait for it to finish):
 
 ```bash
 uv run {mergeCccExclusionsHelper} \
     --project-root "{project-root}" \
-    --skills-output-folder "{skills_output_folder}" \
-    --forge-data-folder "{forge_data_folder}"
-```
-
-The script (see `src/shared/scripts/skf-merge-ccc-exclusions.py` docstring for the full schema) builds the SKF exclusion list (4 always-include hardcoded patterns + 2 conditional from validated config), applies the validation rules to reject empty / absolute / glob-meta config values with actionable warnings, and performs an idempotent set-union merge into `{project-root}/.cocoindex_code/settings.yml`. User customizations are preserved. When the file does not exist yet (first-time setup before `ccc init`) the script creates it; when nothing new needs adding the script skips the write entirely (mtime preserved).
-
-**Parse the JSON output and set context flags:**
-
-- `{settings_yml_existed}` ← `settings_yml_existed`
-- `{settings_yml_written}` ← `written`
-- `{settings_yml_patterns_added}` ← `patterns_added`
-- `{ccc_exclude_patterns}` ← `effective_patterns` (the script returns the final, sorted, deduplicated SKF pattern set after validation — consume verbatim; do not re-derive in prose).
-- `{ccc_exclusion_warnings}` ← `warnings` (a list — step 4 folds them into the envelope's warnings array)
-
-**If `{settings_yml_written}` is true** (new patterns merged into settings.yml): set `{needs_reindex: true}` — new exclusions require re-indexing for the index to reflect them. Display: "**CCC exclusions configured:** {patterns_added} SKF patterns applied to .cocoindex_code/settings.yml"
-
-**If `{settings_yml_written}` is false** (idempotent re-run, all patterns already present): display nothing (exclusions already configured). Do NOT change `{needs_reindex}` — it stays at whatever section 2 set it to.
-
-**Flow decision:**
-
-- If `{needs_reindex}` is true: proceed to section 4
-- If `{needs_reindex}` is false: proceed to section 5 (Auto-Proceed)
-
-### 4. Create or Refresh CCC Index
-
-**If `{ccc_daemon}` is `"stopped"` or `"healthy"`:** the `ccc index` command auto-starts the daemon when needed.
-
-**If `{ccc_daemon}` is `"error"`:** attempt indexing anyway — errors will be caught below.
-
-Run (CWD must be `{project-root}`):
-
-```bash
-ccc init
-```
-
-**If init fails** (project may already be initialized): continue — this is not an error. Note: when `{settings_yml_existed}` was false and `ccc init` just created the settings.yml, the merge in section 3 ran BEFORE ccc init. The script handles "no settings.yml exists" by creating one with just the SKF exclusions, which `ccc init` will then either preserve (if it merges) or overwrite (in which case the next workflow run re-merges). Either way the SKF exclusions end up in the file by the time `ccc index` runs the second time.
-
-Before invoking `ccc index`, display: "**Building semantic index — this can take several minutes on large codebases (1000+ files). Run `ccc status` in another terminal to monitor progress.**" so the user does not assume the workflow has hung during the long-running call.
-
-Then run:
-
-```bash
-ccc index
+    --config "{project-root}/_bmad/skf/config.yaml" \
+    --prior-state-from "{sidecar_path}/forge-tier.yaml" \
+    --index-fresh "{ccc_index_fresh}" \
+    --skip-index "{ccc_skip_index}" \
+    [--defer-index] \
+    --build-index \
+    --result-to "{run_dir}/ccc-exclusions.json"
 ```
 
-**Note:** `ccc index` can take several minutes on large codebases (1000+ files). Run with an extended timeout or in background mode. Use `ccc status` to verify completion — check that `Chunks` and `Files` counts are non-zero.
-
-**If succeeds:**
-
-- Run `ccc status` to get file count
-- Store `{ccc_index_result: "created", ccc_indexed_path: {project-root}, ccc_last_indexed: {current ISO timestamp}, ccc_file_count: {count from ccc status}}`
-- Display: "**CCC index created.** {ccc_file_count} files indexed for semantic discovery."
-
-**If fails:**
-
-- Store `{ccc_index_result: "failed", ccc_indexed_path: null, ccc_last_indexed: null, ccc_indexing_failed_reason: {error}}` (the failed-reason flag flows into step 4's envelope warnings)
-- Display: "CCC indexing failed: {error}. Extraction will use direct AST scanning — semantic pre-ranking unavailable this session."
-- Continue — this is not a workflow error
+Go on to section 3 however the call ends: a non-zero exit, or a call the shell stopped, is no workflow error either (steps 2 and 4 report it as a failed index).
 
-### 5. Auto-Proceed
+### 3. Auto-Proceed
 
-After ccc index verification is complete (or skipped because ccc is unavailable), display "**Proceeding to write configuration...**", then load `{nextStepFile}`, read it fully, and execute it.
+Load `{nextStepFile}`, read it fully, and execute it.

package/src/skf-setup/references/detect-and-tier.md

@@ -1,11 +1,15 @@
 ---
 nextStepFile: 'ccc-index.md'
 # `{detectToolsHelper}` = first existing path in `{detectToolsProbeOrder}`;
-# halt if neither exists. This script is the source of truth for tool
-# detection and tier calculation — no prose-driven probes.
+# halt if neither exists.
 detectToolsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-tools.py'
   - '{project-root}/src/shared/scripts/skf-detect-tools.py'
+# `{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'
 ---
 
 <!-- Config: communicate in {communication_language}. The first-run preamble below is user-visible — render it in the user's language. -->
@@ -14,100 +18,88 @@ detectToolsProbeOrder:
 
 ## STEP GOAL:
 
-Verify availability of the four forge tools (ast-grep, gh, qmd, ccc), read any existing configuration for re-run comparison, check for tier override, and calculate the capability tier — all via `{detectToolsHelper}` so the deterministic work is done once, by a tested script, never by the LLM.
+Through `{detectToolsHelper}`, verify the four forge tools (ast-grep, gh, qmd, ccc), each at its minimum version, compare them with the previous run's configuration, and calculate the capability tier. Then, on an interactive run, tell the user what setup is about to write before step 1b or step 2 writes anything.
 
 ## Rules
 
-- Focus only on tool detection and tier calculation — do not write any files (Step 02)
-- Never reimplement tool probes or the tier rules in prose — the script is authoritative
-- Tool command failures are not errors — they indicate unavailability (the script swallows them)
+- Focus only on tool detection and tier calculation: write nothing but this run's folder and the detector's output and stderr in it (step 2 writes the configuration)
+- Never reimplement tool probes or the tier rules in prose: the script is authoritative
+- 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 `detectToolsProbeOrder` exists, halt with phase `step 1:helper-missing`, `path` set to its first entry, and reason `Setup cannot proceed: skf-detect-tools.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. Check for Existing Configuration (Re-run Detection)
+### 1. Run Detection Helper
 
-Prior state lives in two files; the detector helper (§2) reads forge-tier.yaml itself when invoked with `--prior-state-from`, so this section only handles preferences.yaml directly and the first-run preamble.
+Create this run's folder:
 
-**Read existing preferences.yaml** at `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml`:
+```bash
+mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-setup-XXXXXXXX"
+```
 
-- If exists: check for `tier_override` value
-- If not found: set `{tier_override}` to null
+Bind `{run_dir}` ← the path it prints. If the folder cannot be created, halt with phase `step 1:run-folder`, `path` `{project-root}/_bmad-output/.skf-run`, and reason `Setup cannot proceed: the run folder could not be created: <message>`, where `<message>` is the command's first stderr line. With no run folder to hold that stderr, a quiet run repeats the command with its stderr piped to the emitter, which fills `<message>`; a repeat that succeeds removes the folder it made, and its reason then ends `(no error message)`:
 
-**First-run preamble** — when the prior-state read (§2 below, `prior.previous_tier`) returns null AND `{headless_mode}` is `false`, display this preamble before continuing so the user knows what is about to happen and can abort cleanly with Esc / Ctrl+C before any writes. (When `{headless_mode}` is true, skip the preamble entirely — pipelines never need it.)
+```bash
+{ mkdir -p "{project-root}/_bmad-output/.skf-run" && rmdir "$(mktemp -d "{project-root}/_bmad-output/.skf-run/skf-setup-XXXXXXXX")"; } 2>&1 >/dev/null | uv run {emitEnvelopeHelper} emit-blocked --phase "step 1:run-folder" --path "{project-root}/_bmad-output/.skf-run" --reason "Setup cannot proceed: the run folder could not be created: <message>" --stderr-from - [--customization-resolver-unavailable "{customization_resolver_unavailable}"]
+```
 
-"**About to set up the forge.** This workflow will:
+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.
 
-- Detect available tools (ast-grep, gh, qmd, ccc) — read-only probes only
-- Write `{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml` (capability tier + tool state)
-- Write `{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml` (first-run defaults)
-- Create `{forge_data_folder}/` if missing
-- When ccc is available: augment `{project-root}/.cocoindex_code/settings.yml` with SKF exclusion patterns, then create or refresh the project ccc index
+Then run the detector into the folder:
 
-**About tiers:** SKF picks one of four tiers (Quick / Forge / Forge+ / Deep) based on which tools are installed. **All four are fully usable** — higher tiers add power, they don't fix gaps. If you're new and only have a base Python install, Quick tier is the right starting point and the report at the end will show you exactly which tools to install if you want to climb later.
+```bash
+uv run {detectToolsHelper} --project-root "{project-root}" \
+    --prior-state-from "{sidecar_path}/forge-tier.yaml" \
+    [--tier-override="{tier_override}"] [--require-tier="{require_tier}"] \
+    > "{run_dir}/detect-tools.json" 2> "{run_dir}/detect-tools.err" && cat "{run_dir}/detect-tools.json"
+```
 
-Press Esc or Ctrl+C now if this isn't the right project — no files have been written yet."
+Pass `--tier-override` only when `{tier_override}` (bound at activation from `preferences.yaml`) is non-null, and `--require-tier` only when `{require_tier}` is non-null, with the value exactly as activation bound it, even when it names no tier: the script rejects such a value, and the halt below then names the valid tiers.
 
-**Re-run notice** — when the prior-state read (§2 below, `prior.previous_tier`) returns a non-null value AND `{headless_mode}` is `false`, display this notice instead of the first-run preamble, before continuing, so a user who re-ran in the wrong/sibling repo can abort before any config rewrite or re-index. (When `{headless_mode}` is true, skip it — pipelines re-run intentionally.)
+Output is one JSON document on stdout; `DETECT_OUTPUT_SCHEMA` in the helper's docstring documents it.
 
-"**Forge already set up here:** {previous_tier} tier, detected {previous_detection_date}. Re-running re-probes the tools and refreshes config/index in this project. To refresh the tier without paying the ccc re-index cost, re-run with `--ccc-skip-index`. Press Esc or Ctrl+C now if this isn't the project you meant — nothing has been rewritten yet."
+**If the script exits non-zero or prints no JSON:** halt before section 2 with phase `step 1:detect-tools`, `path` `{project-root}`, and reason `Setup cannot proceed: tool detection failed: <message>`, where `<message>` is the diagnostic in `{run_dir}/detect-tools.err`: an interactive run reads that file and shows the `message` of its JSON error, else its first line. Under `{quiet_mode}` the blocked envelope is the only line displayed, and the emitter reads `<message>` from that file:
 
-### 2. Run Detection Helper
+```bash
+uv run {emitEnvelopeHelper} emit-blocked --phase "step 1:detect-tools" --path "{project-root}" \
+    --reason "Setup cannot proceed: tool detection failed: <message>" --stderr-from "{run_dir}/detect-tools.err" \
+    [--customization-resolver-unavailable "{customization_resolver_unavailable}"]
+```
 
-Build the Bash invocation: `uv run {detectToolsHelper} --project-root "{project-root}" --prior-state-from "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"`. If `{tier_override}` is non-null, append `--tier-override "{tier_override}"`. If `{require_tier}` is non-null, append `--require-tier "{require_tier}"`. Then execute. (`--project-root` lets the script compute the CCC-index freshness verdict — `prior.ccc_index_fresh` — so step 1b branches on a boolean instead of doing timestamp math.)
+### 2. Parse Output and Set Context Flags
 
-The script (see `src/shared/scripts/skf-detect-tools.py` docstring for the full `DETECT_OUTPUT_SCHEMA`) probes ast-grep / gh / qmd / ccc concurrently with two-step verification for qmd and ccc (binary-identity check + daemon-health check, including the `CocoIndex Code` identity-marker substring check that rejects PATH-shadowing aliases). It applies the 4-rule tier table, performs the tier-override sanity check (override is honored but flagged unsafe when underlying tools are missing), and evaluates `--require-tier` using a tool-prerequisite check (Deep does not subsume Forge+ — Deep does not require ccc). Output is one JSON document on stdout.
+Steps 2 and 4 read the staged `detect-tools.json` themselves. Bind only what the next steps branch on (field paths are relative to the script's top-level object):
 
-### 3. Parse Output and Set Context Flags
+- `{ccc}` ← `tools.ccc.available`
+- `{calculated_tier}` ← `tier.calculated`, the tier downstream steps act on
+- `{require_tier_satisfied}` ← `require_tier.satisfied` (`true | false | null`; null when `--require-tier` was not set) and `{require_tier_failure_missing_tools}` ← `require_tier.missing_tools` (a list)
+- `{previous_tier}` ← `prior.previous_tier` and `{previous_detection_date}` ← `prior.previous_detection_date` (both null on a first run)
+- `{ccc_index_fresh}` ← `prior.ccc_index_fresh` (boolean; step 1b forwards it as `--index-fresh`)
 
-From the JSON, set these context flags. Field paths are relative to the script's top-level object.
+A tier tool below its minimum version binds `false` here, like a missing one: it counts toward no tier, and step 4 names it with its upgrade from the staged output.
 
-From `tools`:
+### 3. Show the First-Run Preamble or the Re-run Notice (skip when `{quiet_mode}` is true)
 
-- `{ast_grep}` ← `tools.ast_grep.available`
-- `{ast_grep_version}` ← `tools.ast_grep.version`
-- `{gh_cli}` ← `tools.gh_cli.available`
-- `{gh_cli_version}` ← `tools.gh_cli.version`
-- `{qmd}` ← `tools.qmd.available`
-- `{qmd_status}` ← `tools.qmd.status` (`"absent" | "daemon_stopped" | "healthy"` — drives the climb-hint distinction in step 4)
-- `{qmd_version}` ← `tools.qmd.version`
-- `{ccc}` ← `tools.ccc.available`
-- `{ccc_daemon}` ← `tools.ccc.daemon` (`"healthy" | "stopped" | "error" | null`)
-- `{ccc_version}` ← `tools.ccc.version`
-- `{security_scan}` ← `tools.security_scan.available` (informational only — never affects tier)
+Now that section 2 has bound `{previous_tier}` and `{previous_detection_date}`, and before step 1b or step 2 writes anything, display one of these:
 
-From `tier`:
+**First-run preamble:** when `{previous_tier}` is null:
 
-- `{calculated_tier}` ← `tier.calculated` — the tier downstream steps act on
-- `{detected_tier}` ← `tier.detected` — what would have been chosen without override
-- `{tier_override_active}` ← `tier.override_applied`
-- `{tier_override_invalid}` ← `tier.override_invalid`
-- `{tier_override_invalid_value}` ← `tier.override_invalid_value`
-- `{tier_override_invalid_suggestion}` ← `tier.override_invalid_suggestion` (closest valid tier name from a fuzzy match — `null` when no candidate cleared the cutoff or when override is valid; consumed by step 4's invalid-override note as a "did you mean ...?" hint)
-- `{tier_override_unsafe}` ← `tier.override_unsafe`
-- `{tier_override_unsafe_missing}` ← `tier.override_unsafe_missing` (a list — step 4 joins with `", "` for display)
+"**About to set up the forge.** Setup has probed the available tools (ast-grep, gh, qmd and ccc, plus git and uv), read-only, and keeps their result in the scratch folder `{run_dir}` until it finishes. It goes on now to:
 
-From `require_tier`:
-
-- `{require_tier_satisfied}` ← `require_tier.satisfied` (`true | false | null`; null when `--require-tier` was not set)
-- `{require_tier_failure_missing_tools}` ← `require_tier.missing_tools` (a list)
+- Write `{sidecar_path}/forge-tier.yaml` (capability tier + tool state)
+- Create `{forge_data_folder}/` if missing
+- When ccc is available: prepare `{project-root}/.cocoindex_code/settings.yml` (run `ccc init` if it is missing, which in a git checkout also adds `/.cocoindex_code/` to `.gitignore`; merge the SKF exclusion patterns and remove ones a previous folder config left behind), then create or refresh the project ccc index
 
-From `prior` (populated by `--prior-state-from`; all fields null/empty on first run):
+**About tiers:** SKF picks one of four tiers (Quick / Forge / Forge+ / Deep) based on which tools are installed, each at its minimum version or newer. **All four are fully usable**: higher tiers add power, they don't fix gaps. If you're new and only have a base Python install, Quick tier is the right starting point and the report at the end will show you exactly which tools to install or upgrade if you want to climb later."
 
-- `{previous_tier}` ← `prior.previous_tier`
-- `{previous_detection_date}` ← `prior.previous_detection_date`
-- `{previous_tools}` ← `prior.previous_tools`
-- `{previous_ccc_index_status}` ← `prior.previous_ccc_index_status`
-- `{previous_ccc_indexed_path}` ← `prior.previous_ccc_indexed_path`
-- `{previous_ccc_last_indexed}` ← `prior.previous_ccc_last_indexed`
-- `{previous_ccc_staleness_threshold_hours}` ← `prior.previous_ccc_staleness_threshold_hours`
-- `{ccc_index_fresh}` ← `prior.ccc_index_fresh` (boolean; the script's deterministic freshness verdict — prior index covers this project AND status was fresh/created AND `last_indexed` is within the staleness threshold of now. Step 1b branches on this directly instead of doing timestamp math.)
+**Re-run notice:** when `{previous_tier}` is non-null:
 
-From `deltas` (computed by the script from current tools + prior; eliminates LLM-side set arithmetic in the report banner):
+"**Forge already set up here:** {previous_tier} tier, detected {previous_detection_date}. The tools were just re-probed, and setup now refreshes this project's config and ccc index. Next time, to refresh only the tier without paying the ccc re-index cost, run it with `--ccc-skip-index`."
 
-- `{tools_added}` ← `deltas.tools_added` (the list)
-- `{tools_removed}` ← `deltas.tools_removed` (the list)
-- `{tier_changed}` ← `deltas.tier_changed` (boolean)
+When `{require_tier_satisfied}` is `false`, end the one you display with: "`--require-tier {require_tier}` is not met: this run writes the detected tier but builds no ccc index and runs no registry hygiene."
 
 ### 4. Auto-Proceed
 
-After context flags are populated, display "**Proceeding to CCC index check...**", then load `{nextStepFile}`, read it fully, and execute it.
+Load `{nextStepFile}`, read it fully, and execute it.

package/src/skf-setup/references/health-check.md

@@ -18,6 +18,8 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 - No user-facing reports, file writes, or result contracts in this step — those belong in step 4
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
+- `{quiet_mode}` reaches `{nextStepFile}` as activation set it: skf-setup is the only workflow that sets it, and when it is true the shared health check displays nothing of its own, queues any findings locally, and displays step 4's `{setup_envelope_line}` verbatim last, as the final message of a standalone run; when `{pipeline_mode}` is true, control then returns to the forger, which keeps chaining
+- When `{quiet_mode}` is true, write no assistant text at all between tool calls: no status, progress or step-transition notes, however brief
 
 ## MANDATORY SEQUENCE
 

package/src/skf-setup/references/invocation-contract.md

@@ -0,0 +1,14 @@
+# skf-setup Invocation Contract
+
+The flags, gate, outputs, headless contract and failure modes of `skf-setup`, for headless callers and pipeline integrators. No run loads this file: SKILL.md's On Activation and the step files hold everything a run does.
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | (none) |
+| **Flags** | `--headless` / `-H` (skip prompts, auto-resolve gates to defaults); `--quiet` (an alias of `--headless`; its step 3 orphan default is recorded as `quiet-default`); `--require-tier=<Quick\|Forge\|Forge+\|Deep>` or `--require-tier <tier>` (halt with failure if calculated tier does not satisfy the requirement; any other value halts the run `blocked`, see Failure modes); `--orphan-action=<keep\|remove>` (resolve the orphan-removal gate non-interactively, even outside `--headless`; any other value halts at activation); `--ccc-skip-index` (skip building the CCC index: settings.yml is still prepared and its SKF exclusions kept current, and the envelope's `ccc_index.status` becomes `"skipped"`; the fast re-probe lane for an expert re-running only to refresh the detected tier without paying the full ccc re-index cost) |
+| **Gates** | One optional: orphaned QMD collection removal (step 3, Deep tier only; default: Keep, or whatever `--orphan-action` set; resolves without prompting under `--headless` or `--quiet`). Only a collection with a forge suffix that the registry does not list and whose QMD path lies inside this project is offered: another project's collections never are |
+| **Outputs** | `{sidecar_path}/forge-tier.yaml` and `{forge_data_folder}/` (setup never writes `preferences.yaml`: the installer creates it, and setup reads it when it is there); when ccc is available, `.cocoindex_code/settings.yml` (created by `ccc init` when missing; SKF exclusion patterns merged and stale ones removed), a `/.cocoindex_code/` line in `.gitignore` when `ccc init` adds one, and the project ccc index; for the run itself, a scratch folder under `{project-root}/_bmad-output/.skf-run/` holding the helpers' outputs, which step 4 deletes (a halt that names a phase leaves it in place) |
+| **Headless** | All gates auto-resolve with their default action under `--headless` or its alias `--quiet`, under `headless_mode: true` in `{sidecar_path}/preferences.yaml` (known once activation has loaded it, so the halts before that emit an envelope only under a flag or in a pipeline), and in a forger pipeline. Under `--headless`, `--quiet` or `headless_mode: true`, a standalone run's final message, and so everything `claude -p` prints, is exactly one line: the single-line `SKF_SETUP_RESULT_JSON: {…}` envelope from step 4 (displayed once the health check has finished, or at the tier-miss halt), or a blocked envelope from a halt, or the bare halt reason when no envelope helper can run (see Failure modes). Setup displays no FORGE STATUS banner or health-check output, and no halt diagnostic beyond that one line; the health check still runs and saves any findings to the local improvement queue. Inside a forger pipeline (`{pipeline_mode}` true), setup displays the same line and returns control to the forger. Branch on the envelope's top-level `status` field: `success`, `tier_failure` (require-tier miss), or `blocked` (any pre-report halt, whose `error.phase` names the cause). `skf-emit-result-envelope.py` derives `status` from the run's staged outputs, so pipelines never compose it from `require_tier_satisfied` + `error`. Schema: `shared/scripts/schemas/skf-setup-result-envelope.v1.json`. |
+| **Failure modes** | `--require-tier` not satisfied → status `tier_failure`, the envelope sets `"require_tier_satisfied": false`, and the workflow halts before step 5 (interactive runs also print a "REQUIRED TIER NOT MET" block). Such a run fails fast: it builds no ccc index that is due (`ccc_index.status` `"skipped"`, while a fresh index record still carries forward) and runs no registry hygiene, so it removes no QMD collection, even under `--orphan-action=remove`; it still writes `forge-tier.yaml` with the detected tier. A `--require-tier` value that is not exactly one of the four tiers is no miss: the detector rejects it, and the run ends `blocked` at `step 1:detect-tools` with a reason that names the valid tiers (with a did-you-mean hint for a wrong-case tier). A write failure (forge-tier.yaml or the forge data folder could not be written) halts step 2 with a `blocked` envelope whose `error.phase` (`step 2:write-tools` or `step 2:forge-data-dir`) and `error` name the path and reason. The other halts (uv missing, config missing, malformed or naming no usable `sidecar_path`, an `--orphan-action` other than `keep` or `remove`, a run folder that cannot be created, a helper that no probe path resolves, a failed tool detection) end the same way under `--headless` or `--quiet`: `error.phase` names the halt and `error.reason` carries the diagnostic. The exception is a run where the envelope helper itself cannot run (SKF's scripts are not installed in the project, as in a directory that is not an SKF project, or an On Activation halt on a machine where none of `uv`, `python3`, `python` and `py -3` can run it): its one line is the bare halt reason with no envelope, and a pipeline treats a missing envelope as a failure. |