bmad-module-skill-forge 1.5.1 → 1.7.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,7 @@ 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. |
 | `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 +60,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 +88,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 +119,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/continue.md

@@ -6,6 +6,7 @@ nextStepOptions:
   step 4: 'map-and-detect.md'
   step 5: 'recommend.md'
   step 6: 'generate-briefs.md'
+  step 7: 'health-check.md'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -61,8 +62,9 @@ Map the last completed step to the next step file:
 | identify-units | map-and-detect |
 | map-and-detect | recommend |
 | recommend | generate-briefs |
+| generate-briefs | health-check |
 
-**IF all steps completed:**
+**IF `health-check` is in `stepsCompleted`:**
 "**This analysis appears to be complete.** All steps have been finished. Would you like to start a new analysis?"
 
 ### 5. Update and Route

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

@@ -13,6 +13,8 @@ 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.** 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
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
@@ -81,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:

package/src/skf-brief-skill/references/analyze-target.md

@@ -32,9 +32,15 @@ To analyze the target repository by resolving its location, reading its structur
 ### 1. Resolve Target Location
 
 **For GitHub URLs:**
+
+**Resolve the analysis ref first.** `{analysis_ref}` is the git ref every GitHub-API fetch in this step (tree, manifests, contents) reads from — resolve it before fetching anything so the analyzed structure matches the version being skilled:
+- If neither `target_ref` nor `target_version` was set in step 01: `{analysis_ref}` = `HEAD` (default branch). This is the common case — skip straight to the probes below with no extra call.
+- If `target_ref` is set (an explicit ref the user stated verbatim, highest priority): use it directly as `{analysis_ref}` — no tag lookup.
+- If `target_version` is set: resolve it to a tag via `gh api repos/{owner}/{repo}/git/refs/tags` (paginate if the repo has many tags), matching in priority order — exact `{target_version}`, then `v{target_version}`. This mirrors the clone-path tag matching in `skf-create-skill/references/source-resolution-protocols.md` (see that file for the full monorepo-tag priority if the simple forms miss). On a single match, set `{analysis_ref}` to that tag. On **multiple matches**, present them and ask which to use (headless: take the exact match, else the `v`-prefixed one). On **zero matches**, warn `"No git tag matches version {target_version}; analyzing the default branch (HEAD) instead — structure and exports may not match the pinned version."`, set `{analysis_ref}` = `HEAD`, and record the fallback in the §5 analysis summary.
+
 - Issue both probes in **one message with two parallel Bash calls** — they are independent:
   - `gh api repos/{owner}/{repo}` (verify repo exists)
-  - `gh api repos/{owner}/{repo}/git/trees/HEAD?recursive=1` (fetch file tree)
+  - `gh api repos/{owner}/{repo}/git/trees/{analysis_ref}?recursive=1` (fetch file tree at the resolved ref)
 - If the repo-existence probe fails, fall through to the failure-class triage below; the tree response from the parallel call is discarded in that case.
 
 **Truncation detection:** After receiving the tree response, check the `truncated` field in the JSON output. If `truncated: true`:
@@ -73,8 +79,8 @@ echo '{"tree": [<flat list of repo-relative file paths>], "manifests": {"package
   uv run {detectWorkspacesHelper}
 ```
 
-- **`tree`** — pass the flat list of repo-relative file paths already fetched in §1 (for GitHub: the `path` values from the `gh api .../git/trees/HEAD?recursive=1` response; for local: the equivalent listing).
-- **`manifests`** — only the root manifests need contents; child-workspace manifests are looked up from the tree by the script. Include any of `package.json`, `Cargo.toml`, `pnpm-workspace.yaml`, `lerna.json` that appears at the repo root. Fetch them in **one message with N parallel Bash calls** (`gh api .../contents/{path}` for GitHub, file reads for local), then base64-decode together. Per-workspace manifest contents (e.g. `packages/foo/package.json`) are optional — including them populates the workspace `name` field with the manifest's declared package name; omitting them falls back to the directory basename.
+- **`tree`** — pass the flat list of repo-relative file paths already fetched in §1 (for GitHub: the `path` values from the `gh api .../git/trees/{analysis_ref}?recursive=1` response; for local: the equivalent listing).
+- **`manifests`** — only the root manifests need contents; child-workspace manifests are looked up from the tree by the script. Include any of `package.json`, `Cargo.toml`, `pnpm-workspace.yaml`, `lerna.json` that appears at the repo root. Fetch them in **one message with N parallel Bash calls** (`gh api .../contents/{path}?ref={analysis_ref}` for GitHub, file reads for local), then base64-decode together. Per-workspace manifest contents (e.g. `packages/foo/package.json`) are optional — including them populates the workspace `name` field with the manifest's declared package name; omitting them falls back to the directory basename.
 
 The script returns a JSON envelope: `{is_monorepo, manifest_kind, workspaces[], warnings[]}`. Apply the result deterministically — see `src/shared/scripts/schemas/workspace-detection.v1.json` for the full contract.
 
@@ -96,6 +102,8 @@ Headless: if the input contract supplied an `include` glob that begins with one
 
 Surface any non-empty `warnings[]` from the script to the operator log so a malformed root manifest is debuggable; the workflow does not HALT — falling back to repo-root analysis is always safe.
 
+**`cross-ecosystem workspace ignored` warning:** when a root workspace manifest from a different language ecosystem co-exists with the surfaced one (e.g. a root `Cargo.toml [workspace]` alongside a pnpm workspace), the script surfaces only the higher-priority kind and emits this warning naming the ignored kind and its member count. The ignored ecosystem's workspaces are **not** in `workspaces[]`, so the numbered menu above will not list them. When this warning is present, tell the operator both ecosystems exist and ask which the skill should cover; if they pick the ignored ecosystem, scope §2-§4b at its root (or the relevant member) rather than the surfaced workspace, and carry the ignored kind into §3 (see the `workspace_signal` note there).
+
 ### 2. Read Repository Structure
 
 List the top-level directory structure:
@@ -117,10 +125,14 @@ List the top-level directory structure:
 Delegate the rule walk to `{detectLanguageHelper}` instead of evaluating manifest presence and extension frequency in prose:
 
 ```bash
-echo '{"tree": [<flat list of repo-relative file paths from §1>]}' | uv run {detectLanguageHelper}
+echo '{"tree": [<flat list of repo-relative file paths from §1>], "workspace_signal": "<§1b manifest_kind, or omit when null>"}' | uv run {detectLanguageHelper}
 ```
 
-The script returns `{language, confidence, detection_source, fallback_to_extension_frequency}` after walking the documented rule table (manifest presence first — package.json with tsconfig.json disambiguation, Cargo.toml, pyproject.toml/setup.py/setup.cfg, go.mod, pom.xml, build.gradle.kts, build.gradle Groovy with Java/Kotlin disambiguation, *.csproj/*.sln, Gemfile — then extension-frequency fallback over recognized source extensions). Use the returned values directly:
+Pass the §1b `manifest_kind` as `workspace_signal` (omit the key when it is `null` / not a monorepo). This gives the workspace root precedence: for a `cargo-workspace` or `python-multi-package` root, the script returns the root language (rust/python) instead of being misled into `typescript` by a nested `package.json` + `tsconfig.json` in a non-workspace subdirectory (e.g. a `docs/` or `website/` site). JS-family workspace kinds (`npm-workspaces`/`pnpm-workspaces`/`lerna`) carry no override — their root `package.json` resolves js/ts normally.
+
+**When §1b surfaced a `cross-ecosystem workspace ignored` warning and the operator chose the ignored ecosystem:** pass that ignored kind as `workspace_signal` (not the surfaced kind), so a co-located `cargo-workspace`/`python-multi-package` root resolves to rust/python instead of being pinned to the surfaced ecosystem's language by the workspace that won detection priority.
+
+The script returns `{language, confidence, detection_source, fallback_to_extension_frequency}` after walking the documented rule table (the `workspace_signal` precedence above first, then manifest presence — package.json with tsconfig.json disambiguation, Cargo.toml, pyproject.toml/setup.py/setup.cfg, go.mod, pom.xml, build.gradle.kts, build.gradle Groovy with Java/Kotlin disambiguation, *.csproj/*.sln, Gemfile — then extension-frequency fallback over recognized source extensions). Use the returned values directly:
 
 "**Detected language:** {language}
 **Confidence:** {confidence}
@@ -140,7 +152,7 @@ This section runs exactly one of §4.1 (script path) or §4.2 (fallback path) ba
 
 #### 4.1 Procedure — script-supported languages
 
-1. Read the relevant files into memory (no parsing yet — just collect content). For GitHub sources, issue **all N `gh api repos/{owner}/{repo}/contents/{file}` calls in a single message with N parallel Bash calls** (one per manifest + each entry point), then base64-decode the responses together — these are 2-4 independent fetches per typical run. For local sources read directly (also parallelisable, but local reads are fast enough that serial Read tool calls are acceptable).
+1. Read the relevant files into memory (no parsing yet — just collect content). For GitHub sources, issue **all N `gh api repos/{owner}/{repo}/contents/{file}?ref={analysis_ref}` calls in a single message with N parallel Bash calls** (one per manifest + each entry point), then base64-decode the responses together — these are 2-4 independent fetches per typical run. Carrying `{analysis_ref}` through here is what keeps the analyzed exports/version aligned with the pinned tag rather than HEAD. For local sources read directly (also parallelisable, but local reads are fast enough that serial Read tool calls are acceptable).
 
    | Language | Manifest | Entry points (mode=quick) |
    |----------|----------|--------------------------|
@@ -252,6 +264,10 @@ Present the complete analysis:
 - Docs: {found/not found — location}
 - Config: {list of config files found}
 - Version: {detected version or "Not detected — defaulting to 1.0.0"}
+{If the target was a GitHub URL:}
+- Analysis ref: {analysis_ref} {append " (resolved from target_version {target_version})" when a tag was matched, or " (no tag matched {target_version} — analyzed default branch)" on the zero-match fallback}
+
+Store `{analysis_ref}` in workflow context — step 03 (`scope-definition.md`) reuses it for any further `contents/` fetches so scope analysis reads the same ref as this step.
 
 ---
 

package/src/skf-brief-skill/references/confirm-brief.md

@@ -26,6 +26,8 @@ To present the complete skill brief in human-readable format, highlighting all f
 
 Use the values already accepted in steps 01-03 directly — do not re-load `{briefSchemaPath}` here. The 18 fields below are all in conversation; the schema is only consulted in §4 if an inline adjustment needs a specific field's validation rule cited.
 
+**Ratify run (`ratify_mode: true`):** steps 2-3 were skipped (interactive `[R]` at gather-intent §3.1a, or the headless §8 GATE `from_brief` route), so there is no fresh steps 01-03 output to compile. Use the brief context variables **hydrated from the parsed brief** at step 1 in place of that output — the hydrated variable names match the field references below one-for-one. `detected_version` is absent on this path; rely on the hydrated `version` (step 5 pins it via `version_resolved`).
+
 Compile all gathered data from steps 01-03 into the complete brief:
 
 - **name:** {skill name from step 01}
@@ -41,6 +43,7 @@ Compile all gathered data from steps 01-03 into the complete brief:
 - **scope.include:** {include patterns from step 03}
 - **scope.exclude:** {exclude patterns from step 03}
 - **scope.notes:** {any scope notes from step 03}
+- **scope.tier_a_include:** {tier-A authoring-surface patterns from step 03 §3c — omit if unset}
 - **scope.rationale:** {recommended -> chosen, reason — from step 03}
 - **source_type:** {source or docs-only, from step 01}
 - **doc_urls:** {collected documentation URLs with labels, from steps 01/03 — include if source_type is "docs-only" or supplemental URLs were collected}
@@ -69,6 +72,7 @@ Scope: {scope.type}
   Include: {scope.include patterns, one per line}
   Exclude: {scope.exclude patterns, one per line}
   Notes:   {scope.notes}
+  Tier-A:  {scope.tier_a_include patterns, one per line — omit this line entirely if scope.tier_a_include unset}
   Rationale: {chosen} chosen over {recommended} — {reason}
              {omit this line entirely if scope.rationale absent}