feat(okf): add OKF v0.1 conformance checker; fix index.md to spec

Validated the OKF work against the authoritative spec
(github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md §9).
This surfaced a real bug: index.md is a RESERVED file and must contain no
frontmatter (§6) — except the bundle-root index.md may declare only okf_version
(§11). The emitters were writing concept-style `type: Repository` frontmatter
into index.md, which is non-conformant. Fixed.

- add scripts/tools/okf-check.sh — faithful §9 validator: every non-reserved .md
  has parseable frontmatter (§9.1) with non-empty `type` (§9.2); reserved
  index.md/log.md follow §6/§7 (no frontmatter except root okf_version; ISO-8601
  log date headings). --quiet for summary-only. tests/test-tools-okf-check.sh.
- fix okf-emit.sh + okf-bundle.sh index.md: reserved-file conformant (no
  frontmatter / root okf_version only; §6 bullet body). Remove okf-bundle --check
  (okf-check.sh is the single source of truth).
- add `type:` to track concept templates (spec/plan/hld/lld/discovery/rca) and
  inline tracks.md (TrackIndex) so a freshly-init'd draft/ is fully conformant.
- wire `okf-check.sh --dir draft` (advisory) into /draft:init and /draft:index.
- update affected tests (emit/bundle/snapshot) for the conformant index.md format;
  each now asserts the emitted bundle passes okf-check. regenerate integrations.

No browser required — conformance is purely structural; the OKF visualizer is
optional eyeballing only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mayurpise

Makefile

@@ -32,6 +32,7 @@ TEST_SCRIPTS = \
 	./tests/test-tools-graph-snapshot.sh \
 	./tests/test-tools-okf-emit.sh \
 	./tests/test-tools-okf-bundle.sh \
+	./tests/test-tools-okf-check.sh \
 	./tests/test-tools-graph-impact.sh \
 	./tests/test-tools-graph-callers.sh \
 	./tests/test-tools-validate-frontmatter.sh \

core/templates/discovery.md

@@ -1,4 +1,5 @@
 ---
+type: Discovery
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"

core/templates/hld.md

@@ -1,4 +1,5 @@
 ---
+type: HLD
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"

core/templates/lld.md

@@ -1,4 +1,5 @@
 ---
+type: LLD
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"

core/templates/plan.md

@@ -1,4 +1,5 @@
 ---
+type: Plan
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"

core/templates/rca.md

@@ -1,4 +1,5 @@
 ---
+type: RCA
 project: "{PROJECT_NAME}"
 track_id: "{TRACK_ID}"
 jira_ticket: "{JIRA_KEY}"

core/templates/spec.md

@@ -1,4 +1,5 @@
 ---
+type: Spec
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"

integrations/agents/AGENTS.md

@@ -1709,6 +1709,7 @@ Create `draft/tracks.md` with metadata header:
 
 ```markdown
 ---
+type: TrackIndex
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -1759,14 +1760,17 @@ to (re)generate the Open Knowledge Format root index so the whole `draft/` tree
 a portable, vendor-neutral OKF bundle. This is the default — no flag required.
 
 ```bash
-scripts/tools/okf-bundle.sh --dir draft        # writes draft/index.md (type: Repository)
-scripts/tools/okf-bundle.sh --dir draft --check  # verifies every concept declares type:
+scripts/tools/okf-bundle.sh --dir draft   # writes the bundle-root draft/index.md
+scripts/tools/okf-check.sh  --dir draft   # OKF v0.1 conformance (advisory, non-fatal)
 ```
 
 `okf-bundle.sh` links every concept file present (`.ai-profile.md`, `.ai-context.md`,
 `architecture.md`, `product.md`, `tech-stack.md`, `workflow.md`, `guardrails.md`), the
-tracks, and the graph sub-bundle (`graph/okf/`). Concept `type:` frontmatter comes
-from the templates; `--check` is a conformance gate, not a hard failure of init.
+tracks, and the graph sub-bundle (`graph/okf/`). Concept `type:` frontmatter comes from
+the templates; `okf-check.sh` validates §9 conformance (frontmatter + `type` on every
+concept; reserved `index.md`/`log.md` structure). It is advisory — report the result,
+do not fail init. Note: operational reports later written into `draft/` (e.g.
+`deep-review-report.md`) are not OKF concepts and will be flagged.
 
 **Finalize run memory:** Update `draft/.state/run-memory.json`:
 - `status`: `"completed"`
@@ -3972,8 +3976,8 @@ Format root index so the root `draft/` tree is a portable OKF bundle. This is th
 default; the index links `service-index.md` and every other concept present.
 
 ```bash
-scripts/tools/okf-bundle.sh --dir draft        # writes draft/index.md (type: Repository)
-scripts/tools/okf-bundle.sh --dir draft --check  # conformance gate (non-fatal)
+scripts/tools/okf-bundle.sh --dir draft   # writes the bundle-root draft/index.md
+scripts/tools/okf-check.sh  --dir draft   # OKF v0.1 conformance (advisory, non-fatal)
 ```
 
 ## Step 9: Completion Report
@@ -20724,6 +20728,7 @@ If task exceeds 5 iterations:
 <core-file path="core/templates/spec.md">
 
 ---
+type: Spec
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -20898,6 +20903,7 @@ approvers:
 <core-file path="core/templates/plan.md">
 
 ---
+type: Plan
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -21756,6 +21762,7 @@ Org-wide conventions:
 <core-file path="core/templates/rca.md">
 
 ---
+type: RCA
 project: "{PROJECT_NAME}"
 track_id: "{TRACK_ID}"
 jira_ticket: "{JIRA_KEY}"
@@ -21930,6 +21937,7 @@ git-ignored at the track level. No HTML or PDF templates ship here.
 <core-file path="core/templates/discovery.md">
 
 ---
+type: Discovery
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -22018,6 +22026,7 @@ without line numbers are exempt from drift checks (they document
 <core-file path="core/templates/hld.md">
 
 ---
+type: HLD
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -22354,6 +22363,7 @@ Result stored in `metadata.json:pre_deploy_status`
 <core-file path="core/templates/lld.md">
 
 ---
+type: LLD
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"

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

@@ -1709,6 +1709,7 @@ Create `draft/tracks.md` with metadata header:
 
 ```markdown
 ---
+type: TrackIndex
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -1759,14 +1760,17 @@ to (re)generate the Open Knowledge Format root index so the whole `draft/` tree
 a portable, vendor-neutral OKF bundle. This is the default — no flag required.
 
 ```bash
-scripts/tools/okf-bundle.sh --dir draft        # writes draft/index.md (type: Repository)
-scripts/tools/okf-bundle.sh --dir draft --check  # verifies every concept declares type:
+scripts/tools/okf-bundle.sh --dir draft   # writes the bundle-root draft/index.md
+scripts/tools/okf-check.sh  --dir draft   # OKF v0.1 conformance (advisory, non-fatal)
 ```
 
 `okf-bundle.sh` links every concept file present (`.ai-profile.md`, `.ai-context.md`,
 `architecture.md`, `product.md`, `tech-stack.md`, `workflow.md`, `guardrails.md`), the
-tracks, and the graph sub-bundle (`graph/okf/`). Concept `type:` frontmatter comes
-from the templates; `--check` is a conformance gate, not a hard failure of init.
+tracks, and the graph sub-bundle (`graph/okf/`). Concept `type:` frontmatter comes from
+the templates; `okf-check.sh` validates §9 conformance (frontmatter + `type` on every
+concept; reserved `index.md`/`log.md` structure). It is advisory — report the result,
+do not fail init. Note: operational reports later written into `draft/` (e.g.
+`deep-review-report.md`) are not OKF concepts and will be flagged.
 
 **Finalize run memory:** Update `draft/.state/run-memory.json`:
 - `status`: `"completed"`
@@ -3972,8 +3976,8 @@ Format root index so the root `draft/` tree is a portable OKF bundle. This is th
 default; the index links `service-index.md` and every other concept present.
 
 ```bash
-scripts/tools/okf-bundle.sh --dir draft        # writes draft/index.md (type: Repository)
-scripts/tools/okf-bundle.sh --dir draft --check  # conformance gate (non-fatal)
+scripts/tools/okf-bundle.sh --dir draft   # writes the bundle-root draft/index.md
+scripts/tools/okf-check.sh  --dir draft   # OKF v0.1 conformance (advisory, non-fatal)
 ```
 
 ## Step 9: Completion Report
@@ -20724,6 +20728,7 @@ If task exceeds 5 iterations:
 <core-file path="core/templates/spec.md">
 
 ---
+type: Spec
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -20898,6 +20903,7 @@ approvers:
 <core-file path="core/templates/plan.md">
 
 ---
+type: Plan
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -21756,6 +21762,7 @@ Org-wide conventions:
 <core-file path="core/templates/rca.md">
 
 ---
+type: RCA
 project: "{PROJECT_NAME}"
 track_id: "{TRACK_ID}"
 jira_ticket: "{JIRA_KEY}"
@@ -21930,6 +21937,7 @@ git-ignored at the track level. No HTML or PDF templates ship here.
 <core-file path="core/templates/discovery.md">
 
 ---
+type: Discovery
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -22018,6 +22026,7 @@ without line numbers are exempt from drift checks (they document
 <core-file path="core/templates/hld.md">
 
 ---
+type: HLD
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -22354,6 +22363,7 @@ Result stored in `metadata.json:pre_deploy_status`
 <core-file path="core/templates/lld.md">
 
 ---
+type: LLD
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"

scripts/lib.sh

@@ -160,6 +160,7 @@ TOOLS=(
     "graph-snapshot.sh"
     "okf-emit.sh"
     "okf-bundle.sh"
+    "okf-check.sh"
     "graph-impact.sh"
     "graph-callers.sh"
     "validate-frontmatter.sh"