bmad-module-skill-forge 1.9.0 → 2.0.1

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":}
@@ -91,6 +84,7 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   CCC Index:
   {if ccc_index_result is "fresh": up to date — semantic discovery ready}
   {if ccc_index_result is "created": indexed this run — semantic discovery ready}
+  {if ccc_index_result is "skipped": skipped (--ccc-skip-index) — run `/skf-setup` without --ccc-skip-index to build the index when you're ready}
   {if ccc_index_result is "failed": indexing failed — semantic discovery unavailable this session}
   {end if}
 
@@ -121,13 +115,17 @@ 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}
 
 {if {tier_changed} is false and {tools_added} is empty and {tools_removed} is empty and {previous_tier} is non-null:}
   {same-tier message from tier-rules.md}
+  {if preferences_yaml_created is false and (ccc_index_result is "fresh" or ccc_index_result is "none" or ccc_index_result is "skipped"): Nothing changed — your preferences were left untouched and the index was already current. You're good.}
 
-{if {tier_changed} is false and ({tools_added} or {tools_removed} is non-empty):}
+{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.
@@ -137,20 +135,14 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
 ═══════════════════════════════════════
 
 {if {headless_mode} is false:}
-  Next: try `/skf-brief-skill` to scope your first compilation target, or `/skf-quick-skill` for a fast template-driven path. Already have a skill? `/skf-audit-skill` drift-checks an existing skill against current sources.
+  Next: the fastest start is `@Ferris forge-auto <repo-or-doc-url>` — one command auto-scopes, briefs, compiles, tests at a 90% quality gate, and exports a verified skill with zero configuration. Prefer to scope by hand? `/skf-brief-skill` scopes your first compilation target, or `/skf-quick-skill` is a fast template-driven path. Already have a skill? `/skf-audit-skill` drift-checks an existing skill against current sources.
 ```
 
 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):
 
@@ -168,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 '{
@@ -203,16 +193,20 @@ echo '{
   "ccc_exclusion_warnings": {ccc_exclusion_warnings_list},
   "ccc_registry_stale_removed": {ccc_registry_stale_removed_paths_list},
   "ccc_indexing_failed_reason": {ccc_indexing_failed_reason_or_null},
+  "orphan_auto_resolution": {orphan_auto_resolution_or_null},
   "error": {error_object_or_null}
 }' | uv run {emitEnvelopeHelper} emit
 ```
 
 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.

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

@@ -1,36 +1,6 @@
-# Tier Calculation Rules
+# Tier Report Copy
 
-## Tool Detection Commands
-
-| Tool | Verification Command | What Confirms Availability |
-|------|---------------------|---------------------------|
-| ast-grep | `ast-grep --version` | Returns version string without error |
-| gh | `gh --version` | Returns version string without error |
-| qmd | `qmd status` | Returns status indicating initialized and operational |
-| ccc | Step A: `ccc --help` Step B: `ccc doctor` | Step A: exits 0 AND help output identifies the binary as cocoindex-code. Step B: daemon healthy. See `references/detect-and-tier.md` §7 for the full identity-marker procedure. |
-
-**Important:** Use verification commands, not existence checks (`which`, `command -v`). A tool must be functional, not just present on PATH. For daemon-based tools (ccc), verify both binary identity and daemon health — a binary with the right name but the wrong implementation is a false positive, not a tool.
-
-## Tier Calculation
-
-| Priority | Tier | Required Tools | Rule |
-|----------|------|---------------|------|
-| 1 (highest) | Deep | ast-grep + gh + qmd | All three core tools available and functional |
-| 2 | Forge+ | ast-grep + ccc | ast-grep AND ccc available, regardless of gh/qmd |
-| 3 | Forge | ast-grep | ast-grep available, without ccc/gh/qmd |
-| 4 (default) | Quick | None | Default when no tools are available |
-
-**Evaluation order:** Check Deep first, then Forge+, then Forge. The first match wins. This ensures Deep always takes priority when all tools are present.
-
-**Override:** If `tier_override` is set in preferences.yaml, use that value instead of calculated tier.
-
-**Edge cases:**
-- gh available but no ast-grep → Quick (gh alone doesn't unlock Forge)
-- ast-grep + gh but no qmd → Forge (qmd required for Deep)
-- ast-grep + qmd but no gh → Forge (gh required for Deep)
-- ccc available but no ast-grep → Quick (ccc alone doesn't unlock Forge+)
-- ast-grep + ccc + gh but no qmd → Forge+ (qmd required for Deep)
-- ast-grep + gh + qmd + ccc → Deep (Deep subsumes Forge+; ccc enhances transparently)
+The user-facing report strings the Step 4 report (`report.md`) consumes. Tool-detection probes and tier-calculation rules are owned by `skf-detect-tools.py` (see `references/detect-and-tier.md` §2) — this file holds only display copy, never detection or tier logic.
 
 ## Tier Capability Descriptions
 

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

@@ -1,12 +1,11 @@
 ---
 nextStepFile: 'auto-index.md'
-# Resolve `{forgeTierRwHelper}` by probing `{forgeTierRwProbeOrder}` in order
-# (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves — the script owns the canonical
-# forge-tier.yaml format AND the array-preservation contract that protects
-# qmd_collections / ccc_index_registry / staleness_threshold_hours from being
-# lost on rewrite. NEVER fall back to inline YAML emission — drift between the
-# script and a prose-rendered template will silently corrupt downstream skills.
+# `{forgeTierRwHelper}` = first existing path in `{forgeTierRwProbeOrder}`;
+# halt if neither exists. The script owns the canonical forge-tier.yaml format
+# and the array-preservation contract that protects qmd_collections /
+# ccc_index_registry / staleness_threshold_hours from being lost on rewrite.
+# Do not fall back to inline YAML emission — a prose-rendered template drifts
+# from the script and silently corrupts downstream skills.
 forgeTierRwProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
   - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
@@ -39,7 +38,7 @@ Write the detected tool availability and calculated tier to `forge-tier.yaml` (p
 
 Build the JSON payload from context flags set by step 1 and step 1b. The payload must include `tools`, `tier`, and `ccc_index`; the script handles `tier_detected_at` defaulting to "now" if absent and preserves `qmd_collections`, `ccc_index_registry`, and a user-customized `ccc_index.staleness_threshold_hours` from any existing file.
 
-Invoke via `uv run` so the script's PEP 723 PyYAML dependency resolves automatically (this is what `docs/getting-started.md`'s uv prereq exists for). Bare `python3` would fail on a fresh interpreter with `ModuleNotFoundError`.
+Invoke via `uv run`.
 
 ```bash
 echo '{
@@ -63,7 +62,7 @@ echo '{
        --target "{project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml"
 ```
 
-The script atomically writes the file via temp + fsync + rename (mirrors `skf-atomic-write.py`'s crash-safety contract) and returns a JSON response with `wrote`, `preserved_arrays.qmd_collections` count, `preserved_arrays.ccc_index_registry` count, and the resolved `tier`.
+The script atomically writes the file via temp + fsync + rename (crash-safe) and returns a JSON response with `wrote`, `preserved_arrays.qmd_collections` count, `preserved_arrays.ccc_index_registry` count, and the resolved `tier`.
 
 **Parse the response and set context flags for step 4:**
 
@@ -80,7 +79,7 @@ uv run {forgeTierRwHelper} init-prefs \
     --target "{project-root}/_bmad/_memory/forger-sidecar/preferences.yaml"
 ```
 
-The script creates the file with first-run defaults (matching the prior inline template — `tier_override: ~`, `passive_context: true`, `headless_mode: false`, `compact_greeting: false`, plus reserved-for-future-use commented fields) IF the file does not exist. When the file already exists, the script refuses to overwrite (preserves user customization) and reports `wrote: false`.
+The script creates the file with first-run defaults (`tier_override: ~`, `passive_context: true`, `headless_mode: false`, `compact_greeting: false`) if the file does not exist. When the file already exists, the script refuses to overwrite (preserves user customization) and reports `wrote: false`.
 
 **Parse the response and set context flags for step 4:**
 

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

@@ -7,7 +7,7 @@ description: Cognitive completeness verification — quality gate before export.
 
 ## Overview
 
-Verifies that a skill is complete enough to be useful to an AI agent by checking coverage of the public API surface (naive mode) or validating SKILL.md + references coherence (contextual mode). Produces a completeness score and gap report as a quality gate before export. Every finding must trace to actual code with file:line citations.
+Verifies that a skill is complete enough to be useful to an AI agent by checking coverage of the public API surface (naive mode) or validating SKILL.md + references coherence (contextual mode). Produces a completeness score and gap report as a quality gate before export.
 
 ## Conventions
 
@@ -16,7 +16,6 @@ Verifies that a skill is complete enough to be useful to an AI agent by checking
 - `{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.
-- Step files use `## STEP GOAL:` headings rather than the `## MANDATORY SEQUENCE` + `## CRITICAL STEP COMPLETION NOTE` pattern used by generate-driven SKF workflows — this skill is a validation harness with score-driven step semantics, not a chain that produces new artifacts.
 
 ## Role
 
@@ -50,7 +49,7 @@ These rules apply to every step in this workflow:
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | skill_name [required]; optional flags: `--allow-workspace-drift`, `--no-discovery` (skip §4b Discovery Testing), `--no-health-check` (skip §7 health-check dispatch), `--tier=<Quick\|Forge\|Forge+\|Deep>` (bypass forge-tier.yaml sidecar requirement), `--threshold=<N>` (override pass threshold; CLI wins over per-pipeline defaults and `workflow.default_threshold` scalar) |
+| **Inputs** | skill_name [required]; optional flags: `--allow-workspace-drift`, `--no-discovery` (skip the report step's Discovery Testing block), `--no-health-check` (skip §7 health-check dispatch), `--tier=<Quick\|Forge\|Forge+\|Deep>` (bypass forge-tier.yaml sidecar requirement), `--threshold=<N>` (override pass threshold; CLI wins over per-pipeline defaults and `workflow.default_threshold` scalar) |
 | **Gates** | step 6: Confirm Gate [C] |
 | **Outputs** | per-run `test-report-{skill_name}-{run_id}.md` with completeness score and result (PASS/FAIL); per-run `skf-test-skill-result-{run_id}.json` and `skf-test-skill-result-latest.json` written atomically under `{forge_version}/`; `evidence-report-fallback.md` written under `{forge_version}/` when threshold fallback occurs (score between 80% and target threshold) — downstream consumers (export-skill, update-skill `--from-test-report`) glob `test-report-{skill_name}-*.md` and pick newest by parsed ISO timestamp |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
@@ -63,19 +62,20 @@ Every terminal state in this workflow exits with a stable code so headless autom
 | Code | Meaning              | Raised by                                                                                  |
 | ---- | -------------------- | ------------------------------------------------------------------------------------------ |
 | 0    | success / PASS       | step 6 §6b — `testResult: 'pass'` (after the result contract is written in §4c)            |
+| 1    | error (HARD HALT)    | infrastructure / precondition HALT in step 1 or step 6 before a verdict exists — see the "Result Contract" `halt_reason` set (the hard gate uses code 2) |
 | 2    | fail / FAIL          | step 4c §3 — hard gate blocked (`halt_reason: "hard-gate-blocked"`); step 6 §6b — `testResult: 'fail'` (after the result contract is written in §4c) |
 | 3    | inconclusive         | step 6 §6b — `testResult: 'inconclusive'` (distinct from fail so orchestrators can route to manual-review queues) |
-| 4    | pass-with-drift      | step 6 §6b — `testResult: 'pass-with-drift'` (distinct from clean pass — `--allow-workspace-drift` was in effect; orchestrators MUST route to re-test-against-pinned-commit queues and refuse export; never exit 0 under drift override) |
+| 4    | pass-with-drift      | step 6 §6b — `testResult: 'pass-with-drift'` (distinct from clean pass — `--allow-workspace-drift` was in effect; re-test against the pinned commit and refuse export — exit 0 would wrongly signal a clean pass) |
 
 ## Result Contract (Headless)
 
-When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HALT the Exit Codes table above marks with a non-zero code emits the same envelope shape on **stderr** with `status: "error"` and the `halt_reason` naming the failure, so a headless orchestrator branches on the reason without grepping prose:
 
 ```
 SKF_TEST_RESULT_JSON: {"status":"success|error","skill_name":"…","verdict":"PASS|FAIL|INCONCLUSIVE|pass-with-drift","score":N,"threshold":N,"report_path":"…|null","next_workflow":"export-skill|update-skill|null","exit_code":0,"halt_reason":null,"threshold_fallback":true,"original_threshold":90}
 ```
 
-`status` is `"success"` on the terminal happy path (any of PASS / FAIL / INCONCLUSIVE / pass-with-drift — the workflow completed), `"error"` on any HARD HALT before §4c. `verdict` is the canonical result string. `next_workflow` is `"export-skill"` only when `verdict == "PASS"`; `"update-skill"` for `FAIL` or `pass-with-drift`; `null` for `INCONCLUSIVE` (manual review). `halt_reason` is `null` on the terminal path or one of the workflow-defined halt strings (`"forge-tier-missing"`, `"target-inaccessible"`, `"write-failed"`, `"step-completeness-violation"`, `"report-anchor-missing"`, `"health-check-missing"`, `"atomic-writer-missing"`, `"hard-gate-blocked"`). `exit_code` matches the table above. When threshold fallback occurred, the envelope includes `"threshold_fallback":true` and `"original_threshold":N`; these fields are omitted when no fallback occurred.
+`status` is `"success"` on the terminal happy path (PASS / FAIL / INCONCLUSIVE / pass-with-drift — the workflow completed), `"error"` on an emitted HARD HALT. `verdict` is the canonical result string (`null` on an infrastructure error halt). `next_workflow` is `"export-skill"` only when `verdict == "PASS"`; `"update-skill"` for `FAIL` or `pass-with-drift`; `null` for `INCONCLUSIVE` and error halts. `halt_reason` is `null` on the terminal path or one of the emitted strings: `"target-inaccessible"`, `"forge-tier-missing"`, `"workspace-drift"`, `"another-run-active"`, `"frontmatter-invalid"` (init HALTs), `"atomic-writer-missing"`, `"step-completeness-violation"`, `"report-anchor-missing"`, `"health-check-missing"` (report HALTs), or `"hard-gate-blocked"` (step 4c). `exit_code` is the code the Exit Codes table above assigns to the reached terminal state or HALT. Step 1 §3 frontmatter-validation now emits the `"frontmatter-invalid"` stderr envelope (see init.md §3c) and is branchable. Only the coverage/coherence analysis aborts print a diagnostic and exit non-zero **without** this envelope — they are the sole remaining outcomes outside the branchable set. When threshold fallback occurred, the envelope includes `"threshold_fallback":true` and `"original_threshold":N`; these fields are omitted when no fallback occurred.
 
 The same payload is persisted to disk by step 6 §4c (atomic write) at two locations under `{forge_version}/`:
 
@@ -115,8 +115,10 @@ The on-disk payload is the richer form: it adds `outputs[]` (report-path entries
    - `{outputFormatsPath}` ← `workflow.output_formats_path` if non-empty, else `assets/output-section-formats.md`
    - `{scoringRulesPath}` ← `workflow.scoring_rules_path` if non-empty, else `references/scoring-rules.md`
    - `{defaultThreshold}` ← `workflow.default_threshold` if non-empty/non-null, else `80`. CLI `--threshold=<N>` wins over per-pipeline defaults (from init.md §1b) which win over this scalar at the usage site in `references/score.md`.
-   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string. When empty, the post-finalization hook in `references/report.md` is a no-op.
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (the post-finalization hook in `references/report.md` is then a no-op).
 
-   Stash all five as workflow-context variables. Stage files reference `{testReportTemplatePath}` / `{outputFormatsPath}` / `{scoringRulesPath}` / `{defaultThreshold}` / `{onCompleteCommand}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies without forking the skill.
+   Stash all five as workflow-context variables that stage files reference directly — no conditional at the usage site.
+
+   **Apply the array surfaces** (not silent no-ops): run `workflow.activation_steps_prepend` in order now; treat each `workflow.persistent_facts` entry as standing context for the run (`file:`-prefixed entries load their file/glob contents as facts — the bundled default globs any `project-context.md`); then run `workflow.activation_steps_append` after activation.
 
 4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-test-skill/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-test-skill.
+# Team overrides:     _bmad/custom/skf-test-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-test-skill.user.toml (under {project-root})
 
 [workflow]
 

package/src/skf-test-skill/references/coherence-check.md

@@ -1,8 +1,9 @@
 ---
 nextStepFile: 'external-validators.md'
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
-outputFormatsFile: 'assets/output-section-formats.md'
-scoringRulesFile: 'references/scoring-rules.md'
+outputFormatsFile: '{outputFormatsPath}'
+scoringRulesFile: '{scoringRulesPath}'
+coherenceAggregationScript: 'scripts/aggregate-coherence.py'
 migrationSectionRules: 'references/migration-section-rules.md'
 scanSkillMdStructureProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-scan-skill-md-structure.py'
@@ -104,7 +105,7 @@ Scan SKILL.md for all cross-references:
 - Integration pattern references (middleware chains, plugin hooks, shared state)
 - Script/asset references (`scripts/{file}`, `assets/{file}`) in SKILL.md body
 
-Delegate to a subagent that grep/regexes SKILL.md for reference patterns and returns ONLY this JSON shape — no prose, no commentary, no markdown fences: `{"references_found": [{"line": N, "type": "file-path|skill|type-import|integration-pattern|script-asset", "target": "..."}]}`. Parent strips wrapping markdown fences (if present) before parsing. If subagent unavailable, scan in main thread.
+Delegate to a subagent that grep/regexes SKILL.md for reference patterns and returns only this JSON shape — no prose, no commentary, no markdown fences: `{"references_found": [{"line": N, "type": "file-path|skill|type-import|integration-pattern|script-asset", "target": "..."}]}`. Parent strips wrapping markdown fences (if present) before parsing. If subagent unavailable, scan in main thread.
 
 ### 4. Contextual Mode: Validate Each Reference
 
@@ -117,13 +118,13 @@ For EACH reference found, delegate to a subagent that:
    - Skill references: referenced skill exists in skills output folder
    - Integration patterns: documented pattern matches actual implementation
    - Script/asset references: verify the referenced file exists in the skill's `scripts/` or `assets/` directory
-3. Returns ONLY this JSON shape per reference — no prose, no commentary, no markdown fences: `{"reference": "...", "line": N, "target_exists": <bool>, "type_match": <bool>, "signature_match": <bool>, "issues": ["..."]}`
+3. Returns only this JSON shape per reference — no prose, no commentary, no markdown fences: `{"reference": "...", "line": N, "target_exists": <bool>, "type_match": <bool>, "signature_match": <bool>, "issues": ["..."]}`
 
 Parent strips wrapping markdown fences (if present) before parsing. If subagent unavailable, validate each reference in main thread.
 
 4. **Scripts/assets directory check:** If a `scripts/` or `assets/` directory exists alongside SKILL.md, verify that a "Scripts & Assets" section (Section 7b) is present in SKILL.md. This directory-level check applies in both modes (naive mode performs it in Section 2; contextual mode performs it here alongside per-reference validation). Flag absence as Medium severity gap per `{scoringRulesFile}`.
 
-5. **Path containment:** for every resolved reference target, compute its canonical path (`os.path.realpath`) and require that it lives inside `{skillDir}`, inside `{source_path}` (the extraction tree recorded in metadata.json), OR — for stack skills — inside `{skills_output_folder}`. The third root applies only here in contextual mode: a stack's constituent cross-references legitimately resolve to `skills/{name}/active` under `{skills_output_folder}`, which lies outside `{skillDir}`, and a stack's metadata.json records no single `source_path` to anchor them. References whose canonical path escapes all applicable roots (e.g. `../../../etc/passwd`, absolute paths to unrelated dirs, symlink redirections outside the skill, its source, or — for a stack — the skills output tree) are **High severity** findings: `coherence — reference escapes skill/source sandbox: {raw_ref} → {canonical_path}`. Canonicalization happens before the root check, so a symlink that points outside every applicable root is still caught. Do NOT validate the target's contents for escaping references — the escape itself is the finding.
+5. **Path containment:** for every resolved reference target, compute its canonical path (`os.path.realpath`) and require that it lives inside `{skillDir}`, inside `{source_path}` (the extraction tree recorded in metadata.json), OR — for stack skills — inside `{skills_output_folder}`. The third root applies only here in contextual mode: a stack's constituent cross-references legitimately resolve to `skills/{name}/active` under `{skills_output_folder}`, which lies outside `{skillDir}`, and a stack's metadata.json records no single `source_path` to anchor them. References whose canonical path escapes all applicable roots (e.g. `../../../etc/passwd`, absolute paths to unrelated dirs, symlink redirections outside the skill, its source, or — for a stack — the skills output tree) are **High severity** findings: `coherence — reference escapes skill/source sandbox: {raw_ref} → {canonical_path}`. Canonicalization happens before the root check, so a symlink that points outside every applicable root is still caught. Do not validate the target's contents for escaping references — the escape itself is the finding.
 
 ### 5. Contextual Mode: Check Integration Pattern Completeness
 
@@ -160,17 +161,20 @@ results.
 
 ### 5c. Calculate Coherence Scores
 
-**Contextual mode only.** Calculate coherence percentages using the formulas defined in `{scoringRulesFile}` — Coherence Score Aggregation section:
+**Contextual mode only.** The reference-validity ratio, the integration-completeness ratio, and their fixed 0.6 / 0.4 weighted mean are pure arithmetic — the judgment (which references are valid in §4, which patterns are complete in §5) has already happened. Do not compute these percentages by hand; they are aggregated by `{coherenceAggregationScript}` (the formulas it encodes are documented in `{scoringRulesFile}` — Coherence Score Aggregation).
 
-```
-reference_validity = (valid_references / total_references) * 100
-integration_completeness = (complete_patterns / total_patterns) * 100
-combined_coherence = (reference_validity * 0.6) + (integration_completeness * 0.4)
+Tally the counts from the §4 per-reference JSON (`valid_references` = references with `target_exists && type_match && signature_match && no issues`; `total_references` = references extracted in §3) and the §5 integration JSON (`patterns_documented`, `patterns_complete`), then invoke:
+
+```bash
+echo '{"valid_references": <V>, "total_references": <T>, "patterns_documented": <PD>, "patterns_complete": <PC>}' | uv run {coherenceAggregationScript} --stdin
 ```
 
-**Edge case:** If no integration patterns are documented (patterns_documented = 0), combined coherence equals reference validity alone. Do not divide by zero.
+The script also accepts the JSON as a positional argument or via `--json-input`. Parse its output and read:
+- `referenceValidity` — reference-validity percentage
+- `integrationCompleteness` — integration-completeness percentage (`null` when no patterns are documented)
+- `combinedCoherence` — the combined coherence percentage passed to score.md §3a as the `coherence` input
 
-These values fill the `{percentage}%` placeholders in the output template loaded in Section 6.
+The script handles both edge cases the formula requires: `patterns_documented == 0` → `combinedCoherence` equals `referenceValidity` (no divide-by-zero); `total_references == 0` → `referenceValidity` is 100.0 (no references means no broken references). These values fill the `{percentage}%` placeholders in the output template loaded in Section 6.
 
 ### 6. Append Coherence Analysis to Output
 
@@ -178,26 +182,10 @@ Load `{outputFormatsFile}` and use the appropriate Coherence Analysis section fo
 
 ### 7. Report Coherence Results
 
-**For Naive Mode:**
-"**Coherence check complete (naive mode).**
-
-Basic structural validation of **{skill_name}**:
-- {N} structural issues found
-- Coherence category not scored (weight redistributed to coverage)
-
-**Proceeding to external validation...**"
-
-**For Contextual Mode:**
-"**Coherence check complete (contextual mode).**
-
-Reference validation of **{skill_name}**:
-- References: {valid}/{total} valid ({percentage}%)
-- Integration patterns: {complete}/{total} complete ({percentage}%)
-- Combined coherence: {percentage}%
-
-**{N} issues found** — details in Coherence Analysis section.
+Report the coherence result to the user, then proceed to external validation:
 
-**Proceeding to external validation...**"
+- **Naive mode:** the count of structural issues found (the coherence category is not scored — its weight redistributes to coverage).
+- **Contextual mode:** the reference-validity ratio, the integration-completeness ratio, the combined coherence percentage, and the issue count — full details are in the Coherence Analysis section.
 
 Update stepsCompleted, then load and execute {nextStepFile}.