@drafthq/draft 3.4.0 → 3.5.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "3.4.0",
+      "version": "3.5.0",
       "author": {
         "name": "mayurpise"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "author": {
     "name": "mayurpise"
   },

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "draft",
   "displayName": "Draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "skills": "./skills/",
   "agents": "./core/agents/",
   "author": {

package/core/templates/okf/concept.md

@@ -52,3 +52,12 @@ so a focused task knows exactly which source files to open.
 ## See also
 
 - [Related concept](../systems/other.md)
+
+<!-- okf:concept-template v1
+A stub or redirect-only page (e.g. "see architecture.md", an unreplaced
+{PLACEHOLDER} token, or a body below the per-type minimum) FAILS
+okf-validate-quality.sh and therefore does NOT satisfy okf-coverage-check.sh —
+the bundle will not be promoted. Diagram types (Subsystem/Module/Feature/
+Entrypoint) require ≥1 valid Mermaid block and ≥2 x-grounded-paths.
+-->
+

package/integrations/agents/AGENTS.md

@@ -336,6 +336,16 @@ DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
 
 The tier-gated default rests on **maintainability/readability** (one navigable concept per file, cleaner PRs, a generated `architecture.md` preserved for linear onboarding) — not on the A/B benchmark, which was accuracy-parity (`docs/audit/okf-benchmark.md`). `monolith` is **retained, not retired**: it is the tier-1/2 default, the A/B baseline, and the fallback. If `DRAFT_INIT_MODE` is unset, do not commit to a mode until **Step 1.4.5** has computed the tier.
 
+**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) — no required package with `fan_in ≥ floor` is **MISSING**.
+5. 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.
+
 ### Route Explicit Modes Before Initialization
 
 If the user explicitly invoked a specialist mode, route directly:
@@ -3291,7 +3301,10 @@ esac
 Everything else in `draft init` (5-phase analysis, graph snapshot, `.state/`
 hashing, scope detection, atomic staging) is **reused unchanged**. This mode adds
 a decomposition + serialization stage. It introduces **no new LLM analysis
-engine** and exactly **one** new deterministic helper, `okf-validate.sh`.
+engine**; its deterministic helpers are `okf-plan-concepts.sh` (expected-concept
+set), `okf-validate.sh` (structure), `okf-validate-quality.sh` (per-type
+anti-stub), `okf-coverage-check.sh` (completeness), and `okf-validate-all.sh`
+(the single promotion gate that runs all three), plus `okf-render-views.sh`.
 
 ## Target layout
 
@@ -3384,25 +3397,64 @@ Derive concepts from the graph, not by hand:
 
 ```
 1. Survey        → existing draft init 5-phase + graph snapshot (graph-snapshot.sh)
-2. Plan          → derive the concept list (above) from graph clusters +
-                   entrypoints + features. Topo-sort by dependency so pages that
-                   others link to (overview, core subsystems) generate FIRST —
-                   forward cross-links resolve.
-3. Generate      → per concept, pull grounding from the graph and write the page:
+2. Plan          → DETERMINISTIC. okf-plan-concepts.sh derives the expected-concept
+                   set from the graph (every package with fan_in ≥ floor → required
+                   Subsystem/Module; entrypoints → required; below-floor / allow-defer
+                   → deferred with a reason) and 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
+                   cannot be silently dropped. 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), wiki/log.md  (see M4).
-5. Validate      → okf-validate.sh draft/wiki \
-                     --path-index draft/.state/path-to-concept.json
-                   FAIL the build (do not atomic-rename) on any dangle, missing
-                   field, bad type, or path-index gap.
-6. Emit          → mv draft.tmp/ draft/ ; update .state/.
+                   (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),
+                   okf-validate-quality.sh (per-type anti-stub / depth / 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" } }
 ```
 
+### 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
@@ -3456,17 +3508,22 @@ section `index.md` tables are the injection slots for the routing tables.
 `draft init refresh` under `okf` mode:
 
 ```
-1. Diff hashes.json vs working tree     → changed source paths
-2. path-to-concept.json                 → affected concept pages
-3. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
-4. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
-5. Re-validate: okf-validate.sh on the bundle + path-index (cross-links touching
-   changed concepts must still resolve)
-6. Append log.md; update hashes.json + path-to-concept.json
+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
 ```
 
 A 1-file change regenerates only the concept(s) that file grounds. Unchanged
-concepts are byte-identical across runs.
+concepts are byte-identical across runs. The full gate still runs, so refresh
+cannot promote a bundle that a newly-added module left incomplete.
 
 ## Backward compatibility (§9)
 
@@ -22687,6 +22744,15 @@ so a focused task knows exactly which source files to open.
 
 - [Related concept](../systems/other.md)
 
+<!-- okf:concept-template v1
+A stub or redirect-only page (e.g. "see architecture.md", an unreplaced
+{PLACEHOLDER} token, or a body below the per-type minimum) FAILS
+okf-validate-quality.sh and therefore does NOT satisfy okf-coverage-check.sh —
+the bundle will not be promoted. Diagram types (Subsystem/Module/Feature/
+Entrypoint) require ≥1 valid Mermaid block and ≥2 x-grounded-paths.
+-->
+
+
 </core-file>
 
 ---

package/integrations/copilot/.github/copilot-instructions.md

@@ -336,6 +336,16 @@ DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
 
 The tier-gated default rests on **maintainability/readability** (one navigable concept per file, cleaner PRs, a generated `architecture.md` preserved for linear onboarding) — not on the A/B benchmark, which was accuracy-parity (`docs/audit/okf-benchmark.md`). `monolith` is **retained, not retired**: it is the tier-1/2 default, the A/B baseline, and the fallback. If `DRAFT_INIT_MODE` is unset, do not commit to a mode until **Step 1.4.5** has computed the tier.
 
+**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) — no required package with `fan_in ≥ floor` is **MISSING**.
+5. 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.
+
 ### Route Explicit Modes Before Initialization
 
 If the user explicitly invoked a specialist mode, route directly:
@@ -3291,7 +3301,10 @@ esac
 Everything else in `draft init` (5-phase analysis, graph snapshot, `.state/`
 hashing, scope detection, atomic staging) is **reused unchanged**. This mode adds
 a decomposition + serialization stage. It introduces **no new LLM analysis
-engine** and exactly **one** new deterministic helper, `okf-validate.sh`.
+engine**; its deterministic helpers are `okf-plan-concepts.sh` (expected-concept
+set), `okf-validate.sh` (structure), `okf-validate-quality.sh` (per-type
+anti-stub), `okf-coverage-check.sh` (completeness), and `okf-validate-all.sh`
+(the single promotion gate that runs all three), plus `okf-render-views.sh`.
 
 ## Target layout
 
@@ -3384,25 +3397,64 @@ Derive concepts from the graph, not by hand:
 
 ```
 1. Survey        → existing draft init 5-phase + graph snapshot (graph-snapshot.sh)
-2. Plan          → derive the concept list (above) from graph clusters +
-                   entrypoints + features. Topo-sort by dependency so pages that
-                   others link to (overview, core subsystems) generate FIRST —
-                   forward cross-links resolve.
-3. Generate      → per concept, pull grounding from the graph and write the page:
+2. Plan          → DETERMINISTIC. okf-plan-concepts.sh derives the expected-concept
+                   set from the graph (every package with fan_in ≥ floor → required
+                   Subsystem/Module; entrypoints → required; below-floor / allow-defer
+                   → deferred with a reason) and 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
+                   cannot be silently dropped. 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), wiki/log.md  (see M4).
-5. Validate      → okf-validate.sh draft/wiki \
-                     --path-index draft/.state/path-to-concept.json
-                   FAIL the build (do not atomic-rename) on any dangle, missing
-                   field, bad type, or path-index gap.
-6. Emit          → mv draft.tmp/ draft/ ; update .state/.
+                   (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),
+                   okf-validate-quality.sh (per-type anti-stub / depth / 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" } }
 ```
 
+### 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
@@ -3456,17 +3508,22 @@ section `index.md` tables are the injection slots for the routing tables.
 `draft init refresh` under `okf` mode:
 
 ```
-1. Diff hashes.json vs working tree     → changed source paths
-2. path-to-concept.json                 → affected concept pages
-3. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
-4. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
-5. Re-validate: okf-validate.sh on the bundle + path-index (cross-links touching
-   changed concepts must still resolve)
-6. Append log.md; update hashes.json + path-to-concept.json
+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
 ```
 
 A 1-file change regenerates only the concept(s) that file grounds. Unchanged
-concepts are byte-identical across runs.
+concepts are byte-identical across runs. The full gate still runs, so refresh
+cannot promote a bundle that a newly-added module left incomplete.
 
 ## Backward compatibility (§9)
 
@@ -22687,6 +22744,15 @@ so a focused task knows exactly which source files to open.
 
 - [Related concept](../systems/other.md)
 
+<!-- okf:concept-template v1
+A stub or redirect-only page (e.g. "see architecture.md", an unreplaced
+{PLACEHOLDER} token, or a body below the per-type minimum) FAILS
+okf-validate-quality.sh and therefore does NOT satisfy okf-coverage-check.sh —
+the bundle will not be promoted. Diagram types (Subsystem/Module/Feature/
+Entrypoint) require ≥1 valid Mermaid block and ≥2 x-grounded-paths.
+-->
+
+
 </core-file>
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Context-Driven Development for AI coding agents — install Draft into Claude Code, Cursor, Codex, or opencode.",
   "bin": {
     "draft": "cli/bin/draft.js"

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