bmad-module-skill-forge 1.8.0 → 2.0.0

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

@@ -8,6 +8,13 @@ forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 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}. -->
@@ -195,11 +202,13 @@ 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.

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/report.md

@@ -125,10 +125,26 @@ 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 `len(headless_decisions[])` (0 when the run was interactive) so a consumer can tell from the result JSON alone whether any gate auto-resolved. 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.
 
+### Result Contract on HARD HALT
+
+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.**
+
+**Always (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>"}
+```
+
+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).
+
+**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):**

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

@@ -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):**
 

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

@@ -0,0 +1,110 @@
+---
+nextStepFile: 'step-doc-rot.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 5b: Auto-Shard
+
+## STEP GOAL:
+
+Proactively reduce oversized SKILL.md bodies to under 400 lines by extracting Tier 2 sections (`## Full` headings) to `references/`, providing 100 lines of headroom below the 500-line `body.max_lines` ceiling. Tier 1 sections always remain inline. If the body is already within budget, skip cleanly.
+
+## Rules
+
+- 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/
+- 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
+
+### §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`.
+
+```
+body_lines_before = body_line_count
+```
+
+**IF `body_line_count` <= 400:**
+- 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.
+
+### §2. Selective Shard — Tier 2 Extraction
+
+Identify 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).
+
+**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}`
+4. Replace the extracted section in SKILL.md with a cross-reference blockquote:
+   ```markdown
+   > See [Full API Reference](references/full-api-reference.md)
+   ```
+5. Re-count body lines
+6. **IF `body_line_count` <= 400:** stop extracting, proceed to §3
+
+Track: `sections_extracted: [{heading names}]`
+
+### §3. Tier 1 Preservation Check
+
+Verify ALL Tier 1 sections remain inline in SKILL.md after extraction. Check for 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)
+- `## 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)
+
+**IF any Tier 1 section is missing after extraction:**
+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
+```
+
+**IF `body_line_count` > 400 after all Tier 2 sections extracted:**
+- 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`
+
+### §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
+
+Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`
+
+Set context:
+- `auto_shard_triggered: true`
+- `sections_extracted: [{heading names}]`
+- `body_lines_before: {before}`
+- `body_lines_after: {after}`
+
+### §6. Auto-Proceed
+
+Load, read the entire file, then execute `{nextStepFile}`.

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

@@ -0,0 +1,109 @@
+---
+nextStepFile: 'validate.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 5c: Doc-Rot
+
+## 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.
+
+## Rules
+
+- Auto-proceed step — no user interaction required
+- Graceful skip — if no corrections are found in any feeder artifact, proceed without modification
+- Only modify the compiled SKILL.md (correction block insertion) and references (if corrections target referenced content)
+- Do not modify feeder artifacts (evidence-report.md, provenance-map.json, metadata.json) — this step READS them only
+- Do not modify frontmatter — correction blocks are body content only
+- Matching is case-insensitive substring grep — no semantic or AI-based assessment
+
+## MANDATORY SEQUENCE
+
+### §1. Locate Feeder Artifacts
+
+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:** `_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 `_bmad-output/{skill-name}/SKILL.md` itself — check for `[QMD:...]` or `[DOC:...]` annotations referencing corrections
+
+For each artifact, attempt to load its content. If an artifact does not exist or is empty, skip it — this is not an error.
+
+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.
+
+| Pattern | Category |
+|---------|----------|
+| `deprecated` | Deprecation |
+| `@deprecated` | Deprecation |
+| `breaking change` | Breaking change |
+| `BREAKING` | Breaking change |
+| `removed in` | Removal |
+| `was removed` | Removal |
+| `renamed to` | Rename |
+| `renamed from` | Rename |
+| `superseded by` | Supersession |
+| `replaced by` | Supersession |
+| `no longer supported` | End of life |
+| `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}]`
+
+**IF `correction_matches` is empty:**
+- 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)
+
+**ELSE:** Proceed to §3.
+
+### §3. Annotate SKILL.md with Correction Blocks
+
+For each entry in `correction_matches`, insert a `## CORRECTION` block into the compiled SKILL.md.
+
+**Block format:**
+
+```markdown
+## CORRECTION
+
+**Source:** {source}
+**Pattern:** {pattern}
+**Affected:** {affected}
+**Detail:** {context_line}
+```
+
+**Insertion rules:**
+- **After the relevant API section** in SKILL.md if the `affected` function or section can be identified and located in the document
+- **At the end of SKILL.md body** (before any trailing sections like `## Manual Sections`) if the affected section cannot be determined
+- **Never inside frontmatter** — body content only
+- Each correction block is self-contained with its own source citation
+- Multiple corrections produce multiple `## CORRECTION` blocks
+
+Store: `corrections_added: {count of blocks inserted}`
+
+### §4. Log Results
+
+Log: `"doc-rot: {corrections_added} correction blocks added from {feeder_artifacts_scanned_count} feeder artifacts"`
+
+Set context:
+- `doc_rot_triggered: true`
+- `corrections_added: {count}`
+- `feeder_artifacts_scanned: [{list}]`
+- `correction_matches: [{match records}]`
+
+### §5. Auto-Proceed
+
+Load, read the entire file, then execute `{nextStepFile}`.

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

@@ -0,0 +1,123 @@
+---
+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}. -->
+
+# Step 5a: Doc Sources
+
+## STEP GOAL:
+
+Record detected documentation pages and README with content hashes in metadata.json so that downstream audit (analyze-skill) can detect when upstream docs have changed since the skill was compiled.
+
+## Rules
+
+- Auto-proceed step — no user interaction required
+- Graceful failure — if doc detection fails, skip with a warning and proceed to validate
+- Do not modify any compiled artifact other than `metadata.json`
+- Do not block the pipeline on any doc detection error
+
+## MANDATORY SEQUENCE
+
+### 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 forge-auto pipeline).
+
+- **If upstream results exist:** use them directly, skip to step 3.
+- **If no upstream results:** continue to step 2.
+
+### 2. Run Doc Detection (if needed)
+
+Check that `{source_repo}` is available from the skill brief.
+
+**If `{source_repo}` is not available:**
+- Set `doc_detection_results` to an empty array `[]`
+- Add evidence note: `"Doc sources: detection skipped — no source_repo in brief"`
+- Skip to step 3.
+
+**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 {detectDocsHelper} \
+  --repo-url {source_repo} \
+  [--local-path {source_path}] \
+  [--skip-pages-api]
+```
+
+Pass `--local-path {source_path}` when a local clone exists from the extraction step to avoid redundant cloning for `docs/` folder detection.
+
+**Handle exit codes:**
+- **Exit 0** (found ≥1 doc): parse JSON stdout as `doc_detection_results`
+- **Exit 1** (none found): set `doc_detection_results` to empty array `[]`
+- **Exit 2** (error): set `doc_detection_results` to empty array `[]`, add evidence note: `"Doc sources: detection partial — skf-detect-docs.py error (exit 2)"`
+
+### 3. Ensure README Entry
+
+After obtaining detection results, check if any entry has a URL matching `*/README.md` or `*/readme.md`.
+
+**If a README entry already exists** from detection (e.g., `detected_via: "docs_folder"` found a README): keep it as-is.
+
+**If no README entry exists,** add one:
+
+- `url`: Construct from `{source_repo}/blob/main/README.md`
+- `detected_via`: `"readme_always"`
+- `content_hash`: Hash the README content using `sha256:{hexdigest}` convention:
+  - If `{source_path}` is available: read `{source_path}/README.md` locally with `encoding="utf-8"`, compute `sha256:{hexdigest}`
+  - Else: fetch via `gh api repos/{owner}/{repo}/readme --jq '.content'`, base64-decode, hash
+  - If README cannot be found or fetched: set `content_hash` to `null`
+- `recorded_at`: current ISO-8601 timestamp with timezone
+
+### 4. Build doc_sources Array
+
+Map each detection result to the `doc_sources` schema:
+
+```json
+{
+  "url": "{url from detection result}",
+  "detected_via": "{detected_via from detection result}",
+  "content_hash": "{content_hash from detection result — sha256:{hexdigest} or null}",
+  "recorded_at": "{current ISO-8601 timestamp with timezone}"
+}
+```
+
+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)
+- `recorded_at` ← generated at step execution time (ISO-8601 with timezone)
+
+Note: `content_type` from detect-docs output is NOT carried into `doc_sources`.
+
+### 5. Update metadata.json
+
+Read the staging `_bmad-output/{skill-name}/metadata.json` that compile (step 5) wrote.
+
+**If the staging metadata.json is unreadable:** HALT — this indicates compile failed (critical, not doc-detection-related).
+
+**Replace** the `doc_sources` field entirely (do not merge or append to stale data from prior compiles):
+
+```python
+metadata["doc_sources"] = new_doc_sources  # full replacement
+```
+
+Write the updated metadata.json back to the staging directory.
+
+Add evidence note summarizing the result:
+- Success: `"Doc sources: {N} detected, README tracked"`
+- Skip: `"Doc sources: detection skipped — {reason}"`
+- Partial: `"Doc sources: detection partial — {N} found, {errors}"`
+
+### 6. Auto-Proceed
+
+Load, read the entire file, then execute `{nextStepFile}`.

package/src/skf-create-skill/references/sub/fetch-docs.md

@@ -6,6 +6,12 @@ nextStepFile: '../enrich.md'
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# Resolve `{deriveAssemblyShapeHelper}` the same way — used in §1 to decide
+# whether this is a whole-language reference (registry-corpora prose retained
+# as a Language Guide) or a standard skill (unchanged behaviour).
+deriveAssemblyShapeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-derive-assembly-shape.py'
+  - '{project-root}/src/shared/scripts/skf-derive-assembly-shape.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -33,6 +39,14 @@ Evaluate the following conditions. **If the condition fails, skip silently to se
 
 No tier gate — if `doc_urls` are present, this step runs at Quick, Forge, and Deep tiers alike.
 
+**Determine assembly shape (whole-language gate).** Resolve `{deriveAssemblyShapeHelper}` from `{deriveAssemblyShapeProbeOrder}` (first existing path wins) and run it on the brief:
+
+```bash
+uv run {deriveAssemblyShapeHelper} {brief_path}
+```
+
+If the result's `assembly_shape` is `whole-language-reference` (the brief carries ≥1 `doc_urls` entry with `source: language-registry` — a compiler/interpreter repo enriched with the language's canonical prose), set the in-context flag `whole_language_reference: true`. This changes ONLY how the registry-sourced corpora are handled below (§4a): their prose is retained as a **Language Guide** rather than shredded into per-export items. For every other brief the flag is false and this step behaves exactly as before — no change to ordinary skills.
+
 ### 2. Security Notice
 
 Display an informational notice (not a gate — the user already approved these URLs in the brief):
@@ -122,6 +136,19 @@ Parse the successfully fetched markdown for:
 
 **No hallucination:** If information cannot be found in the fetched content, exclude it. Do not infer or fabricate API details.
 
+**Whole-language references — retain prose, do NOT shred (`whole_language_reference: true`):** For a whole-language reference the registry-sourced corpora (the guide/Book, the standard/library docs) ARE the product, not the compiler's internal exports. Reducing that prose to per-export signature items and then discarding it under the §5 "T3 never overrides T1" rule (the compiler's AST already owns names like `Vec`, `Option`, `HashMap`) would gut exactly the content the skill exists to teach. So for these briefs, skip §4a below for the registry corpora.
+
+### 4a. Retain the Language Guide (whole-language references only)
+
+**Skip this section entirely unless `whole_language_reference: true`.** When it is true, for each `doc_urls` entry whose `source` is `language-registry`:
+
+- Do NOT reduce its fetched markdown to per-export items. Instead retain the cleaned prose as a Language-Guide entry `{url, label, prose}`, where `prose` is the substantive body (narrative, idioms, usage examples, conceptual reference) lightly trimmed of navigation/boilerplate, each block cited `[EXT:{url}]`.
+- Collect these into a `language_guide[]` context artifact, in `doc_urls` order.
+
+This artifact is a **distinct** carrier — it is NOT merged into the extraction inventory and is NOT subject to the §5 conflict rule, so the canonical prose survives intact into step 5 (compile), which foregrounds it as the skill's Language Guide. Non-registry docs (README-detected, homepage, Pages, docs-folder) still flow through §4's normal per-export extraction and the §5 merge unchanged.
+
+**If a registry corpus could not be fetched** (network failure), record it in `language_guide[]` as `{url, label, prose: null}` and warn — step 5 surfaces the gap rather than emitting a thin guide silently.
+
 ### 5. Build Doc-Fetch Inventory
 
 **Mode determines merge behavior:**
@@ -131,6 +158,8 @@ Parse the successfully fetched markdown for:
 
 **Conflict rule:** T3 items NEVER override existing T1, T1-low, or T2 items for the same export. When an export already has a higher-confidence entry, the T3 item is discarded. T3 has the lowest priority.
 
+**Language-Guide carve-out:** the `language_guide[]` artifact from §4a (whole-language references) is NOT part of the export inventory and is therefore NOT subject to this conflict rule — it carries no export key, so it cannot collide with a T1 compiler export and can never be pruned. It is passed separately into step 5, which renders it as the foregrounded Language Guide section. Only the per-export T3 items participate in the T1/T2/T3 merge.
+
 **Edge case — T1-zero supplemental mode:** If T1 extraction produced zero results and `doc_urls` are present in supplemental mode, T3 items should be used as the primary inventory since no T1 data exists to conflict with.
 
 **Aggregate totals for reporting:**

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

@@ -17,6 +17,13 @@ atomicWriteProbeOrder:
 descriptionGuardProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-description-guard.py'
   - '{project-root}/src/shared/scripts/skf-description-guard.py'
+# Resolve `{frontmatterValidator}` by probing `{frontmatterValidatorProbeOrder}`
+# in order (installed SKF module path first, src/ dev-checkout fallback); first
+# existing path wins. §0's post-restore re-validation hook uses it; an installed
+# module has no src/ tree, so a bare src/ path would silently fail the hook.
+frontmatterValidatorProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-frontmatter.py'
+  - '{project-root}/src/shared/scripts/skf-validate-frontmatter.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -43,7 +50,7 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 
 Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — the calling sections (§2 and §4) invoke the helper at the capture and verify-restore points.
 
-**This skill's post-restore re-validation hook:** after `{descriptionGuardHelper}` reports `restored: true`, run `uv run {project-root}/src/shared/scripts/skf-validate-frontmatter.py <staging-skill-dir>/SKILL.md` and capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field, flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step 9 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
+**This skill's post-restore re-validation hook:** after `{descriptionGuardHelper}` reports `restored: true`, resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins), run `uv run {frontmatterValidator} <staging-skill-dir>/SKILL.md` and capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field, flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step 9 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
 
 ### 1. Check Tool Availability
 
@@ -199,7 +206,9 @@ tessl installs automatically via `npx`. A missing tool is not an error — grace
 
 **If §6 produced no novel suggestions (all dismissed via `{tesslDismissalData}`) OR tessl was unavailable:** Skip this gate — auto-proceed.
 
-**If §6 produced novel suggestions** (ones not matched by any dismissal rule), present them to the user:
+**GATE [default: S]** — If `{headless_mode}` is true AND §6 produced novel suggestions: auto-select [S] Skip (a headless run has no human to triage novel suggestions), record `"tessl suggestions: {N} novel suggestion(s) auto-skipped (headless)"` in the evidence report under "Dismissed tessl suggestions", log `"headless: auto-skip {N} novel tessl suggestion(s)"`, and append `{step: "validate", gate: "tessl-suggestions", decision: "S", value: "{N} novel auto-skipped", rationale: "headless mode — no human to triage novel tessl suggestions", timestamp: {ISO}}` to the in-context `headless_decisions[]` list (step 5 §7 reads it into the evidence-report `## Auto-Decisions` table). This is the one consequential auto-decision that drops human-relevant feedback, so it must leave an audit row rather than vanishing. Then auto-proceed to §7 — do NOT present the menu below.
+
+**If §6 produced novel suggestions** (ones not matched by any dismissal rule) AND `{headless_mode}` is false, present them to the user:
 
 "**Content quality review: {score}%**
 
@@ -228,7 +237,7 @@ tessl suggestions (novel — not matched by `{tesslDismissalData}`):
 Cross-check metadata.json against extraction inventory:
 - `stats.exports_documented` / `stats.exports_public_api` / `stats.exports_internal` / `stats.exports_total` are accurate
 - `stats.public_api_coverage` and `stats.total_coverage` are correctly computed (null when denominator is 0)
-- `confidence_distribution.t1`, `confidence_distribution.t1_low`, `confidence_distribution.t2`, `confidence_distribution.t3` match actual counts
+- `confidence_distribution.{t1, t1_low, t2, t3}` bin **per-export signature tiers** — each documented export lands in exactly one tier, so the four bins must **sum to `stats.exports_documented`**. Do NOT fold T2 annotation counts or T3 doc-item counts into the bins (a common error: binning ~8 annotations + ~80 doc items on top of 59 exports → sum 147 ≠ 59). `skf-test-skill` coverage-check §4b enforces this sum as an internal-consistency defect. Carve-outs mirror that consumer: for a **stack** skill the distribution bins constituents (sums to the constituent count, not `exports_documented`); for a **reference-app** it bins per-citation provenance entries (sums to the citation count, not `pattern_surfaces_documented`)
 - `spec_version` is "1.3"
 - If `scripts[]` or `assets[]` arrays present: verify `stats.scripts_count`/`stats.assets_count` match array lengths; verify `file_entries` count in provenance-map.json matches
 

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

@@ -62,9 +62,9 @@ Every HARD HALT in this workflow exits with a stable code so headless automators
 | Code | Meaning              | Raised by                                                                                    |
 | ---- | -------------------- | -------------------------------------------------------------------------------------------- |
 | 0    | success              | step 4 (terminal)                                                                           |
-| 2    | input-missing / input-invalid | step 1 §4 (headless missing `skill_name` arg) → `input-missing`; non-existent skill / unparseable version → `input-invalid` |
+| 2    | input-missing / input-invalid | step 1 §4 (headless missing `skill_name` arg) → `input-missing`; step 1 §4 (headless skill arg matches no listed skill) / step 1 §6 (headless version arg absent from the `versions` map) → `input-invalid` |
 | 3    | resolution-failure   | step 1 §2 (manifest is malformed JSON); step 1 §3 (no skills found anywhere)               |
-| 4    | write-failure        | On-Activation §3 pre-flight write probe (skills_output_folder unwritable); step 2 §2 (manifest write); step 2 §3 (context-file rewrite); step 2 §4 (directory delete) |
+| 4    | write-failure        | On-Activation §3 pre-flight write probe (skills_output_folder unwritable); step 2 §2 (manifest write → `manifest-write-failed`); step 2 §3 (context-file rewrite → `context-rebuild-failed`); step 2 §4 (full purge failure — every target directory failed to delete → `delete-failed`) |
 | 5    | state-conflict       | step 1 §7 (active-version-guard refuses to drop the active version while non-deprecated peers remain) |
 | 6    | user-cancelled       | step 1 §10 confirmation gate `[N]`; any prompt that accepted `cancel`/`exit`/`:q`; On-Activation §4 (`headless-purge-forbidden`) |
 

package/src/skf-drop-skill/references/execute.md

@@ -152,13 +152,15 @@ Report: "**Rebuilt managed sections in:** {list of updated files}. {if any faile
 
 ### 4. Delete Files (Purge Mode Only)
 
-**If `drop_mode != "purge"`**, skip this section entirely. Set `files_deleted = []` and `disk_freed = "N/A (soft drop)"`, then jump to section 5.
+**If `drop_mode != "purge"`**, skip this section entirely. Set `files_deleted = []`, `disk_freed = "N/A (soft drop)"`, `delete_failures = []`, and `purge_status = "success"`, then jump to section 5.
 
 **If `drop_mode == "purge"`:**
 
 1. Initialize `files_deleted = []` and `bytes_freed = 0`.
 
-2. For each directory path in `affected_directories`:
+2. Also initialize `delete_failures = []` to track paths whose deletion was attempted but did not succeed.
+
+3. For each directory path in `affected_directories`:
    a. Verify the path is inside either `{skills_output_folder}` or `{forge_data_folder}` (defense in depth against accidental deletion of unrelated paths)
    b. If the directory does not exist, record it as "(already absent)" and continue
    c. Compute the directory size in bytes before deletion (recursive sum)
@@ -166,23 +168,29 @@ Report: "**Rebuilt managed sections in:** {list of updated files}. {if any faile
    e. Verify deletion succeeded (the path no longer exists)
    f. Append the path to `files_deleted` and add its byte size to `bytes_freed`
 
-3. **Version-level purge, single version:**
+4. **Version-level purge, single version:**
    - `{skills_output_folder}/{target_skill}/{version}/` is deleted, but `{skills_output_folder}/{target_skill}/` remains (it still contains other versions or the `active` symlink)
    - If the `active` symlink pointed to the just-deleted version, update or remove it:
      - If other versions remain in the manifest for `{target_skill}`, repoint `active` to the manifest's current `active_version` (skipping deprecated)
      - If no non-deprecated versions remain, remove the `active` symlink (reachable only when dropping the sole surviving version, which in step 1 was permitted because no other non-deprecated versions existed)
 
-4. **Skill-level purge:**
+5. **Skill-level purge:**
    - `{skills_output_folder}/{target_skill}/` and `{forge_data_folder}/{target_skill}/` are deleted in full — the `active` symlink disappears with the parent directory
 
-5. Convert `bytes_freed` to a human-readable string for the final report (e.g. `"4.2 MB"`). Store as `disk_freed`.
+6. Convert `bytes_freed` to a human-readable string for the final report (e.g. `"4.2 MB"`). Store as `disk_freed`.
 
-**On deletion error:**
+**On deletion error (per path):**
 
-- Record which path failed and the error message
-- Continue attempting the remaining paths — partial purge is still better than no purge
+- Append the path and its error message to `delete_failures`
+- Continue attempting the remaining paths — a partial purge is still better than no purge
 - Report all failures at the end of this section
 
+**After the loop — classify the deletion outcome.** Let `attempted` be the number of paths in `affected_directories` that existed on disk (i.e. were not recorded as "(already absent)"):
+
+- **Full purge failure** — `attempted > 0` AND every attempted path is in `delete_failures` (nothing was deleted): the purge accomplished none of its destructive intent, so it must NOT report success. HALT (exit code 4, `halt_reason: "delete-failed"`): "**Purge failed** — none of the {attempted} target director(ies) could be deleted: {list each path with its error}. The manifest and context files were already updated in sections 2–3; the on-disk files remain and can be removed manually (`rm -rf {path}`)." In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with the resolved `skill`, `drop_mode`, `versions_affected`, `files_deleted: []`, and `manifest_updated` from section 2. Do not proceed to section 5.
+- **Partial purge failure** — `delete_failures` is non-empty but at least one path was deleted: keep record-and-continue. Set `purge_status = "partial"` so step 3's on-disk result record reflects it (the `output-contract-schema.md` `status` enum supports `"partial"`); proceed to section 5. The headless single-line envelope has no `"partial"` value in its enum, so it stays `"success"` while `context_files_failed`/`verification_errors`/the report surface the unfreed paths.
+- **No failures** — `delete_failures` is empty: set `purge_status = "success"` and proceed to section 5.
+
 ### 5. Verify Final State
 
 Run these verification checks:
@@ -203,6 +211,8 @@ Store the following for step 3:
 
 - `files_deleted` — list of directory paths actually deleted (purge mode) or `[]` (soft drop)
 - `disk_freed` — human-readable size (purge mode) or `"N/A (soft drop)"`
+- `delete_failures` — list of `{path, error}` for paths whose deletion was attempted but failed (empty if none; a *full* purge failure already HALTed in section 4 and never reaches this step)
+- `purge_status` — `"success"`, `"partial"` (some paths failed to delete), or `"success"` for soft drops; step 3 maps this to the on-disk result record's `status` field
 - `manifest_updated` — boolean (true if section 2 succeeded)
 - `context_files_updated` — list of successfully rebuilt files
 - `context_files_failed` — list of files that failed to rebuild (empty if none)
@@ -220,7 +230,8 @@ If any stage fails, record which stage failed and provide recovery guidance in t
 |--------------|-------------------|
 | Manifest update | "Manifest is in pre-drop state. Re-run the workflow once the underlying I/O issue is resolved. No files were deleted." |
 | Context file rebuild | "Manifest is already updated. Re-run `[EX] Export Skill` against any still-valid skill to regenerate the affected managed sections, or rerun the drop workflow." |
-| File deletion (purge) | "Manifest and context files are consistent. Remaining directories listed in the report can be deleted manually: `rm -rf {path}`." |
+| File deletion (purge — partial) | "Manifest and context files are consistent. Remaining directories listed in the report can be deleted manually: `rm -rf {path}`." (status `partial`) |
+| File deletion (purge — full) | "No target directory could be deleted. Manifest and context files are already updated; the on-disk files remain. HALT with `delete-failed` (exit 4) — re-run once the I/O issue is resolved, or remove the listed directories manually." |
 | Verification | "Execution completed but post-write checks found drift. See the report for specific paths requiring manual review." |
 
 ## CRITICAL STEP COMPLETION NOTE

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

@@ -73,6 +73,8 @@ These require manual review — see the error-handling guidance in step 2.
 
 Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/drop-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/drop-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all purged file paths in `outputs`; include `target_skill`, `drop_mode`, and `versions_affected` in `summary`.
 
+Set the record's `status` from step 2's `purge_status`: `"partial"` when some (but not all) purge-mode directories failed to delete — surface the failing paths from `delete_failures` in `summary.delete_failures` — otherwise `"success"`. A *full* purge failure never reaches this step: step 2 §4 HALTs with `halt_reason: "delete-failed"` and the error-envelope path below handles it.
+
 When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 4 (matches the SKILL.md "Result Contract (Headless)" shape):
 
 ```