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

package/src/{workflows/create-skill → skf-create-skill}/steps-c/step-07-generate-artifacts.md

@@ -1,8 +1,13 @@
 ---
-name: 'step-07-generate-artifacts'
-description: 'Write all output files — 4 deliverables to skills/ and 3 workspace artifacts to forge-data/'
 nextStepFile: './step-08-report.md'
 forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
+# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves — the active-symlink flip and registry
+# writes below MUST go through the atomic helper for concurrency safety.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
 # Step 7: Generate Artifacts
@@ -11,43 +16,11 @@ forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
 
 To write all compiled content to disk — 4 deliverable files to `{skill_package}` and 3 workspace artifacts to `{forge_version}`, creating directories as needed. Then create or update the `active` symlink.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🎯 ALWAYS follow the exact instructions in the step file
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a 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 skill compilation engine performing artifact generation
-- ✅ All content was assembled in step-05 and validated in step-06
-- ✅ This step ONLY writes — it does not modify, compile, or validate content
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on writing files from the compiled content in context
-- 🚫 FORBIDDEN to modify content during writing — write exactly what was compiled
-- 🚫 FORBIDDEN to skip any artifact — all base artifact types must be written (4 deliverables + 3 workspace files + N reference files)
-- 💬 Report each file written with its path
-- 📁 Create directories before writing files
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 Write files using the compiled content from context
-- 📖 Create directory structure first, then write files
-- 🚫 Halt with error if a file write fails — do not continue with partial output
-
-## CONTEXT BOUNDARIES:
-
-- Available: All compiled content from step-05, validation results from step-06, source_root from step-01 (needed for section 5b CCC registration)
-- Focus: File system operations — create directories, write files
-- Limits: Do NOT modify content during writing
-- Dependencies: All content must be compiled and validated in context
-- Path resolution: See `knowledge/version-paths.md` for canonical path templates (`{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}`)
+- Focus only on writing files from compiled content — do not modify content during writing
+- All base artifact types must be written (4 deliverables + 3 workspace files + N reference files)
+- Create directories before writing files
 
 ## MANDATORY SEQUENCE
 
@@ -98,6 +71,10 @@ Write these 4 files from the compiled content:
 - One file per detected asset, copied from source with content preserved
 - Only created when `assets_inventory` is non-empty
 
+**Note on `file_type: "doc"` entries** (promoted authoritative docs from step-03 §2a):
+
+Promoted docs are tracked in `file_entries[]` with `file_type: "doc"` for drift detection but are **NOT** copied into the skill package. The source file remains at its original location outside `{skill_package}`. Step-07 must skip any `file_entries[]` row where `file_type == "doc"` when iterating for file copy — these entries exist only for provenance tracking, not bundling. Step-07 verification (§5) also does not check for doc files in the skill package.
+
 ### 3. Write Workspace Artifacts to {forge_version}
 
 Write these 3 files from the compiled content:
@@ -110,16 +87,21 @@ Write these 3 files from the compiled content:
 
 **File 7:** `{forge_version}/extraction-rules.yaml`
 - Language and ast-grep schema used for this extraction (for reproducibility)
+- Note: This file is generated here from extraction data collected during steps 3-4, not assembled in step-05
 
-### 4. Create Active Symlink
+### 4. Create Active Symlink (atomic flip)
 
-Create or update the `active` symlink at `{skill_group}/active` pointing to `{version}`:
+Create or update the `active` symlink at `{skill_group}/active` pointing to `{version}` using the shared atomic-flip helper. The helper holds an `flock` on `{skill_group}/active.skf-lock`, refuses to replace a non-symlink at `{skill_group}/active` (protecting against accidental rm-rf of a real directory), and uses a rename-over-symlink pattern so the update is atomic from a concurrent reader's perspective:
 
+```bash
+python3 {atomicWriteHelper} flip-link \
+  --link {skill_group}/active \
+  --target {version}
 ```
-{skill_group}/active -> {version}
-```
 
-If the symlink already exists, remove it first and recreate. This ensures `{skill_group}/active/{name}/` resolves to the just-written skill package.
+The helper returns non-zero (exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a symlink — in that case, halt with: "Refusing to flip `{skill_group}/active` — existing path is not a symlink. Investigate manually; expected a symlink pointing at a version directory."
+
+**Never `rm` + `ln -s` the active link manually.** The bare-rm pattern has two failure modes: (1) a concurrent reader sees a missing `active` mid-flip, and (2) a bug or typo that replaces `{skill_group}/active` with a plain directory turns the next manual `rm -rf {skill_group}/active` into data loss. The helper encapsulates both guards.
 
 ### 5. Verify Write Completion
 
@@ -164,12 +146,12 @@ Index the generated skill artifacts into a QMD collection so that audit-skill an
 ```bash
 qmd collection remove {name}-extraction 2>/dev/null  # no-op if new
 qmd collection add {skill_package} --name {name}-extraction --mask "**/*"
-qmd embed  # generates vector embeddings for vector_search/deep_search
+qmd embed --collection {name}-extraction  # generates vector embeddings for semantic (vec) and HyDE query sub-types; scope to this collection to avoid re-embedding others. If the installed qmd CLI lacks --collection, gate the embed behind a per-skill freshness check (skip when the existing {name}-extraction entry is within 24 hours — rationale: an unscoped embed re-runs over every collection, which in a populated QMD store can cost minutes of GPU time per create-skill run; 24 hours is long enough to absorb rapid re-forges from the same brief without losing meaningful content freshness) and warn in evidence-report.
 ```
 
 **Registry update:**
 
-Read `{forgeTierConfig}` and update the `qmd_collections` array.
+Read `{forgeTierConfig}` and update the `qmd_collections` array **under an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`** (see step-03b §4 for the full pattern — acquire lock → read → modify → atomic write via `skf-atomic-write.py write` → release). If `flock` is unavailable, fall back to read-CAS-by-mtime.
 
 If an entry with `name: "{name}-extraction"` already exists, replace it. Otherwise, append:
 
@@ -184,7 +166,7 @@ If an entry with `name: "{name}-extraction"` already exists, replace it. Otherwi
 Write the updated forge-tier.yaml.
 
 **Error handling:**
-- If QMD collection creation fails: log the error, note that indexing can be retried via [SF] setup-forge. Do NOT fail the workflow.
+- If QMD collection creation fails: log the error, note that indexing can be retried via [SF] setup. Do NOT fail the workflow.
 - If forge-tier.yaml update fails: log the error, continue. The collection exists in QMD even if the registry entry failed.
 
 **IF forge tier is NOT Deep:** Skip this section silently. No messaging.
@@ -197,11 +179,11 @@ Ensure the source path used for extraction is indexed by ccc and registered in t
 
 **Index verification:**
 
-Dispatch to ccc CLI (`ccc index {source_root}`) or ccc MCP tool — `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. This is a no-op if the source was already indexed during setup-forge or step-02b.
+Dispatch to ccc CLI (`ccc index {source_root}`) or ccc MCP tool — `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. This is a no-op if the source was already indexed during setup or step-02b.
 
 **Registry update:**
 
-Read `{forgeTierConfig}` and update the `ccc_index_registry` array.
+Read `{forgeTierConfig}` and update the `ccc_index_registry` array **under an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`** (same pattern as §6 — acquire lock → read → modify → atomic write via `skf-atomic-write.py write` → release). If `flock` is unavailable, fall back to read-CAS-by-mtime.
 
 Deduplicate by `source_repo` + `skill_name` (NOT local `path`, which may be ephemeral). Replace existing match or append:
 
@@ -237,29 +219,3 @@ After all artifacts are written, verified, and optionally indexed into QMD, imme
 
 ONLY WHEN all 7 artifact files are written, the active symlink is created, and verification is complete will you proceed to load `{nextStepFile}` for the compilation report.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Directory structure created ({skill_group}, {skill_package}, {forge_version})
-- All 4 deliverable files written to {skill_package}
-- All 3 workspace artifact files written to {forge_version}
-- Active symlink created at {skill_group}/active -> {version}
-- Write completion verified — all 7 files exist and symlink resolves
-- Deep tier: QMD collection `{name}-extraction` created/updated and registered in forge-tier.yaml
-- Non-Deep tier: QMD indexing skipped silently
-- Brief confirmation displayed with file list
-- Auto-proceeded to step-08
-
-### ❌ SYSTEM FAILURE:
-
-- Modifying content during the write step
-- Skipping any of the 7 required files
-- Proceeding with partial output if a write fails
-- Not creating directories before writing
-- Not verifying all files were written
-- Failing the workflow due to QMD indexing errors (should degrade gracefully)
-
-**Master Rule:** This step writes artifacts, creates the active symlink, and registers QMD collections. All content was compiled and validated in previous steps. Write faithfully, verify completely. QMD indexing failures never block the workflow.

package/src/skf-create-skill/steps-c/step-08-report.md

@@ -0,0 +1,145 @@
+---
+nextStepFile: './step-09-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.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+---
+
+# Step 8: Report
+
+## STEP GOAL:
+
+To display the final compilation summary — skill name, version, source, export count, confidence distribution, tier used, file list, and any warnings — and suggest next steps for the user.
+
+## Rules
+
+- Focus only on reporting compilation results — do not modify any files
+- Deliver structured report with confidence breakdown
+- Chains to the local health-check step via `{nextStepFile}` after completion (non-batch mode, or after the final batch brief) — the user-facing report is NOT the terminal step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Display Forge Completion Banner
+
+"**Skill forged: {name} v{version} — {export_count} functions, {primary_confidence} confidence.**"
+
+Where `{primary_confidence}` is the predominant confidence tier (T1 if Forge/Deep, T1-low if Quick).
+
+### 2. Display Compilation Summary
+
+"**Compilation Summary**
+
+| Field | Value |
+|-------|-------|
+| **Skill** | {name} v{version} |
+| **Source** | {source_repo} @ {branch} ({commit_short}) |
+| **Language** | {language} |
+| **Forge Tier** | {tier} — {tier_description} |
+| **Files Scanned** | {file_count} |
+| **Exports Documented** | {documented_count} public API ({public_api_coverage}%) / {total_count} total ({total_coverage}%) |
+
+**Confidence Distribution:**
+| Tier | Count | Description |
+|------|-------|-------------|
+| T1 (AST) | {t1_count} | Structurally verified via ast-grep |
+| T1-low (Source) | {t1_low_count} | Inferred from source reading |
+| T2 (QMD) | {t2_count} | QMD-enriched semantic context |
+| T3 (External) | {t3_count} | Sourced from external documentation URLs |
+
+**Output Files:**
+- `{skill_package}/SKILL.md` — Active skill with trigger-based usage
+- `{skill_package}/context-snippet.md` — Passive context snippet (used by export-skill)
+- `{skill_package}/metadata.json` — Machine-readable birth certificate
+- `{skill_package}/references/` — Progressive disclosure ({ref_count} files)
+- `{forge_version}/provenance-map.json` — Source map with AST bindings
+- `{forge_version}/evidence-report.md` — Build audit trail
+- `{forge_version}/extraction-rules.yaml` — Reproducible extraction schema
+- `{skill_group}/active` -> `{version}` — Symlink to current version"
+
+### 3. Display Warnings (If Any)
+
+If there were warnings from extraction, validation, or enrichment, display them:
+
+"**Warnings:**
+- {warning_1}
+- {warning_2}
+- ..."
+
+If no warnings, omit this section entirely.
+
+**Next steps:** After reviewing the report, recommend the next workflow:
+- **TS** (test skill) — verify completeness before export
+- **EX** (export) — publish to your IDE's context system
+- If issues were flagged, suggest **reviewing the SKILL.md** and re-running compilation
+
+### 4. Suggest Next Steps
+
+"**Recommended next steps:**
+- **[TS] Test Skill** — verify completeness and accuracy before export
+- **[EX] Export Skill** — publish to your skill library or agentskills.io
+- **[US] Update Skill** — edit specific sections or add manual content
+
+To use this skill immediately, add the context snippet to your CLAUDE.md:
+```
+{context_snippet_content}
+```"
+
+### 5. Batch Mode Status (If Applicable)
+
+**If running in --batch mode:**
+
+"**Batch progress:** {completed_count} of {total_count} skills compiled.
+
+{If more remaining:} Proceeding to next brief: {next_skill_name}..."
+
+Update the batch checkpoint in `{sidecar_path}/batch-state.yaml` with:
+
+```yaml
+batch_active: true
+brief_list: [{full list of brief paths}]
+current_index: {index of next brief to process, 0-based}
+completed: [{list of completed skill names}]
+last_updated: {ISO timestamp}
+```
+
+**Before writing:** validate the same two invariants that step-01 re-checks on resume — `0 <= current_index < len(brief_list)` AND `os.path.exists(brief_list[current_index])`. If either fails (e.g., the next brief file was deleted mid-batch, or arithmetic pushed the index off the end), set `batch_active: false` and write `batch_halt_reason: "invalid checkpoint at write time — index or file missing"` instead of the active record. The next run will re-discover rather than resume a broken index.
+
+Then load and execute `steps-c/step-01-load-brief.md` for the next brief. Step-01 detects an active batch via `batch-state.yaml` and loads the brief at `current_index` only after re-validating the same invariants (belt and braces — the checkpoint may have been edited between runs).
+
+**If all batch briefs complete:**
+
+Set `batch_active: false` in `{sidecar_path}/batch-state.yaml` to prevent stale state. Display: "Batch complete. {completed_count} skills compiled."
+
+**If not batch mode:**
+
+End workflow. No further steps.
+
+### Result Contract
+
+**If not batch mode (or all batch briefs complete):**
+
+**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 neither candidate path resolves:** skip the result-contract write entirely. Append a warning to `evidence-report.md`: "Result contract skipped — `shared/references/output-contract-schema.md` could not be resolved at either candidate path." Then set `validation_status: 'schema-unavailable'` in `metadata.json` (and re-write metadata.json via `skf-atomic-write.py write`). Pipeline consumers will observe the missing `-latest.json` and the metadata flag.
+
+### 6. Chain to Health Check
+
+**If not batch mode (or all batch briefs complete):**
+
+ONLY WHEN the compilation report, warnings (if any), recommended next steps, and result contract have been handled will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+
+**If batch mode with remaining briefs:** Skip the health-check chain — load and execute `steps-c/step-01-load-brief.md` for the next brief instead. The health check runs only after the final brief in the batch.
+
+## CRITICAL STEP COMPLETION NOTE
+
+This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md` (unless batch mode loops back to step-01). After the health check completes, the create-skill workflow is fully done.
+
+For batch mode: load and execute `steps-c/step-01-load-brief.md` for remaining briefs via sidecar checkpoint. Health check runs only after the last brief.
+

package/src/skf-create-skill/steps-c/step-09-health-check.md

@@ -0,0 +1,23 @@
+---
+# `shared/health-check.md` resolves relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+# Step 9: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of create-skill — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-08
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- In batch mode, this step is only reached after the final brief — step-08 loops back to step-01-load-brief for remaining briefs and skips chaining here
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+Load `{nextStepFile}`, read it fully, then execute it.

package/src/{workflows/create-skill/steps-c → skf-create-skill/steps-c/sub}/step-02b-ccc-discover.md

@@ -1,7 +1,5 @@
 ---
-name: 'step-02b-ccc-discover'
-description: 'CCC semantic discovery pass — Forge+ and Deep tiers when ccc is available, skip for Quick/Forge'
-nextStepFile: './step-03-extract.md'
+nextStepFile: '../step-03-extract.md'
 ---
 
 # Step 2b: CCC Semantic Discovery
@@ -12,44 +10,11 @@ If tier is Forge+ or Deep AND ccc is available, perform a semantic discovery pas
 
 For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🎯 ALWAYS follow the exact instructions in the step file
-- 🔄 CRITICAL: When loading next step, ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a 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 skill compilation engine performing semantic pre-discovery
-- ✅ CCC discovery is a hint layer — it guides extraction, it does not replace it
-- ✅ Discovery failure is graceful degradation, not an error
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on running ccc semantic search and storing results
-- 🚫 FORBIDDEN to extract exports — that is step-03
-- 🚫 FORBIDDEN to modify brief data or source resolution
-- 🚫 FORBIDDEN to block the workflow if ccc fails
-- ⏱️ Quick and Forge tiers: skip this step entirely and silently
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow MANDATORY SEQUENCE exactly
-- 💾 Discovery results stored in context as `{ccc_discovery}`
-- 📖 Results are consumed by step-03 to pre-rank the file extraction queue
-- 🚫 Never treat ccc results as verified extractions
-
-## CONTEXT BOUNDARIES:
-
-- Available: tier, tools.ccc, ccc_index from forge-tier.yaml (loaded in step-01)
-- Available: brief_data (name, scope, description) from step-01
-- Available: source_root (resolved source path) from step-01 — note: for remote sources, `source_root` may not be a local path until step-03 performs the ephemeral clone
-- Focus: Semantic discovery only — no extraction, no compilation
-- Dependencies: step-02 must have completed
+- Focus only on running ccc semantic search and storing results — do not extract exports
+- Do not block the workflow if ccc fails
+- Quick and Forge tiers: skip this step entirely and silently
 
 ## MANDATORY SEQUENCE
 
@@ -67,7 +32,7 @@ Check `tools.ccc` from forge-tier.yaml. If `tools.ccc` is false, set `{ccc_disco
 
 If `tools.ccc` is true, check the remote source guard **before** proceeding to section 2:
 
-**Remote source guard:** If `source_root` is a remote URL (GitHub repository not yet cloned locally — ephemeral clone happens in step-03), CCC cannot operate yet. Set `{ccc_discovery: []}` and display: "CCC discovery deferred — remote source will be indexed after ephemeral clone in step-03." Auto-proceed to section 5 (step completion). Step-03 will detect the deferred scenario and run CCC discovery on the ephemeral clone before AST extraction begins.
+**Remote source guard:** If `source_root` is a remote URL (GitHub repository — workspace clone or ephemeral clone happens in step-03), CCC cannot operate yet. Set `{ccc_discovery: []}` and display: "CCC discovery deferred — remote source will be indexed after clone in step-03." Auto-proceed to section 5 (step completion). Step-03 will detect the deferred scenario and run CCC discovery on the resolved clone (workspace or ephemeral) before AST extraction begins.
 
 If `source_root` is a local path, continue to section 2.
 
@@ -79,7 +44,7 @@ Read `ccc_index` from forge-tier.yaml:
 - If `ccc_index.status` is `"stale"`: display brief note — "CCC index is stale — discovery results may miss recent changes." Continue to section 3.
 - If `ccc_index.status` is `"none"` or `"failed"`: attempt lazy indexing via `ccc_bridge.ensure_index(source_root)`. If indexing succeeds, continue to section 3. If indexing fails, set `{ccc_discovery: []}` and auto-proceed to section 5.
 
-**Tool resolution for ccc_bridge.ensure_index:** Use `/ccc` skill indexing (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc init` + `ccc index` (CLI). Note: `ccc init` takes no positional arguments — it initializes the index for the current working directory. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**Tool resolution for ccc_bridge.ensure_index:** Use `/ccc` skill indexing (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc init` + `ccc index` (CLI). Note: `ccc init` takes no positional arguments — it initializes the index for the current working directory. See `knowledge/tool-resolution.md`.
 
 ### 3. Construct Semantic Query
 
@@ -97,7 +62,7 @@ Where:
 
 Run `ccc_bridge.search(query, source_root, top_k=20)`:
 
-**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc search --limit 20 "{query}"` (CLI). Note: `ccc search` operates on the index in the current working directory — there is no flag to specify a project directory. See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md).
+**Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc search --limit 20 "{query}"` (CLI). Note: `ccc search` operates on the index in the current working directory — there is no flag to specify a project directory. See `knowledge/tool-resolution.md`.
 
 **If search succeeds:**
 
@@ -140,26 +105,3 @@ Immediately load, read entire file, then execute `{nextStepFile}`.
 
 ONLY WHEN discovery is complete (Forge+/Deep with ccc) or the step is skipped (Quick/Forge or ccc unavailable) will you proceed to load `{nextStepFile}` for AST extraction.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Quick/Forge tiers: skipped silently with no output, auto-proceeded
-- Forge+/Deep with ccc: semantic query constructed from brief data
-- Forge+/Deep with ccc: ccc_bridge.search executed, results stored as `{ccc_discovery}` in context
-- Discovery summary displayed (count of regions and unique files)
-- CCC failures handled gracefully (empty discovery, continue)
-- Auto-proceeded to step-03
-
-### ❌ SYSTEM FAILURE:
-
-- Halting on CCC unavailability or search failures
-- Extracting exports or signatures (that is step-03)
-- Displaying skip messages for Quick/Forge tiers
-- Treating CCC discovery results as verified extractions
-- Not storing `{ccc_discovery}` in context (even if empty)
-- Beginning compilation or SKILL.md assembly in this step
-
-**Master Rule:** CCC discovery is a hint layer. It improves extraction coverage but never replaces structural verification. Failures degrade gracefully.