bmad-module-skill-forge 0.5.0 → 0.6.0

package/README.md

@@ -102,8 +102,9 @@ SKF builds on these excellent open-source tools:
 |--------------------------------------------------------------|--------------------------------------------------------------------|
 | [agentskills.io](https://github.com/agentskills/agentskills) | Skill specification and ecosystem standard                         |
 | [GitHub CLI](https://cli.github.com/)                        | Source code access and repository intelligence (all tiers)         |
-| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Deep tiers)            |
+| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Forge+/Deep tiers)     |
 | [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp)     | MCP server for memory-efficient AST queries (recommended)          |
+| [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) | Semantic code search and file discovery pre-ranking (Forge+ tier)  |
 | [QMD](https://github.com/tobi/qmd)                           | Local hybrid search engine for knowledge indexing (Deep tier)      |
 | [skill-check](https://github.com/thedaviddias/skill-check)   | Skill validation, auto-fix, quality scoring, and security scanning |
 | [Snyk Agent Scan](https://github.com/snyk/agent-scan)   | Security scanning for prompt injection and data exposure (optional) |

package/docs/agents.md

@@ -22,10 +22,13 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 
 **Key Capabilities:**
 - AST analysis via ast-grep for structural truth
+- Semantic code discovery via cocoindex-code for intelligent file pre-ranking
 - QMD knowledge search for temporal context and evidence
 - agentskills.io specification compliance and validation
 - GitHub source navigation and package-to-repo resolution
 - Cross-knowledge synthesis for stack skills and integration patterns
+- Skill authoring best practices enforcement (third-person voice, consistent terminology, discovery optimization)
+- Source-derived scripts and assets extraction with provenance tracking
 
 **Workflow-Driven Modes:**
 

package/docs/concepts.md

@@ -31,25 +31,27 @@ Provenance means every instruction in a skill traces back to where it came from.
 
 ---
 
-## Confidence Tiers (T1/T2/T3)
+## Confidence Tiers (T1/T1-low/T2/T3)
 
 Each piece of information in a skill carries a confidence level based on where it came from:
 
 - **T1 — AST extraction:** Pulled directly from source code via AST parsing. This is structural truth — the function signature actually exists in the code right now.
+- **T1-low — Source reading:** Found by reading source files directly without AST parsing. The location is correct but the type signature may be inferred. Produced by Quick tier and by Forge/Deep when ast-grep cannot parse a specific file.
 - **T2 — Evidence:** Found in issues, PRs, changelogs, or documentation within the repository. Reliable context, but not as definitive as code.
 - **T3 — External:** Pulled from external documentation or websites. Treated with caution and clearly marked.
 
-**Example:** A function signature is T1. A deprecation warning from a closed GitHub issue is T2. A usage example from a blog post is T3.
+**Example:** A function signature is T1. A source-read export without AST verification is T1-low. A deprecation warning from a closed GitHub issue is T2. A usage example from a blog post is T3.
 
 ---
 
-## Capability Tiers (Quick/Forge/Deep)
+## Capability Tiers (Quick/Forge/Forge+/Deep)
 
 Your capability tier depends on which tools you have installed. Each tier builds on the previous one:
 
-- **Quick** — GitHub CLI only. SKF reads source files and builds best-effort skills. Works in under a minute.
+- **Quick** — No tools required. SKF reads source files and builds best-effort skills. Works in under a minute. GitHub CLI used when available.
 - **Forge** — Adds [ast-grep](https://ast-grep.github.io). SKF uses AST parsing for structural truth. Instructions are verified against the actual code structure.
-- **Deep** — Adds [QMD](https://github.com/tobi/qmd). SKF indexes knowledge for semantic search. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence.
+- **Forge+** — Adds [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code). SKF uses semantic code search to discover relevant source regions before AST extraction, improving coverage on large codebases.
+- **Deep** — Adds [GitHub CLI](https://cli.github.com) + [QMD](https://github.com/tobi/qmd). Requires ast-grep, gh, and QMD. SKF indexes knowledge for semantic search and performs GitHub repository exploration. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence.
 
 You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [How It Works](../how-it-works.md) for the full technical treatment.
 
@@ -94,3 +96,19 @@ Ferris switches between four modes depending on which workflow is active: Archit
 SKF's core principle: if an instruction can't be traced back to actual source code, it doesn't get included in the skill. This is the opposite of how most AI tools work — they generate plausible-sounding content from training data. SKF only includes what it can verify.
 
 This doesn't mean skills are perfect. Quick-tier skills read source files without AST verification, so they rely on best-effort extraction. But even Quick skills cite their sources, and no tier includes invented information.
+
+---
+
+## Scripts & Assets
+
+Skills can include executable scripts and static assets alongside the main SKILL.md instructions. Scripts handle deterministic operations (validation, setup, data processing) while assets provide templates, schemas, and configuration examples. Both are extracted from the source repository with provenance tracking — SKF copies them, it doesn't fabricate them.
+
+**Example:** A database library skill might include `scripts/migrate.sh` (copied from the library's `bin/` directory) and `assets/config-schema.json` (copied from the library's `schemas/` directory). Each file carries a `[SRC:file:L1]` citation and SHA-256 hash for drift detection.
+
+---
+
+## Best Practices
+
+SKF integrates skill authoring best practices from the Claude platform and community guidelines. Generated skills use third-person descriptions for reliable agent discovery, consistent terminology throughout, and appropriate degrees of freedom (prescriptive for fragile operations like database migrations, flexible for creative tasks like code reviews). These practices are enforced during compilation and verified during testing.
+
+**Example:** A skill description reads "Processes payments via REST API with token-based auth. NOT for: billing dashboards" — third-person voice, specific keywords, and negative triggers help agents select the right skill.

package/docs/examples.md

@@ -46,6 +46,24 @@ Provenance tags trace each instruction to its source:
 
 See [How It Works](../how-it-works.md) for the full output structure.
 
+**Full skill directory structure:**
+
+```
+skills/cognee/
+├── SKILL.md              # What your agent reads
+├── context-snippet.md    # Compressed index for CLAUDE.md
+├── metadata.json         # Machine-readable provenance
+├── references/           # Progressive disclosure detail
+│   ├── api-core.md
+│   └── graph-types.md
+├── scripts/              # Executable utilities (when detected)
+│   └── setup-graphdb.sh
+└── assets/               # Templates and schemas (when detected)
+    └── config-schema.json
+```
+
+The `scripts/` and `assets/` directories appear only when the source repository contains them. Each file traces back to its source with provenance citations and SHA-256 hashes.
+
 ---
 
 ## Example Workflows
@@ -150,7 +168,7 @@ The brief's `doc_urls` field drives the doc_fetcher step. The agent uses whateve
 
 ### Progressive Capability
 
-Start with Quick mode (no setup required), upgrade to Forge (install ast-grep), then Deep (install QMD). Each tier builds on the previous — you never lose capability.
+Start with Quick mode (no setup required), upgrade to Forge (install ast-grep), then Forge+ (install cocoindex-code for semantic discovery), then Deep (install QMD). Each tier builds on the previous — you never lose capability.
 
 ### Batch Operations
 
@@ -164,6 +182,14 @@ Stack skills focus on integration patterns. Individual skills focus on API surfa
 
 After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates CLAUDE.md automatically. Skill generation becomes routine — like running tests.
 
+### Best Practices Built In
+
+Generated skills automatically follow authoring best practices: third-person descriptions for reliable agent discovery, consistent terminology, degrees-of-freedom matching (prescriptive for fragile operations, flexible for creative tasks), and table-of-contents headers in large reference files. Discovery testing recommendations are included in test reports.
+
+### Scripts & Assets
+
+If your source repo includes executable scripts (`scripts/`, `bin/`) or static assets (`templates/`, `schemas/`), SKF detects and packages them automatically with provenance tracking. Custom scripts you add to `scripts/[MANUAL]/` are preserved during updates — just like `<!-- [MANUAL] -->` markers in SKILL.md.
+
 ---
 
 ## Troubleshooting
@@ -182,6 +208,9 @@ An official skill already exists for this package. Consider installing it with `
 **Quick mode skills have lower confidence**
 Quick mode reads source without AST analysis. Install ast-grep to upgrade to Forge mode for structural truth (T1 confidence).
 
+**Want semantic discovery for large codebases?**
+Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) to unlock Forge+ mode. CCC indexes your codebase and pre-ranks files by semantic relevance before AST extraction, improving coverage on projects with 500+ files.
+
 ---
 
 ## Getting More Help

package/docs/getting-started.md

@@ -194,6 +194,17 @@ Your existing skill is now out of date. Audit detects the drift, Update regenera
 @Ferris TS    # Verify the update
 ```
 
+### I want scripts and assets included in my skills
+
+Your source repo has CLI tools, setup scripts, or config templates that agents should use. SKF detects and packages them automatically.
+
+```
+@Ferris BS    # Brief — set scripts_intent: detect
+@Ferris CS    # Create — scripts/ and assets/ auto-detected
+```
+
+Scripts from `scripts/`, `bin/`, and `tools/` directories are copied with provenance. Config templates and schemas from `assets/`, `templates/`, and `schemas/` are included. Custom files you add to `scripts/[MANUAL]/` survive updates.
+
 ---
 
 ## What's Next?

package/docs/how-it-works.md

@@ -35,7 +35,7 @@ Each workflow directory contains these files, and each has a specific job:
 | `data/*.md`               | Workflow-specific reference data — schemas, heuristics, rules, patterns                                             | Read by steps on demand                           |
 | `templates/*.md`          | Output skeletons with placeholder vars — steps fill these in to produce the final artifact                          | Read by steps when generating output              |
 | `skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path                                                          | Read by steps to decide which fragments to load   |
-| `knowledge/*.md`          | 10 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`) | Selectively read into context when a step directs |
+| `knowledge/*.md`          | 12 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`, `ccc-bridge.md`) | Selectively read into context when a step directs |
 
 ```mermaid
 flowchart LR
@@ -96,7 +96,8 @@ SKF uses an additive tier model. Each tier is the previous tier plus one tool. Y
 |------|-------|-------------|
 | **Quick** | `gh_bridge` + `skill-check` + `tessl` | Source reading + spec validation + content quality review. Best-effort skills in under a minute. |
 | **Forge** | + `ast_bridge` | Structural truth. AST-verified signatures. Co-import detection. T1 confidence. |
-| **Deep** | + `qmd_bridge` | Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
+| **Forge+** | + `ccc_bridge` | Semantic discovery. CCC pre-ranks files by meaning before AST extraction. Better coverage on large codebases. |
+| **Deep** | + `gh_bridge` + `qmd_bridge` | Requires ast-grep + gh + QMD. Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
 
 Setup detects your installed tools and sets your tier automatically:
 
@@ -105,10 +106,10 @@ Setup detects your installed tools and sets your tier automatically:
 ```
 
 ```
-Forge initialized. Tools: gh, ast-grep, QMD. Tier: Deep. Ready.
+Forge initialized. Tools: gh, ast-grep, ccc, QMD. Tier: Deep. Ready.
 ```
 
-Don't have ast-grep or QMD yet? No problem — Quick mode works with just the GitHub CLI. Install tools later; your tier upgrades automatically.
+Don't have ast-grep, cocoindex-code, or QMD yet? No problem — Quick mode works with just the GitHub CLI. Install tools later; your tier upgrades automatically.
 
 ### Tier Override — Comparing Output Across Tiers
 
@@ -128,10 +129,13 @@ This is useful for comparing skill quality across tiers for the same target:
 # 2. Change to tier_override: Forge
 @Ferris CS                # recompile at Forge tier — compare output
 
-# 3. Reset to tier_override: ~ (auto-detect)
+# 3. Change to tier_override: Forge+
+@Ferris CS                # recompile with semantic discovery — compare coverage
+
+# 4. Reset to tier_override: ~ (auto-detect)
 ```
 
-Set `tier_override` to `Quick`, `Forge`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
+Set `tier_override` to `Quick`, `Forge`, `Forge+`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
 
 ---
 
@@ -142,7 +146,8 @@ Every claim in a generated skill carries a confidence tier that traces to its so
 | Tier | Source | Tool | What It Means |
 |------|--------|------|---------------|
 | **T1** | AST extraction | `ast_bridge` | Current code, structurally verified. Immutable for that version. |
-| **T2** | QMD evidence / source reading | `qmd_bridge` / `gh_bridge` | Historical + planned context (issues, PRs, changelogs, docs). |
+| **T1-low** | Source reading | `gh_bridge` | Source-read without AST verification. Location correct, signature may be inferred. |
+| **T2** | QMD evidence | `qmd_bridge` | Historical + planned context (issues, PRs, changelogs, docs). |
 | **T3** | External documentation | `doc_fetcher` | External, untrusted. Quarantined. |
 
 ### Temporal Provenance
@@ -165,11 +170,12 @@ Progressive disclosure controls how much context surfaces at each level:
 
 Your forge tier limits what authority claims a skill can make:
 
-| Forge Tier | AST? | QMD? | Max Authority | Accuracy Guarantee |
-|-----------|------|------|---------------|-------------------|
-| Quick | No | No | `community` | Best-effort |
-| Forge | Yes | No | `official` | Structural (AST-verified) |
-| Deep | Yes | Yes | `official` | Full (structural + contextual + temporal) |
+| Forge Tier | AST? | CCC? | QMD? | Max Authority | Accuracy Guarantee |
+|-----------|------|------|------|---------------|-------------------|
+| Quick | No | No | No | `community` | Best-effort |
+| Forge | Yes | No | No | `official` | Structural (AST-verified) |
+| Forge+ | Yes | Yes | No | `official` | Structural + semantic discovery |
+| Deep | Yes | opt. (enhances when installed) | Yes | `official` | Full (structural + contextual + temporal) |
 
 ---
 
@@ -184,14 +190,17 @@ skills/{name}/
 ├── SKILL.md              # Active skill (loaded on trigger)
 ├── context-snippet.md    # Passive context (compressed, always-on)
 ├── metadata.json         # Machine-readable provenance
-└── references/           # Progressive disclosure
-    ├── {function-a}.md
-    ├── {function-b}.md
-    └── integrations/     # Stack skills only
-        ├── auth-db.md
-        └── pwa-auth.md
+├── references/           # Progressive disclosure
+│   ├── {function-a}.md
+│   └── {function-b}.md
+├── scripts/              # Executable automation (when detected in source)
+│   └── {script-name}.sh
+└── assets/               # Templates, schemas, configs (when detected in source)
+    └── {asset-name}.json
 ```
 
+The `scripts/` and `assets/` directories are optional — only created when the source repository contains executable scripts or static assets matching detection heuristics. Each file traces to its source via `[SRC:file:L1]` provenance citations with SHA-256 content hashes for drift detection. User-authored files go in `scripts/[MANUAL]/` or `assets/[MANUAL]/` subdirectories and are preserved during updates.
+
 ### SKILL.md Format
 
 Skills follow the [agentskills.io specification](https://agentskills.io/specification) with frontmatter:
@@ -199,9 +208,10 @@ Skills follow the [agentskills.io specification](https://agentskills.io/specific
 ```yaml
 ---
 name: payment-service
-version: 2.1.0
-description: Payment processing API skill — 23 verified functions
-author: org/payment-team
+description: >
+  Processes payments via REST API with token-based auth. Use when writing
+  payment integration code. NOT for: billing dashboards or reporting.
+  23 verified functions from github.com/org/payment-service.
 ---
 ```
 
@@ -233,11 +243,21 @@ Machine-readable provenance for every skill:
     "coverage": 1.0,
     "confidence_t1": 20,
     "confidence_t2": 3,
-    "confidence_t3": 0
-  }
+    "confidence_t3": 0,
+    "scripts_count": 1,
+    "assets_count": 1
+  },
+  "scripts": [
+    { "file": "scripts/validate.sh", "purpose": "Validates config schema", "confidence": "T1-low" }
+  ],
+  "assets": [
+    { "file": "assets/config-schema.json", "purpose": "Configuration JSON schema", "confidence": "T1-low" }
+  ]
 }
 ```
 
+`scripts` and `assets` arrays are optional — omitted entirely (not empty) when the source has no scripts or assets.
+
 ### Stack Skill Output
 
 Stack skills map how your dependencies interact — shared types, co-import patterns, integration points:
@@ -301,7 +321,7 @@ Export injects a managed section between markers:
 
 ## Tool Ecosystem
 
-### 6 Tools
+### 7 Tools
 
 | Tool | Wraps | Purpose |
 |------|-------|---------|
@@ -309,6 +329,7 @@ Export injects a managed section between markers:
 | **`skill-check`** | [thedaviddias/skill-check](https://github.com/thedaviddias/skill-check) | Validation + auto-fix (`check --fix`), quality scoring (0-100), security scan, split-body, diff comparison |
 | **`tessl`** | [tessl](https://tessl.io) | Content quality review, actionability scoring, progressive disclosure evaluation, AI judge with suggestions |
 | **`ast_bridge`** | ast-grep CLI | Structural extraction, custom AST queries, co-import detection |
+| **`ccc_bridge`** | cocoindex-code | Semantic code search, project indexing, file discovery pre-ranking |
 | **`qmd_bridge`** | QMD (local search) | BM25 keyword search, vector semantic search, collection indexing |
 | **`doc_fetcher`** | Environment web tools | Remote documentation fetching for T3-confidence content. Tool-agnostic — uses whatever web fetching is available (Firecrawl, WebFetch, curl, etc.). Output quarantined as T3. |
 
@@ -319,6 +340,7 @@ When tools disagree, higher priority wins for instructions. Lower priority is pr
 | Priority | Source | Tool |
 |----------|--------|------|
 | 1 (highest) | AST extraction | `ast_bridge` |
+| 1b | CCC discovery (pre-ranking) | `ccc_bridge` |
 | 2 | QMD evidence | `qmd_bridge` |
 | 3 | Source reading (non-AST) | `gh_bridge` |
 | 4 | External documentation | `doc_fetcher` |
@@ -344,6 +366,8 @@ forge-data/{skill-name}/
 └── extraction-rules.yaml   # Language-specific ast-grep schema
 ```
 
+The `provenance-map.json` includes a `file_entries` array for script/asset file-level provenance (SHA-256 hashes, source paths) alongside the export-level `entries` array.
+
 `skills/` and `forge-data/` are committed. Agent memory (`_bmad/_memory/forger-sidecar/`) is gitignored.
 
 ---
@@ -396,7 +420,7 @@ src/
 │   └── README.md
 ├── knowledge/
 │   ├── skf-knowledge-index.csv
-│   └── *.md (10 fragments)
+│   └── *.md (12 fragments)
 └── workflows/
     ├── setup-forge/
     ├── analyze-source/

package/docs/index.md

@@ -17,7 +17,7 @@ hero:
 
 ## What does Skill Forge do?
 
-AI agents hallucinate API calls. They invent function names, guess parameter types, and produce code that doesn't compile. Skill Forge fixes this by analyzing code repositories, documentation, and developer discourse — extracting real signatures and patterns and compiling them into verified instruction files that any AI agent can follow. Every instruction traces back to where it came from.
+AI agents hallucinate API calls. They invent function names, guess parameter types, and produce code that doesn't compile. Skill Forge fixes this by analyzing code repositories, documentation, and developer discourse — extracting real signatures and patterns and compiling them into verified instruction files that any AI agent can follow. Every instruction traces back to where it came from. Generated skills can also include executable scripts and static assets extracted from the source repository, each with full provenance tracking.
 
 ## Quick Install
 

package/docs/workflows.md

@@ -15,11 +15,11 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **Command:** `@Ferris SF`
 
-**Purpose:** Initialize forge environment, detect tools, set capability tier, verify QMD collection health.
+**Purpose:** Initialize forge environment, detect tools (ast-grep, ccc, gh, qmd), set capability tier, index project in CCC (Forge+), verify QMD collection health (Deep).
 
 **When to Use:** First time using SKF in a project. Run once per project.
 
-**Key Steps:** Detect tools → Determine tier → Write forge-tier.yaml → QMD hygiene (Deep)
+**Key Steps:** Detect tools → CCC index check (Forge+) → Determine tier → Write forge-tier.yaml → QMD hygiene (Deep)
 
 **Agent:** Ferris (Architect mode)
 
@@ -33,7 +33,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** Before `Create Skill` when you want maximum control over what gets compiled.
 
-**Key Steps:** Gather intent → Analyze target → Define scope → Write skill-brief.yaml
+**Key Steps:** Gather intent → Analyze target → Define scope → Scripts/assets intent → Write skill-brief.yaml
 
 **Agent:** Ferris (Architect mode)
 
@@ -47,7 +47,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** After Brief Skill, or with an existing skill-brief.yaml.
 
-**Key Steps:** Load brief → Ecosystem check → AST extract → QMD enrich → Compile → Validate → Generate
+**Key Steps:** Load brief → Ecosystem check → AST extract → Scripts/assets detect → QMD enrich → Compile → Validate → Generate
 
 **Agent:** Ferris (Architect mode)
 
@@ -61,7 +61,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** After source code changes when an existing skill needs updating.
 
-**Key Steps:** Load existing → Detect changes → Re-extract → Merge (preserve MANUAL) → Validate → Write
+**Key Steps:** Load existing → Detect changes (incl. scripts/assets) → Re-extract → Merge (preserve MANUAL) → Validate → Write
 
 **Agent:** Ferris (Surgeon mode)
 
@@ -119,7 +119,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** To check if a skill has fallen out of date with its source code.
 
-**Key Steps:** Load skill → Re-index source → Structural diff → Semantic diff (Deep) → Classify severity → Report
+**Key Steps:** Load skill → Re-index source → Structural diff → Script/asset drift → Semantic diff (Deep) → Classify severity → Report
 
 **Agent:** Ferris (Audit mode)
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.5.0",
-  "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Deep).",
+  "version": "0.6.0",
+  "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
     "bmad-method",

package/src/agents/forger.agent.yaml

@@ -15,7 +15,7 @@ agent:
       Skill compilation specialist who transforms code repositories, documentation, and developer discourse into verified agent skills.
       Manages the full lifecycle: source analysis, skill briefing, AST-backed compilation,
       integrity testing, and ecosystem-ready export across progressive capability tiers
-      (Quick/Forge/Deep).
+      (Quick/Forge/Forge+/Deep).
 
     identity: |
       The forge master — a precision-focused craftsman who works through four modes:

package/src/forger/forge-tier.yaml

@@ -6,8 +6,24 @@ tools:
   ast_grep: ~
   gh_cli: ~
   qmd: ~
+  ccc: ~
+  security_scan: ~
 
 # Capability tier (derived from tool availability)
-# Quick = no tools required | Forge = + ast-grep | Deep = + ast-grep + gh + QMD
+# Quick = no tools | Forge = + ast-grep | Forge+ = + ast-grep + ccc | Deep = + ast-grep + gh + QMD
 tier: ~
 tier_detected_at: ~
+
+# CCC semantic index state (managed by setup-forge and extraction workflows)
+ccc_index:
+  indexed_path: ~
+  last_indexed: ~
+  status: "none"
+  staleness_threshold_hours: 24
+
+# CCC index registry (tracks which source paths have been indexed for skill workflows)
+ccc_index_registry: []
+
+# QMD collection registry (populated by create-skill, consumed by audit/update-skill)
+# Each entry tracks a QMD collection created during skill workflows
+qmd_collections: []

package/src/forger/preferences.yaml

@@ -2,7 +2,7 @@
 # Created by setup-forge workflow on first run
 # Edit this file to customize Ferris behavior
 
-# Override detected tier (set to Quick, Forge, or Deep to force a tier)
+# Override detected tier (set to Quick, Forge, Forge+, or Deep to force a tier)
 tier_override: ~
 
 # Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)

package/src/knowledge/ccc-bridge.md

@@ -0,0 +1,110 @@
+# CCC Bridge
+
+## Principle
+
+`ccc_bridge.*` references in workflow steps are **conceptual interfaces**, not callable functions. They describe a semantic code discovery operation to perform. Use the `ccc` MCP server tools (when available) or `ccc` CLI commands to execute these operations. See the TOOL/SUBPROCESS FALLBACK rule — if ccc is unavailable, the calling step falls back to direct ast-grep or source reading without ccc pre-discovery.
+
+## Rationale
+
+Without ccc pre-discovery, extraction steps scan all source files uniformly — processing them in directory order or entry-point-first order. On large codebases (500+ files), this means AST extraction in CLI streaming mode uses `head -N` cutoffs that may miss relevant exports in files that appear late in the scan. Integration detection in Stack Skill relies on grep-based co-import counting, which misses semantic relationships between libraries that don't appear in the same file.
+
+With ccc pre-discovery:
+- Extraction steps receive a relevance-ranked file queue — the most semantically important files are processed first, before any streaming cutoff
+- Integration detection gains semantic augmentation — pairs below the 2-file co-import threshold can be evaluated via natural language queries
+- Audit workflows can detect renamed/moved exports via semantic search before classifying them as deleted
+
+The key architectural constraint: ccc discovers, ast-grep verifies. Discovery method is orthogonal to confidence tier. This keeps the 4-tier confidence system (T1/T1-low/T2/T3) clean and avoids tier proliferation.
+
+## When ccc Is Used
+
+ccc is a **discovery layer only**. It answers "where should I look?" — it does not produce citations or structural claims. Every path or symbol returned by ccc_bridge must be verified by `ast_bridge` (T1) or source reading (T1-low) before it enters the extraction inventory. ccc results never appear in provenance citations.
+
+ccc is available at **Forge+** and **Deep** tiers (when `tools.ccc: true` in forge-tier.yaml).
+
+## Availability
+
+ccc_bridge operations are available when:
+- `tools.ccc: true` in forge-tier.yaml (verified by `ccc --help` + `ccc doctor` in setup-forge)
+- `ccc_index.status` is `"fresh"` or `"stale"` in forge-tier.yaml (an index exists for the project)
+
+When either condition is false, calling steps skip ccc discovery silently and proceed with direct ast-grep or source reading. This is standard Forge tier behavior — not a degradation.
+
+## Operations
+
+### `ccc_bridge.search(query, path?, top_k?)`
+
+**Resolves to:** `ccc search "{query}" --path {path} --top {top_k}` (CLI) or the `ccc` MCP search tool (preferred)
+
+Returns: list of `{file, score, snippet}` entries ranked by semantic relevance to the query. These are **candidates** for ast-grep extraction — not verified exports.
+
+**Usage context:** Called before ast-grep in Forge+ and Deep tier extraction steps to discover semantically relevant source regions. Results pre-rank the file extraction queue so ast-grep processes the most relevant files first.
+
+### `ccc_bridge.ensure_index(path)`
+
+**Resolves to:** Check `ccc_index.status` in forge-tier.yaml. If `"none"` or the indexed_path does not match, run `ccc init {path}` then `ccc index` and update forge-tier.yaml.
+
+**Usage context:** Called by setup-forge step-01b to ensure the project root is indexed. Called lazily by extraction steps when `ccc_index.status` is `"none"` but ccc is available.
+
+### `ccc_bridge.status()`
+
+**Resolves to:** Two-step verification:
+1. `ccc --help` — confirms binary exists (exit 0)
+2. `ccc doctor` — confirms daemon is running, extracts version string, validates embedding model
+
+**Usage context:** Called exclusively by setup-forge step-01 during tool detection. Downstream workflows read the result from forge-tier.yaml — they do not re-verify.
+
+## Confidence
+
+ccc discovery does not produce a confidence tier. The provenance chain is:
+
+1. ccc discovers candidate files (internal hint — not cited)
+2. ast-grep verifies exports in those files → **T1** citation `[AST:file:Lnn]`
+3. Or source reading verifies → **T1-low** citation `[SRC:file:Lnn]`
+
+The ccc search is invisible in the output artifact. A Forge+ skill's citations are indistinguishable from a Forge skill's citations — the difference is in extraction coverage, not citation format.
+
+## Indexing Lifecycle
+
+### When Indexing Happens
+
+1. **setup-forge step-01b:** Indexes the project root when setup-forge runs. This is the primary indexing point.
+2. **Workflow discovery steps:** If `ccc_index.status` is `"stale"` or `"none"`, discovery steps trigger a re-index and warn the user. They do not block.
+3. **ccc daemon:** Incremental indexing means re-indexing unchanged files is a near-no-op.
+
+### Freshness
+
+- Staleness threshold: 24 hours (configurable via `ccc_index.staleness_threshold_hours` in forge-tier.yaml)
+- A stale index still produces useful results — the workflow proceeds with the stale index and notes the staleness
+- setup-forge is the designated refresh authority
+
+### Relationship to QMD Registry
+
+ccc_index and qmd_collections are **orthogonal**:
+- `ccc_index` in forge-tier.yaml tracks the persistent source code index (one per project)
+- `qmd_collections[]` in forge-tier.yaml tracks per-skill workflow artifact collections
+- ccc indexes source code for semantic search; QMD indexes curated artifacts for temporal/knowledge search
+- The janitor role for QMD (setup-forge step-03) operates independently of ccc_index
+
+## Query Volume Bounds
+
+To prevent excessive daemon calls, workflow steps cap ccc queries:
+- **create-skill extraction:** max 2 queries per skill (discovery + optional scope refinement)
+- **analyze-source mapping:** max 1 query per qualifying unit
+- **create-stack-skill integration detection:** max 1 query per library pair
+- **audit-skill re-index:** max 1 query per export missing from its recorded location
+
+## Anti-Patterns
+
+- Using ccc_bridge results as citations without ast-grep verification — ccc output is never a provenance citation
+- Blocking a workflow because ccc is unavailable — ccc is always optional
+- Running ccc_bridge.ensure_index() without checking ccc_index.status first — unnecessary re-indexing
+- Passing ccc results directly to the extraction inventory — they are candidates, not extractions
+- Listing ccc as "unavailable" in reports for Quick/Forge tiers — ccc is a Forge+ capability, not something Quick/Forge tiers are missing
+
+## Related Fragments
+
+- [progressive-capability.md](progressive-capability.md) — Forge+ tier definition and positive framing
+- [confidence-tiers.md](confidence-tiers.md) — why ccc does not create a new confidence tier
+- [qmd-registry.md](qmd-registry.md) — the parallel but separate registry for QMD collections
+
+_Source: designed as part of the Forge+ tier integration for cocoindex-code semantic code search_

package/src/knowledge/confidence-tiers.md

@@ -22,8 +22,8 @@ With confidence tiers:
 
 | Tier | Label | Source | Extraction Method | Available At |
 | --- | --- | --- | --- | --- |
-| T1 | AST-verified | Source code | ast-grep structural parsing | Forge, Deep |
-| T1-low | Source-read | Source code | Pattern matching, file reading | Quick, Forge, Deep |
+| T1 | AST-verified | Source code | ast-grep structural parsing | Forge, Forge+, Deep |
+| T1-low | Source-read | Source code | Pattern matching, file reading | Quick, Forge, Forge+, Deep |
 | T2 | QMD-enriched | Knowledge base | QMD semantic search + synthesis | Deep |
 | T3 | External reference | Docs, URLs | External documentation lookup | All tiers |
 
@@ -131,7 +131,7 @@ Every generated skill includes a confidence distribution in `metadata.json`:
     "t2": 12,
     "t3": 3
   },
-  "extraction_tier": "deep"
+  "extraction_tier": "deep"  // valid values: "quick", "forge", "forge+", "deep"
 }
 ```
 

package/src/knowledge/overview.md

@@ -24,12 +24,13 @@ With knowledge files:
 |------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------|
 | [zero-hallucination.md](zero-hallucination.md)             | Every claim traces to source; uncitable content excluded          | AN, BS, CS, QS, SS, US, AS, TS     |
 | [confidence-tiers.md](confidence-tiers.md)                 | T1/T1-low/T2/T3 trust model and citation formats                  | AN, BS, CS, QS, SS, US, AS, TS, EX |
-| [progressive-capability.md](progressive-capability.md)     | Quick/Forge/Deep tier philosophy and behavior adaptation          | All 10                             |
+| [progressive-capability.md](progressive-capability.md)     | Quick/Forge/Forge+/Deep tier philosophy and behavior adaptation          | All 10                             |
 | [agentskills-spec.md](agentskills-spec.md)                 | agentskills.io output format principles and compliance            | CS, QS, SS, US, TS, EX             |
 | [skill-lifecycle.md](skill-lifecycle.md)                   | End-to-end pipeline, artifact flow, workflow selection            | All 10                             |
 | [provenance-tracking.md](provenance-tracking.md)           | Provenance-map.json entries and file_entries, evidence reports, claim traceability | CS, QS, SS, US, AS, TS             |
 | [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm                | CS, US, AS, TS, EX                 |
 | [qmd-registry.md](qmd-registry.md)                         | Progressive QMD collection registry and collection gate principle | SF, BS, CS, US, AS                 |
+| [ccc-bridge.md](ccc-bridge.md)                             | ccc_bridge interface, indexing lifecycle, Forge+ discovery-before-extraction | SF, CS, SS, AS, US, BS             |
 | [split-body-strategy.md](split-body-strategy.md)           | Selective vs full split-body, detection pattern, agent accuracy   | CS, QS, US, TS, EX                |
 
 ## JiT Loading Protocol