bmad-module-skill-forge 1.7.0 → 1.8.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "1.7.0",
+      "version": "1.8.0",
       "author": {
         "name": "Armel"
       },

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "1.7.0"
+skf_version: "1.8.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/package.json

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

package/src/shared/scripts/schemas/skill-brief.v1.json

@@ -24,7 +24,12 @@
     "target_ref": {
       "type": "string",
       "minLength": 1,
-      "description": "Optional explicit git ref (tag or branch) used verbatim as source_ref, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag livekit/v0.7.42 for skill livekit-rust). Remote sources only."
+      "description": "Optional explicit git ref (tag or branch) used verbatim as source_ref, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag livekit/v0.7.42 for skill livekit-rust). Remote sources only. Mutually exclusive with constituent_refs."
+    },
+    "constituent_refs": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "minLength": 1 },
+      "description": "Per-constituent git ref overrides for composite (multi-repo or multi-ref) sources. Keys must match entries in the analyze-source project_paths array. When absent, a single target_ref or auto-detected ref applies to all paths. Mutually exclusive with target_ref."
     },
     "source_type": {
       "type": "string",

package/src/shared/scripts/skf-forge-tier-rw.py

@@ -42,6 +42,17 @@ Subcommands:
                 collections without re-rendering the whole file in
                 prose.
 
+  register-ccc-index
+                Append-or-replace a single entry in the
+                `ccc_index_registry` array. Reads the entry as JSON on
+                stdin (must include `source_repo` and `skill_name`;
+                composite key `source_repo`+`skill_name` is the upsert
+                key — existing entry with the same composite key is
+                replaced, otherwise appended). All other forge-tier
+                state is preserved verbatim. Used by skf-create-skill
+                §6b to register CCC-indexed source paths without
+                re-rendering the whole file in prose.
+
   clean-stale   Two cleanup operations gated by flags:
                   --qmd-live-names a,b,c — remove qmd_collections
                     entries whose `name` is not in the comma-separated
@@ -74,6 +85,7 @@ system-wide:
   uv run skf-forge-tier-rw.py read --target /path/forge-tier.yaml
   echo '{...}' | uv run skf-forge-tier-rw.py write-tools --target /path/forge-tier.yaml
   uv run skf-forge-tier-rw.py init-prefs --target /path/preferences.yaml
+  echo '{...}' | uv run skf-forge-tier-rw.py register-ccc-index --target /path/forge-tier.yaml
   uv run skf-forge-tier-rw.py clean-stale --target /path/forge-tier.yaml \\
       --qmd-live-names foo-brief,bar-extraction --prune-missing-ccc-paths
 """
@@ -373,6 +385,61 @@ def cmd_register_qmd_collection(target: Path) -> None:
     })
 
 
+def cmd_register_ccc_index(target: Path) -> None:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        _die(1, "register-ccc-index: empty stdin (expected JSON entry)")
+    try:
+        entry = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _die(1, f"register-ccc-index: invalid JSON on stdin: {e}")
+
+    if not isinstance(entry, dict):
+        _die(1, "register-ccc-index: entry must be a JSON object")
+    source_repo = entry.get("source_repo")
+    skill_name = entry.get("skill_name")
+    if not source_repo or not isinstance(source_repo, str):
+        _die(1, "register-ccc-index: entry must include a non-empty 'source_repo' string")
+    if not skill_name or not isinstance(skill_name, str):
+        _die(1, "register-ccc-index: entry must include a non-empty 'skill_name' string")
+
+    data = _read_yaml(target)
+    if data is None:
+        _die(1, f"register-ccc-index: target does not exist: {target}. "
+                f"Run setup workflow first to create forge-tier.yaml.")
+
+    registry = list(data.get("ccc_index_registry") or [])
+    replaced = False
+    for i, existing in enumerate(registry):
+        if (isinstance(existing, dict)
+                and existing.get("source_repo") == source_repo
+                and existing.get("skill_name") == skill_name):
+            registry[i] = entry
+            replaced = True
+            break
+    if not replaced:
+        registry.append(entry)
+
+    payload = {
+        "tools": data.get("tools", {}),
+        "tier": data.get("tier", "Quick"),
+        "tier_detected_at": data.get("tier_detected_at",
+                                     datetime.now(timezone.utc).isoformat()),
+        "ccc_index": data.get("ccc_index", {}),
+        "ccc_index_registry": registry,
+        "qmd_collections": data.get("qmd_collections", []),
+    }
+    rendered = render_forge_tier_yaml(payload)
+    _atomic_write(target, rendered)
+    _ok({
+        "source_repo": source_repo,
+        "skill_name": skill_name,
+        "action": "replaced" if replaced else "appended",
+        "ccc_index_registry_count": len(registry),
+        "wrote": str(target),
+    })
+
+
 def cmd_clean_stale(target: Path, qmd_live_names: list[str] | None,
                     prune_missing_ccc_paths: bool) -> None:
     data = _read_yaml(target)
@@ -468,6 +535,10 @@ def main() -> None:
                                 help="Append-or-replace a single qmd_collections entry by name")
     p_register.add_argument("--target", type=Path, required=True)
 
+    p_ccc = sub.add_parser("register-ccc-index",
+                           help="Append-or-replace a single ccc_index_registry entry by source_repo+skill_name")
+    p_ccc.add_argument("--target", type=Path, required=True)
+
     args = parser.parse_args()
 
     if args.cmd == "read":
@@ -483,6 +554,8 @@ def main() -> None:
         cmd_clean_stale(args.target, live, args.prune_missing_ccc_paths)
     elif args.cmd == "register-qmd-collection":
         cmd_register_qmd_collection(args.target)
+    elif args.cmd == "register-ccc-index":
+        cmd_register_ccc_index(args.target)
 
 
 if __name__ == "__main__":

package/src/shared/scripts/skf-validate-frontmatter.py

@@ -21,6 +21,7 @@ system-wide:
   uv run skf-validate-frontmatter.py <skill-md-path>
   uv run skf-validate-frontmatter.py <skill-md-path> --skill-dir-name <name>
   uv run skf-validate-frontmatter.py <skill-md-path> --max-body-lines 500
+  uv run skf-validate-frontmatter.py <skill-md-path> --max-body-lines 500 --max-body-tokens 5000
 
 Input:
   Path to a SKILL.md file.
@@ -31,6 +32,11 @@ Input:
   exceeds N lines. Opt-in — when omitted, body size is never checked and
   the verdict is unchanged. Callers pass the skill-check `body.max_lines`
   default (500) to pre-catch that hard reject before commit.
+  Optional --max-body-tokens N: when set, emit a high-severity `body`
+  issue if the estimated body token count exceeds N. Token count is
+  estimated as ceil(character_count / 4). Callers pass the skill-check
+  `body.max_tokens` default (5000) to pre-catch that soft/hard reject
+  before commit.
 
 Output:
   JSON object:
@@ -154,6 +160,28 @@ def body_line_count(content: str) -> int | None:
     return len(lines) - (closing + 1)
 
 
+def body_token_estimate(content: str) -> int | None:
+    """Estimate the SKILL.md body token count as ceil(char_count / 4).
+
+    Returns None when the frontmatter delimiters are absent or unclosed
+    (same boundary condition as body_line_count). The heuristic matches
+    the agentskills.io spec's token estimation convention.
+    """
+    if not content.startswith("---\n") and not content.startswith("---\r\n"):
+        return None
+    lines = content.splitlines()
+    closing = -1
+    for i in range(1, len(lines)):
+        if lines[i] == "---":
+            closing = i
+            break
+    if closing == -1:
+        return None
+    body = "\n".join(lines[closing + 1:])
+    char_count = len(body)
+    return -(-char_count // 4)  # ceil division
+
+
 def _validate_name(name: str, skill_dir_name: str | None) -> list[dict]:
     """Validate skill name format. Aligned with canonical validator.py."""
     issues: list[dict] = []
@@ -220,14 +248,16 @@ def validate_frontmatter(
     content: str,
     skill_dir_name: str | None = None,
     max_body_lines: int | None = None,
+    max_body_tokens: int | None = None,
 ) -> dict:
     """Validate SKILL.md frontmatter against agentskills.io spec.
 
     When `max_body_lines` is set, additionally emit a high-severity `body`
-    issue if the body exceeds that many lines (opt-in — the verdict is
-    unchanged when it is None, so the other consumers of this validator are
-    unaffected). Returns a result dict with status, issues, frontmatter,
-    body_lines, and summary.
+    issue if the body exceeds that many lines. When `max_body_tokens` is
+    set, emit a high-severity `body` issue if the estimated token count
+    exceeds that limit. Both are opt-in — the verdict is unchanged when
+    they are None. Returns a result dict with status, issues, frontmatter,
+    body_lines, body_tokens, and summary.
     """
     fm, issues = parse_frontmatter(content)
 
@@ -239,6 +269,14 @@ def validate_frontmatter(
             "message": f"body lines {body_lines} exceeds max {max_body_lines}",
         })
 
+    body_tokens = body_token_estimate(content)
+    if max_body_tokens is not None and body_tokens is not None and body_tokens > max_body_tokens:
+        issues.append({
+            "severity": "high",
+            "field": "body",
+            "message": f"body token estimate {body_tokens} exceeds max {max_body_tokens}",
+        })
+
     if fm is not None:
         # Name validation
         name = fm.get("name", "")
@@ -301,6 +339,7 @@ def validate_frontmatter(
         "issues": issues,
         "frontmatter": fm,
         "body_lines": body_lines,
+        "body_tokens": body_tokens,
         "summary": {
             "total": len(issues),
             **severity_counts,
@@ -345,6 +384,18 @@ def main() -> int:
             "the skill-check body.max_lines default (500) to pre-catch that reject."
         ),
     )
+    parser.add_argument(
+        "--max-body-tokens",
+        metavar="N",
+        type=int,
+        default=None,
+        help=(
+            "when set, emit a high-severity 'body' issue if the estimated body "
+            "token count exceeds N (opt-in; omitted = body tokens not checked). "
+            "Token estimate uses ceil(char_count / 4). Pass the skill-check "
+            "body.max_tokens default (5000) to pre-catch that reject."
+        ),
+    )
     parser.add_argument(
         "-o", "--output",
         metavar="FILE",
@@ -365,7 +416,7 @@ def main() -> int:
     else:
         content = skill_md_path.read_text(encoding="utf-8")
         skill_dir_name = args.skill_dir_name or skill_md_path.parent.name
-        result = validate_frontmatter(content, skill_dir_name, args.max_body_lines)
+        result = validate_frontmatter(content, skill_dir_name, args.max_body_lines, args.max_body_tokens)
 
     output_text = json.dumps(result, indent=2)
 

package/src/skf-analyze-source/assets/skill-brief-schema.md

@@ -27,7 +27,8 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | `scripts_intent`   | string | `detect` / `none` / free-text                    | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
 | `assets_intent`    | string | `detect` / `none` / free-text                    | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/").        |
 | `target_version`   | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable.                                                   |
-| `target_ref`       | string | Git ref (tag or branch)                          | Optional. Explicit git ref used verbatim as the resolved `source_ref`, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag `livekit/v0.7.42` for skill `livekit-rust`). Remote sources only. |
+| `target_ref`       | string | Git ref (tag or branch)                          | Optional. Explicit git ref used verbatim as the resolved `source_ref`, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag `livekit/v0.7.42` for skill `livekit-rust`). Remote sources only. Mutually exclusive with `constituent_refs`. |
+| `constituent_refs` | object | map of path→ref strings                          | Optional. Per-constituent git ref overrides for composite (multi-repo or multi-ref) sources. Keys must match entries in the analyze-source `project_paths` array. When absent, a single `target_ref` (or auto-detected ref) applies to all paths. Mutually exclusive with `target_ref`. |
 | `source_authority` | string | `official` / `community` / `internal`            | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`.                                                                           |
 | `source_ref`       | string | Git ref (tag/branch/HEAD)                        | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually.                                                                                                                        |
 

package/src/skf-analyze-source/references/identify-units.md

@@ -48,6 +48,7 @@ For EACH detected boundary from the scan:
 - Package Boundary — workspace member or independently versioned
 - Module Boundary — logical grouping within a package
 - Library Boundary — third-party with significant project-specific usage
+- Composite Boundary — ≥2 boundaries that only deliver value together (detected in §3b below; not assigned during initial per-boundary classification)
 
 **Step C — Assign scope type:**
 - `full-library` — entire codebase of the unit
@@ -105,9 +106,28 @@ For disqualified candidates, note reason:
 |------|--------|
 | {path} | {disqualification reason} |
 
+### 3b. Detect Composite Unit Merges
+
+After building the classification table, apply the Composite Boundary detection heuristic from {heuristicsFile} against the qualifying units:
+
+1. **Scan for merge candidates:** Among the qualifying units (from `kept[]`), find groups of ≥2 Package or Module boundaries that meet EITHER trigger:
+   - **Mutual hard dependency:** Every constituent imports from at least one other constituent in the group, AND no constituent's public API is self-contained
+   - **Shared integration surface:** Constituents share types/traits defined in one constituent but consumed by all others, AND the consuming constituents have no independent barrel
+
+2. **If candidate groups are found**, propose each merge:
+   - Derive a composite name from the common namespace prefix or repo name
+   - List the constituents (boundary names and paths being merged)
+   - State the triggering heuristic and evidence
+
+3. **If no candidate groups are found**, skip to §4.
+
+**Merge does NOT fire for:** Units already flagged as Stack Skill Candidates in step 4 (map-and-detect §5) — those are multi-unit groupings that deliver value *separately* but are *also* useful together. Composite merges are for units that are *only* useful together (the key distinction). If a group of units is independently useful but commonly combined, it remains as separate units and is flagged as a stack skill candidate later.
+
+**This step is a recommendation — not automatic.** Merges are presented to the user in §5 for confirmation (see "Composite Merge Proposals" below). If the user rejects a merge, the constituents remain as separate units in the classification table.
+
 ### 4. Detect Primary Language Per Unit
 
-For each qualifying unit, determine the primary programming language based on:
+For each qualifying unit (including any approved composites from §3b), determine the primary programming language based on:
 - File extensions in the unit directory
 - Manifest file type (package.json → JS/TS, Cargo.toml → Rust, go.mod → Go, etc.)
 - Entry point file extension
@@ -126,20 +146,34 @@ For each qualifying unit, determine the primary programming language based on:
 **Already-Skilled Units:** {count from existing_skills match}
 {List with recommendation to run update-skill if source has changed}
 
+{IF composite merge proposals exist from §3b:}
+
+**Composite Merge Proposals:** {count}
+
+| # | Composite Name | Constituents | Heuristic | Evidence |
+|---|----------------|--------------|-----------|----------|
+| 1 | {name} | {list of constituent unit names} | {mutual hard dependency / shared integration surface} | {brief evidence} |
+
+If approved, each composite replaces its constituents in the classification table as a single Composite Boundary unit. The constituents are recorded in the composite's metadata for downstream workflows (create-skill reads constituents to scope extraction across all member paths).
+
+{END IF}
+
 **Notes:**
 - {Any observations about project structure patterns}
 - {Any ambiguous boundaries that need user clarification}
 
-Do these classifications look correct? Should any units be added, removed, or reclassified?"
+Do these classifications look correct? Should any units be added, removed, or reclassified?
+{IF composites proposed:} Are the composite merge proposals correct? (Accept/reject each individually.)"
 
-Wait for user feedback. Adjust classifications based on user input.
+Wait for user feedback. Adjust classifications based on user input. For approved composites: remove the constituent rows from the qualifying units table and add a single composite row with `Boundary Type: Composite`, scope type inherited from the dominant constituent, and confidence reflecting the merge heuristic strength.
 
 ### 6. Append to Report
 
 Append the complete "## Identified Units" section to {outputFile}:
 
 Replace the placeholder `[Appended by identify-units]` with:
-- Classification table (qualifying units)
+- Classification table (qualifying units, including approved composites)
+- Composite merge details (if any): composite name, constituents list, heuristic, evidence
 - Disqualification table
 - Already-skilled units list
 - Language detection results
@@ -149,8 +183,11 @@ Update {outputFile} frontmatter:
 ```yaml
 stepsCompleted: [append 'identify-units' to existing array]
 lastStep: 'identify-units'
+confirmed_composites: [{list of approved composite merge objects: {name, constituents[], heuristic}}]
 ```
 
+(`confirmed_composites` is an empty array when no composites were proposed or all were rejected.)
+
 ### 7. Present MENU OPTIONS
 
 Display: "**Select:** [C] Continue to Export Mapping and Integration Detection | [X] Cancel and exit"

package/src/skf-analyze-source/references/init.md

@@ -50,6 +50,8 @@ Look for {outputFile}.
 
 **Headless flag consumption:** If `project_paths[]` is already populated (e.g. collected by the section-1 stale-collision guard) OR `--project-path <path>` was passed at invocation, set/keep `project_paths[]` (comma-split the flag value if multiple paths were supplied), skip the prompt below, and proceed to validation. Otherwise prompt as today.
 
+**Per-path ref overrides (`--target-refs`):** If `--target-refs <mapping>` was passed at invocation, parse it as a comma-separated list of `path:ref` pairs (e.g., `owner/repo:v1.0.0,owner/repo2:main`). Build a `constituent_refs` map from the pairs. Each key must match an entry in `project_paths[]` (validated after path collection). When `--target-refs` is absent but multiple `project_paths` exist, set `constituent_refs` to `{}` (empty — all paths use default ref resolution). When only a single path exists, omit `constituent_refs` entirely (use `target_ref` if set on the brief). `constituent_refs` and `target_ref` are mutually exclusive — if both are supplied, HALT with: "`--target-refs` and `--target-ref` are mutually exclusive. Use `--target-refs` for multi-path analysis, or `--target-ref` for single-path."
+
 "**Welcome to Analyze Source — the SKF decomposition engine.**
 
 I'll analyze your project to identify discrete skillable units and produce skill-brief.yaml files for each recommended unit.
@@ -71,6 +73,7 @@ Wait for user input.
 - For each provided path/URL: check that it exists (local) or is accessible (remote)
 - **IF any invalid:** "Path `{path}` doesn't appear to be valid. Please correct it."
 - Store as `project_paths[]` array in report frontmatter (single path stored as 1-element array for consistency)
+- **IF `constituent_refs` was built from `--target-refs`:** Validate that every key in the map matches an entry in `project_paths[]`. If any key has no matching path, HALT: "constituent_refs key `{key}` does not match any entry in project_paths."
 
 **Collect intent hint** (drives recommendation ranking in Step 5):
 
@@ -127,6 +130,7 @@ date: '{current_date}'
 user_name: '{user_name}'
 project_name: '{project_name}'
 project_paths: ['{provided_project_path}']
+constituent_refs: {map from --target-refs, or omit if single path}
 forge_tier: '{detected_tier}'
 existing_skills: [{list of existing skill names}]
 intent_hint: '{intent_hint or empty string}'
@@ -136,6 +140,8 @@ stack_skill_candidates: []
 nextWorkflow: ''
 ```
 
+**`constituent_refs` presence rules:** Include the field only when `project_paths` has more than one entry. When present, keys are path strings matching `project_paths[]` entries, values are explicit git refs (tag/branch/commit). Paths with no explicit ref have no entry in the map (default ref resolution applies). Downstream steps (scan-project, brief generation) read this map to resolve per-constituent refs when cloning or reading off-HEAD constituents.
+
 "**Initialization complete.**
 
 **Project:** {project_path}

package/src/skf-analyze-source/references/scan-project.md

@@ -28,6 +28,7 @@ To map the complete project structure by scanning directory trees, detecting ser
 
 Read {outputFile} frontmatter to obtain:
 - `project_paths[]` — the root(s) to scan (one or more paths/URLs)
+- `constituent_refs` — optional per-path git ref overrides (present only when `project_paths` has multiple entries and explicit refs were supplied via `--target-refs`)
 - `forge_tier` — determines scanning depth
 - Scope hints (if any were provided in step 01)
 
@@ -37,14 +38,16 @@ Load {heuristicsFile} for reference on detection signals.
 
 **Resolve `{scanManifestsHelper}`** from `{scanManifestsProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
-**For each path in `project_paths[]`**, launch a subprocess that scans the project directory structure (aggregate results across all repos with clear repo-level grouping):
+**For each path in `project_paths[]`**, resolve the constituent ref (if any) and launch a subprocess that scans the project directory structure (aggregate results across all repos with clear repo-level grouping):
+
+**Per-path ref resolution:** If `constituent_refs` is present and contains an entry for the current path, use that ref. For remote paths, this means cloning or fetching at the specified ref (`git clone --branch {ref} --depth 1` or `git show {ref}:<subpath>` for off-HEAD access). For local paths with a non-HEAD ref, check out or read from the specified ref using `git show {ref}:<path>`. When no `constituent_refs` entry exists for a path, use default ref resolution (HEAD for local, latest tag or HEAD for remote).
 
 1. Map the top-level directory tree (2-3 levels deep)
 2. Identify workspace configuration files (pnpm-workspace.yaml, lerna.json, Cargo.toml [workspace], go.work, etc.)
 3. Enumerate package manifests deterministically — invoke `uv run {scanManifestsHelper} scan {path}` and parse the JSON envelope. The script returns `{manifests[], total_unique, monorepo, warnings?}` covering npm/python/rust/go/maven/gradle/ruby/composer/swift; record each `{path, ecosystem}` for the manifests catalog in §4 and capture `monorepo` for the boundary-signal pass in §3
 4. Locate entry point files (index.ts, main.ts, app.ts, main.go, main.rs, __init__.py, etc.)
 5. Detect service configuration (Dockerfile, docker-compose.yml, kubernetes manifests, serverless.yml) — keep this step LLM-driven; file glob + presence check is sufficient, no parsing required
-6. Return structured findings — file paths and types only, not contents
+6. Return structured findings — file paths and types only, not contents. When `constituent_refs` was used, include the resolved ref in each repo-level result group: `{path, ref, manifests[], monorepo, warnings?}`
 
 **If subprocess unavailable:** Perform directory scanning in main thread using file I/O tools.
 

package/src/skf-analyze-source/references/unit-detection-heuristics.md

@@ -70,6 +70,22 @@ Rules for identifying discrete skillable units within a project. A "skillable un
 - Props interfaces outnumber function signatures as primary API surface
 - Scope type: `component-library`
 
+### Composite Boundary
+- Two or more Package or Module boundaries that only deliver value together (no constituent is independently useful to the skill consumer)
+- Hard cross-boundary dependency: constituents share types, traits, or interfaces that are not re-exported through a single barrel — consumers must import from multiple constituents to use the integration
+- Common pattern: a set of crates/packages in the same repo that implement a protocol together (e.g., plugin crates for a framework, verification + encoding halves of a cryptographic library)
+- Scope type: inherits from the dominant constituent (typically `full-library` or `specific-modules`)
+
+**Detection heuristic (apply after initial classification, before user confirmation):**
+1. Among the qualifying units, find groups of ≥2 boundaries where EITHER:
+   - **Mutual hard dependency:** Every constituent imports from at least one other constituent in the group, AND no constituent's public API is self-contained (removing any one breaks the others)
+   - **Shared integration surface:** Constituents share types/traits defined in one constituent but consumed by all others, AND the consuming constituents have no independent barrel (their value depends on the shared definitions)
+2. For each detected group, propose merging into a single composite unit:
+   - Name: `{common-prefix}` or `{integration-name}` (derive from shared namespace or repo name)
+   - Constituents: list of merged boundary names and paths
+   - Rationale: which heuristic triggered (mutual hard dependency or shared integration surface)
+3. The merge is a **recommendation** — present to user for confirmation in identify-units §3b
+
 ## Disqualification Rules
 
 Do NOT recommend as a skillable unit if:

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

@@ -195,19 +195,14 @@ Ensure the source path used for extraction is indexed by ccc and registered in t
 
 **Registry update:**
 
-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.
+Register the indexed source path via `register-ccc-index` (comment-preserving round-trip, same pattern as §6's `register-qmd-collection`). Acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`, then:
 
-Deduplicate by `source_repo` + `skill_name` (NOT local `path`, which may be ephemeral). Replace existing match or append:
-
-```yaml
-  - source_repo: "{brief.source_repo}"
-    path: "{source_root}"
-    skill_name: "{name}"
-    indexed_at: "{current ISO date}"
-    source_workflow: "create-skill"
+```bash
+echo '{"source_repo":"{brief.source_repo}","path":"{source_root}","skill_name":"{name}","indexed_at":"{current ISO date}","source_workflow":"create-skill"}' \
+  | uv run {forgeTierRw} register-ccc-index --target {forgeTierConfig}
 ```
 
-Write the updated forge-tier.yaml.
+Deduplicates by `source_repo` + `skill_name` (NOT local `path`, which may be ephemeral). Release the lock after the command completes. If `flock` is unavailable, fall back to read-CAS-by-mtime.
 
 **Error handling:** If ccc indexing or registry update fails, log and continue — do NOT fail the workflow.
 

package/src/skf-create-stack-skill/references/generate-output.md

@@ -226,19 +226,19 @@ Use the schema from `{provenanceMapSchemaPath}` — see that asset for the canon
 
 ### 8. Pre-Commit Frontmatter & Body-Size Gate
 
-The full schema/frontmatter validation runs in step 8 (`validate.md`) — but that runs *after* commit-dir and flip-link have already published the package. The two most common non-auto-fixable `skill-check` hard rejects — a `description` over the 1024-char limit (which `skill-check --fix` cannot trim for you) and a SKILL.md body over the `body.max_lines` limit (default **500**) — would therefore only surface on an already-committed, symlink-active artifact, forcing edits to the live `SKILL.md`. Additive re-composition of an already-large stack grows the body monotonically, so the body overflow is the likeliest trigger. Catch both here, while the package is still in `.skf-tmp`.
+The full schema/frontmatter validation runs in step 8 (`validate.md`) — but that runs *after* commit-dir and flip-link have already published the package. The most common non-auto-fixable `skill-check` hard rejects — a `description` over the 1024-char limit (which `skill-check --fix` cannot trim for you), a SKILL.md body over the `body.max_lines` limit (default **500**), and a body exceeding the `body.max_tokens` limit (default **5000**) — would therefore only surface on an already-committed, symlink-active artifact, forcing edits to the live `SKILL.md`. Additive re-composition of an already-large stack grows the body monotonically, so body overflow (lines or tokens) is the likeliest trigger. Catch all three here, while the package is still in `.skf-tmp`.
 
-Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins). Run it against the **staged** `SKILL.md`, passing the real skill name so the directory-match check is not fooled by the `.skf-tmp` staging suffix, and `--max-body-lines 500` to assert the skill-check body limit pre-commit:
+Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins). Run it against the **staged** `SKILL.md`, passing the real skill name so the directory-match check is not fooled by the `.skf-tmp` staging suffix, `--max-body-lines 500` to assert the skill-check body-line limit, and `--max-body-tokens 5000` to assert the skill-check body-token limit pre-commit:
 
 ```bash
-uv run {frontmatterValidator} {skill_staging}/SKILL.md --skill-dir-name {project_name}-stack --max-body-lines 500
+uv run {frontmatterValidator} {skill_staging}/SKILL.md --skill-dir-name {project_name}-stack --max-body-lines 500 --max-body-tokens 5000
 ```
 
-The validator emits JSON: `status` (`pass`/`warn`/`fail`), `issues[]` (each with `severity` ∈ `high|medium|low`, `field`, `message`), `body_lines` (the counted body size), and `summary`. Disposition:
+The validator emits JSON: `status` (`pass`/`warn`/`fail`), `issues[]` (each with `severity` ∈ `high|medium|low`, `field`, `message`), `body_lines` (the counted body size), `body_tokens` (the estimated token count), and `summary`. Disposition:
 
 - **`status` is `fail`, OR any `issues[]` entry has `severity` `high` or `medium`** — a hard violation that `npx skill-check` (step 8) would reject and `--fix` cannot auto-correct. HALT-to-fix **in staging**, then re-run the validator until it clears. Remediate by `field`:
   - `description` / `name` / `compatibility` — trim/correct `{skill_staging}/SKILL.md` (e.g. shorten `description` to ≤ 1024 chars).
-  - `body` (`body lines N exceeds max 500`) — reduce the staged body: prefer a **selective split** of the largest Tier-2 section(s) into `{skill_staging}/references/`, keeping Tier-1 content inline (mirrors `validate.md` §3); or trim redundant content. Re-run the gate until `body_lines ≤ 500`.
+  - `body` (`body lines N exceeds max 500` or `body token estimate N exceeds max 5000`) — reduce the staged body: prefer a **selective split** of the largest Tier-2 section(s) into `{skill_staging}/references/`, keeping Tier-1 content inline (mirrors `validate.md` §3); or trim redundant content. Re-run the gate until both `body_lines ≤ 500` and `body_tokens ≤ 5000`.
 
   Do NOT proceed to §9 commit-dir with an unresolved high/medium issue. Note: an over-long `description` is rated `medium` and exits `0`, so key the HALT on the issue severities above — not on the exit code.
 - **Only `low`-severity issues (e.g. an unexpected field)** — record each as a WARNING in the evidence report and proceed; these do not block the commit.

package/src/skf-test-skill/references/source-access-protocol.md

@@ -58,6 +58,20 @@
 
   **When this clause does NOT apply:** any repo with a non-empty barrel file, any monorepo (use the stratified-scope clause), or any single-package repo whose `scope.type` is explicitly `public-api` / `specific-modules` / `component-library` / `docs-only` (those scope types have their own denominator semantics). Also does NOT apply when `scope.type: "reference-app"` — that scope type carries its own pattern-surface denominator semantics (the brief speaks for itself), so this clause's filesystem trigger is moot.
 
+- **Single-crate curated subset (`scope.type: "specific-modules"`):** If the source is a single-package (non-monorepo) repo whose skill brief sets `scope.type: "specific-modules"` and uses `scope.include`/`scope.exclude` to carve a subset of the crate's public surface, the coverage denominator is the **in-scope reachable barrel** — not the full barrel.
+
+  **Resolution:** Derive the barrel as normal for the language (e.g., Rust: `pub use` chain from `lib.rs`), then filter:
+
+  1. **Exclude** any modules or items that fall under `scope.exclude` patterns.
+  2. **Include only** items reachable from the modules listed in `scope.include`.
+  3. **Respect module visibility:** items behind `mod` (not `pub mod`) boundaries that are not re-exported through the barrel are unreachable and excluded. For Rust: count only unrestricted, module-level (column-0) `pub` item declarations in barrel-reachable modules; exclude `pub(crate)` / `pub(super)` / `pub(in …)` restricted items.
+
+  The resulting count is the denominator. Annotate the coverage report with: `Specific-modules subset — denominator: in-scope reachable barrel ({N} items from {M} modules, after scope.include/exclude filtering)`.
+
+  **When `effective_denominator` is present:** prefer `metadata.json.stats.effective_denominator` (same priority-1 rule as the stratified-scope clause), subject to the same deflation guard.
+
+  **When this clause does NOT apply:** monorepo packages (use the stratified-scope clause), `scope.type: "full-library"` (use the standard barrel), or empty-barrel packages (use the empty-barrel clause). This clause is specifically for single-crate repos where the brief intentionally documents a curated subset rather than the full public surface.
+
 Internal module symbols are **excluded** from the coverage denominator unless they are explicitly documented in SKILL.md (in which case they count as documented extras, not missing coverage).
 
 This matches the extraction-patterns.md convention used during skill creation: coverage measures how well SKILL.md documents what users actually import, not the entire internal codebase.