135 lines
15 KiB
Markdown
135 lines
15 KiB
Markdown
# 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 `type` in every non-reserved `.md` → `raw/*.md` (evidence, deliberately not concepts, AD-2) would fail validation;
|
|
- §8 permits frontmatter in an `index.md` *only* for the bundle-root `index.md` → any `schema/`/`adapters/` `index.md` with frontmatter would be out of spec.
|
|
Recommendation: state in AD-1 that **bundle root = `wiki/`** (with `okf_version` in `wiki/index.md` only) and that `raw/`, `schema/`, `adapters/` are outside the bundle and excluded from OKF validation. Also note that AD-9's subdirectory `index.md` files must contain **no frontmatter** (§8 exception applies only to bundle-root `index.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.
|