bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -1,11 +1,13 @@
 ---
 nextStepFile: 'health-check.md'
-# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
-# (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves.
+# §2b copies the -latest result file to the stack group root with the
+# atomic writer; without it, §2b skips that copy with a warning.
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
@@ -18,76 +20,80 @@ Display the final summary of the forged stack skill with confidence distribution
 
 ## Rules
 
-- Do not write or modify any files — report is console output only
+- Write only the §2b result contract (the per-run record and its `-latest` copy in `{forge_version}/`, and the `-latest` copy at the stack group root), then delete the run folder (§3). The rest of the report is console output only
 - Lead with the positive summary, then details, then warnings
 - Recommend next workflows based on what was produced
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is NOT the terminal step
 
 ## MANDATORY SEQUENCE
 
+**Warnings.** Each `workflow_warnings[]` entry this step appends is recorded at once: write its `[{step}/{severity}] {code}: {message}` line to `{run_dir}/warning.txt` with a file write, then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/warning.txt")"`, resolving `{emitEnvelopeHelper}` from `{emitEnvelopeProbeOrder}` if it is not bound.
+
 ### 1. Report the Forge Result
 
 Surface the forge result to the console, leading with the win:
 
-- **Headline:** stack `{project_name}-stack` — `{lib_count}` libraries, `{integration_count}` integration patterns, forge tier `{tier}`.
-- **Confidence distribution:** the T1 / T1-low / T2 counts (T1 = AST-verified structural extraction, T1-low = source-reading inference, T2 = QMD-enriched temporal context). **In compose-mode**, note the tiers are inherited from the source skills — they reflect the extraction method used when those skills were originally generated, not the current compose run.
+- **Headline:** stack `{stack_name}`: `{lib_count}` libraries, `{integration_count}` integration patterns, forge tier `{tier}`.
+- **Confidence (libraries per tier, from `metadata.json` `confidence_distribution`):** T1 {n}, T1-low {n}, T2 {n}, T3 {n}. In code mode, T1 = an ast-grep rule matched every export and T1-low = at least one export was read by eye, or none was recorded. **In compose-mode**, each library keeps its constituent's own tier (`evidence_tier`), which reflects how that skill was generated, not the current compose run.
 - **Output files:** the `{skill_package}` deliverables (SKILL.md, context-snippet.md with `{token_estimate}` tokens, metadata.json, `references/` per-library files, and `references/integrations/` pair files when integrations exist), the `{forge_version}` workspace (provenance-map.json, evidence-report.md), and the `{skill_group}/active -> {version}` symlink.
 - **Validation:** all checks passed, or `{warning_count}` finding(s) each with its description.
-- **Warnings — only if `workflow_warnings[]` is non-empty:** the accumulated entries rendered as `[{step}/{severity}] {code}: {message}`. `workflow_warnings[]` (defined in SKILL.md's *Workflow state contract*) is the single sink surfacing every warning pushed during the run; if it is empty, omit this section.
+- **Warnings, only if `workflow_warnings[]` is non-empty:** each line of `{run_dir}/warnings.jsonl` decoded as the JSON string it holds, which is in the `[{step}/{severity}] {code}: {message}` form. That sink (SKILL.md's *Workflow state contract*) holds every warning recorded during the run; if it is empty, omit this section.
 
 ### 2. Recommend Next Workflows
 
 "**Next steps:**
-- **[TS] test-skill** — Validate the stack skill against its own assertions
-- **[EX] export-skill** — Package for distribution or agent loading
+- **[TS] test-skill**: Validate the stack skill against its own assertions
+- **[EX] export-skill**: Validate the package, write its context snippet and update the managed section in CLAUDE.md, AGENTS.md or .cursorrules
 
-- **[VS] verify-stack** — Validate the stack's integration feasibility against your architecture document{IF compose_mode:} (re-run to confirm feasibility after any architecture changes from **[RA] refine-architecture**){END IF}"
+- **[VS] verify-stack**: Validate the stack's integration feasibility against your architecture document{IF compose_mode:} (re-run to confirm feasibility after any architecture changes from **[RA] refine-architecture**){END IF}"
 
 ### 2b. Result Contract
 
-Write the result contract per `shared/references/output-contract-schema.md` using the shared atomic writer. Two artifacts — both written via `skf-atomic-write.py write`:
+The shared emitter writes the result contract (`shared/references/output-contract-schema.md`) and builds the success envelope in one call. Resolve the atomic writer first (see **Missing atomic writer** below), and `{emitEnvelopeHelper}` from `{emitEnvelopeProbeOrder}` if it is not bound. Stage `{run_dir}/result-context.json`:
+
+```json
+{"status": "success", "skill_package": "{skill_package}", "skill_name": "{stack_name}",
+ "stack_libraries": ["<library>"], "mode": "code|compose", "quality_score": null, "halt_reason": null,
+ "result_contract": {"skill": "skf-create-stack-skill", "status": "success",
+  "outputs": [{"type": "skill", "path": "{skill_package}/SKILL.md"},
+              {"type": "skill", "path": "{skill_package}/context-snippet.md"},
+              {"type": "skill", "path": "{skill_package}/metadata.json"},
+              {"type": "report", "path": "{forge_version}/evidence-report.md"}],
+  "summary": {"lib_count": 0, "integration_count": 0, "forge_tier": "<tier>", "confidence_tier": "<tier>",
+              "confidence_distribution": {}, "quality_score": null}}}
+```
 
-**Per-run record (inside the version dir):**
+`skill_package` is the absolute path to the committed package and `stack_libraries` the committed `metadata.json`'s `libraries`. Both `quality_score` fields are `{quality_score}`, the skill-check score step 8 §3 bound (`null` when skill-check did not run), never a test-skill score. The summary's counts, `confidence_tier` and `confidence_distribution` are the committed `metadata.json`'s `library_count`, `integration_count`, `confidence_tier` and `confidence_distribution`, and `forge_tier` its run tier. Then run:
 
 ```bash
-<json-content> | python3 {atomicWriteHelper} write \
-  --target {forge_version}/create-stack-skill-result-{YYYYMMDD-HHmmss}-{pid}-{rand}.json
+uv run {emitEnvelopeHelper} emit --workflow skf-create-stack-skill --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
 ```
 
-- `{YYYYMMDD-HHmmss}` is a UTC timestamp with seconds resolution.
-- Append `-{pid}-{rand}` (process id + short random suffix) to the filename to avoid same-second collisions when multiple runs land in the same second (S16).
+The emitter stamps `timestamp`, `run_id`, the run's auto-decisions and its warnings into the record, writes `create-stack-skill-result-<YYYYMMDD-HHmmss>.json` (it picks the name, with `-2` for a run that ends in the same second as another) and its `create-stack-skill-result-latest.json` copy in `{forge_version}`, and prints the success line on stdout: display it when `{headless_mode}` is true. A file it cannot write becomes a `result_file_write_failed` warning in the envelope, with `result_path` `null` when the per-run record is the one that failed. If the emitter exits non-zero, fix the payload its stderr names and run it once more; if it fails again, print its error and continue: the result contract is advisory and never halts the report.
 
-**Stable latest pointer (ABOVE the version dir, at the stack group root):**
+**Stable latest pointer at the stack group root.** Pipeline consumers read `{forge_data_folder}/{stack_name}/create-stack-skill-result-latest.json`, above the version folder, without knowing the current version. Copy the record there (a copy, not a symlink, so no consumer chases a link across version folders):
 
 ```bash
-<json-content> | python3 {atomicWriteHelper} write \
-  --target {forge_data_folder}/{project_name}-stack/create-stack-skill-result-latest.json
+python3 {atomicWriteHelper} write --target {forge_data_folder}/{stack_name}/create-stack-skill-result-latest.json < {forge_version}/create-stack-skill-result-latest.json
 ```
 
-- Note the path: the `-latest.json` lives at `{forge_data_folder}/{project_name}-stack/` (the stack group root), NOT inside `{forge_version}/`. Pipeline consumers read this stable path without knowing the current version.
-- Write the same JSON body as the timestamped record (this is a copy, not a symlink, so pipeline consumers never chase a link across version boundaries).
-
-Include `SKILL.md`, `context-snippet.md`, and `metadata.json` paths in `outputs`; include `lib_count`, `integration_count`, `forge_tier`, `confidence_tier`, and confidence distribution in `summary`.
-
-If either atomic write fails, log the error, leave any prior `-latest.json` untouched, and continue — the report is advisory and should not block the health-check chain.
+Skip the copy when the emitter printed no line, or when its envelope's `warnings` hold a `result_file_write_failed` entry naming `create-stack-skill-result-latest.json` or `{forge_version}` itself: the `-latest` file there may then hold an earlier run's record. If the copy is skipped or fails, print "The group-root copy of the result contract was not written: {the reason}", leave any prior group-root `-latest.json` untouched, and continue: §1 has already listed the warnings.
 
-**Headless success envelope.** When `{headless_mode}` is true, emit the single-line result envelope on **stdout** (the success counterpart to the error envelopes every HARD HALT emits on stderr) before chaining to step 10. `skill_package` is the absolute path to the committed package; `stack_libraries` is the included library names:
-
-```
-SKF_STACK_RESULT_JSON: {"status":"success","skill_package":"{skill_package}","skill_name":"{project_name}-stack","stack_libraries":["<lib>", "..."],"mode":"{code|compose}","exit_code":0,"halt_reason":null}
-```
+**Missing atomic writer.** Resolve `{atomicWriteHelper}` from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists, append `{step: "step-09", severity: "warn", code: "result-contract-skipped", message: "group-root result copy skipped: skf-atomic-write.py not found (re-install SKF)"}` to `workflow_warnings[]` before the emit, so the envelope and the result files carry it, print its message, since §1 has already listed the warnings, and make no group-root copy; any prior one stays untouched. The emitter still writes the result files in `{forge_version}`, so a missing writer never halts the report.
 
 ### 2c. Post-Completion Hook (optional)
 
-If `{onCompleteCommand}` (resolved at SKILL.md On Activation §3 from `workflow.on_complete`) is non-empty, invoke it now — after the result contract (§2b) is written, before chaining to health-check:
+If `{onCompleteCommand}` (resolved at SKILL.md On Activation §3 from `workflow.on_complete`) is non-empty, invoke it now, after §2b and before chaining to health-check:
 
 ```bash
 {onCompleteCommand}
 ```
 
-Run it with a bounded timeout (default 60s). On success, continue. On non-zero exit, timeout, or any failure, append the reason to `workflow_warnings[]` (e.g. `on_complete — failed (exit {N}): {stderr_first_line}`) and continue. **The hook must never fail the workflow** — it is integration glue (catalog registration, downstream pipeline notify) orthogonal to the forged stack. When `{onCompleteCommand}` is empty (bundled default), skip this section entirely.
+The hook runs even when §2b updated no `create-stack-skill-result-latest.json` (a failed write or emit); that file then still holds an earlier forge's record, if any.
+
+Run it with a bounded timeout (default 60s). On success, continue. On non-zero exit, timeout, or any failure, print one report line, `on_complete failed (exit {N}): {stderr_first_line}`, and continue: §1 has already listed the warnings and §2b has emitted the envelope, so that line is where the failure shows. **The hook must never fail the workflow**: it is integration glue (catalog registration, downstream pipeline notify) orthogonal to the forged stack. When `{onCompleteCommand}` is empty (bundled default), skip this section entirely.
 
 ### 3. Chain to Health Check
 
-After the report sections above are handled, 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.
+After the report sections above are handled, delete the run folder, whose warnings and decisions the envelope and the result files now hold: `rm -rf "{run_dir}"`. 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.
 

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

@@ -15,7 +15,8 @@ Validate all written output files against their expected structure and verify co
 
 ## Rules
 
-- Validate structure and completeness, not content quality — validation is read-only
+- Validate structure and completeness, not content quality
+- Only §3 writes to the committed package: `skill-check --fix` may rewrite `SKILL.md`, and a `body.max_lines` finding moves sections into `references/` (or runs `split-body --write`). Every other section leaves the package as step 7 committed it
 - Advisory mode: always proceed to report regardless of findings
 
 ## MANDATORY SEQUENCE
@@ -25,7 +26,7 @@ Validate all written output files against their expected structure and verify co
 Run the shared deterministic output validator once against the committed package — it checks the three core deliverable files' existence, SKILL.md frontmatter, and context-snippet format/token in a single call, so this step consumes its JSON rather than re-deriving those by hand. Resolve `{outputValidator}` from `{outputValidatorProbeOrder}` (first existing path wins). If neither candidate exists, log a WARNING (`"output validator unavailable — skf-validate-output.py missing"`) and fall back to the manual file/frontmatter/snippet checks below.
 
 ```bash
-python3 {outputValidator} {skill_package} --generated-by create-stack-skill --skill-type stack
+python3 {outputValidator} {skill_package} --generated-by create-stack-skill --skill-type stack --forge-tier {forge_tier}
 ```
 
 Consume from its JSON:
@@ -34,8 +35,9 @@ Consume from its JSON:
 - `validation.skill_md.frontmatter` — feeds the frontmatter check in §3 (manual-fallback path).
 - `validation.context_snippet.issues` — feeds §8.
 - `validation.stack_counts` — the stack count-equalities, derived deterministically from disk + metadata by the `--skill-type stack` pass: `issues[]` (each `{severity, field, message}`, one per mismatch of `library_count` / `integration_count` / `confidence_distribution`; empty when all agree) and `observed` (`library_count_meta`, `ref_file_count`, `integration_count_meta`, `pair_file_count`, `confidence_sum`). Feeds the count rows in §5 and the confidence-sum row in §7 — do not re-count files or re-sum the distribution by hand.
+- `validation.stack_structure`: the stack structure pass. The `check` of each `issues[]` entry (`{severity, check, field, message}`) names the section below that records it: `skill_md` (§4), `metadata` (§5), `references` (§6) or `tier_labels` (§7). Do not re-read the output files to check what it checks.
 
-**Under `--skill-type stack`, `validation.skill_md.body` and `validation.metadata` are emitted as `{"skipped": ...}` markers** — the *individual-skill* schema (which looks for `## Overview` / `Description` / `Key Exports` / `Usage` sections and a `source_repo` field) does not apply to a stack package, so the validator skips those passes and runs `validation.stack_counts` instead. Stack-shaped body structure and the remaining (non-count) metadata fields are checked in §4 / §5.
+Under `--skill-type stack` the validator skips the individual-skill body and metadata passes (their `{"skipped": ...}` markers are no finding) and runs these two instead. When §3 changes the package it runs this command again, and §4 to §8 read the latest run. When the validator is unavailable, §4 to §7 each record one **WARNING** finding that their checks did not run.
 
 Then confirm the remaining files the validator does not cover:
 
@@ -62,7 +64,7 @@ timeout 10s npx --no-install skill-check -h
 ```
 
 - If exits 0: Use skill-check for automated validation in sections 3, 9.
-- If exits non-zero, times out, or returns "command not found": Use manual fallback paths. Mark `metadata.validation_status: "manual-only"` (do this in step 7 when appropriate) and record every skipped check in the evidence report.
+- If exits non-zero, times out, or returns "command not found": Use manual fallback paths, append a `workflow_warnings[]` entry (`step: "step-08"`, `severity: "warn"`, `code: "skill-check-unavailable"`, `message: "skill-check unavailable: manual fallback checks used, security scan skipped"`) so step 9 does not report the run as skill-check validated, recording it at once (write its `[step-08/warn] skill-check-unavailable: {message}` line to `{run_dir}/warning.txt` with a file write, then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/warning.txt")"`), and list every skipped check in the §10 validation results.
 
 **Important:** Do not assume availability — empirical check required.
 
@@ -72,60 +74,39 @@ timeout 10s npx --no-install skill-check -h
 
 This validates frontmatter, description, body limits, links, formatting — and auto-fixes deterministic issues. Parse JSON for `scores[].score` (match the entry by `relativePath`/`skillId`; falls back to a top-level `qualityScore` on older skill-check builds), `diagnostics[]`, `fixed[]`.
 
-**Post-fix provenance drift guard (S15):** If `fixed[]` is non-empty, `skill-check --fix` has modified `SKILL.md` after step 7 wrote it — so the `metadata.json` hashes/provenance recorded against the pre-fix body may now be stale. Emit a **WARNING** finding listing each auto-fix (`"skill-check --fix modified SKILL.md: {fix_description} — metadata.json hashes/provenance may be out of date"`) rather than silently accepting the fixes, so the drift is surfaced. If the caller wants authoritative metadata, they should re-run the workflow.
-
-**If `body.max_lines` reported**, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 content inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). For a stack capstone the canonical split is the catalog (`Library Reference Index` + `Per-Library Summaries`) → `references/stack-catalog.md`, leaving an inline pointer (see `{stackSkillTemplatePath}` "Sizing Guidance"). This is the **intended** large-stack layout, not a violation: §4 below accepts the pointer form, so clearing the skill-check body ERROR this way does not also trip the structure check. Fall back to `npx skill-check split-body <skill-dir> --write` if not feasible. Verify any in-SKILL.md anchor links (e.g. to the catalog/pointer or other moved sections) still resolve after the split. Then re-validate.
+Bind `{quality_score}` ← that score, from the latest skill-check run (§3 runs it again after a split); `{quality_score}` is null when skill-check is unavailable. It is the skill-check score, not a test-skill score, and step 9 puts it in the result envelope and the result contract.
 
-**If unavailable**, do not hand-walk the frontmatter — use `validation.skill_md.frontmatter` from the §1 output-validator run, which checks delimiters, `name` format + directory match (`{project_name}-stack`), `description` presence/length, and unknown fields against the agentskills.io allow-set. Record each reported issue at its severity as a **WARNING** finding. (If the output validator was *also* unavailable in §1, fall back to the manual checklist: `---` delimiters; `name` lowercase-alphanumeric-plus-hyphens 1-64 chars matching `{project_name}-stack`; `description` present and 1-1024 chars; only `name`/`description`/`license`/`compatibility`/`metadata`/`allowed-tools` permitted.) Invalid frontmatter will fail `npx skills add` and `npx skill-check check`.
+**Post-fix provenance drift guard (S15):** If `fixed[]` is non-empty, `skill-check --fix` has modified `SKILL.md` after step 7 wrote it — so the `metadata.json` hashes/provenance recorded against the pre-fix body may now be stale. Emit a **WARNING** finding listing each auto-fix (`"skill-check --fix modified SKILL.md: {fix_description} — metadata.json hashes/provenance may be out of date"`) rather than silently accepting the fixes, so the drift is surfaced. If the caller wants authoritative metadata, they should re-run the workflow.
 
-### 4. Validate SKILL.md Body Structure
+**If `body.max_lines` reported**, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 content inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). For a stack capstone the canonical split is the catalog (`Library Reference Index` + `Per-Library Summaries`) → `references/stack-catalog.md`, leaving an inline pointer (see `{stackSkillTemplatePath}` "Sizing Guidance"). The moved catalog's links resolve from `references/`, so rewrite each `[ref](references/{name}.md)` in it to `[ref]({name}.md)`. This is the **intended** large-stack layout, not a violation: §4 below accepts the pointer form, so clearing the skill-check body ERROR this way does not also trip the structure check. Fall back to `npx skill-check split-body <skill-dir> --write` if not feasible. After the split, verify that any in-SKILL.md anchor links (e.g. to the catalog/pointer or other moved sections) still resolve, and that every link inside a moved section resolves from its new file.
 
-Load `{stackSkillTemplatePath}` and verify SKILL.md contains expected sections:
+**Re-validate a changed package.** When `fixed[]` is non-empty or a split ran, run the §1 `{outputValidator}` command again (after a split, skill-check too), so §4 to §8 record the package as it now stands.
 
-- [ ] Header with project name, library count, integration count, forge tier
-- [ ] Integration Patterns section (before per-library summaries)
-- [ ] Conventions section
-- [ ] **Catalog** — `Library Reference Index` table + `Per-Library Summaries`, in **either** form:
-  - *Inline* (small stacks): both sections present in SKILL.md, **or**
-  - *Pointer* (large stacks): a `Library Catalog` pointer to `references/stack-catalog.md`, **and** that file exists and contains both sections.
+**If unavailable**, do not hand-walk the frontmatter: use `validation.skill_md.frontmatter` from the §1 output-validator run, which checks delimiters, `name` format + directory match (`{stack_name}`), `description` presence/length, and unknown fields against the agentskills.io allow-set. Record each reported issue at its severity as a **WARNING** finding. (If the output validator was *also* unavailable in §1, fall back to the manual checklist: `---` delimiters; `name` lowercase-alphanumeric-plus-hyphens 1-64 chars matching `{stack_name}`; `description` present and 1-1024 chars; only `name`/`description`/`license`/`compatibility`/`metadata`/`allowed-tools` permitted.) Invalid frontmatter will fail `npx skills add` and `npx skill-check check`.
 
-  Accept either form — do not WARN when the catalog has been extracted to clear the `body.max_lines` budget (§3). Only record a **WARNING** when *neither* the inline sections *nor* a pointer-plus-`stack-catalog.md` is present, or when the pointer's target file is missing.
+### 4. Validate SKILL.md Body Structure
 
-Record other missing sections (Header, Integration Patterns, Conventions) as **WARNING** findings.
+Record each `validation.stack_structure.issues[]` entry whose `check` is `skill_md` as a **WARNING** finding. The catalog's pointer form (a `## Library Catalog` section linking `references/stack-catalog.md`) is the intended large-stack layout (§3), not a violation.
 
 ### 5. Validate metadata.json Fields
 
-Parse metadata.json and verify required fields:
-
-- [ ] `skill_type` equals "stack"
-- [ ] `name` matches `{project_name}-stack`
-- [ ] `version` and `generation_date` present
-- [ ] `forge_tier` is present and matches the forge tier from step 01 (`Quick|Forge|Forge+|Deep`)
-- [ ] `confidence_tier` is present and is exactly one of `T1|T1-low|T2|T3` — the dominant T-code computed from `confidence_distribution` (pick the tier with the highest count; ties resolve to the weaker tier: T1-low > T1, T2 > T1-low, T3 > T2 for tie-break so the reported tier never overstates confidence)
-- [ ] `libraries` array present and non-empty
-- [ ] `confidence_distribution` object present with `t1`, `t1_low`, `t2`, `t3` keys (lowercase, matching template definition)
+Record each `validation.stack_structure.issues[]` entry whose `check` is `metadata` as a **WARNING** finding.
 
-**Count equalities (library / integration)** — do NOT re-count files here; take them from `validation.stack_counts` in the §1 output-validator run (invoked with `--skill-type stack`), which derived them deterministically from disk. The `library_count` vs per-library reference files and `integration_count` vs integration pair files checks surface as `field: "library_count"` / `field: "integration_count"` entries in `validation.stack_counts.issues[]` (absent when they agree); echo the exact numbers from `validation.stack_counts.observed` (`library_count_meta` / `ref_file_count`, `integration_count_meta` / `pair_file_count`). The `confidence_distribution`-sum equality is covered in §7.
+**Count equalities (library / integration):** do NOT re-count files here; take them from `validation.stack_counts` in the latest output-validator run (§1, or §3's re-run), which derived them deterministically from disk. The `library_count` vs per-library reference files and `integration_count` vs integration pair files checks surface as `field: "library_count"` / `field: "integration_count"` entries in `validation.stack_counts.issues[]` (absent when they agree); echo the exact numbers from `validation.stack_counts.observed` (`library_count_meta` / `ref_file_count`, `integration_count_meta` / `pair_file_count`). The `confidence_distribution`-sum equality is covered in §7.
 
-Record each `validation.stack_counts.issues[]` count entry (`library_count` / `integration_count`) and any other mismatch above as **WARNING** findings.
+Record each `validation.stack_counts.issues[]` count entry (`library_count` / `integration_count`) as a **WARNING** finding.
 
 ### 6. Validate Reference File Completeness
 
-For each confirmed library, verify `references/{library}.md` contains: library name header, version from manifest (**in compose-mode**: version from source skill metadata), Key Exports section, Usage Patterns section.
-
-For each integration pair, verify `references/integrations/{libraryA}-{libraryB}.md` contains: integration pair header, type classification, Integration Pattern section, Key Files section.
-
-Record missing or incomplete files as **WARNING** findings.
+Record each `validation.stack_structure.issues[]` entry whose `check` is `references` as a **WARNING** finding.
 
 ### 7. Validate Confidence Tier Labels
 
-Scan all output files for confidence tier coverage:
+Record each `validation.stack_structure.issues[]` entry whose `check` is `tier_labels` as a **WARNING** finding.
 
-- [ ] SKILL.md: each per-library summary and integration pair entry has a confidence label
-- [ ] Reference files: each has a confidence label in its header
-- [ ] metadata.json: `confidence_distribution` sums to `library_count` — take this from the §1 output-validator run (`--skill-type stack`): the `field: "confidence_distribution"` entry in `validation.stack_counts.issues[]` is present only on mismatch, with `validation.stack_counts.observed.confidence_sum` vs `library_count_meta` for the exact numbers. Do not re-sum the distribution by hand.
+- [ ] metadata.json: `confidence_distribution` sums to `library_count`: take this from the latest output-validator run (`--skill-type stack`): the `field: "confidence_distribution"` entry in `validation.stack_counts.issues[]` is present only on mismatch, with `validation.stack_counts.observed.confidence_sum` vs `library_count_meta` for the exact numbers. Do not re-sum the distribution by hand.
 
-Record missing tier labels and any `validation.stack_counts` `confidence_distribution` issue as **WARNING** findings.
+Record the `validation.stack_counts` `confidence_distribution` issue, if any, as a **WARNING** finding.
 
 ### 8. Validate context-snippet.md
 

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

@@ -1,6 +1,6 @@
 ---
 name: skf-drop-skill
-description: Drop a specific skill version or an entire skill — soft (deprecate) or hard (purge) with platform context rebuild. Use when the user requests to "drop" or "remove a skill."
+description: Deprecates or purges a skill version or a whole skill, then rebuilds the platform context files. Use when the user requests to "drop a skill" or "remove a skill".
 ---
 
 # Drop Skill
@@ -12,12 +12,13 @@ Drops a specific skill version or an entire skill, either as a soft deprecation
 ## 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.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` holds its helpers (`dir-sizes.py`, `drop-roster.py`).
 - `{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.
-- **Module-level path exception:** paths starting with `knowledge/` or `shared/` resolve from the SKF module root, not the skill root — install layout puts both at `{project-root}/_bmad/skf/`. The `versionPathsKnowledge: 'knowledge/version-paths.md'` frontmatter scalar in stage files uses this convention; same for `shared/health-check.md` chained from the terminal step.
-- **Cross-skill data coupling:** `references/execute.md` reads `skf-export-skill/assets/managed-section-format.md` for the IDE→context-file mapping table and the four-case (Create / Append / Regenerate / Malformed) logic when rebuilding context files. Drop-skill assumes that asset is present at install time and that its semantics are stable across the two skills' versions.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
+- **Shared context-file rebuild:** `references/select.md` and `references/execute.md` resolve the context files and rebuild their managed sections through `shared/scripts/skf-rebuild-managed-sections.py`, the helper export-skill writes them with, so the three skills that write the section produce the same bytes from one IDE mapping. `skf-export-skill/assets/managed-section-format.md` documents that format.
 
 ## Role
 
@@ -29,8 +30,9 @@ These rules apply to every step in this workflow:
 
 - Never delete files in purge mode without clearing the §10 confirmation gate (auto-resolved with its default in headless)
 - Never drop an active version when other non-deprecated versions exist — enforce the active version guard
+- Never purge content SKF did not generate: select.md §8b takes the purge verdict for the skill folder and its forge folder from the inventory helper; a forge folder SKF did not generate is left in place, and a purge SKF cannot check is refused
 - Only load one step file at a time — never preload future steps
-- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread, with two exceptions. A helper On-Activation §4 resolves is never replaced by hand (a missing one halts the run before the first prompt): never type an envelope or edit the manifest or a context file yourself. And never decide by hand whether SKF generated a folder: without the inventory helper, select.md offers manifest skills only and refuses every purge
 - Always communicate in `{communication_language}`
 - At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
@@ -46,72 +48,47 @@ These rules apply to every step in this workflow:
 
 ## Invocation Contract
 
-| Aspect | Detail |
-|--------|--------|
-| **Inputs** | skill_name [required], mode (deprecate/purge) [required], version (all/specific) [required] |
-| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--dry-run` (run selection + display the §10 confirmation block, then exit with `status="dry-run"` — no manifest mutation, no file deletion). Useful for "show me what this would touch before I commit." |
-| **Gates** | step 1: Input Gate [use args], Confirm Gate [Y] |
-| **Outputs** | Updated manifest, rebuilt context files, (purge: deleted directories), `drop-skill-result-{timestamp}.json` and `drop-skill-result-latest.json` |
-| **Headless** | Gates auto-resolve with their default action (see Workflow Rules). When `forbid_purge_in_headless` is `"true"` in `customize.toml` AND the effective drop mode is `"purge"` (defined in On-Activation §4 — explicit `mode=purge` or `default_mode` purge), §4 HALTs with exit code 6 (`halt_reason: "headless-purge-forbidden"`) before any work begins. |
-| **Exit codes** | See "Exit Codes" below |
-
-## Exit Codes
-
-Every hard HALT exits with a stable code so headless automators branch on the failure class without grepping message text. The `Raised by` column names the HALT class per code; the authoritative per-site declarations (with exact `halt_reason`) live in the step files.
-
-| Code | Meaning              | Raised by (class) |
-| ---- | -------------------- | ----------------- |
-| 0    | success              | step 4 (terminal) |
-| 2    | input-missing / input-invalid | step 1 headless input gates — missing or unmatched `skill_name`, `version`, or `--mode` value (§4 / §6 / §8) |
-| 3    | resolution-failure   | step 1 manifest/skill-list resolution (§2 corrupt manifest, §3 nothing to drop) |
-| 4    | write-failure        | On-Activation write probe; step 2 manifest write / context rebuild / full-purge failure |
-| 5    | state-conflict       | step 1 active-version guard (§7) |
-| 6    | user-cancelled       | any interactive cancel or confirm-gate `[N]`; On-Activation headless-purge guard |
-
-## Result Contract (Headless)
-
-When `{headless_mode}` is true, step 3 emits a single-line `SKF_DROP_SKILL_RESULT_JSON:` envelope on **stdout**; every HARD HALT emits the same shape on **stderr** with `status: "error"`. The template, `status`/`halt_reason` semantics, `exit_code` (per the Exit Codes table above), and full enum live in `references/headless-contract.md` — the emitting stages load it directly, so an error path never depends on this file.
+Headless callers and pipelines: the inputs, flags, gate map, exit codes and `SKF_DROP_SKILL_RESULT_JSON` envelope live in `references/invocation-contract.md`. Interactive runs do not need it.
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
-   - `snippet_skill_root_override` (optional string) — when set, the context-file rebuild in step 2 preserves any snippet `root:` prefix that matches the override instead of rewriting it to the target IDE's skill root. See `skf-export-skill/assets/managed-section-format.md` for full semantics.
-   - Generate and store `timestamp` as `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run.
+   - `snippet_skill_root_override` (optional string): when set, the context-file rebuild in step 2 passes it to `assemble` as `--skill-root-override`, so every row's `root:` takes it instead of the target IDE's skill root. See `skf-export-skill/assets/managed-section-format.md` for full semantics.
 
 2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
 3. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-drop-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. Keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran): the run folder does not exist yet, so step 4 records it.
 
-   - `{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)
+   Bind each scalar to its bundled default when the merged value is empty or absent:
 
-   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 scalar.
+   - `{forbidPurgeInHeadless}` ← on when `workflow.forbid_purge_in_headless` holds any value other than the empty string (a TOML `true`, `false` or `"false"` included), else off
+   - `{onCompleteCommand}` ← `workflow.on_complete`, else empty (step 3 then runs no hook)
 
-   Apply the scalar fallback now so stage files don't have to repeat the conditional logic. For each of the five scalars, if the merged value is empty or absent, the bundled default applies:
+   Also apply the array surfaces: run `workflow.activation_steps_prepend` now, keep `workflow.persistent_facts` as standing context (`file:` entries load their contents: the bundled default loads every `project-context.md` under `{project-root}`; an entry prefixed `!` drops each earlier entry it names and loads nothing itself, so an override's `"!file:{project-root}/**/project-context.md"` turns that default off), then run `workflow.activation_steps_append` after.
 
-   - `{defaultMode}` ← `workflow.default_mode` (empty = always prompt; `"deprecate"` or `"purge"` = skip §8 Ask Mode)
-   - `{forbidPurgeInHeadless}` ← `workflow.forbid_purge_in_headless` (empty or non-`"true"` = no guard)
-   - `{unknownIdeDefaultContextFile}` ← `workflow.unknown_ide_default_context_file` if non-empty, else `AGENTS.md`
-   - `{unknownIdeDefaultSkillRoot}` ← `workflow.unknown_ide_default_skill_root` if non-empty, else `.agents/skills/`
-   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — step 3 skips the post-drop hook entirely)
+4. **Pre-flight: helpers, run folder, write probe and headless-purge guard.** All of it runs before the first prompt, so a broken install or a read-only folder stops the run before the user answers anything. Each HALT below names its exit code, `halt_reason` and phase: in headless mode it prints its envelope as the Halt Envelope section of `references/invocation-contract.md` says, and an interactive HALT displays its message only.
+
+   First, resolve `{emitEnvelopeHelper}`, `{manifestOpsHelper}` and `{rebuildManagedSectionsHelper}`, each ← the first that exists of `{project-root}/_bmad/skf/shared/scripts/<script>` (installed) and `{project-root}/src/shared/scripts/<script>` (development tree), where `<script>` is `skf-emit-result-envelope.py`, `skf-manifest-ops.py` and `skf-rebuild-managed-sections.py` in turn. Then create the run folder for the envelope payloads, and bind `{run_dir}` ← the path it prints (step 3, a `--dry-run` at the confirmation gate, or an interactive HALT in step 1 or 2 deletes it; any other HALT keeps it):
+
+   ```bash
+   mkdir -p "{project-root}/_bmad-output/.skf-run" && mktemp -d "{project-root}/_bmad-output/.skf-run/skf-drop-skill-XXXXXXXX"
+   ```
 
-   Stash all five as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+   If the run folder cannot be created, HALT (exit code 4, `halt_reason: "write-failed"`, phase `on-activation:run-folder`): "SKF cannot create its run folder under `{project-root}/_bmad-output/.skf-run/`: {the first stderr line}. Nothing was changed."
 
-   Also apply the array surfaces: run `workflow.activation_steps_prepend` now, keep `workflow.persistent_facts` as standing context (`file:` entries load their contents), then run `workflow.activation_steps_append` after.
+   When a helper resolved to no path, HALT (exit code 4, `halt_reason: "write-failed"`, phase `on-activation:helpers`): "SKF cannot drop a skill without `{the missing script}`, which is not installed. Nothing was changed. Re-install SKF." A `--dry-run` stops here too.
 
-4. **Pre-flight write probe + headless-purge guard.**
+   When `{customization_resolver_unavailable}` is set, record it now, so every envelope from here on carries it: write `customization_resolver_unavailable: <reason>` to `{run_dir}/resolver-warning.txt` with a file write (a resolver error can hold quotes or `$( )`, so never echo it or type it into an argument), then run `uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "$(cat "{run_dir}/resolver-warning.txt")"` from `{project-root}`.
 
-   First, verify `{skills_output_folder}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at step 2's manifest write — by then the user has already gone through every selection prompt:
+   Next, check that `{skills_output_folder}` is writable:
 
    ```bash
    mkdir -p "{skills_output_folder}" && \
@@ -119,8 +96,8 @@ When `{headless_mode}` is true, step 3 emits a single-line `SKF_DROP_SKILL_RESUL
      rm "{skills_output_folder}/.skf-write-probe"
    ```
 
-   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, emit the error envelope per **Result Contract (Headless)** with `skill: null` and `drop_mode: null` (neither is resolved yet at activation time).
+   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`, phase `on-activation:write-probe`, path `{skills_output_folder}`): "SKF cannot write to `{skills_output_folder}`: {the first stderr line}. Nothing was changed."
 
-   Second, enforce the headless-purge guard. First compute the **effective drop mode**: it is `"purge"` when the parsed `mode` arg is `"purge"`, OR when no `mode` arg was passed AND `{defaultMode}` (resolved in §3) is `"purge"` — a purge reached via `default_mode` is still an unattended irreversible purge and must be caught here, not only an explicit `--mode purge`. If `{headless_mode}` is true AND `{forbidPurgeInHeadless}` is `"true"` AND the effective drop mode is `"purge"`: HALT with exit code 6 and `halt_reason: "headless-purge-forbidden"`, emit the error envelope, and exit immediately. The operator must re-run with an explicit `mode=deprecate` (an explicit arg overrides `default_mode`) or set `forbid_purge_in_headless = ""` (or omit the override entirely) to proceed.
+   Last, the headless-purge guard. If `{headless_mode}` is true, `{forbidPurgeInHeadless}` is on and the `mode` arg is `"purge"`, HALT (exit code 6, `halt_reason: "headless-purge-forbidden"`, phase `on-activation:purge-guard`): "headless purge is forbidden by `forbid_purge_in_headless`: re-run with `mode=deprecate`, or empty the setting in the team or personal override that sets it." A draft skill cannot be deprecated, so it needs an interactive run or the guard off; select.md §8 purges a draft headless only on `mode=purge`, so this guard covers that purge too.
 
 5. Load, read the full file, and then execute `references/select.md` to begin the workflow.

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

@@ -10,15 +10,18 @@
 #   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 (audit-log emit,
-# ticket-reference enforcement) that must precede any destructive work.
+# Steps to run once On Activation has loaded config.yaml and resolved this
+# customization, before its pre-flight (helper check, run folder, write
+# probe and headless-purge guard) and before the first prompt. Overrides
+# append. Use for org-wide checks (audit-log emit, ticket-reference
+# enforcement) that must precede any destructive 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.
+# Steps to run right after the prepend steps and the persistent facts,
+# still before the pre-flight: a run that then HALTs on a missing helper,
+# an unwritable folder or the headless-purge guard has already run them.
+# Overrides append. Use for context loads or banner customization.
 
 activation_steps_append = []
 
@@ -26,42 +29,53 @@ activation_steps_append = []
 # (drop-policy reminders, retention guardrails, audit-trail rules).
 # Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "Purges of skills tagged `compliance` require ticket reference."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/drop-policy.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-drop-skill.toml:
+#   [workflow]
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
-# Optional post-drop hook. When non-empty, invoked with
-# `--result-path=<path>` after the drop-skill result JSON is finalized
-# (references/report.md). Failures are logged to workflow_warnings[] but
-# never fail the workflow — useful for audit-log emit, a notifier, or a
-# ticket-tracker integration after an irreversible purge.
+# Optional post-drop hook: a shell command, run as
+# `<command> --result-path=<path>` once step 3 (references/report.md) has
+# written the drop's result record. It runs only after a drop whose record
+# the emitter wrote (report.md skips it when `result_path` is null), so a
+# dry run, a HALT or a failed record write never calls it. A hook that
+# exits non-zero is shown as a line of its own and never fails the drop,
+# which may already be irreversible. Useful for an audit-log emit, a
+# notifier or a ticket-tracker update after a purge.
 
 on_complete = ""
 
-# --- Optional safety + default scalars ---
+# --- Optional safety scalar ---
 #
-# Default drop mode. Empty string = always prompt the user at §8 Ask Mode.
-# Set to "deprecate" or "purge" to skip the prompt — the headless
-# auto-decision log records the override source.
-
-default_mode = ""
-
-# Hard-block hard-purge in headless mode. When set to "true", a headless
-# invocation with `mode=purge` HALTs at activation with exit code 6
-# (`halt_reason: "headless-purge-forbidden"`) instead of silently deleting
-# files. Operators must either re-run with `mode=deprecate` or unset this
-# flag for that run. Empty string = no guard (default).
+# Block a purge in headless mode. Any value other than the empty string
+# turns the guard on ("true", a TOML true, and even "false" or false), so a
+# mistyped value that still parses blocks the purge rather than allowing it.
+# An override file that fails to parse (an unquoted True, yes or on, or a
+# bad line elsewhere in it) stops the resolver: the run warns
+# customization_resolver_unavailable and uses this file alone, so the guard
+# is off. Quote the value, as in "true". In
+# {project-root}/_bmad/custom/skf-drop-skill.toml (or .user.toml) write it
+# under the table, as two lines: `[workflow]` then
+# `forbid_purge_in_headless = "true"`. A key above the `[workflow]` line is
+# ignored without a warning, which leaves the guard off. With the guard
+# on, a headless run with `mode=purge` HALTs at activation with exit code 6
+# (`halt_reason: "headless-purge-forbidden"`) instead of deleting files:
+# re-run with `mode=deprecate`, or interactively. A draft skill with no
+# manifest entry cannot be deprecated, so it needs an interactive run or
+# the guard off. The drop mode has no default: every run passes `mode` or
+# answers the prompt. Empty string = no guard (default).
 
 forbid_purge_in_headless = ""
-
-# Fallback IDE → context-file mapping for unknown IDEs in `config.yaml.ides`.
-# Empty string = use bundled defaults (AGENTS.md / .agents/skills/).
-
-unknown_ide_default_context_file = ""
-unknown_ide_default_skill_root = ""