bmad-module-skill-forge 1.6.0 → 1.8.0

package/src/shared/scripts/skf-write-skill-brief.py

@@ -44,14 +44,19 @@ Context payload shape (consumed by `write`):
       "type":    "full-library" | ...,
       "include": ["src/**/*.ts"],
       "exclude": ["**/*.test.*"],
-      "notes":   ""
+      "notes":   "",
+      # Conditionally present (preserved verbatim on a ratify/re-write):
+      "tier_a_include": ["code/core/src/**"],   # stratified-scope monorepos
+      "amendments":     [{...}]                 # post-authoring audit log
     },
 
     # Conditionally present:
     "doc_urls":         [{"url": "...", "label": "..."}],
     "scripts_intent":   "detect" | "none" | free-text,
     "assets_intent":    "detect" | "none" | free-text,
-    "source_authority": "official" | "community" | "internal"
+    "source_authority": "official" | "community" | "internal",
+    "target_ref":       "livekit/v0.7.42",   # monorepo tag escape hatch
+    "source_ref":       "v0.5.0"             # auto-resolved git ref
   }
 
 Version precedence (resolved into the rendered YAML's `version` field):
@@ -84,14 +89,18 @@ Flat input form (`--from-flat`):
     "forge_tier":       "Quick",
     "created":          "2026-05-02",
     "created_by":       "armel",
-    "scope_type":       "full-library",
-    "scope_include":    ["src/**/*.ts"],
-    "scope_exclude":    ["**/*.test.*"],
-    "scope_notes":      "",
-    "doc_urls":         null | [...],
-    "scripts_intent":   null | "detect" | "none" | "...",
-    "assets_intent":    null | "detect" | "none" | "...",
-    "source_authority": null | "official" | "community" | "internal"
+    "scope_type":           "full-library",
+    "scope_include":        ["src/**/*.ts"],
+    "scope_exclude":        ["**/*.test.*"],
+    "scope_notes":          "",
+    "scope_tier_a_include": null | ["code/core/src/**"],
+    "scope_amendments":     null | [{...}],
+    "doc_urls":             null | [...],
+    "scripts_intent":       null | "detect" | "none" | "...",
+    "assets_intent":        null | "detect" | "none" | "...",
+    "source_authority":     null | "official" | "community" | "internal",
+    "target_ref":           null | "livekit/v0.7.42",
+    "source_ref":           null | "v0.5.0"
   }
 
 Output (success):
@@ -293,6 +302,42 @@ def validate_context(ctx: dict[str, Any]) -> list[str]:
                     field=f"scope.rationale.{rk}",
                 )
 
+    # scope.tier_a_include — optional narrower tier-A include list for
+    # stratified-scope monorepos (read by skf-test-skill for the coverage
+    # denominator). Absent/None → key omitted. When present it must be a list
+    # of glob strings; the writer preserves it verbatim so a ratify/re-write
+    # does not silently drop it.
+    tier_a_include = scope.get("tier_a_include")
+    if tier_a_include is not None:
+        if not isinstance(tier_a_include, list):
+            _die("scope.tier_a_include must be an array of glob strings", field="scope.tier_a_include")
+        for i, pat in enumerate(tier_a_include):
+            if not isinstance(pat, str) or not pat:
+                _die(
+                    f"scope.tier_a_include[{i}] must be a non-empty glob string",
+                    field="scope.tier_a_include",
+                )
+
+    # scope.amendments — optional additive audit log written post-authoring by
+    # skf-create-skill / skf-update-skill. The writer is not the amendments
+    # schema authority (those workflows own the entry shape); it only preserves
+    # the log verbatim on re-write. Light check: a list of objects.
+    amendments = scope.get("amendments")
+    if amendments is not None:
+        if not isinstance(amendments, list):
+            _die("scope.amendments must be an array of amendment objects", field="scope.amendments")
+        for i, entry in enumerate(amendments):
+            if not isinstance(entry, dict):
+                _die(f"scope.amendments[{i}] must be an object", field="scope.amendments")
+
+    # target_ref / source_ref — optional git refs (top-level). target_ref is a
+    # remote-monorepo tag escape hatch; source_ref is the auto-resolved ref.
+    # Both must round-trip on a ratify/re-write rather than being dropped.
+    for ref_field in ("target_ref", "source_ref"):
+        ref_val = ctx.get(ref_field)
+        if ref_val is not None and (not isinstance(ref_val, str) or not ref_val):
+            _die(f"{ref_field} must be a non-empty string when present", field=ref_field)
+
     # target_version semver shape (when present)
     tv = ctx.get("target_version")
     if tv is not None:
@@ -320,6 +365,19 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
     if source_type == "docs-only":
         source_authority = "community"  # forced
 
+    # Build the scope sub-object. tier_a_include (when present) sits between
+    # exclude and notes, matching the schema doc's illustrative order. Absent →
+    # the key is omitted, so briefs without it render byte-identically to before.
+    scope_obj: dict[str, Any] = {
+        "type": ctx["scope"]["type"],
+        "include": list(ctx["scope"]["include"]),
+        "exclude": list(ctx["scope"]["exclude"]),
+    }
+    scope_tier_a = ctx["scope"].get("tier_a_include")
+    if scope_tier_a is not None:
+        scope_obj["tier_a_include"] = list(scope_tier_a)
+    scope_obj["notes"] = ctx["scope"]["notes"]
+
     brief: dict[str, Any] = {
         "name": ctx["name"],
         "version": resolved_version,
@@ -330,12 +388,7 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
         "forge_tier": ctx["forge_tier"],
         "created": ctx["created"],
         "created_by": ctx["created_by"],
-        "scope": {
-            "type": ctx["scope"]["type"],
-            "include": list(ctx["scope"]["include"]),
-            "exclude": list(ctx["scope"]["exclude"]),
-            "notes": ctx["scope"]["notes"],
-        },
+        "scope": scope_obj,
     }
 
     # Conditional: scope.rationale — canonical position is after `notes` and
@@ -353,6 +406,13 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
             "recorded": scope_rationale["recorded"],
         }
 
+    # Conditional: scope.amendments — additive audit log, emitted verbatim after
+    # rationale (matches the schema doc order). The writer preserves it as-is;
+    # the writing authority for entry shape is skf-create-skill / skf-update-skill.
+    scope_amendments = ctx["scope"].get("amendments")
+    if scope_amendments is not None:
+        brief["scope"]["amendments"] = scope_amendments
+
     # Conditional: target_version (must equal version)
     tv = ctx.get("target_version")
     if tv is not None:
@@ -364,6 +424,14 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
             )
         brief["target_version"] = tv
 
+    # Conditional: target_ref / source_ref git refs — preserved verbatim when
+    # present (monorepo tag escape hatch + auto-resolved ref). Emitted after
+    # target_version so a ratify/re-write does not strip them.
+    for ref_field in ("target_ref", "source_ref"):
+        ref_val = ctx.get(ref_field)
+        if ref_val is not None:
+            brief[ref_field] = ref_val
+
     # Conditional: doc_urls (always emitted when present)
     doc_urls = ctx.get("doc_urls")
     if doc_urls:
@@ -412,8 +480,11 @@ def atomic_write(target: Path, content: str) -> int:
     target.parent.mkdir(parents=True, exist_ok=True)
     tmp = target.with_name(target.name + ".skf-tmp")
     encoded = content.encode("utf-8")
+    # O_BINARY (Windows only; 0 elsewhere) suppresses the text-mode \n -> \r\n
+    # translation that would otherwise corrupt verbatim writes on Windows.
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_BINARY", 0)
     try:
-        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+        fd = os.open(tmp, flags, 0o644)
         try:
             os.write(fd, encoded)
             os.fsync(fd)
@@ -439,6 +510,8 @@ _FLAT_SCOPE_KEYS = (
     "scope_exclude",
     "scope_notes",
     "scope_rationale",
+    "scope_tier_a_include",
+    "scope_amendments",
 )
 
 
@@ -493,6 +566,13 @@ def flat_to_nested(flat: dict[str, Any]) -> dict[str, Any]:
         # six-subkey object validated by validate_context.
         if "scope_rationale" in flat and flat["scope_rationale"] is not None:
             scope["rationale"] = flat["scope_rationale"]
+        # Optional stratified-scope tier-A include list and post-authoring
+        # amendments log. Same null-drop semantics — preserved on a ratify
+        # re-write so the brief's authored surface and audit trail survive.
+        if "scope_tier_a_include" in flat and flat["scope_tier_a_include"] is not None:
+            scope["tier_a_include"] = flat["scope_tier_a_include"]
+        if "scope_amendments" in flat and flat["scope_amendments"] is not None:
+            scope["amendments"] = flat["scope_amendments"]
         nested["scope"] = scope
     return nested
 

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

@@ -27,6 +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. 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.                                                                                                                        |
 
@@ -59,11 +61,15 @@ The create-skill workflow (extract) also performs version reconciliation at extr
 
 ```yaml
 scope:
-  type: full-library | specific-modules | public-api | component-library | docs-only
+  type: full-library | specific-modules | public-api | component-library | reference-app | docs-only
   include:
     - 'src/**/*.ts'          # At least one required
   exclude:
     - 'src/**/*.test.ts'     # Optional
+  # Optional: narrower tier-A include list for stratified-scope monorepos
+  # and reference-app pattern surfaces (refined later by skf-brief-skill)
+  # tier_a_include:
+  #   - 'code/core/src/manager-api/**'
   notes: 'Optional rationale for scope decision'
   # Additional fields when scope.type is "component-library":
   # registry_path: "path/to/registry.ts"  # Optional — auto-detected if omitted
@@ -83,8 +89,11 @@ scope:
 | specific-modules  | Selected components or packages                                                      |
 | public-api        | Only exported interfaces                                                             |
 | component-library | UI component libraries with registries, props-based APIs, and design system variants |
+| reference-app     | Whole app whose value is wiring patterns, not public exports (embedded sidecars, CLI demos, integration-pattern demonstrators). Also the home for **language / spec references** — engine- or spec-versioned query languages, grammars, or DSLs (e.g. SurrealQL) whose value is construct idioms, not exports. These have no separate scope type; they ride `reference-app` as a sub-shape (see `skf-create-skill` Language / spec-reference sub-shape) |
 | docs-only         | When source_type is docs-only — no source code available, all content from doc_urls  |
 
+> **Documented vs source language.** The `language` field records the language the skill *documents*. For a language / spec reference this may differ from the source language it is extracted from — e.g. a SurrealQL reference extracted from a Rust engine records `language: surrealql`, not `rust`. Use the documented language and a matching code-fence default (e.g. ` ```surql `) throughout the brief.
+
 ## YAML Template
 
 ```yaml
@@ -111,7 +120,7 @@ created_by: '{user_name}'
 1. **Name uniqueness**: No duplicate names within forge_data_folder
 2. **Source accessibility**: source_repo path must exist or be reachable
 3. **Language recognized**: Must be a known programming language
-4. **Scope type valid**: Must match one of the five defined types (full-library, specific-modules, public-api, component-library, docs-only)
+4. **Scope type valid**: Must match one of the six defined types (full-library, specific-modules, public-api, component-library, reference-app, docs-only)
 5. **Include patterns**: At least one include glob pattern required (exception: `docs-only` scope, where include patterns are optional since no source code is available)
 6. **Forge tier match**: Must match value in forge-tier.yaml
 7. **Docs-only mode**: When `source_type: "docs-only"`, `doc_urls` required (>= 1), `source_repo` optional

package/src/skf-analyze-source/references/generate-briefs.md

@@ -1,6 +1,9 @@
 ---
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 schemaFile: 'assets/skill-brief-schema.md'
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
 nextStepFile: 'health-check.md'
 ---
 
@@ -46,30 +49,47 @@ For EACH unit in `confirmed_units`, construct a skill-brief.yaml using:
 | name | Confirmed name from step 05 recommendation card |
 | version | Auto-detect from source (see schema Version Detection), fall back to `1.0.0` |
 | source_repo | `{project_paths[0]}` from frontmatter (or per-unit path if multi-repo) |
-| language | Primary language detected in step 03 |
+| language | Language the skill **documents** (primary language detected in step 03). For a language / spec reference this is the *documented* language, which may differ from the source language it is extracted from — e.g. a SurrealQL reference extracted from a Rust engine records `surrealql`, not `rust` (see {schemaFile} "Documented vs source language") |
 | scope.type | Scope type from step 05 recommendation card |
 | scope.include | Include patterns from step 05 recommendation card |
 | scope.exclude | Inferred from heuristics (test files, generated code) |
+| scope.tier_a_include | Optional — narrower tier-A surface for stratified-scope monorepos and `reference-app` pattern surfaces; usually left to skf-brief-skill to refine |
 | scope.notes | Rationale from step 05 recommendation card |
 | description | Description from step 05 recommendation card |
 | forge_tier | `{forge_tier}` from frontmatter |
-| created | Current date (ISO format YYYY-MM-DD) |
+| created | Current date as a **quoted** string in ISO format `'YYYY-MM-DD'` — quote it so YAML stores it as text, not a parsed date object (the schema, and the §3a gate, require a string) |
 | created_by | `{user_name}` from frontmatter |
 
 ### 3. Validate Each Brief
 
-For each generated brief, check against {schemaFile} validation rules:
+Validation has two parts: a **deterministic schema gate** (authoritative for structure) and **semantic cross-checks** the schema cannot express. Run the schema gate first.
+
+**3a. Deterministic schema gate.** Resolve `{validateBriefSchemaHelper}` from `{validateBriefSchemaProbeOrder}` (first existing path wins; HALT with a clear message if no candidate exists). For each generated brief, pipe the *exact* assembled YAML to the helper:
+
+```bash
+uv run {validateBriefSchemaHelper} - <<'YAML'
+{assembled-brief-yaml}
+YAML
+```
+
+The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}` — the same validator and contract `skf-brief-skill` runs at consumption time, so a brief that passes here will not be rejected there for structural reasons. Apply the result:
+
+- **`valid: false`** — the `errors[]` name the offending field (e.g. a `description` mis-indented under `scope:`, which leaves the required top-level `description` absent). Repair the assembled YAML and re-run the helper until `valid: true`. **Never write a brief that has not passed this gate.**
+- **`valid: true`** — carry any non-empty `warnings[]` into the §4 preview, then proceed.
+
+This catches structural YAML errors where they are created, rather than letting them surface downstream as a HALT in `skf-brief-skill`'s ratify path.
+
+**3b. Semantic cross-checks** (not expressible in the JSON schema — apply in addition to 3a):
 
 1. **Name uniqueness** — no duplicate names within the batch or existing skills
 2. **Source accessible** — project_path exists
 3. **Language recognized** — valid programming language identifier
-4. **Scope type valid** — matches `full-library`, `specific-modules`, `public-api`, or `component-library`
-5. **Include patterns** — at least one glob pattern present
-6. **Forge tier match** — matches forge_tier from config
+4. **Include patterns** — at least one glob pattern present (the schema requires the `scope.include` key but does not enforce a non-empty list)
+5. **Forge tier match** — matches forge_tier from config
 
-**If validation fails for any brief:**
+**If any check fails:**
 - Document the failure with specific field and reason
-- Present to user for correction before writing
+- Repair (3a structural errors) or present to user for correction (3b semantic issues) before writing
 - Do NOT write invalid briefs
 
 ### 4. Present Generation Preview
@@ -99,7 +119,7 @@ Wait for explicit user confirmation before writing files.
 
 For each confirmed brief:
 1. Create directory `{forge_data_folder}/{unit-name}/` if it does not exist
-2. Write `skill-brief.yaml` to `{forge_data_folder}/{unit-name}/skill-brief.yaml`
+2. Write `skill-brief.yaml` to `{forge_data_folder}/{unit-name}/skill-brief.yaml` — write the exact YAML that passed the §3a schema gate verbatim; do not re-serialize, so the bytes on disk are the bytes that validated
 3. Verify file was written successfully
 
 **IF user modifies (M):**
@@ -124,6 +144,7 @@ For each generated brief, recommend the appropriate next workflow:
 | Brief has `scope.type: component-library` and registry defines boundaries | create-skill — component boundaries defined by registry |
 | Brief has `scope.type: specific-modules` or scope needs refinement | brief-skill — refine scope before creating skill |
 | Brief has `scope.type: public-api` or complex interface | brief-skill — detailed scoping needed |
+| Brief has `scope.type: reference-app` | brief-skill — refine the pattern surface and capture `tier_a_include` before creating skill |
 | Unit flagged as stack skill candidate | create-stack-skill — after individual skills exist |
 | Unit flagged as already-skilled | update-skill — refresh existing skill |
 

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/recommend.md

@@ -57,7 +57,7 @@ For EACH qualifying unit, prepare a recommendation card:
 
 **Proposed Brief Fields:**
 - name: {suggested kebab-case name}
-- scope.type: {full-library / specific-modules / public-api / component-library}
+- scope.type: {full-library / specific-modules / public-api / component-library / reference-app / docs-only}
 - scope.include: {suggested glob patterns}
 - description: {suggested 1-3 sentence description}
 ```

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-brief-skill/SKILL.md

@@ -13,7 +13,7 @@ A good skill brief sets a tight, cohesive boundary: one capability with 3-8 prim
 
 Brief-skill is split from create-skill so the scoping conversation runs *once*, on cheap signals (manifests, top-level exports, intent), without paying for AST extraction. Compilation is expensive; scoping decisions are cheap to revise. Keeping them in separate workflows lets a user iterate on the brief, share it for review, and re-run create-skill against the same brief whenever the upstream version moves.
 
-**Ratify path (interactive only).** When the user already has a `skill-brief.yaml` produced by another workflow — typically `skf-analyze-source`'s `generate-briefs` step, where one analyze pass emits several recommended briefs — invoking `/skf-brief-skill` with a path to that brief at the first prompt routes to a fast-path review: gather-intent §3.1a loads the YAML, hydrates the brief context, and jumps straight to step 4 (confirm-brief) where the standard review/edit cycle still applies before step 5 writes. This skips re-deriving fields the upstream draft already supplies and saves the 5-10 minutes a full re-run of intent + analyze + scope would cost.
+**Ratify path.** When the user already has a `skill-brief.yaml` produced by another workflow — typically `skf-analyze-source`'s `generate-briefs` step, where one analyze pass emits several recommended briefs — the brief can be *ratified* (reviewed and rewritten without re-deriving its fields) instead of authored from scratch. **Interactively:** invoke `/skf-brief-skill` with a path to that brief at the first prompt — gather-intent §3.1a loads the YAML, hydrates the brief context, and jumps straight to step 4 (confirm-brief) where the standard review/edit cycle still applies before step 5 writes. **Headlessly:** pass `from_brief <path>` — the step 1 §8 GATE runs the same schema validation and hydration and writes through the canonical writer (overwriting in place), enabling a fully headless analyze → brief → create pipeline that preserves the upstream-authored scope. Either path skips re-deriving fields the upstream draft already supplies and saves the 5-10 minutes a full re-run of intent + analyze + scope would cost.
 
 ## Conventions
 
@@ -83,10 +83,10 @@ These rules apply to every step in this workflow:
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting] |
+| **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting], `from_brief` [optional: path to a pre-authored `skill-brief.yaml` to *ratify* — when supplied it is the source of truth, `target_repo`/`skill_name` become optional/derived-from-brief, and the run mirrors the interactive §3.1a ratify path: schema-validate, skip analyze-target/scope-definition, write through the canonical writer in place] |
 | **Gates** | step 1: Input Gate [use args] | step 3: Confirm Gate [C] | step 4: Confirm Gate [C] |
 | **Outputs** | `skill-brief.yaml` at `{forge_data_folder}/{skill-name}/skill-brief.yaml`; final `SKF_BRIEF_RESULT_JSON` line on stdout when `{headless_mode}` is true |
-| **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; pre-supplied inputs consumed at the gates that would otherwise prompt; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise) |
+| **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; pre-supplied inputs consumed at the gates that would otherwise prompt; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise); supplying `from_brief <path>` instead routes the step 1 GATE to a ratify path that schema-validates the pre-authored brief, skips analyze-target/scope-definition, and writes through the canonical writer (overwriting in place, no `--force` needed) rather than deriving a new brief |
 | **Transient-failure retry** | This workflow does **not** auto-retry network or subprocess failures. A failed `gh` fetch (analyze-target.md §1, portfolio-similarity-check.md), QMD probe, or extraction script is logged and surfaced in the final result envelope as a warning, but the workflow continues with whatever signal it has. Headless pipelines that want retry semantics should wrap the invocation at their orchestrator level (e.g. CI re-runner on non-zero exit). Rationale: brief-skill is read-mostly with one terminal write (the YAML at step 5); a partial-signal retry has more failure modes than just re-running the whole workflow, which is cheap. |
 | **Exit codes** | See "Exit Codes" below |
 

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

@@ -23,6 +23,7 @@
 | `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. |
 | `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.                                                                                                                        |
 | `scope.tier_a_include` | array | Glob patterns                                 | Optional. Narrower tier-A include list for stratified-scope monorepo skills. When present, `skf-test-skill` re-derives the coverage denominator from this list instead of the coarse `scope.include`, so the denominator reflects the authoring surface rather than incidentally-matched internal infrastructure. See `skf-test-skill/references/source-access-protocol.md` stratified-scope resolution. |
@@ -136,7 +137,7 @@ scope:
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `path` | string | yes | Relative path (or glob, for `category: "scope-expansion"`) from source root to the file or tree being amended. For `promoted` actions this matches the literal entry added to `scope.include`. |
-| `action` | string | yes | One of: `promoted` (path added to `scope.include`), `skipped` (user declined promotion; decision recorded to prevent re-prompting), `demoted-include` (path removed from `scope.include` — only valid with `category: "scope-expansion"`), `demoted-exclude` (path removed from `scope.exclude` — only valid with `category: "scope-expansion"`). |
+| `action` | string | yes | One of: `promoted` (path added to `scope.include`), `skipped` (user declined promotion; decision recorded to prevent re-prompting), `excluded` (path added to `scope.exclude` — only valid with `category: "scope-expansion"`; used by gap-driven rescope to remove an internal / `#[doc(hidden)]` / out-of-scope export from the public surface), `demoted-include` (path removed from `scope.include` — only valid with `category: "scope-expansion"`), `demoted-exclude` (path removed from `scope.exclude` — only valid with `category: "scope-expansion"`). |
 | `category` | string | no | One of: `auth-doc` (default for entries without this field — the historical sole use case), `scope-expansion`. Distinguishes which workflow path wrote the entry and which writer-rules apply on re-runs. |
 | `reason` | string | yes | Human-readable sentence explaining the decision. Either user-provided at prompt time or auto-generated. |
 | `heuristic` | string | conditional | Required for `category: "auth-doc"` — the basename that matched (`llms.txt`, `AGENTS.md`, etc.). Omit for `category: "scope-expansion"`. |
@@ -150,6 +151,8 @@ scope:
 
 **Demotion (scope-expansion only):** `demoted-include` removes a previously-promoted path from `scope.include` — used when a prior `[P]` decision is reversed. `demoted-exclude` removes a path from `scope.exclude` — used when a previously excluded path needs to be re-evaluated. Both write the structural change and append the amendment so future runs see the rationale. Demotion is not valid for `category: "auth-doc"`: auth-doc skips already prevent re-prompting without scope mutation.
 
+**Exclusion (scope-expansion only):** `excluded` adds a path to `scope.exclude` — written by `skf-update-skill` gap-driven rescope (detect-changes §0 rule R1) when a coverage gap's remediation is removal (the export is internal, `#[doc(hidden)]`, or out of scope). The amendment is the audit trail; the `scope.exclude` write is what shrinks the source barrel, so the legitimate scope reduction is expressed in the brief rather than by editing `metadata.stats`. This keeps the reduction visible to `skf-test-skill`'s denominator-deflation check, which re-derives the barrel from `scope.include` filtered by `scope.exclude`. Not valid for `category: "auth-doc"`.
+
 **Backward compatibility:** `scope.amendments` is optional. Briefs without this field validate unchanged. Treat missing as an empty list. Existing entries without `category` are equivalent to `category: "auth-doc"` — readers must default the field when absent.
 
 **Who reads `amendments[]`:**
@@ -165,6 +168,7 @@ scope:
 - `skf-create-skill` §2a (Discovered Authoritative Files Protocol) — `category: "auth-doc"`
 - `skf-update-skill` §1b (mirror of §2a applied during change detection) — `category: "auth-doc"`
 - `skf-update-skill` §1c (Major-Version Scope Reconciliation) — `category: "scope-expansion"`
+- `skf-update-skill` gap-driven rescope (detect-changes §0 rule R1) — `category: "scope-expansion"`, `action: "excluded"`
 - Manual edits by the brief author are permitted but should include all required fields above (and `category` when the entry is not an auth-doc decision).
 
 ## YAML Template
@@ -188,6 +192,7 @@ scope:
     - "{pattern}"
   notes: "{optional-scope-notes}"
 # target_version: "X.Y.Z"       # Optional: overrides auto-detection when specified
+# target_ref: "livekit/v0.7.42" # Optional: explicit git ref, used verbatim (monorepo crate tags)
 # source_ref: "v0.5.0"          # Auto-resolved — do not set manually
 # Optional: documentation URLs for T3 content (required when source_type: "docs-only")
 # doc_urls: