bmad-module-skill-forge 2.0.0 → 2.0.1

package/src/skf-rename-skill/scripts/skf-validate-rename-name.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""SKF Validate Rename Name — deterministic new-name gate for skf-rename-skill.
+
+select.md §5 accepts a proposed new skill name and must decide four things, each
+with one correct answer for a given (name, filesystem, manifest) state:
+
+  format     — matches the module's canonical kebab-case rule
+               ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ (same regex as
+               skf-validate-output.py / skf-validate-brief-inputs.py)
+  length     — 1..64 characters (agentskills.io spec)
+  identity   — differs from the current name (nothing to rename otherwise)
+  collision  — does NOT already exist as a manifest `exports` key, a top-level
+               directory under the skills output folder, or a top-level
+               directory under the forge data folder
+
+Doing this in the prompt is a set-membership computation across three sources
+plus a regex match — deterministic, so it lives here and the prompt keeps only
+the interactive re-ask / halt decision. Checks run in the select.md §5 order and
+`first_failure` names the first failing one so the caller maps it to the right
+halt (`input-invalid`/exit 2 for format/length/identity, `name-collision`/exit 5
+for collision).
+
+`interrupted_rename` fires the select.md §5 recovery fingerprint: the new name
+collides only on disk (not in the manifest) AND both old-name directories still
+exist — the signature of a rename interrupted between copy and delete-old, which
+the caller surfaces as a named cleanup path instead of a dead-end collision.
+
+Output (stdout, always JSON):
+  {status, valid, old_name, new_name, first_failure, checks{...},
+   interrupted_rename, regex}
+
+Exit codes:
+  0  valid (all checks pass)
+  2  invalid (at least one check failed; see first_failure / checks)
+  1  operation error (bad args)
+
+CLI example:
+  python3 skf-validate-rename-name.py --old-name rename --new-name rename-skill \
+      --skills-output-folder /out --forge-data-folder /forge
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+NAME_REGEX = r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
+MIN_LEN = 1
+MAX_LEN = 64
+
+
+def load_exports(manifest_path: Path) -> tuple[set[str], str | None]:
+    """Return (export skill-name keys, error). Missing manifest -> empty set."""
+    if not manifest_path.is_file():
+        return set(), None
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        # select.md §2 halts before §5 on a malformed manifest, so treat an
+        # unreadable file here as "no exports" rather than crashing the gate.
+        return set(), f"{type(e).__name__}: {e}"
+    exports = data.get("exports", {}) if isinstance(data, dict) else {}
+    return set(exports.keys()) if isinstance(exports, dict) else set(), None
+
+
+def validate_name(
+    old_name: str,
+    new_name: str,
+    skills_output_folder: str,
+    forge_data_folder: str,
+    manifest_path: str | None = None,
+) -> dict:
+    skills_dir = Path(skills_output_folder)
+    forge_dir = Path(forge_data_folder)
+    manifest = Path(manifest_path) if manifest_path else skills_dir / ".export-manifest.json"
+
+    export_keys, manifest_error = load_exports(manifest)
+
+    fmt_ok = re.match(NAME_REGEX, new_name) is not None
+    length = len(new_name)
+    len_ok = MIN_LEN <= length <= MAX_LEN
+    identity_ok = new_name != old_name
+
+    locations: list[dict] = []
+    if new_name in export_keys:
+        locations.append({"kind": "manifest.exports", "path": str(manifest)})
+    if (skills_dir / new_name).is_dir():
+        locations.append({"kind": "skills_output_folder", "path": str(skills_dir / new_name)})
+    if (forge_dir / new_name).is_dir():
+        locations.append({"kind": "forge_data_folder", "path": str(forge_dir / new_name)})
+    collision_ok = len(locations) == 0
+
+    # Recovery fingerprint: collides on disk only (not manifest) and both
+    # old-name directories still exist -> stranded partial rename, not a genuine
+    # clash.
+    collides_on_disk_only = (
+        not collision_ok
+        and all(loc["kind"] != "manifest.exports" for loc in locations)
+    )
+    interrupted_rename = bool(
+        collides_on_disk_only
+        and (skills_dir / old_name).is_dir()
+        and (forge_dir / old_name).is_dir()
+    )
+
+    checks = {
+        "format": {"ok": fmt_ok},
+        "length": {"ok": len_ok, "length": length},
+        "identity": {"ok": identity_ok},
+        "collision": {"ok": collision_ok, "locations": locations},
+    }
+
+    first_failure = None
+    for name in ("format", "length", "identity", "collision"):
+        if not checks[name]["ok"]:
+            first_failure = name
+            break
+
+    result = {
+        "status": "ok",
+        "valid": first_failure is None,
+        "old_name": old_name,
+        "new_name": new_name,
+        "first_failure": first_failure,
+        "checks": checks,
+        "interrupted_rename": interrupted_rename,
+        "regex": NAME_REGEX,
+    }
+    if manifest_error:
+        result["manifest_error"] = manifest_error
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate a proposed rename target name.")
+    parser.add_argument("--old-name", required=True)
+    parser.add_argument("--new-name", required=True)
+    parser.add_argument("--skills-output-folder", required=True)
+    parser.add_argument("--forge-data-folder", required=True)
+    parser.add_argument("--manifest", default=None)
+    args = parser.parse_args(argv)
+
+    result = validate_name(
+        args.old_name,
+        args.new_name,
+        args.skills_output_folder,
+        args.forge_data_folder,
+        args.manifest,
+    )
+    print(json.dumps(result, indent=2))
+    return 0 if result["valid"] else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/skf-setup/SKILL.md

@@ -7,12 +7,13 @@ description: Initialize forge environment, detect tools, and set capability tier
 
 ## Overview
 
-Initializes the forge environment by detecting available tools, determining the capability tier (Quick/Forge/Forge+/Deep), and writing persistent configuration to `{project-root}/_bmad/_memory/forger-sidecar/`. When `ccc` (cocoindex-code) is available, also augments `.cocoindex_code/settings.yml` with SKF exclusion patterns and creates or refreshes the project's semantic-search index. On Deep tier, reconciles the QMD collection registry; whenever ccc is available, reconciles the CCC index registry as well. The workflow is autonomous with one optional gate — orphaned QMD collection removal in step 3 (Deep tier only; default action: Keep) — which auto-resolves non-interactively when `{headless_mode}` is true or when `--orphan-action=<keep|remove>` is passed.
+Initializes the forge environment by detecting available tools, determining the capability tier (Quick/Forge/Forge+/Deep), and writing persistent configuration to `{project-root}/_bmad/_memory/forger-sidecar/`. When `ccc` (cocoindex-code) is available, also augments `.cocoindex_code/settings.yml` with SKF exclusion patterns and creates or refreshes the project's semantic-search index. On Deep tier, reconciles the QMD collection registry; whenever ccc is available, reconciles the CCC index registry as well.
 
 ## 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.
+- `references/` holds prompt content carved out of SKILL.md — workflow stages chained via frontmatter `nextStepFile`, plus static reference docs.
+- Deterministic work is delegated to shared Python helpers under `src/shared/scripts/` (installed as `_bmad/skf/shared/scripts/`). Each step's frontmatter declares a `*ProbeOrder` array for the helpers it needs: run the first path in the array that exists, and halt if none resolve — the script owns that logic, with no prose fallback.
 - `{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.
@@ -23,15 +24,12 @@ You are a system executor performing environment resolution. Run each step in se
 
 ## Workflow Rules
 
-- One optional gate (step 3 orphan-removal prompt; default: Keep). Every other step auto-proceeds.
 - Only load one step file at a time — never preload future steps.
 - Communicate in `{communication_language}`.
-- If `{headless_mode}` is true, or if `{orphan_action}` is non-null, auto-resolve the gate non-interactively and log the decision.
+- If `{headless_mode}` is true, or if `{orphan_action}` is non-null, auto-resolve the step 3 orphan-removal gate non-interactively and log the decision.
 
 ## Stages
 
-All stages auto-proceed except the optional orphan-removal gate in step 3.
-
 | # | Step | File |
 |---|------|------|
 | 1 | Detect Tools & Set Tier | references/detect-and-tier.md |
@@ -49,15 +47,14 @@ All stages auto-proceed except the optional orphan-removal gate in step 3.
 | **Flags** | `--headless` / `-H` (skip prompts, auto-resolve gates to defaults); `--require-tier=<Quick\|Forge\|Forge+\|Deep>` (halt with failure if calculated tier does not satisfy the requirement); `--orphan-action=<keep\|remove>` (resolve the orphan-removal gate non-interactively, even outside `--headless`); `--ccc-skip-index` (skip CCC indexing; envelope `ccc_index.status` becomes `"skipped"` — the fast re-probe lane for an expert re-running only to refresh the detected tier without paying the full ccc re-index cost); `--quiet` (suppress the human-readable FORGE STATUS banner — pipelines and expert re-runners get the envelope only) |
 | **Gates** | One optional: orphaned QMD collection removal (step 3, Deep tier only; default: Keep, or whatever `--orphan-action` set) |
 | **Outputs** | `forger-sidecar/forge-tier.yaml`, `forger-sidecar/preferences.yaml`, `{forge_data_folder}/`; when ccc is available, `.cocoindex_code/settings.yml` (exclusion patterns merged) and the project ccc index |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Under `--headless` or `--quiet`, step 4 emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope as the only stdout line — the FORGE STATUS banner is suppressed. Branch on the envelope's top-level `status` field (one of `success`, `tier_failure`, `write_failure`, `blocked`) — `skf-emit-result-envelope.py` derives it from the payload, so pipelines never compose it from `require_tier_satisfied` + `error`. Schema in `references/report.md` §4. |
-| **Failure modes** | `--require-tier` not satisfied → status becomes `tier_failure`, the envelope sets `"require_tier_satisfied": false`, and the workflow halts before step 5 (interactive runs also print a "REQUIRED TIER NOT MET" block). |
-| **Exit codes** | The workflow runs as an LLM-driven sequence rather than a CLI process, so "exit code" describes the agent's terminal state for a calling pipeline that reads `SKF_SETUP_RESULT_JSON`. **0 — success** (no JSON `error` field, all writes completed, `require_tier_satisfied` is `true` or `null`). **1 — required-tier failure** (`require_tier_satisfied` is `false`; envelope still emitted with full state for diagnosis). **2 — write failure** (forge-tier.yaml or preferences.yaml could not be written; envelope `error` field names the path and reason). Pipelines should branch on the JSON `require_tier_satisfied` and `error` fields rather than process exit codes. |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Under `--headless` or `--quiet`, step 4 emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope as the only stdout line — the FORGE STATUS banner is suppressed. Branch on the envelope's top-level `status` field: `success`, `tier_failure` (require-tier miss), or `blocked` (any pre-report halt — the `error.phase` names the cause). `skf-emit-result-envelope.py` derives `status` from the payload, so pipelines never compose it from `require_tier_satisfied` + `error`. Schema in `references/report.md` §4. |
+| **Failure modes** | `--require-tier` not satisfied → status `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). A write failure (forge-tier.yaml or preferences.yaml could not be written) halts step 2 with a `blocked` envelope whose `error.phase` (`step 2:write-tools` or `step 2:init-prefs`) and `error` name the path and reason. |
 
 ## On Activation
 
-> **Halt contract for headless/quiet runs.** Any halt below MUST first emit a blocked envelope when `{headless_mode}` or `{quiet_mode}` is true, before printing the human diagnostic. Pipe `{"phase":"<phase>","reason":"<reason>","path":"<path>"}` to `python3 <helper> emit-blocked` where `<helper>` is the first existing path of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` then `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`. The `emit-blocked` subcommand declares zero dependencies (no `uv`, no `pyyaml`), so it works even when `uv` itself is the thing that's missing.
+> **Halt contract for headless/quiet runs.** Any halt below must first emit a blocked envelope when `{headless_mode}` or `{quiet_mode}` is true, before printing the human diagnostic — a pipeline observer that sees no envelope treats the run as not-completed-cleanly. Pipe `{"phase":"<phase>","reason":"<reason>","path":"<path>"}` to `python3 <helper> emit-blocked` where `<helper>` is the first existing path of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` then `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`. The `emit-blocked` subcommand declares zero dependencies (no `uv`, no `pyyaml`), so it works even when `uv` itself is the thing that's missing.
 
-1. **Parse invocation flags FIRST** (so every halt below knows whether to emit an envelope): `{headless_mode}` (true on `--headless` / `-H`), `{require_tier}` (`--require-tier=<Quick|Forge|Forge+|Deep>`, case-sensitive; null if absent or unparseable), `{orphan_action}` (`--orphan-action=<keep|remove>`; null if absent), `{ccc_skip_index}` (true on `--ccc-skip-index`), `{quiet_mode}` (true on `--quiet`).
+1. **Parse invocation flags first** (so every halt below knows whether to emit an envelope): `{headless_mode}` (true on `--headless` / `-H`), `{require_tier}` (`--require-tier=<Quick|Forge|Forge+|Deep>`, case-sensitive; null if absent or unparseable), `{orphan_action}` (`--orphan-action=<keep|remove>`; null if absent), `{ccc_skip_index}` (true on `--ccc-skip-index`), `{quiet_mode}` (true on `--quiet`).
 
 2. **Probe `uv` runtime.** Run `uv --version`. Every step invokes shared Python helpers via `uv run` (PEP 723 inline metadata auto-resolves `pyyaml`). If `uv` is missing, halt with phase `on-activation:uv-missing` and the human diagnostic:
 
@@ -67,4 +64,15 @@ All stages auto-proceed except the optional orphan-removal gate in step 3.
 
 4. **Reconcile `{headless_mode}`** with `preferences.yaml`: OR the parsed flag with `headless_mode: true` from the YAML.
 
-5. Execute `references/detect-and-tier.md`.
+5. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-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), and `_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.
+
+   Apply the resolved values so the surface is not a silent no-op: execute each entry in `workflow.activation_steps_prepend` in order now (org-wide pre-flight checks such as auth, network, or compliance); treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries are paths or globs whose contents load as facts); stash `{onCompleteCommand}` ← `workflow.on_complete` (empty string = no-op) for `references/report.md` §5 to invoke at the terminal stage. After activation completes, execute each entry in `workflow.activation_steps_append` in order, before the first stage runs.
+
+6. Execute `references/detect-and-tier.md`.

package/src/skf-setup/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-setup.
+# Team overrides:     _bmad/custom/skf-setup.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-setup.user.toml (under {project-root})
 
 [workflow]
 
@@ -31,3 +33,11 @@ activation_steps_append = []
 #     contents are loaded and treated as facts).
 
 persistent_facts = []
+
+# Instruction run once the forge is fully configured — after the status report
+# (step 4) emits, before chaining to the shared health check. Override wins. Use
+# for a post-setup action an org wants after the forge is configured — e.g.
+# trigger the first index build or notify an onboarding channel. Empty string =
+# no terminal hook.
+
+on_complete = ""

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

@@ -1,10 +1,9 @@
 ---
 nextStepFile: 'report.md'
-# Resolve `{qmdClassifyHelper}` and `{forgeTierRwHelper}` by probing the
-# corresponding `*ProbeOrder` arrays (installed SKF module path first, src/
-# dev-checkout fallback); first existing path wins. HALT if neither resolves
-# for the helper a section actually invokes — both scripts own classification
-# / registry-cleanup contracts that have no prose fallback.
+# `{qmdClassifyHelper}` and `{forgeTierRwHelper}` = first existing path in
+# their `*ProbeOrder` arrays; halt if neither exists for a helper a section
+# actually invokes. Both scripts own classification / registry-cleanup
+# contracts with 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'
@@ -45,7 +44,7 @@ Default `{orphan_auto_resolution}` to null at the top of this step; only the non
 
 **If `{calculated_tier}` is Forge+:** Same as Quick/Forge with ccc — no QMD work (qmd unavailable at Forge+), but ccc registry hygiene runs.
 
-**If `{calculated_tier}` IS Deep:** Continue to section 2.
+**If `{calculated_tier}` is Deep:** Continue to section 2.
 
 ### 2. Classify Live QMD Collections vs Registry
 
@@ -56,7 +55,7 @@ uv run {qmdClassifyHelper} \
     --registry-from-yaml "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"
 ```
 
-The script (see `src/shared/scripts/skf-qmd-classify-collections.py` docstring for the full schema) invokes `qmd collection list` itself, applies the forge-namespace suffix filter (`-brief | -temporal | -docs | -extraction`) before classifying, and exits non-zero with an error message on stderr if the daemon is down. Collections owned by unrelated tools are silently excluded from the orphan / healthy / stale sets and counted under `foreign_filtered_count` for telemetry only. This is the PR #244 incident protection: foreign collections never enter any classification that could lead to data loss.
+The script (see `src/shared/scripts/skf-qmd-classify-collections.py` docstring for the full schema) invokes `qmd collection list` itself, applies the forge-namespace suffix filter (`-brief | -temporal | -docs | -extraction`) before classifying, and exits non-zero with an error message on stderr if the daemon is down. Collections owned by unrelated tools are silently excluded from the orphan / healthy / stale sets and counted under `foreign_filtered_count` for telemetry only — foreign collections never enter any classification that could lead to data loss.
 
 **Error handling:** If the script exits non-zero, set `{hygiene_result: "qmd_unavailable", hygiene_healthy: 0, hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0, hygiene_stale_cleaned: 0}` and skip directly to section 4 (which will still run the ccc-prune branch if `{ccc}` is true).
 
@@ -74,7 +73,7 @@ Set `{hygiene_result: "completed"}`.
 
 **If `{orphaned_collections}` is empty:** Set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0}` and skip to section 4.
 
-**Non-interactive resolution.** If `{orphan_action}` is non-null, resolve the gate without prompting using that value: log `"Auto-decision (--orphan-action={value}): kept|removed {len(orphaned_collections)} orphaned forge collection(s)"` and set `{orphan_auto_resolution: {action: "{orphan_action}", count: len(orphaned_collections), source: "orphan-action-flag"}}` so step 4 can fold it into the envelope warnings (the audit trail matters most when `remove` deletes collections headlessly). If `{orphan_action}` is `"keep"`, set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: len(orphaned_collections)}` and skip to section 4. If `"remove"`, fall through to the removal block below (still no user prompt). Independently, if `{headless_mode}` is true and `{orphan_action}` is null, auto-resolve to the default **Keep** with the equivalent log line, set `{orphan_auto_resolution: {action: "keep", count: len(orphaned_collections), source: "headless-default"}}`, and skip to section 4. The two paths compose: `--orphan-action` overrides the headless default; `--headless` without `--orphan-action` keeps backward-compatible behavior. (On an interactive resolution — section 3's prompt below — leave `{orphan_auto_resolution}` null; the human chose, so there is no auto-decision to audit.)
+**Non-interactive resolution.** If `{orphan_action}` is non-null, resolve the gate without prompting using that value: log `"Auto-decision (--orphan-action={value}): kept|removed {len(orphaned_collections)} orphaned forge collection(s)"` and set `{orphan_auto_resolution: {action: "{orphan_action}", count: len(orphaned_collections), source: "orphan-action-flag"}}` so step 4 can fold it into the envelope warnings (the audit trail matters most when `remove` deletes collections headlessly). If `{orphan_action}` is `"keep"`, set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: len(orphaned_collections)}` and skip to section 4. If `"remove"`, fall through to the removal block below (still no user prompt). Independently, if `{headless_mode}` is true and `{orphan_action}` is null, auto-resolve to the default **Keep** with the equivalent log line, set `{orphan_auto_resolution: {action: "keep", count: len(orphaned_collections), source: "headless-default"}}`, and skip to section 4. The two paths compose: `--orphan-action` overrides the headless default; `--headless` alone falls back to the default Keep. (On an interactive resolution — section 3's prompt below — leave `{orphan_auto_resolution}` null; the human chose, so there is no auto-decision to audit.)
 
 **If `{headless_mode}` is false**, display to the user:
 
@@ -99,7 +98,7 @@ Track the count of successful removals as `{hygiene_orphaned_removed}`. Set `{hy
 
 ### 4. Stale Registry Cleanup
 
-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.
+This section runs whenever 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.
 
 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.
 
@@ -110,7 +109,7 @@ uv run {forgeTierRwHelper} clean-stale \
     [--prune-missing-ccc-paths]
 ```
 
-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).
+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.
 
 **Parse the JSON output and set context flags for step 4:**
 

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

@@ -1,10 +1,9 @@
 ---
 nextStepFile: 'write-config.md'
-# Resolve `{mergeCccExclusionsHelper}` by probing `{mergeCccExclusionsProbeOrder}`
-# in order (installed SKF module path first, src/ dev-checkout fallback); first
-# existing path wins. HALT if neither resolves — the script owns config-value
-# validation and the set-union merge into .cocoindex_code/settings.yml; no
-# fallback to prose-driven validation.
+# `{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:
   - '{project-root}/_bmad/skf/shared/scripts/skf-merge-ccc-exclusions.py'
   - '{project-root}/src/shared/scripts/skf-merge-ccc-exclusions.py'
@@ -25,7 +24,7 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 - 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
-- Never reimplement the exclusion-pattern validation in prose — the script owns the PR #248 rules
+- The script owns exclusion-pattern validation — do not reimplement it in prose
 
 ## MANDATORY SEQUENCE
 
@@ -35,24 +34,24 @@ 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 4 (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 4 — 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 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 4 — 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.previous_ccc_*` context flags) — no YAML re-parse here, the detector already read forge-tier.yaml. Use `prior.previous_ccc_staleness_threshold_hours` if set, else default 24 hours.
+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 those flags:
+Decide `{needs_reindex}` and `{ccc_index_result}` from `{ccc_index_fresh}`:
 
-- If `previous_ccc_indexed_path` matches `{project-root}` AND `previous_ccc_index_status` is `"fresh"` or `"created"` AND `previous_ccc_last_indexed` is within `staleness_threshold_hours` of now → index is fresh. Set `{needs_reindex: false}`, `{ccc_index_result: "fresh", ccc_indexed_path: {project-root}, ccc_last_indexed: <existing timestamp>}`. Exclusions still merge in section 3 (which may force a re-index).
-- If path matches but the timestamp is older than threshold, or if the path doesn't match, or if any prior CCC field is null → `{needs_reindex: true}`.
+- 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}`.
 
 ### 3. Merge SKF Exclusion Patterns
 
 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.
 
-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` so PEP 723 inline metadata resolves the script's PyYAML dependency automatically (per `docs/getting-started.md`'s prereq list — uv exists for this exact purpose). Bare `python3` will fail on a fresh Python with `ModuleNotFoundError: No module named 'yaml'`.
+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`.
 
 ```bash
 uv run {mergeCccExclusionsHelper} \
@@ -61,14 +60,14 @@ uv run {mergeCccExclusionsHelper} \
     --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 PR #248 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).
+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_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"
@@ -114,7 +113,7 @@ ccc index
 
 - 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
+- Continue — this is not a workflow error
 
 ### 5. Auto-Proceed
 

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

@@ -1,9 +1,8 @@
 ---
 nextStepFile: 'ccc-index.md'
-# Resolve `{detectToolsHelper}` by probing `{detectToolsProbeOrder}` in order
-# (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves — the script is the source of truth for
-# tool detection and tier calculation; no fallback to prose-driven probes.
+# `{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.
 detectToolsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-tools.py'
   - '{project-root}/src/shared/scripts/skf-detect-tools.py'
@@ -54,9 +53,9 @@ Press Esc or Ctrl+C now if this isn't the right project — no files have been w
 
 ### 2. Run Detection Helper
 
-Build the Bash invocation: `uv run {detectToolsHelper} --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. (The script's PEP 723 metadata is why `uv run` is required — bare `python3` skips dependency resolution.)
+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.)
 
-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.
+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.
 
 ### 3. Parse Output and Set Context Flags
 
@@ -101,6 +100,7 @@ From `prior` (populated by `--prior-state-from`; all fields null/empty on first
 - `{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.)
 
 From `deltas` (computed by the script from current tools + prior; eliminates LLM-side set arithmetic in the report banner):
 
@@ -108,8 +108,6 @@ From `deltas` (computed by the script from current tools + prior; eliminates LLM
 - `{tools_removed}` ← `deltas.tools_removed` (the list)
 - `{tier_changed}` ← `deltas.tier_changed` (boolean)
 
-**The script is the source of truth.** Every tier-rules edge case (override-honored-but-unsafe, Deep-doesn't-subsume-Forge+, qmd-binary-vs-daemon distinction, ccc-identity-marker rejection of foreign binaries) is locked into the test suite at `test/test-skf-detect-tools.py`. Substituting prose-driven logic for the script's output here will cause subtle re-run regressions that the prompt's prose is no longer detailed enough to catch.
-
 ### 4. Auto-Proceed
 
 After context flags are populated, display "**Proceeding to CCC index check...**", then load `{nextStepFile}`, read it fully, and execute it.

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

@@ -1,12 +1,11 @@
 ---
 tierRulesData: 'references/tier-rules.md'
 nextStepFile: '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).
+# `{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).
 emitEnvelopeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
   - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
@@ -27,19 +26,13 @@ Display the forge status report with positive capability framing, surface tier c
 - 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
-
-## Headless Mode Display Rule
-
-When `{headless_mode}` is `true` OR `{quiet_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 those modes 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, CI pipelines, and expert re-runners consume the envelope alone; they should not be forced to scroll past 30 lines of ASCII-art they cannot use.
-
-When both `{headless_mode}` and `{quiet_mode}` are `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).
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing status report is not the terminal step
 
 ## MANDATORY SEQUENCE
 
 ### 1. Load Capability Descriptions
 
-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.
+Load and read {tierRulesData} for the tier capability descriptions and re-run messages. Needed by section 2.
 
 ### 2. Display Forge Status Report (skip when `{headless_mode}` or `{quiet_mode}` is true)
 
@@ -54,7 +47,7 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {tier capability description from tier-rules.md}
 
   Tools Detected:
-  {for each tool that is available, show: tool name — version}
+  {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:}
@@ -64,7 +57,7 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {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)}
+  {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":}
@@ -122,6 +115,9 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
            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}
 
@@ -129,7 +125,7 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {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):}
+{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.
@@ -144,15 +140,9 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
 
 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.
 
-**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. Display Required-Tier Failure Block (when applicable; skip when `{headless_mode}` or `{quiet_mode}` is true)
 
-If `{require_tier_satisfied}` is `false` AND both `{headless_mode}` and `{quiet_mode}` are `false`, display this block immediately after the status report. In headless or quiet modes the failure surfaces via the envelope's `require_tier_satisfied: false` and the synthesized `warnings` entry — the human prose block would be log noise.
+If `{require_tier_satisfied}` is `false`, display this block immediately after the status report (the heading gate already handles the headless/quiet skip).
 
 When the block does fire (interactive run with require-tier failure):
 
@@ -170,11 +160,9 @@ When the block does fire (interactive run with require-tier failure):
 ═══════════════════════════════════════
 ```
 
-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` 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` 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.
+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.
 
 ```bash
 echo '{
@@ -212,10 +200,13 @@ echo '{
 
 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 (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").
-
-**When both `{headless_mode}` and `{quiet_mode}` are `false`, do NOT invoke the script** — interactive runs read the human-readable banner.
+**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").
 
 ### 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 5. 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.
+After the forge status report (and any failure block + JSON envelope) has been displayed:
+
+- 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.
+
+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.