bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/skf-audit-skill/{steps-c/step-06-report.md → references/report.md}

@@ -1,8 +1,10 @@
 ---
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
-nextStepFile: './step-07-health-check.md'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Drift report prose in {document_output_language}. -->
+
 # Step 6: Generate Report
 
 ## STEP GOAL:
@@ -18,8 +20,6 @@ Finalize the drift report by completing the Audit Summary with calculated metric
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Complete Audit Summary
 
 Update the ## Audit Summary section at the top of {outputFile} with final calculated values:
@@ -77,10 +77,10 @@ Append to {outputFile}:
 {IF any CRITICAL or HIGH findings:}
 **Recommended:** Run `[US] Update Skill` workflow to apply priority remediations automatically.
 
-{IF `audit_ref != baseline_ref` (source version bump detected in step-01 §5b):}
-**Version preservation (non-destructive).** `update-skill` preserves the prior version at `{skill_group}/{baseline_version}/` unchanged and writes the new skill to `{skill_group}/{audit_version}/` (see `skf-update-skill/steps-c/step-04-merge.md` §6b, which creates the new version directory and leaves the previous one on disk). The `active` symlink at `{skill_group}/active` repoints to the new version (see `skf-update-skill/steps-c/step-06-write.md` §5b). On the next export, the prior version's export-manifest entry transitions to `status: archived` — files retained for rollback (see `skf-export-skill/steps-c/step-04-update-context.md`). Do **not** recommend `skf-drop-skill` + `skf-create-skill` for a version bump — that destroys the prior version's artifacts.
+{IF `audit_ref != baseline_ref` (source version bump detected in step 1 §5b):}
+**Version preservation (non-destructive).** `update-skill` preserves the prior version at `{skill_group}/{baseline_version}/` unchanged and writes the new skill to `{skill_group}/{audit_version}/` (see `skf-update-skill/references/merge.md` §6b, which creates the new version directory and leaves the previous one on disk). The `active` symlink at `{skill_group}/active` repoints to the new version (see `skf-update-skill/references/write.md` §5b). On the next export, the prior version's export-manifest entry transitions to `status: archived` — files retained for rollback (see `skf-export-skill/references/update-context.md`). Do **not** recommend `skf-drop-skill` + `skf-create-skill` for a version bump — that destroys the prior version's artifacts.
 
-**Surface new entry points for the brief gate.** If the audit observed new top-level modules, renamed package trees, or new public entry points (new `__init__.py`, `index.ts`, `lib.rs`, or equivalent) that were not in the brief's original scope, call them out here. `update-skill` step-02 §1b detects new candidate files via heuristic and prompts `[P]romote` / `[S]kip` / `[U]pdate-brief`; surfacing them in advance makes that gate faster to resolve, or lets the user refine scope via `skf-brief-skill` before running update-skill.
+**Surface new entry points for the brief gate.** If the audit observed new top-level modules, renamed package trees, or new public entry points (new `__init__.py`, `index.ts`, `lib.rs`, or equivalent) that were not in the brief's original scope, call them out here. `update-skill` step 2 §1b detects new candidate files via heuristic and prompts `[P]romote` / `[S]kip` / `[U]pdate-brief`; surfacing them in advance makes that gate faster to resolve, or lets the user refine scope via `skf-brief-skill` before running update-skill.
 
 {IF only MEDIUM or LOW findings:}
 **Optional:** Minor drift detected. Manual updates sufficient, or run `[US] Update Skill` for automated remediation.
@@ -120,7 +120,7 @@ Append to {outputFile}:
 ### 4. Update Report Frontmatter
 
 Update {outputFile} frontmatter:
-- Append `'step-06-report'` to `stepsCompleted`
+- Append `'report'` to `stepsCompleted`
 - Set `drift_score` to final calculated score
 - Set `nextWorkflow` to `'update-skill'` if CRITICAL or HIGH findings, otherwise leave empty
 
@@ -170,6 +170,24 @@ Update {outputFile} frontmatter:
 
 Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_version}/audit-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the drift report path in `outputs`; include `drift_count` and `severity` (CLEAN/MINOR/SIGNIFICANT/CRITICAL) in `summary`.
 
+**Stdout envelope (headless only).** When `{headless_mode}` is true, emit a single-line JSON envelope to **stdout** immediately after the on-disk result contract is written, so chaining workflows can consume `drift_score`, `report_path`, and `next_workflow` from a captured stdout line without polling the filesystem. The shape matches the "Result Contract (Headless)" section in SKILL.md verbatim:
+
+```
+SKF_AUDIT_RESULT_JSON: {"status":"success","skill_name":"{skill_name}","drift_score":"{CLEAN|MINOR|SIGNIFICANT|CRITICAL}","report_path":"{outputFile}","next_workflow":"{update-skill|null}","audit_ref":"{audit_ref}","exit_code":0,"halt_reason":null}
+```
+
+Field rules: `next_workflow` is `"update-skill"` when CRITICAL or HIGH findings exist (matches the frontmatter `nextWorkflow` set in §4), otherwise `null`. `audit_ref` carries the resolved value from step 1 §5b (`baseline_ref` when no upstream drift was detected, `latest_tag` or `remote_head` when the operator chose `[C] Checkout-and-audit-against-latest`).
+
+**HALT envelope mirror (headless only).** For every HARD HALT raised in this workflow (skill-not-found at init.md §1, forge-tier missing at §2, source-dir missing at §5, write-failed at §6, user-cancelled at any `[X]` selection), emit the same envelope shape on **stderr** with `status: "error"`, `drift_score: null` (or last known value if classification ran), `report_path: null` if the report write failed, `exit_code` matching the Exit Codes table, and `halt_reason` set to the failure class from the table (`"skill-not-found"`, `"forge-tier-missing"`, `"source-dir-missing"`, `"write-failed"`, `"user-cancelled"`). This is the only signal a wrapping pipeline receives on failure — log it before exiting.
+
+**Post-audit hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it as:
+
+```bash
+{onCompleteCommand} --result-path={result_json_path}
+```
+
+where `{result_json_path}` is the per-run record path written above (`{forge_version}/audit-skill-result-{YYYYMMDD-HHmmss}.json`). Log success/failure to `workflow_warnings[]` — never fail the workflow on a hook error. The hook runs after the result contract is finalized so notifiers, ticket-tracker integrations, or downstream pipelines see a complete record. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
+
 ### 6. Chain to Health Check
 
 ONLY WHEN the report has been written, presented, and the result contract saved will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the user-facing summary reads as final.

package/src/skf-audit-skill/{steps-c/step-04-semantic-diff.md → references/semantic-diff.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-05-severity-classify.md'
+nextStepFile: 'severity-classify.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 4: Semantic Diff
 
 ## STEP GOAL:
@@ -18,8 +20,6 @@ Compare QMD knowledge context between the original skill creation and current st
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Check Forge Tier
 
 **IF forge tier is Quick, Forge, or Forge+:**
@@ -34,7 +34,7 @@ Append to {outputFile}:
 Semantic analysis compares QMD knowledge context for meaning-level changes that structural diff cannot detect. To enable semantic diff, run setup with QMD available to unlock Deep tier.
 ```
 
-Update frontmatter: append `'step-04-semantic-diff'` to `stepsCompleted`
+Update frontmatter: append `'semantic-diff'` to `stepsCompleted`
 
 "**Semantic diff skipped (requires Deep tier). Proceeding to severity classification...**"
 
@@ -55,7 +55,7 @@ Launch a subprocess (Pattern 3 — data operations) that:
      - Fall through to the **direct-content fallback** below instead of skipping outright.
    - **Registry entry present and populated.** Use the `name` field from the registry entry as the collection to query. Proceed to bullet 2.
 
-   **Direct-content fallback** (used when the collection is registered but empty): load `SKILL.md` and `references/*.md` from the audited skill, then spot-check each documented export against the current source tree under `{source_root}` using the Deep-tier AST tooling this step already requires (ast_bridge; see step-02 §1 "Deep tier"). This fallback is reachable only from Deep tier — §1 short-circuits Quick/Forge/Forge+ before §2 runs, so AST tooling is guaranteed available here. Record findings with confidence label `T1-low-fallback` rather than T2 — this is direct content inspection, not QMD-backed semantic analysis. The step's output schema is otherwise unchanged; set `qmd_collection = null` in the Semantic Drift header and annotate: "Semantic diff ran in direct-content fallback mode — QMD collection was registered but empty."
+   **Direct-content fallback** (used when the collection is registered but empty): load `SKILL.md` and `references/*.md` from the audited skill, then spot-check each documented export against the current source tree under `{source_root}` using the Deep-tier AST tooling this step already requires (ast_bridge; see step 2 §1 "Deep tier"). This fallback is reachable only from Deep tier — §1 short-circuits Quick/Forge/Forge+ before §2 runs, so AST tooling is guaranteed available here. Record findings with confidence label `T1-low-fallback` rather than T2 — this is direct content inspection, not QMD-backed semantic analysis. The step's output schema is otherwise unchanged; set `qmd_collection = null` in the Semantic Drift header and annotate: "Semantic diff ran in direct-content fallback mode — QMD collection was registered but empty."
 
 2. Queries for knowledge context around each export documented in the skill
 3. Retrieves: usage patterns, conventions, architectural context, dependency relationships
@@ -128,7 +128,7 @@ Append to {outputFile}:
 ### 5. Update Report and Auto-Proceed
 
 Update {outputFile} frontmatter:
-- Append `'step-04-semantic-diff'` to `stepsCompleted`
+- Append `'semantic-diff'` to `stepsCompleted`
 
 ### 6. Present MENU OPTIONS
 

package/src/skf-audit-skill/{steps-c/step-05-severity-classify.md → references/severity-classify.md}

@@ -1,9 +1,11 @@
 ---
-nextStepFile: './step-06-report.md'
+nextStepFile: 'report.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 severityRulesFile: 'references/severity-rules.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 5: Severity Classification
 
 ## STEP GOAL:
@@ -18,8 +20,6 @@ Grade every drift finding from Steps 03 and 04 by severity level (CRITICAL/HIGH/
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Severity Rules
 
 Launch a subprocess (Pattern 3 — data operations) that:
@@ -85,7 +85,7 @@ Apply scoring rules from {severityRulesFile}:
 
 ### 5. Compile Severity Classification Section
 
-**Rollup inherits from step-03.** If step-03 §5 collapsed ≥ 10 same-kind findings into a single rollup row (deleted source file, renamed module, entire package tree removed), carry that rollup through to the matching severity table as one row — do not re-expand it here. Keep the existing 6-column severity table shape; the rollup encodes root cause, count, and representative symbols **inline in the `Finding` cell** rather than adding new columns, so rollup and per-item rows render cleanly in one table. Changed-signature and cross-file findings remain per-row; they were not eligible for rollup in step-03 and are not eligible here.
+**Rollup inherits from step 3.** If step 3 §5 collapsed ≥ 10 same-kind findings into a single rollup row (deleted source file, renamed module, entire package tree removed), carry that rollup through to the matching severity table as one row — do not re-expand it here. Keep the existing 6-column severity table shape; the rollup encodes root cause, count, and representative symbols **inline in the `Finding` cell** rather than adding new columns, so rollup and per-item rows render cleanly in one table. Changed-signature and cross-file findings remain per-row; they were not eligible for rollup in step 3 and are not eligible here.
 
 **Rollup row form (any severity table):**
 
@@ -138,7 +138,7 @@ Append to {outputFile}:
 ### 6. Update Report and Auto-Proceed
 
 Update {outputFile} frontmatter:
-- Append `'step-05-severity-classify'` to `stepsCompleted`
+- Append `'severity-classify'` to `stepsCompleted`
 - Set `drift_score` to calculated overall score
 
 ### 7. Present MENU OPTIONS

package/src/skf-audit-skill/references/severity-rules.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Severity Classification Rules
 
 ## Severity Levels

package/src/skf-audit-skill/{steps-c/step-03-structural-diff.md → references/structural-diff.md}

@@ -1,8 +1,16 @@
 ---
-nextStepFile: './step-04-semantic-diff.md'
+nextStepFile: 'semantic-diff.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
+loadProvenanceProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-load-provenance.py'
+  - '{project-root}/src/shared/scripts/skf-load-provenance.py'
+compareFileHashesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-compare-file-hashes.py'
+  - '{project-root}/src/shared/scripts/skf-compare-file-hashes.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 3: Structural Diff
 
 ## STEP GOAL:
@@ -17,8 +25,6 @@ Compare the original provenance map extractions from create-skill against the cu
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Prepare Comparison Sets
 
 Load both datasets:
@@ -29,19 +35,19 @@ Load both datasets:
 **Current (from Step 02 extraction):**
 - Export list with names, types, signatures, file paths, line numbers
 
-**Canonicalize extractor methodology differences before matching.** The extractor used by `skf-create-skill` at baseline time and the re-extractor used by step-02 can differ in cosmetic detail (quote style, module qualification, re-export resolution). Without normalization, those cosmetic differences surface as false-positive "Changed" and "Removed" entries even when the source commit has not moved. Apply these transforms to both sets symmetrically:
+**Canonicalize extractor methodology differences before matching.** The extractor used by `skf-create-skill` at baseline time and the re-extractor used by step 2 can differ in cosmetic detail (quote style, module qualification, re-export resolution). Without normalization, those cosmetic differences surface as false-positive "Changed" and "Removed" entries even when the source commit has not moved. Apply these transforms to both sets symmetrically:
 
 - **Quote style on string defaults.** Normalize string-literal defaults in signatures to a single style — e.g., `kind: str = "Hnsw"` ↔ `kind: str = 'Hnsw'`. Pick one canonical form and apply to both sides.
 - **Module qualification of stdlib helpers.** Strip module prefixes on well-known stdlib helpers when the unqualified form is importable at the call site: `dataclasses.field(...)` → `field(...)`, `typing.Optional[...]` → `Optional[...]`, `typing.List[...]` → `List[...]`. Do not collapse user-defined namespaces.
-- **Public-API re-export resolution.** When `{source_root}/**/__init__.py` re-exports an internal symbol under a different public name (`from .internal import _Impl as Public`, or via `__all__`), resolve both sides to the public name before key-matching — otherwise a renamed re-export in the current scan shows up as "Removed `_Impl`" + "Added `Public`" instead of matching the baseline entry. Build the re-export map once per package by walking `__init__.py` files.
+- **Public-API re-export resolution.** When `{source_root}/**/__init__.py` re-exports an internal symbol under a different public name (`from .internal import _Impl as Public`, or via `__all__`), resolve both sides to the public name before key-matching — otherwise a renamed re-export in the current scan shows up as "Removed `_Impl`" + "Added `Public`" instead of matching the baseline entry. The re-export map is already in workflow context as `{reexport_map}` (produced by `skf-load-provenance.py normalize` in step 1 §4). Apply it directly without re-walking `__init__.py` files.
 
-Record the set of transforms actually applied in workflow context — step-06 surfaces them in the Provenance section so a reviewer can tell which differences the diff collapsed and which were real.
+Record the set of transforms actually applied in workflow context — step 6 surfaces them in the Provenance section so a reviewer can tell which differences the diff collapsed and which were real.
 
 Normalize both sets for comparison:
 - Match by canonicalized export name (primary key)
 - Group by file for location-aware comparison
 
-> **Longer-term fix.** The principled remedy is to persist `skf-create-skill`'s ast-grep ruleset to `{forge_version}/extraction-rules.yaml` at create time and have step-02 replay that exact ruleset. When the file is present, step-02 extraction becomes reproducible against the baseline and the canonicalization pass above becomes a no-op. Until then, normalization is the salvage remediation for provenance maps that predate extractor pinning.
+> **Longer-term fix.** The principled remedy is to persist `skf-create-skill`'s ast-grep ruleset to `{forge_version}/extraction-rules.yaml` at create time and have step 2 replay that exact ruleset. When the file is present, step 2 extraction becomes reproducible against the baseline and the canonicalization pass above becomes a no-op. Until then, normalization is the salvage remediation for provenance maps that predate extractor pinning.
 
 ### 2. Detect Added Exports
 
@@ -87,16 +93,28 @@ For each changed export, record:
 
 **Only execute if provenance-map.json contains `file_entries`.**
 
-For each entry in `file_entries`:
-1. Locate the source file at the original `source_file` path
-2. Compute current SHA-256 content hash (bare hex — `hashlib.sha256(...).hexdigest()`, `sha256sum`, and `openssl dgst` all produce this form)
-3. **Normalize the stored hash before comparison.** `skf-create-skill` writes `content_hash` with a leading algorithm-name prefix (`"sha256:879bfcc2…"`). A bare-hex hash from `hashlib` will never equal the prefixed value byte-for-byte, so without normalization every `file_entry` flags as CHANGED on every audit. Strip the algorithm prefix before comparing — accept any leading lowercase-alphanumeric prefix terminated by `:` (e.g. `sha256:`, `sha1:`, `md5:`); if no prefix is present, leave the value unchanged. The reader-side normalization is unconditionally safe — applying it to bare-hex values produced by a fixed writer is a no-op.
-4. Compare the normalized stored hash against the freshly computed hash:
-   - CHANGED: hash mismatch → record as script/asset content drift
-   - MISSING: source file no longer exists → record as removed
-   - NEW: source contains files matching script/asset patterns not in `file_entries` → record as added
+**Resolve `{compareFileHashesHelper}`** from `{compareFileHashesProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Run one deterministic comparison subprocess — it walks tracked file_entries[] AND the inverse direction (source-tree → candidate set in standard script/asset/doc directories) so the LLM does not orchestrate per-file hashing:
+
+```bash
+uv run {compareFileHashesHelper} compare {provenanceMap} {sourceRoot}
+```
+
+Parse the emitted JSON:
+
+```
+{
+  "added":   ["<rel-path>", ...],   // present on disk in tracked dirs, NOT in file_entries
+  "removed": ["<rel-path>", ...],   // in file_entries, missing on disk
+  "changed": [{"path": "...", "stored_hash": "sha256:...", "current_hash": "sha256:..."}],
+  "stats":   {"added": N, "removed": N, "changed": N, "unchanged": N}
+}
+```
+
+Hash-prefix normalization (writer-vs-reader compatibility — `skf-create-skill` writes `content_hash` with a `"sha256:"` prefix, a bare-hex hash from `hashlib` would otherwise never match) is handled inside the script. Downstream consumers read `added`/`removed`/`changed` directly with no further normalization.
 
-Append results to the Structural Drift section as "### Script/Asset Drift ({count})".
+Append the three lists into the Structural Drift section as "### Script/Asset Drift ({stats.added + stats.removed + stats.changed})".
 
 ### Stack-Specific Structural Diff
 
@@ -164,7 +182,7 @@ Append to {outputFile}:
 ### 6. Update Report and Auto-Proceed
 
 Update {outputFile} frontmatter:
-- Append `'step-03-structural-diff'` to `stepsCompleted`
+- Append `'structural-diff'` to `stepsCompleted`
 
 ### 7. Present MENU OPTIONS
 

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

@@ -13,6 +13,14 @@ A good skill brief sets a tight, cohesive boundary: one capability with 3-8 prim
 
 Brief-skill is split from create-skill so the scoping conversation runs *once*, on cheap signals (manifests, top-level exports, intent), without paying for AST extraction. Compilation is expensive; scoping decisions are cheap to revise. Keeping them in separate workflows lets a user iterate on the brief, share it for review, and re-run create-skill against the same brief whenever the upstream version moves.
 
+## 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.
+- `{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 skill scoping architect collaborating with a developer who wants to create an agent skill. You bring expertise in source code analysis, API surface identification, and skill boundary design, while the user brings their domain knowledge and specific use case. Work together as equals.
@@ -21,11 +29,9 @@ You are a skill scoping architect collaborating with a developer who wants to cr
 
 These rules apply to every step in this workflow:
 
-- Read each step file completely before taking any action
-- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
-- **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when `{extractPublicApiScript}` already returned a version, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need.
-- Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the `description`, `notes`, and other free-form fields persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies (see step-05). The two values may be the same.
+- **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when `{extractPublicApiHelper}` already returned a version, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need.
+- Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the `description`, `notes`, and other free-form fields persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies (see step 5). The two values may be the same.
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
 
 ## On Activation
@@ -35,27 +41,51 @@ These rules apply to every step in this workflow:
 
 2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
 
-3. Load, read the full file, and execute `./steps-c/step-01-gather-intent.md`.
+3. **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)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the three scalars, if the merged value is empty or absent, use the bundled default:
+
+   - `{descriptionVoiceExamplesPath}` ← `workflow.description_voice_examples_path` if non-empty, else `assets/description-voice-examples.md`
+   - `{scopeTemplatesPath}` ← `workflow.scope_templates_path` if non-empty, else `assets/scope-templates.md`
+   - `{briefSchemaPath}` ← `workflow.brief_schema_path` if non-empty, else `assets/skill-brief-schema.md`
+
+   Stash all three as workflow-context variables. Stage files reference `{descriptionVoiceExamplesPath}` / `{scopeTemplatesPath}` / `{briefSchemaPath}` 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.
+
+4. Load, read the full file, and execute `references/gather-intent.md`.
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Gather Intent | steps-c/step-01-gather-intent.md | No (interactive) |
-| 2 | Analyze Target | steps-c/step-02-analyze-target.md | Yes |
-| 3 | Scope Definition | steps-c/step-03-scope-definition.md | No (interactive) |
-| 4 | Confirm Brief | steps-c/step-04-confirm-brief.md | No (confirm) |
-| 5 | Write Brief | steps-c/step-05-write-brief.md | Yes |
-| 6 | Workflow Health Check (terminal) | steps-c/step-06-health-check.md | Yes |
+| 1 | Gather Intent | references/gather-intent.md | No (interactive) |
+| 2 | Analyze Target | references/analyze-target.md | Yes |
+| 3 | Scope Definition | references/scope-definition.md | No (interactive) |
+| 4 | Confirm Brief | references/confirm-brief.md | No (confirm) |
+| 5 | Write Brief | references/write-brief.md | Yes |
+| 6 | Workflow Health Check (terminal) | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting] |
-| **Gates** | step-01: Input Gate [use args] | step-03: Confirm Gate [C] | step-04: Confirm Gate [C] |
+| **Gates** | step 1: Input Gate [use args] | step 3: Confirm Gate [C] | step 4: Confirm Gate [C] |
 | **Outputs** | `skill-brief.yaml` at `{forge_data_folder}/{skill-name}/skill-brief.yaml`; final `SKF_BRIEF_RESULT_JSON` line on stdout when `{headless_mode}` is true |
 | **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; pre-supplied inputs consumed at the gates that would otherwise prompt; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise) |
+| **Transient-failure retry** | This workflow does **not** auto-retry network or subprocess failures. A failed `gh` fetch (analyze-target.md §1, portfolio-similarity-check.md), QMD probe, or extraction script is logged and surfaced in the final result envelope as a warning, but the workflow continues with whatever signal it has. Headless pipelines that want retry semantics should wrap the invocation at their orchestrator level (e.g. CI re-runner on non-zero exit). Rationale: brief-skill is read-mostly with one terminal write (the YAML at step 5); a partial-signal retry has more failure modes than just re-running the whole workflow, which is cheap. |
 | **Exit codes** | See "Exit Codes" below |
 
 ## Exit Codes
@@ -64,16 +94,16 @@ Every HARD HALT in this workflow exits with a stable code so headless automators
 
 | Code | Meaning              | Raised by                                                                                  |
 | ---- | -------------------- | ------------------------------------------------------------------------------------------ |
-| 0    | success              | step-06 (terminal)                                                                         |
-| 2    | input-missing / input-invalid | step-01 GATE — required headless arg absent (`target_repo`, `skill_name`, or `doc_urls` when `source_type=docs-only`) → `input-missing`; enum violation, malformed semver, non-kebab `skill_name`, or step-05 brief-context schema validation failure → `input-invalid` |
-| 3    | resolution-failure   | step-01 §1 (`forge-tier.yaml` missing); step-02 §1 (target inaccessible / `gh auth` fails) |
-| 4    | write-failure        | step-01 §1 pre-flight write probe (data folder unwritable: read-only mount, disk full, permissions denied); step-05 §4 (write to `{forge_data_folder}/{skill-name}/skill-brief.yaml` failed) |
-| 5    | overwrite-cancelled  | step-05 §2 (existing brief, `force` not supplied)                                          |
-| 6    | user-cancelled       | any interactive menu in step-01/03/04 (user selected `[X]` Cancel and exit)                |
+| 0    | success              | step 6 (terminal)                                                                         |
+| 2    | input-missing / input-invalid | step 1 GATE — required headless arg absent (`target_repo`, `skill_name`, or `doc_urls` when `source_type=docs-only`) → `input-missing`; enum violation, malformed semver, non-kebab `skill_name`, or step 5 brief-context schema validation failure → `input-invalid` |
+| 3    | resolution-failure   | step 1 §1 (`forge-tier.yaml` missing); step 2 §1 (target inaccessible / `gh auth` fails) |
+| 4    | write-failure        | step 1 §1 pre-flight write probe (data folder unwritable: read-only mount, disk full, permissions denied); step 5 §4 (write to `{forge_data_folder}/{skill-name}/skill-brief.yaml` failed) |
+| 5    | overwrite-cancelled  | step 5 §2 (existing brief, `force` not supplied)                                          |
+| 6    | user-cancelled       | any interactive menu in step 1/03/04 (user selected `[X]` Cancel and exit)                |
 
 ## Result Contract (Headless)
 
-When `{headless_mode}` is true, step-05 emits a single-line JSON envelope on **stdout** before chaining to step-06, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+When `{headless_mode}` is true, step 5 emits a single-line JSON envelope on **stdout** before chaining to step 6, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
 
 ```
 SKF_BRIEF_RESULT_JSON: {"status":"success|error","brief_path":"…|null","skill_name":"…","version":"…|null","language":"…|null","scope_type":"…|null","exit_code":0,"halt_reason":null}

package/src/skf-brief-skill/assets/description-voice-examples.md

@@ -1,6 +1,6 @@
 # Description Voice Examples
 
-Loaded by step-01 §7b only. The five examples below show the *range* of acceptable voices for the `description` field — they vary in lead, structure, and trigger phrasing on purpose. The point is to anchor the LLM to "two facts must come through (what the skill is, when to use it); everything else is voice — do not template-stamp."
+Loaded by step 1 §7b only. The five examples below show the *range* of acceptable voices for the `description` field — they vary in lead, structure, and trigger phrasing on purpose. The point is to anchor the LLM to "two facts must come through (what the skill is, when to use it); everything else is voice — do not template-stamp."
 
 ## Examples
 

package/src/skf-brief-skill/assets/skill-brief-schema.md

@@ -46,7 +46,7 @@ If the source is a remote GitHub repo, use `gh api repos/{owner}/{repo}/contents
 
 If detection succeeds, use the detected version. If it fails or returns a non-semver value, fall back to `"1.0.0"`.
 
-The create-skill workflow (step-03-extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
+The create-skill workflow (extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
 
 **Target version override:** When `target_version` is present in the brief, it takes precedence over auto-detection. Auto-detection still runs for informational purposes (displayed as "Detected version" alongside the user-specified "Target version"), but the `target_version` value is used as the brief's `version` field. This is particularly useful for docs-only skills (where no package manifest exists) and when the user wants to compile a skill for a specific older version.
 
@@ -67,6 +67,14 @@ scope:
   #   - "code/core/src/manager-api/**"
   #   - "code/core/src/preview-api/**"
   notes: "Optional notes about scope decisions"
+  # Optional: authoring-time scope-type rationale (written once by brief-skill 2c)
+  # rationale:
+  #   recommended: full-library
+  #   chosen: public-api
+  #   accepted_recommendation: false
+  #   heuristic: narrow-public-api
+  #   reason: "user overrode full-library->public-api: only documented API ships"
+  #   recorded: "2026-05-18"
   # Optional: amendment log for scope decisions made during create-skill §2a,
   # update-skill §1b (auth-doc), and update-skill §1c (scope-expansion).
   # amendments:
@@ -94,6 +102,28 @@ scope:
   #   - "**/*.stories.*"
 ```
 
+### Scope Rationale (Optional)
+
+`scope.rationale` is a single optional object recording **why the scope type was chosen at authoring time**. Unlike `scope.amendments[]` (an additive log that accumulates post-authoring decisions across workflow runs), `scope.rationale` is one decision, written once by `skf-brief-skill` step 03 §2c and revised in place on a step-4 `[R]` re-entry. It sits structurally beside `scope.amendments`, reusing the same structured / script-readable / human-auditable ethos rather than a prose decision log.
+
+**Fields:**
+
+| Field | Type | Required | Source |
+|---|---|---|---|
+| `recommended` | string (one of the six `scope.type` values) | yes | `skf-recommend-scope-type.py` → `scope_type` |
+| `chosen` | string (one of the six) | yes | final `scope.type` |
+| `accepted_recommendation` | bool | yes | `chosen == recommended` |
+| `heuristic` | string | yes | script `matched_heuristic` |
+| `reason` | string | yes | accepted → script `rationale` verbatim; overridden → user's stated reason, or `"user overrode {recommended}->{chosen}; reason not stated"` |
+| `recorded` | string (ISO date `YYYY-MM-DD`) | yes | current date — mirrors `amendments[].date` |
+
+**Who reads `scope.rationale`:**
+
+- Humans reviewing the brief — it records why the boundary was drawn the way it was.
+- `skf-update-skill` Update intent MAY later surface conflicts against it (e.g., a scope change that contradicts the original authoring decision). **Not implemented now — deferred.** The field is forward-compatible; the reader is wired later.
+
+**Backward compatibility:** `scope.rationale` is optional. Briefs without this field validate unchanged — treat missing as absent (null). Mirrors the `scope.amendments` backward-compat rule.
+
 ### Scope Amendments (Optional)
 
 `scope.amendments[]` is an additive, optional audit log of scope decisions made by workflows after the brief was first authored. Two writer paths exist today:
@@ -171,7 +201,7 @@ scope:
 
 ## Human-Readable Presentation Format
 
-The runtime template lives in `steps-c/step-04-confirm-brief.md` §2 — that is the single source of truth for how the brief is rendered for user confirmation (brief-skill step-04 only; analyze-source batch generation does not render). If the rendering format needs to change, edit the step file. This asset documents the data contract; the step owns the presentation.
+The runtime template lives in `references/confirm-brief.md` §2 — that is the single source of truth for how the brief is rendered for user confirmation (brief-skill step 4 only; analyze-source batch generation does not render). If the rendering format needs to change, edit the step file. This asset documents the data contract; the step owns the presentation.
 
 ## Validation Rules
 

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

@@ -0,0 +1,44 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-brief-skill.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   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 brief authoring work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (house style, naming conventions, description-voice guardrails).
+# Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Skill briefs must cite an authoritative source."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/brief-style.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical asset paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default.
+
+description_voice_examples_path = ""
+scope_templates_path = ""
+brief_schema_path = ""

package/src/skf-brief-skill/{steps-c/step-02-analyze-target.md → references/analyze-target.md}

@@ -1,11 +1,19 @@
 ---
-nextStepFile: './step-03-scope-definition.md'
+nextStepFile: 'scope-definition.md'
 versionResolutionFile: 'references/version-resolution.md'
-extractPublicApiScript: '{project-root}/src/shared/scripts/skf-extract-public-api.py'
-detectWorkspacesScript: '{project-root}/src/shared/scripts/skf-detect-workspaces.py'
-detectLanguageScript: '{project-root}/src/shared/scripts/skf-detect-language.py'
+extractPublicApiProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extract-public-api.py'
+  - '{project-root}/src/shared/scripts/skf-extract-public-api.py'
+detectWorkspacesProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-workspaces.py'
+  - '{project-root}/src/shared/scripts/skf-detect-workspaces.py'
+detectLanguageProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
+  - '{project-root}/src/shared/scripts/skf-detect-language.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Analyze Target
 
 ## STEP GOAL:
@@ -21,8 +29,6 @@ To analyze the target repository by resolving its location, reading its structur
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Resolve Target Location
 
 **For GitHub URLs:**
@@ -58,11 +64,13 @@ Display: "**Resolving target...**"
 
 ### 1b. Detect Monorepo / Workspace Layout
 
-Delegate workspace detection to `{detectWorkspacesScript}` instead of reasoning through manifest rules in prose. Build a payload from the tree fetched in §1 plus the small set of root manifests the detector needs, then invoke the script:
+**Resolve `{detectWorkspacesHelper}`** from `{detectWorkspacesProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Delegate workspace detection to `{detectWorkspacesHelper}` instead of reasoning through manifest rules in prose. Build a payload from the tree fetched in §1 plus the small set of root manifests the detector needs, then invoke the script:
 
 ```bash
 echo '{"tree": [<flat list of repo-relative file paths>], "manifests": {"package.json": "<raw text>", "Cargo.toml": "<raw text>", "pnpm-workspace.yaml": "<raw text>", "lerna.json": "<raw text>"}}' | \
-  uv run {detectWorkspacesScript}
+  uv run {detectWorkspacesHelper}
 ```
 
 - **`tree`** — pass the flat list of repo-relative file paths already fetched in §1 (for GitHub: the `path` values from the `gh api .../git/trees/HEAD?recursive=1` response; for local: the equivalent listing).
@@ -79,7 +87,7 @@ This looks like a monorepo ({manifest_kind}) with these workspaces:
   1. {workspaces[0].name} ({workspaces[0].path})
   2. {workspaces[1].name} ({workspaces[1].path})
   ...
-Which one should the skill cover? Pick a number, type 'all' to scope at the repo root, or 'list' to keep listing more.
+Which one should the skill cover? Pick a number, or type 'all' to scope at the repo root.
 ```
 
 Interactive: wait for the user choice. On a numbered choice, store `monorepo_workspace: {path}` and rebase §2-§4b against that path. On `'all'`, leave `monorepo_workspace` unset and proceed at the repo root with a note in the analysis summary that scope is unfiltered.
@@ -104,10 +112,12 @@ List the top-level directory structure:
 
 ### 3. Detect Primary Language
 
-Delegate the rule walk to `{detectLanguageScript}` instead of evaluating manifest presence and extension frequency in prose:
+**Resolve `{detectLanguageHelper}`** from `{detectLanguageProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Delegate the rule walk to `{detectLanguageHelper}` instead of evaluating manifest presence and extension frequency in prose:
 
 ```bash
-echo '{"tree": [<flat list of repo-relative file paths from §1>]}' | uv run {detectLanguageScript}
+echo '{"tree": [<flat list of repo-relative file paths from §1>]}' | uv run {detectLanguageHelper}
 ```
 
 The script returns `{language, confidence, detection_source, fallback_to_extension_frequency}` after walking the documented rule table (manifest presence first — package.json with tsconfig.json disambiguation, Cargo.toml, pyproject.toml/setup.py/setup.cfg, go.mod, pom.xml, build.gradle.kts, build.gradle Groovy with Java/Kotlin disambiguation, *.csproj/*.sln, Gemfile — then extension-frequency fallback over recognized source extensions). Use the returned values directly:
@@ -120,7 +130,9 @@ If `confidence` is `low` (or `unknown` is returned for `language`): flag for use
 
 ### 4. List Top-Level Modules and Exports
 
-Identify the public API surface. **Delegate the parsing to `{extractPublicApiScript}` whenever the detected language is supported** — the script is the single source of truth for manifest parsing, export discovery, and version detection across the whole SKF pipeline. Hand-rolling these in prose creates drift seams the LLM cannot fully close.
+**Resolve `{extractPublicApiHelper}`** from `{extractPublicApiProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Identify the public API surface. **Delegate the parsing to `{extractPublicApiHelper}` whenever the detected language is supported** — the script is the single source of truth for manifest parsing, export discovery, and version detection across the whole SKF pipeline. Hand-rolling these in prose creates drift seams the LLM cannot fully close.
 
 **Script-supported languages** (use the script): `js`, `ts`, `javascript`, `typescript`, `python`, `rust`, `go`, `java`, `kotlin`.
 
@@ -153,7 +165,7 @@ This section runs exactly one of §4.1 (script path) or §4.2 (fallback path) ba
 3. Invoke the script and parse its JSON stdout:
 
    ```bash
-   echo '<payload-json>' | uv run {extractPublicApiScript} --language <lang> --mode quick
+   echo '<payload-json>' | uv run {extractPublicApiHelper} --mode quick
    ```
 
    On a non-zero exit (codes 1 or 2 per the script's docstring), capture stderr, log it, and fall through to §4.2 (the prose-fallback path) — never HALT just because the script choked on an unusual manifest.
@@ -200,7 +212,7 @@ If CCC is unavailable or returns no results: skip this subsection silently.
 
 ### 4b. Detect Source Version
 
-**When the language was script-supported (§4 took the script path):** the `version` field returned by `{extractPublicApiScript}` IS the detected version — do not re-derive it and do not load `{versionResolutionFile}`. The script already implements the language-specific lookups documented in that reference, so loading the reference here only burns context.
+**When the language was script-supported (§4 took the script path):** the `version` field returned by `{extractPublicApiHelper}` IS the detected version — do not re-derive it and do not load `{versionResolutionFile}`. The script already implements the language-specific lookups documented in that reference, so loading the reference here only burns context.
 
 **When the language was not script-supported:** load `{versionResolutionFile}` and follow the prose Detection Algorithm directly (Ruby / C# / Swift / etc. fall outside the script's coverage).
 
@@ -268,5 +280,5 @@ Pause briefly for user input. If the user provides corrections or asks questions
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN the analysis is complete and the summary has been presented to the user will you load and read fully `./step-03-scope-definition.md` to begin scope definition.
+ONLY WHEN the analysis is complete and the summary has been presented to the user will you load and read fully `scope-definition.md` to begin scope definition.