bmad-module-skill-forge 2.0.2 → 2.2.0

package/docs/troubleshooting.md

@@ -3,7 +3,7 @@ title: Troubleshooting
 description: Common errors in Skill Forge — forge setup, ecosystem checks, tier confidence — and how to resolve them.
 ---
 
-If something isn't working, start here. For general setup help see [Getting Started → Need help?](../getting-started/#need-help).
+If something isn't working, start here. For general setup help see [Getting Started → Need help?](/docs/getting-started.md#need-help).
 
 ---
 
@@ -13,13 +13,13 @@ If something isn't working, start here. For general setup help see [Getting Star
 
 Surfaced by `/skf-setup` On Activation when `uv --version` is missing on `$PATH`. SKF helpers depend on `uv` to auto-resolve their Python dependencies via PEP 723 inline metadata; bare `python3` ignores that metadata and would fail later with `ModuleNotFoundError: No module named 'yaml'`. The probe halts the workflow up-front with one cohesive diagnostic instead of letting five steps each fail individually.
 
-**Fix:** install `uv` from <https://docs.astral.sh/uv/getting-started/installation/> and re-run `/skf-setup`. `uv` is documented as a runtime prerequisite in [Getting Started → Prerequisites](../getting-started/#prerequisites-full-reference).
+**Fix:** install `uv` from <https://docs.astral.sh/uv/getting-started/installation/> and re-run `/skf-setup`. `uv` is documented as a runtime prerequisite in [Getting Started → Prerequisites](/docs/getting-started.md#prerequisites-full-reference).
 
 ### "Setup cannot proceed: `_bmad/skf/config.yaml` was not found"
 
 Surfaced by `/skf-setup` On Activation when the SKF install config is missing — typically because you invoked `/skf-setup` from a directory that is not an SKF-initialised project. The check runs before any file mutation so nothing is written.
 
-**Fix:** from the project root, run `npx bmad-module-skill-forge install` (or `npx bmad-method install` and add SKF as a custom module — see [Getting Started → Install](../getting-started/#install)), then re-run `/skf-setup`. If you ARE in the right project but the file was deleted, restore it from version control or re-run the SKF installer. A separate "config.yaml is not valid YAML" diagnostic surfaces the parser error inline if the file exists but is malformed — open the file at the named path and repair the YAML.
+**Fix:** from the project root, run `npx bmad-module-skill-forge install` (or `npx bmad-method install` and add SKF as a custom module — see [Getting Started → Install](/docs/getting-started.md#install)), then re-run `/skf-setup`. If you ARE in the right project but the file was deleted, restore it from version control or re-run the SKF installer. A separate "config.yaml is not valid YAML" diagnostic surfaces the parser error inline if the file exists but is malformed — open the file at the named path and repair the YAML.
 
 ### Forge reports ast-grep is unavailable
 
@@ -35,7 +35,7 @@ An official skill already exists for this package. Consider installing it with `
 
 ### Quick-tier skills have lower confidence scores
 
-Quick tier reads source without AST analysis, so signatures are read directly from files rather than structurally verified. Install ast-grep to upgrade to the Forge tier for AST-verified signatures (T1 confidence) — see [Capability Tiers](../concepts/#capability-tiers-quickforgeforgedeep).
+Quick tier reads source without AST analysis, so signatures are read directly from files rather than structurally verified. Install ast-grep to upgrade to the Forge tier for AST-verified signatures (T1 confidence) — see [Capability Tiers](/docs/concepts.md#capability-tiers-quickforgeforgedeep).
 
 ### Want semantic discovery for large codebases?
 
@@ -43,11 +43,11 @@ Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) to unlo
 
 ### `@Ferris deepwiki` shows a deprecation notice
 
-The auto pipeline was briefly named `deepwiki`; it's now [`forge-auto`](../forge-auto/) — renamed to avoid confusion with the DeepWiki MCP, since the pipeline compiles a verified skill from source and does **not** call that MCP. `deepwiki` still works (it resolves to `forge-auto`) but prints a one-time notice. Switch your commands to `@Ferris forge-auto <repo-or-doc-url>`.
+The auto pipeline was briefly named `deepwiki`; it's now [`forge-auto`](/docs/forge-auto.md) — renamed to avoid confusion with the DeepWiki MCP, since the pipeline compiles a verified skill from source and does **not** call that MCP. `deepwiki` still works (it resolves to `forge-auto`) but prints a one-time notice. Switch your commands to `@Ferris forge-auto <repo-or-doc-url>`.
 
 ### `@Ferris onboard` returns an error
 
-The `onboard` alias was removed. Its replacement is [`forge-auto`](../forge-auto/), which does everything `onboard` did plus auto-scope, auto-brief, and a stricter 90% quality gate. Run `@Ferris forge-auto <repo-or-doc-url>` instead.
+The `onboard` alias was removed. Its replacement is [`forge-auto`](/docs/forge-auto.md), which does everything `onboard` did plus auto-scope, auto-brief, and a stricter 90% quality gate. Run `@Ferris forge-auto <repo-or-doc-url>` instead.
 
 ### forge-auto halted at the Test stage
 
@@ -64,4 +64,4 @@ Campaign is designed for exactly this. State lives in `_campaign-state.yaml` on
 1. Run `@Ferris SF` to check your tool availability and current tier
 2. Check `forge-tier.yaml` in your forger sidecar for your configuration
 3. If `/bmad-help` is installed (via full BMAD Method), run it and describe your state — e.g. `/bmad-help my batch creation failed halfway, how do I resume?`
-4. [File an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) — SKF's [health check system](../workflows/#terminal-step-health-check) is the primary feedback channel, and manual issues feed the same pipeline
+4. [File an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) — SKF's [health check system](/docs/workflows.md#terminal-step-health-check) is the primary feedback channel, and manual issues feed the same pipeline

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.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "2.0.2",
+  "version": "2.2.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/references/description-guard-protocol.md

@@ -63,6 +63,8 @@ Output JSON:
 
 If `restored == true`, also update the in-context copy of `description` to match `guarded_description` so subsequent stages do not work from a stale tool-mutated version. Record `description_guard_restored: true` (with the tool name) in workflow context for the evidence report.
 
+**Empty snapshot refusal.** The helper exits 1 and leaves the file untouched when `--captured-description` is empty or whitespace-only. There is nothing to restore from: either `guarded_description` was lost from context between capture and verify, or the field was already empty before the tool ran. Never retry with the empty value — writing it back would blank the field the guard exists to protect. If the compiled description is still available in context (the in-context SKILL.md copy), re-run `verify-restore` with that value. Otherwise record `description_guard_restored: false` and `description_guard_refused: empty-capture` (with the tool name) in workflow context; the calling stage's evidence-report populator renders that as a fired guard (`Restored: false`, the triggering tool, `Original description preserved: false`, `Notes: guard refused — empty captured snapshot (empty-capture)`) rather than as the all-`—` clean-run state, and the frontmatter validator surfaces the empty field through the normal artifact path.
+
 ## Why Token-Stream Comparison
 
 Token-stream comparison is the documented sweet spot between two failure modes:

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-description-guard.py

@@ -32,6 +32,9 @@ Subcommands:
          "current_description": "..."}
       If not diverged (including whitespace-only differences), emit
         {"diverged": false, "restored": false, "diff_kind": "none"|"whitespace-only"}
+      An empty or whitespace-only --captured-description is refused with
+      exit 1 before the file is read: there is nothing to restore from, and
+      writing it back would blank the very field this guard protects.
 
 Token-stream comparison is the documented sweet spot — catches replaced
 words, truncation, and reintroduced angle-brackets while ignoring cosmetic
@@ -47,7 +50,8 @@ is auto-resolved:
 
 Exit codes:
   0  — operation succeeded (including no-divergence verify)
-  1  — user error (bad args, file missing, frontmatter unparseable)
+  1  — user error (bad args, empty captured description, file missing,
+       frontmatter unparseable)
   2  — operation failure (restore write failed)
 """
 
@@ -173,6 +177,11 @@ def restore_description(skill_md: Path, captured: str) -> None:
     chooses for each scalar — downstream readers parse YAML, so any valid
     YAML emission is acceptable.
     """
+    if not captured.strip():
+        # Defence in depth for library callers: the CLI refuses this earlier,
+        # but no code path may ever write an empty description.
+        raise ValueError("cannot restore: captured description is empty or whitespace-only")
+
     text = skill_md.read_text(encoding="utf-8")
     leading, fm_yaml, body = _split_frontmatter(text)
     if not fm_yaml:
@@ -238,6 +247,18 @@ def _cmd_capture(args: argparse.Namespace) -> int:
 
 
 def _cmd_verify_restore(args: argparse.Namespace) -> int:
+    captured = args.captured_description
+    if not captured.strip():
+        # Restoring an empty snapshot would blank the field the guard exists
+        # to protect. The snapshot was lost from context, or the description
+        # was already empty before the tool ran; either way there is nothing
+        # to restore, so refuse before touching the file.
+        _fail(
+            "--captured-description is empty or whitespace-only; refusing to "
+            "overwrite the on-disk description with an empty value (the capture "
+            "was lost, or the field was already empty before the tool ran)"
+        )
+
     skill_md = Path(args.skill_md)
     if not skill_md.is_file():
         _fail(f"file not found: {skill_md}")
@@ -246,7 +267,6 @@ def _cmd_verify_restore(args: argparse.Namespace) -> int:
     except ValueError as exc:
         _fail(str(exc))
 
-    captured = args.captured_description
     diff_kind = classify_divergence(captured, current)
     diverged = is_diverged(diff_kind)
 

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

@@ -74,6 +74,42 @@ Each list is stably sorted by url.  Stored hashes are normalized (leading
 `algo:` prefix stripped) before comparison so a bare-hex writer form still
 matches.  Exit 0 on any well-formed input (never blocks the informational
 audit); exit 2 on malformed args or JSON.
+
+---------------------------------------------------------------------------
+Subcommand: hash-urls
+---------------------------------------------------------------------------
+
+Compile-time `doc_sources[]` for docs-only skills (create-skill step 5a).
+The detect path above needs a GitHub repository; a docs-only brief has none
+— its `source_repo` is the documentation site and its corpus is the brief's
+`doc_urls`.  This subcommand fetches each URL and hashes the raw response
+bytes with the SAME primitive `compare-hashes` uses, so a hash recorded here
+compares byte-for-byte at audit time.  (Hashing the markdown a web-fetch tool
+rendered would not: the audit re-fetches the raw bytes.)
+
+  uv run src/shared/scripts/skf-detect-docs.py hash-urls <source>
+
+Input `<source>`:
+  - a path to a JSON file that is EITHER an array whose items are URL
+    strings or `{url, ...}` objects (the brief's `doc_urls[]` entry shape)
+    OR an object with a `doc_urls` array (the brief block itself), OR
+  - `-` to read that JSON from stdin.
+
+Output (JSON object on stdout):
+  {
+    "doc_sources":  [{"url", "detected_via": "brief_doc_urls",
+                      "content_hash": "sha256:..."|null, "recorded_at"}],
+    "fetch_failed": [{"url", "reason"}],
+    "stats": {"total", "hashed", "fetch_failed", "invalid"}
+  }
+
+URLs keep their input order and are deduplicated on first occurrence; an
+entry without a usable url string is dropped and counted under
+`stats.invalid`.  A URL that cannot be fetched still gets an entry with
+`content_hash: null` — the audit side files it under `skipped_null_hash`
+instead of reporting drift.  `doc_sources` is already in the metadata.json
+schema, and the whole object is valid `compare-hashes` input.  Exit 0 on any
+well-formed input; exit 2 on malformed args or JSON.
 """
 
 from __future__ import annotations
@@ -88,6 +124,7 @@ import subprocess
 import sys
 import urllib.error
 import urllib.request
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
@@ -252,8 +289,10 @@ def _fetch_and_hash(url: str) -> Optional[str]:
             return "sha256:" + hashlib.sha256(content).hexdigest()
         except (OSError, IOError):
             return None
-    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
     try:
+        # Request() itself raises ValueError on a scheme-less or relative URL;
+        # it must sit inside the guard so a bad entry degrades to None.
+        req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
         with urllib.request.urlopen(req, timeout=_FETCH_TIMEOUT) as resp:
             content = resp.read()
         return "sha256:" + hashlib.sha256(content).hexdigest()
@@ -294,7 +333,14 @@ def _fetch_and_hash_reason(url: str) -> Tuple[Optional[str], Optional[str]]:
         except OSError as exc:
             return None, f"local read failed: {exc}"
         return "sha256:" + hashlib.sha256(content).hexdigest(), None
-    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    try:
+        # Request() raises ValueError ("unknown url type") on a scheme-less or
+        # relative URL — a legal brief entry, since the brief schema only
+        # requires a non-empty string. Keep it inside the guard so one bad
+        # entry lands in fetch_failed instead of aborting the whole run.
+        req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    except ValueError as exc:
+        return None, f"invalid URL: {exc}"
     try:
         with urllib.request.urlopen(req, timeout=_FETCH_TIMEOUT) as resp:
             content = resp.read()
@@ -601,16 +647,166 @@ def _cmd_compare_hashes(argv: List[str]) -> int:
     return 0
 
 
+# ---------------------------------------------------------------------------
+# Subcommand: hash-urls — docs-only doc_sources from the brief's doc_urls
+# ---------------------------------------------------------------------------
+
+# `doc_sources[].detected_via` value for entries that come from the brief's
+# `doc_urls` (and the subpages step 3c fetched from them) rather than from
+# repository detection. Listed in skf-create-skill/assets/skill-sections.md.
+BRIEF_DOC_URLS_DETECTED_VIA = "brief_doc_urls"
+
+
+def _load_url_list(raw_text: str, source_label: str) -> List[Any]:
+    """Parse a hash-urls input blob into a list of URL entries.
+
+    Accepts a top-level JSON array whose items are URL strings or objects
+    with a `url` key (the brief's `doc_urls[]` entry shape), or a top-level
+    object with a `doc_urls` array (the brief block itself). An object without
+    `doc_urls` yields an empty list (nothing to hash).
+
+    Raises ValueError on malformed JSON or an unexpected top-level shape.
+    """
+    try:
+        data = json.loads(raw_text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"malformed JSON in {source_label}: {exc}") from exc
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        entries = data.get("doc_urls")
+        if entries is None:
+            return []
+        if not isinstance(entries, list):
+            raise ValueError(f"`doc_urls` in {source_label} is not an array")
+        return entries
+    raise ValueError(
+        f"{source_label} must be a JSON array or an object with a "
+        f"`doc_urls` array; got {type(data).__name__}"
+    )
+
+
+def hash_urls(entries: List[Any], recorded_at: Optional[str] = None) -> Dict[str, Any]:
+    """Fetch and hash each URL into a compile-time `doc_sources[]` entry.
+
+    Byte-symmetric with `compare_doc_hashes`: both go through
+    `_fetch_and_hash_reason`, so a hash recorded here reads as `unchanged` at
+    audit time for unchanged bytes. URLs keep their input order (brief order,
+    then discovered subpages) and are deduplicated on first occurrence. A URL
+    that cannot be fetched still gets an entry with `content_hash: None`, which
+    the audit side skips rather than reporting as drift.
+    """
+    stamp = recorded_at or datetime.now(timezone.utc).isoformat()
+    doc_sources: List[Dict[str, Any]] = []
+    fetch_failed: List[Dict[str, Any]] = []
+    seen: set = set()
+    invalid = 0
+    for entry in entries:
+        url = entry.get("url") if isinstance(entry, dict) else entry
+        if not isinstance(url, str) or not url.strip():
+            invalid += 1
+            continue
+        if url in seen:
+            continue
+        seen.add(url)
+        content_hash, reason = _fetch_and_hash_reason(url)
+        doc_sources.append({
+            "url": url,
+            "detected_via": BRIEF_DOC_URLS_DETECTED_VIA,
+            "content_hash": content_hash,
+            "recorded_at": stamp,
+        })
+        if content_hash is None:
+            fetch_failed.append({"url": url, "reason": reason})
+    return {
+        "doc_sources": doc_sources,
+        "fetch_failed": fetch_failed,
+        "stats": {
+            "total": len(doc_sources),
+            "hashed": len(doc_sources) - len(fetch_failed),
+            "fetch_failed": len(fetch_failed),
+            "invalid": invalid,
+        },
+    }
+
+
+def _cmd_hash_urls(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-detect-docs.py hash-urls",
+        description=(
+            "Fetch each documentation URL, hash the response bytes, and emit "
+            "compile-time doc_sources entries (detected_via: brief_doc_urls) "
+            "for a docs-only skill."
+        ),
+    )
+    parser.add_argument(
+        "source",
+        help=(
+            "path to a JSON file (array of URL strings or {url, ...} objects, "
+            "or an object with a doc_urls array such as the brief's block), "
+            "or - to read that JSON from stdin"
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    if args.source == "-":
+        raw = sys.stdin.read()
+        label = "<stdin>"
+    else:
+        path = Path(args.source)
+        try:
+            raw = path.read_text(encoding="utf-8")
+        except OSError as exc:
+            json.dump({"error": f"cannot read {path}: {exc}", "code": "READ_ERROR"}, sys.stderr)
+            sys.stderr.write("\n")
+            return 2
+        label = str(path)
+
+    try:
+        entries = _load_url_list(raw, label)
+    except ValueError as exc:
+        json.dump({"error": str(exc), "code": "INVALID_JSON"}, sys.stderr)
+        sys.stderr.write("\n")
+        return 2
+
+    result = hash_urls(entries)
+    json.dump(result, sys.stdout, separators=(",", ":"))
+    sys.stdout.write("\n")
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # CLI entry point
 # ---------------------------------------------------------------------------
 
+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 (raw UTF-8 input on stdin for `compare-hashes -` and
+    `hash-urls -`). 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)
     # Additive subcommand: route `compare-hashes ...` to the doc-drift path
     # before the existing detect parser runs. The default (no subcommand)
     # invocation `--repo-url <url> ...` is unchanged.
     if len(sys.argv) > 1 and sys.argv[1] == "compare-hashes":
         return _cmd_compare_hashes(sys.argv[2:])
+    if len(sys.argv) > 1 and sys.argv[1] == "hash-urls":
+        return _cmd_hash_urls(sys.argv[2:])
 
     parser = argparse.ArgumentParser(
         description="Detect documentation URLs for a GitHub repository.",

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

@@ -89,6 +89,7 @@ DETECT_OUTPUT_SCHEMA (v1):
       "previous_ccc_indexed_path":              str|null,
       "previous_ccc_last_indexed":              str|null,
       "previous_ccc_staleness_threshold_hours": int|null,
+      "previous_ccc_file_count":                 int|null,
       # Deterministic CCC-index freshness verdict — computed against
       # --project-root and datetime.now(UTC) captured at detect time, so the
       # ccc-index.md step branches on a boolean instead of doing timestamp math.
@@ -142,6 +143,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 +173,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 +189,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
@@ -335,6 +370,7 @@ def read_prior_state(prior_state_path) -> dict:
         "previous_ccc_indexed_path": None,
         "previous_ccc_last_indexed": None,
         "previous_ccc_staleness_threshold_hours": None,
+        "previous_ccc_file_count": None,
     }
     if not prior_state_path:
         return empty
@@ -359,6 +395,10 @@ def read_prior_state(prior_state_path) -> dict:
         "previous_ccc_indexed_path": ccc_index.get("indexed_path"),
         "previous_ccc_last_indexed": ccc_index.get("last_indexed"),
         "previous_ccc_staleness_threshold_hours": ccc_index.get("staleness_threshold_hours"),
+        # Surfaced so ccc-index.md's fresh-index branch can carry the count
+        # forward instead of leaving `{ccc_file_count}` unbound (or nulling a
+        # value the index still has) when nothing re-indexes this run.
+        "previous_ccc_file_count": ccc_index.get("file_count"),
     }