@drafthq/draft 3.4.0 → 3.5.1

package/scripts/lib.sh

@@ -197,6 +197,11 @@ TOOLS=(
     # OKF taxonomy emitter (DRAFT_INIT_MODE=okf)
     "okf-validate.sh"
     "okf-render-views.sh"
+    # OKF completeness enforcement (deterministic plan + coverage/quality gates)
+    "okf-plan-concepts.sh"
+    "okf-validate-quality.sh"
+    "okf-coverage-check.sh"
+    "okf-validate-all.sh"
 )
 
 # ─────────────────────────────────────────────────────────

package/scripts/tools/_lib.sh

@@ -203,6 +203,73 @@ memory_project_for_repo() {
         | head -1
 }
 
+# Total physical RAM in MB (portable). Echoes a positive integer, or nothing.
+_total_ram_mb() {
+    if [[ -r /proc/meminfo ]]; then
+        awk '/^MemTotal:/{printf "%d", $2/1024; exit}' /proc/meminfo
+    elif command -v sysctl >/dev/null 2>&1; then   # macOS / BSD
+        local bytes; bytes="$(sysctl -n hw.memsize 2>/dev/null || true)"
+        [[ -n "$bytes" ]] && printf '%d' "$(( bytes / 1024 / 1024 ))"
+    fi
+}
+
+# Cgroup memory args for a transient scope. MemoryHigh throttles (reclaim/swap →
+# slower, never thrashes the host); MemoryMax is the hard ceiling a few % above.
+# Pure (no I/O) so it is unit-testable. Usage: _mem_bound_args <total_mb> <pct>
+_mem_bound_args() {
+    local total="$1" pct="$2"
+    printf 'MemoryHigh=%dM MemoryMax=%dM' \
+        "$(( total * pct / 100 ))" "$(( total * (pct + 5) / 100 ))"
+}
+
+# Whether this host can confine a process to a memory-bounded cgroup v2 scope.
+# Probes once (starts a throwaway scope) and caches the verdict for the process.
+_DRAFT_CGROUP_OK=""
+_can_cgroup_bound() {
+    if [[ -z "$_DRAFT_CGROUP_OK" ]]; then
+        if command -v systemd-run >/dev/null 2>&1 \
+            && [[ -e /sys/fs/cgroup/cgroup.controllers ]] \
+            && systemd-run --user --scope -q -p MemoryMax=64M -- true >/dev/null 2>&1; then
+            _DRAFT_CGROUP_OK=yes
+        else
+            _DRAFT_CGROUP_OK=no
+        fi
+    fi
+    [[ "$_DRAFT_CGROUP_OK" == yes ]]
+}
+
+# Index a repository under a memory bound. The codebase-memory-mcp engine
+# self-budgets ~50% of *physical* RAM and is not cgroup-aware, so a first index
+# of a huge repo can exhaust the host (the original 30 GB hang). On Linux we
+# confine it to a transient cgroup scope sized to DRAFT_INDEX_MEM_PCT (default
+# 25) of total RAM; CBM_WORKERS caps the engine's parallel working set so the
+# throttle has less transient pressure to absorb. Where cgroup v2 + systemd-run
+# are unavailable (e.g. macOS) the worker cap is the only bound. Never falls back
+# from a started scope to an unbounded run — a bounded OOM fails the index
+# cleanly (host stays alive) rather than re-triggering the hang.
+# Echoes the engine's JSON result on stdout (same contract as memory_cli).
+memory_index_bounded() {
+    local repo_abs="$1"
+    local json="{\"repo_path\":\"$repo_abs\"}"
+    export CBM_WORKERS="${CBM_WORKERS:-4}"
+    local total pct
+    total="$(_total_ram_mb)"
+    pct="${DRAFT_INDEX_MEM_PCT:-25}"
+    if [[ "${total:-0}" -gt 0 ]] && _can_cgroup_bound; then
+        local high_arg max_arg
+        read -r high_arg max_arg <<< "$(_mem_bound_args "$total" "$pct")"
+        if [[ -n "${DRAFT_MEMORY_DEBUG:-}" ]]; then
+            systemd-run --user --scope -q -p "$high_arg" -p "$max_arg" \
+                -- "$MEMORY_BIN" cli index_repository "$json"
+        else
+            systemd-run --user --scope -q -p "$high_arg" -p "$max_arg" \
+                -- "$MEMORY_BIN" cli index_repository "$json" 2>/dev/null
+        fi
+    else
+        memory_cli index_repository "$json"
+    fi
+}
+
 # Ensure a repository is indexed in the engine; echo its project name.
 # Indexes on demand when absent. Returns 1 if the engine is unavailable.
 memory_ensure_index() {
@@ -212,7 +279,7 @@ memory_ensure_index() {
     local proj
     proj="$(memory_project_for_repo "$repo_abs" 2>/dev/null || true)"
     if [[ -z "$proj" ]]; then
-        proj="$(memory_cli index_repository "{\"repo_path\":\"$repo_abs\"}" 2>/dev/null \
+        proj="$(memory_index_bounded "$repo_abs" \
             | jq -r '.project // empty' 2>/dev/null || true)"
     fi
     [[ -n "$proj" ]] || return 1

package/scripts/tools/okf-coverage-check.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# okf-coverage-check.sh — prove the OKF bundle documents EVERY required component.
+#
+# This is the gate that fixes "the wiki is not generated completely for all
+# modules". It compares the deterministic expected set (concept-plan.json from
+# okf-plan-concepts.sh) against the pages that actually exist in the bundle. A
+# required concept with no page — or a present-but-empty page — fails the build,
+# so a gappy bundle cannot be promoted (draft.tmp/ → draft/). Deferred entries
+# must be reasoned in the generated coverage.md, never silently absent.
+#
+# Checks:
+#   C-PLAN   every required plan entry has a bundle page (concept_id exists)
+#   C-STUB   each satisfying page has real body content (>= --min-stub-lines)
+#   C-DEFER  every deferred entry is recorded with a reason (always true: from plan)
+#
+# Side effect: regenerates <BUNDLE>/systems/coverage.md (tool-owned) unless
+# --no-coverage-page is given.
+#
+# Usage:
+#   okf-coverage-check.sh --plan FILE --bundle DIR [--min-stub-lines N]
+#                         [--no-coverage-page] [--json] [--report FILE]
+#
+# Exit codes: 0 complete, 1 incomplete (missing/stub required), 2 plan/bundle missing.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/tools/_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+PLAN=""
+BUNDLE=""
+MIN_STUB_LINES=10
+WRITE_PAGE=1
+JSON=0
+REPORT=""
+
+usage() {
+    cat <<'EOF'
+okf-coverage-check.sh — verify every required concept in the plan has a real page.
+
+Usage:
+  okf-coverage-check.sh --plan FILE --bundle DIR [--min-stub-lines N]
+                        [--no-coverage-page] [--json] [--report FILE]
+
+Flags:
+  --plan FILE          concept-plan.json from okf-plan-concepts.sh (required).
+  --bundle DIR         The wiki/ bundle directory (required).
+  --min-stub-lines N   Min non-blank body lines for a page to count as real (default 10).
+  --no-coverage-page   Do not (re)write <BUNDLE>/systems/coverage.md.
+  --json               Emit a JSON summary.
+  --report FILE        Also write the JSON summary to FILE.
+  --help               Show this help.
+
+Exit: 0 complete, 1 incomplete, 2 plan/bundle not found.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --plan) PLAN="$2"; shift 2;;
+        --bundle) BUNDLE="$2"; shift 2;;
+        --min-stub-lines) MIN_STUB_LINES="$2"; shift 2;;
+        --no-coverage-page) WRITE_PAGE=0; shift;;
+        --json) JSON=1; shift;;
+        --report) REPORT="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -n "$PLAN" ]] || { usage >&2; exit 1; }
+[[ -n "$BUNDLE" ]] || { usage >&2; exit 1; }
+[[ -f "$PLAN" ]] || { echo "ERROR: plan not found: $PLAN" >&2; exit 2; }
+[[ -d "$BUNDLE" ]] || { echo "ERROR: bundle directory not found: $BUNDLE" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "ERROR: jq required" >&2; exit 2; }
+BUNDLE="${BUNDLE%/}"
+
+jq -e '.expected' "$PLAN" >/dev/null 2>&1 || { echo "ERROR: plan has no .expected array: $PLAN" >&2; exit 2; }
+
+# Non-blank body line count for a page.
+body_lines() {
+    awk 'NR==1&&/^---$/{fm=1;next} fm&&/^---$/{fm=0;next} !fm{print}' "$1" | grep -cE '.' || true
+}
+
+MISSING=()      # concept_id (required, no page)
+STUB=()         # concept_id\tlines (required, page too thin)
+FULL=()         # concept_id
+DEFERRED=()     # concept_id\treason
+EXPECTED_TOTAL=0; REQUIRED=0
+
+# Iterate expected entries.
+while IFS=$'\t' read -r cid required reason ftype fanin; do
+    [[ -z "$cid" ]] && continue
+    EXPECTED_TOTAL=$((EXPECTED_TOTAL + 1))
+    if [[ "$required" == "true" ]]; then
+        REQUIRED=$((REQUIRED + 1))
+        if [[ -f "$BUNDLE/$cid" ]]; then
+            bl="$(body_lines "$BUNDLE/$cid")"
+            if [[ "$bl" -ge "$MIN_STUB_LINES" ]]; then
+                FULL+=("$cid")
+            else
+                STUB+=("$cid"$'\t'"$bl")
+            fi
+        else
+            MISSING+=("$cid")
+        fi
+    else
+        DEFERRED+=("$cid"$'\t'"${reason:-unspecified}")
+    fi
+done < <(jq -r '.expected[] | [.concept_id, (.required|tostring), (.reason_if_deferred // "-"), (.type // "Module"), (.fan_in // 0 | tostring)] | @tsv' "$PLAN")
+
+MAPPED=$(( ${#FULL[@]} ))
+PASS=1
+{ [[ ${#MISSING[@]} -gt 0 ]] || [[ ${#STUB[@]} -gt 0 ]]; } && PASS=0
+PCT=100
+[[ $REQUIRED -gt 0 ]] && PCT=$(( MAPPED * 100 / REQUIRED ))
+
+# --- Generate coverage.md (tool-owned) ---
+write_coverage_page() {
+    local out="$BUNDLE/systems/coverage.md"
+    mkdir -p "$BUNDLE/systems"
+    local tmp; tmp="$(mktemp)"
+    {
+        echo "<!-- okf:coverage-generated -->"
+        echo "# Component Coverage"
+        echo ""
+        echo "> Generated by \`okf-coverage-check.sh\` — do not hand-edit (except deferral reasons in the manifest)."
+        echo "> Required components documented: ${MAPPED}/${REQUIRED} (${PCT}%)."
+        echo ""
+        echo "| Component | Wiki page | Status | Fan-in |"
+        echo "|-----------|-----------|--------|--------|"
+        local cid status fanin
+        while IFS=$'\t' read -r cid required reason ftype fanin; do
+            [[ -z "$cid" ]] && continue
+            if [[ "$required" == "true" ]]; then
+                if [[ -f "$BUNDLE/$cid" ]]; then
+                    bl="$(body_lines "$BUNDLE/$cid")"
+                    if [[ "$bl" -ge "$MIN_STUB_LINES" ]]; then
+                        echo "| \`${cid%.md}\` | [page](${cid#systems/}) | Full | ${fanin} |"
+                    else
+                        echo "| \`${cid%.md}\` | ${cid} | **STUB (${bl} lines)** | ${fanin} |"
+                    fi
+                else
+                    echo "| \`${cid%.md}\` | — | **MISSING** | ${fanin} |"
+                fi
+            else
+                echo "| \`${cid%.md}\` | — | Deferred (${reason:-unspecified}) | ${fanin} |"
+            fi
+        done < <(jq -r '.expected[] | [.concept_id, (.required|tostring), (.reason_if_deferred // "-"), (.type // "Module"), (.fan_in // 0 | tostring)] | @tsv' "$PLAN")
+    } > "$tmp"
+    mv "$tmp" "$out"
+}
+[[ $WRITE_PAGE -eq 1 ]] && write_coverage_page
+
+# --- Report ---
+emit_json() {
+    printf '{"valid":%s,"bundle":"%s","plan":"%s","required":%d,"mapped":%d,"coverage_pct":%d,"missing":[' \
+        "$([[ $PASS -eq 1 ]] && echo true || echo false)" \
+        "$(json_escape "$BUNDLE")" "$(json_escape "$PLAN")" "$REQUIRED" "$MAPPED" "$PCT"
+    for i in "${!MISSING[@]}"; do [[ $i -gt 0 ]] && printf ','; printf '"%s"' "$(json_escape "${MISSING[$i]}")"; done
+    printf '],"stub":['
+    local first=1
+    for s in "${STUB[@]:-}"; do
+        [[ -z "$s" ]] && continue
+        IFS=$'\t' read -r cid bl <<< "$s"
+        [[ $first -eq 1 ]] && first=0 || printf ','
+        printf '{"concept_id":"%s","lines":%d}' "$(json_escape "$cid")" "$bl"
+    done
+    printf '],"deferred":%d}\n' "${#DEFERRED[@]}"
+}
+
+if [[ -n "$REPORT" ]]; then mkdir -p "$(dirname "$REPORT")"; emit_json > "$REPORT"; fi
+
+if [[ $JSON -eq 1 ]]; then
+    emit_json
+else
+    if [[ $PASS -eq 1 ]]; then
+        echo "OKF coverage complete: ${MAPPED}/${REQUIRED} required components (${PCT}%), ${#DEFERRED[@]} deferred"
+    else
+        echo "OKF coverage INCOMPLETE: ${MAPPED}/${REQUIRED} required (${PCT}%)" >&2
+        for m in "${MISSING[@]:-}"; do [[ -n "$m" ]] && echo "  - MISSING: $m" >&2; done
+        for s in "${STUB[@]:-}"; do
+            [[ -z "$s" ]] && continue
+            IFS=$'\t' read -r cid bl <<< "$s"
+            echo "  - STUB: $cid ($bl body lines < $MIN_STUB_LINES)" >&2
+        done
+    fi
+fi
+
+[[ $PASS -eq 1 ]] || exit 1
+exit 0

package/scripts/tools/okf-plan-concepts.sh

@@ -0,0 +1,296 @@
+#!/usr/bin/env bash
+# okf-plan-concepts.sh — derive the DETERMINISTIC expected-concept set for an OKF
+# bundle, BEFORE any page is written.
+#
+# The OKF emitter used to let the LLM enumerate the concept list in-context, so
+# under context pressure it silently under-enumerated and modules went
+# undocumented — and okf-validate.sh only ever checked the pages that *did* get
+# written. This tool makes the boundary of the work a tool output: every package
+# / module / component the graph knows about (at or above a fan-in floor), plus
+# every entrypoint, becomes a REQUIRED concept the bundle must contain. Pages
+# below the floor (or matching an allow-defer glob) are recorded as deferred with
+# a reason, never silently dropped.
+#
+# Discovery priority:
+#   1. --manifest FILE  — explicit component list (authoritative; every entry required)
+#   2. graph            — graph-arch.sh packages (fan_in) + entry_points
+#   3. heuristic        — top-level source dirs (engine unavailable; degraded:true)
+#
+# Output: concept-plan.json (see schema below). The generation loop iterates
+# `generated_order`; okf-coverage-check.sh gates promotion on every required
+# `concept_id` existing as a non-stub page.
+#
+# Usage:
+#   okf-plan-concepts.sh --repo DIR [--scope PATH] [--manifest FILE]
+#                        [--min-fan-in N] [--allow-defer GLOB]... [--out FILE] [--json]
+#
+# Exit codes: 0 plan written, 1 invocation error, 2 no expected set could be
+#             derived (graph + manifest both unavailable).
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/tools/_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+REPO="."
+SCOPE="."
+MANIFEST=""
+MIN_FAN_IN=2
+OUT=""
+JSON=0
+ALLOW_DEFER=()
+
+usage() {
+    cat <<'EOF'
+okf-plan-concepts.sh — derive the deterministic expected-concept set for an OKF bundle.
+
+Usage:
+  okf-plan-concepts.sh --repo DIR [--scope PATH] [--manifest FILE]
+                       [--min-fan-in N] [--allow-defer GLOB]... [--out FILE] [--json]
+
+Flags:
+  --repo DIR         Repository root (default: cwd).
+  --scope PATH       Sub-tree for module-scoped init (default: .).
+  --manifest FILE    Component list (one component per line; '#' comments; blanks
+                     ignored). When present it is authoritative — every entry is
+                     required and the graph is not consulted.
+  --min-fan-in N     Package fan-in floor for "required" (default: 2). Packages
+                     below the floor are deferred with a reason.
+  --allow-defer GLOB Defer (don't require) components whose name matches GLOB.
+                     Repeatable. Deferred entries still appear in the plan.
+  --out FILE         Write the plan JSON here (default: stdout).
+  --json             Also echo the plan JSON to stdout when --out is given.
+  --help             Show this help.
+
+Exit: 0 plan written, 1 invocation error, 2 no expected set derivable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --scope) SCOPE="$2"; shift 2;;
+        --manifest) MANIFEST="$2"; shift 2;;
+        --min-fan-in) MIN_FAN_IN="$2"; shift 2;;
+        --allow-defer) ALLOW_DEFER+=("$2"); shift 2;;
+        --out) OUT="$2"; shift 2;;
+        --json) JSON=1; shift;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ "$MIN_FAN_IN" =~ ^[0-9]+$ ]] || { echo "ERROR: --min-fan-in must be an integer" >&2; exit 1; }
+
+# Slugify a component name into a bundle-safe filename stem.
+slug() {
+    printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' \
+        | sed -E 's/^-+//; s/-+$//; s/-+/-/g'
+}
+
+# Does $1 match any --allow-defer glob?
+is_deferred_name() {
+    local name="$1" g
+    for g in "${ALLOW_DEFER[@]:-}"; do
+        [[ -z "$g" ]] && continue
+        # shellcheck disable=SC2053
+        [[ "$name" == $g ]] && return 0
+    done
+    return 1
+}
+
+# Accumulators (parallel arrays describing each expected concept).
+E_ID=(); E_TYPE=(); E_RES=(); E_FANIN=(); E_REQ=(); E_REASON=()
+SOURCE="heuristic"
+DEGRADED="false"
+
+add_concept() {
+    # name section type resource fan_in required reason
+    local name="$1" section="$2" type="$3" resource="$4" fan_in="$5" required="$6" reason="$7"
+    local stem; stem="$(slug "$name")"
+    [[ -n "$stem" ]] || stem="component"
+    E_ID+=("$section/$stem.md")
+    E_TYPE+=("$type")
+    E_RES+=("$resource")
+    E_FANIN+=("$fan_in")
+    E_REQ+=("$required")
+    E_REASON+=("$reason")
+}
+
+# --- 1. Manifest path (authoritative) ---
+plan_from_manifest() {
+    local line name
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        line="${line%%#*}"
+        name="$(printf '%s' "$line" | sed -E 's/^[[:space:]]*-?[[:space:]]*//; s/[[:space:]]*$//')"
+        [[ -z "$name" ]] && continue
+        if is_deferred_name "$name"; then
+            add_concept "$name" systems Module "$name" 0 false "manifest: allow-defer match"
+        else
+            add_concept "$name" systems Module "$name" 0 true ""
+        fi
+    done < "$MANIFEST"
+    SOURCE="manifest"
+}
+
+# --- 2. Graph path ---
+plan_from_graph() {
+    local arch; arch="$(scripts_graph_arch)" || return 1
+    [[ -n "$arch" ]] || return 1
+    echo "$arch" | jq -e '.packages != null' >/dev/null 2>&1 || return 1
+
+    SOURCE="graph"
+    local name fan_in type required reason
+    # Packages → systems/<pkg>.md
+    while IFS=$'\t' read -r name fan_in; do
+        [[ -z "$name" ]] && continue
+        if is_deferred_name "$name"; then
+            required=false; reason="allow-defer match"; type=Module
+        elif (( fan_in >= MIN_FAN_IN )); then
+            required=true; reason=""; type=Subsystem
+        else
+            required=false; reason="fan_in $fan_in < floor $MIN_FAN_IN"; type=Module
+        fi
+        add_concept "$name" systems "$type" "$name" "$fan_in" "$required" "$reason"
+    done < <(echo "$arch" | jq -r '.packages[]? | [.name, (.fan_in // 0)] | @tsv')
+
+    # Entry points → entrypoints/<name>.md (always required)
+    while IFS= read -r name; do
+        [[ -z "$name" ]] && continue
+        if is_deferred_name "$name"; then
+            add_concept "$name" entrypoints Entrypoint "$name" 0 false "allow-defer match"
+        else
+            add_concept "$name" entrypoints Entrypoint "$name" 0 true ""
+        fi
+    done < <(echo "$arch" | jq -r '
+        (.entry_points // [])[]? | if type=="object" then (.name // .path // empty) else . end' \
+        | sort -u)
+}
+
+# graph-arch.sh wrapper that tolerates the "unavailable" sentinel.
+scripts_graph_arch() {
+    local out
+    out="$("$SCRIPT_DIR/graph-arch.sh" --repo "$REPO" 2>/dev/null || true)"
+    [[ -n "$out" ]] || return 1
+    echo "$out" | jq -e '.source == "unavailable"' >/dev/null 2>&1 && return 1
+    printf '%s' "$out"
+}
+
+# --- 3. Heuristic fallback ---
+plan_from_heuristic() {
+    SOURCE="heuristic"
+    DEGRADED="true"
+    local scope_dir="$REPO/$SCOPE"
+    [[ -d "$scope_dir" ]] || scope_dir="$REPO"
+    local d name
+    while IFS= read -r d; do
+        name="$(basename "$d")"
+        case "$name" in
+            test|tests|qa|tools|vendor|node_modules|.git|dist|build|target) continue;;
+            .*) continue;;
+        esac
+        # Only dirs that actually contain source-ish files.
+        if find "$d" -maxdepth 2 -type f \
+            \( -name '*.go' -o -name '*.py' -o -name '*.js' -o -name '*.ts' \
+               -o -name '*.rs' -o -name '*.java' -o -name '*.rb' -o -name '*.sh' \
+               -o -name '*.c' -o -name '*.cpp' -o -name '*.kt' \) 2>/dev/null \
+            | head -1 | grep -q .; then
+            if is_deferred_name "$name"; then
+                add_concept "$name" systems Module "$name" 0 false "allow-defer match"
+            else
+                add_concept "$name" systems Module "$name" 0 true ""
+            fi
+        fi
+    done < <(find "$scope_dir" -mindepth 1 -maxdepth 1 -type d | sort)
+}
+
+# --- Drive discovery in priority order ---
+if [[ -n "$MANIFEST" ]]; then
+    [[ -f "$MANIFEST" ]] || { echo "ERROR: --manifest not found: $MANIFEST" >&2; exit 1; }
+    plan_from_manifest
+elif plan_from_graph; then
+    :
+else
+    plan_from_heuristic
+fi
+
+if [[ ${#E_ID[@]} -eq 0 ]]; then
+    echo "ERROR: no expected concepts derived (graph + manifest unavailable, heuristic empty)" >&2
+    exit 2
+fi
+
+# Required-first, then deferred; stable within group (topological-ish: high fan-in
+# subsystems first so forward cross-links resolve during generation).
+emit_plan() {
+    local n=${#E_ID[@]} i
+    # Build sortable index lines: <req_rank>\t<fanin_desc>\t<idx>
+    local order=()
+    for ((i=0; i<n; i++)); do
+        local rank=1; [[ "${E_REQ[$i]}" == "true" ]] && rank=0
+        order+=("$(printf '%d\t%010d\t%d' "$rank" "$(( 9999999999 - ${E_FANIN[$i]:-0} ))" "$i")")
+    done
+    local sorted; sorted="$(printf '%s\n' "${order[@]}" | sort)"
+
+    local req=0 def=0
+    for ((i=0; i<n; i++)); do
+        [[ "${E_REQ[$i]}" == "true" ]] && req=$((req+1)) || def=$((def+1))
+    done
+
+    {
+        printf '{\n'
+        printf '  "version": 1,\n'
+        printf '  "repo": "%s",\n' "$(json_escape "$REPO")"
+        printf '  "scope": "%s",\n' "$(json_escape "$SCOPE")"
+        printf '  "source": "%s",\n' "$SOURCE"
+        printf '  "degraded": %s,\n' "$DEGRADED"
+        printf '  "min_fan_in": %d,\n' "$MIN_FAN_IN"
+        # generated_order
+        printf '  "generated_order": ['
+        local first=1
+        while IFS=$'\t' read -r _ _ idx; do
+            [[ -z "$idx" ]] && continue
+            [[ $first -eq 1 ]] && first=0 || printf ','
+            printf '"%s"' "$(json_escape "${E_ID[$idx]}")"
+        done <<< "$sorted"
+        printf '],\n'
+        # expected[]
+        printf '  "expected": [\n'
+        first=1
+        while IFS=$'\t' read -r _ _ idx; do
+            [[ -z "$idx" ]] && continue
+            [[ $first -eq 1 ]] && first=0 || printf ',\n'
+            local reason_json="null"
+            [[ -n "${E_REASON[$idx]}" ]] && reason_json="\"$(json_escape "${E_REASON[$idx]}")\""
+            printf '    {"concept_id":"%s","type":"%s","resource":"%s","fan_in":%d,"required":%s,"reason_if_deferred":%s}' \
+                "$(json_escape "${E_ID[$idx]}")" \
+                "$(json_escape "${E_TYPE[$idx]}")" \
+                "$(json_escape "${E_RES[$idx]}")" \
+                "${E_FANIN[$idx]:-0}" \
+                "${E_REQ[$idx]}" \
+                "$reason_json"
+        done <<< "$sorted"
+        printf '\n  ],\n'
+        printf '  "counts": {"expected_total": %d, "required": %d, "deferred": %d}\n' "$n" "$req" "$def"
+        printf '}\n'
+    }
+}
+
+PLAN_JSON="$(emit_plan)"
+
+# Validate our own output parses before writing.
+if command -v jq >/dev/null 2>&1; then
+    echo "$PLAN_JSON" | jq -e '.expected' >/dev/null 2>&1 \
+        || { echo "ERROR: generated plan is not valid JSON (internal error)" >&2; exit 1; }
+fi
+
+if [[ -n "$OUT" ]]; then
+    mkdir -p "$(dirname "$OUT")"
+    printf '%s' "$PLAN_JSON" > "$OUT"
+    echo "concept plan → $OUT (source=$SOURCE, $(echo "$PLAN_JSON" | jq -r '.counts.required') required, $(echo "$PLAN_JSON" | jq -r '.counts.deferred') deferred)" >&2
+    [[ $JSON -eq 1 ]] && printf '%s' "$PLAN_JSON"
+else
+    printf '%s' "$PLAN_JSON"
+fi
+exit 0

package/scripts/tools/okf-render-views.sh

@@ -25,6 +25,8 @@ BUNDLE=""
 ARCH_OUT=""
 WEB_OUT=""
 CMAP_INTO=()
+COVERAGE_REPORT=""
+VALIDATED_AT=""
 
 usage() {
     cat <<'EOF'
@@ -40,6 +42,10 @@ Flags:
   --web FILE               Write a self-contained, offline HTML viewer (single file:
                            all pages inlined, built-in markdown renderer, sidebar +
                            search). Double-click to open — no server, no internet.
+  --coverage-report FILE   okf-coverage-check.sh JSON; its mapped/required/pct and
+                           validity are rendered into the architecture.md banner.
+  --validated-at STR       Timestamp string shown in the banner (caller supplies it;
+                           this tool has no clock dependency).
   --help                   Show this help.
 
 Requires jq (already a Draft prereq) for --web. Exit 0 ok, 1 error, 2 bundle not found.
@@ -51,6 +57,8 @@ while [[ $# -gt 0 ]]; do
         --arch-out) ARCH_OUT="$2"; shift 2;;
         --concept-map-into) CMAP_INTO+=("$2"); shift 2;;
         --web) WEB_OUT="$2"; shift 2;;
+        --coverage-report) COVERAGE_REPORT="$2"; shift 2;;
+        --validated-at) VALIDATED_AT="$2"; shift 2;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
         *)
@@ -92,6 +100,27 @@ strip_frontmatter() {
     ' "$1"
 }
 
+# Coverage-honesty banner, sourced from okf-coverage-check.sh's JSON report.
+# Silent when no report is supplied (keeps the view backward-compatible).
+emit_coverage_banner() {
+    [[ -n "$COVERAGE_REPORT" && -f "$COVERAGE_REPORT" ]] || return 0
+    command -v jq >/dev/null 2>&1 || return 0
+    local valid mapped required pct
+    valid="$(jq -r '.valid // empty' "$COVERAGE_REPORT" 2>/dev/null || true)"
+    mapped="$(jq -r '.mapped // empty' "$COVERAGE_REPORT" 2>/dev/null || true)"
+    required="$(jq -r '.required // empty' "$COVERAGE_REPORT" 2>/dev/null || true)"
+    pct="$(jq -r '.coverage_pct // empty' "$COVERAGE_REPORT" 2>/dev/null || true)"
+    [[ -n "$mapped" && -n "$required" ]] || return 0
+    if [[ "$valid" == "true" ]]; then
+        echo "> **Coverage:** ${mapped}/${required} required components (${pct}%)."
+    else
+        echo "> **⚠ INCOMPLETE — do not use for RCA:** only ${mapped}/${required} required"
+        echo "> components (${pct}%) are documented. Re-run \`/draft:init\` to fill the gaps."
+    fi
+    [[ -n "$VALIDATED_AT" ]] && echo "> Validated: ${VALIDATED_AT} — $([[ "$valid" == "true" ]] && echo PASS || echo FAIL)."
+    echo ""
+}
+
 # --- 1. Render architecture.md ---
 render_architecture() {
     local out="$1"
@@ -109,6 +138,7 @@ render_architecture() {
         echo "> The bundle is the source of truth; this is the single-document linear"
         echo "> view for onboarding. Regenerate with \`okf-render-views.sh\`."
         echo ""
+        emit_coverage_banner
         echo "## Contents"
         echo ""
         # TOC from page titles.