bmad-module-skill-forge 2.0.1 → 2.1.0

package/docs/why-skf.md

@@ -44,7 +44,7 @@ For docs-only skills, the audit shape is the same — `provenance-map.json` stil
 
 If it doesn't, **that's a bug.** [Open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) and SKF republishes the skill with a new commit SHA and a new provenance map. No other AI-skills tool treats disagreement between claim and source as a defect. SKF does.
 
-See the [Verifying a Skill](../verifying-a-skill/) page for the full three-step audit on real skills, the test reports that log *exactly* where coverage falls short, and the scoring formula behind the 80% pass threshold.
+See the [Verifying a Skill](/docs/verifying-a-skill.md) page for the full three-step audit on real skills, the test reports that log *exactly* where coverage falls short, and the scoring formula behind the 80% pass threshold.
 
 ---
 
@@ -53,27 +53,27 @@ See the [Verifying a Skill](../verifying-a-skill/) page for the full three-step
 ### The curious developer
 
 Your agent just hallucinated a method that doesn't exist, again. You want this to stop, and you don't want to read a long architecture reference before running your first command.
-→ Start with [Getting Started](../getting-started/).
+→ Start with [Getting Started](/docs/getting-started.md).
 
 ### The BMAD user
 
 You already use BMAD Method, BMM phases, TEA, or BMB, and you want to know where SKF fits.
-→ Read [BMAD Synergy](../bmad-synergy/) for the phase-by-phase integration playbook.
+→ Read [BMAD Synergy](/docs/bmad-synergy.md) for the phase-by-phase integration playbook.
 
 ### The skeptic
 
 "AI docs for AI" sounds like the problem pretending to be the solution. You want receipts before you install anything.
-→ Start with [Verifying a Skill](../verifying-a-skill/) — the three-step audit on real skills, including the 1% that fails.
+→ Start with [Verifying a Skill](/docs/verifying-a-skill.md) — the three-step audit on real skills, including the 1% that fails.
 
 ### The OSS maintainer
 
 You want to ship verified skills alongside your library releases — `npx skills publish`-ready, drift-detectable, version-pinned.
-→ See [Examples → OSS Maintainer Publishing Official Skills](../examples/#scenario-h-oss-maintainer-publishing-official-skills).
+→ See [Examples → OSS Maintainer Publishing Official Skills](/docs/examples.md#scenario-h-oss-maintainer-publishing-official-skills).
 
 ### The team lead evaluating adoption
 
 You're considering running SKF across a brownfield platform. You need to know about rollback safety, `[MANUAL]` section preservation, and the health-check feedback loop before committing.
-→ Start with [Architecture](../architecture/), then [Workflows → Workflow Health Check](../workflows/#terminal-step-health-check).
+→ Start with [Architecture](/docs/architecture.md), then [Workflows → Workflow Health Check](/docs/workflows.md#terminal-step-health-check).
 
 ---
 
@@ -89,6 +89,6 @@ Everything else is downstream of one question: *are the instructions your AI rea
 
 ## Next
 
-- **[Install SKF](../getting-started/#install)** — Node ≥ 22, Python ≥ 3.10, `uv`, one `npx` command
-- **[Audit a skill in 60 seconds](../verifying-a-skill/)** — see the receipts before you install
+- **[Install SKF](/docs/getting-started.md#install)** — Node ≥ 22, Python ≥ 3.10, `uv`, one `npx` command
+- **[Audit a skill in 60 seconds](/docs/verifying-a-skill.md)** — see the receipts before you install
 - **[Browse real skills](https://github.com/armelhbobdad/oh-my-skills)** — four Deep-tier skills, all shipping their audit trails

package/docs/workflows.md

@@ -3,9 +3,9 @@ title: Workflows
 description: All 15 SKF workflows with commands, steps, and connection diagram
 ---
 
-Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../concepts/) for definitions.
+Trigger workflows by typing commands to [Ferris](/docs/agents.md). See [Concepts](/docs/concepts.md) for definitions.
 
-> Already using BMAD? See [BMAD Synergy](../bmad-synergy/) for when to invoke each SKF workflow during BMM phases and alongside TEA, BMB, and GDS.
+> Already using BMAD? See [BMAD Synergy](/docs/bmad-synergy.md) for when to invoke each SKF workflow during BMM phases and alongside TEA, BMB, and GDS.
 
 ---
 
@@ -83,7 +83,7 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 **Purpose:** Brief-less fast skill with package-to-repo resolution.
 
-**Note:** QS is **tier-unaware** — it always runs at community tier and does not use ast-grep, CCC, or QMD even when your forge is configured at Forge+/Deep. For tier-aware compilation, use `BS → CS`, `forge`, or `forge-auto`. See [Skill Model](../skill-model/).
+**Note:** QS is **tier-unaware** — it always runs at community tier and does not use ast-grep, CCC, or QMD even when your forge is configured at Forge+/Deep. For tier-aware compilation, use `BS → CS`, `forge`, or `forge-auto`. See [Skill Model](/docs/skill-model.md).
 
 **When to Use:** When you need a skill quickly — no brief needed. Accepts package names or GitHub URLs. Append `@version` to target a specific version (e.g., `@Ferris QS cognee@1.0.0`).
 
@@ -164,7 +164,7 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 **Key Steps:** Load skill → Detect mode → Coverage check → Coherence check → External validation (skill-check, tessl) → Hard gate → Score → Gap report
 
-**Scored Categories:** Export Coverage (36%), Signature Accuracy (22%), Type Coverage (14%), Coherence (18%), External Validation (10%). Default pass threshold: **80%** (per-pipeline defaults: forge-auto 90%, forge 80%). Pass routes to Export Skill; fail routes to Update Skill with a gap report. See [Completeness Scoring](../verifying-a-skill/#how-the-score-is-computed) for the full formula and tier adjustments.
+**Scored Categories:** Export Coverage (36%), Signature Accuracy (22%), Type Coverage (14%), Coherence (18%), External Validation (10%). Default pass threshold: **80%** (per-pipeline defaults: forge-auto 90%, forge 80%). Pass routes to Export Skill; fail routes to Update Skill with a gap report. See [Completeness Scoring](/docs/verifying-a-skill.md#how-the-score-is-computed) for the full formula and tier adjustments.
 
 **Agent:** Ferris (Audit mode)
 
@@ -315,7 +315,7 @@ flowchart TD
     EXPORT --> MAINT[Maintenance + Campaign Report]
 ```
 
-> **One workflow per session** (unless using pipeline mode or campaign). Each arrow in the standard and compose-mode diagrams represents a new conversation session. Campaign manages its own multi-session orchestration internally — see [Campaign Orchestration](../campaign/). Clear your context between workflows for best results — or use pipeline mode to chain them automatically. See [Pipeline Mode](#pipeline-mode) below.
+> **One workflow per session** (unless using pipeline mode or campaign). Each arrow in the standard and compose-mode diagrams represents a new conversation session. Campaign manages its own multi-session orchestration internally — see [Campaign Orchestration](/docs/campaign.md). Clear your context between workflows for best results — or use pipeline mode to chain them automatically. See [Pipeline Mode](#pipeline-mode) below.
 
 ---
 
@@ -474,7 +474,7 @@ If the answer to all of these is "no", the health check exits in one line (`Clea
 
 - **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.
+- **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 doesn't re-report the same defect across sessions or across different projects on the same machine, for as long as the issue it points at stays open. Once that issue is closed as completed, the suppression lifts on purpose: a fresh sighting of a fixed defect is a regression, and it gets reported and linked back to the original.
 - **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.
 
 **Net effect:** 1,000 users hitting the same bug produce **one canonical issue** with a reaction-count of roughly 1,000 — not 1,000 duplicate issues or a 1,000-comment thread. The maintainer sees population impact at a glance, and your report is never lost.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -44,18 +44,21 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run docs:validate-drift",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:rehype && npm run test:docs-links-tool && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run validate:docs-links && npm run docs:validate-drift",
     "skf:install": "node tools/cli/skf-cli.js install",
     "skf:status": "node tools/cli/skf-cli.js status",
     "skf:uninstall": "node tools/cli/skf-cli.js uninstall",
     "skf:update": "node tools/cli/skf-cli.js update",
-    "test": "npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:rehype && npm run test:docs-links-tool && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run validate:docs-links && npm run lint && npm run lint:md && npm run format:check",
     "test:cli": "node test/test-cli-integration.js",
+    "test:docs-links-tool": "node test/test-validate-docs-links.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-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-language-corpora.py test/test-skf-merge-doc-urls.py test/test-skf-derive-assembly-shape.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 test/test-skf-shape-detect.py test/test-skf-detect-docs.py test/test-skf-step-doc-sources.py test/test-skf-step-doc-drift.py test/test-skf-step-hard-gate.py test/test-skf-per-pipeline-thresholds.py test/test-skf-evidence-report-fallback.py test/test-skf-validate-pins.py test/test-skf-auto-shard.py test/test-skf-preapply.py test/test-skf-step-doc-rot.py test/test-skf-campaign-state.py test/test-skf-campaign-pins.py test/test-skf-campaign-deps.py test/test-skf-campaign-report.py test/test-skf-campaign-stepfiles.py test/test-skf-campaign-validate-state.py test/test-skf-campaign-provenance.py test/test-skf-campaign-parse-manifest.py test/test-skf-campaign-render-kickoff.py test/test-skf-campaign-render-batch.py test/test-skf-shard-body.py test/test-skf-render-metadata-stats.py test/test-skf-comention-pairs.py test/test-skf-count-tokens.py test/test-skf-reconcile-coverage.py test/test-skf-verify-provenance-completeness.py test/test-skf-find-cycles.py test/test-skf-validate-feasibility-report.py test/test-skf-rewrite-skill-name.py test/test-skf-verify-no-trace.py test/test-skf-validate-inventory.py test/test-skf-check-metadata-coherence.py test/test-skf-scan-doc-rot.py test/test-skf-aggregate-coherence.py test/test-skf-dir-sizes.py test/test-skf-parse-pipeline.py test/test-skf-validate-rename-name.py test/test-skf-verify-declared-numerator.py test/test-skf-combine-external-scores.py test/test-skf-new-file-diff.py test/test-skf-coverage-tally.py test/test-skf-report-delta.py test/test-skf-verdict-rollup.py -v",
+    "test:rehype": "node test/test-rehype-markdown-links.js",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
+    "validate:docs-links": "node tools/validate-docs-links.js --strict",
     "validate:refs": "node tools/validate-file-refs.js --strict",
     "validate:schemas": "node test/validate-agent-schema.js",
     "validate:skills": "node tools/validate-skills.js --strict"
@@ -111,6 +114,7 @@
     "prettier-plugin-packagejson": "^2.5.19",
     "semver": "^7.6.3",
     "sharp": "^0.33.5",
+    "unist-util-visit": "^5.1.0",
     "wrap-ansi": "^7.0.0",
     "xml2js": "^0.6.2",
     "yaml": "^2.7.0",

package/src/shared/health-check.md

@@ -151,7 +151,36 @@ The `section-slug` is a kebab-case normalized section heading (e.g. `missing-sta
 
 **2. Check the local seen-cache** at `{seenCachePath}`:
 
-If the cache exists and already contains this fingerprint for this user, skip submission silently and log: `"fp-{hash}: already submitted from this machine on {date}, issue {url} — skipping"`. This prevents the same user from re-reporting the same defect across sessions.
+Read `{seenCachePath}`. A missing file, an empty file, or one that does not parse as JSON is an empty cache — never an error, never a reason to halt.
+
+**Presence in the cache is not the verdict.** A fingerprint whose defect was already fixed must NOT suppress: a fresh sighting of a fixed defect is a *regression*, and it is the single most valuable report this loop can produce. Look up the fingerprint and work these branches in order, stopping at the first that matches:
+
+1. **No record for this fingerprint** → `unseen`. Go to sub-step 3.
+2. **Record with `"action": "resolved"`** → `regression`. Recorded by hand when the defect was fixed. Go to sub-step 3 and apply the regression treatment below.
+3. **Record with `"action"` of `created`, `reacted`, or `commented`, and a non-empty `issue_url`** → you must decide whether that issue is still live before you may suppress. The cache is machine-local and records only what *this* user did; the issue's own state is shared, so it is the better authority. Run exactly this, and give it a hard time bound so a hung network can never strand the run:
+
+   ```
+   timeout 10 gh issue view {issue_url} --json state,stateReason --jq '.state + "/" + (.stateReason // "")'
+   ```
+
+   - `CLOSED/COMPLETED`, or `MERGED` (the record points at a resolving PR) → `regression`. It was fixed and closed out.
+   - `CLOSED/NOT_PLANNED` → `handled`. **Not** a fix: this is how the dedup Action closes a duplicate, and how a maintainer closes a wontfix. Treating it as a regression would file a REGRESSION issue against a defect nobody ever fixed, every session, forever.
+   - `OPEN` → `handled`. Already filed and still being tracked.
+   - Any failure at all (offline, timeout, no auth, deleted issue, unparseable output) → `handled`. This refinement never blocks a run and never halts on error.
+4. **Record with one of those actions but an empty `issue_url`** → `handled`. There is no issue to consult, so the local record stands.
+5. **Record with no `action`, or any other value** → `unrecognized`. Hand-edited, or written by a newer version of this file, so it cannot be confirmed handled. Go to sub-step 3 as an ordinary submission.
+
+**`handled` is the only verdict that suppresses.** Skip submission silently and log: `"fp-{hash}: already handled on {date}, issue {url} — skipping"`. Every other verdict proceeds to sub-step 3.
+
+**Why anything uncertain reports instead of suppressing.** A duplicate report is self-healing: the dedup Action closes it and moves the upvote to the canonical issue. A silenced regression is caught by nothing at all. When the verdict is in doubt, report.
+
+**Regression treatment** (verdicts `regression` only). Carry the prior record forward so the recurrence can never be filed as a first sighting:
+
+- Append ` — REGRESSION` to the issue title, after `{short description}`.
+- Add a `## Regression` section immediately above `## Finding`, containing one line: `Regression of {issue_url}, resolved {date}.` If the prior record has no `issue_url`, write `Regression of a previously resolved local finding, resolved {date}.` The `{fp}` label still ties the two together server-side.
+- Leave `## Finding` and the other one-sentence sections exactly as specified below. The backlink lives in its own section precisely so those budgets are untouched.
+
+**What this does and does not catch.** The fingerprint is `sha1` over the section slug, so a fix that renames or relocates the section it touches changes the fingerprint. Such a regression arrives as `unseen` and is reported as a first sighting, which is safe but unlinked. These branches catch the regressions that recur under the same heading in the same step file, which is the case where the old behaviour was silent.
 
 **3. Check GitHub CLI availability** with `gh auth status`. If `gh` is unavailable, fall through to step 5c (local fallback).
 
@@ -205,9 +234,11 @@ gh issue create \
   --body "{formatted body using issue template structure}"
 ```
 
+When sub-step 2 returned `regression`, append ` — REGRESSION` to that `--title` value, after `{short description}`, and include the `## Regression` backlink section in the body. The command above is the literal one you run, so the marker has to be in it: an instruction that the title should say REGRESSION loses to a copied command that does not.
+
 The fingerprint `{fp}` appears in both title (human-readable) and label (server-side filterable). Maintainers can query all reports for a defect via the `fp-*` label without relying on title text.
 
-After the issue is created, write the fingerprint → issue-url mapping to the seen-cache at `{seenCachePath}` so this user never re-reports the same fingerprint.
+After the issue is created, write the fingerprint → issue-url mapping to the seen-cache at `{seenCachePath}` so this user does not re-report it while that issue stays open.
 
 **Writing rules — non-negotiable:**
 
@@ -300,7 +331,13 @@ After each successful `gh issue create`, append to `{seenCachePath}`:
 }
 ```
 
-Ensure the parent directory exists. This file is global across the user's machine — not per-project — so the same defect is never re-reported across different repos the user works in.
+Ensure the parent directory exists. This file is global across the user's machine — not per-project — so the same defect is not re-reported across different repos the user works in while its issue stays open.
+
+**Merge, never replace.** Read the existing file, set this one key, write the whole object back. A write that emits only the new key silently discards every other fingerprint the user has ever recorded.
+
+**Read before you write, and never downgrade a `resolved` record.** Before setting the key, check whether one already exists with `"action": "resolved"`. If it does, and you are here because that resolved defect just recurred, you are recording the regression's new issue: overwrite it with `created` and the new URL, which is correct because a live issue now tracks the recurrence. In every other case leave a `resolved` record alone. The record must never move from `resolved` back to a suppressing action without a new open issue to justify it, or the next run silently re-arms the suppression the fix removed.
+
+**The `action` vocabulary is `created`, `reacted`, `commented`, `resolved`.** The first three are written by this workflow. `resolved` is written by hand when the defect is fixed, and it is the only one that does not suppress. See the health-check section of `CONTRIBUTING.md` for when to record it.
 
 ### 5c. Local-Queue Path (gh unavailable OR friction/gap default)
 

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

@@ -84,6 +84,12 @@
           "enum": ["full-library", "specific-modules", "public-api", "component-library", "reference-app", "docs-only"]
         },
         "include": { "type": "array", "items": { "type": "string" } },
+        "tier_a_include": {
+          "type": "array",
+          "description": "Optional narrower tier-A include list. When present it becomes the coverage-denominator basis instead of the coarse scope.include, and it exempts the brief from the denominator deflation guard in skf-test-skill references/source-access-protocol.md — so an empty or blank-item list must not be accepted: it would silence that guard while narrowing nothing.",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
         "exclude": { "type": "array", "items": { "type": "string" } },
         "notes": { "type": "string" },
         "rationale": {

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

@@ -378,7 +378,27 @@ def _parse_argv(argv: list[str]) -> dict:
     return payload
 
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure JSON-carrying streams to UTF-8 (issue #465).
+
+    A default Windows console decodes stdio as cp1252, which cannot carry
+    non-ASCII JSON (ensure_ascii=False output, raw UTF-8 input). Preserves
+    each stream's existing error handler — reconfigure(encoding=...) alone
+    would reset it to 'strict', downgrading e.g. an already-UTF-8 stderr on
+    Linux. For stdin this must run before the first read. Skips in-process
+    test doubles without reconfigure().
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 def main(argv: list[str]) -> int:
+    _force_utf8(sys.stdin, sys.stdout)
     payload = _parse_argv(argv)
     result = detect(payload)
     json.dump(result, sys.stdout, ensure_ascii=False)

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

@@ -142,6 +142,29 @@ def _ok(payload: dict) -> None:
     print(json.dumps(payload))
 
 
+def _resolve_outside_cwd(command: str) -> str | None:
+    """shutil.which with a CWD-shim guard. Returns the resolved path or None.
+
+    shutil.which on Windows searches the current directory ahead of PATH,
+    and CWD here is the repo under analysis — a bare-name lookup resolving
+    into CWD would execute a repo-planted shim (e.g. ast-grep.cmd). Such a
+    resolution is treated as not-found. Explicit paths supplied by callers
+    (containing a separator) are honored as-is. Keep identical to the
+    sibling guard in skf-qmd-classify-collections.py.
+    """
+    resolved = shutil.which(command)
+    if resolved is None:
+        return None
+    if os.sep in command or (os.altsep and os.altsep in command):
+        return resolved
+    resolved_dir = os.path.dirname(resolved)
+    if resolved_dir:
+        cwd = os.path.normcase(os.path.abspath(os.getcwd()))
+        if os.path.normcase(os.path.abspath(resolved_dir)) == cwd:
+            return None
+    return resolved
+
+
 def _run(cmd: list[str], timeout: int = PROBE_TIMEOUT_SEC) -> tuple[int, str, str]:
     """Run a subprocess. Return (returncode, stdout, stderr). Never raises.
 
@@ -149,6 +172,13 @@ def _run(cmd: list[str], timeout: int = PROBE_TIMEOUT_SEC) -> tuple[int, str, st
     CalledProcessError) as a failed probe — returns rc=127 and an empty
     stdout/stderr. Tool detection should never crash the workflow.
 
+    cmd[0] is resolved through shutil.which() before spawning (with the
+    CWD-shim guard in _resolve_outside_cwd): Windows CreateProcess only
+    ever appends .exe to a bare name, so npm-installed shims
+    (ast-grep.CMD, qmd.CMD) would raise FileNotFoundError and read as
+    "tool absent". An unresolvable command returns rc=127 without
+    spawning anything.
+
     The child is wrapped in the OS `timeout(1)` utility (when available) so a
     daemon-backed probe blocked in an uninterruptible syscall (e.g.
     `qmd status` waiting on its daemon socket) is reaped at the OS level —
@@ -158,6 +188,10 @@ def _run(cmd: list[str], timeout: int = PROBE_TIMEOUT_SEC) -> tuple[int, str, st
     `start_new_session=True` isolates the child's process group; the
     Python-level timeout is a secondary net set slightly above the OS one.
     """
+    resolved = _resolve_outside_cwd(cmd[0])
+    if resolved is None:
+        return 127, "", ""
+    cmd = [resolved, *cmd[1:]]
     if _TIMEOUT_BIN:
         run_cmd = [_TIMEOUT_BIN, "--kill-after=2", str(timeout), *cmd]
         py_timeout = timeout + 5

package/src/shared/scripts/skf-emit-result-envelope.py

@@ -496,7 +496,27 @@ def cmd_emit_blocked() -> None:
     print(emit_envelope_line(envelope))
 
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure JSON-carrying streams to UTF-8 (issue #465).
+
+    A default Windows console decodes stdio as cp1252, which cannot carry
+    non-ASCII JSON (ensure_ascii=False output, raw UTF-8 input). Preserves
+    each stream's existing error handler — reconfigure(encoding=...) alone
+    would reset it to 'strict', downgrading e.g. an already-UTF-8 stderr on
+    Linux. For stdin this must run before the first read. Skips in-process
+    test doubles without reconfigure().
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 def main() -> None:
+    _force_utf8(sys.stdin, sys.stdout)
     parser = argparse.ArgumentParser(
         description=__doc__,
         formatter_class=argparse.RawDescriptionHelpFormatter,

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

@@ -80,7 +80,27 @@ def corpora_for(language: str) -> list[dict]:
     return out
 
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure JSON-carrying streams to UTF-8 (issue #465).
+
+    A default Windows console decodes stdio as cp1252, which cannot carry
+    non-ASCII JSON (ensure_ascii=False output, raw UTF-8 input). Preserves
+    each stream's existing error handler — reconfigure(encoding=...) alone
+    would reset it to 'strict', downgrading e.g. an already-UTF-8 stderr on
+    Linux. For stdin this must run before the first read. Skips in-process
+    test doubles without reconfigure().
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 def main(argv: list[str]) -> int:
+    _force_utf8(sys.stdout, sys.stderr)
     parser = argparse.ArgumentParser(
         description="Look up canonical companion prose corpora for a language.",
     )

package/src/shared/scripts/skf-merge-doc-urls.py

@@ -213,7 +213,27 @@ def merge_doc_urls(
     return kept, suppressed
 
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure JSON-carrying streams to UTF-8 (issue #465).
+
+    A default Windows console decodes stdio as cp1252, which cannot carry
+    non-ASCII JSON (ensure_ascii=False output, raw UTF-8 input). Preserves
+    each stream's existing error handler — reconfigure(encoding=...) alone
+    would reset it to 'strict', downgrading e.g. an already-UTF-8 stderr on
+    Linux. For stdin this must run before the first read. Skips in-process
+    test doubles without reconfigure().
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 def main() -> int:
+    _force_utf8(sys.stdin, sys.stdout)
     raw = sys.stdin.read()
     if not raw or not raw.strip():
         sys.stderr.write("skf-merge-doc-urls: empty stdin (expected JSON object)\n")

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

@@ -79,7 +79,9 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import re
+import shutil
 import sys
 from pathlib import Path
 
@@ -92,6 +94,10 @@ FOREIGN_SAMPLE_CAP = 5
 # Header line emitted by newer qmd builds, e.g. "Collections (56):".
 _QMD_HEADER_RE = re.compile(r"^Collections \(\d+\):\s*$")
 
+# Empty-state message from `qmd collection list`, e.g.
+# "No collections found. Run 'qmd collection add .' to create one."
+_QMD_EMPTY_STATE_PREFIX = "No collections found"
+
 
 def _die(code: int, message: str) -> None:
     print(json.dumps({"status": "error", "message": message}), file=sys.stderr)
@@ -199,7 +205,12 @@ def parse_collection_list_output(raw: str) -> list[str]:
     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.
+
+    The empty-state message ("No collections found. …") is recognized before
+    per-line tokenizing — it would otherwise parse as a collection named "No".
     """
+    if raw.lstrip().startswith(_QMD_EMPTY_STATE_PREFIX):
+        return []
     names: list[str] = []
     for line in raw.splitlines():
         if not line.strip():
@@ -212,6 +223,29 @@ def parse_collection_list_output(raw: str) -> list[str]:
     return names
 
 
+def _resolve_outside_cwd(command: str) -> str | None:
+    """shutil.which with a CWD-shim guard. Returns the resolved path or None.
+
+    shutil.which on Windows searches the current directory ahead of PATH,
+    and CWD here is the repo under analysis — a bare-name lookup resolving
+    into CWD would execute a repo-planted shim (e.g. qmd.cmd). Such a
+    resolution is treated as not-found. Explicit paths supplied by callers
+    (containing a separator) are honored as-is. Keep identical to the
+    sibling guard in skf-detect-tools.py.
+    """
+    resolved = shutil.which(command)
+    if resolved is None:
+        return None
+    if os.sep in command or (os.altsep and os.altsep in command):
+        return resolved
+    resolved_dir = os.path.dirname(resolved)
+    if resolved_dir:
+        cwd = os.path.normcase(os.path.abspath(os.getcwd()))
+        if os.path.normcase(os.path.abspath(resolved_dir)) == cwd:
+            return None
+    return resolved
+
+
 def fetch_live_names_from_qmd() -> tuple[list[str], str | None]:
     """Invoke `qmd collection list` and return (names, error).
 
@@ -221,11 +255,19 @@ def fetch_live_names_from_qmd() -> tuple[list[str], str | None]:
     counts as a "live collection name".
     """
     import subprocess
+    # Resolve before spawning: on Windows qmd ships from npm as a .CMD
+    # shim, which a bare-name subprocess.run cannot launch (WinError 2).
+    qmd = _resolve_outside_cwd("qmd")
+    if qmd is None:
+        return [], "qmd not found on PATH"
     try:
+        # qmd emits UTF-8; a locale-default decode (cp1252 on Windows)
+        # mojibakes names or raises UnicodeDecodeError on unmapped bytes.
         result = subprocess.run(
-            ["qmd", "collection", "list"],
+            [qmd, "collection", "list"],
             capture_output=True,
-            text=True,
+            encoding="utf-8",
+            errors="replace",
             timeout=30,
             check=False,
         )

package/src/shared/scripts/skf-recommend-scope-type.py

@@ -356,7 +356,27 @@ def _parse_argv(argv: list[str]) -> dict:
     return payload
 
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure JSON-carrying streams to UTF-8 (issue #465).
+
+    A default Windows console decodes stdio as cp1252, which cannot carry
+    non-ASCII JSON (ensure_ascii=False output, raw UTF-8 input). Preserves
+    each stream's existing error handler — reconfigure(encoding=...) alone
+    would reset it to 'strict', downgrading e.g. an already-UTF-8 stderr on
+    Linux. For stdin this must run before the first read. Skips in-process
+    test doubles without reconfigure().
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 def main(argv: list[str]) -> int:
+    _force_utf8(sys.stdin, sys.stdout)
     payload = _parse_argv(argv)
     result = recommend(payload)
     json.dump(result, sys.stdout, ensure_ascii=False)

package/src/shared/scripts/skf-render-metadata-stats.py

@@ -64,7 +64,7 @@ Judgment payload (stdin JSON, compute mode)::
     {
       "exports_public_api":  40,          # int  — public-entry-point export count (judgment)
       "exports_internal":    19,          # int  — non-underscore internal export count (judgment)
-      "effective_denominator": 12,        # int|null — optional, stratified-scope monorepo only
+      "effective_denominator": 12,        # int|null — optional, curated-subset scopes only
       "pattern_surfaces_documented": 8,   # int  — reference-app only (exports_documented proxy)
       "exports_documented":  0,           # int  — stack only (own-barrel count, usually 0)
       "scripts": [ ... ],                 # list — scripts[] array (or "scripts_count": int)

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

@@ -1075,7 +1075,27 @@ def path_to_manifest_name(ecosystem: str) -> str:
 # CLI wiring
 # ---------------------------------------------------------------------------
 
+def _force_utf8(*streams) -> None:
+    """Reconfigure JSON-carrying streams to UTF-8 (issue #465).
+
+    A default Windows console decodes stdio as cp1252, which cannot carry
+    non-ASCII JSON (ensure_ascii=False output, raw UTF-8 input). Preserves
+    each stream's existing error handler — reconfigure(encoding=...) alone
+    would reset it to 'strict', downgrading e.g. an already-UTF-8 stderr on
+    Linux. For stdin this must run before the first read. Skips in-process
+    test doubles without reconfigure().
+    """
+    for stream in streams:
+        if hasattr(stream, "reconfigure"):
+            errors = getattr(stream, "errors", None)
+            if errors is None:
+                stream.reconfigure(encoding="utf-8")
+            else:
+                stream.reconfigure(encoding="utf-8", errors=errors)
+
+
 def main(argv: list[str]) -> int:
+    _force_utf8(sys.stdout, sys.stderr)
     parser = argparse.ArgumentParser(
         description="Classify a repo into a known skill shape from its manifest files.",
     )

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

@@ -13,7 +13,7 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | source_repo | string | GitHub URL or local path                         | Repository or project root (optional when `source_type: "docs-only"`)       |
 | language    | string | Recognized language                              | Primary programming language                                                |
 | scope       | object | See Scope Object below                           | Boundary definition                                                         |
-| description | string | 1-3 sentences                                    | What the skill covers                                                       |
+| description | string | 1-3 sentences                                    | What the skill covers. Must contain a literal `Use when` clause — validators test for that exact phrase. |
 | forge_tier  | string | `Quick` / `Forge` / `Forge+` / `Deep`            | Inherited from forge-tier.yaml (Title Case)                                 |
 | created     | string | ISO date `YYYY-MM-DD`                            | Generation date                                                             |
 | created_by  | string | user_name from config                            | Who generated the brief                                                     |
@@ -31,6 +31,7 @@ Defines the output contract for skill-brief.yaml files generated by analyze-sour
 | `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.                                                                                                                        |
+| `scope.tier_a_include` | array | Glob patterns (min 1, non-empty)            | Optional narrower tier-A include list for a curated-subset skill — stratified monorepo packages, single-crate `specific-modules` scopes, and multi-entry exports-map packages. When present, `skf-test-skill` re-derives the coverage denominator from this list instead of the coarse `scope.include`. **It also exempts the brief from the denominator deflation guard**, so supply it only when it genuinely narrows the surface — never as an empty list, and never as a way to widen. See `skf-test-skill/references/source-access-protocol.md`. |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)

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

@@ -59,7 +59,7 @@ For each qualifying unit, prepare a recommendation card:
 - name: {suggested kebab-case name}
 - 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}
+- description: {suggested 1-3 sentence description, containing a literal `Use when` clause}
 ```
 
 ### 3. Present Recommendations

package/src/skf-audit-skill/references/re-index.md

@@ -143,7 +143,7 @@ Skip this section. Temporal context requires Deep tier.
 
 For each export in the skill baseline that was NOT found at its recorded file path during re-extraction (potential "deleted" export):
 
-1. Run `ccc_bridge.search("{export_name}", source_root, top_k=5)` — **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{export_name}" --path {source_root} --top 5` (CLI) — to find candidate current locations
+1. Run `ccc_bridge.search("{export_name}", source_root, top_k=5)` — **Tool resolution:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `cd {source_root} && ccc search --limit 5 "{export_name}"` (CLI) — to find candidate current locations. `ccc search` reads the index in the current working directory and has no project-selector flag (`--path` is a file-path glob filter *within* the index, and the result cap is `--limit`, not `--top`) — see `knowledge/ccc-bridge.md`.
 2. If CCC returns files containing the export name:
    - Run ast-grep verification on each candidate file
    - If verified at a new location: reclassify from "deleted" to "moved" with the new file:line reference

package/src/skf-brief-skill/assets/description-voice-examples.md

@@ -6,9 +6,9 @@ Loaded by step 1 §7b only. The five examples below show the *range* of acceptab
 
 > Render Markdown to HTML using the marked library. Use when the user pastes raw Markdown and wants formatted output, or asks how to convert MD files in a build pipeline.
 
-> Stripe API client for Node.js — payment intents, subscriptions, customer portal, webhooks. Triggers on tasks involving Stripe-managed payments, subscription billing, or webhook event handling.
+> Stripe API client for Node.js — payment intents, subscriptions, customer portal, webhooks. Use when the task involves Stripe-managed payments, subscription billing, or webhook event handling.
 
-> Charts and visualizations powered by D3.js. Reach for this when the user asks to plot data, build interactive graphs, or wants bare D3 control instead of a React-charts abstraction.
+> Charts and visualizations powered by D3.js. Use when the user asks to plot data, build interactive graphs, or wants bare D3 control instead of a React-charts abstraction.
 
 > Lint Python code with Ruff. Use when the user wants to add or configure Ruff in a Python project, debug rule selectors, or understand why a specific check fired.
 
@@ -16,4 +16,6 @@ Loaded by step 1 §7b only. The five examples below show the *range* of acceptab
 
 ## Notes on Voice
 
-Each example leads differently (verb / noun / "Charts and..." / verb / noun-phrase) and matches the trigger phrasing ("Use when...", "Triggers on...", "Reach for this when...") to the voice rather than copy-pasting a single template. Compose in that spirit using the gathered material — the target repo, the user's intent, the version if set, and any scope hints — but **do not template-stamp**.
+Each example leads differently (verb / noun / "Charts and..." / verb / noun-phrase) rather than copy-pasting a single template. Compose in that spirit using the gathered material — the target repo, the user's intent, the version if set, and any scope hints — but **do not template-stamp**.
+
+The **lead** is where the voice varies; the **trigger clause** is fixed. Every description must contain a literal `Use when` clause somewhere, because validators test for that exact phrase — `skill-check`'s `description.use_when_phrase` rule scores a description below 100 without it. Phrasings like "Triggers on…" or "Reach for this when…" read well but do not satisfy it on their own, so keep them for additional text rather than as the only trigger.