15 KiB
Review — Spec Coverage & OKF 0.2 Conformance of the Architecture Spine
- Review target:
ARCHITECTURE-SPINE.md(Wiki of Wikis, 2026-08-14) - Reference:
prd.md(PRD — Wiki of Wikis, 2026-08-14) - Normative standard: OKF 0.2 —
https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md - Reviewed: 2026-08-14
- Verdict: PASS with recommendations — all FR-1..FR-16 and NFR-1..NFR-7 are governed; all three architecture-delegated PRD tickets (OQ-2/3/4) are answered; no statement produces a non-conformant bundle or an "own OKF dialect". Four low-severity conformance hardening points and one product-level note (PRD OQ-6) are recorded.
A. SPEC COVERAGE — every FR / NFR has a governing entry
Legend: ✅ governed (AD), 🟡 governed via convention table / Deferred / Open Question.
A.1 Functional requirements FR-1 .. FR-16
| FR | Title (PRD) | Governing entry (spine) | Status |
|---|---|---|---|
| FR-1 | Sources bereitstellen | AD-2 (separation), AD-3 (immutable), AD-12 (acquisition outside core), Capability Map | ✅ |
| FR-2 | Sources und Curated Knowledge unterscheiden | AD-2, Consistency "Canonical evidence raw/ vs Canonical knowledge wiki/", §12-layout ticket | ✅ |
| FR-3 | Provenienz bewahren | AD-4 (source-grounded, provenance propagation), Consistency "Provenance | OKF sources", FT-5 |
✅ |
| FR-4 | Sources gegen bestehendes Wissen verarbeiten | AD-5 (incremental pipeline, existing knowledge as input) | ✅ |
| FR-5 | Concepts erzeugen | AD-5, AD-7 (identity), Capability Map | ✅ |
| FR-6 | Bestehende Concepts aktualisieren | AD-5, AD-7, AD-16 (classify before mutation) | ✅ |
| FR-7 | Wissen synthetisieren | AD-4 (multi-source synthesis w/ provenance), AD-5 | ✅ |
| FR-8 | Widersprüche sichtbar behandeln | AD-16 (NEW/CONFIRM/CORRECT/CONTRADICT/REDUNDANT; explicit log.md disagreements) | ✅ |
| FR-9 | OKF-konforme Concepts erzeugen | AD-1 (OKF bundle canonical), AD-15 (trust metadata per OKF), Stack "Metadata | YAML Frontmatter according to OKF", FR-9 conventions | ✅ |
| FR-10 | Concepts miteinander verlinken | AD-8 (standard Markdown links, no proprietary link format) | ✅ |
| FR-11 | Progressive Discovery ermöglichen | AD-9 (index.md + hierarchy), AD-8 | ✅ |
| FR-12 | Knowledge Bundle inkrementell weiterentwickeln | AD-5 (incremental), AD-6 (reasoning/mutation separation), FT-6 | ✅ |
| FR-13 | Vorhandene menschliche Kuratierung berücksichtigen | AD-15 (same model for human/machine; no deletion without source basis), AD-16 (conflict must surface) | ✅ |
| FR-14 | Änderungen nachvollziehbar machen | AD-14 (Git as history), Consistency "Update history | Git + optional OKF log.md" | ✅ |
| FR-15 | Tool-unabhängigen Zugriff ermöglichen | AD-1 (bundle readable w/o derived artifacts), AD-8, AD-9, AD-13, FT-1/FT-7 | ✅ |
| FR-16 | Consumer vom Compiler entkoppeln | AD-10 (agent-independent contract), AD-13 (retrieval belongs to consumers), FT-2/FT-3 | ✅ |
Result FR: 16 / 16 covered. No FR appears unaddressed anywhere in the spine.
A.2 Non-functional requirements NFR-1 .. NFR-7
| NFR | Title (PRD) | Governing entry (spine) | Status |
|---|---|---|---|
| NFR-1 | Portability | AD-1 (canonical = portable OKF bundle), Operational Envelope "Portability", FT-7 | ✅ |
| NFR-2 | Human Readability | AD-1 (understandable w/o derived artifacts), AD-15 (Markdown-first), Stack "Content | Markdown" | ✅ |
| NFR-3 | Agent Readability | AD-9 (progressive discovery), AD-13 (standard file ops), AD-8 | ✅ |
| NFR-4 | Version-Control Friendliness | AD-14 (textual diffs), AD-8 (plain links), Operational Envelope "Git recovery" | ✅ |
| NFR-5 | No Mandatory Runtime | AD-11 (no own runtime / no server), AD-13, Operational Envelope "Local-first", FT-1 | ✅ |
| NFR-6 | Vendor Independence | AD-10 (agent-independent), AD-13, Stack "LLM/Agent runtime not bound" | ✅ |
| NFR-7 | Graceful Partial Knowledge | AD-4 (uncertainty allowed), AD-15 (draft|stable|deprecated, generated-unverified default), AD-16 (explicit disagreement), D-6 | ✅ |
Result NFR: 7 / 7 covered.
A.3 PRD architecture-delegated tickets and remaining Open Questions
The PRD explicitly hands three questions to the architecture; the spine must answer each, not silently drop it.
| PRD item | What was delegated | Spine response | Status |
|---|---|---|---|
| OQ-2 Verification Workflow (with NOTEs for PM on trust metadata, v1 default: machine-generated & unverified) | Which verified / human:-prefix metadata the compiler emits; how human review is marked |
AD-15: generated {by, at} unverified by default; verified only with human:-prefixed actor; lifecycle via status/stale_after; explicit v1 default = generated, no verified. Also D-7 (review workflow/UI deferred, trust state still represented via OKF). |
✅ Answered |
| OQ-3 Compilation Scope (+ §12 Relevanzbestimmung) | How the compiler finds relevant existing concepts for a new source, WITHOUT embedding/vector infra (must be textual & deterministic) | AD-17 "Wichtig — funktionaler Grund" block: relevance determination restricted to textual, deterministic means (grep/ripgrep, Markdown traversal, link-following); vector/embedding infrastructure explicitly excluded. Also D-2 (retrieval engine deferred) consistent. | ✅ Answered |
| OQ-4 Conflict Resolution (+ A-3 CLI/file-based constraint) | Which conflicts the compiler may resolve itself vs. defer to the user, implementable CLI-only | AD-16: classification NEW/CONFIRM/CORRECT/CONTRADICT/REDUNDANT; contradictions preserved explicitly, never silently merged; uncertainty may be part of a concept. AD-17 (4): competing producer changes resolved by "productive value" principle into log.md, blocks never silently deleted/overwritten/documented+exposed. Fully file-based (log.md), no GUI. |
✅ Answered |
Other PRD Open Questions (not explicitly mandated to the spine, but checked for completeness):
| PRD item | Spine treatment | Status |
|---|---|---|
| OQ-1 Human-authored Concepts (first-class vs tolerated) | AD-15: human and machine curation share the same OKF Concept model; existing human content is persistent knowledge that must not be dropped for lacking provenance — i.e. first-class. Spine Q-2 (Agent ownership) further positions humans. | ✅ Addressed |
| OQ-5 Source Lifecycle (remove/replace/false source) | D-5 (Source deletion and replacement semantics) — explicitly deferred with "Revisit before:" trigger. Also AD-3 acknowledgment. | 🟡 Addressed as Deferred |
| OQ-6 Product Name | Not addressed anywhere in the spine. Product (not architecture) decision; low severity, listed for completeness only. | 🟡 Not addressed (out of spine mandate) |
A.4 Coverage conclusion
No FR-1..FR-16 and no NFR-1..NFR-7 is missing a governing AD / convention / Deferred / Open-Question entry. All three explicitly delegated architecture tickets (OQ-2, OQ-3, OQ-4) are answered explicitly in the spine (AD-15, AD-17, AD-16/AD-17); none is silently dropped. Secondary OQ-1 and OQ-5 are handled (AD-15 / D-5). Only the product-name question OQ-6 is unaddressed — a legitimately non-architecture item.
B. OKF 0.2 CONFORMANCE — spine claims vs. the actual spec
Verified against okf/SPEC.md at GoogleCloudPlatform/knowledge-catalog (v0.2).
B.1 Claims that are fully conformant (verified)
| Spine claim | Spec basis | Verdict |
|---|---|---|
| AD-1: canonical knowledge is an OKF-0.2-conformant Markdown Knowledge Bundle; bundles must remain understandable without derived artifacts | Spec: bundle of Markdown files w/ YAML frontmatter; conformance §11 | ✅ Identical |
FR-9/AD-1: type is the only required frontmatter key; okf_version: "0.2" declared only in a bundle-root index.md |
§4.1 (type only always-required key); §8/§12 (okf_version only permitted in bundle-root index.md) |
✅ Exact match |
AD-7: Concept identity = relative path within bundle without .md (e.g. flowable/timers); renames are semantic changes |
§2 Concept ID: "path ... with the .md suffix removed" |
✅ Exact match |
AD-15: generated {by, at} unverified default; verified with human:-prefix actor = human-reviewed; status draft|stable|deprecated; optional stale_after; v1 default machine-generated/unreviewed |
§5.2/§5.3 (human: prefix ⇔ human-reviewed), §5.4 (status values; absent ⇒ stable), §5.5 (stale_after date) |
✅ Exact match |
AD-9: index.md at each hierarchy level as directory listing / discovery layer |
§3.1/§8 (index.md reserved as "Directory listing" at any level; used as discovery) |
✅ Conformant |
AD-16 / Consistency: contradictions & update history via log.md |
§3.1/§9 (log.md reserved, "Update history", date-grouped ## YYYY-MM-DD entries) |
✅ Conformant (see B.2 #3 for format hardening) |
| AD-8: relationships via standard Markdown links, not a proprietary graph/link format | §6.1 (bundle-relative / links or standard relative links; no proprietary format) |
✅ Conformant (see B.2 #4) |
| AD-10: adapters must not define deviating knowledge semantics ("Ein Adapter darf keine abweichende Knowledge-Semantik definieren") | Enforces PRD §6.2 ("eigener OKF-Dialekt" forbidden); consistent with spec's permissive model | ✅ Guardrail aligned |
| Spine does not invent frontmatter fields beyond the OKF set (sources/generated/verified/status/stale_after) | §4.1 unknown additional keys tolerated, but an invented drive-schema would be a dialect | ✅ No "own dialect" found |
Affirmative finding: No spine statement produces a non-conformant bundle, and no "own OKF dialect" is proposed. Consistency table entries map 1:1 onto OKF mechanisms («Provenance → sources», «Update history → Git + OKF log.md», «Concept format → Markdown + YAML frontmatter», «Concept identity → relative OKF path»).
B.2 Findings — tiered
F-1 (Low, conformance hardening) — Bundle root is never explicitly declared.
The spine defines raw/ and wiki/ as architectural boundaries (Structural Seed) and canonical knowledge as wiki/**/*.md (AD-1), but never states explicitly that the OKF bundle root IS wiki/. The same repository contains raw/, schema/, adapters/ with .md files. If a validator ever treats the repo root as bundle root:
- conformance §11 requires a non-empty
typein every non-reserved.md→raw/*.md(evidence, deliberately not concepts, AD-2) would fail validation; - §8 permits frontmatter in an
index.mdonly for the bundle-rootindex.md→ anyschema//adapters/index.mdwith frontmatter would be out of spec. Recommendation: state in AD-1 that bundle root =wiki/(withokf_versioninwiki/index.mdonly) and thatraw/,schema/,adapters/are outside the bundle and excluded from OKF validation. Also note that AD-9's subdirectoryindex.mdfiles must contain no frontmatter (§8 exception applies only to bundle-rootindex.md).
F-2 (Low, conformance hardening) — "Errors | kein erfolgreicher Run bei ungültigem Bundle" needs a precise definition of "ungültig".
The Consistency convention "Errors" says a run must not succeed on an invalid bundle. §11/§4.1 require that consumers MUST NOT reject a bundle / concept for missing optional frontmatter fields, unknown type, unknown extra keys, broken links, or missing index.md — and §12 even asks consumers that don't understand the declared version to attempt best-effort consumption rather than refuse. "Ungültig" must therefore be scoped to structural invalidity (missing/empty type, unparseable YAML, reserved filename misuse), explicitly NOT "missing optional fields", or the compiler's own acceptance check would contradict the standard's permissiveness.
F-3 (Low, conformance hardening) — log.md is used beyond its spec-defined purpose; format must be pinned.
§9 defines log.md as an update-history record: flat list, date-grouped ## YYYY-MM-DD (ISO 8601), prose entries whose leading bold word is a convention (e.g. Update/Creation/Deprecation). AD-16 and AD-17 additionally use log.md as a disagreement / conflict ledger ("dokumentierte Disagreements", "der Konflikt wird in log.md dokumentiert"). This is an extension of §9 semantics; it is tolerated only as long as entries remain prose within date-grouped ## YYYY-MM-DD blocks. Recommendation: state that all log.md entries (including disagreements) follow the §9 date-grouped format, so the disagreement ledger does not drift into a structured dialect.
F-4 (Info) — Link form recommendation not adopted (optional).
AD-8 mandates "normal Markdown links" but does not choose the spec's recommended form: §6.1 prefers bundle-relative links beginning with / ("stable when documents are moved within their subdirectory") over plain relative paths. Not a violation (plain relative is allowed), but adopting /-prefixed bundle-relative links would tighten conformance and stability. Optional.
F-5 (Info) — references/ convention unused (optional).
§6.3 defines references/ as the conventional place to mirror external material inside a bundle. The spine instead uses raw/ (outside the bundle) for external material — no conflict, since raw/ is not part of the bundle and references/ is "a naming convention, not a requirement". If any external material is ever mirrored inside wiki/, it should follow the references/ convention. No action required now.
B.3 Conformance conclusion
The spine's OKF claims (AD-1, AD-7, AD-9, AD-15, FR-9 conventions, Consistency table, Stack) match OKF 0.2 to the letter on: required type, optional sources/generated/verified (human:)/status/stale_after, okf_version only in bundle-root index.md, references/ as optional convention, concept ID = path-minus-.md, and consumer permissiveness for missing optional fields. The four findings above are hardening/word-smithing items, not conformance violations.
C. Findings summary
| # | Severity | Finding | Location |
|---|---|---|---|
| — | — | All FR-1..16 and NFR-1..7 governed; OQ-2/3/4 answered; OQ-1/5 handled | — |
| F-1 | Low | Bundle root (=wiki/) never declared explicitly; raw/-wiki/ same-repo validation risk; subdirectory index.md must be frontmatter-free |
AD-1, AD-9, Structural Seed |
| F-2 | Low | "Ungültiges Bundle" must mean structurally invalid, not missing optional fields (spec §11 MUST-NOT-reject) | Consistency "Errors" |
| F-3 | Low | log.md disagreement ledger must keep §9 date-grouped prose format |
AD-16, AD-17 |
| F-4 | Info | Optional: adopt /-prefixed bundle-relative links (§6.1 recommended form) |
AD-8 |
| F-5 | Info | Optional: references/ convention if external material ever enters wiki/ |
AD-2/Structural Seed |
| OQ-6 | Info | PRD product-name question unaddressed in spine (product, not architecture, item) | — |
Overall verdict: PASS. Spec coverage is complete (16 FR + 7 NFR → 23/23 entries, 3/3 delegated tickets answered). OKF 0.2 conformance is sound; no non-conformant output and no own dialect. The 3 low-severity findings (F-1..F-3) are recommended before implementation begins because they affect how the compiler validates and writes bundles.