bmad-module-skill-forge 2.1.0 → 3.0.0

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # /// script
-# requires-python = ">=3.10"
+# requires-python = ">=3.11"
 # ///
 """SKF Validate Rename Name — deterministic new-name gate for skf-rename-skill.
 
@@ -12,9 +12,11 @@ with one correct answer for a given (name, filesystem, manifest) state:
                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
+  collision  — does NOT already exist (a folder, a file or a link, even a
+               broken one) as a manifest `exports` key, a top-level entry
+               under the skills output folder or the forge data folder, and
+               is not `improvement-queue`, SKF's own forge folder (location
+               kind `reserved`)
 
 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
@@ -23,14 +25,34 @@ the interactive re-ask / halt decision. Checks run in the select.md §5 order an
 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.
+`interrupted_rename` fires the select.md §5 recovery fingerprint. A rename's
+copy creates the new skill folder first, and a new forge folder only from an
+old one. So the new name collides only on disk (not in the manifest, not on a
+reserved name), at least under the skills output folder, while the old skill
+folder still exists, and under the forge data folder only when the old skill
+has a forge folder too — 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. The new skill folder must also hold nothing a copy of the
+old one could not: every entry in it exists in the old folder, of the same
+kind, with only each version's package renamed. A forge-only collision
+(another tool's folder with the new name), or a module's own skill or another
+tool's folder at the new name, is a genuine clash.
+
+`interrupted_after_rekey` fires the recovery for a rename that stopped after
+it re-keyed the export manifest, before it deleted the old folders: the new
+name is a manifest key and the old name no longer is, both skill folders are
+plain folders, and the old one holds nothing the new one lacks (every entry
+in it exists in the new folder, of the same kind, with only each version's
+package renamed). The new name is then the skill, and the old folders are
+what that run left. `leftover_folders` lists them for the caller to name:
+the old skill folder and, when that rename moved the forge folder (the old
+and new forge folders are plain folders and the old one holds nothing the
+new one lacks), the old forge folder. It is empty when the fingerprint does
+not fire.
 
 Output (stdout, always JSON):
   {status, valid, old_name, new_name, first_failure, checks{...},
-   interrupted_rename, regex}
+   interrupted_rename, interrupted_after_rekey, leftover_folders, regex}
 
 Exit codes:
   0  valid (all checks pass)
@@ -46,13 +68,19 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import re
 import sys
 from pathlib import Path
 
 NAME_REGEX = r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$"
+# Keep identical to FORGE_GROUP_DIRS in skf-skill-inventory.py
+# (test/test-skf-skill-inventory.py pins the copies).
+FORGE_GROUP_DIRS = frozenset({"_campaign", "improvement-queue"})
 MIN_LEN = 1
 MAX_LEN = 64
+# OS clutter that a copy can gain without the rename writing it.
+CLUTTER = frozenset({".DS_Store", "Thumbs.db", "desktop.ini"})
 
 
 def load_exports(manifest_path: Path) -> tuple[set[str], str | None]:
@@ -69,6 +97,107 @@ def load_exports(manifest_path: Path) -> tuple[set[str], str | None]:
     return set(exports.keys()) if isinstance(exports, dict) else set(), None
 
 
+# Keep identical to _is_link_or_junction in skf-skill-inventory.py
+# (test/test-skf-skill-inventory.py pins the copies).
+def _is_link_or_junction(p: Path) -> bool:
+    """True for POSIX symlinks AND Windows junctions/symlinks.
+
+    `Path.is_symlink()` is False for Windows junctions; os.readlink succeeds
+    for both symlinks and junctions (since CPython 3.8 on Windows). A regular
+    directory raises OSError on readlink, which is the signal we want to
+    refuse replacement. On Windows, any other reparse point (a cloud-sync
+    placeholder, a deduplicated file, an app execution alias) raises
+    ValueError: it does not redirect to another path, so it is not a link.
+    """
+    if p.is_symlink():
+        return True
+    if not p.exists() and not p.is_symlink():
+        return False
+    try:
+        os.readlink(p)
+        return True
+    except (OSError, ValueError):
+        return False
+
+
+def _within(new: Path, old: Path, depth: int, old_name: str, new_name: str) -> bool:
+    """True when every entry under `new` also exists under `old`, of the same kind.
+
+    Depth 0 is the skill folder, depth 1 a version folder: there the renamed
+    package `{new_name}` stands for `{old_name}`. OS clutter and `.skf-`
+    names (the rename's own staging and link swaps) are ignored. A link or
+    junction matches only a link or junction.
+    """
+    try:
+        children = list(new.iterdir())
+    except OSError:
+        return False
+    for child in children:
+        name = child.name
+        if name in CLUTTER or ".skf-" in name:
+            continue
+        counterpart = old / (old_name if depth == 1 and name == new_name else name)
+        child_link, counterpart_link = _is_link_or_junction(child), _is_link_or_junction(counterpart)
+        if child_link or counterpart_link:
+            if not (child_link and counterpart_link):
+                return False
+        elif child.is_dir():
+            if not counterpart.is_dir() or not _within(child, counterpart, depth + 1, old_name, new_name):
+                return False
+        elif not counterpart.is_file():
+            return False
+    return True
+
+
+def _looks_like_a_copy(skills_dir: Path, old_name: str, new_name: str) -> bool:
+    """True when `{skills_dir}/{new_name}` could be a rename's copy of `{old_name}`.
+
+    The copy takes the old skill folder as it is, then renames each version's
+    `{old_name}/` package to `{new_name}/` and rewrites files in place, so it
+    never holds an entry the old folder lacks. A module's own skill (a root
+    `SKILL.md`) or another tool's folder with the new name does.
+    """
+    new, old = skills_dir / new_name, skills_dir / old_name
+    if (_is_link_or_junction(new) or not new.is_dir()
+            or _is_link_or_junction(old) or not old.is_dir()):
+        return False
+    return _within(new, old, 0, old_name, new_name)
+
+
+def _copied_whole(old: Path, new: Path, old_name: str, new_name: str) -> bool:
+    """True when both are plain folders and `old` holds nothing `new` lacks.
+
+    _within with the two folders swapped: every entry under the old folder
+    exists under the new one, of the same kind, where a version's
+    `{old_name}/` package stands for its renamed `{new_name}/`.
+    """
+    if (_is_link_or_junction(old) or not old.is_dir()
+            or _is_link_or_junction(new) or not new.is_dir()):
+        return False
+    return _within(old, new, 0, new_name, old_name)
+
+
+def _rekeyed_leftovers(skills_dir: Path, forge_dir: Path, old_name: str, new_name: str,
+                       export_keys: set[str]) -> list[str]:
+    """The old folders a rename left when it stopped after re-keying the manifest.
+
+    Empty unless the manifest names the new skill and no longer the old one,
+    and the old skill folder holds nothing the new one lacks. The old forge
+    folder is listed only when the rename moved it: its copy under the new
+    name exists, and it holds nothing that copy lacks. When both settings
+    name one folder, the skill folder is the forge folder, listed once.
+    """
+    if new_name not in export_keys or old_name in export_keys:
+        return []
+    if not _copied_whole(skills_dir / old_name, skills_dir / new_name, old_name, new_name):
+        return []
+    leftovers = [str(skills_dir / old_name)]
+    if (os.path.realpath(forge_dir) != os.path.realpath(skills_dir)
+            and _copied_whole(forge_dir / old_name, forge_dir / new_name, old_name, new_name)):
+        leftovers.append(str(forge_dir / old_name))
+    return leftovers
+
+
 def validate_name(
     old_name: str,
     new_name: str,
@@ -90,24 +219,33 @@ def validate_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():
+    if os.path.lexists(skills_dir / new_name):
         locations.append({"kind": "skills_output_folder", "path": str(skills_dir / new_name)})
-    if (forge_dir / new_name).is_dir():
+    if os.path.lexists(forge_dir / new_name):
         locations.append({"kind": "forge_data_folder", "path": str(forge_dir / new_name)})
+    if new_name in FORGE_GROUP_DIRS:
+        locations.append({"kind": "reserved", "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)
-    )
+    # Recovery fingerprint: a rename's copy creates the new skill folder
+    # first, and a new forge folder only from an old one. So a stranded
+    # partial rename collides on disk only (not in the manifest, not on a
+    # reserved name), at least in the skills folder, where the new folder
+    # holds nothing a copy of the old skill folder could not, and at the
+    # forge folder only when the old skill has one.
+    kinds = {loc["kind"] 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()
+        not collision_ok
+        and not kinds & {"manifest.exports", "reserved"}
+        and "skills_output_folder" in kinds
+        and _looks_like_a_copy(skills_dir, old_name, new_name)
+        and ("forge_data_folder" not in kinds or (forge_dir / old_name).is_dir())
     )
+    # Recovery fingerprint after the commit point: the manifest already names
+    # the new skill, so the new name is taken for good, and the old folders are
+    # what the rename left before it deleted them.
+    leftover_folders = [] if collision_ok or "reserved" in kinds else _rekeyed_leftovers(
+        skills_dir, forge_dir, old_name, new_name, export_keys)
 
     checks = {
         "format": {"ok": fmt_ok},
@@ -130,6 +268,8 @@ def validate_name(
         "first_failure": first_failure,
         "checks": checks,
         "interrupted_rename": interrupted_rename,
+        "interrupted_after_rekey": bool(leftover_folders),
+        "leftover_folders": leftover_folders,
         "regex": NAME_REGEX,
     }
     if manifest_error:

package/src/skf-setup/SKILL.md

@@ -1,32 +1,37 @@
 ---
 name: skf-setup
-description: Initialize forge environment, detect tools, and set capability tier (Quick/Forge/Forge+/Deep). Use when the user requests to "set up" or "initialize the forge".
+description: Initialize forge environment, detect tools, and set capability tier (Quick/Forge/Forge+/Deep). Use when the user requests to "set up the forge" or "initialize the forge".
 ---
 
 # Setup Forge
 
 ## 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.
+Detects the available tools, sets the capability tier (Quick/Forge/Forge+/Deep) and writes the forge configuration to `{sidecar_path}/`. With `ccc` it also keeps `.cocoindex_code/settings.yml` and the semantic-search index current, and it reconciles the QMD and CCC index registries.
 
 ## 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.
-- 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.
+- **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.
+- **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.
+- `references/` holds the workflow stages (chained by frontmatter `nextStepFile`), the invocation contract and `tier-rules.md`, the tier table `report.md` passes to the emitter's banner.
+- Shared Python helpers do the deterministic work, with no prose fallback: each step's frontmatter `*ProbeOrder` array lists a helper's installed path (`{project-root}/_bmad/skf/shared/scripts/<name>`) then its dev path (`{project-root}/src/shared/scripts/<name>`). Run the first that exists; if none does, halt through the On Activation halt contract with phase `step <N>:helper-missing`.
 - `{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.
 
 ## Role
 
-You are a system executor performing environment resolution. Run each step in sequence, write configuration files, and report results at completion.
+You are a system executor: run each step in sequence, write the configuration files, and report at completion.
 
 ## Workflow Rules
 
 - 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 step 3 orphan-removal gate non-interactively and log the decision.
+- If `{orphan_action}` is non-null or `{quiet_mode}` is true, resolve the step 3 orphan-removal gate without prompting; step 3 records the decision for the envelope's `warnings`.
+- When `{quiet_mode}` is true, the one line setup displays is the `SKF_SETUP_RESULT_JSON: {…}` envelope that step 4 builds, or the blocked envelope from a halt. In a standalone run that line is the run's final message, so it is all `claude -p` prints (step 4 holds it until then).
+- When `{quiet_mode}` is true, write no assistant text at all between tool calls: no status, progress or step-transition notes, however brief.
+- When `{pipeline_mode}` is true, the forger runs setup as one step of a pipeline: display the same envelope line, then return control to the forger, which keeps chaining. The final-message rule above is for a standalone run.
 
 ## Stages
 
@@ -41,38 +46,33 @@ You are a system executor performing environment resolution. Run each step in se
 
 ## Invocation Contract
 
-| Aspect | Detail |
-|--------|--------|
-| **Inputs** | (none) |
-| **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: `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. |
+`references/invocation-contract.md` holds the flags, gate, outputs, `SKF_SETUP_RESULT_JSON` contract and failure modes for pipeline authors; no run loads it.
 
 ## 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 — 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.
+> **Halt contract.** Every halt in this workflow that names a phase, below and in the step files, follows this contract; the step 4 tier-miss halt names none and displays its `tier_failure` envelope instead. When `{quiet_mode}` is true, run `<runner> <helper> emit-blocked --phase '<phase>' --reason '<reason>' --path "<path>"` (`<path>` written with `/`; no `--path` for a halt without one): `<helper>` is `skf-emit-result-envelope.py`, at its installed path, else its dev path (Conventions), and `<runner>` is `uv run` in the step files. The halts in this list can fire before `uv` is proven present, so for them try the runners `uv run`, `python3`, `python` and `py -3` in that order and stop at the first that exits 0 and prints a line starting `SKF_SETUP_RESULT_JSON:` (the helper is stdlib-only). Display that line verbatim, nothing else. If neither path exists, or no runner exits 0 and prints that line, display the reason alone as that one line. Interactive runs display the reason as their diagnostic and emit no envelope. Text from the user or a helper never goes into the single-quoted `--reason`: write `<message>` there and pass the text on stdin with `--stderr-from -` and a quoted `<<'SKF_TEXT'` heredoc, one per runner tried, for the emitter to fold to one line and escape. Once item 6 binds `{customization_resolver_unavailable}` to a reason, every halt also passes `--customization-resolver-unavailable "<reason>"`, escaping each `\`, `"`, `$` and backtick in it with a backslash. `--headless` and `--quiet` are known at every halt, `headless_mode` from `preferences.yaml` only after item 5.
 
-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: `{headless_mode}` (true on `--headless` / `-H`, and when `{pipeline_mode}` is true), `{quiet_mode}` (true on `--quiet`, the alias of `--headless`, and whenever `{headless_mode}` is true), `{require_tier}` and `{orphan_action}` (each flag's raw value exactly as given, after `=` or a space; an empty string when nothing, or another flag, follows it; null only when the flag is absent), `{ccc_skip_index}` (true on `--ccc-skip-index`, false otherwise). `{pipeline_mode}` is not a flag: it is true only when the forger invokes setup as one step of a pipeline and passes it, and false otherwise, including every direct `/skf-setup` run. Step 1's detector rejects a `{require_tier}` that names no tier. When `{orphan_action}` is non-null and neither `keep` nor `remove`, halt with phase `on-activation:orphan-action-invalid`, no `path`, and reason `Setup cannot proceed: --orphan-action takes keep or remove, not <message>. Re-run with --orphan-action=keep or --orphan-action=remove.`, where `<message>` is the value as given, or `an empty value` when there is none, passed as the halt contract says.
 
-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:
+2. **Check for the config.** If `{project-root}/_bmad/skf/config.yaml` does not exist, halt with phase `on-activation:config-missing`, `path` `{project-root}/_bmad/skf/config.yaml`, and reason `Setup cannot proceed: the SKF config file was not found. SKF is not installed in this project: from the project root, run npx bmad-module-skill-forge install (or npx bmad-method install and add SKF), then re-run /skf-setup.`
 
-   "**Setup cannot proceed: `uv` is not installed.** SKF helpers depend on `uv` to auto-resolve their Python dependencies. Install it from <https://docs.astral.sh/uv/getting-started/installation/> and re-run `/skf-setup`."
+3. **Probe `uv` runtime.** Run `uv --version`. If `uv` is missing, halt with phase `on-activation:uv-missing`, no `path`, and reason `Setup cannot proceed: uv is not installed. Install it from https://docs.astral.sh/uv/getting-started/installation/ and re-run /skf-setup.`
 
-3. **Load config** from `{project-root}/_bmad/skf/config.yaml` and resolve `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`. Halt with phase `on-activation:config-missing` if the file does not exist, or `on-activation:config-malformed` if the YAML is invalid, with the matching human diagnostic.
+4. **Load config and preferences.** `<preflight>` is `skf-preflight.py`, at its installed path, else its dev path (neither: halt with phase `on-activation:helper-missing`, `path` the installed one, reason `Setup cannot proceed: skf-preflight.py was not found. Reinstall SKF, then re-run /skf-setup.`). Run `uv run "<preflight>" "{project-root}" --allow-missing-sidecar`, which parses config.yaml and `preferences.yaml` into one JSON object:
 
-4. **Reconcile `{headless_mode}`** with `preferences.yaml`: OR the parsed flag with `headless_mode: true` from the YAML.
+   - `status` `ok`: bind `{project_name}`, `{user_name}`, `{communication_language}` and `{document_output_language}` from `config`, each folder from its absolute path (`{output_folder}`, `{skills_output_folder}`, `{forge_data_folder}` and `{sidecar_path}` from `config.<name>_resolved`), and `{tier_override}` from `sidecar.preferences.tier_override` (null when absent). With `sidecar.preferences_error`, go on with the defaults and, unless `{quiet_mode}` is true, display that error in one line.
+   - `code` `CONFIG_MISSING`: the item 2 halt. Any other `hard-halt`, or no JSON `status`: halt with phase `on-activation:config-malformed`, `path` `{project-root}/_bmad/skf/config.yaml`, and reason `Setup cannot proceed: <message>`: its `error` without the leading `Cannot initialize. ` (else the first line the call printed), passed as the halt contract says, never preflight's whole JSON.
 
-5. **Resolve workflow customization.** Run:
+5. **Reconcile `{headless_mode}`**: OR it with `derived.headless_mode` (`headless_mode: true` in `preferences.yaml`). Then, if `{headless_mode}` is true, set `{quiet_mode}` to true.
+
+6. **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), 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.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-setup.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. Bind `{customization_resolver_unavailable}` ← that reason (null when the resolver ran), which `references/report.md` and every later halt hand to the emitter; print the warning only when `{quiet_mode}` is false.
 
-   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.
+   Apply the resolved values, with no narration of your own when `{quiet_mode}` is true: run each `workflow.activation_steps_prepend` entry now; treat each `workflow.persistent_facts` entry as standing context (a `file:` entry loads its file or glob contents); bind `{onCompleteCommand}` ← `workflow.on_complete` (empty: no hook) for `references/report.md` §5; then run each `workflow.activation_steps_append` entry, before the first stage.
 
-6. Execute `references/detect-and-tier.md`.
+7. Execute `references/detect-and-tier.md`.

package/src/skf-setup/customize.toml

@@ -1,8 +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})
+# Team overrides:     {project-root}/_bmad/custom/skf-setup.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-setup.user.toml
 
 [workflow]
 
@@ -10,9 +10,12 @@
 #   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
 #   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
 
-# Steps to run before the standard activation (uv probe, config load).
-# Overrides append. Use for org-wide pre-flight checks (auth, network,
-# compliance) that must precede any forge setup work.
+# Steps run at activation after flag parsing, the config check, the uv
+# probe and the config load (SKILL.md On Activation items 1-5), and
+# before tool detection (step 1). Overrides append. Use for org-wide
+# pre-flight checks (auth, network, compliance) that must precede any
+# forge setup work. A prepend step cannot install uv or create
+# config.yaml: those halts fire before it runs.
 
 activation_steps_prepend = []
 
@@ -34,10 +37,11 @@ activation_steps_append = []
 
 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.
+# An instruction the agent carries out (not a shell command run with
+# --result-path, as in most other SKF workflows) once the forge is fully
+# configured: after the status report (step 4), before chaining to the
+# shared health check, and never on a required-tier miss. Override wins. Use
+# for a post-setup action an org wants, such as notifying an onboarding
+# channel. Empty string = no terminal hook.
 
 on_complete = ""

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

@@ -2,125 +2,112 @@
 nextStepFile: 'report.md'
 # `{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.
+# actually invokes.
 qmdClassifyProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-qmd-classify-collections.py'
   - '{project-root}/src/shared/scripts/skf-qmd-classify-collections.py'
 forgeTierRwProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
   - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
+# `{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 orphan-removal prompt and the headless-resolution log message render in the user's language. -->
+<!-- Config: communicate in {communication_language}. The orphan-removal prompt and the `--orphan-action` auto-decision message (interactive runs only) render in the user's language. -->
 
 # Step 3: QMD + CCC Registry Hygiene
 
 ## STEP GOAL:
 
-When the detected tier is Deep, classify live QMD collections against the `qmd_collections` registry and prompt the user before removing orphans. Whenever ccc is available (Forge+ or Deep), prune `ccc_index_registry` entries whose source paths no longer exist. All set-arithmetic and YAML mutation goes through scripts (`{qmdClassifyHelper}` and `{forgeTierRwHelper}`); the workflow only orchestrates external CLI calls (`qmd collection list`, `qmd collection remove`) and the user-prompt branch.
-
-For Quick and Forge tiers, skip silently and proceed (QMD is not available; ccc registry cleanup only runs when ccc is available regardless of tier).
+Reconcile the `qmd_collections` registry with the live QMD collections, and prune `ccc_index_registry` entries whose source paths no longer exist. Classification, removal and every registry edit go through `{qmdClassifyHelper}` and `{forgeTierRwHelper}`, which stage their results in the run folder for step 4; this step runs them and makes the orphan-removal decision.
 
 ## Rules
 
-- Focus only on registry hygiene — no new collection creation (that belongs to create-skill)
-- Never reimplement the forge-namespace suffix filter in prose — the classifier owns it
-- Never silently delete collections — always prompt before `qmd collection remove`
-- Headless runs must auto-resolve the orphan prompt to the documented default (Keep)
-- Do not fail the workflow if hygiene encounters errors
+- Never reimplement the forge-namespace suffix filter or the path check in prose: the classifier owns them
+- Run `qmd collection remove`, through the classifier's `remove-orphans`, only on the interactive **[R]** or an explicit `--orphan-action=remove`: that flag is the consent, and `{orphan_auto_resolution}` records the decision, so the envelope's `warnings` name each collection the removal deleted
+- 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 a section needs a helper whose probe order has no existing path, halt (an install fault, not a hygiene error) with phase `step 3:helper-missing`, `path` set to that array's first entry, and reason `Setup cannot proceed: <script file name> 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
+- Do not fail the workflow if hygiene encounters errors; a missing helper is not a hygiene error
 
 ## MANDATORY SEQUENCE
 
 ### 1. Check Tier
 
-Read `{calculated_tier}` and `{ccc}` from context (set by step 1).
-
-Default `{orphan_auto_resolution}` to null at the top of this step; only the non-interactive branch in section 3 overrides it.
-
-**If `{calculated_tier}` is Quick or Forge AND `{ccc}` is false:** No registry hygiene needed. Set `{hygiene_result: "skipped", hygiene_healthy: 0, hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0, hygiene_stale_cleaned: 0, ccc_registry_stale_cleaned: 0, ccc_registry_stale_removed_paths: []}`. Proceed directly to section 5 (Auto-Proceed) — no output, no messaging.
-
-**If `{calculated_tier}` is Quick or Forge AND `{ccc}` is true:** No QMD work, but ccc registry needs pruning. Set QMD-related flags to defaults (`hygiene_result: "skipped"`, all hygiene_* counts = 0). Skip directly to section 4 (Stale Registry Cleanup), running it with the ccc-prune flag only.
-
-**If `{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.
+Set `{orphan_auto_resolution}` to null. When `{require_tier_satisfied}` (from step 1) is `false`, go to section 5 with no output: a run that ends `tier_failure` runs no hygiene, so it removes no collection and prunes no registry entry, and step 4 reports none. Otherwise the QMD sections (2 and 3) run only when `{calculated_tier}` is Deep, and section 4 runs when `{calculated_tier}` is Deep or `{ccc}` is true. Go to section 2 at Deep tier, else to section 4 when `{ccc}` is true, else to section 5 with no output.
 
 ### 2. Classify Live QMD Collections vs Registry
 
-Run the classifier — it owns the `qmd collection list` invocation and stdout parsing. Invoke via `uv run`:
-
 ```bash
-uv run {qmdClassifyHelper} \
-    --registry-from-yaml "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"
+uv run {qmdClassifyHelper} classify \
+    --registry-from-yaml "{sidecar_path}/forge-tier.yaml" \
+    --project-root "{project-root}" \
+    > "{run_dir}/qmd-classify.json" && cat "{run_dir}/qmd-classify.json"
 ```
 
-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.
+**If the script exits non-zero** (qmd is not running), go to section 4: step 4 reports QMD hygiene as skipped.
 
-**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).
+Otherwise bind `{orphaned_collections}` ← `orphaned` and `{orphan_paths}` ← `orphaned_paths`.
 
-**Parse the JSON output and set context flags:**
-
-- `{hygiene_healthy}` ← `len(healthy)`
-- `{orphaned_collections}` ← `orphaned` (the list — used in section 3)
-- `{stale_collections}` ← `stale` (the list — used in section 4)
-- `{live_collections}` ← comma-join of `live_names` (used in §4's clean-stale invocation; the script owns the raw set, the prompt only forwards it)
-- `{foreign_filtered_count}` ← `foreign_filtered_count`
+### 3. Handle Orphaned Collections
 
-Set `{hygiene_result: "completed"}`.
+**If `{orphaned_collections}` is empty:** go to section 4.
 
-### 3. Handle Orphaned Collections
+**Non-interactive resolution.** Resolve the gate without prompting in the first case that applies:
 
-**If `{orphaned_collections}` is empty:** Set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: 0}` and skip to section 4.
+- `{orphan_action}` is non-null (activation lets through only `keep` or `remove`) → act on that value, with `source: "orphan-action-flag"`
+- `{quiet_mode}` is true → the default **Keep**, with `source: "headless-default"` when `{headless_mode}` is true and `source: "quiet-default"` otherwise (a `--quiet` run)
 
-**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.)
+Set `{orphan_auto_resolution: {action: <keep|remove>, source: <as above>}}`: step 4 adds the count and, after a removal, the collections removed and not removed, so the envelope's `warnings` audit a decision nobody confirmed. On keep, unless `{quiet_mode}` is true, display `"Auto-decision (--orphan-action=keep): kept {count} orphaned forge collection(s)"`, where `{count}` is the number of names in `{orphaned_collections}`, then go to section 4. On remove, run the removal below, still with no prompt.
 
-**If `{headless_mode}` is false**, display to the user:
+**GATE [default: K]**: reached only when none of the cases above applies, so `{orphan_action}` is null and `{quiet_mode}` is false. Display to the user:
 
-"**QMD Hygiene: Found {count} orphaned collection(s) not tracked in the forge registry:**
+"**QMD Hygiene: Found {count} orphaned collection(s) in this project that its forge registry does not list:**
 
-{list orphaned collection names}
+{each name in `{orphaned_collections}`, with its path from `{orphan_paths}`}
 
-These collections exist in QMD but are not managed by any skill workflow. They may be from a previous auto-index run or manual creation.
+QMD indexes them from folders inside this project, but no skill workflow recorded them: a run may have stopped before it registered one, or one was added by hand.
 
 **[R]emove** orphaned collections — clean up QMD
 **[K]eep** orphaned collections — leave them as-is (default)"
 
-**If user selects R (Remove):** For each name in `{orphaned_collections}`:
+On the user's **[K]**, go to section 4.
+
+**On remove** (the user's **[R]**, or the non-interactive remove):
 
 ```bash
-qmd collection remove <name>
+uv run {qmdClassifyHelper} remove-orphans \
+    --classification-from "{run_dir}/qmd-classify.json" \
+    --project-root "{project-root}" \
+    > "{run_dir}/qmd-remove.json" && cat "{run_dir}/qmd-remove.json"
 ```
 
-Track the count of successful removals as `{hygiene_orphaned_removed}`. Set `{hygiene_orphaned_kept: 0}`.
-
-**If user selects K (Keep) or no orphans:** Set `{hygiene_orphaned_removed: 0, hygiene_orphaned_kept: len(orphaned_collections)}`.
+It reads each orphan's path again just before removing it, removes only a collection that still lies inside this project, and lists the names under `removed` and `failed` (each failure's reason under `errors`). After a non-interactive remove, unless `{quiet_mode}` is true, display `"Auto-decision (--orphan-action=remove): removed {removed, comma-separated}"`, followed by `"; could not remove: {failed, comma-separated}"` when `failed` is non-empty.
 
 ### 4. Stale Registry Cleanup
 
-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.
+Pass `--prune-missing-ccc-paths` when `{ccc}` is true, and leave it out otherwise:
 
 ```bash
 uv run {forgeTierRwHelper} clean-stale \
-    --target "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml" \
-    [--qmd-live-names "{live_collections}"]  \
-    [--prune-missing-ccc-paths]
+    --target "{sidecar_path}/forge-tier.yaml" \
+    --qmd-live-from "{run_dir}/qmd-classify.json" \
+    [--prune-missing-ccc-paths] \
+    > "{run_dir}/clean-stale.json" && cat "{run_dir}/clean-stale.json"
 ```
 
-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:**
+The script removes the `qmd_collections` entries no live collection matches, reading the live names from section 2's output; with no such output (below Deep tier, or a classifier that failed) it leaves `qmd_collections` alone.
 
-- `{hygiene_stale_cleaned}` ← `len(qmd_removed)`
-- `{ccc_registry_stale_cleaned}` ← `len(ccc_removed)`
-- `{ccc_registry_stale_removed_paths}` ← `ccc_removed` (the list — step 4 folds individual paths into envelope warnings)
+**If the script exits non-zero:** the registry stays as it was. Unless `{quiet_mode}` is true, display one line: "Registry cleanup skipped: {message}.", where `{message}` is the `message` of the stderr JSON `{"status":"error","message":...}`. Then continue to section 5: hygiene errors never fail the workflow.
 
-If `{hygiene_stale_cleaned}` > 0, display: "**Cleaned {hygiene_stale_cleaned} stale QMD registry entry/entries** (collection no longer exists in QMD)."
+**Otherwise**, when `qmd_removed` is non-empty and `{quiet_mode}` is false, display: "**Cleaned {n} stale QMD registry entry/entries** (collection no longer exists in QMD).", where `{n}` is the number of names in `qmd_removed`.
 
-(The script already logs each ccc removal as a WARNING line; no additional display needed.)
+Removed ccc registry paths are not displayed here: the step 4 report's CCC Registry line counts them, and the envelope's `warnings` lists each one.
 
 ### 5. Auto-Proceed
 
-After hygiene completes (or is skipped for non-Deep tiers without ccc), display "**Proceeding to forge status report...**", then load `{nextStepFile}`, read it fully, and execute it.
+Load `{nextStepFile}`, read it fully, and execute it.