bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/{workflows/create-stack-skill → skf-create-stack-skill}/steps-c/step-06-compile-stack.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-06-compile-stack'
-description: 'Compile SKILL.md with integration layer and present for user review'
-
 nextStepFile: './step-07-generate-output.md'
-stackSkillTemplate: '../data/stack-skill-template.md'
+stackSkillTemplate: 'assets/stack-skill-template.md'
 ---
 
 # Step 6: Compile Stack Skill
@@ -12,40 +9,11 @@ stackSkillTemplate: '../data/stack-skill-template.md'
 
 Assemble the main SKILL.md by combining per-library extractions with the integration layer, and present for user review before writing output files.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are an integration architect operating in Ferris Architect mode
-- ✅ The integration layer is the VALUE — not just concatenated library docs
-- ✅ Zero hallucination — only include content backed by extraction evidence
-
-### Step-Specific Rules:
-
-- 🎯 Compile SKILL.md following the stack-skill-template structure
-- 🚫 FORBIDDEN to write output files — that is step 07
-- 💬 Present compiled content for user review (Gate 2)
-- 🎯 Integration patterns go FIRST — they are the primary value
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Load stack-skill-template.md for section structure
-- 💾 Store compiled skill_content as workflow state
-- 📖 Wait for user review and approval before proceeding
-- 🚫 FORBIDDEN to proceed without user confirming the compilation
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- From step 04: per_library_extractions[] with exports, patterns, confidence
-- From step 05: integration_graph with pairs, types, hub libraries, cross-cutting patterns
-- This step produces: skill_content (compiled SKILL.md ready for writing)
-- User interaction: Gate 2 — compile checkpoint required
+- Compile SKILL.md following the stack-skill-template structure — integration patterns go first (primary value)
+- Do not write output files (Step 07)
+- Present compiled content for user review
 
 ## MANDATORY SEQUENCE
 
@@ -72,7 +40,7 @@ description: >
 
 **Frontmatter rules:**
 
-- `name`: lowercase alphanumeric + hyphens only, must match skill output directory name. Prefer gerund form (`processing-pdfs`) for clarity.
+- `name`: lowercase alphanumeric + hyphens only, must match skill output directory name. **Stack skills MUST end in `-stack`** (e.g., `{project_name}-stack`) — this is how consumers (skf-verify-stack, skf-test-skill) detect stack vs individual skills.
 - `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can...").
 - No other frontmatter fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec
 
@@ -154,6 +122,7 @@ Display: **Select:** [C] Continue to Output Generation
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting compilation
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve stack compilation"
 - ONLY proceed to next step when user approves and selects 'C'
 
 #### Menu Handling Logic:
@@ -161,25 +130,3 @@ Display: **Select:** [C] Continue to Output Generation
 - IF C: Store skill_content, then load, read entire file, then execute {nextStepFile}
 - IF Any other: Process as feedback, adjust compilation, redisplay preview, then [Redisplay Menu Options](#8-present-menu-options)
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- SKILL.md follows stack-skill-template structure
-- Integration layer presented FIRST (primary value)
-- All content includes confidence tier labels
-- Per-library sections ordered by connectivity
-- User reviewed and approved compilation
-- skill_content stored for step 07
-
-### ❌ SYSTEM FAILURE:
-
-- Integration layer missing or buried below library listings
-- Content without confidence tier labels
-- Proceeding without user review (Gate 2)
-- Writing files in this step (step 07's job)
-- Fabricating integration patterns not from step 05
-
-**Master Rule:** Integration layer is the value. Present it first, get user approval before writing.

package/src/skf-create-stack-skill/steps-c/step-07-generate-output.md

@@ -0,0 +1,328 @@
+---
+nextStepFile: './step-08-validate.md'
+stackSkillTemplate: 'assets/stack-skill-template.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 — stage/commit/flip-link/write below
+# MUST go through the atomic helper, per §1 rollback contract.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+---
+
+# Step 7: Generate Output Files
+
+## STEP GOAL:
+
+Write all deliverable and workspace artifact files to their target directories.
+
+## Rules
+
+- Write all output files in correct directory structure — do not modify compiled content from Step 06
+- Create directory structure before writing files
+- Report each file written with path and size
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Resolve Paths and Stage Target Directory
+
+Resolve `{version}` from the primary library version or default to `1.0.0` (see S11 in "Primary library" note below). The final artifact paths are:
+
+```
+{skill_group}                          # {skills_output_folder}/{project_name}-stack/
+{skill_package}                        # {skills_output_folder}/{project_name}-stack/{version}/{project_name}-stack/
+├── references/
+│   └── integrations/
+{forge_version}                        # {forge_data_folder}/{project_name}-stack/{version}/
+```
+
+Where the skill name is `{project_name}-stack` and `{version}` is the semver version (with build metadata stripped per `knowledge/version-paths.md`).
+
+**Primary library definition (S11):** In code-mode, the primary library is the dependency with the highest import count from step-03; its `version` (from the manifest) becomes `{primary_library_version}`. In compose-mode, use the highest semver across constituent skill `metadata.json` files. If neither is available, fall back to `1.0.0`.
+
+**Pre-flight: group-dir type check (S3):** If `{skills_output_folder}/{project_name}-stack/` already exists, probe `{skills_output_folder}/{project_name}-stack/active/{project_name}-stack/metadata.json`. If that metadata exists and `skill_type != "stack"`, HALT with:
+
+"**Cannot proceed.** `{skills_output_folder}/{project_name}-stack/` exists but is not a stack skill (`skill_type={found_type}`). Rename the existing directory or choose a different `project_name` to avoid collision."
+
+Do NOT proceed to staging or commit.
+
+**Atomic write strategy (C2 / B5):** All artifact writes for `{skill_package}` MUST stage into a temp directory first, then commit atomically via `skf-atomic-write.py commit-dir`. The active symlink flip only happens AFTER the commit succeeds.
+
+Create the staging directory:
+
+```bash
+python3 {atomicWriteHelper} stage-dir --target {skill_package}
+```
+
+After this call, writes land in `{skill_package}.skf-tmp/` (referred to below as `{skill_staging}`). Create the required subdirectories inside the staging dir:
+
+```bash
+mkdir -p {skill_staging}/references/integrations
+```
+
+Also create the forge workspace directory directly (these are workspace artifacts, not deliverables — they do not need stage-dir / commit-dir):
+
+```bash
+mkdir -p {forge_version}
+```
+
+**Rollback contract:** If ANY write in sections 2–7 below fails, immediately run:
+
+```bash
+python3 {atomicWriteHelper} commit-dir --rollback --target {skill_package}
+```
+
+Then abort with a structured error contract (see B7): purge any `{forge_version}/*-tmp` staging artifacts, emit `{"status":"error","skill":"skf-create-stack-skill","stage":"step-07","reason":"<message>"}` on stderr, and halt the workflow.
+
+### 2. Stage SKILL.md
+
+Write the approved `skill_content` from step 06 to `{skill_staging}/SKILL.md` (regular write — the whole staging dir will be atomically committed later).
+
+### 3. Stage Per-Library Reference Files
+
+For each confirmed library, write `{skill_staging}/references/{library_name}.md`:
+
+Load structure from `{stackSkillTemplate}` references section:
+- Library name, version from manifest (**in compose-mode**: version from source skill `metadata.json`)
+- Import count and file count (**in compose-mode**: export count from source skill metadata)
+- Key exports with signatures
+- Usage patterns with file:line citations (**in compose-mode**: usage patterns from source skill SKILL.md)
+- Confidence tier label
+
+### 4. Stage Integration Pair Reference Files
+
+For each detected integration pair, write `{skill_staging}/references/integrations/{libraryA}-{libraryB}.md`:
+
+Load structure from `{stackSkillTemplate}` integrations section:
+- Library pair and integration type
+- Co-import file count
+- Integration pattern description with file:line citations
+- Usage convention
+- Confidence tier label
+
+**If no integrations detected:** Skip this section (no files to write).
+
+### 5. Stage context-snippet.md
+
+Write `{skill_staging}/context-snippet.md`:
+
+Use the Vercel-aligned indexed format targeting **~80-120 tokens** (M2). Token estimation is heuristic — use `ceil(char_count / 4)` as the working approximation (the standard rule-of-thumb for English text in BPE-style tokenizers; precise counts differ per model). Compute against the rendered snippet body (excluding trailing newline).
+
+```
+[{project_name}-stack v{version — in code-mode: primary_library_version or 1.0.0; in compose-mode: highest version across constituent skill metadata.json files, or 1.0.0 if none}]|root: skills/{project_name}-stack/
+|IMPORTANT: {project_name}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
+|stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
+|integrations: {pattern-1}, {pattern-2}
+|gotchas: {1-2 most critical integration pitfalls}
+```
+
+**Overflow strategy (M2):** If the estimated token count exceeds **120 tokens**, trim in this fixed order until under budget:
+
+1. **Drop the `gotchas` line first.** Pitfalls live in SKILL.md and references; the snippet's job is discovery, not full warning surface.
+2. **Strip versions from the `stack` line** (`{dep-1}, {dep-2}` instead of `{dep-1}@{v1}`). Versions are recoverable from `metadata.json`.
+3. **Truncate the `stack` list to the top 8 dependencies by import count** (or by export count in compose-mode), appending `, ...+{N} more`.
+4. **Truncate the `integrations` list to the top 5 by file count**, appending `, ...+{N} more`.
+
+If the snippet is still over budget after step 4, log a warning to workflow_warnings (see Workflow Rules in SKILL.md) — do not block the write. The `IMPORTANT:` line is mandatory and never trimmed.
+
+**Underflow note:** Snippets below ~80 tokens are acceptable (small stacks naturally produce short snippets). The lower bound is informational, not enforced.
+
+### 6. Stage metadata.json
+
+Write `{skill_staging}/metadata.json`:
+
+Populate all fields from the metadata.json schema defined in `{stackSkillTemplate}`.
+
+**Tier fields:**
+- `forge_tier` — the run tier (Quick/Forge/Forge+/Deep) resolved in step-01.
+- `confidence_tier` — the dominant T-code from `confidence_distribution`. Pick the tier with the highest count; resolve ties toward the weaker tier (T1-low > T1, T2 > T1-low, T3 > T2) so the reported value never overstates confidence. When `confidence_distribution` is empty (no libraries extracted), emit `"T1-low"` as the conservative default.
+
+```json
+{
+  "skill_type": "stack",
+  "name": "{project_name}-stack",
+  "version": "{primary_library_version or 1.0.0}",
+  "generation_date": "{current_date}",
+  "forge_tier": "{Quick|Forge|Forge+|Deep — the tier under which this run executed}",
+  "confidence_tier": "{T1|T1-low|T2|T3 — dominant T-code from confidence_distribution below}",
+  "spec_version": "1.3",
+  "source_authority": "{official|community|internal — use the lowest authority among constituent skills}",
+  "generated_by": "create-stack-skill",
+  "exports": [],
+  "library_count": N,
+  "integration_count": N,
+  "libraries": ["lib1", "lib2"],
+  "integration_pairs": [["lib1", "lib2"]],
+  "language": "{primary language or list of languages from constituent skills}",
+  "ast_node_count": "{number or omit if no AST extraction performed}",
+  "confidence_distribution": {"t1": N, "t1_low": N, "t2": N, "t3": N},
+  "tool_versions": {
+    "ast_grep": "{version or null}",
+    "qmd": "{version or null}",
+    "skf": "{skf_version}"
+  },
+  "stats": {
+    "exports_documented": N,
+    "exports_public_api": N,
+    "exports_internal": N,
+    "exports_total": N,
+    "public_api_coverage": 0.0,
+    "total_coverage": 0.0,
+    "scripts_count": N,
+    "assets_count": N
+  },
+  "dependencies": [],
+  "compatibility": "{semver-range}"
+}
+```
+
+### 7. Write Forge Data Artifacts (Workspace)
+
+Write workspace artifacts directly to `{forge_version}` (these are workspace-only, not part of the skill package — no staging required). Each individual file MUST be written via `skf-atomic-write.py write` to avoid partial-write corruption:
+
+```bash
+<json-content> | python3 {atomicWriteHelper} write --target {forge_version}/provenance-map.json
+<md-content>   | python3 {atomicWriteHelper} write --target {forge_version}/evidence-report.md
+```
+
+If any workspace write fails, invoke the rollback contract from §1.
+
+**provenance-map.json:**
+
+**In code-mode:**
+```json
+{
+  "provenance_version": "2.0",
+  "skill_name": "{project_name}-stack",
+  "skill_type": "stack",
+  "source_repo": ["{repo_url_1}", "{repo_url_2}"],
+  "source_commit": {"{repo_1}": "{hash_1}", "{repo_2}": "{hash_2}"},
+  "generated_at": "{ISO-8601}",
+  "entries": [
+    {
+      "export_name": "{name}",
+      "export_type": "{type}",
+      "source_library": "{library-name}",
+      "params": [],
+      "return_type": "{type}",
+      "source_file": "{file}",
+      "source_line": 0,
+      "confidence": "T1|T1-low|T2",
+      "extraction_method": "ast_bridge|source_reading|qmd_bridge",
+      "signature_source": "T1|T2|T3"
+    }
+  ],
+  "integrations": [
+    {
+      "libraries": ["{libA}", "{libB}"],
+      "pattern_type": "{type}",
+      "detection_method": "co-import grep",
+      "co_import_files": [{"file": "{path}", "line": 0}],
+      "confidence": "T1|T2"
+    }
+  ]
+}
+```
+
+**In compose-mode:**
+```json
+{
+  "provenance_version": "2.0",
+  "skill_name": "{project_name}-stack",
+  "skill_type": "stack",
+  "source_repo": null,
+  "source_commit": null,
+  "source_ref": null,
+  "generated_at": "{ISO-8601}",
+  "entries": [
+    {
+      "export_name": "{name}",
+      "export_type": "{type}",
+      "source_library": "{library-name}",
+      "params": [],
+      "return_type": "{type}",
+      "source_file": "{from constituent skill}",
+      "source_line": 0,
+      "confidence": "T1|T1-low|T2",
+      "extraction_method": "compose-from-skill",
+      "signature_source": "T1|T2|T3"
+    }
+  ],
+  "integrations": [
+    {
+      "libraries": ["{libA}", "{libB}"],
+      "pattern_type": "{type}",
+      "detection_method": "architecture_co_mention|inferred_from_shared_domain",
+      "co_import_files": [],
+      "confidence": "T2|T3"
+    }
+  ],
+  "constituents": [
+    {
+      "skill_name": "{constituent-skill-name}",
+      "skill_path": "skills/{skill-dir}/",
+      "version": "{version from constituent metadata.json}",
+      "composed_at": "{ISO-8601}",
+      "metadata_hash": "sha256:{hash of constituent metadata.json}"
+    }
+  ]
+}
+```
+
+> **Note:** Per-export entries use the same schema as single skills (see `skill-sections.md`), with `source_library` identifying the originating library. In compose-mode, `constituents[]` enables audit to detect constituent drift via metadata hash comparison. **Use the `metadata_hash` value already stored in workflow state during step-02 (S13) — do NOT re-read and re-hash at step-07 time. The stored hash captures the state as it was at manifest-detection time, which is the correct provenance anchor.**
+
+**evidence-report.md:**
+- Extraction summary per library
+- Integration detection results per pair
+- Warnings and failures encountered
+- Confidence tier distribution
+
+### 8. Commit Staging Directory
+
+After all staged writes in sections 2–6 completed successfully, atomically swap the staging dir into place:
+
+```bash
+python3 {atomicWriteHelper} commit-dir --target {skill_package}
+```
+
+The helper moves any existing `{skill_package}` aside to a `.skf-rollback-<pid>` dir before the swap. On failure the helper restores the prior target and exits non-zero — in that case invoke the rollback contract from §1 and HALT.
+
+### 9. Flip Active Symlink
+
+ONLY AFTER `commit-dir` succeeds, flip the `{skill_group}/active` symlink to point at `{version}`:
+
+```bash
+python3 {atomicWriteHelper} flip-link --link {skill_group}/active --target {version}
+```
+
+The helper holds an flock on `{skill_group}/active.skf-lock` and refuses to replace a non-symlink at `{skill_group}/active` — this guards against accidentally overwriting a real directory (ECH BLOCKER 6/B6). After the flip, `{skill_group}/active/{project_name}-stack/` resolves to the just-committed skill package.
+
+If `flip-link` fails, emit a warning (the committed package is still valid), note the symlink-flip failure in the evidence report, and continue.
+
+### 10. Display Write Summary
+
+"**Output files written.**
+
+**Deliverables** ({skill_package}):
+- SKILL.md ({line_count} lines)
+- context-snippet.md ({token_estimate} tokens)
+- metadata.json
+- references/ -- {lib_count} library files
+- references/integrations/ -- {pair_count} integration files
+
+**Workspace** ({forge_version}):
+- provenance-map.json
+- evidence-report.md
+
+**Symlink:** {skill_group}/active -> {version}
+
+**Total files written:** {total_count}
+
+**Proceeding to validation...**"
+
+### 11. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+

package/src/{workflows/create-stack-skill → skf-create-stack-skill}/steps-c/step-08-validate.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-08-validate'
-description: 'Validate all output files against structure requirements and confidence tier completeness'
-
 nextStepFile: './step-09-report.md'
-stackSkillTemplate: '../data/stack-skill-template.md'
+stackSkillTemplate: 'assets/stack-skill-template.md'
 ---
 
 # Step 8: Validate Output
@@ -12,40 +9,10 @@ stackSkillTemplate: '../data/stack-skill-template.md'
 
 Validate all written output files against their expected structure and verify confidence tier label completeness.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a quality gate operator in Ferris Architect mode
-- ✅ Validation is advisory — findings are warnings, not blockers
-- ✅ Report findings accurately — do not downplay or exaggerate
-
-### Step-Specific Rules:
-
-- 🎯 Validate structure and completeness, not content quality
-- 🚫 FORBIDDEN to modify any output files — validation is read-only
-- 💬 Report findings with specific file paths and issue descriptions
-- 🎯 Advisory mode: always proceed to report regardless of findings
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Check each deliverable file against its expected structure
-- 💾 Store validation_result as workflow state
-- 📖 Auto-proceed to report after validation complete
-- 🚫 FORBIDDEN to halt on validation warnings (advisory only)
-
-## CONTEXT BOUNDARIES:
+## Rules
 
-- From step 07: written_files[] (all output artifacts with paths)
-- From step 01: forge_tier, project_name, skills_output_folder, forge_data_folder
-- This step produces: validation_result {status, findings[], warnings[]}
-- This is a quality gate — findings inform the report but do not block it
+- Validate structure and completeness, not content quality — validation is read-only
+- Advisory mode: always proceed to report regardless of findings
 
 ## MANDATORY SEQUENCE
 
@@ -73,10 +40,14 @@ Record any missing files as **ERROR** findings.
 
 ### 2. Check Tool Availability
 
-Run: `npx skill-check -h`
+Probe skill-check with `--no-install` to avoid cold-install hangs, wrap in a short timeout, and treat any hang or non-zero exit as unavailable (S14):
 
-- If succeeds: Use skill-check for automated validation in sections 3, 9
-- If fails: Use manual fallback paths in those sections
+```bash
+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-07 when appropriate) and record every skipped check in the evidence report.
 
 **Important:** Do not assume availability — empirical check required.
 
@@ -86,6 +57,8 @@ Run: `npx skill-check -h`
 
 This validates frontmatter, description, body limits, links, formatting — and auto-fixes deterministic issues. Parse JSON for `qualityScore`, `diagnostics[]`, `fixed[]`.
 
+**Post-fix provenance drift guard (S15):** If `fixed[]` is non-empty, `skill-check --fix` has modified `SKILL.md` after step-07 wrote it. The safe default for v1.0 is to 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"`). Do NOT silently accept the fixes without surfacing the drift. 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). Fall back to `npx skill-check split-body <skill-dir> --write` if not feasible. Verify `#quick-start` and `#key-types` anchors still resolve after split. Then re-validate.
 
 **If unavailable**, perform manual frontmatter check:
@@ -115,7 +88,8 @@ Parse metadata.json and verify required fields:
 - [ ] `skill_type` equals "stack"
 - [ ] `name` matches `{project_name}-stack`
 - [ ] `version` and `generation_date` present
-- [ ] `confidence_tier` matches forge tier from step 01 (Quick/Forge/Forge+/Deep) — in both code-mode and compose-mode, this is the forge tier; per-library inherited confidence is tracked separately in `confidence_distribution`
+- [ ] `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)
 - [ ] `library_count` matches actual reference files; `integration_count` matches pair files
 - [ ] `libraries` array present and non-empty
 - [ ] `confidence_distribution` object present with `t1`, `t1_low`, `t2`, `t3` keys (lowercase, matching template definition)
@@ -143,10 +117,10 @@ Record missing tier labels as **WARNING** findings.
 ### 8. Validate context-snippet.md
 
 Verify context-snippet.md follows Vercel-aligned indexed format:
-- [ ] First line matches: `[{project}-stack v{version}]|root: {prefix}{project}-stack/` where prefix is `skills/` or a platform root (`.claude/skills/`, `.cursor/skills/`, `.agents/skills/`)
+- [ ] First line matches: `[{project}-stack v{version}]|root: {prefix}{project}-stack/` where prefix is `skills/` (draft form) or any IDE skill root (`.{dir}/skills/`)
 - [ ] Second line starts with `|IMPORTANT:`
 - [ ] Stack and integrations lines present
-- [ ] Approximate token count is ~80-120 tokens
+- [ ] Approximate token count is ~80-120 tokens (use the `ceil(char_count / 4)` heuristic from step-07 §5; tolerate up to ~150 if the overflow strategy was applied and a workflow_warning was emitted)
 
 Record format violations as **WARNING** findings.
 
@@ -172,23 +146,3 @@ Record security findings as advisory **WARNING** findings — they do not block
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- All expected files checked; `npx skill-check check --fix` executed if available (or manual fallback)
-- Quality score captured; auto-fix and split-body applied as needed; security scan executed (or skipped with note)
-- SKILL.md validated against template; metadata.json fields verified; reference files checked
-- Confidence tier coverage verified; validation results displayed with specific findings
-- Advisory mode: always proceeded to report
-
-### ❌ SYSTEM FAILURE:
-
-- Modifying output files during validation (except via skill-check --fix)
-- Halting on validation warnings; not checking all expected files
-- Reporting vague findings without file paths; skipping confidence tier check
-- Not recording quality score when skill-check is available
-
-**Master Rule:** Validate everything, fix what's deterministic via skill-check, scan for security issues. Advisory findings — always proceed to report.