bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-create-skill/references/generate-artifacts.md

@@ -4,10 +4,17 @@ forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
 # path wins. HALT if neither resolves — the active-symlink flip and registry
-# writes below MUST go through the atomic helper for concurrency safety.
+# writes below go through the atomic helper for concurrency safety.
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# Resolve `{forgeTierRwHelper}` by probing `{forgeTierRwProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves — §6b's ccc-index registry round-trip is
+# comment-preserving and has no prose fallback.
+forgeTierRwProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
+  - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -73,7 +80,7 @@ Write these 4 files from the compiled content:
 
 **Note on `file_type: "doc"` entries** (promoted authoritative docs from step 3 §2a):
 
-Promoted docs are tracked in `file_entries[]` with `file_type: "doc"` for drift detection but are **NOT** copied into the skill package. The source file remains at its original location outside `{skill_package}`. Step-07 must skip any `file_entries[]` row where `file_type == "doc"` when iterating for file copy — these entries exist only for provenance tracking, not bundling. Step-07 verification (§5) also does not check for doc files in the skill package.
+Promoted docs are tracked in `file_entries[]` with `file_type: "doc"` for drift detection but are **not** copied into the skill package. The source file remains at its original location outside `{skill_package}`. Step-07 must skip any `file_entries[]` row where `file_type == "doc"` when iterating for file copy — these entries exist only for provenance tracking, not bundling. Step-07 verification (§5) also does not check for doc files in the skill package.
 
 ### 3. Write Workspace Artifacts to {forge_version}
 
@@ -101,7 +108,7 @@ python3 {atomicWriteHelper} flip-link \
 
 The helper returns non-zero (exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a symlink — in that case, halt with: "Refusing to flip `{skill_group}/active` — existing path is not a symlink. Investigate manually; expected a symlink pointing at a version directory."
 
-**Never `rm` + `ln -s` the active link manually.** The bare-rm pattern has two failure modes: (1) a concurrent reader sees a missing `active` mid-flip, and (2) a bug or typo that replaces `{skill_group}/active` with a plain directory turns the next manual `rm -rf {skill_group}/active` into data loss. The helper encapsulates both guards.
+Do not `rm` + `ln -s` the active link by hand. The bare-rm pattern has two failure modes: (1) a concurrent reader sees a missing `active` mid-flip, and (2) a bug or typo that replaces `{skill_group}/active` with a plain directory turns the next manual `rm -rf {skill_group}/active` into data loss. The helper encapsulates both guards.
 
 ### 5. Verify Write Completion
 
@@ -174,10 +181,10 @@ If an entry with `name: "{name}-extraction"` already exists, replace it. Otherwi
 Write the updated forge-tier.yaml.
 
 **Error handling:**
-- If QMD collection creation fails: log the error, note that indexing can be retried via [SF] setup. Do NOT fail the workflow.
+- If QMD collection creation fails: log the error, note that indexing can be retried via [SF] setup. Do not fail the workflow.
 - If forge-tier.yaml update fails: log the error, continue. The collection exists in QMD even if the registry entry failed.
 
-**IF forge tier is NOT Deep:** Skip this section silently. No messaging.
+**IF forge tier is not Deep:** Skip this section silently. No messaging.
 
 ### 6b. CCC Index Registry Registration (Forge+ and Deep with ccc)
 
@@ -195,34 +202,22 @@ Ensure the source path used for extraction is indexed by ccc and registered in t
 
 **Registry update:**
 
-Register the indexed source path via `register-ccc-index` (comment-preserving round-trip, same pattern as §6's `register-qmd-collection`). Acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`, then:
+**Resolve `{forgeTierRwHelper}`** from `{forgeTierRwProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Register the indexed source path via `register-ccc-index` — a comment-preserving round-trip on `forge-tier.yaml`. This differs from §6, which mutates the registry with an inline read→modify→atomic-write under `flock`; here the helper owns the read→modify→write internally so the `ccc_index_registry` deduplication logic stays in the script. Acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`, then:
 
 ```bash
 echo '{"source_repo":"{brief.source_repo}","path":"{source_root}","skill_name":"{name}","indexed_at":"{current ISO date}","source_workflow":"create-skill"}' \
-  | uv run {forgeTierRw} register-ccc-index --target {forgeTierConfig}
+  | uv run {forgeTierRwHelper} register-ccc-index --target {forgeTierConfig}
 ```
 
-Deduplicates by `source_repo` + `skill_name` (NOT local `path`, which may be ephemeral). Release the lock after the command completes. If `flock` is unavailable, fall back to read-CAS-by-mtime.
+Deduplicates by `source_repo` + `skill_name` (not local `path`, which may be ephemeral). Release the lock after the command completes. If `flock` is unavailable, fall back to read-CAS-by-mtime.
 
-**Error handling:** If ccc indexing or registry update fails, log and continue — do NOT fail the workflow.
+**Error handling:** If ccc indexing or registry update fails, log and continue — do not fail the workflow.
 
 **IF `tools.ccc` is false:** Skip this section silently.
 
-### 7. Menu Handling Logic
-
-**Auto-proceed step — no user interaction.**
-
-After all artifacts are written, verified, and optionally indexed into QMD, immediately load, read entire file, then execute `{nextStepFile}`.
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed file writing step with no user choices
-- All 7 files must be written before proceeding
-- QMD indexing failure does NOT block proceeding
-- File write failures are real errors — halt, do not proceed with partial output
-- Proceed directly to next step after successful generation
-
-## CRITICAL STEP COMPLETION NOTE
+### 7. Auto-Proceed
 
-ONLY WHEN all 7 artifact files are written, the active symlink is created, and verification is complete will you proceed to load `{nextStepFile}` for the compilation report.
+No user interaction. Once all 7 files are written and verified (and optionally indexed into QMD), load `{nextStepFile}`, read it fully, then execute it. A QMD-indexing failure does not block; a file-write failure halts (§5) rather than proceeding with partial output.
 

package/src/skf-create-skill/references/health-check.md

@@ -1,7 +1,7 @@
 ---
 # `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'
 ---
 

package/src/skf-create-skill/references/load-brief.md

@@ -40,14 +40,14 @@ Extract and report:
 - `tools`: which tools are available (gh, ast-grep, ccc, qmd)
 - `ccc_index`: ccc index state (status, indexed_path, last_indexed) — needed by step 2b
 
-**Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is one of the exact valid tier values (`Quick`, `Forge`, `Forge+`, `Deep`), use it instead of the detected tier. **If `tier_override` is set but is NOT one of those four values:** log a warning — "Unknown tier_override `{value}` in preferences.yaml; falling back to detected tier `{detected_tier}`. Valid values: Quick, Forge, Forge+, Deep." — and use the detected tier. Never silently apply an unknown override value, and never map it heuristically to a tier.
+**Apply tier override:** Read `{preferencesFile}`. If `tier_override` is set and is one of the exact valid tier values (`Quick`, `Forge`, `Forge+`, `Deep`), use it instead of the detected tier. **If `tier_override` is set but is not one of those four values:** log a warning — "Unknown tier_override `{value}` in preferences.yaml; falling back to detected tier `{detected_tier}`. Valid values: Quick, Forge, Forge+, Deep." — and use the detected tier. Never silently apply an unknown override value, and never map it heuristically to a tier.
 
 **Record the decision:** append an entry to the in-context `headless_decisions[]` buffer (initialize to `[]` at the start of this step if absent) whenever a non-interactive choice is made automatically — both the valid-override path AND the rejected-override path:
 
 - Valid override applied: `{step: "load-brief", gate: "tier-override", decision: "apply", value: "{tier_override}", rationale: "explicit preferences.yaml tier_override", timestamp: {ISO}}`
 - Invalid override rejected: `{step: "load-brief", gate: "tier-override", decision: "reject-invalid", value: "{tier_override}", fallback: "{detected_tier}", rationale: "tier_override not in {Quick,Forge,Forge+,Deep}", timestamp: {ISO}}`
 
-Step-05 §7 reads `headless_decisions[]` and emits an "Auto-Decisions" section into `evidence-report.md` so reviewers can audit every silent choice the workflow made.
+These entries stay in the in-context buffer until §3 establishes the on-disk auto-decision sink and seeds it with the buffer-so-far; from then on every later gate's decision is appended to the sink as it lands (per the headless Workflow Rule). Step 5 §7 renders the sink into the evidence-report `## Auto-Decisions` table and step 6 §8 reconciles it, so reviewers can audit every silent choice even on a run long enough to compact the in-context buffer before step 5.
 
 ### 2. Discover Skill Brief
 
@@ -58,7 +58,7 @@ Step-05 §7 reads `headless_decisions[]` and emits an "Auto-Decisions" section i
 
 **If user invoked with --batch flag:**
 - Check `{sidecar_path}/batch-state.yaml` for an active batch checkpoint:
-  - If `batch_active: true`: validate the checkpoint before trusting it. Both conditions below MUST hold:
+  - If `batch_active: true`: validate the checkpoint before trusting it — both conditions below must hold:
     1. `0 <= current_index < len(brief_list)` — the index points inside the recorded list.
     2. `os.path.exists(brief_list[current_index])` — the brief file is still on disk.
     If both hold, load the brief at `brief_list[current_index]` (resuming a batch loop from step 8). If **either** check fails, the checkpoint is stale (briefs renamed, moved, or deleted between runs; index off the end after a partial failure). Log a warning — "Stale batch checkpoint — current_index={i}, brief_list length={n}, brief_exists={bool}. Resetting and re-discovering." — then set `batch_active: false` in `batch-state.yaml` and fall through to the no-checkpoint branch below.
@@ -95,9 +95,19 @@ The helper emits:
 
 **If `valid` is true:** continue with `brief` (the parsed object) for downstream sections. Surface any `warnings[]` to the user but do not halt.
 
+**Establish the auto-decision sink (durable headless audit).** The brief is now confirmed, so create the on-disk audit sink at `{sidecar_path}/auto-decisions.jsonl` — one compact JSON object per line — and seed it with whatever is already in the in-context `headless_decisions[]` buffer (the §1 tier-override row, or nothing if none fired). This truncates any stale sink a prior brief left behind:
+
+```bash
+: > {sidecar_path}/auto-decisions.jsonl          # truncate / create empty
+# then, for each entry already in headless_decisions[], append its compact JSON:
+printf '%s\n' '{decision-json}' >> {sidecar_path}/auto-decisions.jsonl
+```
+
+From here on, **every time a later gate appends an auto-decision to `headless_decisions[]`, append that same object as a line to this sink the moment it lands** (the on-landing append the headless Workflow Rule mandates). The array is tiny, so the append costs nothing and keeps a complete on-disk copy across the token-heavy step 3→5 extraction window — the point where a long component-library run can compact the in-context buffer. Step 5 §7 renders this sink into the evidence-report `## Auto-Decisions` table and step 6 §8 reconciles it, so the audit table and `auto_decision_count` stay complete even when the buffer is lost.
+
 **Field reference (for human readers):**
 
-The complete contract — required fields, optional fields, types, and rules — lives in `src/shared/scripts/schemas/skill-brief.v1.json` and the prose mirror at `src/skf-brief-skill/assets/skill-brief-schema.md`. Read those if you need to explain a specific field; do NOT restate the rules here.
+The complete contract — required fields, optional fields, types, and rules — lives in `src/shared/scripts/schemas/skill-brief.v1.json` and the prose mirror at `src/skf-brief-skill/assets/skill-brief-schema.md`. Read those if you need to explain a specific field; do not restate the rules here.
 
 ### 4. Resolve Source Code Location
 
@@ -137,19 +147,7 @@ Where tier_description follows positive capability framing:
 - Forge+: "Semantic-guided precision — ccc pre-ranks files before AST extraction"
 - Deep: "Full intelligence — structural + contextual + QMD knowledge synthesis"
 
-### 6. Menu Handling Logic
-
-**Auto-proceed step — no user interaction.**
-
-After initialization is complete and all data is loaded (including `target_version` if present in the brief), immediately load, read entire file, then execute `{nextStepFile}`.
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed initialization step with no user choices
-- Proceed directly to next step after successful initialization
-- If any prerequisite check fails, HALT with actionable error — do NOT proceed
-
-## CRITICAL STEP COMPLETION NOTE
+### 6. Auto-Proceed
 
-ONLY WHEN forge-tier.yaml is loaded, skill-brief.yaml is validated, and source code location is resolved will you proceed to load `{nextStepFile}` for ecosystem check.
+No user interaction. After initialization completes and all data is loaded (including `target_version` if present), load `{nextStepFile}`, read it fully, then execute it. A failed prerequisite check above has already halted with an actionable error rather than reaching here.
 

package/src/skf-create-skill/references/report.md

@@ -20,7 +20,7 @@ To display the final compilation summary — skill name, version, source, export
 
 - Focus only on reporting compilation results — do not modify any files
 - Deliver structured report with confidence breakdown
-- Chains to the local health-check step via `{nextStepFile}` after completion (non-batch mode, or after the final batch brief) — the user-facing report is NOT the terminal step
+- Chains to the local health-check step via `{nextStepFile}` after completion (non-batch mode, or after the final batch brief) — the user-facing report is not the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -72,11 +72,6 @@ If there were warnings from extraction, validation, or enrichment, display them:
 
 If no warnings, omit this section entirely.
 
-**Next steps:** After reviewing the report, recommend the next workflow:
-- **TS** (test skill) — verify completeness before export
-- **EX** (export) — publish to your IDE's context system
-- If issues were flagged, suggest **reviewing the SKILL.md** and re-running compilation
-
 ### 4. Suggest Next Steps
 
 "**Recommended next steps:**
@@ -125,21 +120,39 @@ End workflow. No further steps.
 
 **Resolve the schema reference:** before writing, verify that `{project-root}/src/shared/references/output-contract-schema.md` exists and is readable. Try in order: `{project-root}/src/shared/references/output-contract-schema.md`, then `{project-root}/_bmad/skf/shared/references/output-contract-schema.md` (installed-forge path).
 
-- **If resolved:** write the result contract per the schema — the per-run record at `{forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_version}/create-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include `SKILL.md`, `context-snippet.md`, and `metadata.json` paths in `outputs` and confidence distribution in `summary`. Use `python3 {atomicWriteHelper} write --target {forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` (stdin-piped JSON) for the per-run record, then the same helper for the `-latest.json` copy.
+- **If resolved:** write the result contract per the schema — the per-run record at `{forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_version}/create-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include `SKILL.md`, `context-snippet.md`, `metadata.json`, **and `{forge_version}/evidence-report.md`** paths in `outputs` (the evidence report carries the `## Auto-Decisions` audit table where every silent auto-decision is recorded — pipeline consumers follow this path to audit the run) and confidence distribution in `summary`. Also set `summary.auto_decision_count` to the number of decision rows in the reconciled evidence-report `## Auto-Decisions` table (0 when the run was interactive and the section holds only the no-auto-decisions line) so a consumer can tell from the result JSON alone whether any gate auto-resolved. Count the persisted rows — the durable audit record step 6 §8 reconciled from disk — rather than the in-context `headless_decisions[]` length, so the count matches the table even if a long headless run compacted the buffer. Use `python3 {atomicWriteHelper} write --target {forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` (stdin-piped JSON) for the per-run record, then the same helper for the `-latest.json` copy.
 
 - **If neither candidate path resolves:** skip the result-contract write entirely. Append a warning to `evidence-report.md`: "Result contract skipped — `shared/references/output-contract-schema.md` could not be resolved at either candidate path." Then set `validation_status: 'schema-unavailable'` in `metadata.json` (and re-write metadata.json via `skf-atomic-write.py write`). Pipeline consumers will observe the missing `-latest.json` and the metadata flag.
 
-### 6. Chain to Health Check
+**Post-completion hook (optional).** After the result JSON and `metadata.json` are finalized, if `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it:
 
-**If not batch mode (or all batch briefs complete):**
+```bash
+{onCompleteCommand} --result-path={forge_version}/create-skill-result-latest.json
+```
 
-ONLY WHEN the compilation report, warnings (if any), recommended next steps, and result contract have been handled 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 report reads as final.
+Log success or failure to `workflow_warnings[]` but never fail the workflow on a hook error — the skill is already written and the result contract is final. The hook runs last so a git-add, registry registration, notifier, or downstream-skill chain sees a complete package. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
 
-**If batch mode with remaining briefs:** Skip the health-check chain — load and execute `references/load-brief.md` for the next brief instead. The health check runs only after the final brief in the batch.
+### Result Contract on HARD HALT
 
-## CRITICAL STEP COMPLETION NOTE
+The success-variant contract above is only reached at step 8. The ~10 HARD HALT conditions in steps 1–7 (forge-config missing, no brief, brief invalid, source not found, prerequisite failure in load-brief; atomic/detect/auth helper unresolved and the Tier-1 split-count drop in extract/validate; the non-symlink active-link refusal in generate-artifacts) otherwise print a human string and exit with **no machine-readable outcome** — a pipeline polling `create-skill-result-latest.json` cannot distinguish "halted at brief-invalid" from "still running" from "crashed". Mirror skf-quick-skill: **whenever `{headless_mode}` is true, every HARD HALT must surface an error-variant result before exiting.**
+
+**For every HARD HALT under `{headless_mode}` (regardless of phase)** — emit a single line on **stderr** (one line, no pretty-print; matches the prefix-and-envelope convention used by `skf-emit-result-envelope.py`):
+
+```
+SKF_CREATE_SKILL_RESULT_JSON: {"status":"failed","phase":"<step-slug>","outputs":{},"summary":{"halt_reason":"<short class>","evidence_report":"<path-or-null>"},"skill_package":"<path-or-null>"}
+```
 
-This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md` (unless batch mode loops back to step 1). After the health check completes, the create-skill workflow is fully done.
+Use `status: "partial"` instead of `"failed"` when artifacts were already staged or promoted before the HALT (i.e. the HALT fired at step 7 generate-artifacts after some files were written); use `"failed"` for HALTs before any artifact exists on disk (steps 1–6).
 
-For batch mode: load and execute `references/load-brief.md` for remaining briefs via sidecar checkpoint. Health check runs only after the last brief.
+**Additionally, when `{forge_version}` is resolved** (HALT at step 7 onward, where the staging tree has been promoted) — write the same JSON object (without the `SKF_CREATE_SKILL_RESULT_JSON: ` prefix) to disk at `{forge_version}/create-skill-result-{YYYYMMDD-HHmmss}.json` and a copy at `{forge_version}/create-skill-result-latest.json` (copy, not symlink) via `python3 {atomicWriteHelper} write`, so consumers that hardcode the `-latest.json` path see a deterministic file even on failed runs. Set `summary.evidence_report` to `{forge_version}/evidence-report.md` whenever that file exists, so the consumer can still reach the `## Auto-Decisions` audit on a failed run. HALTs before step 7 cannot write to disk because `{forge_version}` is only created at step 7 §1; for those, the stderr envelope is the contract and `summary.evidence_report` is `null`.
+
+When `{headless_mode}` is false, HARD HALTs display their human message only — no envelope is emitted.
+
+### 6. Chain to Health Check
+
+**If not batch mode (or all batch briefs complete):**
+
+Only after the compilation report, warnings (if any), recommended next steps, and result contract have been handled do you load `{nextStepFile}`, read it fully, and execute it. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+
+**If batch mode with remaining briefs:** Skip the health-check chain — load and execute `references/load-brief.md` for the next brief instead. The health check runs only after the final brief in the batch.
 

package/src/skf-create-skill/references/source-resolution-protocols.md

@@ -123,7 +123,7 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
 
    If fetch or checkout fails, proceed to the **ephemeral fallback** (step 5).
 
-   **If `{workspace_repo_path}/.git/` does NOT exist (workspace miss):**
+   **If `{workspace_repo_path}/.git/` does not exist (workspace miss):**
 
    Clone the repository into the workspace for persistent reuse. Create the parent directory first (`{workspace_root}/repos/{host}/{owner}/`):
 
@@ -131,7 +131,7 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
    mkdir -p "{workspace_root}/repos/{host}/{owner}/"
    ```
 
-   Clone with the appropriate branch flag — `--branch` is only valid for real branch/tag names, not for `HEAD`. **Do NOT pass `--single-branch`** here: workspace clones are persistent and re-used for future forges with different `source_ref` values (a later run may target a different tag or branch). A single-branch workspace clone would force every re-forge with a new ref to fall through to ephemeral cloning, defeating the workspace cache:
+   Clone with the appropriate branch flag — `--branch` is only valid for real branch/tag names, not for `HEAD`. **Do not pass `--single-branch`** here: workspace clones are persistent and re-used for future forges with different `source_ref` values (a later run may target a different tag or branch). A single-branch workspace clone would force every re-forge with a new ref to fall through to ephemeral cloning, defeating the workspace cache:
 
    ```
    # If source_ref is a real branch or tag (not HEAD/null):
@@ -154,7 +154,7 @@ If `source_repo` is a remote URL (GitHub URL or owner/repo format) AND tier is F
    - `remote_clone_path = {workspace_repo_path}`
    - `remote_clone_type = "workspace"`
 
-   **Scope filtering:** Since the workspace uses a full checkout (no sparse-checkout), apply `include_patterns` and `exclude_patterns` from the brief as **file-level filters** when building the extraction file list. Always-included root files (`pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `setup.py`, `setup.cfg`, `VERSION`) are exempt from pattern filtering.
+   **Scope filtering:** Since the workspace uses a full checkout (no sparse-checkout), apply `include_patterns` and `exclude_patterns` from the brief as **file-level filters** when building the extraction file list. Always-included root files (`pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `Package.swift`, `setup.py`, `setup.cfg`, `VERSION`) are exempt from pattern filtering.
 
 5. **Ephemeral fallback (on any workspace failure):**
 
@@ -216,7 +216,7 @@ Also store `source_ref` in context (from tag resolution above, or `HEAD` if no t
 
 ## Version Reconciliation (all tiers, source mode only)
 
-**Target version override:** If `brief.target_version` is present, use it as the authoritative version for the skill. Do NOT warn about a brief-vs-source version mismatch — the user intentionally specified this version. Set the working version to `brief.target_version` and skip the rest of this reconciliation section. The `target_version` field indicates deliberate user intent (e.g., targeting an older version, or providing the version for a docs-only skill).
+**Target version override:** If `brief.target_version` is present, use it as the authoritative version for the skill. Do not warn about a brief-vs-source version mismatch — the user intentionally specified this version. Set the working version to `brief.target_version` and skip the rest of this reconciliation section. The `target_version` field indicates deliberate user intent (e.g., targeting an older version, or providing the version for a docs-only skill).
 
 **If `source_type: "docs-only"`:** skip this section — no source files exist to reconcile.
 

package/src/skf-create-skill/references/step-auto-shard.md

@@ -1,5 +1,12 @@
 ---
 nextStepFile: 'step-doc-rot.md'
+# Resolve `{shardBodyHelper}` by probing `{shardBodyProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves — hand line-counting is the least reliable
+# deterministic op and would silently ship an over-budget body or wrongly HALT.
+shardBodyProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-shard-body.py'
+  - '{project-root}/src/shared/scripts/skf-shard-body.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -15,42 +22,66 @@ Proactively reduce oversized SKILL.md bodies to under 400 lines by extracting Ti
 - Auto-proceed step — no user interaction required
 - Graceful skip — if body is under threshold, proceed without modification
 - Only extract Tier 2 sections (identified by `## Full` heading prefix)
-- Tier 1 sections must NEVER be moved to references/
+- Tier 1 sections stay inline — moving one to references/ would break the standalone SKILL.md the two-tier design guarantees
 - Do not modify frontmatter — only body content and references/ directory
 - Do not invoke `npx skill-check split-body` — this step uses direct extraction
 - Do not invoke the Description Guard Protocol — frontmatter is untouched
 
 ## MANDATORY SEQUENCE
 
+### §0. Run the Shard Script (primary path)
+
+The counting, boundary detection, size-sort, file writes, and blockquote replacement described in §1–§5 are fully deterministic and run every invocation — so a script owns them, not the model. Do not count body lines or extract sections by hand when the script ran.
+
+**Resolve `{shardBodyHelper}`** from `{shardBodyProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
+Run:
+
+```bash
+uv run {shardBodyHelper} <staging-skill-dir>/SKILL.md --budget 400
+```
+
+The script performs everything §1–§5 document — it counts the body between the frontmatter close and EOF, enumerates the `## Full` Tier 2 sections, extracts the largest first to `references/` until the body fits, writes the extracted files and the trimmed SKILL.md through the atomic-write helper, rewrites each section as a cross-reference blockquote, and checks Tier 1 preservation and cross-reference integrity. Read its JSON and set context directly:
+
+- **`action: "skip"`** → the body was already within budget. Log `"auto-shard: skipped (body {body_lines_before} lines)"`, set `auto_shard_triggered: false`, `sections_extracted: []`, `body_lines_before`/`body_lines_after` from the report, then skip to §6.
+- **`action: "shard"`** → set `auto_shard_triggered: true` and copy `sections_extracted`, `body_lines_before`, `body_lines_after` straight from the report.
+- **HALT** if `tier1_preserved` is false: `"Auto-shard removed Tier 1 section(s) {tier1_missing}. Aborting."`
+- **HALT** if `xref_ok` is false: `"Auto-shard cross-references did not resolve. Aborting."`
+- If `under_budget` is false, selective Tier 2 extraction alone could not bring the body under budget (rare — Tier 1 itself exceeds ~300 lines). Apply the §4 editing-judgment trim, then continue.
+
+Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`, then proceed to §6.
+
+**Manual fallback (only when `uv`/Python is unavailable):** perform §1–§5 by hand as documented below — they describe exactly what the script does.
+
 ### §1. Count Body Lines
 
-Count all lines in the staging SKILL.md between the frontmatter closing `---` and EOF. Exclude trailing blank lines from the count. Store as `body_line_count`.
+The script counts all lines in the staging SKILL.md between the frontmatter closing `---` and EOF, excluding trailing blank lines, and reports the total as `body_lines_before`.
 
 ```
 body_lines_before = body_line_count
 ```
 
-**IF `body_line_count` <= 400:**
+**IF `body_line_count` <= 400:** the script emits `action: "skip"` and writes nothing —
 - Log: `"auto-shard: skipped (body {body_line_count} lines)"`
 - Set context: `auto_shard_triggered: false`, `sections_extracted: []`, `body_lines_before: {body_line_count}`, `body_lines_after: {body_line_count}`
 - Skip to §6 (Auto-Proceed)
 
-**ELSE:** Proceed to §2.
+**ELSE:** the script proceeds to §2.
 
 ### §2. Selective Shard — Tier 2 Extraction
 
-Identify Tier 2 sections by their `## Full` heading prefix:
+The script identifies Tier 2 sections by their `## Full` heading prefix:
 - `## Full API Reference` → `references/full-api-reference.md`
 - `## Full Type Definitions` → `references/full-type-definitions.md`
 - `## Full Integration Patterns` → `references/full-integration-patterns.md`
 
-Sort identified sections by line count descending (extract largest first).
+Sections are sorted by line count descending (largest first).
 
 **FOR EACH Tier 2 section (largest first):**
 
 1. Extract the full section content (from `## Full` heading to the next `##` heading or EOF)
 2. Derive the reference filename from the heading: kebab-case (as shown above)
-3. Write the extracted content (preserving the `##` heading) to `<staging-skill-dir>/references/{filename}`
+3. Write the extracted content (preserving the `##` heading) to `<staging-skill-dir>/references/{filename}` via the atomic-write helper
 4. Replace the extracted section in SKILL.md with a cross-reference blockquote:
    ```markdown
    > See [Full API Reference](references/full-api-reference.md)
@@ -58,44 +89,40 @@ Sort identified sections by line count descending (extract largest first).
 5. Re-count body lines
 6. **IF `body_line_count` <= 400:** stop extracting, proceed to §3
 
-Track: `sections_extracted: [{heading names}]`
+The report's `sections_extracted: [{heading, file, lines}]` records exactly which sections were pulled.
 
 ### §3. Tier 1 Preservation Check
 
-Verify ALL Tier 1 sections remain inline in SKILL.md after extraction. Check for these headings:
+The script verifies ALL Tier 1 sections that were inline before extraction remain inline in SKILL.md afterward. These headings:
 
 - `## Overview`
 - `## Quick Start`
 - `## Common Workflows`
 - `## Key API Summary` (or `## Component Catalog` for component-library scope)
-- `## Migration & Deprecation Warnings` (conditional — only check if it was present before extraction)
+- `## Migration & Deprecation Warnings` (conditional — only checked if it was present before extraction)
 - `## Key Types`
 - `## Architecture at a Glance`
-- `## CLI` (conditional — only check if present before extraction)
-- `## Scripts & Assets` (conditional — only check if present before extraction)
-- `## Manual Sections` (conditional — only check if present before extraction)
+- `## CLI` (conditional — only checked if present before extraction)
+- `## Scripts & Assets` (conditional — only checked if present before extraction)
+- `## Manual Sections` (conditional — only checked if present before extraction)
+
+The result surfaces as `tier1_preserved` (with any pulled headings in `tier1_missing`).
 
-**IF any Tier 1 section is missing after extraction:**
+**IF `tier1_preserved` is false:**
 HALT: `"Auto-shard removed Tier 1 section {name}. Aborting."`
 
 ### §4. Post-Shard Validation
 
-Re-count body lines after all Tier 2 sections have been extracted.
-
-```
-body_lines_after = body_line_count
-```
+The report's `body_lines_after` is the recount after all extraction. `under_budget` is true when the body now fits.
 
-**IF `body_line_count` > 400 after all Tier 2 sections extracted:**
+**IF `under_budget` is false** (body still > 400 after all Tier 2 sections extracted — this is the one genuine editing-judgment step):
 - Trim oversized Tier 1 sections: reduce `## Key API Summary` and `## Architecture at a Glance` content to fit within the 400-line budget
-- Do NOT move any Tier 1 section to references/
-- Re-count and update `body_lines_after`
+- Do not move any Tier 1 section to references/
+- Re-run `{shardBodyHelper}` (or re-count) and update `body_lines_after`
 
 ### §5. Cross-Reference Integrity
 
-**FOR EACH extracted reference file:**
-1. Verify the file exists at `<staging-skill-dir>/references/{filename}`
-2. Verify the cross-reference blockquote in SKILL.md contains a link resolving to the file
+The script verifies, for each extracted reference file, that the file exists at `<staging-skill-dir>/references/{filename}` and that the cross-reference blockquote in SKILL.md links to it — reported as `xref_ok`. HALT if `xref_ok` is false.
 
 Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`
 

package/src/skf-create-skill/references/step-doc-rot.md

@@ -1,5 +1,6 @@
 ---
 nextStepFile: 'validate.md'
+scanDocRotHelper: 'scripts/scan-doc-rot.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -8,7 +9,7 @@ nextStepFile: 'validate.md'
 
 ## STEP GOAL:
 
-Scan feeder artifacts for doc-rot correction indicators and annotate the compiled SKILL.md with `## CORRECTION` blocks. Matching is grep-based and deterministic — no AI judgment is used for detection.
+Scan feeder artifacts for doc-rot correction indicators and annotate the compiled SKILL.md with `## CORRECTION` blocks. Matching is a deterministic substring grep performed by `{scanDocRotHelper}` (`scripts/scan-doc-rot.py`) — no AI judgment is used for detection. The prompt keeps only the genuine judgment the script cannot make: enriching each match's `affected` symbol (§2) and choosing where each `## CORRECTION` block goes (§3).
 
 ## Rules
 
@@ -23,12 +24,12 @@ Scan feeder artifacts for doc-rot correction indicators and annotate the compile
 
 ### §1. Locate Feeder Artifacts
 
-Identify the feeder artifacts in the staging directory for the current skill:
+Identify the feeder artifacts in the **staging directory** for the current skill. This step (5c) runs **before** step 7 promotes the staging tree to `{forge_data_folder}/{skill-name}/{version}/`, so the feeder artifacts only exist under the staging path compile (step 5 §1a) wrote — reading the not-yet-promoted `{forge_data_folder}` path would make every match a no-op:
 
-1. **Evidence report:** `{forge_data_folder}/{skill-name}/{version}/evidence-report.md`
-2. **Provenance map:** `{forge_data_folder}/{skill-name}/{version}/provenance-map.json` — focus on T2/T3 entries with temporal annotations
+1. **Evidence report:** `_bmad-output/{skill-name}/evidence-report.md`
+2. **Provenance map:** `_bmad-output/{skill-name}/provenance-map.json` — focus on T2/T3 entries with temporal annotations
 3. **Temporal context:** changelogs, migration guides, and issue/PR data fetched by step 3b and enriched by step 4 (available in workflow context)
-4. **Compiled SKILL.md:** the staged SKILL.md itself — check for `[QMD:...]` or `[DOC:...]` annotations referencing corrections
+4. **Compiled SKILL.md:** the staged `_bmad-output/{skill-name}/SKILL.md` itself — check for `[QMD:...]` or `[DOC:...]` annotations referencing corrections. **Do not treat its own `## Migration & Deprecation Warnings` section (§4b) as a correction source:** compile (step 5 §4b) already authored that section from the same T2-future annotations, so its bullets are already-surfaced corrections — §2 discards matches that land inside it.
 
 For each artifact, attempt to load its content. If an artifact does not exist or is empty, skip it — this is not an error.
 
@@ -36,7 +37,31 @@ Store: `feeder_artifacts_scanned: [{list of artifacts that were loaded}]`
 
 ### §2. Grep for Correction Indicators
 
-Scan each loaded feeder artifact for the following correction patterns. All matches are **case-insensitive substring matches** — no regex interpretation, no semantic analysis.
+The scan is deterministic plumbing — a fixed-table substring grep with one correct answer per input — so it runs in `{scanDocRotHelper}`, **not** in-prompt. Do not hand-grep the feeder artifacts: identical feeders must yield identical `correction_matches`, and only the script guarantees that across multi-KB inputs. Pass the `## Migration & Deprecation Warnings`-bearing compiled SKILL.md (feeder #4) as `--skill-md` and every other loaded feeder as a positional argument:
+
+```bash
+uv run {scanDocRotHelper} \
+  --skill-md _bmad-output/{skill-name}/SKILL.md \
+  _bmad-output/{skill-name}/evidence-report.md \
+  _bmad-output/{skill-name}/provenance-map.json \
+  _bmad-output/{skill-name}-temporal/*.md
+```
+
+(Pass whichever of the §1 feeder paths actually exist — the script skips any that are missing or empty, and reports the loaded set in `scanned`.)
+
+The script emits `{scanned: [...], matches: [...], match_count, excluded_count}` on stdout. Each entry in `matches` is a match record with the deterministic fields the script owns:
+
+- `source`: the feeder artifact path where the match was found
+- `pattern`: the specific pattern string that matched
+- `category`: the category label
+- `context_line`: the line containing the match
+- `line_number`: the 1-indexed line the match sits on
+
+Read `matches` into `correction_matches: [{match records}]`. Then add the one judgment field the script cannot infer:
+
+- `affected`: the function name, API, or section the correction relates to — enrich each record from surrounding context (use the `[QMD:...]`/`[DOC:...]` annotations and nearby symbols); if not identifiable, set to `"unknown"`.
+
+**What the script does (the contract it implements — keep this table and the script's `PATTERN_TABLE` in lockstep):** it matches every feeder line against the following correction patterns. All matches are **case-insensitive substring matches** — no regex interpretation, no semantic analysis.
 
 | Pattern | Category |
 |---------|----------|
@@ -54,16 +79,9 @@ Scan each loaded feeder artifact for the following correction patterns. All matc
 | `migration required` | Migration |
 | `signature changed` | Signature change |
 
-For each match, record:
-- `source`: the feeder artifact path or citation where the match was found
-- `pattern`: the specific pattern string that matched
-- `category`: the category from the table above
-- `context_line`: the line or excerpt containing the match
-- `affected`: the function name, API, or section the correction relates to (extract from surrounding context if identifiable; otherwise set to `"unknown"`)
-
-Store all matches as `correction_matches: [{match records}]`
+**Exclusion — drop already-surfaced §4b corrections (deterministic, no AI judgment, applied inside the script before it emits):** the script discards any match whose `source` is the compiled SKILL.md (feeder #4) **and** whose `context_line` sits inside that file's own `## Migration & Deprecation Warnings` section — i.e. on a line at or after the `## Migration & Deprecation Warnings` heading and before the next `##` heading (`excluded_count` reports how many it dropped). Compile (step 5 §4b) authored that section from the same T2-future annotations, so re-emitting its bullets as `## CORRECTION` blocks in §3 would duplicate already-surfaced content verbatim. This is a positional heading-boundary check on text already loaded, not a semantic assessment. Set `feeder_artifacts_scanned` from the script's `scanned` list.
 
-**IF `correction_matches` is empty:**
+**IF `correction_matches` is empty** (the script returned `match_count: 0`, or the run had no feeder files to pass)**:**
 - Log: `"doc-rot: skipped (no correction indicators found in feeder artifacts)"`
 - Set context: `doc_rot_triggered: false`, `corrections_added: 0`
 - Skip to §5 (Auto-Proceed)

package/src/skf-create-skill/references/step-doc-sources.md

@@ -1,5 +1,12 @@
 ---
 nextStepFile: 'step-auto-shard.md'
+# Resolve `{detectDocsHelper}` by probing `{detectDocsProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves — §2 has no prose fallback for doc-source
+# detection (Pages-API walk, docs/ folder scan, content hashing).
+detectDocsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-docs.py'
+  - '{project-root}/src/shared/scripts/skf-detect-docs.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -21,7 +28,7 @@ Record detected documentation pages and README with content hashes in metadata.j
 
 ### 1. Check for Upstream Doc Detection Results
 
-Check if `doc_detection_results` is already populated in the workflow context (set by BS auto-brief in the deepwiki pipeline).
+Check if `doc_detection_results` is already populated in the workflow context (set by BS auto-brief in the forge-auto pipeline).
 
 - **If upstream results exist:** use them directly, skip to step 3.
 - **If no upstream results:** continue to step 2.
@@ -37,10 +44,12 @@ Check that `{source_repo}` is available from the skill brief.
 
 **If `{source_repo}` is available:**
 
+**Resolve `{detectDocsHelper}`** from `{detectDocsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+
 Invoke the detect-docs script:
 
 ```bash
-uv run python src/shared/scripts/skf-detect-docs.py \
+uv run {detectDocsHelper} \
   --repo-url {source_repo} \
   [--local-path {source_path}] \
   [--skip-pages-api]
@@ -85,10 +94,10 @@ Map each detection result to the `doc_sources` schema:
 Field mapping from `skf-detect-docs.py` output:
 - `url` ← `url` (direct copy)
 - `detected_via` ← `detected_via` (direct copy; or `"readme_always"` for the mandatory README entry)
-- `content_hash` ← `content_hash` (direct copy, already in `sha256:{hexdigest}` format from story 1.2)
+- `content_hash` ← `content_hash` (direct copy, already in `sha256:{hexdigest}` format)
 - `recorded_at` ← generated at step execution time (ISO-8601 with timezone)
 
-Note: `content_type` from detect-docs output is NOT carried into `doc_sources`.
+Note: `content_type` from detect-docs output is not carried into `doc_sources`.
 
 ### 5. Update metadata.json
 

package/src/skf-create-skill/references/sub/ccc-discover.md

@@ -82,7 +82,7 @@ Set `{ccc_discovery: []}` in context.
 
 Display: "CCC discovery unavailable — proceeding with standard extraction."
 
-Do NOT halt. This is not an error.
+Do not halt. This is not an error.
 
 **If search returns empty results:**
 
@@ -92,16 +92,5 @@ No message needed — empty results are normal for small or highly focused libra
 
 ### 5. Auto-Proceed
 
-Immediately load, read entire file, then execute `{nextStepFile}`.
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step with no user choices
-- Quick/Forge tiers skip directly with no output
-- Forge+/Deep with ccc displays brief discovery summary then auto-proceeds
-- CCC failures do not halt — degrade and proceed
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN discovery is complete (Forge+/Deep with ccc) or the step is skipped (Quick/Forge or ccc unavailable) will you proceed to load `{nextStepFile}` for AST extraction.
+No user interaction. Load `{nextStepFile}`, read it fully, then execute it. CCC failures degrade and proceed — they never halt.