@drafthq/draft 3.5.2 → 3.5.3

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.5.2",
+      "version": "3.5.3",
       "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.5.2",
+  "version": "3.5.3",
   "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.5.2",
+  "version": "3.5.3",
   "skills": "./skills/",
   "agents": "./core/agents/",
   "author": {

package/core/templates/okf/index.md

@@ -1,17 +1,13 @@
 ---
-type: Subsystem
-title: "{PROJECT_NAME} — Wiki"
-description: >
-  Root index of the project wiki. Start here, then route into
-  overview/, systems/, features/, reference/, or entrypoints/ via the
-  Concept Map. Open a concept only when its description matches the task.
-resource: .
-tags: [index]
-timestamp: "{ISO_TIMESTAMP}"
 okf_version: "0.1"
-okf_types_version: "0.1"
 ---
 
+<!-- OKF §6/§11: an index file carries NO concept frontmatter; the root index.md
+     may declare ONLY `okf_version`. The frozen concept-`type` vocabulary version
+     is tracked here in the body (not in frontmatter) so bumping it stays visible
+     without violating the index-frontmatter rule.
+     okf-types-version: 0.1 -->
+
 # {PROJECT_NAME} — Wiki
 
 > Project wiki. One concept per file; cross-links form the graph. The

package/core/templates/okf/section-index.md

@@ -1,14 +1,5 @@
----
-type: Subsystem
-title: "{SECTION_TITLE}"
-description: >
-  Section index. Lists every concept in this section with its one-line
-  routing description so an agent can pick the right page without opening
-  each one. {SECTION_PURPOSE}
-resource: .
-tags: [index]
-timestamp: "{ISO_TIMESTAMP}"
----
+<!-- OKF §6: an index file contains NO frontmatter. This page is a reserved
+     navigation index, not a concept — its Concepts table is tool-generated. -->
 
 # {SECTION_TITLE}
 

package/integrations/agents/AGENTS.md

@@ -3353,7 +3353,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 |
 |------|---------|------|
@@ -3379,6 +3380,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:
@@ -22653,19 +22664,15 @@ List down alerting thresholds on those metrics:
 <core-file path="core/templates/okf/index.md">
 
 ---
-type: Subsystem
-title: "{PROJECT_NAME} — Wiki"
-description: >
-  Root index of the project wiki. Start here, then route into
-  overview/, systems/, features/, reference/, or entrypoints/ via the
-  Concept Map. Open a concept only when its description matches the task.
-resource: .
-tags: [index]
-timestamp: "{ISO_TIMESTAMP}"
 okf_version: "0.1"
-okf_types_version: "0.1"
 ---
 
+<!-- OKF §6/§11: an index file carries NO concept frontmatter; the root index.md
+     may declare ONLY `okf_version`. The frozen concept-`type` vocabulary version
+     is tracked here in the body (not in frontmatter) so bumping it stays visible
+     without violating the index-frontmatter rule.
+     okf-types-version: 0.1 -->
+
 # {PROJECT_NAME} — Wiki
 
 > Project wiki. One concept per file; cross-links form the graph. The
@@ -22773,17 +22780,8 @@ Entrypoint) require ≥1 valid Mermaid block and ≥2 x-grounded-paths.
 
 <core-file path="core/templates/okf/section-index.md">
 
----
-type: Subsystem
-title: "{SECTION_TITLE}"
-description: >
-  Section index. Lists every concept in this section with its one-line
-  routing description so an agent can pick the right page without opening
-  each one. {SECTION_PURPOSE}
-resource: .
-tags: [index]
-timestamp: "{ISO_TIMESTAMP}"
----
+<!-- OKF §6: an index file contains NO frontmatter. This page is a reserved
+     navigation index, not a concept — its Concepts table is tool-generated. -->
 
 # {SECTION_TITLE}
 

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

@@ -3353,7 +3353,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 |
 |------|---------|------|
@@ -3379,6 +3380,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:
@@ -22653,19 +22664,15 @@ List down alerting thresholds on those metrics:
 <core-file path="core/templates/okf/index.md">
 
 ---
-type: Subsystem
-title: "{PROJECT_NAME} — Wiki"
-description: >
-  Root index of the project wiki. Start here, then route into
-  overview/, systems/, features/, reference/, or entrypoints/ via the
-  Concept Map. Open a concept only when its description matches the task.
-resource: .
-tags: [index]
-timestamp: "{ISO_TIMESTAMP}"
 okf_version: "0.1"
-okf_types_version: "0.1"
 ---
 
+<!-- OKF §6/§11: an index file carries NO concept frontmatter; the root index.md
+     may declare ONLY `okf_version`. The frozen concept-`type` vocabulary version
+     is tracked here in the body (not in frontmatter) so bumping it stays visible
+     without violating the index-frontmatter rule.
+     okf-types-version: 0.1 -->
+
 # {PROJECT_NAME} — Wiki
 
 > Project wiki. One concept per file; cross-links form the graph. The
@@ -22773,17 +22780,8 @@ Entrypoint) require ≥1 valid Mermaid block and ≥2 x-grounded-paths.
 
 <core-file path="core/templates/okf/section-index.md">
 
----
-type: Subsystem
-title: "{SECTION_TITLE}"
-description: >
-  Section index. Lists every concept in this section with its one-line
-  routing description so an agent can pick the right page without opening
-  each one. {SECTION_PURPOSE}
-resource: .
-tags: [index]
-timestamp: "{ISO_TIMESTAMP}"
----
+<!-- OKF §6: an index file contains NO frontmatter. This page is a reserved
+     navigation index, not a concept — its Concepts table is tool-generated. -->
 
 # {SECTION_TITLE}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.5.2",
+  "version": "3.5.3",
   "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/tools/okf-coverage-check.sh

@@ -122,6 +122,17 @@ write_coverage_page() {
     mkdir -p "$BUNDLE/systems"
     local tmp; tmp="$(mktemp)"
     {
+        # OKF §9.1/§9.2: every non-reserved .md needs parseable frontmatter with a
+        # non-empty `type`. coverage.md is tool-generated and not a code concept, so
+        # it uses a descriptive (non-frozen) type; okf-validate.sh exempts it from the
+        # frozen-vocab check via is_meta_page (basename + the marker below).
+        echo "---"
+        echo "type: Report"
+        echo "title: Component Coverage"
+        echo "description: Coverage of required components by wiki pages — which are documented, stubbed, or missing."
+        echo "resource: ."
+        echo "---"
+        echo ""
         echo "<!-- okf:coverage-generated -->"
         echo "# Component Coverage"
         echo ""
@@ -130,14 +141,21 @@ write_coverage_page() {
         echo ""
         echo "| Component | Wiki page | Status | Fan-in |"
         echo "|-----------|-----------|--------|--------|"
-        local cid status fanin
+        local cid status fanin link
         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")"
+                    # coverage.md lives in systems/; link relative to it. Concepts in
+                    # other sections (entrypoints/, reference/, …) need a ../ prefix,
+                    # otherwise the link dangles and fails structure validation.
+                    case "$cid" in
+                        systems/*) link="${cid#systems/}";;
+                        *)         link="../$cid";;
+                    esac
                     if [[ "$bl" -ge "$MIN_STUB_LINES" ]]; then
-                        echo "| \`${cid%.md}\` | [page](${cid#systems/}) | Full | ${fanin} |"
+                        echo "| \`${cid%.md}\` | [page](${link}) | Full | ${fanin} |"
                     else
                         echo "| \`${cid%.md}\` | ${cid} | **STUB (${bl} lines)** | ${fanin} |"
                     fi

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

@@ -109,6 +109,17 @@ strip_frontmatter() {
     ' "$1"
 }
 
+# Human-facing title for a page: frontmatter `title`, else the first `# H1` in the
+# body, else the bundle-relative path. Index files are frontmatter-less under OKF
+# §6, so the H1 fallback keeps the rendered TOC / nav readable.
+page_title() {
+    local t; t="$(get_yaml_field "$1" title)"
+    if [[ -z "$t" ]]; then
+        t="$(strip_frontmatter "$1" | grep -m1 -E '^#[[:space:]]+' | sed -E 's/^#[[:space:]]+//')"
+    fi
+    printf '%s' "$t"
+}
+
 # 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() {
@@ -159,7 +170,7 @@ render_architecture() {
                 echo "- **${sec}/**"
                 last_sec="$sec"
             fi
-            title="$(get_yaml_field "$BUNDLE/$rel" title)"
+            title="$(page_title "$BUNDLE/$rel")"
             [[ -n "$title" ]] || title="$rel"
             local anchor; anchor="$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-')"
             anchor="${anchor#-}"; anchor="${anchor%-}"
@@ -183,10 +194,14 @@ render_architecture() {
 build_concept_map() {
     echo "| Concept | Type | Open it when… |"
     echo "|---------|------|---------------|"
-    local rel type title desc
+    local rel base type title desc
     while IFS= read -r -d '' page; do
         rel="${page#"$BUNDLE/"}"
-        [[ "$(basename "$rel")" == "index.md" ]] && continue
+        base="$(basename "$rel")"
+        # Meta pages are not routable concepts (reserved index/log + the typed,
+        # tool-generated coverage page).
+        [[ "$base" == "index.md" || "$base" == "log.md" || "$base" == "coverage.md" ]] && continue
+        grep -q '<!-- okf:coverage-generated -->' "$page" 2>/dev/null && continue
         type="$(get_yaml_field "$page" type)"
         [[ -n "$type" ]] || continue
         title="$(get_yaml_field "$page" title)"
@@ -330,7 +345,7 @@ HTML_HEAD
         while IFS= read -r -d '' page; do
             local rel title type
             rel="${page#"$BUNDLE/"}"
-            title="$(get_yaml_field "$page" title)"; [[ -n "$title" ]] || title="$rel"
+            title="$(page_title "$page")"; [[ -n "$title" ]] || title="$rel"
             type="$(get_yaml_field "$page" type)"
             printf '%s: {"title": %s, "type": %s, "md": %s},\n' \
                 "$(jq -Rn --arg v "$rel" '$v')" \

package/scripts/tools/okf-validate.sh

@@ -135,18 +135,25 @@ while IFS= read -r -d '' page; do
     rel="${page#"$BUNDLE/"}"
     base="$(basename "$rel")"
 
+    # Meta pages are NOT concepts: reserved index.md/log.md (OKF §6/§7) carry no
+    # concept frontmatter, and the tool-generated coverage page uses a descriptive
+    # (non-frozen) type. Exempt them from the frozen-vocab + required-field + body
+    # checks, and don't count them as concepts. The template-token (§3b) and
+    # cross-link (§4) scans below still cover them.
+    if is_meta_page "$base" "$page"; then
+        continue
+    fi
+
     type_val="$(get_yaml_field "$page" "type")"
 
     # Empty / placeholder pages: a non-meta page with no type (or no body) slips
     # past every downstream check (quality + coverage both key on `type`). Catch
     # it here so a blank or stub file can never ship.
     if [[ -z "$type_val" ]]; then
-        if ! is_meta_page "$base" "$page"; then
-            if [[ "$(nonblank_body_lines "$page")" -eq 0 ]]; then
-                add_error "$rel: empty page (no frontmatter type, no body) — every wiki page must be a real concept"
-            else
-                add_error "$rel: untyped page (missing frontmatter 'type:') — not a valid concept page"
-            fi
+        if [[ "$(nonblank_body_lines "$page")" -eq 0 ]]; then
+            add_error "$rel: empty page (no frontmatter type, no body) — every wiki page must be a real concept"
+        else
+            add_error "$rel: untyped page (missing frontmatter 'type:') — not a valid concept page"
         fi
         continue
     fi

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: