@drafthq/draft 3.5.2 → 3.6.0

package/scripts/tools/render-track.sh

@@ -48,7 +48,7 @@ TO_STDOUT=0
 while (($#)); do
     case "$1" in
         -h|--help) USAGE_HELP_MODE=1 usage ;;
-        --out) OUT_PATH="$2"; shift 2 ;;
+        --out) OUT_PATH="${2:?--out requires a value}"; shift 2 ;;
         --stdout) TO_STDOUT=1; shift ;;
         -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
         *) TRACK_DIR="$1"; shift ;;

package/scripts/tools/run-coverage.sh

@@ -51,7 +51,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --path) COVERAGE_PATH="$2"; shift 2;;
+        --path) COVERAGE_PATH="${2:?--path requires a value}"; shift 2;;
         --schema-check) SCHEMA_CHECK="true"; shift;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;

package/scripts/tools/scan-markers.sh

@@ -6,7 +6,7 @@
 #
 # Usage:
 # scripts/tools/scan-markers.sh [--root DIR] [--markers LIST]
-# [--min-age-days N] [--include-untracked]
+# [--min-age-days N]
 #
 # Exit codes: 0 OK (even with zero hits), 1 invocation error, 2 not a git repo
 # (emits [] on stdout so consumers can still parse).
@@ -38,9 +38,9 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --root) ROOT="$2"; shift 2;;
-        --markers) MARKERS="$2"; shift 2;;
-        --min-age-days) MIN_AGE="$2"; shift 2;;
+        --root) ROOT="${2:?--root requires a value}"; shift 2;;
+        --markers) MARKERS="${2:?--markers requires a value}"; shift 2;;
+        --min-age-days) MIN_AGE="${2:?--min-age-days requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac

package/scripts/tools/validate-frontmatter.sh

@@ -43,8 +43,8 @@ REQUIRED="name,description"
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --require) REQUIRED="$2"; shift 2;;
-        --mode) MODE="$2"; shift 2;;
+        --require) REQUIRED="${2:?--require requires a value}"; shift 2;;
+        --mode) MODE="${2:?--mode requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
         *)

package/scripts/tools/verify-citations.sh

@@ -48,7 +48,7 @@ while (($#)); do
     case "$1" in
         -h|--help) USAGE_HELP_MODE=1 usage ;;
         --json) EMIT_JSON=1; shift ;;
-        --tolerance) TOLERANCE="$2"; shift 2 ;;
+        --tolerance) TOLERANCE="${2:?--tolerance requires a value}"; shift 2 ;;
         -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
         *) TRACK_PATHS+=("$1"); shift ;;
     esac
@@ -83,7 +83,7 @@ extract_citations() {
             # bracket expression prematurely terminates a regex literal in
             # POSIX/BSD awk ("nonterminated character class"), though gawk is
             # lenient. The string form is portable across awk implementations.
-            while (match(s, "[A-Za-z0-9_][A-Za-z0-9_./-]*\\.[A-Za-z0-9]+:[0-9]+")) {
+            while (match(s, "[A-Za-z0-9_][A-Za-z0-9_./-]*\\.[A-Za-z0-9]+:[0-9]+(-[0-9]+)?")) {
                 cite = substr(s, RSTART, RLENGTH)
                 printf("%s\t%d\t%s\n", FILENAME, NR, cite)
                 s = substr(s, RSTART + RLENGTH)

package/scripts/tools/verify-doc-anchors.sh

@@ -150,7 +150,7 @@ scan_md() {
         # token the `(planned)` annotation owns.
         if echo "$line" | grep -qE '\(planned\)|\[New file'; then
             local paths
-            paths="$(echo "$line" | grep -oE '[A-Za-z][A-Za-z0-9_./-]*\.[A-Za-z]+' | sort -u)"
+            paths="$(echo "$line" | grep -oE '[A-Za-z][A-Za-z0-9_./-]*\.[A-Za-z]+' | sort -u || true)"
             local path_count
             path_count="$(printf '%s\n' "$paths" | grep -c . || true)"
             if (( path_count == 1 )); then

package/scripts/tools/verify-graph-binary.sh

@@ -51,8 +51,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --repo) REPO="$2"; shift 2 ;;
-    --plugin-root) PLUGIN_ROOT="$2"; shift 2 ;;
+    --repo) REPO="${2:?--repo requires a value}"; shift 2 ;;
+    --plugin-root) PLUGIN_ROOT="${2:?--plugin-root requires a value}"; shift 2 ;;
     --json) EMIT_JSON=1; shift ;;
     --verbose) VERBOSE=1; shift ;;
     --strict) STRICT=1; shift ;;

package/skills/adr/SKILL.md

@@ -54,7 +54,7 @@ Check for arguments:
 If argument is `list`:
 1. Prefer the deterministic `adr-index.sh` wrapper for the listing — it returns a structured JSON `{adrs:[{id,title,date,status,path,related_tracks}]}` derived from each ADR's frontmatter. Resolve via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
    ```bash
-   DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+   DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/bughunt/SKILL.md

@@ -72,7 +72,7 @@ Read and follow the base procedure in `core/shared/draft-context-loading.md`.
   ```bash
   # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
   # is not exported into skill Bash). See core/shared/tool-resolver.md.
-  DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+  DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/coverage/SKILL.md

@@ -33,7 +33,7 @@ If no active track and no argument provided:
 **Preferred:** use the deterministic `detect-test-framework.sh` wrapper — it emits JSON `{languages:[{language,framework,runner_command,test_globs,config_file}]}`. Resolve via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
 
 ```bash
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -75,7 +75,7 @@ Build the coverage command with the appropriate scope/filter flags.
 
 ```bash
 # Re-resolve helpers (this is a separate Bash session from Step 2).
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/debug/SKILL.md

@@ -14,7 +14,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/decompose/SKILL.md

@@ -14,7 +14,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -417,7 +417,7 @@ Resolve the script via the canonical tool resolver (see [core/shared/tool-resolv
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -664,7 +664,7 @@ As the last step after the completion announcement, emit a metrics record. Best-
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/deep-review/SKILL.md

@@ -15,7 +15,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -330,7 +330,7 @@ As the last step after saving the deep-review report, emit a metrics record. Bes
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/deploy-checklist/SKILL.md

@@ -67,7 +67,7 @@ by validator.
 ```bash
 TRACK_DIR="$1" # absolute path to track-under-deploy, or .
 
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/graph/SKILL.md

@@ -37,7 +37,7 @@ echo "Target repo: $REPO_ABS"
 # Locate Draft's bundled helpers. Skills run with cwd = the user's project and
 # ${CLAUDE_PLUGIN_ROOT} is not exported into skill Bash, so resolve DRAFT_TOOLS here
 # and call helpers as "$DRAFT_TOOLS/<tool>.sh". See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/impact/SKILL.md

@@ -21,7 +21,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/implement/SKILL.md

@@ -139,7 +139,7 @@ If one of these applies, route directly to the specialist workflow and stop this
    ```bash
    # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
    # is not exported into skill Bash). See core/shared/tool-resolver.md.
-   DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+   DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -639,7 +639,7 @@ After a phase passes review, refresh `metadata.json.impact` so future tracks can
 
 2. **Compute downstream blast radius (graph-aware, optional):** If `draft/graph/schema.yaml` exists, for each file in `files_touched` query (this runs in its own Bash session — re-resolve the helpers):
    ```bash
-   DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+   DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/init/SKILL.md

@@ -218,13 +218,16 @@ The tier-gated default rests on **maintainability/readability** (one navigable c
 
 **OKF Completeness Verification (blocking — tier 3+ `okf` mode).** Completeness is enforced by tooling, not honor system, so the wiki is generated completely for every module/sub-module/component on every run. Before promoting `draft.tmp/` → `draft/`, ALL must hold (see `references/okf-emitter.md` for the pipeline):
 
-1. `okf-plan-concepts.sh` ran and the expected/required/deferred counts were logged **before** any page was written (the concept boundary is a tool output, not an in-context guess).
-2. Every `required` entry in `concept-plan.json` has a non-stub page.
-3. `okf-validate-all.sh … --plan … --strict` exits 0 (structure + per-type quality + coverage all pass).
-4. `systems/coverage.md` was generated by tooling (verify the `<!-- okf:coverage-generated -->` marker) — **every** package/module the graph found is required by default (the fan-in floor only types Subsystem-vs-Module, it does not exempt), so none may be **MISSING**. Section `index.md` tables are regenerated by `okf-render-views.sh --section-indexes`, never hand-authored, so their links cannot dangle.
-5. On any failure: **do not** atomic-rename; surface `.state/validation-report.json`.
+1. `okf-plan-concepts.sh` ran and counts were logged **before** any page was written. Plan discovery is language-aware: **Cargo workspace members / npm workspaces / Go modules first**, then graph packages (noise-filtered), then heuristic dirs. Log `discovery[]` (e.g. `cargo+graph`).
+2. `okf-emit-catalog.sh` ran so every REQUIRED plan entry has at least a minimum non-stub catalog page (LLM deep-dives may enrich top hotspots afterward).
+3. Every `required` entry in `concept-plan.json` has a non-stub page.
+4. `okf-render-views.sh` + `okf-fix-links.sh --fix` produced `architecture.md` with resolving `wiki/…` links and GFM TOC anchors.
+5. `okf-validate-all.sh … --plan … --strict` exits 0 (**quality → coverage → structure**; structure runs last so coverage.md rewrites are checked).
+6. `okf-fix-links.sh --draft draft.tmp --check` exits 0 (zero dead links in architecture / wiki views).
+7. `systems/coverage.md` has the `<!-- okf:coverage-generated -->` marker; section indexes were regenerated by `okf-render-views.sh --section-indexes`.
+8. On any failure: **do not** atomic-rename; surface `.state/validation-report.json`.
 
-> **Red flag:** writing concept pages without first running `okf-plan-concepts.sh`, or finishing generation while any `required` plan entry is unwritten, is a **completeness failure** — not a stylistic one.
+> **Red flag:** writing concept pages without first running `okf-plan-concepts.sh` + `okf-emit-catalog.sh`, or finishing while any `required` plan entry is unwritten, is a **completeness failure** — not a stylistic one.
 
 ### Route Explicit Modes Before Initialization
 
@@ -524,7 +527,7 @@ One command resolves ROOT, ensures the engine, builds the whole-repo spine, and
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/init/references/architecture-spec.md

@@ -280,7 +280,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/init/references/okf-emitter.md

@@ -77,7 +77,8 @@ Templates for each bundle page live in `core/templates/okf/` (`index.md`,
 ## Frozen `type` vocabulary
 
 Every concept carries a `type` from this frozen set (changing it churns every
-file; versioned via `index.md` frontmatter `okf_types_version`):
+file; versioned via the `okf-types-version` comment in the wiki root `index.md`
+body — OKF §6/§11 permit only `okf_version` in an index file's frontmatter):
 
 | type | Maps to | Home |
 |------|---------|------|
@@ -103,6 +104,16 @@ the task at hand?"), never a summary. Draft extensions are namespaced `x-` and
 ignored by generic OKF consumers: `x-grounded-paths`, `x-hotspot-score`,
 `x-callers`.
 
+**Meta pages are not concepts.** Index files (`wiki/index.md` and every
+`<section>/index.md`) carry **no concept frontmatter**: per OKF §6 an index file
+has no frontmatter, and per §11 the root `index.md` may declare **only**
+`okf_version`. The tool-generated `systems/coverage.md` is a non-reserved file, so
+OKF §9.1/§9.2 require it to carry a typed frontmatter block; it uses a descriptive
+`type: Report` and is exempt from the frozen vocabulary via `is_meta_page`
+(basename + the `<!-- okf:coverage-generated -->` marker). `okf-validate.sh`
+short-circuits all meta pages before the concept checks, so they are never
+vocab-checked or counted as concepts.
+
 ## Concept granularity (resolves open decision 1)
 
 Derive concepts from the graph, not by hand:
@@ -122,75 +133,40 @@ Derive concepts from the graph, not by hand:
 ```
 1. Survey        → existing /draft:init 5-phase + graph snapshot (graph-snapshot.sh)
 2. Plan          → DETERMINISTIC. okf-plan-concepts.sh derives the expected-concept
-                   set from the graph. EVERY package the graph knows about is
-                   required (fan_in ≥ floor → Subsystem; below floor → Module — the
-                   floor only types/orders, it never exempts); entrypoints → required;
-                   only --allow-defer matches are deferred (with a reason). Writes
-                   draft.tmp/.state/concept-plan.json.
+                   set. Discovery order (exclusive of --manifest):
+                     a) Cargo workspace members / npm workspaces / Go modules
+                     b) graph packages (noise-filtered when a language inventory exists)
+                     c) heuristic top-level source dirs
+                   Coarse graph parents (e.g. crates/codegen) become Subsystems;
+                   crate/package names become Modules. Tokenizer noise (str, int, …)
+                   is dropped when unmapped. Writes draft.tmp/.state/concept-plan.json.
                      okf-plan-concepts.sh --repo . [--scope PATH] \
                        [--manifest FILE] [--min-fan-in 2] [--allow-defer GLOB]... \
                        --out draft.tmp/.state/concept-plan.json
-                   This replaces the old in-context concept enumeration — the boundary
-                   of the work is now a tool output, not an LLM judgment, so modules
-                   and sub-modules cannot be silently dropped. (Legacy fan-in
-                   exemption is opt-in via --defer-below-floor.) LOG the counts
-                   (expected/required/deferred) BEFORE writing any page.
-                   `generated_order` is topo-ish (required + high-fan-in first) so
-                   forward cross-links resolve.
-3. Generate      → iterate concept-plan.generated_order; write ONE page per REQUIRED
-                   entry, grounding each from the graph:
-                     x-callers        ← graph-callers.sh --symbol <c>
-                     x-grounded-paths  ← graph-impact.sh  --symbol <c>  (blast radius)
-                     x-hotspot-score   ← hotspot-rank.sh
-                     overview diagrams ← mermaid-from-graph.sh
-                   Record each source path → page in .state/path-to-concept.json.
-                   Loop post-condition: every required concept_id has an output file.
-                   ⚠ Writing pages via shell heredoc without reading x-grounded-paths
-                   sources, or finishing while any required entry is unwritten, is a
-                   completeness failure — not a stylistic one.
-4. Render views  → ai-context.md (synopsis + Concept Map), architecture.md
-                   (concatenated view + coverage banner), wiki/log.md  (see M4).
-5. Validate      → the promotion gate. Run all layers via the orchestrator:
-                     5a. okf-validate-all.sh draft.tmp/wiki \
-                           --repo . \
-                           --plan draft.tmp/.state/concept-plan.json \
-                           --path-index draft.tmp/.state/path-to-concept.json \
-                           --strict --report draft.tmp/.state/validation-report.json
-                   It runs, in order: okf-validate.sh (structure + reverse index +
-                   empty/untyped-page + leftover-template-token + dangling-link checks),
-                   okf-validate-quality.sh (per-type anti-stub / depth / per-section
-                   content / mermaid lint), okf-coverage-check.sh (every required plan
-                   entry → real page).
-                   ANY layer failing ⇒ exit non-zero ⇒ DO NOT atomic-rename.
-                   coverage.md (systems/coverage.md) is regenerated by the coverage
-                   layer; it is tool-owned (marker <!-- okf:coverage-generated -->) —
-                   never hand-author it except deferral reasons in the manifest.
-6. Emit          → mv draft.tmp/ draft/  ONLY IF step 5 exit 0 ; update .state/.
-                   On failure keep draft.tmp/ and surface validation-report.json.
-```
-
-### Validation report schema (`.state/validation-report.json`)
-
-```json
-{ "valid": false, "bundle": "draft.tmp/wiki",
-  "layers": { "structure": "pass", "quality": "pass", "coverage": "fail" } }
+                   LOG counts (expected/required/deferred + discovery[]) BEFORE pages.
+3. Catalog floor → okf-emit-catalog.sh writes a quality-passing MINIMUM page for
+                   every REQUIRED plan entry that is still missing (so XL monorepos
+                   do not depend on the LLM for completeness):
+                     okf-emit-catalog.sh --plan draft.tmp/.state/concept-plan.json \
+                       --bundle draft.tmp/wiki --repo .
+4. Generate/enrich → iterate concept-plan.generated_order; enrich top hotspots
+                   (LLM) beyond the catalog floor. Record path-to-concept.json.
+                   Post-condition: every required concept_id has a non-stub page.
+5. Render views  → okf-render-views.sh (architecture.md + Concept Map + section
+                   indexes). Uses GFM slugs for TOC; rewrites sibling links to
+                   wiki/<section>/…. Then okf-fix-links.sh --draft draft.tmp --fix.
+6. Validate      → promotion gate (order is intentional):
+                     okf-validate-all.sh draft.tmp/wiki \
+                       --plan draft.tmp/.state/concept-plan.json \
+                       --path-index draft.tmp/.state/path-to-concept.json \
+                       --strict --report draft.tmp/.state/validation-report.json
+                   Runs: quality → coverage (rewrites coverage.md) → structure LAST
+                   so coverage relative links are checked. Also run:
+                     okf-fix-links.sh --draft draft.tmp --check
+                   ANY failure ⇒ DO NOT atomic-rename.
+7. Emit          → mv draft.tmp/ draft/  ONLY IF step 6 exit 0 ; update .state/.
 ```
 
-### Component manifest (optional — `--manifest FILE`)
-
-When the graph engine is unavailable (or a repo wants an authoritative list), pass
-a plain-text manifest: one component name per line, `#` comments and blanks ignored.
-Every listed component becomes a REQUIRED concept; `--allow-defer GLOB` still moves
-matches to deferred. Without a manifest the plan comes from the graph, and only if
-both are unavailable does it fall back to a heuristic top-level-dir scan (which it
-marks `degraded: true`).
-
-Page bodies are LLM-narrated for readability **but** the graph-derived
-frontmatter and the `Blast radius`/`Used by` sections are deterministic. To keep
-incremental carry-forward byte-identical (open decision 2), cache the narrated
-prose keyed by the source hash of `x-grounded-paths` — unchanged sources reuse
-the cached narration verbatim.
-
 ## Render views (M4)
 
 Both are produced by the deterministic helper `okf-render-views.sh` (no LLM) —
@@ -244,17 +220,16 @@ section `index.md` tables are the injection slots for the routing tables.
 `/draft:init refresh` under `okf` mode:
 
 ```
-1. Re-derive the plan: okf-plan-concepts.sh (modules added since last run become
-   REQUIRED — a new package can't slip through a refresh either)
-2. Diff hashes.json vs working tree     → changed source paths
-3. path-to-concept.json                 → affected concept pages
-4. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
-5. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
-6. Re-validate (full gate): okf-validate-all.sh on the bundle with --plan and
-   --path-index. Refresh re-runs structure + quality + coverage — a changed
-   concept must still clear the quality bar, and a newly-required module must
-   still be present.
-7. Append log.md; update hashes.json + path-to-concept.json
+1. Re-derive the plan: okf-plan-concepts.sh (cargo/npm/go + graph). Modules added
+   since last run become REQUIRED — a new crate cannot slip through a refresh.
+2. Diff plan vs previous concept-plan.json → NEW required concept_ids
+3. Diff hashes.json vs working tree       → changed source paths
+4. path-to-concept.json                   → affected concept pages
+5. okf-emit-catalog.sh for any NEW missing required pages (completeness floor)
+6. Regenerate/enrich changed + new concepts; carry the rest verbatim
+7. Re-render ai-context.md / architecture.md / log.md + okf-fix-links --fix
+8. Re-validate: okf-validate-all + okf-fix-links --check
+9. Append log.md; update hashes.json + path-to-concept.json + concept-plan.json
 ```
 
 A 1-file change regenerates only the concept(s) that file grounds. Unchanged

package/skills/learn/SKILL.md

@@ -14,7 +14,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/quick-review/SKILL.md

@@ -15,7 +15,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/review/SKILL.md

@@ -15,7 +15,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -384,7 +384,7 @@ For the files changed in the diff, perform static checks using `grep` or similar
    ```bash
    # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
    # is not exported into skill Bash). See core/shared/tool-resolver.md.
-   DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+   DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -1129,7 +1129,7 @@ As the last step after saving the review report, emit a metrics record. Best-eff
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/standup/SKILL.md

@@ -54,7 +54,7 @@ Check for arguments:
 **Preferred:** invoke `parse-git-log.sh` — it parses conventional commits into structured JSONL `{sha,type,scope,track_id,subject,author,timestamp,files_changed}`, eliminating ambiguity in `type(track-id): subject` parsing. Resolve via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
 
 ```bash
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/status/SKILL.md

@@ -44,7 +44,7 @@ Display a comprehensive overview of project progress.
 If `parse-reports.sh` and `freshness-check.sh` are available, gather structured signals to enrich the status output (severity counts per track, stale `draft/` docs). Resolve via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
 
 ```bash
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/tech-debt/SKILL.md

@@ -14,7 +14,7 @@ First resolve the bundled helpers:
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
@@ -95,7 +95,7 @@ For TODO/FIXME/HACK/XXX/DEPRECATED markers, prefer the deterministic `scan-marke
 ```bash
 # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
 # is not exported into skill Bash). See core/shared/tool-resolver.md.
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"

package/skills/upload/SKILL.md

@@ -52,7 +52,7 @@ Run the WS-9 chain from [verification-gates.md](../../core/shared/verification-g
 
 ```bash
 TRACK_DIR="draft/tracks/<id>"
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}/scripts/tools"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"