bmad-module-skill-forge 1.4.0 → 1.5.0

package/src/skf-analyze-source/{steps-c/step-02-scan-project.md → references/scan-project.md}

@@ -1,9 +1,12 @@
 ---
-nextStepFile: './step-03-identify-units.md'
+nextStepFile: 'identify-units.md'
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 heuristicsFile: 'references/unit-detection-heuristics.md'
+scanManifestsScript: '{project-root}/src/shared/scripts/skf-scan-manifests.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 2: Scan Project
 
 ## STEP GOAL:
@@ -14,13 +17,11 @@ To map the complete project structure by scanning directory trees, detecting ser
 
 - Focus only on structural scanning — do not classify units or map exports yet
 - Do not read source file contents beyond manifest files and entry points
-- Use subprocess Pattern 1 for scanning across many files
+- Delegate per-file scanning to subagents in parallel when many files are involved (main-thread fallback is fine)
 - Tier-aware scanning depth: Quick (file structure), Forge (+ manifest parsing), Deep (+ config analysis)
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Context
 
 Read {outputFile} frontmatter to obtain:
@@ -36,9 +37,9 @@ Load {heuristicsFile} for reference on detection signals.
 
 1. Map the top-level directory tree (2-3 levels deep)
 2. Identify workspace configuration files (pnpm-workspace.yaml, lerna.json, Cargo.toml [workspace], go.work, etc.)
-3. Find all package manifests (package.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml, build.gradle, pom.xml)
+3. Enumerate package manifests deterministically — invoke `uv run {scanManifestsScript} scan {path}` and parse the JSON envelope. The script returns `{manifests[], total_unique, monorepo, warnings?}` covering npm/python/rust/go/maven/gradle/ruby/composer/swift; record each `{path, ecosystem}` for the manifests catalog in §4 and capture `monorepo` for the boundary-signal pass in §3
 4. Locate entry point files (index.ts, main.ts, app.ts, main.go, main.rs, __init__.py, etc.)
-5. Detect service configuration (Dockerfile, docker-compose.yml, kubernetes manifests, serverless.yml)
+5. Detect service configuration (Dockerfile, docker-compose.yml, kubernetes manifests, serverless.yml) — keep this step LLM-driven; file glob + presence check is sufficient, no parsing required
 6. Return structured findings — file paths and types only, not contents
 
 **If subprocess unavailable:** Perform directory scanning in main thread using file I/O tools.
@@ -120,7 +121,7 @@ Wait for user feedback. If user identifies gaps, rescan as directed.
 
 Append the complete "## Project Scan" section to {outputFile}:
 
-Replace the placeholder `[Appended by step-02-scan-project]` with the full scan results including:
+Replace the placeholder `[Appended by scan-project]` with the full scan results including:
 - Structure overview
 - Detected boundaries table
 - Manifests catalog
@@ -130,17 +131,18 @@ Replace the placeholder `[Appended by step-02-scan-project]` with the full scan
 
 Update {outputFile} frontmatter:
 ```yaml
-stepsCompleted: [append 'step-02-scan-project' to existing array]
-lastStep: 'step-02-scan-project'
+stepsCompleted: [append 'scan-project' to existing array]
+lastStep: 'scan-project'
 ```
 
 ### 7. Present MENU OPTIONS
 
-Display: "**Select:** [C] Continue to Unit Identification"
+Display: "**Select:** [C] Continue to Unit Identification | [X] Cancel and exit"
 
 #### Menu Handling Logic:
 
 - IF C: Save scan results to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF X: HARD HALT with exit code 6 (`user-cancelled`). Emit the `SKF_ANALYZE_RESULT_JSON` envelope on stderr with `status: "error"`, `halt_reason: "user-cancelled"`, and counts/paths reflecting state at cancellation
 - IF Any other: help user, then [Redisplay Menu Options](#7-present-menu-options)
 
 #### EXECUTION RULES:

package/src/skf-analyze-source/references/unit-detection-heuristics.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Unit Detection Heuristics
 
 ## Purpose

package/src/skf-analyze-source/templates/analysis-report-template.md

@@ -18,24 +18,24 @@ nextWorkflow: ''
 
 ## Project Scan
 
-[Appended by step-02-scan-project]
+[Appended by scan-project]
 
 ## Identified Units
 
-[Appended by step-03-identify-units]
+[Appended by identify-units]
 
 ## Export Map
 
-[Appended by step-04-map-and-detect]
+[Appended by map-and-detect]
 
 ## Integration Points
 
-[Appended by step-04-map-and-detect]
+[Appended by map-and-detect]
 
 ## Recommendations
 
-[Appended by step-05-recommend]
+[Appended by recommend]
 
 ## Generation Results
 
-[Appended by step-06-generate-briefs]
+[Appended by generate-briefs]

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

@@ -9,6 +9,14 @@ description: Drift detection between skill and current source code. Use when the
 
 Detects drift between an existing skill and its current source code, producing a severity-graded drift report with AST-backed findings and actionable remediation suggestions. Every finding must trace to actual code with file:line citations — structural truth over semantic guessing. Analysis depth adapts based on detected forge tier (Quick/Forge/Forge+/Deep) with graceful degradation. Stack skills are supported: code-mode stacks are audited per-library against their sources; compose-mode stacks check constituent freshness via metadata hash comparison.
 
+## 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 auditor operating in Ferris Audit mode. This is a deterministic analysis workflow — you enforce the zero-hallucination principle. You bring AST analysis expertise and drift detection methodology, while the source code provides the ground truth.
@@ -18,11 +26,8 @@ You are a skill auditor operating in Ferris Audit mode. This is a deterministic
 These rules apply to every step in this workflow:
 
 - Never fabricate findings — all data must trace to source code with file:line citations
-- 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
 - Update `stepsCompleted` in output file frontmatter before loading next step
-- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
 - Always communicate in `{communication_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
 
@@ -30,22 +35,45 @@ These rules apply to every step in this workflow:
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Initialize & Baseline | steps-c/step-01-init.md | No (confirm) |
-| 2 | Re-Index Source | steps-c/step-02-re-index.md | Yes |
-| 3 | Structural Diff | steps-c/step-03-structural-diff.md | Yes |
-| 4 | Semantic Diff | steps-c/step-04-semantic-diff.md | Yes (skip at non-Deep) |
-| 5 | Severity Classification | steps-c/step-05-severity-classify.md | Yes |
-| 6 | Report | steps-c/step-06-report.md | Yes |
-| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+| 1 | Initialize & Baseline | references/init.md | No (confirm) |
+| 2 | Re-Index Source | references/re-index.md | Yes |
+| 3 | Structural Diff | references/structural-diff.md | Yes |
+| 4 | Semantic Diff | references/semantic-diff.md | Yes (skip at non-Deep) |
+| 5 | Severity Classification | references/severity-classify.md | Yes |
+| 6 | Report | references/report.md | Yes |
+| 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | skill_name [required] |
-| **Gates** | step-01: Confirm Gate [C] |
-| **Outputs** | drift-report-{timestamp}.md with drift_score and nextWorkflow |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Inputs** | `skill_name` [required], `skill_path` [optional override — full path to skill directory; bypasses manifest/symlink resolution], `tier_override` [optional: Quick / Forge / Forge+ / Deep — overrides detected tier], `degraded` [optional bool — pre-confirm degraded-mode opt-in when no provenance map exists], `upstream_drift_choice` [optional: C / S / X — pre-supplied answer for the upstream-drift gate at init.md §5b], `dirty_worktree_choice` [optional: T / A / F — pre-supplied answer for the dirty-worktree sub-gate at init.md §5b], `force` [optional bool — when paired with `dirty_worktree_choice=F` or used for any future destructive-action gate, signals consent to skip the confirmation] |
+| **Gates** | step 1: Manifest-vs-Symlink Gate [N] · Upstream-Drift Gate [C/S/X] · Dirty-Worktree Sub-Gate [T/A/F] · Degraded-Mode Gate [D/X] · Baseline Confirm Gate [C] |
+| **Outputs** | `drift-report-{timestamp}.md` at `{forge_version}/` with `drift_score` and `nextWorkflow` frontmatter; per-run result contract at `{forge_version}/audit-skill-result-{timestamp}.json` plus `-latest.json` copy; final `SKF_AUDIT_RESULT_JSON` line on stdout when `{headless_mode}` is true |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true; pre-supplied inputs (`upstream_drift_choice`, `dirty_worktree_choice`, `degraded`, `tier_override`) consumed at the gates that would otherwise prompt |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                                          |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| 0    | success              | step 7 (terminal health-check)                                                                                     |
+| 2    | input-missing        | step 1 §1 — no `skill_name` supplied in headless mode (interactive prompt cannot resolve)                          |
+| 3    | resolution-failure   | step 1 §1 (skill not found at resolved path: missing `SKILL.md`); step 1 §2 (`forge-tier.yaml` missing — setup-forge not run); step 1 §5 (source directory from provenance map no longer exists / inaccessible) |
+| 4    | write-failure        | step 1 §6 / step 6 §3 (drift report write failed: read-only mount, disk full, permissions denied)                 |
+| 6    | user-cancelled       | step 1 §1 manifest-vs-symlink gate `[X]` · step 1 §4 degraded-mode gate `[X]` · step 1 §5b upstream-drift gate `[X]` · step 1 §5b dirty-worktree sub-gate `[A]` (and `[A]` headless default) |
+
+## 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"`:
+
+```
+SKF_AUDIT_RESULT_JSON: {"status":"success|error","skill_name":"…","drift_score":"CLEAN|MINOR|SIGNIFICANT|CRITICAL|null","report_path":"…|null","next_workflow":"update-skill|null","audit_ref":"…|null","exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `drift_score` is `null` when the workflow halted before severity classification ran. `next_workflow` is `"update-skill"` when CRITICAL or HIGH findings exist, otherwise `null`. `halt_reason` is one of: `null` (success), `"input-missing"`, `"skill-not-found"`, `"forge-tier-missing"`, `"source-dir-missing"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
@@ -56,4 +84,27 @@ 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 then execute `./steps-c/step-01-init.md` to begin the workflow.
+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 scalars, if the merged value is empty or absent, use the bundled default:
+
+   - `{driftReportTemplatePath}` ← `workflow.drift_report_template_path` if non-empty, else `assets/drift-report-template.md`
+   - `{severityRulesPath}` ← `workflow.severity_rules_path` if non-empty, else `references/severity-rules.md`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — report.md skips the hook invocation entirely)
+
+   Stash all three as workflow-context variables. Stage files reference `{driftReportTemplatePath}` / `{severityRulesPath}` / `{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 (custom drift-report layout, stricter severity thresholds) or wire in post-audit hooks (Slack notifier, ticket-tracker integration) without forking the skill.
+
+4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-audit-skill/assets/drift-report-template.md

@@ -17,6 +17,7 @@ previousWorkflow: 'create-skill'
 
 ## Audit Summary
 
+**Confidence Mode:** {confidence_mode}
 **Skill:** {skill_name}
 **Source:** {source_path}
 **Tier:** {forge_tier}
@@ -35,28 +36,28 @@ previousWorkflow: 'create-skill'
 
 ## Structural Drift
 
-<!-- Appended by step-03-structural-diff -->
+<!-- Appended by structural-diff -->
 
 ---
 
 ## Semantic Drift
 
-<!-- Appended by step-04-semantic-diff (Deep tier only) -->
+<!-- Appended by semantic-diff (Deep tier only) -->
 
 ---
 
 ## Severity Classification
 
-<!-- Appended by step-05-severity-classify -->
+<!-- Appended by severity-classify -->
 
 ---
 
 ## Remediation Suggestions
 
-<!-- Appended by step-06-report -->
+<!-- Appended by report -->
 
 ---
 
 ## Provenance
 
-<!-- Appended by step-06-report -->
+<!-- Appended by report -->

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

@@ -0,0 +1,49 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-audit-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 audit 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, severity-threshold policies, audit guardrails).
+# Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Critical drift requires CODEOWNERS notification."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/audit-policy.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.
+
+drift_report_template_path = ""
+severity_rules_path = ""
+
+# Optional post-audit hook. When non-empty, invoked with
+# `--result-path=<path>` after the drift report and result JSON are finalized.
+# Failures are logged to workflow_warnings[] but never fail the workflow.
+
+on_complete = ""

package/src/skf-audit-skill/{steps-c/step-07-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 6
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`