bmad-module-skill-forge 1.5.1 → 1.7.0

package/.claude-plugin/marketplace.json

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

package/docs/_data/pinned.yaml

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

package/docs/workflows.md

@@ -426,7 +426,7 @@ If the answer to all of these is "no", the health check exits in one line (`Clea
 
 ### How findings are routed
 
-- **Severity gate.** Only `bug` findings submit live as GitHub issues by default. `friction` and `gap` findings — the most subjective categories — go to a **local queue** at `{output_folder}/improvement-queue/` unless you explicitly opt in to submit them live during the review gate. This keeps the high-signal reports (real defects) flowing to maintainers while the softer observations sit safely on your disk for you to batch or revisit.
+- **Severity gate.** Only `bug` findings submit live as GitHub issues by default. `friction` and `gap` findings — the most subjective categories — go to a **local queue** at `{forge_data_folder}/improvement-queue/` unless you explicitly opt in to submit them live during the review gate. This keeps the high-signal reports (real defects) flowing to maintainers while the softer observations sit safely on your disk for you to batch or revisit.
 - **Fingerprint dedup.** Every finding gets a deterministic 7-hex fingerprint computed from `sha1(severity|workflow|step_file|section)` — no LLM similarity judgment, just a tuple hash. Before Ferris opens a new issue, it searches the repo for an existing open issue with the same `fp-*` label. If one exists, you're offered a choice: add a 👍 reaction (silent upvote), react + post a one-sentence environment delta, open a new issue anyway (if you're certain it's distinct), or skip. Re-reporting the same fingerprint is safe — it just adds to the signal-count on the canonical issue.
 - **Global seen-cache.** Once you've submitted or reacted for a given fingerprint, it's recorded at `~/.skf/health-check-seen.json` so the same user never re-reports the same defect across sessions or across different projects on the same machine.
 - **Server-side safety net.** If two users race past the client-side search and both open issues with the same fingerprint, a GitHub Action on this repo catches it: the later issue is auto-closed as a duplicate, linked to the canonical (lowest-numbered) issue, and a 👍 is added there to preserve the signal-count. Manual filers using the [issue template](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) feed the same pipeline.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.5.1",
+  "version": "1.7.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -53,7 +53,7 @@
     "test:cli": "node test/test-cli-integration.js",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py -v",
+    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-atomic-write.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py -v",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/src/knowledge/version-paths.md

@@ -119,9 +119,10 @@ When reading artifacts, resolve the skill path using the export manifest:
 1. Read `{skills_output_folder}/.export-manifest.json`
 2. Look up the skill name in `exports`
 3. Read `active_version` to get the target version
-4. Resolve to `{skill_package}` using the active version
-5. If manifest does not contain the skill: check for `active` symlink at `{skill_group}/active`
-6. If neither manifest nor symlink: fall back to flat-path resolution (migration — see below)
+4. **Manifest-lag guard.** If the `active` symlink at `{skill_group}/active` resolves to a *different* version than the manifest's `active_version`, prefer the **symlink target** and emit an Info note. The manifest `active_version` only advances when `export-skill` runs, but the `active` symlink is flipped forward by every writing workflow (CS/QS/SS/US) the instant it commits a new version. So in the canonical SS→TS→EX order the manifest lags the just-forged version in the window between forge and export — a manifest-first read would otherwise resolve the *previously exported* version. Preferring the symlink target closes this gap (and, for `export-skill`, makes that export publish the forged version and reconcile the manifest). This guard never overrides legitimate state: `drop-skill` — the only workflow that switches the active version — repoints the symlink to the manifest's `active_version` (it never leaves them diverged), and no workflow flips the symlink *backward*, so the only divergence that can occur is exactly this forge→export lag.
+5. Resolve to `{skill_package}` using the chosen version — the symlink target when it diverges per step 4, otherwise `active_version`
+6. If manifest does not contain the skill: check for `active` symlink at `{skill_group}/active`
+7. If neither manifest nor symlink: fall back to flat-path resolution (migration — see below)
 
 ### Manifest-Driven Snippet Scanning (EX Step-04)
 

package/src/shared/health-check.md

@@ -3,7 +3,7 @@ name: 'health-check'
 description: 'Workflow self-improvement health check — captures real friction as GitHub issues'
 # No nextStepFile — this is always the terminal step
 healthCheckRepo: '{health_check_repo}'
-localFallbackFolder: '{output_folder}/improvement-queue'
+localFallbackFolder: '{forge_data_folder}/improvement-queue'  # forge workspace artifact — use forge_data_folder (single, unambiguous SKF var), NOT output_folder (a Core Config var that resolves differently across co-installed BMad modules)
 seenCachePath: '$HOME/.skf/health-check-seen.json'
 liveSubmitSeverities: ['bug']  # friction/gap go local-queue-default with explicit opt-in
 ---

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

@@ -21,6 +21,11 @@
       "pattern": "^v?\\d+\\.\\d+\\.\\d+([.\\-+][0-9A-Za-z][0-9A-Za-z.\\-+]*)?$",
       "description": "User-specified target. When present, MUST equal version."
     },
+    "target_ref": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional explicit git ref (tag or branch) used verbatim as source_ref, bypassing version-to-tag matching. Escape hatch for monorepo crate tags whose prefix differs from the skill name (e.g. tag livekit/v0.7.42 for skill livekit-rust). Remote sources only."
+    },
     "source_type": {
       "type": "string",
       "enum": ["source", "docs-only"]

package/src/shared/scripts/skf-atomic-write.py

@@ -144,8 +144,11 @@ def cmd_write(target: Path) -> None:
     data = sys.stdin.buffer.read()
     target.parent.mkdir(parents=True, exist_ok=True)
     tmp = target.with_name(target.name + ".skf-tmp")
+    # 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, data)
             os.fsync(fd)

package/src/shared/scripts/skf-description-guard.py

@@ -160,17 +160,45 @@ def is_diverged(diff_kind: str) -> bool:
 def restore_description(skill_md: Path, captured: str) -> None:
     """Atomically rewrite SKILL.md so its frontmatter `description` equals captured.
 
-    Preserves frontmatter key order and surrounding whitespace by doing a
-    line-level rewrite of just the `description:` value, not a full YAML
-    re-dump (which would re-order keys, change quoting style, and likely
-    fail roundtrip tests downstream).
+    Parses the entire frontmatter via PyYAML, replaces the top-level
+    `description` value, and re-emits the frontmatter via `yaml.safe_dump`.
+    This guarantees valid YAML output regardless of the source representation
+    (inline, double-quoted, single-quoted, folded `>`, literal `|`), and
+    avoids the line-level pitfalls a previous implementation had with folded
+    block scalars and nested `description:` keys in sibling mappings.
+
+    Key order is preserved (PyYAML's `safe_dump` honours dict insertion order;
+    this module's `requires-python = ">=3.10"` guarantees ordered dicts).
+    Quoting style of *other* fields may change to whatever `safe_dump`
+    chooses for each scalar — downstream readers parse YAML, so any valid
+    YAML emission is acceptable.
     """
     text = skill_md.read_text(encoding="utf-8")
     leading, fm_yaml, body = _split_frontmatter(text)
     if not fm_yaml:
         raise ValueError(f"cannot restore: no frontmatter in {skill_md}")
 
-    new_fm = _rewrite_description_line(fm_yaml, captured)
+    try:
+        fm = yaml.safe_load(fm_yaml)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"frontmatter in {skill_md} is not valid YAML: {exc}") from exc
+    if not isinstance(fm, dict):
+        raise ValueError(f"frontmatter in {skill_md} is not a mapping")
+    if "description" not in fm:
+        raise ValueError(f"frontmatter in {skill_md} has no `description` field")
+
+    fm["description"] = captured
+
+    # `width=10**9` keeps the description on one line regardless of length;
+    # PyYAML otherwise inserts line breaks at ~80 chars which would re-introduce
+    # folded-scalar continuation lines — the exact failure mode this rewrite fixes.
+    new_fm = yaml.safe_dump(
+        fm,
+        sort_keys=False,
+        default_flow_style=False,
+        allow_unicode=True,
+        width=10**9,
+    ).rstrip("\n")
     new_text = f"{leading}{new_fm}\n---\n{body}"
 
     # atomic: write to a sibling temp file, fsync, rename
@@ -191,81 +219,6 @@ def restore_description(skill_md: Path, captured: str) -> None:
         raise
 
 
-def _rewrite_description_line(fm_yaml: str, new_description: str) -> str:
-    """Replace the `description:` value in a YAML frontmatter block.
-
-    Preserves other keys verbatim. Handles three common shapes:
-      description: single-line value
-      description: "double-quoted value"
-      description: |     # block scalar (folded variant: >)
-        multi-line
-        value here
-    """
-    lines = fm_yaml.split("\n")
-    out: list[str] = []
-    i = 0
-    quoted = _yaml_quote_inline(new_description)
-    replaced = False
-    while i < len(lines):
-        line = lines[i]
-        if not replaced and _is_description_key_line(line):
-            stripped = line.lstrip()
-            indent = line[: len(line) - len(stripped)]
-            # detect block-scalar indicator (| or >)
-            after_key = stripped[len("description:") :].lstrip()
-            if after_key.startswith("|") or after_key.startswith(">"):
-                # skip block-scalar continuation lines (deeper indent than the key line)
-                key_indent = len(indent)
-                i += 1
-                while i < len(lines):
-                    nxt = lines[i]
-                    if nxt.strip() == "":
-                        # blank lines belong to the block scalar
-                        i += 1
-                        continue
-                    nxt_indent = len(nxt) - len(nxt.lstrip())
-                    if nxt_indent <= key_indent:
-                        break
-                    i += 1
-                out.append(f"{indent}description: {quoted}")
-                replaced = True
-                continue
-            out.append(f"{indent}description: {quoted}")
-            replaced = True
-            i += 1
-            continue
-        out.append(line)
-        i += 1
-    if not replaced:
-        raise ValueError("description key not found while rewriting frontmatter")
-    return "\n".join(out)
-
-
-def _is_description_key_line(line: str) -> bool:
-    stripped = line.lstrip()
-    return stripped.startswith("description:") and (
-        len(stripped) == len("description:") or stripped[len("description:")] in (" ", "\t", "")
-    )
-
-
-def _yaml_quote_inline(value: str) -> str:
-    """Emit a YAML scalar suitable as the inline value of `description: `.
-
-    Uses double-quoted form so control characters and embedded quotes are
-    safe. Block scalars (| / >) are not used — the description field is a
-    single semantic string and downstream readers (skill-check, agentskills)
-    expect inline form.
-    """
-    escaped = (
-        value.replace("\\", "\\\\")
-        .replace("\"", "\\\"")
-        .replace("\n", "\\n")
-        .replace("\r", "\\r")
-        .replace("\t", "\\t")
-    )
-    return f'"{escaped}"'
-
-
 # --------------------------------------------------------------------------
 # CLI
 # --------------------------------------------------------------------------

package/src/shared/scripts/skf-detect-language.py

@@ -14,6 +14,13 @@ co-located with a deterministic rule rather than restated in prose.
 
 Detection rules (apply in order, first match wins):
 
+  0. workspace_signal (optional, from skf-detect-workspaces.manifest_kind):
+       "cargo-workspace"       → rust (high)
+       "python-multi-package"  → python (high)
+       A non-JS workspace root's language wins over a nested package.json +
+       tsconfig.json (e.g. a docs/ or website/ site that is not a workspace
+       member). JS-family workspaces (npm/pnpm/lerna) carry no entry here and
+       fall through to rule 1, whose root package.json correctly resolves js/ts.
   1. package.json (with optional tsconfig.json companion):
        tsconfig.json present → typescript (high)
        tsconfig.json absent  → javascript (high)
@@ -37,6 +44,10 @@ CLI:
 
 Input (JSON object on stdin or via --json):
   tree — list of repo-relative file paths (required, non-empty)
+  workspace_signal — optional manifest_kind from skf-detect-workspaces. When it
+                     names a non-JS workspace ("cargo-workspace",
+                     "python-multi-package"), rule 0 returns the root language
+                     and ignores nested package.json/tsconfig matches.
 
 Output (JSON on stdout):
   language          — javascript | typescript | rust | python | go
@@ -60,6 +71,17 @@ import sys
 from collections import Counter
 from typing import Any
 
+# Workspace manifest_kind → root language (rule 0). Only non-JS workspace kinds
+# appear here: a Cargo/Python workspace root is unambiguously rust/python, and a
+# nested package.json+tsconfig (a docs or website subproject) must not win. JS
+# workspace kinds (npm-workspaces/pnpm-workspaces/lerna) are intentionally
+# absent — their root manifest IS package.json, so rule 1 resolves js/ts
+# correctly. generic-folders / null carry no language signal.
+_WORKSPACE_SIGNAL_LANGUAGE: dict[str, str] = {
+    "cargo-workspace": "rust",
+    "python-multi-package": "python",
+}
+
 # Manifest basenames the rule table checks. Kept tight — tree-wide pattern
 # matches (e.g. *.csproj) are handled separately to avoid false positives
 # from generated artifacts under build/ or dist/.
@@ -185,6 +207,18 @@ def detect(payload: dict[str, Any]) -> dict[str, Any]:
     if len(tree) == 0:
         _die("payload.tree must be non-empty")
 
+    # Rule 0 — workspace precedence. A non-JS workspace root (from
+    # skf-detect-workspaces.manifest_kind) wins over any nested package.json +
+    # tsconfig.json, which would otherwise be misread as a typescript root.
+    workspace_signal = payload.get("workspace_signal")
+    if isinstance(workspace_signal, str) and workspace_signal in _WORKSPACE_SIGNAL_LANGUAGE:
+        return {
+            "language": _WORKSPACE_SIGNAL_LANGUAGE[workspace_signal],
+            "confidence": "high",
+            "detection_source": f"workspace manifest_kind={workspace_signal} (root manifest wins over nested package.json)",
+            "fallback_to_extension_frequency": False,
+        }
+
     # Rule 1 — package.json (with tsconfig.json disambiguation)
     if _has_basename(tree, "package.json"):
         if _has_basename(tree, "tsconfig.json"):

package/src/shared/scripts/skf-detect-workspaces.py

@@ -361,6 +361,59 @@ DETECTORS: list[tuple[str, callable]] = [
     ("generic-folders",      detect_generic_folders),
 ]
 
+# Language ecosystem each manifest kind belongs to. Drives the cross-ecosystem
+# secondary-manifest warning below. `generic-folders` is intentionally absent —
+# it is a tree-shape heuristic, not a distinct root workspace manifest, so it
+# never participates in cross-ecosystem warnings.
+ECOSYSTEM_OF_KIND = {
+    "npm-workspaces":       "js",
+    "pnpm-workspaces":      "js",
+    "lerna":                "js",
+    "cargo-workspace":      "rust",
+    "python-multi-package": "python",
+}
+
+ROOT_MANIFEST_OF_KIND = {
+    "npm-workspaces":       "package.json",
+    "pnpm-workspaces":      "pnpm-workspace.yaml",
+    "lerna":                "lerna.json",
+    "cargo-workspace":      "Cargo.toml",
+    "python-multi-package": None,  # discovered from the tree; no single root manifest
+}
+
+
+def _cross_ecosystem_warnings(
+    primary_kind: str, tree: set[str], manifests: dict[str, str]
+) -> list[str]:
+    """Warn when a root workspace manifest from a *different* language ecosystem
+    than the surfaced one also resolves members.
+
+    First-match-wins detection silently drops a co-located workspace from another
+    ecosystem (e.g. a root `Cargo.toml [workspace]` when a pnpm workspace wins),
+    which then poisons downstream language detection and the §1b workspace menu.
+    This re-runs only the manifest-backed detectors from a different ecosystem,
+    against a throwaway warnings sink so their parse errors are not propagated,
+    and emits one warning per ignored cross-ecosystem kind that resolves >=1
+    member. The surfaced `manifest_kind` / `workspaces` are left unchanged.
+    """
+    primary_eco = ECOSYSTEM_OF_KIND.get(primary_kind)
+    out: list[str] = []
+    for kind, detector in DETECTORS:
+        eco = ECOSYSTEM_OF_KIND.get(kind)
+        if kind == primary_kind or eco is None or eco == primary_eco:
+            continue  # self, generic-folders, or same ecosystem as the winner
+        result = detector(tree, manifests, [])
+        if result and len(result) >= 1:
+            manifest = ROOT_MANIFEST_OF_KIND.get(kind)
+            where = f" (root {manifest})" if manifest else ""
+            out.append(
+                f"cross-ecosystem workspace ignored: {kind}{where} resolves "
+                f"{len(result)} member(s) but only {primary_kind} was surfaced. "
+                f"If the skill targets the {kind} ecosystem, re-scope to it — "
+                f"language detection keys off the surfaced manifest_kind."
+            )
+    return out
+
 
 # --------------------------------------------------------------------------
 # Entry point
@@ -381,6 +434,7 @@ def detect(payload: dict) -> dict:
     for kind, detector in DETECTORS:
         result = detector(tree, manifests, warnings)
         if result and len(result) >= 1:
+            warnings.extend(_cross_ecosystem_warnings(kind, tree, manifests))
             return {
                 "is_monorepo":   True,
                 "manifest_kind": kind,

package/src/shared/scripts/skf-enumerate-stack-skills.py

@@ -24,11 +24,16 @@ benefit from LLM judgment).
 Subcommand:
   enumerate <skills-root>
       Emit JSON {"skills": [...], "cycles": [...], "warnings": [...]}
-      describing every subdirectory of <skills-root> that contains a
-      SKILL.md. Each entry carries:
-
-        name             — skill name (subdirectory name)
-        path             — relative path under skills-root, forward-slash
+      describing every subdirectory of <skills-root> that resolves to a
+      skill package. Both layouts from knowledge/version-paths.md are
+      supported: the flat layout (<child>/SKILL.md) and the version-nested
+      layout (<child>/active/<name>/SKILL.md via the `active` symlink, or
+      <child>/<version>/<name>/SKILL.md by highest version). Each entry
+      carries:
+
+        name             — skill name (top-level subdirectory name)
+        path             — relative path to the resolved package under
+                           skills-root, forward-slash
         exports          — exports list resolved via cascade
         exports_source   — "metadata|references|skill-md|unknown"
         confidence       — "T1|T2|T1-low" (mapped from exports_source)
@@ -393,6 +398,80 @@ def detect_cycles(graph: dict[str, list[str]]) -> list[str]:
     return sorted(cycle_nodes)
 
 
+# --------------------------------------------------------------------------
+# Version-nested layout resolution
+# --------------------------------------------------------------------------
+
+
+def _version_sort_key(name: str) -> tuple:
+    """Sort key for version directory names — higher sorts as newer.
+
+    Parses the leading dotted numeric core (`N.N.N`); a pre-release suffix
+    (`-rc1`, `-beta.2`, ...) ranks below the same core release. Names without
+    a numeric core rank lowest. Deterministic tie-break on the raw name.
+    """
+    core, _, pre = name.partition("-")
+    nums: list[int] = []
+    for part in core.split("."):
+        if part.isdigit():
+            nums.append(int(part))
+        else:
+            break
+    return (tuple(nums), 0 if pre == "" else -1, name)
+
+
+def _inner_package(version_dir: Path) -> Path | None:
+    """Within a version directory, return the inner package dir holding SKILL.md.
+
+    Matches the `{version}/{skill-name}/SKILL.md` shape from
+    knowledge/version-paths.md. Returns None if no inner dir has a SKILL.md.
+    """
+    try:
+        for inner in sorted(version_dir.iterdir()):
+            if inner.is_dir() and (inner / "SKILL.md").is_file():
+                return inner
+    except OSError:
+        return None
+    return None
+
+
+def _resolve_package_dir(child: Path) -> Path | None:
+    """Resolve the agentskills package dir (the one containing SKILL.md).
+
+    Supports both layouts defined in knowledge/version-paths.md:
+      - flat:           {child}/SKILL.md
+      - version-nested: {child}/active/{skill-name}/SKILL.md (via the `active`
+                        symlink) or {child}/{version}/{skill-name}/SKILL.md.
+
+    For the nested layout the `active` symlink wins; otherwise the highest
+    version directory by semver precedence is used. Returns None when no
+    SKILL.md is reachable (caller skips the entry as a non-package).
+    """
+    # Flat layout — direct SKILL.md.
+    if (child / "SKILL.md").is_file():
+        return child
+
+    # Nested layout — prefer the stable `active` pointer.
+    active = child / "active"
+    if active.is_dir():  # is_dir() follows the symlink; False if broken
+        pkg = _inner_package(active)
+        if pkg is not None:
+            return pkg
+
+    # Fallback — highest version directory.
+    try:
+        version_dirs = [
+            d for d in child.iterdir() if d.is_dir() and d.name != "active"
+        ]
+    except OSError:
+        return None
+    for vdir in sorted(version_dirs, key=lambda d: _version_sort_key(d.name), reverse=True):
+        pkg = _inner_package(vdir)
+        if pkg is not None:
+            return pkg
+    return None
+
+
 # --------------------------------------------------------------------------
 # Enumeration entry point
 # --------------------------------------------------------------------------
@@ -416,8 +495,10 @@ def enumerate_stack_skills(skills_root: Path) -> dict:
         if name.startswith("."):
             continue
 
-        # Symlink fallback — resolve and verify target is a directory we
-        # can read. If anything fails, warn and skip the entry.
+        # Symlink fallback — a child-level symlink (e.g. a top-level `active`
+        # pointer) must resolve to a readable directory. If it's broken, warn
+        # and skip; otherwise keep the original path so the reported `path`
+        # stays relative to skills_root.
         if child.is_symlink():
             try:
                 target = child.resolve(strict=True)
@@ -431,16 +512,18 @@ def enumerate_stack_skills(skills_root: Path) -> dict:
                     f"{name}: symlink target is not a directory"
                 )
                 continue
-            skill_dir = target
-        else:
-            if not child.is_dir():
-                continue
-            skill_dir = child
+        elif not child.is_dir():
+            continue
 
-        # Require SKILL.md to consider this a skill package. Subdirs
-        # without SKILL.md (e.g. `shared/`, `knowledge/`) are skipped
-        # silently — they're not skill packages by definition.
-        if not (skill_dir / "SKILL.md").is_file():
+        # Resolve the package dir across flat and version-nested layouts
+        # (knowledge/version-paths.md). Subdirs with no reachable SKILL.md
+        # (e.g. `shared/`, `knowledge/`) are skipped silently — not packages.
+        try:
+            skill_dir = _resolve_package_dir(child)
+        except OSError as exc:
+            result["warnings"].append(f"{name}: failed to resolve package dir ({exc})")
+            continue
+        if skill_dir is None:
             continue
 
         try:
@@ -449,6 +532,14 @@ def enumerate_stack_skills(skills_root: Path) -> dict:
             result["warnings"].append(f"{name}: enumeration failed: {exc}")
             continue
 
+        # Reflect the resolved package location (forward-slash, relative to
+        # skills_root) — for the nested layout this is the `{active_skill}`
+        # path, for the flat layout just the skill name.
+        try:
+            entry["path"] = skill_dir.relative_to(skills_root).as_posix()
+        except ValueError:
+            entry["path"] = name
+
         result["skills"].append(entry)
         result["warnings"].extend(skill_warnings)
         compose_graph[name] = composes

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

@@ -146,8 +146,11 @@ def _atomic_write(target: Path, content: str) -> None:
     """Crash-safe write via temp + fsync + rename. Mirrors skf-atomic-write.py."""
     target.parent.mkdir(parents=True, exist_ok=True)
     tmp = target.with_name(target.name + ".skf-tmp")
+    # 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, content.encode("utf-8"))
             os.fsync(fd)

package/src/shared/scripts/skf-manifest-ops.py

@@ -135,13 +135,17 @@ def cmd_set(manifest_path, skill_name, version, ides=None):
     existing = exports.get(skill_name, {})
     today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
 
-    # Preserve existing versions dict, archive the previously-active version
+    # Preserve existing versions dict, archive every *other* still-active version.
+    # Archiving by status (rather than only the entry matching the prior
+    # active_version) keeps a single active version even when active_version was
+    # advanced to this version before set() ran — otherwise the genuine prior
+    # version would stay active, breaking the single-active invariant. Idempotent.
     versions = existing.get("versions", {})
     if isinstance(versions, list):
         versions = {}  # Safety: handle any residual v1 data
-    old_active = existing.get("active_version")
-    if old_active and old_active in versions and old_active != version:
-        versions[old_active]["status"] = "archived"
+    for other_version, other_entry in versions.items():
+        if other_version != version and other_entry.get("status") == "active":
+            other_entry["status"] = "archived"
 
     # Add or update the new active version. Absent --ides preserves the
     # existing ides/platforms list verbatim (backward-compatible). When

package/src/shared/scripts/skf-merge-ccc-exclusions.py

@@ -119,8 +119,11 @@ def _atomic_write(target: Path, content: str) -> None:
     """Crash-safe write via temp + fsync + rename. Mirrors skf-atomic-write.py."""
     target.parent.mkdir(parents=True, exist_ok=True)
     tmp = target.with_name(target.name + ".skf-tmp")
+    # 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, content.encode("utf-8"))
             os.fsync(fd)

package/src/shared/scripts/skf-qmd-classify-collections.py

@@ -89,6 +89,9 @@ import yaml
 FORGE_SUFFIXES = ("-brief", "-temporal", "-docs", "-extraction")
 FOREIGN_SAMPLE_CAP = 5
 
+# Header line emitted by newer qmd builds, e.g. "Collections (56):".
+_QMD_HEADER_RE = re.compile(r"^Collections \(\d+\):\s*$")
+
 
 def _die(code: int, message: str) -> None:
     print(json.dumps({"status": "error", "message": message}), file=sys.stderr)
@@ -184,6 +187,31 @@ def classify(live: list[str], registry: list[str]) -> dict:
     }
 
 
+def parse_collection_list_output(raw: str) -> list[str]:
+    """Extract collection names from `qmd collection list` stdout.
+
+    qmd's output format varies by version. Newer builds print a
+    `Collections (N):` header, a blank line between entries, each entry as
+    `<name> (qmd://<name>/)`, and indented metadata lines (`  Pattern:`,
+    `  Files:`). Older builds print one bare name per line. Both layouts are
+    handled: skip blank lines, the header, and indented metadata, then take
+    the first whitespace-delimited token of each remaining line — that strips
+    the trailing ` (qmd://name/)` URI and is a no-op for the bare-name form.
+    Without this, suffixed entries fail the `is_forge_owned` suffix check and
+    every forge collection is mis-classified as foreign.
+    """
+    names: list[str] = []
+    for line in raw.splitlines():
+        if not line.strip():
+            continue
+        if line[0].isspace():  # indented per-collection metadata
+            continue
+        if _QMD_HEADER_RE.match(line):
+            continue
+        names.append(line.split()[0])
+    return names
+
+
 def fetch_live_names_from_qmd() -> tuple[list[str], str | None]:
     """Invoke `qmd collection list` and return (names, error).
 
@@ -205,9 +233,7 @@ def fetch_live_names_from_qmd() -> tuple[list[str], str | None]:
         return [], f"qmd collection list failed: {e}"
     if result.returncode != 0:
         return [], f"qmd collection list exited {result.returncode}: {result.stderr.strip() or '<no stderr>'}"
-    # Each non-empty line is a collection name (qmd's stable contract).
-    names = [line.strip() for line in result.stdout.splitlines() if line.strip()]
-    return names, None
+    return parse_collection_list_output(result.stdout), None
 
 
 def main() -> None: